@iowarp/clio-coder 0.4.8 → 0.4.9

package/docs/architecture/library.md

@@ -13,7 +13,7 @@ Clio uses **library** for the collection and **package** for a distributable ite
 7. **Trust follows origin.** `installLibraryPackage({kind, sourcePath, scope, origin, trust, ...})` is exported from `src/domains/plugins/index.ts`. Interop supplies a reviewed prepared tree, `{kind: "interop", host, source: absoluteOriginalPath}`, and `trust: "foreign"`. Skill and prompt loaders honor foreign trust at either scope. Generic updates and forced replacement of adopted content refuse until explicit removal and reviewed re-adoption.
 8. **Eval is an explicit action.** Named evals are contained suite files in the manifest. Installation does not execute them. `eval validate/run --package` resolves a local package or an active verified installation and includes package identity in suite provenance. Evals can execute authored commands in the declared workspace; validation alone does not execute them.
 9. **Operator authority remains separate from autonomy.** Recognized model shell calls cannot install, update, enable, disable or remove package content through the library. Read-only inspection and install/update dry-runs remain available. Interop adoption with `--yes` is likewise an operator action. Runtime offers and overlays commit only through their bound approval paths.
-10. **One inventory, two projections.** `src/domains/resources/library-inventory.ts` produces the bounded, body-free record of packages, scoped copies and actual recipe resources. The CLI reads it for `library recipes` and the model reads it through `context(scope="library")`; they agree about ownership, runtime name, scope, origin, availability and invocation because they are the same records. The model projection is narrower, not different: it is the model audience, so internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are absent, and it drops absolute recipe paths. A catalog `provides` hint is projected as its own tagged row that names its installable owner and that member's honest state, and it never carries an invocation. Neither projection activates, installs, registers or pins anything, and neither fetches a remote source. A native worker registry has no admitted library projection and receives a clear unavailable read rather than the global library.
+10. **One inventory, two projections.** `src/domains/resources/library-inventory.ts` produces the bounded, body-free record of packages, scoped copies and actual recipe resources. The CLI reads it for `library recipes` and the model reads it through `gateway(op="call", capability="clio_library", args={})`; they agree about ownership, runtime name, scope, origin, availability and invocation because they are the same records. The model projection is narrower, not different: it is the model audience, so internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are absent, and it drops absolute recipe paths. A catalog `provides` hint is projected as its own tagged row that names its installable owner and that member's honest state, and it never carries an invocation. Neither projection activates, installs, registers or pins anything, and neither fetches a remote source. A native worker registry has no admitted library projection and receives a clear unavailable read rather than the global library.
 
 ## Identity at runtime
 

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

@@ -33,7 +33,7 @@ The first is a terseness rule. It is tempting to cap the prose a model emits bet
 
 The second is anything that varies with the wall clock or the working tree. No timestamp, no `git status`, no branch name, no session id, and no run id belongs anywhere in the compiled prefix. Every backend Clio targets caches by exact prefix and re-prefills from the earliest changed byte, so one such field turns the whole prompt into a cache miss on every turn for no information the model could not have asked a tool for. On the sprint's measurement server that is a whole 2,778-token prompt re-prefilled at 2.6 s where the same change behind the stable sections cost 516 tokens and 0.72 s. Volatile facts belong in the user message, in a tool result, or in the runtime block, which is last for this reason.
 
-The disk fragments under `src/domains/prompts/fragments/` are layered by who reads them. `identity.clio` and `operating.contract` are constitutional: they render for every reader, name no tool, and state what is always true about Clio and her harness. `operating.delegation` (the delegation threshold as a count taken before the first edit, with the dispatch call shape beside it; receipts, spot-checks, shared `[worker result]` notes) renders only when `dispatch` is on the session's tool surface, and `operating.skills` (skill-shaped tasks, `/skill <name>` suggestions) only when `context` is; a fragment that teaches a tool is absent when the tool is, the same rule the Fleet block follows. `identity.docs-routing`, the directive to call `context(scope="docs")` before answering a question about Clio herself, follows the `context` gate too, while `identity.self-awareness` (installed paths, code outranks docs, configuration locations) names no tool and is unconditional. `operating.worker` (the assigned-task contract) renders only for dispatched workers, which never see the coordinator fragments. `safety.<level>` states what runs, what is approval-required, and what is blocked at the effective autonomy, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name, so the same body is true on every surface; the session and every worker read that one body, and what "approval-required" resolves to is the only role text (one operator confirmation for the session, the worker's `onPermission` routing for a worker).
+The disk fragments under `src/domains/prompts/fragments/` are layered by who reads them. `identity.clio` and `operating.contract` are constitutional: they render for every reader, name no tool, and state what is always true about Clio and her harness. `operating.delegation` (the delegation threshold as a count taken before the first edit, with the dispatch call shape beside it; receipts, spot-checks, shared `[worker result]` notes) renders only when `dispatch` is on the session's tool surface, and `operating.skills` (skill-shaped tasks, `/skill <name>` suggestions) only when `context` is; a fragment that teaches a tool is absent when the tool is, the same rule the Fleet block follows. `identity.docs-routing` directs questions about Clio herself through `gateway(op="call", capability="clio_docs", args={query: ...})` before answering or searching the workspace. It renders only when Clio self-awareness is present, `gateway` is on the supplied tool surface, and provider tool support is not explicitly false. This gate does not depend on `context`, and tool hints cannot establish tool availability. The Skills fragment retains direct `context(scope="skills")` listing and operator-activation guidance; its secondary catalog guidance uses `clio_library` only when `gateway` is on the attached direct-tool surface and explicitly says that route is unavailable without it. Catalog reads activate and install nothing. `identity.self-awareness` (installed paths, code outranks docs, configuration locations) names no tool and is unconditional. `operating.worker` (the assigned-task contract) renders only for dispatched workers, which never see the coordinator fragments. `safety.<level>` states what runs, what is approval-required, and what is blocked at the effective autonomy, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name, so the same body is true on every surface; the session and every worker read that one body, and what "approval-required" resolves to is the only role text (one operator confirmation for the session, the worker's `onPermission` routing for a worker).
 
 Prompt extensions can add dynamic fragments for project rules, the operator profile, and Clio source-tree awareness. Pending skill requests and middleware reminders are visible text in the user message, not hidden prompt machinery.
 
@@ -56,11 +56,11 @@ In addition to project root `CLIO-CODER.md` handbooks, Clio supports directory-s
 
 `wiki.page` and `wiki.plan` (`src/domains/prompts/fragments/wiki/*.md`) load through this same loader, with the same id/version/content-hash contract as every other fragment, but they are consumed differently: `context/wiki/prompts.ts` reads them by id, substitutes per-dispatch `{{token}}` placeholders (a page's path, title, and relative path; the plan file's path), and sends the result as a wiki-generation dispatch's `task`, never as a compiled system prompt. `{{token}}` substitution has no home in the fragment loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders use in `compiler.ts`: the loader hands back a raw body, and the one caller that needs live values fills them in. Both files' bodies open and close on a standalone `---` line that predates their frontmatter and was kept unchanged as body text so the substituted prompt stays byte-identical to what the old hand-rolled `readFileSync` produced.
 
