@iowarp/clio-coder 0.4.6 → 0.4.8

package/docs/README.md

@@ -4,9 +4,6 @@
 
 # Clio Coder documentation
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder documentation visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/readme_blueprint.html).
-
 This is the documentation map for Clio Coder. Start with the path closest to
 what you are trying to do; the deeper references are here when you need exact
 schemas, wire contracts, or architectural invariants.
@@ -23,8 +20,7 @@ docs/
 ├── guide/          Operator and user workflows
 ├── architecture/   Runtime contracts and design
 ├── process/        Development, validation, and release practice
-├── history/        Dated records that are not current guidance
-└── html/           Source-checkout visual blueprints
+└── history/        Dated records that are not current guidance
 ```
 
 ## Start here
@@ -36,7 +32,10 @@ docs/
 | Understand what Clio may read, change, or execute | [Safety Model](architecture/safety-model.md) |
 | Diagnose a problem by its exact message | [Troubleshooting](guide/troubleshooting.md) |
 
-A minimal first run is:
+A minimal first run needs Node.js 22.19 or newer and a model to talk to: a
+local inference server such as Ollama or LM Studio, a lab gateway, or a cloud
+API. Quick Connect asks for the endpoint, a key when the server needs one, and
+a model.
 
 ```bash
 npm install -g @iowarp/clio-coder
@@ -64,6 +63,9 @@ interactive session. `clio-coder doctor` is a read-only installation check;
 | Skills discovery, marketplace safety, installation, and publishing | [Skills Marketplace](guide/skills-marketplace.md) |
 | Agents, prompts, extensions, and portable share archives | [Extensions and Sharing](guide/extensions-and-sharing.md) |
 | Private resource catalogs and synchronization | [Resource Library](guide/resource-library.md) |
+| Portable domain bundles, library pins, and lifecycle | [Plugins](guide/plugins.md) |
+| Package manifests and component references | [Authoring Plugins](guide/authoring-plugins.md) |
+| Executable harness capabilities | [Harness Extensions](guide/harness-extensions.md) |
 | TUI layout, responsive behavior, colors, and interaction rules | [TUI Design](architecture/tui-design.md) |
 | Terminal panes beside a session and the files pane: install, keys, settings, doctor, troubleshooting | [Panes and the Files Pane](guide/panes-and-files.md) |
 
@@ -92,6 +94,7 @@ validation, reference data, or human scientific judgment.
 | An executable multi-node walkthrough with a reviewer gate | [Fleet Demo Runbook](process/fleet-demo-runbook.md) |
 | Capacity leases, heartbeats, locks, and node drain control | [Capacity and Scheduling](architecture/capacity-and-scheduling.md) |
 | Worker process protocol, watchdogs, steering, and exit mapping | [Worker Dispatch Mechanics](architecture/worker-dispatch-mechanics.md) |
+| Worker context inheritance, fork, and splice modes | [Worker Context](architecture/worker-context.md) |
 | Typed dispatch intent and compatibility boundaries | [Dispatch Typed Intent](architecture/dispatch-typed-intent.md) |
 | Why dispatch remains one domain and where its seams actually are | [Dispatch Architecture Rationale](architecture/dispatch-architecture-rationale.md) |
 
@@ -103,6 +106,7 @@ validation, reference data, or human scientific judgment.
 | Prompt-envelope reuse, provider tool delivery, and bounded results | [Prompt Envelope and Tools](architecture/prompt-envelope-and-tools.md) |
 | All built-in worker tools, arguments, outputs, and error examples | [Tool Usage](guide/tool-usage.md) |
 | Implementing a runtime or inference-server adapter | [Provider Adapter Cookbook](architecture/provider-adapter-cookbook.md) |
+| External coding agent discovery, inspection, and safe resource adoption | [Coding Agent Interoperability](guide/interop.md) |
 | Middleware hooks, effects, budgets, and component snapshots | [Middleware and Components](architecture/middleware-and-components.md) |
 | Process exit codes, stdout/stderr rules, JSONL, and `--help` contracts | [Exit Codes and Output](guide/exit-codes-and-output.md) |
 | Environment overrides, directory controls, and debug toggles | [Environment Variables](guide/environment-variables.md) |
@@ -126,6 +130,7 @@ repository.
 | Topic | Guide |
 | --- | --- |
 | Source layout, compile-time boundaries, domain loading, and runtime flow | [Architecture](architecture/architecture.md) |
