@enderfga/claw-orchestrator 7.16.2 → 7.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/README.md +13 -8
  2. package/dist/src/index.js +109 -1
  3. package/dist/src/index.js.map +1 -1
  4. package/dist/src/kernel/engine.js +14 -0
  5. package/dist/src/kernel/engine.js.map +1 -1
  6. package/dist/src/kernel/nodes/agent.js +1 -0
  7. package/dist/src/kernel/nodes/agent.js.map +1 -1
  8. package/dist/src/kernel/nodes/goal.js +19 -6
  9. package/dist/src/kernel/nodes/goal.js.map +1 -1
  10. package/dist/src/kernel/types.d.ts +7 -0
  11. package/dist/src/kernel/types.js.map +1 -1
  12. package/dist/src/mcp-annotations.js +1 -0
  13. package/dist/src/mcp-annotations.js.map +1 -1
  14. package/dist/src/persistent-codex-app-session.d.ts +2 -0
  15. package/dist/src/persistent-codex-app-session.js +19 -0
  16. package/dist/src/persistent-codex-app-session.js.map +1 -1
  17. package/openclaw.plugin.json +1 -0
  18. package/package.json +1 -1
  19. package/skills/SKILL.md +4 -4
  20. package/skills/references/autoloop.md +6 -5
  21. package/skills/references/getting-started.md +1 -1
  22. package/skills/references/mcp.md +4 -4
  23. package/skills/references/tools.md +61 -35
  24. package/skills/references/workflow.md +17 -12
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@enderfga/claw-orchestrator",
3
- "version": "7.16.2",
3
+ "version": "7.17.0",
4
4
  "description": "Claw Orchestrator — run Claude Code, Codex, Antigravity, Grok Build, OpenCode, any ACP agent and custom coding CLIs as one unified runtime. Drop into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose or any Model Context Protocol (MCP) host, serve editors as an ACP agent, install as an OpenClaw plugin, or run standalone. Persistent sessions, durable resumable workflows, acceptance checks the runtime runs itself, fan-out, multi-agent council, Codex /goal runs, autoloop, ultraplan, ultrareview, and a per-turn cost ledger with spend caps.",
5
5
  "type": "module",
6
6
  "main": "./dist/src/index.js",
package/skills/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: claw-orchestrator
3
- description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, OpenCode, any Agent Client Protocol agent (Kimi Code, dsh) and custom CLIs. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running durable, resumable workflows (solve / fanout / council / Codex goal) and having the runtime verify the result against an acceptance contract, fanning one task out to several engines, 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, tracking per-turn cost and spend caps across engines, 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", "acp engine", "acp agent", "kimi code", "kimi acp", "dsh acp", "any acp agent", "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".
3
+ description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, OpenCode, any Agent Client Protocol agent (Kimi Code, dsh) and custom CLIs. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running durable, resumable workflows (solve / fanout / council / Codex goal) and having the runtime verify the result against an acceptance contract, fanning one task out to several engines, 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, tracking per-turn cost and spend caps across engines, exposing the orchestrator's 79 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", "acp engine", "acp agent", "kimi code", "kimi acp", "dsh acp", "any acp agent", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "autoloop_resume", "resume autoloop", "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".
4
4
  metadata:
