@iowarp/clio-coder 0.3.7 → 0.3.9

package/docs/proactive-memory.md

@@ -1,6 +1,6 @@
 # Proactive task memory
 
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.9).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still
@@ -120,7 +120,7 @@ malformed response, or telemetry failure is silent and never blocks a tool.
 - `memory.intervention.everyNTools` (default `10`): Minimum completed-tool interval between background interventions.
 - `memory.intervention.windowSteps` (default `8`): Completed tool-trajectory window analyzed during background evaluation.
 - `memory.intervention.maxTokens` (default `400`): Bounds the rendered memory-bank and reminder context budget; the policy model output cap is a separate fixed `4,000`-token contract in `task-memory-policy.ts`, sized so that a model which reasons anyway still reaches its envelope.
-- `memory.intervention.timeoutMs` (default `180000`): Wall-clock limit for one background memory-policy request. The step is detached, so this deadline never delays a turn; set it above the observed step time for your route or finished work is discarded as a timeout. Step latency on a small local route is long-tailed rather than tightly clustered, so size this off a high percentile and not off a median.
+- `memory.intervention.timeoutMs` (default `30000`): Wall-clock limit for one background memory-policy request. The step is detached, so this deadline never delays a turn, but it does hold a request slot on a real inference endpoint that your own turns and your dispatched workers queue against. The default is what a turn boundary can wait for rather than what a long-tailed route eventually answers in: on the reference route below, 23 of 60 steps ran past 30 seconds and 531 of the measured 1,666 seconds were spent beyond that mark. Raise it only if you have measured that your route's slow steps are the ones producing reminders, and read the trade in "Cost and the default decision" first.
 
 ## Trigger semantics
 
@@ -203,6 +203,88 @@ Thus `last` remains `injected` across such continuations until a later
 tool-bearing or explicitly triggered memory step produces a new outcome (e.g.,
 a healthy tool leading to `silent`).
 
+## Cost and the default decision
+
+The LLM tier costs real tokens, real seconds of model time, and a request slot on
+a server that is usually the same machine the operator's own turns run on. Every
+step is therefore accounted for the way a `/btw` side question is: one cost entry
+under the `background-memory` label, which `/cost` shows as its own `memory steps`
+row, and one durable row in `<stateDir>/usage/out-of-turn.jsonl` carrying the
+usage, the call's duration, and the backend's prefill facts, which
+`clio-coder usage report` folds after the process exits. `/memory` shows the
+lifetime figures folded from `steps.jsonl`: steps, tokens, model time, and the
+hit rate.
+
+### The measurement
+
+From one operator's `steps.jsonl`, 274 rows spanning 2026-08-14 to 2026-08-29 on
+a small local background route:
+
+| Figure | Value |
+| --- | --- |
+| Model-tier steps | 60 |
+| Tokens | 137,205 |
+| Model time | 1,666.6 s |
+| Step latency | median 18.7 s, p90 70.2 s, max 102.5 s |
+| Injections produced by the model tier | 6 |
+| Hit rate | 10.0 percent |
+| Cost per injection | 22,868 tokens and 278 s of model time |
+| Model-tier injections in the last 5 days | 0 of 4 steps |
+
+Four further injections in the same window came from the free rules tier, so the
+lifetime total of 10 injections is not the model tier's score. Rules-tier
+injections cost nothing.
+
+### The decision
+
+The default does not change, and it is a deliberate default rather than an
+unexamined one:
+
+- `memory.intervention.enabled` stays `true`. It runs the rules tier, which makes
+  no model calls, spends no tokens, and produced 4 of the 10 injections.
+- The LLM tier stays opt-in through `background.target` and `background.model`,
+  which is already the case: an unset background role never resolves a client.
+  A 10 percent hit rate at 22,868 tokens per injection does not earn a default-on
+  position, and it is not so poor that it earns removal from an operator who has
+  measured their own route and wants it.
+- The step deadline drops from 180 s to 30 s. This is the one behavioral change,
+  and it is a genuine trade: at 30 s, two of the six observed injections, at
+  53.6 s and 57.7 s, would have been cut, while 531 s of the 1,666 s spent would
+  not have been spent at all. The deadline is the bound on what one optional call
+  may hold a shared local server for, not a prediction of when a route answers.
+- A step that would run on the endpoint the chat target is streaming against is
+  skipped with reason `endpoint_busy`, and the skip is recorded. On a single-slot
+  llama.cpp router the alternative is queueing behind the operator's own decoding
+  or evicting the resident model, and neither is a cost an optional call may
+  impose.
+
+### What a background target costs on a shared local server
+
+If `background.target` names the same server as `orchestrator.target`, that
+server's slots are shared. On a llama.cpp router started with `--parallel 1`
+there is exactly one, and the memory step and the operator's turn contend for it.
+
+The consequence is worth stating plainly: a shared endpoint suppresses the model
+tier rather than merely delaying it. A step is started from the `turn_end` hook,
+which fires inside the streaming run at `agent_end`
+(`src/interactive/turn-runtime.ts`), while the chat loop still holds its
+foreground registration on that endpoint; the loop releases the hold afterwards,
+in the `finally` around the run (`src/interactive/chat-loop.ts`). Every boundary
+therefore finds the endpoint busy and records `dropped`/`endpoint_busy`. That is
+the intended trade: an optional call may not take the one slot the operator's own
+turn is using, and it may not make the server swap the resident model out. The
+`/memory` step list and `steps.jsonl` say so on every boundary, so the tier is
+visibly declining rather than quietly idle.
+
+The second mechanism is an `expected cold` stamp, for the case where a step did
+run on the chat endpoint. Its prompt is a trajectory rather than the chat prefix,
+so the next turn's prefill is expected to be cold; `/context` names
+`background_memory` as the reason instead of reporting an unexplained cold
+prefix.
+
+Pointing the background role at a second machine avoids both effects and is the
+arrangement the tier is designed for.
+
 ## Choosing a background model
 
 Memory reads a trajectory and writes a fixed envelope. It does not plan, and it
