{"slug": "hermes-kanban-multi-agent-profile-collaboration", "title": "Hermes Kanban – Multi-Agent Profile Collaboration", "summary": "Hermes Kanban, a durable task board for multi-agent profile collaboration, is now available, allowing multiple named agents to work on tasks via a shared SQLite database and a dedicated kanban_* toolset. The board supports completion checkpoints, circuit breakers, and CLI/dashboard interfaces, with features for research triage, scheduled ops, digital twins, engineering pipelines, and fleet work.", "body_md": "# Kanban — Multi-Agent Profile Collaboration\n\n**Want a walkthrough?** Read the [Kanban tutorial](/docs/user-guide/features/kanban-tutorial) — four user stories (solo dev, fleet farming, role pipeline with retry, circuit breaker) with dashboard screenshots of each. This page is the reference; the tutorial is the narrative.\n\nHermes Kanban is a durable task board, shared across all your Hermes profiles, that lets multiple named agents collaborate on work without fragile in-process subagent swarms. Every task is a row in `~/.hermes/kanban.db`; every handoff is a row anyone can read and write; every worker is a full OS process with its own identity.\n\n### Completion checkpoints before the iteration cap\n\nDispatcher-owned workers get one checkpoint notice near 90% of their finite iteration\nbudget, attached to a fresh tool result while another tool-capable call remains. Use\n`agent.budget_warning_ratio` to choose an earlier threshold. Tiny budgets warn no later\nthan their penultimate iteration; a one-iteration run has no pre-cap checkpoint window.\nThe notice is saved in the session transcript before the next request. Workers should\ncall `kanban_complete` only after verifying the task contract, or persist a progress\ncomment and continue. A commit or diff alone never automatically completes a task.\n\nThe hard cap, toolless final summary, and consecutive-failure circuit breaker are unchanged: workers that still exhaust their budget remain subject to bounded retries. This is a reporting opportunity, not a guarantee that a model will heed the notice. Ordinary conversations and delegated children do not inherit the automatic Kanban checkpoint; their iteration warning remains opt-in.\n\n### Two surfaces: the model talks through tools, you talk through the CLI\n\nThe board has two front doors, both backed by the same `~/.hermes/kanban.db`:\n\n- **Agents drive the board through a dedicated `kanban_*` toolset** —`kanban_show` ,`kanban_list` ,`kanban_complete` ,`kanban_request_review` ,`kanban_request_changes` ,`kanban_block` ,`kanban_heartbeat` ,`kanban_comment` ,`kanban_attach` ,`kanban_attach_url` ,`kanban_attachments` ,`kanban_create` ,`kanban_link` ,`kanban_unblock` . The dispatcher spawns each worker with these tools already in its schema; orchestrator profiles can also enable the`kanban` toolset explicitly. The model reads and routes tasks by calling tools directly,*not* by shelling out to`hermes kanban` . See[How workers interact with the board](#how-workers-interact-with-the-board) below.\n- **You (and scripts, and cron) drive the board through `hermes kanban …`** on the CLI,`/kanban …` as a slash command, or the dashboard. These are for humans and automation — the places without a tool-calling model behind them.\n\nBoth surfaces route through the same `kanban_db` layer, so reads see a consistent view and writes can't drift. The rest of this page shows CLI examples because they're easy to copy-paste, but every CLI verb has a tool-call equivalent the model uses.\n\nThis is the shape that covers the workloads `delegate_task` can't:\n\n- **Research triage** — parallel researchers + analyst + writer, human-in-the-loop.\n- **Scheduled ops** — recurring daily briefs that build a journal over weeks.\n- **Digital twins** — persistent named assistants (`inbox-triage` ,`ops-review` ) that accumulate memory over time.\n- **Engineering pipelines** — decompose → implement in parallel worktrees → review → iterate → PR.\n- **Fleet work** — one specialist managing N subjects (50 social accounts, 12 monitored services).\n\nFor the full design rationale, comparative analysis against Cline Kanban / Paperclip / NanoClaw / Google Gemini Enterprise, and the eight canonical collaboration patterns, see `docs/hermes-kanban-v1-spec.pdf` in the repository.\n\n## PR completion contracts\n\nDeclare PR work at creation with `--completion-contract OWNER/REPO` (or an exact\n`https://github.com/OWNER/REPO/pull/123` URL for existing work). `kanban_create`\naccepts the same `completion_contract`. Use `local-only` for intentionally local\nwork; existing and undeclared cards retain that default. Prose URLs are not policy.\n\nAfter publishing, pass `metadata.published_pr` to completion. The first matching\nURL binds the card permanently; retries cannot substitute a green sibling PR.\nCLI `show --json` and `kanban_show` expose the persisted contract.\n\nThe shared `complete_task` boundary covers worker tools, CLI, review approval and\ndashboard completion. It reads classic branch protection and active ruleset\nrequired contexts, paginates exact-head check runs and legacy statuses, then\nre-reads the PR head/base. Optional failed/skipped telemetry does not veto accepted\nrequired checks. Missing, pending, failed, cancelled, timed-out, stale, skipped or\nneutral **required** evidence cannot complete the card. Neither can zero-run\nacceptance, unreadable policy or GitHub API failures. A repository without required\nchecks needs a local-only contract. `gh` must be authenticated with read access to\nthe repository's checks and rules; no remote writes are performed by this gate.\n\nRejection retains the active card and workspace. Durable `pr_acceptance` events\nstore PR URL, SHA, required contexts, check IDs/URLs, classifications and recovery\ninstructions; `last_failure_error` surfaces the next step. Fix failures, rerun\ninfrastructure checks or wait, then retry completion. Use `kanban_block` when\nhuman action is needed. Generic GitHub `failure` cannot establish whether a test\nor artifact upload failed; inspect its retained URL. Explicit infrastructure\nconclusions and API failures are classified separately. No extra worker is spawned.\n\nReceipt persistence and the terminal write recheck run/status/contract ownership under one SQLite lock: a reclaimed worker cannot complete or attach acceptance to the new run. The final GitHub read is a completion-time snapshot, not a distributed transaction or a continuous post-completion monitor. This is a single-user lifecycle guard, not OS isolation against arbitrary direct database writes. GitHub Enterprise is not covered. Related publication/lifecycle work: #91230, #84254, #52311; local verification and publication alone are not remote acceptance.\n\n## Kanban vs. `delegate_task`\n\nThey look similar; they are not the same primitive.\n\n| | `delegate_task` | Kanban | \n|---|---|---|\n| Shape | RPC call (fork → join) | Durable message queue + state machine | \n| Parent | Blocks until child returns | Fire-and-forget after `create` | \n| Child identity | Anonymous subagent | Named profile with persistent memory | \n| Resumability | None — failed = failed | Block → unblock → re-run; crash → reclaim | \n| Human in the loop | Not supported | Comment / unblock at any point | \n| Agents per task | One call = one subagent | N agents over task's life (retry, review, follow-up) | \n| Audit trail | Lost on context compression | Durable rows in SQLite forever | \n| Coordination | Hierarchical (caller → callee) | Peer — any profile reads/writes any task | \n\n**One-sentence distinction:** `delegate_task` is a function call; Kanban is a work queue where every handoff is a row any profile (or human) can see and edit.\n\n**Use `delegate_task` when** the parent agent needs a short reasoning answer before continuing, no humans involved, result goes back into the parent's context.\n\n**Use Kanban when** work crosses agent boundaries, needs to survive restarts, might need human input, might be picked up by a different role, or needs to be discoverable after the fact.\n\nThey coexist: a kanban worker may call `delegate_task` internally during its run.\n\n## Core concepts\n\n- **Board** — a standalone queue of tasks with its own SQLite DB, workspaces\ndirectory, and dispatcher loop. A single install can have many boards\n(e.g. one per project, repo, or domain); see[Boards (multi-project)](#boards-multi-project) below. Single-project users stay on the`default` board and never see the\nword \"board\" outside this docs section.\n- **Task** — a row with title, optional body, one assignee (a profile name), status (`triage | todo | ready | running | blocked | review | done | archived` ), optional tenant namespace, optional idempotency key (dedup for retried automation).\n- **Link** —`task_links` row recording a parent → child dependency. The dispatcher promotes`todo → ready` when all parents are`done` .\n- **Comment** — the inter-agent protocol. Agents and humans append comments; when a worker is (re-)spawned it reads the full comment thread as part of its context.\n- **Workspace** — the directory a worker operates in. Three kinds:\n - `scratch` (default) — fresh tmp dir under`~/.hermes/kanban/workspaces//` (or`~/.hermes/kanban/boards//workspaces//` on non-default boards).**Deleted when the task completes** — scratch is ephemeral by design. Files explicitly declared through`kanban_complete(artifacts=[...])` are copied into durable per-task attachment storage before cleanup; existing deliverable paths in legacy completion summaries receive the same treatment. Other scratch files are removed. A missing declared scratch artifact keeps the task in-flight so the worker can correct the path and retry. Use`worktree:` or`dir:` when the whole workspace should remain available. The first time a scratch workspace is created on an install, the dispatcher logs a warning and emits a`tip_scratch_workspace` event on the task (visible via`hermes kanban show ` ).\n - `dir:` — an existing shared directory (Obsidian vault, mail ops dir, per-account folder).**Must be an absolute path.** Relative paths like`dir:../tenants/foo/` are rejected at dispatch because they'd resolve against whatever CWD the dispatcher happens to be in, which is ambiguous and a confused-deputy escape vector. The path is otherwise trusted — it's your box, your filesystem, the worker runs with your uid. This is the trusted-local-user threat model; kanban is single-host by design.**Preserved on completion.**\n - `worktree` — a git worktree under`.worktrees//` for coding tasks. Use`worktree:` to pin the exact target path. Worker-side`git worktree add` creates it, using`--branch` when provided.**Preserved on completion.**\n- **Dispatcher** — a long-lived loop that, every N seconds (default 60): reclaims stale claims, reclaims crashed workers (PID gone but TTL not yet expired), promotes ready tasks, atomically claims, spawns assigned profiles. Runs**inside the gateway** by default (`kanban.dispatch_in_gateway: true` ). One dispatcher sweeps all boards per tick; workers are spawned with`HERMES_KANBAN_BOARD` pinned so they can't see other boards. After`kanban.failure_limit` consecutive spawn failures on the same task (default: 2) the dispatcher auto-blocks it with the last error as the reason — prevents thrashing on tasks whose profile doesn't exist, workspace can't mount, etc.\n- **Tenant** — optional string namespace*within* a board. One specialist fleet can serve multiple businesses (`--tenant business-a` ) with data isolation by workspace path and memory key prefix. Tenants are a soft filter; boards are the hard isolation boundary.\n\n## Boards (multi-project)\n\nBoards let you separate unrelated streams of work — one per project, repo,\nor domain — into isolated queues. A new install has exactly one board\ncalled `default` (DB at `~/.hermes/kanban.db` for back-compat). Users who\nonly want one stream of work never need to know about boards; the feature\nis opt-in.\n\nPer-board isolation is absolute:\n\n- Separate SQLite DB per board (`~/.hermes/kanban/boards//kanban.db` ).\n- Separate `workspaces/` and`logs/` directories.\n- Workers spawned for a task see **only** their board's tasks — the\ndispatcher sets`HERMES_KANBAN_BOARD` in the child env and every`kanban_*` tool the worker has access to reads it.\n- Linking tasks across boards is not allowed (keeps the schema simple; if you really need cross-project refs, use free-text mentions and look them up by id manually).\n\n### Managing boards from the CLI\n\n```\n# See what's on disk. Fresh installs show only \"default\".hermes kanban boards list# Create a new board.hermes kanban boards create atm10-server \\ --name \"ATM10 Server\" \\ --description \"Minecraft modded server ops\" \\ --icon 🎮 \\ --switch # optional: make it the active board# Operate on a specific board without switching.hermes kanban --board atm10-server listhermes kanban --board atm10-server create \"Restart ATM server\" --assignee ops# Change which board is \"current\" for subsequent calls.hermes kanban boards switch atm10-serverhermes kanban boards show # who's active right now?# Rename the display name (the slug is immutable — it's the directory name).hermes kanban boards rename atm10-server \"ATM10 (Prod)\"# Archive (default) — moves the board's dir to boards/_archived/-/.# Recoverable by moving the dir back.hermes kanban boards rm atm10-server# Hard delete — `rm -rf` the board dir. No recovery.hermes kanban boards rm atm10-server --delete\n```\n\nBoard resolution order (highest precedence first):\n\n1. Explicit `--board ` on the CLI call.\n2. `HERMES_KANBAN_BOARD` env var (set by the dispatcher when spawning a\nworker, so workers can't see other boards).\n3. `~/.hermes/kanban/current` — the slug persisted by`hermes kanban boards switch` .\n4. `default` .\n\nSlugs are validated: lowercase alphanumerics + hyphens + underscores, 1-64\nchars, must start with alphanumeric. Uppercase input is auto-downcased.\nAnything else (slashes, spaces, dots, `..`) is rejected at the CLI layer\nso path-traversal tricks can't name a board.\n\n### Managing boards from the dashboard\n\n`hermes dashboard` → Kanban tab shows a board switcher at the top as soon\nas more than one board exists (or any board has tasks). Single-board users\nsee only a small `+ New board` button; the switcher is hidden until it\nmatters.\n\n- **Board dropdown** — pick the active board. Your selection is saved to\nthe browser's`localStorage` so it persists across reloads without\nshifting the CLI's`current` pointer out from under a terminal you left\nopen.\n- **+ New board** — opens a modal asking for slug, display name,\ndescription, and icon. Option to auto-switch to the new board.\n- **Settings** — opens a modal for editing the current board's display\nname, description, and**project directory** (`default_workdir` ). The\nproject directory is the board-level workspace default every new task\ninherits (git repo → preserved worktree, plain dir → preserved\ndirectory); each task can still override it at creation time. Clearing\nthe field reverts new tasks to disposable scratch workspaces.\n- **Archive** — only shown on non-`default` boards. Confirms, then moves\nthe board dir to`boards/_archived/` .\n\nAll dashboard API endpoints accept `?board=` for board scoping. The\nevents WebSocket is pinned to a board at connection time; switching in\nthe UI opens a fresh WS against the new board.\n\n## File attachments\n\nTasks can carry file attachments — PDFs, images, source documents — so a worker has the source material it needs without you pasting paths into the body and hoping it finds them.\n\n- **Upload** — open a task in the dashboard drawer and use the**Attachments** section's*Upload file* button (multiple files at once\nare fine). Each upload is capped at 25 MB.\n- **Storage** — files land under`/kanban/attachments//` for the default board, or`/kanban/boards//attachments//` for a named\nboard. Set`HERMES_KANBAN_ATTACHMENTS_ROOT` to pin a custom location.\n- **What the worker sees** — when the dispatcher hands a task to a worker,\nthe worker's context includes an**Attachments** section listing each\nfile's name and its**absolute path** . The worker has full file/terminal\ntool access, so it reads attachments directly (`read_file` , or shell\ntools like`pdftotext` ).\n- **Download / remove** — the drawer lists each attachment with a download\nlink and a remove (×) control. Removing an attachment deletes both the\nmetadata row and the on-disk file.\n\nAttachment paths resolve directly on the **local** terminal backend, which\nis the default for Kanban workers. If you run workers on a remote backend\n(Docker, Modal), mount the board's `attachments/` directory into the\nsandbox so the absolute paths in the worker context are reachable.\n\n## Quick start\n\nThe commands below are **you** (the human) setting up the board and creating tasks. Once a task is assigned, the dispatcher spawns the assigned profile as a worker, and from there **the model drives the task through `kanban_*` tool calls, not CLI commands** — see [How workers interact with the board](#how-workers-interact-with-the-board).\n\n```\n# 1. Create the board (you)hermes kanban init# 2. Start the gateway (hosts the embedded dispatcher)hermes gateway start# 3. Create a task (you — or an orchestrator agent via kanban_create)hermes kanban create \"research AI funding landscape\" --assignee researcher# 4. Watch activity live (you)hermes kanban watch# 5. See the board (you)hermes kanban listhermes kanban stats\n```\n\nWhen the dispatcher picks up `t_abcd` and spawns the `researcher` profile, the very first thing that worker's model does is call `kanban_show()` to read its task. It doesn't run `hermes kanban show t_abcd`.\n\n### Gateway-embedded dispatcher (default)\n\nThe dispatcher runs inside the gateway process. Nothing to install, no separate service to manage — if the gateway is up, ready tasks get picked up on the next tick (60s by default).\n\n```\n# config.yamlkanban: dispatch_in_gateway: true # default dispatch_interval_seconds: 60 # default review_dispatch: true # default: spawn the assigned profile with # the bundled sdlc-review skill. Set false # for human-only review boards.\n```\n\nOverride the config flag at runtime via `HERMES_KANBAN_DISPATCH_IN_GATEWAY=0`\nfor debugging. Standard gateway supervision applies: run `hermes gateway start` directly, or wire the gateway up as a systemd user unit (see the\ngateway docs). Without a running gateway, `ready` tasks stay where they are\nuntil one comes up — `hermes kanban create` warns about this at creation\ntime.\n\nRunning `hermes kanban daemon` as a separate process is **deprecated**;\nuse the gateway. If you truly cannot run the gateway (headless host\npolicy forbids long-lived services, etc.) a `--force` escape hatch keeps\nthe old standalone daemon alive for one release cycle, but running both\na gateway-embedded dispatcher AND a standalone daemon against the same\n`kanban.db` causes claim races and is not supported.\n\n### Idempotent create (for automation / webhooks)\n\n```\n# First call creates the task. Any subsequent call with the same key# returns the existing task id instead of duplicating.hermes kanban create \"nightly ops review\" \\ --assignee ops \\ --idempotency-key \"nightly-ops-$(date -u +%Y-%m-%d)\" \\ --json\n```\n\n### Bulk CLI verbs\n\nAll the lifecycle verbs accept multiple ids so you can clean up a batch in one command:\n\n```\nhermes kanban complete t_abc t_def t_hij --result \"batch wrap\"hermes kanban archive t_abc t_def t_hijhermes kanban unblock t_abc t_defhermes kanban block t_abc \"need input\" --ids t_def t_hij\n```\n\n`unblock` restores the safe source phase: **`review`** for reviewer-origin work\nwhose parents are complete, **`ready`** for implementation work whose parents\nare complete, or **`todo`** while any parent remains open. A `todo` task keeps\nits source-phase provenance and returns to `review` or `ready` automatically\nwhen the dependency gate clears. `unblock` never routes directly to `triage`.\n\nIf you unblock a task and it later shows up in **`triage`**, the unblock is not\nwhat put it there. A subsequent *re-block for the same reason* did: after a task\nis blocked → unblocked → re-blocked for the same cause `BLOCK_RECURRENCE_LIMIT`\ntimes (default `2`), the unblock-loop breaker stops sending it back to `blocked`\n— where a cron would just keep unblocking it — and routes it to `triage` for a\nhuman decision. This is a deterministic DB guard, not an LLM judgment call, and\na task's body text cannot opt out of it: the recurrence counter deliberately\nsurvives each unblock (it resets only on a successful `complete`). To keep an\nunblocked task in the work pool, resolve *why it keeps re-blocking* (unfinished\nparent, missing input, unmet capability) before unblocking, or raise\n`BLOCK_RECURRENCE_LIMIT` if the loop is expected.\n\n## How workers interact with the board\n\n**Workers do not shell out to `hermes kanban`.** When the dispatcher spawns a worker it sets `HERMES_KANBAN_TASK=t_abcd` in the child's env, and that env var flips on a dedicated **kanban toolset** in the model's schema. The same toolset is also available to orchestrator profiles that enable `kanban` in their toolsets config. These tools read and mutate the board directly via the Python `kanban_db` layer, same as the CLI does. A running worker calls these like any other tool; it never sees or needs the `hermes kanban` CLI.\n\n| Tool | Purpose | Required params | \n|---|---|---|\n| `kanban_show` | Read the current task (title, body, prior attempts, parent handoffs, comments, full pre-formatted `worker_context` ). Defaults to the env's task id. | — | \n| `kanban_list` | List task summaries with filters for `assignee` ,`status` ,`tenant` , archived visibility, and limit. Intended for orchestrators discovering board work. | — | \n| `kanban_complete` | Finish with `summary` +`metadata` structured handoff. | at least one of `summary` /`result` | \n| `kanban_request_review` | Start same-card review with a durable `summary` , optional`metadata` , and optional reviewer profile. The task moves to`review` ; this is not a block. | `summary` | \n| `kanban_request_changes` | Reviewer verdict from an active review run. Closes that run, reapplies parent gating, and routes the task to its original implementer without block-loop accounting. | `reason` | \n| `kanban_block` | Stop work and route by why: `kind=dependency` (waits in`todo` , auto-resumes),`needs_input` /`capability` /`transient` (surface to a human). Repeated same-kind re-blocks auto-escalate to`triage` . | `reason` | \n| `kanban_heartbeat` | Signal liveness during long operations. Pure side-effect. | — | \n| `kanban_comment` | Append a durable note to the task thread. | `task_id` ,`body` | \n| `kanban_attach` | Attach a file to a task by passing its bytes inline (base64); stored under the task's attachments dir (25 MB cap). | file bytes + name | \n| `kanban_attach_url` | Attach a file to a task by URL. | `url` | \n| `kanban_attachments` | List a task's attachments. | — | \n| `kanban_create` | (Orchestrators) fan out into child tasks with an `assignee` , optional`parents` ,`skills` , etc. | `title` ,`assignee` | \n| `kanban_link` | (Orchestrators) add a `parent_id → child_id` dependency edge after the fact. | `parent_id` ,`child_id` | \n| `kanban_unblock` | (Orchestrators) restore a blocked task to its source phase ( `review` or`ready` ), or`todo` while a parent remains open. | `task_id` | \n\nA typical worker turn looks like:\n\n```\n# Model's tool calls, in order:kanban_show() # no args — uses HERMES_KANBAN_TASK# (model reads the returned worker_context, does the work via terminal/file tools)kanban_heartbeat(note=\"halfway through — 4 of 8 files transformed\")# (more work)kanban_complete( summary=\"migrated limiter.py to token-bucket; added 14 tests, all pass\", metadata={\"changed_files\": [\"limiter.py\", \"tests/test_limiter.py\"], \"tests_run\": 14},)\n```\n\nAn **orchestrator** worker fans out instead:\n\n```\nkanban_show()kanban_create( title=\"research ICP funding 2024-2026\", assignee=\"researcher-a\", body=\"focus on seed + series A, North America, AI-adjacent\",)# → returns {\"task_id\": \"t_r1\", ...}kanban_create(title=\"research ICP funding — EU angle\", assignee=\"researcher-b\", body=\"…\")# → returns {\"task_id\": \"t_r2\", ...}kanban_create( title=\"synthesize findings into launch brief\", assignee=\"writer\", parents=[\"t_r1\", \"t_r2\"], # promotes to ready when both complete body=\"one-pager, 300 words, neutral tone\",)kanban_complete(summary=\"decomposed into 2 research tasks + 1 writer; linked dependencies\")\n```\n\nThe \"(Orchestrators)\" tools — `kanban_list`, `kanban_create`, `kanban_link`, `kanban_unblock`, and `kanban_comment` on foreign tasks — are available through the same toolset; the convention (encoded in the auto-injected kanban guidance) is that worker profiles don't fan out or route unrelated work, and orchestrator profiles don't execute implementation work. Dispatcher-spawned workers are still task-scoped for destructive lifecycle operations and cannot mutate unrelated tasks.\n\n### Why tools instead of shelling to `hermes kanban`\n\nThree reasons:\n\n1. **Backend portability.** Workers whose terminal tool points at a remote backend (Docker / Modal / Singularity / SSH) would run`hermes kanban complete`*inside* the container, where` hermes` isn't installed and`~/.hermes/kanban.db` isn't mounted. The kanban tools run in the agent's own Python process and always reach`~/.hermes/kanban.db` regardless of terminal backend.\n2. **No shell-quoting fragility.** Passing`--metadata '{\"files\": [...]}'` through shlex + argparse is a latent footgun. Structured tool args skip it entirely.\n3. **Better errors.** Tool results are structured JSON the model can reason about, not stderr strings it has to parse.\n\n**Zero schema footprint on normal sessions.** A regular `hermes chat` session has zero `kanban_*` tools in its schema unless the active profile explicitly enables the `kanban` toolset for orchestrator work. Dispatcher-spawned task workers get task-scoped tools because `HERMES_KANBAN_TASK` is set; orchestrator profiles get the broader routing surface through config. No tool bloat for users who never touch kanban.\n\nThe auto-injected kanban guidance teaches the model which tool to call when and in what order.\n\n### Recommended handoff evidence\n\n`kanban_complete(summary=..., metadata={...})` is intentionally flexible:\nthe summary is the human-readable closeout, and `metadata` is the\nmachine-readable handoff that downstream agents, reviewers, or dashboards can\nreuse without scraping prose.\n\nFor engineering and review tasks, prefer this optional metadata shape:\n\n```\n{ \"changed_files\": [\"path/to/file.py\"], \"verification\": [\"pytest tests/hermes_cli/test_kanban_db.py -q\"], \"dependencies\": [\"parent task id or external issue, if any\"], \"blocked_reason\": null, \"retry_notes\": \"what failed before, if this was a retry\", \"residual_risk\": [\"what was not tested or still needs human review\"]}\n```\n\nThese keys are a convention, not a schema requirement. The useful property is that every worker leaves enough evidence for the next reader to answer four questions quickly:\n\n1. What changed?\n2. How was it verified?\n3. What can unblock or retry this if it fails?\n4. What risk is still deliberately left open?\n\nKeep secrets, raw logs, tokens, OAuth material, and unrelated transcripts out of\n`metadata`. Store pointers and summaries instead. If a task has no files or\ntests, say so explicitly in `summary` and use `metadata` for the evidence that\ndoes exist, such as source URLs, issue ids, or manual review steps.\n\n### The worker lifecycle\n\nEvery profile that works kanban tasks automatically gets the worker lifecycle — it's injected into the worker's system prompt at spawn (the `KANBAN_GUIDANCE` block), so there is **nothing to install or configure**. It teaches the worker the full lifecycle in **tool calls**, not CLI commands:\n\n1. On spawn, call `kanban_show()` to read title + body + parent handoffs + prior attempts + full comment thread.\n2. `cd $HERMES_KANBAN_WORKSPACE` (via the terminal tool) and do the work there.\n3. Call `kanban_heartbeat(note=\"...\")` every few minutes during long operations.**If your work may run longer than 1 hour, call `kanban_heartbeat` at least once an hour** — the dispatcher reclaims tasks that have been running past`kanban.dispatch_stale_timeout_seconds` (default 4 h) with no heartbeat in the last hour, on the assumption the worker crashed without cleanup. A reclaim is benign (the task goes back to`ready` for re-dispatch without a failure-counter tick) but you lose your current run's progress.\n4. Complete with `kanban_complete(summary=\"...\", metadata={...})` , or`kanban_block(reason=\"...\")` if stuck.\n\nThat final `kanban_complete` / `kanban_block` call is part of the worker\nprotocol. If the worker process exits with status 0 while the task is still\n`running`, the dispatcher treats that as a protocol violation and emits a\n`protocol_violation` event.\n\n**Agent-side prevention:** Before the worker exits, Hermes injects up to two\nsynthetic nudges when it detects the model is about to stop without a terminal\nboard tool call. This catches the common case where the model narrates the next\nstep (\"Let me write the report\") and stops with `finish_reason=stop`. The nudge\nreminds the model to call `kanban_complete` or `kanban_block` immediately. This\nguard is active only for dispatcher-spawned workers (`HERMES_KANBAN_TASK` is\nset) and can be disabled with `HERMES_KANBAN_STOP_NUDGE=0`.\n\n**Dispatcher-side recovery:** If the nudges are exhausted or the worker crashes\nbefore reaching the nudge, the dispatcher gives the violation a **bounded retry**\n(up to `_PROTOCOL_VIOLATION_FAILURE_LIMIT` consecutive violations, default 3)\nbefore auto-blocking the task instead of respawning it into the same loop. The\nbudget counts only *consecutive* clean-exit protocol violations — interleaved\nrate-limited requeues are neutral, and any other failure kind resets the\nstreak — and a per-task `max_retries` overrides the bound. This usually means\nthe model wrote a plain-text answer and exited without using the Kanban tool\nsurface.\n\nThe lifecycle plus the load-bearing reference details (workspace kinds, deliverable `artifacts`, claiming created cards) ship in that system-prompt block, so every worker has them regardless of which profile it runs under — no per-profile skill setup required.\n\n### Pinning extra skills to a specific task\n\nSometimes a single task needs specialist context the assignee profile doesn't carry by default — a translation job that needs the `translation` skill, a review task that needs `github-code-review`, a security audit that needs `security-pr-audit`. Rather than editing the assignee's profile every time, attach the skills directly to the task.\n\n**From an orchestrator agent** (the usual case — one agent routing work to another), use the `kanban_create` tool's `skills` array:\n\n```\nkanban_create( title=\"translate README to Japanese\", assignee=\"linguist\", skills=[\"translation\"],)kanban_create( title=\"audit auth flow\", assignee=\"reviewer\", skills=[\"security-pr-audit\", \"github-code-review\"],)\n```\n\n**From a human (CLI / slash command)**, repeat `--skill` for each one:\n\n```\nhermes kanban create \"translate README to Japanese\" \\ --assignee linguist \\ --skill translationhermes kanban create \"audit auth flow\" \\ --assignee reviewer \\ --skill security-pr-audit \\ --skill github-code-review\n```\n\n**From the dashboard**, type the skills comma-separated into the **skills** field of the create-task dialog.\n\nThe dispatcher emits one `--skills ` flag per skill listed, so the worker spawns with all of them loaded on top of the auto-injected kanban guidance. The skill names must match skills that are actually installed on the assignee's profile (run `hermes skills list` to see what's available); there's no runtime install.\n\n### Per-task model override\n\nPin a task's worker to a specific model (and optionally provider), independent of the assignee profile's default:\n\n```\n# At creationhermes kanban create \"hard refactor\" --assignee coder \\ --model claude-opus-4.6 --provider anthropic# Or later — takes effect on the next dispatchhermes kanban set-model t_abcd claude-opus-4.6 --provider anthropichermes kanban set-model t_abcd none # clear the override\n```\n\nThe dispatcher spawns the worker with the pinned model (`--provider ` is passed when set; `--provider` requires a model). The dashboard's per-task model dropdown drives the same `model_override` field. With no override, the worker uses its profile's configured model.\n\n### Cost strategy: frontier orchestrator, inexpensive workers\n\nKanban's per-profile configs make the planner/worker cost split natural. Decomposing a project into well-scoped cards takes frontier-level judgment; executing a card that already carries a clear goal, context, and handoff evidence usually doesn't — and the workers are where the vast majority of tokens are spent, so the worker model is where the cost lives. Run your orchestrator/dispatcher profile on a frontier model and point worker profiles at inexpensive models. Each profile has its own `config.yaml` under `~/.hermes/profiles//`, and the dispatcher injects the profile-scoped `HERMES_HOME` when it spawns `hermes -p `, so each worker reads its own profile's model settings:\n\n```\n# ~/.hermes/config.yaml (orchestrator / dispatcher profile)model: default: \"your-frontier-model\"# ~/.hermes/profiles/coder/config.yaml (worker profile)model: default: \"your-inexpensive-model\"# ~/.hermes/profiles/researcher/config.yaml (another worker profile)model: default: \"your-inexpensive-model\"\n```\n\nFor the occasional quality-sensitive card, pin just that task back to a stronger model with the [per-task model override](#per-task-model-override) (`--model`/`--provider` at create time, `hermes kanban set-model` later, or the dashboard's model dropdown) — no profile edits needed.\n\n### Lifecycle plugin hooks\n\nBoard transitions fire [plugin hooks](/docs/user-guide/features/hooks#plugin-hooks): `kanban_task_claimed`, `kanban_task_completed`, and `kanban_task_blocked`, each carrying `task_id` and `profile_name`. Hooks fire **after** the board DB change commits, so callbacks always see durable state. Note the process split: `kanban_task_claimed` fires in the **dispatcher** process, while `kanban_task_completed`/` kanban_task_blocked` fire in the **worker** process — register the hook in the dispatcher profile to observe every transition centrally.\n\n``` python\ndef register(ctx): def on_blocked(task_id=None, profile_name=None, **kw): ctx.dispatch_tool(\"terminal\", {\"command\": f\"notify-send 'kanban blocked: {task_id}'\"}) ctx.register_hook(\"kanban_task_blocked\", on_blocked)\n```\n\n### Goal-mode cards (`--goal`)\n\nBy default each worker gets **one shot** at its card — do the work, call `kanban_complete`/` kanban_block`, exit. Pass `--goal` (CLI) or `goal_mode=True` (the `kanban_create` tool / dashboard) to instead run that worker in a **goal loop**, the same Ralph-style engine behind the `/goal` slash command: after every turn an auxiliary judge checks the worker's output against the card's title + body (treated as the acceptance criteria), and if the work isn't done — and the turn budget remains — the worker keeps going **in the same session** until the judge agrees, the worker terminates the task itself, or the budget runs out (which **blocks** the card for human review rather than exiting silently). If the judge rules the goal **unachievable** as written, the card is blocked immediately with the judge's reason — an impossible card is never marked done, and `kanban complete` / `kanban request-review` on such a card are rejected with a pointer to `kanban block` or re-scoping.\n\n```\nhermes kanban create \"Translate the docs site to French\" \\ --body \"Acceptance: every page translated, no English left, links intact.\" \\ --assignee linguist \\ --goal \\ --goal-max-turns 15 # optional; default 20\n```\n\nUse it for open-ended, multi-step, or \"keep going until X is true\" cards. Skip it for cheap one-shot work — the per-turn judge overhead isn't worth it, and the dispatcher's existing retry/circuit-breaker already handles transient worker failures. The judge is only as good as your goal text, so write the body as **explicit acceptance criteria**.\n\n`/goal` engine — they don't connect to it\n`--goal` runs the continuation loop *inside that one card's worker session*. It shares the engine with the [`/goal` slash command](/docs/user-guide/features/goals), not the state: setting a `/goal` in a chat session never creates, claims, or moves a kanban card, and a goal-mode card's loop is invisible to any chat session's `/goal status`. If you want this conversation to keep iterating, use [`/goal`](/docs/user-guide/features/goals); if you want work on the board, create a card.\n\n### How the orchestrator behaves\n\nA **well-behaved orchestrator does not do the work itself.** It decomposes the user's goal into tasks, links them, assigns each to one of the profiles you've set up, and steps back. The orchestrator guidance — anti-temptation rules, a Step-0 profile-discovery prompt (the dispatcher silently fails on unknown assignee names, so the orchestrator must ground every card in profiles that actually exist on your machine), and a decomposition playbook keyed on `kanban_create` / `kanban_link` / `kanban_comment` — is injected into the worker's system prompt automatically; there is nothing to install.\n\nA canonical orchestrator turn (two parallel researchers handing off to a writer):\n\n```\n# Goal from user: \"draft a launch post on the ICP funding landscape\"kanban_create(title=\"research ICP funding, NA angle\", assignee=\"researcher-a\", body=\"…\") # → t_r1kanban_create(title=\"research ICP funding, EU angle\", assignee=\"researcher-b\", body=\"…\") # → t_r2kanban_create( title=\"synthesize ICP funding research into launch post draft\", assignee=\"writer\", parents=[\"t_r1\", \"t_r2\"], # promoted to 'ready' when both researchers complete body=\"one-pager, neutral tone, cite sources inline\",) # → t_w1# Optional: add cross-cutting deps discovered later without re-creating taskskanban_link(parent_id=\"t_r1\", child_id=\"t_followup\")kanban_complete( summary=\"decomposed into 2 parallel research tasks → 1 synthesis task; writer starts when both researchers finish\",)\n```\n\nThe orchestrator guidance ships in the worker's system prompt automatically — there is nothing to install or sync per profile.\n\n**Decide before you fan out.** Design decisions belong to the orchestrator, not to the workers. If two parallel cards would each have to pick the same thing — a naming scheme, a schema, a file format, an API shape — the orchestrator decides it once and stamps the decision into **both** card bodies. Workers cannot see sibling cards, so every child card body must carry every decision it depends on. Example: for the parallel cards \"build the exporter\" and \"build the importer\", don't let each worker invent its own file format — pick one up front (say, newline-delimited JSON with a `version` field) and write it into both bodies, or the two halves will never round-trip.\n\nFor best results, pair it with a profile whose toolsets are restricted to board operations (`kanban`, `gateway`, `memory`) so the orchestrator literally cannot execute implementation tasks even if it tries.\n\n## Dashboard (GUI)\n\nThe `/kanban` CLI and slash command are enough to run the board headlessly, but a visual board is often the right interface for humans-in-the-loop: triage, cross-profile supervision, reading comment threads, and dragging cards between columns. Hermes ships this as a **bundled dashboard plugin** at `plugins/kanban/` — not a core feature, not a separate service — following the model laid out in [Extending the Dashboard](/docs/user-guide/features/extending-the-dashboard).\n\nOpen it with:\n\n```\nhermes kanban init # one-time: create kanban.db if not already presenthermes dashboard # \"Kanban\" tab appears in the nav, after \"Skills\"\n```\n\n### What the plugin gives you\n\n- A **Kanban** tab showing one column per status:`triage` ,`todo` ,`ready` ,`running` ,`blocked` ,`done` (plus`archived` when the toggle is on).\n - `triage` is the parking column for rough ideas. By default (`kanban.auto_decompose: true` ), the dispatcher auto-runs the**decomposer** on tasks that land here. The built-in decomposer uses the`auxiliary.kanban_decomposer` model path, reads your profile roster (with descriptions), and fans the task out into a small graph of child tasks routed to the best-fit specialists. The original task stays alive as the parent of every child so its assignee (`kanban.orchestrator_profile` , or the active default profile when unset) wakes back up to judge completion when everything finishes. Flip the**Orchestration: Auto/Manual** pill at the top of the page (emerald = Auto, muted gray = Manual), or by editing`config.yaml` directly. Both modes coexist with`hermes kanban specify` - that's still available as a single-task spec rewrite when you don't want fan-out.\n- Cards show the task id, title, priority badge, tenant tag, assigned profile, comment/link counts, a **progress pill** (`N/M` children done when the task has dependents), and \"created N ago\". A per-card checkbox enables multi-select.\n- **Per-profile lanes inside Running** — toolbar checkbox toggles sub-grouping of the Running column by assignee.\n- **Live updates via WebSocket** — the plugin tails the append-only`task_events` table on a short poll interval; the board reflects changes the instant any profile (CLI, gateway, or another dashboard tab) acts. Reloads are debounced so a burst of events triggers a single refetch.\n- **Drag-drop** cards between columns to change status. The drop sends`PATCH /api/plugins/kanban/tasks/:id` which routes through the same`kanban_db` code the CLI uses — the three surfaces can never drift. Moves into destructive statuses (`done` ,`archived` ,`blocked` ) prompt for confirmation. Touch devices use a pointer-based fallback so the board is usable from a tablet.\n- **Create-task dialog** — click`+` on any column header to open a modal with labeled fields: title, assignee, priority, skills, workspace kind/path (seeded from the board's project directory; per-task override), goal mode, and (optionally) a parent task from a dropdown over every existing task. Press Enter to create the task, Shift+Enter to insert a newline in the title field, or Escape to cancel. Creating from the Triage column automatically parks the new task in triage.\n- **Multi-select with bulk actions** — shift/ctrl-click a card or tick its checkbox to add it to the selection. A bulk action bar appears at the top with batch status transitions, archive, and reassign (by profile dropdown, or \"(unassign)\"). Destructive batches confirm first. Per-id partial failures are reported without aborting the rest.\n- **Click a card** (without shift/ctrl) to open a side drawer (Escape or click-outside closes) with:\n - **Editable title** — click the heading to rename.\n - **Editable assignee / priority** — click the meta row to rewrite.\n - **Editable description** — markdown-rendered by default (headings, bold, italic, inline code, fenced code,`http(s)` /`mailto:` links, bullet lists), with an \"edit\" button that swaps in a textarea. Markdown rendering is a tiny, XSS-safe renderer — every substitution runs on HTML-escaped input, only`http(s)` /`mailto:` links pass through, and`target=\"_blank\"` +`rel=\"noopener noreferrer\"` are always set.\n - **Dependency editor** — chip list of parents and children, each with an`×` to unlink, plus dropdowns over every other task to add a new parent or child. Cycle attempts are rejected server-side with a clear message.\n - **Status action row** (→ triage / → ready / → running / block / unblock / complete / archive) with confirm prompts for destructive transitions. For cards in the**Triage** column the row also exposes two LLM-driven actions:**⚗ Decompose** fans the task out into a graph of child tasks routed to specialist profiles by description, and**✨ Specify** does a single-task spec rewrite. Decompose falls back to specify-style promotion when the LLM decides the task doesn't benefit from fan-out, so it's a strict superset. Both are reachable from the CLI (`hermes kanban decompose ` /`specify ` /`--all` ), from any gateway platform (`/kanban decompose ` ), and programmatically via`POST /api/plugins/kanban/tasks/:id/decompose` and`…/specify` . Configure the models under`auxiliary.kanban_decomposer` and`auxiliary.triage_specifier` in`config.yaml` .\n - Result section (also markdown-rendered), comment thread with Enter-to-submit, the last 20 events.\n- **Toolbar filters** — free-text search, tenant dropdown (defaults to`dashboard.kanban.default_tenant` from`config.yaml` ), assignee dropdown, \"show archived\" toggle, \"lanes by profile\" toggle, and a**Nudge dispatcher** button so you don't have to wait for the next 60 s tick.\n\nVisually the target is the familiar Linear / Fusion layout: dark theme, column headers with counts, coloured status dots, pill chips for priority and tenant. The plugin reads only theme CSS vars (`--color-*`, `--radius`, `--font-mono`, ...), so it reskins automatically with whichever dashboard theme is active.\n\n### Auto vs Manual orchestration\n\nThe kanban board has two ways to handle a task you drop into the Triage column:\n\n**Auto (default)** — `kanban.auto_decompose: true`. The gateway-embedded dispatcher runs the **decomposer** on each tick, capped by `kanban.auto_decompose_per_tick` (default 3 tasks per tick) so a bulk-load of triage tasks doesn't burst-spend the auxiliary LLM. The decomposer uses the built-in decomposition prompt plus the `auxiliary.kanban_decomposer` model path, reads your installed profiles + their descriptions, and asks the LLM to produce a JSON task graph: which tasks to spawn, who they go to, and which depend on which. The original triage task becomes the parent of every leaf in the graph, so it stays alive until the whole graph completes - and then promotes back to `ready` so its assignee (`kanban.orchestrator_profile`, or the active default profile when unset) can judge completion and add more tasks if the work isn't done. This is the \"drop a one-liner, walk away\" flow.\n\nA completed built-in fan-out is recorded atomically with its child graph. Moving that root back to Triage does not create another graph; ordinary prerequisite links do not prevent a task's first decomposition. The completion marker survives event retention until the task is deleted. This is not semantic deduplication of independently created manual graphs, nor a repair for previously pruned history.\n\nWhen a new task omits its tenant, creation inherits the first nonempty tenant among its parents, in supplied order. An explicit tenant (including the worker's active tenant passed by tools) wins. Boards remain the hard isolation boundary.\n\n**Manual** — `kanban.auto_decompose: false`. Triage tasks stay in triage until you act. Click the **⚗ Decompose** button on a card, run `hermes kanban decompose ` (or `--all`), or use `/kanban decompose ` from a chat. This matches the pre-decomposer behavior of the board, useful when you want full control over what runs when.\n\n**Important boundary:** Manual mode disables only the built-in Triage decomposer. It does not prevent a profile from calling `kanban_create`, and it does not disable creator-session wake-ups. With `kanban.auto_subscribe_on_create: true`, a task's terminal event resumes the originating agent with a synthetic status turn so it can inspect the handoff and decide whether genuinely new follow-up work is needed. Set `auto_subscribe_on_create: false` when task completion should remain passive. For provenance, built-in decomposer children use `created_by=auto-decomposer`; tasks created by a resumed profile carry that profile name instead.\n\nFlip between the two modes from the **Orchestration: Auto/Manual** pill at the top of the kanban page (emerald = Auto, muted gray = Manual), or by editing `config.yaml` directly. Both modes coexist with `hermes kanban specify` — that's still available as a single-task spec rewrite when you don't want fan-out.\n\nThe decomposer's routing decisions depend on profile descriptions, which is a per-profile labeling primitive you set with `hermes profile create --description \"...\"`, `hermes profile describe --text \"...\"`, `hermes profile describe --auto` (LLM-generates from the profile's installed skills + model), or the dashboard's per-profile editor in the expanded **Orchestration settings** panel. Profiles without a description still appear in the roster — they're routable by name, just less precisely. The decomposer NEVER lands a child task with `assignee=None`: when the LLM picks an unknown profile, the child gets routed to `kanban.default_assignee` (or the active default profile if that's unset).\n\n`kanban.orchestrator_profile` does not load that profile's prompt, skills, or custom logic into the decomposition call. It controls who owns the root/orchestration task after fan-out. To change the decomposer's model/provider, configure `auxiliary.kanban_decomposer`. To use a profile's custom task-splitting logic instead of the built-in decomposer, switch to Manual mode and have that profile create or decompose tasks explicitly.\n\nConfig knobs (all under `kanban:` in `~/.hermes/config.yaml`):\n\n| Key | Default | Purpose | \n|---|---|---|\n| `auto_decompose` | `true` | Dispatcher auto-runs the built-in decomposer for Triage tasks every tick. It does not gate profile-driven `kanban_create` calls or creator wake turns. | \n| `auto_decompose_per_tick` | `3` | Cap on decompositions per dispatcher tick. Excess defers to the next tick. | \n| `orchestrator_profile` | `\"\"` | Profile assigned to the root/orchestration task after decomposition. Empty = fall back to active default profile. | \n| `default_assignee` | `\"\"` | Where a child task lands when the LLM picks an unknown profile. Empty = fall back to active default. | \n| `auto_subscribe_on_create` | `true` | When `kanban_create` runs inside a persistent gateway/TUI session, terminal events resume that originating agent with a synthetic status turn. Set to`false` for passive completion or to require explicit`kanban_notify-subscribe` calls. Independent of`auto_decompose` . | \n| `done_sub_retention_days` | `30` | Notify subscriptions survive `done` (reopen-safe) and are removed on`archived` . The notifier GC purges subscriptions whose task has been`done` or`blocked` with no new events for this many days, bounding sub-table growth on boards that never archive.`0` disables the sweep. | \n\nAnd the two auxiliary LLM slots:\n\n| Key | Purpose | \n|---|---|\n| `auxiliary.kanban_decomposer` | Model that produces the task graph (called by Decompose). Set `provider` /`model` to override the main chat model. | \n| `auxiliary.profile_describer` | Model that auto-generates profile descriptions (called by `hermes profile describe --auto` ). | \n\n### Architecture\n\nThe GUI is strictly a **read-through-the-DB + write-through-kanban_db** layer with no domain logic of its own:\n\n```\n┌────────────────────────┐ WebSocket (tails task_events)│ React SPA (plugin) │ ◀──────────────────────────────────┐│ HTML5 drag-and-drop │ │└──────────┬─────────────┘ │ │ REST over fetchJSON │ ▼ │┌────────────────────────┐ writes call kanban_db.* ││ FastAPI router │ directly — same code path ││ plugins/kanban/ │ the CLI /kanban verbs use ││ dashboard/plugin_api.py │└──────────┬─────────────┘ │ │ │ ▼ │┌────────────────────────┐ ││ ~/.hermes/kanban.db │ ───── append task_events ──────────┘│ (WAL, shared) │└────────────────────────┘\n```\n\n### REST surface\n\nAll routes are mounted under `/api/plugins/kanban/` and protected by the dashboard's ephemeral session token:\n\n| Method | Path | Purpose | \n|---|---|---|\n| `GET` | `/board?tenant=&include_archived=…` | Full board grouped by status column, plus tenants + assignees for filter dropdowns | \n| `GET` | `/tasks/:id` | Task + comments + events + links | \n| `POST` | `/tasks` | Create (wraps `kanban_db.create_task` , accepts`triage: bool` and`parents: [id, …]` ) | \n| `PATCH` | `/tasks/:id` | Status / assignee / priority / title / body / result | \n| `POST` | `/tasks/bulk` | Apply the same patch (status / archive / assignee / priority) to every id in `ids` . Per-id failures reported without aborting siblings | \n| `POST` | `/tasks/:id/comments` | Append a comment | \n| `POST` | `/tasks/:id/specify` | Run the triage specifier — auxiliary LLM fleshes out the task body and promotes it from `triage` to`todo` . Returns`{ok, task_id, reason, new_title}` ;`ok=false` with a human-readable reason on \"not in triage\" / no aux client / LLM error is a 200, not a 4xx | \n| `POST` | `/tasks/:id/decompose` | Run the kanban decomposer — auxiliary LLM produces a task graph and the helper atomically creates the children + links the root + flips `triage → todo` . Returns`{ok, task_id, reason, fanout, child_ids, new_title}` . Same 200-on-LLM-error convention as`/specify` . | \n| `GET` | `/profiles` | List installed profiles with their descriptions (consumed by the dashboard's profile-description editor and the orchestrator picker). | \n| `PATCH` | `/profiles/:name` | Set or clear a profile's description (user-authored — `description_auto: false` ). Returns`{ok, profile, description}` . | \n| `POST` | `/profiles/:name/describe-auto` | Generate a description for a profile via `auxiliary.profile_describer` . Persists with`description_auto: true` so the dashboard can surface a \"review\" badge. | \n| `GET` | `/orchestration` | Read the kanban orchestration settings ( `orchestrator_profile` ,`default_assignee` ,`auto_decompose` ) plus the*resolved* effective values after fallbacks. | \n| `PUT` | `/orchestration` | Update one or more of the three orchestration keys in `config.yaml` . Validates that non-empty profile names actually exist. | \n| `POST` | `/links` | Add a dependency ( `parent_id` →`child_id` ) | \n| `DELETE` | `/links?parent_id=…&child_id=…` | Remove a dependency | \n| `POST` | `/dispatch?max=…&dry_run=…` | Nudge the dispatcher — skip the 60 s wait | \n| `GET` | `/config` | Read `dashboard.kanban` preferences from`config.yaml` —`default_tenant` ,`lane_by_profile` ,`include_archived_by_default` ,`render_markdown` | \n| `WS` | `/events?since=` | Live stream of `task_events` rows | \n\nEvery handler is a thin wrapper — the plugin is ~700 lines of Python (router + WebSocket tail + bulk batcher + config reader) and adds no new business logic. A tiny `_conn()` helper auto-initializes `kanban.db` on every read and write, so a fresh install works whether the user opened the dashboard first, hit the REST API directly, or ran `hermes kanban init`.\n\n### Dashboard config\n\nAny of these keys under `dashboard.kanban` in `~/.hermes/config.yaml` changes the tab's defaults — the plugin reads them at load time via `GET /config`:\n\n```\ndashboard: kanban: default_tenant: acme # preselects the tenant filter lane_by_profile: true # default for the \"lanes by profile\" toggle include_archived_by_default: false render_markdown: true # set false for plain 
 rendering\n```\n\nEach key is optional and falls back to the shown default.\n\n### Security model\n\nThe dashboard's HTTP auth middleware [explicitly skips `/api/plugins/`](/docs/user-guide/features/extending-the-dashboard#backend-api-routes) — plugin routes are unauthenticated by design because the dashboard binds to localhost by default. That means the kanban REST surface is reachable from any process on the host.\n\nThe WebSocket takes one additional step: it requires the dashboard's ephemeral session token as a `?token=…` query parameter (browsers can't set `Authorization` on an upgrade request), matching the pattern used by the in-browser PTY bridge.\n\nIf you run `hermes dashboard --host 0.0.0.0`, every plugin route — kanban included — becomes reachable from the network. **Don't do that on a shared host.** The board contains task bodies, comments, and workspace paths; an attacker reaching these routes gets read access to your entire collaboration surface and can also create / reassign / archive tasks.\n\nTasks in `~/.hermes/kanban.db` are profile-agnostic on purpose (that's the coordination primitive). If you open the dashboard with `hermes -p  dashboard`, the board still shows tasks created by any other profile on the host. Same user owns all profiles, but this is worth knowing if multiple personas coexist.\n\n### Live updates\n\n`task_events` is an append-only SQLite table with a monotonic `id`. The WebSocket endpoint holds each client's last-seen event id and pushes new rows as they land. When a burst of events arrives, the frontend reloads the (very cheap) board endpoint — simpler and more correct than trying to patch local state from every event kind. WAL mode means the read loop never blocks the dispatcher's `BEGIN IMMEDIATE` claim transactions.\n\n### Extending it\n\nThe plugin uses the standard Hermes dashboard plugin contract — see [Extending the Dashboard](/docs/user-guide/features/extending-the-dashboard) for the full manifest reference, shell slots, page-scoped slots, and the Plugin SDK. Extra columns, custom card chrome, tenant-filtered layouts, or full `tab.override` replacements are all expressible without forking this plugin.\n\nTo disable without removing: add `dashboard.plugins.kanban.enabled: false` to `config.yaml` (or delete `plugins/kanban/dashboard/manifest.json`).\n\n### Scope boundary\n\nThe GUI is deliberately thin. Everything the plugin does is reachable from the CLI; the plugin just makes it comfortable for humans. Auto-assignment, budgets, governance gates, and org-chart views remain user-space — a router profile, another plugin, or a reuse of `tools/approval.py` — exactly as listed in the out-of-scope section of the design spec.\n\n## CLI command reference\n\nThis is the surface **you** (or scripts, cron, the dashboard) use to drive the board. Workers running inside the dispatcher use the `kanban_*` [tool surface](#how-workers-interact-with-the-board) for the same operations — the CLI here and the tools there both route through `kanban_db`, so the two surfaces agree by construction.\n\n```\nhermes kanban init                                     # create kanban.db + print daemon hinthermes kanban create \"\" [--body ...] [--assignee <profile>]                                [--parent <id>]... [--tenant <name>]                                [--workspace scratch|worktree|worktree:<path>|dir:<path>]                                [--branch <name>]                                [--priority N] [--triage] [--idempotency-key KEY]                                [--max-runtime 30m|2h|1d|<seconds>]                                [--max-retries N]                                [--goal] [--goal-max-turns N]                                [--skill <name>]...                                [--json]hermes kanban list [--mine] [--assignee P] [--status S] [--tenant T] [--archived]        [--workflow-template-id <id>] [--current-step-key <key>]        [--sort created|created-desc|priority|priority-desc|status|assignee|title|updated]        [--json]hermes kanban show <id> [--json]hermes kanban assign <id> <profile>                    # or 'none' to unassignhermes kanban reassign <id>... <profile>               # bulk re-assign tasks to a profilehermes kanban edit <id> [--title ...] [--body ...]     # edit task title / body / priority in place        [--priority N]hermes kanban promote <id>...                          # move todo/blocked tasks to ready (recovery)hermes kanban schedule <id> --at <ISO8601>             # set/clear a task's scheduled_at start timehermes kanban diagnostics [--json]                     # board health snapshot (alias: diag)hermes kanban link <parent_id> <child_id>hermes kanban unlink <parent_id> <child_id>hermes kanban claim <id> [--ttl SECONDS]hermes kanban comment <id> \"<text>\" [--author NAME]# Bulk verbs — accept multiple ids:hermes kanban complete <id>... [--result \"...\"]hermes kanban block <id> \"<reason>\" [--ids <id>...]hermes kanban unblock <id>...hermes kanban archive <id>...hermes kanban request-review <id> [--summary \"...\"] [--metadata JSON] [--reviewer PROFILE]hermes kanban request-changes <id> \"<required changes>\"               # active reviewer -> implementerhermes kanban reopen-review  <id>... [--reason \"...\"]                 # changes requested: 'review' -> ready/todohermes kanban tail <id>                                # follow a single task's event streamhermes kanban watch [--assignee P] [--tenant T]        # live stream ALL events to the terminal        [--kinds completed,blocked,…] [--interval SECS]hermes kanban heartbeat <id> [--note \"...\"]            # worker liveness signal for long opshermes kanban runs <id> [--json]                       # attempt history (one row per run)hermes kanban assignees [--json]                       # profiles on disk + per-assignee task countshermes kanban dispatch [--dry-run] [--max N]           # one-shot pass        [--failure-limit N] [--json]hermes kanban daemon --force                           # DEPRECATED — standalone dispatcher (use `hermes gateway start` instead)        [--failure-limit N] [--pidfile PATH] [-v]hermes kanban stats [--json]                           # per-status + per-assignee countshermes kanban log <id> [--tail BYTES]                  # worker log from ~/.hermes/kanban/logs/hermes kanban notify-subscribe <id>                    # gateway bridge hook (used by /kanban in the gateway)        --platform <name> --chat-id <id> [--thread-id <id>] [--user-id <id>]        [--chat-type dm|group|channel|thread] [--delivery-mode notify|notify+wake|wake]hermes kanban notify-list [<id>] [--json]hermes kanban notify-unsubscribe <id>        --platform <name> --chat-id <id> [--thread-id <id>]hermes kanban context <id>                             # what a worker seeshermes kanban specify [<id> | --all] [--tenant T]      # flesh out a triage-column idea        [--author NAME] [--json]                       #   into a full spec and promote to todohermes kanban gc [--event-retention-days N]            # workspaces + old events + old logs        [--log-retention-days N]\n```\n\nAll commands are also available as a slash command in the interactive CLI and in the messaging gateway (see [`/kanban` slash command](#kanban-slash-command) below).\n\n`--max-retries` is a per-task circuit-breaker override for the dispatcher. `--max-retries 1` blocks the task on the first non-successful attempt, while `--max-retries 3` allows two retries and blocks on the third failure. Omit it to use `kanban.failure_limit` from `config.yaml`, then the built-in default.\n\n### Concurrency, scheduling, and child promotion config\n\n| Config key | Default | What it does | \n|---|---|---|\n| `kanban.max_in_progress` | unset (unlimited) | Caps the number of simultaneously running tasks. When the board already has N running, the dispatcher skips spawning more — useful for slow workers (local LLMs, resource-constrained hosts) so they finish what they have before more pile up and time out. Invalid or below-1 values log a warning and behave as unlimited. | \n| `kanban.max_in_progress_per_profile` | unset (unlimited) | Per-profile variant of `max_in_progress` — caps how many tasks any single assignee profile may run concurrently. Useful when one profile is slow or rate-limited but others should keep flowing. Applies alongside the board-wide`max_in_progress` ; both must allow a spawn for it to proceed. | \n| `kanban.auto_promote_children` | `true` | After `decompose_triage_task()` produces children with no parent-blocker dependencies, they're automatically promoted to`ready` so the dispatcher can pick them up. Set to`false` to require manual review — children stay in`todo` until you promote them. | \n| `kanban.default_workdir` | unset | Board-level default working directory applied to new tasks when neither `--workspace` nor the task itself overrides it. Per-task`workspace:` still wins. | \n\n```\nkanban:  max_in_progress: 2  auto_promote_children: false  default_workdir: ~/work/active-project\n```\n\n### Scheduled task starts (`scheduled_at`)\n\nSet `scheduled_at` on a task to delay dispatch until a specific time. The dispatcher skips ready tasks whose `scheduled_at` is in the future and picks them up on the first tick after that timestamp.\n\n```\nhermes kanban create \"nightly backup audit\" \\  --assignee ops --scheduled-at \"2026-06-01T03:00:00Z\"\n```\n\n### Respawn guard\n\nThe dispatcher refuses to re-spawn a ready task when it hit a quota/auth/429 error on the previous run (`blocker_auth`), or completed a run successfully within the guard window (` recent_success`), or a recent task comment links to a GitHub PR (` active_pr`). This prevents repeat worker storms on the same bug or task while a human catches up. See the `respawn_guarded` row in the [event reference](#event-reference).\n\n### Drag-to-delete and bulk delete (dashboard)\n\nThe dashboard exposes a **trash drop zone** on the kanban page — drag any card into it to delete the task (cascades through `task_events`, child links, and subscriptions). A confirmation prompt protects against accidents. Bulk delete is also reachable via `DELETE /api/plugins/kanban/tasks` with a JSON body `{\"ids\": [\"t_abc\", \"t_def\", ...]}`.\n\n### Worker visibility endpoints\n\nThe dashboard plugin API now exposes these read-only endpoints (plus a run-control verb) for external monitors:\n\n| Endpoint | Returns | \n|---|---|\n| `GET /api/plugins/kanban/workers/active` | Currently spawned workers with PID, profile, task id, started-at, last heartbeat | \n| `GET /api/plugins/kanban/runs/{id}` | Single-run detail — task id, status, started/ended, exit code, log path | \n| `POST /api/plugins/kanban/runs/{run_id}/terminate` | Terminate a reclaimable run — stops the worker and frees the task for re-dispatch | \n| `GET /api/plugins/kanban/inspect` | Combined dispatcher snapshot — backlog, in-progress count vs. `max_in_progress` , recent events | \n\nAll of these are gated by the same dashboard plugin auth as the rest of the kanban plugin API.\n\n### Kanban Swarm topology helper\n\n`hermes kanban swarm` creates a durable **Kanban Swarm v1** graph in one shot: a completed root/blackboard card, N parallel worker cards, a verifier card gated on all workers, and a synthesizer card gated on the verifier. Shared swarm context (the \"blackboard\") is stored as structured JSON comments on the root card so any worker can read it.\n\n```\nhermes kanban swarm \"Design a multi-region failover plan\" \\  --workers researcher,architect,sre \\  --verifier reviewer --synthesizer writer\n```\n\nThe resulting graph is committed atomically: dispatchers and dashboard readers see either no new swarm or the complete topology, never a partially linked root/worker/verifier graph. It then dispatches normally — workers run in parallel, the verifier wakes after they all finish, and the synthesizer wakes after the verifier marks the work clean.\n\n## `/kanban` slash command\n\nEvery `hermes kanban <action>` verb is also reachable as `/kanban <action>` — from inside an interactive `hermes chat` session **and** from any gateway platform (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, email, SMS). Both surfaces call the exact same `hermes_cli.kanban.run_slash()` entry point that reuses the `hermes kanban` argparse tree, so the argument surface, flags, and output format are identical across CLI, `/kanban`, and `hermes kanban`. You don't have to leave the chat to drive the board.\n\n```\n/kanban list/kanban show t_abcd/kanban create \"write launch post\" --assignee writer --parent t_research/kanban comment t_abcd \"looks good, ship it\"/kanban unblock t_abcd/kanban dispatch --max 3/kanban specify t_abcd                  # flesh out a triage one-liner into a real spec/kanban specify --all --tenant engineering  # sweep every triage task in one tenant\n```\n\nQuote multi-word arguments the same way you would on a shell — `run_slash` parses the rest of the line with `shlex.split`, so `\"...\"` and `'...'` both work.\n\n### Mid-run usage: `/kanban` bypasses the running-agent guard\n\nThe gateway normally queues slash commands and user messages while an agent is still thinking — that's what stops you from accidentally starting a second turn while the first is in flight. **`/kanban` is explicitly exempted from this guard.** The board lives in `~/.hermes/kanban.db`, not in the running agent's state, so reads (` list`, `show`, `context`, `tail`, `watch`, `stats`, `runs`) and writes (` comment`, `unblock`, `block`, `assign`, `archive`, `create`, `link`, …) all go through immediately, even mid-turn.\n\nThis is the whole point of the separation:\n\n- A worker blocks waiting on a peer → you send `/kanban unblock t_abcd` from your phone and the dispatcher picks the peer up on its next tick. The blocked worker isn't interrupted — it just stops being blocked.\n- You spot a card that needs human context → `/kanban comment t_xyz \"use the 2026 schema, not 2025\"` lands on the task thread and the*next* run of that task will read it in`kanban_show()` .\n- You want to know what your fleet is doing without stopping the orchestrator → `/kanban list --mine` or`/kanban stats` inspects the board without touching your main conversation.\n\n### Auto-subscribe on `/kanban create` (gateway only)\n\nWhen you create a task from the gateway with `/kanban create \"…\"`, the originating chat (platform + chat id + thread id) is automatically subscribed to that task's terminal events (`completed`, `blocked`, `gave_up`, `crashed`, `timed_out`). You'll get one message back per terminal event — including the first line of the worker's result summary on `completed` — without having to poll or remember the task id.\n\n```\nyou> /kanban create \"transcribe today's podcast\" --assignee transcriberbot> Created t_9fc1a3  (ready, assignee=transcriber)     (subscribed — you'll be notified when t_9fc1a3 completes or blocks)… ~8 minutes later …bot> ✓ t_9fc1a3 completed by transcriber     transcribed 42 minutes, saved to podcast/2026-05-04.md\n```\n\nSubscriptions survive a task reaching `done` — completion is reversible (a reviewer or controller can reopen a done task), so the origin session keeps getting notified through reopen cycles. They auto-remove on `archived` (the irreversible end state). On boards that never archive, a GC sweep purges subscriptions for tasks that have sat in `done` or `blocked` with no new activity for `kanban.done_sub_retention_days` days (default 30; set 0 to disable), so stale rows don't accumulate forever. If you script a create with `--json` (machine output) the auto-subscribe is skipped — the assumption is that scripted callers want to manage subscriptions explicitly via `/kanban notify-subscribe`.\n\nDispatcher workers creating tasks through `kanban_create` or `hermes kanban create`\ncopy the owning task's durable notification subscriptions even without `parents`\ndependency links. Destinations, route anchors, and delivery modes are preserved;\na passive subscription is not upgraded to a wake by auto-subscribe. This copies\nexisting subscriptions independently of `auto_subscribe_on_create`, which controls\nadding the current conversation as a new destination. No destination is invented\nfor a bare CLI session or a worker whose owning task has no subscriptions.\n\nFor `kanban_create`, session lineage resolves in this order: explicit `session_id`,\nthe owning worker task's durable session, request-scoped API origin, then the\ncurrent process session. Built-in decomposition also inherits its root's durable\nsession. Session lineage is not itself a notification destination: changing\n`session_id` does not replace existing subscriptions; use `notify-subscribe` and\n`notify-unsubscribe` to change where events are delivered.\n\nA chat-originated auto-subscribe is created in `notify+wake` mode: on a terminal event the destination agent both receives the passive message **and** takes a real turn, so it can read the board context and reply in its own voice. See [Delivery modes](#delivery-modes) below.\n\n### Output truncation in messaging\n\nGateway platforms have practical message-length caps. If `/kanban list`, `/kanban show`, or `/kanban tail` produce more than ~3800 characters of output, the response is truncated with a `… (truncated; use \\` hermes kanban …` in your terminal for full output)` footer. The CLI surface has no such cap.\n\n### Autocomplete\n\nIn the interactive CLI, typing `/kanban`  and hitting Tab cycles through the built-in subcommand list (`list`, `ls`, `show`, `create`, `assign`, `link`, `unlink`, `claim`, `comment`, `complete`, `block`, `unblock`, `archive`, `tail`, `dispatch`, `context`, `init`, `gc`). The remaining verbs listed in the CLI reference above (` watch`, `stats`, `runs`, `log`, `assignees`, `heartbeat`, `notify-subscribe`, `notify-list`, `notify-unsubscribe`, `daemon`) also work — they're just not in the autocomplete hint list yet.\n\n## Collaboration patterns\n\nThe board supports these eight patterns without any new primitives:\n\n| Pattern | Shape | Example | \n|---|---|---|\n| **P1 Fan-out** | N siblings, same role | \"research 5 angles in parallel\" | \n| **P2 Pipeline** | role chain: scout → editor → writer | daily brief assembly | \n| **P3 Voting / quorum** | N siblings + 1 aggregator | 3 researchers → 1 reviewer picks | \n| **P4 Long-running journal** | same profile + shared dir + cron | Obsidian vault | \n| **P5 Human-in-the-loop** | worker blocks → user comments → unblock | ambiguous decisions | \n| **P6 `@mention`** | inline routing from prose | `@reviewer look at this` | \n| **P7 Thread-scoped workspace** | `/kanban here` in a thread | per-project gateway threads | \n| **P8 Fleet farming** | one profile, N subjects | 50 social accounts | \n| **P9 Triage specifier** | rough idea → `triage` →`hermes kanban specify` expands body →`todo` | \"turn this one-liner into a spec'd task\" | \n\nFor worked examples of each, see `docs/hermes-kanban-v1-spec.pdf`.\n\n## Handing context to follow-up cards (the parent link)\n\nA parent link is not just a scheduling gate — it is the context handoff channel from a **completed** card to a new one. When you create a card with `--parent <done-card-id>`, two things happen:\n\n1. **It's immediately eligible.**`create_task` sets status by parent state: a child whose parents are all`done` is created directly in`ready` — no waiting, no manual promotion. (Children of still-open parents sit in`todo` until`recompute_ready` promotes them when the last parent finishes.)\n2. **The parent's handoff rides along.** The worker context assembled for the child (`build_worker_context` , what`kanban_show()` returns) contains a`## Parent task results` section with each parent's completion`summary` and`metadata` , verbatim:\n\n```\n## Parent task results### t_77c26979 (completed just now)Added exponential backoff with jitter to the retry helper._metadata_: `{\"changed_files\": [\"hermes_cli/retry.py\", \"tests/test_retry.py\"], \"decisions\": [\"capped backoff at 60s\", \"jitter = full\"]}`\n```\n\nThis is why the pattern for follow-up work on a finished card is **a new child card, not reopening the done card**. Completed cards are immutable history — their context flows forward through the parent link. Same-card rework (retry loops on a failing card) is a different mechanism: prior attempts on the *same* card surface as \"prior attempts\" in that card's own context.\n\nA worktree or branch alone is not a substitute: repo state tells the follow-up worker *what* the code looks like, but not *why* — the decisions, tests run, and files touched live in the parent's structured handoff, not in git. Evidence that didn't exist when the parent completed (e.g. a CI log that failed later) belongs in the new card's **body**.\n\n```\n# Implementation card t_impl is done. CI fails two hours later.hermes kanban create \"Fix CI failure from t_impl: test_retry flakes on 3.11\" \\    --assignee coder \\    --parent t_impl \\    --body \"$(cat <<'EOF'CI run #4812 failed after t_impl merged.Log excerpt: FAILED tests/test_retry.py::test_backoff_jitter - TimeoutErrorAcceptance: tests/test_retry.py green on 3.11 and 3.12 in CI.Use a fresh worktree/branch; do not force-push the original branch.EOF)\"\n```\n\nThe remediation worker spawns with the original card's summary and metadata (changed files, decisions) already in context, plus the fresh evidence you put in the body.\n\n### Reconciling colliding worker branches\n\nIn engineering pipelines (P1/P2 with worktrees), two workers' branches can\nconflict when merged. Don't let either worker self-adjudicate — the colliding\nagent lacks its peer's context and reliably overwrites the other side or\nabandons its own. Instead, create a reconciliation card assigned to a **third,\nneutral profile** with **both** conflicted cards linked as parents: the parent\nlinks carry both sides' completion summaries into the reconciler's context, so\nit receives both diffs *and* both intents. The bundled\n[`agent-merge-conflict-arbiter` optional skill](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/autonomous-ai-agents/agent-merge-conflict-arbiter/SKILL.md)\ngives that worker the full procedure: classify each conflicted hunk, resolve\nimpartially, verify, and hand back a summary naming every decision.\n\n### Collision hotspots in parallel campaigns\n\nIn wide campaigns some files become collision magnets: many workers each add a little to the same file, nobody owns keeping it small, and it turns into the site of constant merge conflicts. The mitigation is a comment convention, not a new primitive. A worker that notices its diff keeps colliding with siblings in one file — or that a file it touches keeps appearing in other cards' recent comments — should not silently pile on. Instead it leaves a comment on its own card with a recognizable prefix:\n\n```\nhotspot: hermes_cli/kanban_db.py — third conflicting edit to the dispatch loop this wave\n```\n\nand repeats the flag in its completion `metadata`. Orchestrators (or humans\nreviewing the board) who see **two or more `hotspot:` comments naming the same\npath** should create a dedicated refactor/decomposition card for that file\n**before** queuing more work that touches it — splitting the magnet file is\ncheaper than reconciling every future collision it would cause. For conflicts\nthat have *already* happened, use the reconciliation-card pattern above with\nthe `agent-merge-conflict-arbiter` optional skill; hotspot flagging is the upstream fix that keeps\nthe reconciler from becoming a standing lane.\n\n## Multi-tenant usage\n\nWhen one specialist fleet serves multiple businesses, tag each task with a tenant:\n\n```\nhermes kanban create \"monthly report\" \\    --assignee researcher \\    --tenant business-a \\    --workspace dir:~/tenants/business-a/data/\n```\n\nWorkers receive `$HERMES_TENANT` and namespace their memory writes by prefix. The board, the dispatcher, and the profile definitions are all shared; only the data is scoped.\n\n## Desktop notifications\n\nThe Desktop app's Kanban plugin surfaces the same terminal events natively — no gateway platform required. While the Kanban board's live event socket is connected, each `completed`, `blocked`, `gave_up`, `crashed`, `timed_out`, or routed-to-triage (` block_loop_detected`) event raises an in-app toast with the worker's handoff (summary, block reason, or error) and an \"Open Kanban\" action. When you're away from the Hermes window, the same event also fires a native OS notification (gated by **Settings ▸ Notifications ▸ Plugin notifications**), so a task hitting a blocker while you're in another app still reaches you.\n\nCoverage window: desktop notifications ride the live event stream, so they fire only while the app is running with the Kanban plugin enabled. Events that land while the app is closed are not replayed as notifications on next launch — use a gateway subscription (below) for delivery that must survive the app being closed.\n\n## Gateway notifications\n\nWhen you run `/kanban create …` from the gateway (Telegram, Discord, Slack, etc.), the originating chat is automatically subscribed to the new task. The gateway's background notifier polls `task_events` every few seconds and delivers one message per terminal event (`completed`, `blocked`, `gave_up`, `crashed`, `timed_out`) to that chat. Completed tasks also send the first line of the worker's `--result` so you see the outcome without having to `/kanban show`.\n\nYou can manage subscriptions explicitly from the CLI — useful when a script / cron job wants to notify a chat it didn't originate from:\n\n```\nhermes kanban notify-subscribe t_abcd \\    --platform telegram --chat-id 12345678 --thread-id 7 \\    --chat-type group --delivery-mode notify+wakehermes kanban notify-listhermes kanban notify-unsubscribe t_abcd \\    --platform telegram --chat-id 12345678 --thread-id 7\n```\n\nA subscription removes itself automatically once the task reaches `done` or `archived`; no cleanup needed.\n\n### Delivery modes\n\n`--delivery-mode` controls **how** the notifier reacts to a terminal event. Every subscription is in one of three modes (`notify` is the default and the original behavior):\n\n| Mode | Passive message | Wakes the agent | Use it when | \n|---|---|---|---|\n| `notify` | yes | no | You just want a heads-up message in the chat (default). | \n| `notify+wake` | yes | yes | You also want the destination agent to take a real turn — read the board context and reply in its own voice. Chat-originated auto-subscribes use this. | \n| `wake` | no | yes | You only want the agent to act on the event, with no separate ping. | \n\nFor `notify+wake`, delivery completes only once the wake is admitted to the adapter's turn queue as well as the passive ping being sent. Missing handlers, rejected routes, and full queues are retried on later notifier ticks without expiring the subscription. Sent pings are checkpointed separately in SQLite, so a rejected wake does not repeat an already checkpointed ping. `notify` remains passive and never starts a turn. Admission is not a guarantee of model execution or a successful reply; normal turn gates still apply. This is not exactly-once delivery: a process crash between a send and its checkpoint can repeat the ping, and the existing claim-before-delivery cursor is not a crash-recoverable queue.\n\nA \"wake\" forges a synthetic inbound message to the destination gateway agent so it takes a normal turn (reads the comment + result, reasons, replies) instead of getting a one-line passive notification. It only fires when the notifier runs inside a live gateway process; otherwise a `notify+wake` subscription still delivers its passive message, while a `wake`-only subscription does nothing in that process.\n\n**Which events wake.** The ones that hand a decision back to the origin: `completed`, `blocked`, `gave_up`, `crashed`, `timed_out`, `review_requested` (a worker finished the implementation and handed off via `kanban_request_review`) and `block_loop_detected` (the task was routed to `triage` after repeated blocks). `status`, `archived` and `unblocked` are delivered but never wake — they are bookkeeping transitions, not decisions. When a `completed` or `review_requested` event carries a summary, that handoff rides the wake turn, so the woken agent sees what the worker actually did.\n\n`--chat-type` (`dm` | `group` | `channel` | `thread`) records the originating chat's type so a woken turn resolves the operator's **real** session: `build_session_key` keys groups, channels, and threads differently from DMs, so an inaccurate `chat_type` would route the wake into a separate, context-less session. The `/kanban` auto-subscribe and slash-command paths capture this automatically — you only set it by hand when subscribing a chat from a script or cron. Omit it to leave an existing subscription unchanged (new subscriptions default to `dm`).\n\n### Multi-profile setups: delivery is profile-owned\n\nIn a one-gateway-per-profile deployment (one dispatcher, separate gateway\nprocesses for `writer`, `admin`, etc. — see the [multi-gateway\nguide](https://github.com/NousResearch/hermes-agent/blob/main/docs/kanban/multi-gateway.md)),\ndispatch and delivery have separate owners:\n\n- **Dispatch stays single-owner.** Exactly one gateway keeps`kanban.dispatch_in_gateway: true` and runs the dispatcher; every other\ngateway sets it to`false` .\n- **Notification delivery is profile-owned.** Every gateway — including\nnon-dispatch ones — runs the notifier and polls only subscriptions stamped\nwith a profile whose platform adapters it hosts. A task created from the`writer` profile's Telegram gets its`completed` /`blocked` message delivered\nby the`writer` gateway, even though the`default` gateway did the\ndispatching.\n- **Route-only multiplex profiles** can use the primary adapter when the\nsubscription's persisted platform, chat, thread, scope and parent-channel\nanchors resolve to that exact served profile through`gateway.profile_routes` .\nA connected secondary adapter remains authoritative; a partial secondary\nadapter registry never falls back to the primary bot. Unmatched, reassigned,\ndisabled or ambiguous routes remain undelivered and retryable. Old rows\nmissing required routing anchors are not guessed into a profile. Wake turns keep\nthe destination profile's runtime scope and the authorized transport.\n- **Legacy subscriptions** created before profile stamping (no`notifier_profile` on the row) are delivered only by the gateway that holds\nthe actual dispatcher singleton lock, so two gateways never race for them.\n\nDuplicate delivery across gateways is prevented by the atomic per-event claim in the board DB. No relays, credential sharing, or extra dispatchers are needed — each profile gateway simply delivers through its own adapters.\n\n## Runs — one row per attempt\n\nA task is a logical unit of work; a **run** is one attempt to execute it. When the dispatcher claims a ready task it creates a row in `task_runs` and points `tasks.current_run_id` at it. When that attempt ends — completed, blocked, crashed, timed out, spawn-failed, reclaimed — the run row closes with an `outcome` and the task's pointer clears. A task that's been attempted three times has three `task_runs` rows.\n\nWhy two tables instead of just mutating the task: you need **full attempt history** for real-world postmortems (\"the second reviewer attempt got to approve, the third merged\"), and you need a clean place to hang per-attempt metadata — which files changed, which tests ran, which findings a reviewer noted. Those are run facts, not task facts.\n\nRuns are also where **structured handoff** lives. When a worker completes a task (via `kanban_complete(...)`) it can pass:\n\n- `summary` (tool param) /`--summary` (CLI) — human handoff; goes on the run; downstream children see it in their`build_worker_context` .\n- `metadata` (tool param) /`--metadata` (CLI) — free-form JSON dict on the run; children see it serialized alongside the summary.\n- `result` (tool param) /`--result` (CLI) — short log line that goes on the task row (legacy field, kept for back-compat).\n\nDownstream children read the most recent completed run's summary + metadata for each parent. Retrying workers read the prior attempts on their own task (outcome, summary, error) so they don't repeat a path that already failed.\n\n```\n# What a worker actually does — a tool call, from inside the agent loop:kanban_complete(    summary=\"implemented token bucket, keys on user_id with IP fallback, all tests pass\",    metadata={\"changed_files\": [\"limiter.py\", \"tests/test_limiter.py\"], \"tests_run\": 14},    result=\"rate limiter shipped\",)\n```\n\nThe same handoff is reachable from the CLI when you (the human) need to close out a task a worker can't — e.g. a task that was abandoned, or one you marked done manually from the dashboard:\n\n```\nhermes kanban complete t_abcd \\    --result \"rate limiter shipped\" \\    --summary \"implemented token bucket, keys on user_id with IP fallback, all tests pass\" \\    --metadata '{\"changed_files\": [\"limiter.py\", \"tests/test_limiter.py\"], \"tests_run\": 14}'# Review the attempt history on a retried task:hermes kanban runs t_abcd#   #  OUTCOME       PROFILE           ELAPSED  STARTED#   1  blocked       worker               12s  2026-04-27 14:02#        → BLOCKED: need decision on rate-limit key#   2  completed     worker                8m   2026-04-27 15:18#        → implemented token bucket, keys on user_id with IP fallback\n```\n\nRuns are exposed on the dashboard (Run History section in the drawer, one coloured row per attempt) and on the REST API (`GET /api/plugins/kanban/tasks/:id` returns a `runs[]` array). `PATCH /api/plugins/kanban/tasks/:id` with `{status: \"done\", summary, metadata}` forwards both to the kernel, so the dashboard's \"mark done\" button is CLI-equivalent. `task_events` rows carry the `run_id` they belong to so the UI can group them by attempt, and the `completed` event embeds the first-line summary in its payload (capped at 400 chars) so gateway notifiers can render structured handoffs without a second SQL round-trip.\n\n**Bulk close caveat.** `hermes kanban complete a b c --summary X` is refused — structured handoff is per-run, so copy-pasting the same summary to N tasks is almost always wrong. Bulk close *without* `--summary` / `--metadata` still works for the common \"I finished a pile of admin tasks\" case.\n\n**Reclaimed runs from status changes.** If you drag a running task off `running` in the dashboard (back to `ready`, or straight to `todo`), or archive a task that was still running, the in-flight run closes with `outcome='reclaimed'` rather than being orphaned. The `task_runs` row is always in a terminal state when `tasks.current_run_id` is `NULL`, and vice versa — that invariant holds across CLI, dashboard, dispatcher, and notifier.\n\n**Synthetic runs for never-claimed completions.** Completing or blocking a task that was never claimed (e.g. a human closes a `ready` task from the dashboard with a summary, or a CLI user runs `hermes kanban complete <ready-task> --summary X`) would otherwise drop the handoff. Instead the kernel inserts a zero-duration run row (`started_at == ended_at`) carrying the summary / metadata / reason so attempt history stays complete. The `completed` / `blocked` event's `run_id` points at that row.\n\n**Live drawer refresh.** When the dashboard's WebSocket event stream reports new events for the task the user is currently viewing, the drawer reloads itself (via a per-task event counter threaded into its `useEffect` dependency list). Closing and reopening is no longer required to see a run's new row or updated outcome.\n\n### Forward compatibility\n\nTwo nullable columns on `tasks` are reserved for v2 workflow routing: `workflow_template_id` (which template this task belongs to) and `current_step_key` (which step in that template is active). The v1 kernel ignores them for routing but lets clients write them, so a v2 release can add the routing machinery without another schema migration.\n\n## Event reference\n\nEvery transition appends a row to `task_events`. Each row carries an optional `run_id` so UIs can group events by attempt. Kinds group into three clusters so filtering is easy (`hermes kanban watch --kinds completed,gave_up,timed_out`):\n\n**Lifecycle** (what changed about the task as a logical unit):\n\n| Kind | Payload | When | \n|---|---|---|\n| `created` | `{assignee, status, parents, tenant}` | Task inserted. `run_id` is`NULL` . | \n| `promoted` | — | `todo → ready` because all parents hit`done` .`run_id` is`NULL` . | \n| `claimed` | `{lock, expires, run_id}` | Dispatcher atomically claimed a `ready` task for spawn. | \n| `completed` | `{result_len, summary?}` | Worker wrote `--result` /`--summary` and task hit`done` .`summary` is the first-line handoff (400-char cap); full version lives on the run row. If`complete_task` is called on a never-claimed task with handoff fields, a zero-duration run is synthesized so`run_id` still points at something. | \n| `blocked` | `{reason, kind, recurrences}` | Worker or human flipped the task to `blocked` .`kind` is the typed block reason (`needs_input` ,`capability` ,`transient` , or`null` for a generic block);`recurrences` is the unblock-loop counter. Synthesizes a zero-duration run when called on a never-claimed task with`--reason` . | \n| `dependency_wait` | `{reason, kind}` | Worker blocked with `kind=dependency` — the task is only waiting on another task, so it routes to`todo` (parent-gated, auto-promoted) instead of`blocked` . No human needed. | \n| `block_loop_detected` | `{reason, kind, recurrences, limit}` | A task was unblocked and re-blocked for the same reason `BLOCK_RECURRENCE_LIMIT` times (default 2). Instead of landing in`blocked` again — where a cron would keep unblocking it — it routes to`triage` for a human decision, breaking the unblock↔re-block loop. | \n| `unblocked` | — | `blocked → ready` (or`todo` if parents are still open), either manually or via`/unblock` . Resets the dispatcher's`consecutive_failures` but deliberately preserves`block_recurrences` so the loop breaker keeps its memory.`run_id` is`NULL` . | \n| `archived` | — | Hidden from the default board. If the task was still running, carries the `run_id` of the run that was reclaimed as a side effect. | \n\n**Edits** (human-driven changes that aren't transitions):\n\n| Kind | Payload | When | \n|---|---|---|\n| `assigned` | `{assignee}` | Assignee changed (including unassignment). | \n| `edited` | `{fields}` | Title or body updated. | \n| `reprioritized` | `{priority}` | Priority changed. | \n| `status` | `{status}` | Dashboard drag-drop wrote a status directly (e.g. `todo → ready` ). Carries the`run_id` of the run that was reclaimed when dragging off`running` ; otherwise`run_id` is NULL. | \n\n**Worker telemetry** (about the execution process, not the logical task):\n\n| Kind | Payload | When | \n|---|---|---|\n| `spawned` | `{pid}` | Dispatcher successfully started a worker process. | \n| `heartbeat` | `{note?}` | Worker called `hermes kanban heartbeat $TASK` to signal liveness during long operations. | \n| `reclaimed` | `{stale_lock}` | Claim TTL expired without a completion; task goes back to `ready` . | \n| `crashed` | `{pid, claimer}` | Worker PID no longer alive but TTL hadn't expired yet. | \n| `timed_out` | `{pid, elapsed_seconds, limit_seconds, sigkill}` | `max_runtime_seconds` exceeded; dispatcher SIGTERM'd (then SIGKILL'd after 5 s grace) and re-queued. | \n| `stale` | `{elapsed_seconds, last_heartbeat_at, heartbeat_age_seconds, timeout_seconds, pid, terminated}` | Task ran longer than `kanban.dispatch_stale_timeout_seconds` (default 4 h) AND no`kanban_heartbeat` arrived in the last hour. Dispatcher SIGTERM'd the host-local worker (if any), reset the task to`ready` for re-dispatch. Does NOT tick the failure counter (stale is dispatcher-side absence detection, not a worker fault). Workers running long operations should call`kanban_heartbeat` at least once an hour to avoid this. | \n| `reconciled` | `{reason, claim_lock, claim_expires, worker_pid}` | Orphaned-card reconciliation: the card was `running` with broken claim bookkeeping (`claim_lock` or`claim_expires` NULL — crash mid-claim, manual SQL, DB restore) and no live worker, so none of the TTL/crash/stale paths could ever recover it. The dispatcher requeued it to`ready` with an explanatory comment. Gated by`kanban.reconcile_orphans` in config.yaml (default`true` ). | \n| `respawn_guarded` | `{reason}` | Dispatcher refused to re-spawn this ready task this tick. Reasons: `blocker_auth` (last failure was a quota/auth/429 error — wait for the rate window to reset),`recent_success` (a completed run happened in the last hour — wait for review before re-running),`active_pr` (a GitHub PR URL appears in a recent comment — a prior worker already opened a PR). The task stays in`ready` ; the next tick gets another chance to spawn. If the underlying condition persists, the normal`consecutive_failures` circuit breaker will auto-block via`gave_up` after`failure_limit` failures. | \n| `spawn_failed` | `{error, failures}` | One spawn attempt failed (missing PATH, workspace unmountable, …). Counter increments; task returns to `ready` for retry. | \n| `protocol_violation` | `{pid, claimer, exit_code, protocol_violation}` | Worker exited successfully while the task was still `running` , usually because it answered without calling`kanban_complete` or`kanban_block` . Emitted on every violation (the payload's`protocol_violation: true` marker is copied into the run metadata and feeds the violation-only retry budget). Below the budget — up to`_PROTOCOL_VIOLATION_FAILURE_LIMIT` (default 3)*consecutive* violations, per-task`max_retries` overriding — the task simply returns to`ready` for another attempt; when the streak reaches the bound the dispatcher also emits`gave_up` and auto-blocks. | \n| `gave_up` | `{failures, effective_limit, limit_source, error}` | Circuit breaker fired after N consecutive non-successful attempts. Task auto-blocks with the last error. The effective limit resolves as task `max_retries` , then dispatcher`failure_limit` /`kanban.failure_limit` , then the built-in default. | \n\n`hermes kanban tail <id>` shows these for a single task. `hermes kanban watch` streams them board-wide.\n\n## Out of scope\n\nKanban is deliberately single-host. `~/.hermes/kanban.db` is a local SQLite file and the dispatcher spawns workers on the same machine. Running a shared board across two hosts is not supported — there's no coordination primitive for \"worker X on host A, worker Y on host B,\" and the crash-detection path assumes PIDs are host-local. If you need multi-host, run an independent board per host and use `delegate_task` / a message queue to bridge them.\n\n## Design spec\n\nThe complete design — architecture, concurrency correctness, comparison with other systems, implementation plan, risks, open questions — lives in `docs/hermes-kanban-v1-spec.pdf`. Read that before filing any behavior-change PR.", "url": "https://wpnews.pro/news/hermes-kanban-multi-agent-profile-collaboration", "canonical_source": "https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban", "published_at": "2026-09-07 23:24:05+00:00", "updated_at": "2026-09-07 23:31:36.133862+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-products"], "entities": ["Hermes Kanban", "Hermes"], "alternates": {"html": "https://wpnews.pro/news/hermes-kanban-multi-agent-profile-collaboration", "markdown": "https://wpnews.pro/news/hermes-kanban-multi-agent-profile-collaboration.md", "text": "https://wpnews.pro/news/hermes-kanban-multi-agent-profile-collaboration.txt", "jsonld": "https://wpnews.pro/news/hermes-kanban-multi-agent-profile-collaboration.jsonld"}}