feat: add sanitized Kanban REST API

[andriy4k07]

Sanitized Kanban REST API for external control planes

Summary

Adds a narrow, authenticated, safe-by-default REST API over the existing Hermes Kanban store, mounted at
/api/plugins/kanban. It gives external control planes a stable integration boundary for creating, routing,
inspecting, and managing Kanban tasks — without reading raw SQLite state, touching internal dashboard routes, or
executing profiles directly.

Design constraints, all preserved end to end:

• Reuses hermes_cli.kanban_db — same database, WAL/transaction behavior, task state machine, dependency promotion
  rules, and dispatcher lifecycle. No second schema, no second queue.
• No profile-execution endpoint. Work is routed by task assignment; the existing gateway dispatcher claims and
  launches it.
• Sanitized DTOs only — never raw internal rows.
• No product-specific workflow types or business logic.

API surface

Area	Endpoints
Status	GET /health, GET /capabilities
Boards	GET /boards, GET /boards/{id-or-name}
Profiles	GET /profiles — sanitized assignee roster (read-only)
Tasks	GET /tasks, POST /tasks, GET /tasks/{id}, PATCH /tasks/{id}
Actions	POST /tasks/{id}/comment, /complete, /block, /unblock, /archive
Dependencies	POST /tasks/{parent}/links/{child}, DELETE /tasks/{parent}/links/{child}
Observability	GET /tasks/{id}/events, /runs, /log

All request models are strict Pydantic (extra="forbid"); unknown fields are rejected.

Authentication

External controllers authenticate with a dedicated service credential, wired through the dashboard-auth framework
rather than bolted onto the routes:

• The generic token-auth seam gains prefix registration (exact-path matching cannot cover parameterised routes)
  and required scopes: a verified principal lacking the route's scope is refused with 403 + an audit event. With
  multiple service credentials stacked, one credential can no longer open another surface's routes — the drain secret
  cannot drive the kanban API and vice versa.
• A new bundled dashboard_auth plugin (mirroring the drain plugin) verifies Authorization: Bearer $HERMES_KANBAN_API_SECRET with a constant-time compare and vouches for a kanban-scoped principal. A
  weak/short/low-entropy secret (< 256 bits) fails closed at load; the shared entropy gate now lives in
  dashboard_auth.secret_strength and is reused by both plugins.
• The interactive dashboard subtree (see below) is excluded from the token seam and stays on cookie/session auth.
  Without the secret set, the plugin is a no-op and prior behavior is unchanged.

Idempotency (concurrency-safe)

POST /tasks accepts an Idempotency-Key header or idempotency_key body field. A repeat returns the existing live
task with HTTP 200 and created: false; a fresh insert returns HTTP 201 and created: true.

The guarantee holds under concurrency and is enforced at the storage layer:

• A partial UNIQUE index on idempotency_key (live, non-archived tasks; legacy duplicates deduped during
  migration) closes the check-then-insert race. Archiving a task frees its key.
• create_task_idempotent resolves a lost race to the winner's row instead of surfacing IntegrityError — every
  caller (CLI, tools, dispatcher, REST) gets one task id, satisfying the multi-process stress contract
  (idempotency_key_race).

Sanitization

Task and run DTOs expose workflow state plus routing attribution — assignee, created_by (which profile/surface
created the card), and the executing profile per run — and deliberately omit: task bodies and results, comment
text, workspace paths, branch names, claim locks, worker PIDs, session IDs, idempotency keys, run
summaries/metadata/errors, and raw event payloads.

GET /profiles returns only name, description, and has_description — no models, providers, paths, env, or
skill inventories. GET /tasks/{id}/log returns a bounded excerpt (8 KiB default, 32 KiB max) after Hermes secret
redaction, Authorization-header scrubbing, and absolute-path replacement with [PATH].

Error details follow an allowlist: known-safe validation messages pass through verbatim; anything else collapses to a
stable generic detail with the raw error logged server-side only.

Dashboard compatibility

The first-party dashboard needs a richer API than should be exposed externally, so its existing routes are namespaced
under /api/plugins/kanban/dashboard (bundled dashboard JS updated). Both routers share the same kanban_db
implementation. Third-party consumers of the previously undocumented dashboard routes should migrate to the sanitized
API or adopt the new namespace.

