@iowarp/clio-coder 0.4.4 → 0.4.6

package/docs/architecture/context-engine.md

@@ -31,7 +31,7 @@ At submit time, Clio captures a context snapshot and persists a slim JSONL recor
 
 Every snapshot records the divergence between the two accountings. `estimatedTokens` is the chars/4 prompt-side total the snapshot was captured with and is never rewritten by a reconcile; `reconciledTokens` is the provider's own prompt count for the call, with cached prompt tokens folded back in; `divergenceRatio` is the second over the first. A ratio above 1 means the estimator is under-counting what the backend charges for the same messages.
 
-The reconciled figure is not only a display value. Once a provider has answered, the compaction verdict budgets against `max(estimate, reconciled + estimate of everything appended since)`, at all three evaluation points: the pre-submit trigger, the post-tool continuation guard, and the preflight overflow check. The estimate stays a floor because it prices material the attested call never saw; the provider count can only raise the figure, never lower it. A working-set projection subtracts the tokens the eviction planner priced out and re-anchors on the projected message list rather than discarding the attestation, so post-eviction accounting is still provider-anchored. A summary compaction rewrites the conversation the attestation described, so it drops the anchor and the next call re-establishes it.
+The reconciled figure is not only a display value; it governs compaction verdicts at the pre-submit trigger, the post-tool continuation guard, and the preflight overflow check. When no live anchor is trusted—such as before the first provider response, after a session reset, or when target, runtime, model, endpoint, or message history diverges—accounting falls back to the conservative legacy estimator. While a live anchor is trusted, the floor is structural (the breakdown sum of prompt, messages, pending input, and tool schemas), pricing material the attested call never saw without letting provider counts fall below structural reality. Live provider accounting counts measured prompt schemas once within the anchored history, avoiding false pressure from duplicate schema charges. It prices independent positive prompt and tool growth without netting shrinkage against growth, and preserves the post-reconcile message tail through working-set eviction replay. A working-set projection subtracts the tokens the eviction planner priced out and re-anchors on the projected message list rather than discarding the attestation, so post-eviction accounting remains provider-anchored. A summary compaction rewrites the conversation the attestation described, so it drops the anchor and the next provider call re-establishes it.
 
 Session metadata enforces session format version 4 (`CURRENT_SESSION_FORMAT_VERSION = 4`). Version 4 is additive: it adds the `contextEviction` and `contextRecall` records and changes no existing entry. A version 3 session therefore migrates to 4 in place when Clio opens it, and no entry is rewritten. Only a session written by a newer build is refused, with an error naming the version it read and pointing at upgrading. The bump is one-way for the operator: a 0.3.3 binary cannot open a session this release wrote.
 
@@ -41,7 +41,7 @@ The `/context` overlay and footer meter read the same ledger categories in displ
 
 Auto-compaction is controlled by `context.compaction.threshold`. Pressure is `budgeted_tokens / context_window`, where the budgeted figure is the reconciled total when the provider has attested one and the chars/4 estimate otherwise. The default threshold is `0.8`.
 
-Crossing that threshold engages three mechanisms in a fixed order. The first two are cheap, reversible, and call no model. Only the third rewrites what the session says about itself.
+Crossing that threshold first applies reversible working-set eviction without a model call. If pressure remains high, an LLM summary replaces older material in model replay. Recall remains available on demand; it is not an automatic compaction stage. Both mechanisms preserve the raw ledger by default.
 
 ### 1. Working-set eviction
 
@@ -53,7 +53,7 @@ If the projection drops pressure below the threshold, Clio sends the request and
 
 ### 2. Recall
 
-An evicted body comes back on demand and only on demand. The marker names the exact call: `context(scope="recall", ref="<turnId>")` returns the original body byte-exact through the observation envelope and appends a `contextRecall` entry. Operators use `/context recall <ref>`, which prints the body to the transcript without putting it into model context.
+An evicted or summarized tool-result body comes back on demand. `context(scope="recall", ref="<turnId>")` returns its persisted body through the observation envelope and appends a `contextRecall` entry. Omit `ref` to discover historical results with `query`, `limit`, and `offset`; discovery does not append a recall record. Operators use `/context recall <ref>`, which prints the body to the transcript without putting it into model context. Content removed by older destructive compaction or masking cannot be recovered.
 
 A recall does not un-evict. The marker stays byte-identical where it was, so the provider prefix cache is untouched, and repeated recalls of the same ref are the churn signal the `/context` overlay reports.
 
@@ -63,7 +63,9 @@ Offline replay does not infer those explicit decisions from a later read of the
 
 If pressure remains above the threshold after eviction, Clio runs the summary compaction path: it calls the summarization model, appends a `compactionSummary` entry, refreshes projected replay messages from the session, and continues. This is the only mechanism that spends tokens and the only one whose output is a lossy paraphrase, which is why it runs last.
 
-Iterative compaction has one raw-history boundary. The first pass searches from the start of the active path. A later pass searches strictly after the previous `compactionSummary`, while the prior checkpoint and its retained suffix are fed to the summarizer as canonical context for one cumulative replacement. The replay benchmark uses that same boundary. It must not run `findCutPoint` over the visible retained suffix again: doing so re-prices history already captured by the previous checkpoint and overstates repeated summary churn.
+Compaction projects the active-path working set before counting tokens, choosing a cut, or serializing the summary request. Evicted bodies and thinking therefore stay excluded from the summarizer as well as ordinary replay; the raw ledger remains available for exact recall. The first pass searches from the start of the active path. Later passes search strictly after the previous `compactionSummary`, using the prior checkpoint and retained suffix as canonical context for one cumulative replacement. Compaction retains selected verified skill text, exact operator instructions verbatim, canonical active replay, complete tool batches (keeping the full tool call and result batch intact rather than cutting mid-batch), and prior retained suffixes across iterative checkpoint boundaries. This ensures essential task constraints and verified context persist across repeated checkpoints without over-promising that every oversized model task will fit. Each summary request budgets the complete prompt and its bounded output against the resolved model window.
+
+A summary that reaches its model output limit is incomplete and cannot replace the current checkpoint. Its reported usage remains recorded as a failed compaction call. Manual compaction preserves the latest operator request verbatim when a split removes it, even after the active turn has settled. Esc and Ctrl+C cancel manual and pre-submit compaction through the same signal as the production summary call; canceling pre-submit compaction also stops the pending chat submission. Post-tool continuation forwards the engine abort signal, and ACP session cancellation reaches compaction before the chat stream starts. Session reset and disposal abort outstanding summaries. Compaction checks cancellation before invocation, before accepting a response, and before publication, so a late response cannot become a checkpoint. These checks do not establish semantic summary quality, which requires separate model evidence.
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the summary path directly and skip every pre-stage. The overflow guard runs before the user turn is committed, so a blocked oversized request does not leave an unanswered user entry in the ledger.
 
@@ -151,7 +153,7 @@ The public settings use one compaction threshold plus a non-destructive working-
 
 ```yaml
 chat:
-  prewarm: true
+  prewarm: false
 
 context:
   workingSet:
@@ -187,17 +189,17 @@ Settings validation is strict: an older file still carrying the removed `compact
 
 Project guidance is resolved from the filesystem root to the working directory. An ordinary `CLIO-CODER.md` adds a layer for its directory and descendants. `CLIO-CODER.override.md` starts a replacement boundary: it wins over `CLIO-CODER.md` in the same directory, discards all handbook layers inherited from ancestors, and remains effective below that directory. Ordinary handbooks in deeper directories may add new layers after the override. A sibling outside the override's subtree keeps its own inherited chain.
 
