@iowarp/clio-coder 0.3.7 → 0.3.9

package/docs/evidence-and-memory.md

@@ -1,7 +1,7 @@
 # Evidence Corpus and Long-Term Memory
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.7). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.9). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
 
 Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.3.7, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
@@ -68,15 +68,15 @@ Eval evidence adds `eval-result.json` and uses empty receipt/protected-artifact
 | `audit-linked.jsonl` | Audit rows linked to run/session context when available. |
 | `receipt.json` | Receipt bundle (`{ version: 1, receipts: [...] }`); only receipts that pass integrity verification contribute verified fields. |
 | `gate-decisions.json` | Integrity-verified review verdicts, compete winner selections, and winner confirmations discovered from linked receipt ids. |
-| `trust-status.json` | Canonical per-run six-axis trust projections derived from authenticated receipts, gate decisions, grounded validation artifacts, and exact finish-contract audit rows. |
+| `trust-status.json` | Canonical per-run six-axis trust projections derived from authenticated receipts, gate decisions, and grounded validation artifacts. |
 | `protected-artifacts.json` | Protected artifact state/events. |
-| `findings.json` / `findings.md` | Structured and readable findings. |
+| `findings.json` / `findings.md` | Structured findings plus a readable report that begins with each linked run's canonical tier, fixed-order summary, and six axes. |
 
 ### Run attribution under concurrency
 
 Session ledger entries are attributed to a run by the run id the producer stamped on the entry at write time. Rows built from those entries carry that provenance in a `runLink` field (`{ kind, confidence, candidateRunIds? }`) in `tool-events.jsonl` and `protected-artifacts.json`; a write-time stamp is `kind: "entry-run-id"`, `confidence: "exact"`. Entries written without run context fall back to timestamp windowing, labeled `kind: "timestamp-window"`, `confidence: "best-effort"`, and printed as `link=timestamp-window` in the transcript. Concurrent dispatch runs share one clock and their windows overlap, so an entry inside more than one window has no owner the bundle can name. Such an entry is reported in the bundle of every run it may belong to, with `runId: null`, `kind: "ambiguous-timestamp-window"`, and a `candidateRunIds` list, plus a `best-effort-link` finding counting them. It is never dropped and never claimed as exact.
 
-When a run was chained (pipeline), composed with a persona override, or escalated for a permission, `transcript.md` and `trace.cleaned.jsonl` surface the receipt's provenance field sets, and `clio-coder evidence inspect` prints them as a `provenance <runId>:` block. The field paths, types, and stability labels are documented in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance).
+When a run was chained (pipeline), composed with a persona override, or escalated for a permission, `transcript.md` and `trace.cleaned.jsonl` surface the receipt's provenance field sets, and `clio-coder evidence inspect` prints them as a `provenance <runId>:` block. The block is the detail behind the canonical trust projection, never a second reading of it: it is printed only for a run whose seal the projection verified, its `autonomy:` line carries the policy name, external mode, and bypass flag and never the axis word (`mediated`, `approximated`, `bypassed` are the trust summary's to print), and a run whose seal was rejected or retired gets no block at all, so the output never publishes a value the projection reported as `absent`. The field paths, types, and stability labels are documented in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance).
 
 ### Task and decision provenance
 
@@ -106,6 +106,7 @@ Clio Coder classifies every run, session, and eval record using a closed set of
 | `blocked-tool` | Failure | The safety net blocked a tool call requested by the model. |
 | `escalation` | Precaution | A worker permission escalation timed out or was denied; see the receipt provenance schema below. |
 | `receipt-integrity` | Security | Forensic verification detected receipt modification or checksum mismatch. |
+| `receipt-retired` | Provenance | The receipt was sealed under an integrity version this build no longer verifies. It is not migrated and not read as evidence; the row names both versions. An info row, never the security warning a modified receipt gets. |
 | `protected-artifact`| Precaution | Mutating a path protected by project or system safety policies. |
 | `tool-loop` | Constraint | The model repeatedly called the same tool with identical arguments. |
 | `test-failure` | Failure | A verification command containing test/lint keywords exited non-zero. |