@@ -257,7 +339,7 @@ memory:
     everyNTools: 10
     windowSteps: 8
     maxTokens: 400
-    timeoutMs: 180000
+    timeoutMs: 30000
 ```
 
 With `background.target` and `background.model` unset, Clio stays in the
@@ -289,12 +371,12 @@ percentile of 79.9, and a 95th of 131.6. Capability is not the constraint;
 latency is, its spread is wide, and the detached step above is what makes the
 tier usable anyway.
 
-Size `timeoutMs` off that tail rather than off the median. The shipped 180000
-captures roughly the whole distribution on this route. A 20000 setting looks
-generous against an 18.6-second median and in practice discarded about half of
-all steps, since the request is aborted on timeout and its work is thrown
-away. A route whose steps mostly record `timeout` is a misconfigured deadline
-before it is a slow model.
+The deadline is a bound on what an optional call may hold that server for, not a
+figure sized to capture the tail. The shipped 30000 sits above the median and
+below the tail deliberately, and a step that exceeds it records `timeout` with
+its work discarded. A route whose steps mostly record `timeout` is a
+misconfigured deadline before it is a slow model, so read the ledger before
+raising it: `/memory` shows the hit rate the raise would be buying.
 
 The target ID is not hard-coded. Any configured orchestrator-eligible local
 target and wire model can fill the background role. Before enabling it, use the
@@ -316,6 +398,25 @@ For an immediate kill switch, set `memory.intervention.enabled` to `false` in
 `/settings`. Removing the background target instead returns to rules-only
 operation while leaving deterministic protection active.
 
+## Where what the tier writes ends up
+
+A bank entry lives and dies with its session. When a reminder actually reaches
+the operator, the entries it cited are also proposed into the durable store at
+`<dataDir>/memory/records.json`, unapproved, scoped to the repository the session
+is working in, with provenance naming the session and the source entry. That is
+the one automatic writer of that file; everything else about it is unchanged.
+`/memory` and `clio-coder memory list` show the proposal, and
+`clio-coder memory approve <id>` is still a separate operator action, so nothing
+the background plane produced reaches a system prompt without review. A step with
+no session, or one running outside a canonical repository, proposes nothing:
+global scope broadens applicability to every future session and is not a claim a
+background step may make on the operator's behalf.
+
+Rules-tier reminders are not proposed. Their entries are this middleware's own
+one-line records of a repeated tool failure, and filing each one as a durable
+lesson would fill the review queue with rows nobody asked for. They remain
+promotable by hand from `/memory`.
+
 ## What the LLM tier actually writes
 
 Measured on the shipped prompt against `google/gemma-4-26b-a4b-qat`, across ten
@@ -392,11 +493,23 @@ keeps one previous generation as `steps.jsonl.1`. Every exact-schema record has:
 - `silent`, `injected`, `gated`, `timeout`, `malformed`, or `dropped` decision;
 - count of cited entries, input/output/total memory-model tokens, and latency.
 
-`dropped` is the one outcome that ran no step: the boundary triggered while an
-earlier step still held the single in-flight slot. It costs no tokens and no
-latency, its triggers survive to the next free boundary, and it does not replace
-the operator-visible last decision. Counting `dropped` rows against `llm` rows
-over a session is how a starved cadence becomes visible.
+The same steps are also billed. See "Cost and the default decision" for the
+`/cost` row, the durable out-of-turn usage row, and the lifetime figures `/memory`
+folds out of this file.
+
+`dropped` is the one outcome that ran no step. It has two causes, separated by
+the row's reason: `step_in_flight` means the boundary triggered while an earlier
+step still held the single in-flight slot, and `endpoint_busy` means the step
+would have called the endpoint the chat target was streaming against. Both cost
+no tokens and no latency, both leave their triggers pending for the next free
+boundary, and neither replaces the operator-visible last decision. Counting
+`dropped` rows against `llm` rows over a session is how a starved cadence becomes
+visible.
+
+A step that exceeds the deadline records `timeout`, never `silent`: reason
+`deadline` when the policy's own race fired first, and `timed_out` when the
+transport aborted at its deadline. Both are distinct from `client_error`, which
+is a route that refused rather than a route that was slow.
 
 The log contains no task, trajectory, bank, error, or reminder text. File creation,
 rotation, serialization, and injected sinks are all best effort; a read-only

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

@@ -1,7 +1,7 @@
 # Prompt Envelope and Tools
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.9).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 
@@ -13,6 +13,24 @@ The chat loop compiles one provider-facing system prompt for a session. The comp
 
 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.
 
+## Section order: stable prefix first
+
+The compiled prompt lays its sections down in `SESSION_PROMPT_SECTION_ORDER` (`src/domains/prompts/compiler.ts`): identity, operating contract, delegation, skills, safety, tool contract, fleet, retrieval hints, project context, memory, runtime, then the operator-editable tail fragments (workspace root, Clio repo awareness, project rules, operator profile) in their own order.
+
+One rule fixes that list. A section goes as late as its volatility, and anything that reads a clock, a probe, or a mutable store goes after everything that does not. Every backend Clio targets caches by exact prefix and re-prefills from the earliest changed byte, so a section that can change between two turns must not sit ahead of sections that cannot. The runtime block is last of the compiled sections because its `Context window: N` moves when the backend reloads a model or a co-residency clamp lands; memory sits just ahead of it because an approved memory record rewrites that section mid-session; project rules are dead last because path-scoped rules join the prompt when a matching file enters working context.
+
+`Context window: N` is the window the backend will actually serve. A recorded loaded window outranks a probe, which reports a figure the target advertises without saying it is what is open, so a resumed session states the window its ledger measured rather than a re-probed server-wide number. Each prompt-manifest record carries that window and the layer that answered it (`contextWindow`, `contextWindowSource`) alongside a `version` for the prompt layout itself, so a recompile whose only cause was the window moving is explained by the record rather than inferred.
+
+`PROMPT_MANIFEST_VERSION` (`src/domains/session/prompt-manifest.ts`) is `2` as of this release, and the reordering above is what moved it. The field is additive: a record written by 0.3.8 carries no `version` and reads back as version 1, so a `prompt-manifest.jsonl` from an older session still parses. The rule for the field is that it tracks the layout rather than the inputs. Bump it when the compiled text moves for a reason other than a changed fragment, a changed tool surface, or a changed setting, so that a resumed session has the version in hand to explain the single `promptRecompiled` entry its first compile writes.
+
+### What not to add to the prefix
+
+Two additions look free and are not.
+
+The first is a terseness rule. It is tempting to cap the prose a model emits between tool calls, because that text is generated tokens on every hop of a long turn. Anthropic measured that exact change on Claude Code and reported a 3 percent quality regression, so a word-count or verbosity limit on inter-tool text is a bad trade: the tokens it saves are the cheapest ones in the turn, and the model's own narration of what it is about to do is load-bearing for what it then does. Bound tool results instead, where a single `grep` can cost thousands of tokens and the envelope caps already do the work.
+
+The second is anything that varies with the wall clock or the working tree. No timestamp, no `git status`, no branch name, no session id, and no run id belongs anywhere in the compiled prefix. Every backend Clio targets caches by exact prefix and re-prefills from the earliest changed byte, so one such field turns the whole prompt into a cache miss on every turn for no information the model could not have asked a tool for. On the sprint's measurement server that is a whole 2,778-token prompt re-prefilled at 2.6 s where the same change behind the stable sections cost 516 tokens and 0.72 s. Volatile facts belong in the user message, in a tool result, or in the runtime block, which is last for this reason.
+
 The disk fragments under `src/domains/prompts/fragments/` are layered by who reads them. `identity.clio` and `operating.contract` are constitutional: they render for every reader, name no tool, and state what is always true about Clio and her harness. `operating.delegation` (fleet coordination, receipts, spot-checks, shared `[worker result]` notes) renders only when `dispatch` is on the session's tool surface, and `operating.skills` (skill-shaped tasks, `/skill <name>` suggestions) only when `context` is; a fragment that teaches a tool is absent when the tool is, the same rule the Fleet block follows. `identity.docs-routing`, the directive to call `context(scope="docs")` before answering a question about Clio herself, follows the `context` gate too, while `identity.self-awareness` (installed paths, code outranks docs, configuration locations) names no tool and is unconditional. `operating.worker` (the assigned-task contract) renders only for dispatched workers, which never see the coordinator fragments. `safety.<level>` states what runs, what is approval-required, and what is blocked at the effective autonomy, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name, so the same body is true on every surface; the session and every worker read that one body, and what "approval-required" resolves to is the only role text (one operator confirmation for the session, the worker's `onPermission` routing for a worker).
 
 Prompt extensions can add dynamic fragments for project rules, the operator profile, and Clio source-tree awareness. Pending skill requests and middleware reminders are visible text in the user message, not hidden prompt machinery.
@@ -21,7 +39,9 @@ Prompt extensions can add dynamic fragments for project rules, the operator prof
 
 Prompt templates expand into the operator's user message before submission. They do not alter the compiled system prompt or bypass the trust check on project-scope compatibility roots. The prompt-root locations, frontmatter fields, and trust rules are documented in [extensions-and-sharing.md](extensions-and-sharing.md#prompt-templates).
 
-Arguments after `/template-name` use shell-style command argument parsing. Single or double quotes keep spaces inside one argument. The template body may use `$1` through `$9` for positional arguments, `$@`, and `$ARGUMENTS` for every parsed argument joined with spaces, as well as argument slices. A positional placeholder with no matching argument expands to an empty string. Template names that collide with built-in slash commands fail closed with a diagnostic and are excluded from `/prompts`.
+The first whitespace character after `/template-name` is the command delimiter; CRLF counts as one delimiter. Leading whitespace before the slash is also command framing. Every byte after that delimiter is the argument payload, including leading or trailing whitespace, repeated spaces, tabs, quotes, and line breaks.
+
+The template body may use `$ARGUMENTS` to insert that raw payload byte-for-byte. Raw insertion is not recursively substituted, so placeholder-like text such as `$1` remains data. `$1` through `$9`, `$@`, `${@:N}`, and `${@:N:L}` retain shell-style parsing: single or double quotes group spaces within one argument, `$@` joins all parsed arguments with single spaces, `${@:N}` selects parsed arguments from one-based position `N`, and `${@:N:L}` selects `L` arguments beginning there. A positional placeholder with no matching argument expands to an empty string. Template names that collide with built-in slash commands fail closed with a diagnostic and are excluded from `/prompts`.
 
 ## Directory-scoped handbook overrides
 

package/docs/provider-adapter-cookbook.md

@@ -1,7 +1,7 @@
 # Provider Adapter Cookbook
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.9).
 
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 

package/docs/release-cut-checklist.md

@@ -1,6 +1,6 @@
-# v0.3.7 Release-Cut Checklist
+# v0.3.8 Release-Cut Checklist
 
-The ordered steps that turn the prepared `v0.3.7` branch into a published
+The ordered steps that turn the prepared `v0.3.8` branch into a published
 release. Everything above the line marked **AUTHORIZATION BOUNDARY** is
 repeatable and reversible and is run locally before the cut. Everything below
 it is external or irreversible and needs an explicit decision from the
@@ -11,16 +11,17 @@ state of every step.
 
 | Item | State |
 | --- | --- |
-| Branch | `v0.3.7`, pushed to `origin` under the explicit refspec `refs/heads/v0.3.7`; sixteen feature and docs commits, the version-bump commit, and the fix commits the interactive release testing produced, ahead of `main` |
-| `package.json` version | `0.3.7`; the top `CHANGELOG.md` heading is `## 0.3.7 - 2026-08-24` |
-| `main` | `9b54219d`, the v0.3.6 release SHA; it is an ancestor of `v0.3.7` and moves only at Part 4 |
-| `origin/main` | `9b54219d`, matching `main` |
-| Tags | `v0.3.6` exists on `9b54219d`; none for 0.3.7, local or remote |
-| GitHub Release | `v0.3.6` published 2026-08-24; none for 0.3.7 |
-| npm registry | `@iowarp/clio-coder@0.3.7` absent; `latest` is `0.3.6` |
-| npm history | Published versions 0.3.0 through 0.3.4 and 0.3.6. Version 0.3.5 was published and withdrawn and can never be reused. |
-| Milestone | `v0.3.7` holds the thirteen issues this branch closes (#155, #204, #206 through #216); the ten off-map items (#156, #158 through #164, #198, #199) moved to `v0.3.8` on 2026-08-24 |
-| Commit provenance identity | Post-release maintainer follow-up, not a gate: verifying `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and GitLab identities (such as `clio-coder-bot` or `iowarp-clio`, with `assets/clio-coder-avatar-512.png` as the avatar) only changes how those platforms render the trailers. |
+| Branch | After the release-cut evidence commit, `v0.3.8` is 30 commits ahead of `main`: the 29-commit candidate through `9b7b80cc` plus the final documentation and verification-evidence commit. The candidate includes the original implementation, the four release-test fixes (#233, #235, #238, #239), the WTF-P extension-resource merge, the `$ARGUMENTS` fidelity fix (#240), and the extension-agent resolution fix (#241). `origin/v0.3.8` remains at `af6546b2`, 17 commits behind the final local tip. |
+| `package.json` version | `0.3.8`; `package-lock.json` agrees at both version fields; the top changelog heading is `## 0.3.8 - 2026-08-29`. |
+| `main` | `598be99c`, the v0.3.7 release SHA; it is an ancestor of the final `v0.3.8` candidate and moves only at Part 4. |
+| `origin/main` | `598be99c`, matching local `main` and still an ancestor of the final candidate. |
+| Tags | `v0.3.7` exists on `598be99c`; no `v0.3.8` tag exists locally or remotely. The redundant `wtfp-safety` tag was deleted. The eight local `tmp-032-*` recovery tags remain and must never be pushed. |
+| GitHub Release | `v0.3.7` is published; no GitHub Release exists for `v0.3.8`. |
+| npm registry | `@iowarp/clio-coder@0.3.8` is absent; `latest` is `0.3.7`; the 0.3.8 dist-tag is undecided. |
+| npm history | Published versions are 0.3.0 through 0.3.4, 0.3.6, and 0.3.7. Version 0.3.5 was published and withdrawn and can never be reused. |
+| Milestone | `v0.3.8` has six open issues, all fixed on the branch: #233, #235, #238, #239, #240, and #241. They close from their `Fixes` trailers when the final candidate reaches `main`. |
+| Interactive release test | The original three-round report is `docs/release-notes/v0.3.8-release-test.md` (57 PASS / 8 FAIL / 3 PARTIAL / 6 OBSERVATION / 2 NOT RUN). The continuation is `docs/release-notes/v0.3.8-verification.md` (44 PASS / 6 non-blocking FAIL / 7 OBSERVATION / 1 NOT RUN), which closes the blocker, verifies the three later merges, and carries the final `CUT` verdict. |
+| Commit provenance identity | Still a post-release maintainer follow-up rather than a release gate; unchanged from 0.3.7. |
 
 ---
 
@@ -38,8 +39,14 @@ Run against the exact final candidate with `NO_COLOR` unset and
 7. `npm run ci` (runs 1 through 6)
 8. `npm run ci:release` (7 plus `scripts/check-release.mjs`: dist shebang
    integrity, version coherence between `package.json` and the top
-   `CHANGELOG.md` heading, the forbidden-file list, the required runtime
-   resources, and the tarball and unpacked size budgets)
+   `CHANGELOG.md` heading, the deterministic 26-scenario behavioral machinery
+   corpus against its checked baseline, the forbidden-file list, the required
+   runtime resources, and the tarball and unpacked size budgets). A baseline
+   mismatch prints reviewable evidence and names prompt- or recipe-affected
+   corpus results. For an intentional change, inspect that diff, run
+   `node benchmarks/eval/check-behavioral-release.mjs --update` (with `TMPDIR` on a disk-backed path if `/tmp` is a small tmpfs),
+   review `benchmarks/eval/behavioral-machinery-baseline.json`, and commit it
+   with the change.
 9. Optional: step 8 again under Node 24. Hosted CI gates on Node 22 alone,
    the `engines` floor; the weekly `flake-hunt` workflow carries Node 24.
    Repeat locally only when the cut touches runtime-sensitive code.
