@enderfga/claw-orchestrator 5.0.0 → 6.0.0

package/skills/references/autoloop.md

@@ -21,11 +21,11 @@ This page is the operator reference.
 
 ## Roles
 
-| Agent | Default | cwd | Owns |
-|---|---|---|---|
-| **Planner** | claude / opus | workspace | strategy, `plan.md`, `goal.json`, talking to you |
-| **Coder** | claude / sonnet | workspace | code changes, eval execution |
-| **Reviewer** | claude / sonnet | `<workspace>/tasks/<run_id>/reviewer_sandbox/` | distrust audit; advance / hold / rollback |
+| Agent        | Default         | cwd                                            | Owns                                             |
+| ------------ | --------------- | ---------------------------------------------- | ------------------------------------------------ |
+| **Planner**  | claude / opus   | workspace                                      | strategy, `plan.md`, `goal.json`, talking to you |
+| **Coder**    | claude / sonnet | workspace                                      | code changes, eval execution                     |
+| **Reviewer** | claude / sonnet | `<workspace>/tasks/<run_id>/reviewer_sandbox/` | distrust audit; advance / hold / rollback        |
 
 Each role can use any built-in engine, or a `custom` engine config supplied by a
 local caller (custom engines name an executable, so the HTTP API does not accept
@@ -34,15 +34,17 @@ uses its own default model rather than receiving the Claude `opus` / `sonnet`
 defaults. Role instructions are included in-band for engines that do not expose a
 native system-prompt flag.
 
-Engines without native multi-turn conversation (Cursor, OpenCode, one-shot custom
-engines) spawn a fresh process per send, so the dispatcher replays that role's
-transcript in-band as a `<conversation_history>` block, oldest turns dropped past a
-character budget. Claude, Codex and Antigravity keep context themselves and get no
-replay.
+Engines without native multi-turn conversation (Gemini and one-shot custom engines)
+spawn a fresh process per send with nothing to resume, so the dispatcher replays that
+role's transcript in-band as a `<conversation_history>` block, oldest turns dropped
+past a character budget. Claude, Codex, Antigravity, Grok, OpenCode and Cursor each
+resume their own conversation by id and get no replay — see
+`engineHasNativeConversation` in `types.ts`, which is the single source of truth for
+this and is checked with a two-turn recall test per engine.
 
 The Planner runs read-only so strategy cannot turn into source edits, and that is
 enforced by the engine rather than requested politely: Claude uses plan mode,
-Antigravity and Cursor use their plan modes, and OpenCode gets a generated
+Antigravity uses its plan mode, and OpenCode gets a generated
 `clawo-readonly` agent that denies `edit`/`bash`/`external_directory` (its built-in
 `plan` agent is a user-overridable preset that denies neither, so a "read-only"
 session could otherwise still author files through a shell heredoc). A custom
@@ -103,14 +105,14 @@ curl -X POST http://127.0.0.1:18789/v1/openclaw/tools/autoloop_stop \
 
 ## Plugin tools
 
-| Tool | Args | What |
-|---|---|---|
-| `autoloop_start` | `run_id`, `workspace`, per-role `*_engine?`, `*_model?`, `*_custom_engine?`, `send_timeout_ms?` | Start a run; launches Planner and stores Coder/Reviewer defaults. Each `custom` role requires its matching config. |
-| `autoloop_chat` | `run_id`, `text` | Send a chat message to the Planner; returns the Planner's reply. |
-| `autoloop_status` | `run_id` | Current state (status, iter, push count, subagents_spawned). |
-| `autoloop_list` | — | All active runs in this manager process. |
-| `autoloop_stop` | `run_id`, `reason?` | Terminate; stops Planner / Coder / Reviewer. |
-| `autoloop_reset_agent` | `run_id`, `agent` ('planner' / 'coder' / 'reviewer'), `force?`, `eager_restart?` | Reset one subagent. Planner reset requires `force: true`. |
+| Tool                   | Args                                                                                            | What                                                                                                               |
+| ---------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `autoloop_start`       | `run_id`, `workspace`, per-role `*_engine?`, `*_model?`, `*_custom_engine?`, `send_timeout_ms?` | Start a run; launches Planner and stores Coder/Reviewer defaults. Each `custom` role requires its matching config. |
+| `autoloop_chat`        | `run_id`, `text`                                                                                | Send a chat message to the Planner; returns the Planner's reply.                                                   |
+| `autoloop_status`      | `run_id`                                                                                        | Current state (status, iter, push count, subagents_spawned).                                                       |
+| `autoloop_list`        | —                                                                                               | All active runs in this manager process.                                                                           |
+| `autoloop_stop`        | `run_id`, `reason?`                                                                             | Terminate; stops Planner / Coder / Reviewer.                                                                       |
+| `autoloop_reset_agent` | `run_id`, `agent` ('planner' / 'coder' / 'reviewer'), `force?`, `eager_restart?`                | Reset one subagent. Planner reset requires `force: true`.                                                          |
 
 ## Planner-emitted control tools
 
@@ -118,17 +120,17 @@ The Planner controls the run by emitting fenced ` ```autoloop ` JSON blocks
 inside its replies. The dispatcher parses them out and applies them. You
 never see the JSON — only the Planner's narrative.
 
-| Tool | Args | What |
-|---|---|---|
-| `notify_user` | `level` ('info' / 'warn' / 'decision' / 'error'), `summary`, `detail?`, `channel?` ('auto' / 'wechat' / 'webchat' / 'both' / 'email') | Push you out-of-band. |
-| `spawn_subagents` | `coder_engine?`, `coder_model?`, `reviewer_engine?`, `reviewer_model?`, `initial_directive?` | Start Coder + Reviewer. Omitted values inherit run defaults. An engine change without a model uses the new engine's default. Once a role session has started, changing its engine/model is rejected. Custom configs cannot be emitted by Planner. Only after explicit user approval. |
-| `send_directive` | `goal`, `constraints?`, `success_criteria?`, `max_attempts?` | Next iter's instruction to Coder. |
-| `pause_loop` | `reason` | Halt subloop at next iter boundary; chat keeps working. |
-| `resume_loop` | — | Resume after pause. |
-| `terminate` | `reason` | End run. |
-| `update_push_policy` | partial PushPolicy | Mutate notification rules (e.g. when you say "tell me every iter"). |
-| `write_plan` | `content` (full plan.md body), `commit_message?` | Write `plan.md` to the workspace and git-commit. The **only** way the Planner can author plan.md — Write/Edit are stripped from the Planner session as a hard role boundary. Re-running replaces the whole file. |
-| `write_goal` | `content` (full goal.json body), `commit_message?` | Same, for `goal.json`. Content is JSON-validated before write; malformed content errors back to the Planner. |
+| Tool                 | Args                                                                                                                                  | What                                                                                                                                                                                                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `notify_user`        | `level` ('info' / 'warn' / 'decision' / 'error'), `summary`, `detail?`, `channel?` ('auto' / 'wechat' / 'webchat' / 'both' / 'email') | Push you out-of-band.                                                                                                                                                                                                                                                                |
+| `spawn_subagents`    | `coder_engine?`, `coder_model?`, `reviewer_engine?`, `reviewer_model?`, `initial_directive?`                                          | Start Coder + Reviewer. Omitted values inherit run defaults. An engine change without a model uses the new engine's default. Once a role session has started, changing its engine/model is rejected. Custom configs cannot be emitted by Planner. Only after explicit user approval. |
+| `send_directive`     | `goal`, `constraints?`, `success_criteria?`, `max_attempts?`                                                                          | Next iter's instruction to Coder.                                                                                                                                                                                                                                                    |
+| `pause_loop`         | `reason`                                                                                                                              | Halt subloop at next iter boundary; chat keeps working.                                                                                                                                                                                                                              |
+| `resume_loop`        | —                                                                                                                                     | Resume after pause.                                                                                                                                                                                                                                                                  |
+| `terminate`          | `reason`                                                                                                                              | End run.                                                                                                                                                                                                                                                                             |
+| `update_push_policy` | partial PushPolicy                                                                                                                    | Mutate notification rules (e.g. when you say "tell me every iter").                                                                                                                                                                                                                  |
+| `write_plan`         | `content` (full plan.md body), `commit_message?`                                                                                      | Write `plan.md` to the workspace and git-commit. The **only** way the Planner can author plan.md — Write/Edit are stripped from the Planner session as a hard role boundary. Re-running replaces the whole file.                                                                     |
+| `write_goal`         | `content` (full goal.json body), `commit_message?`                                                                                    | Same, for `goal.json`. Content is JSON-validated before write; malformed content errors back to the Planner.                                                                                                                                                                         |
 
 ### Custom engines and resume
 
@@ -148,24 +150,25 @@ for the `CustomEngineConfig` shape.
 
 ## Default push policy
 
-| Event | Default |
-|---|---|
-| on_start | info / wechat ("loop started, will notify on issues") |
-| on_iter_done_ok | silent |
-| on_target_hit | info / both (webchat + wechat) |
-| on_metric_regression_2 | warn / both |
-| on_reviewer_reject_2 | warn / both |
-| on_phase_error | error / both |
-| on_stall_30min | warn / wechat |
-| on_decision_needed | decision / both |
+| Event                  | Default                                               |
+| ---------------------- | ----------------------------------------------------- |
+| on_start               | info / wechat ("loop started, will notify on issues") |
+| on_iter_done_ok        | silent                                                |
+| on_target_hit          | info / both (webchat + wechat)                        |
+| on_metric_regression_2 | warn / both                                           |
+| on_reviewer_reject_2   | warn / both                                           |
+| on_phase_error         | error / both                                          |
+| on_stall_30min         | warn / wechat                                         |
+| on_decision_needed     | decision / both                                       |
 
 5-minute dedup on (level, summary) prevents duplicate pushes from the same
 event. Channel chain: `auto` walks wechat → whatsapp → email; `wechat` /
 `webchat` / `email` route directly; `both` does webchat (if session known)
-+ wechat fallback chain. **`on_phase_error` and `on_decision_needed` cannot
-be set to `silent: true`** by Planner — `update_push_policy` strips the flag
-and records the attempt in `decisions.jsonl` (these channels are the
-operator's lifeline; they stay loud).
+
+- wechat fallback chain. **`on_phase_error` and `on_decision_needed` cannot
+  be set to `silent: true`** by Planner — `update_push_policy` strips the flag
+  and records the attempt in `decisions.jsonl` (these channels are the
+  operator's lifeline; they stay loud).
 
 ## Auto-compact
 
@@ -176,7 +179,7 @@ Reviewer 70 %. Override per run via `compactThresholds`. A 30 s debounce
 prevents re-fire while post-compact stats settle. Events: `compact` is
 emitted on the dispatcher EventEmitter AND appended to `decisions.jsonl`.
 
-One-shot engines (`codex`, `agy`, `cursor`, `opencode`) cannot compact — their
+One-shot engines (`codex`, `agy`, `grok`, `opencode`) cannot compact — their
 CLIs expose no such command. The threshold is still meaningful there because
 `contextPercent` now tracks real occupancy, but crossing it cannot free space:
 the session emits a single warning on its log channel the first time compaction
@@ -193,7 +196,7 @@ consecutive `phase_error`s and:
 1. Fires `on_phase_error` on each one (defaults to error / both channels).
 2. After `phaseErrorCircuit` consecutive errors (default **3**) emits a
    `decision`-level push and an automatic `terminate { reason:
-   'phase_error_circuit' }`.
+'phase_error_circuit' }`.
 
 A successful (non-error) `iter_done` resets the counter. Override the
 threshold via `AutoloopConfig.phaseErrorCircuit`.
@@ -212,15 +215,15 @@ with `agent: 'reviewer', eager_restart: true`).
 `<ledger>/decisions.jsonl` is the auditable trail of runner / dispatcher
 decisions:
 
