Skip to content

The agent that grows with you

test(kanban): pin post-commit kanban_task_blocked for dependency waits

Teknium25e7f5fc21d8
diff --git a/tests/hermes_cli/test_kanban_lifecycle_hooks.py b/tests/hermes_cli/test_kanban_lifecycle_hooks.py
index da8dbecb5df..1ea11852525 100644
--- a/tests/hermes_cli/test_kanban_lifecycle_hooks.py
+++ b/tests/hermes_cli/test_kanban_lifecycle_hooks.py
@@ -8,6 +8,7 @@ and that a misbehaving hook callback never breaks the transition.
from __future__ import annotations
+import sqlite3
from pathlib import Path
import pytest
@@ -66,6 +67,46 @@ def test_claim_fires_hook(kanban_home, captured_hooks):
assert kw["run_id"] is not None
[email protected](("kind", "status", "event"), [
+ ("dependency", "todo", "dependency_wait"),
+ ("needs_input", "blocked", "blocked"), # control: always post-commit
+])
+def test_block_hook_runs_after_commit_with_write_lock_free(
+ kanban_home, captured_hooks, kind, status, event,
+):
+ """Every block kind fires kanban_task_blocked after its txn commits: a
+ second connection sees the transition and can take the write lock."""
+ db_path = kb.kanban_db_path()
+ seen = []
+
+ def _probe(**_kw):
+ other = sqlite3.connect(str(db_path), timeout=0, isolation_level=None)
+ try:
+ row = other.execute("SELECT status FROM tasks WHERE id = ?", (tid,)).fetchone()
+ last = other.execute(
+ "SELECT kind FROM task_events WHERE task_id = ? ORDER BY id DESC LIMIT 1", (tid,),
+ ).fetchone()
+ try:
+ other.execute("BEGIN IMMEDIATE")
+ other.execute("ROLLBACK")
+ lock = "free"
+ except sqlite3.OperationalError as exc:
+ lock = str(exc)
+ seen.append((row[0], last[0], lock))
+ finally:
+ other.close()
+
+ get_plugin_manager()._hooks["kanban_task_blocked"].append(_probe)
+ conn = kbc.connect()
+ try:
+ tid = kb.create_task(conn, title="child", assignee="worker")
+ kb.link_tasks(conn, parent_id=kb.create_task(conn, title="parent"), child_id=tid)
+ with kb.write_txn(conn):
+ conn.execute("UPDATE tasks SET status = 'ready' WHERE id = ?", (tid,))
+ assert kb.block_task(conn, tid, reason="waiting", kind=kind)
+ finally:
+ conn.close()
+ assert seen == [(status, event, "free")]
def test_misbehaving_hook_does_not_break_transition(kanban_home, monkeypatch):
diff --git a/website/docs/user-guide/features/hooks.md b/website/docs/user-guide/features/hooks.md
index dfb103090c5..99eff53702f 100644
--- a/website/docs/user-guide/features/hooks.md
+++ b/website/docs/user-guide/features/hooks.md
@@ -383,7 +383,7 @@ def register(ctx):
ctx.register_hook("post_llm_call", my_sync_callback)
ctx.register_hook("on_session_start", my_init_callback)
ctx.register_hook("on_session_end", my_cleanup_callback)
- # Kanban board lifecycle (dependency-wait blocking may fire inside its transaction):
+ # Kanban board lifecycle (each fires after its board write commits):
ctx.register_hook("kanban_task_claimed", my_claim_callback) # dispatcher process
ctx.register_hook("kanban_task_completed", my_done_callback) # worker process
ctx.register_hook("kanban_task_blocked", my_blocked_callback) # worker process
@@ -488,7 +488,7 @@ Payload fields below are the exact event-specific fields supplied by each call s
| `on_room_member_activity` | Observer | While a hosted Group Chat member turn runs on the Bot Mode gateway, once per runtime event the member session emits (tool start/complete, approval request, message/reasoning deltas, errors); queued per consumer off the token path; return ignored. | `room_id`, `thread_id`, `member_id`, `turn_id`, `task_id`, `execution_generation`, `kind`, `seq`, `payload` | `payload` is the client-safe session event body: tool args and results, redacted approval commands, streamed member text. |
| `kanban_task_claimed` | Observer | After claim commit, in dispatcher process before worker spawn; return ignored. | `task_id`, `profile_name`, `board`, `assignee`, `run_id` | Board/task/profile/assignee identifiers. |
| `kanban_task_completed` | Observer | After completion and cleanup, usually in worker process; return ignored. | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `summary` | Summary may contain project/user content. |
-| `kanban_task_blocked` | Observer | After a blocked transition; the dependency-wait path fires before its transaction exits. Return ignored. | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `reason` | Reason may contain project/user content. |
+| `kanban_task_blocked` | Observer | After a blocked transition commits, dependency waits included. Return ignored. | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `reason` | Reason may contain project/user content. |
| `on_kanban_worker_spawned` | Observer | After `spawn_fn` returns and the worker PID is persisted; runs inside the dispatch lock, keep callbacks fast. Return ignored. | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `worker_pid`, `workspace_path` | `workspace_path` is a filesystem path and may reveal project layout or usernames. |
| `on_kanban_worker_exited` | Observer | Tick-derived: after `detect_crashed_workers` reclaims a dead-PID task and the reclaim commits. Return ignored. | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `worker_pid`, `exit_kind`, `exit_code`, `outcome`, `retry_status` | Identifiers and exit metadata only. |
| `on_kanban_worker_stale_claim` | Observer | After a TTL-expired claim is reclaimed; live-PID extensions don't fire. Return ignored. | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `worker_pid`, `heartbeat_stale`, `retry_status` | Identifiers and claim metadata only. |
@@ -1860,7 +1860,7 @@ Fires after completion and cleanup, usually in the worker process. Its `summary`
#### `kanban_task_blocked`
-Fires after a normal blocked transition. The dependency-wait path invokes it before that write transaction exits. Its `reason` can contain project or user content.
+Fires after a blocked transition commits, dependency waits included, so the callback can read and write the board. Its `reason` can contain project or user content.
All three kanban hooks are observer-only and carry `task_id`, `profile_name`, `board`, `assignee`, and `run_id`; completed adds `summary`, and blocked adds `reason`.
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
index ff4fbd8ca2e..8c3bcc80b82 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
@@ -402,7 +402,7 @@ def register(ctx):
| `post_approval_response` | 观察者 | 决策、timeout 或 gateway 通知失败后;忽略返回值。 | `command`, `description`, `pattern_key`, `pattern_keys`, `session_key`, `surface`, `turn_id`, `tool_call_id`, `choice`;smart 路径可增加 `decided_by` | 同样的命令敏感性,加决策 metadata。 |
| `kanban_task_claimed` | 观察者 | Claim commit 后,在 dispatcher 进程 spawn worker 前;忽略返回值。 | `task_id`, `profile_name`, `board`, `assignee`, `run_id` | Board/task/profile/assignee 标识。 |
| `kanban_task_completed` | 观察者 | Completion 和 cleanup 后,通常在 worker 进程;忽略返回值。 | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `summary` | Summary 可能含项目/用户内容。 |
-| `kanban_task_blocked` | 观察者 | Blocked transition 后;dependency-wait 路径在 transaction 退出前触发。忽略返回值。 | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `reason` | Reason 可能含项目/用户内容。 |
+| `kanban_task_blocked` | 观察者 | Blocked transition 提交后(含 dependency-wait)。忽略返回值。 | `task_id`, `profile_name`, `board`, `assignee`, `run_id`, `reason` | Reason 可能含项目/用户内容。 |
---
@@ -1174,7 +1174,7 @@ Completion 和 cleanup 后触发,通常位于 worker 进程;`summary` 可能
#### `kanban_task_blocked`
-普通 blocked transition 后触发;dependency-wait 路径在该 write transaction 退出前调用。`reason` 可能包含项目或用户内容。
+blocked transition 提交后触发(含 dependency-wait),回调可读写看板。`reason` 可能包含项目或用户内容。
三个 kanban hook 均仅观察,并携带 `task_id`、`profile_name`、`board`、`assignee`、`run_id`;completed 增加 `summary`,blocked 增加 `reason`。