@@ -57,7 +64,17 @@ Run against the exact final candidate with `NO_COLOR` unset and
 12. Install that tarball into a clean temporary prefix with an empty
     `CLIO_CODER_HOME` and verify `--version`, `--help`, an empty-state non-TTY
     launch, `doctor`, and `uninstall --dry-run` without developer-local state.
-13. Interactive release testing, which this cut added because the release is
+13. Before interactive release testing, run the model-required public
+    behavioral corpus manually against the release target and built CLI:
+    `node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model.yaml --target mini --clio-coder-entry dist/cli/index.js`
+    and
+    `node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model-negative-control.yaml --target mini --clio-coder-entry dist/cli/index.js`.
+    Retain both Artifact v4 files as release evidence. The positive corpus must
+    report its scenario and role rows without an undeclared envelope mismatch;
+    the negative control must still record violated exploration and safety
+    labels. These model-dependent runs are manual and are never required by
+    ordinary deterministic CI. Continue with interactive release testing,
+    which this cut added because the release is
     almost entirely interactive surface: a tester agent drives the step-12
     install through real TUI sessions in a throwaway repository, one session
     per shipped feature, against local targets for the main session and a
@@ -69,35 +86,37 @@ Run against the exact final candidate with `NO_COLOR` unset and
 ## Part 2: version and notes (repeatable)
 
 14. Files carrying a version reference, to update together if the number
