| Feature | Description |
|---|
| Prompt-spawn | warden start --role general "<prompt>" — no repo needed. Runs claude in the caller’s directory (or --dir). |
| Auto-classification | The daemon labels a prompt-spawned agent’s type with claude -p shortly after creation (falls back to other). The label is informational; the role decides behaviour. |
| Auto-generated subject | Each agent gets a one-line ≤8-word summary of what it’s doing, seeded from the prompt and refreshed by the poller from the transcript or tmux pane (throttled, change-gated). |
| Managed worktree spawn | --role worker --repo <path> creates/adopts an isolated git worktree (--worktree for a scratch one, --in-repo to opt out). |
| Worktree adoption | If a worktree for the ticket already exists, the spawn reattaches to it instead of erroring. |
| Supervised mode | --supervised launches with --permission-mode acceptEdits (risky tools prompt → feed the approvals inbox) instead of the default --dangerously-skip-permissions bypass. Persisted and reused on restore. |
| Command / feature | Description |
|---|
stop | The single umbrella teardown verb. Default = full teardown: terminate + clear (archive) record + remove worktree (asks first unless --yes). Subtractive flags: --keep-record, --keep-worktree (--keep-worktree alone == done), --hard, --pr/--base, --force, --delete-adopted-branch. Safe order: PR → terminate → remove worktree → clear record. A failure names the failed step and what already completed (e.g. remove worktree failed: … (completed: terminated; record left intact — fix the cause and retry)); the record is cleared last, so a failed guard (running / dirty / unpushed) is safely retryable. An already-deleted branch counts as success. |
terminate | Stop an agent (kill tmux + the agent process); keeps the record and worktree. The safe, reversible “stop” default. Alias for stop --keep-record --keep-worktree. |
restore | Recreate and resume a session only when its stored status is orphaned and its tmux session is gone (claude --resume). In Cockpit TUI, select the orphaned agent and press r. |
recover | Safety net for the tombstone reaper: revive an archived orphaned record whose tmux session is confirmed still alive. Bare recover only reports candidates; --apply re-inserts each one under its original id (children reconnect automatically). |
done | Terminate and clear the record in one step (worktree kept). --hard purges instead of archiving. Alias for stop --keep-worktree. |
delete | Clear the stored record (archive by default, --hard purge). Leaves tmux + worktree alone. Alias for stop --keep-worktree (record only). |
remove-worktree | Remove the git worktree + branch. Destructive — refuses while the agent runs or has uncommitted/unpushed work unless --force. Alias for stop --keep-record (worktree only). |
adopt | Register an existing Claude session — resume newest-for-dir under tmux, or live-register a running tmux session. |
| Cascade cleanup | Deleting a pipeline/agent cascades cleanup of its shared-context keys and (on hard-delete) its mailbox inbox. |
| Presented state | Stored/API status | Meaning |
|---|
pending | spawning | Launching |
busy | working | Actively working |
idle | idle | Alive, no active turn |
need-input | waiting_for_input | Waiting for input or approval |
done | done | Finished |
orphaned | orphaned | Process gone, record survives; eligible for recovery |
rate_limited | rate_limited | Paused at a provider limit; automatically resumes |
These are presentation aliases; persisted and raw API statuses retain their
existing names. Legacy errored records display as done when an exit code is
recorded, otherwise as orphaned; there is no eighth UX state. A displayed alias
does not itself grant recovery: restore/recover requires the stored orphaned
state. Backend quota switching is a separate automatic mechanism.
