@iowarp/clio-coder 0.3.9 → 0.4.1

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.9).
+> **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).
 
@@ -468,8 +468,10 @@ Plain `clio-coder doctor` is read-only. `clio-coder doctor --fix` creates missin
 directories and template files, repairs credential permissions, and refreshes
 install metadata. It validates `settings.yaml` directly against the current
 schema but never rewrites removed keys or migrates an old settings shape. Any
-unknown or retired key remains a validation error for the operator to edit
-deliberately.
+unknown or retired key remains a validation error on that doctor run. Registered
+`clio-coder upgrade` migrations are the narrow exception: the 0.4.1 pane-key
+migration removes `panes.agents` and `panes.keepFailed` from an older file before
+strict startup reads it. Other reported paths still require deliberate editing.
 
 ---
 
@@ -508,19 +510,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:
 
@@ -528,6 +530,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 |
@@ -542,10 +546,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` |
@@ -555,13 +564,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) |
@@ -581,196 +602,146 @@ 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` |
 
 ---
 
 ## Settings inventory
 
-Every key `settings.yaml` accepts, with its shipped default, what validation admits, and when a change takes effect. `DEFAULT_SETTINGS` in `src/core/defaults.ts` is the one place a default is written; validation lives in `src/core/config.ts`. A key absent from this table is an unknown-key error, not a silently ignored typo. The one exception is `identity`, which pre-0.3.1 files carry: it is accepted and ignored so those files keep loading.
+This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation is strict: a path absent from this inventory is rejected, including a retired version-1 path. `clio-coder upgrade` performs the one-time v1-to-v2 rename before configuration-domain load and keeps the original as the sibling `settings.yaml.v1.bak` backup.
 
-"When it applies" has four values. **Immediately** means a running session picks the change up from the config watcher. **Next turn** means the running turn finishes on the old value. **Next session** means `settings.yaml` is a saved default that a launched session copies and then owns, so writing it never redirects a session already running. **Restart** means the process reads it once at boot.
+"When it applies" follows the configuration classifier. **Immediately** means a running process observes the value without rebuilding runtime state. **Next turn** and **next dispatch** mean current work finishes on the old value. **Next session** identifies routing defaults copied into session-owned state at launch. **Restart** means process or pane-host setup must be rebuilt.
 