-The Tool Contract section of the prompt renders a fixed set of base lines plus one optional guidance sentence per tool, sourced from the tool registry (`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in `src/tools/bootstrap.ts`). The base lines cover the complete-surface rule, the harness model (direct tools, fleet workers, skills as distinct capability sets), the capability-inventory rule, tool-free answering, the narrow-orientation tool list, validation before final claims, and failure recovery through `context(scope="docs")` instead of blind retries. Delegation, the tasks board, and skill listing are not restated here: `operating.delegation`, the `tasks` hint, and `operating.skills` each say their rule once and render exactly when their tool is on the surface. Fleet routing, including the sentence that `agent:"auto"` is a fallback rather than a router, lives in the Fleet block next to the roster ids and is not restated here; the threshold that says when to delegate at all is the opening of `operating.delegation`, not a Fleet line, because on the round-2 drive with Qwen3.8-27B the bare threshold after the tool contract lost to inertia on every run, while the same count stated up front with the call shape next to it dispatched both workers on every two-changes run and scout on every reconnaissance run once the sentence about repository size was in place. The chat loop derives the hint list once from the session's frozen tool surface at compile time, and the compiler renders the hints sorted by tool name, so the compiled text depends only on which hinted tools are on the surface. The frozen name list is the surface: a hint renders only for a tool in that list, and the gates that decide whether the Delegation, Skills, and docs-routing passages render read the same list, so a stale hint can neither render itself nor pull in a passage for a tool the model cannot call. Today six tools carry hints: `ask_user`, `bash`, `code_nav`, `context`, `panes`, and `tasks`. A hint carries only a decision-local call shape the tool's own description cannot; policy that applies across tools is said once in its prompt section, so `dispatch` carries no hint. Removing a tool from the surface removes its hint with no compiler change; adding a hint to a tool is a deliberate prompt-text change that must land with updated prompt contract tests and a CHANGELOG note.
+The Tool Contract section of the prompt renders a fixed set of base lines plus one optional guidance sentence per tool, sourced from the tool registry (`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in `src/tools/bootstrap.ts`). The base lines cover the complete-surface rule, the harness model (direct tools, fleet workers, skills as distinct capability sets), the capability-inventory rule, tool-free answering, the narrow-orientation tool list, validation before final claims, and failure recovery through `gateway(op="call", capability="clio_docs", args={query: ...})` instead of blind retries. Delegation, the tasks board, and skill listing are not restated here: `operating.delegation`, the `tasks` hint, and `operating.skills` each say their rule once and render exactly when their tool is on the surface. Fleet routing, including the sentence that `agent:"auto"` is a fallback rather than a router, lives in the Fleet block next to the roster ids and is not restated here; the threshold that says when to delegate at all is the opening of `operating.delegation`, not a Fleet line, because on the round-2 drive with Qwen3.8-27B the bare threshold after the tool contract lost to inertia on every run, while the same count stated up front with the call shape next to it dispatched both workers on every two-changes run and scout on every reconnaissance run once the sentence about repository size was in place. The chat loop derives the hint list once from the session's frozen tool surface at compile time, and the compiler renders the hints sorted by tool name, so the compiled text depends only on which hinted tools are on the surface. The frozen name list is the surface: a hint renders only for a tool in that list, and the gates that decide whether the Delegation, Skills, and docs-routing passages render read the same list, so a stale hint can neither render itself nor pull in a passage for a tool the model cannot call. Today six tools carry hints: `ask_user`, `bash`, `code_nav`, `context`, `panes`, and `tasks`. A hint carries only a decision-local call shape the tool's own description cannot; policy that applies across tools is said once in its prompt section, so `dispatch` carries no hint. Removing a tool from the surface removes its hint with no compiler change; adding a hint to a tool is a deliberate prompt-text change that must land with updated prompt contract tests and a CHANGELOG note.
 
 ## One tool surface per session
 
-For tool-capable providers, Clio sends the full registry as the session tool surface. The list is deterministic and sorted through the worker-tool resolver (`resolveAgentTools` in `src/tools/agent-tools.ts`), so the serialized schemas stay byte-identical on every submit. The schema handed to the agent loop is `wireParameterSchema(spec.parameters)`: a copy with every `~`-prefixed key removed, because TypeBox 1.x stamps string-keyed markers such as `~unsafe` and `~optional` on the schemas it builds and, unlike the older symbol keys, those survive JSON serialization and reach the model as properties. Validation is unaffected (`Value.Check` answers identically with and without them) and the registry keeps the original object. `src/tools/agent-tools.ts` is the single agent-tool adapter across the codebase. Both the orchestrator session and worker subprocesses resolve their tool set through the same `effectiveToolNames` narrowing function, ensuring that the attested signature and runtime surface cannot diverge.
+For tool-capable providers, Clio attaches only the admitted direct registry projection as the session tool surface. Gateway capabilities remain registered but carry schemas only in discovery results. The list is deterministic and sorted through the worker-tool resolver (`resolveAgentTools` in `src/tools/agent-tools.ts`), so the serialized schemas stay byte-identical on every submit. The schema handed to the agent loop is `wireParameterSchema(spec.parameters)`: a copy with every `~`-prefixed key removed, because TypeBox 1.x stamps string-keyed markers such as `~unsafe` and `~optional` on the schemas it builds and, unlike the older symbol keys, those survive JSON serialization and reach the model as properties. Validation is unaffected (`Value.Check` answers identically with and without them) and the registry keeps the original object. `src/tools/agent-tools.ts` is the single agent-tool adapter across the codebase. Both the orchestrator session and worker subprocesses resolve their tool set through the same `effectiveToolNames` narrowing function, ensuring that the attested signature and runtime surface cannot diverge.
 
 Tools are keyed strictly by the canonical `ToolName` union defined in `src/core/tool-names.ts` with no alias table. Pure and idempotent `prepareArguments` normalizers defined on `ToolSpec` serve as the sole leniency layer for coercing legacy or weak-model parameter formats.
 
@@ -78,12 +78,11 @@ The worker compiler runs after target capability and tool-profile admission. Can
 
 Project context, memory, bounded dispatch briefing, pipeline input, the assigned task, and the per-run safety-posture reminder remain dynamic user messages. A briefing is a separately delimited message labeled as untrusted task context/data; it is never concatenated into the task or stable system prompt. Dynamic ordering is project, safety, memory, briefing, then pipeline input, with pipeline input last. These messages do not affect the stable composition hash. Persona, effective autonomy, target tool capability, or final toolkit changes do affect it.
 
-## Seven planes, twenty-four tools
+## Eight planes, thirty builtin tools
 
-The canonical builtin catalog contains 24 tools organized in seven planes. A
+The canonical builtin catalog contains 30 tools organized in eight planes. A
 particular session or worker receives the subset whose dependencies and policy
-allow it to register. Each plane is one policy unit: its tools share an action
-class, a size posture, a details schema, and a concurrency rule.
+allow it to register. The policy table records each tool's plane, action class, size posture, and concurrency rule; tools within a plane can differ.
 `src/tools/policy.ts` asserts these invariants at bootstrap, so drift between
 the plane design, the safety classifier, and the registered specs fails loudly
 instead of shipping a surface that behaves differently from what the policy
@@ -91,10 +90,10 @@ engine assumes.
 
 | Plane | Tools | Action class | Concurrency |
 | --- | --- | --- | --- |