-    changes: `package.json` and `package-lock.json`, the `## 0.3.7 - <date>`
-    heading in `CHANGELOG.md`, the `(Version: 0.3.7)` markers in `docs/*.md`,
-    the `Blueprint (v0.3.7)` titles in `docs/html/*.html`, the `--branch`
+    changes: `package.json` and `package-lock.json`, the `## 0.3.8 - <date>`
+    heading in `CHANGELOG.md`, the `(Version: 0.3.8)` markers in `docs/*.md`,
+    the `Blueprint (v0.3.8)` titles in `docs/html/*.html`, the `--branch`
     pin in the README install block (the hygiene lint checks it), and the
     measured-at figures in `scripts/check-release.mjs` if the package size
     moved materially. For 0.3.7 the tarball measured 6.5 MB packed and
-    37.9 MB unpacked, inside the 10 MB and 50 MB ceilings set for 0.3.6.
-15. Confirm the `## 0.3.7` section of `CHANGELOG.md` describes every
+    37.9 MB unpacked; re-measure for 0.3.8, inside the 10 MB and 50 MB ceilings set for 0.3.6.
+15. Confirm the `## 0.3.8` section of `CHANGELOG.md` describes every
     user-visible behavior change under `### Added`, and every change to an
     existing behavior under `### Changed`, and carries no Workbench release
     narrative. The release workflow uses this section verbatim as the GitHub
     Release body.
 16. `docs/artifact-versions.md` lists every persisted artifact this release
