@enderfga/claw-orchestrator 7.12.0 → 7.13.0

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify", "clawo solve", "clawo fanout", "fix and verify", "solve from the terminal".
+description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify", "clawo solve", "clawo fanout", "fix and verify", "solve from the terminal", "codex goal", "/goal", "clawo goal", "long-horizon goal", "unattended codex run", "goal node", "run codex in a sandbox", "launcher".
 metadata:
   {
     'openclaw':
@@ -213,15 +213,18 @@ For setup, the dsh YAML block, and the cancellation/permission limits: see [refe
 
 ## Durable workflows
 
-`workflow_start` runs a declarative graph of `agent` / `fanout` / `council` / `verifier` /
-`human_gate` / `router` / `subflow` / `autoloop` / `ultraapp_synth` /
+`workflow_start` runs a declarative graph of `agent` / `fanout` / `council` / `goal` /
+`verifier` / `human_gate` / `router` / `subflow` / `autoloop` / `ultraapp_synth` /
 `ultraapp_deploy` nodes. Every state transition is checkpointed to
 `~/.claw-orchestrator/wf/<runId>/`, so a run survives a process restart and `workflow_resume`
 picks it up at the node boundary — nodes already succeeded are not re-run, and the one that
 was in flight is retried because a half-finished node left no result to trust.
 
-Three built-in templates: `solve` (triage → implement → verify → repair-until-green →
-review), `council`, and `fanout`. Retry, per-node timeout, cancel, steer, human gates, and
+Four built-in templates: `solve` (triage → implement → verify → repair-until-green →
+review), `council`, `fanout`, and `goal` (a Codex `/goal` on one `codex-app` thread, run
+unattended for as long as it takes — reattached on resume, resumed after usage limits and
+stalls within a bound, optionally under a sandbox `launcher` — then verify → repair on the
+same thread; `clawo goal` from the terminal). Retry, per-node timeout, cancel, steer, human gates, and
 bounded loops come from the kernel rather than from each mode's own state machine.
 
 For node shapes, routing conditions, and the control surfaces:

package/skills/references/autoloop.md

@@ -138,6 +138,19 @@ A successful increase appends exactly one `timeout_migration` record to
 pending dispatch identity when available. It does not rewrite the original
 stored spec, chat or iteration evidence, or any earlier audit bytes.
 
+A live run paused by `pause_loop` or an expired activity lease, with
+`pending_dispatch` null, continues on `autoloopResume()` / `POST /autoloop/<id>/resume`
+with no timeout fields. That resume clears the lease expiry, sets status back
+to `planning` (or `running` once subagents have been spawned), re-arms the
+activity lease from the resume, and leaves the original hard deadline where it
+was. That call returns once the run is active again; Planner chat accepted
+during the pause was parked, not delivered, and is then delivered once, in
+order, by the background drain. If the hard deadline has already passed, the
+same resume terminates the run with `hard_timeout_exceeded` and delivers
+nothing. A no-option resume of an `awaiting_resume` send-timeout pause is still
+a no-op: the pending dispatch, its reason, and the lease suspension stay as
+they are until an explicit timeout increase names that dispatch.
+
 ## Quick start
 
 Over HTTP, against `clawo serve` (default `127.0.0.1:18796`):
@@ -212,7 +225,7 @@ removes partial files, and suppresses both spawn and directives.
 | `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.                                                                                                                                                                                                                              |
+| `pause_loop`         | `reason`                                                                                                                              | Pause the live run. Planner chat is parked during a pause and is delivered once, in order, on resume.                                                                                                                                                                                |
 | `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").                                                                                                                                                                                                                  |
@@ -390,7 +403,7 @@ Every JSON artifact in the ledger carries a `schema_version` field (currently
 | `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>/resume`             | `{ ok, state }` — for a live ordinary or activity-lease pause (`pending_dispatch` null), an empty timeout body continues that run: the response returns once status is `planning` or `running` again, the lease re-arms, the hard deadline stays put, and parked Planner input is then delivered once, in order. A live `awaiting_resume` pause is unchanged unless the body increases the send timeout. Otherwise 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 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 dashboard's 3-pane autoloop view (`/dashboard`) consumes these endpoints:
@@ -464,13 +477,39 @@ 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`. If the highest committed Coder iteration
+agents, the same as `autoloop_stop`.
+
+On a non-fresh boot (resume / revisit), before any Planner session or
+checkpoint publish, the boot reads the run ledger once and restores typed
+`iter` and `metric_history` from the contiguous valid closed prefix of
+`iter/0..K` (each closed entry needs `directive.json` plus a parsed
+`verdict.json` whose `iter` matches and whose `decision` is a supported
+Reviewer decision). Finite verdict metrics are kept in order, capped at
+`MAX_METRIC_HISTORY` (20). The stored checkpoint's `iter` / `metric_history`
+are never progress authority. A fresh start skips that read. When there is no
+valid closed prefix (including missing or open/malformed `iter/0` with a later
+canonical directory present), the reader returns without restore or refusal —
+same Planner-only resume as before. If the highest committed Coder iteration
 has ledger artifacts and no `verdict.json`, and `HEAD` still names that iter,
-resume starts and sends only the Reviewer: one `review_request` for that
-checkpoint, and the dispatcher persists `verdict.json`. It does not create or
-resume a Coder session, and a historical persisted Coder registry row is left
-unchanged. An in-flight send is still not retried, and there is no message
-outbox.
+resume still starts and sends only the Reviewer: one `review_request` for that
+iteration (with rebuilt `prior_metrics`), and the dispatcher persists
+`verdict.json`. It does not create or resume a Coder session, and a historical
+persisted Coder registry row is left unchanged. An in-flight send is still not
+retried, and there is no message outbox. A gap or malformed closed tail after a
+valid prefix refuses the resume with a fixed generic error before any new
+session or effect; ledger text is never echoed into the error.
+
+**Accepted chat survives stop and owner loss.** `autoloop_chat` and `POST
+/autoloop/:id/chat` accept a message only once it is in the run's checkpoint;
+otherwise they fail (`autoloop chat could not be persisted`, or a stopping,
+restoring or limit error) and nothing is sent. Up to 1,000 entries and 8 MiB
+can be pending. Chat that was not yet handed to the Planner is delivered once,
+in order, after a resume. Chat that was being delivered when the run stopped is
+not resent: the status gains `unconfirmed_chat` (`count`, `last_at`,
+`history_pending`) and chat history gets one system notice asking to re-send it
+if needed. No further chat is handed over until that notice is recorded; if it
+cannot be written the run pauses with `chat_notice_pending`, and a plain resume
+retries it.
 
 ## Known limitations
 
@@ -489,6 +528,11 @@ outbox.
   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.
+- **Closed-ledger restore does not rebuild streaks or status.** Only `iter` and
+  capped `metric_history` are restored from the closed prefix; `rejectStreak`,
+  `regressionStreak`, and run `status` fields are not reconstructed. Prefixless
+  corruption, path/symlink size hardening, and fresh `autoloop_start` reuse of a
+  retained ledger id remain out of scope.
 
 ## Related
 

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

@@ -2,12 +2,14 @@
 
 This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated. Recent rows also record the other engines' versions checked in the same sync.
 
-## Currently tracked: **Claude Code CLI 2.1.302** (as of 2026-10-17, plugin v7.12.0)
+## Currently tracked: **Claude Code CLI 2.1.307** (as of 2026-10-24, plugin v7.13.0)
 
 ## Sync history
 
 | Plugin Version      | Claude CLI Version | Date       | Notable integrations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| v7.13.0             | 2.1.307            | 2026-10-24 | Codex 0.163.0→0.164.0; the other engines as tracked in v7.12.1. Integrated: Codex 0.164 app-server goal RPCs (`thread/goal/set` / `get` / `clear`, six goal states, `tokenBudget`, `thread/goal/updated`), structured `error` notifications (`codexErrorInfo`, `willRetry`), `turn/steer` during goal turns, and `approvalPolicy` on `thread/start` / `thread/resume`; the `goal` workflow node is built on them. Measured: a goal objective is capped at 4,000 characters, and a thread can be resumed only after its first turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| v7.12.1             | 2.1.307            | 2026-10-22 | CC 2.1.302→2.1.307, agy 1.4.0→1.4.4, grok 1.0.62→1.0.67; Codex 0.163.0 and OpenCode 1.19.3 unchanged. No flag the wrappers pass changed. grok 1.0.67 makes `grok-4.7` its default and only model: registered (same prices and 500K window as `grok-4.6`), the `grok` alias moved to it, and a session with no `model` is labelled with the model grok reports. grok read-only re-measured on 1.0.67 (direct and shell writes blocked; the subagent probe hit the free-tier limit). OpenCode 2 still beta-only, still refused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | v7.12.0             | 2.1.302            | 2026-10-17 | CC 2.1.296→2.1.302, Codex 0.162.1→0.163.0, agy 1.3.2→1.4.0, grok 1.0.50→1.0.62, OpenCode 1.19.0→1.19.3. No flag the wrappers pass changed. grok read-only re-measured on 1.0.62 (direct, shell and subagent writes blocked; the failed-sandbox warning unchanged). OpenCode 2 still beta-only, still refused. Codex 0.163.0 turns Daybreak (security programme, not a model) on for eligible accounts; billing follows the model codex reports.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | v7.11.0             | 2.1.296            | 2026-10-11 | CC 2.1.295→2.1.296, Codex 0.162.0→0.162.1, OpenCode 1.18.35→1.19.0; agy 1.3.2 and grok 1.0.50 unchanged. No flag the wrappers pass changed. OpenCode 1.19.0 offers `opencode upgrade --major` to OpenCode 2 (beta builds `0.0.0-beta-N`, replaces V1): measured on 0.0.0-beta-17823 it drops `step_finish` and `--variant`, and its free tier answers 403 to a custom agent, so the read-only agent is unverifiable — the OpenCode session now refuses a V2 binary at start.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | v7.10.0             | 2.1.295            | 2026-10-09 | CC 2.1.292→2.1.295, Codex 0.160.1→0.162.0, agy 1.3.1→1.3.2, grok 1.0.46→1.0.50; OpenCode 1.18.35 unchanged. No flag the wrappers pass changed. Integrated: Claude Haiku 5.5 registered and the `haiku` alias moved to it (`--model haiku` resolves to `claude-haiku-5-5` in 2.1.295); Sonnet 5.5's cache-hit price corrected to 0.05× input. Integrated: grok 1.0.50's `--sandbox read-only` backs Grok's `sandboxMode: 'read-only'`, measured against direct, shell, subagent, resumed-turn and out-of-project writes; a profile grok cannot apply only warns, so the session kills the process on that warning.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

package/skills/references/cli.md

@@ -238,6 +238,37 @@ engine may appear more than once. With `--wait` the run is followed to the end
 and every answer is printed, followed by the synthesis when `--synthesize` was
 given. Checks run after the fan-out, as for `solve`.
 
+## `clawo goal`
+
+Run a Codex `/goal` on one `codex-app` thread, then have the runtime check the
+result: goal → verify → repair on the same thread. See [workflow.md](./workflow.md#goal).
+
+```bash
+clawo goal "<objective>" | --objective-file <file>
+           [--check "<command>"]... [--contract <file>] [--check-timeout <minutes>]
+           [--launcher <arg>]... [--model <model>] [--effort <level>] [--sandbox <mode>] [--thread <id>]
+           [--token-budget N] [--goal-timeout <minutes>] [--max-repairs N]
+           [--cwd <dir>] [--wait] [--json]
+```
+
+| Option             | Default           | Notes                                                                                                               |
+| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `--objective-file` | —                 | Read the objective from a file instead of the argument. Codex accepts at most 4,000 characters                      |
+| `-c, --check`      | —                 | A command check, repeatable, run after the goal. Split on whitespace; quote-needing commands go in `--contract`     |
+| `--check-timeout`  | 10                | Minutes for each `--check`. The verifier's node timeout is sized from the checks                                    |
+| `--launcher`       | —                 | Run codex under this command, one argv element per flag: `--launcher ./sandbox.sh --launcher task --launcher "0 1"` |
+| `-m, --model`      | codex's own       | Codex model                                                                                                         |
+| `--sandbox`        | `workspace-write` | Codex's own sandbox mode. With an outer sandbox as the boundary, `danger-full-access`                               |
+| `--thread`         | —                 | Start on this existing codex thread: its goal is replaced, its history kept                                         |
+| `--token-budget`   | —                 | The goal stops as `budgetLimited` past this                                                                         |
+| `--goal-timeout`   | none              | Wall-clock minutes for one goal pass                                                                                |
+| `--max-repairs`    | `1`               | Times a red verdict sends the goal back to the same thread                                                          |
+| `-w, --wait`       | off               | Follow the run; exit `0` only if it completes                                                                       |
+
+`clawo workflow show <runId>` prints the goal's status, tokens, time, resume
+attempts and thread id while it runs; `clawo workflow steer <runId> "<text>"`
+goes into the running turn.
+
 ## `clawo workflow`
 
 ```bash
@@ -245,7 +276,7 @@ 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 steer <runId> "<text>"  # a correction for the next agent node, or into a running goal
 clawo workflow approve <runId> [reject]
 ```
 

package/skills/references/dashboard.md

@@ -120,7 +120,11 @@ that both read the file always agree.
 Opening a run whose `status` is `terminated` (because its process has
 exited, or because you're viewing it cross-process) fetches
 `/autoloop/<id>/chat_history`, replays the conversation into the Planner pane,
-and shows a green **Resume run** button in the topbar. Clicking it POSTs `/autoloop/<id>/resume`;
+and shows a green **Resume run** button in the topbar. The same button is shown
+for any live paused run, and it follows later SSE state: a pause adds it, and
+returning to an active status removes it. Timeout fields are included only when
+`pending_dispatch` exists; an ordinary or activity-lease pause resumes with
+an empty timeout body. Clicking it POSTs `/autoloop/<id>/resume`;
 the orchestrator re-attaches the Planner (reusing the persisted Claude
 session ID when available, so Claude's context picks up where it left
 off) and the dashboard reconnects to `/events` for live updates.

package/skills/references/multi-engine.md

@@ -28,7 +28,7 @@ SessionManager
 
 ### Claude Code (`engine: 'claude'`)
 
-Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.302**.
+Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.307**.
 
 - Persistent multi-turn conversations
 - Real-time streaming (text, tool_use, tool_result, system events)
@@ -62,7 +62,7 @@ await manager.startSession({
 
 ### OpenAI Codex (`engine: 'codex'`)
 
-Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.163.0**.
+Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.164.0**.
 
 - Non-interactive execution via `codex exec --sandbox workspace-write --skip-git-repo-check --json`
 - Real `usage` from the `turn.completed` JSON event (input, output, cached, reasoning tokens). **These are cumulative over the thread, not per turn**, so they replace the session totals rather than being added to them; subtracting consecutive values gives one turn's prompt
@@ -102,19 +102,18 @@ await manager.startSession({
 
 ### OpenAI Codex App-Server (`engine: 'codex-app'`)
 
-Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON-RPC subprocess. **Required for `/goal` long-horizon objective support** — Codex's exec subcommand has no slash-command surface.
+Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON-RPC subprocess. **Required for `/goal` long-horizon objective support** — Codex's exec subcommand has no goal surface. Tested with `codex` CLI **0.164.0**.
 
 - Long-running subprocess; one `codex app-server` per session
 - JSON-RPC 2.0 over stdio with v2 protocol method names (`initialize`, `thread/start`, `turn/start`, ...)
 - Real-time streaming via `item/agentMessage/delta` notifications
 - Cumulative token tracking from `thread/tokenUsage/updated` notifications. The same notification's `last` breakdown and `modelContextWindow` drive `contextPercent`, so it reports live occupancy against the window the server enforces rather than a running total over the model's published window
 - `appendSystemPrompt` is placed at the top of the first message of a new thread (app-server has no system-prompt flag); a resumed thread already carries it
-- Goal lifecycle observation via `thread/goal/updated` and `thread/goal/cleared` notifications
-- Goal control via the `codex_goal_*` tools (which internally send the `/goal` slash command as user text — see [tools.md](./tools.md#codex-13))
-- v2 RPC tools (Codex 0.137): `codex_interrupt` (`turn/interrupt`), `codex_steer` (`turn/steer`), `codex_fork` (`thread/fork`), `codex_rollback` (`thread/rollback`), `codex_models` (`model/list`), `codex_thread_list` (`thread/list`). A `turn/completed` with `status: 'failed'` rejects the turn and increments `toolErrors`.
-- Thread resume: starting with `resumeSessionId` loads the existing thread via `thread/resume` instead of `thread/start`.
-
-> **Feature flag.** `goals` is an experimental Codex feature. The session always passes `--enable goals`; some goal commands may still fail or be ignored by the server.
+- Goals through the typed RPCs `thread/goal/set` / `get` / `clear`: setting an objective starts the server's own turn loop, which runs until the goal is `complete`, `budgetLimited`, `blocked`, `usageLimited` or `paused`. Each change arrives as `thread/goal/updated`. The `codex_goal_*` tools wrap these; the kernel's `goal` node drives them for unattended runs ([workflow.md](./workflow.md#goal))
+- `error` notifications are read as `{ error: { message, codexErrorInfo }, willRetry }`. The session keeps the last one (`lastError`, with `codexErrorInfo` as a name such as `serverOverloaded`) and emits it as `codex:error`; an error notification never throws when nothing listens for errors
+- v2 RPC tools (Codex 0.137): `codex_interrupt` (`turn/interrupt`), `codex_steer` (`turn/steer`, including into a turn the goal loop started), `codex_fork` (`thread/fork`), `codex_rollback` (`thread/rollback`), `codex_models` (`model/list`), `codex_thread_list` (`thread/list`). A `turn/completed` with `status: 'failed'` rejects the turn and increments `toolErrors`.
+- Threads are opened and resumed with `approvalPolicy: "never"`, and a server request the session cannot handle (an approval, a request for user input) gets an error reply at once: nothing here can answer one, and an unanswered request blocks its turn. The sandbox mode is the boundary.
+- Thread resume: starting with `resumeSessionId` loads the existing thread via `thread/resume` instead of `thread/start`. The id the session manager stores and replays (model switch, restart) is the app-server's own thread id. A thread resumed with an active goal continues it on its own.
 
 ```typescript
 await manager.startSession({
@@ -123,17 +122,27 @@ await manager.startSession({
   model: 'gpt-5.5',
   cwd: '/project',
 });
-// Then either:
-//   await manager.codexGoalCommand('codex-goal-task', 'build a tic-tac-toe app');
+await manager.codexGoal('codex-goal-task', { action: 'set', objective: 'build a tic-tac-toe app' });
 // or via the codex_goal_set tool:
 //   await tool('codex_goal_set', { name: 'codex-goal-task', objective: 'build a tic-tac-toe app' });
 ```
 
+### Running an engine under a launcher
+
+`SessionConfig.launcher` is an argv prefix the engine binary runs under, for every
+engine: `launcher: ['/opt/task/sandbox.sh', 'task', '0 1']` spawns
+`/opt/task/sandbox.sh task '0 1' codex app-server …`. This is how a caller puts
+the agent inside its own sandbox (bubblewrap, a container entry point, `taskset`)
+without a custom engine. The launcher is the caller's own command, at the same
+trust level as a contract's command check, which the HTTP API also accepts: set
+it through the SessionManager API, `/session/start` or a workflow spec (the `goal`
+node's `launcher`). It is not a parameter of the `session_start` tool.
+
 ### Google Antigravity (`engine: 'agy'`)
 
 Wraps Google's **Antigravity CLI** (`agy`) — the successor to Gemini CLI (consumer
 Gemini CLI tiers stopped serving 2026-06-18). Each `send()` spawns a new process
-in print mode. Tested with `agy` **1.4.0**.
+in print mode. Tested with `agy` **1.4.4**.
 
 - One-shot execution per message (no persistent subprocess)
 - **Structured output and real usage** — `--output-format stream-json` emits an
@@ -218,12 +227,14 @@ await manager.startSession({
 ### Grok Build (`engine: 'grok'`)
 
 Wraps xAI's **Grok Build** CLI. Each `send()` spawns `grok -p <msg> --output-format json`, which
-prints a single JSON object and exits. Tested with `grok` **1.0.62**.
+prints a single JSON object and exits. Tested with `grok` **1.0.67**.
 
 - **Cost comes from the engine, not from the price table.** The result object carries
   `total_cost_usd`, and the wrapper writes it straight into the session's spend, so the run ledger
   and the `maxBudgetUsd` gate both read what xAI charged. Other engines multiply tokens by a rate in
-  `models.ts`. `grok-4.6` is still registered, for its context window and an indicative breakdown.
+  `models.ts`. `grok-4.7` (grok's default since 1.0.67) and `grok-4.6` are still registered, for
+  their context window and an indicative breakdown; with no `model` set, the session is labelled with
+  the model grok reports under `modelUsage`.
 - **Real conversation continuity**: the `sessionId` from turn 1 is replayed as `--resume <id>`.
   `--continue` is not used — it means "the most recent session for this cwd", which collides
   between concurrent sessions.
@@ -263,7 +274,7 @@ prints a single JSON object and exits. Tested with `grok` **1.0.62**.
 await manager.startSession({
   name: 'grok-task',
   engine: 'grok',
-  model: 'grok-4.6',
+  model: 'grok-4.7',
   cwd: '/project',
 });
 ```

package/skills/references/tools.md

@@ -297,38 +297,37 @@ Returns `{ ok, stdout, stderr }`.
 
 ### `codex_goal_set`
 
-Set a long-horizon objective. Sends `/goal <objective>` via the app-server. **Requires `engine: "codex-app"`.**
+Set a long-horizon objective (`thread/goal/set`). Codex then works turn after turn on its own until the goal leaves `active`. **Requires `engine: "codex-app"`.**
 
-| Parameter   | Type   | Required |
-| ----------- | ------ | -------- |
-| `name`      | string | yes      |
-| `objective` | string | yes      |
-| `timeout`   | number |          |
+| Parameter     | Type   | Required | Notes                                                            |
+| ------------- | ------ | -------- | ---------------------------------------------------------------- |
+| `name`        | string | yes      |                                                                  |
+| `objective`   | string | yes      |                                                                  |
+| `tokenBudget` | number |          | Tokens the goal may spend; it stops as `budgetLimited` past this |
 
-Returns `{ ok, text, goal }` where `goal` is `{ objective, status: "active"|"paused"|"budgetLimited"|"complete", tokensUsed, timeUsedSeconds, tokenBudget?, ... }` or `null`.
+Returns `{ ok, goal }` where `goal` is `{ objective, status, tokenBudget, tokensUsed, timeUsedSeconds, ... }`. `status` is one of `active`, `paused`, `blocked`, `usageLimited`, `budgetLimited`, `complete`.
 
 ### `codex_goal_get`
 
-Read the cached goal state. Pure read — does not send a turn.
+Ask the app-server for the goal (`thread/goal/get`). Sends no turn.
 
 | Parameter | Type   | Required |
 | --------- | ------ | -------- |
 | `name`    | string | yes      |
 
-Returns `{ ok, goal }` (`null` if no goal active).
+Returns `{ ok, goal }` (`null` if the thread has no goal).
 
 ### `codex_goal_pause` / `codex_goal_resume` / `codex_goal_clear`
 
-Send `/goal pause`, `/goal resume`, or `/goal clear` respectively. Requires `engine: "codex-app"`.
+Pause (`status: "paused"`), resume (`status: "active"`, also for a goal stopped by a usage limit) or remove (`thread/goal/clear`) the goal. Requires `engine: "codex-app"`.
 
 | Parameter | Type   | Required |
 | --------- | ------ | -------- |
 | `name`    | string | yes      |
-| `timeout` | number |          |
 
-Returns `{ ok, text, goal }`.
+Returns `{ ok, goal }` (`null` after `clear`).
 
-> **Stability note:** Codex's `goals` feature is experimental upstream. The wrapper only formats the `/goal` slash text, so upstream changes affect that text, not the protocol.
+For a goal that has to run unattended for hours, judged by checks the agent did not write, use the `goal` workflow (`workflow_start` with `template: "goal"`, or `clawo goal`) instead of these tools; see [workflow.md](./workflow.md#goal).
 
 ### Codex app-server RPCs
 
@@ -645,7 +644,11 @@ or smaller values are rejected, and there is deliberately no
 Each successful increase appends one migration row to `decisions.jsonl`; the
 original run spec, history, and prior audit bytes are not rewritten. The
 matching live awaiting-resume condition is advanced without replaying the
-timed-out logical dispatch.
+timed-out logical dispatch. A live ordinary or activity-lease pause
+(`pending_dispatch` null) resumes with no timeout fields: the call returns once
+the run is active again, the lease re-arms without moving the hard deadline,
+and Planner chat parked during the pause is then delivered once, in order. A
+no-option resume does not clear a pending send timeout.
 
 ### `autoloop_chat`
 
@@ -656,6 +659,14 @@ Send a message into the Planner conversation.
 | `run_id`  | string | yes      |
 | `text`    | string | yes      |
 
+The message is accepted only once it is stored in the run checkpoint; otherwise
+the call fails with `autoloop chat could not be persisted` (or a stopping,
+restoring or limit error) and nothing is sent. Accepted chat survives
+`autoloop_stop` and owner loss and is delivered once, in order, after a resume.
+A message that was mid-delivery when the run stopped is not resent; it is
+reported through `unconfirmed_chat` in `autoloop_status` and one notice in chat
+history.
+
 ### `autoloop_status`
 
 Get the current state and push log.

package/skills/references/workflow.md

@@ -46,7 +46,9 @@ its choice is not recorded. A run parked at a `human_gate` parks there again.
 Steers survive a restart. They are logged when they arrive and recorded as
 consumed when the node that took them finishes, so on resume every steer no
 finished node consumed is queued again — including one a node was holding when
-it died, which goes to that node's retry.
+it died, which goes to that node's retry. A `goal` node delivers steers into
+the running turn as they arrive, so one delivered before a crash is delivered
+again after the resume.
 
 **This makes node execution at-least-once, not exactly-once.** There is no
 idempotency key and no side-effect commit marker, so a node that wrote files and
@@ -136,17 +138,18 @@ is unrecoverable and reads back as "not found".
 
 ## Node kinds
 
-| Kind         | Does                                                                                      |
-| ------------ | ----------------------------------------------------------------------------------------- |
-| `agent`      | One session, one turn                                                                     |
-| `fanout`     | N agents in parallel, optional synthesis                                                  |
-| `council`    | The existing council engine, votes recorded as advisory                                   |
-| `verifier`   | Runs an acceptance contract, writes evidence — see [`verification.md`](./verification.md) |
-| `human_gate` | Parks the run until a person answers                                                      |
-| `router`     | Picks the next node from declarative conditions; a backwards route is the loop            |
-| `subflow`    | Runs another workflow as a step and adopts its verdict                                    |
+| Kind         | Does                                                                                                                                                                                                                                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent`      | One session, one turn                                                                                                                                                                                                                                               |
+| `fanout`     | N agents in parallel, optional synthesis                                                                                                                                                                                                                            |
+| `council`    | The existing council engine, votes recorded as advisory                                                                                                                                                                                                             |
+| `verifier`   | Runs an acceptance contract, writes evidence — see [`verification.md`](./verification.md)                                                                                                                                                                           |
+| `human_gate` | Parks the run until a person answers                                                                                                                                                                                                                                |
+| `router`     | Picks the next node from declarative conditions; a backwards route is the loop                                                                                                                                                                                      |
+| `subflow`    | Runs another workflow as a step and adopts its verdict                                                                                                                                                                                                              |
 | `autoloop`   | A long-lived Planner / Coder / Reviewer loop; its executor is injected. On the node's first visit (`visits === 1`) the shared fresh-start boundary applies (dirty-worktree refusal + run-local `tasks/<config.runId>/.gitignore`); resume and later visits skip it. |
-| `ultraapp_*` | UltraApp's synth and deploy stages; their executors are injected too                      |
+| `goal`       | A Codex `/goal` on one `codex-app` thread, run until the goal finishes — see [below](#goal)                                                                                                                                                                         |
+| `ultraapp_*` | UltraApp's synth and deploy stages; their executors are injected too                                                                                                                                                                                                |
 
 Every node takes `retry: { max, backoffMs }`, `timeoutMs`, and
 `onFailure: 'fail' | 'continue'`.
@@ -258,9 +261,79 @@ test suite would double the most expensive part of the run to learn nothing new.
 - **`council`** — one council node, plus the implicit verifier when a contract is
   declared.
 - **`fanout`** — one fan-out node.
+- **`goal`** — a `goal` node → verify → repair on the same thread; `task` is the
+  objective. See [below](#goal).
 
 These are ordinary specs, not privileged paths.
 
+## Goal
+
+A `goal` node runs one Codex `/goal` on one `codex-app` thread. Codex's
+app-server runs the goal itself: `thread/goal/set` starts its turn loop, which
+keeps going until the goal is `complete`, out of budget, `blocked`, or stopped
+by a usage limit. The node adds what an unattended run needs around that loop.
+
+```jsonc
+{
+  "id": "goal",
+  "kind": "goal",
+  "objective": "Reach the goal described in GOAL.md …",
+  "cwd": "/work/task/ws",
+  "model": "gpt-6.1-sol", // optional; codex's own default otherwise
+  "launcher": ["/work/goal/sandbox/sandbox.sh", "task", "0 1"], // optional argv prefix
+  "threadId": "019c…", // optional: start on this existing thread, replacing its goal
+  "tokenBudget": 50000000, // optional; the goal ends as budgetLimited past it
+  "capacityRetry": { "max": 20, "backoffMs": 60000 }, // default
+  "stallMs": 300000, // default 5 min
+  "timeoutMs": 86400000, // optional wall-clock budget; no default
+}
+```
+
+- **The objective fits Codex's limit.** Codex accepts at most 4,000 characters;
+  a longer objective fails the node before a session opens. Put a long brief in
+  a file in the working directory and name the file in the objective.
+- **The thread is checkpointed.** Node data holds `threadId`, `status`,
+  `tokensUsed`, `timeUsedSeconds`, `resumes`, `lastError`, the agent's last reply
+  (`lastMessage`, at most 4,000 characters) and the thread's spend
+  (`costUsd`), updated as the goal moves (progress at most every 10 s, status
+  changes at once). `workflow_status` and `clawo workflow show` read it while the
+  goal runs.
+- **Resume reattaches, it does not restart.** A resumed run hands the stored
+  thread id to `thread/resume`; a goal that had not finished continues where it
+  was. If the resume lands on a different thread the node fails rather than
+  starting the objective over. An app-server that exits mid-goal is reopened on
+  the same thread the same way.
+- **Stalls are resumed within a bound.** A goal that is `usageLimited` or
+  `paused`, or `active` with no turn running and either no news for `stallMs` or
+  an error the server will not retry (`serverOverloaded`, `usageLimitExceeded`,
+  `rateLimitExceeded`, a dropped connection), is set back to `active` after a
+  backoff that starts at `capacityRetry.backoffMs` and doubles to at most 15 min.
+  Every attempt counts before it is made, reopening a dead app-server included;
+  past `capacityRetry.max` the node fails.
+- **Repair on the same thread.** Revisited after a red verifier, the node clears
+  the finished goal and sets a new objective on the same thread: the failing
+  checks first (as diagnostic data, like an agent node's repair brief), then the
+  original objective. The agent keeps its context. The original objective is
+  always kept whole; when both do not fit in 4,000 characters the checks are cut
+  (the full output stays in the run's evidence). A first goal that was never set
+  left nothing on its thread, so its revisit starts a new one.
+- **Steering is live.** `workflow_steer` text goes into the running turn through
+  `turn/steer`; with no turn running it waits for the next one. Text queued
+  before the goal is set is put in front of the objective.
+- **No approval prompts.** Nothing can answer one, so the thread runs with
+  `approvalPolicy: "never"` and any request the server sends anyway (approval,
+  user input) is answered with an error at once; the sandbox mode is the
+  boundary.
+- **Ends.** `complete` succeeds. `budgetLimited` and `blocked` fail with the
+  reason. Cancel interrupts the running turn and pauses the goal. Like
+  `autoloop`, the node has no default timeout.
+
+The `goal` template wraps this in `goal → verify → repair-gate`. The goal node
+continues on failure, so a goal that ran out of budget is still judged. The
+verifier's node timeout is sized from the contract (each check's timeout, at
+least 30 min), so a judge that takes hours is not cut off at the 30-minute node
+default. `maxRepairs` defaults to 1.
+
 ## The verifier is a terminal barrier
 
 A passing verdict only stands while it still describes the tree.
@@ -299,7 +372,7 @@ success.
 
 | Action        | Tool               | HTTP                              | CLI                                    |
 | ------------- | ------------------ | --------------------------------- | -------------------------------------- |
-| Start         | `workflow_start`   | `POST /workflow/new`              | —                                      |
+| Start         | `workflow_start`   | `POST /workflow/new`              | `clawo solve` / `fanout` / `goal`      |
 | Poll          | `workflow_status`  | `GET /workflow/<id>/state`        | `clawo workflow show <id>`             |
 | List          | `workflow_list`    | `GET /workflow/list`              | `clawo workflow list`                  |
 | Resume        | `workflow_resume`  | `POST /workflow/<id>/resume`      | `clawo workflow resume <id>`           |
@@ -309,7 +382,8 @@ success.
 | Evidence      | —                  | `GET /workflow/<id>/evidence`     | `clawo verify <id>`                    |
 | Live events   | —                  | `GET /workflow/<id>/events` (SSE) | —                                      |
 
-Steer text is **prepended** to the next agent node's prompt: an instruction that
+In a running `goal` node, steer text goes into the current turn (`turn/steer`).
+Otherwise, steer text is **prepended** to the next agent node's prompt: an instruction that
 arrives while the previous node was running is a correction, and corrections
 belong before the task.