-| OBSERVE | `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | read | parallel |
+| OBSERVE | `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present`, `clio_docs`, `clio_library`, `data` | read | parallel |
 | OBSERVE | `evidence` | read | sequential |
 | MUTATE | `write`, `edit` | write | sequential |
-| EXECUTE | `bash`, `verify` | execute | sequential |
+| EXECUTE | `bash`, `verify`, `run_script` | execute | sequential |
 | EXECUTE | `git` | read | parallel |
 | ORCHESTRATE | `dispatch`, `steer` | dispatch | sequential |
 | ORCHESTRATE | `monitor` | read | parallel |
@@ -103,18 +102,21 @@ engine assumes.
 | ORCHESTRATE | `panes` | read | sequential |
 | ORCHESTRATE | `limitation` | read | parallel |
 | ORCHESTRATE | `decide` | read | sequential |
-| RETRIEVE | `web_fetch` | read | parallel |
+| RETRIEVE | `web_read`, `web_fetch` | read | parallel |
 | INTERACT | `ask_user` | read | sequential |
 | ARTIFACT | `artifact` | write | sequential |
+| GATEWAY | `gateway` | read (inner call retains its class) | sequential |
 
 Several tools sit in a plane for containment rather than class. `git` is
 read-only inspection (op=status/diff/log) that runs on the safe-exec spine, so
 it lives in the EXECUTE plane with read-class safety disposition. `monitor`
 never mutates a run, so it stays read class and parallel inside the ORCHESTRATE
-plane. `tasks` orchestrates the agent's own work rather than workers: it mutates
-only the session's task ledger, never the workspace, so it keeps read class
-(never gated behind a confirmation) but runs sequential so two board mutations
-in one batch cannot interleave. `ledger` is the agent ledger, the coordination
+plane. `tasks` orchestrates the agent's own work rather than workers: board
+mutations append session task-ledger snapshots, and calls can reconcile the
+project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done`
+update its durable correlation. These Clio-owned bookkeeping effects retain
+read class without granting source-workspace mutation authority. Calls run
+sequentially so two board mutations in one batch cannot interleave. `ledger` is the agent ledger, the coordination
 board concurrent dispatch workers share: a post reaches a one-way control lane
 and a read answers from a local mirror, so it touches no workspace and stays
 read class, and reviewers and judges are pinned to read-only autonomy where a
@@ -148,20 +150,20 @@ Several tools absorb what used to be separate tools:
 
 - `find(pattern, path?, order?, limit?, include_ignored?)` locates paths by glob pattern (`*`, `**`, `?`, `[abc]`), default limit 500. `order="path"` (default) returns fd's native order; `order="mtime"` returns newest first from a bounded candidate set instead of statting the whole tree, and reports `details.candidates` when the candidate cap made the ordering approximate.
 - `grep(pattern, path?, mode?, glob?, ignore_case?, literal?, context?, limit?, include_ignored?)` searches file contents with ripgrep, degrading to a bounded pure-Node search when rg is absent. `mode=content` (default) returns line-referenced matches, `mode=files` returns matching paths, `mode=count` returns per-file counts. Context lines are consumed from rg's `--json` stream.
-- `context(scope="workspace"|"docs"|"skills"|"library"|"recall")` observes the session workspace snapshot, bundled documentation (omit `query` to list the corpus), skills (`name` optional, `include_tree` for resources), the read-only recipe catalog (`kind`, `query`, `ref`, and `limit`/`offset` pages of tagged resource, hint, and package rows), or persisted historical tool results. In recall scope, provide `ref` for exact retrieval or omit it for discovery with `query`, `limit`, and `offset`.
-- `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` lists package.json verification scripts and strict version-1 `.clio-coder/verifiers.yaml` entries through the same `{id, description, command, cwd, timeoutMs, tags, source}` projection. `verify(check="<id>")` runs a package script or the catalog's exact argv/cwd/timeout through safe-exec with no shell. Model `args`, cwd, timeout, output-cap, and environment fields cannot mutate a project entry. `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
-- `artifact(kind="plan"|"review"|"report", content, ...)` writes named artifacts behind one surface: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is authored outside protected active skill roots with the ordinary write tool and validated by the library validator before operator installation.
+- `context(scope="workspace"|"skills"|"recall")` observes the session workspace snapshot, activates installed skills, or retrieves persisted historical results. Recall accepts `ref` for exact retrieval or `query`, `limit`, and `offset` for discovery. Bundled docs and recipe browsing use gateway capabilities `clio_docs` and `clio_library`.
+- `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` lists package.json verification scripts and strict version-1 or version-2 `.clio-coder/verifiers.yaml` entries through the same `{id, description, command, cwd, timeoutMs, tags, source}` projection. Version 1 supports command checks; version 2 also supports `numeric-compare` and `perf-budget` judgements. New catalogs use version 2; see the [project verifier contract](../guide/tool-usage.md#project-verifier-catalog). `verify(check="<id>")` runs a package script or the catalog's exact argv/cwd/timeout through safe-exec with no shell. Model `args`, cwd, timeout, output-cap, and environment fields cannot mutate a project entry. `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
+- `gateway(op="call", capability="artifact", args={kind: "plan"|"review"|"report", content: ...})` writes named artifacts: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is authored outside protected active skill roots with the ordinary write tool and validated by the library validator before operator installation.
 - `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona`, `tool_profile`, and a typed `budget: {toolCalls, readReserve, retryRevision?}`. The budget must fit the recipe's authored range and the operator lifetime cap. `retryRevision` is the only authority for a later retry, result-contract revision, or review revision to grow its phase. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
 - `monitor(run_id?, mode?)` is read-only visibility into known synchronous and detached runs: `list` enumerates, `status` reports one, `peek` returns the in-process event tail, `receipt` exposes the stored evidence, and `wait` observes one run without collecting or canceling it. `collect` is the authoritative terminal batch operation over a detached batch or run-id list; collect before final synthesis. Completed output reports receipt integrity, evidence verification, briefing provenance, and bounded project-context provenance as different fields.
 - `steer(run_id, action, message?)` controls a running worker: `guide` writes a canonical trimmed steering message to an HTTP or SDK worker and `cancel` terminates it. Successfully written steers gain ordered byte/hash/timestamp provenance; after the runtime accepts the guidance, `clio_coder_steer_received` acknowledges the exact matching sequence, and prose is never stored in ledger or receipt. Single-shot subprocess runtimes and ACP remain non-steerable. Interactive operators can steer synchronous live-input runs; parent-model steering requires detached ids because model tools are sequential.
 
 ### One ignore policy for path walkers
 
-`grep`, `find`, and their pure-Node fallbacks answer "which parts of the tree are visible" from one shared policy in `src/tools/ignore-policy.ts`. Three layers apply: `.clio-coder`, `.fallow`, and `.git` are always excluded; `.gitignore` is honored natively by rg/fd; and one generated-dirs list (`node_modules`, `dist`, `build`, `coverage`, `.venv`, and similar) is force-excluded even when a project forgot to gitignore it. `include_ignored: true` lifts the gitignore and generated-dirs layers together. The clio-internal layer always stands, except that pointing a tool directly at one of those directories means the caller wants those paths.
+`grep`, `find`, and their pure-Node fallbacks answer "which parts of the tree are visible" from one shared policy in `src/tools/ignore-policy.ts`. Three layers apply: `.clio-coder`, `.fallow`, and `.git` are always excluded; `.gitignore` is honored natively by rg/fd; and one generated-dirs list (`node_modules`, `dist`, `build`, `coverage`, `.venv`, and similar) is force-excluded even when a project forgot to gitignore it. `include_ignored: true` lifts the gitignore and generated-dirs layers together. Fallbacks do not parse `.gitignore`; they disclose their generated-directory-only ignore behavior. The clio-internal layer always stands, except that pointing a tool directly at one of those directories means the caller wants those paths.
 
 ## The observation envelope
 
-The six content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav`, `context`) close every result through one shared envelope in `src/tools/observation.ts`. `credential_present` sits in the OBSERVE plane but returns a typed boolean and carries no envelope cap, and `evidence` returns bounded JSON under its own 16KB summary policy. The envelope owns four guarantees.
+The content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav`, `context`, `clio_docs`, `clio_library`, `data`) and gateway find listings close every result through one shared envelope in `src/tools/observation.ts`. `credential_present` sits in the OBSERVE plane but returns a typed boolean and carries no envelope cap, and `evidence` returns bounded JSON under its own 16KB summary policy. The envelope owns four guarantees.
 
 **One notice line, one format.** A truncated text result appends exactly one notice:
 
