PR #23120: feat(kanban): push notification when a task transitions to blocked

• Repository: NousResearch/hermes-agent
• Author: unimatrix27
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/23120

Description (problem / solution / changelog)

Summary

Closes #22995.

Adds a global block-notifier so unattended kanban workflows surface a stall without requiring a per-task notify-subscribe. Off by default for backward compatibility.

New config keys (hermes_cli/config.py, default config block):

kanban:
  notify_on_block: false           # push when a task transitions to blocked
  notify_on_block_channel: ""      # empty = broadcast to all home channels;
                                   # or "<platform>:<chat_id>[:<thread_id>]"

When notify_on_block is true, a new gateway watcher (_kanban_global_block_watcher) tails task_events for kinds blocked (manual kanban block) and gave_up (auto-block on failure_limit) across every board and delivers one message per event to either every connected platform's home channel (default) or a single explicit platform:chat_id[:thread_id] target.

The watcher persists its cursor in a new tiny kanban_kv table so it survives gateway restarts. On first enable the cursor is seeded to MAX(task_events.id) per board so a long-running install doesn't flood the home channel with historical block events the moment the flag flips on.

The watcher mirrors the existing _kanban_notifier_watcher pattern:

• All SQLite work runs via asyncio.to_thread so the event loop never blocks on the WAL lock.
• Failed sends do not advance the cursor — the next tick retries.
• Malformed notify_on_block_channel disables the watcher with a clear warning log line rather than silently swallowing events.
• Cross-board fan-out reuses the same list_boards iteration as the per-task notifier.

Why this is independent of the existing notifier

_kanban_notifier_watcher already delivers terminal events, but only to chats in kanban_notify_subs — i.e. the user must run kanban notify-subscribe for every task. The issue points out this scales poorly for fleet/multi-agent workflows where a single blocked task can stall every downstream task. The new watcher is the zero-subscription, zero-token-cost path the issue asks for.

Files

The new schema is added via CREATE TABLE IF NOT EXISTS so existing DBs migrate transparently on the next connect() — same pattern as the existing kanban_notify_subs table.

Test plan

• pytest tests/hermes_cli/test_kanban_core_functionality.py -k "kv or block_notify or max_event_id or unseen_block_events" — 4 new passing
• pytest tests/hermes_cli/test_kanban_notify.py — 12 passing (5 new + 7 existing, no regressions)
• python3 -m py_compile clean on all modified files
• Manual: end-to-end smoke run; confirm watcher exits silently when flag is off
• Reviewer: run scripts/run_tests.sh against the full suite (my local minimal venv doesn't include FastAPI/dashboard plugin deps; the only failures I saw were the pre-existing plugins/kanban/dashboard tests that require those)

Tested on macOS (darwin 25.3.0, Python 3.11.14). No OS-specific syscalls touched — all changes are SQLite + asyncio so cross-platform behavior is unchanged.

🤖 Generated with Claude Code

Changed files

• gateway/run.py (modified, +249/-0)
• hermes_cli/config.py (modified, +16/-0)
• hermes_cli/kanban.py (modified, +2/-0)
• hermes_cli/kanban_db.py (modified, +119/-0)
• tests/hermes_cli/test_kanban_core_functionality.py (modified, +84/-0)
• tests/hermes_cli/test_kanban_notify.py (modified, +287/-0)