@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/architecture/model-catalog.md

@@ -49,19 +49,17 @@ campaign artifacts, credentials, and non-reference private endpoint details
 belong outside this repository. Use `clio-coder eval run --suite <path> --target <id>` and retain
 the resulting execution envelope when comparing models or serving settings.
 
-The current reference deployment has two local targets. `mini` is a llama.cpp
-router at `http://192.168.86.141:8080` serving `ornith1.5-35b-moe` with four
-slots and 262144 tokens of context per slot. `dynamo` is LM Studio at
-`http://192.168.86.143:1234`, serving `qwen3.8-27b-dynamo` for chat. These are
-operator-managed deployment facts, not compiled defaults; use a live probe to
-confirm availability before a run.
+Record deployment facts with each evaluation rather than treating a particular
+host/model pairing as a product default. Use a live probe and server configuration
+to establish context and slots; a shared KV pool is not one full independent
+context allocation per slot.
 
 ## What "sanctioned" means
 
 A model family is "sanctioned" only when we can say what was tested and under which runtime. It is not a blanket endorsement. For each family, capture:
 
 - exact model id / artifact / quantization;
-- provider or runtime surface (`lmstudio`, `ollama-native`, `llamacpp`, `openrouter`, `openai-codex`, etc.);
+- provider or runtime surface (`lmstudio`, `ollama`, `llamacpp`, `openrouter`, `openai-codex`, etc.);
 - hardware and serving configuration;
 - context window and max output actually exercised;
 - tool-use, reasoning, vision, embeddings/rerank/FIM behavior where relevant;
@@ -184,11 +182,13 @@ fleet worker default remains `fleet.default.thinkingLevel: off`; an explicit
 target, profile, roster member, command option, or in-session selection can
 override the applicable setting.
 
-- **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
+- **Ollama (`ollama`, native API):** Ollama uses native `think` request controls and the response’s `message.thinking` field. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
 - **LM Studio (`lmstudio`):** Chat uses the OpenAI-compatible `/v1/chat/completions` surface, including its `reasoning` stream field. Clio controls thinking only with `reasoning_effort` and never sends `chat_template_kwargs` to LM Studio. See <https://lmstudio.ai/docs/developer/openai-compat/chat-completions>.
 - **LiteLLM (`litellm`):** This is a gateway runtime, not an `openai-compat`
-  alias. Discovery checks `/health/liveliness`, reads routed names and capability
-  metadata from `/v1/model/info`, and records the physical deployment reported
+  alias. Authenticated `/v1/models` controls selectable aliases; `/v1/model/info`
+  (or `/model/info`) enriches exact matches. Restricted detail or public liveness
+  access does not invalidate a successful listing. An explicitly empty listing
+  stays empty, and detail-only aliases are unverified hints. Clio records the physical deployment reported
   by `x-litellm-*` response headers. Deterministic gateways should publish one
   `node/model` name per deployment; genuine multi-deployment aliases expose only
   the capabilities guaranteed by every route and use the smallest unanimously
@@ -246,7 +246,9 @@ LM Studio lists downloadable model keys alongside loaded model instances. When u
 - Bare keys that already have a resident instance are never sent as raw keys (avoiding duplicate GPU allocations).
 - Resolution prefers the target's `defaultModel`, then instances unique to that host.
 - Keys reported as loaded by multiple hosts are identified as LM Link peer projections and are excluded from auto-selection.
-- Unloaded keys trigger just-in-time loading as expected.
+- Unloaded keys can trigger the server’s just-in-time load policy. Explicit REST loading requires managed lifecycle and configured load options; `user-managed` never grants Clio explicit load/unload authority.
+- Without explicit loading, a temporary catalog failure does not gate the chat request. With explicit loading, metadata must be available to resolve the intended instance.
+- Only recognized resource-capacity errors permit fallback eviction of Clio-owned instances. Invalid options and authentication errors do not; a failed replacement triggers a bounded restoration attempt.
 
 ### llama.cpp Residency and Sleep Handling
 
