@iowarp/clio-coder 0.4.2 → 0.4.4

package/docs/guide/proactive-memory.md

@@ -121,7 +121,7 @@ malformed response, or telemetry failure is silent and never blocks a tool.
 - `context.memory.cadenceToolCalls` (default `10`): Minimum completed-tool interval between background interventions.
 - `context.memory.trajectorySteps` (default `8`): Completed tool-trajectory window analyzed during background evaluation.
 - `context.memory.maxOutputTokens` (default `2000`): Bounds the rendered memory-bank context and the ordinary policy-model completion. An always-on-thinking model receives additional reasoning headroom, at least `4,000` tokens when its model cap permits, so it can still reach the strict envelope.
-- `context.memory.timeoutMs` (default `60000`): 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 dispatched workers queue against. Raise it only after inspecting the timeout and hit-rate evidence for the selected route.
+- `context.memory.timeoutMs` (default `60000`): Wall-clock limit for one background memory-policy step, including its one permitted chat fallback attempt. 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 dispatched workers queue against. Raise it only after inspecting the timeout and hit-rate evidence for the selected route.
 
 ## Trigger semantics
 
@@ -254,38 +254,48 @@ unexamined one:
   would not have been spent. The current 60-second deadline is the source-backed
   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 `context.memory.target` names the same server as `chat.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.
+- A step whose known endpoint occupancy exhausts the resolved request capacity is
+  skipped with reason `endpoint_busy`. The same gateway URL alone does not imply
+  a single request slot or a single physical model server.
+
+### Dedicated routing, chat fallback and endpoint capacity
+
+Clio prefers the explicitly configured memory target and model. If that route is
+known unavailable (missing target/runtime, down target, absent model in a known
+catalog, or a model reported unloaded/loading), Clio selects the active chat
+route for that step. A runtime client error on the dedicated route permits one
+chat attempt within the original remaining deadline. It does not retry after a
+timeout, cancellation, session/branch switch, malformed envelope, or a model's
+explicit silence. The fallback never falls back again. Both routes unavailable
+produce a visible `client_error` outcome. An unset memory role remains rules-only;
+chat fallback does not enable model-based memory by default.
+
+A runtime notice names the selected chat fallback and its reason. Routing stays
+session-local and does not edit saved settings. Each attempted call records its
+own known usage under its actual target/model and emits its own telemetry outcome;
+failed dedicated usage is retained alongside fallback usage. The final policy
+result describes the final attempt, without merging different provider identities.
+A generation change discards late content while preserving the original usage owner.
+
+Capacity follows the same existing evidence as dispatch: explicit target
+`maxConcurrentRequests`, current discovery, a valid discovery prior, then the
+conservative one-slot default for a local-native runtime. Known occupancy includes
+this process's foreground requests, active dispatch leases and held reservation
+waves. A two-slot endpoint with one foreground request can admit memory; a full
+one-slot endpoint skips it. Known dedicated saturation does not itself initiate
+chat fallback. Larger declared capacities work without a new constant.
+
+LiteLLM is a gateway protocol, so Clio does not invent a local one-slot limit for
+its URL. Distinct model routes such as dynamo, mini and zbook can share that URL;
+the gateway owns their physical routing and backend residency. An explicit or
+observed endpoint-wide bound still applies when present. Clio's process-local
+foreground holds and observed dispatch state are not a global scheduler for every
+client using the gateway. Slot holds are released on success, failure and abort.
+
+The existing `background_memory` expected-cold stamp remains keyed by endpoint
+URL. It records a possible shared-endpoint cache disturbance, including after a
+failed request, rather than proving that a different model behind the gateway
+actually evicted the chat prefix.
 
 ## Choosing a background model
 
@@ -294,9 +304,11 @@ does not need to be clever. A small non-reasoning model is the right choice, and
 Clio always requests the memory route with thinking off. Version 2 therefore
 has no configurable memory thinking-level key.
 
-That request reaches the wire wherever the runtime carries a thinking control:
+The off request depends on the resolved runtime and model metadata:
 llama.cpp reads `chat_template_kwargs.enable_thinking`, and LM Studio reads
-`reasoning_effort`, where `none` is the off value.
+`reasoning_effort`, with the off value selected by the model family. A gateway
+needs a recognized, unanimous upstream runtime declaration; unknown metadata
+does not establish a dialect. Requesting off does not prove server compliance.
 
 A model that reasons anyway still works. Some genuinely cannot be silenced, and
 the catalog records those as always-on so the level reads `forced` rather than
@@ -306,12 +318,11 @@ blocks are discarded and only the envelope is kept, and the output budget is
 sized to let a reasoning preamble run its course first. The cost is latency,
 which the detached step absorbs.
 
-One configuration is refused rather than degraded. If the background role names
-the same target and model as the orchestrator, and that model reasons, the LLM
-memory tier stays off and memory runs on its free deterministic tier. A single
-reasoning model already driving chat, workers, and shadow agents cannot also
-deliberate over memory steps without contending with the work the operator
-actually asked for.
+The active chat model may also serve memory, including a reasoning model, when
+request capacity permits. Memory still requests thinking off and uses its own
+bounded envelope and output budget. A dedicated small model is preferred for
+latency and resource use; sharing a model is a capacity decision rather than an
+unconditional refusal.
 
 This is a mix-and-match plane, not a local-only one. The background role resolves
 through the same target machinery as every other role, so the useful shapes are:
@@ -356,30 +367,30 @@ independent of the chat target and the fleet default. A running session owns
 its routing snapshot, while the saved
 selection becomes the default for new sessions.
 
-The reference topology separates chat from memory work:
+An example gateway topology keeps the three backend routes distinct:
 
 | Role | Target | Runtime and endpoint | Model | Capacity |
 | --- | --- | --- | --- | --- |
-| Chat | `dynamo` | LM Studio at `192.168.86.143:1234` | `qwen3.8-27b-dynamo` | Reported by the LM Studio probe |
-| Background memory | `mini` | llama.cpp router at `192.168.86.141:8080` | `ornith1.5-35b-moe` | 4 parallel slots, 262,144 context tokens per slot |
+| Chat and memory fallback | `dynamo` | LiteLLM at `http://gateway:4000` | `dynamo/qwen3.8-27b` | Gateway-owned unless an explicit or observed endpoint bound is available |
+| Preferred background memory | `zbook` | Same LiteLLM gateway | `zbook/ornith-1.5-35b-a3b` | Same capacity evidence rules |
+| Alternative memory candidate | `mini` | Same LiteLLM gateway | `mini/ornith1.5-35b-moe` | Same capacity evidence rules |
 