Documentation

website/docs/user-guide/features/kanban-rest-api.md — credential provisioning, the full endpoint contract,
idempotency semantics, and a worked example (parent operation → dependent children → dependency links → completion →
polling sanitized events/runs/logs).

Testing

• Affected suites (REST adapter, kanban store, token-auth seam, auth middleware, both auth plugins):

  python -m pytest tests/hermes_cli/test_kanban_api.py tests/hermes_cli/test_kanban_db.py \                          
    tests/hermes_cli/test_dashboard_token_auth.py tests/hermes_cli/test_dashboard_auth_middleware.py \               
    tests/plugins/dashboard_auth/ -q                                                                                 
  # 509 passed                                                                                                       
                                                                                                                     

• Auth is covered end-to-end through the real mounted dashboard app in gated mode: valid bearer drives the external
  surface, missing/wrong token → 401, a foreign-scoped service credential → 403, and the dashboard subtree never
  accepts the bearer.

• Idempotency race coverage: a deterministic lost-race regression at the storage layer, a threaded concurrent-create
  regression, and the multi-process stress scenario. Exercised live as well: 6 concurrent POST /tasks with one key →
  exactly one 201 + five 200s, one row persisted.

• Full atypical stress suite on this branch:

python tests/stress/test_atypical_scenarios.py

28 scenarios, 0 failures, 0 skips