-For example, a session in `repo/src/parser/` loads `repo/src/CLIO-CODER.override.md` followed by `repo/src/parser/CLIO-CODER.md`; it does not load `repo/CLIO-CODER.md`. A session in `repo/docs/` still loads `repo/CLIO-CODER.md`. Surviving files are rendered in ancestor-to-descendant order as separate `<project-context path="...">` blocks, preserving the source of every instruction. The nearest surviving handbook supplies the project name used by compact reporting, while conventions, hard invariants, imported context, and custom sections layer in order.
+For example, a session in `repo/src/parser/` loads `repo/src/CLIO-CODER.override.md` followed by `repo/src/parser/CLIO-CODER.md`; it does not load `repo/CLIO-CODER.md`. A session in `repo/docs/` still loads `repo/CLIO-CODER.md`. Selected readable, non-whitespace-only handbooks are ordinary authored Markdown: arbitrary headings and a missing project identity are accepted, and source bytes are preserved. A strict structured projection is optional and may be absent; it never fabricates a project name or rules. Surviving source layers render ancestor-to-descendant with explicit paths, subject to the preload budget below.
 
-An unreadable or malformed override fails closed. Clio warns about that file but does not reactivate the inherited or same-directory handbook it replaced. `clio-coder config inspect` lists every effective handbook and its layer number.
+An empty or unreadable override fails closed. Clio reports that file but does not reactivate the inherited or same-directory handbook it replaced. Ordinary Markdown does not have to satisfy the generated-handbook schema. `clio-coder config inspect` lists every effective handbook and its layer number.
 
 Handbook resolution is read-only. `/context init` and its CLI form are the only commands that author or update the exact `CLIO-CODER.md` in the current directory; `/context refresh` touches neither standard nor override handbooks. Neither command rewrites an inherited file or an override. A same-directory override therefore continues to shadow a standard handbook created or updated by init until the operator removes the override. Normal reset preserves both handbook names; `context reset --all` may remove the local standard `CLIO-CODER.md` after its second confirmation but always preserves `CLIO-CODER.override.md` as operator-authored context.
 
 ## Project-context preload class
 
-The compiled session prompt preloads the full rendered project context (the effective handbook fragments plus project-type and codewiki markers) only when at least one selected handbook parses and the rendered text stays within 8000 characters and 220 lines; otherwise it preloads a compact synopsis. The rule lives in `src/domains/prompts/preload.ts` and every reporting surface classifies with it:
+The compiled session prompt uses one bounded selector in `src/domains/prompts/preload.ts`. Small rendered inputs remain exact; oversized authored handbooks retain safe exact prefixes within 8,000 UTF-16 units and 220 rendered lines, including metadata. Allocation favors nearest layers and renders included layers ancestor-first. It no longer replaces oversized guidance with a lossy synopsis. Model-facing omission notices identify source paths and included/omitted physical line ranges with retrieval instructions. Captured-source hashes are retained separately in preload classification and accounting/manifest metadata; they are not printed as per-source hashes in those notices. The conservative prefix scanner preserves line endings, whitespace, Unicode, and complete command lines; an oversized first block may leave no authored excerpt. This is incomplete guidance, not a complete policy. Reporting surfaces share the selection:
 
-- `/context init` and `clio-coder context init` print `preload: full (N.NkB, N lines)` or `preload: synopsis (reason: size|lines)` after the summary, and warn when a full preload is within 10% of either limit.
+- `/context init` and `clio-coder context init` report full or partial preload, included UTF-16 units and rendered lines, and source omission accounting; they warn when a full preload is within 10% of either limit.
 - `clio-coder config inspect` shows the shared preload class and layer position on every effective handbook entry.
 - The `/context` overlay shows a `project preload:` line under the category legend once a session prompt has compiled, followed by the effective handbook path(s): one `handbook:` line for a single file, or a `handbooks (ancestor → nearest):` list when layered handbooks apply. Paths render workspace-relative; a handbook above the workspace keeps a `~`-shortened or absolute path.
 
@@ -209,13 +211,13 @@ flag `--wiki` is the only refresh path that may update the Markdown wiki, and
 it only runs when an existing wiki metadata file is present. Regenerating or
 updating the exact local standard handbook stays with `/context init`.
 
-`clio-coder context init` is model-driven by default. The `--heuristic` flag is the sole deterministic flag for offline handbook generation. The `--propose` flag writes ignored drafts to `.clio-coder/proposals/`, `--apply` updates from the existing handbook, and `--rewrite` generates a fresh handbook.
+`clio-coder context init` is model-driven by default; `--heuristic` selects deterministic offline generation. Plain init preserves an existing authored handbook. When a generator produces a candidate, it writes a review proposal under `.clio-coder/proposals/` with adjacent JSON recording generation telemetry, source hash, and proposal hash. `--propose` never publishes, even when no handbook exists. `--apply` and `--rewrite` explicitly publish generated updates or replacements. Publication provenance changes only when the handbook is published. Generated drafts still pass strict proposal and serialization validation; accepting ordinary authored Markdown does not relax those checks.
 
 When bootstrapping across local runtimes such as `llamacpp` where strict grammar/schema enforcement might be rejected by the endpoint, generator logic retries automatically using a bounded prompt-parser fallback. If `--rewrite` was requested but the model generation fails to produce a valid handbook rewrite, `clio-coder context init` prints a notice and exits with code 1 rather than leaving an inconsistent state.
 
 ## Generated handbook structure and verification expectations
 
-During handbook generation (`context init` and `clio-coder context init`), Clio derives structural sections directly from workspace manifests and toolchains:
+During handbook generation (`context init` and `clio-coder context init`), Clio derives structural sections from workspace manifests and toolchains. Starter project-wide rules come only from scanned project-wide instruction locations and explicitly opted-in global Codex guidance; directory-scoped skills, examples, and nested instructions remain evidence with their original scope. Declared verification commands are suggestions, not evidence that they were executed:
 
 - **Context retrieval**: Derived from the codewiki index, naming primary entry points and directing agents to use `code_nav` for navigation. To prevent staleness across repository mutations, exact volatile file counts are omitted.
 - **Verification expectations**: Synthesized from declared toolchain configuration and manifest files:
@@ -257,26 +259,19 @@ Source coverage spans TypeScript, JavaScript, Python, Rust, Go, C, C++, CUDA
 as `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`,
 `CMakeLists.txt`, `Gemfile`, and `*.csproj`.
 
-Extraction is async and tree-sitter-first. Clio loads WASM grammars for the ten
-source language grammars above, extracts symbols/imports/exports from the parsed tree,
-and merges regex import extraction for languages with regex extractors. If a
-tree-sitter parse fails for one file, that file falls back to the available
-regex extractor instead of aborting the whole build. C# is covered by the
-tree-sitter C# grammar.
+Codewiki reconciliation runs in a worker under the coordinator’s artifact lease. When the selected input is the exact committed index read under that lease, the coordinator sends an artifact reference and recorded line total instead of cloning the parsed index between threads. An unchanged reconciliation returns only its fingerprint; stale and incremental paths load the artifact in the worker. Reset shares the writer queue and lease, so admitted writes finish before reset removes their output and later incremental notifications cannot recreate an absent index.
+
+Extraction is async and tree-sitter-first. Clio loads WASM grammars for the ten source languages above, extracts symbols/imports/exports, and merges available regex import extraction. A failed parse falls back to the available regex extractor for that file. Python edges distinguish relative import levels and absolute package imports, using package initializer evidence; they describe a static source graph and do not execute import hooks or infer arbitrary PYTHONPATH settings. Fingerprint migration also reconciles old edges when source bytes are unchanged.
 
 Ambiguous `.h` files are classified deterministically by `classifyCHeaderLanguage` (`src/core/c-header-language.ts`). The scanner removes comments before checking C++-only standard-library includes, and removes comments and literals before checking C++ syntax markers such as templates, namespaces, class/member declarations, scope resolution, C++ casts, and C++ qualifiers. If any C++ marker is present, the header is indexed as `c++`; otherwise, it defaults to `c`. This guarantees that both full indexing and incremental file syncs assign identical language tags to `.h` files. Declaration-only C/C++ APIs are indexed so header-heavy MPI, CUDA, and scientific libraries remain navigable even when implementations live elsewhere.
 