-### Routing defaults
-
-These are saved defaults, not a live control surface. See [Live routing vs saved defaults](#live-routing-vs-saved-defaults).
+### Structural and target catalog
 
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
-| `orchestrator.target` | `null` | a target id present in `targets` | next session |
-| `orchestrator.model` | `null` | string | next session |
-| `orchestrator.thinkingLevel` | `off` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; further narrowed to what the resolved model supports | next session |
-| `background.target` | `null` | a target id present in `targets` | next session |
-| `background.model` | `null` | string | next session |
-| `background.thinkingLevel` | `off` | as above | next session |
-| `workers.default.target` | `null` | a target id present in `targets` | next session |
-| `workers.default.model` | `null` | string | next session |
-| `workers.default.thinkingLevel` | `off` | as above | next session |
-| `scope` | `[]` | list of strings | next session |
-
-### Safety and worker policy
-
-`workers.rosters.<name>.members` defines council membership beside
-`workers.profiles`. Every member accepts `label`, `target`, and the optional
-keys `model`, `thinking`, and `color`. Labels must match
-`[a-z][a-z0-9_-]{0,31}` and must be unique inside the roster. A roster contains
-two to five members. Colors accept a theme token such as `accent`, `success`,
-or `reason`, or a six-digit hexadecimal value such as `#5ba8ff`. Unknown roster
-and member keys are rejected during configuration load. The existing settings
-watcher validates and publishes roster changes with every other hot reload.
+| `version` | `2` | integer, exactly `2` | restart |
+| `targets` | `[]` | target descriptor list with unique ids and registered runtimes | next turn for the catalog; next session for saved routing defaults |
 
-| Key | Default | Validation | When it applies |
-| --- | --- | --- | --- |
-| `autonomy` | `auto-edit` | `read-only`, `suggest`, `auto-edit`, `full-auto` | immediately |
-| `workers.onPermission` | `deny` | `deny`, `fail`, `escalate` | next dispatch |
-| `workers.escalation.timeoutMs` | `120000` | integer ≥ 1 | next dispatch |
-| `workers.escalation.fallback` | `deny` | `deny`, `fail` | next dispatch |
-| `workers.maxRetries` | `2` | integer ≥ 0 | next dispatch |
-| `workers.resilienceCooldownMs` | `15000` | integer ≥ 0 | next dispatch |
-| `workers.profiles` | `{}` | map of profile name to a target/model/thinking choice | next dispatch |
-| `workers.rosters` | `{}` | map of roster name to 2 to 5 council members | next dispatch |
-| `workers.agentBindings` | `{}` | map of agent id to a key present in `workers.profiles` | next dispatch |
-| `skills.trustProjectCompatRoots` | `false` | boolean | restart |
-| `library.catalog` | `null` | string or null | immediately |
-| `library.remote` | `null` | string or null | immediately |
-| `library.confirmedRemote` | `null` | string or null | immediately |
-| `library.sync` | `false` | boolean | immediately |
-
-### Git commit provenance
+### Chat
 
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
-| `attribution.gitCommits` | `true` | boolean | immediately for subsequent commits |
-
-Enabled attribution adds the compiled identity `Clio Coder <clio-coder@iowarp.ai>` only through evidence-justified role trailers. Assistance requires material creation or editing, testing requires a successful recorded validation command, and review requires a passing independent verifier. `Co-authored-by` is the GitHub/GitLab contributor and avatar compatibility trailer and appears only for material authorship, never for testing or review alone. Disabling the setting leaves commit messages entirely unchanged. Full hook behavior, evidence semantics, and how GitHub and GitLab render the identity and avatar once maintainers verify the email are in [git-commit-provenance.md](git-commit-provenance.md).
-
-### Guardrails
-
-Every one of these has an environment override for a single process; see [environment-variables.md](environment-variables.md). Resolution is env, then settings, then the built-in default.
+| `chat.target` | `null` | configured target id or null | next session |
+| `chat.model` | `null` | string or null | next session |
+| `chat.thinkingLevel` | `off` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | next session |
+| `chat.modelPicker.cycleSet` | `[]` | list of target or target/model references | immediately for this session; next session as the saved default |
+| `chat.modelPicker.favorites` | `[]` | list of target/model references | immediately |
+| `chat.modelPicker.recentLimit` | `12` | integer ≥ 1 | immediately |
+| `chat.maxOutputTokens` | `32768` | integer ≥ 0 | next turn |
+| `chat.prewarm` | `true` | boolean | next turn |
+| `chat.retry.enabled` | `true` | boolean | next turn |
+| `chat.retry.maxRetries` | `3` | integer ≥ 0 | next turn |
+| `chat.retry.baseDelayMs` | `2000` | integer ≥ 0 | next turn |
+| `chat.retry.maxDelayMs` | `60000` | integer ≥ 0 | next turn |
+| `chat.retry.streamStallMs` | `180000` | integer ≥ 0; `0` disables the stall timer | next turn |
+
+### Fleet
+
+`fleet.rosters.<name>.members` contains two to five members. Each member has a unique `label`, a `target`, and optional `model`, `thinkingLevel`, and `color`. `fleet.agentProfiles` is the persisted agent-id-to-profile map.
 
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
-| `guardrails.turnToolCallBudget` | `60` | integer ≥ 1 | next turn |
-| `guardrails.workerToolCallCap` | `150` | integer ≥ 1 | next dispatch |
-| `guardrails.maxDispatchRuns` | `1000` | integer ≥ 1 | next dispatch |
-| `guardrails.readMaxBytes` | `51200` | integer ≥ 1, floored at 1024 by the tool | next turn |
-| `guardrails.observationTurnBudgetBytes` | `196608` | integer ≥ 1 | next turn |
-| `guardrails.internalDispatchTimeoutMs` | `900000` | integer ≥ 1 | next dispatch |
-
-### Context and cost
+| `fleet.default.target` | `null` | configured target id or null | next session |
+| `fleet.default.model` | `null` | string or null | next session |
+| `fleet.default.thinkingLevel` | `off` | supported thinking level | next session |
+| `fleet.profiles` | `{}` | map of profile name to target/model/thinking/optional-node routes | next dispatch |
+| `fleet.rosters` | `{}` | map of roster name to council members | next dispatch |
+| `fleet.agentProfiles` | `{}` | map of native agent id to an existing fleet profile | next dispatch |
+| `fleet.nodes` | `[]` | list of validated local/SSH node descriptors | next dispatch |
+| `fleet.adaptiveRouting.roles` | `[]` | subset of `researcher`, `verifier`, `reviewer`, `judge` | next dispatch |
+| `fleet.adaptiveRouting.postures` | `[]` | subset of `quality`, `balanced`, `latency`, `economy` | next dispatch |
+| `fleet.adaptiveRouting.agentRoles` | `[]` | exact agent-id/execution-role pairs | next dispatch |
+| `fleet.permissions.mode` | `deny` | `deny`, `fail`, `escalate` | next dispatch |
+| `fleet.permissions.escalation.timeoutMs` | `120000` | integer ≥ 1 | next dispatch |
+| `fleet.permissions.escalation.fallback` | `deny` | `deny` or `fail` | next dispatch |
+| `fleet.concurrency` | `auto` | `auto` or integer ≥ 1 | restart |
+| `fleet.retry.maxRetries` | `2` | integer ≥ 0 | next dispatch |
+| `fleet.retry.routeCooldownMs` | `15000` | integer ≥ 0 | next dispatch |
+| `fleet.limits.toolCallsPerRun` | `150` | integer ≥ 1 | next dispatch |
+| `fleet.limits.internalRunTimeoutMs` | `900000` | integer ≥ 1 | next dispatch |
+| `fleet.history.maxRuns` | `1000` | integer ≥ 1 | next dispatch |
+| `fleet.history.journal` | `true` | boolean | next dispatch |
+
+### Context
 
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
-| `compaction.auto` | `true` | boolean | next turn |
-| `compaction.threshold` | `0.8` | number in 0 to 1 | next turn |
-| `compaction.excludeLastTurns` | `6` | integer ≥ 1 | next turn |
 | `context.workingSet.enabled` | `true` | boolean | next turn |
-| `context.workingSet.policy` | `structural-v1` | `age-horizon` or `structural-v1` | next turn |
+| `context.workingSet.policy` | `structural-v1` | `structural-v1` or `age-horizon` | next turn |
 | `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 |
-| `defaults.maxTokens` | `32768` | integer ≥ 0 | next turn |
-| `budget.sessionCeilingUsd` | `5` | number ≥ 0 | immediately |
-| `budget.concurrency` | `auto` | `auto` or integer ≥ 1 | next dispatch |
-| `retry.enabled` | `true` | boolean | next turn |
-| `retry.maxRetries` | `3` | integer ≥ 0 | next turn |
-| `retry.baseDelayMs` | `2000` | integer ≥ 0 | next turn |
-| `retry.maxDelayMs` | `60000` | integer ≥ 0 | next turn |
-| `retry.streamStallMs` | `180000` | integer ≥ 0, `0` disables | next turn |
-
-`retry.streamStallMs` covers the failure a request error never reports: the backend answers `/health` while the slot behind the stream is dead. A run whose stream produces nothing for that long is aborted and handed to the same retry ladder as any transient error, so a headless run or a fleet worker recovers without a human pressing Esc. Time inside a tool call and inside the post-tool compaction guard does not count against it, so a long build is never mistaken for a wedged stream. Set it to `0` to keep the old behavior, where a stalled stream waits forever.
-
-Generic provider and transport errors are classified by transient retry rules, including DNS and WebSocket failures while excluding quota, usage-limit, and billing exhaustion even when the message also contains `429` or `500`. Clio adds only its local-runtime policy: model-loading errors receive a longer bounded delay, the TUI shows a cancellable countdown, and recovery resumes through the existing agent loop.
-
-### Proactive memory
-
-| Key | Default | Validation | When it applies |
-| --- | --- | --- | --- |
-| `memory.intervention.enabled` | `true` | boolean | next turn |
-| `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` | `30000` | integer ≥ 1 | next turn |
-
-### Turn-end watchdog
+| `context.compaction.auto` | `true` | boolean | next turn |
+| `context.compaction.threshold` | `0.8` | number from 0 through 1 | next turn |
+| `context.compaction.model` | unset | non-empty string when present | next turn |
+| `context.compaction.systemPrompt` | unset | non-empty path string when present | next turn |
+| `context.memory.enabled` | `true` | boolean | next turn |
+| `context.memory.target` | `null` | configured target id or null | next turn |
+| `context.memory.model` | `null` | string or null | next turn |
+| `context.memory.cadenceToolCalls` | `10` | integer ≥ 2 | next turn |
+| `context.memory.trajectorySteps` | `8` | integer ≥ 1 | next turn |
+| `context.memory.maxOutputTokens` | `2000` | integer ≥ 1 | next turn |
+| `context.memory.timeoutMs` | `60000` | integer ≥ 1 | next turn |
+
+### Safety
+
+The six limit leaves retain their one-process environment overrides where documented in [environment-variables.md](environment-variables.md); resolution is environment, then v2 settings, then compiled default.
 
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
-| `watchdog.enabled` | `false` | boolean | immediately |
-| `watchdog.target` | unset | non-empty target id | immediately |
-| `watchdog.cadenceToolCalls` | unset | integer ≥ 1 | immediately |
-
-The watchdog is off by default because it spends one worker run per mutating
-turn. With `enabled: true`, a turn that changed the tree is handed to one
-read-only `verifier` run briefed with the turn's coalesced diff and the task
-board's current scope. Its blockers become one transcript notice naming the
-count and the first three failed checks, and nothing else: it never follows up,
-never queues a turn, and never mutates. A passing report emits nothing at all. A
-turn with no file mutations never fires it.
-
-`watchdog.target` routes the run at a named target, which is how a cheap local
-model reviews turns run on a subscription route; unset, the run takes the
-session's active target. `watchdog.cadenceToolCalls: N` additionally fires the
-watchdog after every N tool calls inside a turn, with the same diff-and-scope
-briefing, so mid-turn scope drift is visible before the turn ends. At most one
-watchdog run is in flight at a time; a trigger that arrives while one is running
-is dropped and counted rather than queued. Headless and ACP runs never fire the
-watchdog regardless of the setting, because neither has an operator reading a
-transcript. The block has its own Settings Center section under EXPERIENCE ›
-Watchdog; clearing the target or the cadence row removes that key from
-`settings.yaml` rather than writing an empty value.
-
-### Delegation
-
-| Key | Default | Validation | When it applies |
-| --- | --- | --- | --- |
-| `delegation.agents` | `[]` | list of agent definitions | next dispatch |
-| `delegation.defaults.connectTimeoutMs` | `30000` | integer ≥ 1 | next dispatch |
-| `delegation.defaults.turnTimeoutMs` | `300000` | integer ≥ 1 | next dispatch |
-| `delegation.defaults.permissionTimeoutMs` | `120000` | integer ≥ 1 | next dispatch |
-| `delegation.defaults.toolGovernance` | `clio-policy` | `clio-policy`, `agent-managed`, `deny-all` | next dispatch |
-
-`delegation.agents` is the one settings key Clio itself appends to, and only after an explicit answer in `clio-coder configure --interop` or `/interop`. Everything else here is operator-authored.
+| `safety.autonomy` | `auto-edit` | `read-only`, `suggest`, `auto-edit`, `full-auto` | immediately |
+| `safety.limits.sessionCostUsd` | `5` | number ≥ 0 | next turn |
+| `safety.limits.chatToolCallsPerTurn` | `60` | integer ≥ 1 | next turn |
+| `safety.limits.readBytesPerCall` | `51200` | integer ≥ 1; the read tool applies its 1024-byte floor | next turn |
+| `safety.limits.observationBytesPerTurn` | `196608` | integer ≥ 1 | next turn |
+| `safety.review.enabled` | `false` | boolean | immediately |
+| `safety.review.target` | unset | configured target id when present | immediately |
+| `safety.review.cadenceToolCalls` | unset | integer ≥ 1 when present | immediately |
 
 ### Interface
 
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
-| `theme` | `default` | string naming a registered theme | immediately |
-| `terminal.showTerminalProgress` | `false` | boolean | immediately |
-| `terminal.outputVerbosity` | `default` | `minimal`, `default`, `verbose` | immediately |
-| `terminal.tuiMode` | `regular` | `regular`, `fullscreen` | restart |
-| `terminal.fullscreenScrollbar` | `auto` | `hidden`, `auto`, `always` | restart |
-| `terminal.smoothStreaming` | `off` | `off`, `auto`, `on` | immediately |
-| `terminal.notify` | `false` | boolean | immediately |
-| `modelSelector.favorites` | `[]` | list of strings | immediately |
-| `modelSelector.recentLimit` | `12` | integer ≥ 1 | immediately |
-| `keybindings` | `{}` | map of binding id to a key string or list of them | restart |
-
-`terminal.notify` turns on a content-free desktop notification for the three
-moments an operator is waiting: a turn ends, a detached fleet batch settles, and
-a worker permission or `ask_user` request parks. The payload is fixed. The title
-is always `clio-coder` and the body comes from a closed vocabulary (`turn
-finished`, `batch <shortId> settled`, `approval needed`), so no prompt text, file
-path, or model output ever leaves the process in a notification. Clio emits OSC
-777 by default and OSC 9 on iTerm2, Windows Terminal, and ConEmu, never both for
-one event. Headless, ACP, and non-TTY runs never emit one regardless of the
-setting. The knob has a Settings Center row under EXPERIENCE › Terminal,
-labeled `Desktop notifications`.
-
-Recently selected models are runtime state and live in `recent-models.json` under the state directory, not here. A `state.recentModels` key in `settings.yaml` is an unknown-key error.
-
-### Structural and catalog keys
+| `interface.terminalProgress` | `false` | boolean | next turn |
+| `interface.outputDetail` | `default` | `minimal`, `default`, `verbose` | next turn |
+| `interface.mode` | `regular` | `regular` or `fullscreen` | restart |
+| `interface.fullscreenScrollbar` | `auto` | `hidden`, `auto`, `always` | restart |
+| `interface.smoothStreaming` | `off` | `off`, `auto`, `on` | immediately |
+| `interface.desktopNotifications` | `false` | boolean | next turn |
+| `interface.panes.enabled` | `off` | `auto`, `embedded`, `off` | restart |
+| `interface.panes.notifications` | `failures` | `failures`, `all`, `off` | immediately |
+| `interface.panes.layout` | `off` | `off`, `workers`, `cockpit` | restart |
+| `interface.panes.workers.ratio` | `0.34` | finite dock ratio | restart |
+| `interface.panes.files.enabled` | `true` | boolean | immediately on the next files-pane open |
+| `interface.panes.files.mode` | `companion` | `companion` or `chooser` | immediately on the next files-pane open |
+| `interface.panes.files.profile` | `managed` | `managed` or `user` | immediately on the next files-pane open |
+| `interface.panes.files.followCwd` | `true` | boolean | immediately on the next files-pane open |
+| `interface.panes.files.ratio` | `0.3` | finite dock ratio | restart |
+| `interface.keybindings` | `{}` | map of binding id to a key string or list of strings | immediately |
+
+### Integrations
 
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
-| `version` | `1` | integer, currently `1` only | restart |
-| `targets` | `[]` | list of target descriptors, each with a unique id and a registered runtime | immediately for the catalog, next session for routing |
-| `runtimePlugins` | `[]` | list of plugin descriptors | restart |
-| `fleet.nodes` | `[]` | list of node descriptors | next dispatch |
-| `routing.activeRoles` | `[]` | list of strings; empty keeps measured routing shadow-only | next dispatch |
-| `routing.activePostures` | `[]` | list of strings | next dispatch |
-| `routing.agentAutomation.activeAgentRoles` | `[]` | list of strings | next dispatch |
+| `integrations.projectResources.trustProjectImports` | `false` | boolean | next turn |
+| `integrations.externalAgents.entries` | `[]` | list of validated ACP agent definitions | next dispatch |
+| `integrations.externalAgents.defaults.connectTimeoutMs` | `30000` | integer ≥ 1 | next dispatch |
+| `integrations.externalAgents.defaults.turnTimeoutMs` | `300000` | integer ≥ 1 | next dispatch |
+| `integrations.externalAgents.defaults.permissionTimeoutMs` | `120000` | integer ≥ 1 | next dispatch |
+| `integrations.externalAgents.defaults.toolGovernance` | `clio-policy` | `clio-policy`, `agent-managed`, `deny-all` | next dispatch |
+| `integrations.runtimePlugins` | `[]` | list of plugin package names | restart |
+| `integrations.library.catalog` | `null` | string or null | next turn |
+| `integrations.library.remote` | `null` | string or null | next turn |
+| `integrations.library.confirmedRemote` | `null` | string or null | next turn |
+| `integrations.library.sync` | `false` | boolean | next turn |
+| `integrations.git.commitAttribution` | `true` | boolean | immediately for subsequent commits |
+
+The retired v1-only paths `identity`, `background.thinkingLevel`, `theme`, and `compaction.excludeLastTurns` have no v2 replacement. Fresh v2 files naming them receive targeted removal diagnostics. The v1 migrator drops them with the reason recorded in its migration report; they are tombstones, not executable aliases.
 
 ---
 

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.9).
+> **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.
 

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