fix(kanban): report truthful gave-up causes

[stevenbaert]

Summary

Kanban's notifier currently describes every gave_up event as caused by repeated spawn failures. That is incorrect for iteration exhaustion, timeouts, crashes, and other circuit-breaker causes.

This change:

• renders the sanitized event error when one is present;
• otherwise uses the cause-neutral fallback failure limit reached;
• preserves board, task, and assignee attribution;
• leaves completed, blocked, crashed, and timed-out notification branches unchanged.

Reproduction

An event with:

kind=gave_up
error=Iteration budget exhausted (80/80)

previously rendered as:

gave up after repeated spawn failures
Iteration budget exhausted (80/80)

The two lines contradicted each other and sent operators toward the wrong remediation path.

Verification

Independent QA was performed on exact commit 8cc4aff20318d8459904b759db34c4947614ef71:

• focused notifier and watcher tests: 13 passed;
• iteration-exhaustion producer test: 1 passed;
• isolated notifier flow verified all five terminal branches;
• py_compile: passed;
• git diff --check: passed;
• exact-head linkage recheck: approved.

Risk

Low and limited to human-facing gave_up notification formatting. Event production, retry limits, dispatch behavior, and runtime lifecycle are unchanged.

Tracker

Installation tracker and acceptance criteria: https://github.com/stevenbaert/hermes/issues/712

No runtime activation or gateway restart is included.

[not1tony]

Repro for a misleading error message case that fits this issue's scope:

# Current board is cqgambit
hermes kanban boards switch cqgambit

# Card t_4dff09c7 is in 'ready' on the 'default' board
hermes kanban block t_4dff09c7 "test" --kind needs_input

Actual: cannot block t_4dff09c7 (unknown id or not in running/ready)

Truth: The id IS known (it exists on another board) and the card IS in ready. The real problem is the card is on a different board than the current one. The error message should name the current board and suggest the fix ("task not found on current board 'cqgambit' — switch to 'default' first").

The operator retried the same command 8 times because the error doesn't tell them what's actually wrong. The kanban_block tool in the agent API has no board parameter, so the only fix is hermes kanban boards switch <correct-board> first — but the error doesn't suggest this. Same pattern likely affects other kanban verbs that lack --board flags.

[teknium1]

Thanks for the focused fix. The premise holds on current main: gateway/kanban_watchers.py:373-380 labels every gave_up event as repeated spawn failures, while agent/turn_finalizer.py:115-125 records iteration exhaustion as a timed_out failure and hermes_cli/kanban_db.py:7026-7036 carries the supplied error into the eventual gave_up payload.

The formatter in commit 8cc4aff20318d8459904b759db34c4947614ef71 removes the unsupported cause claim, preserves board/assignee/task attribution, and covers both populated-error and absent-payload cases. The current base has not changed either touched file since the PR base, so this should salvage cleanly.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

Thirteen PRs address or reference four Kanban gateway issues, covering dispatcher exclusivity, false stuck telemetry, auto-decompose diagnostics and secret scope, concurrency parsing, activity and notifier reporting, archived-board races, and worker-log cleanup. The diffs address distinct causes, with material overlap in the singleton-lock, false-stuck, max_spawn-coercion, and auto-decompose secret-scope groups.

Related pull requests