-The corresponding saved role selection is:
+The corresponding role selection is:
 
 ```yaml
 chat:
   target: dynamo
-  model: qwen3.8-27b-dynamo
+  model: dynamo/qwen3.8-27b
 context:
   memory:
-    target: mini
-    model: ornith1.5-35b-moe
+    target: zbook
+    model: zbook/ornith-1.5-35b-a3b
 ```
 
-A smaller, efficient model is the intended shape for this role. The current
-reference uses a separate multi-slot endpoint so memory does not compete with
-the LM Studio chat stream. Capability is not the only constraint; latency and
-endpoint contention still matter, and the detached step above bounds their
-effect on the operator's turn.
+These are example configured target/model IDs, not built-in routes. Compare a
+slow dedicated model with an alternative using actual step latency, valid bank
+writes and known usage; the active chat route remains the fallback. Do not create
+aliases or change endpoint URLs just to bypass capacity accounting.
 
 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 `60000` is a bounded compromise,
@@ -489,7 +500,7 @@ clear the prior heap bank before the new session can observe it.
 
 ## Telemetry
 
-Each completed memory step appends one content-free record to:
+Each completed memory-policy attempt appends one content-free record to:
 
 ```text
 <stateDir>/memory/steps.jsonl
@@ -512,7 +523,7 @@ 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
+found the known endpoint request capacity exhausted. 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

package/docs/guide/skills-marketplace.md

@@ -5,6 +5,14 @@
 
 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.
 
+## Operator ownership of installed skills
+
+The active project `.clio-coder/skills/` tree and the resolved user `<configDir>/skills/` tree are operator-owned. Main-agent and worker tool admissions refuse writes, edits, artifacts and recognized shell mutations to either tree, including ancestor deletion and current symlink aliases. This boundary stays active at every autonomy level, even when the general default path policy is disabled. Reads and loading already installed skills retain their existing rules.
+
+Draft a proposed skill outside these active trees, for example in `draft-skills/`. The operator installs or updates it through `clio-coder skills install`, `skills update`, `skills sync`, `library add --yes`, the Skills Hub, `/skill <name>`, or an explicitly accepted marketplace offer. Even `full-auto` must wait for that offer's bound operator answer; a task match alone no longer installs a skill. Model shell calls to recognizable Clio skill installation, update and sync commands are refused. Confirmed `library add --yes` commands are also reserved for operators, including additions of other resource kinds that may install skill dependencies. An unconfirmed `library add` only prints a plan and remains available, as do inventory, search, inspection and validation commands.
+
+This is a tool-admission boundary, not an operating-system sandbox. Shell inspection covers literal paths and recognized command forms, respecting comments, quoted words and redirection operands when identifying Clio commands. Quoted search patterns remain read-only, and literal operator filenames do not hide later mutation operands. It cannot prove the effects of arbitrary scripts, dynamically constructed paths, aliases, or concurrent filesystem changes. Keep shell execution supervised when stronger confinement is required.
+
 ## Where marketplace rows come from
 
 There is one source, `discoverMarketplaceSkills()` in `src/domains/resources/skills/marketplace.ts`, and it reads two kinds of real local data:
@@ -62,6 +70,16 @@ creation. Extension resource roots and share archives are documented in
 [extensions-and-sharing.md](extensions-and-sharing.md); this page owns the TUI
 Hub and marketplace behavior.
 
+## Remote entries and overlays
+
+Some skills are worth carrying in the catalog without vendoring their content. `skills/remote.yaml` lists them: each entry names a skill, its category, a `sourceUrl` that must be a GitHub tree URL at a pinned tag, an `overlay` package inside the catalog, and an optional `exclude` list of upstream top-level members. `npm run skills:pin` publishes such an entry into `skills/skill-marketplace.json` with `origin: "remote"`, the upstream URL as its `sourceUrl`, and the `overlay` and `exclude` fields attached. The overlay's `SKILL.md` is pinned in `skills/registry.yaml` like every other catalog skill, so `npm run skills:check` fails when it drifts.
+
+`archify` is the worked example. Its entry points at `https://github.com/tt-a1i/archify/tree/v2.16.0/archify`, overlays `skills/planning/archify`, and excludes `test` and `package-lock.json`. Running `clio-coder skills install archify --project` clones that tag, drops the excluded members, copies the overlay over the clone so Clio's wrapper `SKILL.md` replaces the upstream one, validates the shaped tree, and swaps it into `.clio-coder/skills/archify/` with the usual provenance stamps. The renderer, its schemas, and its brand-mark notices come from upstream at install time and never enter the npm tarball. The wrapper omits upstream's update-awareness step on purpose: that step performs a network request during a chat turn, and no Clio chat turn depends on the network.
+
+Discovery treats the overlay folder as part of the remote entry rather than as a skill of its own, so a bare-name install never lands the wrapper without the renderer it wraps. `clio-coder skills update` recovers the same overlay and exclude list from the marketplace, so an update refetches the pinned upstream and re-applies the wrapper instead of replacing it.
+
+Two operational notes. A copy dropped into a project-scope `.claude/skills/archify` is a compat import and stays untrusted until `integrations.projectResources.trustProjectImports` is on; install through Clio to get a trusted, provenance-stamped copy. And since the skill's authoring loop is several `bash` calls (validate, deliver, verify), `auto-edit` is the sensible permission posture for a mapping session; full manual approval works but prompts on every command.
+
 ## Publishing a skill
 
 Add a directory under `skills/<category>/<name>/` (or `skills/<name>/`) in the repo containing a `SKILL.md` with `name` and `description` frontmatter. The directory name must match `[A-Za-z0-9][A-Za-z0-9._-]*`. Run `npm run skills:pin` to republish `skills/skill-marketplace.json`, which is the index consumers point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at or copy to `<configDir>/skill-marketplace.json`. Scientific and niche coding domains are the marketplace's focus; see the existing `skills/` tree for the house format.

