@iowarp/clio-coder 0.4.6 → 0.4.7

package/docs/architecture/artifact-versions.md

@@ -28,10 +28,10 @@ normalization.
 | **Dispatch Path Scope Provenance** | `1` | `version: 1` in `interface DispatchPathScopeProvenance`<br>`src/domains/dispatch/path-scope.ts` | `pathScope` on the sealed run receipt | Resolved policy-bearing paths with per-field provenance (`declared`/`derived`/`inferred`), source, and confidence. Never carries the task or briefing prose an inferred path came from. | Sealed inside the receipt integrity digest; shares the receipt's fail-closed policy. |
 | **Resolved Dispatch Plan Artifact** | `3` | `version: 3` in `interface ResolvedDispatchPlanArtifact`<br>`src/tools/dispatch-plan.ts:121` | Trusted admission-time tool argument, rendered and hashed into the plan approval | Pinned agent/target/model/node per task plus the sealed `intent` and admission-resolved `resolvedVerification`. The rendered artifact carries `intent_sha256` for a declared task and the full inferred scope table for a legacy one. | Fail-closed. Any version but 3 parses as `null`, as does any task whose present `intent` is not a normalized v2 intent; omitted intent remains the valid legacy-inference shape. The call falls back to unresolved admission rather than executing a half-understood plan. |
 | **Session Ledger** | `4` | `CURRENT_SESSION_FORMAT_VERSION = 4`<br>`src/engine/session.ts:73` | `<stateDir>/sessions/<cwdHash>/<sessionId>/` (`meta.json`, `current.jsonl`, `tree.json`) | Append-only ledger format with UUIDv7 turn IDs, session header line, and tree graph linkage. Version 4 adds `contextEviction` and `contextRecall` entry kinds. | The reader accepts v3 and v4. Opening v3 restamps metadata as v4 without rewriting ledger entries; versions below 3 and versions from a newer build are refused. |
-| **Worker Spec** | `3` | `WORKER_SPEC_VERSION = 3`<br>`src/worker/spec-contract.ts:23` | Subprocess `stdin` control plane JSON payload | Worker invocation parameters, tool surface profile, and execution bounds. | Fail-closed preflight rejection before worker activation. |
+| **Worker Spec** | `4` | `WORKER_SPEC_VERSION = 4`<br>`src/worker/spec-contract.ts:23` | Subprocess `stdin` control plane JSON payload | Worker invocation parameters, tool surface profile, and execution bounds. | Fail-closed preflight rejection before worker activation. |
 | **Worker Runtime Descriptor** | `2` | `WORKER_RUNTIME_DESCRIPTOR_VERSION = 2`<br>`src/worker/spec-contract.ts:24` | Nested `runtime` object in the Worker Spec | Serialized runtime id, kind, API family, auth mode, and optional aliases used to rehydrate the worker's provider runtime. Hardware and environment facts belong to the separate worker-protocol attestation. | Worker-spec parsing rejects an unsupported descriptor version or id mismatch. Rehydration rejects id, kind, API-family, or auth drift before the worker model call. |
 | **Worker Protected Artifact State** | `1` | `WORKER_PROTECTED_ARTIFACT_STATE_VERSION = 1`<br>`src/worker/spec-contract.ts:25` | Worker spec initialization snapshot | Snapshot of active protected artifact paths and validation commands passed to worker. | Worker fails closed before executing mutations. |
