Kanban workflow execution
Kanban workflow execution turns durable board items into supervised worker runs. It keeps the board state, task graph, work history, ownership lease, worker progress, and human notifications in one flow so work can pause, recover, and resume without losing its place. See Kanban workflow automation for the wider automation model.
Execution model
Board persistence
The board is the durable source of truth for work. A board stores work items, dependency links, comments, run history, events, attachments, and notification subscriptions in a shared SQLite store. Each board also has its own workspace and log area, so a worker assigned to one board does not silently operate on another board. hermes_cli/kanban_db.py• L1-12
Board writes use short, serialized transactions. A compare-and-swap claim means that only one dispatcher can move a ready item into active work. The event and run records preserve what happened even when the current item state later changes. hermes_cli/kanban_db.py• L776-983
Work-item state
A work item is a durable request with an owner, a status, optional parent links, and a workspace. Its status describes where it is in the workflow; its run records describe each attempt to execute it. The board workflow exposes planning, waiting, execution, review, completion, and archival states while keeping archive outside the active columns. hermes_cli/kanban_workflow.py• L27-51
The main state changes follow this path. Dependency checks and explicit human actions can send an item back to an earlier state without erasing its history.
flowchart LR
T[Triage] --> TD[Todo]
TD --> R[Ready]
R --> RUN[Running]
RUN --> D[Done]
RUN --> REV[Review]
REV --> D
REV --> R
RUN --> B[Blocked]
B --> R
RUN --> S[Scheduled]
S --> R
D --> A[Archived]
P[Open parent] -. holds .-> TD
D -. releases .-> R
The state machine is guarded at the persistence boundary. For example, a child cannot finish while a parent is open, and a worker cannot close a live run unless it proves that it owns that run. hermes_cli/kanban_db.py• L2100-2121, hermes_cli/kanban_db.py• L2640-2744
References: hermes_cli/kanban_db.py• L1-12 hermes_cli/kanban_db.py• L776-983 hermes_cli/kanban_workflow.py• L27-51 hermes_cli/kanban_db.py• L2100-2121 hermes_cli/kanban_db.py• L2640-2744
Planning and decomposition
Triage planning
Triage is the planning state for rough or incomplete requests. A specifier can turn a rough item into a clear goal, approach, and acceptance criteria, then promote it to the normal work queue. If the auxiliary planner is unavailable or returns unusable content, the item stays available for later human or automated action. hermes_cli/kanban_specify.py• L1-10, hermes_cli/kanban_specify.py• L190-234
Task graphs
Decomposition turns one planned item into a dependency graph of smaller work items. Independent children can run in parallel. A child with parents waits in todo until every parent is complete, then becomes ready; the root remains as the coordinating item and wakes when its children finish. The graph is created as one durable change and cyclic graphs are rejected. hermes_cli/kanban_decompose.py• L1-16, hermes_cli/kanban_db_graph.py• L54-166
flowchart TD
ROOT[Planned root item] --> C1[Independent child]
ROOT --> C2[Independent child]
C1 --> C3[Dependent child]
C2 --> C3
C3 --> ROOT
C1 -. done .-> C3
C2 -. done .-> C3
The planner assigns each child to a real profile or to the configured default owner. This prevents a valid graph from becoming stranded because one generated assignee does not exist. hermes_cli/kanban_decompose.py• L156-190
References: hermes_cli/kanban_specify.py• L1-10 hermes_cli/kanban_specify.py• L190-234 hermes_cli/kanban_decompose.py• L1-16 hermes_cli/kanban_decompose.py• L156-190 hermes_cli/kanban_db_graph.py• L54-166
Worker dispatch
Dispatch cycle
The dispatcher is the board’s execution coordinator. On each cycle it first repairs or releases work that can no longer be safely owned, promotes newly unblocked items, and then claims and starts work for eligible assignees. A board-level lock prevents two dispatchers from changing the same board at the same time. hermes_cli/kanban_db_dispatch.py• L1980-2036, hermes_cli/kanban_db_dispatch.py• L2355-2456
Dispatch respects both global and per-profile capacity. It also leaves work queued when the owner profile is unavailable, when a retry guard says that another attempt is unsafe, or when the host is under memory pressure. This separates “waiting for capacity” from “failed work.” hermes_cli/kanban_db_dispatch.py• L2052-2161, gateway/kanban_watchers_dispatcher.py• L46-117
Worker admission
A claim is the time-limited ownership lease that gives one worker authority to act on one work item. The dispatcher records the claim and opens a run before it starts the worker. The worker then presents the exact board, item, run, and claim identity to the assigned profile owner, which admits the run only if the lease is still current. hermes_cli/kanban_db.py• L2124-2168, gateway/session_kanban.py• L14-70
The worker receives a bounded context with the item specification, attachments, earlier attempts, completed parent handoffs, recent role history, and comments. This gives a retry or downstream worker the facts needed to continue without treating old output as current state. hermes_cli/kanban_db.py• L3894-3917, hermes_cli/kanban_db_context.py• L130-239
sequenceDiagram
participant D as Dispatcher
participant B as Board
participant W as Worker client
participant O as Profile owner
D->>B: Claim ready item and open run
D->>W: Start with board and claim identity
W->>O: Submit exact claim
O->>B: Admit claim and build worker context
O->>W: Start supervised run
W->>B: Report progress or terminal handoff
References: hermes_cli/kanban_db_dispatch.py• L1980-2036 hermes_cli/kanban_db_dispatch.py• L2355-2456 hermes_cli/kanban_db.py• L2124-2168 gateway/session_kanban.py• L14-70 hermes_cli/kanban_db.py• L3894-3917 hermes_cli/kanban_db_context.py• L130-239
Progress and notifications
Worker progress
Progress has two forms. A heartbeat proves that a long-running worker is still making observable progress and extends its claim. A comment is durable work communication for a human or a later worker. Normal worker activity can also refresh board liveness without requiring a model tool call. hermes_cli/kanban_db_dispatch.py• L605-640, tools/kanban_tools.py• L519-603
Every terminal handoff records a run outcome and an event. Completion carries a summary and structured facts. Review carries the implementer’s handoff to a reviewer. Blocking records why work cannot continue, while a dependency block returns the item to parent-gated waiting rather than treating it as a human failure. tools/kanban_tools.py• L725-949, hermes_cli/kanban_db.py• L3125-3241
Notification delivery
A notification subscription connects a work item to a platform destination. The notifier tails durable events through a per-subscription cursor, claims unseen events atomically, and delivers terminal or review changes to the right channel. A failed delivery rewinds the cursor for retry; a dead destination is removed only after repeated failures. hermes_cli/kanban_db_notify.py• L67-145, hermes_cli/kanban_db_notify.py• L346-460, gateway/kanban_watchers_notifier.py• L321-384
Some events wake the originating session as well as sending a passive message. The wake includes the worker handoff or review detail so the originating agent can make the next decision without redoing the whole board scan. gateway/kanban_watchers_notifier.py• L47-50, gateway/kanban_watchers_notifier.py• L593-692
References: hermes_cli/kanban_db_dispatch.py• L605-640 tools/kanban_tools.py• L519-603 tools/kanban_tools.py• L725-949 hermes_cli/kanban_db.py• L3125-3241 hermes_cli/kanban_db_notify.py• L67-145 hermes_cli/kanban_db_notify.py• L346-460 gateway/kanban_watchers_notifier.py• L321-384 gateway/kanban_watchers_notifier.py• L593-692
Ownership recovery
Claim recovery
Recovery protects against duplicate workers and lost progress. An expired claim is not released blindly: the system checks worker identity, heartbeat age, host ownership, and any profile-owner admission evidence. A live worker keeps its claim or receives a short defer window; only a worker that is dead or provably no longer executing can be reclaimed. hermes_cli/kanban_db.py• L2317-2429
The dispatcher also handles crashes, time limits, stale progress, broken claim records, and workers that exit without a terminal Kanban handoff. These outcomes close the current run, preserve the cause in the event history, and either requeue the item or trip the failure breaker into blocked. hermes_cli/kanban_db_dispatch.py• L745-850, hermes_cli/kanban_db_dispatch.py• L1060-1137
Owner admission recovery
Profile owners add an admission receipt when they accept a run. Reclaim paths pause while that receipt could still represent an active attempt. They resume only when the owner’s admission is settled or the recorded processes are dead and the claim has no recent heartbeat. Missing or unreadable evidence fails closed. hermes_cli/kanban_owner_recovery.py• L10-62, hermes_cli/kanban_owner_recovery.py• L131-185
This recovery model lets a worker client wait through an owner restart instead of declaring a false failure. The client retries the same attempt and reads the durable receipt, while the board remains the authority for whether that attempt is still valid. hermes_cli/kanban_worker_client.py• L18-24, hermes_cli/kanban_worker_client.py• L59-160
References: hermes_cli/kanban_db.py• L2317-2429 hermes_cli/kanban_db_dispatch.py• L745-850 hermes_cli/kanban_db_dispatch.py• L1060-1137 hermes_cli/kanban_owner_recovery.py• L10-62 hermes_cli/kanban_owner_recovery.py• L131-185 hermes_cli/kanban_worker_client.py• L18-24 hermes_cli/kanban_worker_client.py• L59-160
Workflow resumption
Requeue and re-gating
Resumption returns an item to the phase that makes sense for its last run. An implementation run normally returns to ready; a review run returns to review. Parent links are checked again, so an item returns to todo when an upstream parent has reopened or remains incomplete. hermes_cli/kanban_db.py• L2236-2248, hermes_cli/kanban_db.py• L3551-3599
Review creates a controlled loop between implementer and reviewer. A reviewer can approve the item, request changes back to the original implementer, or raise a real external blocker. Reopening a completed parent invalidates downstream work and re-gates its descendants so old results do not pass as current. hermes_cli/kanban_db.py• L3259-3385, hermes_cli/kanban_db.py• L3408-3550, hermes_cli/kanban_db.py• L3637-3729
Session resumption
A Kanban worker session is not an ordinary user session. A normal CLI, desktop, or TUI resume is refused when the session has Kanban ownership provenance because the resumed process would lack the dispatcher’s claim and supervision. The one exception is the worker process that still carries the dispatcher-granted task identity. hermes_cli/kanban_resume_guard.py• L1-20, hermes_cli/kanban_resume_guard.py• L28-68
This distinction prevents two writers from entering the same workspace. A restarted owner resumes the exact admitted attempt through the managed worker path; a human or orchestrator resumes the workflow by changing the board state and letting the dispatcher create a new supervised run. gateway/session_kanban.py• L83-152
References: hermes_cli/kanban_db.py• L2236-2248 hermes_cli/kanban_db.py• L3551-3599 hermes_cli/kanban_db.py• L3259-3385 hermes_cli/kanban_db.py• L3408-3550 hermes_cli/kanban_db.py• L3637-3729 hermes_cli/kanban_resume_guard.py• L1-20 hermes_cli/kanban_resume_guard.py• L28-68 gateway/session_kanban.py• L83-152
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to task status rules must stay aligned across the workflow definition, dependency promotion, claim paths, review paths, and dashboard/API moves.
- Changes to run ownership must preserve the exact task, run, board, and claim identity across dispatcher spawn, owner admission, worker environment, and lifecycle tool calls.
- Changes to terminal event kinds must update notification cursors, passive delivery, wake delivery, and event-history rendering together.
- Changes to worker resumption must keep the session provenance guard consistent with the managed owner path; otherwise a resumed session can write outside supervision.
- Changes to workspace cleanup or artifact handoff must preserve deliverables before a completed or review handoff removes temporary work.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Two dispatchers tick one board | Duplicate claims or conflicting recovery work | Per-board dispatcher lock and atomic claim |
| A worker exits without a terminal handoff | The item is treated as a failed run even if the process exited cleanly | Crash classification and bounded retry breaker |
| A claim expires while its worker is still alive | A second worker could start in the same workspace | Process identity and heartbeat checks defer reclaim |
| An owner restart interrupts admission | The client may report a false failure or duplicate the run | Durable admission receipt and same-attempt retry |
| A parent reopens after a child starts | Old child output could be accepted as current | Descendant invalidation and parent re-gating |
| Notification delivery fails | The user may miss a terminal state | Atomic event cursor claim with rewind and retry |
| A normal session resumes a Kanban transcript | An unsupervised second writer may enter the workspace | Central resume-time ownership guard |
Key files
| File | Why to read it |
|---|---|
| hermes_cli/kanban_db.py | Core durable task, run, state-transition, workspace, and context contracts |
| hermes_cli/kanban_workflow.py | Board columns and human-requested move rules |
| hermes_cli/kanban_db_graph.py | Parent-child graph creation and dependency gating |
| hermes_cli/kanban_db_dispatch.py | Dispatch ticks, claims, worker failure handling, and recovery |
| gateway/session_kanban.py | Profile-owner admission and supervised worker execution |
| hermes_cli/kanban_owner_recovery.py | Evidence rules for safe reclaim after owner loss |
| hermes_cli/kanban_db_notify.py | Durable notification subscriptions and event cursors |
| gateway/kanban_watchers_notifier.py | Event delivery and session wake behavior |
| hermes_cli/kanban_resume_guard.py | Protection against unsupervised session resumption |
| hermes_cli/kanban_db_context.py | Information passed to a new or resumed worker attempt |