@iowarp/clio-coder 0.4.1 → 0.4.2

package/docs/{provider-adapter-cookbook.md → architecture/provider-adapter-cookbook.md}

@@ -1,17 +1,17 @@
 # Provider Adapter Cookbook
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Provider Adapter Cookbook visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/provider_adapter_blueprint.html).
 
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 
 Source of truth:
-- Runtime descriptor types: [src/domains/providers/types/runtime-descriptor.ts](../src/domains/providers/types/runtime-descriptor.ts)
-- Registry loader: [src/domains/providers/registry.ts](../src/domains/providers/registry.ts)
-- Probe reasoning helpers: [src/domains/providers/probe/reasoning.ts](../src/domains/providers/probe/reasoning.ts)
-- Model capabilities resolver: [src/domains/providers/model-capabilities.ts](../src/domains/providers/model-capabilities.ts)
-- Inference capability flags: [src/domains/providers/types/capability-flags.ts](../src/domains/providers/types/capability-flags.ts)
-- Model target resolution: [src/domains/providers/runtime-resolution.ts](../src/domains/providers/runtime-resolution.ts)
+- Runtime descriptor types: [src/domains/providers/types/runtime-descriptor.ts](../../src/domains/providers/types/runtime-descriptor.ts)
+- Registry loader: [src/domains/providers/registry.ts](../../src/domains/providers/registry.ts)
+- Probe reasoning helpers: [src/domains/providers/probe/reasoning.ts](../../src/domains/providers/probe/reasoning.ts)
+- Model capabilities resolver: [src/domains/providers/model-capabilities.ts](../../src/domains/providers/model-capabilities.ts)
+- Inference capability flags: [src/domains/providers/types/capability-flags.ts](../../src/domains/providers/types/capability-flags.ts)
+- Model target resolution: [src/domains/providers/runtime-resolution.ts](../../src/domains/providers/runtime-resolution.ts)
 
 ---
 
