@iowarp/clio-coder 0.4.1 → 0.4.3

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
@@ -29,11 +33,12 @@ Markdown.
 | RCA write-ups for shipped fixes | the GitHub issue's closing comment, never a committed file | Human deliverable |
 | Codewiki index | `.clio-coder/codewiki.json` | Agent-to-agent |
 | Markdown wiki | `.clio-coder/wiki/` | Human transient |
+| Architecture maps: `context map` seeds and archify-delivered HTML | `.clio-coder/artifacts/maps/` | Human transient |
 | Session context state | `.clio-coder/state.json` | Agent-to-agent |
 | 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 +46,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 +67,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 +101,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 recorded side question, handoff, prompt prewarm, background-memory call, or summary stream in an unsuccessful compaction. Labels are `side-question`, `handoff`, `prewarm`, `background-memory`, and `failed-compaction`; rows retain session/repository identity, timestamp, selected target/model, and observed usage. New failed-compaction rows add `callOutcome`, nullable unknown usage fields, and estimated/unknown cost provenance; legacy numeric rows remain readable. Successful compactions keep usage on their checkpoint. 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.
 
 ---