@@ -169,7 +171,7 @@ The six content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav
 [<tool>: <shown>/<total> <unit> shown (<shownSize> of <totalSize>) | full: <offloadPath> | next: <exact-call>]
 ```
 
-Unknown segments are omitted. `<total>` renders as `N+` when the search was killed early at its limit, meaning matches beyond it exist but were never counted. `next` is always an exact continuation call fragment such as `limit=200` or `offset=451`, never prose. Untruncated results get no notice. Empty results are standardized: `grep` returns `No matches found`, `find` returns `No files found matching pattern`, `ls` returns `(empty directory)`, and the JSON-format tools return valid JSON with empty arrays and `next` populated.
+Unknown segments are omitted. `<total>` renders as `N+` when the search was killed early at its limit, meaning matches beyond it exist but were never counted. `next` is always an exact continuation call fragment such as `limit=200` or `offset=451`, never prose. Untruncated results get no notice. Empty results are standardized: `grep` returns `No matches found`, `find` returns `No visible files found matching pattern`, `ls` returns `(empty directory)`, and the JSON-format tools return valid JSON with empty arrays and `next` populated.
 
 **Offload on truncation.** When a byte cap cuts collected content, the tool spills its full rendering to the per-session scratch file (`<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt`) and reports the path in the notice, so no collected match, path, or line is ever unrecoverable. Two deliberate exceptions exist: `read` never offloads because the source file is directly re-addressable via `next: offset=N`, and a bare item-limit truncation without a byte cut continues via `next` alone, since an offload would only duplicate the body.
 
@@ -179,25 +181,31 @@ Unknown segments are omitted. `<total>` renders as `N+` when the search was kill
 {"error":"result exceeded <cap>","offloadPath":"...","next":"..."}
 ```
 
-**One turn budget.** All six envelope tools draw from a single per-turn pool keyed `sessionId:turnId`, default 192KB and configured by `safety.limits.observationBytesPerTurn`. Each call reserves the minimum of its self cap and the remaining budget before doing the work. An exhausted pool short-circuits with an `[observation budget exhausted ...]` notice naming the tool, the subject, and the used/limit sizes, instead of paying for a search whose output could not be returned. A call whose cap was reduced by the pool appends a budget note telling the model to narrow its arguments or continue in a follow-up turn.
+**One turn budget.** All envelope tools draw from a single per-turn pool keyed `sessionId:turnId`, default 192KB and configured by `safety.limits.observationBytesPerTurn`. Each call reserves the minimum of its self cap and the remaining budget before doing the work. An exhausted pool short-circuits with an `[observation budget exhausted ...]` notice naming the tool, the subject, and the used/limit sizes, instead of paying for a search whose output could not be returned. A call whose cap was reduced by the pool appends a budget note telling the model to narrow its arguments or continue in a follow-up turn.
 
-Per-call self caps: `read` 50KB (`safety.limits.readBytesPerCall`), `grep` 16KB for `mode=content` and 8KB for `files`/`count`, `find` 8KB, `ls` 8KB, `code_nav` 16KB, `context` 16KB for docs and library and 50KB for skills/workspace. The registry backstop cap for each envelope tool is its self cap plus 2KB slack, so a tool's own notice with its exact continuation call survives shaping instead of being cut again and replaced by a generic hint; the bootstrap policy assertion fails loudly if a cap ever drops below that.
+Per-call self caps: `read` 50KB (`safety.limits.readBytesPerCall`), `grep` 16KB for `mode=content` and 8KB for `files`/`count`, `find` 8KB, `ls` 8KB, `code_nav` 16KB, `context` 50KB for skills/workspace, `clio_docs`/`clio_library` 16KB, `data` 32KiB, and gateway find 32KiB. The registry backstop cap for each envelope tool is its self cap plus 2KB slack, so a tool's own notice with its exact continuation call survives shaping instead of being cut again and replaced by a generic hint; the bootstrap policy assertion fails loudly if a cap ever drops below that.
 
 Every envelope result carries `details.observation` (`{tool, unit, shownCount, totalCount, shownBytes, totalBytes, truncated, format, next?, offloadPath?, budget?}`) for the TUI ledger, session turns, and observers.
 
 ## Description tiering
 
-Tool descriptions are tiered by how much a wrong call costs. The hot tools the model calls constantly (`read`, `grep`, `find`, `dispatch`) embed their operational contract in the description: caps, modes, ignore semantics, and how truncated results continue. Every other tool carries a one-to-two-sentence statement of what it does, and deep usage guidance lives in the bundled docs corpus ([tool-usage.md](../guide/tool-usage.md)) rather than the prompt prefix, retrievable on demand through `context(scope="docs")`. This keeps the serialized schema block small and byte-stable while still giving the model a path to depth when it needs one.
+Tool descriptions are tiered by how much a wrong call costs. The hot tools the model calls constantly (`read`, `grep`, `find`, `dispatch`) embed their operational contract in the description: caps, modes, ignore semantics, and how truncated results continue. Every other tool carries a one-to-two-sentence statement of what it does, and deep usage guidance lives in the bundled docs corpus ([tool-usage.md](../guide/tool-usage.md)) rather than the prompt prefix, retrievable on demand through `gateway(op="call", capability="clio_docs", args={query: ...})`. This keeps the serialized schema block small and byte-stable while still giving the model a path to depth when it needs one.
 
-## The gateway reservation
+## Direct placement and the capability gateway
 
-`gateway` is a design-reserved name in `src/core/tool-names.ts`, not an implemented tool. The reserved contract sketch is `gateway(op: "find" | "describe" | "call", capability?, args?)`: an MCP/database proxy with one fixed schema, where external capabilities surface through find/describe/call results rather than as per-capability schemas in the prompt prefix. It would carry the network action class and run sequentially. Reserving the name keeps classifiers and profiles from ever assigning `gateway` to a dynamic tool.
+`src/tools/surface.ts` owns placement independently of policy planes. Direct tools are `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`, `context`, `code_nav`, `verify`, `run_script`, and `gateway`, plus all ORCHESTRATE and INTERACT members when their dependencies are bound. Gateway capabilities are `artifact`, `web_read`, `web_fetch`, `git`, `evidence`, `credential_present`, `clio_docs`, `clio_library`, `data`, extension commands, and trusted local MCP tools. The permanent context schema retains only workspace, skills, and recall.
+
+`gateway(op="find"|"describe"|"call", capability?, query?, args?)` is read class and sequential. Its inner call runs through canonical registry admission with the capability's own class, skill restrictions, approvals, and cancellation. Nested accounting counts the model call once. `effectiveToolCall` restores capability identity for artifact folding, mutation observers, path indexing, exported evidence, and transcripts. Terminal artifact results, images, and details survive routing. Gateway placement changes schema attachment, not authority or evidence.
+
+Native worker recipes continue to name capabilities such as `git`; `effectiveToolNames` adds `gateway` to the attached and attested direct projection while preserving the admitted capability allowlist for inner calls. Find and describe use that allowlist too. MCP sources are session-owned and are not installed into worker registries in this release.
+
+The recorded prompt fixture measured **31,272 bytes across 19 attached tools**, using `wireParameterSchema` and JSON serialization of name, description, and parameters. It excludes optional `ask_user` and `panes`. The historical full-surface figure was a different surface; a post-change full-surface total was derived by adding schemas, not measured. These figures do not establish an overall schema-size reduction. The placement decision and new contracts should be assessed independently of that incomparable total.
 
 ## Context protection
 
 Clio uses two context-protection mechanisms.
 