-Incremental updates are real updates, not a full rebuild hidden behind the
-name. Successful file-mutating tools report changed paths through the
-middleware observer. The context domain coalesces those paths, checks per-file
-content hashes and reparses only changed files (`perf(context)` optimization),
-reads only the changed indexable files for path-based updates, replaces their file and symbol records, removes
-deleted records, and rebuilds edges from the merged import set. Non-indexable
-paths are no-ops.
+Successful file-mutating tools report changed paths through a coalesced, serialized observer queue. Path updates can reuse unchanged parse records and reparse changed files, but publishing a new global fingerprint requires full source-content reconciliation so an unnotified edit cannot be certified as current. The coordinator brackets reconciliation with source-byte fingerprints and retries an unstable scan up to three times; unreadable or persistently changing inputs prevent certification. An unchanged notification retains the previous global baseline instead of certifying unrelated files. Deleted records are removed and import edges are rebuilt from the reconciled records. This reduces reparsing work, not the source reads needed to establish global freshness.
 
 ### Architecture seed
 
-`clio-coder context map` derives an archify architecture specification from the structural index with no model call and writes it to `.clio-coder/artifacts/maps/<repo>.architecture.json` (or `--out <path>`). The seed guarantees that every component is a real directory area of the index under the wiki plan's area-depth rule, capped at twelve by file count plus at most three external packages; that every connection is an import edge the index recorded, collapsed area to area and labeled with its count; and that `meta.repository` appears only when the origin remote is a GitHub URL and `HEAD` is a full revision. Only in that case do components carry `sources`, each naming an indexed file and its first declared symbol's line, because archify accepts source citations only against a pinned revision. Component IDs remain unique across internal and external names, connection IDs are unique, and matching directory/package names retain separate import destinations and counts. Placement is layered by import direction with explicit routes for archify's standard profile; composition warnings may still require operator edits. It refuses, naming `clio-coder context index`, when no index exists. Clio never renders the seed: the archify skill validates and delivers it. When the seed carries pinned repository evidence, pass `--repo-root .` to re-verify every cited path against the working tree; omit that option for an unpinned seed.
+`clio-coder context map` derives an archify architecture specification from the structural index with no model call and writes it to `.clio-coder/artifacts/maps/<repo>.architecture.json` (or `--out <path>`). Map generation reconciles the existing structural index before mapping; missing index refuses, naming `clio-coder context index`. Pinned source citations require that the workspace is clean at repository root, indexed file bytes match current files and Git blobs, the origin remote is a GitHub URL, and `HEAD` is a full revision. When those conditions hold, components carry `sources` naming indexed files and declared symbol lines. Unknown or dirty source states cleanly produce usable uncited architecture seeds; `--json` reports the path, component and connection counts, repository metadata, reconciled index status, and source state (`clean`, `dirty`, or `unknown`). Component IDs remain unique across internal and external names, connection IDs are unique, and matching directory/package names retain separate import destinations and counts. Placement is layered by import direction with explicit routes for archify's standard profile; composition warnings may still require operator edits.
+
+Clio never renders the seed directly: the architecture mapping pipeline separates deterministic seed generation (`context map`), model-authored refinement (`archify` skill), validation and delivery (`archify validate` / `deliver`), and review. Standard validation checks schema conformance and layout composition, while verification commands check path and symbol citations against the workspace. Mechanical validation passes do not establish semantic claims or visual layout quality: source review assesses semantic claims, while visual review in a browser assesses layout presentation. Custom model-authored maps can remain layout-invalid until refined. When the seed carries pinned repository evidence, pass `--repo-root .` to re-verify every cited path against the working tree; omit that option for an unpinned seed.
 
 ### Markdown Wiki & `code_nav` Resolution
 
@@ -293,14 +288,12 @@ page's plan entry, its anchor sources, and the sibling paths it may link to. The
 repository-wide payload, including the codewiki digest, appears only in the
 planning prompt. Because a static prompt is re-sent on every round of a run, this
 is what keeps prefill cost from growing quadratically with the size of the wiki.
+Ordinary planner, page, and whole-run time and tool estimates are advisory across
+generation, not automatic aborts. An explicit caller deadline (`timeout_ms`) or
+operator cancellation remains authoritative. Failed writers remain pending; admission
+rejection does not consume a writer attempt.
 
-`_plan.json` is the skeleton and the checkpoint. It is derived deterministically
-from the codewiki index, so a usable plan exists before any model runs; the
-planning dispatch may merge, split, rename, drop, or re-anchor entries by
-rewriting it, and a malformed rewrite falls back to the candidate. The harness
-owns each entry's status and rewrites the file after every page, so a run that
-ends early records exactly which pages are still owed. Staging survives such a
-run and the next one resumes from it.
+`_plan.json` is the skeleton and checkpoint. A deterministic codewiki plan exists before model dispatch; the planner may merge, split, rename, drop, or re-anchor entries, with malformed rewrites falling back to the candidate. The harness owns completion and attempts. Changes to authored title, intent, or source set reset progress; dropped planned pages are checkpointed as retirements and removed during assembly. A resumed checkpoint checks source evidence and conservatively requeues pages when it is missing or changed. Resolved and requested coverage depth (`auto`, `simple`, `medium`, `detailed`) are harness-owned. Explicit upgrades and downgrades requeue coverage with existing prose retained, while dispatch receipts remain untouched. Default interrupted and partial retries retain saved depth; completed auto updates may increase coverage as the codebase grows. Every depth requires the same evidence accuracy.
 
 Every page opens with repaired front matter. Its metadata model has `title`,
 `summary`, `sources`, `symbols`, `tests`, `invariants`, and `validate`, but the
@@ -310,20 +303,23 @@ directory `index.md`, and the task-routing table are generated from the repaired
 values after each run, so navigation cannot drift or miss a page and no writer
 has to remember to update it.
 
-Assembly repairs rather than rejects. A missing H1, absent or malformed front
-matter, a dangling `sources` entry, a link to a page that was never written, and
-a citation to a path that does not exist are all mechanically fixable, so each is
-fixed or recorded in a `<!-- clio:wiki ... -->` marker and reported; none fails a
-run. An empty page is dropped and its plan entry stays owed. An update run's
-scope is computed, not guessed: a page is rewritten when git reports a change to
-one of the sources its own front matter claims.
+Both original writer output and completed saved pages pass nonmutating mechanical
+validation before completion or reuse. Supported missing or escaping paths, invalid
+line ranges, malformed source/test metadata, and empty bodies keep pages pending.
+Canonical metadata and body citations participate in source-byte dependencies,
+including JS source aliases. Failed refreshes retain dependencies; successful repairs
+replace them so obsolete references can retire. Assembly mechanically repairs missing
+headings, malformed front matter, dangling citations, and links, reporting repairs or
+omission markers. Assembly repair alone does not establish completion: a page is complete
+only after a successful writer dispatch and retention by assembly. Mechanical evidence
+checks do not prove semantic claims or that the model read the source. Empty pages,
+failed writers, and unplanned writer-added pages remain pending. Existing readable
+prose can remain available after a failed update while its page stays pending and stale.
+Writer-discovered source and test dependencies survive routing repair for later update scoping.
 
