@enderfga/claw-orchestrator 7.5.2 → 7.5.4

package/skills/references/autoloop.md

@@ -2,8 +2,9 @@
 
 Three-agent autonomous iteration loop for a git workspace. You converse with
 the **Planner** to design a plan; on your approval, the Planner spawns the
-**Coder** + **Reviewer** subloop, monitors it, and pushes you (wechat →
-whatsapp → email fallback chain) only when something needs your attention.
+**Coder** + **Reviewer** subloop, monitors it, and pushes you (WeChat →
+WhatsApp → email fallback chain, see [Notification setup](#notification-setup))
+only when something needs your attention.
 
 This page is the operator reference.
 
@@ -34,10 +35,10 @@ 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 (Gemini and one-shot custom engines)
-spawn a fresh process per send with nothing to resume, so the dispatcher replays that
+Engines without native multi-turn conversation (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
+past a character budget. Claude, Codex, Antigravity, Grok and OpenCode 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.
@@ -52,21 +53,16 @@ Planner receives `permissionMode: 'manual'` and its `CustomEngineConfig` **must*
 map that mode to the CLI's read-only flag — if it cannot, the session refuses to
 start rather than silently running write-enabled.
 
-Antigravity's read-only boundary remains `--mode plan` on every Planner turn,
-including recovery. agy 1.1.26 can soft-deny a tool confirmation, emit a valid
-conversation id, leave `result.response` blank, and still exit 0. A missing or
-whitespace-only response is therefore a failed turn at the agy adapter boundary
-for every caller, not a successful empty Planner reply. If the private log for
-that exact turn contains agy's narrow `tool_confirmation_manager` soft-denial
-marker, the caller receives a fixed, sanitized diagnosis; native log content is
-never returned. The captured conversation id remains usable, so a later
-operator-initiated chat resumes with `--conversation`. Recovery neither retries
-the failed message automatically nor relaxes permissions. Because the failed
-reply never reaches the control parser, it cannot change `plan.md` or
-`goal.json`, spawn subagents, or emit an initial directive. agy 1.2.2 can instead
-return a non-empty successful reply for the same soft denial; the adapter emits
-the refused tool names through `SendResult.permissionDenials` while preserving
-that reply.
+Antigravity's read-only boundary is `--mode plan` on every Planner turn,
+including recovery. An empty or whitespace-only agy reply is a failed turn, not
+an empty Planner reply. When agy's log for that turn shows a soft-denied tool
+confirmation, the caller receives a fixed diagnosis (native log content is never
+returned); when agy instead returns a non-empty reply for a soft denial, the
+reply is kept and the refused tool names are reported in
+`SendResult.permissionDenials`. The Planner's conversation id stays resumable,
+the failed message is not retried automatically, and permissions are not
+relaxed. A failed reply never reaches the control parser, so it cannot change
+`plan.md` or `goal.json`, spawn subagents, or emit an initial directive.
 
 Coder and Reviewer engine/model choices can be overridden by the first successful
 `spawn_subagents`; later attempts to change an already-started role are rejected
@@ -76,6 +72,11 @@ Coder and Reviewer **never speak to you directly**. Anything they observe
 flows through the Planner. The Planner decides what to surface and what to
 absorb.
 
+A run left idle past `sessionTtlMinutes` has its role sessions evicted like any
+other session. The next message to a role starts it again under the same name,
+which resumes the persisted conversation where the engine supports it, instead of
+failing with "Session not found".
+
 ## UX flow
 
 ```
@@ -86,19 +87,24 @@ absorb.
 3. autoloop_chat { run_id, "go" }             → Planner emits spawn_subagents
 4. Coder + Reviewer self-iterate              → ledger writes per iter
 5. Planner pushes you on target_hit / regression / decision / stall
-6. Run terminates on target hit, plan-defined max_iters, or your terminate.
+6. Run ends when the Planner emits terminate, the phase-error circuit trips,
+   the hard deadline passes, or you stop it. An expired activity lease
+   pauses the run instead.
 ```
 
+Stopping at a target or at `max_iters` from `goal.json` is the Planner's
+decision: the runtime does not evaluate `goal.json`.
+
 ## Timeout hierarchy and recoverable sends
 
 Autoloop has three independent start-time controls. Their bounds are inclusive,
 and omitting them retains the defaults:
 
-| Wire field                     | Runtime field             | Default  | Minimum | Maximum   | Meaning |
-| ------------------------------ | ------------------------- | -------- | ------- | --------- | ------- |
-| `send_timeout_ms`              | `sendTimeoutMs`           | 600000   | 5000    | 7200000   | Wall-clock cap for one Planner, Coder, or Reviewer delivery |
-| `activity_lease_ms`            | `activityLeaseMs`         | 1800000  | 60000   | 7200000   | Inactivity lease, renewed only by validated user or agent progress |
-| `autoloop_hard_timeout_ms`     | `autoloopHardTimeoutMs`   | 86400000 | 600000  | 259200000 | Absolute run deadline, anchored to start and never renewed |
+| Wire field                 | Runtime field           | Default  | Minimum | Maximum   | Meaning                                                            |
+| -------------------------- | ----------------------- | -------- | ------- | --------- | ------------------------------------------------------------------ |
+| `send_timeout_ms`          | `sendTimeoutMs`         | 600000   | 5000    | 7200000   | Wall-clock cap for one Planner, Coder, or Reviewer delivery        |
+| `activity_lease_ms`        | `activityLeaseMs`       | 1800000  | 60000   | 7200000   | Inactivity lease, renewed only by validated user or agent progress |
+| `autoloop_hard_timeout_ms` | `autoloopHardTimeoutMs` | 86400000 | 600000  | 259200000 | Absolute run deadline, anchored to start and never renewed         |
 
 Timer checks and runner-generated bookkeeping do not renew the activity lease.
 The hard deadline cannot be extended by repeated activity and wins if it fires
@@ -122,44 +128,49 @@ stored spec, chat or iteration evidence, or any earlier audit bytes.
 
 ## Quick start
 
+Over HTTP, against `clawo serve` (default `127.0.0.1:18796`):
+
 ```bash
-# Start a run (creates Planner session)
-curl -X POST http://127.0.0.1:18789/v1/openclaw/tools/autoloop_start \
-  -H 'content-type: application/json' \
+TOKEN=$(cat ~/.openclaw/server-token)
+
+# Start a run (creates the Planner session)
+curl -X POST http://127.0.0.1:18796/autoloop/new \
+  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
   -d '{"run_id":"my-run","workspace":"/abs/path/to/workspace"}'
 
-# Chat with the Planner
-curl -X POST http://127.0.0.1:18789/v1/openclaw/tools/autoloop_chat \
-  -H 'content-type: application/json' \
-  -d '{"run_id":"my-run","text":"Read the workspace and design a plan to fix X"}'
+# Chat with the Planner (202; the reply arrives on /events as planner_reply)
+curl -X POST http://127.0.0.1:18796/autoloop/my-run/chat \
+  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
+  -d '{"text":"Read the workspace and design a plan to fix X"}'
 
 # Inspect state
-curl http://127.0.0.1:18789/autoloop/my-run/state
+curl http://127.0.0.1:18796/autoloop/my-run/state -H "Authorization: Bearer $TOKEN"
 
-# Live SSE stream (the 3-pane UI subscribes here)
-curl http://127.0.0.1:18789/autoloop/my-run/events
+# Live SSE stream (the dashboard's 3-pane view subscribes here)
+curl -N http://127.0.0.1:18796/autoloop/my-run/events -H "Authorization: Bearer $TOKEN"
+```
+
+Resetting an agent and stopping a run have no HTTP route; call the tools
+(plugin or MCP):
 
-# Reset Coder if it drifts (lazy; eager_restart=true to start a fresh session immediately)
-curl -X POST http://127.0.0.1:18789/v1/openclaw/tools/autoloop_reset_agent \
-  -H 'content-type: application/json' \
-  -d '{"run_id":"my-run","agent":"coder","eager_restart":true}'
+```jsonc
+// Reset the Coder if it drifts (lazy by default; eager_restart starts a fresh session now)
+autoloop_reset_agent({ "run_id": "my-run", "agent": "coder", "eager_restart": true })
 
-# Stop
-curl -X POST http://127.0.0.1:18789/v1/openclaw/tools/autoloop_stop \
-  -H 'content-type: application/json' \
-  -d '{"run_id":"my-run","reason":"done"}'
+// Stop
+autoloop_stop({ "run_id": "my-run", "reason": "done" })
 ```
 
 ## Plugin tools
 
-| Tool                   | Args                                                                                            | What                                                                                                               |
-| ---------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Tool                   | Args                                                                                                                                               | What                                                                                                                                    |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `autoloop_start`       | `run_id`, `workspace`, per-role `*_engine?`, `*_model?`, `*_custom_engine?`, `send_timeout_ms?`, `activity_lease_ms?`, `autoloop_hard_timeout_ms?` | Start a run; launches Planner and stores Coder/Reviewer defaults and timeout controls. 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`.                                                          |
+| `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 autoloop runs in the run store, live or not.                                                                                        |
+| `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
 
@@ -193,18 +204,17 @@ removes partial files, and suppresses both spawn and directives.
 
 ### Custom engines and resume
 
-Custom engine configs are accepted only by `autoloop_start` (or the HTTP resume
-body), never through Planner output. This keeps config fields such as `env` and
-static CLI arguments out of the Planner transcript and `decisions.jsonl`.
-The central registry persists only each role's engine and model, including the
-effective Coder/Reviewer selection after a successful spawn. Resume leaves the
-prior append-only row untouched until startup succeeds, so a transient CLI
-failure cannot erase the run. When resuming a run that uses `custom`, provide
-the matching `planner_custom_engine`, `coder_custom_engine`, or
-`reviewer_custom_engine` again; otherwise resume fails with a clear
+Custom engine configs are accepted only by `autoloop_start` (and, on resume, by
+`SessionManager.autoloopResume()` or by reference in the HTTP resume body), never
+through Planner output. This keeps config fields such as `env` and static CLI
+arguments out of the Planner transcript and `decisions.jsonl`. The run record
+stores only each role's engine and model, including the effective Coder/Reviewer
+selection after a successful spawn. When resuming a run that uses `custom`,
+supply the matching config again (over HTTP, as a `*CustomEngineRef`, see
+[Backend HTTP / SSE](#backend-http--sse)); otherwise resume fails with a clear
 configuration error rather than silently switching to Claude. Custom config
-shape is validated at runtime, while its `env` and static CLI arguments remain
-out of registry and audit records. See [`multi-engine.md`](./multi-engine.md)
+shape is validated at runtime, while its `env` and static CLI arguments stay
+out of the run record and audit logs. See [`multi-engine.md`](./multi-engine.md)
 for the `CustomEngineConfig` shape.
 
 ## Default push policy
@@ -213,34 +223,53 @@ for the `CustomEngineConfig` shape.
 | ---------------------- | ----------------------------------------------------- |
 | on_start               | info / wechat ("loop started, will notify on issues") |
 | on_iter_done_ok        | silent                                                |
-| on_target_hit          | info / both (webchat + wechat)                        |
+| on_target_hit          | info / both                                           |
 | 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)
+The runtime fires five of these itself: `on_stall_30min` (30 minutes without
+activity), `on_metric_regression_2`, `on_reviewer_reject_2` (two in a row),
+`on_phase_error`, and `on_target_hit` (only when an acceptance contract passes,
+see [Acceptance contracts](#acceptance-contracts)). `on_start`,
+`on_iter_done_ok` and `on_decision_needed` are policy entries for the Planner's
+own `notify_user` calls.
+
+A 5-minute dedup on (level, summary) prevents duplicate pushes from the same
+event. Channels: `auto` and `both` walk WeChat → WhatsApp → email and stop at
+the first that succeeds; `wechat` and `email` go to that channel only;
+`webchat` is a no-op (see [Known limitations](#known-limitations)).
+**`on_phase_error` and `on_decision_needed` cannot be set to `silent: true`**
+by the Planner: `update_push_policy` strips the flag and records the attempt in
+`decisions.jsonl`.
 
-- 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).
+## Notification setup
+
+- **WeChat** needs `AUTOLOOP_WECHAT_RECIPIENT` and `AUTOLOOP_WECHAT_ACCOUNT`.
+- **WhatsApp** needs `AUTOLOOP_WHATSAPP_RECIPIENT`.
+- Both send through the `openclaw` CLI, which must be on `PATH`.
+- **Email** is sent by running `bash "$AUTOLOOP_EMAIL_SCRIPT" -s "<subject>"`
+  with the message body on stdin.
+
+Any channel whose variables are unset is skipped silently. With none set,
+pushes are recorded in `push_log.jsonl` only.
 
 ## Auto-compact
 
 Each agent's context is monitored after every turn. When `getStats().contextPercent`
 crosses the per-agent threshold the dispatcher invokes `/compact` with a
 role-tuned hint (`compactSummaryFor`). Defaults: Planner 80 %, Coder 70 %,
-Reviewer 70 %. Override per run via `compactThresholds`. A 30 s debounce
+Reviewer 70 %. The dispatcher's `compactThresholds` option overrides them; it
+is library-level only and not exposed through `autoloop_start` or the HTTP
+API. 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`, `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:
+`contextPercent` tracks real occupancy, but crossing it cannot free space:
 the session emits a single warning on its log channel the first time compaction
 is requested, then the thread keeps growing until the CLI refuses the request.
 Treat that warning as the signal to start a fresh session.
@@ -257,8 +286,9 @@ consecutive `phase_error`s and:
    `decision`-level push and an automatic `terminate { reason:
 'phase_error_circuit' }`.
 
-A successful (non-error) `iter_done` resets the counter. Override the
-threshold via `AutoloopConfig.phaseErrorCircuit`.
+A successful (non-error) `iter_done` resets the counter. The threshold is
+`AutoloopConfig.phaseErrorCircuit`, which is library-level only and not exposed
+through `autoloop_start` or the HTTP API.
 
 ## Reviewer frozen memory
 
@@ -294,6 +324,8 @@ JSONL, one entry per line, ts-prefixed.
 ├── goal.json            # Planner-authored, git-committed
 ├── push_log.jsonl       # every notify_user attempt + channel used
 ├── decisions.jsonl      # runner / dispatcher audit trail (see above)
+├── chat.jsonl           # Planner-pane conversation, replayed by /chat_history
+├── evidence/iter-<n>/   # acceptance-contract bundle, when a contract is configured
 ├── reviewer_sandbox/    # Reviewer cwd; restaged per iter
 │   ├── plan.md          # copy
 │   ├── goal.json        # copy
@@ -304,7 +336,7 @@ JSONL, one entry per line, ts-prefixed.
 └── iter/<n>/
     ├── directive.json     # Planner → Coder        (schema_version: 1)
     ├── eval_output.json   # what Coder reported     (schema_version: 1)
-    ├── diff.patch         # git diff of the iter
+    ├── diff.patch         # git diff of the iter, created files included
     ├── verdict.json       # Reviewer decision + audit notes (schema_version: 1)
     └── coder_summary.txt
 ```
@@ -315,25 +347,28 @@ inside an iter** (pre-commit hook reject, signing key missing, …) the
 dispatcher emits a `phase_error` instead of writing `iter_artifacts`, so
 the failure is visible to the runner and counts toward the circuit.
 
+`files_changed` in the iteration artifacts is taken from git, never from the
+Coder's own report.
+
 Every JSON artifact in the ledger carries a `schema_version` field (currently
 `1`) to make future migrations explicit.
 
 ## 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?, activity_lease_ms?, autoloop_hard_timeout_ms? }`. Timeout fields use the defaults and inclusive bounds documented above; malformed or out-of-range values return 400 before a run starts.                                                                                                                                                                                                                                                                                                                                                                                        |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Endpoint                                 | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /autoloop/list`                     | `{ ok, runs: AutoloopState[] }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `POST /autoloop/new`                     | `{ ok, run_id, planner_session }` — body `{ workspace, run_id?, planner_engine?, planner_model?, coder_engine?, coder_model?, reviewer_engine?, reviewer_model?, send_timeout_ms?, activity_lease_ms?, autoloop_hard_timeout_ms? }`. Timeout fields use the defaults and inclusive bounds documented above; malformed or out-of-range values return 400 before a run starts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `GET /autoloop/<id>/state`               | `{ ok, state: AutoloopState, live }` — `live` is `true` only when the run is running in this process. For a run that is not live here, `state` is the last state recorded in the run store, so historical runs open with their real iteration count. 404 when there is no such run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `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. A run still in memory that has already reached `terminated` or `crashed` gets the same single-shot pair instead of an open stream that would never receive another event. Every such stream sets `retry: 864000000`, so an `EventSource` does not keep reconnecting to a stream that can only end again.                                                                                                                                                                                                                                                                                            |
+| `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: if the store still holds it, the error says so and names `POST /autoloop/<id>/resume`; an unknown or malformed id is plain `not found`. 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. For recoverable send timeouts, body fields `send_timeout_ms` and `pending_dispatch_id` apply the increase-only migration described above; `allow_decrease`, lease overrides, and hard-cap overrides are rejected. 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.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `POST /autoloop/<id>/delete`             | `{ ok }` — stops the loop if still live, deletes the run record from the run store, and purges the role sessions' persisted resume ids so the run cannot be resumed. The ledger directory under `<workspace>/tasks/<run_id>/` is kept on disk. 404 when there is no such run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
-The 3-pane UI consumes these endpoints:
+The dashboard's 3-pane autoloop view (`/dashboard`) consumes these endpoints:
 
 - **Left**: Planner chat (subscribes to `planner_reply`)
 - **Center**: Coder activity (`coder_reply` + `iter_done`)
@@ -341,8 +376,6 @@ The 3-pane UI consumes these endpoints:
 - **Top bar**: state (status / iter / metric)
 - **Bottom**: push_log
 
-The UI itself ships in a separate cross-repo PR.
-
 ## `goal.json` shape
 
 The Planner authors goal.json based on your conversation. There is no
@@ -377,106 +410,56 @@ The Planner will riff on this shape during your chat and ask if it's right.
 - ✅ Reviewer accumulates "fakery patterns I've seen" in `reviewer_memory.md` (persists across iters).
 - ✅ Reviewer defaults to `hold` under uncertainty; only `advance` after independent verification.
 
-## Smoke test
+## Acceptance contracts
 
-`scripts/smoke-autoloop.ts` runs a buggy `add_two` scenario end-to-end with
-Opus Planner + Sonnet × 2. Validates plan.md / goal.json commit, spawn,
-iter 0 ledger artifacts (`directive` + `eval_output` + `diff.patch` +
-`verdict`), and termination on `target_hit`. Cost ~$1-3, wall-clock
-~5-15 min. Run with `npx tsx scripts/smoke-autoloop.ts` (requires
-`~/.claude/settings.json` to have your auth env).
+The Reviewer's sandbox holds the iteration's artifacts (`directive.json`,
+`diff.patch`, `eval_output.json`, `coder_summary.txt`, `plan.md`, `goal.json`,
+the prior verdict) but no code or evaluator, so its `advance` is a judgement of
+the Coder's report rather than a measurement.
 
-## Known limitations
+An acceptance contract closes that gap. When one is configured, an `advance`
+stands only if the checks pass against the workspace: otherwise the verdict is
+rewritten to `hold`, the failing checks are appended to `audit_notes`, and the
+bundle is written to `<ledger>/evidence/iter-<n>/`. A passing contract fires
+`on_target_hit`. Without a contract the Reviewer's verdict is used as-is.
 
-- **`webchat` channel is a no-op** — `notifyUserFallbackChain` does not yet
-  carry a webchat session id at the run level, so `channel: 'webchat'`
-  always returns `channel_used: 'none'`. Use `auto` / `wechat` / `email`
-  until the inbound route lands.
-- **One-way push.** WeChat → Planner inbound replies are not yet wired (would
-  need an openclaw-gateway tmux-passthrough route). Reply via webchat /
-  `autoloop_chat`.
-- **No webchat UI yet.** Backend SSE is shipped; the UI is a separate
-  cross-repo PR in ChatGPT-Next-Web.
-- **No fork / population mode.** Single linear iter trajectory per run.
-- **Cross-run knowledge isolated.** Each run's `reviewer_memory.md` and
-  `coder_notes.md` live in that run's ledger; no shared meta-store yet.
-- **No cost / wall-clock budget cap.** Only `phaseErrorCircuit` + Reviewer
-  hold/reject streaks bound the run; a steady-but-pointless ratchet could
-  run for days. Set `max_iters` in `goal.json` to bound iter count.
-- **Run state in memory.** SessionManager restart drops the live `autoloops`
-  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.
+**The contract is library-level only.** It is set on the dispatcher config
+(`contract` in `ClaudeAgentDispatcherConfig`) and is not yet exposed through
+`autoloop_start` or the HTTP API, so a run started from the tool or
+`POST /autoloop/new` has no contract.
 
-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.
+## Lifecycle and resume
 
-### `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.
+An autoloop is a kernel run whose single node holds the loop for as long as it
+lives. The run record holds the last state the loop published and the engines
+`spawn_subagents` chose, so `autoloop_status` and `GET /autoloop/<id>/state`
+show a run's real state after it stops or the process restarts.
 
-### `diff.patch` sees created files
+Resume is explicit. `POST /autoloop/<id>/resume` (or
+`SessionManager.autoloopResume()`) restarts a run from its stored spec.
+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 stops all three
+agents, the same as `autoloop_stop`.
 
-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.
+## Known limitations
 
-`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.
+- **`webchat` channel is a no-op.** No webchat session id is carried at the run
+  level, so `channel: 'webchat'` always returns `channel_used: 'none'`. Use
+  `auto` / `wechat` / `email`.
+- **One-way push.** Replies to a push are not routed back to the Planner;
+  answer with `autoloop_chat`.
+- **No fork / population mode.** Single linear iter trajectory per run.
+- **Cross-run knowledge isolated.** Each run's `reviewer_memory.md` and
+  `coder_notes.md` live in that run's ledger; there is no shared store.
+- **No cost cap.** `maxBudgetUsd` is not exposed for autoloop. Wall-clock time
+  is bounded by `autoloop_hard_timeout_ms` (default 24 h); the iteration count
+  is bounded only by the Planner honouring `max_iters` in `goal.json`.
+- **Resume is not automatic.** After a restart a run is not live in the new
+  process until it is resumed, and a send that was in flight is not retried.
+- **Multi-run / same workspace** races on `git index.lock`. Run separate
+  workspaces (or git worktrees) for concurrent runs.
 
 ## 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`.
+- [`workflow.md`](./workflow.md) — the kernel that stores and resumes runs