hermes - 💡(How to fix) Fix Kanban needs first-class waiting states for human, approval, and review gates

Summary

Kanban currently overloads blocked for several different meanings:

• a real execution failure that might be retried later
• waiting for human input
• waiting for login / OAuth / external website state
• waiting for explicit operator approval
• implementation done, waiting for review
• governance / policy gate

The recent sticky-block fix in #28994 / #28712 is important and should stop the immediate blocked -> promoted -> spawned loop. But the incident also shows a deeper state-model gap: human/approval/review gates are not first-class states, so dispatcher behavior, dashboard presentation, run history, and worker guidance all have to infer intent from free-form block reasons such as human-required:, approval-required:, or review-required:.

That is fragile for autonomous Kanban dispatch.

Why this matters

Kanban is now promoted as a multi-agent work queue. Once the gateway dispatcher is enabled, state semantics become safety-critical: a card's status decides whether Hermes may spend paid model quota and mutate local workspaces without further human interaction.

blocked is too broad for that job.

A human-gated task should not be treated like a failed worker run. It should be visibly parked until the operator provides the missing input or explicitly resumes it.

Evidence from a local incident

On a personal install, several cards were repeatedly respawned before the latest sticky-block fix was available locally. The exact task names and local paths are redacted here, but the categories were:

1. A school/contact confirmation task whose worker repeatedly concluded:

   • human-required: missing real-world confirmation
   • waiting for teacher / family member to provide actual answer

2. A login-gated submission task whose worker repeatedly concluded:

   • human-login-required
   • human-wechat-login-required

3. A cleanup task whose worker repeatedly concluded:

   • approval-required: no explicit cleanup approval recorded

4. A completed implementation handoff whose worker used:

   • review-required: implementation pushed; needs reviewer eyes

The event pattern was the problematic loop already fixed by #28712:

blocked(reason starts with human-required / approval-required / review-required)
promoted
claimed
spawned
blocked(...same semantic reason...)
promoted
claimed
spawned

Even with the sticky-block fix, these examples show that blocked is carrying multiple product meanings that need different UX and dispatcher behavior.

Expected behavior

Kanban should have first-class waiting semantics so the system does not need to parse prose to know whether a card is runnable.

Possible design shape:

• waiting_human — waiting for user / family / coworker / external person input
• waiting_login or waiting_auth — waiting for human login, OAuth, website session, credential, device approval
• waiting_approval — waiting for explicit operator approval before destructive or policy-sensitive action
• waiting_review — implementation is done; review should happen next

I am not attached to these exact names. The core requirement is that these states are non-dispatchable by default and visibly distinct from failure-blocked work.

Semantics proposal

For first-class waiting states:

• Dispatcher must never spawn workers for them.
• They require an explicit state transition such as unblock, resume, approve, or mark-reviewed before dispatch.
• They should not count as failure / retry attempts.
• They should be visible in CLI/dashboard filtering separately from failed blocked tasks.
• Worker tooling should make the right terminal action obvious:
  • work done -> kanban_complete
  • cannot proceed because real-world input is missing -> kanban_wait_human or equivalent
  • destructive action needs approval -> kanban_wait_approval
  • implementation done and linked reviewer card exists -> complete the implementation card, not block it as review-required

Backward compatibility

This can be incremental:

1. Keep existing blocked behavior.
2. Add structured wait states or structured block categories.
3. Teach kanban_block to accept an optional category, e.g. category="human" | "approval" | "review" | "auth" | "failure".
4. Preserve existing cards; optionally infer a category from common prefixes only for display/migration, not as the long-term contract.

Related issues

• #28712 / PR #28994 — fixed the immediate sticky-block respawn loop.
• #29014 — provider quota drain from blocked/manual-gate respawns; closed as duplicate of #28712.
• #29027 — review-required: blocks causing duplicate worker runs.
• #29034 — broader default-safety problem: gateway defaults can launch paid worker swarms across all boards.
• #23959 — first-class kind field for card shape; related but different. This issue is about status / dispatchability semantics, not card type metadata.

Why a separate issue

The sticky-block fix prevents one dangerous loop, but it does not make human-gated work a clear product concept. Without first-class waiting states, users and workers will keep encoding safety-critical control flow into free-form block reasons. That is not robust enough for an autonomous worker queue that can spend paid model quota.