# Queen Poll

> Use when waiting for kanban tasks after dispatch.

- Skill: `jajabong/queen-poll` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jajabong/queen-poll`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jajabong/queen-poll/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jajabong (https://skillmd.com/u/jajabong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jajabong/queen-poll

---


# Queen Poll — Wait for Kanban Tasks

Hermes gateway 每 60s tick 自动 claim + spawn kanban task，但 **Queen 在 idle 状态不知道任务已完成**。必须主动 poll，否则 fire-and-forget 让用户问才汇总，浪费大量 wall-clock。

## When to use

- 刚派了 1+ 个 kanban task（`hermes kanban create` 或 dispatcher.py）
- 需要等 task 跑到 `done` / `blocked` / `crashed` 才汇总
- 不想用 `terminal background=true` + 反复 poll stdout 推测状态

## Canonical pattern

```bash
# 1. 派单
hermes kanban create "..." --assignee default --workspace dir:/path

# 2. 立即 poll（不等用户问）
python3 ~/.hermes/scripts/queen_poll.py \
    --board <board-slug> \
    --task-id t_<id> \
    --interval 30 \
    --timeout 1800

# 3. poll 退出 0（terminal reached）后：
hermes kanban show <task-id>  # 读 final summary
# 汇总 → 给用户最终汇报
```

## CLI

```
queen_poll.py [--board SLUG] [--interval SEC] [--timeout SEC]
              [--task-id ID] [--match "title substring"]

exit 0 = all matched tasks reached done/blocked/crashed
exit 1 = timeout
exit 2 = no matching task found (often: task not yet dispatched)
```

## Pitfalls

### 共享 workspace 冲突

2+ tasks 都指 `dir:/Users/henry/hermes-wiki` 时，同时写 `concepts/` 可能撞文件。派单前确认 output 路径不重叠，或用 `worktree` workspace。

### protocol_violation 重试

worker 完成工作但没调 `kanban_complete` 就退出 → dispatcher 下次 tick 当 `crashed` 重试。worker prompt 必须显式说：

> 完成所有写操作后调用 `hermes kanban complete <task-id>` 标记 done；如果调 API 失败，至少调 `hermes kanban comment <task-id> -m "..."` 让 dispatcher 知道结果。

### Timeout 设大

multi-task 真做调研 + 写文件常常 30-60 分钟/任务。timeout 至少 **1800s (30min)**，跨多任务 3600s+。

### Board 切换后默认 board 不变

`hermes kanban boards switch <slug>` 只改当前 session 的默认 board。**派单前必须确认当前 board**，否则 task 会落到 default board 而非你预期的 drill board。

### ⚠️ 4 节点 Queen 拓扑陷阱（2026-08-24 multi-node 调试）

**Queen 唯一性原则**：集群内**只能有一个 hermes gateway daemon**。多个 daemon → kanban state 分裂、bot 消息重复、cron 双重触发。

**默认 Queen = MacMini (10.0.0.3)**：
- launchd 守护：`~/Library/LaunchAgents/ai.hermes.gateway.plist` (KeepAlive=true, RunAtLoad=true)
- 飞书/lark/wecom/telegram/discord/whatsapp/slack/signal 全平台 bot 在 Queen 节点
- kanban/cron/artifacts/state.db 全在 Queen 节点 `~/.hermes/`

**MacBook 客户端 ≠ Queen**：MacBook `hermes chat` session 是临时 client，LLM 调用走 VPS anchor API (`45.197.146.62:8088`)，不经过 Queen。

**其他节点 hermes 选型**：
- VPS：❌ **不装 hermes**（API 网关角色）
- Aimax：⚠️ **短期不装**（MacMini Queen ssh 调），**中期装 daemon** 做 GPU 专用 agent

**MacBook ↔ MacMini 协调规则**：
1. 轻量查询/单次实现 → MacBook hermes 直跑（不 ssh MacMini）
2. 长程/多租户/cron/bot → ssh MacMini Queen 触发
3. 关键操作前 → ssh 看 MacMini Queen 状态（kanban/cron/gateway log）

**SSH 配置铁律**（防止 WG MTU 切碎 + 跨 ISP 阻挡）：
- `KexAlgorithms=curve25519-sha256`（避免 OpenSSH 默认 chacha20-poly1305 被 WG 路径阻断）
- aimax/macmini 走 `ProxyCommand ssh -W %h:%p vps`（本机例外）
- `ServerAliveInterval=30 ServerAliveCountMax=3`
- `ControlMaster auto` + `ControlPersist 10m`（10 分钟内免重复输密码）
- aimax 走 udp2raw 抗中国电信 UDP 封锁

**盲区教训**：只查本机 `~/.hermes/` 看不到 Queen 真实状态。**摸 Queen 必须 ssh 到 Queen 节点**。本次教训：飞书 bot 已配齐但 kanban 0 task — 不代表 Queen 没跑，可能 ws 没收到消息 / 消息被 use_case 当对话处理没派单。

**Queen 真实状态诊断 4 命令**（不动手，仅汇报）：
```
1. tail -100 ~/.hermes/logs/gateway.log   # ws 连接 / 消息 / 派单记录
2. ls -la ~/.hermes/cron/jobs/            # cron 任务列表
3. sqlite3 ~/.hermes/kanban.db "SELECT COUNT(*) FROM tasks"  # task 总数
4. grep -E "feishu|websocket|connect|disconnect" ~/.hermes/logs/gateway.log | tail -30  # ws 健康度
```

## 反模式（fire-and-forget）

- ❌ 派单后等用户问"进展如何"
- ❌ 用 `terminal background=true` 反复 poll worker stdout 推测状态
- ❌ 假设 dispatcher tick 完成后 Queen 自动知道

## Implementation

`~/.hermes/scripts/queen_poll.py` — 300 行 Python，调 `hermes kanban list --json`，轮询 status 直到 terminal state。已落地。