@@ -116,6 +117,9 @@ Clio Coder classifies every run, session, and eval record using a closed set of
 | `auth-failure` | Failure | Missing or invalid credentials/API keys. |
 | `external-bypass` | Security | An external runner bypassed standard safety gates. |
 | `external-approximation`| Validation | An external runner approximated results rather than fully executing. |
+| `independent-review` | Validation | The canonical independent-review axis: a failed, correlated, or inconclusive review is a warning; a successful run with no review at all is an info row saying its result rests on its own receipt. |
+| `context-provenance` | Provenance | The canonical context-provenance axis read `invalid`: the receipt's briefing or project-context record contradicts itself. |
+| `completion-evidence` | Validation | The canonical completion-evidence axis: a mutation that finished without validation evidence at the completion boundary is a warning; an explicit limitation is an info row. |
 | `unknown` | Undefined | Unclassified execution failure. |
 
 ---
@@ -207,30 +211,91 @@ They do not mutate receipt, gate-decision, evidence-bundle, or session formats.
 | Current receipt present but integrity not checked | Artifact integrity is `unknown`; the receipt's own digest never authenticates itself. The other receipt-owned axes are `absent` with `not_observed` until authentication succeeds. |
 | Historical receipt missing its integrity block | Receipt-owned axes are `unknown` through the compatibility source, even if a caller presents a contradictory positive verification result. |
 | Integrity verification succeeds or fails | Artifact integrity is `verified` or `failed`. A failure leaves the receipt-owned validation grounding, context provenance, and autonomy enforcement `absent`; no untrusted receipt claim contributes a positive state. Validation the session ledger observed on its own (a validation command that ran and exited 0) still grounds the run, so a tampered run can read `artifactIntegrity: failed` beside `validationGrounding: validated`. The two axes name different artifacts and different authorities, and the bundle's `receipt-integrity` finding is what flags the pairing. |
+| Receipt sealed under a retired integrity version | Artifact integrity is `unknown` through the compatibility source `run_receipt:<runId>:integrity-v<N>-retired`, which is where the human clause reads the version back from (`seal v19 retired (this build verifies v20)`); `failed` and "seal broken" are reserved for a seal this build checked and rejected. The receipt-owned axes are `absent` with `historical_format`, and the verdict is `unknown` rather than `compromised`. The receipt is not migrated and not read as evidence: the bundle records a `receipt-retired` info finding, `evidence build` prints it as a note and exits 0, and `/view verify` reports `verify retired` with both versions. |
 | Receipt `verification.state: verified` | Validation grounding is `validated` unless a stronger typed failure or ungrounded claim is present. |
 | Receipt `verification.state: unverified` | Validation grounding is `absent` with `not_observed`; lack of a validation tool is not a failed validation. |
 | Receipt verification `unknown` or `not_applicable` | Validation grounding preserves `unknown` or `not_applicable`. A missing historical verification field maps to `unknown`. |
 | Typed receipt validation or result-contract quality | A passing correctness-bearing fact maps to `validated`; a failing fact maps to `failed`; an ungrounded passing claim maps to `ungrounded`. |
-| Valid bounded project context or valid briefing hash | Context provenance is `recorded`. Explicit project-context tier `none` with no briefing is `not_applicable`; a missing historical field is `unknown`; a contradictory block is `invalid`. |
+| Valid bounded project context, valid none-tier workspace-root record, or valid briefing hash | Context provenance is `recorded`. A `none`-tier run still receives the workspace-root message, so a none-tier block naming exactly `workspace-root` with a well-formed count and hash is `recorded`. Explicit project-context tier `none` with no content and no briefing is `not_applicable`; a missing historical field is `unknown`; a contradictory block (a handbook section under a none policy, a hash with no section, a malformed count) is `invalid`. |
 | Gate decision | An authenticated independent pass or fail maps to `passed` or `failed`. Correlated review maps to `not_independent`. Unauthenticated artifacts map to `unknown`; operator or full-auto confirmation alone is `not_applicable` to independent review. |
 | Receipt autonomy grade | `mediated`, `approximated`, and `bypassed` map to `enforced`, `approximated`, and `bypassed`. A dangerous-bypass flag always normalizes to `bypassed`; a missing historical block is `unknown`. |