@@ -255,6 +257,11 @@ To maintain router availability during model switches and idle states (#127, #13
 - If a model load is rejected, the reconciler reloads the previously evicted model to keep the slot occupied.
 - When the llama.cpp router reports an idle model as `sleeping`, Clio recognizes it as resident rather than requesting another load (preventing `400 model is already running` errors).
 
+Router metadata, load, unload, and polling requests carry the target’s configured
+headers and credentials and honor cancellation. User-managed targets remain
+observe-only. Recovery of a model displaced during reconciliation has a separate
+bounded deadline so cancellation does not abandon restoration immediately.
+
 ### Probed Context Window Precedence
 
 Loaded context window probe results take precedence over static or advertised catalog defaults (#129). When a local model server reports an active loaded context length via `/v1/models` or runtime probe, Clio adopts that measured window size for all subsequent token budgeting and compaction decisions.

package/docs/architecture/observability.md

@@ -157,7 +157,7 @@ New failed-compaction rows preserve missing usage fields as `null`. Positive par
 
 `clio-coder usage report` includes these calls in its known subtotals, labels the failed-attempt count, and exposes `failedCompaction.knownUsage`, `erroredKnownUsage`, and per-field `unobservedUsageCalls` in the token and model JSON facts. A field with missing coverage and no known positive amount is `null`, including cost-only or wholly unobserved failures. Text output identifies incomplete subtotals. The live `/cost` view records positive known contributions under a failed-compaction label; its numeric token counters remain known subtotals. These figures do not certify provider billing or complete spending. The existing session-cost ceiling checks the numeric known sum, so unreported cost does not become an enforced complete-cost bound.
 
-Eval tracked/stdout folds do not include the failed-compaction sidecar, and live `/cost` reseeding reads the session ledger rather than this store. A later usage report can therefore include retained failed-compaction amounts that those views omit. This consumer reconciliation is deferred to v0.4.5 or later; the retained known amounts must not be presented as complete cross-surface billing.
+In v0.5.0, eval tracked/stdout folds omit the failed-compaction sidecar, and live `/cost` reseeding reads the session ledger rather than this store. A later usage report can therefore include retained failed-compaction amounts that those views omit. These consumer projections remain separate; retained known amounts must not be presented as complete cross-surface billing.
 
 A failed or empty summary produces no checkpoint. Required failed-compaction usage appends are flushed and a write failure remains an explicit operation error; no model call is repeated to repair accounting. If checkpoint append throws, Clio checks that checkpoint's exact identity in the original ledger before choosing the sidecar: an already written checkpoint is not counted again, and proven absence permits the sidecar. An unreadable or malformed ledger that leaves persistence ambiguous fails visibly without a speculative duplicate write. This is the existing bounded usage store, not a new recovery store; its 1000-row retention and unknown telemetry limits still apply.
 

package/docs/architecture/pi-boundary.md

@@ -1,6 +1,6 @@
 # Pi SDK Boundary
 
-Clio Coder pins Pi 0.85.1 as its provider, agent-loop, and terminal SDK. This
+Clio Coder pins Pi 0.86.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
 `Keep` is an explicit boundary decision, not an invitation to replace the
@@ -14,7 +14,7 @@ Clio-owned surface during a dependency bump.
 | pi-ai `StringEnum` | `src/engine/ai.ts` | Route through Pi. | The deleted `src/tools/string-enum.ts` TypeBox adapter duplicated Pi's compact provider-safe schema. Tools now import the re-export from the engine boundary. |
 | pi-agent-core `COMPACTION_SUMMARY_PREFIX`, `COMPACTION_SUMMARY_SUFFIX`, `BRANCH_SUMMARY_PREFIX`, `BRANCH_SUMMARY_SUFFIX`, and `bashExecutionToText` | `src/interactive/chat-renderer.ts` through `src/engine/messages.ts` | Route through Pi. | Replay text must match Pi's `convertToLlm` wording while Clio keeps its `SessionEntry` mapping and replay bounds. |
 | pi-tui `stripTerminalSequences` | `src/domains/session/tree/preview.ts` | Keep the Clio sanitizer. | Pi removes SGR and OSC sequences but intentionally leaves private-mode CSI and character-set escapes that may occur in captured tool output. |
-| pi-ai `isRetryableAssistantError` | `src/domains/session/retry.ts` | Route generic classification through Pi and keep the Clio delta. | Clio additionally recognizes self-hosted model loading and enforces its separate 15-second floor. |
+| pi-ai `isRetryableAssistantError` and `retryDelayMs` | `src/domains/session/retry.ts` | Route generic classification and capped exponential backoff through Pi; keep the Clio delta. | Clio additionally recognizes self-hosted model loading and enforces its separate 15-second floor. |
 | pi-ai `retryAssistantCall` and pi-agent-core `AgentHarness` retry | `src/interactive/chat-loop.ts` and `src/interactive/turn-recovery.ts` | Keep Clio orchestration. | Clio retries `agent.continue()` with a visible cancellable countdown. `retryAssistantCall` wraps one completion, and `AgentHarness` requires Pi's session repository. |
 | pi-ai `StreamOptions.samplingParams`, `OpenAICompletionsOptions.thinkingBudgets`, and `supportsThinkingTokenBudget` | `src/engine/apis/openai-completions.ts` | Route request controls through Pi. | Clio retains only catalog-to-option selection and runtime-specific payload fields. |
 | pi-ai `compat.thinkingFormat` | `src/engine/apis/openai-completions.ts` payload adapters | Keep the LM Studio and llama.cpp deltas. | Pi has no LM Studio TTL or draft-model field and no llama.cpp `cache_prompt` field. |
@@ -28,7 +28,7 @@ Clio-owned surface during a dependency bump.
 | pi-ai `CredentialStore` and `Models.getAuth` | `src/domains/providers/auth/storage.ts` | Keep Clio ownership. | Clio's locked YAML store, damage control, target-first registry, and runtime overrides are product boundaries. |
 | pi-ai `createModels`, `createProvider`, and `ModelsStore` | `src/domains/providers/**` | Keep Clio ownership. | Targets, nodes, probing, residency, ALCF, and fleet placement are Clio concepts rather than provider-keyed SDK state. |
 | pi-ai `Provider.auth.oauth` | `src/engine/oauth.ts` | Route built-in OAuth through Pi and keep ALCF. | Pi owns provider OAuth implementations. Clio adds the ALCF science-provider flow. |
-| pi-agent-core `findCutPoint` and `findTurnStartIndex` | `src/domains/session/compaction/cut-point.ts` | Keep the current implementation pending a tested adapter. | These helpers are public root exports in 0.85.1. They accept Pi v4 `Entry[]`; Clio uses its own `SessionEntry` union, ledger indexes, tool-batch boundaries, and small-session fallback. Reuse requires preserving those contracts through an entry/index projection, not a direct import substitution. |
+| pi-agent-core `findCutPoint` and `findTurnStartIndex` | `src/domains/session/compaction/cut-point.ts` | Keep the current implementation pending a tested adapter. | These helpers are public root exports in 0.86.1. They accept Pi v4 `Entry[]`; Clio uses its own `SessionEntry` union, ledger indexes, tool-batch boundaries, and small-session fallback. Reuse requires preserving those contracts through an entry/index projection, not a direct import substitution. |
 | pi-agent-core `estimateTokens` and `estimateContextTokens` | `src/domains/session/compaction/tokens.ts` and `src/domains/session/context-accounting.ts` | Keep Clio's outer accounting. | Pi also anchors estimates to provider usage. Clio additionally accounts for framing, system prompts, tool schemas, pending input, usage invalidation, and the greater of projected and anchored totals. Both use heuristics for unmeasured content; neither character estimate guarantees an upper bound for every tokenizer. |
 | pi-agent-core `generateSummary`, `generateSummaryWithUsage`, and `serializeConversation` | `src/domains/session/compaction/compact.ts` and `src/domains/session/compaction/branch-summary.ts` | Keep the current summary boundary pending a tested adapter. | The public summary generators accept `AgentMessage[]`, `Models`, and Pi harness context; `serializeConversation` accepts provider messages. Clio additionally owns bounded cumulative checkpoints, turn-prefix summaries, cancellation, usage settlement, and publication checks. The internal `SUMMARIZATION_SYSTEM_PROMPT` constant is not a public root export. |
 | pi-agent-core `JsonlSessionRepo`, v4 `Session`, and `AgentHarness` | `src/engine/session.ts` and `src/domains/session/**` | Keep Clio ownership. | The on-disk ledger, active tree, fork behavior, receipts, and evidence are Clio's durable spine. |
@@ -49,10 +49,63 @@ Clio-owned surface during a dependency bump.
 | pi-ai OpenAI-compatible reasoning replay and signature serialization fixes (0.84.3, 0.84.4) | `src/engine/apis/openai-completions.ts` | Inherit. | The wrapper delegates `stream` and `streamSimple` to Pi's adapter. Clio persists raw assistant content blocks, including `thinkingSignature`, and restores them through rich replay; Pi decides whether signatures remain usable for the selected model and transport. |
 | pi-ai Anthropic server-side refusal fallback with returned-model pricing (0.84.3) | `src/interactive/turn-context.ts` `reconcileUsage` and `src/domains/observability/trace-store.ts` | Inherit. | Usage and cost arrive already priced for the returned model; Clio records `message.model` as reported. `fallbacks` is only sent for catalog models that declare `allowedFallbackModels`. |
 | pi-tui capability overrides (`PI_HYPERLINKS`, `PI_IMAGE_PROTOCOL`, `PI_TRUE_COLOR`, `setCapabilityOverrides`) and `PI_TUI_ESC_TIMEOUT` (0.84.2, 0.84.4) | `src/interactive/theme/tokens.ts` truecolor detection | Decline. | These govern pi-tui's own image, hyperlink, and escape-sequence handling. Clio's theme detects truecolor from `COLORTERM` and `TERM` independently and does not consume pi-tui capability detection. |
-| pi-tui `TuiAltScreenOptions.copyOnSelect` / `copySelection` and transcript search (`tui.altScreen.search*`, 0.84.2, 0.84.4) | `src/interactive/interactive-shell.ts` alt-screen construction and `src/domains/config/keybindings.ts` | Inherit defaults. | Selection copy stays on by default. Search is pi-tui's viewport listener and runs before Clio's router; `ctrl+g` advances a match only while the search overlay is focused, so the Clio leader chord is unavailable during a search and nowhere else. Locked by the engine lifecycle contract. |
+| pi-tui `TuiAltScreenOptions.copyOnSelect` / `copySelection` and transcript search (`tui.altScreen.search*`, 0.84.2, 0.84.4) | `src/interactive/interactive-shell.ts` alt-screen construction and `src/domains/config/keybindings.ts` | Inherit defaults. | Selection copy stays on by default. The tracked input-policy patch runs Clio's router before Pi's viewport listeners; `ctrl+g` advances a match only while the search overlay is focused, so the Clio leader chord is unavailable during a search and nowhere else. Locked by the engine lifecycle contract. |
 | pi-tui alternate-screen direct-row painting (0.84.2) | `src/engine/instrumented-tui.ts` | Inherit. | `compositeOverlays`, `extractCursorPosition`, and `applyLineResets` still run inside one `doRender`, so Clio's frame and phase measurements are unchanged. Locked by the engine lifecycle contract. |
 
-## 0.85.1 integration
+## 0.86.1 integration
+
+All three direct Pi dependencies are pinned to **0.86.1** in the manifest and
+lockfile. Only pi-tui is patched. Pi's agent core and AI providers run stock
+JavaScript. The dependency graph uses Pi's declared Anthropic SDK 0.124.0;
+Clio does not force the older client. See [patch ownership and alternatives](../../patches/README.md).
+
+The breaking change is transcript ownership. `Agent.state.systemPrompt` is a
+read-only projection of system messages. Pi's `normalizeContext` folds legacy
+`systemPrompt` and `tools` into a leading system message; it **does not deduplicate**
+a transcript that already contains that baseline. Clio therefore sends native
+transcripts with `messages` only and builds legacy prompt/tool snapshots only
+where a Clio-owned consumer needs them.
+
+| Pi 0.86.1 surface | Clio adaptation and reason |
+| --- | --- |
+| `normalizeContext`, `getCurrentSystemPrompt`, `getCurrentTools` | `src/engine/context.ts` delegates section patches, prompt concatenation, and tool additions/removals to Pi. Native API dispatch and OpenAI completions preserve the transcript; Ollama's custom wire and worker request projection consume the resolved snapshot. Clio does not implement its own transcript reducer. |
+| `createInitialSystemMessage`, `toToolDeclaration` | Session replay and prompt recompilation replace Clio's complete baseline through `replaceEngineMessages` / `setEngineSystemPrompt`. Clio persists its compiled prompt and conversation separately, so rehydration intentionally produces one baseline, not a second prompt appended to the old one. Executable tools remain in `state.tools`; only portable declarations enter messages. |
+| Parent-to-worker context and tool-free side rounds | Fork/splice capture excludes parent system/tool declarations before validating complete conversation batches. The child retains its own compiled prompt and executable loadout. Side-question and handoff rounds similarly drop session system entries before installing their own tool-free prompt. First-turn middleware counts conversation only. |
+| `AgentLoopTurnUpdate.context` | Post-tool compaction returns the complete rebuilt transcript and executable tools. The active loop receives the new prompt and retained conversation before its continuation. No obsolete top-level `systemPrompt` is carried on that context. |
+| System messages in `Agent.state.messages` | Conversation accounting, measured-anchor indexes, snapshots and replay comparisons exclude system entries because system text and schemas already have their own budget categories. Worker result offsets are measured after Agent construction, excluding the injected baseline and every inherited message. |
+| `getToolStateChanges`, public context transforms, `convertToLlm` | Warming copies the transcript, declares changed executable tools using Pi's diff, then applies the same transforms and conversion as a real turn. Transformed system messages and tools reach the provider intact. Warming never executes tools or appends its response to the session. Local residency, foreground ownership, input limits and billing admission remain Clio policy. |
+| `resolveTranscript` and provider compatibility flags | Pi decides whether a model receives mid-conversation system messages/tool additions or a collapsed request. The completions wrapper transforms assistant reasoning without flattening system history. Legacy custom stream delegates still receive a resolved request snapshot for compatibility. |
+| Retry and overflow fixes | Clio inherits Pi's Cloudflare 520/Azure transient-error classification and z.ai overflow detection. Capped exponential delay uses Pi's public `retryDelayMs`; model-loading floors, cancellable UI countdowns, stream-stall limits and `Agent.continue()` recovery remain Clio-owned. |
+| Cache retention and provider request assembly | Pi continues to own native cache-control fields and provider-specific retention behavior. Clio supplies target policy, session identity, local-runtime fields and measured cache telemetry. Upstream coding-agent prompt warming is not a public pi-agent-core/pi-ai warm API and does not replace Clio's local-only admission and lifetime rules. |
+| Meta provider and Muse OAuth | Environment-key parity includes `META_API_KEY`. This upgrade does not invent a new Clio built-in runtime or activate every Pi provider. Clio's explicitly selected provider catalogs and OAuth flows remain tied to supported runtime descriptors; out-of-tree runtime plugins can use the public Pi provider factory. |
+| pi-tui native platform helpers | The pinned package supplies `darwin-platform.node`, `win32-platform.node`, and `linux-platform-x11.node` for arm64/x64. The installed-package check verifies these assets; the old Darwin modifiers-only filename no longer exists. Pi owns clipboard and modifier integration. |
+| pi-tui rendering, LaTeX, fuzzy matching and file completion fixes | Inherited through the unchanged public TUI wrappers. Stock 0.86.1 still lacks the application input ordering and semantic edit/search APIs required by Clio, so the narrowly scoped TUI patch remains. |
+
+Regression coverage includes `engine-transcript`, `engine-lifecycle`,
+`provider-context-boundary`, compaction controls and skill checkpoints,
+`live-context-anchor`, worker context tests, `prewarm-request-path`,
+`prewarm-lifecycle`, and keyboard maintenance tests. The warm-versus-real fixture
+uses a local HTTP server and compares serialized request prefixes after system
+and tool changes; provider-payload capture tests stop before any network I/O.
+
+### Dispatch schema compatibility found during live verification
+
+Pi 0.86.1's non-strict Anthropic tool serializer retains the root `properties`
+and `required` fields but omits root `$defs`. Clio previously referenced shared
+intent, budget, and worker-context definitions from those properties. The wire
+therefore contained unresolved references, and Haiku/Sonnet supplied JSON strings
+where dispatch required objects. Clio now inlines those nested schemas in its
+own tool declaration. A regression captures Pi's actual Anthropic payload before
+network I/O and validates both single and batched dispatch arguments against it.
+
+The duplication adds prompt tokens; it avoids a provider rewrite or another SDK
+patch. Enabling strict sampling globally would change model compatibility and is
+not equivalent to repairing the existing non-strict path. Once upstream preserves
+root definitions on that path, shared references can be reconsidered with the
+same wire regression. No upstream issue is claimed here.
+
+## Earlier 0.85.1 integration
+
 
 The three SDK packages stay on the same exact version. The older Anthropic
 client override is removed so Pi can use its declared `@anthropic-ai/sdk`
@@ -86,7 +139,7 @@ Review these files first when Pi changes. They intentionally contain little
 behavior and should not grow another implementation of an SDK primitive.
 
 - `src/engine/api-registry.ts` owns Clio's ordered dispatcher using Pi's public lazy API factories and the provider catalogs selected in `src/engine/models.ts` for Clio's built-in runtimes. Its dynamic `/compat` bridge exists only for configured out-of-tree runtime plugins that require Pi's process-global registry identity.
-- `src/engine/env-api-keys.ts` pins Pi 0.85's synchronous environment-key and ambient-credential discovery behind a parity contract; revisit it on every Pi upgrade until Pi exports that helper directly.
+- `src/engine/env-api-keys.ts` pins Pi 0.86.1's synchronous environment-key and ambient-credential discovery behind a parity contract; revisit it on every Pi upgrade until Pi exports that helper directly.
 - `src/engine/apis/openai-completions.ts` maps compatibility flags, sampling parameters, and thinking budgets. Its Clio deltas are the local-runtime guards and sentinel, Harmony, and Gemma filters.
 - `src/engine/provider-payload.ts` retains only the OpenAI Responses reasoning-summary patch.
 - `src/engine/types.ts` and `src/engine/ai.ts` expose erased Pi types and `StringEnum` behind the engine boundary.

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

@@ -4,36 +4,89 @@ Clio Coder keeps the model-facing envelope stable and moves enforcement into the
 
 Source of truth: `src/core/tool-names.ts`, `src/tools/agent-tools.ts`, `src/tools/bootstrap.ts`, `src/tools/policy.ts`, `src/tools/observation.ts`, `src/tools/ignore-policy.ts`, and the per-tool modules under `src/tools/**`.
 
-## One system prompt per session
+## Typed composition and cache identity
 
-The chat loop compiles one provider-facing system prompt for a session. The
+The chat loop compiles a provider-facing system prompt from typed inputs. The
 version-2 compile identity hashes the target id, runtime id, wire model id,
 autonomy, session id, working directory, sorted working-context paths, context
 window source, prompt-input epoch, resolved session inputs, and the exact
 attached tool-schema bytes. `mainPromptCacheIdentity` in
 `src/interactive/prompt-cache-identity.ts` owns that list.
 
-The compiled prompt is reused byte-for-byte on ordinary submits. Handbook source bytes and prompt inputs are captured per session, so ordinary recompilation does not silently reload edited files. Init, refresh, and reset invalidate the session snapshot and prompt cache, including partial-write failure paths; config hot-reload also invalidates inputs. Path-scoped rules can recompile when a matching file enters working context. When recompilation changes the text, the ledger records `promptRecompiled` with previous hash, new hash, and token estimate. The bounded handbook preload retains exact safe prefixes; captured-source hashes belong to its accounting/manifest metadata. Model-facing omission notices identify source paths and line ranges, and later filesystem retrieval reads current bytes.
+The compiled prompt is reused byte-for-byte when the complete identity is unchanged. Host-supplied turn constraints and ready-skill counts are part of the resolved session inputs, so changing them recompiles the appropriate conditional sections. Handbook source bytes and prompt inputs are captured per session, so ordinary recompilation does not silently reload edited files. Init, refresh, and reset invalidate the session snapshot and prompt cache, including partial-write failure paths; config hot-reload also invalidates inputs. Path-scoped rules can recompile when a matching file enters working context. When recompilation changes the text, the ledger records `promptRecompiled` with previous hash, new hash, and token estimate. The bounded handbook preload retains exact safe prefixes; captured-source hashes belong to its accounting/manifest metadata. Model-facing omission notices identify source paths and line ranges, and later filesystem retrieval reads current bytes.
 
 ## Section order: stable prefix first
 
-The compiled prompt lays its sections down in `SESSION_PROMPT_SECTION_ORDER` (`src/domains/prompts/compiler.ts`): identity, operating contract, delegation, skills, safety, tool contract, fleet, retrieval hints, project context, memory, runtime, then the operator-editable tail fragments (workspace root, Clio repo awareness, project rules, operator profile) in their own order.
+The immutable prefix contains identity and the constitutional operating contract. Its `stablePrefix` metadata records the exact UTF-8 byte count and SHA-256, including the following section separator. Machine paths and tool-dependent documentation routing live in a separate harness-awareness section after project context, so changing gateway access or installation paths cannot disturb the constitution. Worker prompts expose the same measurement for their own identity and shared/assigned-task contracts.
 
-One rule fixes that list. A section goes as late as its volatility, and anything that reads a clock, a probe, or a mutable store goes after everything that does not. Every backend Clio targets caches by exact prefix and re-prefills from the earliest changed byte, so a section that can change between two turns must not sit ahead of sections that cannot. The runtime block is last of the compiled sections because its `Context window: N` moves when the backend reloads a model or a co-residency clamp lands; memory sits just ahead of it because an approved memory record rewrites that section mid-session; project rules are dead last because path-scoped rules join the prompt when a matching file enters working context.
+The remaining layers contain conditional role guidance, safety, the factual tool inventory and admitted hints, fleet information, retrieval hints, captured project context, harness-awareness, memory, runtime, and customization fragments. Current task scope renders last. Memory and effective-context-window changes preserve the preceding bytes. A changed tool surface or conditional role layer invalidates from its first changed byte; a stable-prefix hash is a reuse candidate, not a claim that the backend actually reused KV state.
 
-`Context window: N` is the window the backend will actually serve. A recorded loaded window outranks a probe, which reports a figure the target advertises without saying it is what is open, so a resumed session states the window its ledger measured rather than a re-probed server-wide number. Each prompt-manifest record carries that window and the layer that answered it (`contextWindow`, `contextWindowSource`) alongside a `version` for the prompt layout itself, so a recompile whose only cause was the window moving is explained by the record rather than inferred.
+`TurnConstraints` comes from `src/core/turn-constraints.ts`; the compiler shares `turnAllowsTool` with admission. `mode` is an explicit host workflow switch (`answer`, `proposal`, or `change`), never inferred from English and never an authorization grant. Answers omit delegation/fleet workflows and validation pressure. Proposals omit implementation validation and task-board hints and state that implementation remains blocked. Tool allowlists suppress forbidden capability guidance, including secondary gateway calls; the Direct tools line still describes the actual attached schemas. No-delegation and disabled skills remove their associated instructions. Unknown inputs retain the ordinary policy. This is a typed compiler, with a few fragment substitutions, not a general template language.
 
-`PROMPT_MANIFEST_VERSION` (`src/domains/session/prompt-manifest.ts`) is `2` as of this release, and the reordering above is what moved it. The field is additive: a record written by 0.3.8 carries no `version` and reads back as version 1, so a `prompt-manifest.jsonl` from an older session still parses. The rule for the field is that it tracks the layout rather than the inputs. Bump it when the compiled text moves for a reason other than a changed fragment, a changed tool surface, or a changed setting, so that a resumed session has the version in hand to explain the single `promptRecompiled` entry its first compile writes.
+The composition root snapshots the ready-skill count by workspace, prompt-source epoch, trust/discovery settings, and explicit skill paths, sharing it with the reminder rather than rescanning files on each compile check. Ready-skill count zero omits activation instructions. The once-per-session skills reminder requires a ready model-visible skill; marketplace entries alone do not arm it. Answer/proposal modes, disabled skills, and tool restrictions suppress both the reminder and its suggestion-wait continuation. When enabled, discovery is conditional on a useful workflow rather than a mandatory first step. Explicit skill requests continue through the existing activation/admission channel.
 
-### What not to add to the prefix
+Native Pi 0.86.1 transcript semantics remain unchanged. Warming and actual requests must compare their effective prompt and ordered schema identities after public transforms and payload hooks. A boot warm cannot predict a future task's narrower surface: such a change is an expected prefix disturbance, not proof of cache failure.
+
+`Context window: N` is the window Clio budgets this turn against. It is a
+resolved figure, not proof of backend capacity: `contextWindowSource`
+(`src/domains/providers/runtime-resolution.ts`) records which layer answered, and
+the answer may be `loaded`, `probe`, `target-override`, `catalog`, `model-hint`,
+`descriptor-default`, or `unknown`. Only the first two rest on anything observed.
 
-Two additions look free and are not.
+The resolver combines requested, configured, observed, and saved limits rather
+than treating them as interchangeable. See [context window
+resolution](context-engine.md#context-window-resolution) for the precedence and
+capacity safeguards.
 
-The first is a terseness rule. It is tempting to cap the prose a model emits between tool calls, because that text is generated tokens on every hop of a long turn. Anthropic measured that exact change on Claude Code and reported a 3 percent quality regression, so a word-count or verbosity limit on inter-tool text is a bad trade: the tokens it saves are the cheapest ones in the turn, and the model's own narration of what it is about to do is load-bearing for what it then does. Bound tool results instead, where a single `grep` can cost thousands of tokens and the envelope caps already do the work.
+Each prompt-manifest record carries that window and the layer that answered it
+(`contextWindow`, `contextWindowSource`) alongside a `version` for the prompt
+layout itself, so a recompile whose only cause was the window moving is explained
+by the record rather than inferred.
 
-The second is anything that varies with the wall clock or the working tree. No timestamp, no `git status`, no branch name, no session id, and no run id belongs anywhere in the compiled prefix. Every backend Clio targets caches by exact prefix and re-prefills from the earliest changed byte, so one such field turns the whole prompt into a cache miss on every turn for no information the model could not have asked a tool for. On the sprint's measurement server that is a whole 2,778-token prompt re-prefilled at 2.6 s where the same change behind the stable sections cost 516 tokens and 0.72 s. Volatile facts belong in the user message, in a tool result, or in the runtime block, which is last for this reason.
+`PROMPT_MANIFEST_VERSION` (`src/domains/session/prompt-manifest.ts`) is `3` for the typed layer layout and separate harness-awareness section. Version 2 recorded the earlier stable-prefix ordering. The field is additive: a record written by 0.3.8 carries no `version` and reads back as version 1, so a `prompt-manifest.jsonl` from an older session still parses. The rule for the field is that it tracks the layout rather than the inputs. Bump it when the compiled text moves for a reason other than a changed fragment, a changed tool surface, or a changed setting, so that a resumed session has the version in hand to explain the single `promptRecompiled` entry its first compile writes.
 
-The disk fragments under `src/domains/prompts/fragments/` are layered by who reads them. `identity.clio` and `operating.contract` are constitutional: they render for every reader, name no tool, and state what is always true about Clio and her harness. `operating.delegation` (the delegation threshold as a count taken before the first edit, with the dispatch call shape beside it; receipts, spot-checks, shared `[worker result]` notes) renders only when `dispatch` is on the session's tool surface, and `operating.skills` (skill-shaped tasks, `/skill <name>` suggestions) only when `context` is; a fragment that teaches a tool is absent when the tool is, the same rule the Fleet block follows. `identity.docs-routing` directs questions about Clio herself through `gateway(op="call", capability="clio_docs", args={query: ...})` before answering or searching the workspace. It renders only when Clio self-awareness is present, `gateway` is on the supplied tool surface, and provider tool support is not explicitly false. This gate does not depend on `context`, and tool hints cannot establish tool availability. The Skills fragment retains direct `context(scope="skills")` listing and operator-activation guidance; its secondary catalog guidance uses `clio_library` only when `gateway` is on the attached direct-tool surface and explicitly says that route is unavailable without it. Catalog reads activate and install nothing. `identity.self-awareness` (installed paths, code outranks docs, configuration locations) names no tool and is unconditional. `operating.worker` (the assigned-task contract) renders only for dispatched workers, which never see the coordinator fragments. `safety.<level>` states what runs, what is approval-required, and what is blocked at the effective autonomy, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name, so the same body is true on every surface; the session and every worker read that one body, and what "approval-required" resolves to is the only role text (one operator confirmation for the session, the worker's `onPermission` routing for a worker).
+### What not to add to the prefix
+
+Keep task-specific and volatile facts out of the immutable identity and
+constitutional prefix. Put current state in the appropriate changing layer,
+user message, or tool result. The runtime layer precedes customization and the
+final task-scope layer.
+
+Stable effective prompt and tool-schema bytes make prefix reuse possible on
+backends that support it. They do not guarantee a cache hit: serving policy,
+residency, and the backend's cache implementation also matter. Use reported
+cache evidence to assess reuse, rather than assuming a fixed latency saving.
+
+Bound tool results with the existing envelope caps. Treat any proposed limit on
+model narration as a behavior change to evaluate, not an established quality or
+cost improvement.
+
+The disk fragments under `src/domains/prompts/fragments/` are layered by who
+reads them. The governing rule is that a fragment which teaches a tool is absent
+when the tool is, the same rule the Fleet block follows.
+
+| Fragment | Renders when | Contents |
+| --- | --- | --- |
+| `identity.clio` | The default main-session identity; the compiler uses the identity selected by its inputs. | Clio’s identity. Workers instead use `identity.clio-coder-worker`. |
+| `operating.contract` | The default main-session operating contract and the shared contract in worker prompts. | Constitutional operating rules, preceding conditional capability guidance. |
+| `identity.self-awareness` | The selected identity is `identity.clio` and the fragment is present in the table (`compiler.ts:673`). | Installed paths, code outranks docs, configuration locations. Names no tool. |
+| `operating.delegation` | `sessionCanDispatch` holds, meaning provider tool support is not explicitly false, `dispatch` is on the surface, and `turnAllowsTool` admits it; and the turn mode is not `answer` (`compiler.ts:244`, `compiler.ts:701`). `proposal` mode still renders it. | The delegation threshold as a count taken before the first edit, the dispatch call shape, receipts, spot-checks, and shared `[worker result]` notes. |
+| `operating.skills` | `sessionCanUseSkills` holds: provider tool support is not explicitly false, `context` is on the surface and admitted by `turnAllowsTool`, `skillDiscoveryEnabled` is not false, turn constraints do not disable skills, the mode is not `answer`, and `readySkillCount` is not zero (`compiler.ts:259`). | Skill-shaped tasks and `/skill <name>` suggestions, plus direct `context(scope="skills")` listing and autonomy-aware activation guidance. |
+| `identity.docs-routing` | `identity.self-awareness` rendered, provider tool support is not explicitly false, `gateway` is on the surface, and `turnAllowsTool` admits `clio_docs` (`compiler.ts:676`). | Routes questions about Clio herself through `gateway(op="call", capability="clio_docs", args={query: ...})` before answering or searching the workspace. |
+| `operating.worker` | The reader is a dispatched worker, which never sees the coordinator fragments. | The assigned-task contract. |
+| `safety.<level>` | Always, selected by the effective autonomy level. | What runs, what is approval-required, and what is blocked, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name. |
+
+`identity.docs-routing` does not depend on `context`, and tool hints cannot
+establish tool availability. The Tool Contract independently describes agent,
+prompt, fleet, and package discovery through `clio_library` when `gateway` and
+that capability are admitted and the scope permits workflow discovery, so
+disabling skill discovery alone does not hide the rest of the library. Catalog
+reads activate and install nothing.
+
+The `safety.<level>` body is the same on every surface: the session and every
+worker read that one body, and the only role-specific text is what
+"approval-required" resolves to, meaning one operator confirmation for the
+session and the worker's `onPermission` routing for a worker.
 
 Prompt extensions can add dynamic fragments for project rules, the operator profile, and Clio source-tree awareness. Pending skill requests and middleware reminders are visible text in the user message, not hidden prompt machinery.
 
@@ -56,7 +109,58 @@ In addition to project root `CLIO-CODER.md` handbooks, Clio supports directory-s
 
 `wiki.page` and `wiki.plan` (`src/domains/prompts/fragments/wiki/*.md`) load through this same loader, with the same id/version/content-hash contract as every other fragment, but they are consumed differently: `context/wiki/prompts.ts` reads them by id, substitutes per-dispatch `{{token}}` placeholders (a page's path, title, and relative path; the plan file's path), and sends the result as a wiki-generation dispatch's `task`, never as a compiled system prompt. `{{token}}` substitution has no home in the fragment loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders use in `compiler.ts`: the loader hands back a raw body, and the one caller that needs live values fills them in. Both files' bodies open and close on a standalone `---` line that predates their frontmatter and was kept unchanged as body text so the substituted prompt stays byte-identical to what the old hand-rolled `readFileSync` produced.
 
-The Tool Contract section of the prompt renders a fixed set of base lines plus one optional guidance sentence per tool, sourced from the tool registry (`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in `src/tools/bootstrap.ts`). The base lines cover the complete-surface rule, the harness model (direct tools, fleet workers, skills as distinct capability sets), the capability-inventory rule, tool-free answering, the narrow-orientation tool list, validation before final claims, and failure recovery through `gateway(op="call", capability="clio_docs", args={query: ...})` instead of blind retries. Delegation, the tasks board, and skill listing are not restated here: `operating.delegation`, the `tasks` hint, and `operating.skills` each say their rule once and render exactly when their tool is on the surface. Fleet routing, including the sentence that `agent:"auto"` is a fallback rather than a router, lives in the Fleet block next to the roster ids and is not restated here; the threshold that says when to delegate at all is the opening of `operating.delegation`, not a Fleet line, because on the round-2 drive with Qwen3.8-27B the bare threshold after the tool contract lost to inertia on every run, while the same count stated up front with the call shape next to it dispatched both workers on every two-changes run and scout on every reconnaissance run once the sentence about repository size was in place. The chat loop derives the hint list once from the session's frozen tool surface at compile time, and the compiler renders the hints sorted by tool name, so the compiled text depends only on which hinted tools are on the surface. The frozen name list is the surface: a hint renders only for a tool in that list, and the gates that decide whether the Delegation, Skills, and docs-routing passages render read the same list, so a stale hint can neither render itself nor pull in a passage for a tool the model cannot call. Today six tools carry hints: `ask_user`, `bash`, `code_nav`, `context`, `panes`, and `tasks`. A hint carries only a decision-local call shape the tool's own description cannot; policy that applies across tools is said once in its prompt section, so `dispatch` carries no hint. Removing a tool from the surface removes its hint with no compiler change; adding a hint to a tool is a deliberate prompt-text change that must land with updated prompt contract tests and a CHANGELOG note.
+The Tool Contract section of the prompt renders a fixed set of base lines plus
+one optional guidance sentence per tool, sourced from the tool registry
+(`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in
+`src/tools/bootstrap.ts`).
+
+The base lines cover the complete-surface rule, the harness model (direct tools,
+fleet workers, skills as distinct capability sets), the capability-inventory
+rule, tool-free answering, the narrow-orientation tool list, validation for
+authorized file changes within scope, and schema correction after argument
+errors. Policy denials do not invite another route.
+
+Six tools carry hints today: `ask_user`, `bash`, `code_nav`, `context`, `panes`,
+and `tasks`. A hint carries only a decision-local call shape the tool's own
+description cannot; policy that applies across tools is said once in its prompt
+section, so `dispatch` carries no hint.
+
+<details>
+<summary>Why delegation and fleet routing are not restated here</summary>
+
+Delegation, the tasks board, and skill listing are not restated in the Tool
+Contract. `operating.delegation`, the `tasks` hint, and `operating.skills` each
+say their rule once and render exactly when their tool is on the surface.
+
+Fleet routing, including the sentence that `agent:"auto"` is a fallback rather
+than a router, lives in the Fleet block next to the roster ids.
+
+The threshold that says when to delegate at all is the opening of
+`operating.delegation` rather than a Fleet line. On the round-2 drive with
+Qwen3.8-27B, the bare threshold placed after the tool contract lost to inertia on
+every run, while the same count stated up front with the call shape next to it
+dispatched both workers on every two-changes run and scout on every
+reconnaissance run once the sentence about repository size was in place.
+
+</details>
+
+<details>
+<summary>How the hint list is frozen, and what changing it requires</summary>
+
+The chat loop derives the hint list once from the session's frozen tool surface
+at compile time, and the compiler renders the hints sorted by tool name, so the
+compiled text depends only on which hinted tools are on the surface.
+
+The frozen name list is the surface. A hint renders only for a tool in that list,
+and the gates that decide whether the Delegation, Skills, and docs-routing
+passages render read the same list, so a stale hint can neither render itself nor
+pull in a passage for a tool the model cannot call.
+
+Removing a tool from the surface removes its hint with no compiler change. Adding
+a hint to a tool is a deliberate prompt-text change that must land with updated
+prompt contract tests and a CHANGELOG note.
+
+</details>
 
 ## One tool surface per session
 
@@ -107,29 +211,23 @@ engine assumes.
 | ARTIFACT | `artifact` | write | sequential |
 | GATEWAY | `gateway` | read (inner call retains its class) | sequential |
 
-Several tools sit in a plane for containment rather than class. `git` is
-read-only inspection (op=status/diff/log) that runs on the safe-exec spine, so
-it lives in the EXECUTE plane with read-class safety disposition. `monitor`
-never mutates a run, so it stays read class and parallel inside the ORCHESTRATE
-plane. `tasks` orchestrates the agent's own work rather than workers: board
-mutations append session task-ledger snapshots, and calls can reconcile the
-project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done`
-update its durable correlation. These Clio-owned bookkeeping effects retain
-read class without granting source-workspace mutation authority. Calls run
-sequentially so two board mutations in one batch cannot interleave. `ledger` is the agent ledger, the coordination
-board concurrent dispatch workers share: a post reaches a one-way control lane
-and a read answers from a local mirror, so it touches no workspace and stays
-read class, and reviewers and judges are pinned to read-only autonomy where a
-write class would block the peer review the board exists for. `panes` controls
-only Clio-owned terminal panes through the live mux; it stays read class but is
-sequential so two operations cannot race the same pane registry. `evidence` sits in the OBSERVE plane
-because it only reads canonical evidence, trust status, gate decisions, and
-findings, but it is sequential because `run` mode may materialize a bundle
-under Clio's data directory. `limitation` and `decide` sit in the ORCHESTRATE
-plane as read class: each appends one typed receipt or decision-board entry
-to the session ledger and touches nothing else. `limitation` is parallel
-because the call is pure; `decide` is sequential so two decisions in one batch
-cannot race the supersede lookup.
+Several tools sit in a plane for containment rather than class:
+
+| Tool | Placement | Why |
+| --- | --- | --- |
+| `git` | EXECUTE plane, read class | Read-only inspection (`op=status/diff/log`) that runs on the safe-exec spine. |
+| `monitor` | ORCHESTRATE plane, read class, parallel | It never mutates a run. |
+| `tasks` | Read class, sequential | It orchestrates the agent's own work rather than workers. Sequential so two board mutations in one batch cannot interleave. |
+| `ledger` | Read class | A post reaches a one-way control lane and a read answers from a local mirror, so it touches no workspace. Reviewers and judges are pinned to read-only autonomy, where a write class would block the peer review the board exists for. |
+| `panes` | Read class, sequential | It controls only Clio-owned terminal panes through the live mux. Sequential so two operations cannot race the same pane registry. |
+| `evidence` | OBSERVE plane, sequential | It only reads canonical evidence, trust status, gate decisions, and findings, but `run` mode may materialize a bundle under Clio's data directory. |
+| `limitation` | ORCHESTRATE plane, read class, parallel | It appends one typed receipt to the session ledger and touches nothing else. The call is pure. |
+| `decide` | ORCHESTRATE plane, read class, sequential | It appends one decision-board entry and touches nothing else. Sequential so two decisions in one batch cannot race the supersede lookup. |
+
+For `tasks`, board mutations append session task-ledger snapshots, and calls can
+reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and
+linked `done` update its durable correlation. These Clio-owned bookkeeping
+effects retain read class without granting source-workspace mutation authority.
 
 Registration is conditional on wiring: `context` gains its workspace scope only
 when a session contract is bound, `dispatch`/`monitor`/`steer` register only
@@ -150,11 +248,11 @@ Several tools absorb what used to be separate tools:
 
 - `find(pattern, path?, order?, limit?, include_ignored?)` locates paths by glob pattern (`*`, `**`, `?`, `[abc]`), default limit 500. `order="path"` (default) returns fd's native order; `order="mtime"` returns newest first from a bounded candidate set instead of statting the whole tree, and reports `details.candidates` when the candidate cap made the ordering approximate.
 - `grep(pattern, path?, mode?, glob?, ignore_case?, literal?, context?, limit?, include_ignored?)` searches file contents with ripgrep, degrading to a bounded pure-Node search when rg is absent. `mode=content` (default) returns line-referenced matches, `mode=files` returns matching paths, `mode=count` returns per-file counts. Context lines are consumed from rg's `--json` stream.
-- `context(scope="workspace"|"skills"|"recall")` observes the session workspace snapshot, activates installed skills, or retrieves persisted historical results. Recall accepts `ref` for exact retrieval or `query`, `limit`, and `offset` for discovery. Bundled docs and recipe browsing use gateway capabilities `clio_docs` and `clio_library`.
+- `context(scope="workspace"|"settings"|"skills"|"recall")` observes the session workspace snapshot, explains effective settings through an allowlisted read-only projection, activates installed skills, or retrieves persisted historical results. Settings reads use the session settings getter, support query/limit/offset pages, omit credentials and arbitrary command configuration, and return an unavailable error when no authoritative getter is bound. Recall accepts `ref` for exact retrieval or `query`, `limit`, and `offset` for discovery. Bundled docs and recipe browsing use gateway capabilities `clio_docs` and `clio_library`.
 - `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` lists package.json verification scripts and strict version-1 or version-2 `.clio-coder/verifiers.yaml` entries through the same `{id, description, command, cwd, timeoutMs, tags, source}` projection. Version 1 supports command checks; version 2 also supports `numeric-compare` and `perf-budget` judgements. New catalogs use version 2; see the [project verifier contract](../guide/tool-usage.md#project-verifier-catalog). `verify(check="<id>")` runs a package script or the catalog's exact argv/cwd/timeout through safe-exec with no shell. Model `args`, cwd, timeout, output-cap, and environment fields cannot mutate a project entry. `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
 - `gateway(op="call", capability="artifact", args={kind: "plan"|"review"|"report", content: ...})` writes named artifacts: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is authored outside protected active skill roots with the ordinary write tool and validated by the library validator before operator installation.
 - `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona`, `tool_profile`, and a typed `budget: {toolCalls, readReserve, retryRevision?}`. The budget must fit the recipe's authored range and the operator lifetime cap. `retryRevision` is the only authority for a later retry, result-contract revision, or review revision to grow its phase. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
-- `monitor(run_id?, mode?)` is read-only visibility into known synchronous and detached runs: `list` enumerates, `status` reports one, `peek` returns the in-process event tail, `receipt` exposes the stored evidence, and `wait` observes one run without collecting or canceling it. `collect` is the authoritative terminal batch operation over a detached batch or run-id list; collect before final synthesis. Completed output reports receipt integrity, evidence verification, briefing provenance, and bounded project-context provenance as different fields.
+- `monitor(run_id?, mode?)` is read-only visibility into known synchronous and detached runs: `list` enumerates, `status` reports one, `peek` returns the in-process event tail, `receipt` exposes the stored evidence, and `wait` observes one run without collecting or canceling it. `collect` is the authoritative terminal batch operation over a detached batch or run-id list; collect before final synthesis. Completed output retains receipt integrity, evidence verification, briefing provenance, and bounded project-context provenance as distinct detail fields. Successful typed internal-helper results use compact text and `details.runs[].helperResult`; full receipts remain available on demand. The coordinator uses grounded helper results for navigation without routinely repeating their investigation.
 - `steer(run_id, action, message?)` controls a running worker: `guide` writes a canonical trimmed steering message to an HTTP or SDK worker and `cancel` terminates it. Successfully written steers gain ordered byte/hash/timestamp provenance; after the runtime accepts the guidance, `clio_coder_steer_received` acknowledges the exact matching sequence, and prose is never stored in ledger or receipt. Single-shot subprocess runtimes and ACP remain non-steerable. Interactive operators can steer synchronous live-input runs; parent-model steering requires detached ids because model tools are sequential.
 
 ### One ignore policy for path walkers
@@ -193,7 +291,7 @@ Tool descriptions are tiered by how much a wrong call costs. The hot tools the m
 
 ## Direct placement and the capability gateway
 
-`src/tools/surface.ts` owns placement independently of policy planes. Direct tools are `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`, `context`, `code_nav`, `verify`, `run_script`, and `gateway`, plus all ORCHESTRATE and INTERACT members when their dependencies are bound. Gateway capabilities are `artifact`, `web_read`, `web_fetch`, `git`, `evidence`, `credential_present`, `clio_docs`, `clio_library`, `data`, extension commands, and trusted local MCP tools. The permanent context schema retains only workspace, skills, and recall.
+`src/tools/surface.ts` owns placement independently of policy planes. Direct tools are `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`, `context`, `code_nav`, `verify`, `run_script`, and `gateway`, plus all ORCHESTRATE and INTERACT members when their dependencies are bound. Gateway capabilities are `artifact`, `web_read`, `web_fetch`, `git`, `evidence`, `credential_present`, `clio_docs`, `clio_library`, `data`, extension commands, and trusted local MCP tools. The permanent context schema retains workspace, settings, skills, and recall.
 
 `gateway(op="find"|"describe"|"call", capability?, query?, args?)` is read class and sequential. Its inner call runs through canonical registry admission with the capability's own class, skill restrictions, approvals, and cancellation. Nested accounting counts the model call once. `effectiveToolCall` restores capability identity for artifact folding, mutation observers, path indexing, exported evidence, and transcripts. Terminal artifact results, images, and details survive routing. Gateway placement changes schema attachment, not authority or evidence.
 
@@ -237,3 +335,13 @@ intended replacement. Unchanged spans keep their original bytes, including
 smart punctuation and CRLF line endings. Ambiguous duplicate matches,
 overlapping hunks, empty changes, and no-op edits are rejected instead of
 guessing.
+
+## Execution-environment awareness
+
+The main session workspace fragment includes the current OS account and machine
+hostname alongside the workspace root. These values come from the same local
+identity detector used for run receipts, are quoted as data, and are captured in
+the session prompt snapshot. They identify the process environment, not a verified
+person or the remote inference server. They are sent to the selected model as
+prompt context; configure does not persist a new personal profile or machine field.
+A new session on another machine captures that machine’s identity.

package/docs/architecture/provider-adapter-cookbook.md

@@ -73,7 +73,7 @@ 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:
+The `probe` method passively validates endpoint reachability and collects metadata. It must not submit inference or use a model-specific endpoint that can start a worker. Keep generating qualification explicit:
 
 * **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:
@@ -83,7 +83,7 @@ The `probe` method validates endpoint reachability and collects loaded models:
   * `modelStates` (optional): Footprint mappings detailing VRAM/RAM loading stats.
 
 ### 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).
+A runtime can supply a `probeReasoning` method, invoked only for explicit reasoning qualification (`targets --probe --reasoning`). The OpenAI-compatible helper sends a short completion with `reasoning_effort: low` and recognizes nonempty `reasoning_content`, `reasoning`, or `reasoning_text` response fields. Observed reasoning is positive evidence; an ordinary answer, error, or timeout is inconclusive (`null`), not proof that reasoning is unsupported.
 
 Clio caches this result in the providers domain by exact target and model id for
 the current process. Provider reinitialization, configuration reload, and target