+| Package kinds, catalog resolution, integrity, and trust | [Library Architecture](architecture/library.md) |
 | Pi framework boundary and Clio-owned policy | [Pi Boundary](architecture/pi-boundary.md) |
 | Documentation style and source-alignment workflow | [Documentation Guide](process/documentation-guide.md) |
 | Source-to-guide ownership map | [Documentation Coverage](process/documentation-coverage.md) |
@@ -172,20 +177,59 @@ local dogfooding instructions do not collide with public documentation. If the
 file exists in your checkout, read it before making changes; if it does not,
 the architecture guide and `CONTRIBUTING.md` are the public starting points.
 
-## Interactive blueprints
+## Where Clio finds these docs when it is running in someone else's project
+
+Clio's documentation ships with Clio, not with your workspace. Everything below
+resolves from the installed package root (`resolvePackageRoot()`,
+`src/core/package-root.ts`), never from the directory you launched in.
+
+**What is indexed.** Every `.md` file under `<package-root>/docs/`, plus root
+`README.md`, `CHANGELOG.md` and `CLIO-CODER.md` when each exists. The npm package
+ships the Markdown reference used by both the application and agents. A root `CLIO-CODER.md` is indexed
+only when present, such as in a source checkout. The index is deterministic and needs no
+network or embedding service (`src/tools/context/docs-engine.ts`).
+
+**Searching and then reading.** `context(scope="docs", query="…")` returns
+section headings with citations such as `docs/architecture/safety-model.md`.
+Citations are **package-relative**, and this is the step that matters when the
+workspace is someone else's repository: reading `docs/architecture/safety-model.md`
+as a plain relative path reads *that project's* `docs/`, if it has one. Clio's
+own system prompt names the installed documentation directory as
+`{CLIO_DOCS_PATH}`, substituted as `join(packageRoot, "docs")`
+(`src/domains/prompts/compiler.ts`). Resolve the citation against the **package
+root**, which is that directory's parent. So when the prompt names `/pkg/docs`:
+
+- `docs/guide/foo.md` → `/pkg/docs/guide/foo.md`
+- `CHANGELOG.md` → `/pkg/CHANGELOG.md`, not `/pkg/docs/CHANGELOG.md`
+
+Do not duplicate the `docs/` segment, and do not resolve a citation against the
+workspace. Omitting `query` lists the corpus instead of searching it.
+
+**The web documentation.** `clio-coder docs` opens the documentation map in the
+Clio Coder web app. `clio-coder docs safety` opens the safety guide. It resolves
+content from the installed package, independent of your current project, and
+reuses this installation's background app when configured. Otherwise it starts
+a foreground loopback server; press Ctrl+C to stop. `--no-open` prints the private
+launch link without opening a browser. The command never installs a service.
+
+## Reading in the application
+
+The GUI renders these Markdown sources directly with the application's theme,
+syntax highlighting, copy controls, tables and diagrams. Navigation groups come
+from this map, search indexes the same pages, and each page's outline is generated
+from its headings. Internal references stay in the application.
 
-Every Markdown page has a dedicated visual blueprint under `docs/html/`, and
-the separate `docs/html/index.html` landing page mirrors this documentation
-tree. Blueprint links use the public repository so they still work when a guide
-is read from the npm package. From a source checkout, serve the same files
-locally with:
+Edit the Markdown once to update both human and agent documentation. There is
+no separate HTML source tree, document server, or alternate reading view.
 
 ```bash
 clio-coder docs
+clio-coder docs safety
+clio-coder docs guide/configuration-reference.md --no-open
 ```
 
-The Markdown pages are the portable reference and ship with the npm package.
-The HTML blueprints are development aids and are not required for the runtime.
+The Markdown files remain the portable reference for the CLI, agents, editors,
+and repository readers. Opening documentation does not require a model connection.
 
 ## Writing documentation
 

package/docs/architecture/acp.md

@@ -1,8 +1,5 @@
 # Agent Client Protocol (ACP) Server
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Agent Client Protocol (ACP) Server visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/acp_blueprint.html).
-
 This document defines the architecture, transport protocols, tool mediation layers, permission handling, and error taxonomy for Clio Coder's Agent Client Protocol (ACP) server implementation in the current source tree.
 
 Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
@@ -14,11 +11,10 @@ Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 Clio Coder provides a native ACP server via the `clio-coder acp` command. The server implements the open Agent Client Protocol specification (ACP v1 / schema 0.4.5) over standard I/O JSON-RPC 2.0 transport (`src/engine/acp/transport.ts`).
 
 The ACP server allows external IDEs, editors (such as Zed), and automated orchestration engines to drive Clio Coder sessions over a structured protocol.
