@iowarp/clio-coder 0.3.8 → 0.4.0

package/docs/commands-and-modes.md

@@ -1,7 +1,7 @@
 # Commands and Modes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.3.8).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.4.0).
 
 
 Clio Coder is a terminal-first alpha harness. This page keeps the command
@@ -46,11 +46,18 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder auth login [target-or-runtime] [--api-key <value>]` | Add credentials through the supported flow. |
 | `clio-coder auth logout [target-or-runtime]` | Remove stored credentials. |
 | `clio-coder doctor [--fix] [--json]` | Diagnose state; with `--fix`, create missing structure and templates, repair credential permissions, and refresh install metadata. Settings remain strict and are not migrated. |
+| `clio-coder tools list [--json]` | List the pinned external tool registry and whether each program resolves from `PATH`, Clio's vendored data directory, or nowhere. |
+| `clio-coder tools status <id> [--json] [--reset-profile]` | Inspect one registered tool. `--reset-profile` applies only to yazi's generated profile. |
+| `clio-coder tools install <id> [--force] [--json]` | Download the platform asset, verify every declared checksum, and atomically vendor it. |
+| `clio-coder tools remove <id>\|--all [--json]` | Remove Clio-vendored copies without touching a program found on `PATH`. |
+| `clio-coder panes install` | Alias for `clio-coder tools install herdr`. |
 | `clio-coder reset [--state\|--data\|--cache\|--auth\|--config\|--all] [--dry-run] [--force]` | Reset selected Clio Coder state. `--state` is the default level. |
 | `clio-coder uninstall [--dry-run] [--remove-binary] [--force]` | Remove Clio Coder state and print uninstall guidance. |
 | `clio-coder upgrade [--dry-run] [--channel=<latest\|beta\|dev>] [--skip-migrations]` | Refresh state metadata, apply migrations, and update npm installs when applicable. |
 | `clio-coder agents [--json] [--all]` | List discovered agent specs. |
-| `clio-coder fleet list\|run\|status\|drain\|resume` | List `.clio-coder/fleets/*.md` contracts, run one, show dispatch state, or control admission. `drain` denies new execution starts for up to one hour and preserves running work; `resume` reopens admission immediately. `run <name>` takes `[--var k=v ...]` and `[--json]`; `status`, `drain`, and `resume` each take `[--json]`. |
+| `clio-coder fleet list\|run\|status\|drain\|resume` | List fleet contracts, run one, show dispatch state, or control admission. `drain` denies new execution starts for up to one hour and preserves running work; `resume` reopens admission immediately. `run <name>` takes `[--var k=v ...]` and `[--json]`; `status`, `drain`, and `resume` each take `[--json]`. |
+| `clio-coder fleet view <runId\|fleetRootId> [--follow]` | Read the append-only run journal after verifying receipt trust. A fleet root prints its durable step index. `--follow` requires an interactive terminal and one run id. |
+| `clio-coder fleet view --watch <selection-file>` | Follow the run id currently named by the selection file and retarget when it changes. This is the operator-pulled watch surface used by the pane integration. |
 | `clio-coder dev components [list] [--json]` | List behavior-affecting harness components. |
 | `clio-coder dev components snapshot --out <path>` | Write a component snapshot JSON file. |
 | `clio-coder dev components diff --from <a> --to <b> [--json]` | Compare component snapshots. |
@@ -105,6 +112,15 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `--tool-profile <name>` | Restrict dispatched-agent tools: `minimal-local`, `science-local`, or `full-agent`. |
 | `--require <capability>` | Require a target capability for dispatch. Repeatable. |
 | `--steer-channel <path>` | Read live steering lines from a FIFO or an appended regular file to steer the active run. |
+| `--with-panes` | Activate guest pane integration for this invocation when Clio is already inside a reachable herdr session. It overrides `panes.enabled`. |
+| `--no-panes` | Disable pane integration for this invocation. It overrides `panes.enabled`. |
+
+`--with-panes` is an explicit first-class launch mode, not permission to start a
+pane server. Clio confirms `HERDR_ENV=1`, connects to an existing socket, and
+pings it before registering pane tools. The fleet watch pane runs
+`fleet view --watch` against a selection file. Clio writes only the selected run
+id, while the viewer reads journals itself, so dispatch remains independent of
+the pane host and a second terminal can use the same journal surface directly.
 
 ### Headless Session Continuity
 
@@ -164,6 +180,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/tasks` | `/tasks add <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
 | `/memory` | `/memory seed` | Inspect, promote, or seed task memory |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
+| `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane |
 | `/thinking` | `/thinking [level]` | Set the chat thinking level, or open Settings → Orchestrator |
 | `/output` | `/output [verbosity]` | Set transcript detail (minimal, default, verbose), or open Settings → Terminal |
 | `/model` | `/model [pattern]` | Open model selector or set a model |
@@ -195,6 +212,14 @@ There are no slash-command aliases. `/context compact`, `/quit`, `/model`,
 spellings stay errors that name `/help` instead of guessing which operation the
 operator intended.
 
+`/model` never changes routing on its own. Both spellings, the picker and
+`/model <pattern>`, resolve the swap and then ask where it lands: `Apply this
+session`, `Apply and save globally`, or `Cancel`. Session is the default and
+touches no file, so a mid-conversation experiment dies with the session that
+made it; global is the same write the settings center performs, and it is the
+only one a later launch inherits. Cancel leaves the model where it was. A
+thinking level named in the pattern follows the same choice.
+
 `/btw <question>` runs one model round beside the session and renders the answer
 in an overlay. It sends the same compiled message history the next turn would
 send, as read-only input, under a short system instruction saying this is a side
@@ -277,6 +302,10 @@ it is never sent to the model. That covers spellings removed outright, such as
 behavior where an unrecognized spelling reached the model as prose and was answered
 conversationally, which left the operator believing a command had run when nothing had.
 
+A headless `clio-coder run "/typo"` refuses the same way. The verdict is reached
+before boot, so no session is opened and no turn is spent; the diagnostic names
+the token on stderr and the run exits `2`, the usage-error code.
+
 Command-shaped means one word of letters, digits, hyphens, or colons after the slash, so
 paths such as `/home/user/notes.md` still reach the model unchanged. One word
 followed by prose is treated as a command, because `/status please` and `/tmp is

package/docs/configuration-and-targets.md

@@ -1,7 +1,7 @@
 # Configuration, Targets, Runtimes, and Auth
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive configuration validator, target resolver, and CLI command generator is located at [docs/html/configuration_blueprint.html](html/configuration_blueprint.html) (Version: 0.3.8).
+> **Interactive Spec Available:** An interactive configuration validator, target resolver, and CLI command generator is located at [docs/html/configuration_blueprint.html](html/configuration_blueprint.html) (Version: 0.4.0).
 
 Clio Coder is target-first: chat and fleet dispatch resolve through configured targets in `settings.yaml`, not through provider-specific ad hoc flags. Chat and print targets are HTTP and native engine-backed runtimes. Fleet dispatch can also target the sanctioned Claude Code subscription runtimes described below.
 
@@ -29,7 +29,7 @@ Default config file:
 <configDir>/settings.yaml
 ```
 
-Role contents: config holds user-authored files (settings, credentials, agents, skills, prompts, extensions, runtimes); data holds durable artifacts (memory, evidence, evals); state holds machine-produced session state (sessions, audit, receipts, runs.json, recent-models.json, install.json, interop.json, interviews, scratch); cache holds disposable derived files.
+Role contents: config holds user-authored files (settings, credentials, agents, skills, prompts, extensions, runtimes); data holds durable artifacts (memory, evidence, evals, vendored external tools); state holds machine-produced session state (sessions, audit, receipts, runs.json, recent-models.json, install.json, interop.json, interviews, scratch); cache holds disposable derived files.
 
 The `library` settings block configures the private resource catalog. `library.catalog` is an optional path and defaults to `<configDir>/library.yaml`. `library.remote` is an optional git remote URL, and the catalog repository must name that git remote `library`. `library.sync` defaults to `false`, which makes sync and push refuse before spawning git. `library.confirmedRemote` is written by `clio-coder library remote confirm <url>` and must exactly match `library.remote` before sync or push can run. Confirmation sets both values when `library.remote` is unset and refuses a differing configured URL with `library_remote_mismatch`. See [resource-library.md](resource-library.md).
 
@@ -139,6 +139,9 @@ targets:
     runtime: lmstudio
     url: http://127.0.0.1:1234
     defaultModel: your-model-id
+    # Optional. Request slots this inference endpoint can serve at once.
+    # Overrides live discovery; omit it and Clio reads the server's own count.
+    maxConcurrentRequests: 2
     capabilities:
       reasoning: true       # optional; only if your model/runtime supports it
     lmstudio:
@@ -173,7 +176,7 @@ memory:
     everyNTools: 10
     windowSteps: 8
     maxTokens: 400
-    timeoutMs: 180000        # shipped operator default in src/core/defaults.ts; library fallback in task-memory-policy.ts is 20000 ms
+    timeoutMs: 30000         # shipped operator default in src/core/defaults.ts; the library fallback in task-memory-policy.ts is the same value
 
 workers:
   default:
@@ -256,6 +259,9 @@ context:
     protectLastTurns: 6
     minEvictableTokens: 200
 
+prewarm:
+  enabled: true       # send the next turn's prefix early; local-native targets only
+
 retry:
   enabled: true
   maxRetries: 3
@@ -273,6 +279,26 @@ guardrails:
 
 Target capability overrides may include `chat`, `tools`, `toolCallFormat`, `reasoning`, `thinkingFormat`, `structuredOutputs`, `vision`, `audio`, `embeddings`, `rerank`, `fim`, `contextWindow`, and `maxTokens`.
 
+### `maxConcurrentRequests`
+
+`maxConcurrentRequests` is a per-target integer of at least 1, validated with the rest of the target block, and it is the operator's override for how many requests the inference endpoint behind that target can serve at once. It is not a settings-file default and has no shipped value, so it does not appear in the settings inventory below.
+
+Set it only when discovery is wrong. Clio resolves the limit in this order: this override; then a `parallelSlots` count cached on the target's probe result; then one slot for any other `local-native` runtime; then no bound at all for a cloud runtime, vLLM, or SGLang. llama.cpp discovery reads `total_slots` from the router's `/props`, falls back to the selected worker's `/props?model=<id>` when the router reports none, and falls back again to the `--parallel` argv on the selected `/v1/models` entry. LM Studio reads `config.parallel` off the loaded instance and otherwise reports one; Ollama reads `OLLAMA_NUM_PARALLEL` from the environment the Clio process can see and otherwise reports one.
+
+The limit is keyed on the endpoint rather than the target, so two targets pointed at the same normalized URL share it. Raising it above what the server will actually serve does not create capacity; it removes the refusal that would have told you the server was full. See [capacity-and-scheduling.md](capacity-and-scheduling.md) for the admission model and the exact denial text.
+
+### The `local-native` tier
+
+Three behaviors in this release are gated on a runtime's tier being `local-native` rather than on a target id or a server name, so it is worth stating what the tier is. It is a property of the runtime descriptor (`RuntimeTier` in `src/domains/providers/types/runtime-descriptor.ts`), and the runtimes that carry it are `llamacpp` with its completion, embedding, rerank, and Anthropic-surface variants, `lmstudio`, `ollama-native`, `vllm`, `sglang`, and the two `lemonade` surfaces. Everything else is `cloud`, `protocol`, or `subscription`.
+
+The tier means "an inference server the operator runs, whose prefix cache and resident model Clio's own behavior can displace." That is what the three gates are actually asking:
+
+- **Pre-warm** runs only here, whatever `prewarm.enabled` says, because a cloud provider bills the request and caches on its own schedule. The check is made twice, once from configuration before any runtime is resolved and once against the resolved runtime, so an unreachable target does not pay for a capability probe at boot just to be told no.
+- **Endpoint capacity** defaults to one slot here when discovery reports nothing, and to unbounded elsewhere. vLLM and SGLang are the deliberate exceptions inside the tier: both serve genuinely concurrent requests, so an undiscovered limit is left unbounded rather than guessed at one.
+- **Five of the eight expected-cold reasons** are stamped only here, because a single-slot local cache is the only one an interleaved run actually displaces. The other three moved the prompt bytes themselves and are stamped on every tier. The full split is in [context-engine.md](context-engine.md#cache-divergence-honesty).
+
+The tool-prose-loop detector is keyed on the same tier, for the same reason: narrating a tool call instead of emitting one is a behavior of open-weight models served locally, and a list of server names would have left an Ollama or vLLM run with no cutoff at all.
+
 ### LM Studio transport and settings
 
 The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias,
@@ -482,19 +508,19 @@ The Settings Center organizes all configuration under four non-selectable group
 
 | Group | Section | Rows, in order |
 | --- | --- | --- |
-| **CORE** | Autonomy & Safety (`safety`) | `autonomy`, `workers.onPermission`, `delegation.defaults.toolGovernance`, `skills.trustProjectCompatRoots`, and the read-only safety-net fact. |
-| **CORE** | Orchestrator (`orchestrator`) | `orchestrator.thinkingLevel`, `orchestrator.target`, `orchestrator.model`, the memory plane (`background.target`, `background.model`, `background.thinkingLevel`), and the proactive-memory knobs (`memory.intervention.enabled`, `.everyNTools`, `.windowSteps`, `.maxTokens`, `.timeoutMs`). Changing target rebases model and thinking choices. |
-| **ROUTING** | Fleet (`fleet`) | `workers.default.target`, `workers.default.model`, `workers.default.thinkingLevel`, `workers.maxRetries`, `workers.profiles`, and `workers.agentBindings`, rendered under the group headers `Defaults`, `Profiles`, `Agent routes`, and `Placement`. Profile rows carry a `◆ Edit` drill-down and a destructive removal preflight; placement rows are read-only node status. |
+| **CORE** | Autonomy & Safety (`safety`) | `autonomy`, `workers.onPermission`, the escalation bounds that keep that posture non-stall (`workers.escalation.timeoutMs`, `workers.escalation.fallback`), `delegation.defaults.toolGovernance`, `skills.trustProjectCompatRoots`, and the read-only safety-net fact. |
+| **CORE** | Orchestrator (`orchestrator`) | `orchestrator.thinkingLevel`, `orchestrator.target`, `orchestrator.model`, the memory plane (`background.target`, `background.model`, `background.thinkingLevel`), and the proactive-memory knobs (`memory.intervention.enabled`, `.everyNTools`, `.windowSteps`, `.maxTokens`, `.timeoutMs`), and `prewarm.enabled`. Changing target rebases model and thinking choices. |
+| **ROUTING** | Fleet (`fleet`) | `workers.default.target`, `workers.default.model`, `workers.default.thinkingLevel`, `workers.maxRetries`, `workers.resilienceCooldownMs`, `workers.profiles`, `workers.agentBindings`, and the routing activation set (`routing.activeRoles`, `routing.activePostures`, and the read-only `routing.agentAutomation.activeAgentRoles`), rendered under the group headers `Defaults`, `Profiles`, `Agent routes`, `Route activation`, and `Placement`. Profile rows carry a `◆ Edit` drill-down and a destructive removal preflight; placement rows are read-only node status. |
 | **ROUTING** | Targets (`targets`) | The `targets` console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with an in-place action and detail drawer for URL, default model, last probe, and failure reason. Actions include `Use`, `Connect`, `Probe`, and `Remove`. |
 | **ROUTING** | Models (`models`) | `scope`, `modelSelector.recentLimit`, and `modelSelector.favorites`, rendered as a provider-backed checklist with target-level and target/model entries, `Space` toggle, capability inspector, and a preserved `Unavailable` group. Deep link `/scoped-models`. |
-| **RUNTIME** | Budget (`budget`) | `budget.sessionCeilingUsd`, `defaults.maxTokens`, and `budget.concurrency` (restart required). |
-| **RUNTIME** | Compaction (`compaction`) | `compaction.auto`, `compaction.threshold`, and `compaction.excludeLastTurns`. |
-| **RUNTIME** | Retry (`retry`) | `retry.enabled`, `retry.maxRetries`, `retry.baseDelayMs`, and `retry.maxDelayMs`. |
+| **RUNTIME** | Budget (`budget`) | `budget.sessionCeilingUsd`, `defaults.maxTokens`, `budget.concurrency` (restart required), and the six `guardrails.*` backstops under a `Guardrails` group header. |
+| **RUNTIME** | Compaction (`compaction`) | `compaction.auto`, `compaction.threshold`, `compaction.excludeLastTurns`, and the five `context.workingSet.*` keys under a `Working set` group header. |
+| **RUNTIME** | Retry (`retry`) | `retry.enabled`, `retry.maxRetries`, `retry.baseDelayMs`, `retry.maxDelayMs`, and `retry.streamStallMs`. |
 | **EXPERIENCE** | Terminal (`terminal`) | `terminal.showTerminalProgress`, `terminal.outputVerbosity` (`minimal`, `default`, `verbose`), `terminal.tuiMode` (`regular`, `fullscreen`), `terminal.fullscreenScrollbar` (`hidden`, `auto`, `always`), `terminal.smoothStreaming` (`off`, `auto`, `on`), `terminal.notify`, and `theme`. |
 | **EXPERIENCE** | Watchdog (`watchdog`) | `watchdog.enabled`, `watchdog.target`, and `watchdog.cadenceToolCalls`. The two optional keys are editable text rows that render their absence as `(session target)` and `(turn end only)`; submitting an empty value removes the key from `settings.yaml` rather than storing a blank. |
-| **EXPERIENCE** | Advanced (`advanced`) | `runtimePlugins`, `attribution.gitCommits`, `compaction.model`, `compaction.systemPrompt`, `delegation.defaults.connectTimeoutMs`, `delegation.defaults.turnTimeoutMs`, `delegation.defaults.permissionTimeoutMs`, `keybindings`, and `delegation.agents`. |
+| **EXPERIENCE** | Advanced (`advanced`) | `runtimePlugins`, `attribution.gitCommits`, `compaction.model`, `compaction.systemPrompt`, `delegation.defaults.connectTimeoutMs`, `delegation.defaults.turnTimeoutMs`, `delegation.defaults.permissionTimeoutMs`, `keybindings`, `delegation.agents`, and the four `library.*` keys under a `Library` group header. `library.confirmedRemote` is read-only: the confirm flow writes it, because confirming a remote from its own row would be the trust record confirming itself. |
 
-`retry.streamStallMs` has no Settings Center row; edit it in `settings.yaml`.
+Every key `settings.yaml` accepts now has a row, except the ones the Center cannot edit as a nested structure: `workers.rosters` and `routing.agentAutomation.activeAgentRoles` are authored in `settings.yaml`, and the latter has a read-only row that reports the active pairs. `tests/contracts/settings-center.test.ts` enforces this against `DEFAULT_SETTINGS`.
 
 Label to config path mapping:
 
@@ -502,6 +528,8 @@ Label to config path mapping:
 | --- | --- |
 | Autonomy level | `autonomy` |
 | Fleet approvals routing | `workers.onPermission` |
+| Escalation timeout (ms) | `workers.escalation.timeoutMs` |
+| Escalation fallback | `workers.escalation.fallback` (`deny` or `fail`) |
 | Delegation governance | `delegation.defaults.toolGovernance` |
 | Trust project skill roots | `skills.trustProjectCompatRoots` |
 | Safety net | read-only fact, no config path |
@@ -516,10 +544,15 @@ Label to config path mapping:
 | Memory trajectory steps | `memory.intervention.windowSteps` |
 | Memory reminder tokens | `memory.intervention.maxTokens` |
 | Memory timeout (ms) | `memory.intervention.timeoutMs` |
+| Prompt pre-warm | `prewarm.enabled` |
 | Default target | `workers.default.target` |
 | Default model | `workers.default.model` |
 | Default thinking level | `workers.default.thinkingLevel` |
 | Fleet retries | `workers.maxRetries` |
+| Resilience cooldown (ms) | `workers.resilienceCooldownMs` (0 disables the cooldown) |
+| Active routing roles | `routing.activeRoles` (comma-separated from `researcher`, `verifier`, `reviewer`, `judge`) |
+| Active routing postures | `routing.activePostures` (comma-separated from `quality`, `balanced`, `latency`, `economy`) |
+| Active agent routes | `routing.agentAutomation.activeAgentRoles` (read-only; edit the pairs in `settings.yaml`) |
 | Add profile | `workers.profiles` |
 | Add agent route | `workers.agentBindings` |
 | Configured targets | `targets` |
@@ -529,13 +562,25 @@ Label to config path mapping:
 | Session ceiling (USD) | `budget.sessionCeilingUsd` |
 | Output budget (tokens) | `defaults.maxTokens` |
 | Fleet concurrency | `budget.concurrency` (restart required) |
+| Turn tool-call budget | `guardrails.turnToolCallBudget` |
+| Worker tool-call cap | `guardrails.workerToolCallCap` |
+| Run ledger retention | `guardrails.maxDispatchRuns` |
+| Read byte cap | `guardrails.readMaxBytes` |
+| Observation byte pool | `guardrails.observationTurnBudgetBytes` |
+| Internal dispatch timeout (ms) | `guardrails.internalDispatchTimeoutMs` |
 | Auto-compact | `compaction.auto` |
 | Compaction threshold | `compaction.threshold` |
 | Protected recent turns | `compaction.excludeLastTurns` |
+| Working-set eviction | `context.workingSet.enabled` |
+| Eviction policy | `context.workingSet.policy` (`structural-v1` or `age-horizon`) |
+| Eviction target pressure | `context.workingSet.target` (greater than 0, less than 1) |
+| Turns protected from eviction | `context.workingSet.protectLastTurns` |
+| Minimum evictable tokens | `context.workingSet.minEvictableTokens` |
 | Retry transient errors | `retry.enabled` |
 | Max retries | `retry.maxRetries` |
 | Base delay (ms) | `retry.baseDelayMs` |
 | Max delay (ms) | `retry.maxDelayMs` |
+| Stream stall timeout (ms) | `retry.streamStallMs` |
 | Terminal progress badges | `terminal.showTerminalProgress` |
 | Output detail | `terminal.outputVerbosity` (`minimal`, `default`, or `verbose`) |
 | TUI mode | `terminal.tuiMode` (`regular` or `fullscreen`, restart required) |
@@ -555,6 +600,10 @@ Label to config path mapping:
 | Delegate permission (ms) | `delegation.defaults.permissionTimeoutMs` |
 | Keybinding overrides | `keybindings` |
 | Delegation agents | `delegation.agents` |
+| Library catalog path | `library.catalog` (blank uses the config directory) |
+| Library remote | `library.remote` (blank keeps the library local) |
+| Confirmed library remote | `library.confirmedRemote` (read-only; written by the confirm flow) |
+| Library sync | `library.sync` |
 
 ---
 
@@ -642,6 +691,14 @@ Every one of these has an environment override for a single process; see [enviro
 | `context.workingSet.target` | `0.6` | number greater than 0 and less than 1 | next turn |
 | `context.workingSet.protectLastTurns` | `6` | integer ≥ 1 | next turn |
 | `context.workingSet.minEvictableTokens` | `200` | integer ≥ 0 | next turn |
+| `prewarm.enabled` | `true` | boolean | next turn |
+| `panes.enabled` | `off` | `auto`, `embedded`, or `off` | restart; `--with-panes` / `--no-panes` beat it |
+| `panes.notifications` | `failures` | `failures`, `all`, or `off` | next dispatch |
+| `panes.journal` | `true` | boolean | next dispatch |
+| `panes.yazi.enabled` | `true` | boolean | immediately, on the next files-pane open |
+| `panes.yazi.mode` | `companion` | `companion` or `chooser` | immediately, on the next files-pane open |
+| `panes.yazi.profile` | `managed` | `managed` or `user` | immediately, on the next files-pane open |
+| `panes.yazi.followCwd` | `true` | boolean | immediately, on the next explicit files-pane open |
 | `defaults.maxTokens` | `32768` | integer ≥ 0 | next turn |
 | `budget.sessionCeilingUsd` | `5` | number ≥ 0 | immediately |
 | `budget.concurrency` | `auto` | `auto` or integer ≥ 1 | next dispatch |
@@ -663,7 +720,7 @@ Generic provider and transport errors are classified by transient retry rules, i
 | `memory.intervention.everyNTools` | `10` | integer ≥ 2 | next turn |
 | `memory.intervention.windowSteps` | `8` | integer ≥ 1 | next turn |
 | `memory.intervention.maxTokens` | `400` | integer ≥ 1 | next turn |
-| `memory.intervention.timeoutMs` | `180000` | integer ≥ 1 | next turn |
+| `memory.intervention.timeoutMs` | `30000` | integer ≥ 1 | next turn |
 
 ### Turn-end watchdog
 

package/docs/context-engine.md

@@ -1,7 +1,7 @@
 # Context Engine
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.3.8).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.4.0).
 
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
@@ -15,6 +15,8 @@ Each target has a declared, desired, and effective context window. The effective
 
 The loaded window outranks the declared one because it is the only figure describing what the backend will serve. LM Studio routinely opens a model well below its `max_context_length`, and a run planned against the larger number overruns the server before compaction ever fires. Discovery carries that number per model in `discoveredModelStates[<model>].contextLength`, and the residency notice reads the same entry, so a model Clio is budgeting a loaded window for is never announced as absent.
 
+A resumed session carries the loaded window it already recorded. A resume re-resolves its target before discovery has reported what the backend has open, so the first turn used to budget against the probed figure, which on a multi-slot or multi-copy backend can be several times the real headroom, and corrected a turn later. `lastLoadedContextWindow` reads the last `loaded` window the session's own `context-snapshots.jsonl` recorded for the same target and model and hands it to resolution as `knownLoadedContextWindow`. It is used only when live discovery reports nothing, and it is scoped to that target and model, so a different selection re-probes and a model reloaded at a new size corrects as soon as discovery names the live window.
+
 Local-native runtimes use a recommended minimum desired window of 128,000 tokens. If the live model reports a smaller loaded context window, Clio re-resolves the target so accounting uses the actual ceiling.
 
 The `/context` overlay states which layer answered, next to the token total: `loaded`, `probed`, `configured`, `declared`, or `assumed`.
@@ -27,13 +29,17 @@ The estimator in `context-accounting.ts` uses a four-characters-per-token family
 
 At submit time, Clio captures a context snapshot and persists a slim JSONL record under the session directory as `context-snapshots.jsonl`. The slim record keeps token counts, segment metadata, signatures, and hashes, not the heavy prompt or transcript text. When provider usage arrives, `reconcileSnapshot` folds actual input and output counts back into the ledger.
 
+Every snapshot records the divergence between the two accountings. `estimatedTokens` is the chars/4 prompt-side total the snapshot was captured with and is never rewritten by a reconcile; `reconciledTokens` is the provider's own prompt count for the call, with cached prompt tokens folded back in; `divergenceRatio` is the second over the first. A ratio above 1 means the estimator is under-counting what the backend charges for the same messages.
+
+The reconciled figure is not only a display value. Once a provider has answered, the compaction verdict budgets against `max(estimate, reconciled + estimate of everything appended since)`, at all three evaluation points: the pre-submit trigger, the post-tool continuation guard, and the preflight overflow check. The estimate stays a floor because it prices material the attested call never saw; the provider count can only raise the figure, never lower it. A working-set projection subtracts the tokens the eviction planner priced out and re-anchors on the projected message list rather than discarding the attestation, so post-eviction accounting is still provider-anchored. A summary compaction rewrites the conversation the attestation described, so it drops the anchor and the next call re-establishes it.
+
 Session metadata enforces session format version 4 (`CURRENT_SESSION_FORMAT_VERSION = 4`). Version 4 is additive: it adds the `contextEviction` and `contextRecall` records and changes no existing entry. A version 3 session therefore migrates to 4 in place when Clio opens it, and no entry is rewritten. Only a session written by a newer build is refused, with an error naming the version it read and pointing at upgrading. The bump is one-way for the operator: a 0.3.3 binary cannot open a session this release wrote.
 
-The `/context` overlay and footer meter read the same ledger categories: `system`, `tools`, `agents`, `skills`, `memory`, `project`, `messages`, `pending`, `reserve`, `free`, and `streaming`.
+The `/context` overlay and footer meter read the same ledger categories in display order: `system`, `tools`, `agents`, `skills`, `memory`, `project`, `messages`, `pending`, `streaming`, `free`, and `reserve`.
 
 ## Single-threshold compaction
 
-Auto-compaction is controlled by one pressure threshold. Pressure is `estimated_tokens / context_window`. The default threshold is `0.8`.
+Auto-compaction is controlled by one pressure threshold. Pressure is `budgeted_tokens / context_window`, where the budgeted figure is the reconciled total when the provider has attested one and the chars/4 estimate otherwise. The default threshold is `0.8`.
 
 Crossing that threshold engages three mechanisms in a fixed order. The first two are cheap, reversible, and call no model. Only the third rewrites what the session says about itself.
 
@@ -81,14 +87,64 @@ Every provider Clio targets caches by exact prefix. Anthropic hashes the cumulat
 
 The procedural replay target sweep measured 0.4, 0.5, 0.6, and an exhaustive rung-6 stop over 24 traces. Target 0.4 and exhaustive selection converged because un-evictable residue exhausted the candidate pool. Against 0.6, target 0.4 cut cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, with no summary reduction and a 0.00072 reduction in retention covered at 128k. That is below the 10% cache-saving threshold set for changing a cross-tier default, so the default remains 0.6. The complete sweep and reopening rule are in the replay README.
 
+The same arithmetic governs the compiled system prompt, which sits ahead of every message. Its sections are ordered stable prefix first, so a section that can change between two turns never sits ahead of one that cannot; the order and the rule behind it are in [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md#section-order-stable-prefix-first).
+
 Compaction and eviction both change the replayed history. On a local backend with a single prefix-cache slot, the next turn after either one is expected to be cold because the byte prefix moved. Dispatch traffic can disturb the same slot.
 
-Clio records these disturbances once on the next assistant entry as `promptCache.expectedColdReasons`. The recorded reasons are `working_set_evict` for an applied eviction event, `compaction` for the summary path, and `dispatch` for interleaved worker traffic. `compaction` and `dispatch` are stamped only on `local-native` targets, because a single-slot local cache is the one an interleaved run actually disturbs. `working_set_evict` is stamped on every tier: the eviction moved the byte prefix itself, so the cloud prefix cache is cold for the same reason. The user sees one dim notice, and the same reasons persist on that entry in the session ledger next to the per-call cache data.
+Clio records these disturbances once on the next assistant entry as `promptCache.expectedColdReasons`. There are eight recorded reasons, and they split into two groups by what they disturb.
+
+| Reason | Stamped when | Tier |
+| --- | --- | --- |
+| `working_set_evict` | An eviction event was applied to the replayed history. | every tier |
+| `tool_surface_change` | The session's tool signature differs from the last completed run's. | every tier |
+| `prompt_recompiled` | A recompile changed the prompt text and the manifest holds a previous hash to name, or an in-process session switch replaced the prefix after this process had applied a prompt. | every tier |
+| `compaction` | The summary compaction path ran. | `local-native` |
+| `dispatch` | A dispatch started, completed, or failed between turns. | `local-native` |
+| `residency` | A residency load or eviction succeeded on this session's own serving endpoint. | `local-native` |
+| `thinking_change` | The resolved thinking level for this run differs from the last completed backend run's. | `local-native` |
+| `background_memory` | A proactive-memory step completed against the endpoint this session streams to. | `local-native` |
+
+The three tier-independent reasons moved the byte prefix itself, so a cloud prefix cache is cold for exactly the same reason a local one is. The other five disturb a local server or the template it renders, and a single-slot local cache is the only one an interleaved run actually displaces, so they are stamped only when the runtime's tier is `local-native`. Two of them are gated on identity as well as tier: `residency` compares the mutation's target key against this session's own runtime and base URL, and `background_memory` compares the memory step's canonical endpoint key against the target this session streams to, so work on a second server never explains a cold prefix on the first. `prompt_recompiled` deliberately does not fire on a process's first compile: a fresh or resumed session has no previous hash to have diverged from, and stamping it there would mark every session's opening turn as expected-cold. An in-process switch (`/resume`, `/new`, a fork) stamps it from the switch itself rather than from the manifest. Manifest provenance follows the session, so the incoming session's `previousHash` is its own last recorded hash and usually equals what it compiles now, which leaves the manifest with nothing to report; the backend's slot meanwhile still holds the outgoing session's prompt and history, so the first turn after the switch is cold on every tier.
+
+The user sees one dim notice per reason, and the same reasons persist on the run's first assistant entry in the session ledger next to the per-call cache data. The `/context` overlay renders each one in prose (`working-set eviction`, `dispatch traffic`, `residency change`, `thinking-level change`, `tool-surface change`, `prompt recompile`, `compaction`, `background memory step`) and falls through to the wire value only for an unknown reason.
 
 Per-call cache verdicts are `hot`, `partial`, `cold`, and `small`. They are derived from provider usage and persisted with `timing { ttftMs, apiMs }` and `promptCache { input, cacheRead, cacheWrite, backendVerdict }` when available.
 
+### What the serving backend reports
+
+On a llama.cpp or LM Studio target, Clio also persists the server's own prefill accounting rather than inferring it from pi-ai's token counts. The observer reads the last complete timing object off the final ordinary SSE event of a stream, or the top-level one on a non-streaming response, from the response the turn already makes; it opens no second connection and sets no extra payload flag. What lands on the assistant entry is `promptCache.backend`:
+
+| Field | Meaning |
+| --- | --- |
+| `promptTokens` | The whole prompt the server accounted for. On the observed llama.cpp build that is `prompt_n + cache_n`, since `prompt_n` counts only newly evaluated work. |
+| `cachedTokens` | `cache_n`, the prompt work the slot reused. `null` when the server reports no cache figure at all. |
+| `predictedTokens` | `predicted_n`, tokens generated. |
+| `promptMs` | `prompt_ms`, wall-clock milliseconds spent in prefill. |
+| `predictedMs` | `predicted_ms`, wall-clock milliseconds spent generating. |
+| `source` | `llamacpp-timings` or `lmstudio-timings`. |
+
+`uncachedPrefillTokens` is derived centrally as `promptTokens - cachedTokens`, and only when both figures are present and consistent. That distinction carries all the way to the surfaces: a missing `cache_n` persists `cachedTokens: null` and leaves the pi-ai verdict in force, so `/context` says `server does not report cache reads` instead of calling the backend cold. LM Studio 2.29.0 is that case today. Its OpenAI-compatible port returns `usage`, `stats`, and `system_fingerprint` and no `timings` object, on both the streaming and non-streaming shapes and with `timings_per_token` explicitly requested, so `lmstudio-timings` is a shape Clio accepts and has not yet observed.
+
+The verdict keeps its existing pi-ai path unless pi-ai reports `cacheRead === 0` while the backend reports a numeric `cachedTokens`. In that one case the same hot, partial, cold, and small thresholds are applied to the measured counts instead. No timing ratio or wall-clock heuristic participates in a verdict.
+
+`/context` renders the last call as `prefill: N uncached · M cached · X ms`, and falls back to `prefill: N prompt · X ms` when the server gave no cache figure. `/cost` folds every durable call in the session into a total uncached prefill plus the four verdict counts, `clio-coder usage report` carries the same two facts per session, and `clio-coder doctor` reports the latest session's verdict counts and its most frequent expected-cold reason without opening the TUI.
+
 The `/context` overlay closes the loop. When the last settled run came back `cold` and Clio had recorded a reason for it, the overlay adds a line naming that reason, for example `last cold turn: working-set eviction (expected)`, and reports the cache line without the warning token. A reused prompt shell with a cold backend and no recorded reason stays a warning: Clio kept the bytes stable and the provider re-prefilled anyway, which is a disagreement worth surfacing.
 
+## Prompt pre-warm
+
+On a local server prefill is the cost. A fresh session's first turn prefills the whole compiled prompt plus the tool schemas before the model emits a token, and a resumed session's first turn prefills the entire replayed history. Both are paid after the operator presses Enter, and both are fully determined before they type anything. Since llama.cpp picks the slot with the longest common prefix and re-evaluates only the suffix, sending that prefix early leaves the processed KV where the real turn will land.
+
+Clio sends it at three moments: after the session prompt compiles at session start, after a resume rebuilds the message array, and after a compaction settles. The third is included because the next turn is known to be cold and the operator is usually reading the summary rather than typing.
+
+The payload is the request the next turn would send minus the operator's text: the same system prompt, the same tool schemas, the same replayed messages, the same thinking level, and the same `cache_prompt`, with one single-character user message appended so the chat template renders the prefix up to the user turn, and `max_tokens: 1`. It is built through the same `streamSimple` dispatcher `createEngineAgent` hands the engine as its `streamFn`, not a hand-assembled payload, because any byte that differs ahead of the user turn defeats the purpose.
+
+The pre-warm is refused rather than queued whenever it would compete with real work. It runs only on `local-native` targets, whatever `prewarm.enabled` says, because a cloud provider bills the request and caches on its own schedule. It never runs while a turn is in flight, while any dispatch is outstanding, on a worker, or in headless `run`. The dispatch guard is a stand-in: without per-endpoint capacity accounting the pre-warm cannot tell whether a worker already occupies the server it would warm, so it stands down for all worker traffic. The round already claims one endpoint slot for as long as its request is out and releases it in a `finally`, through the `registerEndpointSlot` seam the chat loop wires from the endpoint-capacity registry, so capacity counts a pre-warm the same way it counts the orchestrator's streaming turn.
+
+Pressing Enter lets go of an in-flight pre-warm at the keystroke, before the admission gate. Whether it also aborts the HTTP request is gated on what the backend does with a cancelled one, and the measured backend does nothing. On the operator's llama.cpp router (build `b226-2115b73d8`, Qwen3.8-27B, `--parallel 1`), aborting 1.5 s into a 47,620-token prefill did not cancel the server's work: the server finished prefilling, so the prefix did survive the abort and the next request read 47,596 of 47,620 tokens from cache with `prompt_ms 927`, but that request also waited 89.5 s of wall clock for the abandoned one to leave the single slot. Letting the pre-warm complete instead cost 89.3 s plus a 1.3 s turn, the same wall clock. The abort therefore frees no slot and saves no time on this backend; all it does is discard the usage and timings of prefill the server performed. So a submit detaches the round instead: Clio stops calling it the current pre-warm, never waits on it, withholds its `/context` line because it no longer describes the prefix the next turn will send, and still records what it cost. `ABORT_ROUND_ON_SUBMIT` in `src/interactive/turn-prewarm.ts` carries the measurement and flips the behavior for a backend that honors cancellation.
+
+Each round appends one `prewarm` custom ledger entry carrying its trigger, the backend prompt tokens, `timing`, and `promptCache`. The entry is never rendered and never becomes a model message, so it contributes zero tokens to the context estimate. `/context` shows `prewarmed: N tokens in X ms` until the next settled run answers the question it asked. `prewarm` is never an expected-cold reason: a pre-warm is the opposite of a disturbance. Its provider usage is real spend and is reported to `/cost` and `clio-coder usage report` under its own row, the way a `/btw` side question is.
+
 ## Settings
 
 The public settings use one compaction threshold plus a non-destructive working-set stage:
@@ -108,6 +164,9 @@ context:
     target: 0.6
     protectLastTurns: 6
     minEvictableTokens: 200
+
+prewarm:
+  enabled: true
 ```
 
 `compaction.auto` controls the pre-request trigger. Manual `/context compact` still runs when `auto` is false. `compaction.model` optionally selects a dedicated summarization model, and `compaction.systemPrompt` optionally points at a prompt override file. `compaction.excludeLastTurns` only governs the temporary legacy mask path; working-set protection uses `context.workingSet.protectLastTurns`.

package/docs/development-pipeline.md

@@ -56,6 +56,25 @@ commit the dependency pins, snapshot, boundary notes, and proving contracts
 together. `npm run lint` invokes the surface check automatically when the
 installed Pi versions differ from the checked-in snapshot.
 
+## Test lanes
+
+`npm test` runs `scripts/shard-tests.mjs`. Contract and smoke files are assigned
+deterministically to weighted parallel lanes, with timings from
+`scripts/shard-weights.json`; `--list` shows the assignment and `--shard <n>`
+reproduces one numbered lane. Tests whose assertion is itself sensitive to
+wall-clock scheduling live in the explicit serial set. The runner waits for all
+parallel lanes to drain, then runs that set alone with
+`CLIO_TEST_CONCURRENCY=1`. Reproduce it with:
+
+```bash
+node scripts/shard-tests.mjs --shard serial
+```
+
+Do not repair a timing-measurement failure by widening its product bound or by
+moving ordinary watchdog tests into the serial set. `tests/harness/load.ts`
+scales watchdogs by the parallel lane count; the serial lane is reserved for
+claims that cease to mean the same thing under contention.
+
 ## Issue conventions
 
 - **Title**: conventional tag plus imperative summary (`fix: memory overlay