@@ -72,12 +72,13 @@ export const myCustomRuntime: RuntimeDescriptor = {
 
 ## 2. Probing Mechanisms
 
-Probes discover the current state of a target inference server when Clio starts or when `/targets` or `/model` are refreshed.
+Probes discover the current state of a target inference server when Clio starts
+or when `/settings targets` or `/model` is refreshed.
 
 ### 2.1 Endpoint Probing (`probe`)
 The `probe` method validates endpoint reachability and collects loaded models:
 
-* **Inputs:** `TargetDescriptor` (which holds target `url`, optional `apiKey`, and connection metadata) and `ProbeContext` (which provides timeout signals and credentials). Request paths that resolve OAuth through `providers.auth.resolveForTarget` must pass `{ signal }`; Pi 0.84's `AuthOperationOptions` keeps cancellation attached while Clio waits for or mutates its credential store.
+* **Inputs:** `TargetDescriptor` (which holds target `url`, optional `auth` metadata, and connection metadata) and `ProbeContext` (which provides timeout signals, credential-presence keys, and an optional resolved `authToken`). Request paths that resolve OAuth through `providers.auth.resolveForTarget` must pass `{ signal }`; Pi 0.84's `AuthOperationOptions` keeps cancellation attached while Clio waits for or mutates its credential store.
 * **Return Value:** A `ProbeResult` indicating:
   * `ok`: True if reachable.
   * `serverVersion`: String identifier of the backend (e.g. `"Ollama/0.1.48"`).
@@ -87,7 +88,10 @@ The `probe` method validates endpoint reachability and collects loaded models:
 ### 2.2 Reasoning Probing (`probeReasoning`)
 For local endpoints where models are loaded dynamically, the runtime can supply a `probeReasoning` method. It sends a short mock completion request to inspect whether the model outputs reasoning/thinking tags (such as `reasoning_content` in OpenAI completions or `<think>` tags in raw text streams).
 
-Clio caches this result under the session's provider cache, preventing redundant network requests.
+Clio caches this result in the providers domain by exact target and model id for
+the current process. Provider reinitialization, configuration reload, and target
+disconnect paths clear the relevant cache rather than persisting it in a
+session ledger.
 
 ### 2.3 Exact-ID Capability Selection (`probeCapabilitiesForModel`)
 `probeCapabilitiesForModel` is the one exact-id selector during capability resolution. When a router target serves several models, `probeCapabilitiesForModel` matches `probeModelCapabilities` keyed strictly to the requested wire model ID. A router serving multiple models thus answers only from the `/v1/models` row keyed to its own wire model, preventing capability flags or token limits from bleeding across different models on the same target.
@@ -124,14 +128,14 @@ The `synthesizeModel` method acts as the factory that creates the `pi-ai` compat
   ): Model<Api>
   ```
 * **Tasks:**
-  1. Retrieve configured API credentials using `providers.auth` persisted through `openAuthStorage()`.
-  2. Instantiate the adapter client (e.g., building a `pi-ai` OpenAI or Anthropic provider instance).
-  3. Bind custom prompt templates and FIM (Fill-in-the-Middle) properties where supported.
+  1. Combine target, catalog, probe, and capability metadata into a `pi-ai` model descriptor.
+  2. Select the API family, endpoint, pricing, token limits, and Clio runtime metadata required by the streaming adapter.
+  3. Leave secrets and request-time authentication to `providers.auth.resolveForTarget` at the call site. Optional FIM support belongs to the descriptor's separate `infill` method rather than to prompt binding in `synthesizeModel`.
 
 
 ### 3.1 Stream Filters and Sentinel Stripping
 
-When a model family requires response parsing or sentinel stripping before the payload reaches the core logic, Clio applies runtime-agnostic stream filters during model synthesis. For example, if the resolved model family is `gemma-4`, a dedicated `createGemmaChannelFilter` is applied to intercept and reclassify `<|channel>thought` markers directly from the `text_delta` stream into `thinking_delta` events, dropping orphan channel closers and own-thought labels seamlessly.
+When a model family requires response parsing or sentinel stripping before the payload reaches the core logic, Clio applies runtime-agnostic stream filters in the engine stream adapter after model synthesis. For example, if the resolved model family is `gemma-4`, a dedicated `createGemmaChannelFilter` intercepts and reclassifies `<|channel>thought` markers directly from the `text_delta` stream into `thinking_delta` events, dropping orphan channel closers and own-thought labels seamlessly.
 
 ### 3.2 OpenAI-compatible sampling and vLLM budgets
 
@@ -160,8 +164,10 @@ level onto `thinking.type: "adaptive"` plus `output_config.effort` (read from th
 `thinkingLevelMap` and `compat.forceAdaptiveThinking`) or onto a bounded `budget_tokens` for
 budget-based models. Clio's `onPayload` hook no longer rewrites those fields; it only sets the
 OpenAI Responses `reasoning.summary` verbosity, which the agent loop cannot express as an option.
-`tests/contracts/thinking-runtime.test.ts` captures the wire payload Pi builds and proves Clio
-leaves it untouched.
+`tests/contracts/thinking-off-wire.test.ts` locks the local LM Studio and
+llama.cpp controls used when thinking is off. Anthropic request assembly is
+inherited from the pinned Pi dependency; Clio no longer carries a separate
+contract test that reconstructs Pi's whole adaptive or budget payload.
 
 
 ---
@@ -172,11 +178,16 @@ Clio supports diverse thinking mechanisms. If your model family uses a custom fo
 
 | Mechanism | Behavior |
 | --- | --- |
-| `none` | **Reasoning-Never:** Clio strips thinking request fields (e.g., effort levels), avoids replaying thinking blocks in history, emits no TUI thinking events, and records no reasoning token usage metrics. |
-| `ollama-native` | Standard Ollama native thinking streams. |
-| `lmstudio` | Uses OpenAI-compatible chat and consumes streamed `reasoning`; thinking control uses only `reasoning_effort`. |
-| `openai-completions` | Replays thinking blocks via `reasoning_content` message parameters. |
-| `anthropic-max` | Anthropic extended thinking block protocol. |
+| `none` | The family does not reason; the effective level is `off` and thinking controls are omitted. |
+| `effort-levels` | Named levels map to provider effort values, such as LM Studio `reasoning_effort`. |
+| `budget-tokens` | Named levels map to explicit reasoning-token budgets. |
+| `on-off` | The runtime exposes a binary thinking switch rather than graduated effort. |
+| `always-on` | The model cannot disable reasoning; Clio reports the effective level as forced and allows extra completion headroom where required. |
+
+Wire formats such as `anthropic-extended`, `qwen-chat-template`, and
+`deepseek-r1` live in capability metadata. Runtime API families such as
+`openai-completions` and `ollama-native` are separate descriptor fields; neither
+set is a valid value for `quirks.thinking.mechanism`.
 
 ---
 
@@ -185,7 +196,7 @@ Clio supports diverse thinking mechanisms. If your model family uses a custom fo
 Once your runtime adapter descriptor is implemented:
 
 ### 5.1 Static Built-in Registration
-Add your descriptor to the static array export in [src/domains/providers/runtimes/builtins.ts](../src/domains/providers/runtimes/builtins.ts):
+Add your descriptor to the static array export in [src/domains/providers/runtimes/builtins.ts](../../src/domains/providers/runtimes/builtins.ts):
 ```typescript
 import { myCustomRuntime } from "./custom/my-custom-runtime.js";
 
@@ -198,4 +209,4 @@ export const BUILTIN_RUNTIMES = [
 ### 5.2 Dynamic Plugin Loading
 Clio's `RuntimeRegistry` can load custom runtimes dynamically at startup:
 * **Directories:** Place compiled Javascript descriptors (`.js`) inside `$CLIO_CODER_CONFIG_DIR/runtimes/` (defaulting to `~/.config/clio-coder/runtimes/`).
-* **Package exports:** Publish an npm package that exports a `clioRuntimes` array containing your runtime descriptors, then list the package name under `runtimePlugins` in your configuration settings.
+* **Package exports:** Publish an npm package that exports a `clioRuntimes` array containing your runtime descriptors, then list the package name under `integrations.runtimePlugins` in your configuration settings.

package/docs/{safety-model.md → architecture/safety-model.md}

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder Safety Model visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/safety_blueprint.html).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
@@ -11,9 +11,9 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 ## Two axes: autonomy and the safety net
 