-| Finish-contract assessment | `validation_evidence`, `unvalidated_mutation`, `explicit_limitation`, and `no_mutation` map to `evidenced`, `incomplete`, `limited`, and `not_applicable`. A run whose receipt was presented and rejected downgrades `evidenced` to `unknown`: the row still points at its own record, but a rejected receipt authenticates nothing about the run it names. |
-| Malformed audit row identifier | A blank or whitespace-only optional identifier is treated as absent. The row falls back to its derived correlation id or drops out of the trust projection; it never aborts the bundle. |
+| Finish-contract assessment | The assessment remains linked in `audit-linked.jsonl` and contributes its domain findings and tags. It does not override the receipt-derived `completionEvidence` axis on the evidence surface alone. |
+| Malformed audit row identifier | A blank or whitespace-only optional identifier remains linked as audit input and never aborts the bundle. It cannot affect the receipt-derived trust projection. |
 | Bundle without `trust-status.json` | Inspection reports `projection: historical_format` with no canonical run projections. It never reconstructs positive states from older summary tags. |
 
 Receipt inspection, worker output, monitor details, and evidence rebuilding all
 use the same authenticated receipt projection boundary. Evidence rebuilding
-then composes independently authenticated gate decisions and exact
-finish-contract records without changing receipt-owned axes. Findings such as
-`no-validation`, `proxy-validation`, `external-approximation`, and
-`external-bypass` are selected from the canonical states, while their detailed
-domain artifacts remain in the receipt, gate, audit, and trace files.
+then composes independently authenticated gate decisions without changing
+receipt-owned axes. Findings such as
+`no-validation`, `proxy-validation`, `external-approximation`,
+`external-bypass`, `independent-review`, `context-provenance`, and
+`completion-evidence` are selected from the canonical states. `findings.md`
+prints the tier, summary, and every axis before those diagnostic records, while
+their detailed domain artifacts remain in the receipt, gate, audit, and trace
+files.
 
 The canonical aggregate is an additive projection for downstream work. Receipt
 integrity remains version 18, evidence bundles remain version 1, gate decisions
 remain version 2, and no persisted receipt field or cryptographic algorithm
 changes.
 
