@enderfga/claw-orchestrator 3.7.1 → 4.0.3

package/dist/src/ultraapp/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../../src/ultraapp/versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAiBlC,MAAM,UAAU,YAAY,CAAC,WAAmB;IAC9C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAGvF,CAAC;YACF,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,2BAA2B;QAC7B,CAAC;IACH,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAClF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAe;IACzC,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,IAA8C;IACjG,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACzC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,EAAE,CAAC,aAAa,CACd,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAC/B,IAAI,CAAC,SAAS,CACZ;QACE,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACjC,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAYD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAc;IAC9C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,IAAI,CAAC,SAAS,qBAAqB,EAAE,CAAC;IACrF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC7D,iBAAiB;QACnB,CAAC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAC7D,IAAI,CAAC,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/openclaw.plugin.json

@@ -98,7 +98,21 @@
       "ultraplan_start",
       "ultraplan_status",
       "ultrareview_start",
-      "ultrareview_status"
+      "ultrareview_status",
+      "ultraapp_list",
+      "ultraapp_get",
+      "ultraapp_status",
+      "ultraapp_new",
+      "ultraapp_answer",
+      "ultraapp_add_file",
+      "ultraapp_spec_edit",
+      "ultraapp_build_start",
+      "ultraapp_build_cancel",
+      "ultraapp_feedback",
+      "ultraapp_promote_version",
+      "ultraapp_start_container",
+      "ultraapp_stop_container",
+      "ultraapp_delete"
     ]
   },
   "skills": ["skills/SKILL.md"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enderfga/claw-orchestrator",
-  "version": "3.7.1",
+  "version": "4.0.3",
   "description": "Claw Orchestrator — run Claude Code, Codex, Gemini, Cursor Agent, OpenCode 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, install as an OpenClaw plugin, or run standalone. Persistent sessions, multi-agent council, ultraplan, ultrareview, autoloop, tool orchestration.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -92,6 +92,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0",
+    "diff": "^9.0.0",
     "re2": "^1.24.0"
   },
   "peerDependencies": {
@@ -99,6 +100,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.15.0",
+    "@types/diff": "^7.0.2",
     "@types/node": "^22.10.0",
     "@vitest/coverage-v8": "^3.1.0",
     "eslint": "^9.15.0",

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, 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, switching models/tools at runtime, or exposing the orchestrator's 41 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol".
+description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, 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, or exposing the orchestrator's 55 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. 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", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol".
 metadata:
   {
     "openclaw":
@@ -43,7 +43,7 @@ metadata:
 
 # Claw Orchestrator Skill
 
-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, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 35 tools.
+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, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 55 tools.
 
 ## Engine Quick Reference
 

package/skills/references/autoloop.md

@@ -5,7 +5,7 @@ the **Planner** to design a plan; on your approval, the Planner spawns the
 **Coder** + **Reviewer** subloop, monitors it, and pushes you (wechat →
 whatsapp → email fallback chain) only when something needs your attention.
 
-Design rationale: `tasks/autoloop.md`. This page is the operator reference.
+This page is the operator reference.
 
 ## When to use
 
@@ -100,8 +100,8 @@ never see the JSON — only the Planner's narrative.
 | `resume_loop` | — | Resume after pause. |
 | `terminate` | `reason` | End run. |
 | `update_push_policy` | partial PushPolicy | Mutate notification rules (e.g. when you say "tell me every iter"). |
-| `write_plan_committed` | `message?` | git-commit current plan.md. |
-| `write_goal_committed` | `message?` | git-commit current goal.json. |
+| `write_plan` | `content` (full plan.md body), `commit_message?` | Write `plan.md` to the workspace and git-commit. The **only** way the Planner can author plan.md — Write/Edit are stripped from the Planner session as a hard role boundary. Re-running replaces the whole file. |
+| `write_goal` | `content` (full goal.json body), `commit_message?` | Same, for `goal.json`. Content is JSON-validated before write; malformed content errors back to the Planner. |
 
 ## Default push policy
 
@@ -211,9 +211,12 @@ Every JSON artifact in the ledger carries a `schema_version` field (currently
 | Endpoint | Returns |
 |---|---|
 | `GET /autoloop/list` | `{ ok, runs: AutoloopState[] }` |
+| `POST /autoloop/new` | `{ ok, run_id, planner_session }` — body `{ workspace, run_id?, planner_model?, send_timeout_ms? }` |
 | `GET /autoloop/<id>/state` | `{ ok, state: AutoloopState }` |
 | `GET /autoloop/<id>/push_log` | `{ ok, entries: PushLogEntry[] }` |
-| `GET /autoloop/<id>/events` | SSE: `snapshot` / `message` / `state` / `push` / `iter_done` / `planner_reply` / `coder_reply` / `reviewer_reply` / `terminated` |
+| `GET /autoloop/<id>/events` | SSE: `snapshot` / `message` / `state` / `push` / `iter_done` / `planner_reply` / `planner_error` / `coder_reply` / `reviewer_reply` / `terminated` |
+| `POST /autoloop/<id>/chat` | **202** `{ ok, queued: true }` — body `{ text }`. Fire-and-forget: the Planner's reply streams back via the `/events` SSE channel as a `planner_reply` event (or `planner_error` on failure); the HTTP response intentionally does NOT wait for it, because first-contact replies routinely exceed reverse-proxy idle limits (e.g. Cloudflare Tunnel cuts at ~100s → 524). 400 on empty text, 404 when the run is not in this process's memory. The MCP `autoloop_chat` tool path keeps the synchronous await-and-return-reply semantics (it runs in-process). |
+| `POST /autoloop/<id>/delete` | `{ ok }` — stops the runner if still alive, scrubs the row from `~/.claw-orchestrator/autoloop-registry.jsonl`. The ledger directory under `<workspace>/tasks/<run_id>/` is kept on disk. 404 if the run was not present in either memory or the registry. |
 
 The 3-pane UI consumes these endpoints:
 - **Left**: Planner chat (subscribes to `planner_reply`)

package/skills/references/dashboard.md

@@ -0,0 +1,153 @@
+# Dashboard
+
+The dashboard is a single-page HTML app served by the orchestrator's embedded
+HTTP server. It lets you **launch and observe** Council sessions, Autoloop
+runs, and Forge (Ultraapp) builds from a browser — no CLI, no webchat, no
+plugin tool calls needed.
+
+URL: `http://127.0.0.1:18796/dash` (local) or whatever public hostname you
+front the embedded server with (the recommended setup uses a path-based
+reverse proxy, e.g. `https://<your-host>/dash`).
+
+## Tabs
+
+| Tab | Backed by | Launch endpoint |
+|---|---|---|
+| Autoloop | `SessionManager.autoloopStart()` | `POST /autoloop/new` |
+| Council | `SessionManager.councilStart()` | `POST /council/new` |
+| Forge | `UltraappManager.createRun()` | `POST /ultraapp/new` |
+
+Each tab has a `+ New` button in the sidebar. Council and Autoloop open a
+modal form (because they need workspace/task input); Forge POSTs an empty
+body and drops you into an interview (the spec is built conversationally).
+
+## Standalone deployment
+
+The recommended way to run the dashboard 24/7 is a separate `clawo serve`
+process under launchd — completely decoupled from the OpenClaw gateway. The
+gateway's plugin-side embedded server still works (lazy init on first tool
+call); when both processes try to bind the default port, the loser gracefully
+skips, so the two coexist without conflict.
+
+Example `~/Library/LaunchAgents/com.clawo.serve.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>com.clawo.serve</string>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>ThrottleInterval</key><integer>5</integer>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/opt/homebrew/bin/node</string>
+      <string>/opt/homebrew/bin/clawo</string>
+      <string>serve</string>
+      <string>--port</string><string>18796</string>
+      <string>--host</string><string>127.0.0.1</string>
+    </array>
+    <key>StandardOutPath</key>
+    <string>/Users/USER/.openclaw/logs/clawo-serve.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/USER/.openclaw/logs/clawo-serve.log</string>
+  </dict>
+</plist>
+```
+
+Bootstrap:
+
+```sh
+launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.clawo.serve.plist
+launchctl print "gui/$(id -u)/com.clawo.serve" | grep state
+```
+
+## Auth
+
+The embedded server self-generates a 32-byte token at startup and writes it
+to `~/.openclaw/server-token` (mode 0600). Same-user processes on the box
+read it and present it as `Authorization: Bearer <token>` (or
+`?token=<v>` query / `clawo_auth` cookie).
+
+### Local access
+
+```
+http://127.0.0.1:18796/dash?token=$(cat ~/.openclaw/server-token)
+```
+
+The server sets a `clawo_auth` cookie on the first query-token request, so
+the bookmark `/dash` works on subsequent visits.
+
+### Hosted access via reverse proxy (recommended)
+
+Don't expose the token to the public internet. Instead, gate the public
+hostname with whatever auth layer you already trust (CF Access passkey,
+Tailscale, mTLS, etc.) and have the reverse proxy **inject the Bearer
+token on behalf of the user** when forwarding to port 18796. The browser
+authenticates only against your edge auth; the dashboard's own token stays
+inside the box.
+
+Example sasha-doctor pattern (matches the user-side setup):
+```js
+// after the edge auth check passes:
+if (!req.headers.authorization) {
+  req.headers.authorization =
+    "Bearer " + fs.readFileSync("~/.openclaw/server-token", "utf-8").trim();
+}
+proxyHTTP(req, res, 18796);
+```
+
+The `/login?token=...&redirect=/dash` endpoint exists as a fallback for
+quick one-shot setups (works locally and through proxies that DON'T inject
+the Bearer for you), but the proxy-injects-Bearer pattern is preferred
+because users never see or paste the token.
+
+Token-file write is deferred to the `listen()`-success callback so a second
+process that loses the EADDRINUSE race does NOT clobber the winner's token.
+
+## Cross-process visibility
+
+When the dashboard runs in a different process from where you spawn runs
+(e.g. you started a council via the OpenClaw plugin tool from webchat, but
+the dashboard is in `clawo serve`), the run state is invisible across
+in-memory boundaries. The dashboard fixes this by unioning in-memory state
+with on-disk records on every list call:
+
+- **Councils**: `~/.openclaw/council-logs/council-*.md` — parsed for
+  `- **ID**:`, `- **Time**:`, `- **Task**:`, `- **Status**:` headers.
+  Legacy transcripts (pre-v4.0) fall back to a filename-derived id.
+- **Autoloops**: `~/.claw-orchestrator/autoloop-registry.jsonl` — an
+  append-only JSONL index written by `autoloopStart()`. Stale entries
+  whose ledger directory no longer exists are filtered out at read time.
+- **Forge**: `UltraappStore.listRuns()` already reads from disk
+  (`~/.claw-orchestrator/ultraapps/`).
+
+Result: any run you've ever started — from any process — shows up in the
+sidebar, sorted newest-first, until the underlying files are deleted.
+
+## Reverse-proxy integration
+
+If you front the embedded server with sasha-doctor (or another reverse
+proxy), route these paths to `127.0.0.1:18796`:
+
+- `/dashboard`, `/dash`, `/login`
+- `/autoloop/*`, `/council/*`, `/ultraapp/*`
+
+The dashboard's relative `fetch()` calls expect the proxy to preserve the
+path verbatim — no prefix stripping. `/v1/openclaw/*` should keep routing
+to the OpenClaw gateway, not the embedded server.
+
+## Reset
+
+To wipe dashboard state without touching real run data:
+
+```sh
+# Forget all known autoloops (council/forge unchanged).
+rm ~/.claw-orchestrator/autoloop-registry.jsonl
+
+# Force the standalone server to mint a fresh auth token.
+launchctl kickstart -k "gui/$(id -u)/com.clawo.serve"
+# Then visit /login?token=$(cat ~/.openclaw/server-token)&redirect=/dash once
+# to refresh the cookie.
+```

package/skills/references/mcp.md

@@ -1,6 +1,6 @@
 # MCP integration
 
-Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 41 tools.
+Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 55 tools.
 
 This document covers:
 
@@ -229,7 +229,7 @@ The engines themselves (`claude`, `codex`, `gemini`, `agent`, `opencode`) must a
 
 ## Tool filtering
 
-41 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`:
+55 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`:
 
 ```bash
 CLAWO_MCP_TOOLS="session_start,session_send,session_stop,council_start,council_status" clawo-mcp

package/skills/references/tools.md

@@ -414,3 +414,186 @@ Get status and findings when completed.
 | Parameter | Type | Required |
 |-----------|------|----------|
 | `id` | string | yes |
+
+---
+
+## Autoloop (6)
+
+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).
+
+### `autoloop_start`
+
+Start an autoloop run. Planner is created persistent; Coder + Reviewer are spawned by the Planner once `plan.md` is ready.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cwd` | string | yes | Workspace (must be a git repo) |
+| `goal` | string | yes | High-level user goal in natural language |
+| `model` | string | | Planner model (default Opus) |
+| `coderModel` | string | | Coder subagent model |
+| `reviewerModel` | string | | Reviewer subagent model |
+| `maxIters` | number | | Cap on Coder/Reviewer rounds (default 50) |
+| `pushChannels` | string[] | | Notification channels (`wechat`, `whatsapp`, `email`) |
+
+### `autoloop_chat`
+
+Send a message into the Planner conversation (e.g. answer a clarifying question, refine the plan, kick off the subloop).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `message` | string | yes |
+
+### `autoloop_status`
+
+Get current state, phase, recent inbox messages, and ledger summary.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `autoloop_list`
+
+List active and recent autoloop runs (in-memory + on-disk registry, deduped by run_id).
+
+(no params)
+
+### `autoloop_reset_agent`
+
+Reset one of the subagent sessions (Coder or Reviewer) without losing Planner state — useful when a subagent loops on a stale belief.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `agent` | `'coder'` \| `'reviewer'` | yes | Which subagent to reset |
+
+### `autoloop_stop`
+
+Terminate the run. All sessions are stopped and ledger state is finalised.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+---
+
+## Ultraapp (14)
+
+Forge tab — turn a structured Q&A interview into a deployed web app reachable at `localhost:19000/forge/<slug>/`. See [`ultraapp.md`](./ultraapp.md) for the operator reference (lifecycle, conventions §1–§7, runtime modes, file layout, HTTP routes).
+
+### `ultraapp_list`
+
+List all ultraapp runs.
+
+(no params)
+
+### `ultraapp_get`
+
+Full snapshot of a run: spec + chat + state.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_status`
+
+Lightweight status (mode + timestamps).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_new`
+
+Create a fresh run. Optionally seeds the interview with the user's first message.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `firstMessage` | string | | Free-form opening line; the interview Opus reads it before its first question |
+
+### `ultraapp_answer`
+
+Submit an answer to the current interview question.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `value` | string | yes | One of the question's `options[].value`, or `''` when using freeform |
+| `freeform` | string | | Free-form text when none of the options fit |
+
+### `ultraapp_add_file`
+
+Upload a sample file to `examples/` (the interview engine will `extract_metadata` it).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `path` | string | yes |
+| `content` | string \| Buffer | yes |
+
+### `ultraapp_spec_edit`
+
+Apply RFC 6902 JSON Patch ops to the AppSpec mid-interview.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `patch` | object[] | yes |
+
+### `ultraapp_build_start`
+
+Validate the spec strictly (shape + cross-refs + DAG) and enqueue the build. Council picks it up FIFO.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_build_cancel`
+
+Abort an active build. Council sessions are stopped and the worktrees are left as-is for inspection.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_feedback`
+
+Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spec-delta` (focused interview + auto-rerun), or `structural` (suggest fresh run).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `text` | string | yes | The feedback (1+ chars) |
+
+### `ultraapp_promote_version`
+
+Atomically swap the deployed version. Stops the current container/process, starts the target's, updates the router map.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `version` | string | yes | Target version label (`v1`, `v2`, …) |
+
+### `ultraapp_start_container`
+
+Start the container/process for the active version (no-op if already running).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_stop_container`
+
+Stop the container/process without deleting any state.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_delete`
+
+Stop + remove the run completely (sessions, container, on-disk state, router entry).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |

package/skills/references/ultraapp.md

@@ -0,0 +1,203 @@
+# ultraapp — Reference
+
+Turn a structured Q&A interview into a deployed web app reachable at
+`localhost:19000/forge/<slug>/`. The dashboard's **Forge** tab and a
+14-tool MCP surface drive the end-to-end loop: interview → 3-agent
+council → fix-on-failure → deploy → done-mode feedback.
+
+This page is the operator reference. The interview behavioural contract
+lives in [`skills/ultraapp/SKILL.md`](../ultraapp/SKILL.md). The
+council architectural conventions every generated app must satisfy live
+in [`src/ultraapp/conventions.ts`](../../src/ultraapp/conventions.ts).
+
+## When to use
+
+- You have a workflow in your head (or a sample input file) and want a
+  shareable web app for it without writing code.
+- You want to iterate cosmetically on a deployed app via chat ("make
+  the button green", "shrink the hero h1") without touching the
+  codebase yourself.
+- You want to evolve the AppSpec ("also output a thumbnail") and
+  rebuild without restarting the interview.
+
+## Lifecycle
+
+```text
+interview ─► queued ─► building ─► build-complete ─► deploying ─► done
+                                                                    │
+                                                                    ▼
+                                                              done-mode chat
+                                                              (cosmetic /
+                                                               spec-delta /
+                                                               structural)
+```
+
+| Mode | Meaning |
+|------|---------|
+| `interview` | AppSpec being filled by Q&A. Chat input goes to the interview Opus. |
+| `queued` | Build accepted, waiting for a slot in the FIFO build queue. |
+| `building` | Council writing code, fix-on-failure driving install/build/test. |
+| `build-complete` | Codebase ready, awaiting `deploy` step. |
+| `deploying` | Container/process being started, router map being updated. |
+| `done` | App live at `/forge/<slug>/`. Chat input now goes to the done-mode classifier. |
+| `failed` | Council didn't reach consensus, or fix-on-failure couldn't get the build green. |
+
+## Architectural conventions (§1–§7)
+
+Every generated app MUST satisfy these. They're embedded in the council
+super-task prompt verbatim from `src/ultraapp/conventions.ts`.
+
+| § | Topic | Headline rule |
+|---|-------|---------------|
+| 1 | Path-based deploy | Mount at `BASE_PATH=/forge/<slug>/`; in-app links MUST be relative. |
+| 2 | Async file-queue runtime | Exact endpoints: `GET /`, `POST /run`, `GET /status/:jobId`, `GET /result/:jobId`, `GET /health`. File-based job queue under `$DATA_DIR/jobs/<jobId>/`. NO database. Data path from `process.env.DATA_DIR ?? '/data'`. |
+| 3 | BYOK | If `runtime.needsLLM`, API keys live in browser localStorage and are sent direct to the provider. The server MUST NEVER receive the key (enforced by `eslint-plugin-no-server-keys`). |
+| 4 | Dockerfile + smoke test | Single multi-stage Dockerfile, `npm run smoke` drives one full job in < 90s using `examples[0].ref`. |
+| 5 | Council voting protocol | 3 agents in git worktrees, all-YES vote required, max 8 rounds. |
+| 6 | Tech stack | Modern TypeScript / JavaScript framework (Next.js, Vite + Hono, SvelteKit). NO Python, NO pure SSGs. |
+| 7 | **Frontend quality** | **Real styling system + real type hierarchy + four-state coverage on every async surface + drag-and-drop forms + appropriate result presentation + one deliberate theme.** §7g requires every agent to capture Chrome-headless screenshots at 1440×900 AND 375×812 and visually inspect the PNGs before voting YES — source-code review is explicitly insufficient evidence. |
+
+## Runtime modes
+
+```bash
+clawo serve --ultraapp-runtime host    # default
+clawo serve --ultraapp-runtime docker  # opt-in
+```
+
+| Mode | Build | Run | Pros | Cons |
+|------|-------|-----|------|------|
+| `host` | `npm install && npm run build` | `npm start` (detached, `setsid`-equivalent) | Zero extra deps; works anywhere Node works; faster start. | No process isolation; deps installed under the user. |
+| `docker` | `docker build .` | `docker run -d --restart unless-stopped` | Per-app isolation, restart policy, image is the artefact. | Requires a running Docker daemon. |
+
+Both modes allocate a backend port in `[19100, 19999]`. The reverse-
+proxy router runs at port `19000` (auto-fallback up to `19099` if
+taken) and maps `/forge/<slug>/*` to the right backend. Slug→port map
+persists to `~/.claw-orchestrator/_router.json`. Host-mode pid metadata
+persists to `~/.claw-orchestrator/host-procs.json`.
+
+## File layout (per run)
+
+```text
+~/.claw-orchestrator/ultraapps/<runId>/
+├── spec.json                  # current AppSpec (latest)
+├── spec.history.jsonl         # every accepted update_spec patch
+├── chat.jsonl                 # all chat turns (interview + done-mode)
+├── state.json                 # { runId, mode, createdAt, updatedAt }
+├── examples/                  # uploaded sample files
+├── data/                      # passed to host-mode app as DATA_DIR
+├── council-project/           # fresh git repo the council collaborates in
+│   ├── .worktrees/{agent-A,agent-B,agent-C}/
+│   └── (council code, merged to main on consensus)
+└── versions/
+    ├── v1/
+    │   ├── codebase/          # snapshot of council main HEAD
+    │   └── artifact.json      # { worktreePath, builtAt, deploy: { url, port, … } }
+    └── v2/                    # patcher / spec-delta produces v2, v3, …
+```
+
+## HTTP routes (drive headlessly)
+
+All routes are served by the embedded server (default `:18796`), under
+`Authorization: Bearer <token>` from `~/.openclaw/server-token`.
+
+| Method + path | Purpose |
+|----|----|
+| `GET /ultraapp/list` | All runs with mode + createdAt. |
+| `POST /ultraapp/new` | Body: `{ firstMessage?: string }`. Returns `{ runId }`. |
+| `GET /ultraapp/<id>` | Full snapshot: spec + chat + state. |
+| `POST /ultraapp/<id>/answer` | Body: `{ value, freeform? }`. Submit interview answer. |
+| `POST /ultraapp/<id>/spec-edit` | Body: RFC 6902 patch ops. Edit the spec mid-interview. |
+| `POST /ultraapp/<id>/files` | Multipart upload to `examples/`. |
+| `GET /ultraapp/<id>/events` | SSE stream of build/chat events (mode pill, narrator, council activity). |
+| `POST /ultraapp/<id>/build` | Validate spec strictly + enqueue. |
+| `POST /ultraapp/<id>/build/cancel` | Abort the active build. |
+| `GET /ultraapp/<id>/artifacts` | List `versions/vN/`. |
+| `POST /ultraapp/<id>/start` | Start the deployed container/process for the active version. |
+| `POST /ultraapp/<id>/stop` | Stop without deleting. |
+| `POST /ultraapp/<id>/delete` | Stop + remove all per-run state. |
+| `POST /ultraapp/<id>/feedback` | Body: `{ text }`. Done-mode classifier routes cosmetic / spec-delta / structural. |
+| `POST /ultraapp/<id>/promote-version` | Body: `{ version: "vN" }`. Atomically swap deployed version. |
+
+## MCP tools (14)
+
+Same surface as HTTP, callable from any Model Context Protocol host
+(Claude Desktop, Hermes Agent, Cursor, Cline, Continue, Zed,
+Windsurf, Goose). Param schemas in [`tools.md`](./tools.md#ultraapp).
+
+```text
+ultraapp_list           ultraapp_get             ultraapp_status
+ultraapp_new            ultraapp_answer          ultraapp_add_file
+ultraapp_spec_edit      ultraapp_build_start     ultraapp_build_cancel
+ultraapp_feedback       ultraapp_promote_version
+ultraapp_start_container ultraapp_stop_container ultraapp_delete
+```
+
+## Done-mode feedback classification
+
+After the run reaches `done`, chat input goes to a per-run Haiku
+classifier. Three classes:
+
+| Class | Routes to | Behaviour |
+|-------|-----------|-----------|
+| `cosmetic` | Patcher | Opus generates a unified diff against the deployed worktree → `applyUnifiedDiff` → validate via fix-on-failure → on success snapshot to `versions/vN+1/`, on any failure restore the snapshot atomically and post the reason to chat. |
+| `spec-delta` | Focused interview | Flips mode back to `interview` with a bootstrap message that names the field(s) being changed. Completion auto-triggers a fresh `startBuild`. |
+| `structural` | Suggestion only | Posts a narrator note: "this sounds like a different app — click + New". |
+
+To swap which version is live, use `promote-version` (HTTP) or
+`ultraapp_promote_version` (MCP) — the router map and host-procs map
+update atomically.
+
+## Reference traces + replay
+
+5 captured JSONL traces of real interviews ground-truth the interview
+engine against drift:
+
+```text
+src/__tests__/fixtures/ultraapp-traces/
+├── text-summariser.jsonl      (synthetic, simple text in/out)
+├── image-batch-resize.jsonl   (batch upload + Pillow + zip)
+├── vlog-cut.jsonl             (ffmpeg + whisper + branching DAG)
+├── llm-agent-pipeline.jsonl   (BYOK, multi-step LLM)
+├── branching-dag.jsonl        (parallel paths converging)
+├── _format.md                 (trace JSONL schema)
+└── expected/<name>.appspec.json   (frozen target)
+```
+
+```bash
+tsx scripts/test-ultraapp-integration.ts --trace=image-batch-resize
+tsx scripts/test-ultraapp-integration.ts --trace=all
+```
+
+The `spec-extraction-quality.test.ts` test replays each trace through
+the interview engine and asserts the resulting `AppSpec` matches the
+frozen snapshot — any future engine or skill drift fails this test.
+
+## Operator quick start
+
+```bash
+# 1. Boot
+clawo serve   # dashboard at :18796, ultraapp router at :19000
+open "http://127.0.0.1:18796/dashboard?token=$(cat ~/.openclaw/server-token)"
+
+# 2. Forge tab → + New → walk through the interview
+
+# 3. After [Start Build] (or POST /ultraapp/<id>/build), watch:
+#      mode pill: queued → building → done
+#      narrator: short conversational chat updates
+#      Versions panel: v1, v2, … with Promote per row
+
+# 4. Live URL appears in the share card. The deployed app is reachable at:
+curl http://127.0.0.1:19000/forge/<slug>/health
+```
+
+## Known limitations (v4.0.0)
+
+- The done-mode patcher loop occasionally hangs between
+  feedback-classification and the patcher Opus session creation;
+  cosmetic changes can be applied manually until the underlying race
+  is fixed.
+- The §7g frontend gate currently relies on per-agent honesty about
+  running the screenshot capture; agents that skip the inspection can
+  still pass the smoke gate. A follow-up will plumb a server-side
+  screenshot validator into the council verifier so the gate becomes
+  structurally enforced rather than persona-enforced.