package/docs/guide/tool-usage.md

@@ -311,7 +311,7 @@ Arguments:
 Projects may commit a versioned executable catalog at `.clio-coder/verifiers.yaml`:
 
 ```yaml
-version: 1
+version: 2
 checks:
   - id: rust-workspace
     description: Run the Rust workspace tests
@@ -319,9 +319,29 @@ checks:
     cwd: .
     timeoutMs: 600000
     tags: [rust, test]
+  - id: grid-metadata
+    description: Compare the regional grid statistics against the reference
+    kind: numeric-compare
+    command: [python, tools/grid_stats.py, out/region_west.nc]
+    reference: tests/reference/region_west.json
+    tolerance: { relative: 1.0e-6, ulp: 4 }
+    cwd: .
+    timeoutMs: 120000
+    tags: [scientific, netcdf]
+  - id: solver-time
+    description: Keep the solver inside its wall-time budget
+    kind: perf-budget
+    command: [python, tools/solve.py, --small]
+    baseline: .clio-coder/baselines/solver-time.json
+    tolerance: { relative: 0.25 }
+    cwd: .
+    timeoutMs: 600000
+    tags: [scientific, performance]
 ```
 
-Version 1 is strict. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
+Every check has a `kind`, absent or `command` by default. A version 1 file still loads and every check there is `kind: command`; the kind fields require `version: 2`. `kind: command` reads the exit code. `kind: numeric-compare` runs the command, parses its stdout as a JSON object of `string -> number | number[]`, and judges it against `reference` (a repository-relative JSON file of the same shape) under `tolerance`, which names at least one of `relative`, `absolute`, or `ulp`; a value passes only when every named tolerance holds, a key missing on either side fails with the key named, arrays compare elementwise and fail on length mismatch, and `NaN` or infinity fails. `kind: perf-budget` runs the command and judges the wall time the harness measured against either `budget: {wallTimeMs, tolerance?: {relative}}` or `baseline`, a repository-relative JSON `{wallTimeMs}` that `clio-coder verifiers baseline <id>` records from one clean run, with an optional `tolerance: {relative}` of headroom over it. Exactly one of `budget` and `baseline` is present. A command that exits non-zero, times out, or is aborted fails before any judgement. Both kinds record a structured `report` on the `verify` result details and on the host-verification check of a dispatch receipt (per-key worst deviation and the failed tolerance, or measured time, effective budget, and ratio); a failing judgement is a check failure, not a new evidence category.
+
+Version 2 keeps version 1's strictness. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
 
 Provider IDs share one namespace. If a catalog ID collides with a discovered package script, listing and execution fail and identify both source files. Catalog parsing also fails closed before any package or project check runs.
 
