@iowarp/clio-coder 0.4.6 → 0.4.8

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/**`.
@@ -42,11 +39,11 @@ Prompt extensions can add dynamic fragments for project rules, the operator prof
 
 ## Prompt template expansion
 
-Prompt templates expand into the operator's user message before submission. They do not alter the compiled system prompt or bypass the trust check on project-scope compatibility roots. The prompt-root locations, frontmatter fields, and trust rules are documented in [extensions-and-sharing.md](../guide/extensions-and-sharing.md#prompt-templates).
+Ordinary prompt templates expand into the operator's user message before submission. They do not alter the compiled system prompt or bypass the trust check on project-scope compatibility roots. As an explicit exception, display-only templates (`display-only: true`) render directly to the transcript as local operator cards without consuming tokens or being sent to the model. The prompt-root locations, frontmatter fields, and trust rules are documented in [extensions-and-sharing.md](../guide/extensions-and-sharing.md#prompt-templates).
 
 The first whitespace character after `/template-name` is the command delimiter; CRLF counts as one delimiter. Leading whitespace before the slash is also command framing. Every byte after that delimiter is the argument payload, including leading or trailing whitespace, repeated spaces, tabs, quotes, and line breaks.
 
-The template body may use `$ARGUMENTS` to insert that raw payload byte-for-byte. Raw insertion is not recursively substituted, so placeholder-like text such as `$1` remains data. `$1` through `$9`, `$@`, `${@:N}`, and `${@:N:L}` retain shell-style parsing: single or double quotes group spaces within one argument, `$@` joins all parsed arguments with single spaces, `${@:N}` selects parsed arguments from one-based position `N`, and `${@:N:L}` selects `L` arguments beginning there. A positional placeholder with no matching argument expands to an empty string. Template names that collide with built-in slash commands fail closed with a diagnostic and are excluded from `/resources prompts`.
+The template body may use `$ARGUMENTS` to insert that raw payload byte-for-byte. Raw insertion is not recursively substituted, so placeholder-like text such as `$1` remains data. `$1` through `$9`, `$@`, `${@:N}`, and `${@:N:L}` retain shell-style parsing: single or double quotes group spaces within one argument, `$@` joins all parsed arguments with single spaces, `${@:N}` selects parsed arguments from one-based position `N`, and `${@:N:L}` selects `L` arguments beginning there. A positional placeholder with no matching argument expands to an empty string. Template names that collide with built-in slash commands fail closed with a diagnostic and are excluded from `/prompts`.
 
 ## Directory-scoped handbook overrides
 
@@ -151,9 +148,9 @@ 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"|"recall")` observes the session workspace snapshot, bundled documentation (omit `query` to list the corpus), skills (`name` optional, `include_tree` for resources), or persisted historical tool results. In recall scope, provide `ref` for exact retrieval or omit it for discovery with `query`, `limit`, and `offset`.
+- `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 written with the ordinary write tool and validated by the skills loader.
+- `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.
 - `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.
@@ -184,7 +181,7 @@ Unknown segments are omitted. `<total>` renders as `N+` when the search was kill
 
 **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.
 
-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 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` 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.
 
 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.
 
@@ -217,7 +214,7 @@ 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.
+`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.
 
 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.
 

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`.
@@ -86,6 +83,25 @@ graph TD
 
 Net `confirm` is never auto-allowed by autonomy, including full-auto. Net `block` is never downgraded by anything. A tool hidden by target capability or explicit suppression is not shown to the model; a tool that is shown still must pass this path before it can run.
 
+### Interplay of autonomy, protected paths, and one-shot permission approval
+
+The three enforcement layers interact with strict precedence to ensure safety invariants cannot be bypassed:
+
+1. **Zero-access protected paths outrank all autonomy levels**:
+   - Zero-access paths (including `.git/config`, `credentials.yaml`, `.env`, and sensitive SSH keys) are hard-blocked by the safety net with canonicalized symlink path resolution.
+   - Even `full-auto` autonomy cannot read, write, or modify zero-access paths; `block` verdicts are final and never park for approval cards.
+   - Built-in path protections cannot be overridden by malformed or permissive project `.clio-coder/safety.yaml` rules.
+
+2. **One-shot permission approval cards**:
+   - When an action requires operator consent (under `suggest` for writes and commands, under `auto-edit` for unrecognized bash, or at any autonomy level for `system_modify` confirm rails), Clio pauses execution and displays a focused interactive permission card.
+   - Operator approval is strictly **one-shot**: approving a command or write grants authority *only* for that single execution instance. It does not grant blanket approval for future calls, does not loosen the active autonomy level, and cannot downgrade safety-net blocks.
+   - In headless mode, calls requiring interactive permission fail closed immediately.
+
+3. **Worker escalation and autonomy boundaries**:
+   - Dispatched workers run non-interactively and inherit the resolved execution autonomy.
+   - When a worker encounters a permission gate, `fleet.permissions.mode` dictates whether it fails immediately (`fail`), returns a structured rejection (`deny`), or parks and escalates (`escalate`).
+   - Under `escalate`, the parked call emits a `clio_coder_permission_escalated` event to stdout, which surfaces in the interactive orchestrator as an operator permission card. No model-facing tool can approve a worker permission; approvals are human-only.
+
 ### Worker permission escalation
 
 Dispatched workers run non-interactively, so step 3 resolves per `fleet.permissions.mode`: `deny` turns the parked call into a structured denial, `fail` ends the run, and `escalate` hands the ask up to the interactive operator. Under `escalate` the worker parks the call, emits a `clio_coder_permission_escalated` event, and waits; dispatch republishes the ask on the bus tagged with the run id; the operator resolves it in the same permission overlay used for the main agent; and the decision returns down the worker's stdin. Resolution is human-only by construction: no model-facing tool can approve a worker permission, and the dispatch `resolveWorkerPermission` method is reachable only from the interactive layer. This preserves the receipt's honesty, since a model approving its own fleet's asks would collapse the audit trail.
@@ -263,7 +279,7 @@ Prefer typed tools over Bash:
 - `verify(check="<id>")` runs either a declared package.json verification script (the `test*/lint*/build*/typecheck*/check*/format*/ci*` family) or an exact version-1 `.clio-coder/verifiers.yaml` argv vector through bounded execution helpers with no shell; `verify()` lists both sources through one canonical check projection.
 - `verify(check="frontend", path=...)` validates frontend artifacts without granting arbitrary shell access.
 
-A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml`, `.clio-coder/safety.yaml`, `.clio-coder/skills/`, and the user-scoped `<configDir>/skills/` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: these files and skill roots are operator authority, and a model that could author them could change its own permissions or active instructions. Skill installs go through `clio-coder skills install`.
+A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml`, `.clio-coder/safety.yaml`, `.clio-coder/skills/`, and the user-scoped `<configDir>/skills/` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: these files and skill roots are operator authority, and a model that could author them could change its own permissions or active instructions. Creating skills therefore requires authoring outside these protected roots (such as in a staging workspace or package directory) followed by operator installation where needed. Skill installs go through `clio-coder library install`.
 
 The project verifier catalog is an executable authority supplied by the repository, not by model prose. Its schema rejects unknown fields, shell strings, invalid or duplicate IDs, oversized values, absolute or escaping working directories, unsupported versions, and collisions with package-provider IDs. It also refuses the common shell executables (`sh`, `bash`, `zsh`, and the like) as argv[0], which is a tripwire against the obvious mistake rather than a sandbox: `python3 -c`, `node -e`, and `env bash -c` pass the schema, so the authority boundary is the fact that the catalog file is operator-owned and read-only to the model, and that every catalog check is scanned by the damage-control rules and parked at `auto-edit`. A catalog entry fixes argv, repository-relative cwd, and timeout. Tool-call `args`, `cwd`, timeout, output-cap, or environment-shaped fields cannot widen it. Safe-exec uses `spawn` without a shell, filters the child environment to the Clio allowlist, honors cancellation, and reports exact argv and termination evidence.
 
@@ -332,7 +348,7 @@ How an ask resolves depends on the context:
 
 In interactive mode, a permission request opens a queued overlay prompt immediately in the TUI, and the composer rail switches to `CONFIRM` with the same keys for as long as the prompt owns the keyboard.
 - **Queued Overlays:** If multiple tools or worker dispatches require permission during a single turn, the TUI queues the requests. Closing one overlay automatically pops the next permission overlay in the queue. Each queued request retains its consequence tier and authenticated requester. A request that arrives while a different overlay (a picker, `/context`, the fleet board) holds the screen is announced with an `[approval]` notice and re-presented the moment that overlay closes.
-- **Operator Options:** `Enter` grants permission once, which resumes only the parked tool call without changing the overall operating posture; the one-shot grant is scoped to the presented request's `requestId`. `Esc` denies only the presented request and advances the queue; the next parked call re-presents. `s` denies it and ends the turn. Cancel-all is reserved for shutdown, an aborted turn, headless runs, and transport failure, where no operator can answer.
+- **Operator Options:** `Enter` grants permission once, which resumes only the parked tool call without changing the overall operating posture; the one-shot grant is scoped to the presented request's `requestId`. `Esc` denies only the presented request and advances the queue; the next parked call re-presents. `s` denies it and ends the turn. `?` unfolds the standing terms (approval scope, consequence, reversibility, what deny and stop do) that the card otherwise states in one row, and `v` opens a parked write or edit for reading. Cancel-all is reserved for shutdown, an aborted turn, headless runs, and transport failure, where no operator can answer.
 - **Enter never doubles as send:** `Enter` allows only from an empty composer. While the composer holds a draft, `Enter` does nothing, both surfaces say `[Backspace] clear draft` in its place, and only deletion keys reach the editor. An operator who typed a message and pressed the habitual send key cannot approve a parked call by accident; on a safety rail the ambiguous key resolves away from allow.
 
 ### Deterministic Headless Behavior

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/`.
@@ -113,7 +110,7 @@ export interface SessionTreeNode {
 
 ### Active Path Lineage Selection
 
-When an operator branches or switches turns using `/tree` or `Alt+T`, the next append point changes without mutating or deleting historical entries in `current.jsonl`.
+When an operator branches or switches turns using `/tree`, the next append point changes without mutating or deleting historical entries in `current.jsonl`.
 
 The active path filter (`src/domains/session/tree/active-path.ts`) traces ancestry back from the active leaf:
 1. Resolves all `turnId` identifiers tracing back to the root `null` parent.
@@ -187,6 +184,17 @@ When resuming a session via `/resume` or a headless `clio-coder run --session <i
 
 When resumed or forked session history is replayed to the model, compaction summaries, branch summaries, and operator bash executions use standardized user-role text through `src/engine/messages.ts`. Working-set projection runs before compaction counting and summary serialization, while raw ledger entries remain intact. Tool results hidden by summaries are discoverable with `context(scope="recall")` and recoverable by exact ref through the normal observation envelope; older destructive logs cannot recover removed bytes.
 
+## How new sessions, resume and fork differ in history and workspace
+
+Clio provides distinct lifecycle operations for managing conversation continuity, history lineage, and workspace directories:
+
+| Operation | Session ID & Ledger | History Lineage | Workspace (`cwd`) Behavior |
+| --- | --- | --- | --- |
+| **New session (`/new` or fresh launch)** | Mints a new UUIDv7 `<sessionId>` in `<stateDir>/sessions/<cwdHash>/<sessionId>/` with an empty `current.jsonl` containing only the session header. | Starts at turn 0 with a clean context window. Previous session turns, compactions, and memory working sets are not carried forward. Shared project tasks remain accessible on disk in `.clio-coder/user-tasks.json`. | Uses the active process working directory (`process.cwd()`). Computes a fresh `<cwdHash>` for the session directory. |
+| **Resumed session (`/resume <id>`, `--continue`, `--session`)** | Reopens the existing session directory and writer. Continues appending new turns directly to the existing `current.jsonl` ledger. | Reconstructs the exact message history, compaction summaries, task board snapshots (`taskLedger`), and decision board states along the active leaf path (`meta.pinnedLeafTurnId` or latest tip). | Probes recorded `meta.cwd` against the filesystem (`resolveSessionCwd`). If the recorded directory was moved or deleted, triggers the `cwd-fallback` interactive prompt before resuming. |
+| **Forked session (`/fork` or `/tree` branch fork)** | Mints a brand new UUIDv7 `<sessionId>` in a new session directory. Stamps `parentSession` and `parentTurnId` in the new session header. Leaves the parent ledger closed and immutable. | Copies the exact active path lineage up to `parentTurnId` from the parent ledger into the new session ledger, excluding later turns, abandoned sibling branches, and unanchored sidecars. Subsequent turns append only to the new ledger. | Inherits the parent session's `cwd`, `model`, and `target` settings. Operates in the same workspace directory without creating a duplicate disk workspace. |
+| **Handoff (`/handoff <goal>`)** | Mints a brand new session with a new ID. The previous session receives an immutable `handoffNote` entry and closes. | Replaces raw conversation turns with a single synthesized `handoffSeed` context message containing a reviewed distillation of settled decisions and validated read-ledger paths. Loaded skill activations are replayed so skills carry forward. | Operates in the current project workspace directory, carrying forward validated project context while shedding conversation token weight. |
+
 ---
 
 ## 6. Session Export

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.

package/docs/architecture/tui-design.md

@@ -1,8 +1,5 @@
 # Clio TUI Design System
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio TUI Design System visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tui_design_blueprint.html).
-
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../../src/interactive/).
 
 The governing principle: **the user reads state from color, structure from frames, and identity from brand marks.** Everything that is not state or structure remains visually quiet.
@@ -174,7 +171,7 @@ All TUI overlays and cards support compact widths down to 40 columns:
 
 ### 4.7 Decision Consequence Frames
 
-Permission confirmation and `ask_user` use one pure consequence presentation classifier while keeping separate input and execution protocols. The classifier supplies the tier title, semantic frame token, consequence and reversibility copy, requester attribution, and display actions. Permission keeps allow-once, deny, and stop behavior. `ask_user` keeps selection, free-text, cancellation, and its compact, panel, or interview layout chosen from question shape.
+Permission confirmation and `ask_user` use one pure consequence presentation classifier while keeping separate input and execution protocols. The classifier supplies the tier title, semantic frame token, consequence and reversibility copy, requester attribution, and display actions. Permission keeps allow-once, deny, and stop behavior. `ask_user` keeps selection, free-text, cancellation, and a single bottom-anchored, content-sized interview frame sized directly to the round.
 
 | Tier | Title | Token | Plain-text identity |
 | --- | --- | --- | --- |
@@ -193,7 +190,7 @@ The words carry the meaning when color is disabled. Permission copy states the e
 
 The Clio screen maintains a responsive, four-zone structure: the launchpad / session header, transcript, composer, and footer. `interface.mode` chooses the renderer at startup. The default `regular` mode uses terminal scrollback. Opt-in `fullscreen` mode uses the alternate screen: the launchpad/header and transcript occupy an independently scrollable viewport while the follow-up queue, composer, and footer remain docked at the bottom.
 
-In fullscreen mode, `PageUp` and `PageDown` scroll one viewport, `Home` and `End` jump to its bounds, `Ctrl+Shift+Up` and `Ctrl+Shift+Down` jump between semantic prompts, and the mouse wheel scrolls the transcript. Dragging the scrollbar thumb moves the viewport directly. `interface.fullscreenScrollbar` is `hidden`, `auto` (visible during interaction), or `always`. Manual scrolling suspends follow-end so new output does not steal the operator's position; returning to the bottom resumes it. Both fullscreen settings are restart-scoped because Clio constructs its terminal renderer and component graph once at startup.
+In fullscreen mode, `PageUp` and `PageDown` scroll one viewport, `Ctrl+G Home` and `Ctrl+G End` jump to its bounds, `Ctrl+Up` and `Ctrl+Down` jump between semantic prompts; plain Home/End edit the composer, and the mouse wheel scrolls the transcript. Dragging the scrollbar thumb moves the viewport directly. `interface.fullscreenScrollbar` is `hidden`, `auto` (visible during interaction), or `always`. Manual scrolling suspends follow-end so new output does not steal the operator's position; returning to the bottom resumes it. Both fullscreen settings are restart-scoped because Clio constructs its terminal renderer and component graph once at startup.
 
 `interface.smoothStreaming` controls presentation-only pacing of derived assistant text and thinking. The shipped `off` value uses the immediate 16 ms coalescer. `auto` paces only on a capable local TTY and bypasses pacing for non-TTY, SSH, multiplexers, CI, screen-reader/reduced-motion markers, or observed stdout backpressure. `on` explicitly requests grapheme-safe pacing, while still stopping frame production behind stdout backpressure. Raw provider wrappers never enter the panel, canonical events and persistence remain synchronous, and tool/message/turn/abort/retry/submit/teardown boundaries drain visible state before they continue.
 
@@ -201,8 +198,96 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
 
 ### 5.1 Welcome Launchpad & Session Header
 
-- **Pre-Submit Launchpad**: Before the first prompt, renders a compact launchpad at line 0 with bold CAPS section tags (`WORKSPACE`, `ROUTE`, `NEXT`), honest readiness state, and a context-sensitive next action (e.g. `ctx missing · /context init`, `ctx checking…`, or `ctx ready · type a task`). Asynchronous repository probes use height-stable dim placeholders (`factsPending`).
-- **Session Header Collapse**: On first user submission, the launchpad deliberately collapses into an immutable, single-line session header (`>C_ Clio Coder vX.Y.Z · <workspace · git branch> · <target·model · ready> · ctx ready · type a task`) so the conversation transcript owns the viewport while the header keeps naming where Clio works, which route answers, and what the context is ready for.
+The header has two shapes and no box. Source: `src/interactive/welcome-dashboard.ts`;
+contracts: `tests/extended/welcome-boot-header.test.ts`.
+
+- **Launchpad (before the first prompt): exactly three rows.** A masthead with
+  identity flush left and workspace flush right separated by a `frame`-token
+  rule, then the route, then one next step.
+
+  ```
+  >C_ Clio Coder v0.4.7 ──────────────────── ~/iowarp/clio-coder · main*
+    ✓ dynamo · qwen3.8-27b
+    describe a task · Enter to send · / for commands
+  ```
+
+  Under width pressure the identity drops its version, then its name; the
+  workspace drops its branch, then head-truncates the path keeping the leaf
+  (`…/clio-coder`). The product name outranks the version, and the branch is
+  given up before the path's leaf is obscured.
+
+- **Route row.** `✓ <target> · <model>` healthy, `! …` degraded, `✗ …`
+  unavailable, `◌ …` configured but not yet probed, `not configured` when
+  neither is set. A healthy route prints no probe latency; the glyph carries the
+  verdict and `/doctor` owns the timing. A failing route prints its reason,
+  sanitized to one line. The row reserves room for that reason where it can,
+  shrinking the route text to keep it, and drops it only when the width cannot
+  hold even the floors. The action row still names the route problem either way.
+
+- **Action row: one line, chosen by what actually blocks work.** First match
+  wins: no route (`no route selected · /model`), no model
+  (`no model selected · /model`), route unavailable or degraded
+  (`… · /settings targets`), `CLIO-CODER.md` malformed
+  (`CLIO-CODER.md malformed · /context to inspect`), no handbook
+  (`describe a task · /context init to index this repo`), stale handbook
+  (`describe a task · /context refresh to update it`), otherwise
+  `describe a task · <SubmitKey> to send · / for commands`. Missing project
+  context is guidance, not a blocker; the line still invites work. A *malformed*
+  handbook is pointed at inspection rather than regeneration, since the file
+  needs repair before it needs rebuilding. `<SubmitKey>` comes from the live
+  `tui.input.submit` binding and is omitted when that action is unbound.
+
+- **Session header (after the first prompt): exactly one row, and live.**
+
+  ```
+  >C_ Clio Coder v0.4.7 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*
+  ```
+
+  It follows a mid-session model change rather than freezing at collapse. It
+  carries identity, route and workspace and deliberately drops readiness,
+  latency, project-context state and onboarding text, which the footer and the
+  composer rail own. When the row will not fit, the survival order is the `>C_`
+  wordmark, then the route, then the workspace path, then the branch, then
+  `Clio Coder v<version>`. **The route is the last fact given up**, and it
+  outlives the workspace and the product name; below roughly the width of the
+  wordmark itself the row is the truncated wordmark alone.
+
+- **Transitions.** The first submit collapses the launchpad exactly once, before
+  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.
+
+- **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
+  domain's own reader, refreshed off the frame; until the first reading lands
+  the header shows `describe a task` rather than asserting a state it does not
+  know. A read that throws never becomes `ok` or `none` and never renews the
+  trust window, so once reads have been failing longer than the 10s window the
+  header stops asserting the last value, and a reading is only ever served for
+  the directory it was taken in. This is a change to per-frame render I/O; it is
+  not a claim that process startup got faster.
+
+- **Text safety.** Provider reasons, model ids, branch names and paths pass
+  through the project's one-line sanitizer (`sanitizeCallTargetText`,
+  `src/domains/safety/call-target.ts`) before styling: OSC and CSI stripped, C0
+  and DEL neutralized, whitespace collapsed. A hostile upstream error cannot
+  retitle the terminal, clear the screen, move the cursor, or inject colour
+  through the header. Wide Unicode, emoji and ZWJ sequences are preserved and
+  measured in terminal columns.
+
+Stage 0, before hydration, renders the same wordmark helper over three rows so
+the footprint matches the hydrated header, then the editor, then a footer line
+that stays blank until `Ctrl+C` arms the exit:
+
+```
+>C_ Clio Coder
+Starting Clio · you can type now
+
+```
 
 ### 5.2 Composer (ClioEditor)
 
@@ -213,7 +298,7 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
   - 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).
 - **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 · Shift+Enter newline` (or resolved keybindings).
+- **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
 
@@ -226,7 +311,7 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
   3. `Session`: Session cost, throughput, total token breakdown, leader key state.
   4. `Workspace`: CWD, branch, target, git dirty status.
   Empty rows collapse rather than occupying blank grid space.
-- **Notification Badge & Degradation Ladder**: The footer notification badge reserves the severity head (`ℹ 1 notice`, `⚠ 1 warning`, `✗ 1 error`), separator, and `[Alt+X] dismiss` tail first, allocating the middle width to an ellipsized message. At narrow widths, it degrades gracefully down the ladder (`head · [Alt+X] dismiss` → `head · [Alt+X]` → `head` → glyph alone) without clipping the action key.
+- **Notification Badge & Degradation Ladder**: The footer notification badge reserves the severity head (`ℹ 1 notice`, `⚠ 1 warning`, `✗ 1 error`), separator, and `[Ctrl+G x] dismiss` tail first, allocating the middle width to an ellipsized message. At narrow widths, it degrades gracefully down the ladder (`head · [Ctrl+G x] dismiss` → `head · [Ctrl+G x]` → `head` → glyph alone) without clipping the action key.
 
 ### 5.4 State Choreography Table
 
@@ -338,9 +423,9 @@ Wrapping happens before the row cap, so the block is at most six rows tall at an
 
 ### 7.3 Task and Decision Boards
 
-- **Composite Tasks Board (`/tasks`, `Alt+B`)**: Presents four sections in one reopenable overlay: the live session board, terminal task history, successful workspace artifacts, and project-scoped operator tasks. Selecting a workspace artifact opens the filtered `/view` path. Operator rows support add, hand, done, and drop actions; refresh is explicit for captured history and artifacts, while lightweight repaint reads the current board snapshot.
-- **Settled Decisions Board (`/decisions`, `Alt+D`)**: Groups completed and cancelled interviews on the active branch, expands source questions and answers, and lets the operator supersede a value or submit a correction. Corrections travel through the ordinary operator-turn path after the durable decision snapshot is updated.
-- **Approved editor overrides**: `Alt+B` and `Alt+D` are deliberate application-input boundary overrides of Pi's editor word-back and word-delete chords. Clio routes them before the editor so the two global boards remain one chord away. They are explicit exceptions to the general rule that Clio app bindings avoid Pi editor reserves, and users may rebind the Clio actions in `settings.yaml`.
+- **Composite Tasks Board (`/tasks`)**: Presents four sections in one reopenable overlay: the live session board, terminal task history, successful workspace artifacts, and project-scoped operator tasks. Selecting a workspace artifact opens the filtered `/view` path. Operator rows support add, hand, done, and drop actions; refresh is explicit for captured history and artifacts, while lightweight repaint reads the current board snapshot.
+- **Settled Decisions Board (`/decisions`)**: Groups completed and cancelled interviews on the active branch, expands source questions and answers, and lets the operator supersede a value or submit a correction. Corrections travel through the ordinary operator-turn path after the durable decision snapshot is updated.
+- **Editing and focus**: Alt+B/D keep word movement/deletion. Ctrl+G shows a persistent contextual action menu. The application policy runs before viewport shortcuts; release events are discarded first. Search and modal children own cancellation. Permission deletions and local undo use semantic component operations. See the complete [keyboard contract](../guide/commands-and-modes.md#keybindings).
 
 ### 7.4 Slash Autocomplete Command Palette
 - **Grouped Palette**: Typing `/` opens a grouped command palette (ordered by `Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints and formatted descriptions.
@@ -379,3 +464,14 @@ Global scope requires a second `g` press on the same entry after the warning
 line appears. Status rows are labeled private and neither action can promote
 them. Both actions create unapproved durable proposals, show the resulting
 memory ID, and leave approval to the separate reviewed memory lifecycle.
+
+## Keyboard engine compatibility
+
+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
+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.
+MIT notices ship beside the bundle. A frozen contributor install and an ordinary
+npm consumer install are separate acceptance checks.

package/docs/architecture/worker-context.md

@@ -0,0 +1,104 @@
+# Worker context inheritance
+
+Clio dispatch separates **what a worker inherits** from **how workers are scheduled**. This implements the isolation, fork, and splice patterns discussed in [Organizing context in a multi-agent harness](https://www.langchain.com/blog/organizing-context-in-a-multi-agent-harness), using Clio's existing Pi agent loop and dispatch admission boundary.
+
+The default remains an isolated conversation. A native worker gets its own Pi Agent, worker system prompt, admitted tools, dynamic project context, task, and run-local accounting. Context inheritance does not grant additional tools, write roots, or autonomy. Conversation isolation is not a filesystem sandbox; use dispatch worktrees when filesystem isolation is required.
+
+## Dispatch API
+
+```json
+{
+  "agent": "researcher",
+  "task": "Investigate the parser failure and cite the relevant source lines.",
+  "intent": { "read_roots": ["src/parser"] },
+  "context": { "mode": "splice", "paths": ["src/parser"], "max_tokens": 8000 }
+}
+```
+
+`context` is independent of the top-level scheduling `mode` (`parallel`, `sequential`, `pipeline`, and so on). A batch's `context` is the default for each task; an object task can replace it, for example with `{ "mode": "isolated" }` for a separate check. Ordinary `briefing` and pipeline predecessor outputs remain separate dynamic inputs.
+
+| Context mode | Native HTTP/Pi worker | ACP and other runtimes | Selection |
+| --- | --- | --- | --- |
+| `isolated` | Fresh conversation | Fresh runtime conversation | No inherited session messages; existing project context and explicit briefing still apply |
+| `fork` | Existing history seeded into Pi | Rejected; use splice | Entire captured model-visible history, without silent trimming |
+| `splice` | Bounded historical evidence packet | Same packet through existing prompt delivery | Exact selected text, with source labels; no summarizer or extra model call |
+
+Fork accepts optional `max_tokens`. Splice also accepts `paths` and `refs`. The token limit is an estimate for the inherited portion, not the complete worker request. The final request must also fit the worker's system prompt, tool schemas, task, dynamic inputs, and output reserve. The allowed explicit token range is 256-262144; the default splice limit is 8000. A seed has a 512 KiB serialized cap, and the complete native WorkerSpec must fit the existing 1 MiB stdin frame. Larger contexts fail explicitly.
+
+Splice refs address the captured messages: `tool:<call-id>` for a tool result, or `message:<zero-based-index>` for a user or assistant message. Unknown refs fail. Ref indexes are snapshot-relative, not session turn IDs. Path selection is the practical default: explicit paths override the intent's read roots, relevant paths, and write roots. Matching uses lexical paths in tool arguments relative to the parent's workspace; it does not read files, follow symlinks, or perform semantic relevance search. Without paths, recent tool observations are candidates.
+
+All parent user/context text, tool errors, and explicit refs are required. If they cannot fit, dispatch refuses the splice and asks for a larger budget or an isolated task with an explicit briefing. Optional observations are selected newest first, then rendered in original order. Repeated calls with identical names and arguments use the newest optional observation; a smaller stale result cannot replace a newer result that did not fit. Assistant conclusions enter only through explicit refs and are labeled as parent claims. Private reasoning is omitted from splices. Required user images and explicitly selected image results require native fork; optional image observations are omitted and the packet discloses that it contains selected text only.
+
+## Capture, ownership, and reproducibility
+
+The chat loop captures its current Pi messages, or its prepared model replay when no runtime is active. This is the active branch's model-visible working set: existing compaction and eviction projections stay in effect. It does not reopen the raw parent ledger or resurrect sibling branches.
+
+Capture occurs synchronously when dispatch arguments are admitted, before asynchronous routing, metadata probes, permission handling, or execution. Every inheriting member of one dispatch call uses the same capture boundary. A final incomplete assistant tool-call batch, including any results already completed within that batch, is excluded as a unit. Capture also follows Pi's exclusion of aborted and errored assistant responses, drops results belonging to their partial tool declarations, and records the excluded count. User instructions survive that filtering. An orphaned result, duplicate tool-call ID, or incomplete older batch causes explicit refusal rather than constructing invalid provider history.
+
+The snapshot is deeply copied. Admission freezes selected requests, and retries and detached execution carry the selected seed rather than rereading the parent. Pipeline steps receive their upstream result separately; later parent turns do not become part of the already admitted seed. Separate dispatch calls have separate capture boundaries. Automatically constructed reviewers and judges retain their own fresh requests; do not use inherited author conclusions when an independent check is the purpose of a separately dispatched worker.
+
+Native forks enter `initialState.messages`. They are not replayed as new events, credited as worker token usage, or counted as reads and tests executed by the worker. Pi remains responsible for converting model-specific messages at the provider boundary. A splice enters once through dynamic prompt messages. The worker's own assignment comes after inherited context and dynamic inputs.
+
+The parent session writer is never forked or closed. Human `/tree`, `/fork`, and resume retain their existing semantics. Workers do not append their raw conversations to the parent; dispatch continues to return the normal sealed worker result.
+
+## Context pressure and recovery
+
+Every native worker checks context headroom before each provider request. The estimate includes actual system and tool surfaces and reserves output capacity. It honors the configured compaction threshold and automatic working-set eviction setting. Parent usage is never a sizing anchor for a child; after the worker's first completion, its own provider usage calibrates subsequent estimates.
+
+The first request is never automatically reduced: an oversized fork must be explicitly replaced by a smaller splice. During later requests, the guard preserves the two most recent assistant rounds and all user context, tool errors, mutations, and unknown tools. It may remove older private reasoning when visible assistant content remains, and replace large older successful observations from known read tools with stable markers. The original Pi history is not rewritten.
+
+Evicted observations are durably stored before replacement under `$XDG_STATE_HOME/clio-coder/context-observations/<digest>.json` (or Clio's configured state root). A marker provides an exact file location and a `worker:<digest>` recall ref. Native `context(scope="recall")` discovers only this run's evicted observations. Passing a ref retrieves the exact persisted result through the existing bounded observation envelope. The run-local allowlist rejects another worker's refs, arbitrary paths, and parent-session refs; stored bytes are digest-checked on recall. Recall does not count as rereading or validating the current source. Workers without an admitted context tool can use the marker's file through their admitted read tool.
+
+If protected context still cannot fit, the worker ends with `worker_context_exhausted`. Dispatch classifies that as deterministic and does not retry it unchanged. Backend token counts can differ from structural estimates; the guard is conservative headroom management, not a promise that every provider tokenizer or oversized individual tool response will fit.
+
+## Evidence and compatibility
+
+Non-isolated requests record context mode, parent session/leaf/workspace, snapshot digest, selected-content digest, estimated tokens, bytes, selected refs, omitted messages, the excluded unfinished tail, and excluded interrupted responses. The resolved plan displays the selection's digest and size; the run envelope and receipt carry the provenance under `workerContext`. Receipt integrity binds it, and context provenance remains separate from independent validation evidence.
+
+The host persists the selected seed at `$XDG_STATE_HOME/clio-coder/context-seeds/<contentHash>.json`, using mode 0600 and durable writes. These are exact historical artifacts with the same sensitivity as session history; no automatic garbage collection is introduced in this change. Native seeds are self-contained over the wire, including for remote workers. Their metadata and contents are validated before model use and are covered by the existing whole-spec attestation.
+
+WorkerSpec version **4** is required. Rebuild/update remote workers together with the orchestrator; an older worker must reject the new specification rather than silently ignore inherited history. ACP and other runtime adapters receive bounded splice text but do not implement native history forking or Clio's native pressure/recall loop.
+
+No extra LLM request is needed for capture or selection. Optional splice budgeting uses additive size estimates and one final serialization, rather than serializing the growing packet for every candidate. Stable projections help repeated requests retain an unchanged prefix, but provider cache reuse is measured behavior, not guaranteed: worker system prompts, tool surfaces, models, and provider cache rules can differ from the parent.
+
+## A worker's output token limit
+
+A worker is a separate process. It does not inherit the parent session's live
+settings; it reads layered settings from disk for its own working directory
+(`startWorkerRun`, `src/engine/worker-runtime.ts`). An unsaved `/settings` or
+`/model` override in the parent session therefore does not reach it. Those
+resolved settings also govern the worker's observation caps and working-set
+eviction, not just its output cap. External vendor runtimes, such as Claude CLI
+or Antigravity delegation, return before this native path and are not governed by
+the native request adapter at all.
+
+Precedence for `chat.maxOutputTokens`, highest first: `.clio-coder/settings.local.yaml`,
+`.clio-coder/settings.yaml`, the user `settings.yaml`, then the compiled default.
+**The compiled default is `0`** (`src/core/defaults.ts`), which is not a token
+count. `0` means "use the resolved model's advertised output limit", falling back
+to the product floor when the model does not advertise one.
+
+Both project layers are gated on workspace trust (`src/core/workspace-trust.ts`).
+An untrusted project, a project whose configuration changed after trust was
+recorded, or a malformed settings file all drop the project layers and fall back
+to user settings or the compiled default. This is why a worker can legitimately
+run with a different cap than the project file appears to ask for.
+
+Whatever the resolved number is, it is a request, not a promise. `remainingContextMaxTokens`
+(`src/engine/apis/output-budget.ts`) clamps it to the model's advertised output
+limit and to the remaining context window, and each provider then maps the budget
+onto its own wire contract. On the OpenAI-compatible LiteLLM path,
+`reasoning_effort` is forwarded under `allowed_openai_params` when thinking
+effort is enabled (`src/engine/apis/openai-completions.ts`); that is a LiteLLM
+compatibility allowance and not a universal provider contract. A per-response cap
+also caps one response, not a task: it does not bound total task tokens or
+guarantee the task finishes.
+
+`tests/extended/worker-output-settings.test.ts` covers the eight combinations of
+trust state and layer (trusted project at low/medium/xhigh effort, trusted local
+override, untrusted, changed-after-trust, malformed, and user settings only).
+
+## Validation
+
+The worker-context contract tests cover incomplete multi-tool batches, copy isolation, path and explicit-ref selection, stale duplicate reads, mandatory constraints and errors, images, admission freezing, active-branch eviction replay, receipt tampering, scoped recall, and provider-usage reconciliation after eviction. Dispatch integration tests run the actual Pi worker against a controlled HTTP provider and verify single delivery, exclusion of later parent turns, absence of inherited fork events, wire validation, and rejection before a provider call when context is oversized. The normal full CI gate also exercises existing dispatch, session replay, worker transport, and operator behavior.
+

package/docs/architecture/worker-dispatch-mechanics.md

@@ -1,8 +1,5 @@
 # Worker Dispatch Mechanics
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Worker Dispatch Mechanics visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/worker_dispatch_blueprint.html).
-
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
 Source of truth:
@@ -231,7 +228,7 @@ The current reduced contract suite divides dispatch coverage by ownership:
 | --- | --- |
 | `tests/contracts/dispatch-lifecycle.test.ts` | Attached and detached lifecycle deduplication, durable transitions, terminal finalization, and orphan recovery from durable attempts. |
 | `tests/contracts/dispatch-admission.test.ts` | Typed-scope authority, capability pairing, deterministic capacity admission, conservative slot defaults, and ACP authority boundaries. |
-| `tests/contracts/dispatch-schema.test.ts` | Capability-shaped model schema, referenced `$defs`, and hidden-field compatibility. |
+| `tests/extended/dispatch-schema.test.ts` | Capability-shaped model schema, referenced `$defs`, and hidden-field compatibility. |
 
 Earlier releases carried separate envelope, assignment, detached-assignment,
 and failure-class test files for the detailed retry scenarios. Those files are