-    added or re-versioned: run receipt integrity v19, fleet contract v5, the
-    fleet run record, the checkout writer lease, the out-of-turn usage ledger,
-    and the library pin file.
+    added or re-versioned. For 0.3.8 that is run receipt integrity v20, which
+    adds `pathProvenance` on dispatch intent and the resolved `pathScope`, and
+    whose entry must also record that a receipt below v20 is reported as
+    retired rather than invalid, and the durable assignment record, which now
+    carries its owner pid, process birth token, and acquisition time.
 17. Re-run `npm run ci:release` after any version edit and commit as one
-    commit on `v0.3.7`.
+    commit on `v0.3.8`.
 
 ## Part 3: present the gate
 
-18. Report to the operator before touching `main`: the exact final `v0.3.7`
+18. Report to the operator before touching `main`: the exact final `v0.3.8`
     SHA and clean status, the commits added since the handoff SHA, the gate
     commands with pass/fail totals, the package version and changelog heading,
     the tarball audit, the clean-install results, the interactive test table,
     and any deferred live check, confirmation that no tag, GitHub Release, or
     npm version exists yet, the proposed commands for Parts 4 through 6, and
     the npm dist-tag. The dist-tag is the operator's call; for 0.3.7 the
-    operator chose `latest` on 2026-08-24.
+    operator chose `latest` on 2026-08-24; 0.3.8's dist-tag is undecided.
 
 ---
 
