Queen Poll Kanban

Queen Poll Kanban

Queen-mode helper: actively wait for kanban tasks to reach a terminal state, instead of fire-and-forget dispatching and waiting for the user to come back.

Why

hermes kanban dispatch runs the gateway daemon every 60s. A task spawned at T=0 may not be picked up until T=60. If Queen dispatches and returns to user, the user has no idea when the task finishes. Orchestrator mode means Queen polls.

When to use

• After hermes kanban create with --workspace dir:<path> or --workspace worktree
• When dispatching ≥2 independent tasks (multi-project drill)
• When the user expects Queen to report completion, not just "I dispatched it"

How

# Single task
python3 ~/.hermes/scripts/queen_poll.py \
    --task-id t_4211cbca \
    --interval 10 \
    --timeout 600

# Multi-task by board
python3 ~/.hermes/scripts/queen_poll.py \
    --board multi-project-drill \
    --interval 10 \
    --timeout 900

# Match by title substring
python3 ~/.hermes/scripts/queen_poll.py \
    --match "audit" \
    --interval 15 \
    --timeout 300

Exit code: 0 when all matched tasks reach done/blocked/crashed; 1 on timeout.

In the main session, run with terminal(background=true, notify_on_complete=true) so the process doesn't block the main loop; the result re-enters the conversation when the poll completes.

What the script does

• Polls hermes kanban list --json every --interval seconds
• Prints a one-line status change whenever a task moves to a new state
• Exits when all matched tasks are terminal, or --timeout is reached
• Filters by --task-id, --match, or --board

Known issues

• hermes kanban list --json output format may include extra preamble text. The script handles JSON-or-text via json.loads fallback to [].
• A worker that exits cleanly without calling kanban_complete registers as crashed (protocol_violation). Queen should treat crashes as work-not-done and either re-dispatch with --max-retries or accept partial result.
• --board is a TOP-LEVEL flag on hermes kanban, not a subcommand flag. Use hermes kanban --board X list --json, not hermes kanban list --board X --json (the latter errors with "unrecognized arguments").
• hermes kanban boards outputs human text, not JSON. The script parses the SLUG column. Falls back to ["default"] if parsing fails.

Anti-pattern: 口头说"后台跑"不实际起进程

Bug found in production (2026-08-10 multi-project drill): Queen said "Queen 现在主动 poll 6 个任务，后台跑，结果出来自动汇报" — but never actually invoked queen_poll.py. The gateway daemon had spawned workers and tasks had completed within minutes, but Queen had no polling process running, so the only way the user learned the result was to ask "进展如何". That is fire-and-forget with extra steps.

Mandatory: before claiming "后台跑 / 自动汇报 / 完成会通知", Queen MUST have already invoked:

terminal(command="python3 ~/.hermes/scripts/queen_poll.py ...", background=true, notify_on_complete=true)

and received a session_id. Without a live session_id, no poll is running and no auto-report will happen. If Queen can't or doesn't run the poll, do not claim auto-report.

Self-test

python3 ~/.hermes/scripts/queen_e2e_test.py

Verifies SOUL structure (4 subsections + hard rule 7), script exists/executable, queen_poll runs against --all-boards and --board proj-a, gateway daemon present. Run after every SOUL/script change.

See also

• hermes kanban — 33 subcommands (init/boards/create/swarm/assign/claim/complete/dispatch/daemon)
• SOUL §长程执行 → "Queen 主动 polling 模式 (v29.8)" + "硬规则 防止口嗨后台 (v29.8.1)"
• ~/.hermes/scripts/queen_poll.py — the script