@iowarp/clio-coder 0.4.7 → 0.4.9

package/docs/architecture/observability.md

@@ -1,8 +1,5 @@
 # Observability Viewer
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Observability Viewer visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/observability_blueprint.html).
-
 `/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
 ```text

package/docs/architecture/pi-boundary.md

@@ -1,8 +1,5 @@
 # Pi SDK Boundary
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Pi SDK Boundary visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/pi_boundary_blueprint.html).
-
 Clio Coder pins Pi 0.85.1 as its provider, agent-loop, and terminal SDK. This
 page records where Pi owns a reusable primitive and where Clio deliberately
 keeps product behavior. Review this table on every Pi upgrade. An action marked
@@ -111,7 +108,7 @@ else, `src/interactive/**` included, reaches Pi through engine re-exports such a
 graph, alongside five other isolation rules including the Stage 0 instant-shell
 closure (`STAGE_0_OWNER`, `STAGE0_SEAMS`). `tests/contracts/engine-lifecycle.test.ts`
 covers agent-loop ordering, reset, tool-argument normalization, the keybinding
-table and alt-screen render seams; `tests/contracts/tool-boundaries.test.ts`
+table and alt-screen render seams; `tests/extended/tool-boundaries.test.ts`
 covers tool schema admission and execution isolation across runtimes.
 
 ## Pi regression net
@@ -121,11 +118,11 @@ Run these contracts first on a Pi bump, before the full gate:
 - `tests/boundaries/check-boundaries.ts` (static architecture boundaries and Stage 0 seams)
 - `tests/contracts/engine-lifecycle.test.ts` (agent-loop ordering, reset, tool-argument normalization, keybinding table, alt-screen render seams)
 - `tests/contracts/provider-transport.test.ts`
-- `tests/contracts/openrouter-transport.test.ts`
-- `tests/contracts/provider-context-boundary.test.ts`
-- `tests/contracts/rendering-invariants.test.ts`
-- `tests/contracts/gemma-channel-filter.test.ts`
-- `tests/contracts/tool-boundaries.test.ts`
+- `tests/extended/openrouter-transport.test.ts`
+- `tests/extended/provider-context-boundary.test.ts`
+- `tests/extended/rendering-invariants.test.ts`
+- `tests/extended/gemma-channel-filter.test.ts`
+- `tests/extended/tool-boundaries.test.ts`
 - `tests/contracts/session-durability.test.ts`
 - `tests/smoke/process-lifecycle.test.ts`
 

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

@@ -1,8 +1,5 @@
 # Prompt Envelope and Tools
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Prompt Envelope and Tools visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tools_blueprint.html).
-
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 
 Source of truth: `src/core/tool-names.ts`, `src/tools/agent-tools.ts`, `src/tools/bootstrap.ts`, `src/tools/policy.ts`, `src/tools/observation.ts`, `src/tools/ignore-policy.ts`, and the per-tool modules under `src/tools/**`.
@@ -36,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.
 
@@ -59,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.
 
@@ -81,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
@@ -94,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 |
@@ -106,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
@@ -151,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:
 
@@ -172,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.
 
@@ -182,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.
+
+## Direct placement and the capability gateway
+
+`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.
 
-## The gateway reservation
+`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.
 