-The `autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
+The `safety.autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
 
-In Clio Coder v0.4.0, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
+In the current source tree, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
 
 ### Autonomy levels
 
@@ -38,7 +38,7 @@ The exposure tier is the one row keyed by the call rather than by its action cla
 
 The `system_modify` confirm is level-invariant, so it is enforced and attributed as a safety-net confirm rail: the overlay, notices, and audit ledger name the net (reason code `system-modify-confirm`, policy source `builtin-classifier`), not the autonomy level. The matrix row above is unchanged in outcome at every level; only `read-only` converts the ask to a denial. `unknown` remains in the autonomy mapping because the registry substitutes a registered tool's base action class after the net evaluates.
 
-The level is persisted as `autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
+The level is persisted as `safety.autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
 
 ### Consequence tier is presentation, not authority
 
@@ -69,7 +69,7 @@ Every tool call, orchestrator or worker, evaluates in this order:
 
 1. **Safety net** (policy engine + middleware guards): `block` is final at every level; `ask` is a confirm rail (damage-control `ask` rules, project `requireConfirmation`, `system_modify`) that parks at every level; `pass` hands off to step 2. Blocks precede asks: a damage-control `ask` rule never bypasses a hard block, so confirming an ask-rule command that targets a zero-access path still blocks. The built-in path protection (which includes zero-access blocklists for critical files like `.git/config` and `credentials.yaml`, resolved with symlink canonicalization to prevent bypasses) is evaluated even when `.clio-coder/safety.yaml` is malformed, invalid, or attempts to override it. A malformed project policy cannot disable built-in default path protection, so credential protection never fails open.
 2. **Autonomy mapping**: the action class plus the level produce allow, ask, or deny per the matrix above.
-3. **Approvals**: whatever asked in step 1 or 2 parks interactively, denies deterministically headless, resolves per `workers.onPermission` in workers, and non-stall denies in delegations.
+3. **Approvals**: whatever asked in step 1 or 2 parks interactively, denies deterministically headless, resolves per `fleet.permissions.mode` in workers, and non-stall denies in delegations.
 
 ```mermaid
 graph TD
@@ -88,15 +88,20 @@ Net `confirm` is never auto-allowed by autonomy, including full-auto. Net `block
 
 ### Worker permission escalation
 
