@iowarp/clio-coder 0.3.6 → 0.3.8

package/docs/fleet-dispatch.md

@@ -1,6 +1,6 @@
 # Fleet Dispatch
 
-> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.8).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -160,7 +160,7 @@ Use `clio-coder fleet resume [--json]` to reopen admission early. Detailed drain
 
 With no fleet configured and nothing requested, placement resolves to the
 implicit local path and optional fleet-node provenance may remain absent.
-Every new receipt uses strict integrity v15; older receipt formats are not
+Every new receipt uses strict integrity v19; older receipt formats are not
 accepted by the current reader.
 
 ## Failure semantics
@@ -202,8 +202,92 @@ request-level `autonomy` can only narrow the level (reviewers and judges run
 | Detached | `detach: true` | Return logical assignment ids and a batch id immediately; collect later. |
 | Review gate | `review: {reviewer?, max_cycles?}` | Builder, read-only reviewer verdict, bounded revise loop. |
 | Compete | `mode: "compete", candidates: 2..4` | N candidates in scratch worktrees, read-only judge, winner applied or preserved. |
+| Council | `mode: "council", roster: "design"` | Two to five read-only members answer the same task, with optional vote or judge synthesis. |
 | Agent automation | `agent: "auto"` | Baselines candidate agent from task shape via shared classifier (`coder`, `tester`, `documenter`, `verifier`, `researcher`, `scout`); advisory unless activated. |
 
+### Single-writer token
+
+A parallel batch may declare `writers: 1`. One is the only accepted value in
+this release, and omission retains ordinary parallel admission. The scheduler
+admits at most one write-scope step at a time. An agent step with a nonempty
+`writes` allowlist is a writer, as is a workspace-scope step that may mutate
+the checkout. Read-scope steps and agent steps with `writes: []` remain
+concurrent. Waiting writers follow the plan's declared step order and then the
+request order. Agent ledger claims remain advisory and do not enforce the
+token.
+
+The first checkout writer acquires a process-owned lease under the Clio state
+directory. Its key is the canonical checkout path, and its record contains the
+owner pid, process birth token, and acquisition time. A live sibling process
+causes admission to fail with `checkout_writer_lease_held` and the holder pid.
+A dead owner or reused pid is reclaimed. The lease remains held until the last
+writer settles, including writers collected from detached batches. Read-only
+runs never acquire it.
+
+### Worktree per task
+
+A singular writer or an item in `tasks` may declare `worktree: true` and
+`apply: "merge" | "preserve"`. The default is `merge`. Clio creates
+`.clio-coder/worktrees/<runId>/` on `clio/task/<runId>`, maps the worker cwd and
+protected artifacts into that checkout, and runs declared host verification
+there. The approved execution snapshot renders both fields and freezes the
+parent checkout as the merge destination.
+
+After a successful worker and successful host verification, merge application
+commits the task branch, rechecks protected paths, and uses the same guarded
+merge path as compete. A conflict fails closed with
+`worktree_merge_conflict` and preserves the branch and worktree. Preserve
+application never merges and reports the branch. A detached task applies when its run finalizes, so `monitor(mode="collect")` returns the sealed application receipt.
+Admission refuses a non-git checkout, a read-only agent, compete mode, or an
+explicit cwd outside the parent checkout with a named reason.
+
+### Typed intent and host-run verification
+
+The singular request and every object in `tasks` accept an optional `intent`:
+
+```json
+{
+  "read_roots": ["src/domains/dispatch"],
+  "write_roots": ["src/tools"],
+  "relevant_paths": ["docs/fleet-dispatch.md"],
+  "expected_outputs": ["dist/cli.js"],
+  "verification": [{ "check": "test", "timeout_ms": 600000 }]
+}
+```
+
+A top-level intent is inherited by batch items unless an item supplies its own
+intent. `gate: "test"` is exact shorthand for
+`intent.verification: [{check: "test"}]`; supplying both spellings is refused.
+Every path is normalized into a sorted, duplicate-free repository-relative
+POSIX path list before approval. Absolute paths, empty paths, root escapes,
+malformed entries, and values beyond the documented caps fail admission.
+Normalized `intent.writeRoots` feeds the existing worker write-boundary
+enforcement when no legacy `JobSpec.writeRoots` exists. Conflicting declarations
+are refused as `intent_write_roots_contradiction`.
+
+Verification values are declared check ids, never shell commands. Admission
+resolves each id from a package script or `.clio-coder/verifiers.yaml`, clamps
+the requested timeout to the declaration, and freezes the exact argv, cwd,
+timeout, and normalized intent into the execution snapshot and plan hash. A
+later catalog edit cannot change the approved command. Undeclared ids fail
+before approval with `verification_check_undeclared` and declaration guidance.
+
+After a successful worker attempt, the orchestrator runs the frozen checks with
+no shell, a fixed cwd, and the code-step environment allowlist. Logs are written
+under the run artifact directory. Successful evidence is memoized by the
+workspace fingerprint, resolved argv, cwd, and allowed environment values. A
+memo hit names the run that produced the original evidence. A changed tree is a
+miss. An unsuccessful worker records `hostVerification.status="skipped"` with
+`reason="worker_not_successful"`; a failed host check records `rejected` with
+its exit code, bounded output tail, and artifact path. Worker-reported command
+success never populates this status.
+
+Host checks are supported for singular, parallel, sequential, pipeline, and
+detached native runs. Review and compete accept intent paths and outputs but
+refuse verification entries with `verification_unsupported_for_mode`.
+Claude Code subprocess routes refuse them with
+`verification_unsupported_runtime`.
+
 ### Agent ledger
 
 Every topology that runs more than one worker at once opens an agent ledger, the
@@ -321,6 +405,42 @@ the workers are quiesced but the candidates remain until that output is bound
 to an integrity-verified judge receipt; a recovered winner is preserved for
 operator inspection rather than silently auto-applied after restart.
 
+### Council
+
+Council is the read-only sibling of compete. Two to five members run the same
+singular task concurrently on local HTTP or native targets. A request selects
+exactly one configured `workers.rosters` entry or supplies inline `members`.
+Admission pins every member to `read-only` autonomy and to the `read`, `grep`,
+`find`, `ls`, `code_nav`, and `context` tool surface. A route that resolves to
+an SSH fleet node is refused before approval. Council never creates a worktree
+and never mutates the workspace.
+
+Council supports one to three rounds. The first round gives every member the
+same task and briefing. A later round gives each member the other members'
+prior answers as labelled, untrusted briefing data. The member never receives
+its own prior answer. Each briefing is limited to 8 KiB and carries an explicit
+truncation marker when necessary. A failed peer contributes a labelled failure
+marker and no answer text.
+
+`synthesis: "none"` returns the final member answers directly. `vote` performs
+a deterministic majority tally over structured `verdict` fields without a
+model call. A vote council asks each member for that verdict: the member's task
+carries the ballot directive and the member's run seals a `council-ballot`
+postcondition, `{"verdict":"...","text":"..."}`, in place of the seated
+recipe's own result contract. The seated agent, its persona, and its read-only
+tool profile are unchanged, so any recipe can be voted with. The verdict is a
+single line of at most 64 bytes and is lower-cased before the tally, so members
+who reach the same conclusion land on the same key; the reasoning belongs in
+`text`, which is what the council report shows as the member's answer. A member
+that seals no conforming ballot fails its own run and is reported as a failed
+member rather than dropping silently out of the count. A vote with no majority
+reports `no_majority`, and a vote whose final members all failed reports
+`no_verdict_field`. `judge` runs one additional read-only judge against all final
+answers. Every member run seals a receipt. A judge receipt points backward to
+every final member receipt through gate provenance. The approval artifact names
+each member's label, target, model, thinking level, node, color, round count,
+and synthesis mode, so the plan hash binds the whole council contract.
+
 ### ExecutionPlan and plan approval
 
 Every orchestration shape compiles to one strict ExecutionPlan v2 DAG with
@@ -367,11 +487,36 @@ rejected.
 
 Clio ships three builtin fleet contracts under `src/domains/agents/fleets/`: `build-test`, `build-review`, and `sdlc`. Projects can declare custom fleet contracts or shadow builtin fleets by placing Markdown files under `.clio-coder/fleets/<name>.md`. A file named `.clio-coder/fleets/<name>.md` shadows a builtin fleet of the same name.
 
-Fleet contracts support schema versions 1 through 4:
+Fleet contracts support schema versions 1 through 5:
 - Version 1: Supports agent steps only.
 - Version 2: Introduces deterministic code steps.
 - Version 3: Adds bounded check/repair loops and commit steps with `commitFrom` message sources.
 - Version 4 (`FLEET_WRITE_BOUNDARY_VERSION = 4`): Introduces per-step declared write boundaries (`writes`) and orchestrator post-step enforcement.
+- Version 5 (`FLEET_DYNAMIC_STEP_VERSION = 5`): Adds plan steps, executable gate steps, per-step target or worker-profile defaults, and the optional single-writer declaration.
+
+#### Contract v5: plan, gate, and per-step target
+
+A version 5 agent step, including an agent loop check or repair, may declare either `target: <targetId>` or `profile: <workers.profiles key>`. It may never declare both. Fleet preflight resolves these values through the same worker routing used by `/run --target` and `/run --agent-profile`. An unknown value refuses before approval and names the target or profile. Versions 1 through 4 continue to refuse both fields.
+
+A `kind: gate` step asks its validator agent to write exactly one repository-relative `path`. The contract derives the step's write boundary from that path, so a separate `writes` property is refused. Its `run` property names a command whose argv contains one whole-token `{{path}}` placeholder. After the agent writes the executable acceptance check, the coordinator runs it without a shell against the otherwise untouched tree. A red result admits the gate. A green result refuses the run as `gate_not_discriminating`. The fleet ledger records the gate path hash. A loop may use `check: {kind: gate, gate: <stepId>}`. Only the bounded output lines beginning with `FAIL` cross that failed check edge into the repair agent.
+
+A `kind: plan` step defaults to the builtin `architect`. It declares `roster`, `maxTasks` from 1 through 16, an optional `proposals: true`, its own scope and write boundary, and an optional target or profile default. The architect returns a `delegation-plan` object whose tasks contain `id`, `agent`, `description`, `depends_on`, `writes`, and an optional `mode` of `sequential` or `parallel`. The coordinator admits only roster agents, unique and acyclic task ids, resolvable dependencies, the declared task count, and task writes contained by the plan step boundary. Successful tasks carry lineage to the plan step and inherit its target or profile. A contract with `writers: 1` serializes write tasks through the existing single-writer token.
+
+When `proposals: true`, every roster member first runs with read-only autonomy against the same task. Their answers reach the architect as labelled, bounded briefing data. Proposal agents do not choose targets for generated work. The plan step's contract default remains authoritative for every admitted task.
+
+### Fleet authoring
+
+The fleet CLI provides five authoring and inspection operations:
+
+- `clio-coder fleet new <name> --from <builtin>` copies one of `build-review`, `build-test`, or `sdlc` into `.clio-coder/fleets/<name>.md`. The command requires a safe file stem and refuses to replace an existing contract.
+- `clio-coder fleet validate <name> [--json]` parses the contract, validates its graph and command bindings, resolves every agent, and compiles the execution plan. It creates no state directory, ledger row, reservation, worker, or receipt.
+- `clio-coder fleet graph <name> [--json]` renders the compiled waves with each step kind, agent or command, scope, and write boundary. Bounded loops also show their check and repair nodes beneath the loop identifier.
+- `clio-coder fleet commands init` discovers declared package scripts, just recipes, Makefile targets, and supported `pyproject.toml` script and tool entries. It writes a fully commented `.clio-coder/fleets/commands.yaml` draft. Uncommenting an entry confirms its exact argument vector, and an existing registry is never replaced.
+- `clio-coder fleet run <name> --resume <runId>` starts a new fleet run after replaying the successful, integrity-valid prefix recorded for the named prior fleet run.
+
+Run resumption is separate from `clio-coder fleet resume`, which continues to reopen dispatch admission after an operator drain. A resumable fleet run records its contract name, rendered plan hash, ordered step identifiers, variables, and receipt references in the durable fleet ledger. Runs started from the TUI through `/fleet run` use the same durable record and can be resumed by the authoring CLI. The new run records the prior fleet run as its resume parent. Replayed steps are reported as `replayed`, retain their original receipt or code-report references, and do not create new receipts.
+
+The current contract must compile to the same plan hash. A mismatch refuses before execution and prints the changed positions in the ordered step list. Variables must exactly match the original run. A different value, an added value, or an omitted value is refused even when the resulting task text would otherwise be similar.
 
 ### Per-step write boundaries (Contract v4)
 
@@ -386,12 +531,14 @@ The grammar for declared write boundary entries requires repository-relative POS
 Write boundary enforcement is detect-and-rollback, never OS or filesystem sandboxing. A step runs with whatever filesystem permissions its underlying execution environment possesses. Upon step completion, the orchestrator inspects the working tree to verify compliance:
 1. Snapshot baseline: Before a step executes, the orchestrator captures a snapshot (`captureWorkspaceSnapshot`) recording the baseline git HEAD commit and existing dirty path content tokens.
 2. Workspace diffing: After step completion, the orchestrator runs git status inspection (`diffWorkspace`) to identify changed paths relative to the snapshot baseline commit.
-3. Rollback execution: Unauthorized changes (modified paths not covered by the step's declared allowlist) are automatically rolled back (`rollbackPath`).
-4. Content source: Rollback restores content strictly from what git already has in the pinned baseline commit (`snapshot.head`). If a path was already dirty when the step snapshot was captured, its prior content is not stored in git, so in-place restoration cannot be guaranteed. The working tree is left as the step made it, and the status settles as `rollback-incomplete`.
-5. Violation handling: Any unauthorized change fails the step with the typed reason `writes_boundary_violation`.
-6. Window attribution: Enforcement evaluates scheduling windows (`wave-<n>` or `revalidate-<stepId>-<n>`). A wave window cannot combine steps with overlapping declared boundaries or multiple concurrent step writers, ensuring single-step attribution.
-7. Ignored paths and state subtraction: Enforcement evaluates paths reported by git status. Git-ignored paths remain outside enforcement. The Clio state directory (`.clio-coder/` or `clioStateDir()`) is subtracted from status checks so orchestrator receipts, code step log artifacts, and boundary verdicts do not trigger false violations.
-8. Durable records: Verdicts are serialized as JSON records at `write-boundaries/<rootId>/<window>.json` under the Clio state directory, carrying the baseline HEAD commit, checked paths, violations, rollback actions, status, and SHA-256 digest.
+3. Authorship attribution: A changed path outside the allowlist is blamed on the window only when it intersects what the window's own runs recorded writing. That record is the run's tool-call stream, folded by the same recorder that grounds a sealed mutation report and read back through `DispatchContract.observedRunWrites`. A change that no run in the window recorded is an unattributed concurrent change: it is listed under `unattributed` in the verdict and reported to the operator, and it is never rolled back. This is what keeps a file an operator edited while a fleet ran from being overwritten with its committed version.
+4. Open records: A run's recorded write set is read as a closed list only when the run could not have written outside it. A window whose steps do not all offer a closed record falls back to blaming every change outside the allowlist, which is the behavior that predates attribution. Three things open a record: a `kind: code` step, whose registered command publishes no tool events; a run whose tool telemetry coverage is not `complete`, such as one on a subprocess runtime; and a run that made a successful call to a tool able to mutate a path its own arguments do not name. That last set is derived from the tool surface rather than authored, as every registered tool outside the `read` and `write` action classes, which today is `bash`, `verify`, `dispatch`, and `steer`, plus any dynamic or MCP tool whose schema this process cannot read. The `git` tool is a closed status, diff, and log surface and stays enumerable. The verdict records `attributionComplete: false` and the operator-facing detail says the blame was inferred from the checkout rather than from the step's own record.
+5. Rollback execution: Attributed unauthorized changes are automatically rolled back (`rollbackPath`).
+6. Content source: Rollback restores content strictly from what git already has in the pinned baseline commit (`snapshot.head`). If a path was already dirty when the step snapshot was captured, its prior content is not stored in git, so in-place restoration cannot be guaranteed. The working tree is left as the step made it, and the status settles as `rollback-incomplete`.
+7. Violation handling: Any attributed unauthorized change fails the step with the typed reason `writes_boundary_violation`.
+8. Window attribution: Enforcement evaluates scheduling windows (`wave-<n>` or `revalidate-<stepId>-<n>`). A wave window cannot combine steps with overlapping declared boundaries or multiple concurrent step writers, ensuring single-step attribution.
+9. Ignored paths and state subtraction: Enforcement evaluates paths reported by git status, which never lists a git-ignored path. A declared `writes` entry the repository ignores is therefore refused before anything runs, by `fleet validate`, by `fleet run` preflight, and by the `/fleet run` preview, with a diagnostic naming the entry and the ignoring rule (for example `'work/' is ignored by .gitignore:1:work/`). Silently certifying such a window as clean is not an option, because nothing about it was observed. The Clio state directory (`.clio-coder/` or `clioStateDir()`) is subtracted from status checks so orchestrator receipts, code step log artifacts, and boundary verdicts do not trigger false violations.
+10. Durable records: Verdicts are serialized as JSON records at `write-boundaries/<rootId>/<window>.json` under the Clio state directory, carrying the baseline HEAD commit, checked paths, violations, unattributed concurrent changes, the attribution completeness flag, rollback actions, status, and SHA-256 digest.
 
 ### Bounded check/repair loops
 
@@ -432,7 +579,10 @@ commands:
     argv: ["npm", "run", "build"]
     timeoutMs: 600000
   commit:
-    argv: ["git", "commit", "-m"]
+    argv: ["git", "commit", "-m", "{{commitMessage}}"]
+    timeoutMs: 60000
+  acceptance:
+    argv: ["node", "{{path}}"]
     timeoutMs: 60000
 ```
 
@@ -443,6 +593,8 @@ Each command entry supports:
 - `env` (optional): Array of extra environment variable names to pass through on top of `FLEET_COMMAND_BASE_ENV` (`PATH`, `HOME`, `LANG`, `LC_ALL`, `TZ`, `TMPDIR`).
 - `description` (optional): Human-readable description.
 
+The whole-token `{{commitMessage}}` substitution is available to commit steps. The whole-token `{{path}}` substitution is available to version 5 gate commands. Each substitution becomes exactly one argv element and never passes through a shell.
+
 
 ## Measured route selection and agent automation
 
@@ -526,10 +678,23 @@ assignment failed, reports the reason on stderr, and records it in the
 assignment's `outcomeDetail`.
 
 Assignment status, attempt ids, and terminal run id are stored separately in
-`assignments.json` while each attempt keeps its own strict v15 receipt.
+`assignments.json` while each attempt keeps its own strict v19 receipt.
 Pipelines and batches await assignment terminals, so downstream stages consume
 the successful fallback output rather than an earlier failed attempt.
 
+A fleet run is the exception to "the attempts settle the record". Every step of
+a fleet dispatches under the fleet root id as its lineage root, so all of them
+share one row, and no single step is the run's verdict. The run claims the row
+by writing `verdictOwner: "fleet"` when it opens, files every settled step's
+terminal run id in `attempts` (an agent step's receipt id, a code step's
+`code-*` run id, whose report sits under `code-steps/<fleetRootId>/`), and
+writes `status` once at the end from the whole-run outcome. Until then the row
+stays `running`, and a step settling under it records its attempt without
+touching the status. A run that stops before its last step, whose final step
+fails, or that throws is `failed`; a run abandoned by a crashed process is
+reconciled to `failed` at the next startup rather than inheriting a green
+step's success.
+
 Editing assignments also own one baseline-pinned workspace transaction. Every
 attempt gets a distinct worktree. Before any winning diff can reach the
 destination checkout, a pure gate checks terminal outcome, receipt integrity,
@@ -540,7 +705,7 @@ closed while a winner remains unapplied.
 
 ## Receipts
 
-Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 15`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical verification path: any other version is invalid, and a receipt that fails verification is never read as evidence. The fleet provenance fields covered by the digest
+Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 19`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical verification path: any other version is invalid, and a receipt that fails verification is never read as evidence. The fleet provenance fields covered by the digest
 include:
 
 - `node`: the fleet node the worker ran on (`id`, `kind`, `host`). The `node.id` explicitly identifies the worker process host executing the task, not the model host (which is represented by the `target` id). This behavior tracks issue #120.
@@ -551,11 +716,22 @@ include:
   approval kind, and the registry approval identity when supervised).
 - `briefing`: byte count and SHA-256 of the exact canonical parent briefing;
   the prose is not retained and is distinct from bounded project context.
+- `intent`: the normalized typed path, expected-output, and verification
+  declaration that admission sealed for the run.
+- `verification`: the existing evidence state and basis observed from worker
+  tool execution.
+- `hostVerification`: host-run status and the resolved check evidence, including
+  argv, cwd, exit code, duration, memo provenance, bounded output tail, and
+  optional artifact path.
+- `worktree`: task worktree path, branch, diff hash, requested application,
+  applied status, and an optional closed failure reason.
 - `steering`: ordered byte/hash/timestamp and acknowledgement provenance for
   successfully written steers; steering prose is never stored.
 - `outcomeCode`: the stable terminal classifier, including
   `worker_final_output_missing` when an otherwise successful worker exits
-  without a nonempty receipt-sealed final answer.
+  without a nonempty receipt-sealed final answer and
+  `host_verification_rejected` when a declared host check rejects the settled
+  tree. Both suppress automatic retry.
 - `routingIntent`, `routeDecision`, and `quality`: the normalized hard bounds,
   complete current-policy decision, exact execution role, route estimate and
   readiness evidence, and authenticated quality sources.
@@ -575,11 +751,14 @@ retained only as `state: "partial"` diagnostics and automatic retry is
 suppressed. Dispatch, monitor, ledger, receipt, terminal bus event, and retry
 policy all consume that same final classification.
 
-Receipt integrity and evidence verification are separate axes. Integrity says
+Receipt integrity, host verification, and evidence verification are separate axes. Integrity says
 that the sealed receipt matches its ledger envelope; evidence verification
 reports whether Clio observed an applicable validation tool (or marks the
-basis unknown/not applicable). A read-only Scout can therefore report `receipt_integrity=verified/v15/sha256` alongside
-`evidence_verification=not_applicable/read-only-agent`. Briefing provenance and
+basis unknown/not applicable). A read-only Scout can therefore report `receipt_integrity=verified/v19/sha256` alongside
+`evidence_verification=not_applicable/read-only-agent`. Host verification is
+rendered independently as `host_verification=verified|rejected|skipped|not_requested`.
+A host-executed successful check projects onto canonical validation grounding as
+authenticated validator evidence. Briefing provenance and
 bounded `project_context` provenance are also rendered independently; neither
 hash substitutes for the other.
 
@@ -689,6 +868,39 @@ hard block.
 - `/fleet` opens Settings → Fleet: profiles (with the node pin), bindings,
   and read-only node rows (state, capacity, and last-seen). Running and
   retrying runs, with their node, live in the `Alt+W` Fleet Runs board.
+- `/fleet run <name> [--var k=v ...]` compiles the contract's plan and opens
+  the approval overlay before anything dispatches. The overlay lists the steps
+  grouped by wave, and for each step its kind, its agent and resolved target
+  (or its command id and the exact argv from `commands.yaml` for a code step),
+  its scope, and its declared write boundary, followed by the budget ceiling
+  the run would be admitted under. Enter dispatches the plan through the same
+  path `clio-coder fleet run` uses, so admission, autonomy, receipts, and the
+  durable ledger are identical. Esc cancels with nothing dispatched and nothing
+  written. A contract that fails preflight opens the same overlay with its
+  diagnostics and no accept key. A turn in flight refuses the command with a
+  notice rather than queueing it: an approved plan describes the workspace as
+  it stands.
+- A council is one question asked of several members, so its rows render as one
+  card rather than as three to five unrelated neighbours. On the `Alt+W` board the
+  members sit side by side, one column each, as long as every column keeps at
+  least 34 cells; below that the whole group stacks one member under another
+  rather than squeezing some columns and not others. Each column carries the
+  member label in its roster color (a member with no color takes the accent), the
+  target and model, the round, the status, and the same bounded answer tail the
+  run's own card would show. The synthesis run takes the full width under the
+  members, because it is the council's answer rather than one voice in it. A
+  council that ran several rounds still shows one column per member: each label
+  keeps its newest round, so the card describes the council rather than its
+  history.
+- The compact Fleet Runs island shows a council as one card naming the group, how
+  many members are seated, and which round they are on. The grid belongs to the
+  board, where there is width to read an answer in. `/share` is what moves a
+  council answer into the main agent's context; the card moves nothing.
+- Board rows a fleet plan dispatched carry a phase column naming the step's
+  wave index and step id (`w2 build`). A run that is not a fleet step renders
+  the column empty. The compact Fleet Runs island keeps its fixed width, so it
+  shows the column only when the row can still hold a readable agent label;
+  otherwise the phase appears on the expanded card.
 - The monitor tool reports the node and reroute lineage on `status`, `list`,
   and `collect`.
 - `clio-coder fleet status [--json]` shows the durable ledger view cross-process.

package/docs/git-commit-provenance.md

@@ -49,11 +49,11 @@ Co-authored-by: Clio Coder <clio-coder@iowarp.ai>
 Existing human trailers stay in place. A Clio trailer already present in any
 letter case is respected rather than repeated, line endings are normalized only
 while attribution is enabled, and repeated processing is idempotent. When a directly relevant
-receipt-v15 digest passes integrity verification, Clio may additionally add the
+receipt-v19 digest passes integrity verification, Clio may additionally add the
 full digest:
 
 ```text
-Clio-Evidence: receipt-v15/sha256:<64-character digest>
+Clio-Evidence: receipt-v19/sha256:<64-character digest>
 ```
 
 Clio does not invent, shorten, or add an unrelated digest. The role trailers do

package/docs/glossary.md

@@ -1,6 +1,6 @@
 # Clio Coder Glossary
 
-This document defines the 45 core architectural concepts and terminology used throughout Clio Coder, mapped to their authoritative TypeScript type definitions in `src/`.
+This document defines the 50 core architectural concepts and terminology used throughout Clio Coder, mapped to their authoritative TypeScript type definitions in `src/`.
 
 ---
 
@@ -28,7 +28,7 @@ This document defines the 45 core architectural concepts and terminology used th
 
 ### 6. Receipt
 - **Definition**: An immutable, cryptographically sealed record of a completed run containing full execution facts, tool telemetry, token accounting, validation grounding, and outcome codes.
-- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 15`).
+- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 19`).
 
 ### 7. Envelope
 - **Definition**: A bounded container enforcing byte-length limits and truncation indicators on a dynamic payload. Tool output carries shown and total byte counts plus a continuation fragment; a parent briefing carries byte count and SHA-256 content hash instead.
@@ -185,3 +185,23 @@ This document defines the 45 core architectural concepts and terminology used th
 ### 45. Marker
 - **Definition**: The byte-stable one-line stub the projection renders in place of an evicted body, naming the ref, the reason, the tool, the size, and the exact recall call. It carries no timestamp and no counter, because a marker whose bytes drifted between renders would cold-start the prefix cache on a turn that evicted nothing new.
 - **Owning Type**: `renderMarker` in `src/domains/context/working-set/marker.ts`.
+
+### 46. Canonical Trust Status
+- **Definition**: The six-axis record of what is known about one run: artifact integrity, validation grounding, independent review, context provenance, autonomy enforcement, and completion evidence. It is an algebra, not a score: no axis promotes another, every non-absent state names its source and authority, and `absent`, `unknown`, and `not_applicable` are states in their own right. See [docs/evidence-and-memory.md](evidence-and-memory.md#canonical-trust-status) for the full state table.
+- **Owning Type**: `CanonicalTrustStatus` in `src/domains/evidence/trust-status.ts`.
+
+### 47. Trust Projection
+- **Definition**: The one rendering of the canonical trust status every operator surface prints. The compact human line answers who claims the result, what was observed, what was independently checked, and what is still unknown, in six fixed clauses (`sealed; grounded by host-verification; not independently reviewed; mediated; context recorded; completion evidenced`). The machine projection is the same answer as a bounded, versioned record with references to the detailed artifacts. Dispatch and monitor output, `evidence inspect`, `findings.md`, the Alt+W board, the receipt view, the eval bridge, and the ACP wire all print from it.
+- **Owning Type**: `formatTrustSummary` and `TrustSummaryProjection` in `src/domains/evidence/trust-projection.ts`.
+
+### 48. Trust Verdict
+- **Definition**: The presentation tier read off the axes in a fixed order, used for styling and sorting and never as a score. `reviewed` requires an authenticated independent pass and is the only tier styled as independently verified. `grounded` is observed validation without independent review. `unverified` is a sealed receipt with nothing observed. `compromised` is a broken seal, a bypassed gate, a failed or inferred validation, a failed or correlated review, or a contradictory context record. `unknown` is an unchecked or missing seal.
+- **Owning Type**: `TrustVerdict` and `trustVerdict` in `src/domains/evidence/trust-projection.ts`.
+
+### 49. Trust Vocabulary
+- **Definition**: The standardized word for each canonical state, so the same fact is never spelled two ways. `sealed` means the receipt authenticated against the ledger row; it says nothing about correctness. `grounded` means validation was observed to run and pass, named by its claimant (`host-verification`, `validation-tool`, `receipt-quality`, `evidence-grounding`). `independently reviewed` means an authenticated reviewer that was not the run itself recorded a verdict. `inferred` means the worker claimed validation and nothing was observed to have run. `mediated` is the word for the `enforced` autonomy state: Clio's own safety gate mediated the run. `approximated` and `bypassed` name an external runtime's enforcement, always with the runtime's id. `unknown` means a named source could not answer; `not applicable` means a named authority decided the axis does not apply.
+- **Owning Type**: `TRUST_STATE_WORDS` in `src/domains/evidence/trust-projection.ts`.
+
+### 50. Commonly Confused Trust States
+- **Definition**: `sealed` is not `grounded`: a receipt can authenticate perfectly and describe a run that validated nothing. `grounded` is not `independently reviewed`: a host check is Clio observing the run's own declared command, not a second agent judging the result. A `host checks verified` unit on the board is folded into validation grounding and is never independent review. `mediated` and `enforced` are one state under two names, the receipt grade and the canonical id. `not_requested` is not a trust state at all; a run with no host check reads `no validation observed`. `completion unevidenced` (a mutation finished with no validation at the completion boundary) is distinct from `no validation observed` (no validation was linked anywhere in the run): the first is the finish contract's observation, the second the evidence linker's.
+- **Owning Type**: `TRUST_STATE_WORDS` and `trustVerdict` in `src/domains/evidence/trust-projection.ts`; the axis states in `TRUST_STATUS_STATES` in `src/domains/evidence/trust-status.ts`.

package/docs/installation-and-lifecycle.md

@@ -3,7 +3,7 @@
 Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.6). You can open it directly in any web browser to view details dynamically.
+> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.8). You can open it directly in any web browser to view details dynamically.
 
 ---
 
@@ -229,7 +229,7 @@ Upgrading from 0.3.1 to 0.3.3 is automated:
 clio-coder upgrade
 ```
 
-Key lifecycle and operational updates in v0.3.6:
+Key lifecycle and operational updates in v0.3.7:
 - Upgraded the underlying engine SDK libraries to 0.84.0 with signal-aware OAuth cancellation.
 - Hardened migration resilience: damaged `credentials.yaml` files no longer block upgrades when no renames are needed (#121); `--skip-migrations` is available as a recovery override.
 - Fullscreen TUI mode (`terminal.tuiMode`, `terminal.fullscreenScrollbar`) is available via Settings → Terminal (restart required). Adaptive presentation pacing is the live `terminal.smoothStreaming` setting; 0.3.3 defaults it to `off`, with conservative `auto` and explicit `on` available from the same section.

package/docs/middleware-and-components.md

@@ -1,7 +1,7 @@
 # Middleware and Component Registry
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.8).
 
 Clio Coder has two related but separate surfaces:
 
@@ -129,6 +129,7 @@ These ship in every interactive session. Each is one bounded behavior with a vis
 | `nudge.detached-dispatch` | `turn_end` | A settled turn that ends while a detached dispatch batch has every run terminal and uncollected is continued once, naming the ready batches; `monitor mode="collect"` clears it, including across resume. Batches with runs still in flight, and surfaces without `monitor`, do not trigger. |
 | `nudge.read-only-exploration` | `after_tool`, `turn_end` | After nine or more read-only calls (`read`, `grep`, `find`, `ls`, `code_nav`, read-only shell) in one user turn without a successful Scout dispatch, injects one advisory to delegate broad reconnaissance to Scout. One advisory per user turn, and only on surfaces that have `dispatch`. |
 | `rail.unbacked-worker-claim` | `after_tool`, `turn_end` | A reply that reports worker or Scout results in a turn with no `dispatch` call gets one warning that the claim is not backed by a receipt. A `[worker result]` note the operator shared is receipt-backed and exempt. No continuation: the operator decides. |
+| `observer.watchdog` | `after_tool`, `turn_end` | Opt-in through `watchdog.enabled` (default off). A turn that changed the tree is reviewed by one read-only `verifier` dispatch briefed with the turn's coalesced diff (per-path last-write-wins, bounded to 12 KiB) and the task board's current scope. Its failed checks become one transcript notice naming the count and the first three; a passing report emits nothing. `watchdog.cadenceToolCalls: N` also fires it every N tool calls inside the turn. One run in flight at a time; an overlapping trigger is dropped and counted. It emits no middleware effects, never continues a turn, and never mutates. Turns with no file mutations, headless runs, and ACP runs never fire it. |
 | `observer.memory-intervention` | `after_tool` | Every `memory.intervention.everyNTools` tool calls, asks a background model for a bounded reflection over the recent window and injects it as a reminder when it arrives. Governed by the `memory.intervention` settings block. |
 
 Two coded controls sit beside the registrations rather than among them. `tool-choice-control` turns `require_tool` and `lock_tools` effects into the provider's tool-choice field for the next round: a required tool clears when that tool starts, a lock lasts until the next submitted turn and outranks later requirements. `hook-receipts` is the durable ring (200 entries, throttled to one write per two seconds) of user-defined hook executions that `clio-coder config inspect` reads.

package/docs/model-catalog.md

@@ -1,7 +1,7 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.8).
 
 Clio Coder treats a selectable model as the intersection of three sources:
 