-`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.
+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.
@@ -217,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 the human `clio-coder docs` server. From a source checkout, the server serves `docs/html/**` blueprints for people; in every installation, the docs scope indexes the bundled Markdown 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/provider-adapter-cookbook.md

@@ -1,8 +1,5 @@
 # Provider Adapter Cookbook
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Provider Adapter Cookbook visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/provider_adapter_blueprint.html).
-
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 
 Source of truth:
@@ -164,7 +161,7 @@ level onto `thinking.type: "adaptive"` plus `output_config.effort` (read from th
 `thinkingLevelMap` and `compat.forceAdaptiveThinking`) or onto a bounded `budget_tokens` for
 budget-based models. Clio's `onPayload` hook no longer rewrites those fields; it only sets the
 OpenAI Responses `reasoning.summary` verbosity, which the agent loop cannot express as an option.
-`tests/contracts/thinking-off-wire.test.ts` locks the local LM Studio and
+`tests/extended/thinking-off-wire.test.ts` locks the local LM Studio and
 llama.cpp controls used when thinking is off. Anthropic request assembly is
 inherited from the pinned Pi dependency; Clio no longer carries a separate
 contract test that reconstructs Pi's whole adaptive or budget payload.

package/docs/architecture/safety-model.md

@@ -1,8 +1,5 @@
 # Clio Coder Safety Model
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Safety Model visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/safety_blueprint.html).
-
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
 Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bootstrap.ts`, `src/tools/policy.ts`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts`, `src/interactive/view/artifacts.ts`, and `damage-control-rules.yaml`.
@@ -116,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.
 
@@ -144,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

@@ -1,8 +1,5 @@
 # Session Lifecycle
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Session Lifecycle visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/session_lifecycle_blueprint.html).
-
 This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in the current source tree.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
@@ -48,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`)
@@ -66,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";
@@ -88,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.
 
 ---
@@ -210,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/time-conventions.md

@@ -1,8 +1,5 @@
 # Time and Clock Conventions
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Time and Clock Conventions visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/time_conventions_blueprint.html).
-
 This document describes the time practices implemented in the current Clio
 Coder source tree. The code distinguishes process-local elapsed spans from
 durable instants, but it does not impose one clock primitive on every module.

package/docs/architecture/trace-store.md

@@ -1,8 +1,5 @@
 # Trace store contract
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Trace store contract visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/trace_blueprint.html).
-
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing
 `<state-dir>/trace.sqlite` loses no authoritative run data.
@@ -99,7 +96,6 @@ clio-coder trace procs <runId> [--db PATH]
 clio-coder trace code-steps <rootId> [--json]
 clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]
 clio-coder trace sql <SELECT query> [--db PATH]
-clio-coder trace ui [--db PATH] [--port N]
 ```
 
 `clio-coder trace --help` and every subcommand `--help` print usage and exit with code 0.
@@ -122,24 +118,36 @@ When resolving the SQLite database path:
 5. **`procs`**: Lists orchestrator and worker process executions associated with a `runId`. Displays state (`live` or `ended`), PID, process kind, name, and command string.
 6. **`prune`**: Applies the resolved age and byte retention policy while protecting queued and running runs. Text and JSON results report the policy, removed runs and rows, physical bytes reclaimed, protected runs, and whether `VACUUM` ran.
 7. **`sql`**: Executes a single read-only `SELECT` or `WITH` SQL statement against the SQLite trace database. The subcommand enforces read-only access before opening storage: queries containing semicolons or data mutation keywords (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, etc.) are rejected with exit code 2. BigInt numbers in result objects format as JSON strings.
-8. **`ui`**: Launches the web-based interactive trace viewer server on the specified `--port` (default 0). This subcommand requires a source checkout containing `apps/trace-viewer/server.mjs`.
 
-### Trace Viewer Surface
+### Unified Web Trace API
 
-The viewer binds to `127.0.0.1` only and serves a read-only JSON API beside the static page:
+The source application in `apps/clio-coder-web/` replaces the separate trace
+viewer. It binds to `127.0.0.1` and requires the per-launch bearer token. The CLI
+trace commands above continue to work independently of the web process.
 
 | Endpoint | Source |
 | --- | --- |
-| `GET /api/health` | Schema version handshake. |
-| `GET /api/runs[?limit=N]` | `runs`, newest first. |
-| `GET /api/runs/:runId` | One `runs` row. |
-| `GET /api/runs/:runId/phases` | `phases`, ordered by `seq`. |
-| `GET /api/runs/:runId/events[?after=cursor&limit=N]` | `events` by rowid cursor, capped at 500 per page. |
-| `GET /api/runs/:runId/gates` | `gate_results`. |
-| `GET /api/runs/:runId/envelopes` | `envelopes`. |
-| `GET /api/runs/:runId/processes` | `processes`. |
-| `GET /api/runs/:runId/receipt` | Sidecars beside the database: `<stateDir>/receipts/<runId>.json` and the matching `<stateDir>/evidence-index.json` row. |
-
-The receipt endpoint derives `<stateDir>` from the directory holding the trace database, since `clio-coder trace ui` reads `<stateDir>/trace.sqlite`. A mirror copied away from its state directory has no sidecars, so a missing, unreadable, or malformed file yields a `null` half with HTTP 200 rather than an error. The response drops `output`, `upstreamResponses`, `routeDecision`, `briefing`, and `steering`: the panel renders provenance, not transcripts.
-
-The run page renders the task request, wall-clock duration, phase description, failure reason and retry count, a chronological log of every event type with its payload, gate verdicts and violations, the run's processes, and a receipt panel covering outcome, verification state and basis, spend, per-tool call statistics, safety counters, findings, and build provenance. Fields the harness never sealed read as absent rather than as zero.
+| `GET /api/traces/status` | Schema and availability status. |
+| `GET /api/traces/runs` | Keyset-paginated runs, with source and text filters. |
+| `GET /api/traces/runs/:runId` | One run. |
+| `GET /api/traces/runs/:runId/phases` | Phases ordered by sequence. |
+| `GET /api/traces/runs/:runId/events` | Rowid-cursor event history. |
+| `GET /api/traces/runs/:runId/live` | SSE event tail. |
+| `GET /api/traces/runs/:runId/gates` | Gate results. |
+| `GET /api/traces/runs/:runId/envelopes` | Trace envelopes. |
+| `GET /api/traces/runs/:runId/processes` | Process records. |
+| `GET /api/traces/runs/:runId/receipt` | Receipt and evidence-index sidecars. |
+
+The receipt endpoint reads sidecars beside the database. Missing or malformed
+sidecars yield a null half without failing the run page. The default projection
+omits `output`, `upstreamResponses`, `routeDecision`, `briefing`, and `steering`;
+`?include=full` explicitly requests the full receipt. The authenticated operator can
+inspect trace payloads. The browser renders all model content through its safe
+rich-content renderer.
+
+The run page shows the request, phase waterfall, duration, costs, events with
+payloads, gate decisions, processes, and receipt provenance. Unrecorded fields
+remain absent rather than becoming zero. The typed route table and OpenAPI in
+`apps/clio-coder-web/contracts/` define query parameters and response schemas.
+
+The shared `TraceReader.runsPage({before, limit, filter})` seam owns run-list pagination for the web API. It orders by `started_at DESC, run_id DESC`, returns a bounded page and `nextBefore`, and combines source, status, and search filters with bound SQL parameters. A read-only legacy database derives `source` without a migration. The app validates and encodes the cursor; it does not duplicate pagination SQL.