-Dispatched workers run non-interactively, so step 3 resolves per `workers.onPermission`: `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_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.
+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.
 
-Escalation can never hang a run. Every escalated ask resolves by an operator decision or by the `workers.escalation` timeout fallback (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`); a headless session has no subscriber, so the timeout fallback always governs there. The worker keeps emitting heartbeats while parked, so the reconciler does not reap it, and every escalation and its resolution source (operator or timeout) is recorded on the receipt.
+Escalation can never hang a run. Every escalated ask resolves by an operator decision or by the `fleet.permissions.escalation` timeout fallback (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`); a headless session has no subscriber, so the timeout fallback always governs there. The worker keeps emitting heartbeats while parked, so the reconciler does not reap it, and every escalation and its resolution source (operator or timeout) is recorded on the receipt.
 
 ---
 
 ## Operating Posture and Visible Tools
 
-Clio operates under a single operating posture with a standard, unified visible toolset. The 20 built-in tools are organized in seven planes; each plane is one policy unit for action class, size posture, and concurrency, asserted at bootstrap by `src/tools/policy.ts` so the classifier and the registered specs can never drift apart silently.
+Clio operates under a single operating posture. The canonical catalog contains
+21 built-in tools organized in seven planes; each plane is one policy unit for
+action class, size posture, and concurrency, asserted at bootstrap by
+`src/tools/policy.ts` so the classifier and registered specs cannot drift apart
+silently. Dependency wiring, target capability, worker profile, and recipe
+policy determine which subset is visible in a particular context.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
@@ -105,12 +110,12 @@ Clio operates under a single operating posture with a standard, unified visible
 | EXECUTE | `bash`, `verify` | `execute` |
 | EXECUTE | `git` | `read` |
 | ORCHESTRATE | `dispatch`, `steer` | `dispatch` |
-| ORCHESTRATE | `monitor`, `tasks` | `read` |
+| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes` | `read` |
 | RETRIEVE | `web_fetch` | `read` |
 | INTERACT | `ask_user` | `read` |
 | ARTIFACT | `artifact` | `write` |
 
-`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
+`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
 
 Target capability, dispatch tool profiles, and recipe constraints can further narrow the tools available to a run. That narrowing is convenience and budget control; safety still lives in code gates.
 
@@ -287,7 +292,7 @@ Dispatch workers can run the same HTTP or native runtimes as the orchestrator. C
 
 Three integration paths exist for driving Claude Code, ranging from fully enforced to advisory gating:
 
-- **`claude-sdk` (Enforced Safety):** Drives [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) directly. This is the **strong safety path** because Clio enforces tool gating before execution. Clio registers a `PreToolUse` hook (which fires for all tool uses, including auto-allowed reads) and wraps `canUseTool` for permission paths. Every tool request is mapped into a Clio tool/action class, evaluated by the safety net, and passed through the active autonomy matrix. Because a dispatched worker is noninteractive, any `ask` decision is resolved as a non-stall denial (`workers.onPermission=deny` returns denial; `workers.onPermission=fail` terminates the run with a permission-required code).
+- **`claude-sdk` (Enforced Safety):** Drives [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) directly. This is the **strong safety path** because Clio enforces tool gating before execution. Clio registers a `PreToolUse` hook (which fires for all tool uses, including auto-allowed reads) and wraps `canUseTool` for permission paths. Every tool request is mapped into a Clio tool/action class, evaluated by the safety net, and passed through the active autonomy matrix. Because a dispatched worker is noninteractive, any `ask` decision is resolved as a non-stall denial (`fleet.permissions.mode=deny` returns denial; `fleet.permissions.mode=fail` terminates the run with a permission-required code).
 - **`claude-code` (Subprocess Gating):** Drives `claude -p` as a subprocess. Because the CLI lacks a direct callback hook, Clio cannot evaluate each tool invocation. Instead, Clio maps the active autonomy level to the binary's command-line parameters (such as `--permission-mode` and tool allowlists). Unrecognized tools are gated by the subprocess runtime itself. Dispatch at autonomy `suggest` is refused outright (the same applies to `antigravity-code`): a subprocess cannot park a tool call for approval, so `suggest` has no honest mapping and the runner fails closed before launching the external CLI. A dangerous bypass (`--allow-dangerously-skip-permissions`) is only sent when autonomy is `full-auto` and `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1`, and it is never silent: the run's receipt records it (see the enforcement grades below) and evidence raises an external-bypass finding.
 - **Claude Code over ACP (Advisory Gating):** Drives Zed's `@zed-industries/claude-code-acp` (or `@agentclientprotocol/claude-agent-acp`) bridge as an [Agent Client Protocol (ACP)](https://agentclientprotocol.com) delegation agent. Clio's ACP mediator intercepts tool calls and filters them against the safety net, but gating is ultimately **advisory** as Claude governs its own runtime execution. For strict, code-enforced per-tool safety, `claude-sdk` is preferred over ACP.
 
@@ -330,8 +335,8 @@ When executing tasks in headless mode through `clio-coder run`, there is no term
 
 ### Workers and delegations
 
-- **Workers** inherit the session's autonomy level, capped by dispatch scope admission. A worker ask resolves per `workers.onPermission`: `deny` continues the run with a rejection; `fail` ends it; `escalate` forwards it to the interactive operator (see the escalation section above). All three values are editable in the `/settings` center.
-- **Delegations (ACP)** under `clio-policy` governance evaluate through the same net and autonomy mapping; an ask resolves as a non-stall deny so the external agent never hangs waiting for an operator.
+- **Workers** inherit the session's autonomy level, capped by dispatch scope admission. A worker ask resolves per `fleet.permissions.mode`: `deny` continues the run with a rejection; `fail` ends it; `escalate` forwards it to the interactive operator (see the escalation section above). All three values are editable in the `/settings` center.
+- **Delegations (ACP)** under `clio-coder-policy` governance evaluate through the same net and autonomy mapping; an ask resolves as a non-stall deny so the external agent never hangs waiting for an operator.
 - **ACP server sessions** (a remote client driving Clio) snapshot the autonomy level at `session/new`, so a mid-session settings change on the host cannot alter an in-flight remote session's admission decisions.
 
 ---
@@ -348,7 +353,7 @@ It is critical to distinguish these two control axes:
 
 | Setting | Axis | Governed By | Handled In |
 | --- | --- | --- | --- |
-| **Autonomy** | Authority | `autonomy` settings dial, `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | `src/tools/registry.ts`, `src/domains/safety/` |
+| **Autonomy** | Authority | `safety.autonomy` settings dial, `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | `src/tools/registry.ts`, `src/domains/safety/` |
 | **Rigor** | Validation | `CLIO_CODER_RIGOR` override, workspace validation contracts | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract-registration.ts` |
 
 ---

package/docs/{session-lifecycle.md → architecture/session-lifecycle.md}

@@ -1,6 +1,9 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.4.0`.
+> **Visual blueprint:** The source checkout includes the complete
+> [Session Lifecycle visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/session_lifecycle_blueprint.html).
+
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in the current source tree.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 
@@ -35,7 +38,7 @@ export interface ClioSessionMeta {
   endedAt: string | null;
   model: string | null;
   target: string | null;
-  clioVersion: string;
+  clioCoderVersion: string;
   piMonoVersion: string;
   platform: string;
   nodeVersion: string;
@@ -43,7 +46,7 @@ export interface ClioSessionMeta {
 }
 ```
 
-Format version `CURRENT_SESSION_FORMAT_VERSION = 4` (`src/engine/session.ts`) is stamped on all sessions created since the working-set layer landed. Version 4 adds the `contextEviction` and `contextRecall` ledger kinds. `runMigrations` in `src/domains/session/migrations/` rejects both directions on `/resume`: a missing or earlier version names the remedy (remove the session directory), and a version from the future says the session was written by a newer Clio and must not be read by this build.
+Format version `CURRENT_SESSION_FORMAT_VERSION = 4` (`src/engine/session.ts`) is stamped on all sessions created since the working-set layer landed. Version 4 adds the `contextEviction` and `contextRecall` ledger kinds. `runMigrations` in `src/domains/session/migrations/` performs the one supported additive migration from version 3 to version 4. A missing version or a version below 3 names the remedy (remove the session directory), while a version above 4 says the session was written by a newer Clio and must not be read by this build.
 
 ---
 
@@ -56,7 +59,7 @@ The session ledger `current.jsonl` records all conversation events, model turns,
 The first line of `current.jsonl` is the canonical session header:
 
 ```json
-{"type":"session","version":3,"id":"01912a34-b567-7890-abcd-ef0123456789","timestamp":"2026-08-14T12:00:00.000Z","cwd":"/path/to/project"}
+{"type":"session","version":4,"id":"01912a34-b567-7890-abcd-ef0123456789","timestamp":"2026-08-14T12:00:00.000Z","cwd":"/path/to/project"}
 ```
 
 ### Entry Taxonomy
@@ -171,7 +174,7 @@ When an operator issues `/new`, `/resume`, `/tree`, or `/fork` while an assistan
 
 ## 5. Session Resumption (`/resume`) & Working Directory Fallback
 
-When resuming a session via `/resume` or `CLIO_CODER_RESUME_SESSION_ID`:
+When resuming a session via `/resume` or a headless `clio-coder run --session <id>` / `--continue`:
 1. `src/domains/session/manager.ts:resumeSessionState` loads `meta.json` and runs migrations.
 2. `src/domains/session/cwd-fallback.ts:resolveSessionCwd` probes the recorded `meta.cwd` against the filesystem.
 3. If the directory is invalid, it returns a typed failure reason:

package/docs/architecture/time-conventions.md

@@ -0,0 +1,125 @@
+# Time and Clock Conventions
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Time and Clock Conventions visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/time_conventions_blueprint.html).
+
+This document describes the time practices implemented in the current Clio
+Coder source tree. The code distinguishes process-local elapsed spans from
+durable instants, but it does not impose one clock primitive on every module.
+
+---
+
+## 1. Choose a clock for the lifetime of the fact
+
+| Fact | Current practice | Representative sources |
+| --- | --- | --- |
+| Process-local elapsed span | Use a monotonic source such as `performance.now()` or `process.hrtime.bigint()` when the start and finish occur in one process. | `src/domains/dispatch/heartbeat.ts`, `src/domains/dispatch/code-step.ts`, `src/core/startup-timer.ts` |
+| Durable or cross-process instant | Store epoch milliseconds or canonical UTC from `new Date(...).toISOString()`. | Session entries, receipts, dispatch rows, audit rows |
+| Persisted expiry, lock age, or restart-visible deadline | Some owners intentionally compare `Date.now()` values because the fact must survive a process boundary or is derived from filesystem metadata. | `src/core/state-file-lock.ts`, dispatch admission and recovery |
+| Concurrent ordering | Prefer an explicit sequence or store order when the protocol supplies one; do not invent ordering from close timestamps. | `src/domains/dispatch/agent-ledger-store.ts`, `src/domains/dispatch/execution-scheduler.ts` |
+
+This means neither `performance.now()` nor `Date.now()` is universally correct.
+A monotonic value has meaning only within its clock origin and is the right
+choice for a live heartbeat age or one process's latency. A wall-clock value is
+necessary for a receipt timestamp, a persisted lease deadline, a filesystem
+mtime age, or a record another process must read after restart.
+
+### Combined anchor and span pattern
+
+When a record needs both a human-readable anchor and an accurate in-process
+duration, `src/domains/dispatch/code-step.ts` uses one wall anchor and one
+monotonic span:
+
+```ts
+const startedAtMs = Date.now();
+const clock = process.hrtime.bigint();
+const startedAt = new Date(startedAtMs).toISOString();
+// ... operation executes ...
+const durationMs = Number((process.hrtime.bigint() - clock) / 1_000_000n);
+const endedAt = new Date(startedAtMs + durationMs).toISOString();
+```
+
+The derived ending instant stays consistent with the measured duration even if
+the wall clock changes during the operation.
+
+### Cross-host and restart boundaries
+
+Never subtract process-local monotonic values from different processes or
+hosts. A restart has no shared monotonic origin with the worker it recovers;
+`src/domains/dispatch/orphan-recovery.ts` first adjudicates the host-scoped
+process identity and then uses the persisted heartbeat only as a display and
+evidence bound. Transport protocols that need a durable anchor and live
+liveness carry both. `HeartbeatStamp.current` is the wall-clock instant, while
+`HeartbeatStamp.monotonic` is the value the live watchdog compares.
+
+On a shared filesystem, a process record created by another host is not checked
+against the local process table. Host, pid, and process-birth facts prevent pid
+reuse and cross-host confusion. When exact event ordering matters, use a
+protocol sequence, SQLite rowid, or append order defined by the owning store.
+
+### Injectable seams are local contracts
+
+Clock injection exists where deterministic timing tests or protocol logic need
+it. Examples include the pure heartbeat classifier, dispatch admission queues,
+capacity leases, fleet preflight, worker spawn, and the audit writer's date
+function. Other modules read a platform clock directly. There is no global
+test-clock harness; tests use the seam supplied by the owner under test or
+exercise real passage explicitly.
+
+---
+
+## 2. UTC storage and local rendering
+
+Durable and wire timestamps use canonical ISO-8601 UTC strings produced by
+`toISOString()` unless a schema explicitly owns epoch milliseconds. Localized
+display strings do not belong in persisted models.
+
+Operator-facing conversion is centralized in
+`src/interactive/format-time.ts` for the surfaces that display session and
+message instants:
+
+| Function | Output | Purpose |
+| --- | --- | --- |
+| `clockLocal(instant)` | `HH:MM:SS` through `en-GB` with a 24-hour cycle | Local time of day |
+| `dateLocal(instant)` | `YYYY-MM-DD` through `en-CA` | Local calendar date |
+| `relative(instant, now)` | `3m ago`, `yesterday`, or a local date | Coarse recency |
+
+The module keeps its `Intl.DateTimeFormat` instances at module scope and
+rebuilds them when `process.env.TZ` changes. Machine-readable surfaces such as
+structured logs, session records, and receipts bypass these formatters.
+
+---
+
+## 3. Receipt and audit integrity
+
+Persisted receipt fields such as `startedAt` and `endedAt` participate in the
+integrity digest owned by `src/domains/dispatch/receipt-integrity.ts`. Timestamp
+normalization and duration derivation must finish before sealing. A sealed
+receipt must not be rewritten merely to make its clocks look tidier.
+
+Safety audit rows are written under:
+
+```text
+<stateDir>/audit/YYYY-MM-DD.jsonl
+```
+
+The filename date is the operator-local calendar date on which the writer
+opened that generation. Each row still carries a canonical UTC `ts`. Concurrent
+producers do not promise timestamp order in the raw file, so consumers sort by
+`ts` when reconstructing time order. The local date label is not itself a
+machine ordering key.
+
+---
+
+## 4. Review checklist
+
+When adding a timed fact:
+
+1. Decide whether it is a process-local span, a durable instant, or a
+   restart-visible deadline.
+2. Keep monotonic values inside their originating process.
+3. Persist UTC anchors and the measured duration when both are useful.
+4. Use host identity and process-birth evidence before consulting a local pid.
+5. Add a narrow injectable seam when deterministic tests need one; do not imply
+   that an unrelated module shares it.
+6. Normalize timestamps before sealing any receipt or evidence digest.

package/docs/{trace-store.md → architecture/trace-store.md}

@@ -1,7 +1,7 @@
 # Trace store contract
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Trace store contract visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/trace_blueprint.html).
 
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing
@@ -28,7 +28,12 @@ try to change it, because changing journal mode is a database write.
 The seven Clio trace tables are `runs`, `phases`, `events`, `envelopes`,
 `gate_results`, `agent_sessions`, and `processes`; `meta` carries the schema
 version. Runs use terminal run ids. Interactive session turns are also recorded
-as `runs` rows using `assignment_id = "session"`. A phase belongs to a run and carries its
+as `runs` rows, distinguished by `runs.source` (`'dispatch'` or `'session'`;
+a session turn also carries the historical sentinel `assignment_id =
+"session"`, which predates the column and is unchanged). `runs.source` is an
+additive column: a database created before it existed gains it in place on
+next open, backfilled from that sentinel, the same way `processes.host` and
+`processes.birth_token` were added without a schema-version bump. A phase belongs to a run and carries its
 assignment/worker-facing name, kind, owner, attempt, timing, status, itemized
 token spend, optional itemized dollar spend, total dollar spend, and context
 occupancy. Missing historical or unavailable component costs are `NULL`, never
@@ -83,7 +88,7 @@ writes before slower evidence builds.
 
 ## CLI Commands
 
-The `clio-coder trace` command surfaces 8 subcommands for inspecting, bounding, and querying the SQLite trace mirror:
+The `clio-coder trace` command surfaces 9 subcommands for inspecting, bounding, and querying the SQLite trace mirror, plus the code-step record files beside it:
 
 ```bash
 clio-coder trace runs [--db PATH] [--limit N] [--json]
@@ -91,6 +96,7 @@ clio-coder trace inspect --json
 clio-coder trace phases <runId> [--db PATH]
 clio-coder trace tail <runId> [--follow] [--db PATH]
 clio-coder trace procs <runId> [--db PATH]
+clio-coder trace code-steps <rootId> [--json]
 clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]
 clio-coder trace sql <SELECT query> [--db PATH]
 clio-coder trace ui [--db PATH] [--port N]
@@ -98,6 +104,8 @@ clio-coder trace ui [--db PATH] [--port N]
 
 `clio-coder trace --help` and every subcommand `--help` print usage and exit with code 0.
 
+`trace code-steps` is the one subcommand that does not read the mirror. A deterministic fleet code step is a subprocess, not a model run, so `src/domains/dispatch/code-step-store.ts` writes its `CodeStepRecord` to `<stateDir>/code-steps/<rootId>/<runId>.json` instead of fabricating route rows in the ledger. The command reads those files back oldest first, prints the record verbatim under `--json`, and treats an absent root directory as the empty state with exit 0. `--db` is ignored.
+
 ### Database Resolution and Error Handling
 
 When resolving the SQLite database path:
@@ -107,7 +115,7 @@ When resolving the SQLite database path:
 
 ### Subcommand Specifications
 
-1. **`runs`**: Lists recent dispatch runs from the trace store. `--limit` sets maximum rows (1 to 500, default 50); `--json` emits the selected trace rows as an array. Formats status, start time, total tokens, total USD cost, and run ID in text mode.
+1. **`runs`**: Lists recent dispatch runs and interactive session turns from the trace store. `--limit` sets maximum rows (1 to 500, default 50); `--json` emits the selected trace rows as an array. Formats status, `source` (`dispatch` or `session`), start time, total tokens, total USD cost, and run ID in text mode.
 2. **`inspect`**: Emits only `--json`, from the default database, with no caller-controlled path or window. The version-1 snapshot carries at most eight newest runs and bounded phase, event-kind, and process-kind aggregates. It omits request text, phase error prose, event payloads, command lines, PIDs, hosts, and database paths, and distinguishes an unavailable database from an available empty one through `available`.
 3. **`phases`**: Lists sequence phases for a designated `runId`. Displays status, attempt, owner, total tokens, USD cost, and phase name.
 4. **`tail`**: Displays append-ordered event rows for a designated `runId`. When `--follow` is specified, polls for new events every 500 ms until two consecutive idle polls observe a finished run status.

package/docs/{tui-design.md → architecture/tui-design.md}

@@ -1,9 +1,9 @@
 # Clio TUI Design System
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio TUI Design System visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tui_design_blueprint.html).
 