@@ -348,8 +368,11 @@ clio-coder verifiers author
 clio-coder verifiers author --exclude cmake-build-debug --rename go-test=go-suite
 clio-coder verifiers author --dry-run go-suite --yes
 clio-coder verifiers validate
+clio-coder verifiers baseline solver-time
 ```
 
+`author` also lists one incomplete `numeric-compare` check for every validation-contract artifact that declares `numerical_tolerances`, with the reference and tolerance filled in and the exact `verifiers add` line to complete; the command is the operator's to supply, so the proposal never enters the catalog on its own. `baseline <id>` runs a `perf-budget` check once and writes its wall time to the check's `baseline` path; a failing or timed-out command records nothing.
+
 `validate` reads the committed file with the same parser used by `verify()`. `dry-run <id>` is an explicit request to execute one admitted check through the production `verify` path. `author --dry-run <id> --yes` writes only after confirmation and starts the selected dry run only after the write is accepted by production discovery.
 
 Later changes use the same preview and confirmation boundary. `edit` preserves the ID unless `rename` is requested. Renames and additions reject collisions with catalog IDs and active package-script IDs. Removals state that the deleted command will no longer be executable through catalog authority. Generated IDs are stable for a stable ordered signal set; a collision receives the first available deterministic `-2`, `-3`, and later suffix.
@@ -362,7 +385,7 @@ clio-coder verifiers rename validate-grid validate-regional-grid --yes
 clio-coder verifiers remove validate-regional-grid --yes
 ```
 
-The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority.
+The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority. `--kind numeric-compare` takes `--reference <path>` and `--tolerance '<json>'`; `--kind perf-budget` takes either `--budget-ms <n>` with optional `--budget-relative <r>` or `--baseline <path>` with optional `--tolerance '{"relative": r}'`. `edit` accepts the same options to change a check's kind.
 
 `verify(check="frontend", path=<file>)` validates an HTML, CSS, or JavaScript artifact without shell access. The path must stay inside the workspace root and end in `.html`, `.htm`, `.css`, `.js`, `.mjs`, or `.cjs`. Checks per type: HTML tag balance (comment-aware, HTML5 optional end tags honored), inline and referenced script syntax (classic scripts parsed in-process, modules via `node --check`), inline and linked CSS brace/string/comment balance, local script and stylesheet references resolved and existence-checked (external and root-relative references are skipped), and an optional headless browser load. `browser="auto"` warns when no chromium/chrome/edge executable is on PATH, `"required"` fails, `"off"` skips. Each check reports pass, warn, fail, or skip; any fail makes the whole result an error. `details = {action: "verify", check: "frontend", path, browserMode, status, checks}`.
 