5
5
  {
6
6
  'openclaw':
@@ -36,7 +36,7 @@ metadata:
36
36
 
37
37
  # Claw Orchestrator Skill
38
38
 
39
- Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Antigravity, Grok Build, OpenCode, any Agent Client Protocol agent, and custom CLIs into headless agentic engines with 78 tools.
39
+ Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Antigravity, Grok Build, OpenCode, any Agent Client Protocol agent, and custom CLIs into headless agentic engines with 79 tools.
40
40
 
41
41
  ## Engine Quick Reference
42
42
 
@@ -183,7 +183,7 @@ autoloop_status({ run_id: 'fix-parser' });
183
183
  autoloop_stop({ run_id: 'fix-parser', reason: 'done' });
184
184
  ```
185
185
 
186
- Claude roles default to Planner `opus` and Coder/Reviewer `sonnet`. A non-Claude role with no model uses that engine's own default. Custom engine configs come from a local caller at start or resume — or, on an HTTP resume, by reference (`plannerCustomEngineRef` etc., resolved from a `CLAWO_CUSTOM_ENGINE_<NAME>` variable on the host) — never from Planner output. The Reviewer runs in a restaged sandbox and returns advance/hold/rollback verdicts; push policy and SSE keep long runs observable.
186
+ Claude roles default to Planner `opus` and Coder/Reviewer `sonnet`. A non-Claude role with no model uses that engine's own default. Custom engine configs come from a local caller at start or resume — via `autoloop_resume` / HTTP resume references (`plannerCustomEngineRef` etc., resolved from a `CLAWO_CUSTOM_ENGINE_<NAME>` variable on the host) — never from Planner output. The Reviewer runs in a restaged sandbox and returns advance/hold/rollback verdicts; push policy and SSE keep long runs observable.
187
187
 
188
188
  For the full control protocol, registry/resume behavior, and ledger layout, see [references/autoloop.md](references/autoloop.md).
189
189
 
@@ -200,7 +200,7 @@ For the full control protocol, registry/resume behavior, and ledger layout, see
200
200
  | Fan-out | `fanout_start`, `fanout_status`, `fanout_abort` |
201
201
  | Council | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject` |
202
202
  | Ultra | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status` |
203
- | Autoloop | `autoloop_start`, `autoloop_chat`, `autoloop_status`, `autoloop_list`, `autoloop_stop`, `autoloop_reset_agent` |
203
+ | Autoloop | `autoloop_start`, `autoloop_chat`, `autoloop_status`, `autoloop_list`, `autoloop_resume`, `autoloop_stop`, `autoloop_reset_agent` |
204
204
  | Workflow & verify | `workflow_start`, `workflow_status`, `workflow_list`, `workflow_resume`, `workflow_cancel`, `workflow_steer`, `workflow_approve`, `verify_run` |
205
205
  | Ultraapp | `ultraapp_new`, `ultraapp_answer`, `ultraapp_add_file`, `ultraapp_spec_edit`, `ultraapp_build_start`, `ultraapp_build_cancel`, `ultraapp_status`, `ultraapp_get`, `ultraapp_list`, `ultraapp_feedback`, `ultraapp_promote_version`, `ultraapp_start_container`, `ultraapp_stop_container`, `ultraapp_delete` |
206
206
 
package/skills/references/autoloop.md CHANGED
@@ -176,7 +176,7 @@ pending dispatch identity when available. It does not rewrite the original
176
176
  stored spec, chat or iteration evidence, or any earlier audit bytes.
177
177
 
178
178
  A live run paused by `pause_loop` or an expired activity lease, with
179
- `pending_dispatch` null, continues on `autoloopResume()` / `POST /autoloop/<id>/resume`
179
+ `pending_dispatch` null, continues on `autoloop_resume` / `autoloopResume()` / `POST /autoloop/<id>/resume`
180
180
  with no timeout fields. That resume clears the lease expiry, sets status back
181
181
  to `planning` (or `running` once subagents have been spawned), re-arms the
182
182
  activity lease from the resume, and leaves the original hard deadline where it
@@ -236,6 +236,7 @@ the old name is already absent, reset may continue and create the replacement.
236
236
  | `autoloop_chat` | `run_id`, `text` | Send a chat message to the Planner; returns the Planner's reply. |
237
237
  | `autoloop_status` | `run_id` | Current state (status, iter, push count, subagents_spawned). |
238
238
  | `autoloop_list` | — | All autoloop runs in the run store, live or not. |
239
+ | `autoloop_resume` | `run_id`, `send_timeout_ms?`, `pending_dispatch_id?`, `plannerCustomEngineRef?`, `coderCustomEngineRef?`, `reviewerCustomEngineRef?` | Resume via `SessionManager.autoloopResume` once; same semantics as `POST /autoloop/<id>/resume`. |
239
240
  | `autoloop_stop` | `run_id`, `reason?` | Terminate; stops Planner / Coder / Reviewer. |
240
241
  | `autoloop_reset_agent` | `run_id`, `agent` ('planner' / 'coder' / 'reviewer'), `force?`, `eager_restart?` | Reset one subagent. Planner reset requires `force: true`. |
241
242
 
@@ -272,8 +273,8 @@ removes partial files, and suppresses both spawn and directives.
272
273
  ### Custom engines and resume
273
274
 
274
275
  Custom engine configs are accepted only by `autoloop_start` (and, on resume, by
275
- `SessionManager.autoloopResume()` or by reference in the HTTP resume body), never
276
- through Planner output. This keeps config fields such as `env` and static CLI
276
+ `SessionManager.autoloopResume()`, `autoloop_resume` refs, or by reference in the
277
+ HTTP resume body), never through Planner output. This keeps config fields such as `env` and static CLI
277
278
  arguments out of the Planner transcript and `decisions.jsonl`. The run record
278
279
  stores only each role's engine, model, and effort, including the effective Coder/Reviewer
279
280
  selection after a successful spawn. When resuming a run that uses `custom`,
@@ -583,8 +584,8 @@ lives. The run record holds the last state the loop published and the engines
583
584
  `spawn_subagents` chose, so `autoloop_status` and `GET /autoloop/<id>/state`
584
585
  show a run's real state after it stops or the process restarts.
585
586
 
586
- Resume is explicit. `POST /autoloop/<id>/resume` (or
587
- `SessionManager.autoloopResume()`) restarts a run from its stored spec.
587
+ Resume is explicit. `autoloop_resume`, `POST /autoloop/<id>/resume`, or
588
+ `SessionManager.autoloopResume()` restarts a run from its stored spec.
588
589
  Custom-engine configs are the one thing the spec does not carry (they can hold
589
590
  secrets), so a resume must be given them again. Cancelling a run stops all three
590
591
  agents, the same as `autoloop_stop`.
package/skills/references/getting-started.md CHANGED
@@ -165,7 +165,7 @@ In plugin mode, in `~/.openclaw/openclaw.json`:
165
165
  - [Verification](./verification.md) — acceptance contracts the runtime checks itself
166
166
  - [Observability](./observability.md) — the run ledger and spend caps
167
167
  - [Dashboard](./dashboard.md) — the browser UI served at `/dashboard`
168
- - [Tools Reference](./tools.md) — complete tool API reference (78 tools)
168
+ - [Tools Reference](./tools.md) — complete tool API reference (79 tools)
169
169
  - [CLI Reference](./cli.md) — command-line interface
170
170
  - [MCP Server](./mcp.md) — expose the tools to any MCP host
171
171
  - [ACP Agent](./acp.md) — run the orchestrator as an Agent Client Protocol agent
package/skills/references/mcp.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # MCP integration
2
2
 
3
- Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 78 tools.
3
+ Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 79 tools.
4
4
 
5
5
  This document covers:
6
6
 
@@ -37,7 +37,7 @@ Tools fall into a few groups:
37
37
  | Status / introspection | `sessions_overview`, `coding_session_status`, `coding_agents_list` |
38
38
  | Multi-agent council | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject` |
39
39
  | Ultraplan / ultrareview | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status` |
40
- | Autoloop | `autoloop_start`, `autoloop_chat`, `autoloop_status`, `autoloop_list`, `autoloop_reset_agent`, `autoloop_stop` |
40
+ | Autoloop | `autoloop_start`, `autoloop_chat`, `autoloop_status`, `autoloop_list`, `autoloop_reset_agent`, `autoloop_stop`, `autoloop_resume` |
41
41
  | Codex specifics | `codex_resume`, `codex_review`, `codex_goal_set`, `codex_goal_get`, `codex_goal_pause`, `codex_goal_resume`, `codex_goal_clear` |
42
42
  | Codex app-server | `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models`, `codex_thread_list` |
43
43
  | Claude specifics | `claude_goal_set`, `claude_goal_status`, `claude_goal_clear`, `claude_agents_list`, `plugin_details` |
@@ -256,7 +256,7 @@ The engines themselves (`claude`, `codex`, `agy`, `grok`, `opencode`, and any AC
256
256
 
257
257
  ## Tool filtering
258
258
 
259
- 78 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
259
+ 79 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
260
260
 
261
261
  ```bash
262
262
  CLAWO_MCP_TOOLS="session_start,session_send,session_stop,council_start,council_status" clawo-mcp
@@ -286,7 +286,7 @@ For "let the model commission an ultrareview before merging":
286
286
  | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
287
287
  | `readOnlyHint` + `idempotentHint` | `session_list`, `sessions_overview`, `coding_session_status`, `session_grep`, `session_inbox`, `coding_agents_list`, `team_list`, `council_status`, `council_review`, `ultraplan_status`, `ultrareview_status`, `autoloop_status`, `autoloop_list`, `codex_goal_get`, `claude_goal_status`, `claude_agents_list`, `plugin_details`, `codex_models`, `codex_thread_list`, `fanout_status`, `workflow_status`, `workflow_list`, `ultraapp_list`, `ultraapp_get`, `ultraapp_status` |
288
288
  | `destructiveHint` | `session_stop`, `council_abort`, `council_accept`, `council_reject`, `autoloop_stop`, `project_purge`, `codex_interrupt`, `codex_rollback`, `fanout_abort`, `workflow_cancel`, `ultraapp_build_cancel`, `ultraapp_promote_version`, `ultraapp_stop_container`, `ultraapp_delete` |
289
- | `openWorldHint` | `session_start`, `session_send`, `session_handoff`, `team_send`, `session_send_to`, `session_deliver_inbox`, `council_start`, `council_inject`, `ultraplan_start`, `ultrareview_start`, `autoloop_start`, `autoloop_chat`, `codex_resume`, `codex_review`, `codex_goal_set`, `codex_goal_resume`, `session_compact`, `claude_goal_set`, `codex_steer`, `fanout_start`, `workflow_start`, `workflow_resume`, `workflow_approve`, `verify_run`, `ultraapp_new`, `ultraapp_answer`, `ultraapp_add_file`, `ultraapp_spec_edit`, `ultraapp_build_start`, `ultraapp_feedback` |
289
+ | `openWorldHint` | `session_start`, `session_send`, `session_handoff`, `team_send`, `session_send_to`, `session_deliver_inbox`, `council_start`, `council_inject`, `ultraplan_start`, `ultrareview_start`, `autoloop_start`, `autoloop_chat`, `autoloop_resume`, `codex_resume`, `codex_review`, `codex_goal_set`, `codex_goal_resume`, `session_compact`, `claude_goal_set`, `codex_steer`, `fanout_start`, `workflow_start`, `workflow_resume`, `workflow_approve`, `verify_run`, `ultraapp_new`, `ultraapp_answer`, `ultraapp_add_file`, `ultraapp_spec_edit`, `ultraapp_build_start`, `ultraapp_feedback` |
290
290
  | none | `autoloop_reset_agent`, `codex_goal_pause`, `codex_goal_clear`, `session_update_tools`, `session_switch_model`, `claude_goal_clear`, `codex_fork`, `workflow_steer`, `ultraapp_start_container` |
291
291
 
292
292
  Every registered tool has an entry. A hint that is not set takes the MCP default — not read-only, destructive, open-world — so the tools in the last row are advertised at the defaults, and so is each unset hint in the other rows.
package/skills/references/tools.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Tools Reference
2
2
 
3
- All 78 tools are registered as OpenClaw plugin tools and exposed over MCP by `clawo-mcp` (see [mcp.md](./mcp.md)). The embedded HTTP server covers a subset of them.
3
+ All 79 tools are registered as OpenClaw plugin tools and exposed over MCP by `clawo-mcp` (see [mcp.md](./mcp.md)). The embedded HTTP server covers a subset of them.
4
4
 
5
5
  ## Session Lifecycle (6)
6
6
 
@@ -71,14 +71,14 @@ else the value applies.
71
71
 
72
72
  Send a message and get the response.
73
73
 
74
- | Parameter | Type | Required | Description |
75
- | --------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76
- | `name` | string | yes | Session name |
77
- | `message` | string | yes | Message to send |
74
+ | Parameter | Type | Required | Description |
75
+ | --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
76
+ | `name` | string | yes | Session name |
77
+ | `message` | string | yes | Message to send |
78
78
  | `effort` | string | | Effort for this message: `low` … `ultra` (no `auto`). Antigravity, Grok, OpenCode and `codex-app` pass it to the engine for this turn; on Claude, `high` and above prefix the message with `ultrathink` (a persistent custom engine does the same for `high` and `max`). Other engines ignore it |
79
- | `plan` | boolean | | Ask for a plan only. Claude and persistent custom engines prefix the message with a plan-only instruction; the permission mode is unchanged, and other engines ignore it. To enforce read-only, start the session with `sandboxMode: 'read-only'` |
80
- | `timeout` | number | | Timeout in ms (default 300000) |
81
- | `stream` | boolean | | Collect the text chunks into `chunks[]` on the result (returned with the final result, not streamed to the caller) |
79
+ | `plan` | boolean | | Ask for a plan only. Claude and persistent custom engines prefix the message with a plan-only instruction; the permission mode is unchanged, and other engines ignore it. To enforce read-only, start the session with `sandboxMode: 'read-only'` |
80
+ | `timeout` | number | | Timeout in ms (default 300000) |
81
+ | `stream` | boolean | | Collect the text chunks into `chunks[]` on the result (returned with the final result, not streamed to the caller) |
82
82
 
83
83
  Returns `{ ok, output, sessionId, error?, usage, permissionDenials?, images?, chunks? }`. `usage` is
84
84
  `{ tokensIn, tokensOut, costUsd }` for this turn alone — what it added to the session's running totals, which
@@ -370,17 +370,17 @@ Run one task across N engine/model agents **in parallel** and collect their answ
370
370
 
371
371
  ### `fanout_start`
372
372
 
373
- | Parameter | Type | Required | Description |
374
- | ------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
375
- | `task` | string | yes | Shared task sent to every agent, optionally after its `persona`. |
376
- | `projectDir` | string | yes | Working directory all agents run in. |
373
+ | Parameter | Type | Required | Description |
374
+ | ------------------------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
375
+ | `task` | string | yes | Shared task sent to every agent, optionally after its `persona`. |
376
+ | `projectDir` | string | yes | Working directory all agents run in. |
377
377
  | `agents` | array | yes | Up to 16 specs: `{ name, engine?, model?, effort?, prompt?, persona?, baseUrl?, permissionMode?, sandboxMode?, customEngine?, acpAgent? }`. Names must be unique (each forms a session name); `permissionMode` defaults to `bypassPermissions`. |
378
- | `synthesize` | boolean | | Run a final synthesis pass over the successful results (needs ≥2). |
379
- | `synthesisModel` / `synthesisEngine` | string | | Model/engine for the synthesis pass (default engine `claude`). |
380
- | `synthesisAcpAgent` | string | | With `synthesisEngine: 'acp'`: the ACP agent preset the synthesis pass starts. |
381
- | `agentTimeoutMs` | number | | Per-agent timeout (default 600000). |
382
- | `maxTurnsPerAgent` | number | | Max agent loop turns (default 30). |
383
- | `maxBudgetUsd` | number | | Per-agent spend cap. |
378
+ | `synthesize` | boolean | | Run a final synthesis pass over the successful results (needs ≥2). |
379
+ | `synthesisModel` / `synthesisEngine` | string | | Model/engine for the synthesis pass (default engine `claude`). |
380
+ | `synthesisAcpAgent` | string | | With `synthesisEngine: 'acp'`: the ACP agent preset the synthesis pass starts. |
381
+ | `agentTimeoutMs` | number | | Per-agent timeout (default 600000). |
382
+ | `maxTurnsPerAgent` | number | | Max agent loop turns (default 30). |
383
+ | `maxBudgetUsd` | number | | Per-agent spend cap. |
384
384
 
385
385
  Runs in the background; returns `{ ok, id, status, ... }`. Poll with `fanout_status`.
386
386
  Each agent's optional `effort` accepts `low`, `medium`, `high`, `xhigh`, `max`,
@@ -611,7 +611,7 @@ Get status and findings when completed.
611
611
 
612
612
  ---
613
613
 
614
- ## Autoloop (6)
614
+ ## Autoloop (7)
615
615
 
616
616
  Three-agent autonomous iteration loop (Planner / Coder / Reviewer) over a git workspace. See [`autoloop.md`](./autoloop.md) for the operator reference (push policy, ledger layout, smoke test).
617
617
 
@@ -650,13 +650,13 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
650
650
  > permission to choose what binary runs. Built-in engines stay fully selectable
651
651
  > over HTTP.
652
652
  >
653
- > **Resuming by reference.** A remote resume names the credential instead of
654
- > carrying it — `plannerCustomEngineRef` and friends on `POST /autoloop/<id>/resume`,
655
- > `agentCustomEngineRefs` on `workflow_resume` — and the orchestrator resolves the
656
- > name against its own `CLAWO_CUSTOM_ENGINE_<NAME>` environment.
657
- > `GET /autoloop/<id>/resume-requirements` lists which roles need one. The name is
658
- > not sensitive, the value never leaves the host, and an unknown name fails rather
659
- > than starting without credentials.
653
+ > **Resuming by reference.** A remote or MCP resume names the credential instead of
654
+ > carrying it — `plannerCustomEngineRef` and friends on `autoloop_resume` and
655
+ > `POST /autoloop/<id>/resume`, `agentCustomEngineRefs` on `workflow_resume` — and
656
+ > the orchestrator resolves the name against its own `CLAWO_CUSTOM_ENGINE_<NAME>`
657
+ > environment. `GET /autoloop/<id>/resume-requirements` lists which roles need one.
658
+ > The name is not sensitive, the value never leaves the host, and an unknown name
659
+ > fails rather than starting without credentials.
660
660
 
661
661
  Custom configs are not persisted or accepted from Planner output. See [`multi-engine.md`](./multi-engine.md) for their shape.
662
662
 
@@ -674,20 +674,46 @@ agent progress, never by timer checks or runner bookkeeping.
674
674
  `autoloop_hard_timeout_ms` is anchored to run start and never renews; it wins
675
675
  when it coincides with lease expiry.
676
676
 
677
- Recovery is exposed by `POST /autoloop/<id>/resume`, not by an MCP resume tool.
678
- Its timeout body is limited to `send_timeout_ms` plus
677
+ Recovery is exposed by `autoloop_resume` and by `POST /autoloop/<id>/resume`.
678
+ Both forward caller options once to `SessionManager.autoloopResume`; omission
679
+ stays omission. The timeout body is limited to `send_timeout_ms` plus
679
680
  `pending_dispatch_id`. The send timeout must be finite, in range, and strictly
680
681
  larger than the run's latest effective value (600000 for runs that predate this setting). Equal
681
682
  or smaller values are rejected, and there is deliberately no
682
683
  `allow_decrease`. Lease and hard-cap overrides are not accepted on resume.
683
684
  Each successful increase appends one migration row to `decisions.jsonl`; the
684
- original run spec, history, and prior audit bytes are not rewritten. The
685
- matching live awaiting-resume condition is advanced without replaying the
686
- timed-out logical dispatch. A live ordinary or activity-lease pause
687
- (`pending_dispatch` null) resumes with no timeout fields: the call returns once
688
- the run is active again, the lease re-arms without moving the hard deadline,
689
- and Planner chat parked during the pause is then delivered once, in order. A
690
- no-option resume does not clear a pending send timeout.
685
+ original run spec, history, and prior audit bytes are not rewritten. Live
686
+ semantics: a live ordinary or activity-lease pause (`pending_dispatch` null)
687
+ resumes with no timeout fields (active again, lease re-armed, hard deadline
688
+ unchanged, parked Planner chat delivered once); a live send-timeout pending
689
+ pause is a no-op when timeout fields are omitted (pending is not cleared), and
690
+ advancing it needs the matching live awaiting-resume increase plus
691
+ `pending_dispatch_id` without replaying the timed-out logical dispatch. Cold
692
+ semantics: omission still follows manager reconstruction even when a pending
693
+ dispatch was stored; `pending_dispatch_id` is required only when an increase
694
+ and pending coexist; a cold timeout-only increase without pending remains
695
+ supported.
696
+
697
+ ### `autoloop_resume`
698
+
699
+ Resume a v2 autoloop run through the same manager path as the HTTP resume route.
700
+ Returns `{ ok, state }` (normalized by the plugin result wrapper). A paused or
701
+ terminated state is not completed project work. Live pending omission is a
702
+ no-op; cold omission follows reconstruction; pending ID is conditional on
703
+ increase+pending; cold timeout-only increase without pending is supported.
704
+
705
+ | Parameter | Type | Required | Description |
706
+ | ------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
707
+ | `run_id` | string | yes | Run id from `autoloop_start` (store grammar: 1–128 ASCII; first letter/digit/underscore) |
708
+ | `send_timeout_ms` | number | | Optional strict increase (schema range 5000–7200000; no default) |
709
+ | `pending_dispatch_id` | string | | Exact pending id when increasing while a pending dispatch exists (1–128 ASCII letters/digits/`_`/`.`/`:`/`-`) |
710
+ | `plannerCustomEngineRef` | string | | Host secret name for Planner custom engine (`CLAWO_CUSTOM_ENGINE_<REF>`; same 1–128 ASCII grammar) |
711
+ | `coderCustomEngineRef` | string | | Host secret name for Coder custom engine (same grammar) |
712
+ | `reviewerCustomEngineRef` | string | | Host secret name for Reviewer custom engine (same grammar) |
713
+
714
+ Invalid `run_id` / pending / ref shapes fail at the facade with fixed field errors
715
+ before any secret resolve or manager call. Valid-input manager and resolver errors
716
+ propagate unchanged (no blanket catch).
691
717
 
692
718
  ### `autoloop_chat`
693
719
 
package/skills/references/workflow.md CHANGED
@@ -190,18 +190,18 @@ Every node has an `id` and a `kind`, plus these optional fields:
190
190
 
191
191
  The kind-specific fields:
192
192
 
193
- | Kind | Fields |
194
- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195
- | `agent` | `prompt` (required); `engine`, `model`, `effort`, `acpAgent` (a bundled ACP preset id, for `engine: "acp"`); `cwd` (default: the run's); `sessionName`, to keep one conversation across visits and nodes (each turn's process stops, and the next start under the name resumes the conversation; the name outlives the run, so make it unique to the run); `permissionMode` (default `bypassPermissions`); `appendSystemPrompt`, standing instructions for the session |
196
- | `fanout` | `prompt` (required, the shared task) and `agents` (required); `synthesize`, `synthesisEngine` (default `claude`), `synthesisModel`, `synthesisAcpAgent`, `synthesisPermissionMode` (default `bypassPermissions`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `cwd`; `agentTimeoutMs` |
197
- | `council` | `task` (required) and `agents` (required); `projectDir` (default: the run's cwd); `maxRounds` (default 15, as for `council_start`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `defaultPermissionMode`; `agentTimeoutMs` |
198
- | `verifier` | `contract` (required): an inline contract, or `"run"` for the run-level one; `cwd` (default: the run's) |
199
- | `human_gate` | `prompt` (required) |
200
- | `router` | `routes` (required): `[{ "when": <condition>, "to": <node id> }]`, first match wins; `default`, taken when nothing matches (omitted: fall through to the next node) |
201
- | `subflow` | `workflow` (required): an inline `WorkflowSpec`, or the id of an existing run, whose stored spec runs again as a new child run. Template names do not resolve here |
202
- | `goal` | `objective` (required); `engine`, `cwd`, `model`, `effort`, `sandboxMode`, `launcher`, `threadId`, `tokenBudget`, `capacityRetry`, `stallMs` — see [Goal](#goal) |
203
- | `autoloop` | `workspace` and `config` (the `autoloop_start` options). Started by `autoloop_start` |
204
- | `ultraapp_synth`, `ultraapp_deploy` | `appRunId`, `runDir`, `slug`; the deploy stage adds `version` and `codebasePath`. Started by UltraApp builds |
193
+ | Kind | Fields |
194
+ | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195
+ | `agent` | `prompt` (required); `engine`, `model`, `effort`, `acpAgent` (a bundled ACP preset id, for `engine: "acp"`); `cwd` (default: the run's); `sessionName`, to keep one conversation across visits and nodes (each turn's process stops, and the next start under the name resumes the conversation; the name outlives the run, so make it unique to the run); `permissionMode` (default `bypassPermissions`); `appendSystemPrompt`, standing instructions for the session; `disallowedTools`, tools the session may not use (engines `claude` and `grok`; refused at start on the others) |
196
+ | `fanout` | `prompt` (required, the shared task) and `agents` (required); `synthesize`, `synthesisEngine` (default `claude`), `synthesisModel`, `synthesisAcpAgent`, `synthesisPermissionMode` (default `bypassPermissions`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `cwd`; `agentTimeoutMs` |
197
+ | `council` | `task` (required) and `agents` (required); `projectDir` (default: the run's cwd); `maxRounds` (default 15, as for `council_start`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `defaultPermissionMode`; `agentTimeoutMs` |
198
+ | `verifier` | `contract` (required): an inline contract, or `"run"` for the run-level one; `cwd` (default: the run's) |
199
+ | `human_gate` | `prompt` (required) |
200
+ | `router` | `routes` (required): `[{ "when": <condition>, "to": <node id> }]`, first match wins; `default`, taken when nothing matches (omitted: fall through to the next node) |
201
+ | `subflow` | `workflow` (required): an inline `WorkflowSpec`, or the id of an existing run, whose stored spec runs again as a new child run. Template names do not resolve here |
202
+ | `goal` | `objective` (required); `engine`, `cwd`, `model`, `effort`, `sandboxMode`, `launcher`, `threadId`, `tokenBudget`, `capacityRetry`, `stallMs`, `disallowedTools` (`claude` only; refused at start on `codex`) — see [Goal](#goal) |
203
+ | `autoloop` | `workspace` and `config` (the `autoloop_start` options). Started by `autoloop_start` |
204
+ | `ultraapp_synth`, `ultraapp_deploy` | `appRunId`, `runDir`, `slug`; the deploy stage adds `version` and `codebasePath`. Started by UltraApp builds |
205
205
 
206
206
  An entry in a fan-out's or council's `agents` takes `name` (required), `engine`,
207
207
  `model`, `effort`, `acpAgent`, `persona`, `prompt`, `permissionMode` and `baseUrl`;
@@ -401,6 +401,11 @@ what an unattended run needs around that loop.
401
401
  to at most 15 min. Every attempt counts before it is made, reopening a dead
402
402
  app-server included; past `capacityRetry.max` the node fails. The count is part
403
403
  of the checkpoint, so it carries across process restarts and repair visits.
404
+ Codex also marks a goal `blocked` when its turn fails on one of those capacity
405
+ errors (a model at capacity ends the turn with `serverOverloaded`); that goal is
406
+ resumed the same way, on the same thread. A goal `blocked` for any other reason
407
+ ends the node. The error is read from the turn itself as well as from `error`
408
+ notifications, so `lastError` names the cause either way.
404
409
  - **Repair on the same thread.** Revisited after a red verifier — a red verdict
405
410
  other than the one in force when its current objective was set — the node clears
406
411
  the finished goal and sets a new objective on the same thread, carrying the