@enderfga/claw-orchestrator 7.14.0 → 7.15.0

package/skills/references/ultra.md

@@ -116,12 +116,12 @@ if (status?.status === 'completed') {
 
 ### Configuration
 
-| Parameter            | Default                   | Range | Description                                                                                           |
-| -------------------- | ------------------------- | ----- | ----------------------------------------------------------------------------------------------------- |
-| `agentCount`         | 5                         | 1-20  | Number of reviewer agents                                                                             |
-| `maxDurationMinutes` | 10                        | 5-25  | Per-agent timeout                                                                                     |
-| `model`              | session default           | —     | Model for all reviewers                                                                               |
-| `focus`              | bugs + security + quality | —     | Review focus description                                                                              |
-| `engines`            | `['claude']`              | —     | Engines assigned to reviewers round-robin. Not `custom`, which has no config to start a reviewer from |
+| Parameter            | Default                   | Range | Description                                                                                          |
+| -------------------- | ------------------------- | ----- | ---------------------------------------------------------------------------------------------------- |
+| `agentCount`         | 5                         | 1-20  | Number of reviewer agents                                                                            |
+| `maxDurationMinutes` | 10                        | 5-25  | Per-agent timeout                                                                                    |
+| `model`              | session default           | —     | Model for all reviewers                                                                              |
+| `focus`              | bugs + security + quality | —     | Review focus description                                                                             |
+| `engines`            | `['claude']`              | —     | Engines assigned to reviewers round-robin. Not `custom` or `acp`: neither can be held read-only here |
 
 Reviewers run once each (up to 20 turns); there is no cross-review round. Results are stored as a durable run and remain queryable after a restart.

package/skills/references/ultraapp.md

@@ -37,20 +37,21 @@ interview ─► queued ─► building ─► build-complete ─► deploying
 | `interview`      | AppSpec being filled by Q&A. Chat input goes to the interview agent (Claude 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.                                            |
+| `build-complete` | Codebase ready. The resting state when no router is wired (see Runtime modes).     |
 | `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.    |
+| `cancelled`      | The build was cancelled (`build/cancel` or `ultraapp_build_cancel`).               |
 
 ### The build is a workflow run
 
 Everything from `building` onward is a run on the durable kernel — the same one
 `council_start`, `fanout_start` and `autoloop_start` use. The workflow has three
-nodes:
+nodes (two when no router is wired — there is then nowhere to deploy):
 
 | Node     | Kind              | Does                                                         |
 | -------- | ----------------- | ------------------------------------------------------------ |
-| `synth`  | `ultraapp_synth`  | The 3-agent council; snapshots consensus into `versions/v1/` |
+| `synth`  | `ultraapp_synth`  | The 3-agent council; snapshots consensus into `versions/vN/` |
 | `build`  | `verifier`        | The build contract, with its fix-on-red loop and evidence    |
 | `deploy` | `ultraapp_deploy` | Starts the app, registers the route, runs the §7g gate       |
 
@@ -104,57 +105,84 @@ clawo serve --ultraapp-runtime docker  # opt-in
 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/ultraapps/_router.json`. Host-mode pid metadata
 persists to `~/.claw-orchestrator/host-procs.json`.
 
+The router is started by `clawo serve`. The OpenClaw plugin does not start one,
+and `clawo serve` runs without one when the router cannot start (for example,
+no free port in `19000`–`19099`): builds then stop at `build-complete` and are
+not deployed.
+
 ## File layout (per run)
 
 ```text
 ~/.claw-orchestrator/ultraapps/<runId>/
 ├── spec.json                  # current AppSpec (latest)
-├── spec.history.jsonl         # every accepted update_spec patch
+├── spec.history.jsonl         # the full spec after every write (interview update_spec or manual edit)
 ├── chat.jsonl                 # all chat turns (interview + done-mode)
-├── state.json                 # { runId, mode, createdAt, updatedAt }
+├── state.json                 # { runId, mode, createdAt, updatedAt, failure? }
 ├── examples/                  # uploaded sample files
 ├── data/                      # passed to host-mode app as DATA_DIR
+├── evidence/deploy-01/        # deploy-stage evidence (see Acceptance contract)
 ├── 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, …
+    │   ├── codebase/          # snapshot of council main HEAD, its own git repo
+    │   └── artifact.json      # { worktreePath, builtAt, deploy: { url, port, … }, deployedAt }
+    └── v2/                    # each build and each successful patch takes the next vN
 ```
 
+Every version keeps its own `codebase/`, so any of them can be promoted. The live
+version is the one most recently deployed or promoted; `start`, `stop` and the
+patcher act on it.
+
+Run ids have the form `ua-<timestamp>-<hex>`. The build queue
+(`build-queue.json`) and the router map (`_router.json`) sit beside the run
+directories, in `~/.claw-orchestrator/ultraapps/`. A run is read back from its
+directory on first use, so every route works on a run started before the
+orchestrator restarted; its interview session is restarted by name on the run's
+next turn, which resumes the persisted conversation.
+
 ## 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`                  | No body. 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: `{ patch: [...] }` (RFC 6902 ops). Edit the spec mid-interview.                                         |
-| `POST /ultraapp/<id>/files`           | JSON body `{ absolutePath }` (a file on the server host) or `{ filename, dataB64 }`. Copies into `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.                                                  |
+`Authorization: Bearer <token>` from `~/.openclaw/server-token`. Request bodies
+are JSON (`Content-Type: application/json`) and capped at 5 MB.
+
+| Method + path                         | Purpose                                                                                                                                |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /ultraapp/list`                  | All runs (runId, title, mode, createdAt, updatedAt), newest first.                                                                     |
+| `POST /ultraapp/new`                  | No body. 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: `{ patch: [...] }` (RFC 6902 ops). Edit the spec mid-interview.                                                                  |
+| `POST /ultraapp/<id>/files`           | Add an example file: body `{ filename, dataB64 }` or `{ absolutePath }` (below).                                                       |
+| `GET /ultraapp/<id>/events`           | SSE stream of `ultraapp` events: questions, spec updates, chat, completeness, interview completion, build events, the app URL, errors. |
+| `POST /ultraapp/<id>/build`           | Validate spec strictly + enqueue.                                                                                                      |
+| `POST /ultraapp/<id>/build/cancel`    | Cancel a queued or in-flight build.                                                                                                    |
+| `GET /ultraapp/<id>/artifacts`        | List `versions/vN/`.                                                                                                                   |
+| `POST /ultraapp/<id>/start`           | Start the deployed container/process of the live version and re-register its route.                                                    |
+| `POST /ultraapp/<id>/stop`            | Stop without deleting; the route is deregistered until `start`.                                                                        |
+| `POST /ultraapp/<id>/delete`          | Stop every deployed version, remove the images, and delete 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" }`. Make that version live, deploying it first if it never was.                                                 |
+
+`files` with `{ filename, dataB64 }` copies an upload into `examples/`; an upload
+may be up to 100 MiB, and this route accepts a body sized for its base64 text
+(every other route caps bodies at 5 MiB). With `{ absolutePath }` it references a file
+on the server host in place; the path must be under `$HOME` or `/tmp`, with no
+dotfile segment and no symlink. `feedback` sent before the run reaches `done`
+goes to the interview as a free-form answer.
 
 ## MCP tools (14)
 
-Same surface as HTTP, callable from any Model Context Protocol host
+The same operations as HTTP, minus the SSE stream and the artifacts listing,
+plus a cheap `ultraapp_status`. 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-14).
+Windsurf, Goose). `ultraapp_add_file` takes an `absolutePath` only; browser
+uploads go through the dashboard. Param schemas in [`tools.md`](./tools.md#ultraapp-14).
 
 ```text
 ultraapp_list           ultraapp_get             ultraapp_status
@@ -169,15 +197,17 @@ ultraapp_start_container ultraapp_stop_container ultraapp_delete
 After the run reaches `done`, chat input goes to a per-run Haiku
 classifier. Three classes:
 
-| Class        | Routes to         | Behaviour                                                                                                                                                                                                                                              |
-| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `cosmetic`   | Patcher           | A Claude Opus session 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".                                                                                                                                                                               |
+| Class        | Routes to         | Behaviour                                                                                                                                                                                                                                                                                                                                                           |
+| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cosmetic`   | Patcher           | Copies the live version's codebase to the next `versions/vN/`, then a Claude Opus session generates a unified diff against the copy → `applyUnifiedDiff` → validate via fix-on-failure. On success the copy is recorded as `vN` (not deployed; the live app is untouched until you promote it); on any failure the copy is discarded and the reason posted 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`, which builds the next `vN`, deploys it in place of the live version and stops the one it replaced.                                                                                                                    |
+| `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.
+To change which version is live, use `promote-version` (HTTP),
+`ultraapp_promote_version` (MCP) or **Promote** in the dashboard's Versions panel.
+A version deployed before is restarted on its recorded port and the live one
+stopped; if it does not start, the previous version is put back. A version never
+deployed is built and deployed first.
 
 ## Reference traces + replay
 
@@ -186,11 +216,11 @@ output 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)
+├── text-summariser.jsonl      (hand-written; text in, one LLM step, text out)
+├── image-batch-resize.jsonl   (batch image upload, resize + watermark, zip out)
+├── vlog-cut.jsonl             (ffmpeg silence detection, cut + concat)
 ├── llm-agent-pipeline.jsonl   (BYOK, multi-step LLM)
-├── branching-dag.jsonl        (parallel paths converging)
+├── branching-dag.jsonl        (whisper transcript + ffmpeg keyframes, converging)
 ├── _format.md                 (trace JSONL schema)
 └── expected/<name>.appspec.json   (frozen target)
 ```
@@ -201,8 +231,10 @@ npx 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.
+the interview engine, with the model's replies taken from the trace, and
+asserts the resulting `AppSpec` matches the frozen snapshot — a change in
+how replies are parsed or applied to the spec fails it. Because the replies
+are recorded, it does not exercise the live model or `SKILL.md`.
 
 ## Operator quick start
 
@@ -214,9 +246,9 @@ 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
+#      mode pill: queued → building → build-complete → done
 #      narrator: short conversational chat updates
-#      Versions panel: v1, v2, … with Promote per row
+#      Versions panel: v1, v2, …; the live one links to the app, the others have Promote
 
 # 4. Live URL appears in the share card. The deployed app is reachable at:
 curl http://127.0.0.1:19000/forge/<slug>/health
@@ -226,24 +258,29 @@ curl http://127.0.0.1:19000/forge/<slug>/health
 
 UltraApp is the one mode whose acceptance contract is on by default.
 
-**Build stage**, in the council's worktree:
+**Build stage**, in the consensus snapshot (`versions/v1/codebase/`):
 
 ```
 npm install → npm run build → npm test → [docker build] → npm run smoke
 ```
 
-A codebase without a working `scripts.smoke` fails its build (§4).
+`docker build` runs only in `docker` runtime mode. On a red check a repair
+session is started and the whole list re-runs, up to 5 times. A codebase
+without a working `scripts.smoke` fails its build (§4).
 
 **Deploy stage**, against the live URL: both §7g viewports (1440×900 and
 375×812) are captured by the orchestrator with headless Chrome and stored as run
 evidence.
 
-Evidence lands under the run directory:
+Evidence lands in two places. The build stage is an ordinary `verifier` node,
+so its bundle is in the workflow run's directory; the deploy stage writes its own
+into the app's run directory:
 
 ```
+~/.claw-orchestrator/wf/ultraapp-<runId>/evidence/
+  build-v01-01/   bundle.json, checks/*.log, diff.patch
 ~/.claw-orchestrator/ultraapps/<runId>/evidence/
-  build-01/    bundle.json, checks/*.log, diff.patch
-  deploy-01/   bundle.json, shot-desktop.png, shot-mobile.png
+  deploy-01/      bundle.json, shot-desktop.png, shot-mobile.png
 ```
 
 ### What the visual gate does and does not do
@@ -259,15 +296,23 @@ the usual macOS app paths, then `PATH`.
 
 ## Durable build queue
 
-The build queue is persisted to `<store>/build-queue.json` and restored on
-startup.
+The build queue is persisted to `~/.claw-orchestrator/ultraapps/build-queue.json`
+and restored on startup. Builds run one at a time, first in, first out. Only one
+process owns the queue: restoring it takes a lease, and a process that cannot
+take the lease starts with an empty queue.
 
-A build that was in flight when the process died is **re-queued, not resumed**,
-and goes to the front: each build starts from a fresh council worktree, so
-re-running is safe and continuing a half-built tree is not.
+A build that was in flight when the process died goes back to the **front** of
+the queue. When it runs again, its workflow run resumes from the last stage it
+finished (see [The build is a workflow run](#the-build-is-a-workflow-run)), so a
+finished council is not paid for twice. A build started again after it completed,
+failed or was cancelled is a fresh run under the same id.
 
 ## Known limitations
 
+- The interview, spec edits, file additions, builds, done-mode feedback and the
+  `events` stream work only on a run created by the running process. After a
+  restart they answer `unknown runId`; listing, reading, start / stop / delete
+  and promote still work.
 - The done-mode patcher loop occasionally hangs between
   feedback classification and the start of the patcher's Claude Opus session;
   cosmetic changes can be applied manually until the underlying race

package/skills/references/verification.md

@@ -1,31 +1,52 @@
 # Verification — acceptance contracts and evidence
 
 An **acceptance contract** is a list of checks the runtime executes itself and
-whose results it reads. A run that declares one cannot reach `completed` unless
-every required check passes. Completion signals that come from an agent or an
-engine (consensus votes, a Coder's reported metric, an engine's `ok`) are
-recorded, but they are never treated as verification.
+whose results it reads. A run that declares one is judged by its last
+verification: it ends `failed` when a required check of that verification fails,
+and `completed` / `verified` only when every required check passes.
+Completion signals that come from an agent or an engine (consensus votes, a
+Coder's reported metric, an engine's `ok`) are recorded, but they are never
+treated as verification.
 
 ## The one rule about where contracts come from
 
 **A contract comes from the caller or from a mode default. Never from agent
 output.** If an agent could declare its own checks, we would be back to
 self-grading with more steps. Nothing in the kernel reads a contract out of a
-node's result, and `normalizeContract()` drops anything it does not recognise, so
-a contract that arrived through a tool call carries no fields the executor did
-not model.
+node's result.
+
+The `contract` argument of `workflow_start`, `POST /workflow/new` and `verify_run`
+goes through `normalizeContract()`, which drops anything it does not recognise, so
+it carries no fields the executor did not model; one with no recognised check is
+refused before the run starts. That argument takes each check bare,
+`{ "type": "command", … }`, or wrapped, `{ "id"?, "spec": { … }, "required"? }`.
+A contract written inside a spec — `spec.contract`, or a verifier's inline
+`contract` — is used as written, so its checks must be in the wrapped form.
+
+A workflow start normalises every contract the run carries the same way: the
+`contract` start option, the spec's own `contract`, and each verifier node's
+inline `contract`. A check may be written bare (`{ "type": "command", "cmd": … }`)
+or wrapped (`{ "spec": { … }, "required": … }`) in any of them. A contract in
+which no check is recognised is refused at start rather than dropped.
 
 Concretely: there is no shell string anywhere. A `command` check is argv.
 
 ## Check types
 
-| Type          | What it does                                                                | Passes when                                                               |
-| ------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `command`     | Runs argv in a directory                                                    | Exit code equals `expectExit` (default 0)                                 |
-| `http`        | Polls a URL until the deadline                                              | Status equals `expectStatus` (default 200)                                |
-| `screenshot`  | Captures the page at each viewport with headless Chrome and stores the PNGs | Every viewport produced a non-empty image                                 |
-| `diff_policy` | Compares the change set against the recorded baseline                       | File count, forbidden paths, and required paths all satisfied             |
-| `file`        | Checks a path                                                               | Exists (or is absent when `exists: false`) and matches `matches` if given |
+| Type          | Fields                                                                        | What it does                                                                | Passes when                                                                                                       |
+| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `command`     | `cmd`, `args`, `cwd`, `expectExit`, `timeoutMs`                               | Runs argv in a directory (`cwd` is relative to where the checks run)        | Exit code equals `expectExit` (default 0)                                                                         |
+| `http`        | `url`, `expectStatus`, `timeoutMs`, `intervalMs`                              | GETs a URL every `intervalMs` (default 1 s) until the deadline              | Status equals `expectStatus` (default 200)                                                                        |
+| `screenshot`  | `url`, `viewports` (`[{ width, height, label? }]`), `browserBin`, `timeoutMs` | Captures the page at each viewport with headless Chrome and stores the PNGs | Every viewport produced a non-empty image                                                                         |
+| `diff_policy` | `maxFiles`, `forbidPaths`, `requirePaths`                                     | Compares the change set against the recorded baseline                       | At most `maxFiles` files changed, none under a `forbidPaths` entry, and at least one under a `requirePaths` entry |
+| `file`        | `path`, `exists`, `matches`                                                   | Checks a path, relative to where the checks run                             | Exists (or is absent when `exists: false`) and, if `matches` is given, its contents match that regex              |
+
+Each check may also carry an `id` (default `<type>-<n>`, used in the evidence) and
+`required`. The contract itself is `{ id?, checks, fixOnFailureRounds?,
+protectTests? }`. `forbidPaths` and `requirePaths` are path prefixes matched by
+whole segments (`src` covers `src/a.ts`, not `srcfoo/a.ts`), not globs.
+
+As the `contract` argument of `workflow_start` or `verify_run`:
 
 ```jsonc
 {
@@ -48,8 +69,11 @@ blocking.
 
 ### Timeouts
 
-Every check has one; the default is 10 minutes. A check that overruns is killed (its whole process group, with SIGKILL)
-and recorded as failed with `timedOut: true`.
+`timeoutMs` defaults to 10 minutes for a `command` check, 30 seconds for an `http`
+check, and 60 seconds per viewport for a `screenshot`. A command or browser that
+overruns is killed (its whole process group, with SIGKILL); an overrunning command,
+and an `http` check that never saw the expected status, are recorded as failed with
+`timedOut: true`. `diff_policy` and `file` take no `timeoutMs`.
 
 ### What `screenshot` does and does not claim
 
@@ -58,38 +82,48 @@ visual regression testing. The runtime performs the capture, so the screenshots
 are files on disk rather than an agent's claim. Judging the rendering is still a
 human's or an agent's job.
 
-Chrome is resolved from `CLAWO_CHROME_BIN`, then the usual macOS app paths, then
-`PATH`. A host with no browser fails the check immediately rather than paying the
-timeout to find out.
+Chrome is resolved from the check's `browserBin`, then `CLAWO_CHROME_BIN`, then
+the usual macOS app paths, then `PATH`. A host with no browser fails the check
+immediately rather than paying the timeout to find out.
 
 ### `diff_policy` and the baseline
 
 `diff_policy` needs to know what the run changed, which needs a baseline. The
 kernel records `git rev-parse HEAD` when a run starts and diffs against that.
+`verify_run` takes the baseline as `baseSha`; without one, `diff_policy` sees
+untracked files only.
 
-The change set is **tracked changes ∪ untracked files**. That union matters: a
-bare `git diff` lists tracked modifications only, so files an agent _created_ are
-invisible to it.
+The change set is **tracked changes ∪ untracked files**: `git diff <base>` (so
+commits made during the run count too) plus every untracked file that
+`.gitignore` does not exclude. That union matters: a bare `git diff` lists tracked
+modifications only, so files an agent _created_ are invisible to it.
 
 `requirePaths: ["."]` means "the run must have changed something".
 
 ## Evidence bundles
 
 Every verifier attempt writes a directory under the run, named
-`<node>-v<visit>-<attempt>`. Both counters are in the id because the attempt
-counter is per-visit and restarts at 1 each time a loop comes back round — so a
-repair loop keeps every pass rather than overwriting the last one:
+`<node>-v<visit>-<attempt>` with both counters zero-padded (`verify-v02-01`,
+`__verify-v01-01`). Both counters are in the id because the attempt counter is
+per-visit and restarts at 1 each time a loop comes back round — so a repair loop
+keeps every pass rather than overwriting the last one. Fix-on-red rounds inside one
+attempt share its bundle, which records how many were used:
 
 ```
 ~/.claw-orchestrator/wf/<runId>/evidence/<evidenceId>/
-  bundle.json        verdict, per-check results, changed files, base/head SHA
+  bundle.json        verdict, per-check results, fix rounds, changed files,
+                     base/head SHA, tree digest
   checks/<id>.log    output tail for each failed check
   diff.patch         the patch the run produced, new files included
-  shot-*.png         screenshots, when a screenshot check ran
+  shot-<label>.png   screenshots, when a screenshot check ran
 ```
 
-Read one with `clawo verify <runId>`, `GET /workflow/<id>/evidence`, or
-`workflow_status` (which returns the id).
+A failed command's tail is the last 200 lines of its stderr, or of its stdout when
+stderr is empty; a failed `diff_policy` logs the change set it judged.
+
+Read one with `clawo verify <runId>` (`--evidence <id>` for an earlier bundle) or
+`GET /workflow/<id>/evidence` (`?evidenceId=`); without an id both return the
+bundle behind the run's current verdict, whose id `workflow_status` reports.
 
 Bundle writes are best-effort. The verdict is already decided by the check
 results, so a bundle that fails to land loses the record, never the answer.
@@ -100,6 +134,11 @@ results, so a bundle that fails to land loses the record, never the answer.
 **re-runs the whole check list**. The fixer's own claim to have fixed it is
 ignored; only the re-run decides. Set it to 0 (the default) to disable.
 
+Each round's fixer is a session in the checks' directory, with
+`bypassPermissions`, given the first failing required check and its output tail,
+framed as data. Fix-on-red runs only inside a workflow's verifier node:
+`verify_run` runs the checks once and ignores the field.
+
 ## Protected tests
 
 A `command` check runs in the tree the agent just worked in, so an agent could make
@@ -119,30 +158,33 @@ whether it passed or not and runs again before every fixer round.
   symlink by its target), so the index, git attributes and filters, line-ending
   conversion and path quoting have no say.
 - **Counted as tests:** files under `__tests__/`, `__snapshots__/`, `test/`, `tests/`;
-  `*.test.*` and `*.spec.*` scripts; `test_*.py`, `*_test.py`, `*_test.go`, `*_spec.rb`,
-  `spec/spec_helper.rb`, `spec/rails_helper.rb`, `spec/support/`, `.rspec`;
-  `*Test.java`/`.kt`/`.cs`.
+  JavaScript and TypeScript `*.test.*` and `*.spec.*` files; `test_*.py`, `*_test.py`,
+  `*_test.go`, `*_spec.rb`, `spec/spec_helper.rb`, `spec/rails_helper.rb`,
+  `spec/support/`; `*Test` and `*Tests` files in `.java`, `.kt` and `.cs`.
 - **Counted as test configuration:** vitest/jest/playwright/cypress config (including
-  `.json`), `karma.conf.*`, `vitest.setup.*`/`jest.setup.*`/`setupTests.*`,
-  `.mocharc*`, `pytest.ini`, `conftest.py`, `tox.ini`, `phpunit.xml`.
+  `.json`), `vitest.workspace.*`, `karma.conf.*`, `vitest.setup.*`/`jest.setup.*`/
+  `setupTests.*`, `.mocharc*`, `.rspec`, `pytest.ini`, `conftest.py`, `tox.ini`,
+  `phpunit.xml` and `phpunit.xml.dist`.
 - **In a `package.json`:** the `jest`, `mocha`, `ava`, `vitest`, `c8` and `nyc` keys,
-  and every script the checks can reach — the `test`, `pretest` and `posttest` scripts,
-  any script a contract command runs by name (`npm run verify`), and whatever those run
-  in turn through `npm run`, `yarn`, `pnpm`, `run-s`/`run-p`, including their `pre`/`post`
-  hooks. Other scripts, dependencies and key order may change.
+  and every script the checks can reach — `test`, `pretest`, `posttest` and any
+  `test:*` script (with its `pre`/`post` forms), any script a contract command runs by
+  name (`npm run verify`), and whatever those run in turn through `npm run`, `yarn`,
+  `pnpm`, `bun`, `npm-run-all` or `run-s`/`run-p`, including their `pre`/`post` hooks.
+  Other scripts, dependencies and key order may change.
 - **Allowed:** adding test files, packages, and test configuration that governs no test
   the run started with (a new package with its own `jest.config.ts`). New configuration
-  in a directory that holds such a test — a `conftest.py` beside existing tests — is
+  in a directory at or above such a test — a `conftest.py` beside existing tests — is
   refuted, since it changes what they do.
 - **Not considered:** installed dependencies (`node_modules/`, `vendor/`,
   `site-packages/`, `.venv/`), which ship their own tests and configs.
 - **Opting out:** set `"protectTests": false` when changing existing tests is the task.
 - **Where it applies:** kernel runs in a git repository with a `command` check that
   protects tests, including a subflow's verifier, which uses its parent run's record.
-  The record is taken only for such runs. A run created before this check existed
-  reports it as not checked (not required), and so does a verifier running outside the
-  recorded repository. `verify_run`, UltraApp's build gate and Autoloop's gate have no
-  record of the tree before the work and are not covered.
+  The record is taken only for such runs and for runs with a `subflow` node. A run in
+  a repository that has no record (created before this check existed, or one git could
+  not list) reports it as not checked (not required), and so does a verifier running
+  outside the recorded repository. `verify_run`, UltraApp's build gate and Autoloop's
+  gate have no record of the tree before the work and are not covered.
 - **What it does not catch:** tests inside source files (Rust `#[cfg(test)]`), test
   settings inside general config (`vite.config.*`, `pyproject.toml`, `setup.cfg`),
   files hidden by `.gitignore`, and source code that special-cases the test
@@ -150,16 +192,15 @@ whether it passed or not and runs again before every fixer round.
 
 ## Per-mode defaults
 
-| Mode                     | Contract          | Notes                                                                                                                                                                  |
-| ------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **UltraApp**             | **On by default** | Build: `npm install` → `npm run build` → `npm test` → (`docker build`) → **`npm run smoke`**. Deploy: **screenshots at 1440×900 and 375×812** against the live URL.    |
-| **Council**              | Caller-declared   | Consensus votes are recorded on the run as advisory and do not decide completion.                                                                                      |
-| **Autoloop**             | Not yet exposed   | Library-level only (the dispatcher's `contract` option); `autoloop_start` and the HTTP API do not accept one. See [`autoloop.md`](./autoloop.md#acceptance-contracts). |
-| **Fanout / Ultrareview** | Caller-declared   | Per-agent `ok` is the engine's terminal verdict for its turn.                                                                                                          |
-| **Plain sessions**       | None              | Use `verify_run` to check work after the fact.                                                                                                                         |
-
-UltraApp's build gate includes `npm run smoke`, and its deploy gate captures
-screenshots at 1440×900 and 375×812 against the live URL.
+| Mode                        | Contract          | Notes                                                                                                                                                                                               |
+| --------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **UltraApp**                | **On by default** | Build: `npm install` → `npm run build` → `npm test` → (`docker build`) → **`npm run smoke`**, with up to 5 fix-on-red rounds. Deploy: **screenshots at 1440×900 and 375×812** against the live URL. |
+| **`solve` / `goal`**        | Caller-declared   | `workflow_start`'s `contract`, or `--check` / `--contract` on `clawo solve` and `clawo goal`. Without one the `verify` node passes through and the run ends `unverified`.                           |
+| **Council**                 | Caller-declared   | Through `workflow_start` (`template: "council"` or a spec); `council_start` takes none. Consensus votes are recorded on the run as advisory and do not decide completion.                           |
+| **Fanout**                  | Caller-declared   | Through `workflow_start` (`template: "fanout"` or a spec) or `clawo fanout --check`; `fanout_start` takes none. Per-agent `ok` is the engine's terminal verdict for its turn.                       |
+| **Ultrareview / Ultraplan** | None              | `ultrareview_start` and `ultraplan_start` take no contract.                                                                                                                                         |
+| **Autoloop**                | Not yet exposed   | Library-level only (the dispatcher's `contract` option); `autoloop_start` and the HTTP API do not accept one. See [`autoloop.md`](./autoloop.md#acceptance-contracts).                              |
+| **Plain sessions**          | None              | Use `verify_run` to check work after the fact.                                                                                                                                                      |
 
 The visual gate is **advisory by default** so that a host without Chrome does not
 lose a working app to a missing browser. Set
@@ -175,6 +216,14 @@ verify_run({ cwd: "/repo", contract: { checks: [{ type: "command", cmd: "npm", a
 Use it for a plain `session_send` that edited a repo, or for anything from an
 older version. The contract is yours; nothing is read from agent output.
 
+`verify_run` is a tool (plugin and MCP); it has no HTTP route or CLI command. It
+runs the checks once — no fix-on-red, no protected-tests check — and returns the
+bundle. Pass `baseSha` so `diff_policy` sees tracked changes, and `label` to name
+the stored evidence: the bundle is written to
+`~/.claw-orchestrator/wf/<label>/evidence/verify-01/`, and `clawo verify <label>`
+reads it back. A later call with the same label writes over it. It writes no ledger
+row and starts no workflow run.
+
 ## Three outcomes, not two
 
 A run ends `verified`, `refuted`, or `unverified`.
@@ -183,14 +232,21 @@ A run ends `verified`, `refuted`, or `unverified`.
 is not a failure and it is not a pass. `clawo runs` prints it as `—` and
 `clawo workflow list` as `unchecked`, and the `clawo runs` summary line says so in
 words, because collapsing it into either bucket would let an unchecked run read
-as a checked one. A verdict that expired (see below) also reads `unverified`.
+as a checked one. A verdict that expired (see below) also reads `unverified`, and
+so does a run that declared a contract and ended without running it — that run
+ends `failed`.
 
 ## What the guarantee is, precisely
 
 - The checks are run by the runtime, and their exit codes are read by the
   runtime. No part of the verdict is an agent's report about itself.
-- A run carrying a contract cannot reach `completed` unless every required check
-  passed.
+- A run whose verdict is `refuted` ends `failed`, never `completed`, and a run
+  ends `completed` / `verified` only when every required check of its last
+  verification passed. A run-level contract appends the terminal verifier
+  `__verify`, which every completed run passes through; a spec that places its own
+  `"contract": "run"` verifier has to route every path through it — a run that a
+  router steered past it ends `failed` (outcome `unverified`), see
+  [`workflow.md`](./workflow.md#completion).
 - If anything that can touch the workspace runs after the checks and the tree's
   **content** changes, the verdict expires: the outcome drops to `unverified`
   with the reason recorded. Not `refuted` — no check failed.