@@ -110,35 +129,35 @@ confirming the exact SHA and the commands.
 ## Part 4: fast-forward `main`
 
 19. `git fetch origin` immediately before integrating; require `origin/main`
-    to be an ancestor of the reviewed `v0.3.7` tip and confirm no other
+    to be an ancestor of the reviewed `v0.3.8` tip and confirm no other
     worktree has `main` checked out.
-20. `git checkout main && git merge --ff-only v0.3.7`. No merge commit, no
+20. `git checkout main && git merge --ff-only v0.3.8`. No merge commit, no
     rebase, no reset. Verify `main` equals the reviewed SHA and is clean.
 21. `git fetch origin` once more; stop on any unexpected remote movement. Then
     `git push origin main`. Never `--force` or `--force-with-lease`. The push
-    closes the thirteen milestone issues through their `Fixes` trailers.
+    closes the six milestone issues through their `Fixes` trailers.
 
 ## Part 5: exact-SHA CI, tag, GitHub Release
 
-22. The `main` push triggers the `ci` workflow. It is a useful signal but not
-    a gate on tagging, because `release.yml` runs the same gate on the tagged
-    tree itself. A red run still blocks the cut; investigate it rather than
+22. The `main` push triggers the `ci` workflow. Require that exact-SHA run to
+    finish green before tagging; `release.yml` then runs the same gate again on
+    the tagged tree itself. A red run blocks the cut: investigate it rather than
     tagging around it, and never silence a flake with an unrelated change.
