Steward

Steward

Steward watches the work your agents do, fixes the few things that are safe to fix without you, and tells you in one line when it needs a person. It is not a chat assistant and not a second orchestrator. It is per project and on by default.

Overview

• It watches Board card rounds, runner runs (skills, design, planner, assess, capture, normalize) and fleet slots.
• When work gets stuck it opens an incident, tries a bounded fix if one is safe, and otherwise escalates with one notification.
• Every day — and when you switch away mode off — it sends a digest: what is done, what is stuck, what is waiting on you, and the spend.

Important

Fleet slots are observed only. Steward opens incidents for them and lists them in the digest, but never sends a slot a command — the orchestrator owns its slots.

How it works

flowchart LR
  W["Card round / runner run"] --> D{"Stuck?"}
  D -- "no" --> W
  D -- "yes" --> I["Incident opened"]
  I --> S{"Safe automatic fix<br/>within its limit?"}
  S -- "yes" --> A["Nudge · Dismiss · Resume · Hold push"]
  A --> R{"Recovered?"}
  R -- "yes" --> OK["Resolved<br/>(Activity, no notification)"]
  R -- "no" --> S
  S -- "no" --> E["Needs you<br/>(one notification: web + Telegram)"]

Loading

What counts as stuck

Kind	What Steward saw
API error	API Error: … or an interrupted response in the session
Dialog	a Claude Code dialog is open
Permission prompt	the session asks for a permission
Quota	the quota banner
Silent	no activity for the silence threshold (default 10 minutes) and no live background task
Session ended	a card's tmux session is gone
Claude trailer	a card commit carries a Claude attribution trailer
Unknown	none of the above matched; a small local model gives a one-line reason

A round waiting on a long background task is never "silent".

What it does by itself

Only these, each with a limit, and each can be switched off:

Action	What happens	Limit
Nudge	after an API or network error, one fixed line is typed into the session	2 per round — the first at once, the second 2 minutes later; a third error escalates
Dismiss	closes a dialog that needs no decision (a short, fixed list)	an unknown dialog is never answered
Resume	restarts a dead card session with --resume in the same worktree	2 per round, only while the worktree exists; a round you stopped is never resumed
Hold a push	holds a push whose commits carry a Claude attribution trailer and tells the worker which commits to rewrite	the push goes through once the commits are fixed

What it never does

• Answer a permission prompt, merge, or change code.
• Act on a fleet slot.
• Read pane or transcript text into the control plane. The API gets the kind of incident, a one-line reason and the action taken. A tail of the pane is sent with an escalation only when the project ships session content.

What it escalates

Anything it cannot fix safely, and anything past a limit: one notification per incident, in the web app and Telegram. A changed reason notifies again. When the work recovers, the incident closes with a Resolved entry in Activity and no notification.

Where you see it

• Board — a card with an open incident shows a chip such as Stuck: API error · nudged 1/2; once escalated it reads … · needs you. The card sheet has a Steward section listing the card's incidents and what was done about each.
• Activity — More filters › Type › Steward lists incident events: opened, action taken, needs you, resolved.
• Overview › Digest — the latest digest of each project.
• Telegram — the same digest, daily and when you switch away mode off.

Linking a card to an existing issue

The card sheet's Steward section has an Issue field. Enter the number of an open issue in the project's repository and click Link: Run then creates no new issue, and the pull request says Closes #n. Unlink removes it. A closed issue, a pull request or an unknown number is refused with the reason.

The digest

Sent daily at the project's digest time (default 09:00, in your time zone) and when away mode is switched off ("while you were away"). It lists:

1. what is done (merged and finished);
2. what is stuck, and why;
3. what is waiting on you;
4. the spend.

A short summary on top is written by a small model on the runner. If the runner is offline, the digest is the plain template without it.

Settings

Project › Settings › Steward — a project administrator saves; everyone else reads.

Setting	Meaning
Steward	the master switch, on by default. Off: no incidents, no actions, no digest
Silence threshold	minutes without activity before a round counts as silent (1–240)
Digest time	time of day for the daily digest
Nudge, Dismiss, Resume, Hold pushes	one switch per automatic action. An action that is off is not performed — Steward escalates instead

Note

The small local model used for unknown stalls and the digest summary counts against the project's budget.

See also

• Token Saver · Context Handoff · Telegram
• User guide: docs/guides/steward.md
• Runner events and commands: docs/architecture/runner-protocol.md

Decisions: ADR-0040 · Spec: #447, #491