@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/{evidence-and-memory.md → architecture/evidence-and-memory.md}

@@ -1,9 +1,9 @@
 # Evidence Corpus and Long-Term Memory
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.4.0). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
+> **Visual blueprint:** The source checkout includes the complete
+> [Evidence Corpus and Long-Term Memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/memory_blueprint.html).
 
-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.4.0, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
+Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. Currently, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.
 
@@ -15,11 +15,17 @@ Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/ev
 clio-coder evidence build --run <runId>
 clio-coder evidence build --session <sessionId>
 clio-coder evidence build --eval <evalId>
-clio-coder evidence inspect <evidenceId>
+clio-coder evidence inspect <evidenceId> [--json]
 clio-coder evidence list
+clio-coder evidence inventory --json
 ```
 
-`clio-coder evidence inspect <id>` requires a valid evidence artifact ID. If the requested artifact does not exist on disk, it outputs `error: evidence artifact not found: <id> (see clio-coder evidence list)` and exits with code 1.
+`clio-coder evidence inspect <id>` requires a valid evidence artifact ID. If the requested artifact does not exist on disk, it exits with code 1 and prints the error and remedy on separate lines:
+
+```text
+error: evidence artifact not found: <id>
+  run `clio-coder evidence list` to see local bundles
+```
 
 Evidence IDs are deterministic:
 
@@ -76,7 +82,7 @@ Eval evidence adds `eval-result.json` and uses empty receipt/protected-artifact
 
 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 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).
+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
 
@@ -86,7 +92,7 @@ Session evidence retains the two operator-facing bookkeeping ledgers instead of
 
 ## Evidence Tag Taxonomy and Failure Causes
 
-Clio Coder classifies every run, session, and eval record using a closed set of 25 canonical tags. These tags distinguish general execution characteristics (such as lineage linkages) from actual failure causes.
+Clio Coder classifies every run, session, and eval record using a closed set of 29 canonical tags. These tags distinguish general execution characteristics, such as lineage linkages, from actual failure causes.
 
 ### Complete Taxonomy
 
@@ -131,8 +137,8 @@ A subset of the taxonomy represents actual failure causes (governed by the `FAIL
 1. **`timeout`**: Triggered if the run outcome is `"timed_out"` or `"stalled"`, or if the error/failure text contains `"timed out"` or `"timeout"`.
 2. **`auth-failure`**: Triggered if failure text contains keywords like `"auth"`, `"api key"`, `"credential"`, or `"unauthorized"`.
 3. **`missing-dependency`**: Triggered if failure logs contain `"module not found"`, `"missing package"`, or `"missing dependency"`.
-4. **`build-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with build tool names in `toolStats` (e.g. `build`, `compile`, `make`, `cmake`, `cargo`, `gradle`, `ninja`, `tsc`). Forensic evidence can also classify a non-zero run from build language in the recorded task text.
-5. **`test-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with test or lint tool names in `toolStats` (e.g. `pytest`, `ctest`, `jest`, `vitest`, `test`, `lint`, `typecheck`). Forensic evidence can also classify a non-zero run from validation language in the recorded task text.
+4. **`build-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with build tool names in `toolStats` (e.g. `build`, `compile`, `make`, `cmake`, `cargo`, `gradle`, `ninja`, `tsc`). Forensic evidence may also classify it from termination diagnostics in `outcomeDetail` or the recorded failure message. The task text is never causal evidence.
+5. **`test-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with test or lint tool names in `toolStats` (e.g. `pytest`, `ctest`, `jest`, `vitest`, `test`, `lint`, `typecheck`). Forensic evidence may also classify it from termination diagnostics in `outcomeDetail` or the recorded failure message. Validation words in the task text are never causal evidence.
 6. **`blocked-tool`**: Triggered if tool execution statistics show a blocked count greater than `0`.
 
 ---
@@ -152,12 +158,13 @@ Each run receipt (persisted under `<stateDir>/receipts/<runId>.json`) carries an
 ### Computation and Lifecycle
 - **Circular Dependency Prevention**: To prevent circular dependencies, `findingsSummary` is calculated **cheaply in-memory** at receipt-record time using the draft envelope and tool statistics (in `src/domains/dispatch/receipt-findings.ts`). It never reads from disk or calls `buildEvidence`.
 - **First-Pass Success**: Calculated as `true` only if the terminal outcome was `"succeeded"`, the lineage attempt was `0` (no dispatch retries), the tool stats confirm at least one successful validation tool was executed, and no failure-cause tags were detected.
-- **Cryptographic Coverage**: Current receipts use strict v19 and authenticate every current receipt field, including briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance, against the reconstructed ledger. Every version other than v19 is rejected; there is no historical receipt reader.
+- **Cryptographic Coverage**: Current receipts use strict v20 and authenticate every current receipt field, including dispatch intent path provenance, resolved path scope, briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance, against the reconstructed ledger. Only v20 is authenticated as current evidence. Lower versions are reported as retired and are neither migrated nor read as evidence.
 
 | Version | Verification policy | Compatibility policy |
 |---|---|---|
-| v19 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
-| Any other version | No reader | Rejected; remove or archive the incompatible state rather than expecting migration |
+| v20 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
+| v1 through v19 | Historical sealed shape unsupported by this build | Reported as retired; not migrated and not read as evidence |
+| Malformed, unversioned, or future version | No current reader | Invalid; archive incompatible state rather than expecting migration |
 
 Receipt integrity and evidence verification answer different questions. The
 former proves that a receipt matches its ledger envelope; the latter records