▎ Note: one commit (test(stress): catch atypical scenarios up to current kanban contracts) repairs two stress
▎ scenarios that fail on current main independently of this PR — they had gone stale against the spawn_failures →
▎ consecutive_failures rename (#20410) and the archived-parents-are-terminal dependency fix. Included so the suite is
▎ green on this branch; happy to split it into its own PR.

Out of scope

Profile execution or configuration endpoints, raw worker/session state, product-specific workflow types, and any
second Kanban schema or storage layer.

Follow-ups

• Cursor pagination for large boards
• Finer-grained RBAC within the kanban scope (e.g. read-only credentials)
• Explicit API versioning if additional external contracts are introduced

[teknium1]

Thanks for separating a narrow DTO-based contract from the rich operator dashboard surface. The premise is valid: current plugins/kanban/dashboard/plugin_api.py:158-176 serializes the complete task dataclass, and current main has no sanitized adapter.

Problems

• website/docs/user-guide/features/kanban-rest-api.md:20-25 documents a bearer credential for external controllers, but current main accepts Bearer only when it is the ephemeral dashboard _SESSION_TOKEN (hermes_cli/web_server.py:319-336). On gated deployments, routes require a verified cookie session (hermes_cli/web_server.py:361-369). Generic service bearer auth is limited to exact registered paths (hermes_cli/dashboard_auth/token_auth.py:54-74,144-164), and this change registers none.
• The advertised idempotency is not concurrency-safe. hermes_cli/kanban_db.py:2539-2552 checks before BEGIN IMMEDIATE at :2580, and idx_tasks_idempotency is non-unique (:1996-1999). The existing stress contract requires concurrent creates with one key to return one id and persist one row (tests/stress/test_atypical_scenarios.py:712-751).

Suggested changes

• Wire a real service-auth path and test it through the mounted dashboard app, or scope the documentation to dashboard-session clients.
• Make keyed creation atomic at the storage layer and add a concurrent-create regression.

Automated hermes-sweeper review.

[teknium1]

This bearer flow is not available to an external controller on a gated dashboard: current main only accepts Bearer <_SESSION_TOKEN> in loopback mode (hermes_cli/web_server.py:319-336), while gated mode requires a cookie session. The generic service-token seam also only applies to exact registered paths (hermes_cli/dashboard_auth/token_auth.py:54-74), and this router registers none. Please add a real service-auth integration and E2E coverage, or change the contract/docs to dashboard-session authentication.

[andriy4k07]

Thanks — both findings were valid. Addressed in four commits:

1. Bearer auth for external controllers did not actually exist (docs advertised a credential no code path accepted)

Wired a real service-auth path instead of scoping the docs down:

• feat(dashboard-auth): prefix routes and scope enforcement in the token-auth seam — the generic seam now supports
  register_token_route_prefix(prefix, scope=..., exclude=...), since exact-path registration can't cover
  parameterised routes like /tasks/{id}. Registrations may demand a required scope: a verified principal lacking it
  gets 403 + an audit event. This is what keeps one stacked service credential from opening another surface's
  routes — the drain plugin now passes its scope through as well.
• feat(kanban): service bearer credential for the external REST API — a new dashboard_auth plugin mirroring the
  drain plugin: the operator provisions HERMES_KANBAN_API_SECRET (>=256-bit, fail-closed entropy gate shared with
  drain via the new dashboard_auth.secret_strength), and the plugin registers a kanban-scoped token provider plus
  the /api/plugins/kanban/ prefix — excluding the interactive /dashboard subtree, which stays on the cookie/session
  gate.
• Docs rewritten around the real contract (HERMES_KANBAN_API_SECRET), including the fail-closed consequence: with
  the secret set the external surface is token-only on every bind.

E2E coverage goes through the real mounted dashboard app in gated mode (web_server.app + TestClient,
auth_required=True, providers registered through the plugins' own register()): valid bearer drives the external
surface, missing/wrong token → 401, the drain credential on kanban routes → 403 (and vice versa), and the kanban
bearer never opens the dashboard subtree. Also exercised live against a running server: 401/403/200 matrix plus the
documented workflow (links, complete, events, sanitized log).

2. Idempotency was not concurrency-safe at the storage layer

Correct — the partial UNIQUE index made a lost race surface as sqlite3.IntegrityError: the retry loop only
regenerated the task id, so the same key failed again and the caller crashed, violating the idempotency_key_race
stress contract.

• fix(kanban): resolve idempotency-key races inside create_task — recovery now lives in the storage layer.
  create_task_idempotent(...) -> (task_id, created) owns the full contract: fast-path lookup, insert, and
  IntegrityError resolution to the live winner (same created_at DESC, id DESC tiebreak as the migration's survivor
  choice). create_task remains a same-signature wrapper, so no existing caller changes. The REST adapter drops its
  duplicated lookup + IntegrityError handling and just maps created=False → HTTP 200.
• Regressions added at the storage layer: a deterministic lost-race test (the concurrent winner is injected between
  the fast-path lookup and the INSERT via the _new_task_id seam) and a 4-thread concurrent-create test (one id, one
  row). The existing multi-process stress scenario passes.

Verified live as well: 6 concurrent POST /tasks with one Idempotency-Key against a running server → exactly one
201 and five 200s, all six responses carrying the same task id, one row persisted.

[andriy4k07]

Note on the stress-suite commit (test(stress): catch atypical scenarios up to current kanban contracts)

While verifying this PR against tests/stress/test_atypical_scenarios.py, I found two scenarios that fail on current
main as well — they are pre-existing and unrelated to this PR, but since reviewers run the stress suite against
this branch, I've included the fix here so the suite is fully green (28 scenarios, 0 failures, 0 skips).

Both are cases of the stress suite going stale against deliberate kernel changes from May 2026:

• workspace_nonexistent_path read task.spawn_failures, which fix(kanban): unify failure counter across spawn/timeout/crash outcomes #20410 renamed to consecutive_failures when
  the circuit-breaker counter was unified across spawn/timeout/crash outcomes (with a column migration). The scenario
  had also silently stopped testing anything: since the dispatcher crash-loop fix, tasks whose assignee is not a real
  profile on disk are skipped before claiming, so the workspace-failure path was never reached. The scenario now
  creates the profile dir first and asserts the counter actually ticks.
• parent_in_different_status_states expected a child of an archived parent to stay in todo, contradicting
  the documented recompute_ready contract — the "treat archived parent tasks as terminal for dependency resolution"
  fix deliberately made archived terminal like done, so a cancelled parent can't wedge its children forever. The
  expectation now matches the kernel.

Happy to split this commit out into its own PR if you'd rather land the test repair independently — the failures
reproduce on main without any of this PR's changes.