@@ -627,6 +650,58 @@ panes(action="open", preset="logs")
 panes(action="close", target="all")
 ```
 
+## evidence: inspect canonical evidence and trust status
+
+Reads evidence bundles as JSON. Source: `src/tools/evidence.ts`. Read class; sequential, because `run` mode may materialize a bundle under Clio's data directory. It shares the inventory and trust projections behind `clio-coder evidence inventory` and `clio-coder evidence inspect`, so the model and the operator read the same record.
+
+Arguments:
+
+- `mode` (required). `list`, `inspect`, or `run`.
+- `id` (required for `inspect`). An evidence bundle id.
+- `runId` (required for `run`). A dispatch run id; the bundle is built first when none exists.
+
+`list` returns the bounded newest-first inventory: provenance, tags, totals, and a worst-run trust verdict per bundle. `inspect` returns the bundle overview, the per-run trust axes and verdict, the gate decisions, and the findings. `run` resolves `run-<runId>` and builds the bundle when it is absent; a run with no ledger row is reported absent with `artifactAbsent: true` in the details. Results are capped at 16KB, and a truncated result stays valid JSON with a `preview`. Provenance requires this tool and Verifier may use it.
+
+```text
+evidence(mode="list")
+evidence(mode="inspect", id="run-r-42")
+evidence(mode="run", runId="r-42")
+```
+
+## limitation: record what a turn could not verify
+
+Records a typed limitation receipt for the finish contract. Source: `src/tools/limitation.ts`. Read class; parallel. The tool is pure: it touches no filesystem and runs no shell, so the successful receipt in the session ledger is its whole effect.
+
+Arguments:
+
+- `scope` (required). What could not be verified, in one sentence.
+- `reason` (required). `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`.
+- `paths` (optional). Repository-relative paths left unverified.
+
+Call it once, before the final reply, when files changed and validation could not run. The finish contract accepts a successful `limitation` receipt inside the same window as the mutation scan in place of validation evidence. A rejected call (empty scope, unknown reason) leaves no receipt and does not count, and the assistant's prose never does. The six mutating recipes carry the tool and the operating contract tells the model to call it; see [the finish gate](../architecture/safety-model.md#the-finish-gate-and-re-prompt-behavior).
+
+```text
+limitation(scope="CUDA kernels changed but no GPU is available here", reason="environment", paths=["src/kernels/solve.cu"])
+```
+
+## decide: record a design decision
+
+Appends the model's own design choice to the session decision board beside operator `ask_user` answers. Source: `src/tools/decide.ts`. Read class; sequential, so two decisions in one batch cannot race the supersede lookup. The call succeeds only in a session with a decision board; a worker's call is refused.
+
+Arguments:
+
+- `key` (required). Stable kebab-case name, at most 64 bytes.
+- `value` (required). The option chosen, at most 512 bytes.
+- `alternatives` (required). One to six rejected options, at most 256 bytes each.
+- `rationale` (required). Why the choice won, at most 1024 bytes.
+- `label` (optional). Short title, at most 128 bytes.
+
+The call appends one `decisionLedger` entry with `origin: "agent"` and returns the decision ref `<interviewId>/<key>`. A repeat key supersedes the earlier agent decision with the new rationale as its correction; an operator decision with the same key is never overwritten and the call fails. Dispatch seals every active ref onto the run request, envelope, and receipt, and Clio-controlled commits carry one `Clio-Decision:` trailer per ref; see [commit provenance](../process/git-commit-provenance.md).
+
+```text
+decide(key="cache-key-shape", value="capability tuple", alternatives=["node id"], rationale="matches the existing buckets and survives fleet changes", label="Cache key")
+```
+
 ## ask_user: host-owned operator interviews
 
 Runs a host-owned interactive interview or single-question prompt with the operator, recording decisions and/or free-form answers. Source: `src/tools/ask-user.ts`. Read class; sequential.

package/docs/history/config-knobs-audit.md

@@ -34,7 +34,7 @@ Every runtime-tunable value needs both halves; the pair is one knob, not two. Th
 | `CLIO_CODER_MAX_TOOL_CALLS` | 50 | `src/engine/loop-guard.ts` → `src/engine/worker-runtime.ts` | Worker lifetime tool-call cap for a dispatched run. Different axis than the orchestrator budget despite the near-identical name. |
 | `CLIO_CODER_MAX_DISPATCH_RUNS` | 1000 | `src/domains/dispatch/state.ts` | Dispatch run-ledger retention cap. |
 | `CLIO_CODER_MAX_CONTEXT_TOKENS` | unset | `src/domains/providers/runtime-resolution.ts` | Context-window override for local runtimes. Also set internally by `clio-coder run --max-context-tokens` (see §6). |
-| `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run --kv-cache-mode` path. |
+| `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run` path. |
 | `CLIO_CODER_SAMPLING_OVERRIDES` | unset | `src/engine/apis/sampling-overrides.ts` | JSON sampling-parameter override. Set internally by print-mode sampling flags. |
 | `CLIO_CODER_READ_MAX_BYTES` | 51200 (50 KB) | `src/tools/read.ts` | Per-call byte cap for the read tool. |
 | `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES` | 196608 (192 KB) | `src/tools/observation.ts` | Shared per-turn byte pool across all observation tools. |
@@ -93,7 +93,7 @@ All default off; all enabled with `1`.
 
 ## 6. CLI flags that bridge through env vars (Pre-consolidated State)
 
-`clio-coder run --max-context-tokens` and `--kv-cache-mode` (`src/cli/run.ts:143-234`) and the print-mode sampling flags (`src/cli/modes/print.ts:306-333`) do not plumb their values through function arguments. They mutate `process.env` (`CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, `CLIO_CODER_SAMPLING_OVERRIDES`), run the command, then restore the previous value in a `finally`. The env var is the transport between the CLI layer and deep engine code.
+`clio-coder run --max-context-tokens` (`src/cli/run.ts:143-234`) and the print-mode sampling flags (`src/cli/modes/print.ts:306-333`) do not plumb their values through function arguments. They mutate `process.env` (`CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, `CLIO_CODER_SAMPLING_OVERRIDES`), run the command, then restore the previous value in a `finally`. The env var is the transport between the CLI layer and deep engine code.
 
 ## 7. Script- and benchmark-only vars (Pre-consolidated State)
 

package/docs/process/development-pipeline.md

@@ -20,12 +20,13 @@ under pressure; git mechanics alone never justify a stage.
 | --- | --- | --- |
 | 1. File | [`file-ticket`](../../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
 | 2. Fix | [`fix-issue`](../../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
-| 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`), a gated push, and an open PR; merge is a human decision |
+| 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
 
-Releases follow [release-cut-checklist.md](../history/release-cut-checklist.md) as a
+Releases follow [release-cut-checklist.md](release-cut-checklist.md) as a
 human-gated checklist, not a skill. Worktrees
 ([`worktree-create`](../../skills/git/worktree-create/),
 [`worktree-merge`](../../skills/git/worktree-merge/)),
+[`branch-closeout`](../../skills/git/branch-closeout/),
 [`resolve-merge-conflicts`](../../skills/git/resolve-merge-conflicts/), and
 [`tdd`](../../skills/coding/tdd/) are à-la-carte tools reached for when the
 situation calls for them, not stages every change passes through. An RCA