+### Trust projection
+
+`src/domains/evidence/trust-projection.ts` is the one place the canonical
+status is turned into words. Every operator surface prints from it, so the
+same canonical input renders the same verdict on the dispatch run line, in a
+monitor block, under `clio-coder evidence inspect`, in `findings.md`, on the
+Alt+W board, in the `/view` receipt header, in eval metrics, and on the ACP
+wire.
+
+The compact human line has six fixed clauses in a fixed order and answers the
+four operator questions without receipt internals:
+
+```text
+trust v1: sealed; grounded by host-verification; not independently reviewed; mediated; context recorded; completion evidenced
+```
+
+| Clause | Axis | Question it answers |
+|---|---|---|
+| `sealed` / `seal broken` / `seal unchecked` / `no receipt` | Artifact integrity | Can the record be trusted to be what was written? |
+| `grounded by <claimant>` / `validation failed by <claimant>` / `inferred: validation claimed, none observed` / `no validation observed` / `validation unknown (<system>)` / `validation not applicable` | Validation grounding | Who claims the result, and what was observed? |
+| `independently reviewed: pass` / `independently reviewed: fail` / `independent review inconclusive` / `review not independent` / `not independently reviewed` | Independent review | What did a second, uncorrelated authority check? |
+| `mediated` / `approximated (<runtime>)` / `bypassed (<runtime>)` / `autonomy not recorded` | Autonomy enforcement | Did Clio's own gate mediate the run? |
+| `context recorded` / `context record invalid` / `context not recorded` | Context provenance | Is what the worker was given recorded consistently? |
+| `completion evidenced` / `completion unevidenced` / `completion limited` / `completion not applicable` | Completion evidence | What did the finish contract observe? |
+
+`mediated` is the word for the `enforced` state because it is what the
+receipt grade already says; `inferred` is the word for an `ungrounded` claim.
+Every `unknown` and `absent` state prints as such, so what remains unknown is
+part of the line, never an omission.
+
+The drill-down line prints every axis by its canonical state id and is the
+same on every text surface:
+
+```text
+trust_status=v1 artifactIntegrity:verified validationGrounding:validated independentReview:absent contextProvenance:recorded autonomyEnforcement:enforced completionEvidence:evidenced
+```
+
+The machine projection (`TrustSummaryProjection`, `trust` on the `dispatch`
+tool's `details.runs[]` entries and on the `monitor` receipt details) is
+bounded and versioned: the verdict tier, the six axis states, the claimant,
+the axes still unknown, the compact text, and up to 8 `<kind>:<id>`
+references into the detailed artifacts. It is flat by design so a depth-capped
+wire such as ACP `rawOutput` carries it whole where the nested canonical
+status's artifact references fall off the depth cap.
+
+The verdict tier styles a surface and never scores a run. `reviewed` is the
+only tier styled as independently verified; a sealed receipt with observed
+validation is `grounded`, a sealed receipt with nothing observed is
+`unverified`, a broken seal, bypassed gate, failed or inferred validation,
+failed or correlated review, or contradictory context record is
+`compromised`, and an unchecked or missing seal is `unknown`. The Alt+W board
+never carries a verdict on the terminal bus event: the event is published the
+moment the receipt is sealed, before anything has read it back and
+authenticated it against the ledger row, so the board reads the receipt file
+back and projects that authenticated status, and shows `trust: receipt not
+read back` until it can.
+
 ### Mutation-Report Grounding
 
 Mutation-report receipts are grounded directly against observed tool events recorded in the run ledger:

package/docs/evolution.md

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

package/docs/extensions-and-sharing.md

@@ -1,7 +1,7 @@
 # Extensions, Prompt Templates, Skills, and Share Archives
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.9).
 
 Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that contribute prompts and skills. Share archives are portable JSON files for moving project/user Clio resources between machines or collaborators. Themes are built into the engine and are no longer loaded from extensions.
 
