@enderfga/claw-orchestrator 7.5.3 → 7.5.4

package/skills/references/ultraapp.md

@@ -8,7 +8,7 @@ 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).
+in [`src/ultraapp/conventions.ts`](https://github.com/Enderfga/claw-orchestrator/blob/main/src/ultraapp/conventions.ts).
 
 ## When to use
 
@@ -32,15 +32,15 @@ interview ─► queued ─► building ─► build-complete ─► deploying
                                                                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. |
+| Mode             | Meaning                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------- |
+| `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.                                            |
+| `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.    |
 
 ### The build is a workflow run
 
@@ -73,17 +73,21 @@ state machine hidden inside it.
 ## 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. |
+super-task prompt verbatim from [`src/ultraapp/conventions.ts`](https://github.com/Enderfga/claw-orchestrator/blob/main/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 + type hierarchy, full async-state coverage, drag-and-drop forms, one deliberate theme; §7g screenshot gate (below).                                                                                      |
+
+**§7g:** every agent captures headless-Chrome screenshots at 1440×900 and
+375×812 and inspects them before voting YES; reading source code is not
+accepted as evidence.
 
 ## Runtime modes
 
@@ -128,29 +132,29 @@ persists to `~/.claw-orchestrator/host-procs.json`.
 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.                      |
+| 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.                                                  |
 
 ## 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).
+Windsurf, Goose). Param schemas in [`tools.md`](./tools.md#ultraapp-14).
 
 ```text
 ultraapp_list           ultraapp_get             ultraapp_status
@@ -165,11 +169,11 @@ 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           | 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".                                                                                                                                                              |
+| 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".                                                                                                                                                                               |
 
 To swap which version is live, use `promote-version` (HTTP) or
 `ultraapp_promote_version` (MCP) — the router map and host-procs map
@@ -177,8 +181,8 @@ update atomically.
 
 ## Reference traces + replay
 
-5 captured JSONL traces of real interviews ground-truth the interview
-engine against drift:
+5 reference interview traces (JSONL) pin the interview engine's
+output against drift:
 
 ```text
 src/__tests__/fixtures/ultraapp-traces/
@@ -192,8 +196,8 @@ src/__tests__/fixtures/ultraapp-traces/
 ```
 
 ```bash
-tsx scripts/test-ultraapp-integration.ts --trace=image-batch-resize
-tsx scripts/test-ultraapp-integration.ts --trace=all
+npx tsx scripts/test-ultraapp-integration.ts --trace=image-batch-resize
+npx tsx scripts/test-ultraapp-integration.ts --trace=all
 ```
 
 The `spec-extraction-quality.test.ts` test replays each trace through
@@ -218,11 +222,9 @@ open "http://127.0.0.1:18796/dashboard?token=$(cat ~/.openclaw/server-token)"
 curl http://127.0.0.1:19000/forge/<slug>/health
 ```
 
-## Acceptance contract (6.0.0)
+## Acceptance contract
 
-UltraApp is the one mode whose contract is on by default, because it already ran
-most of these commands and because two of its documented gates were not actually
-enforced.
+UltraApp is the one mode whose acceptance contract is on by default.
 
 **Build stage**, in the council's worktree:
 
@@ -230,10 +232,7 @@ enforced.
 npm install → npm run build → npm test → [docker build] → npm run smoke
 ```
 
-`npm run smoke` is new here. §4 of the architectural conventions has always told
-the council that the smoke test gates build success — it was never in the step
-list, so the claim was false. A codebase without a working `scripts.smoke` now
-fails its build, which is what the brief said all along.
+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
@@ -249,8 +248,7 @@ Evidence lands under the run directory:
 
 ### What the visual gate does and does not do
 
-It captures images and stores them, so "did anyone actually look" is now a file
-on disk instead of an agent's claim. It does **not** compare pixels — judging
+It captures images and stores them as run evidence. It does **not** compare pixels — judging
 the rendering is still a reader's job, and the §7g instructions in the council
 prompt remain the agents' responsibility.
 
@@ -259,13 +257,10 @@ app to a missing browser. Set `CLAWO_ULTRAAPP_VISUAL_GATE=strict` to make a
 failed capture block the deploy. Chrome is resolved from `CLAWO_CHROME_BIN`, then
 the usual macOS app paths, then `PATH`.
 
-## Durable build queue (6.0.0)
+## Durable build queue
 
 The build queue is persisted to `<store>/build-queue.json` and restored on
-startup. Its own comment used to say a restart mid-build meant "the build is
-marked failed and the user can rerun"; in practice nothing was marked — the
-pending list vanished along with any queued build the user was waiting on, with
-no record it had been asked for.
+startup.
 
 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
@@ -274,6 +269,6 @@ re-running is safe and continuing a half-built tree is not.
 ## Known limitations
 
 - The done-mode patcher loop occasionally hangs between
-  feedback-classification and the patcher Opus session creation;
+  feedback classification and the start of the patcher's Claude Opus session;
   cosmetic changes can be applied manually until the underlying race
   is fixed.

package/skills/references/verification.md

@@ -1,19 +1,10 @@
 # Verification — acceptance contracts and evidence
 
-Before 6.0.0, nothing in this runtime ever checked an agent's work. Every
-"finished" signal was the agent grading itself:
-
-- **Council** terminated when a regex found `[CONSENSUS: YES]` in agent prose.
-- **Autoloop**'s `eval_output` was whatever the Coder passed to a tool call, and
-  the Reviewer that was supposed to catch fabrication had a sandbox containing
-  the iteration's artifacts and no code, so it could not re-derive anything.
-- **UltraApp**'s frontend gate was a sentence in a persona string telling agents
-  to capture screenshots. There was no screenshot code anywhere in the project.
-- The run ledger's `ok` was the engine's report on its own turn.
-
-An **acceptance contract** is the opposite of all of that: a list of checks the
-runtime executes and whose results it reads. A run that declares one cannot reach
-`completed` unless every required check passes.
+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.
 
 ## The one rule about where contracts come from
 
@@ -55,24 +46,17 @@ Default true. A failing non-required check is recorded in the evidence bundle bu
 does not refute the run — use it for signals you want visible without making them
 blocking.
 
-(The predecessor of this module, `ultraapp/fix-on-failure.ts`, declared a
-`required` field on its steps and never read it: every step was fatal. It is
-honoured now.)
-
 ### Timeouts
 
-Every check has one, and the default is 10 minutes. This is not cosmetic — the
-old pipeline had no timeout at all, so a wedged `npm test` hung the build
-forever. A check that overruns is killed (its whole process group, with SIGKILL)
+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`.
 
 ### What `screenshot` does and does not claim
 
 It captures images and stores them. It does **not** compare pixels, and it is not
-visual regression testing. What changed in 6.0.0 is that the capture is performed
-by the runtime rather than requested of an agent — so "did anyone actually look"
-stops being a claim and starts being a file on disk. Judging the rendering is
-still a human's or an agent's job.
+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
@@ -85,8 +69,7 @@ kernel records `git rev-parse HEAD` when a run starts and diffs against that.
 
 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 — which is exactly how `autoloop`'s per-iteration `diff.patch`
-used to miss every new file while `git add -A` committed them anyway.
+invisible to it.
 
 `requirePaths: ["."]` means "the run must have changed something".
 
@@ -167,22 +150,16 @@ 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: **both §7g viewports captured** against the live URL. |
-| **Council**              | Caller-declared   | Consensus votes are recorded on the run as advisory and no longer decide completion.                                                                        |
-| **Autoloop**             | Caller-declared   | With a contract, a Reviewer `advance` is held unless the checks pass; passing also fires `on_target_hit`.                                                   |
-| **Fanout / Ultrareview** | Caller-declared   | Per-agent `ok` now reads the engine's terminal verdict rather than "the call did not throw".                                                                |
-| **Plain sessions**       | None              | Use `verify_run` to check work after the fact.                                                                                                              |
+| 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.                                                                                                                         |
 
-Two of UltraApp's defaults close claims the project had been making without
-backing them:
-
-- `conventions.ts` §4 told every council that `npm run smoke` gated build
-  success. It was not in the step list at all. It is now.
-- `ultraapp.md` recorded, as a known limitation since 4.0.0, that the §7g gate
-  "relies on per-agent honesty about running the screenshot capture", with a
-  server-side validator promised as a follow-up. That follow-up is this release.
+UltraApp's build gate includes `npm run smoke`, and its deploy gate captures
+screenshots at 1440×900 and 375×812 against the live URL.
 
 The visual gate is **advisory by default** so that a host without Chrome does not
 lose a working app to a missing browser. Set
@@ -203,15 +180,10 @@ older version. The contract is yours; nothing is read from agent output.
 A run ends `verified`, `refuted`, or `unverified`.
 
 `unverified` means **no contract was declared and nothing checked the work**. It
-is not a failure and it is not a pass. The CLI prints it as `—` and the summary
-line says so in words, because collapsing it into either bucket would let an
-unchecked run read as a checked one.
-
-## Related
-
-- [`workflow.md`](./workflow.md) — the kernel that runs verifiers as nodes
-- [`observability.md`](./observability.md) — how verdicts reach the run ledger
-- [`ultraapp.md`](./ultraapp.md) — the default contract in context
+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`.
 
 ## What the guarantee is, precisely
 
@@ -225,7 +197,6 @@ unchecked run read as a checked one.
 - Outside a git repository the digest is unavailable. Nothing running after the
   checks means the verdict stands; something running after it means we decline
   to vouch, and the run says so.
-
 - If an abandoned attempt (a node past its timeout, which cannot be killed) is
   still running when the run ends, the outcome is `unverified` with the reason
   recorded. The runtime will not vouch for a tree something may still be writing
@@ -236,3 +207,9 @@ A node past its timeout keeps running, and if it outlives the short settle
 window its writes land after the last digest — the run will have said
 `unverified`, but the file is still changed. Give such nodes a timeout they will
 not hit, or make their writes safe to arrive late.
+
+## Related
+
+- [`workflow.md`](./workflow.md) — the kernel that runs verifiers as nodes
+- [`observability.md`](./observability.md) — how verdicts reach the run ledger
+- [`ultraapp.md`](./ultraapp.md) — the default contract in context

package/skills/references/workflow.md

@@ -1,50 +1,18 @@
 # Workflow kernel — durable runs
 
 A durable executor for workflow runs: what is running, what happens when a step
-fails, when to stop, and — the part none of the previous state machines had — how
-to come back after the process dies.
+fails, when to stop, and how to come back after the process dies.
 
 ## Every mode runs on it
 
 `council_start`, `fanout_start`, `ultraplan_start`, `ultrareview_start` and
-`autoloop_start` all create a kernel run. Their tool signatures are unchanged and
-their result shapes are unchanged — `CouncilSession`, `FanoutSession`,
-`UltraplanResult`, `UltrareviewResult`, `AutoloopState` are now _projected_ from
-the run record rather than held in a map.
-
-The engines that do the work — `Council`, `Fanout`, the autoloop
-planner/coder/reviewer dispatcher — are untouched. What they lost is ownership of
-a lifecycle. Deleted along the way:
-
-| Gone               | Was                                                                              |
-| ------------------ | -------------------------------------------------------------------------------- |
-| 5 result maps      | `councils`, `fanouts`, `ultraplans`, `ultrareviews`, `autoloops`                 |
-| 4 eviction timers  | a 30-minute TTL per mode, three of them separate implementations                 |
-| 1 poller           | ultrareview asking the fan-out every 5s whether it had finished                  |
-| 2 fences           | `_startingAutoloops` / `_deletingAutoloops`, guarding a shared map               |
-| 2 disk enumerators | a regex over council markdown transcripts; a bespoke JSONL registry for autoloop |
-
-Concretely, three bugs went with them: a fan-out's results vanished 30 minutes
-after it finished; an ultraplan still running when its TTL fired was rewritten as
-`error: 'Timed out (TTL expired)'` and deleted, so a long plan could be destroyed
-by its own eviction timer; and ultrareview's correctness depended on the
-fan-out's TTL — evict first and its poll threw, the interval was cleared, and the
-review stayed `running` forever.
-
-## Why this exists
-
-Through 5.1.0 each mode carried its own machinery. The same "start in the
-background, poll by id, evict after 30 minutes" was written four separate times
-(`council`, `fanout`, `ultraplan`, `ultrareview`), with four timer sites and six
-status vocabularies that did not overlap. Cross-process listing was implemented
-three incompatible ways — council scraped its own markdown transcripts with a
-regex, autoloop read a JSONL registry, ultraapp walked a store directory.
-
-More to the point, most of it was not durable. A fan-out wrote nothing to disk at
-all and its results vanished after 30 minutes. Ultraplan and ultrareview were
-entirely in memory. A council that crashed mid-round left worktrees and branches
-on disk with no index pointing at them. UltraApp's build queue documented that it
-did not persist, so a restart mid-build failed the build.
+`autoloop_start` all create a kernel run. Their result shapes —
+`CouncilSession`, `FanoutSession`, `UltraplanResult`, `UltrareviewResult`,
+`AutoloopState` — are _projected_ from the run record.
+
+The mode engines (`Council`, `Fanout`, the autoloop planner/coder/reviewer
+dispatcher) do the work; the kernel owns lifecycle, persistence and listing. A
+run's record stays on disk until you delete it.
 
 ## Durability contract
 
@@ -92,75 +60,46 @@ names four things, and all four are checked on every durable write:
 - **`commit(guard, batch)` is the only way to change anything durable.**
   Checkpoints, events and node artifacts all go through it, inside one `O_EXCL`
   critical section that verifies the guard first. The raw writers are not
-  exported, so there is no path around it — the previous version stated this rule
-  in a comment while the engine wrote checkpoints directly from `start`,
-  `resume`, `publish` and `setChild`, and a rule enforced by a comment is not a
-  rule.
+  exported, so there is no path around it.
 - **A batch lands whole.** It is staged in a scratch directory and published by a
   single atomic directory rename; the rename is the commit point, and what
   follows is replayable application of an already-committed transaction. A reader
   finishes any transaction a crashed owner left, and applying is idempotent — the
   manifest records the event log's length from before, so recovery truncates and
-  re-appends rather than duplicating. Without this, `committed` meant "most of it
-  was attempted": the event append swallowed its own errors, so a checkpoint
-  could land with its events silently dropped, and a batch that failed partway
-  left the artifacts it had already written behind.
+  re-appends rather than duplicating.
 - **Creating a run and claiming it are one step.** The run directory is made with
   a non-recursive `mkdir`, which _is_ the claim — it fails for everyone but the
-  first caller. Asking `runExists()` and then creating is a check-then-write
-  race, and it lost: two processes creating the same id 80 times both "succeeded"
-  76 times, leaving one workflow executing under another's `spec.json`.
+  first caller, so two processes creating the same id cannot both succeed.
 - **The lock is exclusive, and release is not "unlink that path".** A vanished
   lock is retried rather than treated as stale debris; a genuinely stale one is
   broken by atomic rename; and a holder removes the lock file only if it is still
-  the one it created. Getting any of those wrong puts two callers in the section
-  at once, and the symptom is not an error — it is a committed transaction being
-  emptied by the other caller's cleanup, so writes vanish and the run wedges.
+  the one it created.
 - **A published transaction is authoritative before it is applied.** Readers
   finish any pending transaction first, and refuse rather than hand back the
   older checkpoint if it cannot be applied. Applying carries a marker written
   after the last data step, so a failure during cleanup cannot make a healthy
   transaction permanently unapplicable.
-- **The lock is exclusive, and release is not "unlink that path".** A vanished
-  lock is retried rather than treated as stale debris; a genuinely stale one is
-  broken by atomic rename; and a holder removes the lock file only if it is still
-  the one it created. Getting any of those wrong puts two callers in the section
-  at once, and the symptom is not an error — it is a committed transaction being
-  emptied by the other caller's cleanup, so writes vanish and the run wedges.
-- **A published transaction is authoritative before it is applied.** Readers
-  finish any pending transaction first, and refuse rather than hand back the
-  older checkpoint if it cannot be applied. Applying carries a marker written
-  after its last data step, so a failure during cleanup cannot make a healthy
-  transaction permanently unapplicable.
-- **`delete` claims before removing.** Releasing the lease first opened a window
-  in which another process could legally resume the run, only for this one to
-  remove the directory under its new owner.
+- **`delete` claims before removing**, so no other process can resume the run
+  while its directory is being removed.
 - **Contention is not a takeover.** `commit` reports `committed`, `superseded` or
   `blocked`, and only `superseded` is permanent. The lock waits briefly rather
   than failing on sight, and an owner that still cannot write stops _and hands
-  its claim back_ — because a live local pid is never judged stale, so a lease
-  left behind by a stopped run can never be taken over and the run is lost for
-  good. Collapsing the two into one boolean is what made a millisecond of
-  contention wedge a run permanently.
+  its claim back_ — a live local pid is never judged stale, so a lease left
+  behind by a stopped run could otherwise never be taken over.
 - **Copy-on-write.** A change is applied to a clone, committed, and adopted only
-  if the disk accepted it. So a superseded owner does not merely fail to
-  persist — the record it hands back to its own caller stops advancing too.
-  Refusing the write while returning a record that says `completed` is the same
-  claim one layer up, and callers read the record.
+  if the disk accepted it, so the record a superseded owner hands back to its
+  caller stops advancing too.
 - **A deleted run id is a new run.** The fence lives in `incarnation.json`, which
   survives `releaseLease` (so the counter never restarts while the run exists)
   and dies with the run directory (so the next run under the same id gets a new
-  random `incarnationId`). Without that, deleting a run and reusing its id reset
-  the fence to 1, and an abandoned attempt still holding fence 1 became valid a
-  second time — a textbook ABA, and not hypothetical, because a timed-out attempt
-  outlives its run by construction.
+  random `incarnationId`). An abandoned attempt from a deleted run therefore
+  cannot write into a new run that reuses its id.
 - **Re-acquiring supersedes.** A second claim, even by the same owner, mints a
   new `acquisitionId` and kills the previous guard.
 - **Owner identity is not the pid.** Two kernels in one process share a pid;
   each has its own owner id, or both would read the other's claim as their own.
-- **Atomic acquisition.** The check and the write happen inside the lock.
-  Read-then-write let two processes both see "free" and both conclude they had
-  it, which is the failure a lease exists to prevent.
+- **Atomic acquisition.** The check and the write happen inside the lock, so two
+  processes cannot both see "free" and both claim the run.
 - **An independent heartbeat.** Renewed on a timer, not only at checkpoints: a
   run executing one long node makes no checkpoints, and must not look abandoned
   for it. On the same host a live pid is the authority and is never judged stale
@@ -173,7 +112,8 @@ A second process trying to resume a run someone else is executing is refused by
 name, with the owner's pid and host in the message.
 
 One thing deliberately sits outside the guard: **evidence bundles**. They are
-written by the verifier as its checks run, under `evidence/<node>-<attempt>/`,
+written by the verifier as its checks run, under
+`evidence/<node>-v<visit>-<attempt>/`,
 and they are append-only artifacts, never read as state. What makes a bundle
 authoritative is the run record's `evidenceId` pointing at it, and that reference
 _is_ committed under the guard. So a bundle left behind by an owner that has been
@@ -205,7 +145,7 @@ Every node takes `retry: { max, backoffMs }`, `timeoutMs`, and
 On `fanout` and `council`, `timeoutMs` bounds the whole node and `agentTimeoutMs` one
 agent's send. They differ because agents beyond the free session slots wait for one, so
 the node can run several agents' worth of time. Without `agentTimeoutMs`, `timeoutMs`
-serves as both, as it did before the field existed. `fanout_start`, `ultrareview_start`,
+serves as both. `fanout_start`, `ultrareview_start`,
 `council_start` and the built-in `fanout`, `council` and `solve` workflows set both: the
 agent's own default, and a node bound for the worst case — one agent at a time, every
 retry taken.
@@ -235,8 +175,8 @@ next node**, so a gate that failed to match simply hands control to the router
 after it, which then matches on its own. Chaining reads as AND and behaves as
 "whatever the last router says".
 
-`maxNodeVisits` (default 50) bounds every loop as a backstop. Use `visits_lt` for
-the actual budget — the backstop failing a run is a bug report, not a feature.
+`maxNodeVisits` (default 50) bounds every loop as a safety backstop. Budget loops
+with `visits_lt`.
 
 ## Example: repair until green
 
@@ -288,7 +228,7 @@ test suite would double the most expensive part of the run to learn nothing new.
 `workflow_start` accepts `template` instead of `spec`:
 
 - **`solve`** — the shape above: triage → (optional human gate) → implement →
-  verify → repair-until-green → optional review.
+  (optional review) → verify → repair-until-green.
 - **`council`** — one council node, plus the implicit verifier when a contract is
   declared.
 - **`fanout`** — one fan-out node.
@@ -299,20 +239,13 @@ These are ordinary specs, not privileged paths.
 
 A passing verdict only stands while it still describes the tree.
 
-The digest is over **content**, not status: HEAD, the full `git diff HEAD`, and
-the bytes of every untracked file. An earlier version hashed
-`git status --porcelain`, which reports a file's state rather than its bytes — so
-a file already `M` before the checks and rewritten afterwards produced an
-identical digest, and the commonest case (an agent editing a file it had already
-edited) was the one it could not see.
-
 This cannot be enforced by inspecting the spec — a router can send control
 anywhere, so which node runs last is not a property of the graph. And "nothing
 may follow the verifier" would be the wrong rule anyway: what matters is not that
 a node ran, but that the tree moved. So the kernel measures. Each evidence bundle
-records a digest of the working tree (`git rev-parse HEAD` plus
-`git status --porcelain`), and when the run ends, if any workspace-touching node
-ran after the verdict, the digest is recomputed.
+records a content digest of the working tree (HEAD, the full `git diff HEAD`,
+and the path and bytes of every untracked file), and when the run ends, if any
+workspace-touching node ran after the verdict, the digest is recomputed.
 
 If it moved, the outcome drops from `verified` to `unverified` with the reason
 recorded on the run. Not `refuted` — no check failed; we simply stopped knowing,
@@ -323,9 +256,8 @@ checks means the verdict stands regardless (a contract that passed in a plain
 directory passed); something running after it means we cannot vouch, and the run
 says so.
 
-The built-in `solve` template puts its reviewer fan-out **before** the gate for
-this reason. It shipped the other way round first, which let reviewers edit a
-tree the verifier had already signed off while the run still reported `verified`.
+The built-in `solve` template puts its reviewer fan-out **before** the verifier,
+so anything the reviewers change is covered by the verdict.
 
 ## Completion
 
@@ -373,11 +305,12 @@ belong before the task.
 - Cancel and a node timeout are different things. A timeout is a node failure
   (it still gets its retries and still honours `onFailure`); cancelling ends the
   run.
-- Nothing prunes run directories. Delete them yourself, or with
-  `workflowDelete`.
+- Nothing prunes run directories. Delete them yourself
+  (`rm -rf ~/.claw-orchestrator/wf/<runId>`), or programmatically with
+  `SessionManager.workflowDelete(runId)`.
 
 ## Related
 
 - [`verification.md`](./verification.md) — contracts, checks, evidence
 - [`observability.md`](./observability.md) — how a run's verdict reaches the ledger
-- [`council.md`](./council.md), [`autoloop.md`](./autoloop.md), [`ultraapp.md`](./ultraapp.md) — the modes, and what changed for each
+- [`council.md`](./council.md), [`autoloop.md`](./autoloop.md), [`ultraapp.md`](./ultraapp.md) — the modes that run on the kernel