-`meta.json` records `updatedAt`, `gitHead`, the indexed source-tree hash, the
-model label, a content hash over the page tree, the page list, and the plan.
-`generation.pagesPlanned` and `generation.pagesWritten` say whether a run
-finished; when they differ, `clio-coder context wiki --update` completes the rest.
+`meta.json` records content publication time and model provenance, source evidence, the page-tree content hash, page list, and plan. `generation.pagesPlanned` and `generation.pagesWritten` describe completeness. A `generated` outcome means content was published; `noop` means Markdown bytes were unchanged. Either can still have pending pages. Unchanged-content attempts persist plan progress and attempts without changing content-publication time or model provenance; successful unchanged-content writers can validate existing prose. The CLI reports `incomplete` when any pages remain pending, with separate published, complete, and pending counts and explicit recovery instructions.
 
-`clio-coder context wiki` creates a wiki when no metadata exists and updates one when metadata is present. During wiki generation, Clio automatically refreshes a stale codewiki index before grounding the model run. The decision to write new pages and update metadata is a no-op if the newly generated content's hash matches the existing content hash. `clio-coder context wiki --update` requests update mode explicitly. `clio-coder context wiki --status` only reads metadata and does not run a model. `clio-coder context refresh --wiki` first rebuilds the structural codewiki and then updates an existing wiki when `.clio-coder/wiki/meta.json` exists; when no wiki metadata exists, it performs no wiki generation.
+`clio-coder context wiki` creates or updates a wiki and first refreshes a stale structural index. `--update` requests update mode explicitly; it refreshes stale pages based on changed source dependencies, but is not a promise to overcome exhausted attempts. `clio-coder context wiki --retry-pending` retries each pending page once, including exhausted pages, without erasing cumulative attempts or replanning at the same depth. If no saved plan exists, `--retry-pending` produces an actionable failure without spending model calls. `--status` reads status and retained failure diagnostics without a model call. Metadata is prepared beside staged pages before publication. After process interruption, the next generation validates live and previous content/metadata pairs and restores a valid previous pair when live is absent or incomplete, preserving a damaged live tree separately. The wiki lock serializes generation, but other editors are not locked out and readers can observe the rename gap: this is process-crash recovery, not atomic directory exchange or power-loss durability. `clio-coder context refresh --wiki` rebuilds codewiki and updates only an existing wiki.
 
 ### Lifecycle Matrix
 
@@ -335,19 +331,12 @@ finished; when they differ, `clio-coder context wiki --update` completes the res
 | `/context init` or `clio-coder context init` | Performs a full codewiki rebuild before generating, preserving, proposing, or previewing `CLIO-CODER.md`; writes state with the fingerprint and codewiki version when it writes state. | No wiki generation. |
 | `/context refresh` or `clio-coder context refresh` | Performs a full codewiki rebuild and writes state. Does not touch `CLIO-CODER.md`. | If an existing wiki is stale and `--wiki` was not passed on the CLI, prints a hint to run `clio-coder context refresh --wiki` or `clio-coder context wiki --update`. |
 | `clio-coder context refresh --wiki` | Performs the same full codewiki rebuild and state write. | Updates an existing wiki through the model-backed page dispatches. No wiki metadata means no wiki model call. |
-| `clio-coder context wiki` | Automatically refreshes the codewiki index if stale before composing the wiki prompt. | Plans, then writes each owed page in its own dispatch, assembles and promotes whatever landed (no-op if content hashes match), and records any pages still owed. |
+| `clio-coder context wiki` | Automatically refreshes the codewiki index if stale before composing the wiki prompt. | Plans, dispatches each owed page, validates completion outcomes, and publishes assembled content or records unchanged-content progress; failed pages remain pending. |
 | `clio-coder context wiki --status` | No index rebuild. | Reads metadata and reports page count, update time, recorded git head, git-head drift, and how many planned pages remain unwritten. |
 
 ### Staleness
 
-Codewiki staleness is controlled by one predicate:
-`isStale(prev, curr)` compares only `fingerprint.treeHash`. The fingerprint
-hash is mtime-aware: it walks the repository, excludes generated/local-state
-directories and lock/archive files, and hashes each included relative path,
-file size, and floored `mtimeMs`. The fingerprint also records `gitHead` and
-`loc`; `loc` comes from the codewiki artifact when available, otherwise from a
-line count over source extensions. Those fields are reporting data, not the
-stale predicate.
+Codewiki staleness uses `isStale(prev, curr)`, comparing `fingerprint.treeHash`. The v3 fingerprint hashes each included relative path and its source-byte digest, so whitespace-only edits and same-size edits with restored timestamps invalidate it. It covers the shared visible indexable file set and excludes ignored/generated/local-state paths. Read errors fail certification. Cached status checks may reuse a fingerprint for five seconds; individual reads remain synchronous even in the cooperatively yielding path. `gitHead` and `loc` remain reporting fields. Older fingerprint domains invalidate once and trigger reconciliation; this is not an atomic filesystem snapshot.
 
 `.clio-coder/state.json` stores the fingerprint and optional `codewikiVersion`.
 Legacy v2/v3/v4 codewiki files can still be read as degraded v5 artifacts, but