-1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ledger` uses 16KB; `panes` uses 8KB; `limitation` and `decide` use 4KB; and `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`, `evidence`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
+1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ledger` uses 16KB; `panes` uses 8KB; `limitation` and `decide` use 4KB; and `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`, `evidence`) use 16KB at the registry boundary. MCP capability results are bounded to 16KB in model context, offloading larger results to disk artifacts with preview and reference. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
 2. Auto-compaction uses one pressure threshold. The default threshold is 0.8. When pressure crosses the threshold, Clio first applies a non-destructive working-set eviction and records the evicted items in the session ledger. If pressure remains above the threshold, it runs the LLM summary compaction path and replays from the compacted session view. The older destructive observation/thinking mask is available only as a compatibility escape hatch when `CLIO_CODER_LEGACY_MASK=1`.
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the LLM summary path directly.
@@ -214,12 +222,14 @@ For aggregate cost and token facts across sessions, use `clio-coder usage report
 
 ## Self-documentation retrieval
 
-`context(scope="docs")` is the model-facing companion to `clio-coder docs`, which opens the human documentation in the unified web app. The app renders the bundled Markdown corpus directly, with generated navigation and heading outlines. The docs scope indexes that same corpus for agents. It is deterministic and offline: no embeddings service, network call, or filesystem write is needed.
+`gateway(op="call", capability="clio_docs", args={query: ...})` is the model-facing companion to `clio-coder docs`, which opens the human documentation in the unified web app. The app renders the bundled Markdown corpus directly, with generated navigation and heading outlines. The clio_docs capability indexes that same corpus for agents. It is deterministic and offline: no embeddings service, network call, or filesystem write is needed.
 
 The search index splits markdown into heading-delimited sections, records heading breadcrumbs and line ranges, and ranks results with light stemming, controlled Clio vocabulary aliases, phrase boosts, and BM25-style body scoring. The tool returns compact JSON containing corpus metadata, normalized and expanded query terms, and ranked hits with `file`, `heading`, `breadcrumb`, `anchor`, section `lines`, `snippetLines`, a bounded `snippet`, `matchedTerms`, `signals`, `coverage`, and `score`. `limit` defaults to 5 sections and caps at 12. The per-file filter the pre-consolidation docs tool accepted was dropped; narrow with more specific query terms instead. Even an empty result is valid JSON with empty arrays and a populated `next` continuation.
 
 ## Edit matching safety
 
+Files over 1 MiB use exact matching only. Mixed or bare-CR endings, NUL bytes, and invalid UTF-8 are refused. Publication is atomic through the shared real-target publisher; file identities do not lock external writers. Diffs are skipped when either version exceeds 1 MiB.
+
 The `edit` tool first attempts exact matching. If the model's old text differs
 only by normalized quote, dash, whitespace, or indentation details, Clio maps
 the normalized match back to the original line span and splices only the

package/docs/architecture/safety-model.md

@@ -113,25 +113,26 @@ Escalation can never hang a run. Every escalated ask resolves by an operator dec
 ## Operating Posture and Visible Tools
 
 Clio operates under a single operating posture. The canonical catalog contains
-24 built-in tools organized in seven planes; each plane is one policy unit for
-action class, size posture, and concurrency, asserted at bootstrap by
+30 built-in tools organized in eight planes; per-tool action class, size posture,
+and concurrency are asserted at bootstrap by
 `src/tools/policy.ts` so the classifier and registered specs cannot drift apart
 silently. Dependency wiring, target capability, worker profile, and recipe
 policy determine which subset is visible in a particular context.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
-| OBSERVE | `evidence`, `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | `read` |
+| OBSERVE | `evidence`, `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present`, `clio_docs`, `clio_library`, `data` | `read` |
 | MUTATE | `write`, `edit` | `write` |