-This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
+This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../../src/interactive/).
 
 The governing principle: **the user reads state from color, structure from frames, and identity from brand marks.** Everything that is not state or structure remains visually quiet.
 
@@ -11,7 +11,7 @@ The governing principle: **the user reads state from color, structure from frame
 
 ## 1. Color System
 
-All color styling is defined in [src/interactive/theme/tokens.ts](../src/interactive/theme/tokens.ts). No raw SGR sequences, `38;2;`/`38;5;` ANSI escape fragments, or hardcoded hex colors are allowed outside this theme module.
+All color styling is defined in [src/interactive/theme/tokens.ts](../../src/interactive/theme/tokens.ts). No raw SGR sequences, `38;2;`/`38;5;` ANSI escape fragments, or hardcoded hex colors are allowed outside this theme module.
 
 ### 1.1 Color Tokens
 
@@ -43,7 +43,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../src/interac
 
 ## 2. Glyph Vocabulary
 
-All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../src/interactive/theme/glyphs.ts). Rendering code reference these names instead of embedding hardcoded glyph literals.
+All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../../src/interactive/theme/glyphs.ts). Rendering code reference these names instead of embedding hardcoded glyph literals.
 
 | Glyph | Name | Meaning | Used by |
 |---|---|---|---|
@@ -82,7 +82,7 @@ All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../src
 
 ## 3. Formatting Rules
 