@@ -355,16 +344,12 @@ their missing or deliberately invalidated per-file hashes make `codewikiNeedsBac
 next session freshness check, `code_nav` demand load, wiki generation, or
 explicit refresh rebuilds them into full v5.
 
-Wiki staleness is separate. New `.clio-coder/wiki/meta.json` files record both the git
-head and the indexed source-tree hash used when the wiki content last changed.
-Clio reports drift at the same git head when tracked or untracked source files
-change, and combines committed and working-tree evidence in its changed-file
-count. Older metadata without a source-tree hash retains the git-head-only
-check. Git-less or unreadable git states degrade to `fresh` with a warning when
-Clio cannot prove drift.
+Wiki staleness uses separate bounded source-byte evidence, including README and configuration files beyond the structural index. Before/after capture and claimed-directory comparisons detect changed, added, or deleted inputs; changes during generation return previously written pages to pending. Capture is limited to 20,000 files and 128 MiB of source bytes. Missing, legacy, unreadable, or over-limit evidence cannot certify freshness, and unavailable Git evidence is conservative rather than treated as a clean diff. These observations do not form an atomic filesystem snapshot or a complete semantic input manifest.
 
 ### Surfacing and Navigation
 
+Project-type markers use the type recorded in `state.json`, falling back to detection only when no state exists. The codewiki marker checks artifact presence and recorded source freshness without parsing the index on the prompt path. It does not validate artifact contents: `code_nav` and session freshness checks read the index and rebuild an unreadable artifact from source before using it.
+
 The compiled prompt surfaces only markers, never the codewiki JSON or wiki page
 contents. Fresh codewiki renders as `<codewiki>available; use code_nav</codewiki>`.
 A stale codewiki marker adds `(stale; run /context refresh)`. A valid wiki marker

package/docs/architecture/context-working-set.md

@@ -18,7 +18,7 @@ Source of truth is `src/domains/context/working-set/` (`contract.ts`, `fold.ts`,
 | Ledger | The durable append-only session record (`current.jsonl`). The working-set layer appends to it and never rewrites it. |
 | Evicted | A unit whose body the projection replaces with a marker. The ledger entry that holds the original body is untouched. |
 | Offloaded | A result the observation envelope already wrote to a file because it exceeded the per-call cap. Its marker carries the pointer instead of a preview, and recall returns the pointer rather than inlining the file. |
-| Recall | Readmitting an evicted body by ref, through `context(scope="recall", ref=...)` for the model or `/context recall <ref>` for the operator. |
+| Recall | Readmitting an evicted or summarized tool-result body by ref, through `context(scope="recall", ref=...)` for the model or `/context recall <ref>` for the operator. |
 | Marker | The byte-stable one-line stub the projection renders in place of an evicted body. It names the ref, the reason, the size, and the exact call that brings the body back. |
 | Projection | A pure, in-memory transform from ledger entries to the entries the replay builder hands the model. `projectWorkingSet(entries, view)` is that function. |
 
@@ -118,19 +118,17 @@ The facts the rungs read come from `path-index.ts`, one deterministic pass over
 
 ## Recall
 
-Recall is explicit and by ref. There is no auto-readmission: the marker tells the model exactly which call brings the body back, and the model decides.
+Exact recall is explicit and by ref for persisted tool results hidden by eviction or summary compaction. There is no automatic readmission. `context(scope="recall", query="...", limit=8, offset=0)` with `ref` omitted discovers eligible results in active-path ledger order. Query matches ref, tool, and path metadata; limit defaults to 8 and caps at 12. Rows include timestamps and evicted/summarized state. `nextOffset` continues the same query against the same active path and ledger state. Discovery does not append `contextRecall`.
 
-`resolveRecall(entries, view, ref, activeLeafTurnId)` resolves a ref against the fold at the live leaf and returns the original body byte-exact, read with the same field precedence the projection would have used. It fails in three typed ways:
+`resolveRecall(entries, view, ref, activeLeafTurnId)` resolves against the active path and compaction cut, returning the persisted tool-result body with the same field precedence as projection. It rejects malformed refs, unknown or other-branch refs, currently visible results, assistant thinking, and legacy destructively compacted bodies. It cannot recover bytes already removed from older logs.
 
-- `invalid_ref` when the ref is empty or carries whitespace.
-- `not_on_active_path` when the session has no such turn on this branch, which includes a ref from a branch `/tree` abandoned.
-- `not_evicted` when the unit is still in context. An assistant turn reports separately that thinking is not recallable.
+Errors distinguish `invalid_ref`, `not_on_active_path`, and `not_evicted`; the last also covers unsupported or still-visible entries with a specific diagnostic.
 
 The `not_on_active_path` and `not_evicted` messages end with the refs that can be recalled on the active path (tool results only, up to eight, then a count). `invalid_ref` reports only the malformed value. Clio deliberately lists valid refs instead of guessing a nearest ref, because similar time-ordered identifiers can name unrelated results.
 
-An LLM summary also preserves recall discovery across its cut. When an evicted tool result falls before `firstKeptTurnId`, the generated checkpoint carries a `<recallable-refs>` block with the same `ref (tool path)` rows used by recall failures, bounded to eight rows plus a remaining count. Results that stay after the cut keep their ordinary markers and are not repeated in the block.
+An LLM summary preserves discovery across its cut. The checkpoint carries a bounded `<recallable-refs>` preview for tool results hidden by compaction, including results that were never explicitly evicted, and points to omitted-ref discovery for the complete paginated inventory. Results after the cut retain their ordinary markers. Exact recall returns historical persisted content; reading the path again returns its current filesystem contents.
 
-**A recall does not un-evict.** The key stays in `view.evicted`, the marker stays byte-identical at its original position, and the recalled body arrives at the tail of the working set inside the recall result. Readmitting it in place would duplicate the bytes and invalidate the provider prefix cache for everything after that point, which costs more than the recall saved.
+**A recall does not un-evict.** For explicitly evicted results, the key stays in `view.evicted` and the marker stays byte-identical. Summarized results remain behind the compaction cut. In both cases the recalled body arrives at the tail inside the recall result. Readmitting it in place would duplicate the bytes and invalidate the provider prefix cache for everything after that point, which costs more than the recall saved.
 
 That also makes recall the churn signal. `churn = recalls / itemsEvicted` over the active path. A high churn number means the policy keeps evicting content the session still needs, which is a reason to change the policy rather than to raise the threshold.
 
@@ -175,7 +173,7 @@ The retired `compaction.excludeLastTurns` key is not accepted by settings v2. Th
 
 - **`/context` overlay.** A working-set section under the category legend: the configured policy with its state (`policy structural-v1 · no events yet` until the first event, `disabled` when `context.workingSet.enabled` is off, and `(last event by <policy>)` when the setting changed after an event), evicted item count, evicted tokens, event count, recall count, and churn. Evicted tokens render as one line after the legend rather than as a meter category, because they are outside the window rather than a slice of it.
 - **Transcript.** An evicted tool row keeps its full body and gains a dim `evicted · <reason>` tag. The transcript shows the ledger, never the projection, so `/resume`, `/tree`, `/fork`, and the HTML export are unaffected by eviction.
-- **`/context recall <ref>`.** Prints the ref, why it was evicted, the token count, and the offload pointer when there is one, followed by the original body. Transcript only.
+- **`/context recall <ref>`.** Prints the ref, its evicted or summarized state, the token count, and any offload pointer, followed by the persisted body. Transcript only.
 - **Prompt cache line.** Every applied event stamps `working_set_evict` on the next assistant entry's `promptCache.expectedColdReasons`. When the last settled run came back cold for that reason, the overlay adds `last cold turn: working-set eviction (expected)` and drops the shell-reused-but-backend-cold warning, because the cold turn is explained rather than surprising.
 - **Notice.** One line per applied event: `[context engine] working set: N items evicted by <policy>; ~X -> ~Y tokens, recall by ref with context(scope="recall")`. The numbers are the plan's, priced over the visible ledger slice, and they are the same numbers the `contextEviction` entry, the `[Compaction] Reclaimed context` toast, and the overlay's `last compaction` line carry. The footer meter is a separate live estimate over the agent message list and can differ from them by the tool schemas and replay text it includes.
 

package/docs/architecture/dispatch-architecture-rationale.md

@@ -126,4 +126,4 @@ affected import site for no behavioral gain. A boundary rule should protect an
 invariant. "Always import through the barrel" protects a preference.
 
 What is *not* permitted is anything the six direction rules forbid, and those
-stay enforced by the boundary checker that `npm run lint` runs.
+stay enforced by the boundary checker that `pnpm run lint` runs.

package/docs/architecture/evidence-and-memory.md

@@ -453,3 +453,13 @@ Only the field matching the record scope is present.
 7. Prune stale records periodically.
 
 Memory is meant to reduce repeated mistakes, not to become an unreviewed second instruction system.
+
+## Convention retention and decision adherence
+
+Remembering a convention starts with inspecting and citing its sources. Capture is selective. An existing source-grounded knowledge or procedural bank entry can be proposed by the operator through `/memory` with `p`, or promoted from an actual version-2 handoff export. Promotion persists an unapproved proposal; separate operator approval admits it to scoped, bounded selection. If no matching entry was captured, report that limit. A general request to remember does not approve an unseen record.
+
+Approval, persistence, and fresh-session consumption are separate observations. Claim consumption only when the matching approved record is delivered; approval does not guarantee selection. Transcript recovery and unrelated memory are not evidence of durable convention delivery. Background memory reasoning is currently disabled; this workflow does not add a low reasoning setting.
+
+An explicit no-edit task includes the handbook and every repository file. Do not substitute a handbook edit, note, handoff export, shell write, or delegated edit for reviewed memory. Explain retention steps that require writes outside the authorized scope.
+
+Decision references and commit trailers establish attribution, not behavioral adherence. Before committing, agents are instructed to check the implementation against active decision semantics, including actual scalar types when a policy requires Python integers. A changed agent-owned policy requires an explicit same-key revision before commit; operator decisions remain operator-owned. This guidance does not guarantee model compliance.

package/docs/architecture/pi-boundary.md

@@ -3,7 +3,7 @@
 > **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
+Clio Coder pins Pi 0.85.1 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
@@ -31,9 +31,9 @@ Clio-owned surface during a dependency bump.
 | pi-ai `CredentialStore` and `Models.getAuth` | `src/domains/providers/auth/storage.ts` | Keep Clio ownership. | Clio's locked YAML store, damage control, target-first registry, and runtime overrides are product boundaries. |
 | pi-ai `createModels`, `createProvider`, and `ModelsStore` | `src/domains/providers/**` | Keep Clio ownership. | Targets, nodes, probing, residency, ALCF, and fleet placement are Clio concepts rather than provider-keyed SDK state. |
 | pi-ai `Provider.auth.oauth` | `src/engine/oauth.ts` | Route built-in OAuth through Pi and keep ALCF. | Pi owns provider OAuth implementations. Clio adds the ALCF science-provider flow. |
-| pi-agent-core application cut-point helpers | `src/domains/session/compaction/cut-point.ts` | Keep Clio ownership. | The published SDK does not export these helpers, and Clio operates on its larger `SessionEntry` union with a tested small-session fallback. |
-| pi-agent-core `estimateTokens` and `estimateContextTokens` | `src/domains/session/compaction/tokens.ts` and `src/domains/session/context-accounting.ts` | Keep Clio ownership. | Clio accounts for message overhead, images, tool-schema splits, and provider-usage reconciliation beyond Pi's character estimate. |
-| pi-agent-core `SUMMARIZATION_SYSTEM_PROMPT`, `generateSummary`, and `serializeConversation` | `src/domains/session/compaction/compact.ts` and `src/domains/session/compaction/branch-summary.ts` | Keep Clio ownership. | Pi's functions require Pi v4 entries and `Models`; Clio compacts its ledger with cumulative checkpoints and turn-prefix summaries. |
+| pi-agent-core `findCutPoint` and `findTurnStartIndex` | `src/domains/session/compaction/cut-point.ts` | Keep the current implementation pending a tested adapter. | These helpers are public root exports in 0.85.1. They accept Pi v4 `Entry[]`; Clio uses its own `SessionEntry` union, ledger indexes, tool-batch boundaries, and small-session fallback. Reuse requires preserving those contracts through an entry/index projection, not a direct import substitution. |
+| pi-agent-core `estimateTokens` and `estimateContextTokens` | `src/domains/session/compaction/tokens.ts` and `src/domains/session/context-accounting.ts` | Keep Clio's outer accounting. | Pi also anchors estimates to provider usage. Clio additionally accounts for framing, system prompts, tool schemas, pending input, usage invalidation, and the greater of projected and anchored totals. Both use heuristics for unmeasured content; neither character estimate guarantees an upper bound for every tokenizer. |
+| pi-agent-core `generateSummary`, `generateSummaryWithUsage`, and `serializeConversation` | `src/domains/session/compaction/compact.ts` and `src/domains/session/compaction/branch-summary.ts` | Keep the current summary boundary pending a tested adapter. | The public summary generators accept `AgentMessage[]`, `Models`, and Pi harness context; `serializeConversation` accepts provider messages. Clio additionally owns bounded cumulative checkpoints, turn-prefix summaries, cancellation, usage settlement, and publication checks. The internal `SUMMARIZATION_SYSTEM_PROMPT` constant is not a public root export. |
 | pi-agent-core `JsonlSessionRepo`, v4 `Session`, and `AgentHarness` | `src/engine/session.ts` and `src/domains/session/**` | Keep Clio ownership. | The on-disk ledger, active tree, fork behavior, receipts, and evidence are Clio's durable spine. |
 | pi-agent-core `loadSkills`, `loadPromptTemplates`, `parseCommandArgs`, `substituteArgs`, and `formatSkillsForSystemPrompt` | `src/domains/resources/skills/loader.ts` and `src/domains/resources/prompts/loader.ts` | Keep Clio loaders and reuse leaf primitives when compatible. | Clio owns marketplace pinning, trust, evals, activation records, and prompt-source policy. Argument substitution can use Pi without replacing the loader. |
 | pi-agent-core harness tools, `executeShellWithCapture`, and `sanitizeBinaryOutput` | `src/tools/**` | Keep Clio ownership. | Tool admission, observation budgets, safety rails, and result shaping apply across interactive, headless, ACP, and worker runs. |
@@ -49,19 +49,47 @@ Clio-owned surface during a dependency bump.
 | 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 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. Clio persists raw assistant content blocks, including `thinkingSignature`, and restores them through rich replay; Pi decides whether signatures remain usable for the selected model and transport. |
 | 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. |
 
+## 0.85.1 integration
+
+The three SDK packages stay on the same exact version. The older Anthropic
+client override is removed so Pi can use its declared `@anthropic-ai/sdk`
+0.123.0 dependency. The repository's esbuild override remains in the pnpm
+workspace configuration.
+
+| Pi change | Clio adaptation or behavior |
+| --- | --- |
+| OpenRouter's catalog can select Anthropic Messages | With no explicit target URL, synthesis keeps Pi's catalog API, URL, compatibility flags, and effort map together. Explicit URLs retain the runtime's OpenAI-completions contract; if the catalog uses another API, synthesis omits its transport-specific compatibility and effort metadata. Unknown models use the OpenAI fallback. The engine already dispatches by the synthesized model's API. |
+| `AssistantMessage.providerThinkingLevel` and Anthropic `supportsMidConvoEffort` | Persist and restore historical provider effort alongside raw content in `assistantSessionPayload` and rich replay. A regression constructs a native Anthropic request after JSON persistence and confirms that earlier high/medium turns retain their effort before the active high-effort marker. Pi owns request assembly and signed-thinking recovery. |
+| `ScrollView` track/thumb style callbacks and `OverlayHandle.getBounds()` | Use the public track and thumb styling callbacks. Overlay wrappers delegate bounds to the currently mounted frame. Regressions exercise rendered bounds, resize, visibility, replacement, ordinary/Alt wheel scrolling, and following the transcript end. |
+| Component mouse handling, optional editor/input hooks, and alt-screen controls | Inherit compatible Pi component behavior. Custom Clio components still need their own mouse wiring where they do not compose a mouse-aware Pi component. `clearOnShrink` remains false by default; removal of its environment lookup does not invert that default. |
+| `AgentTool.replay` | Leave the optional policy unset. Clio uses `Agent`; the new durable harness owns recovery replay and defaults omitted policies to `never`. |
+| OpenAI-compatible `vllmPriority` | Available through Pi's optional compatibility setting. This upgrade does not add a Clio scheduler-priority setting. |
+
+The environment-key parity helper also gains the existing Pi convention
+`qwen-token-plan-individual` → `QWEN_TOKEN_PLAN_API_KEY`. This corrects a
+Clio parity gap; it does not add a built-in Qwen runtime.
+
+Pi's assistant frame encoder/reducer is a public optional API, not a persistence
+feature Clio gains simply by updating its streaming adapter. Clio already strips
+cumulative snapshots from worker deltas in `src/worker/event-projection.ts`;
+adopting frames needs a measured benefit and must preserve terminal messages
+separately. Pi's internal compaction file-list helpers are not exported through
+the package's public root or an allowed subpath, so they are not currently a
+supported way to remove Clio's small file-list formatter.
+
 ## Thin-wrapper watch list
 
 Review these files first when Pi changes. They intentionally contain little
 behavior and should not grow another implementation of an SDK primitive.
 
-- `src/engine/api-registry.ts` owns Clio's ordered dispatcher using Pi's public lazy API factories and full built-in provider catalog. Its dynamic `/compat` bridge exists only for configured out-of-tree runtime plugins that require Pi's process-global registry identity.
-- `src/engine/env-api-keys.ts` pins Pi 0.84's synchronous environment-key and ambient-credential discovery behind a parity contract; revisit it on every Pi upgrade until Pi exports that helper directly.
+- `src/engine/api-registry.ts` owns Clio's ordered dispatcher using Pi's public lazy API factories and the provider catalogs selected in `src/engine/models.ts` for Clio's built-in runtimes. Its dynamic `/compat` bridge exists only for configured out-of-tree runtime plugins that require Pi's process-global registry identity.
+- `src/engine/env-api-keys.ts` pins Pi 0.85's synchronous environment-key and ambient-credential discovery behind a parity contract; revisit it on every Pi upgrade until Pi exports that helper directly.
 - `src/engine/apis/openai-completions.ts` maps compatibility flags, sampling parameters, and thinking budgets. Its Clio deltas are the local-runtime guards and sentinel, Harmony, and Gemma filters.
 - `src/engine/provider-payload.ts` retains only the OpenAI Responses reasoning-summary patch.
 - `src/engine/types.ts` and `src/engine/ai.ts` expose erased Pi types and `StringEnum` behind the engine boundary.
@@ -75,7 +103,9 @@ Run these contracts first on a Pi bump, before the full gate:
 
 - `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/openrouter-transport.test.ts`
 - `tests/contracts/provider-context-boundary.test.ts`
+- `tests/contracts/rendering-invariants.test.ts`
 - `tests/contracts/gemma-channel-filter.test.ts`
 - `tests/contracts/tool-boundaries.test.ts`
 - `tests/contracts/session-durability.test.ts`

package/docs/architecture/prompt-envelope-and-tools.md

@@ -16,7 +16,7 @@ window source, prompt-input epoch, resolved session inputs, and the exact
 attached tool-schema bytes. `mainPromptCacheIdentity` in
 `src/interactive/prompt-cache-identity.ts` owns that list.
 
-The compiled prompt is reused byte-for-byte on ordinary submits. It recompiles only when that key changes or when config hot-reload invalidates the prompt cache. Path-scoped project rules can therefore recompile the prompt when a matching file enters working context. When recompilation changes the text, the session ledger records a `promptRecompiled` entry with the previous hash, new hash, and token estimate.
+The compiled prompt is reused byte-for-byte on ordinary submits. Handbook source bytes and prompt inputs are captured per session, so ordinary recompilation does not silently reload edited files. Init, refresh, and reset invalidate the session snapshot and prompt cache, including partial-write failure paths; config hot-reload also invalidates inputs. Path-scoped rules can recompile when a matching file enters working context. When recompilation changes the text, the ledger records `promptRecompiled` with previous hash, new hash, and token estimate. The bounded handbook preload retains exact safe prefixes; captured-source hashes belong to its accounting/manifest metadata. Model-facing omission notices identify source paths and line ranges, and later filesystem retrieval reads current bytes.
 
 ## Section order: stable prefix first
 
@@ -55,7 +55,7 @@ In addition to project root `CLIO-CODER.md` handbooks, Clio supports directory-s
 - Sibling directories outside the subtree continue to inherit from the root handbook or their own local overrides.
 - Deeper subtrees within the directory may add further localized guidance.
 - Prompt blocks preserve explicit source paths for attribution and debugging.
-- Malformed override files fail closed rather than injecting partial guidance, and context resets never delete override files.
+- Empty or unreadable selected overrides fail closed. Ordinary authored Markdown is accepted without a structured project identity, and context resets never delete override files.
 
 `wiki.page` and `wiki.plan` (`src/domains/prompts/fragments/wiki/*.md`) load through this same loader, with the same id/version/content-hash contract as every other fragment, but they are consumed differently: `context/wiki/prompts.ts` reads them by id, substitutes per-dispatch `{{token}}` placeholders (a page's path, title, and relative path; the plan file's path), and sends the result as a wiki-generation dispatch's `task`, never as a compiled system prompt. `{{token}}` substitution has no home in the fragment loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders use in `compiler.ts`: the loader hands back a raw body, and the one caller that needs live values fills them in. Both files' bodies open and close on a standalone `---` line that predates their frontmatter and was kept unchanged as body text so the substituted prompt stays byte-identical to what the old hand-rolled `readFileSync` produced.
 
@@ -73,11 +73,11 @@ Providers that cannot call tools receive no schemas, and the prompt tells the mo
 
 ## Canonical worker harness
 
-Native and mediated dispatch workers use a separate prompts-domain compiler over the same loaded fragment table. Its stable system prompt has five fixed sections plus one optional trailing one: identity-lite, the constitutional operating contract plus the `operating.worker` assigned-task contract, a tool contract sliced to the final canonical toolkit, the same `safety.<level>` fragment the session reads for the single effective autonomy under a worker one-liner that carries the run's permission routing, one final persona, and the operator-editable layer when either of its parts renders non-empty: active project rules scoped to this run's inferred working context, and the operator profile. A request persona override replaces only the recipe body; eligible bound-skill instructions are composed inside that same final persona and never widen tools.
+Native and mediated dispatch workers use a separate prompts-domain compiler over the shared fragment table. The stable system prompt contains identity-lite, the constitutional operating and assigned-task contracts, the final toolkit contract, effective safety and permission routing, one final persona, and any scoped project rules and operator profile. A request persona replaces the recipe body; eligible bound-skill instructions remain inside the final persona without widening tools. Authored handbook context travels separately in a bounded dynamic message, not in this stable system prompt.
 
-The operator-editable layer reaches a worker through `additionalFragments`, the same channel `compile()` uses for the session, so nothing splices into an existing section. The operator profile renders unconditionally, capped, the same as it does for the session: it governs how the worker should do the task (validation preference, commit-message style, local-only paths), not only how the orchestrator talks to the operator. Project rules are scoped to the worker's working context rather than shipped wholesale. That context is `writeRoots`, when the caller sets them, plus path-like tokens recalled from the task and briefing text, since the model-facing dispatch tool has no structured path field. A missed path token means a rule can go unseen; it can never fabricate one, because `selectActiveRules` still requires a real glob match.
+The operator-editable system layer uses `additionalFragments`. The operator profile renders unconditionally within its cap, while project rules are selected from `writeRoots` and path-like tokens in the task and briefing through real glob matches. The separate handbook message follows the effective project-context tier: native defaults depend on capability class and recipe, with Coder and verification workers bounded and Scout none; ACP defaults to none and requires `projectContext: "bounded"` in its configuration. A bounded run uses captured `ProjectPromptContext` authored Markdown through the shared exact-prefix selector, within 1,500 UTF-16 units including source wrappers and omission notices, and the inherited 220-rendered-line limit. The raw authored branch does not inject a second structured projection of conventions, invariants, or verification. Legacy structured-only callers still receive project name, conventions, and invariants; their derived verification supplement is limited to verification-class workers.
 
-The compiler runs after target capability and tool-profile admission. Its canonical tool names are the same names transported in `WorkerSpec.allowedTools` and attached as schemas; routine non-Scout work removes `code_nav`, narrow profiles remove their excluded schemas and guidance, tool-incapable targets get an explicit no-tools contract, and Claude SDK aliases are filtered from the same canonical set. ACP's external inventory is unknown, so ACP bounded-role admission continues to validate the unchanged raw persona rather than fabricating a complete native schema list.
+The worker compiler runs after target capability and tool-profile admission. Canonical names match `WorkerSpec.allowedTools` and attached schemas: routine non-Scout work removes `code_nav`, narrow profiles remove excluded schemas and guidance, and tool-incapable native targets receive a no-tools contract. Claude SDK aliases are filtered from the same set. For omitted handbook text, native workers without admitted read capability are told retrieval is unavailable; unknown native capability makes the read instruction conditional. ACP and subprocess runtimes have unknown external tool inventories, so their notices refer conditionally to their own file-reading tools without promising a native Clio read schema. ACP bounded-role admission continues to validate its raw persona rather than claiming a complete native toolkit. Retrieval reads current filesystem content, which may differ from the captured source identified by accounting/manifest hashes.
 
 Project context, memory, bounded dispatch briefing, pipeline input, the assigned task, and the per-run safety-posture reminder remain dynamic user messages. A briefing is a separately delimited message labeled as untrusted task context/data; it is never concatenated into the task or stable system prompt. Dynamic ordering is project, safety, memory, briefing, then pipeline input, with pipeline input last. These messages do not affect the stable composition hash. Persona, effective autonomy, target tool capability, or final toolkit changes do affect it.
 
@@ -151,7 +151,7 @@ Several tools absorb what used to be separate tools:
 
 - `find(pattern, path?, order?, limit?, include_ignored?)` locates paths by glob pattern (`*`, `**`, `?`, `[abc]`), default limit 500. `order="path"` (default) returns fd's native order; `order="mtime"` returns newest first from a bounded candidate set instead of statting the whole tree, and reports `details.candidates` when the candidate cap made the ordering approximate.
 - `grep(pattern, path?, mode?, glob?, ignore_case?, literal?, context?, limit?, include_ignored?)` searches file contents with ripgrep, degrading to a bounded pure-Node search when rg is absent. `mode=content` (default) returns line-referenced matches, `mode=files` returns matching paths, `mode=count` returns per-file counts. Context lines are consumed from rg's `--json` stream.
-- `context(scope="workspace"|"docs"|"skills")` is the one OBSERVE entry point for material about the working environment: the session workspace snapshot, retrieval over Clio's bundled documentation (`query` required), and skill listing or loading (`name` optional, `include_tree` for the skill's resource files).
+- `context(scope="workspace"|"docs"|"skills"|"recall")` observes the session workspace snapshot, bundled documentation (omit `query` to list the corpus), skills (`name` optional, `include_tree` for resources), or persisted historical tool results. In recall scope, provide `ref` for exact retrieval or omit it for discovery with `query`, `limit`, and `offset`.
 - `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` lists package.json verification scripts and strict version-1 `.clio-coder/verifiers.yaml` entries through the same `{id, description, command, cwd, timeoutMs, tags, source}` projection. `verify(check="<id>")` runs a package script or the catalog's exact argv/cwd/timeout through safe-exec with no shell. Model `args`, cwd, timeout, output-cap, and environment fields cannot mutate a project entry. `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
 - `artifact(kind="plan"|"review"|"report", content, ...)` writes named artifacts behind one surface: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is written with the ordinary write tool and validated by the skills loader.
 - `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona`, `tool_profile`, and a typed `budget: {toolCalls, readReserve, retryRevision?}`. The budget must fit the recipe's authored range and the operator lifetime cap. `retryRevision` is the only authority for a later retry, result-contract revision, or review revision to grow its phase. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
@@ -205,7 +205,7 @@ Clio uses two context-protection mechanisms.
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the LLM summary path directly.
 
-Compaction rewrites history, so the next turn on a local single-slot backend is expected to lose prefix-cache alignment. Clio records `expectedColdReasons` and shows one dim notice for that turn.
+Compaction changes projected model replay while retaining the raw ledger, so the next turn on a local single-slot backend is expected to lose prefix-cache alignment. Clio records `expectedColdReasons` and shows one dim notice for that turn.
 
 ## Inspecting a session
 

package/docs/architecture/session-lifecycle.md

@@ -168,7 +168,7 @@ reported to `/cost` under a handoffs row and excluded from the turn count.
 
 ### Streaming Turn Settlement During Session Transitions
 
-When an operator issues `/new`, `/resume`, `/tree`, or `/fork` while an assistant turn is actively streaming, `settleChatBeforeSessionSwitch` (`src/interactive/session-switch-settlement.ts`) cancels the in-flight stream and awaits completion. This guarantees that partial assistant records and completed tool executions seal cleanly into the active session ledger before the session writer is replaced, preventing orphaned records in new sessions or unanswered prompts in original sessions (#114). Synchronous session transitions when chat is idle continue to execute immediately.
+When an operator issues `/new`, `/resume`, `/tree`, or `/fork` during streaming, `settleChatBeforeSessionSwitch` cancels and awaits the in-flight turn so partial assistant records and completed tools settle before replacing the writer. Shutdown separately stops shell admission and drains the active operator command. Hooks default to 500 ms each; the operator-shell hook allows six seconds for its existing five-second cancellation escalation, and worker group escalation uses 500 ms. Owned same-process-group descendants are covered by Linux validation, including descendants that close inherited pipes. Arbitrary daemonized or regrouped processes are outside this scope; macOS, Windows, and real SSH behavior remain unverified.
 
 ---
 
@@ -185,7 +185,7 @@ When resuming a session via `/resume` or a headless `clio-coder run --session <i
 
 ### Model-Facing Custom Entry Replay
 
-When resumed or forked session history is replayed to the model, custom session entries (such as compaction summaries, branch summaries, and operator bash executions) are projected into standardized user-role message text via `src/engine/messages.ts` constants (`COMPACTION_SUMMARY_PREFIX`, `BRANCH_SUMMARY_PREFIX`, `bashExecutionToText`) rather than ad-hoc formats, ensuring deterministic prompt construction across sessions.
+When resumed or forked session history is replayed to the model, compaction summaries, branch summaries, and operator bash executions use standardized user-role text through `src/engine/messages.ts`. Working-set projection runs before compaction counting and summary serialization, while raw ledger entries remain intact. Tool results hidden by summaries are discoverable with `context(scope="recall")` and recoverable by exact ref through the normal observation envelope; older destructive logs cannot recover removed bytes.
 
 ---
 
@@ -199,12 +199,12 @@ An explicit path ending in `.md` keeps the plain Markdown form: a heading, UTC e
 
 ## 7. Directory Handbooks and Project Overrides
 
-During session context loading, `loadProjectContextFiles` (`src/domains/context/clio-md.ts`) discovers root `CLIO-CODER.md` handbooks and directory-scoped `CLIO-CODER.override.md` files:
+During session context loading, `loadProjectContextFiles` (`src/domains/context/clio-md.ts`) captures readable authored Markdown from root `CLIO-CODER.md` handbooks and directory-scoped `CLIO-CODER.override.md` files. Optional structured projections do not determine source acceptance. Init, refresh, and reset invalidate captured session inputs; refresh preserves handbook bytes. Preload is bounded to 8,000 UTF-16 units and 220 rendered lines, with exact safe prefixes and capability-aware omission notices naming source paths and line ranges. Captured-source hashes are retained separately in accounting/manifest metadata. Tools-disabled targets cannot retrieve omitted suffixes through session tools; ordinary reads retrieve current content and retain their independent byte and 20 MB file limits:
 - An override handbook replaces inherited project instructions for its directory and all subdirectories, establishing an explicit subtree boundary.
 - Sibling directories remain unaffected.
 - Subdirectories within the subtree may supply narrower instructions with additional override files.
 - Prompt blocks preserve explicit source paths for provenance.
-- Malformed override files fail closed, and context resets never delete override files.
+- Empty or unreadable selected overrides fail closed; ordinary authored Markdown does not require a structured project heading. Context resets never delete override files.
 
 ---