-| EXECUTE | `bash`, `verify` | `execute` |
+| EXECUTE | `bash`, `verify`, `run_script` | `execute` |
 | EXECUTE | `git` | `read` |
 | ORCHESTRATE | `dispatch`, `steer` | `dispatch` |
 | ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes`, `limitation`, `decide` | `read` |
-| RETRIEVE | `web_fetch` | `read` |
+| RETRIEVE | `web_read`, `web_fetch` | `read` |
 | INTERACT | `ask_user` | `read` |
 | ARTIFACT | `artifact` | `write` |
+| GATEWAY | `gateway` | `read`; inner capability retains its own class |
 
-`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. `evidence` reads canonical evidence bundles, trust status, gate decisions, and findings; it touches no workspace, and it is sequential because `run` mode may materialize a bundle under Clio's data directory. `limitation` records a typed receipt of what a turn could not verify and why; it touches no filesystem and runs no shell, so it is read class and parallel. `decide` appends the model's own design decision, with its rejected alternatives and rationale, to the session decision board; dispatch seals every active decision's ref onto the run envelope and receipt, and commit seams write them as `Clio-Decision:` trailers. It is read class and sequential. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
+`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. `evidence` reads canonical evidence bundles, trust status, gate decisions, and findings; it touches no workspace, and it is sequential because `run` mode may materialize a bundle under Clio's data directory. `limitation` records a typed receipt of what a turn could not verify and why; it touches no filesystem and runs no shell, so it is read class and parallel. `decide` appends the model's own design decision, with its rejected alternatives and rationale, to the session decision board; dispatch seals every active decision's ref onto the run envelope and receipt, and commit seams write them as `Clio-Decision:` trailers. It is read class and sequential. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is registered and exposes secondary capabilities through find, describe, and call; placement is independent of action class.
 
 Target capability, dispatch tool profiles, and recipe constraints can further narrow the tools available to a run. That narrowing is convenience and budget control; safety still lives in code gates.
 
@@ -141,6 +142,18 @@ The `/view` workspace category treats a recorded successful write as a durable f
 
 ---
 
+## Gateway, local MCP, and script execution
+
+Gateway calls use the same registry admission as direct calls. The outer read-class routing operation does not authorize its inner capability: safety, autonomy, skill restrictions, and approvals use the inner tool's identity and class. Evidence, mutation observers, and terminal artifact handling recover that identity through `effectiveToolCall`. Native worker attestation substitutes the direct gateway schema for admitted secondary schemas while preserving the capability allowlist. `web_read` is GET-only and read class; `web_fetch` retains outward classification for non-GET requests or a body. Gateway MCP capability results are bounded to 16 KiB in model context, offloading larger responses to external artifacts with preview and reference.
+
+Local stdio MCP uses user `<config>/mcp.yaml` and project `.clio-coder/mcp.yaml`. User declarations are trusted by authorship with action class `unknown`; project declarations cannot launch until the operator runs `clio-coder mcp trust <id>` or `/mcp trust <id>`. The user-owned `mcp-trust.json` binds the canonical project root, id, and declaration digest to `read`, `execute`, or `unknown` (default). Changing command, args, cwd, env, or timeout makes trust stale. The server's own annotations do not choose its action class. Execute-class MCP projects its launch vector through Bash policy; unknown remains subject to unknown-action admission. Launching a trusted server through the gateway is not OS sandboxing. See [configuration and caps](../guide/configuration-reference.md#local-stdio-mcp-configuration-and-trust).
+
+MCP discovery cancellation closes its shared connection and rejects waiters; it does not silently restart that server during the session. Session shutdown awaits the shared close promise. The client owns process-group signalling and the synchronous `killOwnedOnExit()` backstop; retained PIDs or pending teardown records do not confer ownership. Cleanup begins at leader exit or explicit close, sends TERM, waits 3000 ms, sends KILL if needed, and bounds confirmation at 2000 ms. Incomplete cleanup is recorded and reported. ESRCH permanently releases the group, including before the asynchronous teardown result settles; later close or exit hooks never signal it again.
+
+`run_script` projects interpreter argv and cwd through Bash admission, then uses safe-exec's streaming sink. Its declared inputs and outputs describe provenance, not filesystem isolation. Script/interpreter paths and cwd checks constrain the launch request; the process can still access what its OS identity permits. There are no implicit installs or retries. Environment values are not written into the run manifest, but argv and log text remain literal and can contain secrets supplied by the script or caller.
+
+Safe-exec owns a bounded original-group cleanup window: TERM, 3000 ms grace, KILL, and 1000 ms confirmation. A separate 1000 ms drain bound begins at leader exit. `cleanupIncomplete` reports surviving original-group members; `pipeDrainIncomplete` reports streams that did not reach EOF, possibly held by escaped processes. The effective `exitCode` changes leader zero to failure for either condition, while `leaderExit` retains the observed process outcome. Cancellation remains active until settlement. Escaped process groups are not contained; logs may be partial and output files may still change. The POSIX probe-to-signal PGID-reuse race remains an accepted residual risk. ESRCH permanently closes ownership; no later timer, cancellation, or exit cleanup reopens it. Windows cleanup is limited to the supported direct-child path.
+
 ## Skill tool surface narrowing
 
 A `SKILL.md` may declare `allowed-tools` and `disallowed-tools`. The declaration is enforced at tool admission, between the safety net and the autonomy mapping, on every surface that activates skills (interactive turns, headless `clio-coder run` turns, and dispatched workers whose recipes declare skills).

package/docs/architecture/session-lifecycle.md

@@ -45,6 +45,11 @@ export interface ClioSessionMeta {
 
 Format version `CURRENT_SESSION_FORMAT_VERSION = 4` (`src/engine/session.ts`) is stamped on all sessions created since the working-set layer landed. Version 4 adds the `contextEviction` and `contextRecall` ledger kinds. `runMigrations` in `src/domains/session/migrations/` performs the one supported additive migration from version 3 to version 4. A missing version or a version below 3 names the remedy (remove the session directory), while a version above 4 says the session was written by a newer Clio and must not be read by this build.
 
+Session admission checks metadata format before any recovering ledger read. It
+validates replay entries before parking the current session. Required headerless
+ledger normalization must succeed before reopened candidate metadata is published;
+a refused candidate leaves the current session usable.
+
 ---
 
 ## 3. Append-Only Context Ledger (`current.jsonl`)
@@ -63,7 +68,7 @@ The first line of `current.jsonl` is the canonical session header:
 
 Subsequent lines represent typed `SessionEntry` objects (`src/domains/session/entries.ts`):
 
-1. **`message`**: User inputs, assistant responses, and tool calls/results.
+1. **`message`**: User inputs, assistant responses, and tool calls/results. User turn payloads carry the prompt `text` sent to the model, and may carry `operatorText` (the raw input before scaffold expansion) and `displayText` (the literal editor input when a prompt template or command expansion replaced it, rendered by the session picker and transcript replay).
    ```typescript
    export interface MessageEntry {
      kind: "message";
@@ -85,8 +90,9 @@ Subsequent lines represent typed `SessionEntry` objects (`src/domains/session/en
 ### Write Durability & Atomicity
 
 - Appends hold an open `O_APPEND` file descriptor across the writer lifetime (`src/engine/session.ts:openSync`).
-- Each line append is executed via a single `write(2)` call.
-- `fsyncSync` is debounced during high-frequency streaming turns and unconditionally forced on checkpoint (`persistTree`) and session shutdown (`close`).
+- A complete UTF-8 line is written before its entry or tree node is acknowledged. Legal short writes continue from the remaining byte offset. Zero progress or a write error fails the append and attempts to truncate its partial bytes back to the previous length; rollback and cleanup failures retain their causes.
+- `fsyncSync` is debounced during high-frequency streaming turns and forced for pending ledger writes on checkpoint (`persistTree`), explicit flush and session shutdown (`close`). A failed append retains the flush obligation for previously accepted bytes and rollback changes even when its descriptor is retired. Explicit flush failures remain visible and retryable.
+- Atomic ledger replacements complete, flush and close their temporary file before publication. An incomplete replacement leaves the previous canonical ledger in place. These guarantees retain the existing single-owner assumption; they do not introduce cross-process locking or a transaction across all session files.
 - Torn last lines resulting from abrupt system crashes or power losses are tolerated by the ledger reader (`src/engine/session.ts:readSessionFileEntries`), which logs a warning and skips the incomplete trailing record.
 
 ---
@@ -207,7 +213,7 @@ An explicit path ending in `.md` keeps the plain Markdown form: a heading, UTC e
 
 ## 7. Directory Handbooks and Project Overrides
 
-During session context loading, `loadProjectContextFiles` (`src/domains/context/clio-md.ts`) captures readable authored Markdown from root `CLIO-CODER.md` handbooks and directory-scoped `CLIO-CODER.override.md` files. Optional structured projections do not determine source acceptance. Init, refresh, and reset invalidate captured session inputs; refresh preserves handbook bytes. Preload is bounded to 8,000 UTF-16 units and 220 rendered lines, with exact safe prefixes and capability-aware omission notices naming source paths and line ranges. Captured-source hashes are retained separately in accounting/manifest metadata. Tools-disabled targets cannot retrieve omitted suffixes through session tools; ordinary reads retrieve current content and retain their independent byte and 20 MB file limits:
+During session context loading, `loadProjectContextFiles` (`src/domains/context/clio-md.ts`) captures readable authored Markdown from root `CLIO-CODER.md` handbooks and directory-scoped `CLIO-CODER.override.md` files. Optional structured projections do not determine source acceptance. Init, refresh, and reset invalidate captured session inputs; refresh preserves handbook bytes. Preload is bounded to 8,000 UTF-16 units and 220 rendered lines, with exact safe prefixes and capability-aware omission notices naming source paths and line ranges. Captured-source hashes are retained separately in accounting/manifest metadata. Tools-disabled targets cannot retrieve omitted suffixes through session tools; ordinary reads retrieve current content through bounded text windows, with per-call byte limits, a 32 MiB exact line-count budget, and a separate 20 MB (20000000 bytes) image ceiling:
 - An override handbook replaces inherited project instructions for its directory and all subdirectories, establishing an explicit subtree boundary.
 - Sibling directories remain unaffected.
 - Subdirectories within the subtree may supply narrower instructions with additional override files.

package/docs/architecture/tui-design.md

@@ -24,6 +24,8 @@ The governing principle: **the user reads state from color, structure from frame
 
 Preview budgets count terminal rows **after wrapping**, including the `/view` overflow hint, and shrink on short terminals. Reasoning previews retain the newest text when streaming stops. Detailed remains bounded: a successful `cat` or file read cannot fill the transcript with the entire file.
 
+Detailed worker activity puts `now:` operations before newest-first `last:` calls; settled entries do not advertise stale current work. Pending checkpoint questions remain visible even in Compact.
+
 Use **/view transcript** to select full available reasoning, tool arguments/results, local shell output, or worker details. Search the list, press Enter to inspect, and Escape to return. Offloaded tool and dispatch output remains available in the other `/view` categories; missing or truncated captured content is identified. Inspection applies secret redaction, and `!!` output remains excluded from model context.
 
 Output style changes presentation only. **Shift+Tab** still changes the model's thinking effort. It does not reveal unavailable reasoning; Clio shows only reasoning supplied by the provider. The previous Alt+R, Alt+P, and expand-all rendering shortcuts are retired. `/output` now explains how to reach Alt+O and Settings. Existing `minimal`, `default`, and `verbose` preferences map to `compact`, `standard`, and `detailed` without rewriting other preferences.
@@ -110,7 +112,7 @@ Standardized formatters live in [src/interactive/theme/labels.ts](../../src/inte
 - **Duration**: `formatCompactMs` is the unified duration formatter, yielding compact outputs (`860ms`, `4.2s`, `42s`, `1m36s`).
 - **Token Counts**: `formatFooterTokens` formats footer and chip counts (`842`, `12.4k`, `1.2M`). Full numeric strings via `toLocaleString` are reserved for detailed tables like the context legend.
 - **Cost**: The shared `formatUsd` formatter handles dollar values, printing up to four decimal places when under one cent.
-- **Model IDs**: `abbreviateModelId` keeps whole dash-separated parts of model names up to 18 characters; if the parts still overflow, it clips the ID at 18 characters.
+- **Model IDs**: `abbreviateModelId` fits the model label to 24 terminal cells, allocating space to the model family and suffix before shortening its placement prefix. It preserves complete graphemes and marks omissions with `…`. The hydrated presentation passes raw, structured target/model fields through the editor callback; the composer formats them once at its actual width, retaining the full route when it fits and letting placement yield to target, family and variant when it does not. Raw identity and workspace text is sanitized before width measurement or grapheme splitting, so OSC/CSI payloads and control bytes cannot become visible label fragments. Abbreviations are display labels; full routes remain available in model/settings inspection and Fleet Runs detail.
 
 ---
 
@@ -141,7 +143,7 @@ Overlay frames share the island's top border rules and include keyboard shortcut
 └─ [Tab] mode · [Esc] close ─────────────────┘
 ```
 
-Fleet run cards add two bounded budget rows when native dispatch admission supplies an envelope. The `policy` row shows the recipe default or exact pin, its optional maximum, and the invocation request. The `budget` row shows the effective phase, the operator lifetime cap, and the clamp or retry/revision escalation reason. Historical or external-agent rows without this provenance omit both rows.
+Expanded Fleet run cards show available policy and budget details when native dispatch admission supplies an envelope. These values wrap and may occupy several rows; the default card omits them. The `policy` row shows the recipe default or exact pin, its optional maximum, and the invocation request. The `budget` row shows the effective phase, the operator lifetime cap, and the clamp or retry/revision escalation reason. Historical or external-agent rows without this provenance omit both rows.
 
 ### 4.3 Section Headers
 
@@ -256,10 +258,10 @@ contracts: `tests/extended/welcome-boot-header.test.ts`.
   any handler appends transcript output, on all three submit paths (ordinary
   submit, admission of a queued boot submission, interrupt-submit). `/new`
   returns to the launchpad. `/resume`, `/tree`, `/fork` and `/handoff` collapse
-  it, so a rebuilt transcript is never shown under fresh-start onboarding, and
-  `clio-coder --continue` / `--session <id>` opens directly in the collapsed
-  header once `session.resume()` has actually succeeded. Transitions are
-  idempotent.
+  it after a successful session transition, so a rebuilt transcript is never
+  shown under fresh-start onboarding. Interactive resume starts inside the app
+  with `/resume`; `--continue` and `--session <id>` belong to the headless
+  `clio-coder run` command. Transitions are idempotent.
 
 - **No filesystem work on the render path**, in any state, including the first
   frame and render-cache hits. Project-context state comes from the context
@@ -296,14 +298,14 @@ Starting Clio · you can type now
   - `FOLLOW-UP` (muted) while Clio is actively processing a run.
   - `STEER` (neon orange) when Enter will actively steer in-flight work.
   - When the draft scrolls, the active mode folds into the scroll indicator row so the orange warning remains visible.
-- **Top Rail Metadata**: The top rail right displays target/model and thinking level with two-step color hierarchy: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
+- **Top Rail Metadata**: The top rail right displays target/model and thinking level. Narrow labels budget target and model separately, for example `blade… · qwopus3.…dense-q6 · low`, so the gateway does not consume the model family or variant. Thinking levels use a two-step color hierarchy: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
 - **Empty-State Placeholder**: Displays dim prompt `Ask Clio…  / for commands`.
 - **Lower Rail Affordance**: On terminals at or above 60 columns, the bottom rail displays `Enter send · Ctrl+J newline` (or resolved keybindings).
 
 ### 5.3 Progressively Disclosed Footer
 
 - **Compact Mode (Quiet Idle)**: Two always-on lines that eliminate idle telemetry noise (suppresses `tools none`, `◌ idle`, and duplicate turn receipts):
-  - **Line 1 (Workspace & Readiness)**: CWD path, git branch/dirty state, and active phase pill only when meaningful.
+  - **Line 1 (Workspace & Readiness)**: CWD path, git branch/dirty state, and active phase pill only when meaningful. Long workspace parents and branch decoration yield before current activity; the workspace suffix and live worker count remain visible at narrow widths, including while the main agent is idle.
   - **Line 2 (Context & Style)**: Context window meter, Output style, and session cost.
 - **Expanded Mode (`Alt+U`)**: Four responsive sections ordered by operational urgency rather than a static telemetry grid:
   1. `Activity`: Live agent phase, active workers, running tool calls.
@@ -360,9 +362,16 @@ The right-hand label shows `model · thinking`. Thinking level colors map as: `o
 ### 6.5 Transcript Notices
 Replay and system tags (e.g. `[retry]`, `[model]`) are wrapped in `dim` brackets with a `muted` message. Retry tags use `warning` amber.
 
+Provider failures use a bounded, sanitized diagnosis in the primary transcript,
+retaining available HTTP status and actionable route advice. Provider retry labels
+identify their layer; running and waiting phases do not repeat the same error body.
+Live and replay previews use the current terminal height and output-style row
+budget. `/view transcript` and export retain the available redacted diagnostic;
+upstream SDK truncation cannot be undone by the presentation layer.
+
 ### 6.6 Output Style Receipts
 
-Compact omits the separate turn receipt. Standard shows a small completion line with available duration. Detailed includes model calls, input/output tokens, cache usage, and supplied reasoning usage with provenance. Reasoning text is an excerpt, not verification. The quiet footer keeps the style and session cost visible; detailed telemetry is available through Detailed or the expanded dashboard.
+Compact omits the separate turn receipt. Standard shows a small completion line with available duration. Replay treats tool-use messages as intermediate; they cannot create a successful receipt on an earlier failed or cancelled turn. Detailed includes model calls, input/output tokens, cache usage, and supplied reasoning usage with provenance. Reasoning text is an excerpt, not verification. The quiet footer keeps the style and session cost visible; detailed telemetry is available through Detailed or the expanded dashboard.
 
 ### 6.7 Code Ink (Syntax Highlighting)
 
@@ -414,12 +423,14 @@ The `/settings` overlay is a full-screen transactional control center:
 
 ### 7.2 Fleet Runs Board
 
-The `Alt+W` board renders one card per run from the observability run projection, which owns lifecycle, worker progress, receipt trust, retries, cancellation, fleet positions, and evidence readiness; the board owns only ordering, selection, and rendering. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
+`/fleet` and `Alt+W` open Fleet Runs; `/settings fleet` opens fleet configuration. The board consumes the observability run projection, which owns lifecycle, worker progress, receipt trust, retries, cancellation, fleet positions and evidence readiness. The board owns selection and rendering; council members remain grouped in a council card.
+
+An ordinary card defaults to run identity, abbreviated route, a task preview, status, trust/evidence, telemetry and one current-operation row when available. A long task keeps two wrapped rows plus an Enter-detail disclosure. Fleet phase appears only when the run has a recorded fleet position. Route abbreviation preserves its distinguishing suffix. Retry, control and evidence warnings remain visible when present. An ordinary completed, sealed and mediated run with no validation or independent review shows `unverified; no validation observed` in its compact trust row. Enter restores every canonical provenance clause. This shortening applies only when context is recorded and completion evidence is absent; exceptional, unknown or failed states keep the full trust summary visible. Execution completion and receipt sealing do not establish scientific validation.
 
-- **`doing`**: the phase (`◐ thinking` in `reason`, `◑ writing` in `accent`, `⚙ tool` in `action`, `◔ waiting` in `info`) followed by the running call as `<tool> <verb> <object>`, or the last finished call as `last <tool> <verb> <object>`. The verb and object come from a descriptor composed at the worker seam; raw arguments never reach the renderer.
-- **`answer`**: the newest rows of the worker's bounded prose on a `│` rail with a hanging indent under the key, then a dim row naming the lines and bytes the bounds refused and the `/view dispatch:<runId>` deep link.
+- **`doing`** shows `now <tool> <verb> <object>` for the current call. Between calls it can show the worker phase and `last <tool> <verb> <object>` for its most recent completed call. Descriptors come from the worker seam; raw arguments never reach the renderer. A thinking phase exposes no reasoning text.
+- **Enter detail** restores the full wrapped route and task, exposes policy and budget facts, and adds the available answer. The answer uses a `│` rail, retaining up to six wrapped prose rows plus an overflow disclosure for omitted lines/bytes and the `/view dispatch:<runId>` inspection route. This cap applies to the answer preview, not to the complete expanded card. Recognized complete results use the same readable contract presentation as the transcript only when an integrity-verified receipt supplies the declared kind and passing conformance. Partial, malformed, unknown or nonconforming output remains an honest excerpt. Contract conformance does not imply validation; reproduction and other qualification facts remain visible, and inspection retains the available raw output.
 
-Wrapping happens before the row cap, so the block is at most six rows tall at any width and a streaming answer cannot make the card grow under the operator. Detail follows the cursor rather than pinning to a run, and closing the board closes it. Reasoning text is never rendered; the `thinking` phase word is the whole of what the board says about it.
+Detail follows selection rather than pinning to a run. Empty boards show `Use /run or /delegate to start a run.` and advertise only closing. Narrow active hints prioritize supported steering and cancellation over navigation/detail hints; Enter remains available to expand. HTTP/SDK runs expose steering only in supported live states, ACP and subprocess runs do not, and terminal rows expose neither steering nor cancellation.
 
 ### 7.3 Task and Decision Boards
 
@@ -431,6 +442,18 @@ Wrapping happens before the row cap, so the block is at most six rows tall at an
 - **Grouped Palette**: Typing `/` opens a grouped command palette (ordered by `Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints and formatted descriptions.
 - **One Canonical Spelling**: Autocomplete, help, and parsing expose the same unique slash-command names; no alias rows compete with canonical commands.
 
+### 7.5 View Artifact Inspection
+
+View uses explicit list/preview focus labels and match/total counts. Search requires every whitespace-separated term to occur literally, case-insensitively, in resource identity or available provenance; paths remain intact terms. Category prefixes such as `dispatch:<runId>` constrain the same search. Left/Right selects among nonempty categories in the current results; it does not remove the filter. Filtering does not change provider scope or discard global evidence. Initial query editing starts at the end, and selection is retained by resource identity across refresh. Filters persist within one overlay lifetime. In list focus, Ctrl+U uses Input's semantic clear operation without synthesized movement keys: it saves one undo snapshot and the complete killed value, so undo restores query and cursor and yank can restore the full query. Clearing an empty filter changes neither history nor the kill ring.
+
+Workspace outputs lead with their basename and workspace-relative path. In preview, `i` toggles scrollable provenance including the full backing path and available session, run and correlation identities; `o` keeps its backing-path notice and `v` retains available verification. Toggling provenance resets that pane's scroll offset. At narrow widths, Enter opens preview and Esc returns to the list before closing; empty results cannot acquire preview focus. Content loading is deferred off the synchronous render stack, and stale loads or refreshes cannot replace newer selection/results.
+
+### 7.6 Library Browsing and Notices
+
+Library status and footer counts distinguish Browse packages, Installed entries and inspected members, with correct singular/plural forms, separately from discovery notices. From browse focus, `n` opens the searchable child notice view and returns from it to resources. While search has edit focus, `n` is filter text; Esc clears a filter or leaves search focus before returning to the parent browser. Returning restores the original browser's selection, filter draft, browse focus and detail position. Notices retain their individual evidence and offer no package mutation or recipe-use action. Count units describe the selected inventory view, not the number of runnable recipes; unavailable Installed entries remain visible.
+
+Agents and Fleets label plugin provider packages as `[plugin]` and show only the selected category's catalog hints. Those hints do not claim a recipe is loaded. `b` switches Browse/Installed; `Actions: User/Project` (or the compact `s:User/Project` label) identifies the destination for package lifecycle actions, not an inventory scope filter. Narrow status lines retain the `n` notice affordance. The selected inspector opens below the split threshold as well as beside the list at wider widths, puts applicable actions before long provenance, and retains Tab and page-scroll navigation. Enter says `members` only when it opens package members, otherwise `detail`. Plain external metadata is sanitized before composition with trusted semantic state colors, so available, unavailable and other states retain their theme styling. All lifecycle actions retain their existing review paths.
+
 ---
 
 ## 8. Shared Vocabulary
@@ -469,7 +492,7 @@ memory ID, and leave approval to the separate reviewed memory lifecycle.
 
 Clio pins pi-tui 0.85.1 with a tracked pnpm patch for one pre-viewport input
 policy, public existing search focus/operations, and semantic Editor/Input
-edits. Production consumes these only through src/engine. The patch adds no
+edits, including atomic Input clear with native undo and kill-ring preservation. Production consumes these only through src/engine. The patch adds no
 renderer, decoder or search implementation. Published dist bundles patched
 JavaScript and the pure JavaScript transitive dependencies; the pinned installed
 Pi package supplies native Darwin/Windows helpers through its package resolver.