@@ -197,6 +197,8 @@ Required fields are `manifestVersion: 1`, `id`, `version`, and `description`. `n
 
 IDs must be lowercase and may include numbers, dots, underscores, and hyphens; they must start/end alphanumeric.
 
+`compatibility.clio` is optional. When present, it must be a valid SemVer range such as `>=0.3.8`, `^0.3.8`, or `0.3.x`. Installation refuses a package whose range excludes the running Clio version and names the extension, its declared range, and that running version. Clio repeats the check whenever it loads installed extensions, so a package that becomes incompatible after a Clio version change stays visible in `extensions list` with its diagnostic but contributes no resources. An incompatible project package does not hide a compatible user package with the same ID. A manifest without `compatibility.clio` keeps the existing unrestricted behavior.
+
 ---
 
 ## Extension CLI

package/docs/fleet-dispatch.md

@@ -1,6 +1,6 @@
 # Fleet Dispatch
 
-> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.9).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -424,8 +424,18 @@ marker and no answer text.
 
 `synthesis: "none"` returns the final member answers directly. `vote` performs
 a deterministic majority tally over structured `verdict` fields without a
-model call. A vote with no majority reports `no_majority`, and a vote with no
-verdict fields reports `no_verdict_field`. `judge` runs one additional read-only judge against all final
+model call. A vote council asks each member for that verdict: the member's task
+carries the ballot directive and the member's run seals a `council-ballot`
+postcondition, `{"verdict":"...","text":"..."}`, in place of the seated
+recipe's own result contract. The seated agent, its persona, and its read-only
+tool profile are unchanged, so any recipe can be voted with. The verdict is a
+single line of at most 64 bytes and is lower-cased before the tally, so members
+who reach the same conclusion land on the same key; the reasoning belongs in
+`text`, which is what the council report shows as the member's answer. A member
+that seals no conforming ballot fails its own run and is reported as a failed
+member rather than dropping silently out of the count. A vote with no majority
+reports `no_majority`, and a vote whose final members all failed reports
+`no_verdict_field`. `judge` runs one additional read-only judge against all final
 answers. Every member run seals a receipt. A judge receipt points backward to
 every final member receipt through gate provenance. The approval artifact names
 each member's label, target, model, thinking level, node, color, round count,
@@ -521,12 +531,14 @@ The grammar for declared write boundary entries requires repository-relative POS
 Write boundary enforcement is detect-and-rollback, never OS or filesystem sandboxing. A step runs with whatever filesystem permissions its underlying execution environment possesses. Upon step completion, the orchestrator inspects the working tree to verify compliance:
 1. Snapshot baseline: Before a step executes, the orchestrator captures a snapshot (`captureWorkspaceSnapshot`) recording the baseline git HEAD commit and existing dirty path content tokens.
 2. Workspace diffing: After step completion, the orchestrator runs git status inspection (`diffWorkspace`) to identify changed paths relative to the snapshot baseline commit.
-3. Rollback execution: Unauthorized changes (modified paths not covered by the step's declared allowlist) are automatically rolled back (`rollbackPath`).
-4. Content source: Rollback restores content strictly from what git already has in the pinned baseline commit (`snapshot.head`). If a path was already dirty when the step snapshot was captured, its prior content is not stored in git, so in-place restoration cannot be guaranteed. The working tree is left as the step made it, and the status settles as `rollback-incomplete`.
-5. Violation handling: Any unauthorized change fails the step with the typed reason `writes_boundary_violation`.
-6. Window attribution: Enforcement evaluates scheduling windows (`wave-<n>` or `revalidate-<stepId>-<n>`). A wave window cannot combine steps with overlapping declared boundaries or multiple concurrent step writers, ensuring single-step attribution.
-7. Ignored paths and state subtraction: Enforcement evaluates paths reported by git status. Git-ignored paths remain outside enforcement. The Clio state directory (`.clio-coder/` or `clioStateDir()`) is subtracted from status checks so orchestrator receipts, code step log artifacts, and boundary verdicts do not trigger false violations.
-8. Durable records: Verdicts are serialized as JSON records at `write-boundaries/<rootId>/<window>.json` under the Clio state directory, carrying the baseline HEAD commit, checked paths, violations, rollback actions, status, and SHA-256 digest.
+3. Authorship attribution: A changed path outside the allowlist is blamed on the window only when it intersects what the window's own runs recorded writing. That record is the run's tool-call stream, folded by the same recorder that grounds a sealed mutation report and read back through `DispatchContract.observedRunWriteAttribution`. A change that no run in the window recorded is an unattributed concurrent change: it is listed under `unattributed` in the verdict and reported to the operator, and it is never rolled back. This is what keeps a file an operator edited while a fleet ran from being overwritten with its committed version.
+4. Open records: A run's recorded write set is read as a closed list only when the run could not have written outside it. A window whose steps do not all offer a closed record falls back to blaming every change outside the allowlist, which is the behavior that predates attribution. Three things open a record: a `kind: code` step, whose registered command publishes no tool events; a run whose tool telemetry coverage is not `complete`, such as one on a subprocess runtime; and a run that made a successful call to a tool able to mutate a path its own arguments do not name. That last set is derived from the tool surface rather than authored, as every registered tool outside the `read` and `write` action classes, which today is `bash`, `verify`, `dispatch`, and `steer`, plus any dynamic or MCP tool whose schema this process cannot read. The `git` tool is a closed status, diff, and log surface and stays enumerable. When a successful opaque call opens the record, the live Alt+W card immediately names the tool and says that its arguments cannot enumerate every path it may write. The durable verdict records `attributionComplete: false` and an `attributionDowngrades` entry with the reason, tool name, tool call id, run id, and step id. The after-the-fact write-boundary message repeats that cause before explaining why the whole outside diff was blamed on the window.
+5. Rollback execution: Attributed unauthorized changes are automatically rolled back (`rollbackPath`).
+6. Content source: Rollback restores content strictly from what git already has in the pinned baseline commit (`snapshot.head`). If a path was already dirty when the step snapshot was captured, its prior content is not stored in git, so in-place restoration cannot be guaranteed. The working tree is left as the step made it, and the status settles as `rollback-incomplete`.
+7. Violation handling: Any attributed unauthorized change fails the step with the typed reason `writes_boundary_violation`.
+8. Window attribution: Enforcement evaluates scheduling windows (`wave-<n>` or `revalidate-<stepId>-<n>`). A wave window cannot combine steps with overlapping declared boundaries or multiple concurrent step writers, ensuring single-step attribution.
+9. Ignored paths and state subtraction: Enforcement evaluates paths reported by git status, which never lists a git-ignored path. A declared `writes` entry the repository ignores is therefore refused before anything runs, by `fleet validate`, by `fleet run` preflight, and by the `/fleet run` preview, with a diagnostic naming the entry and the ignoring rule (for example `'work/' is ignored by .gitignore:1:work/`). Silently certifying such a window as clean is not an option, because nothing about it was observed. The Clio state directory (`.clio-coder/` or `clioStateDir()`) is subtracted from status checks so orchestrator receipts, code step log artifacts, and boundary verdicts do not trigger false violations.
+10. Durable records: Verdicts are serialized as JSON records at `write-boundaries/<rootId>/<window>.json` under the Clio state directory, carrying the baseline HEAD commit, checked paths, violations, unattributed concurrent changes, the attribution completeness flag and downgrade causes, rollback actions, status, and SHA-256 digest.
 
 ### Bounded check/repair loops
 
@@ -670,6 +682,19 @@ Assignment status, attempt ids, and terminal run id are stored separately in
 Pipelines and batches await assignment terminals, so downstream stages consume
 the successful fallback output rather than an earlier failed attempt.
 
+A fleet run is the exception to "the attempts settle the record". Every step of
+a fleet dispatches under the fleet root id as its lineage root, so all of them
+share one row, and no single step is the run's verdict. The run claims the row
+by writing `verdictOwner: "fleet"` when it opens, files every settled step's
+terminal run id in `attempts` (an agent step's receipt id, a code step's
+`code-*` run id, whose report sits under `code-steps/<fleetRootId>/`), and
+writes `status` once at the end from the whole-run outcome. Until then the row
+stays `running`, and a step settling under it records its attempt without
+touching the status. A run that stops before its last step, whose final step
+fails, or that throws is `failed`; a run abandoned by a crashed process is
+reconciled to `failed` at the next startup rather than inheriting a green
+step's success.
+
 Editing assignments also own one baseline-pinned workspace transaction. Every
 attempt gets a distinct worktree. Before any winning diff can reach the
 destination checkout, a pure gate checks terminal outcome, receipt integrity,

package/docs/glossary.md

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

package/docs/installation-and-lifecycle.md

@@ -3,7 +3,7 @@
 Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.7). You can open it directly in any web browser to view details dynamically.
+> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.9). You can open it directly in any web browser to view details dynamically.
 
 ---
 

package/docs/middleware-and-components.md

@@ -1,7 +1,7 @@
 # Middleware and Component Registry
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.9).
 
 Clio Coder has two related but separate surfaces:
 

package/docs/model-catalog.md

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

package/docs/observability.md

@@ -1,7 +1,7 @@
 # Observability Viewer
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.9).
 
 `/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
