Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / kanban-workflow-execution

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

TriggerConsequenceGuard
Two dispatchers tick one boardDuplicate claims or conflicting recovery workPer-board dispatcher lock and atomic claim
A worker exits without a terminal handoffThe item is treated as a failed run even if the process exited cleanlyCrash classification and bounded retry breaker
A claim expires while its worker is still aliveA second worker could start in the same workspaceProcess identity and heartbeat checks defer reclaim
An owner restart interrupts admissionThe client may report a false failure or duplicate the runDurable admission receipt and same-attempt retry
A parent reopens after a child startsOld child output could be accepted as currentDescendant invalidation and parent re-gating
Notification delivery failsThe user may miss a terminal stateAtomic event cursor claim with rewind and retry
A normal session resumes a Kanban transcriptAn unsupervised second writer may enter the workspaceCentral resume-time ownership guard

Key files

FileWhy to read it
hermes_cli/kanban_db.pyCore durable task, run, state-transition, workspace, and context contracts
hermes_cli/kanban_workflow.pyBoard columns and human-requested move rules
hermes_cli/kanban_db_graph.pyParent-child graph creation and dependency gating
hermes_cli/kanban_db_dispatch.pyDispatch ticks, claims, worker failure handling, and recovery
gateway/session_kanban.pyProfile-owner admission and supervised worker execution
hermes_cli/kanban_owner_recovery.pyEvidence rules for safe reclaim after owner loss
hermes_cli/kanban_db_notify.pyDurable notification subscriptions and event cursors
gateway/kanban_watchers_notifier.pyEvent delivery and session wake behavior
hermes_cli/kanban_resume_guard.pyProtection against unsupervised session resumption
hermes_cli/kanban_db_context.pyInformation passed to a new or resumed worker attempt