-| **Fleet Contract** | `1 \| 2 \| 3 \| 4 \| 5` (Current: `5`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4 \| 5`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`FLEET_DYNAMIC_STEP_VERSION = 5`<br>`src/domains/agents/fleet-contract.ts` | Markdown recipes with YAML front matter, including `.clio-coder/fleets/<name>.md` plus built-in, enabled-extension, and user tiers | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops and commit steps; v4 adds declared per-step write boundaries; v5 adds plan steps, gate steps, per-step target or profile routing, and the single-writer declaration. | Reader refuses contracts whose version features it does not support. |
+| **Fleet Contract** | `1 \| 2 \| 3 \| 4 \| 5` (Current: `5`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4 \| 5`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`FLEET_DYNAMIC_STEP_VERSION = 5`<br>`src/domains/agents/fleet-contract.ts` | Markdown recipes with YAML front matter, including `.clio-coder/fleets/<name>.md` plus built-in, plugin, and user tiers | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops and commit steps; v4 adds declared per-step write boundaries; v5 adds plan steps, gate steps, per-step target or profile routing, and the `writers: 1` single-writer declaration. | Reader refuses contracts whose version features it does not support. |
 | **Execution Plan** | `4` | `version: 4` in `interface ExecutionPlan`<br>`src/domains/dispatch/execution-plan.ts:114` | Complete compiled DAG in memory; plan hash and provenance in receipts; selected steps and hash in the Fleet Run Record | Statically unrolled, deterministically hashed execution plan. v4 adds bounded loop nodes, verification staleness tracking, and commit nodes. | The compiler stamps version 4. There is no execution-plan deserializer or cross-version mismatch path; fleet resume validates its separate Fleet Run Record and plan hash. |
 | **Eval Artifact** | `4` | `version: 4` in `interface EvalArtifactV4`<br>`src/domains/eval/schema/artifact.ts` | `<dataDir>/evals/<evalId>.json` | Stored eval results with suite provenance, matrix parameters, and itemized metric outcomes. `EVAL_TASK_FILE_VERSION = 1` versions compatibility v1 `--task-file` inputs; Suite v2 is a separate contract. | Incompatible eval artifacts are rejected during `clio-coder eval report` and `compare`. |
 | **Prompt Manifest** | `2` | `PROMPT_MANIFEST_VERSION = 2`<br>`src/domains/session/prompt-manifest.ts:30` | `<stateDir>/sessions/<cwdHash>/<sessionId>/prompt-manifest.jsonl` | Per-session record of the compiled system prompt: fragment ids, relative paths, content hashes, section token estimates, and the composition hash. Version 2 is the stable-prefix-first ordering with one `# Memory` header and records `contextWindowSource` beside the window the prompt states (#249). | Additive. A record without a `version` field predates the field and reads as version 1, so a 0.3.8 manifest still parses; the version explains the single `promptRecompiled` entry a resumed session's first compile writes. |
@@ -48,7 +48,7 @@ normalization.
 | **Checkout Writer Lease** | `1` | `version: 1` in `interface CheckoutWriterLeaseRecord`<br>`src/domains/dispatch/checkout-writer-lease.ts` | `<stateDir>/checkout-writer-leases/<key>.json` (key derived from the canonical checkout path) | Cross-process single-writer lease: checkout path, pid, process birth token, acquisition time. | A live sibling holder is refused with `checkout_writer_lease_held`; a dead owner is reclaimed; a malformed or unreadable record throws and fails admission closed. |
 | **Out-of-turn Usage Ledger** | unversioned JSONL | `OutOfTurnUsageRow`<br>`src/domains/observability/out-of-turn-usage.ts` | `<stateDir>/usage/out-of-turn.jsonl` | One row per recorded side question, handoff, prompt prewarm, background-memory call, or summary stream in an unsuccessful compaction. Labels are `side-question`, `handoff`, `prewarm`, `background-memory`, and `failed-compaction`; rows retain session/repository identity, timestamp, selected target/model, and observed usage. New failed-compaction rows add `callOutcome`, nullable unknown usage fields, and estimated/unknown cost provenance; legacy numeric rows remain readable. Successful compactions keep usage on their checkpoint. The ledger is a bounded ring of `MAX_OUT_OF_TURN_USAGE_ROWS = 1000`, rewritten atomically under the state-file lock. | Unparseable rows are skipped and counted by `usage report`; the session ledger is never affected. |
 | **User Tasks File** | `1` | `USER_TASKS_FILE_VERSION = 1`<br>`src/domains/user-tasks/store.ts:6` | `<workspace>/.clio-coder/user-tasks.json` | Durable operator task list with monotonic `uN` ids, status, timestamps, optional notes, and optional session and board links. `nextId` must stay above every stored id. | Fails closed with `UserTasksStoreError` on corrupt JSON, an unknown version or field, an invalid task, a duplicate id, or an unsafe `nextId`; missing files initialize as an empty list. |
-| **Library Pins** | unversioned YAML map | `readLibraryPins`<br>`src/domains/resources/library.ts` | `<configDir>/library-pins.yaml` | Typed ref (`skill:x`, `agent:y`, `prompt:p`, `fleet:z`) to `{sha256, sourceUrl}` for every resource `library add` or the Skills Hub installed. | Malformed YAML throws; a successfully parsed non-map reads as empty. Either a kind-qualified pin or the destination file makes an entry report installed, so a surviving pin still counts when its installed file is missing. |
+| **Library Package State** | `1` | `PluginState`, `readPluginInstallRecord`<br>`src/domains/plugins/types.ts`, `state.ts` | `<configDir>/plugins/state.json` or `<workspace>/.clio-coder/plugins/state.json` | One scoped store for all five package kinds, with disabled IDs and installed records containing kind, source, origin, trust, installation time and full-tree content digest. Each complete package lives beside the state file in its own named directory. | Missing state initializes empty; malformed state, records or unsupported versions fail admission. A state record alone does not prove an installed or loadable package: discovery verifies the actual tree, manifest, compatibility, enablement and scope precedence. The retired `library-pins.yaml` is not an installation authority. |
 
 ---
 

package/docs/architecture/context-engine.md

@@ -7,7 +7,7 @@ Clio Coder tracks context pressure, records per-turn snapshots, and protects the
 
 Source of truth lives in `src/domains/session/context-accounting.ts`, `src/domains/session/context-ledger.ts`, `src/domains/session/compaction/`, `src/domains/context/working-set/`, `src/domains/session/migrations/index.ts`, and the chat-loop integration in `src/interactive/chat-loop.ts`.
 
-The non-destructive eviction layer has its own guide: [context-working-set.md](context-working-set.md).
+The non-destructive eviction layer has its own guide: [context-working-set.md](context-working-set.md). Dispatch inheritance, native worker pressure, and scoped recall are covered in [worker-context.md](worker-context.md).
 
 ## Context window resolution
 
@@ -69,6 +69,40 @@ A summary that reaches its model output limit is incomplete and cannot replace t
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the summary path directly and skip every pre-stage. The overflow guard runs before the user turn is committed, so a blocked oversized request does not leave an unanswered user entry in the ledger.
 
+### What working-set eviction will not take
+
+Only two things ever leave the working set: a tool result's body and an assistant
+turn's thinking. Operator words, summaries, skill activations, ledgers, worker
+runs and bash executions are the session's record of itself and are never
+candidates (`isProtected`, `src/domains/context/working-set/protect.ts`).
+
+Within that, the recent window is untouchable for both kinds:
+`context.workingSet.protectLastTurns` (default 6) fixes a cutoff, and any entry
+at or after it is protected whatever a policy concludes.
+
+Eviction never breaks the call/result envelope. It replaces the observation
+*body* with a marker and leaves the pairing intact: `toolCallId`, `toolName`,
+the existing `details` are retained
+(`projectToolResult`, `src/domains/context/working-set/project.ts`), so replay
+still matches each result to its call and the renderer still knows what the call
+was. Only the text the model reads changes. The `workingSet` stamp on `details`
+is how a reader tells a marker from a genuinely small tool result. Batch
+indivisibility is a separate guarantee belonging to the summarization checkpoint,
+not to body eviction.
+
+Recall then readmits an exact body. **Main-session recall reads the session
+ledger**, not a separate store: `context(scope="recall", ref="<turnId>")` or
+`/context recall <ref>` folds the ledger at the live leaf and returns the body
+through the ordinary observation envelope. A ref that is unknown or sits on an
+abandoned branch is refused rather than guessed at. Native workers are the
+separate case, with their own digest-checked store and `worker:<digest>` refs;
+[worker-context.md](worker-context.md) describes it.
+
+These are structural guarantees about eviction and replay. They are not a claim
+about summary quality: as above, a summary that reaches its model output limit is
+incomplete and cannot replace the checkpoint it was meant to stand in for. The
+durable ledger is not rewritten either way.
+
 ### The legacy mask escape hatch
 
 `CLIO_CODER_LEGACY_MASK=1` restores the destructive pre-stage working-set eviction replaced. It calls `session.replaceEntries` and rewrites the persisted bodies, so masked content is gone for the operator as well as the model. It uses the old marker format:

package/docs/architecture/library.md

@@ -0,0 +1,32 @@
+# Library architecture
+
+> **Visual blueprint:** See the [Library architecture visual reference](../html/library_blueprint.html) in the source checkout.
+
+Clio uses **library** for the collection and **package** for a distributable item. This name covers both local authoring and indexed distribution without suggesting a remote store or a purchase. CLI `library`, slash `/library`, the Library overlay and the bundled `library/registry.yaml` describe the same collection. The Pi API snapshot does not contain the retired command names, so top-level `plugins`, top-level `skills`, and `/resources` are removed rather than retained as aliases. Retired slash commands `/plugins` and `/resources` return an explicit usage error pointing to `/library` (for recipe packages) and `/extensions` (for harness extensions). Bare `/skill` returns usage guidance pointing to `/skills`, while `/skill <name>` activates a skill and `/skill off` clears the active skill's armed tool surface (without erasing instructions already loaded in transcript or context).
+
+## Invariants
+
+1. **One identity.** A package has a portable root `plugin.json`, one lowercase portable name and one explicit bounded Semantic Version. Its kind is `extensions["ai.iowarp.clio"].kind`, defaulting to `plugin`. Kinds are `plugin`, `skill`, `agent`, `prompt`, and `fleet`. One name owns one installation directory per scope; changing kind requires removal.
+2. **One envelope.** Plugins may bundle many public resources. Single-resource kinds declare exactly one public component of their kind, expose exactly that file in their resource root, and can carry private supporting files. Skills normally use `skills/`; a standalone skill package may use `resources.skills: "."` with a root `SKILL.md`. Authoring templates live in `library/_authoring/templates/` outside the five kind roots so they never enter the distribution catalog. Documentation (`README.md`) must be placed at the package root outside any resource directory.
+3. **One integrity rule.** The package digest covers every file and directory, including manifests, scripts, references and eval suites. Links must remain contained; hard links and special files are refused. Staging and publication recheck the digest. Neither force nor pin silently approves a changed indexed source. Installed drift revokes resource admission. Validation is strictly read-only: it verifies manifest schemas, payload contracts (strict v1 agent schemas with custom audience, fleet DAGs, prompt loadability), acyclic package references (`${component:...}`, `${pluginRoot}`), and environmental prerequisites without modifying source bytes or state.
+4. **One durable state.** The existing plugin engine owns complete packages at user and project scope. State records kind, source, origin, trust, time and digest. Atomic staging, state locking, preimage checks and recovery copies apply to every kind. There is no library-specific installer or per-kind pin store.
+5. **One workspace picture.** Library discovery combines the bundled, user, project and explicitly selected indexes with installed state. The list and overlay show disabled, damaged and shadowed copies. Effective loading uses the existing project-over-user plugin precedence. Explicit scope always selects exactly one copy.
+6. **One dependency rule.** Manifest and index package requirements agree, are typed, and form a finite acyclic graph. Only enabled, verified packages satisfy dependencies. Install can plan missing dependencies with explicit inclusion; existing inactive dependencies require repair. Atomicity is per package, not a transaction across a dependency graph.
+7. **Trust follows origin.** `installLibraryPackage({kind, sourcePath, scope, origin, trust, ...})` is exported from `src/domains/plugins/index.ts`. Interop supplies a reviewed prepared tree, `{kind: "interop", host, source: absoluteOriginalPath}`, and `trust: "foreign"`. Skill and prompt loaders honor foreign trust at either scope. Generic updates and forced replacement of adopted content refuse until explicit removal and reviewed re-adoption.
+8. **Eval is an explicit action.** Named evals are contained suite files in the manifest. Installation does not execute them. `eval validate/run --package` resolves a local package or an active verified installation and includes package identity in suite provenance. Evals can execute authored commands in the declared workspace; validation alone does not execute them.
+9. **Operator authority remains separate from autonomy.** Recognized model shell calls cannot install, update, enable, disable or remove package content through the library. Read-only inspection and install/update dry-runs remain available. Interop adoption with `--yes` is likewise an operator action. Runtime offers and overlays commit only through their bound approval paths.
+10. **One inventory, two projections.** `src/domains/resources/library-inventory.ts` produces the bounded, body-free record of packages, scoped copies and actual recipe resources. The CLI reads it for `library recipes` and the model reads it through `context(scope="library")`; they agree about ownership, runtime name, scope, origin, availability and invocation because they are the same records. The model projection is narrower, not different: it is the model audience, so internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are absent, and it drops absolute recipe paths. A catalog `provides` hint is projected as its own tagged row that names its installable owner and that member's honest state, and it never carries an invocation. Neither projection activates, installs, registers or pins anything, and neither fetches a remote source. A native worker registry has no admitted library projection and receives a clear unavailable read rather than the global library.
+
+## Identity at runtime
+
+Package identity, component identity and invocation identity are distinct. The package reference is `kind:name`. A component reference such as `${component:agent:researcher}` is local to one package and resolves a contained file. It does not rename the agent. Prompt invocation names derive from paths beneath the prompt root, agent IDs derive from recipe filenames, and fleets use their authored names. Authors must choose unique runtime names, normally with their package prefix. Installation does not add an automatic colon namespace to agents or fleets.
+
+This is a deliberate refinement of the earlier sprint proposal for automatic namespaces. It preserves Materio's `materio-*` agents and fleets, `/materio:*` prompts, and the WTF-P bridge targets `/wtfp:new-paper`, `/wtfp:map-project`, and `/wtfp:create-outline`. Runtime collisions continue to use each resource loader's documented precedence and diagnostics.
+
+## Owners and boundaries
+
+`src/domains/plugins` remains the internal engine name because it implements the portable manifest, filesystem integrity, installation state and enabled resource roots. `src/domains/resources/library.ts` composes discovery, registration, requirements and reviewed install plans. CLI and TUI consume those functions. The resources domain handles loader-specific schemas, trust and activation; it does not establish a second managed package lifecycle.
+
+Unmanaged local resource files remain discoverable in established Clio and foreign roots. The worker's bounded raw-skill preparation helper and authoring audits are not library installations. Their normalized skill-body hashes describe activation/provenance evidence, not installable package integrity. Maintainer `skills:check` validates authored skill metadata and audit records; the release's distribution integrity rule is `library:check` over full package trees.
+
+Package scripts versus harness extensions: library packages may carry contained scripts for explicit evaluation or verification workflows without registering runtime harness tools or session UI. Harness extensions remain a separate executable integration contract for command tools and hook declarations. They cannot own domain resource roots. No new framework, registry server or installer is introduced by the library.

package/docs/architecture/middleware-and-components.md

@@ -140,7 +140,7 @@ Two coded controls sit beside the registrations rather than among them. `tool-ch
 
 User-defined hook declarations load from three places: `<extensionRoot>/hooks.yaml`, `.clio-coder/hooks.yaml`, and `.clio-coder/hooks.local.yaml`. A hook can be `prompt`, `effect`, or `command`. Command hooks run an argv array without a shell, under the workspace with a timeout and bounded output, and every hook execution emits a receipt. Project files are read from disk; extension declarations come from the committed extension snapshot, which captured the `hooks.yaml` bytes during install-digest verification, so a file rewritten after verification is never reopened. A receipt for an extension hook carries the package provenance, the declarations digest, and the extension generation that admitted it.
 
-User hooks are one owned registration set. The extensions domain publishes nothing when it starts. After the guard registrations and before the turn-end assessors, the composition root prepares boot generation 1 and its user hooks, checks that both candidates are current, and publishes their references in adjacent assignment-only calls. `/resources extensions reload` uses the same paired path for later generations. A replacement for an older or equal generation is refused during preparation; after final validation neither publication primitive can refuse or call out. Conflict diagnostics and the reload event run only after both references are live. An owned registration that would take a builtin or host id is dropped with a `registration_conflict` diagnostic; a later host registration with the same id evicts the owned one. Evaluation captures the registration list once per hook occurrence, so an asynchronous phase that started before a reload finishes against the list it started with.
+User hooks are one owned registration set. The extensions domain publishes nothing when it starts. After the guard registrations and before the turn-end assessors, the composition root prepares boot generation 1 and its user hooks, checks that both candidates are current, and publishes their references in adjacent assignment-only calls. `/extensions reload` uses the same paired path for later generations. A replacement for an older or equal generation is refused during preparation; after final validation neither publication primitive can refuse or call out. Conflict diagnostics and the reload event run only after both references are live. An owned registration that would take a builtin or host id is dropped with a `registration_conflict` diagnostic; a later host registration with the same id evicts the owned one. Evaluation captures the registration list once per hook occurrence, so an asynchronous phase that started before a reload finishes against the list it started with.
 
 ---
 

package/docs/architecture/model-catalog.md

@@ -203,10 +203,30 @@ override the applicable setting.
   route. Stable session ids, request tags, optional request-level timeouts, and
   observed server retry/fallback headers remain supported. Residency is
   observe-only because LiteLLM owns loading and eviction behind the route.
-- **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
+- **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves thinking blocks within assistant messages. Where thinking is enabled and the provider supports thinking signatures (`reasoning_content`, `reasoning`, `reasoning_text`), it preserves thinking blocks across turns.
 - **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
 - **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.
 
+### Output token limit interruption during reasoning and thinking replay
+
+When an LLM response is interrupted because it hits an output token limit during reasoning (`stopReason: "length"` / `finish_reason: "length"`), Clio applies a bounded request repair rather than universal across-the-board replay (`src/engine/apis/openai-completions.ts` `preserveInterruptedReasoning`):
+
+1. **Activation conditions**:
+   - Thinking is active and `requiresThinkingAsText` is not configured.
+   - The assistant turn stopped due to length (`stopReason === "length"`).
+   - Provider, API, and model all match the previous turn.
+   - All content blocks are nonempty, non-redacted thinking blocks.
+   - Thinking signatures are raw `reasoning`, `reasoning_content`, or `reasoning_text`.
+
+2. **Replay and wire propagation**:
+   - The adapter appends a request-local visible interruption notice to prevent upstream Pi from dropping a reasoning-only assistant turn.
+   - In the next request (turn continuation or bounded repair via `stream` or `streamSimple`), the adapter retains the truncated thought trace and replays it on the wire under `assistant[signature]` (for example `reasoning_content: reasoning`).
+   - The request-local notice contains no private reasoning, and private reasoning is never sent as user-visible answer text.
+   - Replay repair does not mutate saved session transcripts, original stop reasons, usage metrics, or thinking signatures.
+   - If target model, provider, or API switches, or reasoning is turned off, this narrow request repair is skipped and existing conversion policy applies; opaque signatures and cross-model conversions retain their original provider semantics.
+   - A per-response output-token cap does not cap total task tokens or guarantee completed task execution; existing repair and deadline limits continue to apply.
+   - Verified by contract suite `tests/contracts/reasoning-length-replay.test.ts`.
+
 ---
 
 ## Subscription Catalog Models

package/docs/architecture/pi-boundary.md

@@ -97,10 +97,28 @@ behavior and should not grow another implementation of an SDK primitive.
 - `src/interactive/chat-renderer.ts` consumes Pi's compaction, branch, and bash replay wording through `src/engine/messages.ts`.
 - Interactive Markdown, Mermaid, LaTeX, fullscreen, alternate-screen, and keybinding glue should continue to compose pi-tui primitives.
 
+## Architecture boundary enforcement and tests
+
+The rule keys on the `@earendil-works/pi-` prefix, and it is a single rule with
+no exceptions: only files under `src/engine/**` may import a `@earendil-works/pi-*`
+package, type-only imports included. The allowlist of type-only exceptions
+(`allowedPiTypeImportSpecifiersOutsideEngine`) is deliberately empty. Everything
+else, `src/interactive/**` included, reaches Pi through engine re-exports such as
+`src/engine/tui-primitives.ts`, and domains take erased engine shapes
+(`EngineModel`, `Api`, `Model`) from `src/engine/types.ts` and `src/engine/ai.ts`.
+
+`tests/boundaries/check-boundaries.ts` enforces this statically over the import
+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`
+covers tool schema admission and execution isolation across runtimes.
+
 ## Pi regression net
 
 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`

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

@@ -42,11 +42,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 +151,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 +184,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.
 

package/docs/architecture/safety-model.md

@@ -86,6 +86,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 +282,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 +351,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

@@ -113,7 +113,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 +187,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/tui-design.md

@@ -174,7 +174,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 +193,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 +201,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/contracts/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 +301,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 +314,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 +426,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 +467,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.