@@ -13,6 +13,35 @@
 
 `/view` opens a full-screen split viewer. The left pane groups artifacts by category and supports type-to-filter. The right pane renders the selected artifact with pager controls. `Tab` or `Shift+Tab` switches between the artifact list and details. `Left` and `Right` jump to the previous or next non-empty category from either pane; `Up` and `Down` select artifacts in the list or scroll details in the content pane. Category jumps honor the active filter and wrap at the ends. `v` verifies a selected receipt. `o` shows the absolute backing path through the notice channel when the selected artifact has one; pathless artifacts produce a warning notice instead. In the list pane, `Esc` clears a non-empty filter before a second `Esc` closes the viewer.
 
+## Trace retention and state usage
+
+The SQLite trace mirror at `<state-dir>/trace.sqlite` is rebuildable and bounded. By default Clio retains terminal runs for 30 days and limits the allocated database to 128 MiB (134,217,728 bytes), whichever limit is reached first. The policy runs after each dispatch or interactive turn becomes terminal. It deletes a run as one unit across `runs`, `phases`, `events`, `envelopes`, `gate_results`, `agent_sessions`, and `processes`. A `queued` or `running` run is never a candidate, even when its start time is older than the age cutoff or its rows put the store over the byte limit.
+
+Two environment variables configure the automatic policy:
+
+| Variable | Default | Valid values |
+| --- | ---: | --- |
+| `CLIO_CODER_TRACE_RETENTION_DAYS` | `30` | An integer of at least 1. |
+| `CLIO_CODER_TRACE_MAX_BYTES` | `134217728` | An integer of at least 1,048,576. |
+
+An operator can apply the current policy immediately or supply one-command overrides:
+
+```bash
+clio-coder trace prune
+clio-coder trace prune --max-age-days 14 --max-bytes 67108864
+clio-coder trace prune --json
+```
+
+The command reports terminal runs removed, total rows removed across the seven run-owned tables, physical bytes reclaimed from `trace.sqlite` and its WAL sidecars, whether `VACUUM` ran, and how many live runs were protected. Age pruning uses a terminal run's `ended_at`. Size pruning removes the oldest terminal runs until the live database pages fit or no terminal candidate remains.
+
+Deleting SQLite rows creates reusable pages but does not normally reduce the file. Clio runs `VACUUM` when at least 20 percent of allocated pages are reclaimable, or whenever reclaiming deleted pages is necessary to enforce the 128 MiB bound. It then truncates the WAL. Smaller deletions remain available for SQLite to reuse and avoid rewriting the whole database on every completed run.
+
+`clio-coder doctor` includes a `state storage` row with the recursive byte total for the state directory and the largest top-level contributor. For example:
+
+```text
+OK   state storage          96.4 MiB (101,082,624 bytes); largest contributor trace.sqlite at 89.9 MiB (94,248,960 bytes)
+```
+
 ---
 
 ## The Evidence Spine End-to-End
