@iowarp/clio-coder 0.3.6 → 0.3.7

package/docs/evidence-and-memory.md

@@ -1,9 +1,9 @@
 # Evidence Corpus and Long-Term Memory
 
 > [!TIP]
-> **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). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
+> **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.7). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
 
-Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.3.6, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
+Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.3.7, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.
 
@@ -148,11 +148,11 @@ Each run receipt (persisted under `<stateDir>/receipts/<runId>.json`) carries an
 ### Computation and Lifecycle
 - **Circular Dependency Prevention**: To prevent circular dependencies, `findingsSummary` is calculated **cheaply in-memory** at receipt-record time using the draft envelope and tool statistics (in `src/domains/dispatch/receipt-findings.ts`). It never reads from disk or calls `buildEvidence`.
 - **First-Pass Success**: Calculated as `true` only if the terminal outcome was `"succeeded"`, the lineage attempt was `0` (no dispatch retries), the tool stats confirm at least one successful validation tool was executed, and no failure-cause tags were detected.
-- **Cryptographic Coverage**: Current receipts use strict v15 and authenticate every current receipt field, including briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, and result-contract conformance, against the reconstructed ledger. Every version other than v15 is rejected; there is no historical receipt reader.
+- **Cryptographic Coverage**: Current receipts use strict v19 and authenticate every current receipt field, including briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance, against the reconstructed ledger. Every version other than v19 is rejected; there is no historical receipt reader.
 
 | Version | Verification policy | Compatibility policy |
 |---|---|---|
-| v15 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
+| v19 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
 | Any other version | No reader | Rejected; remove or archive the incompatible state rather than expecting migration |
 
 Receipt integrity and evidence verification answer different questions. The
@@ -227,7 +227,7 @@ finish-contract records without changing receipt-owned axes. Findings such as
 domain artifacts remain in the receipt, gate, audit, and trace files.
 
 The canonical aggregate is an additive projection for downstream work. Receipt
-integrity remains version 15, evidence bundles remain version 1, gate decisions
+integrity remains version 18, evidence bundles remain version 1, gate decisions
 remain version 2, and no persisted receipt field or cryptographic algorithm
 changes.
 

package/docs/evolution.md

@@ -1,7 +1,7 @@
 # Evolution and Change Manifests
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive change manifest editor, authority risk assessor, and checklist workspace is located at [docs/html/evolution_blueprint.html](html/evolution_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive change manifest editor, authority risk assessor, and checklist workspace is located at [docs/html/evolution_blueprint.html](html/evolution_blueprint.html) (Version: 0.3.7).
 
 Clio Coder uses change manifests to make harness changes reviewable, falsifiable, and rollback-friendly. CLIO stands for Context Layer for Input/Output, named for the Greek muse of history. A manifest is JSON, generated or checked with `clio-coder evolve manifest`, and should describe what changed, why, what evidence supports it, what could regress, how to validate it, and how to roll it back.
 

package/docs/exit-codes-and-output.md

@@ -1,6 +1,6 @@
 # Exit Codes & Machine-Readable Output Contracts
 
-This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.3.6`.
+This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.3.7`.
 
 Source implementations: `src/cli/` and `src/entry/`.
 
@@ -66,6 +66,9 @@ Many Clio CLI subcommands provide structured JSON output for integration with sc
 | `clio-coder targets` | `--json` | JSON object containing the configured `targets` array. |
 | `clio-coder models` | `--json` | JSON array of catalog models with capability flags. |
 | `clio-coder fleet status` | `--json` | JSON snapshot object with `generatedAt`, `admission` (`open` or `draining`), `running`, `retrying`, and `totals`. Each run row carries its `node`, defaulting to `local`. |
+| `clio-coder fleet validate` | `--json` | JSON report with `valid`, `fleet`, and either successful `checks` plus `planHash` or failure `diagnostics`. Validation failures exit `1`; usage errors exit `2`. |
+| `clio-coder fleet graph` | `--json` | JSON object with `fleet`, `planHash`, compiled `waves`, and expanded `loops`. Contract failures exit `1`; usage errors exit `2`. |
+| `clio-coder fleet run --resume` | `--json` | NDJSON step records include `status: "replayed"` and the original receipt reference for replayed prefix steps. Plan or variable mismatches exit `1`. |
 | `clio-coder trace runs` | `--json` | JSON array of trace run records. |
 | `clio-coder trace sql` | Positional query | JSON array of rows returned by the read-only SQLite query. A single `SELECT` or read-only `WITH` statement is accepted; multiple statements and mutating keywords are refused with exit code 2. |
 | `clio-coder paths` | `--json` | JSON object mapping platform directory names to absolute paths. |

package/docs/extensions-and-sharing.md

@@ -1,7 +1,7 @@
 # Extensions, Prompt Templates, Skills, and Share Archives
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.7).
 
 Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that contribute prompts and skills. Share archives are portable JSON files for moving project/user Clio resources between machines or collaborators. Themes are built into the engine and are no longer loaded from extensions.
 