-23. Reconfirm that tag `v0.3.7` and the GitHub Release do not exist, then
-    `git tag -a v0.3.7 -m "Clio Coder 0.3.7"` on the green SHA and
-    `git push origin refs/tags/v0.3.7`.
+23. Reconfirm that tag `v0.3.8` and the GitHub Release do not exist, then
+    `git tag -a v0.3.8 -m "Clio Coder 0.3.8"` on the green SHA and
+    `git push origin refs/tags/v0.3.8`.
 24. The tag push triggers `.github/workflows/release.yml`, which verifies the
     tag matches `package.json`, runs `npm run ci:release` on the tagged tree,
-    extracts the `## 0.3.7` section of `CHANGELOG.md` as the release body, and
+    extracts the `## 0.3.8` section of `CHANGELOG.md` as the release body, and
     attaches the tarball. Do not create a release by hand. Verify the run's
     SHA, the notes, the attached tarball, and the URL.
 
 ## Part 6: npm publication (irreversible)
 
 25. `npm whoami` and confirm the registry and account; reconfirm
-    `@iowarp/clio-coder@0.3.7` is still absent.
+    `@iowarp/clio-coder@0.3.8` is still absent.
 26. Obtain the operator's explicit dist-tag decision. `latest` makes this the
-    default install for every user; `--tag next` keeps `0.3.6` as the default.
+    default install for every user; `--tag next` keeps `0.3.7` as the default.
 27. Run `npm publish` once. `prepublishOnly` re-runs `ci:release` as a safety
     net; it is not a substitute for Part 1.
 28. A published version cannot be replaced. `npm unpublish` is restricted and
@@ -146,13 +165,13 @@ confirming the exact SHA and the commands.
 
 ## Part 7: post-publish verification and follow-ups
 
-29. `npm view @iowarp/clio-coder@0.3.7` and the selected dist-tag.
+29. `npm view @iowarp/clio-coder@0.3.8` and the selected dist-tag.
 30. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
     rather than from a local tarball, then repeat step 12 against it, plus
     `configure` to a real target and one real turn when one is authorized.
     This is the only step that tests what users actually receive.
-31. From an installation of 0.3.6, verify `clio-coder upgrade` finds and
-    applies 0.3.7.
+31. From an installation of 0.3.7, verify `clio-coder upgrade` finds and
+    applies 0.3.8.
 32. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
     tarball evidence, and the post-publish verification in the release report.
 33. Maintainer follow-up, independent of the release: verify the commit

package/docs/safety-model.md

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.9).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 

package/docs/scientific-validation.md

@@ -1,7 +1,7 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.9).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 

package/docs/skills-marketplace.md

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.9).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
 

package/docs/tool-usage.md

@@ -1,7 +1,7 @@
 # Tool Usage Reference
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.9).
 
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 

package/docs/trace-store.md

@@ -1,7 +1,7 @@
 # Trace store contract
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.9).
 
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing

package/docs/troubleshooting.md

@@ -26,6 +26,93 @@ This guide provides concrete, actionable remediation procedures for operational
 
 ---
 