• fix(gateway): add flock-based singleton guard to kanban dispatcher #41679 [closed] partial — (+273/-62) — n/a: Adds a profile-scoped dispatcher singleton lock with cleanup and tests for [Bug]: kanban dispatcher: gateway embeds dispatcher without singleton guard — two gateway instances cause claim-reclaim churn #41448; this closed predecessor remains relevant because the stronger machine-global implementation was shipped through fix(kanban): machine-global singleton lock for the embedded dispatcher (#41448) #49068 as dfa5610 and 226e932.
• fix(kanban): machine-global singleton lock for the embedded dispatcher (#41448) #44919 [closed] fixes — (+106/-0) — n/a: Implements the machine-global cross-platform singleton lock at the shared Kanban root, directly addressing [Bug]: kanban dispatcher: gateway embeds dispatcher without singleton guard — two gateway instances cause claim-reclaim churn #41448; it remains relevant although closed because its reviewed commits were salvaged with attribution into fix(kanban): machine-global singleton lock for the embedded dispatcher (#41448) #49068.
• fix(gateway): avoid false kanban stuck alerts at concurrency cap #46892 best fix — (+256/-1) — n/a: Detects externally occupied max_spawn capacity for fix: _kanban_dispatcher_watcher fires false "stuck" alert when hook fills concurrency cap #46800, but its keep_open review identifies cross-board aggregation that can suppress real warnings and requests per-physical-board accounting plus daemon-path handling.
• fix(kanban): machine-global singleton lock for the embedded dispatcher (#41448) #49068 [merged] best fix — (+107/-0) — n/a: This merged reference implementation carries fix(kanban): machine-global singleton lock for the embedded dispatcher (#41448) #44919's machine-global lock, cross-platform acquisition, explicit release paths, and exclusivity test into main, resolving the concurrent-dispatcher cause in [Bug]: kanban dispatcher: gateway embeds dispatcher without singleton guard — two gateway instances cause claim-reclaim churn #41448.
• fix(kanban): promote auto-decompose failures from DEBUG to rate-limited WARNING #49861 best fix — (+90/-3) — n/a: Promotes non-successful auto-decompose outcomes from DEBUG-only logging to rate-limited WARNING and now includes controlled-time tests for the initial warning, suppression, and 300-second boundary requested by its keep_open verdict.
• fix(kanban): run auto-decompose tick under the profile secret scope #57837 related — (+170/-50) — n/a: Installs and resets a profile secret scope around the threaded auto-decompose tick, with focused scope-lifetime coverage and field evidence supporting the documented keep_open salvage path for multiplexed credential resolution.
• fix(gateway): cast max_spawn config to int to prevent TypeError (#59499) #59588 related — (+98/-3) — n/a: Casts raw max_spawn values but accepts non-positive values and tests synthetic parsing rather than the production path; its keep_open review requests positive validation and a real gateway-to-dispatch regression, both of which fix(kanban): close parent log handle after spawn and validate max_spawn #65644 substantially supplies for the coercion portion.
• fix(kanban): log dispatcher tick summary on crash/timeout/reclaim/auto-block, not only on spawn #62893 related — (+80/-9) — n/a: Expands dispatcher summaries beyond spawn-only ticks to crashes, timeouts, reclaims, auto-blocks, and stale work, with the visible stale-only regression addressing its keep_open review.
• fix(kanban): report truthful gave-up causes #64605 related — (+48/-7) — n/a: Replaces the unsupported repeated-spawn-failure explanation for every gave_up event with the supplied sanitized error or a cause-neutral fallback, preserving attribution and covering both payload cases as supported by its keep_open verdict.
• fix(kanban): prevent archived board watcher resurrection #65321 related — (+392/-32) — n/a: Makes stale named-board watcher and auto-decomposer opens existing-only so archive races cannot recreate a removed board or fall back to default, with the visible diff propagating the mode through decomposition paths and adding the requested race coverage.
• fix(kanban): avoid false dispatcher stuck warnings #65581 best fix — (+485/-35) — n/a: Adds board-local gateway health accounting and daemon deferral handling for fix: _kanban_dispatcher_watcher fires false "stuck" alert when hook fills concurrency cap #46800, addressing its keep_open review's cross-board objection, but its explicit global-deferral signal covers max_in_progress rather than fix: _kanban_dispatcher_watcher fires false "stuck" alert when hook fills concurrency cap #46800's externally occupied max_spawn repro and the diff also includes separable gateway-status changes.
• fix(kanban): close parent log handle after spawn and validate max_spawn #65644 related — (+80/-8) — n/a: Positively validates max_spawn through the real watcher path and closes the parent log handle after successful Popen, but its keep_open review still requires finally-based cleanup and a regression for another Popen exception.
• fix(gateway): respect explicit platform disable for HA and wrap kanban auto-decompose in profile scope #76864 [closed] related — (+62/-57) — n/a: Its Kanban half duplicates fix(kanban): run auto-decompose tick under the profile secret scope #57837's auto-decompose secret-scope repair and its Home Assistant half is unrelated; despite the earlier keep_open verdict, it remains relevant as a closed split source because the author closed it in favor of fix(kanban): run auto-decompose tick under the profile secret scope #57837 and fix(gateway): respect explicit platform disable for Home Assistant in env overrides #76871.

Duplicates

#41679 and #44919 overlap on #41448, with merged #49068 as the machine-global consolidation; #46892 and #65581 overlap on #46800 but currently provide complementary max_spawn detection and board-local health accounting; #59588 overlaps #65644 on max_spawn coercion; the Kanban half of closed #76864 duplicates #57837.

Suggested consolidation

Keep #64605 open with its focused notifier-formatting salvage path, and keep #49861, #57837, #62893, and #65321 open on their documented reviewed paths. Author action: rebase or split #46892/#65581 into a focused #46800 change combining per-board externally occupied max_spawn detection with board-local gateway and daemon accounting while removing #65581's unrelated gateway-status scope; retain both recorded best-fix PRs until that reconciliation, require #65644's finally-based exceptional-Popen cleanup before closing #59588 as its narrower duplicate despite #59588's keep_open review, and leave #41679, #44919, and #76864 closed in favor of #49068, #57837, and #76871 respectively.

Cross-PR triage: Reviewed 13 pull requests and 4 issues in this complex. Each diff was read against this issue; Assessment working set: 142 kB of PR diffs, 45 kB of issue/PR text, 29 kB of discussion (31 comments), 11 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.