@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/guide/tool-usage.md

@@ -2,6 +2,23 @@
 
 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 `gateway(op="call", capability="clio_docs", args={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/`.
 
+### The tool surface at a glance
+
+| Purpose | Tools |
+| --- | --- |
+| Read and search the workspace | [`read`](#read-page-through-a-file-with-offset-limit-and-tail), [`grep`](#grep-search-file-contents-with-ripgrep), [`find`](#find-locate-files-and-directories-by-glob-pattern), [`ls`](#ls-list-one-directory), [`code_nav`](#codenav-navigate-the-codewiki-index) |
+| Change the workspace | [`edit`](#edit-exact-text-replacements-in-one-file), [`write`](#write-create-or-overwrite-a-whole-file), [`bash`](#bash-run-a-shell-command), [`run_script`](#runscript-stream-a-scientific-processing-step-to-disk) |
+| Prove something works | [`verify`](#verify-run-declared-verification-checks), [`evidence`](#evidence-inspect-canonical-evidence-and-trust-status), [`limitation`](#limitation-record-what-a-turn-could-not-verify) |
+| Delegate and supervise work | [`dispatch`](#dispatch-run-bounded-tasks-on-fleet-agents), [`monitor`](#monitor-inspect-dispatched-runs), [`steer`](#steer-guide-or-cancel-a-running-worker), [`ledger`](#ledger-coordinate-peer-workers-through-typed-entries) |
+| Track and record decisions | [`tasks`](#tasks-the-session-task-board), [`decide`](#decide-record-a-design-decision), [`artifact`](#artifact-plans-reviews-and-reports) |
+| Look things up | [`gateway`](#gateway-discover-and-call-secondary-capabilities), [`clio_docs`](#cliodocs-retrieve-bundled-documentation-through-the-gateway), [`clio_library`](#cliolibrary-inspect-the-recipe-catalog-through-the-gateway), [`context`](#context-workspace-skill-activation-and-recall), [`git`](#git-read-only-inspection-of-git-repository-state), [`data`](#data-inspect-structured-files-through-the-gateway) |
+| Reach outside the machine | [`web_read` and `web_fetch`](#webread-and-webfetch-read-web-pages-or-make-full-http-requests), [`credential_present`](#credentialpresent-check-environment-or-file-for-a-credential-key) |
+| Talk to the operator | [`ask_user`](#askuser-host-owned-operator-interviews), [`panes`](#panes-manage-clio-owned-terminal-panes) |
+
+Cross-cutting behavior that applies to every tool is in
+[Observation envelope](#observation-envelope-truncation-notices-offload-next-hints-and-the-turn-budget)
+and [Search scope](#search-scope-read-ls-grep-and-find-outside-the-workspace).
+
 In the current source tree, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
 
 ## gateway: discover and call secondary capabilities
@@ -54,6 +71,10 @@ JSON-format results (including code_nav, context workspace, clio_docs, data, and
 
 Turn budget: all envelope-backed tools draw from one shared pool of 192KB per turn (`safety.limits.observationBytesPerTurn`, keyed on `sessionId:turnId`). When the remaining pool shrinks a call below its self cap, a note is appended naming the bytes already used. When the pool is exhausted, the call short-circuits with `[observation budget exhausted for this turn before <tool> ...]` instead of paying for a search whose output cannot be returned. Use narrower arguments or continue in a follow-up turn.
 
+## Search scope: read, ls, grep, and find outside the workspace
+
+`read`, `ls`, `grep`, and `find` run without asking on any path inside the session workspace, at every autonomy level. A path that resolves outside it, by an absolute path, a `..`, or a link at any component, asks for one-shot approval at `suggest` and `auto-edit`, runs at `full-auto`, and is denied at `read-only`. Headless runs deny the ask, so give a headless run `--autonomy full-auto` or a `--cwd` that contains what it must read. Zero-access paths (`.env`, `~/.ssh/`, the credential store) are refused at every level. Installed skill, plugin, and extension trees, the `full:` offload files a truncation notice names, and dispatch receipts stay readable without an ask. A search that starts inside the workspace never follows a linked directory out of it. See [the safety model](../architecture/safety-model.md#autonomy-levels).
+
 ## read: page through a file with offset, limit, and tail
 
 Reads one UTF-8 text file. Source: `src/tools/read.ts`.
@@ -136,13 +157,44 @@ Arguments:
 - `timeout_ms` (optional). Default 300000 (5 minutes).
 - `output_policy` (optional). Canonical model-context disposition: `full`, `bounded`, `summary`, or `metadata-only`. Omission is exactly `bounded`.
 
-Workspace containment: commands whose filesystem targets resolve outside the session workspace escalate to `system_modify` and ask for one-shot confirmation at every autonomy level (headless runs deny asks). Recognized targets are shell redirects, `tee`/`mkdir`/`touch` path operands, `cp`/`mv`/`ln` destinations, in-place `sed -i` operands, and any `cd`/`pushd` whose directory leaves the workspace, since a `cd` outside re-bases every relative path that follows it. Inside-workspace equivalents stay plain `execute` with no new prompts.
+Workspace containment: commands whose filesystem targets resolve outside the session workspace escalate to `system_modify` and ask for one-shot confirmation at every autonomy level. Headless runs deny asks. Inside-workspace equivalents stay plain `execute` with no new prompts.
+
+<details>
+<summary>Exactly which write targets and wrappers trigger the escalation</summary>
+
+Recognized targets are shell redirects, `tee`/`mkdir`/`touch` path operands, `cp`/`mv`/`ln` destinations, in-place `sed -i` operands, and any `cd`/`pushd` whose directory leaves the workspace, since a `cd` outside re-bases every relative path that follows it.
+
+A write target the shell expands at run time (`$HOME/x`, `${OUT}`, `{a,b}`) cannot be placed and escalates the same way, and so does a link to outside the workspace made by `ln`, `link`, or `cp -s`/`-l`, recreated by `mv` or a link-keeping `cp` (`-a`, `-P`, `-d`, `-r`), or run through `nice`, `timeout`, `xargs`, `find -exec`, or a similar wrapper.
+
+Here-document bodies are read both as text and as script lines, so a body line cannot hide a real `cd`. The child shell never inherits `CDPATH`.
+
+</details>
+
+The four `output_policy` values differ only in what reaches model context:
 
-The default `bounded` policy keeps a tail-biased model excerpt under the 16KB result budget, because the failing assertion, compiler error, and exit summary usually live at the end. `summary` is useful for noisy builds and test runs: code deterministically selects a bounded head, tail, and error-like lines, applies Clio's repository secret redactor, and records the source hash and algorithm in summary provenance. `metadata-only` is appropriate when the model needs only outcome and termination facts; stdout and stderr stay out of model context while the operator presentation, retained byte size, and retrieval path remain available. `full` is for output known to be small. It is admitted only when the complete captured result and its facts fit the bounded result/context budget; otherwise the result explicitly records a typed downgrade to tail-biased `bounded` and provides retrieval. Do not use `full` as the routine default.
+| Policy | What the model sees | Use it for |
+| --- | --- | --- |
+| `bounded` (default) | A tail-biased excerpt under the 16KB result budget, because the failing assertion, compiler error, and exit summary usually live at the end. | Most commands. |
+| `summary` | A deterministic bounded head, tail, and error-like lines, run through Clio's repository secret redactor, with the source hash and algorithm recorded in summary provenance. | Noisy builds and test runs. |
+| `metadata-only` | Outcome and termination facts only. stdout and stderr stay out of model context; operator presentation, retained byte size, and retrieval path remain available. | Commands whose output the model does not need. |
+| `full` | The complete captured result, admitted only when it and its facts fit the bounded result/context budget. Otherwise the result records a typed downgrade to `bounded` and provides retrieval. | Output known to be small. Not a routine default. |
 
 Presentation is independent from model context. The operator-facing display remains folded and tail-biased under every policy. When the display or selected context omits captured content, the terminal result writes one per-session scratch artifact and names it in the result. Live updates use the selected policy, remain bounded, and never write per-update artifacts. Every terminal result records requested and applied context modes, captured/displayed/context bytes, truncation or downgrade state, and any offload path. Exit code, signal, timeout, abort, and output-cap facts survive every policy. Scratch retrieval may contain the raw retained output; the deterministic `summary` projection is the redacted surface.
 
-A command producing more than 16 MiB of combined stdout/stderr is stopped with an error. The cap result distinguishes raw observed bytes from retained bytes and states where the partial output went: inline, a named offload, or explicitly discarded bytes when retention was cut or failed. Observed bytes count data received through settlement, not hypothetical output from an uninterrupted command. The diagnostic survives summary and metadata-only dispositions. Use `run_script` for disk-streamed output beyond this cap. UTF-8 decoding spans process chunks, and a code point split by the hard byte cap is discarded rather than replaced with an invalid character. Raw NUL bytes are removed from model context under every policy, which leaves multi-byte code points and ANSI escape sequences whole; the operator presentation and the scratch artifact keep the captured bytes, and the result still records the omission and its retrieval path. A timeout, abort, output cap, or nonzero exit preserves captured diagnostics and appends a status line such as `bash: command timed out after <ms>ms` or `bash: command failed (exit N)` before canonical shaping.
+A command producing more than 16 MiB of combined stdout/stderr is stopped with an error. Use `run_script` for disk-streamed output beyond this cap.
+
+<details>
+<summary>What the cap result records, and how partial bytes are decoded</summary>
+
+The cap result distinguishes raw observed bytes from retained bytes and states where the partial output went: inline, a named offload, or explicitly discarded bytes when retention was cut or failed. Observed bytes count data received through settlement, not hypothetical output from an uninterrupted command. The diagnostic survives summary and metadata-only dispositions.
+
+UTF-8 decoding spans process chunks, and a code point split by the hard byte cap is discarded rather than replaced with an invalid character. Raw NUL bytes are removed from model context under every policy, which leaves multi-byte code points and ANSI escape sequences whole. The operator presentation and the scratch artifact keep the captured bytes, and the result still records the omission and its retrieval path.
+
+A timeout, abort, output cap, or nonzero exit preserves captured diagnostics and appends a status line such as `bash: command timed out after <ms>ms` or `bash: command failed (exit N)` before canonical shaping.
+
+</details>
+
+Repository test runners run without confirmation at `auto-edit` and `full-auto`: `npm test`, `pytest`, `python -m pytest`, `python -m unittest` (as `python`, `python3`, or `python3.N`), `cargo test`, `go test`, `ctest`, `make test`, `make check`, `ninja test`, `meson test`, `mvn test`, and `gradle test` or `./gradlew test`. Arguments must be bare words, so `ctest --output-on-failure` and `python3 -m unittest -q test_solver` run, while a quoted argument, `$(...)`, a redirect, a pipe, or `;` makes the command ask again. An `&&` chain runs when every step is recognized, so `cd build && ctest` runs from inside the workspace, and `make check && curl ...` asks. These commands execute repository code, which is the price of letting a headless run verify its own work. `npm run lint`, `npm run build`, `npm run typecheck`, and `npm run ci` still ask for one-shot confirmation at every level. At `suggest` a test runner asks like every command, and at `read-only` it is denied.
 
 Reach for bash for builds, git, package managers, and anything without a dedicated tool. Prefer the dedicated tools over their shell equivalents: grep/find/read/ls get envelope truncation, exact continuation hints, and the shared ignore policy that `cat`, shell `grep`, and shell `find` do not. Prefer `verify` over bash for declared package scripts and project-catalog entries, since verify produces typed evidence.
 
@@ -231,7 +283,7 @@ Rendering: match lines print as `path:line: text`, context lines as `path-line-
 
 Truncation: hitting the match limit gives `next: limit=<2x>` with the total rendered as `N+`. Hitting the byte cap (16KB content, 8KB files/count) offloads the full rendering and, in content mode, suggests `next: mode=files`. At 30 seconds the search stops and returns collected matches with an incompleteness notice. Narrow the pattern, path, or glob to continue.
 
-Native and fallback results include `details.search = {complete, reason?, skipped: {count, samples, unknown?}}`. Reasons are `timeout`, `errors`, `limit`, or `cancelled`. Counts describe observed skips, samples are bounded and protected-path filtered, and `unknown=true` means diagnostic coverage could not be determined. Recoverable native errors retain matches; invalid patterns still error. The asynchronous fallback counts unreadable, oversized (over 20 MB (20000000 bytes)), and binary skips and yields during traversal.
+A match on a line that is not valid UTF-8 is shown with each invalid byte sequence replaced by U+FFFD, on the native path and the fallback alike. Native and fallback results include `details.search = {complete, reason?, skipped: {count, samples, unknown?}}`. Reasons are `timeout`, `errors`, `limit`, or `cancelled`. Counts describe observed skips, samples are bounded and protected-path filtered, and `unknown=true` means diagnostic coverage could not be determined. Recoverable native errors retain matches; invalid patterns still error. The asynchronous fallback counts unreadable, oversized (over 20 MB (20000000 bytes)), and binary skips and yields during traversal.
 
 Reach for grep to find where something lives; use mode=files to map breadth cheaply before reading, and mode=count to size a rename or sweep.
 
@@ -393,7 +445,7 @@ Arguments:
 
 ### Project verifier catalog
 
-Repository script checks require one-shot operator confirmation or an approved safety command declaration. Committing a verifier catalog defines the available checks; it does not grant execution authority.
+Repository script checks require one-shot operator confirmation or an approved safety command declaration, except a check whose argv is a recognized test runner (see the bash section), which runs at `auto-edit` without asking. Committing a verifier catalog defines the available checks; it does not grant execution authority.
 
 Projects may commit a versioned executable catalog at `.clio-coder/verifiers.yaml`:
 
@@ -426,7 +478,26 @@ checks:
     tags: [scientific, performance]
 ```
 
-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 uses `tolerance.combine: all|any` (default `all`) to require all named bounds or at least one. Missing keys and array-length mismatches fail independently of combination. `tolerance.nonFinite: fail|match` defaults to `fail`; `match` accepts NaN paired with NaN and same-signed infinities. `ulp` must be an integer at most `Number.MAX_SAFE_INTEGER` (9007199254740991). This is a conjunction/disjunction of individual bounds, not an additive absolute-plus-relative formula. `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 versioned JSON baseline 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.
+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` | What it judges |
+| --- | --- |
+| `command` | The exit code. |
+| `numeric-compare` | The command's stdout, parsed as a JSON object of `string -> number \| number[]`, against `reference` (a repository-relative JSON file of the same shape) under `tolerance`. |
+| `perf-budget` | The wall time the harness measured against either `budget: {wallTimeMs, tolerance?: {relative}}` or `baseline`. Exactly one of the two is present. |
+
+A command that exits non-zero, times out, or is aborted fails before any judgement. Both judged 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.
+
+<details>
+<summary>Tolerance semantics for `numeric-compare` and baseline recording for `perf-budget`</summary>
+
+`tolerance` names at least one of `relative`, `absolute`, or `ulp`. `tolerance.combine: all|any` (default `all`) requires all named bounds or at least one. This is a conjunction or disjunction of individual bounds, not an additive absolute-plus-relative formula.
+
+Missing keys and array-length mismatches fail independently of combination. `tolerance.nonFinite: fail|match` defaults to `fail`; `match` accepts NaN paired with NaN and same-signed infinities. `ulp` must be an integer at most `Number.MAX_SAFE_INTEGER` (9007199254740991).
+
+A `perf-budget` `baseline` is a repository-relative versioned JSON baseline that `clio-coder verifiers baseline <id>` records from one clean run, with an optional `tolerance: {relative}` of headroom over it.
+
+</details>
 
 
 Judged command capture and numeric reference reads have a 32 MiB ceiling. Output-cap, execution, timeout, or abort failures prevent judgement; partial JSON never earns a pass. Reports record effective `combine`, `nonFinite`, and a readable `rule`; numeric provenance includes `reference` (source, path when supplied, SHA-256, bytes) and `actual` (SHA-256, bytes of the extracted payload). Non-finite report numbers serialize as `"NaN"`, `"Infinity"`, or `"-Infinity"`, never JSON null. These report spellings do not extend the input JSON grammar. Relative deviation against zero is zero for equality and undefined for a nonzero actual, so an absolute bound with `combine: any` can admit near-zero values.
@@ -435,7 +506,17 @@ Each declared check carries `judgement = {execution, validation, scientificValid
 
 New performance baselines are version 2 and record `wallTimeMs`, `check`, `recordedAt`, and `environment` (`hostname`, `platform`, `arch`, `cpuModel`, `cpuCount`, `totalMemoryBytes`, `nodeVersion`). Version 1 still loads without an environment. Reports retain baseline path/hash/bytes and compare baseline/current environments in `environment.differing`; differences are informational and do not change the declared time-budget verdict.
 
-Version 2 keeps version 1's strictness. The root version/checks and core check fields (`id`, `description`, `command`, `cwd`, `timeoutMs`, `tags`) are required; kind-specific fields follow the contracts above. Unknown fields 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.
+Version 2 keeps version 1's strictness. The root version/checks and core check fields (`id`, `description`, `command`, `cwd`, `timeoutMs`, `tags`) are required, kind-specific fields follow the contracts above, and unknown fields and duplicate IDs fail.
+
+| Field | Constraint |
+| --- | --- |
+| `id` | Lowercase letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit, at most 64 UTF-8 bytes. `frontend` is reserved. |
+| `description` | Trimmed single-line text, at most 512 bytes. |
+| `command` | A nonempty argv array, at most 64 entries, 4096 bytes per entry. A shell command string is invalid, and `sh`, `bash`, `pwsh`, and `cmd` are rejected. |
+| `cwd` | A repository-relative existing directory, at most 512 bytes. Absolute paths, `..` escapes, and symbolic-link escapes fail. |
+| `timeoutMs` | A positive integer, at most 900000. |
+| `tags` | At most 16 distinct lowercase tags of at most 32 bytes each. |
+| The file | At most 262144 bytes and 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.
 
@@ -523,7 +604,17 @@ gateway(op="call", capability="git", args={op: "log", limit: 10})
 
 Direct OBSERVE retrieval of the working environment. Source: `src/tools/context/index.ts`.
 
-Arguments are `scope` (`workspace`, `skills`, or `recall`), `name` and `include_tree` for skills, and `ref`, `offset`, and `limit` for recall. `query` can narrow recall. Workspace returns the cached session git/project snapshot and requires a bound session. Skills list or activate installed skills; read-only and suggest activation require an explicit operator request, and recipe-bound workers can load only their declared skills. Recall retrieves evicted observations without changing the eviction marker. Workspace and skills use a 50KB cap.
+Arguments are `scope` (`workspace`, `settings`, `skills`, or `recall`), `name` and `include_tree` for skills, and `ref`, `offset`, and `limit` for recall. `query` can narrow recall. Workspace returns the cached session git/project snapshot and requires a bound session. Skills list or activate installed skills; read-only and suggest activation require an explicit operator request, and recipe-bound workers can load only their declared skills. Recall retrieves evicted observations without changing the eviction marker. Workspace, settings, and skills use a 50KB cap.
+
+`context(scope="settings")` reads an allowlisted view of the running session's
+effective configuration. It explains autonomy, worker approvals, and configured
+ceilings, and names the exact configure and `/settings` destinations. `query`
+filters by section alias, settings path, or terms; `limit` is 1–12 (default 12),
+and `offset` follows `nextOffset`. Credentials, endpoint URLs, arbitrary strings,
+and structured command configuration are omitted. Configured ceilings are not
+remaining budgets. The tool never writes settings; it guides the operator to
+changes. A worker without an authoritative snapshot receives an unavailable
+error rather than guessed defaults.
 
 ```text
 context(scope="workspace")
@@ -538,7 +629,20 @@ Source: `src/tools/gateway/clio-context-tools.ts` and `src/tools/context/docs-en
 `clio_docs` runs deterministic, offline retrieval over Clio's recursively
 bundled Markdown tree under `docs/` plus README.md, CHANGELOG.md, and
 CLIO-CODER.md, indexed as heading-delimited sections with light stemming, Clio
-vocabulary aliases, phrase boosts, and BM25-style body scoring. The JSON payload carries `corpus`, the expanded `terms`, and ranked `results` with `file`, `heading`, `breadcrumb`, `anchor`, `lines`, `snippet`, `score`, `coverage`, `matchedTerms`, and `signals`, plus an `omitted` count. Follow the `followUp` guidance: read the cited file and line range when you need the full section. Empty results are still valid JSON with `next` populated (the closest vocabulary expansion, or `query=overview`). 16KB cap; an oversize payload is replaced by the parseable JSON stub. The old `docs_search` `file` filter was dropped in the consolidation. Omitting `query` returns the corpus listing (the file set plus doc and section counts, the same `corpus` shape a search carries) so the model can pick a term without wasting a round on a `requires query` error.
+vocabulary aliases, phrase boosts, and BM25-style body scoring.
+
+Omitting `query` returns the corpus listing, the file set plus doc and section counts, so the model can pick a term without wasting a round on a `requires query` error.
+
+<details>
+<summary>The result payload shape and what an empty or oversize result returns</summary>
+
+The JSON payload carries `corpus`, the expanded `terms`, and ranked `results` with `file`, `heading`, `breadcrumb`, `anchor`, `lines`, `snippet`, `score`, `coverage`, `matchedTerms`, and `signals`, plus an `omitted` count. Follow the `followUp` guidance: read the cited file and line range when you need the full section.
+
+Empty results are still valid JSON with `next` populated, carrying the closest vocabulary expansion or `query=overview`. The result is capped at 16KB; an oversize payload is replaced by the parseable JSON stub.
+
+The old `docs_search` `file` filter was dropped in the consolidation.
+
+</details>
 
 ```text
 gateway(op="call", capability="clio_docs", args={query: "dispatch receipts evidence", limit: 8})
@@ -548,9 +652,28 @@ gateway(op="call", capability="clio_docs", args={query: "dispatch receipts evide
 
 Source: `src/tools/gateway/clio-context-tools.ts` and `src/tools/context/library.ts`. Arguments: `query`, `kind` (`skill`, `agent`, `prompt`, `fleet`, `plugin`), `ref`, `limit` (default 20, max 50), and zero-based `offset`.
 
-`clio_library` is the read-only recipe catalog, backed by the same bounded inventory `clio-coder library recipes --json` reads, and it activates, installs, registers and pins nothing. Rows are tagged and never mixed up with one another. A `resource` row is a recipe that actually loaded: its runtime name (skill frontmatter name, agent recipe id, prompt path with colons, fleet contract name), owning package or `core`/`user`/`project`/`compat` source class, scope, origin evidence, format, and the invocation that works. A `hint` row is a catalog claim about one member of a package: it names the owning package, that owner's installed copy states, and the member's own state (`not-installed` when the owner is not installed, `unknown` when the owner is installed and the member did not turn up), and it never carries an invocation because nothing loaded it. A `package` row is the install target itself with its version, origin, installed copies, and bounded `provides` hints; a package with no hints reports its contents as unknown until inspection rather than empty.
+`clio_library` is the read-only recipe catalog, backed by the same bounded inventory `clio-coder library recipes --json` reads. It activates, installs, registers and pins nothing, and it never returns instruction bodies or absolute recipe paths.
+
+Rows are tagged and never mixed up with one another:
+
+| Row | What it is |
+| --- | --- |
+| `resource` | A recipe that actually loaded, with its runtime name (skill frontmatter name, agent recipe id, prompt path with colons, fleet contract name), owning package or `core`/`user`/`project`/`compat` source class, scope, origin evidence, format, and the invocation that works. |
+| `hint` | A catalog claim about one member of a package. It names the owning package, that owner's installed copy states, and the member's own state (`not-installed` when the owner is not installed, `unknown` when the owner is installed and the member did not turn up). It carries no invocation, because nothing loaded it. |
+| `package` | The install target itself, with version, origin, installed copies, and bounded `provides` hints. A package with no hints reports its contents as unknown until inspection rather than empty. |
+
+<details>
+<summary>What the model view hides, how `kind` and `ref` resolve, and the page budget</summary>
+
+The model view is the model audience: internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are not listed. A run started with `--no-skills` lists no skill rows, because nothing in it can load one.
+
+`kind="plugin"` returns plugin-kind install targets only. Any recipe kind returns the loaded resources of that kind plus the installable owners that provide it, so an Agents or Prompts query finds the owning bundle before it is installed and without fetching its source.
+
+`ref` may match one exact resource key, several same-named records across kinds (the payload says so and each row carries its `key`), or a package, which opens that package's members.
+
+The result is capped at 16KB. The page is fitted to the remaining budget before it is rendered, so `limit` is an upper bound and `nextOffset` carries the remainder. `total` counts what the inventory returned and is flagged `totalIsLowerBound` when the inventory hit its own record cap. Worker registries have no library projection of their own and get a clean unavailable error.
 
-The model view is the model audience: internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are not listed. `kind="plugin"` returns plugin-kind install targets only; any recipe kind returns the loaded resources of that kind plus the installable owners that provide it, so an Agents or Prompts query finds the owning bundle before it is installed and without fetching its source. `ref` may match one exact resource key, several same-named records across kinds (the payload says so and each row carries its `key`), or a package, which opens that package's members. A run started with `--no-skills` lists no skill rows, because nothing in it can load one. Instruction bodies and absolute recipe paths are never returned. 16KB cap: the page is fitted to the remaining budget before it is rendered, so `limit` is an upper bound and `nextOffset` carries the remainder; `total` counts what the inventory returned and is flagged `totalIsLowerBound` when the inventory hit its own record cap. Worker registries have no library projection of their own and get a clean unavailable error.
+</details>
 
 ```text
 gateway(op="call", capability="clio_library", args={kind: "agent", query: "materials"})

package/docs/guide/troubleshooting.md

@@ -10,13 +10,13 @@ diagnostics in the current source tree.
 
 | User-Facing Error / Notice | Cause | Actionable Remediation |
 | :--- | :--- | :--- |
-| `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` | A tool call required manual permission confirmation during a non-interactive headless `clio-coder run` execution. | Run the command interactively in the TUI (`clio`) to grant one-shot approval, adjust the workspace policy in `.clio-coder/safety.yaml`, or run with `--autonomy full-auto` if safe. |
+| `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` | A tool call required manual permission confirmation during a non-interactive headless `clio-coder run` execution. | Run interactively in the TUI (`clio-coder`) to review and approve the request, or review the workspace policy in `.clio-coder/safety.yaml`. `--autonomy full-auto` removes autonomy-only prompts; safety rules can still require approval. |
 | `no trace database yet at <path>` | The trace mirror database has not been initialized because no interactive sessions or dispatches have executed yet. | Execute a turn or dispatch a task. In SQLite trace commands, this notice is informational (exit code `0`). |
 | `trace database not found: <path>` | An explicit `--db <path>` flag was provided pointing to a nonexistent database file. | Verify the database path or omit `--db` to use the default state directory database (`<stateDir>/trace.sqlite`); the next line prints that default path. |
 | `no local skill marketplace catalog or index configured` | No catalog directory (`CLIO_CODER_SKILL_CATALOG_DIR`, a `library/skills/` folder in the working tree, or the installed package's own `library/skills/` catalog) and no JSON index (`CLIO_CODER_SKILL_MARKETPLACE_INDEX`, `<configDir>/skill-marketplace.json`, or the package's `library/skills/skill-marketplace.json`) was found. On an npm install this means the package is incomplete; check `clio-coder doctor`. | Point `CLIO_CODER_SKILL_CATALOG_DIR` at a `library/skills/` catalog or `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json`, or install a skill directly via `clio-coder library install <path\|github-url>`. |
 | `<arg> is a global option and must come before the subcommand: clio-coder <usage> <command> ...` | A global CLI option (such as `--api-key`, `--no-context-files`, or `-nc`) was placed after the subcommand name. Directory roots are configured via `CLIO_CODER_*_DIR` environment variables. | Move the flag before the subcommand name (e.g. `clio-coder --api-key <key> run ...` instead of `clio-coder run --api-key <key> ...`). |
 | `target <id> is not registered` | The designated target ID does not exist in `settings.yaml`. | Run `clio-coder targets` to view available targets, or configure a new target using `clio-coder targets add`. |
-| `budget: ceiling must be >= 0 (got <val>)` | A negative session cost ceiling reached the scheduling budget (`src/domains/scheduling/budget.ts`). | Set a non-negative `safety.limits.sessionCostUsd` in `settings.yaml`, or edit Session ceiling (USD) in Settings → Budget. |
+| `budget: ceiling must be >= 0 (got <val>)` | A negative session cost ceiling reached the scheduling budget (`src/domains/scheduling/budget.ts`). | Set a non-negative `safety.limits.sessionCostUsd` in `settings.yaml`, or edit Session ceiling (USD) in Settings → Permissions & Limits. |
 | `worker_final_output_missing` | A worker process completed execution with exit code 0 but failed to emit a valid final answer before the stream closed. | Check the worker event log using `clio-coder trace tail <runId>` or inspect the receipt via `monitor(run_id="<id>", mode="receipt")`. |
 | `vram_capacity_fit_failure` | The model could not be scheduled or loaded due to insufficient GPU VRAM capacity on the target node. | Select a smaller quantized model variant, reduce context window size, or route to an alternative fleet node with greater memory capacity. |
 | `loop_guard_tools_disabled_exhausted` | The loop detector identified repeated unproductive tool calls with identical arguments and disabled tool execution. | Inspect model prompts and provide clearer intermediate steering instructions to prevent recursive tool loops. |
@@ -76,6 +76,8 @@ The eight causes and what stamps each one are in [context-engine.md](../architec
 
 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-coder-local-coding-targets.yaml` for the measured figures and the exact argv they were taken under.
 
+The opposite case is a turn the server calls hot that still waits seconds for its first token. On a multi-slot llama.cpp server with `--kv-unified`, idle-slot caching is on by default: whenever a request starts, the server moves every idle slot to host RAM, and a returning prompt is restored from there before its slot launches. The prefill line then shows a handful of uncached tokens and the rest cached in a few hundred milliseconds, while the turn's TTFT runs to ten seconds, and a concurrent worker on the same server stalls for the same time. `clio-coder doctor` reports this configuration as a `cache <target>` warning and `clio-coder targets --probe` as a note, for a router target. Start the server with `--no-cache-idle-slots`, or set `cache-idle-slots = false` in its preset. Resident slots make cold prefills slower while other slots hold long prompts; the mechanism and the measured trade-off are in [context-engine.md](../architecture/context-engine.md#self-hosted-prefix-cache-contract).
+
 ---
 
 ## A TUI that stops answering the keyboard

package/docs/process/battletest-2026-09-20-fixes.md

@@ -0,0 +1,161 @@
+# Battletest fixes and verification — 2026-09-20
+
+> [!NOTE]
+> **Historical Record**: This document is a dated historical record of the Pi 0.86.1 battletest verification and defect resolution campaign conducted on 2026-09-20. It records candidate-specific test environments, findings, and verification outcomes, not active operator or contributor workflows. Current architecture and contracts are maintained in `docs/architecture/` and `docs/guide/`.
+
+This is the follow-up implementation campaign for the Pi 0.86.1 battletest.
+It fixes reproducible runtime and evaluation defects, and records the model
+failures that remain. A passing result schema or successful worker process is
+not treated as delivery of the requested task.
+
+## Routes and isolation
+
+- OpenAI subscription: `openai-codex`, `gpt-5.6-luna`, `xhigh`.
+- Anthropic subscription: `anthropic-max`, `claude-haiku-4-5`, thinking off.
+- Local Qwopus: Blade route `mini/qwopus3.8-27b-dense`, requested thinking high.
+  Only one Mini workload ran at a time. Dynamo was stopped when the operator
+  reserved it for another project, and was not resumed.
+
+Tests used the production CLI, real providers, disposable projects, normal tool
+admission and receipts. Multi-turn tests restarted the CLI with `--continue`;
+fork tests used native `context: {"mode":"fork"}`. These were headless tests,
+not a new terminal-overlay or GUI test campaign. Earlier interactive tree,
+compaction, fork, restart/resume, Deny, and Stop evidence remains in the original
+campaign. No GUI source was edited or staged. Production bundles were built into
+isolated directories without running the GUI asset-build hook.
+
+Working evidence: `/tmp/clio-fix-retest-p3kgk22k`.
+Durable archive: `$XDG_DATA_HOME/clio-coder/evidence/battletest-fixes-20260920`
+(default `~/.local/share/clio-coder/evidence/battletest-fixes-20260920`).
+The archive excludes provider configs and credentials. `source-v*.patch`, lane
+metadata, suite YAML, receipts, event streams, grader output and command logs
+identify the candidate behind each attempt. Absolute paths inside the original
+artifacts preserve provenance; use the corresponding archived lane when a
+scratch path has expired.
+
+## Source fixes
+
+| Finding | Change and verification |
+| --- | --- |
+| BT-01: dispatch objects became JSON strings on Anthropic | Pi's non-strict Anthropic serializer drops root `$defs`; Clio's shared references therefore lost their definitions. Dispatch now carries self-contained nested schemas. A no-network test captures the actual Pi payload and validates single/batched objects and rejection of string encodings. Haiku's live fork changed from two rejected string-encoded calls to one admitted object-valued call. No SDK patch was added. Descriptions were shortened to retain the existing attached-schema size gate. |
+| BT-03: gateway execution disappeared from metrics | Metric capture retains bounded gateway operation/capability identity. A capability call contributes its native metric while aggregate model tool-call counts remain unchanged. The web-fetch grader accepts direct and gateway execution. Luna, Haiku and Mini passed the real invalid-scheme case. An expected refusal can pass only when the suite explicitly enables `allowNoop` and an independent grader passes. |
+| BT-04 / BT-08: skills and delegation overrode operator scope | Operating guidance honors no-tools/no-delegation and explicit tool lists; small cohesive multi-file changes no longer mandate delegation. Declined installation stays declined, and no-ready-skill reminders do not prescribe unavailable activation. Proposal work must remain blocked. All three models implemented the small multi-file fixture without dispatch. Proposal-only compliance remains inconsistent; see below. |
+| BT-05: native-read recovery still sealed as no-op | A successful native observation can recover denied shell execution. It cannot clear an unresolved write block. Both cases are covered, and all three providers passed the real denied-shell/native-read scenario. |
+| BT-06: grader evidence and metrics disappeared | Preserve grader stdout/stderr and bounded `proposal.*`, `memory.*`, `scope.*`, `explanation.*` facts, including explicit null for unmeasured values. Reserved host metrics remain protected. |
+| BT-07: shipped coding skills blocked verification | `fix-issue` and `ship` admit `verify`; package versions and all library/skill digest indexes were updated together. Compatibility-discovery tests now reflect the already-committed explicit-import policy. |
+| BT-09: empty stream blamed an unrelated notice | Headless failure now identifies an ended provider stream without an assistant response or terminal result. It does not claim that a thinking-level notice caused the failure. |
+| BT-10: forked workers followed the parent's dispatch request | Fork assignment messages explicitly distinguish inherited background from the current worker assignment. Worker guidance preserves operator constraints. Luna, Haiku and Mini all admitted a real fork and produced passing verifier reports. |
+| BT-11: final synthesis repeated tool-shaped output | Final-only contract repair uses a new user directive to break the tool-exchange pattern; active revision retains the paired exchange and its cache behavior. Locked markup reprompt uses the same terminal-direction approach. Repair/synthesis regressions pass. The new fork fixtures did not exhaust repair. A separate accepted-result/capture mismatch was subsequently reproduced and fixed, as described below. |
+| BT-12: interruption lost completed grades | Atomically checkpoint results after each case, with explicit incomplete/completed status. A real CLI suite was terminated during case two: case one's passing grade survived and no finished artifact was produced. |
+| New: read-only `code_nav` wrote project files | Reconcile a bounded in-memory snapshot using the existing codewiki worker, without taking a writer lease or persisting `.clio-coder/codewiki.json`/`state.json`. Freshness checks and a real no-edit run prove zero workspace changes. |
+| New: bounded console output corrupted grader evidence | Stream complete runner stdout to a private capture before grading; retain it separately from bounded console excerpts. Fail closed at 64 MiB. Drop opaque Pi replay signatures from the presentation JSON stream only, retaining canonical session data. The previously failing Luna scout pipeline passed with complete event capture. |
+| New: board follow-up hid an already delivered proposal | Proposal grading checks delivered assistant text across the turn while retaining final board-state and tool-scope assertions. Mini's original compliant stream passes regrading; the violating Haiku stream still fails. A later fresh Mini run independently violated scope and remains failed. |
+| New: parent confused host checks with worker claims | Dispatch output now explains each separate host check and whether it executed or reused evidence. Luna originally denied that a recorded host check existed; the live follow-up correctly distinguished the worker check and the separate host execution. |
+| New: accepted Scout report disappeared before sealing | Worker validation accepted reports larger than the parent’s 8 KiB capture limit; the parent silently discarded them. Structured helpers now share a 32 KiB acceptance/capture ceiling, including canonicalized salvage. A live Scout report of 9,519 bytes now seals intact with passing conformance/quality. Oversized reports are rejected while worker repair remains possible. |
+
+BT-02 remains an inconclusive interaction observation: the original conditional
+prompt during generation was ambiguous. Earlier unconditional replacement and
+queued-prompt controls passed. No speculative input-routing change was made.
+
+## Real model evidence
+
+This campaign contains 38 graded attempts across successive candidates:
+
+| Route | Graded attempts | Raw passes | Raw failures |
+| --- | ---: | ---: | ---: |
+| Luna | 26 | 13 | 13 |
+| Haiku | 5 | 3 | 2 |
+| Mini Qwopus | 7 | 4 | 3 |
+
+These are audit counts, **not a final-candidate success rate**: they include
+reproductions, old graders, repeated failing cases, and different targeted
+subsets. No original failure was overwritten by a later retry or regrade.
+An early generated test-config error prevented 13 additional attempts from
+calling any model; those are archived separately as invalid configuration.
+The stopped Dynamo attempts are excluded from these model counts.
+
+The separate production multi-turn sequence was:
+
+1. Read a small project, implement `mean`, cover empty and populated arrays,
+   update the test script, run verification, and obey no delegation/commit.
+2. Restart with `--continue`; dispatch one native-fork verifier and await its
+   receipt. Run an independent host check as declared in dispatch intent.
+3. Restart again; recall the marker, `mean([]) === null`, and verification facts
+   without any tool use.
+
+All three routes produced independently passing implementations, zero
+implementation dispatches, one admitted fork, and zero recall tool calls.
+Haiku receipt `1x89cztrglle` and Mini receipt `17m8ayhmicpf` each record exactly
+one successful worker `verify` call plus separate passing host execution.
+Luna receipt `1ranswsbn842` records two successful `verify` tool calls; the
+aggregate does not distinguish check discovery from execution, so this report
+does not certify an exact execution count for that earlier worker. Its report
+and host check passed. Luna's first recall misstated host provenance; after the
+output-label fix it correctly reported both executions. See
+`conversation-results.json` and `host-recall-progress.log` plus the retained
+`fork-after-label`/`recall-after-label` streams.
+
+## Remaining failures and limits
+
+1. **Proposal scope is not reliable on Haiku or Mini.** Haiku made seven
+   unauthorized discovery calls in the latest proposal run and left the board
+   pending. Mini had one compliant run (confirmed by regrading its complete
+   original stream), then made one out-of-scope call on a fresh run. The
+   grader still fails these attempts. Natural-language scope guidance is not
+   equivalent to a structured tool allowlist enforced by the registry.
+2. **Luna's no-edit memory answer is incomplete.** It now leaves the entire
+   workspace unchanged and acknowledges that retention was not performed,
+   but omits the supported proposal/approval workflow. No persistence or
+   fresh-session memory delivery is claimed by this single-turn case.
+3. **Long source explanations still fail.** The original folded YAML prompt
+   ambiguously placed parent coordination text beside the exact worker task;
+   explicit `<worker-task>` boundaries corrected that ambiguity without
+   loosening task equality. The new Coder run preserved the task and produced
+   a conforming 1,016-word report, but used basename-only citations for three
+   nested source files, failing the full-path citation requirement. The new
+   Scout run (`2es91b4wog6c`) failed with missing final output after 12
+   successful read/grep calls. Investigation reproduced the accepted-result/
+   capture-size mismatch, and the corrected rerun (`1hz4db3f2xaj`) successfully
+   sealed a 9,519-byte, 1,167-word structured report. That new report passes
+   conformance and quality, but still fails the corpus's per-source structured
+   citation requirement: `tests/test_coefs.py` appears in prose citations, not
+   as a finding's `path`. This is distinct from losing the terminal report.
+4. **Synthesis evidence remains bounded.** Forked verifiers and the corrected
+   long Scout now return intact results, and repair regressions pass. These
+   cases do not establish universal model adherence or successful completion
+   of every report requested in prose.
+
+No further model jobs were left running. No new model calls are needed to
+inspect the preserved evidence.
+
+## Verification
+
+- Root typecheck, Biome and all 17 hygiene checks passed; Pi surface matches.
+- Production isolated build and the existing Stage 0 import/byte budget passed.
+- Full root contract/smoke gate: 1,099 passed, one skipped, zero failed.
+- Focused worker/context, codewiki, eval capture, headless and keyboard batch:
+  109 passed. Skill/import batch: 27 passed. Repair/result-contract batch:
+  36 passed. Host-evidence/batch-settlement batch: 30 passed. The helper-size,
+  native terminal-handoff and source-explanation batch passed all 33 checks;
+  its exact-boundary follow-up also passed. Additional schema
+  wire, provider-boundary and changed-case checks passed. Counts overlap and
+  must not be added into one unique-test total.
+- All 25 eval suites validate through the production loader.
+- Tests extend existing files; no new test suite files were added.
+
+A full gate caught the inline schema's byte growth. The implementation was
+shortened to pass the existing ceiling; the ceiling was not raised. The final
+build remains isolated so this campaign does not replace GUI build artifacts
+being maintained by the concurrent GUI agent.
+
+## Implementation commits
+
+- `47a08d88`: read-only code navigation.
+- `a6183249`: provider-compatible dispatch schemas, fork assignment boundaries,
+  final-only repair and explicit host-check evidence.
+- `6deea2a0`: native-read recovery and empty-stream diagnostics.
+- `07e9e245`: operator scope, ready-skill policy and verification permissions.
+- `91ecd5ab`: complete eval evidence, checkpoints and grading corrections.
+- `12de54a8`: retain the existing prompt byte budget with inline schemas.
+- `72bf2ece`: align helper acceptance and receipt capture limits, including
+  canonicalized salvage at the boundary.