fix(kanban): hold external/interactive claims so the dispatcher stops re-dispatching live operator sessions

[vk0dev]

Problem

A live interactive operator session (e.g. a Claude Code session in tmux) that runs hermes kanban claim <id> does not emit kanban heartbeats or other Hermes API traffic. Its claim_expires / last_heartbeat_at therefore go stale exactly like a wedged worker, and release_stale_claims() cannot tell the two apart. It reclaims the task, and the next dispatcher tick spawns a parallel worker on a task a human is actively working on — double work, merge conflicts, and wt/* worktree sprawl.

This is distinct from the cgroup-throttle duplication that RECLAIM_DEFER_GRACE_SECONDS addresses: here the claim holder is a healthy interactive process that legitimately never heartbeats.

Fix — explicit external/interactive claim hold

• New nullable tasks.claim_kind column ('worker' | 'external'; NULL = legacy/worker). Additive migration via _migrate_add_optional_columns; existing boards keep current behaviour.
• claim_task(external=True) marks the claim 'external' and holds it indefinitely (claim_expires = NULL). Such a row is invisible to all three reclaimers: release_stale_claims (filters claim_expires IS NOT NULL), enforce_max_runtime and detect_crashed_workers (filter worker_pid IS NOT NULL — an external hold has none). A claim_kind guard in release_stale_claims adds defense-in-depth.
• CLI: hermes kanban claim <id> --external (opt-in; the default claim path is unchanged — still a worker claim with a TTL). An external hold is released only by an explicit complete / block / reclaim.
• complete / block / reclaim clear claim_kind, so a reclaimed external task is cleanly worker-claimable again (operator recovery path for a dead interactive session).

Reclaim of genuinely dead/wedged worker claims is unchanged (regression-guarded).

Tests

Adds coverage in test_kanban_db.py and test_kanban_cli_dispatch_passthrough.py: external claim survives the stale sweep (indefinite + forced-expiry guard), worker claim still reclaimed, --external CLI contract, complete/block/reclaim clear the hold, and the additive migration. Full affected-file suites pass (239 tests).

🤖 Generated with Claude Code

[tonydwb]

Code Review Summary

Verdict: Approved

Well-designed fix for the kanban dispatcher re-dispatching live operator sessions. External (interactive) claims are now held indefinitely and never auto-reclaimed.

Looks Good

• New claim_kind column (worker vs external) cleanly discriminates claim types
• External claims set claim_expires = NULL and worker_pid = NULL, making them invisible to all three reclaimers
• DB migration is additive (new column, backward-compatible with legacy rows)
• CLI --external flag with clear help text explaining the behavior
• Defense-in-depth: release_stale_claims additionally guards on claim_kind
• Well-documented with extensive comments explaining the design rationale

---

Reviewed by Hermes Agent

[teknium1]

Thanks for isolating the interactive-operator claim case. The underlying issue remains reproducible on current main: hermes_cli/kanban.py:1816-1818 creates the normal finite-TTL claim, and hermes_cli/kanban_db.py:3634-3713 can reclaim it when no worker PID exists.

Problems

• The proposed external hold would still be reclaimed by the newer detect_stale_running watchdog. It selects every running task at hermes_cli/kanban_db.py:6466-6472, treats a NULL heartbeat as stale at :6483-6486, and resets the task at :6508-6513. This path is not covered by the PR's claim_kind guard.
• The new public CLI flag is absent from the documented claim syntax at website/docs/user-guide/features/kanban.md:642.

Suggested changes

• During salvage, guard detect_stale_running for external holds and add a regression test for that watchdog.
• Reconcile claim-kind cleanup with current typed-block branches (hermes_cli/kanban_db.py:4825-4946) and document --external.

This is an automated hermes-sweeper review.