@@ -69,8 +98,28 @@ An `EvidenceIndexRow` has the following schema:
 | `turns` | `turns in window` and the `tokens` fact | Folded calls that were turns, so labelled calls are subtracted exactly as `/cost` subtracts them. |
 | `sideQuestions` | `side questions in window` and the `tokens` fact | `/btw` rounds in the window. |
 | `handoffs` | `handoffs in window` and the `tokens` fact | `/handoff` extraction rounds in the window. |
+| `prewarms` | `pre-warms in window` and the `tokens` fact | Prompt pre-warm rounds in the window. |
+| `backgroundMemorySteps` | `background memory steps in window` and the `tokens` fact | Proactive-memory model steps in the window. |
+
+The last five fields appear only when at least one labelled call falls in the window, and each individual line is printed only when its own count is above zero. An archive with no labelled call in it renders exactly as it did before those fields existed, so their presence is itself the signal that money was spent beside a session. All four labelled kinds are subtracted from `turns` the same way, so a session's turn count never includes a round the operator did not take.
+
+The report also prints a prompt-cache block, one row per session that recorded any cache telemetry:
+
+```text
+  prompt cache by session (from backend timings and persisted verdicts)
+  session       uncached prefill  hot/partial/cold/small
+  3vpu6z19ee7t  130353            4/3/2/0
+```
 