@@ -234,10 +241,10 @@ 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.
+The canonical aggregate is an additive projection for downstream work. Evidence
+bundles remain version 1 and gate decisions remain version 2. Receipt integrity
+is independently versioned and currently uses v20; that version adds dispatch
+intent path provenance and resolved path scope while retaining SHA-256 sealing.
 
 ### Trust projection
 

package/docs/{middleware-and-components.md → architecture/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.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Middleware and Component Registry visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/middleware_blueprint.html).
 
 Clio Coder has two related but separate surfaces:
 
@@ -51,7 +51,10 @@ It does not execute scanned files.
 | `eval-suite` | reserved kind | descriptive |
 
 > [!WARNING]
-> The current scanner still looks for `doc-spec` files under `docs/specs/`. Most public docs now live flat under `docs/*.md`, so public docs may not appear as `doc-spec` components until the scanner is updated.
+> The current scanner still looks for `doc-spec` files under `docs/specs/`.
+> Public reference pages now live under `docs/guide/`, `docs/architecture/`,
+> `docs/process/`, and `docs/history/`, so they do not appear as `doc-spec`
+> components unless the scanner's dedicated root is updated.
 
 ### Reload classes
 
@@ -124,17 +127,20 @@ These ship in every interactive session. Each is one bounded behavior with a vis
 | --- | --- | --- |
 | `nudge.stalled-turn` | `turn_end` | The one declarative rule. A turn that called no tools and ended on an announced action ("Next I will inspect `src/cli/index.ts`") is continued once with a reminder to perform it or say plainly that it is finished. Questions, "let me know", conditional offers ("if you want me to"), and completion statements are not announcements. |
 | `observer.skills-reminder` | `turn_start`, `turn_end` | Once per session, on the first substantive turn, when installed or installable skills exist, injects one line teaching the suggestion protocol: list with `context(scope="skills")`, open the reply with `Suggested skill: /skill <name>` when one matches, then continue the task in the same turn. Only the operator loads a skill. At `turn_end`, a reply that made the suggestion and stopped with only listing calls behind it is continued once (#184): the suggestion is not the task. Greetings do not spend the session's one reminder; a resumed or forked session never gets one. |
+| `observer.marketplace-offer` | `turn_start`, `after_tool` | On coordinator sessions, locally matches a substantive request against undeclined, uninstalled skills in Clio's marketplace and offers each matching skill at most once per session. Every autonomy level, including `full-auto`, asks the operator through a tag-bound `ask_user` choice; `Not now` lasts for the session and `Never offer this skill` persists for that skill version. Only an explicit answer to the bound offer can install a skill. Consented installs pass the Clio-marketplace source gate; installation does not itself load the skill. |
 | `observer.task-board-reminder` | `turn_start` | Once per session, when the operator's text literally enumerates three or more steps (`1)`, `2.`, `step 3:`, or three bulleted lines), injects one line asking for `tasks action="plan"` before the first edit. Prose that merely mentions numbers never counts. |
 | `nudge.open-tasks` | `turn_end` | A settled work turn (one that called tools) that ends while the session task board still has pending or active tasks is continued once with the open list. Pure conversation turns, aborted or errored turns, and boards where every remaining task is blocked do not trigger. |
 | `nudge.detached-dispatch` | `turn_end` | A settled turn that ends while a detached dispatch batch has every run terminal and uncollected is continued once, naming the ready batches; `monitor mode="collect"` clears it, including across resume. Batches with runs still in flight, and surfaces without `monitor`, do not trigger. |
 | `nudge.read-only-exploration` | `after_tool`, `turn_end` | After nine or more read-only calls (`read`, `grep`, `find`, `ls`, `code_nav`, read-only shell) in one user turn without a successful Scout dispatch, injects one advisory to delegate broad reconnaissance to Scout. One advisory per user turn, and only on surfaces that have `dispatch`. |
 | `rail.unbacked-worker-claim` | `after_tool`, `turn_end` | A reply that reports worker or Scout results in a turn with no `dispatch` call gets one warning that the claim is not backed by a receipt. A `[worker result]` note the operator shared is receipt-backed and exempt. No continuation: the operator decides. |
 | `observer.watchdog` | `after_tool`, `turn_end` | Opt-in through `watchdog.enabled` (default off). A turn that changed the tree is reviewed by one read-only `verifier` dispatch briefed with the turn's coalesced diff (per-path last-write-wins, bounded to 12 KiB) and the task board's current scope. Its failed checks become one transcript notice naming the count and the first three; a passing report emits nothing. `watchdog.cadenceToolCalls: N` also fires it every N tool calls inside the turn. One run in flight at a time; an overlapping trigger is dropped and counted. It emits no middleware effects, never continues a turn, and never mutates. Turns with no file mutations, headless runs, and ACP runs never fire it. |
-| `observer.memory-intervention` | `after_tool` | Every `memory.intervention.everyNTools` tool calls, asks a background model for a bounded reflection over the recent window and injects it as a reminder when it arrives. Governed by the `memory.intervention` settings block. |
+| `observer.memory-intervention` | `before_tool`, `after_tool`, `turn_start`, `turn_end`, `on_compaction` | Tracks bounded task memory throughout the turn. Repeated failures and post-compaction knowledge can inject rules-only reminders without a model. Interval, error-streak, and loop triggers queue a detached background reflection at `turn_end`; it uses the configured memory route and can deliver a bounded reminder with the next submitted turn. Governed by the `context.memory` settings block. |
 
 Two coded controls sit beside the registrations rather than among them. `tool-choice-control` turns `require_tool` and `lock_tools` effects into the provider's tool-choice field for the next round: a required tool clears when that tool starts, a lock lasts until the next submitted turn and outranks later requirements. `hook-receipts` is the durable ring (200 entries, throttled to one write per two seconds) of user-defined hook executions that `clio-coder config inspect` reads.
 
-User-defined hook declarations load from three places: `<extensionRoot>/hooks.yaml`, `.clio-coder/hooks.yaml`, and `.clio-coder/hooks.local.yaml`. A hook can be `prompt`, `effect`, or `command`. Command hooks run an argv array without a shell, under the workspace with a timeout and bounded output, and every hook execution emits a receipt.
+User-defined hook declarations load from three places: `<extensionRoot>/hooks.yaml`, `.clio-coder/hooks.yaml`, and `.clio-coder/hooks.local.yaml`. A hook can be `prompt`, `effect`, or `command`. Command hooks run an argv array without a shell, under the workspace with a timeout and bounded output, and every hook execution emits a receipt. Project files are read from disk; extension declarations come from the committed extension snapshot, which captured the `hooks.yaml` bytes during install-digest verification, so a file rewritten after verification is never reopened. A receipt for an extension hook carries the package provenance, the declarations digest, and the extension generation that admitted it.
+
+User hooks are one owned registration set. The extensions domain publishes nothing when it starts. After the guard registrations and before the turn-end assessors, the composition root prepares boot generation 1 and its user hooks, checks that both candidates are current, and publishes their references in adjacent assignment-only calls. `/resources extensions reload` uses the same paired path for later generations. A replacement for an older or equal generation is refused during preparation; after final validation neither publication primitive can refuse or call out. Conflict diagnostics and the reload event run only after both references are live. An owned registration that would take a builtin or host id is dropped with a `registration_conflict` diagnostic; a later host registration with the same id evicts the owned one. Evaluation captures the registration list once per hook occurrence, so an asynchronous phase that started before a reload finishes against the list it started with.
 
 ---
 

package/docs/{model-catalog.md → architecture/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.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Model Catalog, Runtime Refresh, and Field Notes visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/models_blueprint.html).
 
 Clio Coder treats a selectable model as the intersection of three sources:
 
@@ -11,7 +11,8 @@ Clio Coder treats a selectable model as the intersection of three sources:
 
 ## Runtime refresh controls
 
-- `/targets` (Settings → Targets): probes every target when it opens; a row's probe action re-probes that target.
+- `/settings targets`: probes every target when it opens; a row's probe action
+  re-probes that target.
 - `/model`: `r` refreshes the selected row's target; `R` refreshes all targets.
 - `clio-coder models`: probes live targets by default before printing the CLI model list. Use `--offline` to skip live probing. Former `--probe` and `--no-probe` flags are gone.
 
@@ -19,7 +20,11 @@ Configured `wireModels` and a target `defaultModel` remain selectable before a
 live catalog is known; Clio labels those rows as `configured` or `default`.
 Once a target returns a live catalog, that catalog is authoritative and models
 the runtime no longer reports stop resolving. Live probe discoveries are labeled
-`live` and carry load-state metadata when the runtime exposes it. This preserves
+`live` and carry load-state metadata when the runtime exposes it. Runtime model
+labels are separate metadata: the stable slug remains the wire identity while
+`clio-coder models` and target status may show the human label beside it. Slugs,
+labels, source, and freshness round-trip through the generic target model
+snapshot; a cached label never replaces a live slug. This preserves
 operator-curated defaults while still letting runtime discovery take over after
 newly installed local models or newly entitled cloud models appear. Catalog YAML
 entries are loaded when the provider domain is built, so bundled or overlay
@@ -31,20 +36,28 @@ Live provider probes are the preferred source for loaded context and per-model m
 `probeCapabilitiesForModel` is the one exact-id selector. When a router serves several models, capability resolution queries `probeCapabilitiesForModel` to ensure probe data is extracted only from the `/v1/models` row keyed to its own exact wire model ID.
 
 Transient probe failures preserve the last-good catalog, load states,
-capabilities, and notes for the same target identity, but the target health is
-reported as down or unavailable with the probe error as the reason. Worker
+labels, capabilities, and notes for the same target identity, but those model
+rows are marked cached/stale and target health is reported as down or unavailable
+with the probe error as the reason. Worker
 dispatch canonicalizes requested model ids against the live catalog when one is
 available, so a short alias can resolve to the canonical live id before the
 worker spec and receipt are written.
 
-## Benchmarking Models
+## Measuring models
 
-The public benchmark adapters under [benchmarks/community/](../benchmarks/community/)
-(SWE-bench Lite, Terminal-Bench, SciCode, HumanEval) drive Clio through
-`clio-coder run --json` or `clio-coder eval run`, each taking `--target` and
-`--model` from the configured targets. `benchmarks/README.md` has the
-commands. The run manifests record the target profile (runtime, model,
-thinking level) so sweeps can be compared consistently.
+Clio's evaluation engine records target, runtime, wire model, thinking level,
+serving facts, and evidence with each run. Reviewable reference suites live
+under [`evals/`](../../evals/); private prompts, external benchmark adapters, raw
+campaign artifacts, credentials, and non-reference private endpoint details
+belong outside this repository. Use `clio-coder eval run --suite <path> --target <id>` and retain
+the resulting execution envelope when comparing models or serving settings.
+
+The current reference deployment has two local targets. `mini` is a llama.cpp
+router at `http://192.168.86.141:8080` serving `ornith1.5-35b-moe` with four
+slots and 262144 tokens of context per slot. `dynamo` is LM Studio at
+`http://192.168.86.143:1234`, serving `qwen3.8-27b-dynamo` for chat. These are
+operator-managed deployment facts, not compiled defaults; use a live probe to
+confirm availability before a run.
 
 ## What "sanctioned" means
 
@@ -55,10 +68,10 @@ A model family is "sanctioned" only when we can say what was tested and under wh
 - hardware and serving configuration;
 - context window and max output actually exercised;
 - tool-use, reasoning, vision, embeddings/rerank/FIM behavior where relevant;
-- quirks needed by the engine (thinking mechanism, sampling, KV cache);
+- quirks needed by the engine (thinking mechanism and sampling), plus serving provenance such as KV cache;
 - failures and "do not use this route yet" notes.
 
-Engine-visible quirks belong in catalog YAML entries under `quirks.kvCache`, `quirks.sampling`, and `quirks.thinking`. Bundled entries under `src/domains/providers/models/**/*.yaml` are for curated Clio-supported families. User/lab/project experiments should start as overlays before they are promoted into source. Free-form notes can live alongside catalog entries and in this docs area for later cookbooks/blog posts. Catalog entries for LM Studio (`lmstudio`) no longer promise native SDK behavior or track SDK versions; all routing and capability reporting now reflects the strict HTTP adapter.
+Engine-visible quirks belong in catalog YAML entries under `quirks.sampling` and `quirks.thinking`. Serving calibration such as KV cache recommendations remains free-form provenance. Bundled entries under `src/domains/providers/models/**/*.yaml` are for curated Clio-supported families. User/lab/project experiments should start as overlays before they are promoted into source. Free-form notes can live alongside catalog entries and in this docs area for later cookbooks/blog posts. Catalog entries for LM Studio (`lmstudio`) no longer promise native SDK behavior or track SDK versions; all routing and capability reporting now reflects the strict HTTP adapter.
 
 ## Local catalog overlays
 
@@ -95,23 +108,33 @@ catalog:
     reasoning: true
     thinkingFormat: qwen-chat-template
     structuredOutputs: json-schema
-    vision: false
+    vision: true
     audio: false
     embeddings: false
     rerank: false
     fim: false
     contextWindow: 262144
-    maxTokens: 32768
+    maxTokens: 131072
   quirks:
     sampling:
       thinking:
-        temperature: 0.6
+        temperature: 1.0
         topP: 0.95
         topK: 20
+        minP: 0.0
+        presencePenalty: 0.0
+        repetitionPenalty: 1.0
     thinking:
-      mechanism: always-on
+      mechanism: effort-levels
+      effortByLevel:
+        low: low
+        medium: medium
+        high: xhigh
+        xhigh: xhigh
       guidance: |
-        Official Qwen3.8-27B chat template. llama.cpp's qwen3_coder parser converts XML tool calls to standard tool_calls JSON.
+        The official template accepts only low, medium, and xhigh reasoning
+        effort values. Clio maps its higher levels to xhigh. Use the runtime's
+        explicit off mechanism to disable thinking.
 ```
 
 Use `settings.yaml` `wireModels` for target inventory. Use overlays for
@@ -159,17 +182,27 @@ Use this shape when testing a subscription model, homelab GPU target, research-l
 
 The Context Engine evaluates thinking mechanisms per model target and manages live reasoning streams. Depending on the runtime capabilities, Clio Coder employs specific thinking replay semantics to ensure chain-of-thought data is preserved or replayed correctly in the conversation history:
 
+The shipped interactive default is `chat.thinkingLevel: low`. The independent
+fleet worker default remains `fleet.default.thinkingLevel: off`; an explicit
+target, profile, roster member, command option, or in-session selection can
+override the applicable setting.
+
 - **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
 - **LM Studio (`lmstudio`):** Chat uses the OpenAI-compatible `/v1/chat/completions` surface, including its `reasoning` stream field. Clio controls thinking only with `reasoning_effort` and never sends `chat_template_kwargs` to LM Studio. See <https://lmstudio.ai/docs/developer/openai-compat/chat-completions>.
 - **LiteLLM (`litellm`):** This is a gateway runtime, not an `openai-compat`
-  alias. Discovery checks `/health/liveliness`, reads aliases and capability
+  alias. Discovery checks `/health/liveliness`, reads routed names and capability
   metadata from `/v1/model/info`, and records the physical deployment reported
-  by `x-litellm-*` response headers. Defaults stay conservative when metadata is
-  absent: tools, vision, and reasoning are not inferred. The runtime advertises
-  standard `json_schema` structured output and treats schema-plus-tools as a
-  conflict because the gateway alias does not identify one stable upstream.
-  Residency is observe-only because LiteLLM owns loading and eviction behind the
-  alias.
+  by `x-litellm-*` response headers. Deterministic gateways should publish one
+  `node/model` name per deployment; genuine multi-deployment aliases expose only
+  the capabilities guaranteed by every route and use the smallest unanimously
+  published context/output limits. Defaults stay conservative when metadata is
+  absent: tools, vision, reasoning, and structured output are not inferred.
+  Explicitly advertised schema support uses standard `json_schema` on the wire.
+  Gateway requests use no hidden OpenAI SDK retries, and LiteLLM failures bypass
+  Clio's interactive transient retry ladder so the operator can select another
+  route. Stable session ids, request tags, optional request-level timeouts, and
+  observed server retry/fallback headers remain supported. Residency is
+  observe-only because LiteLLM owns loading and eviction behind the route.
 - **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
 - **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
 - **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.
@@ -183,6 +216,7 @@ Subscription models are registered and managed as standard HTTP/cloud targets:
 - **`openai-codex` (ChatGPT Plus/Pro OAuth):** Maps to catalog-backed Codex model ids surfaced by `clio-coder configure --list` and `clio-coder models` via a browser-minted subscription OAuth token, supporting complete chat, vision, and tool-use capabilities.
 - **`anthropic-max` (Claude Pro/Max OAuth):** Powers chat and workers using catalog-backed Claude model ids surfaced by `clio-coder configure --list` and `clio-coder models`. It relies on the engine's Anthropic OAuth provider. During auth initialization, it alerts the operator to usage-terms caveat via:
   `Connects with your Claude Pro/Max subscription via OAuth (the same path Claude Code uses). Using subscription credentials outside Anthropic's first-party apps may not align with their terms of service; enable at your own discretion.`
+- **`antigravity-code` (experimental local delegation):** Is not an HTTP model provider and is never orchestrator-eligible. It invokes the operator's own authenticated official `agy` executable only for dispatch work, consumes structured `stream-json` results and token accounting, and discovers model slugs and labels from the non-generating JSON `models` command. Descriptor models are cold-start hints only; a successful target probe is authoritative for that account, including the disappearance of a former model.
 
 ---
 

package/docs/{observability.md → architecture/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.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Observability Viewer visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/observability_blueprint.html).
 
 `/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.
 
@@ -135,7 +135,7 @@ A row has the following schema:
   "repoIdentity": "9f2c1b4ea77d0c31",
   "timestamp": "2026-06-25T14:30:00.000Z",
   "target": "dynamo",
-  "attributedModelId": "Nemo-3.5",
+  "attributedModelId": "qwen3.8-27b-dynamo",
   "usage": {
     "input": 120,
     "output": 8,
@@ -151,7 +151,18 @@ 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.
+`label` is one of `side-question`, `handoff`, `prewarm`, `background-memory`, or `failed-compaction`. Prompt pre-warm and proactive-memory calls are recorded here because neither appends an assistant call to the session JSONL; failed-compaction records preserve calls from an attempt that produced no checkpoint. 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.
+
+
+Failed compaction attempts record one `failed-compaction` row per invoked summary stream when no checkpoint is produced. `callOutcome` distinguishes a completed first stream (`success`) from an `error` or `aborted` stream; a completed call can belong to an unsuccessful split-compaction attempt. The rows capture the originating session/repository and selected target/model before asynchronous work can switch context. Successful compactions keep usage solely on their checkpoint, and their live accounting uses the same selected route. Unset model controls retain the active chat route.
+
+New failed-compaction rows preserve missing usage fields as `null`. Positive partial-response facts survive an error that resets missing fields to zero. Ambiguous failed zeros remain unknown, reasoning is separate from ordinary output/total tokens, and an absent total is not inferred. Positive adapter prices are labeled `estimated`; zero or missing pricing is `unknown`, not a free-call claim. Existing numeric rows and historical checkpoints remain readable without rewriting them.
+
+`clio-coder usage report` includes these calls in its known subtotals, labels the failed-attempt count, and exposes `failedCompaction.knownUsage`, `erroredKnownUsage`, and per-field `unobservedUsageCalls` in the token and model JSON facts. A field with missing coverage and no known positive amount is `null`, including cost-only or wholly unobserved failures. Text output identifies incomplete subtotals. The live `/cost` view records positive known contributions under a failed-compaction label; its numeric token counters remain known subtotals. These figures do not certify provider billing or complete spending. The existing session-cost ceiling checks the numeric known sum, so unreported cost does not become an enforced complete-cost bound.
+
+Eval tracked/stdout folds do not include the failed-compaction sidecar, and live `/cost` reseeding reads the session ledger rather than this store. A later usage report can therefore include retained failed-compaction amounts that those views omit. This consumer reconciliation is deferred to v0.4.5 or later; the retained known amounts must not be presented as complete cross-surface billing.
+
+A failed or empty summary produces no checkpoint. Required failed-compaction usage appends are flushed and a write failure remains an explicit operation error; no model call is repeated to repair accounting. If checkpoint append throws, Clio checks that checkpoint's exact identity in the original ledger before choosing the sidecar: an already written checkpoint is not counted again, and proven absence permits the sidecar. An unreadable or malformed ledger that leaves persistence ambiguous fails visibly without a speculative duplicate write. This is the existing bounded usage store, not a new recovery store; its 1000-row retention and unknown telemetry limits still apply.
 
 ---
 
@@ -207,17 +218,17 @@ Pressing `v` on a selected receipt or running `/view verify <runId>` performs cr
 
 1. **Read Receipt**: Reads the receipt JSON from `<stateDir>/receipts/<runId>.json`.
 2. **Resolve Ledger**: Looks up the run envelope inside `<stateDir>/runs.json`.
-3. **Verify Integrity**: Recomputes the SHA-256 digest over the strict v19 receipt and reconstructible ledger fields. The digest covers every current field, including steering, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance. Every version other than 19 fails verification; there is no historical receipt reader.
+3. **Verify Integrity**: Recomputes the SHA-256 digest over the strict v20 receipt and reconstructible ledger fields. The digest covers every current field, including dispatch intent path provenance, resolved path scope, steering, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance. Receipts below v20 are reported as retired and are never read as evidence or migrated. Malformed, tampered, unversioned, or future-version receipts fail verification; there is no historical receipt reader.
 4. **Report Result**: The viewer reports `ok` or the verification failure reason. It does not rename or delete the receipt. Startup orphan recovery may quarantine corrupt orphan receipt files as `<name>.json.corrupt`, but `/view verify` is read-only.
 
 ---
 
 ## Receipt Fields for Dispatch Provenance
 
-A receipt carries optional provenance and context blocks that answer "what happened" for a chained (pipeline), composed (persona override), escalated, briefed, steered, council, or external run. Those optional blocks remain absent when unused. Current receipts carry strict integrity v19 and an explicit `outcomeCode: null` when no classified deterministic failure occurred. Automation consumers must treat the optional blocks below as absent by default and `outcomeCode` as nullable; older receipt versions are invalid.
+A receipt carries optional provenance and context blocks that answer "what happened" for a chained (pipeline), composed (persona override), escalated, briefed, steered, council, or external run. Those optional blocks remain absent when unused. Current receipts carry strict integrity v20 and an explicit `outcomeCode: null` when no classified deterministic failure occurred. Automation consumers must treat the optional blocks below as absent by default and `outcomeCode` as nullable. Lower receipt versions are retired, while malformed, unversioned, and future versions are invalid.
 
 Receipt integrity verification and evidence verification are independent.
-`receipt_integrity=verified/v19/sha256` means Clio called the receipt verifier
+`receipt_integrity=verified/v20/sha256` means Clio called the receipt verifier
 against the ledger envelope; merely finding an embedded digest is not enough.
 `evidence_verification=<verified|unverified|not_applicable|unknown>/<basis>`
 describes validation evidence inside that verified receipt. Likewise,
@@ -228,7 +239,7 @@ separately and never substitute one hash for another.
 
 The evidence bundle renders these sets in `transcript.md` (human sentences) and `trace.cleaned.jsonl` (structured run rows), `clio-coder evidence inspect` prints them as a `provenance <runId>:` block, and the `dispatch` tool appends a compact suffix to each run line plus additive keys on `details.runs[]`, 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).
+The base provenance sets, steering, routing, quality, worker identity, result-conformance, council provenance, and fleet gate provenance use the strict v20 shape frozen for the release. Version 20 also seals provenance for each declared dispatch-intent path and the resolved `pathScope`, so evidence distinguishes operator-declared scope from legacy scope inferred from prose. These fields are labeled `experimental` until the schema is promoted post-1.0. For the operator-facing registry of receipt and related persistent compatibility contracts, see [artifact-versions.md](artifact-versions.md).
 
 | Field path | Type | When present | Meaning | Status |
 | --- | --- | --- | --- | --- |
@@ -247,7 +258,7 @@ The base provenance sets, steering, routing, quality, worker identity, result-co
 | `steering[].sentAt` | `string` | A steer was successfully written | Write timestamp | experimental |
 | `steering[].acknowledged` | `boolean` | A steer was successfully written | Whether a worker acknowledgement was actually observed | experimental |
 | `steering[].acknowledgedAt` | `string` | Acknowledgement was observed | Acknowledgement timestamp | experimental |
-| `outcomeCode` | six-value stable string union or `null` | Every v19 terminal receipt | Non-null for `vram_capacity_fit_failure`, `worker_tool_call_cap_exhausted`, `loop_guard_tools_disabled_exhausted`, `result_contract_exhausted`, `worker_final_output_missing`, or `host_verification_rejected`; otherwise `null`. Each non-null code denotes terminal deterministic failure and is incompatible with `outcome: "succeeded"`. Dispatch retry policy consumes this code only, never diagnostic prose. | experimental |
+| `outcomeCode` | six-value stable string union or `null` | Every v20 terminal receipt | Non-null for `vram_capacity_fit_failure`, `worker_tool_call_cap_exhausted`, `loop_guard_tools_disabled_exhausted`, `result_contract_exhausted`, `worker_final_output_missing`, or `host_verification_rejected`; otherwise `null`. Each non-null code denotes terminal deterministic failure and is incompatible with `outcome: "succeeded"`. Dispatch retry policy consumes this code only, never diagnostic prose. | experimental |
 | `personaOverride.promptHash` | `string` | Ad-hoc specialist whose persona replaced the recipe body | Hash of the composed static prompt; equals `staticCompositionHash` for the run | experimental |
 | `safety.decisions.escalationRequested` | `number` | Run saw at least one permission escalation | Parked permission asks handed to the operator | experimental |
 | `safety.decisions.escalationApproved` | `number` | Run saw at least one permission escalation | Escalations the operator approved | experimental |
@@ -257,8 +268,8 @@ The base provenance sets, steering, routing, quality, worker identity, result-co
 | `safety.toolTelemetry.ingestionErrors` | `number` | Current dispatch receipts | Malformed or lost frames, event-fold/source errors, and drain timeouts that make otherwise mediated telemetry incomplete | experimental |
 | `safety.toolTelemetry.unfinished` | `{ tool, count }[]` | Current dispatch receipts | Tool starts that had no matching finish when the receipt sealed | experimental |
 | `safety.toolTelemetry.workspaceMutationPossible` | `boolean` | Current dispatch receipts | Whether incomplete or unavailable telemetry could conceal a shared-workspace mutation; retry admission fails closed when true | experimental |
-| `autonomyEnforcement.grade` | `string` | Always in v0.4.0 | The autonomy grade level enforced for the run | experimental |
-| `autonomyEnforcement.autonomy` | `string` | Always in v0.4.0 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
+| `autonomyEnforcement.grade` | `string` | Always | The autonomy grade level enforced for the run | experimental |
+| `autonomyEnforcement.autonomy` | `string` | Always | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
 | `autonomyEnforcement.externalMode` | `string` | When running external worker | The execution mode of the external worker runtime | experimental |
 | `autonomyEnforcement.dangerousBypass` | `boolean` | When running external worker | Whether a safety bypass was explicitly activated | experimental |
 | `validationGrounding.claimed` | `number` | Validation grounding evaluated | Count of validations claimed by worker | experimental |
@@ -283,13 +294,26 @@ The escalation counters appear together and only when `escalationRequested` is p
 Here is a step-by-step trace of how a run passes through the spine.
 
 ### 1. Dispatch Completion
-A dispatched task to execute tests finishes. The dispatch domain persists the run envelope and the receipt, then emits the completion event:
+A dispatched task to execute tests finishes. The dispatch domain persists the run envelope and receipt, then emits `dispatch.completed`. The relevant event fields include:
 ```json
 {
   "runId": "abc1234",
-  "status": "completed",
+  "agentId": "tester",
+  "targetId": "mini",
+  "wireModelId": "ornith1.5-35b-moe",
+  "runtimeId": "llamacpp",
+  "runtimeKind": "http",
+  "requestOrigin": "user",
+  "outcome": "succeeded",
+  "outcomeCode": null,
+  "outcomeDetail": null,
   "exitCode": 0,
-  "lineage": { "attempt": 0 }
+  "lineage": {
+    "parentRunId": null,
+    "rootRunId": "abc1234",
+    "attempt": 0,
+    "depth": 0
+  }
 }
 ```
 

package/docs/{pi-boundary.md → architecture/pi-boundary.md}

@@ -1,6 +1,9 @@
 # Pi SDK Boundary
 
-Clio Coder uses Pi 0.84.0 as its provider, agent-loop, and terminal SDK. This
+> **Visual blueprint:** The source checkout includes the complete
+> [Pi SDK Boundary visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/pi_boundary_blueprint.html).
+
+Clio Coder uses Pi 0.84.4 as its provider, agent-loop, and terminal SDK. This
 page records where Pi owns a reusable primitive and where Clio deliberately
 keeps product behavior. Review this table on every Pi upgrade. An action marked
 `Keep` is an explicit boundary decision, not an invitation to replace the
@@ -11,7 +14,7 @@ Clio-owned surface during a dependency bump.
 | Pi export or surface | Clio file or function | Action | Reason |
 | --- | --- | --- | --- |
 | pi-agent-core `truncateHead`, `truncateTail`, `truncateLine`, and `formatSize` | `src/tools/truncate.ts` | Route through Pi. | Pi owns UTF-8-safe truncation. Clio retains its 16 KiB default and `splitLinesForCounting`, which Pi does not export. |
-| pi-ai `StringEnum` | `src/engine/ai.ts` and the `src/tools/string-enum.ts` adapter | Route through Pi. | The former TypeBox implementation duplicated Pi's compact provider-safe schema. |
+| pi-ai `StringEnum` | `src/engine/ai.ts` | Route through Pi. | The deleted `src/tools/string-enum.ts` TypeBox adapter duplicated Pi's compact provider-safe schema. Tools now import the re-export from the engine boundary. |
 | pi-agent-core `COMPACTION_SUMMARY_PREFIX`, `COMPACTION_SUMMARY_SUFFIX`, `BRANCH_SUMMARY_PREFIX`, `BRANCH_SUMMARY_SUFFIX`, and `bashExecutionToText` | `src/interactive/chat-renderer.ts` through `src/engine/messages.ts` | Route through Pi. | Replay text must match Pi's `convertToLlm` wording while Clio keeps its `SessionEntry` mapping and replay bounds. |
 | pi-tui `stripTerminalSequences` | `src/domains/session/tree/preview.ts` | Keep the Clio sanitizer. | Pi removes SGR and OSC sequences but intentionally leaves private-mode CSI and character-set escapes that may occur in captured tool output. |
 | pi-ai `isRetryableAssistantError` | `src/domains/session/retry.ts` | Route generic classification through Pi and keep the Clio delta. | Clio additionally recognizes self-hosted model loading and enforces its separate 15-second floor. |
@@ -40,6 +43,17 @@ Clio-owned surface during a dependency bump.
 | pi-tui `CombinedAutocompleteProvider` | `src/interactive/slash-autocomplete.ts` | Keep Clio command composition. | Clio's declarative slash specification owns parsing, help, and completion consistency. |
 | pi-tui `KeybindingsManager`, `TUI_KEYBINDINGS`, and `Editor.addToHistory` | `src/domains/config/keybindings.ts` and interactive editor wiring | Route terminal actions through Pi. | Pi owns editor behavior while Clio owns the configured bindings and accepted-input policy. |
 | pi-tui `Markdown`, `renderLatex`, `visibleWidth`, `truncateToWidth`, `wrapTextWithAnsi`, and `stripTerminalSequences` | Interactive Markdown, Mermaid, layout, and width wiring | Route terminal primitives through Pi. | Clio retains theme tokens, Mermaid span styling, and application layout only. |
+| pi-agent-core `prepareNextTurn` / `prepareNextTurnWithContext` (0.84.4 ordering: runs only when the loop will start another assistant turn) | `src/interactive/turn-runtime.ts` continuation guard and `src/interactive/turn-context.ts` `postToolContinuationGuard` | Keep `prepareNextTurn`; no adaptation. | The guard already returned early unless the transcript tail was a tool result, so it was continuation-only on 0.84.0. Under 0.84.4 it also stops running after terminating batches and before `agent_end`, which removes a spurious guard failure after `artifact`-style terminal tool results. End-of-run work stays on `agent_end`. Locked by `tests/contracts/engine-lifecycle.test.ts`. |
+| pi-agent-core `Agent.reset()` (0.84.1 rejects during an active run) | `src/interactive/chat-loop.ts` `resetForSession` and `src/interactive/session-switch-settlement.ts` | Keep Clio's settle-then-replace reset. | Clio never calls `Agent.reset()`. Every session reset caller cancels and awaits `whenSettled()` first, then replaces `agent.state.messages`; the bang-command path waits on `isStreaming()` before refreshing. The contract test records that a mid-run reset is refused upstream. |
+| pi-agent-core `BeforeToolCallResult.terminate` (0.84.1) | `src/tools/agent-tools.ts` blocked-call path | Decline. | Clio blocks tools inside `execute` by throwing the model-facing rejection; a blocked call must not end the batch. Batch termination stays on `AgentToolResult.terminate` from successful terminal tools. |
+| pi-agent-core `streamProxy()` namespace metadata (0.84.2) and `ToolCall.namespace` | None | Decline. | Clio does not proxy assistant streams and does not use OpenAI Responses namespaced or deferred tools. |
+| pi-ai `SimpleStreamOptions.toolChoice` (0.84.3, `auto` / `none`) | `src/engine/provider-payload.ts` and the `onPayload` hook in `src/interactive/turn-runtime.ts` and `src/engine/worker-runtime.ts` | Keep the Clio payload patch. | Clio needs both `none` and a named required tool across every dialect it serves, including generic OpenAI-compatible servers that reject object `tool_choice`. Splitting `none` onto the neutral option would leave two mechanisms for one concern. |
+| pi-ai strict tool-schema conversion and null normalization (0.84.2) | `src/engine/ai.ts` `validateEngineToolArguments` | Inherit. | No Clio tool sets `constrainedSampling`, so strict conversion is inert. `null` for an optional non-nullable argument is now dropped instead of rejected; locked by the engine lifecycle contract. |
+| pi-ai OpenAI-compatible reasoning replay and signature serialization fixes (0.84.3, 0.84.4) | `src/engine/apis/openai-completions.ts` | Inherit. | The wrapper delegates `stream` and `streamSimple` to Pi's adapter, so replay fixes apply to in-run turns. Clio's ledger does not persist `thinkingSignature`, so resumed sessions still replay without signatures (pre-existing). |
+| pi-ai Anthropic server-side refusal fallback with returned-model pricing (0.84.3) | `src/interactive/turn-context.ts` `reconcileUsage` and `src/domains/observability/trace-store.ts` | Inherit. | Usage and cost arrive already priced for the returned model; Clio records `message.model` as reported. `fallbacks` is only sent for catalog models that declare `allowedFallbackModels`. |
+| pi-tui capability overrides (`PI_HYPERLINKS`, `PI_IMAGE_PROTOCOL`, `PI_TRUE_COLOR`, `setCapabilityOverrides`) and `PI_TUI_ESC_TIMEOUT` (0.84.2, 0.84.4) | `src/interactive/theme/tokens.ts` truecolor detection | Decline. | These govern pi-tui's own image, hyperlink, and escape-sequence handling. Clio's theme detects truecolor from `COLORTERM` and `TERM` independently and does not consume pi-tui capability detection. |
+| pi-tui `TuiAltScreenOptions.copyOnSelect` / `copySelection` and transcript search (`tui.altScreen.search*`, 0.84.2, 0.84.4) | `src/interactive/interactive-shell.ts` alt-screen construction and `src/domains/config/keybindings.ts` | Inherit defaults. | Selection copy stays on by default. Search is pi-tui's viewport listener and runs before Clio's router; `ctrl+g` advances a match only while the search overlay is focused, so the Clio leader chord is unavailable during a search and nowhere else. Locked by the engine lifecycle contract. |
+| pi-tui alternate-screen direct-row painting (0.84.2) | `src/engine/instrumented-tui.ts` | Inherit. | `compositeOverlays`, `extractCursorPosition`, and `applyLineResets` still run inside one `doRender`, so Clio's frame and phase measurements are unchanged. Locked by the engine lifecycle contract. |
 
 ## Thin-wrapper watch list
 
@@ -59,14 +73,13 @@ behavior and should not grow another implementation of an SDK primitive.
 
 Run these contracts first on a Pi bump, before the full gate:
 
-- `tests/contracts/thinking-runtime.test.ts`
-- `tests/contracts/openai-completions.test.ts`
-- `tests/contracts/lmstudio.test.ts`
-- `tests/contracts/lmstudio-instance-resolution.test.ts`
-- `tests/contracts/replay-pi-message-text.test.ts`
-- `tests/contracts/tool-string-enum.test.ts`
-- `tests/smoke/tui-width-matrix.test.ts`
-- The headless JSON stream contracts under `tests/contracts/`.
+- `tests/contracts/engine-lifecycle.test.ts` (agent-loop ordering, reset, tool-argument normalization, keybinding table, alt-screen render seams)
+- `tests/contracts/provider-transport.test.ts`
+- `tests/contracts/provider-context-boundary.test.ts`
+- `tests/contracts/gemma-channel-filter.test.ts`
+- `tests/contracts/tool-boundaries.test.ts`
+- `tests/contracts/session-durability.test.ts`
+- `tests/smoke/process-lifecycle.test.ts`
 
 The complete upgrade procedure lives in
-[Development Pipeline](development-pipeline.md#inheriting-a-pi-release).
+[Development Pipeline](../process/development-pipeline.md#inheriting-a-pi-release).