@iowarp/clio-coder 0.4.1 → 0.4.2

package/docs/{architecture.md → architecture/architecture.md}

@@ -1,11 +1,11 @@
 # Clio Coder Architecture and Boundaries
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/architecture_blueprint.html](html/architecture_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder Architecture and Boundaries visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/architecture_blueprint.html).
 
 Clio Coder is an experimental, terminal-first coding harness for the CLIO ecosystem. CLIO stands for Context Layer for Input/Output; the project is named for the Greek muse of history and developed by the Gnosis Research Center at Illinois Tech. Its architecture favors small, auditable subsystems over a single monolithic agent loop: CLI entry points, the interactive TUI, provider/runtime code, worker subprocesses, tools, and feature domains are kept separate so local-model support and scientific-software workflows can evolve without collapsing safety boundaries.
 
-This page is source-code aligned for the current `v0.4.0` development line.
+This page is source-code aligned for the current source tree.
 
 ---
 
@@ -24,7 +24,12 @@ src/
 └── utils/           # small support utilities
 ```
 
-Registered domain modules include:
+Feature-domain directories include the following. Not every row is a loaded
+`DomainModule`: the orchestrator currently loads config, extensions, interop,
+resources, share, context, providers, toolchain, safety, prompts, agents,
+middleware, session, observability, scheduling, dispatch, and lifecycle, plus
+mux when the pane tier is active. The other rows are libraries or CLI-owned
+feature areas.
 
 | Domain | Primary source | Public surface |
 | --- | --- | --- |
@@ -49,6 +54,9 @@ Registered domain modules include:
 | scheduling | `src/domains/scheduling/**` | Budget ceilings, node cluster states, batch capacity checks. |
 | session | `src/domains/session/**` | Append-only JSONL transcripts, tree navigation, compaction. |
 | share | `src/domains/share/**` | Portable workspace and resource archive export/import. |
+| toolchain | `src/domains/toolchain/**` | Pinned external-tool discovery, installation, and resolution. |
+| user-tasks | `src/domains/user-tasks/**` | Library and CLI-owned durable user task list plus board handoff state. |
+| mux | `src/domains/mux/**` | Optional interactive pane-host integration. |
 
 The `interop` domain owns one question: which other coding agents are on this
 machine and in this project. `src/domains/interop/registry.ts` is pure data, one
@@ -67,7 +75,7 @@ or `state` directory. Detection resolves binaries with `access(X_OK)` and no
 shell, checks install directories, and runs a bounded `--version` only when the
 caller asks and only for a binary that already resolved; a probe that cannot
 answer reports `unknown` and never `absent`. The one durable configuration write
-is an append to `delegation.agents`, and it happens only after an operator
+is an append to `integrations.externalAgents.entries`, and it happens only after an operator
 decision.
 
 ---
@@ -161,16 +169,18 @@ Admission disposal is one registry-owned finally boundary, so a
 middleware guard block, ordinary return, or thrown body releases a provisional
 reservation exactly once.
 
-Only the admitted `run` step crosses `src/tools/lazy-tool.ts`. One cached promise
-owns the implementation import, including a deterministic failure, so concurrent
-first calls cannot initialize competing implementations. The loaded spec must
-match the advertised surface before its body can run. Ordinary body exceptions,
-result shaping, `after_tool` middleware, abort signals, and telemetry continue
-through the registry's existing path. This mechanism is built-in-only; it does
-not turn extension manifests or provider plugins into an executable tool loader.
-Source-built and installed-package coverage contracts locate implementations by
-stable behavior provenance, prove them absent during a real provider capability
-request, and prove only the invoked implementation present after first use.
+For ordinary lazy tools, only the admitted `run` step crosses
+`src/tools/lazy-tool.ts`. One cached promise owns the implementation import,
+including a deterministic failure, so concurrent first calls cannot initialize
+competing implementations. The loaded spec must match the advertised surface
+before its body can run. Ordinary body exceptions, result shaping, `after_tool`
+middleware, abort signals, and telemetry continue through the registry's
+existing path. This mechanism is built-in-only; it does not turn extension
+manifests or provider plugins into an executable tool loader. Dispatch is
+different: `registerAllTools` creates its lightweight admission surface eagerly,
+and `src/tools/dispatch.ts` owns a separate cached dynamic import of
+`dispatch-runner.ts` after admission succeeds. It does not pass through
+`lazy-tool.ts`.
 
 ## Boundary invariants
 
@@ -180,11 +190,11 @@ The enforced import rules below are complemented by the maintained
 [Pi SDK boundary table](pi-boundary.md), which records the semantic owner of
 each overlapping helper and the Clio deltas that must survive an SDK upgrade.
 
-These five enforced boundary rules constrain dependency **direction**, never import **form** (whether static vs dynamic, default vs named):
+These six enforced boundary rules constrain dependency **direction**, never import **form** (whether static vs dynamic, default vs named):
 
-### Rule 1: `@earendil-works/*` imports stay in `src/engine/**`
+### Rule 1: `@earendil-works/pi-*` imports stay in `src/engine/**`
 
-Only files under `src/engine/**` may import `@earendil-works/*` packages. Since the 0.83.0 engine-boundary rework, no file outside `src/engine/**` may import `@earendil-works/*` at all, value or type-only. Domain modules import erased engine shapes (`EngineModel`, `Api`, `Model`) directly from `src/engine/types.ts`.
+Only files under `src/engine/**` may import `@earendil-works/pi-*` packages. Since the 0.83.0 engine-boundary rework, no file outside `src/engine/**` may import those packages at all, value or type-only. Domain modules import erased engine shapes (`EngineModel`, `Api`, `Model`) directly from `src/engine/types.ts`.
 
 Why: provider SDKs and pi-ai engine values must remain swappable behind one engine boundary. Domains and presentation layers operate against Clio contracts rather than vendor or runtime implementations. `src/engine/api-registry.ts` composes Pi's public lazy API factories in their canonical order, retains provider-owned authentication/header dispatch, and lets Clio's local-runtime adapters override API families without importing the deprecated compatibility aggregate. The only `pi-ai/compat` edge is dynamic: before a configured out-of-tree runtime evaluates, Clio joins Pi's process-global registry and mirrors its overrides so external provider plugins retain the same registry identity and last-writer-wins order. No configured plugin means no compatibility aggregate. OpenAI-compatible sampler fields and vLLM thinking budgets flow through Pi's `samplingParams` and `supportsThinkingTokenBudget` contracts; Clio's adapter retains only catalog selection and runtime-specific payload deltas. Tool head/tail truncation, byte formatting, and grep-line clipping likewise flow through pi-agent-core's `truncateHead`, `truncateTail`, `formatSize`, and `truncateLine`; Clio retains only its 16 KiB per-observation default and its exported line-count helper. Tool string enums come from pi-ai's `StringEnum` (`src/engine/ai.ts`), the model-facing text for replayed bash executions and branch or compaction summaries comes from pi-agent-core's `bashExecutionToText` and summary prefixes (`src/engine/messages.ts`), and Anthropic thinking payloads are assembled by Pi's narrow lazy stream implementation with no Clio rewrite.
 
@@ -210,6 +220,16 @@ Files under `src/tools/**` may never import `src/interactive/**` (neither value
 
 Turn modules and state machine files in the chat loop (`src/interactive/turn-*.ts`, `chat-loop.ts`) may never import `src/entry/**`. Composition flows in one direction only: the entry point composes the chat loop, never the reverse.
 
+### Rule 6: Stage 0 remains behind declared seams
+
+Value importers outside the computed instant-shell Stage 0 closure and its
+`src/interactive/**` and `src/engine/**` trees may enter those protected trees
+only through a seam declared in `STAGE0_SEAMS`. A declared seam may not lead back
+into the Stage 0 closure unless the existing composition-root overlap is
+explicitly recorded. CLI type edges retain the declaration requirement. This
+keeps unrelated importers from creating another reacher into the cold-start
+chunk graph.
+
 ---
 
 ## Runtime flow
@@ -293,15 +313,16 @@ editor object and buffer. Submissions accepted before attachment are immutable
 FIFO records shown in the shell and admitted exactly once through the normal
 slash/bash/chat pipeline after attachment. A generation guard rejects a late
 hydration after shutdown; every failure path shares one idempotent close and
-terminal restoration transaction. The built-graph contract bounds the Stage 0
-closure and rejects provider, tool, codewiki, tree-sitter, and orchestrator
-implementation markers. ACP, headless, ordinary non-TTY invocation, help, and
+terminal restoration transaction. The source boundary checker protects the
+declared Stage 0 closure and seams. There is no committed built-chunk budget
+contract at this revision; the installed-package smoke test still exercises
+lazy codewiki loading. ACP, headless, ordinary non-TTY invocation, help, and
 subcommands never construct a lease; the established explicit
 `CLIO_CODER_INTERACTIVE=1` non-TTY override remains force-interactive.
 
 Tracing is opt-in and content-free. Its bounded asynchronous writer never does
 filesystem append I/O on the render stack, and shutdown awaits a bounded flush.
-See [performance-methodology.md](performance-methodology.md) for vocabulary,
+See [performance-methodology.md](../process/performance-methodology.md) for vocabulary,
 commands, PTY limitations, and baseline evidence.
 
 ## Command spec

package/docs/{artifact-placement.md → architecture/artifact-placement.md}

@@ -1,9 +1,13 @@
 # Artifact Placement
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Artifact Placement visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_placement_blueprint.html).
+
 Every file Clio generates has one home, decided by who reads it. The rule that
 follows from that: **the repo working tree holds files a human asked for.**
-Anything Clio produced on its own initiative lands in the gitignored project
-directory or under the XDG dirs, never beside your source.
+Anything Clio produced on its own initiative lands in the project-local
+`.clio-coder/` directory or under the XDG directories, never beside your source.
+`context init` can add the recommended blanket ignore for `.clio-coder/`.
 
 This page is the contract. `src/core/artifact-paths.ts` is the code that
 implements the part of it the `artifact` tool owns.
@@ -13,7 +17,7 @@ implements the part of it the `artifact` tool owns.
 | Audience | What it means | Where it goes |
 | --- | --- | --- |
 | Human deliverable | A file the user asked to keep, and will read and commit | Repo working tree, at the path the user named |
-| Human transient | Something a human may want to read once; losing it costs nothing | Project-local `.clio-coder/` (gitignored) |
+| Human transient | Something a human may want to read once; losing it costs nothing | Project-local `.clio-coder/` (normally gitignored) |
 | Agent-to-agent state | Machine-read plumbing between turns, workers, and sessions | `.clio-coder/` for per-project state; XDG data/state/cache for per-machine state |
 
 A class is human-facing only if a person is expected to open it. A plan an
@@ -33,7 +37,7 @@ Markdown.
 | Task-memory handoffs | `.clio-coder/handoffs/` | Agent-to-agent |
 | Dispatch proposals | `.clio-coder/proposals/` | Agent-to-agent |
 | Compete worktrees | `.clio-coder/worktrees/` | Agent-to-agent |
-| Test scratch | `.clio-coder/test-scratch/` | Agent-to-agent |
+| Tool-result and harness scratch | XDG state `scratch/`, with tool offloads grouped by session | Agent-to-agent |
 | Evidence bundles | XDG data `evidence/` | Human transient (`clio-coder evidence`) |
 | Approved memory | XDG data `memory/` | Human transient (`clio-coder memory`) |
 | Eval artifacts | XDG data `evals/` | Human transient (`clio-coder eval`) |
@@ -41,7 +45,6 @@ Markdown.
 | Dispatch receipts | XDG state `receipts/` | Human transient (`clio-coder trace`) |
 | Audit records | XDG state `audit/` | Human transient |
 | Interview transcripts | XDG state `interviews/` | Agent-to-agent |
-| Harness scratch | XDG state `scratch/` | Agent-to-agent |
 | Caches | XDG cache | Agent-to-agent |
 
 `clio-coder paths` prints the resolved XDG directories for your machine.
@@ -63,27 +66,27 @@ first. Keep several by naming explicit paths.
 
 ## `.clio-coder/` and git
 
-`.clio-coder/` is gitignored in full. Everything above that lands there is
-generated, reproducible, and worthless in a diff, and the whole point of the
-contract is that a dogfooding session ends with `git status` clean.
+`clio-coder context init` checks for a blanket `.clio-coder/` ignore. With
+confirmation, or with `--yes`, it appends `.clio-coder/` to `.gitignore`; without
+confirmation it warns and leaves the file unchanged. A project that has never
+accepted or authored that rule can therefore see generated local state in
+`git status`.
 
 Some `.clio-coder/` content is authored rather than generated, and a project
-that wants it reviewed and shared commits it deliberately by adding negations
-next to the ignore:
-
-```gitignore
-.clio-coder/
-!.clio-coder/fleets/          # fleet contracts: repo-owned dispatch policy
-!.clio-coder/fleets/**
-!.clio-coder/rules/           # path-scoped project rules
-!.clio-coder/rules/**
-!.clio-coder/safety.yaml      # project safety policy
-!.clio-coder/agents/          # project agent recipes
-!.clio-coder/agents/**
+that wants it reviewed and shared commits exact files deliberately. With the
+blanket parent directory ignored, child negations alone are ineffective because
+Git does not descend into an excluded parent. Force-add an intentional asset,
+for example:
+
+```bash
+git add -f .clio-coder/fleets/build-review.md
+git add -f .clio-coder/rules/backend.md
+git add -f .clio-coder/safety.yaml
 ```
 
-This repository commits none of those, so its `.clio-coder/` stays fully
-ignored. Benchmark workspaces are temporary external repositories.
+Review the forced path before committing it. This repository commits none of
+those project-local assets, and its `.gitignore` contains the blanket rule.
+Benchmark workspaces are temporary external repositories.
 
 ## Finding what was hidden
 
@@ -97,4 +100,4 @@ Hiding transient output from the working tree must not mean losing it.
 
 Related: [evidence-and-memory.md](evidence-and-memory.md),
 [trace-store.md](trace-store.md), [observability.md](observability.md),
-[development-pipeline.md](development-pipeline.md) for where RCAs are committed.
+[development-pipeline.md](../process/development-pipeline.md) for where RCAs are committed.

package/docs/architecture/artifact-versions.md

@@ -0,0 +1,90 @@
+# Artifact Versions & Serialization Contracts
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Artifact Versions & Serialization Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_versions_blueprint.html).
+
+This document is an operator-facing registry of compatibility-sensitive file
+formats, serialized structures, integrity digests, and migration rules in the
+current source tree. It is not an exhaustive inventory of every internal store
+or wire frame. Source version constants and their readers remain authoritative.
+
+---
+
+## 1. Operator-facing Artifact Registry
+
+Clio Coder gives its compatibility-sensitive persistent and network contracts an
+explicit version or schema identity. This table also calls out selected
+unversioned stores whose handling matters to operators. It does not enumerate
+every internal contract, such as the worker wire protocol, `batches.json`
+(detached batch records), code-step, agent-ledger, and route-history stores.
+Depending on the artifact, an incompatible reader fails closed, skips
+an invalid record, or uses an explicitly documented compatibility
+normalization.
+
+| Artifact / Subsystem | Current Version | Symbol / Type & Source Location | Persisted Path / Wire Location | Schema Semantics & Version Differences | Mismatch Handling |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Run Receipt** | `20` | `RUN_RECEIPT_INTEGRITY_VERSION = 20`<br>`src/domains/dispatch/receipt-integrity.ts:13` | `<stateDir>/receipts/<runId>.json` | Cryptographically sealed run record. Version 20 adds `pathProvenance` on dispatch intent and the resolved `pathScope`, over the v19 base of provenance fields, routing intent, quality labels, `validationGrounding`, `capabilityMismatch`, council provenance, and fleet gate provenance. | Fail-closed. A receipt below v20 is reported as retired rather than invalid, is never read as evidence, and is never migrated; a malformed or tampered v20 receipt fails verification. |
+| **Dispatch Intent** | `2` | `DISPATCH_INTENT_VERSION = 2`, `DISPATCH_INTENT_SUPPORTED_VERSIONS = [2]`<br>`src/domains/dispatch/intent-compatibility.ts` | Inside the resolved dispatch plan artifact, the `JobSpec`/`DispatchRequest`, and the sealed run receipt | Typed model- and producer-declared scope: `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and declared-id `verification`, plus the `pathProvenance` binding every policy-bearing path to the field that declared it. Version 2 adds `pathProvenance` over the v1 path-and-output shape. | Fail-closed, never migrated. The supported set is a membership list, not a range: any other version is refused with `intent_version_unsupported` and the caller restates the fields on a fresh dispatch call. Omitted intent is accepted through the separately tracked legacy inference path; contradictory intent is a terminal refusal. See [dispatch-typed-intent.md](dispatch-typed-intent.md). |
+| **Dispatch Path Scope Provenance** | `1` | `version: 1` in `interface DispatchPathScopeProvenance`<br>`src/domains/dispatch/path-scope.ts` | `pathScope` on the sealed run receipt | Resolved policy-bearing paths with per-field provenance (`declared`/`derived`/`inferred`), source, and confidence. Never carries the task or briefing prose an inferred path came from. | Sealed inside the receipt integrity digest; shares the receipt's fail-closed policy. |
+| **Resolved Dispatch Plan Artifact** | `3` | `version: 3` in `interface ResolvedDispatchPlanArtifact`<br>`src/tools/dispatch-plan.ts:121` | Trusted admission-time tool argument, rendered and hashed into the plan approval | Pinned agent/target/model/node per task plus the sealed `intent` and admission-resolved `resolvedVerification`. The rendered artifact carries `intent_sha256` for a declared task and the full inferred scope table for a legacy one. | Fail-closed. Any version but 3 parses as `null`, as does any task whose present `intent` is not a normalized v2 intent; omitted intent remains the valid legacy-inference shape. The call falls back to unresolved admission rather than executing a half-understood plan. |
+| **Session Ledger** | `4` | `CURRENT_SESSION_FORMAT_VERSION = 4`<br>`src/engine/session.ts:73` | `<stateDir>/sessions/<cwdHash>/<sessionId>/` (`meta.json`, `current.jsonl`, `tree.json`) | Append-only ledger format with UUIDv7 turn IDs, session header line, and tree graph linkage. Version 4 adds `contextEviction` and `contextRecall` entry kinds. | The reader accepts v3 and v4. Opening v3 restamps metadata as v4 without rewriting ledger entries; versions below 3 and versions from a newer build are refused. |
+| **Worker Spec** | `3` | `WORKER_SPEC_VERSION = 3`<br>`src/worker/spec-contract.ts:23` | Subprocess `stdin` control plane JSON payload | Worker invocation parameters, tool surface profile, and execution bounds. | Fail-closed preflight rejection before worker activation. |
+| **Worker Runtime Descriptor** | `2` | `WORKER_RUNTIME_DESCRIPTOR_VERSION = 2`<br>`src/worker/spec-contract.ts:24` | Nested `runtime` object in the Worker Spec | Serialized runtime id, kind, API family, auth mode, and optional aliases used to rehydrate the worker's provider runtime. Hardware and environment facts belong to the separate worker-protocol attestation. | Worker-spec parsing rejects an unsupported descriptor version or id mismatch. Rehydration rejects id, kind, API-family, or auth drift before the worker model call. |
+| **Worker Protected Artifact State** | `1` | `WORKER_PROTECTED_ARTIFACT_STATE_VERSION = 1`<br>`src/worker/spec-contract.ts:25` | Worker spec initialization snapshot | Snapshot of active protected artifact paths and validation commands passed to worker. | Worker fails closed before executing mutations. |
+| **Fleet Contract** | `1 \| 2 \| 3 \| 4 \| 5` (Current: `5`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4 \| 5`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`FLEET_DYNAMIC_STEP_VERSION = 5`<br>`src/domains/agents/fleet-contract.ts` | Markdown recipes with YAML front matter, including `.clio-coder/fleets/<name>.md` plus built-in, enabled-extension, and user tiers | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops and commit steps; v4 adds declared per-step write boundaries; v5 adds plan steps, gate steps, per-step target or profile routing, and the single-writer declaration. | Reader refuses contracts whose version features it does not support. |
+| **Execution Plan** | `4` | `version: 4` in `interface ExecutionPlan`<br>`src/domains/dispatch/execution-plan.ts:114` | Complete compiled DAG in memory; plan hash and provenance in receipts; selected steps and hash in the Fleet Run Record | Statically unrolled, deterministically hashed execution plan. v4 adds bounded loop nodes, verification staleness tracking, and commit nodes. | The compiler stamps version 4. There is no execution-plan deserializer or cross-version mismatch path; fleet resume validates its separate Fleet Run Record and plan hash. |
+| **Eval Artifact** | `4` | `version: 4` in `interface EvalArtifactV4`<br>`src/domains/eval/schema/artifact.ts` | `<dataDir>/evals/<evalId>.json` | Stored eval results with suite provenance, matrix parameters, and itemized metric outcomes. `EVAL_TASK_FILE_VERSION = 1` versions compatibility v1 `--task-file` inputs; Suite v2 is a separate contract. | Incompatible eval artifacts are rejected during `clio-coder eval report` and `compare`. |
+| **Prompt Manifest** | `2` | `PROMPT_MANIFEST_VERSION = 2`<br>`src/domains/session/prompt-manifest.ts:30` | `<stateDir>/sessions/<cwdHash>/<sessionId>/prompt-manifest.jsonl` | Per-session record of the compiled system prompt: fragment ids, relative paths, content hashes, section token estimates, and the composition hash. Version 2 is the stable-prefix-first ordering with one `# Memory` header and records `contextWindowSource` beside the window the prompt states (#249). | Additive. A record without a `version` field predates the field and reads as version 1, so a 0.3.8 manifest still parses; the version explains the single `promptRecompiled` entry a resumed session's first compile writes. |
+| **Eval Verdict Envelope** | `clio-coder.eval.verdict.v1` | `EVAL_VERDICT_SCHEMA_V1`<br>`src/domains/eval/schema/verdict.ts` | Optional result sibling inside the Eval Artifact at `<dataDir>/evals/<evalId>.json` | Strict per-trial verdict identity with outcome and machinery, ledger- and receipt-sourced tracked metrics, and evidence links (#252). One pass decision: the code grader's outcome is part of `result.pass`. Distribution aggregates and serving configuration belong to the enclosing Eval Artifact. | A present malformed envelope is rejected, and behavioral results require one; an absent envelope remains valid for older non-behavioral results and is omitted from verdict comparisons. Separately, `eval compare` refuses artifact-level serving-configuration drift unless explicitly allowed. Released `clio.eval.*` identities are normalized only at the read boundary. |
+| **Behavioral Scenario & Result** | `clio-coder.eval.scenario.v1`, `clio-coder.eval.behavior.v1` | `EVAL_BEHAVIOR_SCENARIO_SCHEMA_V1`, `EVAL_BEHAVIOR_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral.ts` | Suite v2 task declarations; additive sibling inside the Eval Artifact | Versioned behavioral contract: bounded expected and forbidden rules across tool choice, exploration, delegation, safety comprehension, claim grounding, denied-tool recovery, completion behavior, and task correctness, with deterministic judge inputs canonicalized from transcript, tool, receipt, and grader facts (#156). References the canonical `clio-coder.eval.verdict.v1` identity. | Fail-closed. `unknown`, `unmeasured`, `behavioral_failure`, and `infrastructure_failure` stay distinct; a malformed, partial, contradictory, or cross-linked verdict cannot parse as a pass. Existing artifact readers are unaffected because the sibling is additive. Released `clio.eval.*` identities normalize only on read. |
+| **Behavioral Metrics Projection** | `clio-coder.eval.behavior.metrics.v1` | `EVAL_BEHAVIOR_METRICS_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral-metrics.ts` | Additive role- and target/model-bound projection inside the Eval Artifact | Sourced metric families cover correctness, safety, label violations, tool-call efficiency, unnecessary exploration, delegation quality, unsupported claims, tokens, latency, cost, and repeat variability, with coverage, min/max, p90, population variance, and standard deviation per distribution (#161). | Unmeasured observations stay typed `null` and never become zero violations. A baseline hard metric that becomes unmeasured fails the comparison closed, and `--metric` filtering cannot hide a hard failure. Released `clio.eval.*` identities normalize only on read. |
+| **Execution Envelope** | `clio-coder.eval.execution-envelope.v1` | `EVAL_EXECUTION_ENVELOPE_SCHEMA_V1`<br>`src/domains/eval/schema/execution-envelope.ts` | On every new behavioral result inside the Eval Artifact | Strictly parsed binding of prompt fragment ids, versions, and content hashes, composition hash, recipe identity and content hash, target, wire model, runtime, thinking level, tool signature, autonomy, policy hashes, project-context provenance, and corpus id and version (#164). Suites declare which matrix dimensions may vary. | Fail-closed. Comparisons mark rows incomparable on any undeclared envelope drift, refuse one-sided envelopes and within-run variance, and name every prompt- or recipe-affected corpus result. Released `clio.eval.*` identities normalize only on read. |
+| **Trace Database** | `1` | `TRACE_SCHEMA_VERSION = 1`<br>`src/domains/observability/trace-store.ts:26` | `<stateDir>/trace.sqlite` (`meta` table `schema_version`) | Schema version for the 7 SQLite trace mirror tables (`runs`, `phases`, `events`, `envelopes`, `gate_results`, `agent_sessions`, `processes`). | The asynchronous dispatch mirror logs `[clio-coder:trace]` and degrades without failing the parent run. Direct `clio-coder trace` readers reject an unsupported schema and exit 1. |
+| **Capacity State File** | `2` | `version: 2` in `interface CapacityStateFile`<br>`src/domains/dispatch/capacity-lease.ts:56` | `<stateDir>/dispatch-admission.json` | Active capacity leases, drain status, and whole-plan reservations. The cross-process advisory lock lives in a separate `.lock` file. | Corrupted or unparseable state file causes admission to fail closed. |
+| **Protected Artifact Journal** | `1` | `version: 1` in `interface PendingProtectedArtifactRecord`<br>`src/domains/session/protected-artifact-journal.ts:21` | `<stateDir>/protected-artifact-pending/<key>/<id>.json` | Write-ahead durability records for pending protected artifacts. | Leftover records reconciled during session initialization. |
+| **Fleet Run Record** | `1` | `version: 1` in `interface FleetRunRecord`<br>`src/domains/dispatch/state.ts` | `<stateDir>/fleet-runs/<runId>.json` | Durable record of one fleet run: contract name, plan hash, static step ids and steps, `--var` values, replayed and settled step results, and the delegation plan hash a `kind: plan` step produced. Read by `fleet run --resume`. | Resume refuses a changed plan hash with a per-step diff and refuses differing `--var` values. |
+| **Dispatch Run Ledger** | unversioned JSON array | `RunEnvelope`<br>`src/domains/dispatch/state.ts` | `<stateDir>/runs.json` | In-memory mirror of recent dispatch runs (id, agent, target, model, runtime, status, timing, receipt path, budget/briefing/steering provenance), newest-first, persisted as a settings-bounded ring (default 1000 runs). Read by the eval, evidence, CLI (`usage`), and TUI (Dispatch Board) domains, among others. | A missing file reads as empty; a non-array top-level JSON value reads as empty; malformed JSON throws. There is no per-record version field to check or reject on, since `RunEnvelope` carries none. |
+| **Durable Assignment Store** | `1` | `version: 1` in `interface AssignmentStoreFile`<br>`DurableAssignmentRecord`<br>`src/domains/dispatch/assignment-store.ts` | `<stateDir>/assignments.json` | Machine-wide logical-dispatch records: assignment id, attempt ids, terminal run id, status, optional fleet verdict owner, and—while running—`processOwner {pid, processBirthToken, acquiredAt}`. The owner is cleared on a true terminal transition. | A live sibling owner keeps the row running; a genuinely dead or legacy ownerless row is reconciled. An unsupported or unreadable store is treated as empty, and malformed records are ignored. |
+| **Checkout Writer Lease** | `1` | `version: 1` in `interface CheckoutWriterLeaseRecord`<br>`src/domains/dispatch/checkout-writer-lease.ts` | `<stateDir>/checkout-writer-leases/<key>.json` (key derived from the canonical checkout path) | Cross-process single-writer lease: checkout path, pid, process birth token, acquisition time. | A live sibling holder is refused with `checkout_writer_lease_held`; a dead owner is reclaimed; a malformed or unreadable record throws and fails admission closed. |
+| **Out-of-turn Usage Ledger** | unversioned JSONL | `OutOfTurnUsageRow`<br>`src/domains/observability/out-of-turn-usage.ts` | `<stateDir>/usage/out-of-turn.jsonl` | One row per priced side question, handoff, prompt prewarm, or background-memory call. Each row records its `side-question`, `handoff`, `prewarm`, or `background-memory` label plus session id, repository identity, timestamp, target, attributed model, and provider usage. The ledger is a bounded ring of `MAX_OUT_OF_TURN_USAGE_ROWS = 1000`, rewritten atomically under the state-file lock. | Unparseable rows are skipped and counted by `usage report`; the session ledger is never affected. |
+| **User Tasks File** | `1` | `USER_TASKS_FILE_VERSION = 1`<br>`src/domains/user-tasks/store.ts:6` | `<workspace>/.clio-coder/user-tasks.json` | Durable operator task list with monotonic `uN` ids, status, timestamps, optional notes, and optional session and board links. `nextId` must stay above every stored id. | Fails closed with `UserTasksStoreError` on corrupt JSON, an unknown version or field, an invalid task, a duplicate id, or an unsafe `nextId`; missing files initialize as an empty list. |
+| **Library Pins** | unversioned YAML map | `readLibraryPins`<br>`src/domains/resources/library.ts` | `<configDir>/library-pins.yaml` | Typed ref (`skill:x`, `agent:y`, `prompt:p`, `fleet:z`) to `{sha256, sourceUrl}` for every resource `library add` or the Skills Hub installed. | Malformed YAML throws; a successfully parsed non-map reads as empty. Either a kind-qualified pin or the destination file makes an entry report installed, so a surviving pin still counts when its installed file is missing. |
+
+---
+
+## 2. Integrity Verification Contracts
+
+### Receipt Integrity (Version 20)
+
+Receipt integrity authenticates that a sealed receipt matches its ledger envelope without modification. The private `computeReceiptIntegrity` helper hashes a canonical payload built from both records:
+
+```typescript
+function computeReceiptIntegrity(
+  receipt: RunReceipt | RunReceiptDraft,
+  envelope: RunEnvelope,
+  legacyNaming = false,
+): RunReceiptIntegrity {
+  return {
+    version: 20,
+    algorithm: "sha256",
+    digest: sha256(canonicalJson(integrityPayload(receipt, envelope, legacyNaming))),
+  };
+}
+```
+
+Receipt verification checks:
+1. The quality block and integrity block have their strict current shapes, including `integrity.version === 20`. A receipt sealed at a lower version is reported as retired rather than invalid: it is intact, but is not read as evidence and is never migrated.
+2. `executionRole` and `routingIntent` parse, and an optional `routeDecision` is current.
+3. Receipt identity, route, timing, usage, cost, outcome, node, briefing, budget, and steering fields agree with the run ledger envelope.
+4. The SHA-256 of the canonical receipt-and-ledger payload matches `integrity.digest`; the reader also recognizes the released legacy contract-name spelling when recomputing an otherwise current v20 digest.
+
+---
+
+## 3. Migration Mechanics
+
+Session format handling runs automatically when a session is opened:
+
+1. **Discovery**: `src/domains/session/migrations/index.ts:runMigrations` reads the recorded `sessionFormatVersion`, treating a missing field as version 1.
+2. **Readable range**: This build reads only versions 3 and 4. A version below 3 is disposable pre-1.0 state and is refused; a version above 4 belongs to a newer build and is refused with upgrade guidance.
+3. **Additive step**: Version 3 opens as version 4 because v4 only adds the `contextEviction` and `contextRecall` entry kinds. Existing `current.jsonl` and `tree.json` content is not transformed.
+4. **Metadata update**: The session metadata is restamped with `sessionFormatVersion: 4` through the session writer's normal durable path.

package/docs/{capacity-and-scheduling.md → architecture/capacity-and-scheduling.md}

@@ -1,6 +1,11 @@
 # Capacity Leases & Fleet Scheduling
 
-This document specifies the multi-process capacity leasing protocols, node scheduling models, cross-process transaction locks, and failure recovery mechanics implemented in Clio Coder `v0.4.0`.
+> **Visual blueprint:** The source checkout includes the complete
+> [Capacity Leases & Fleet Scheduling visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/capacity_scheduling_blueprint.html).
+
+This document specifies the multi-process capacity leasing protocols, node
+scheduling models, cross-process transaction locks, and failure recovery
+mechanics in the current source tree.
 
 Source implementations: `src/domains/scheduling/` and `src/domains/dispatch/capacity-lease.ts`.
 
@@ -23,7 +28,7 @@ graph TD
 
 | Dimension | Identity | Limit resolution |
 | :--- | :--- | :--- |
-| Global | All dispatches using the state directory. | `budget.concurrency: auto` remains four. |
+| Global | All dispatches using the state directory. | `fleet.concurrency: auto` remains four. |
 | Node | The local node or one configured fleet node. | The configured node limit applies. An unset local node cap remains unbounded. |
 | Inference endpoint | A normalized scheme, host, port, and base path. | A target's `maxConcurrentRequests` override wins, then a probe in this process, then a persisted probe from an earlier process, then one slot for other local-native targets. vLLM and SGLang remain unbounded. |
 
@@ -74,7 +79,7 @@ export interface CapacityStateFile {
 
 ## 2. Capacity Lease Schema & TTLs
 
-Each in-flight worker holds one `CapacityLease` (`src/domains/dispatch/capacity-lease.ts:18-29`):
+Each in-flight worker holds one `CapacityLease` (`src/domains/dispatch/capacity-lease.ts:30-44`):
 
 ```typescript
 export interface CapacityLease {
@@ -82,6 +87,7 @@ export interface CapacityLease {
   assignmentId: string;         // Owning dispatch assignment ID
   nodeId: string;               // Execution node identifier ("local" or remote ID)
   endpointKey?: string;         // Canonical inference endpoint identifier
+  host?: string;                // Owner host; absent only on older records
   ownerPid: number;             // Process ID of the orchestrator/worker owner
   processBirthToken: string;    // OS-level token preventing PID reuse collisions
   acquiredAt: string;           // ISO-8601 acquisition timestamp
@@ -94,20 +100,26 @@ export interface CapacityLease {
 
 The orchestrator's active model stream is registered in memory against the same endpoint key, so its own turn consumes one endpoint slot before a worker is admitted. This foreground count is not written to `dispatch-admission.json`; process exit releases it. Durable leases and held reservation members carry `endpointKey`, and held members count their peak per wave for the endpoint just as they do for a node.
 
-Execution-plan waves also honor the endpoint bound. A plan with four available worker positions targeting one two-slot server packs at most two of them into a wave, or one when the orchestrator already holds the other slot. Endpoint saturation is refused rather than queued, because an endpoint-specific request queue would hold a dispatch open behind a stream whose length nobody knows. The refusal names the endpoint, both slot counts, why one slot is already gone, and the moves that actually free capacity:
+Execution-plan waves also honor the endpoint bound. A plan with four available worker positions targeting one two-slot server packs at most two of them into a wave, or one when the orchestrator already holds the other slot. Reservation preflight refuses a plan whose peak cannot fit because the scheduler must reserve the whole plan atomically. The refusal names the endpoint, both slot counts, why one slot is already gone, and the moves that actually free capacity:
 
 ```text
-dispatch: admission denied: endpoint '192.168.86.141:8080' capacity reached (1/1 slots): 1 foreground stream holds the slot; reduce the same-wave worker count, set this target's maxConcurrentRequests to the slot count the server was started with, collect in-flight runs, or point workers at a second server
+dispatch: admission denied: endpoint '127.0.0.1:8080' capacity reached (1/1 slots): 1 foreground stream holds the slot; reduce the same-wave worker count, set this target's maxConcurrentRequests to the slot count the server was started with, collect in-flight runs, or point workers at a second server
 ```
 
-That remedy is shared by all three paths that can refuse for this reason: lease acquisition (`src/domains/dispatch/capacity-lease.ts`), the admission gate (`src/domains/dispatch/admission.ts`), and reservation preflight (`src/domains/dispatch/reservation-store.ts`). The `1/1` above is the common local case rather than an example: a llama.cpp router started with `--parallel 1` discovers one slot, so any dispatch raised while the orchestrator is streaming is refused before a worker process starts.
+Direct lease acquisition in `src/domains/dispatch/capacity-lease.ts` reports saturation as `capacity reached`. The normal admission controller in `src/domains/dispatch/admission.ts` treats that signal as transient and leaves the assignment in its bounded shared queue, retrying until capacity opens or the request's deadline or 60-second queue ceiling wins. Capacity marked `unavailable`, drain mode, corrupt state, and other errors still fail immediately. Reservation preflight in `src/domains/dispatch/reservation-store.ts` refuses an over-capacity plan instead of queuing a partial reservation. The `1/1` example represents a generic llama.cpp server started with `--parallel 1`: a singular dispatch raised while the orchestrator is streaming waits for that slot, and a council reservation is refused before any worker starts.
+
+The reference `mini` target is not a one-slot example. It is a llama.cpp router
+at `192.168.86.141:8080` serving `ornith1.5-35b-moe` with four parallel slots
+and 262,144 context tokens per slot. One foreground stream on that endpoint
+leaves three slots for worker admission. The reference chat target, `dynamo`,
+is LM Studio at `192.168.86.143:1234` serving `qwen3.8-27b-dynamo`.
 
 ### What `/council` Needs on a Single-GPU Setup
 
 A council seats two to five members and runs the whole roster in one wave, so it needs at least two endpoint slots at once, plus a third if the orchestrator's own turn is streaming to the same server. It cannot answer a capacity denial by dispatching fewer members, which is why its denial says so instead of offering that move:
 
 ```text
-dispatch: admission denied: endpoint 'mini:8080' capacity exceeded (2/1 slots): no active lease, held reservation, or foreground stream currently holds a slot; a council runs its whole roster in one wave and cannot go below 2 members, so set this target's maxConcurrentRequests to the slot count the server was started with, collect in-flight runs, or point workers at a second server
+dispatch: admission denied: endpoint 'one-slot-local:8080' capacity exceeded (2/1 slots): no active lease, held reservation, or foreground stream currently holds a slot; a council runs its whole roster in one wave and cannot go below 2 members, so set this target's maxConcurrentRequests to the slot count the server was started with, collect in-flight runs, or point workers at a second server
 ```
 
 On a single-GPU box there are three ways to make `/council` work, in order of preference:
@@ -122,9 +134,9 @@ A server genuinely started with one slot cannot run a council, and admitting one
 
 | Constant | Value | Description | Source Reference |
 | :--- | :--- | :--- | :--- |
-| `MAX_CAPACITY_LEASES` | `1000` | Hard cap on simultaneous active capacity leases across all nodes. | `src/domains/dispatch/capacity-lease.ts:8` |
-| `DEFAULT_CAPACITY_LEASE_TTL_MS` | `30000` ms (30s) | Inactivity expiration window for leases without a refreshed heartbeat. | `src/domains/dispatch/capacity-lease.ts:9` |
-| `DEFAULT_CAPACITY_DRAIN_TTL_MS` | `3600000` ms (1h) | Automatic expiration window for operator drain mode. | `src/domains/dispatch/capacity-lease.ts:16` |
+| `MAX_CAPACITY_LEASES` | `1000` | Hard cap on simultaneous active capacity leases across all nodes. | `src/domains/dispatch/capacity-lease.ts:13` |
+| `DEFAULT_CAPACITY_LEASE_TTL_MS` | `30000` ms (30s) | Renewal and fallback expiry horizon when exact process identity is unavailable. A matching live process birth token keeps its lease valid beyond this timestamp. | `src/domains/dispatch/capacity-lease.ts:14` |
+| `DEFAULT_CAPACITY_DRAIN_TTL_MS` | `3600000` ms (1h) | Automatic expiration window for operator drain mode. | `src/domains/dispatch/capacity-lease.ts:28` |
 | `NODE_DEATH_FAILURE_THRESHOLD` | `2` consecutive failures | Channel failure count before a remote node is classified offline. | `src/domains/scheduling/cluster.ts:64` |
 
 ---
@@ -133,9 +145,10 @@ A server genuinely started with one slot cannot run a council, and admitting one
 
 To prevent leaked leases when workers or orchestrators crash:
 
-1. **Heartbeat Protocol**: Active workers emit heartbeats over their control channel every 1,000 ms (`src/worker/heartbeat.ts`). The orchestrator updates `heartbeatAt` and extends `expiresAt` by `DEFAULT_CAPACITY_LEASE_TTL_MS`.
-2. **PID Liveness & Birth Tokens**: The lease reconciler inspects `ownerPid` and validates `processBirthToken` against operating system process tables. If the PID has terminated or been recycled by the OS, the lease is immediately reclaimed.
-3. **Lazy Reaping**: Every admission attempt purges expired leases and dead process records inside the cross-process transaction lock before calculating available capacity.
+1. **Worker Heartbeat Protocol**: Active native workers emit control-channel heartbeats every 1,000 ms (`src/worker/heartbeat.ts`) for run liveness and stall detection.
+2. **Capacity-Lease Renewal**: Independently of worker control frames, the process-local admission controller renews every held durable lease every 10,000 ms. A renewal updates `heartbeatAt` and extends `expiresAt` by `DEFAULT_CAPACITY_LEASE_TTL_MS`.
+3. **PID Liveness & Birth Tokens**: The lease reconciler inspects `ownerPid` and validates `processBirthToken` against operating system process tables for records owned by this host. If the PID has terminated or been recycled by the OS, the lease is immediately reclaimed. A record naming another host is not adjudicated with the local process table.
+4. **Lazy Reaping**: Every admission attempt purges reclaimable leases and dead process records inside the cross-process transaction lock before calculating available capacity.
 
 ---
 

package/docs/{context-engine.md → architecture/context-engine.md}

@@ -1,7 +1,7 @@
 # Context Engine
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Context Engine visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_blueprint.html).
 
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
@@ -11,13 +11,13 @@ The non-destructive eviction layer has its own guide: [context-working-set.md](c
 
 ## Context window resolution
 
-Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. Sources rank most-live first: the window discovery reports the model is loaded at, then a probed window, then a target override, then a model hint, catalog knowledge, a local-native default, and finally a descriptor default.
+Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. A one-run `--max-context-tokens` override wins when present. Otherwise sources rank most-live first: the window discovery reports the model is loaded at, then a probed window, a target capability override, a model hint, knowledge-base data, the built-in model catalog, a runtime descriptor default, and finally Clio's assumed fallback.
 
 The loaded window outranks the declared one because it is the only figure describing what the backend will serve. LM Studio routinely opens a model well below its `max_context_length`, and a run planned against the larger number overruns the server before compaction ever fires. Discovery carries that number per model in `discoveredModelStates[<model>].contextLength`, and the residency notice reads the same entry, so a model Clio is budgeting a loaded window for is never announced as absent.
 
 A resumed session carries the loaded window it already recorded. A resume re-resolves its target before discovery has reported what the backend has open, so the first turn used to budget against the probed figure, which on a multi-slot or multi-copy backend can be several times the real headroom, and corrected a turn later. `lastLoadedContextWindow` reads the last `loaded` window the session's own `context-snapshots.jsonl` recorded for the same target and model and hands it to resolution as `knownLoadedContextWindow`. It is used only when live discovery reports nothing, and it is scoped to that target and model, so a different selection re-probes and a model reloaded at a new size corrects as soon as discovery names the live window.
 
-Local-native runtimes use a recommended minimum desired window of 128,000 tokens. If the live model reports a smaller loaded context window, Clio re-resolves the target so accounting uses the actual ceiling.
+Clio uses 131,072 tokens as the minimum desired window and as the fallback when no source reports one, on every runtime tier. A reported effective window below 128,000 tokens triggers the undersized-window warning. If a live model reports a smaller loaded context window, Clio re-resolves the target so accounting uses the actual ceiling.
 
 The `/context` overlay states which layer answered, next to the token total: `loaded`, `probed`, `configured`, `declared`, or `assumed`.
 
@@ -39,13 +39,13 @@ The `/context` overlay and footer meter read the same ledger categories in displ
 
 ## Single-threshold compaction
 
-Auto-compaction is controlled by one pressure threshold. Pressure is `budgeted_tokens / context_window`, where the budgeted figure is the reconciled total when the provider has attested one and the chars/4 estimate otherwise. The default threshold is `0.8`.
+Auto-compaction is controlled by `context.compaction.threshold`. Pressure is `budgeted_tokens / context_window`, where the budgeted figure is the reconciled total when the provider has attested one and the chars/4 estimate otherwise. The default threshold is `0.8`.
 
 Crossing that threshold engages three mechanisms in a fixed order. The first two are cheap, reversible, and call no model. Only the third rewrites what the session says about itself.
 
 ### 1. Working-set eviction
 
-When `compaction.auto` is enabled and pressure crosses the threshold before a request, Clio applies the configured working-set policy first. The policy selects tool-result bodies and closed-turn thinking blocks, `runAutoCompact` appends one `contextEviction` ledger entry, and `refreshAgentMessagesFromSession` projects those units out of model replay behind a one-line marker. Nothing is deleted: the ledger keeps the original bodies, the transcript keeps showing them, and `/resume`, `/tree`, `/fork`, and the HTML export are unaffected.
+When `context.compaction.auto` is enabled and pressure crosses the threshold before a request, Clio applies the configured working-set policy first. The policy selects tool-result bodies and closed-turn thinking blocks, `runAutoCompact` appends one `contextEviction` ledger entry, and `refreshAgentMessagesFromSession` projects those units out of model replay behind a one-line marker. Nothing is deleted: the ledger keeps the original bodies, the transcript keeps showing them, and `/resume`, `/tree`, `/fork`, and the HTML export are unaffected.
 
 Already-evicted units are never selected again. Recent turns keep their full observations and thinking, governed by `context.workingSet.protectLastTurns`. Results whose estimated body is below `context.workingSet.minEvictableTokens` (200 tokens by default) are kept whatever their age as a low-yield churn guard. The engine separately refuses any candidate whose marker would save no tokens. The `age-horizon` policy is therefore the selection the old destructive mask made minus those small results, not a byte-identical reproduction of it; the default `structural-v1` policy applies its structural rules before any age rule.
 
@@ -85,7 +85,7 @@ When the ledger is replayed to the model, compaction summaries, branch summaries
 
 Every provider Clio targets caches by exact prefix. Anthropic hashes the cumulative prefix up to a `cache_control` breakpoint and looks back at most 20 blocks for an earlier write; the minimum cacheable prefix is 512 to 4,096 tokens by model, reads cost 0.1x input and writes 1.25x. OpenAI caches automatically from 1,024 tokens in 128-token increments on exact prefix matches at 0.1x. vLLM hashes each KV block from its parent block's hash, so a change in one block invalidates every later block. llama.cpp (and LM Studio on top of it) picks the slot with the longest common prefix and re-evaluates only the suffix, and `--cache-reuse` can shift later KV chunks back into place after a mid-prompt removal. The consequence is the same everywhere except on llama.cpp with cache reuse: whatever bytes change, everything after the earliest changed position is re-prefilled. That is why a marker is byte-stable, why a recall rides the tail instead of restoring the body in place, why `structural-v1` batches evictions down to `target` instead of trimming on every turn, and why the replay tables report cold prefix tokens per event next to tokens evicted: at a 32k budget one event re-prefills most of the window whichever policy chose the items, so the lever that protects a cloud cache is the number of events, not their contents. A local backend with cache reuse pays less for the same removal, which is where finer-grained eviction and recall earn their keep.
 
-The procedural replay target sweep measured 0.4, 0.5, 0.6, and an exhaustive rung-6 stop over 24 traces. Target 0.4 and exhaustive selection converged because un-evictable residue exhausted the candidate pool. Against 0.6, target 0.4 cut cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, with no summary reduction and a 0.00072 reduction in retention covered at 128k. That is below the 10% cache-saving threshold set for changing a cross-tier default, so the default remains 0.6. The complete sweep and reopening rule are in the replay README.
+A historical local replay target sweep measured 0.4, 0.5, 0.6, and an exhaustive rung-6 stop over 24 traces. Target 0.4 and exhaustive selection converged because un-evictable residue exhausted the candidate pool. Against 0.6, target 0.4 cut cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, with no summary reduction and a 0.00072 reduction in retention covered at 128k. That was below the 10% cache-saving threshold used for the experiment, so the default remained 0.6. The generated tables and reopening calculation were local artifacts and are not versioned in this repository; use the replay commands in [Commands and Modes](../guide/commands-and-modes.md#working-set-replay) to measure the current tree.
 
 The same arithmetic governs the compiled system prompt, which sits ahead of every message. Its sections are ordered stable prefix first, so a section that can change between two turns never sits ahead of one that cannot; the order and the rule behind it are in [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md#section-order-stable-prefix-first).
 
@@ -139,9 +139,9 @@ Clio sends it at three moments: after the session prompt compiles at session sta
 
 The payload is the request the next turn would send minus the operator's text: the same system prompt, the same tool schemas, the same replayed messages, the same thinking level, and the same `cache_prompt`, with one single-character user message appended so the chat template renders the prefix up to the user turn, and `max_tokens: 1`. It is built through the same `streamSimple` dispatcher `createEngineAgent` hands the engine as its `streamFn`, not a hand-assembled payload, because any byte that differs ahead of the user turn defeats the purpose.
 
-The pre-warm is refused rather than queued whenever it would compete with real work. It runs only on `local-native` targets, whatever `prewarm.enabled` says, because a cloud provider bills the request and caches on its own schedule. It never runs while a turn is in flight, while any dispatch is outstanding, on a worker, or in headless `run`. The dispatch guard is a stand-in: without per-endpoint capacity accounting the pre-warm cannot tell whether a worker already occupies the server it would warm, so it stands down for all worker traffic. The round already claims one endpoint slot for as long as its request is out and releases it in a `finally`, through the `registerEndpointSlot` seam the chat loop wires from the endpoint-capacity registry, so capacity counts a pre-warm the same way it counts the orchestrator's streaming turn.
+The pre-warm is refused rather than queued whenever it would compete with real work. It runs only on `local-native` targets, whatever `chat.prewarm` says, because a cloud provider bills the request and caches on its own schedule. It never runs while a turn is in flight, while any dispatch is outstanding, on a worker, or in headless `run`. The dispatch guard is a stand-in: without per-endpoint capacity accounting the pre-warm cannot tell whether a worker already occupies the server it would warm, so it stands down for all worker traffic. The round already claims one endpoint slot for as long as its request is out and releases it in a `finally`, through the `registerEndpointSlot` seam the chat loop wires from the endpoint-capacity registry, so capacity counts a pre-warm the same way it counts the orchestrator's streaming turn.
 
-Pressing Enter lets go of an in-flight pre-warm at the keystroke, before the admission gate. Whether it also aborts the HTTP request is gated on what the backend does with a cancelled one, and the measured backend does nothing. On the operator's llama.cpp router (build `b226-2115b73d8`, Qwen3.8-27B, `--parallel 1`), aborting 1.5 s into a 47,620-token prefill did not cancel the server's work: the server finished prefilling, so the prefix did survive the abort and the next request read 47,596 of 47,620 tokens from cache with `prompt_ms 927`, but that request also waited 89.5 s of wall clock for the abandoned one to leave the single slot. Letting the pre-warm complete instead cost 89.3 s plus a 1.3 s turn, the same wall clock. The abort therefore frees no slot and saves no time on this backend; all it does is discard the usage and timings of prefill the server performed. So a submit detaches the round instead: Clio stops calling it the current pre-warm, never waits on it, withholds its `/context` line because it no longer describes the prefix the next turn will send, and still records what it cost. `ABORT_ROUND_ON_SUBMIT` in `src/interactive/turn-prewarm.ts` carries the measurement and flips the behavior for a backend that honors cancellation.
+Pressing Enter lets go of an in-flight pre-warm at the keystroke, before the admission gate. Whether it also aborts the HTTP request is gated on what the backend does with a cancelled one, and the backend used for the original experiment did nothing. On an earlier single-slot llama.cpp deployment (build `b226-2115b73d8`, Qwen3.8-27B, `--parallel 1`), aborting 1.5 s into a 47,620-token prefill did not cancel the server's work: the server finished prefilling, so the prefix did survive the abort and the next request read 47,596 of 47,620 tokens from cache with `prompt_ms 927`, but that request also waited 89.5 s of wall clock for the abandoned one to leave the single slot. Letting the pre-warm complete instead cost 89.3 s plus a 1.3 s turn, the same wall clock. The abort therefore freed no slot and saved no time on that backend; all it did was discard the usage and timings of prefill the server performed. The current operator topology is different: `mini` is a llama.cpp router at `192.168.86.141:8080` serving `ornith1.5-35b-moe` with four parallel slots and 262,144 context tokens per slot, while `dynamo` is LM Studio at `192.168.86.143:1234` serving `qwen3.8-27b-dynamo` for chat. The cancellation result must be remeasured before it is generalized to either deployment. A submit currently detaches the round: Clio stops calling it the current pre-warm, never waits on it, withholds its `/context` line because it no longer describes the prefix the next turn will send, and still records what it cost. `ABORT_ROUND_ON_SUBMIT` in `src/interactive/turn-prewarm.ts` carries the historical measurement and flips the behavior for a backend that honors cancellation.
 
 Each round appends one `prewarm` custom ledger entry carrying its trigger, the backend prompt tokens, `timing`, and `promptCache`. The entry is never rendered and never becomes a model message, so it contributes zero tokens to the context estimate. `/context` shows `prewarmed: N tokens in X ms` until the next settled run answers the question it asked. `prewarm` is never an expected-cold reason: a pre-warm is the opposite of a disturbance. Its provider usage is real spend and is reported to `/cost` and `clio-coder usage report` under its own row, the way a `/btw` side question is.
 
@@ -150,12 +150,8 @@ Each round appends one `prewarm` custom ledger entry carrying its trigger, the b
 The public settings use one compaction threshold plus a non-destructive working-set stage:
 
 ```yaml
-compaction:
-  auto: true
-  threshold: 0.8
-  excludeLastTurns: 6
-  # model: provider/summary-model-id
-  # systemPrompt: ~/.config/clio-coder/prompts/compaction.md
+chat:
+  prewarm: true
 
 context:
   workingSet:
@@ -164,12 +160,14 @@ context:
     target: 0.6
     protectLastTurns: 6
     minEvictableTokens: 200
-
-prewarm:
-  enabled: true
+  compaction:
+    auto: true
+    threshold: 0.8
+    # model: provider/summary-model-id
+    # systemPrompt: ~/.config/clio-coder/prompts/compaction.md
 ```
 
-`compaction.auto` controls the pre-request trigger. Manual `/context compact` still runs when `auto` is false. `compaction.model` optionally selects a dedicated summarization model, and `compaction.systemPrompt` optionally points at a prompt override file. `compaction.excludeLastTurns` only governs the temporary legacy mask path; working-set protection uses `context.workingSet.protectLastTurns`.
+`context.compaction.auto` controls the pre-request trigger. Manual `/context compact` still runs when `auto` is false. `context.compaction.model` optionally selects a dedicated summarization model, and `context.compaction.systemPrompt` optionally points at a prompt override file. The retired `compaction.excludeLastTurns` key is not part of settings v2. The temporary legacy mask uses its compiled six-turn fallback, while working-set protection uses `context.workingSet.protectLastTurns`.
 
 | Key | Default | Accepted | Meaning |
 | --- | --- | --- | --- |
@@ -300,11 +298,13 @@ owns each entry's status and rewrites the file after every page, so a run that
 ends early records exactly which pages are still owed. Staging survives such a
 run and the next one resumes from it.
 
-Every page opens with front matter carrying `title`, `summary`, `sources`,
-`symbols`, `tests`, `invariants`, and `validate`. That is the retrieval layer:
-`quickstart.md`, every directory `index.md`, and the task-routing table are
-generated from it after each run, so navigation cannot drift or miss a page and
-no writer has to remember to update it.
+Every page opens with repaired front matter. Its metadata model has `title`,
+`summary`, `sources`, `symbols`, `tests`, `invariants`, and `validate`, but the
+serializer always writes only `title`, adds `summary` when non-empty, and omits
+empty list fields. That metadata is the retrieval layer: `quickstart.md`, every
+directory `index.md`, and the task-routing table are generated from the repaired
+values after each run, so navigation cannot drift or miss a page and no writer
+has to remember to update it.
 
 Assembly repairs rather than rejects. A missing H1, absent or malformed front
 matter, a dangling `sources` entry, a link to a page that was never written, and
@@ -372,5 +372,5 @@ version, project language, file/config/symbol/edge counts, language and role
 counts, top areas, entry points, key symbols, and dependency samples. The
 welcome dashboard shows module count, wiki page count and freshness, and a
 small entry-point excerpt from the same digest. Agents query the structural
-layer through the read-only `code_nav` tool. See [tool-usage.md](tool-usage.md)
+layer through the read-only `code_nav` tool. See [tool-usage.md](../guide/tool-usage.md)
 for the full mode reference.