-The last three fields appear only when at least one labelled call falls in the window. An archive with no `/btw` or `/handoff` round in it renders exactly as it did before those fields existed, so their presence is itself the signal that money was spent beside a session.
+`uncached prefill` is the sum of the backend's own newly evaluated prompt tokens across every persisted call in that session, and reads `n/a` rather than `0` when the server reported no cache figure to subtract. The four counts are the per-call verdicts. Both facts are also in `--json` under a `session-cache` fact per session.
+
+`clio-coder doctor` reports the same evidence for the latest session only, as one row, so a cache problem is visible without opening the TUI or a report:
+
+```text
+OK cache telemetry  last session 3vpu6z19ee7t: hot 4 · partial 3 · cold 2 · small 0; top expected reason dispatch (3)
+```
+
+The row reads `top expected reason none` when the session recorded verdicts but no expected-cold reason, and it degrades to a warning saying `no prompt-cache telemetry recorded` when the latest session has none at all, which is the honest answer for a target whose backend reports nothing rather than a claim of a perfect cache. "Latest" selects the most recent `current.jsonl` by its newest entry timestamp, falling back to the file's mtime, so the other diagnostic JSONL files in a session directory cannot be mistaken for the conversation.
 
 ### The Out-of-Turn Usage Store
 
@@ -102,6 +151,8 @@ A row has the following schema:
 
 `repoIdentity` is the same cwd hash the session ledger is filed under, which is what lets `usage report --repo <path>` select these rows with the hash it already computes for the ledgers.
 
+`label` is one of `side-question`, `handoff`, `prewarm`, or `background-memory`. The last two joined for the same reason as the first two: a prompt pre-warm and a proactive-memory step are provider calls the operator did not ask for and would otherwise never see, and neither appends anything to the session JSONL. A row may also carry `timing { durationMs }` and a `promptCache` block built from the backend's own prefill facts when the server reported them; a backend that reports no timings simply omits the block, as LM Studio's OpenAI-compatible port does.
+
 ---
 
 ## Artifact Categories and Path Layouts
@@ -175,7 +226,7 @@ describes validation evidence inside that verified receipt. Likewise,
 message. Model-facing dispatch and collect output name all four concepts
 separately and never substitute one hash for another.
 
-The evidence bundle renders these sets in `transcript.md` (human sentences) and `trace.cleaned.jsonl` (structured run rows), `clio-coder evidence inspect` prints them as a `provenance <runId>:` block, and the `dispatch` tool appends a compact suffix to each run line plus additive keys on `details.runs[]`. A timed-out or denied escalation also raises an `escalation` finding in the bundle.
+The evidence bundle renders these sets in `transcript.md` (human sentences) and `trace.cleaned.jsonl` (structured run rows), `clio-coder evidence inspect` prints them as a `provenance <runId>:` block, and the `dispatch` tool appends a compact suffix to each run line plus additive keys on `details.runs[]`, including `trust`, the bounded canonical trust projection described in [evidence-and-memory.md](evidence-and-memory.md#trust-projection). A timed-out or denied escalation also raises an `escalation` finding in the bundle.
 
 The base provenance sets, steering, routing, quality, worker identity, result-conformance, council provenance, and fleet gate provenance use the strict v19 shape frozen for the release. These fields are labeled `experimental` until the schema is promoted post-1.0. For the complete version registry and migration contract across all artifacts, see [artifact-versions.md](artifact-versions.md).