package/docs/observability.md

@@ -1,7 +1,7 @@
 # Observability Viewer
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.8).
 
 `/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
@@ -57,6 +57,53 @@ An `EvidenceIndexRow` has the following schema:
 
 ---
 
+## Cross-Session Usage Facts
+
+`clio-coder usage report` folds the local archive into one window of facts. Its token and cost facts come from two inputs: the per-session ledgers, folded through the session domain's `ledgerUsageCalls`, and the out-of-turn usage store described below. Both the text report and `--json` carry the same fields.
+
+| Field | Where it appears | Meaning |
+| --- | --- | --- |
+| `apiCalls` | `tokens in window: <total> over <n> model calls` and the `tokens` JSON fact | Provider calls folded in the window, out-of-turn rounds included. |
+| `input`, `output`, `cacheRead`, `cacheWrite`, `reasoningTokens`, `totalTokens` | the same line and fact | Provider-reported token breakdown for those calls. |
+| `costUsd` | `provider-reported cost in window` and the `tokens` fact | Provider-reported cost. Never estimated. |
+| `turns` | `turns in window` and the `tokens` fact | Folded calls that were turns, so labelled calls are subtracted exactly as `/cost` subtracts them. |
+| `sideQuestions` | `side questions in window` and the `tokens` fact | `/btw` rounds in the window. |
+| `handoffs` | `handoffs in window` and the `tokens` fact | `/handoff` extraction rounds in the window. |
+
+The last three fields appear only when at least one labelled call falls in the window. An archive with no `/btw` or `/handoff` round in it renders exactly as it did before those fields existed, so their presence is itself the signal that money was spent beside a session.
+
+### The Out-of-Turn Usage Store
+
+A `/btw` side question and a `/handoff` extraction round are real provider calls that append nothing to the session JSONL, by design: a fleet run briefs its workers from the transcript, and a question the operator asked to orient themselves must not become context those workers inherit. The spend still has to be recorded somewhere durable, so it goes to `<stateDir>/usage/out-of-turn.jsonl`, one JSON line per priced call, written by the chat loop at the same moment it reports the call to `/cost`.
+
+The file is append-only NDJSON kept as a bounded ring (capped at 1000 rows, rewritten atomically under the shared state-file lock when it grows past the cap). Reads are tolerant: a malformed line is reported as a diagnostic on stderr and skipped.
+
+A row has the following schema:
+```json
+{
+  "label": "side-question",
+  "sessionId": "01JQ2K7V8W",
+  "repoIdentity": "9f2c1b4ea77d0c31",
+  "timestamp": "2026-06-25T14:30:00.000Z",
+  "target": "dynamo",
+  "attributedModelId": "Nemo-3.5",
+  "usage": {
+    "input": 120,
+    "output": 8,
+    "cacheRead": 4,
+    "cacheWrite": 0,
+    "reasoning": 2,
+    "totalTokens": 132,
+    "costUsd": 0.0004,
+    "costProvenance": "known"
+  }
+}
+```
+
+`repoIdentity` is the same cwd hash the session ledger is filed under, which is what lets `usage report --repo <path>` select these rows with the hash it already computes for the ledgers.
+
+---
+
 ## Artifact Categories and Path Layouts
 
 Clio resolves directories under platform-specific XDG defaults (on Linux, these default to `~/.config/clio-coder/`, `~/.local/share/clio-coder/`, and `~/.local/state/clio-coder/`).
@@ -109,17 +156,17 @@ Pressing `v` on a selected receipt or running `/view verify <runId>` performs cr
 
 1. **Read Receipt**: Reads the receipt JSON from `<stateDir>/receipts/<runId>.json`.
 2. **Resolve Ledger**: Looks up the run envelope inside `<stateDir>/runs.json`.
-3. **Verify Integrity**: Recomputes the SHA-256 digest over the strict v15 receipt and reconstructible ledger fields. The digest covers every current field, including steering, routing intent and decision, route quality, worker identity, execution role, and result-contract conformance. Every version other than 15 fails verification; there is no historical receipt reader.
+3. **Verify Integrity**: Recomputes the SHA-256 digest over the strict v19 receipt and reconstructible ledger fields. The digest covers every current field, including steering, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance. Every version other than 19 fails verification; there is no historical receipt reader.
 4. **Report Result**: The viewer reports `ok` or the verification failure reason. It does not rename or delete the receipt. Startup orphan recovery may quarantine corrupt orphan receipt files as `<name>.json.corrupt`, but `/view verify` is read-only.
 
 ---
 
 ## Receipt Fields for Dispatch Provenance
 
-A receipt carries optional provenance and context blocks that answer "what happened" for a chained (pipeline), composed (persona override), escalated, briefed, steered, or external run. Those optional blocks remain absent when unused. Current receipts carry strict integrity v15 and an explicit `outcomeCode: null` when no classified deterministic failure occurred. Automation consumers must treat the optional blocks below as absent by default and `outcomeCode` as nullable; older receipt versions are invalid.
+A receipt carries optional provenance and context blocks that answer "what happened" for a chained (pipeline), composed (persona override), escalated, briefed, steered, council, or external run. Those optional blocks remain absent when unused. Current receipts carry strict integrity v19 and an explicit `outcomeCode: null` when no classified deterministic failure occurred. Automation consumers must treat the optional blocks below as absent by default and `outcomeCode` as nullable; older receipt versions are invalid.
 
 Receipt integrity verification and evidence verification are independent.
-`receipt_integrity=verified/v15/sha256` means Clio called the receipt verifier
+`receipt_integrity=verified/v19/sha256` means Clio called the receipt verifier
 against the ledger envelope; merely finding an embedded digest is not enough.
 `evidence_verification=<verified|unverified|not_applicable|unknown>/<basis>`
 describes validation evidence inside that verified receipt. Likewise,
@@ -128,9 +175,9 @@ describes validation evidence inside that verified receipt. Likewise,
 message. Model-facing dispatch and collect output name all four concepts
 separately and never substitute one hash for another.
 
-The evidence bundle renders these sets in `transcript.md` (human sentences) and `trace.cleaned.jsonl` (structured run rows), `clio-coder evidence inspect` prints them as a `provenance <runId>:` block, and the `dispatch` tool appends a compact suffix to each run line plus additive keys on `details.runs[]`. A timed-out or denied escalation also raises an `escalation` finding in the bundle.
+The evidence bundle renders these sets in `transcript.md` (human sentences) and `trace.cleaned.jsonl` (structured run rows), `clio-coder evidence inspect` prints them as a `provenance <runId>:` block, and the `dispatch` tool appends a compact suffix to each run line plus additive keys on `details.runs[]`, including `trust`, the bounded canonical trust projection described in [evidence-and-memory.md](evidence-and-memory.md#trust-projection). A timed-out or denied escalation also raises an `escalation` finding in the bundle.
 
-The base provenance sets, steering, routing, quality, worker identity, and result-conformance coverage all enter in v0.2.9. These fields are labeled `experimental`: their strict v15 shape is frozen for the release, but the labels stay experimental until the schema is promoted post-1.0. For the complete version registry and migration contract across all artifacts, see [artifact-versions.md](artifact-versions.md).
+The base provenance sets, steering, routing, quality, worker identity, result-conformance, council provenance, and fleet gate provenance use the strict v19 shape frozen for the release. These fields are labeled `experimental` until the schema is promoted post-1.0. For the complete version registry and migration contract across all artifacts, see [artifact-versions.md](artifact-versions.md).
 
 | Field path | Type | When present | Meaning | Status |
 | --- | --- | --- | --- | --- |
@@ -149,7 +196,7 @@ The base provenance sets, steering, routing, quality, worker identity, and resul
 | `steering[].sentAt` | `string` | A steer was successfully written | Write timestamp | experimental |
 | `steering[].acknowledged` | `boolean` | A steer was successfully written | Whether a worker acknowledgement was actually observed | experimental |
 | `steering[].acknowledgedAt` | `string` | Acknowledgement was observed | Acknowledgement timestamp | experimental |
-| `outcomeCode` | five-value stable string union or `null` | Every v15 terminal receipt | Non-null for `vram_capacity_fit_failure`, `worker_tool_call_cap_exhausted`, `loop_guard_tools_disabled_exhausted`, `result_contract_exhausted`, or `worker_final_output_missing`; otherwise `null`. Each non-null code denotes terminal deterministic failure and is incompatible with `outcome: "succeeded"`. Dispatch retry policy consumes this code only, never diagnostic prose. | experimental |
+| `outcomeCode` | six-value stable string union or `null` | Every v19 terminal receipt | Non-null for `vram_capacity_fit_failure`, `worker_tool_call_cap_exhausted`, `loop_guard_tools_disabled_exhausted`, `result_contract_exhausted`, `worker_final_output_missing`, or `host_verification_rejected`; otherwise `null`. Each non-null code denotes terminal deterministic failure and is incompatible with `outcome: "succeeded"`. Dispatch retry policy consumes this code only, never diagnostic prose. | experimental |
 | `personaOverride.promptHash` | `string` | Ad-hoc specialist whose persona replaced the recipe body | Hash of the composed static prompt; equals `staticCompositionHash` for the run | experimental |
 | `safety.decisions.escalationRequested` | `number` | Run saw at least one permission escalation | Parked permission asks handed to the operator | experimental |
 | `safety.decisions.escalationApproved` | `number` | Run saw at least one permission escalation | Escalations the operator approved | experimental |
@@ -159,8 +206,8 @@ The base provenance sets, steering, routing, quality, worker identity, and resul
 | `safety.toolTelemetry.ingestionErrors` | `number` | Current dispatch receipts | Malformed or lost frames, event-fold/source errors, and drain timeouts that make otherwise mediated telemetry incomplete | experimental |
 | `safety.toolTelemetry.unfinished` | `{ tool, count }[]` | Current dispatch receipts | Tool starts that had no matching finish when the receipt sealed | experimental |
 | `safety.toolTelemetry.workspaceMutationPossible` | `boolean` | Current dispatch receipts | Whether incomplete or unavailable telemetry could conceal a shared-workspace mutation; retry admission fails closed when true | experimental |
-| `autonomyEnforcement.grade` | `string` | Always in v0.3.6 | The autonomy grade level enforced for the run | experimental |
-| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.6 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
+| `autonomyEnforcement.grade` | `string` | Always in v0.3.7 | The autonomy grade level enforced for the run | experimental |
+| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.7 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
 | `autonomyEnforcement.externalMode` | `string` | When running external worker | The execution mode of the external worker runtime | experimental |
 | `autonomyEnforcement.dangerousBypass` | `boolean` | When running external worker | Whether a safety bypass was explicitly activated | experimental |
 | `validationGrounding.claimed` | `number` | Validation grounding evaluated | Count of validations claimed by worker | experimental |

package/docs/proactive-memory.md

@@ -1,6 +1,6 @@
 # Proactive task memory
 
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.8).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still