+## Reading a cold cache
+
+On a local server prefill is most of what a turn costs, so a cold prefix cache is the difference between a first token in under a second and one in fifty. This is how to find out why a turn went cold, starting from what the TUI shows.
+
+**1. Read the `/context` cache lines.** Two lines answer different questions. The prompt-cache line says what the provider reported and whether the compiled prompt shell was reused. The prefill line says what the server itself did:
+
+```text
+prefill: 34,951 uncached · 0 cached · 48,617 ms
+```
+
+Those are the server's own numbers, not Clio's estimate. `server does not report cache reads` in place of the cached figure means the backend gave no `cache_n` at all, which is LM Studio 2.29.0's OpenAI-compatible port today; on that target the verdict comes from the provider's `cached_tokens` instead and the prefill line reports only total prompt work and milliseconds.
+
+**2. Look for the expected-cold line.** When the last settled run came back `cold` and Clio had recorded a cause, `/context` names it rather than warning:
+
+```text
+last cold turn: working-set eviction (expected)
+```
+
+The eight causes and what stamps each one are in [context-engine.md](context-engine.md#cache-divergence-honesty). `background_memory` renders in prose as `last cold turn: background memory step (expected)`.
+
+**3. Confirm it in the ledger.** The reasons are durable, so a finished session answers the same question without the TUI. Open `current.jsonl` under the session directory `clio-coder paths` reports and read the run's first assistant entry:
+
+```json
+{
+  "timing": { "ttftMs": 53194, "apiMs": 56770 },
+  "promptCache": {
+    "input": 34951, "cacheRead": 0, "cacheWrite": 0,
+    "backendVerdict": "cold",
+    "expectedColdReasons": ["dispatch", "residency"],
+    "backend": {
+      "promptTokens": 34951, "cachedTokens": 0, "predictedTokens": 24,
+      "promptMs": 48617, "predictedMs": 373, "source": "llamacpp-timings"
+    }
+  }
+}
+```
+
+`expectedColdReasons` is stamped once per run, on its first persisted call, so a turn with several model calls carries it on the first one only. `clio-coder doctor` folds the latest session for you and prints the verdict counts plus the most frequent reason, and `clio-coder usage report` gives per-session uncached prefill and verdict counts across the window.
+
+**4. When there is no reason, the warning is the finding.** A cold backend with a reused prompt shell and no recorded reason is a real disagreement: Clio kept the bytes stable and the server re-prefilled anyway. `/context` leaves the warning in place for exactly that case. Four causes are worth checking in order, and none of them is a Clio bug:
+
+- **The server slept.** A llama.cpp router started with `--sleep-idle-seconds N` drops the slot's prefix cache when it sleeps, and `--cache-ram` does not reliably restore a large state. A gap longer than that setting between two turns explains a cold turn completely. Raise the flag, or accept that a session left idle pays for its first turn back.
+- **Something else used the endpoint.** A worker, a second Clio session, or another client on the same server evicts the slot. Clio stamps `dispatch`, `residency`, and `background_memory` only for work it can attribute to itself on that endpoint; a foreign process leaves no stamp. `clio-coder targets --probe` reports the endpoint's slot count, and `/fleet` settings show active slots per endpoint.
+- **The model was swapped.** A router serving one model at a time reloads on a residency change, and everything the previous model had cached is gone. This normally does stamp `residency`, but only when the mutation went through Clio.
+- **The prompt moved for a reason Clio did not classify.** Compare the run's `promptHash` and `toolSignature` in `context-snapshots.jsonl` against the previous run's. Equal hashes with a cold backend point at the server; different hashes with no `prompt_recompiled` or `tool_surface_change` stamp is worth an issue.
+
+One case is expected on hybrid architectures and looks like a bug. Qwen3.8 keeps recurrent state that llama.cpp cannot roll back to an arbitrary token, so a change anywhere inside a cached prefix re-prefills from the last context checkpoint rather than from the changed byte. A small edit to old history can therefore cost thousands of tokens of prefill with the prompt hash otherwise stable. The server's checkpoint count and its `--checkpoint-min-step` are the levers; see the `qwen3.8-27b` family's `serving` and `measuredUnder` notes in `src/domains/providers/models/local-models/clio-local-coding-targets.yaml` for the measured figures and the exact argv they were taken under.
+
+---
+
+## A TUI that stops answering the keyboard
+
+When an interactive session stops responding to typing, the question worth
+answering before anything else is which half of the input pipeline stopped: the
+stdin reader that hands bytes to the application, or the renderer that turns
+them into a frame on stdout. Clio keeps that evidence without being asked. Every
+interactive process holds a bounded in-memory ring of the last 256 input-ingress
+records and the last 256 committed frames, and writes it out when the process
+receives `SIGTERM`, which is the signal a `kill` of the stuck pane sends.
+
+The dump lands in the state directory `clio-coder paths` reports:
+
+```text
+<stateDir>/input-wedge/<ISO timestamp>-<pid>.json
+```
+
+The five newest dumps are kept and older ones are removed as new ones land.
+Read `classification` first:
+
+| `classification` | What it means |
+| :--- | :--- |
+| `input-not-committed` | Bytes reached the application and no frame carrying them ever reached stdout. The renderer is the stuck half. |
+| `no-input-recorded` | Nothing was delivered at all. If the operator was typing, the stdin reader is the stuck half. |
+| `input-committed` | Both halves were moving. Whatever the session was doing, it was not this pipeline. |
+
+`msSinceLastInputIngress` and `msSinceLastCommittedFrame` say how long each half
+had been quiet when the signal arrived, and the `inputIngress` and `frames`
+arrays carry the records themselves. Frames are kept only when they reached
+stdout, so an empty `frames` array is itself a finding.
+
+For a full session trace rather than the tail, set `CLIO_CODER_RENDER_TRACE` to
+a file path before starting the session. That writes every record, including
+provider deltas and terminal writes, as JSONL. The ring is the always-on subset
+of the same records, for the case where nobody armed the trace first.
+
+---
+
 ## Diagnostic Commands
 
 When encountering unexpected system behavior:

package/docs/tui-design.md

@@ -1,7 +1,7 @@
 # Clio TUI Design System
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.9).
 
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
 

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.9).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.