@@ -34,6 +35,38 @@ hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
 bypasses stage 1 and uses [`backlog`](../../skills/planning/backlog/)
 instead; everything downstream is identical.
 
+## Closeout
+
+A merged PR is not operationally finished until its local scaffolding is
+closed. The reusable [`branch-closeout`](../../skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
+
+1. Fetch and prune, confirm the PR's merged state, and identify the resulting
+   commit on `origin/main`. Direct ancestry proves an ordinary merge; a squash
+   or cherry-pick needs the PR-to-result evidence because commit identity and
+   patch identity can both change during integration.
+2. Inspect every associated worktree for tracked changes, untracked files, and
+   ignored state that carries evidence rather than rebuildable output. Remove
+   it through `git worktree remove`; forcing removal requires explicit approval
+   to discard what remains.
+3. Delete the local source and integration branches. For a contributor PR,
+   delete the merged branch from the contributor's fork. The canonical
+   repository never hosts topic, integration, or release-candidate branches.
+4. Turn unfinished experimental findings into an issue with evidence and a
+   next decision. Do not use indefinite `work/`, `wip/`, `keep/`, or temporary
+   tags as a substitute for backlog state.
+5. Report the remaining worktrees, local branches, stashes, local-only tags,
+   and canonical remote heads. The expected canonical head set is exactly
+   `refs/heads/main`; every survivor needs an owner and purpose.
+
+Maintainer release candidates are local-only and use a compact branch name
+that cannot collide with their tag: branch `v043`, tag `v0.4.3`. Gate the exact
+candidate, require fetched `origin/main` to be its ancestor, fast-forward local
+`main`, fetch again, and push only `refs/heads/main:refs/heads/main` with
+explicit authorization. After CI passes, push only the fully qualified
+annotated tag. Once the tag's peeled commit equals the reviewed commit on
+`main` and the release succeeds, delete the local candidate branch. Published
+dotted release tags are immutable history and are never cleanup targets.
+
 ## Inheriting a Pi release
 
 Pi dependency upgrades use a fixed five-step review so that upstream fixes
@@ -73,6 +106,11 @@ There is no committed weighted-shard or special serial-lane runner. Keep timing
 claims within the focused contract that owns them, and use the full `npm run ci`
 gate before handoff.
 
+The release smoke script `scripts/smoke-real-home.sh` (invoked via
+`npm run smoke:real-home`) tests booting the built CLI binary against a copy of
+the operator settings in a scratch home. An optional `--strict` flag makes doctor
+exit 1 fail the smoke run on failing rows instead of tolerating fleet state.
+
 ## Issue conventions
 
 - **Title**: conventional tag plus imperative summary (`fix: memory overlay

package/docs/process/eval-runner.md

@@ -139,7 +139,37 @@ Metrics collected during runs can be validated automatically using the `verify.a
 * `eq` (equal)
 * `neq` (not equal)
 
-Metrics that can be validated include `tokens.input`, `tokens.output`, `tokens.total`, `latency.wallMs`, `tools.totalCalls`, `tools.failed`, `tools.blocked`, `verifier.exitCode`, and `result.pass`.
+Metrics that can be validated include `tokens.input`, `tokens.output`, `tokens.total`, `latency.wallMs`, `tools.totalCalls`, `tools.failed`, `tools.blocked`, `verifier.exitCode`, `result.pass`, and the `provider.*` metrics below. Each `verify.assertions` condition must hold; an unavailable metric fails closed.
+
+### Optional Provider-Health Gates
+
+A task that recovers from a provider error can still pass its task checks by default. Provider health is a separate, opt-in requirement. To require observed provider events and no observed terminal errors, add these assertions to the task:
+
+```yaml
+verify:
+  assertions:
+    - metric: "provider.measured"
+      op: "eq"
+      value: true
+    - metric: "provider.stopReason.error"
+      op: "eq"
+      value: 0
+```
+
+Suite-level `thresholds.fail` uses the opposite condition: a matching condition is a failure. The corresponding hard gate checks each run as follows:
+
+```yaml
+thresholds:
+  fail:
+    - metric: "provider.measured"
+      op: "eq"
+      value: false
+    - metric: "provider.stopReason.error"
+      op: "gt"
+      value: 0
+```
+
+Unavailable metrics also fail closed in a hard threshold. `thresholds.informational` records findings without changing exit status. These examples reject an observed error followed by a successful recovery while leaving the default ungated task-pass policy unchanged. To reject any observed retry start or assistant abort as well, add conditions on `provider.retryStarted` or `provider.stopReason.aborted` with the same assertion-versus-failure polarity.
 
 ---
 
@@ -175,14 +205,44 @@ Under the hood, these are parsed and wrapped into a Suite v2 adapter with:
 
 Clio maintains two distinct token accounting streams with different provenances. These accounts are never merged, reconciled, or treated as interchangeable:
 
-1. **`tokens.*` (Wire Streaming)**: Folded live off stdout from assistant `message_end` events watched by `token-stream.ts` / `createStreamInvariantFold`. This represents usage reported by the provider for assistant messages watched over the wire. On surfaces without stdout streaming (such as `clio-coder fleet run --json`), `tokens.measured` is `false`.
+1. **`tokens.*` (Wire Streaming)**: Folded live off stdout from assistant `message_end` events. These totals include all known usage on errored calls as well as successful calls; recovery never subtracts earlier spend. Only finite, nonnegative usage facts are admitted. On surfaces without the relevant stdout events (such as `clio-coder fleet run --json`), `tokens.measured` is `false`.
 2. **`receiptUsage.*` (Journal Receipts)**: Summed from an evaluation item's run journal. Every attempt writes a receipt carrying token counts and USD cost authenticated against its own ledger envelope.
 
 ### Fail-Closed Reporting
 Both accounting streams report unmeasured state with no counts at all rather than a numeric zero. Reporting zero for an unmeasured run would falsely claim the run cost nothing. On an unmeasured run, `tokens.total` resolves to `null` and fails closed on metric threshold comparisons.
 
+An errored call must carry at least one positive reported token, reasoning, or cost fact before its usage is considered observed. Reasoning-only or cost-only observations do not establish ordinary token totals. A stream containing only errored calls with missing or synthetic all-zero usage remains `tokens.measured: false`. The current event shape cannot distinguish synthetic all-zero failures from genuinely reported zero usage, so it cannot establish measured zero spending in either case. Partial positive usage remains included as known spend. On failed calls, adapters can also initialize individual absent fields to zero; those zeros remain unattributed and make coverage incomplete. The existing inclusive numeric fields are known subtotals, so their zeros do not prove complete zero spending when failed usage is incomplete.
+
+### Provider Observations and Failed-Call Share
+
+The `provider.*` metrics describe events observed on live stdout, folded before diagnostic output is truncated. Native runs and multi-command external runners retain these observations from their executed commands. They do not enumerate SDK-internal retries or network attempts that were never emitted. Filtered or opaque output can leave provider health unobserved even when the process exits successfully or a receipt reports task success.
+
+| Metric | Meaning |
+| --- | --- |
+| `provider.measured` | Whether an assistant terminal reason or a counted retry phase was observed. With no such observations this is `false`, and provider counters are absent. It does not certify complete provider coverage. |
+| `provider.stopReason.stop`, `provider.stopReason.toolUse`, `provider.stopReason.length` | Counts of these terminal reasons on assistant `message_end` events. |
+| `provider.stopReason.error`, `provider.stopReason.aborted`, `provider.stopReason.other` | Separate counts of errored, aborted, and other observed terminal reasons. An unrecognized terminal reason goes into `other`. Partial updates and repeated messages in `turn_end` or `agent_end` do not add counts. |
+| `provider.retryScheduled` | Observed `scheduled` phases: planned retries, including ones cancelled before execution. |
+| `provider.retryStarted` | Observed `retrying` phases: retry execution starts. Repeated `waiting` countdown frames do not count as attempts. |
+| `provider.retryCancelled`, `provider.retryExhausted`, `provider.retryRecovered` | Counts of the corresponding observed phases. They describe retry-chain outcomes and do not fabricate additional assistant calls. Attempt numbers can restart for each chain. |
+| `provider.errorUsageObservedCalls` | Errored calls with at least one positive reported token, reasoning, or cost fact. |
+| `provider.errorUsageUnobservedCalls` | Errored calls with no positive reported token, reasoning, or cost fact, including absent or all-zero usage. |
+| `provider.errorUsageIncompleteCalls` | Errored calls with unobserved usage, incomplete token fields, or ambiguous normalized zero fields. This can overlap `errorUsageObservedCalls` when only part of the usage is known. |
+| `provider.errorCostUnobservedCalls` | Errored calls without a positive cost fact. Zero or absent cost does not prove that an error was free, including when some token usage is known. |
+| `provider.errorTokens.input`, `provider.errorTokens.output`, `provider.errorTokens.total`, `provider.errorTokens.cacheRead`, `provider.errorTokens.cacheWrite` | Known positive token subtotals for errored calls. Absent or ambiguous zero fields remain unattributed; when total usage is absent, a total can still be summed from known token fields and remains incomplete. |
+| `provider.errorCostUsd` | Known positive cost subtotal from errored calls' stream usage objects. Cost can come from adapter pricing; it is not independently certified provider billing. |
+| `provider.errorReasoningTokens`, `provider.errorReasoningUnobservedCalls` | Known failed-call reasoning subtotal and calls without attributable reported reasoning. Reasoning can overlap output, so it is never added to ordinary token totals. |
+
+The failed-call share covers `stopReason: error`; aborted calls remain separately labeled. Failed-share amounts and usage-coverage counters appear only after an errored terminal message is observed. These share metrics supplement the inclusive `tokens.*` totals without changing the summary token shape, receipt schema, or verdict schema. Missing or partial failed usage makes them known subtotals, not a complete amount to subtract from total spend. The native runner's `cost.usd` can use receipt evidence, so equality with the stream-based `provider.errorCostUsd` is not guaranteed.
+
+Positive reported reasoning uses the normalized `usage.reasoning` field, `reasoning_tokens`, and supported nested provider-detail fields. The root `reasoningTokens` alias can be an adapter estimate without a provenance marker, so it is left unattributed rather than promoted to reported provider usage. Normalized zero reasoning is also unattributed because adapters can fill it when provider detail is absent. A reasoning-only failure is observed but has incomplete ordinary-token coverage; no output or total is inferred from it.
+
+These observations also do not reconcile the separate `trackedMetrics` ledger selection (#276). Tracked metrics prefer durable assistant-call facts when available, retain durable compaction and tool records, and otherwise fall back to stream calls. Artifacts expose source counts and warnings, but partial or mixed ledgers can omit stream-only calls and fork-inherited history remains unreconciled. Neither those tracked values nor the new provider counters prove complete run accounting; failed-compaction usage is retained separately in the out-of-turn usage ledger and usage report, and is not included by this eval fold.
+
 ---
 
+Full reconciliation across session, stdout, fork and out-of-turn evidence is deferred to v0.4.5 or later. Version 0.4.3 does not add an automatic rejection of cost or efficiency comparisons merely because those sources are partial or mixed. Matching source counts do not prove complete coverage or shared call identity. Existing missing-metric, serving-configuration and execution-envelope comparison gates still apply.
+
 ## Eval Artifact Format (v4)
 
 Evaluation artifacts use format version 4 (`EvalArtifactV4`). Summary token metrics report `measuredRuns` out of total `runs`:
@@ -297,7 +357,7 @@ Eleven numbers plus a reason histogram, each carrying the source it came from. `
 | `generatedTokens` | ledger |
 | `reasoningTokens` | receipt; nullable, because absent and zero are different claims |
 | `toolCalls`, `toolErrors` | ledger when present, otherwise receipt |
-| `ttftMsFirstCall` | ledger |
+| `ttftMsFirstCall` | ledger; nullable when first-call timing is absent |
 | `wallClockMs` | receipt |
 | `contextTokensAtEnd` | ledger |
 | `compactions` | ledger |
@@ -305,6 +365,10 @@ Eleven numbers plus a reason histogram, each carrying the source it came from. `
 
 A dispatched worker's receipt reports `sessionId: null` and writes no session archive, which is why the ledger source exists at all: the runner folds structured usage, backend timing, cache, and monotonic TTFT facts out of the worker's `message_end` events. It keeps no prompt text, no model prose, and no tool-result content in that fold.
 
+First-call TTFT uses the earliest recorded assistant-call timestamp across the selected ledgers; equal timestamps retain their observed order. Missing or invalid timing, or an invalid timestamp that prevents ordering the calls, yields `{ value: null, source: "estimated" }`. A measured zero remains `{ value: 0, source: "ledger" }`. Native session timing starts at each stream invocation and includes the provider's response-header wait. Stdout-only fallback timing starts at the provider's `message_start`, which can arrive after headers; it requires first output, but is not complete request latency and must not be compared as equivalent to native invocation timing. A completion alone supplies neither a zero duration nor a first-token measurement. Verdict v1 consumers must accept nullable TTFT. Historical numeric values, including estimated zeros and native spans that omitted the pre-header wait, remain readable and are not rewritten.
+
+When a stream message lacks a valid timestamp, its ledger payload marks `timestampEstimated: true` beside the legacy ISO placeholder. This leaves first-call chronology unmeasured while preserving any observed per-call monotonic timing.
+
 ### Scenario aggregates
 
 `aggregates` groups verdicts by `scenarioId`, sets `k` to the trial count, and records `passAtK` (any trial passed) and `passPowK` (every trial passed). Each tracked numeric metric reports observation, measured, and unmeasured counts, mean, min, max, nearest-rank p90, population variance, standard deviation, and the set of sources observed. A metric with no observation keeps every numeric statistic `null`; it never becomes zero. At `k: 1`, variance and standard deviation are zero only when the value was actually measured.

package/docs/process/git-commit-provenance.md

@@ -66,6 +66,21 @@ Clio-Evidence: receipt-v20/sha256:<64-character digest>
 Clio does not invent, shorten, or add an unrelated digest. The role trailers do
 not depend on this optional line.
 
+A commit also names the decisions it was made under, one trailer per active
+decision on the session decision board (an `ask_user` answer or a design
+choice the agent recorded with `decide`):
+
+```text
+Clio-Decision: <interviewId>/<key>
+```
+
+The refs come from the sealed receipt's `decisionRefs` at the fleet seam and
+from the live board at the session seam. They are sorted, capped at 32, added
+once, and only refs of the `<id>/<key>` shape are written, where the key is an
+operator `snake_case` key or an agent `kebab-case` key. A decision trailer
+records rationale provenance; it is not evidence that the decision was correct
+or that its work was validated.
+
 ## Commit paths and hooks
 
 The deterministic SDLC fleet attributes its plan, code, and documentation