-Standardized formatters live in [src/interactive/theme/labels.ts](../src/interactive/theme/labels.ts) and other shared UI modules:
+Standardized formatters live in [src/interactive/theme/labels.ts](../../src/interactive/theme/labels.ts) and other shared UI modules:
 
 - **Duration**: `formatCompactMs` is the unified duration formatter, yielding compact outputs (`860ms`, `4.2s`, `42s`, `1m36s`).
 - **Token Counts**: `formatFooterTokens` formats footer and chip counts (`842`, `12.4k`, `1.2M`). Full numeric strings via `toLocaleString` are reserved for detailed tables like the context legend.
@@ -95,7 +95,7 @@ Standardized formatters live in [src/interactive/theme/labels.ts](../src/interac
 
 ### 4.1 The Island (Framed Block)
 
-Rendered via `frame()` in [src/interactive/theme/rules.ts](../src/interactive/theme/rules.ts):
+Rendered via `frame()` in [src/interactive/theme/rules.ts](../../src/interactive/theme/rules.ts):
 
 ```
 ┌─ Title ──────────────────────────── meta ─┐
@@ -165,11 +165,11 @@ The words carry the meaning when color is disabled. Permission copy states the e
 
 ## 5. Screen Surfaces & State Choreography
 
-The Clio screen maintains a responsive, four-zone structure: the launchpad / session header, transcript, composer, and footer. `terminal.tuiMode` 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.
+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. `terminal.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, `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.
 
-`terminal.smoothStreaming` controls presentation-only pacing of derived assistant text and thinking. `off`, the 0.3.3 release default, is the existing 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. `CLIO_CODER_SMOOTH_STREAM` is the one-process escape hatch and takes precedence over settings; invalid values resolve to `off`.
+`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.
 
 Interactive startup uses one terminal lease across both boot stages. Stage 0 owns the terminal, renderer, root host, exact editor instance, input decoder, raw mode, resize subscription, protocol queries, signals, and stop lifecycle, and commits a measured minimal frame while services hydrate. Hydration synchronously swaps the root and input/signal delegates without reconstructing the editor or initializing terminal protocols again. Early Enter submissions become immutable, visibly queued admissions and drain once through the ordinary command pipeline; a later draft and cursor stay in the same editor. Boot failure or an early signal closes the lease exactly once, restores the terminal, and prints recoverable queued input and draft text. `CLIO_CODER_INSTANT_SHELL=0` selects the legacy fully hydrated first frame; ACP, headless, ordinary non-TTY invocation, and subcommand execution never acquire the lease. An explicit `CLIO_CODER_INTERACTIVE=1` retains its established force-interactive behavior on a non-TTY stream.
 
@@ -266,7 +266,7 @@ Turn usage receipts rendered at the bottom of completed turns respect the output
 
 ### 6.7 Code Ink (Syntax Highlighting)
 
-Syntax highlighting within code blocks is handled by [src/interactive/renderers/code-ink.ts](../src/interactive/renderers/code-ink.ts). It maps a restricted set of four tokens to stay quiet:
+Syntax highlighting within code blocks is handled by [src/interactive/renderers/code-ink.ts](../../src/interactive/renderers/code-ink.ts). It maps a restricted set of four tokens to stay quiet:
 
 - **Comments**: `dim`
 - **String Literals**: `success`
@@ -305,7 +305,7 @@ The `/settings` overlay is a full-screen transactional control center:
   - `Apply this session` (for live-capable settings)
   - `Apply and save globally`
   - `Cancel` (or `Esc`)
-  - Restart-required settings (`budget.concurrency`, `runtimePlugins`, `terminal.tuiMode`, and `terminal.fullscreenScrollbar`) offer only global save and announce `Saved to settings.yaml · restart Clio to apply`.
+  - Restart-required settings (`fleet.concurrency`, `integrations.runtimePlugins`, `interface.mode`, and `interface.fullscreenScrollbar`) offer only global save and announce `Saved to settings.yaml · restart Clio to apply`.
   - Destructive actions (target/profile removal) execute preflight analysis showing affected chat, fleet, and memory routes before confirmation.
 - **Fleet Workbench**: Organizes fleet settings with dim group headers (`Defaults`, `Profiles`, `Agent routes`, `Placement`). Profiles render as one-row summaries with `◆ Edit` affordance; pressing `Enter` drills into profile fields (target, model, thinking level, placement) or destructive removal.
 - **Targets Console Table**: Displays configured targets in an operational console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with an in-place action/detail drawer (URL, default model, last probe, failure reason). Actions include `Use`, `Connect`, `Probe`, and `Remove`. Active connect/probe operations show the single orange activity indicator.
@@ -335,7 +335,7 @@ Wrapping happens before the row cap, so the block is at most six rows tall at an
 
 ## 8. Shared Vocabulary
 
-One quantity gets one word, and every surface that shows it uses that word. A user comparing the transcript, the footer, and an overlay is checking whether Clio is telling a consistent story; a synonym reads as a discrepancy. `tests/contracts/usage-vocabulary.test.ts` holds the pairs that had drifted.
+One quantity gets one word, and every surface that shows it uses that word. A user comparing the transcript, the footer, and an overlay is checking whether Clio is telling a consistent story; a synonym reads as a discrepancy. The current vocabulary is owned by `src/interactive/chat-panel.ts`, `src/interactive/cost-overlay.ts`, `src/interactive/status/reasoning.ts`, and `src/interactive/thinking-level-policy.ts`; there is no standalone `usage-vocabulary` contract test in the current tree.
 
 | Concept | Word | Surfaces |
 | --- | --- | --- |