-| Kind | When |
-|---|---|
-| `spawn_subagents` | Planner emits `spawn_subagents` |
-| `reset_agent` | Any agent reset (manual or auto-recovery) |
-| `compact` | Auto-compact fires |
-| `update_push_policy` | Planner mutates the policy |
-| `policy_silence_blocked` | Planner tried to silence a critical channel |
-| `phase_error` | Surfaced from dispatcher to runner |
-| `terminate` | Run ends (planner reason or `phase_error_circuit`) |
+| Kind                     | When                                               |
+| ------------------------ | -------------------------------------------------- |
+| `spawn_subagents`        | Planner emits `spawn_subagents`                    |
+| `reset_agent`            | Any agent reset (manual or auto-recovery)          |
+| `compact`                | Auto-compact fires                                 |
+| `update_push_policy`     | Planner mutates the policy                         |
+| `policy_silence_blocked` | Planner tried to silence a critical channel        |
+| `phase_error`            | Surfaced from dispatcher to runner                 |
+| `terminate`              | Run ends (planner reason or `phase_error_circuit`) |
 
 JSONL, one entry per line, ts-prefixed.
 
@@ -258,19 +261,21 @@ Every JSON artifact in the ledger carries a `schema_version` field (currently
 
 ## Backend HTTP / SSE
 
-| Endpoint | Returns |
-|---|---|
-| `GET /autoloop/list` | `{ ok, runs: AutoloopState[] }` |
-| `POST /autoloop/new` | `{ ok, run_id, planner_session }` — body `{ workspace, run_id?, planner_engine?, planner_model?, planner_custom_engine?, coder_engine?, coder_model?, coder_custom_engine?, reviewer_engine?, reviewer_model?, reviewer_custom_engine?, send_timeout_ms? }` |
-| `GET /autoloop/<id>/state` | `{ ok, state: AutoloopState }` — also returns a `terminated`-state stub reconstructed from the registry for runs that aren't in this process's memory, so the dashboard can open historical runs without 404'ing. |
-| `GET /autoloop/<id>/push_log` | `{ ok, entries: PushLogEntry[] }` — served from the ledger via `autoloopStatus`, so historical runs work the same as live ones. |
-| `GET /autoloop/<id>/chat_history` | `{ ok, entries: ChatEntry[] }` — replays `<ledger>/chat.jsonl`. The dashboard fetches this when opening a run so the Planner-pane conversation survives a page refresh / cross-process / re-opening a terminated run. Returns `[]` when the file doesn't exist (e.g. runs that predate the chat-history feature). |
-| `GET /autoloop/<id>/events` | SSE: `snapshot` / `message` / `state` / `push` / `iter_done` / `planner_reply` / `planner_error` / `coder_reply` / `reviewer_reply` / `terminated`. For runs that are NOT in this process's memory (terminated, or live in another process), the endpoint emits a single-shot `snapshot` + `terminated` then closes — the dashboard's existing handlers render history without hanging. |
-| `POST /autoloop/<id>/chat` | **202** `{ ok, queued: true }` — body `{ text }`. Fire-and-forget: the Planner's reply streams back via the `/events` SSE channel as a `planner_reply` event (or `planner_error` on failure); the HTTP response intentionally does NOT wait for it, because first-contact replies routinely exceed reverse-proxy idle limits (e.g. Cloudflare Tunnel cuts at ~100s → 524). 400 on empty text, 404 when the run is not in this process's memory. The MCP `autoloop_chat` tool path keeps the synchronous await-and-return-reply semantics (it runs in-process). |
-| `POST /autoloop/<id>/resume` | `{ ok, state }` — restore the role engine/model choices from the registry and re-create dispatcher + runner. Optional body fields `planner_custom_engine`, `coder_custom_engine`, `reviewer_custom_engine` must be supplied again for roles using `custom` because configs are intentionally not persisted. Existing engine-specific conversation resume behavior is reused where supported; `chat.jsonl` remains the visual history fallback. 404 when the registry has no record. |
-| `POST /autoloop/<id>/delete` | `{ ok }` — stops the runner if still alive, scrubs the row from `~/.claw-orchestrator/autoloop-registry.jsonl`, and purges `persistedSessions` so the run cannot be `/resume`'d back. The ledger directory under `<workspace>/tasks/<run_id>/` is kept on disk. 404 if the run was not present in either memory or the registry. |
+| Endpoint                                 | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /autoloop/list`                     | `{ ok, runs: AutoloopState[] }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `POST /autoloop/new`                     | `{ ok, run_id, planner_session }` — body `{ workspace, run_id?, planner_engine?, planner_model?, planner_custom_engine?, coder_engine?, coder_model?, coder_custom_engine?, reviewer_engine?, reviewer_model?, reviewer_custom_engine?, send_timeout_ms? }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `GET /autoloop/<id>/state`               | `{ ok, state: AutoloopState }` — also returns a `terminated`-state stub reconstructed from the registry for runs that aren't in this process's memory, so the dashboard can open historical runs without 404'ing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `GET /autoloop/<id>/push_log`            | `{ ok, entries: PushLogEntry[] }` — served from the ledger via `autoloopStatus`, so historical runs work the same as live ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `GET /autoloop/<id>/chat_history`        | `{ ok, entries: ChatEntry[] }` — replays `<ledger>/chat.jsonl`. The dashboard fetches this when opening a run so the Planner-pane conversation survives a page refresh / cross-process / re-opening a terminated run. Returns `[]` when the file doesn't exist (e.g. runs that predate the chat-history feature).                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `GET /autoloop/<id>/events`              | SSE: `snapshot` / `message` / `state` / `push` / `iter_done` / `planner_reply` / `planner_error` / `coder_reply` / `reviewer_reply` / `terminated`. For runs that are NOT in this process's memory (terminated, or live in another process), the endpoint emits a single-shot `snapshot` + `terminated` then closes — the dashboard's existing handlers render history without hanging.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `POST /autoloop/<id>/chat`               | **202** `{ ok, queued: true }` — body `{ text }`. Fire-and-forget: the Planner's reply streams back via the `/events` SSE channel as a `planner_reply` event (or `planner_error` on failure); the HTTP response intentionally does NOT wait for it, because first-contact replies routinely exceed reverse-proxy idle limits (e.g. Cloudflare Tunnel cuts at ~100s → 524). 400 on empty text, 404 when the run is not in this process's memory. The MCP `autoloop_chat` tool path keeps the synchronous await-and-return-reply semantics (it runs in-process).                                                                                                                                                                                                            |
+| `GET /autoloop/<id>/resume-requirements` | `{ ok, runId, rolesNeedingCustomEngine }` — the roles whose engine was `custom`, so a caller knows which secret references a resume needs. Role names only; nothing sensitive. 404 when there is no such run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `POST /autoloop/<id>/resume`             | `{ ok, state }` — restore the role engine/model choices from the run's spec and re-create dispatcher + runner. A custom-engine config is never persisted and is never accepted over HTTP, so a role using `custom` is re-supplied by **reference**: `plannerCustomEngineRef` / `coderCustomEngineRef` / `reviewerCustomEngineRef` name an environment variable `CLAWO_CUSTOM_ENGINE_<NAME>` on the orchestrator host, which the server reads and resolves. The name is not sensitive, the value never crosses the wire, and an unknown name is an error rather than a silent start without credentials. Existing engine-specific conversation resume behavior is reused where supported; `chat.jsonl` remains the visual history fallback. 404 when there is no such run. |
+| `POST /autoloop/<id>/delete`             | `{ ok }` — stops the runner if still alive, scrubs the row from `~/.claw-orchestrator/autoloop-registry.jsonl`, and purges `persistedSessions` so the run cannot be `/resume`'d back. The ledger directory under `<workspace>/tasks/<run_id>/` is kept on disk. 404 if the run was not present in either memory or the registry.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 The 3-pane UI consumes these endpoints:
+
 - **Left**: Planner chat (subscribes to `planner_reply`)
 - **Center**: Coder activity (`coder_reply` + `iter_done`)
 - **Right**: Reviewer verdicts (`reviewer_reply`)
@@ -291,15 +296,13 @@ wrote down. A typical shape:
     "name": "test_pass_rate",
     "direction": "max",
     "extract_cmd": "bash eval.sh | grep -oE 'metric=[0-9.]+' | cut -d= -f2",
-    "target": 1.0
+    "target": 1.0,
   },
-  "gates": [
-    { "name": "tests_pass", "cmd": "npm test", "must": "exit-0" }
-  ],
+  "gates": [{ "name": "tests_pass", "cmd": "npm test", "must": "exit-0" }],
   "termination": {
     "max_iters": 10,
-    "scalar_target_hit": true
-  }
+    "scalar_target_hit": true,
+  },
 }
 ```
 
@@ -345,3 +348,76 @@ iter 0 ledger artifacts (`directive` + `eval_output` + `diff.patch` +
   map; the on-disk ledger survives but cannot resume a running state.
 - **Multi-run / same workspace** races on `git index.lock`. Run separate
   workspaces (or git worktrees) for concurrent runs.
+
+## Acceptance contracts (6.0.0)
+
+The Reviewer's `advance` was the only thing standing between an iteration and
+"done", and it could not do the job it was given. Its prompt tells it to
+"re-derive the metric independently if the sandbox has the bits to do so", but
+`stageReviewSandbox` copies in the iteration's artifacts — `directive.json`,
+`diff.patch`, `eval_output.json`, `coder_summary.txt` — plus `plan.md`,
+`goal.json`, and the prior verdict. No code, no evaluator. The verdict was
+therefore a reading of the Coder's own report, and `eval_output` was literally
+whatever the Coder passed to a tool call.
+
+Pass a contract at autoloop start and an `advance` is held unless the checks
+pass. The verdict is rewritten to `hold`, the reason is appended to
+`audit_notes`, and the evidence bundle lands at
+`<ledger>/iter/<n>/evidence/`. Without a contract nothing changes.
+
+### `on_target_hit` now fires
+
+That push-policy key was declared in `types.ts`, given a default, and whitelisted
+for runtime updates — and had **zero firing sites** anywhere in the codebase.
+Autoloop had four ways to notice it was failing (stall, metric regression,
+reviewer rejections, phase-error circuit) and no way to notice it had succeeded,
+because a Reviewer verdict is not a measurement. An acceptance contract is, so
+`on_target_hit` fires when one passes.
+
+### `diff.patch` sees created files
+
+The per-iteration patch was captured with a bare `git diff`, which lists tracked
+modifications only. A file the Coder _created_ appeared in neither the patch nor
+the `--name-only` fallback, while the `git add -A` two lines later committed it —
+so the Reviewer audited a picture that structurally could not show new files.
+The capture now covers tracked changes ∪ untracked files.
+
+`files_changed` is also taken from git unconditionally. It previously preferred
+the Coder's own `files_changed` whenever the Coder supplied one, despite the
+comment above it saying the claim was not trusted.
+
+## Related
+
+- [`verification.md`](./verification.md) — contracts, checks, evidence
+
+## Lifecycle moved to the kernel (6.0.0)
+
+An autoloop is a kernel run whose single node holds the loop for as long as it
+lives. Tool signatures are unchanged.
+
+What went away: the `autoloops` map; `~/.claw-orchestrator/autoloop-registry.jsonl`
+with its four bespoke helpers (append, remove-then-append upsert, reverse-scan
+dedup, rewrite-via-tmp-file); and the two `Set`s — `_startingAutoloops` and
+`_deletingAutoloops` — that existed only because a start and a delete could race
+each other over that shared map.
+
+Two things get better rather than merely moving:
+
+- **`autoloop_status` on a run that is not live in this process** used to return
+  an all-zero stub labelled `reconstructed from registry — not in current process
+memory`: iter 0, no metrics, no error history, because the registry only ever
+  held identity. The record holds the last state the loop published, so a
+  historical run opens with its real iteration count.
+- **The engines `spawn_subagents` actually chose** land on the run record
+  alongside the rest of its state, instead of in a parallel file with its own
+  lifecycle.
+
+`autoloop_resume` restarts a terminated run from the stored spec — the immutable
+record of how it was started — rather than from a registry row whose older
+versions omitted the engine fields entirely. Custom-engine configs are the one
+thing the spec does not carry (they can hold secrets), so a resume must be given
+them again.
+
+Cancelling a run now tears the loop down the way a stop does. It previously left
+the three persistent agents running and their session names claimed, which
+surfaced much later as `session name already in use`.

package/skills/references/claude-cli-tracking.md

@@ -8,13 +8,13 @@ This document tracks which Claude Code CLI version Claw Orchestrator is currentl
 
 | Plugin Version | Claude CLI Version | Date | Notable integrations |
 | v4.8.0 | 2.1.207 | 2026-07-12 | **Autoloop role-level multi-engine support.** Planner, Coder, and Reviewer can select independent engines/models while preserving the Claude defaults. Built-in non-Claude Planners use native read-only/plan modes and receive their role protocol in-band. Spawn selections persist across resume; Codex persists its real thread ID. Runtime and invocation checks used Claude Code 2.1.207 and Codex 0.144.1. |
-| v4.7.0 | 2.1.206 | 2026-07-10 | **Antigravity engine ships + permission-mode sync.** Main feature is the community-contributed first-class `engine: 'agy'` (PR #71, reviewed + hardened: layered resume-ID gating, `agy/` prefix routing, shared `sanitize.ts` across all six engines, ENGINE_TYPES single source). Weekly CLI sync: CC 2.1.200 renamed the `default` permission mode to **`manual`** — verified against 2.1.206 that the choices are now `acceptEdits/auto/bypassPermissions/manual/dontAsk/plan`, that `default` is still accepted (hidden compat), and that **`delegate` is hard-rejected at spawn** — so PermissionMode gains `manual`, drops `delegate`, and agy/gemini map `manual` like `default` (→ `--sandbox`). Codex 0.143.0: empirically re-tested `-c model_reasoning_effort=max` — still 400-rejected for gpt-5.5 (the "first-class max" note is Bedrock GPT-5.6-only), so the `max`→`xhigh` map stays. GPT-5.6 Sol/Terra/Luna registered with official pricing ($5/$30, $2.50/$15, $1/$6; 1M/1M/400K ctx) after the user reported using it — it's a limited preview on API/Codex-auth paths (empirically: ChatGPT-account Codex auth gets a 400, which is why the first probe on this box misread it as Bedrock-only; lesson — an auth-path rejection is not model non-existence). Codex default stays gpt-5.5. Free upside: CC 2.1.205 fixed `--json-schema` invalid-schema silent fallback + `format` keyword rejection; CC 2.1.203 fixed background sessions dropping shell-exported `ANTHROPIC_BASE_URL`. Pins → CC 2.1.206 / Codex 0.143.0 (installed; npm has 0.144.1, exec surface unchanged per release notes). |
+| v4.7.0 | 2.1.206 | 2026-07-10 | **Antigravity engine ships + permission-mode sync.** Main feature is the community-contributed first-class `engine: 'agy'` (PR #71, reviewed + hardened: layered resume-ID gating, `agy/` prefix routing, shared `sanitize.ts` across all six engines, ENGINE*TYPES single source). Weekly CLI sync: CC 2.1.200 renamed the `default` permission mode to **`manual`** — verified against 2.1.206 that the choices are now `acceptEdits/auto/bypassPermissions/manual/dontAsk/plan`, that `default` is still accepted (hidden compat), and that **`delegate` is hard-rejected at spawn** — so PermissionMode gains `manual`, drops `delegate`, and agy/gemini map `manual` like `default` (→ `--sandbox`). Codex 0.143.0: empirically re-tested `-c model_reasoning_effort=max` — still 400-rejected for gpt-5.5 (the "first-class max" note is Bedrock GPT-5.6-only), so the `max`→`xhigh` map stays. GPT-5.6 Sol/Terra/Luna registered with official pricing ($5/$30, $2.50/$15, $1/$6; 1M/1M/400K ctx) after the user reported using it — it's a limited preview on API/Codex-auth paths (empirically: ChatGPT-account Codex auth gets a 400, which is why the first probe on this box misread it as Bedrock-only; lesson — an auth-path rejection is not model non-existence). Codex default stays gpt-5.5. Free upside: CC 2.1.205 fixed `--json-schema` invalid-schema silent fallback + `format` keyword rejection; CC 2.1.203 fixed background sessions dropping shell-exported `ANTHROPIC_BASE_URL`. Pins → CC 2.1.206 / Codex 0.143.0 (installed; npm has 0.144.1, exec surface unchanged per release notes). |
 | v4.6.0 | 2.1.199 | 2026-07-03 | **Model registry sync — Claude Fable 5.** Registered `claude-fable-5` (first Claude 5-family model, tier above Opus; standard $10/$50 per Mtok, cache read $1, full 1M context at standard rates per the official pricing page) with new `fable` alias; taught the `isClaudeModel`/`resolveProvider` heuristics to recognize `fable`/`mythos` strings (they only matched claude/opus/sonnet/haiku). Mythos 5 not listed (same price, limited availability). CC 2.1.198–199 are subagent/background-agent reliability fixes — no invocation-surface change; free upside for us: subagent partial output on rate-limit/server error is now returned instead of silently dropped, and API errors in subagents are reported to the parent. Codex unchanged (0.142.5 is a log-scrub patch; pin stays 0.142.4 as installed). |
 | v4.5.0 | 2.1.197 | 2026-07-01 | **Model registry sync — Claude Sonnet 5 + gpt-5.5 pricing.** CLI 2.1.197 shipped Sonnet 5 as the new default (native 1M-token context; standard $3/$15 per Mtok, launch promo $2/$10 through 2026-08-31 — we price the standard rate). Registered `claude-sonnet-5` in `models.ts` and moved the `sonnet` alias to it (was pinned to `claude-sonnet-4-6`), so `--model sonnet` tracks the CLI's own default and cost/context accounting stays correct; `claude-sonnet-4-6` stays selectable by full id. Also corrected `gpt-5.5` (the default Codex model) from placeholder pricing to OpenAI's published $5/$30 per Mtok + 1M context, and updated docs/examples off `gpt-5.4`. The CC 2.1.179→2.1.197 and Codex 0.138→0.142.x ranges are otherwise bug-fix / TUI / remote-executor / plugin-marketplace work that doesn't touch our invocation flags or the stream-json / codex-exec event schema — no wrapper change. Free upside (no code change): 2.1.181 fixed prompt-caching on custom `ANTHROPIC_BASE_URL` (helps proxy mode), 2.1.187 fixed `--json-schema` StructuredOutput infinite-recall, 2.1.196 turned the 5-min streaming idle watchdog on by default; Codex 0.139 preserves `oneOf`/`allOf` in `--output-schema`. Bumped tested versions Claude 2.1.197 / Codex 0.142.4. |
 | v4.3.0 | 2.1.178 | 2026-06-16 | **Parity batch 2 + legacy-subsystem upgrades (local-only, no cloud).** Claude `--fallback-model` array form (CSV, verified via `claude --help`). Codex-app `codex_threads` (`thread/list`) and `thread/resume` on start when `resumeSessionId` is set (param shapes from `generate-json-schema`). Council agents gain per-agent `effort`/`ultracode`. `ultrareview` re-implemented on the new cross-engine `fanout` primitive (opt-in `engines`, default claude-only). Consensus parsing exposes match source for observability. Dropped on purpose: `codex cloud exec`/best-of-N (cloud/managed — loses local control), `--bg` (we own the subprocess), `--output-last-message` (we already capture final text), ultraplan `ultracode` (violates its plan-only contract). Autoloop mid-turn steer deferred — the loop is strictly sequential (Coder fully completes before the Reviewer runs), so steer would always fall back to a fresh turn; a real version needs concurrent review. |
-| v4.2.0 | 2.1.178 | 2026-06-16 | **`ultracode` integration + binary-verified parity pass.** Added the `ultracode` option on `session_start` — Claude Code's dynamic-workflow mode, wired as the `ultracode: true` settings key merged into `--settings` (confirmed by spawning: it activates `workflow_agent` events in headless stream-json; `--effort ultracode` is rejected by the CLI). Added `claude_agents_list` (wraps `claude agents --json`). Verified against the binary that `claude continue/respawn/stop/logs` do **not** exist as headless subcommands (session continuation stays on `--resume`). Codex 0.137 side: app-server RPC tools `codex_interrupt`/`codex_steer`/`codex_fork`/`codex_rollback`/`codex_models`, `codex exec` reasoning-effort (`-c model_reasoning_effort`) + `--profile` passthrough, and a cross-engine `fanout_*` primitive. Bumped tested versions Claude 2.1.178 / Codex 0.137.0. |
-| v4.1.2 | 2.1.161 | 2026-06-03 | **Model registry sync, not a CLI-flag integration.** Registered Opus 4.8 (`claude-opus-4-8`, now the `opus` alias) and 4.7 in `models.ts` — 2.1.154 shipped Opus 4.8 as the new default and our `opus` alias was still pinned to 4.6, mis-attributing cost. Effort ladder `low/medium/high/xhigh/max` was already supported (`index.ts`/`types.ts`). The 2.1.151–2.1.161 range (note: .151/.155 skipped) is otherwise TUI/reliability/telemetry; two fixes silently benefit our spawn path with no code change — 2.1.153 (stream-json stdin-close hang) and 2.1.161 (`-p` stdout corruption from background subagents). **Watch-out documented, not fixed:** 2.1.160 adds permission prompts under `acceptEdits` (our default) for build-tool config files (`.npmrc`/`.bazelrc`/`.pre-commit-config.yaml`/`.devcontainer/` etc.) and shell-startup files — headless flows touching these should set `dangerouslySkipPermissions` or a bypass permission mode. Codex unchanged (0.133.0); separately fixed Codex `turn.failed`/`error` events being swallowed. |
-| v4.1.1 | 2.1.150 | 2026-05-24 | **No Claude wrapper change** — 2.1.141–2.1.150 are almost entirely TUI / agent-view / security / visual; 2.1.150 itself is "internal infrastructure only". The one scripting-adjacent addition, `claude agents --json` (2.1.145), lists *CLI-managed* sessions and is not used by our own session manager. This release's real engine work was on Codex/Gemini: Codex `--output-schema` wired into `jsonSchema` (Codex 0.132+), Gemini `--skip-trust` for the 0.43 trusted-folders gate. Bumped tested versions Claude 2.1.150 / Codex 0.133.0 / Gemini 0.43.0. |
+| v4.2.0 | 2.1.178 | 2026-06-16 | **`ultracode` integration + binary-verified parity pass.** Added the `ultracode` option on `session_start` — Claude Code's dynamic-workflow mode, wired as the `ultracode: true` settings key merged into `--settings` (confirmed by spawning: it activates `workflow_agent` events in headless stream-json; `--effort ultracode` is rejected by the CLI). Added `claude_agents_list` (wraps `claude agents --json`). Verified against the binary that `claude continue/respawn/stop/logs` do **not** exist as headless subcommands (session continuation stays on `--resume`). Codex 0.137 side: app-server RPC tools `codex_interrupt`/`codex_steer`/`codex_fork`/`codex_rollback`/`codex_models`, `codex exec` reasoning-effort (`-c model_reasoning_effort`) + `--profile` passthrough, and a cross-engine `fanout**` primitive. Bumped tested versions Claude 2.1.178 / Codex 0.137.0. |
+| v4.1.2 | 2.1.161 | 2026-06-03 | **Model registry sync, not a CLI-flag integration.** Registered Opus 4.8 (`claude-opus-4-8`, now the `opus`alias) and 4.7 in`models.ts`— 2.1.154 shipped Opus 4.8 as the new default and our`opus`alias was still pinned to 4.6, mis-attributing cost. Effort ladder`low/medium/high/xhigh/max` was already supported (`index.ts`/`types.ts`). The 2.1.151–2.1.161 range (note: .151/.155 skipped) is otherwise TUI/reliability/telemetry; two fixes silently benefit our spawn path with no code change — 2.1.153 (stream-json stdin-close hang) and 2.1.161 (`-p`stdout corruption from background subagents). **Watch-out documented, not fixed:** 2.1.160 adds permission prompts under`acceptEdits` (our default) for build-tool config files (`.npmrc`/`.bazelrc`/`.pre-commit-config.yaml`/`.devcontainer/`etc.) and shell-startup files — headless flows touching these should set`dangerouslySkipPermissions`or a bypass permission mode. Codex unchanged (0.133.0); separately fixed Codex`turn.failed`/`error`events being swallowed. |
+| v4.1.1 | 2.1.150 | 2026-05-24 | **No Claude wrapper change** — 2.1.141–2.1.150 are almost entirely TUI / agent-view / security / visual; 2.1.150 itself is "internal infrastructure only". The one scripting-adjacent addition,`claude agents --json` (2.1.145), lists *CLI-managed\* sessions and is not used by our own session manager. This release's real engine work was on Codex/Gemini: Codex `--output-schema` wired into `jsonSchema` (Codex 0.132+), Gemini `--skip-trust` for the 0.43 trusted-folders gate. Bumped tested versions Claude 2.1.150 / Codex 0.133.0 / Gemini 0.43.0. |
 |---|---|---|---|
 | v4.1.0 | 2.1.140 | 2026-05-13 | `claude_goal_set` / `claude_goal_clear` / `claude_goal_status` tools (wrap CLI 2.1.139 `/goal` slash command), `plugin_details` tool (wraps `claude plugin details`, 2.1.139), `pluginUrl` config (maps to `--plugin-url`, 2.1.129). Skipped items that are user-controlled via `--settings` (worktree.baseRef, autoMode.hard_deny, skillOverrides, sandbox.bwrapPath / socatPath, parentSettingsBehavior) or auto-set by the CLI (`CLAUDE_CODE_SESSION_ID`, `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`, `CLAUDE_CODE_FORCE_SYNC_OUTPUT` — all TTY-only). Hook `args: string[]`, `continueOnBlock`, hook input `effort.level`, subagent `x-claude-code-agent-id` headers are CLI-internal — no wrapper change needed. |
 | v2.14.2 | 2.1.126 | 2026-05-04 | `bedrockServiceTier` (Bedrock service-tier env, 2.1.122), `project_purge` tool (wraps `claude project purge`, 2.1.126); skipped passive-only items (OTel numeric attr, `invocation_trigger`, `/v1/models` gateway discovery, PowerShell shell changes) |

package/skills/references/cli.md

@@ -20,29 +20,33 @@ The server exposes an OpenAI-compatible chat completions endpoint, enabling any
 
 **Endpoints:**
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/v1/chat/completions` | POST | Chat completions (streaming + non-streaming) |
-| `/v1/models` | GET | List available models |
+| Endpoint               | Method | Description                                  |
+| ---------------------- | ------ | -------------------------------------------- |
+| `/v1/chat/completions` | POST   | Chat completions (streaming + non-streaming) |
+| `/v1/models`           | GET    | List available models                        |
 
 **Request format** (same as OpenAI):
+
 ```json
 {
   "model": "claude-sonnet-4-6",
-  "messages": [{"role": "user", "content": "Hello!"}],
+  "messages": [{ "role": "user", "content": "Hello!" }],
   "stream": true
 }
 ```
 
 **Session routing:** Each conversation maps to a persistent session for prompt cache reuse. Session key resolved from (in priority order):
+
 1. `X-Session-Id` header
 2. `user` field in the request body
 3. Default singleton session
 
 **Model routing:** The `model` field auto-routes to the correct engine:
+
 - `claude-*`, `opus`, `sonnet`, `haiku` → Claude engine
 - `gpt-*` → Codex engine
-- `composer-*` → Cursor engine
+- `grok-*` → Grok engine
+- `composer-*` → Cursor engine (legacy)
 - `gemini-3.5-flash`, `gemini-3.1-pro`, `agy-*`, `agy/*` → Antigravity (`agy`) engine
 - other `gemini-*` → the legacy `gemini` engine (Gemini CLI is sunset; prefer `agy`)
 
@@ -58,38 +62,38 @@ The server exposes an OpenAI-compatible chat completions endpoint, enabling any
 clawo session-start [name] [options]
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-d, --cwd <dir>` | Working directory |
-| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `cursor`, `opencode`, or `custom` |
-| `-m, --model <model>` | Model name or alias |
-| `--permission-mode <mode>` | `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk` |
-| `--effort <level>` | `low`, `medium`, `high`, `max`, `auto` |
-| `--allowed-tools <tools>` | Comma-separated tool whitelist |
-| `--max-turns <n>` | Max agent loop turns |
-| `--max-budget <usd>` | API cost ceiling |
-| `--system-prompt <text>` | Replace system prompt |
-| `--append-system-prompt <text>` | Append to system prompt |
-| `--agents <json>` | Custom sub-agents JSON |
-| `--agent <name>` | Default agent |
-| `--bare` | No CLAUDE.md, no git context |
-| `-w, --worktree [name]` | Git worktree |
-| `--fallback-model <model>` | Fallback model |
-| `--json-schema <schema>` | JSON Schema for structured output |
-| `--mcp-config <paths>` | MCP config files (comma-separated) |
-| `--settings <path>` | Settings.json path |
-| `--skip-persistence` | Disable session persistence |
-| `--betas <headers>` | Beta headers (comma-separated) |
-| `--enable-agent-teams` | Enable agent teams |
-| `--include-hook-events` | Stream hook lifecycle events (PreToolUse/PostToolUse) |
-| `--permission-prompt-tool <tool>` | Delegate permission prompts to an MCP tool (non-interactive use) |
-| `--exclude-dynamic-system-prompt-sections` | Move cwd/env/git context to user message for better prompt cache hits (auto-enabled with `--bare`) |
-| `--debug <categories>` | Enable targeted debug output by category (e.g. `"api,mcp"`) |
-| `--debug-file <path>` | Write debug output to file |
-| `--from-pr <n>` | Resume a session linked to a GitHub PR number or URL |
-| `--channels <spec>` | MCP channel subscription (research preview) |
-| `--dangerously-load-development-channels <spec>` | Development MCP channel subscriptions (research preview) |
-| `ENABLE_PROMPT_CACHING_1H=1` (env var) | Enable 1-hour prompt cache TTL (auto-set with `--bare`) |
+| Flag                                             | Description                                                                                        |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `-d, --cwd <dir>`                                | Working directory                                                                                  |
+| `-e, --engine <engine>`                          | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `grok`, `opencode`, or `custom`           |
+| `-m, --model <model>`                            | Model name or alias                                                                                |
+| `--permission-mode <mode>`                       | `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk`                            |
+| `--effort <level>`                               | `low`, `medium`, `high`, `max`, `auto`                                                             |
+| `--allowed-tools <tools>`                        | Comma-separated tool whitelist                                                                     |
+| `--max-turns <n>`                                | Max agent loop turns                                                                               |
+| `--max-budget <usd>`                             | API cost ceiling                                                                                   |
+| `--system-prompt <text>`                         | Replace system prompt                                                                              |
+| `--append-system-prompt <text>`                  | Append to system prompt                                                                            |
+| `--agents <json>`                                | Custom sub-agents JSON                                                                             |
+| `--agent <name>`                                 | Default agent                                                                                      |
+| `--bare`                                         | No CLAUDE.md, no git context                                                                       |
+| `-w, --worktree [name]`                          | Git worktree                                                                                       |
+| `--fallback-model <model>`                       | Fallback model                                                                                     |
+| `--json-schema <schema>`                         | JSON Schema for structured output                                                                  |
+| `--mcp-config <paths>`                           | MCP config files (comma-separated)                                                                 |
+| `--settings <path>`                              | Settings.json path                                                                                 |
+| `--skip-persistence`                             | Disable session persistence                                                                        |
+| `--betas <headers>`                              | Beta headers (comma-separated)                                                                     |
+| `--enable-agent-teams`                           | Enable agent teams                                                                                 |
+| `--include-hook-events`                          | Stream hook lifecycle events (PreToolUse/PostToolUse)                                              |
+| `--permission-prompt-tool <tool>`                | Delegate permission prompts to an MCP tool (non-interactive use)                                   |
+| `--exclude-dynamic-system-prompt-sections`       | Move cwd/env/git context to user message for better prompt cache hits (auto-enabled with `--bare`) |
+| `--debug <categories>`                           | Enable targeted debug output by category (e.g. `"api,mcp"`)                                        |
+| `--debug-file <path>`                            | Write debug output to file                                                                         |
+| `--from-pr <n>`                                  | Resume a session linked to a GitHub PR number or URL                                               |
+| `--channels <spec>`                              | MCP channel subscription (research preview)                                                        |
+| `--dangerously-load-development-channels <spec>` | Development MCP channel subscriptions (research preview)                                           |
+| `ENABLE_PROMPT_CACHING_1H=1` (env var)           | Enable 1-hour prompt cache TTL (auto-set with `--bare`)                                            |
 
 ### session-send
 
@@ -97,12 +101,12 @@ clawo session-start [name] [options]
 clawo session-send <name> <message> [options]
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--effort <level>` | Override effort for this message |
-| `--plan` | Enable plan mode |
-| `-s, --stream` | Collect streaming chunks |
-| `-t, --timeout <ms>` | Timeout (default 300000) |
+| Flag                 | Description                      |
+| -------------------- | -------------------------------- |
+| `--effort <level>`   | Override effort for this message |
+| `--plan`             | Enable plan mode                 |
+| `-s, --stream`       | Collect streaming chunks         |
+| `-t, --timeout <ms>` | Timeout (default 300000)         |
 
 ### session-stop
 
@@ -179,21 +183,60 @@ clawo session-team-send <name> <teammate> <message>
 
 The following tools are available through the OpenClaw plugin SDK and TypeScript API but do not have CLI commands. Use the SDK directly or call them via OpenClaw's tool system.
 
-| Tool | Description |
-|------|-------------|
-| `sessions_overview` | Aggregate dashboard of all active sessions |
-| `session_update_tools` | Hot-swap allowed/disallowed tools via `--resume` |
-| `session_switch_model` | Switch model mid-session via `--resume` |
-| `council_start` | Start multi-agent council with worktree isolation |
-| `council_status` | Poll council progress and agent responses |
-| `council_abort` | Abort a running council |
-| `council_inject` | Inject a message into the next council round |
-| `session_send_to` | Cross-session messaging (immediate or queued) |
-| `session_inbox` | Read inbox messages for a session |
-| `session_deliver_inbox` | Deliver queued messages to an idle session |
-| `ultraplan_start` | Start background Opus planning session |
-| `ultraplan_status` | Poll ultraplan progress |
-| `ultrareview_start` | Start fleet of parallel reviewer agents |
-| `ultrareview_status` | Poll ultrareview findings |
+| Tool                    | Description                                       |
+| ----------------------- | ------------------------------------------------- |
+| `sessions_overview`     | Aggregate dashboard of all active sessions        |
+| `session_update_tools`  | Hot-swap allowed/disallowed tools via `--resume`  |
+| `session_switch_model`  | Switch model mid-session via `--resume`           |
+| `council_start`         | Start multi-agent council with worktree isolation |
+| `council_status`        | Poll council progress and agent responses         |
+| `council_abort`         | Abort a running council                           |
+| `council_inject`        | Inject a message into the next council round      |
+| `session_send_to`       | Cross-session messaging (immediate or queued)     |
+| `session_inbox`         | Read inbox messages for a session                 |
+| `session_deliver_inbox` | Deliver queued messages to an idle session        |
+| `ultraplan_start`       | Start background Opus planning session            |
+| `ultraplan_status`      | Poll ultraplan progress                           |
+| `ultrareview_start`     | Start fleet of parallel reviewer agents           |
+| `ultrareview_status`    | Poll ultrareview findings                         |
 
 See [Tools Reference](./tools.md) for full parameter documentation.
+
+## `clawo workflow` (6.0.0)
+
+```bash
+clawo workflow list [--state <s>] [--workflow <name>] [--limit N] [--json]
+clawo workflow show <runId> [--json]
+clawo workflow resume <runId>          # re-attach to a run whose process died
+clawo workflow cancel <runId>
+clawo workflow steer <runId> "<text>"  # queue a correction for the next agent node
+clawo workflow approve <runId> [reject]
+```
+
+`list` prints one row per run with its outcome as `verified` / `REFUTED` /
+`unchecked`. `unchecked` means no acceptance contract was declared — it is not a
+failure.
+
+Runs survive restarts, so `list` sees runs started by other processes and by
+earlier sessions.
+
+## `clawo verify`
+
+```bash
+clawo verify <runId> [--evidence <id>] [--json]
+```
+
+Prints the evidence bundle: per-check pass/fail with the failing command and its
+output tail, the base and head commits, and the files the run changed (created
+files included).
+
+## `clawo runs` additions
+
+```bash
+clawo runs --verified     # only turns whose acceptance contract passed
+clawo runs --refuted      # only turns whose acceptance contract failed
+```
+
+The table gains a `VERIFIED` column with three values: `yes`, `NO`, and `—` for
+"no contract was declared, so nothing checked it". See
+[`observability.md`](./observability.md).