@@ -251,7 +251,7 @@ Share archives are single JSON files:
   "formatVersion": 1,
   "manifest": {
     "format": "clio.share.v1",
-    "clioVersion": "0.3.6",
+    "clioVersion": "0.3.7",
     "createdAt": "...",
     "files": []
   },
@@ -280,6 +280,8 @@ Options:
 | `--skills` | Include skills. |
 | `--settings` | Include non-secret settings fragment. |
 | `--extensions` | Include extension bundle files, excluding extension `state.json`. |
+| `--agents` | Include agent recipe files. |
+| `--fleets` | Include fleet contract files. |
 | `--all` | Include every supported resource class. |
 
 If no include flags are supplied, export includes all supported classes for the selected scope.
@@ -296,6 +298,8 @@ clio-coder share import project.clio-coder-share.json --force
 
 Dry-run imports produce a plan and report conflicts without writing. Without `--force`, conflicting destination files block writes. With `--force`, conflicting files are overwritten and supported settings-fragment keys are merged into the current settings file.
 
+Archives accept `agent` and `fleet` file entry types alongside prompts and skills. Agent entries import into the user agent root and must pass the recipe parser and policy checks. Fleet entries import into the user fleet root and must pass `parseFleetContract` before any write. Dry-run plans report both types by kind.
+
 Aliases:
 
 ```bash

package/docs/fleet-demo-runbook.md

@@ -136,7 +136,7 @@ clio-coder evidence inspect <evidenceId>
 run ledger; a tampered or mismatched receipt fails the build with the field
 that diverged. The receipts of the remote runs verify on the orchestrator host because the
 ledger and receipts live on the shared filesystem. Current receipts use strict
-v15 and authenticate every current receipt and reconstructed-ledger field.
+v16 and authenticate every current receipt and reconstructed-ledger field.
 Every other receipt version is rejected rather than reported as partial; the
 current binary has no historical receipt reader.
 
@@ -168,7 +168,7 @@ reconstruct:
    complete receipt schema and its stable ledger row. `clio-coder evidence build
    --run <id>` recomputes and cross-checks it; `verifyReceiptIntegrity` in
    `src/domains/dispatch/receipt-integrity.ts` is the reference
-	implementation. Current receipts use v15 and every other version fails
+	implementation. Current receipts use v16 and every other version fails
 	verification. Incompatible state must be archived or removed; it is never
 	read as evidence through a compatibility verifier.
 

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.7).
 
 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,32 @@ 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 with no majority reports `no_majority`, and a vote with no
+verdict fields 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 +477,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)
 
@@ -432,7 +567,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 +581,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,7 +666,7 @@ 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.
 
@@ -540,7 +680,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 +691,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 +726,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 +843,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

@@ -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.

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.7). 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.7).
 
 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.7).
 
 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.7).
 
 `/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,
@@ -130,7 +177,7 @@ 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 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 |