-The source tree includes the `apps/workbench` localhost desktop client. Its ACP
-adapter supports session browsing and deletion, safe settings, target probes,
-usage, recovery, evaluation inventory, routing and dispatch inspection, toolchain
-status, agent attribution, and the live fleet event strip. The workbench is a
-source application and is not included in the published CLI package.
+The source tree includes the `apps/clio-coder-web` application, which supervises
+ACP children and exposes session operations through authenticated local REST and
+SSE. The earlier `apps/workbench` client is retained as reference source and is
+excluded from workspace builds, publication, and product gates.
 
 ```mermaid
 graph LR
@@ -186,7 +182,7 @@ Every frame the server writes is bounded (`src/engine/acp/types.ts`). Every cap
 
 ### Admission failure
 
-A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding `session/update` notifications. `data.reason` is one of `orchestrator-not-configured`, `target-unknown`, `target-not-configured`, `target-not-found`, `runtime-not-registered`, `model-not-configured`, `chat-unsupported`, `streaming-unsupported`, or the catch-all `admission-failed`. That list is closed and the server enforces it: the engine's runtime-resolution diagnostics are a larger and faster-moving vocabulary (`runtime-target-unsupported`, `runtime-use-unsupported`, `required-capability-missing`, and others), and any reason outside the list is reported as `admission-failed` rather than teaching clients a code the profile never promised. The two halves of an unconfigured orchestrator are distinguished: no `chat.target` reports `orchestrator-not-configured`, and a configured target with no `chat.model` reports `model-not-configured`, so a client is pointed at the half of the settings that is actually missing. The message is a sanitized one-line sentence and never contains the settings path. A failure after admission fails with `turn_failed` instead. Readiness before the first prompt is unchanged and lives in the CLI: `paths --json` for home identity, `doctor --json` for installation sanity, and `targets --json [--probe]` for target, auth, and health. `--probe` performs a request to the configured endpoint, so the client decides when that is allowed.
+A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding `session/update` notifications. `data.reason` is one of `orchestrator-not-configured`, `target-unknown`, `target-not-configured`, `target-not-found`, `runtime-not-registered`, `model-not-configured`, `chat-unsupported`, `streaming-unsupported`, `authentication-required`, or the catch-all `admission-failed`. That list is closed and the server enforces it: the engine's runtime-resolution diagnostics are a larger and faster-moving vocabulary (`runtime-target-unsupported`, `runtime-use-unsupported`, `required-capability-missing`, and others), and any reason outside the list is reported as `admission-failed` rather than teaching clients a code the profile never promised. The two halves of an unconfigured orchestrator are distinguished: no `chat.target` reports `orchestrator-not-configured`, and a configured target with no `chat.model` reports `model-not-configured`, so a client is pointed at the half of the settings that is actually missing. The message is a sanitized one-line sentence and never contains the settings path. A failure after admission fails with `turn_failed` instead. The server checks credential availability through the provider auth contract before admitting a prompt; `authentication-required` carries no environment-variable name, credential, or provider prose. A background service does not inherit terminal-only API keys: save the key with `clio-coder auth login <target>`, then close and reopen the session. Other readiness checks before the first prompt live in the CLI: `paths --json` for home identity, `doctor --json` for installation sanity, and `targets --json [--probe]` for target, auth, and health. `--probe` performs a request to the configured endpoint, so the client decides when that is allowed.
 
 ### Permission requests
 

package/docs/architecture/alcf-provider.md

@@ -1,8 +1,5 @@
 # ALCF Inference Provider
 
-> **Visual blueprint:** The source checkout includes the complete
-> [ALCF Inference Provider visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/alcf_blueprint.html).
-
 Clio can use Argonne's ALCF inference gateway as an OpenAI-compatible target
 backed by Globus OAuth. The runtime id is `alcf`; each configured target points
 at one gateway cluster URL, such as Sophia or Metis.

package/docs/architecture/architecture.md

@@ -1,8 +1,5 @@
 # Clio Coder Architecture and Boundaries
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Architecture and Boundaries visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/architecture_blueprint.html).
-
 Clio Coder is an experimental, terminal-first coding harness for the CLIO ecosystem. CLIO stands for Context Layer for Input/Output; the project is named for the Greek muse of history and developed by the Gnosis Research Center at Illinois Tech. Its architecture favors small, auditable subsystems over a single monolithic agent loop: CLI entry points, the interactive TUI, provider/runtime code, worker subprocesses, tools, and feature domains are kept separate so local-model support and scientific-software workflows can evolve without collapsing safety boundaries.
 
 This page is source-code aligned for the current source tree.
@@ -26,14 +23,14 @@ src/
 
 Feature-domain directories include the following. Not every row is a loaded
 `DomainModule`: the orchestrator currently loads config, extensions, interop,
-resources, share, context, providers, toolchain, safety, prompts, agents,
-middleware, session, observability, scheduling, dispatch, and lifecycle, plus
-mux when the pane tier is active. The other rows are libraries or CLI-owned
-feature areas.
+plugins, resources, share, context, providers, toolchain, safety, prompts,
+agents, middleware, session, observability, scheduling, dispatch, and
+lifecycle, plus mux when the pane tier is active. The other rows are libraries
+or CLI-owned feature areas.
 
 | Domain | Primary source | Public surface |
 | --- | --- | --- |
-| agents | `src/domains/agents/**` | Built-in, user, and project agent recipes. |
+| agents | `src/domains/agents/**` | Built-in, plugin, user, and project agent recipes. |
 | components | `src/domains/components/**` | Component snapshots, diffs, and classification. |
 | config | `src/domains/config/**`, `src/core/config.ts` | `settings.yaml`, keybindings, hot reload. |
 | context | `src/domains/context/**` | Layered `CLIO-CODER.md` and subtree `CLIO-CODER.override.md` guidance, codewiki indexer, repository context. |
@@ -47,9 +44,10 @@ feature areas.
 | memory | `src/domains/memory/**` | Approved long-term memory, proactive task intervention. |
 | middleware | `src/domains/middleware/**` | Declarative and programmatic lifecycle hooks and budgets. |
 | observability | `src/domains/observability/**` | SQLite trace store, metrics projections, live telemetry. |
+| plugins | `src/domains/plugins/**` | Plugin discovery, catalog, and lifecycle. |
 | prompts | `src/domains/prompts/**` | Prompt fragments, system prompt envelope, template hashing. |
 | providers | `src/domains/providers/**` | Target-first runtime registry, model probing, credentials. |
-| resources | `src/domains/resources/**` | Skills loader, marketplace synchronization, prompts loader. |
+| resources | `src/domains/resources/**` | Package library, skills loader, prompts loader. |
 | safety | `src/domains/safety/**` | 10-step policy engine, path policy, zero-access rails, audit. |
 | scheduling | `src/domains/scheduling/**` | Budget ceilings, node cluster states, batch capacity checks. |
 | session | `src/domains/session/**` | Append-only JSONL transcripts, tree navigation, compaction. |
@@ -84,7 +82,7 @@ decision.
 
 Clio maintains an explicit distinction between persisted user settings (`settings.yaml`) and session-local routing state (`src/core/session-routing.ts`).
 
-1. **Decoupled Overlays**: Turn-level selections (such as active target, model override, thinking level, and scoped models cycled via Alt+J / Alt+K) apply dynamically through `applySessionRouting` without mutating `settings.yaml`.
+1. **Decoupled Overlays**: Turn-level selections (such as active target, model override, thinking level, and scoped models cycled via explicit model-cycle keys) apply dynamically through `applySessionRouting` without mutating `settings.yaml`.
 2. **Lifecycle Flow**:
    - `seedSessionRouting`: Seeds runtime fields from configuration at startup.
    - `applyRoutingPatch`: Applies surgical routing mutations (such as changing active model or target in the TUI).

package/docs/architecture/artifact-placement.md

@@ -1,8 +1,5 @@
 # Artifact Placement
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Artifact Placement visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_placement_blueprint.html).
-
 Every file Clio generates has one home, decided by who reads it. The rule that
 follows from that: **the repo working tree holds files a human asked for.**
 Anything Clio produced on its own initiative lands in the project-local

package/docs/architecture/artifact-versions.md

@@ -1,8 +1,5 @@
 # Artifact Versions & Serialization Contracts
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Artifact Versions & Serialization Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_versions_blueprint.html).
-
 This document is an operator-facing registry of compatibility-sensitive file
 formats, serialized structures, integrity digests, and migration rules in the
 current source tree. It is not an exhaustive inventory of every internal store
@@ -28,10 +25,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 +45,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/capacity-and-scheduling.md

@@ -1,8 +1,5 @@
 # Capacity Leases & Fleet Scheduling
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Capacity Leases & Fleet Scheduling visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/capacity_scheduling_blueprint.html).
-
 This document specifies the multi-process capacity leasing protocols, node
 scheduling models, cross-process transaction locks, and failure recovery
 mechanics in the current source tree.

package/docs/architecture/context-engine.md

@@ -1,13 +1,10 @@
 # Context Engine
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Context Engine visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_blueprint.html).
-
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
 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 +66,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/context-working-set.md

@@ -1,8 +1,5 @@
 # Working Set
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Working Set visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_working_set_blueprint.html).
-
 The working set is the part of the session ledger the model actually receives on the next request. When context pressure crosses `context.compaction.threshold`, Clio narrows that view before it considers summarizing anything: selected tool-result bodies and closed-turn thinking blocks stop being replayed, and a one-line marker takes each body's place. Nothing is deleted. The ledger keeps every byte the tools produced, the transcript keeps showing them, and the model can ask for any evicted body back by ref.
 
 Source of truth is `src/domains/context/working-set/` (`contract.ts`, `fold.ts`, `project.ts`, `marker.ts`, `protect.ts`, `engine.ts`, `recall.ts`, `policies/`), the ledger records in `src/domains/session/entries.ts`, and the compaction stage in `src/interactive/turn-context.ts` (`runAutoCompact`).

package/docs/architecture/dispatch-architecture-rationale.md

@@ -1,8 +1,5 @@
 # Dispatch Architecture Rationale
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Dispatch Architecture Rationale visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_rationale_blueprint.html).
-
 Why `src/domains/dispatch/` is one domain, why one import out of it looks
 irregular and is allowed to, and why the repository has no barrel-only import
 convention. No code moved as a result of this document. It exists so that a

package/docs/architecture/dispatch-typed-intent.md

@@ -1,8 +1,5 @@
 # Typed Dispatch Intent: Migration and Refusal Policy
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Typed Dispatch Intent: Migration and Refusal Policy visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_typed_intent_blueprint.html).
-
 Typed dispatch intent is the structured declaration of what a dispatched worker
 may read, may write, is expected to produce, and must verify. It replaces the
 practice of reconstructing that answer from optional `writeRoots` plus path-like

package/docs/architecture/evidence-and-memory.md

@@ -1,8 +1,5 @@
 # Evidence Corpus and Long-Term Memory
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Evidence Corpus and Long-Term Memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/memory_blueprint.html).
-
 Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. Currently, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.

package/docs/architecture/library.md

@@ -0,0 +1,30 @@
+# Library architecture
+
+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

@@ -1,8 +1,5 @@
 # Middleware and Component Registry
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Middleware and Component Registry visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/middleware_blueprint.html).
-
 Clio Coder has two related but separate surfaces:
 
 1. **Components**: deterministic inventory of files that can affect harness behavior.
@@ -140,7 +137,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

@@ -1,8 +1,5 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Model Catalog, Runtime Refresh, and Field Notes visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/models_blueprint.html).
-
 Clio Coder treats a selectable model as the intersection of three sources:
 
 1. **Configured targets** in `settings.yaml` (`targets[]`, `defaultModel`, and optional `wireModels`).
@@ -203,10 +200,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/extended/reasoning-length-replay.test.ts`.
+
 ---
 
 ## Subscription Catalog Models

package/docs/architecture/observability.md

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

package/docs/architecture/pi-boundary.md

@@ -1,8 +1,5 @@
 # Pi SDK Boundary
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Pi SDK Boundary visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/pi_boundary_blueprint.html).
-
 Clio Coder pins Pi 0.85.1 as its provider, agent-loop, and terminal SDK. This
 page records where Pi owns a reusable primitive and where Clio deliberately
 keeps product behavior. Review this table on every Pi upgrade. An action marked
@@ -97,17 +94,35 @@ 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/extended/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`
-- `tests/contracts/provider-context-boundary.test.ts`
-- `tests/contracts/rendering-invariants.test.ts`
-- `tests/contracts/gemma-channel-filter.test.ts`
-- `tests/contracts/tool-boundaries.test.ts`
+- `tests/extended/openrouter-transport.test.ts`
+- `tests/extended/provider-context-boundary.test.ts`
+- `tests/extended/rendering-invariants.test.ts`
+- `tests/extended/gemma-channel-filter.test.ts`
+- `tests/extended/tool-boundaries.test.ts`
 - `tests/contracts/session-durability.test.ts`
 - `tests/smoke/process-lifecycle.test.ts`