@iowarp/clio-coder 0.3.9 → 0.4.0

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).
 
@@ -508,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:
 
@@ -528,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 |
@@ -542,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` |
@@ -555,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) |
@@ -581,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` |
 
 ---
 
@@ -669,6 +692,13 @@ Every one of these has an environment override for a single process; see [enviro
 | `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 |

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

package/docs/dispatch-typed-intent.md

@@ -0,0 +1,385 @@
+# Typed Dispatch Intent: Migration and Refusal Policy
+
+Typed dispatch intent is the structured declaration of what a dispatched worker
+may read, may write, is expected to produce, and must verify. It replaces the
+practice of reconstructing that answer from optional `writeRoots` plus path-like
+tokens recalled from task and briefing prose.
+
+This page is the migration contract. It names every dispatch producer and every
+persisted structure typed intent touches, states what happens when intent is
+omitted, partial, versioned differently, or contradictory, lists the stable
+reason codes an operator or integrator can branch on, and states the measurable
+condition under which the legacy inference fallback may be proposed for removal.
+
+Related pages: [tool-usage.md](tool-usage.md) for the `dispatch` tool arguments,
+[fleet-dispatch.md](fleet-dispatch.md) for fleet contracts,
+[artifact-versions.md](artifact-versions.md) for the serialization registry, and
+[safety-model.md](safety-model.md) for how a resolved write boundary is enforced.
+
+---
+
+## 1. The Shape
+
+```jsonc
+{
+  "intent": {
+    "read_roots":     ["src/domains/dispatch/"],
+    "write_roots":    ["src/domains/dispatch/", "tests/contracts/"],
+    "relevant_paths": ["docs/dispatch-typed-intent.md"],
+    "expected_outputs": ["src/domains/dispatch/intent-compatibility.ts"],
+    "verification":   [{ "check": "typecheck" }, { "check": "lint", "timeout_ms": 60000 }]
+  }
+}
+```
+
+Every path is a repository-relative POSIX path under the boundary grammar in
+`src/core/path-boundary.ts`. A trailing `/` means the subtree; no trailing `/`
+means that exact file. Absolute paths, `..`, `.` segments, backslashes, and
+globs are refused rather than interpreted. Each list is normalized,
+deduplicated, and sorted by code point, holds at most 32 entries, and each entry
+is at most 512 UTF-8 bytes. `verification` holds at most 8 entries and every
+`check` is a declared id resolved from package scripts or
+`.clio-coder/verifiers.yaml`, never a shell command.
+
+Normalization is in `src/domains/dispatch/intent.ts`. The normalized object
+carries `version: 2` and a `pathProvenance` array binding every policy-bearing
+path to the field that declared it, its provenance kind, and its confidence.
+`src/domains/dispatch/path-scope.ts` resolves the request's path scope from it.
+`src/domains/dispatch/intent-compatibility.ts` owns every rule on this page.
+
+---
+
+## 2. Compatibility Rules
+
+Each rule resolves to exactly one of three decisions.
+
+| Decision | Meaning | Where it surfaces |
+| :--- | :--- | :--- |
+| **accept** | The request is unambiguous. | Nothing is reported. |
+| **warn** | The request is compatible, but its policy-bearing scope rests on something weaker than a declaration. The dispatch runs with the authority it would have had anyway. | The approval artifact renders the full resolved scope before a supervised dispatch runs; `pathScope` is sealed on the receipt. |
+| **refuse** | The request states two incompatible things about authority, or states one this build cannot interpret. | Terminal admission error carrying the reason code. The dispatch never runs. |
+
+The invariant that separates `warn` from `refuse`: **a warning is never the
+difference between a narrow grant and a wide one.** No compatibility path widens
+read, write, or verification authority to resolve an ambiguity. When the
+compatible reading and the declared reading disagree about what a worker may
+touch, the answer is a refusal, never the union of the two.
+
+### 2.1 Omitted intent
+
+Accepted, with a warning. Policy-bearing scope is resolved by
+`legacyPathScope()`: legacy `writeRoots` become the write boundary with
+provenance `derived`, and path-like tokens in the task (confidence `medium`) and
+briefing (confidence `low`) become working-context paths with provenance
+`inferred`.
+
+Inferred paths select project rules and compile worker context. They never
+become write boundaries and never add a verification requirement. The only path
+into a write boundary without a declaration is the explicit legacy `writeRoots`
+field, which the caller had to set on purpose. This is what makes omission a
+warning rather than a refusal: nothing about it can widen authority.
+
+An absolute or malformed path token in prose is not silently dropped. It throws
+`DispatchPathScopeInferenceError` with code `legacy_scope_path_absolute` or
+`legacy_scope_path_malformed`, because a token the inference cannot normalize is
+exactly where a silent omission would hide an applicable rule.
+
+### 2.2 Partial intent
+
+Accepted. Every field is independently optional and an omitted list normalizes
+to empty. A declaration is not required to be complete to be authoritative:
+declaring only `write_roots` is a complete statement about write scope.
+
+One partial shape gets a warning. Intent that declares `write_roots` or
+`expected_outputs` but no `verification` describes work that changes the tree
+with nothing the orchestrator itself runs to prove the change is sound
+(`intent_partial_verification_absent`).
+
+One partial shape is refused. An `expected_outputs` entry outside every declared
+`write_root` (`intent_outputs_outside_write_roots`) means the write boundary
+would block exactly the artifact the task is required to produce. Refusing that
+at admission costs a rejected call; accepting it costs a full worker run that
+cannot succeed.
+
+### 2.3 Stale or unsupported version
+
+Refused, never migrated. `DISPATCH_INTENT_SUPPORTED_VERSIONS` is `[2]` and
+membership in that list is the whole test. It is deliberately not a range: a
+reader that accepts "2 or newer" accepts fields it cannot interpret, and a
+reader that accepts "2 or older" reads a v1 statement about authority under v2
+rules. Both are the ambiguity typed intent exists to remove.
+
+Raw model-facing intent may echo `version: 2` so a caller can replay a
+declaration it was shown. Any other value fails normalization with
+`intent_version_unsupported`. A normalized intent arriving on a job spec at
+another version fails admission with the same code. The remedy in both messages
+is the same: restate the fields on a fresh dispatch call.
+
+### 2.4 Contradictory intent
+
+Refused. Three contradictions are enumerated.
+
+- **Legacy against declared write scope.** `writeRoots` and `intent.write_roots`
+  resolving to different trees is `intent_write_roots_contradiction`. Neither the
+  union nor the legacy field wins; the caller drops `writeRoots` and declares
+  once.
+- **Narrowed against enclosing scope.** A per-task intent in a batch, or any
+  other narrowed declaration, reaching outside the intent it narrows is
+  `intent_scope_widening`. Narrowing is monotonic: downstream may shrink and may
+  never reach outside. Read scope is checked against reads plus writes, because a
+  declared write root is necessarily readable.
+- **Write scope against run authority.** `write_roots` declared on a request
+  whose autonomy is `read-only` is `intent_write_without_authority`. Silently
+  dropping the declaration would leave the request claiming a write scope nothing
+  enforces.
+
+The declared-versus-inferred case is not a contradiction and is not refused.
+When a request declares intent, prose inference stops resolving scope entirely;
+paths mentioned only in prose are reported as omitted through
+`typed_scope_replaced_inferred_paths` and take no part in rule selection or
+authority. Declared always outranks inferred.
+
+---
+
+## 3. Producer Compatibility Table
+
+Every producer that can reach a worker passes through `validateJobSpec()` in
+`src/domains/dispatch/validation.ts`, which is where the classifier runs. The
+rules above therefore hold for every row below, including the rows that cannot
+declare intent yet: those rows resolve scope by inference and are refused only
+when they state a contradiction.
+
+| Dispatch producer | Source | Typed intent | Behavior without declaration | Refuses on |
+| :--- | :--- | :--- | :--- | :--- |
+| **`dispatch` tool, singular `task`** | `src/tools/dispatch-arguments.ts` | Declared, top-level `intent` | Legacy inference from `writeRoots` + task/briefing tokens | All codes |
+| **`dispatch` tool, batch `tasks[]`** | `src/tools/dispatch-arguments.ts` | Declared per task, shallow-merged over the top-level default | Same as singular, per task | All codes, plus `intent_scope_widening` against the top-level ceiling |
+| **`dispatch` modes parallel / sequential / pipeline / detached** | `src/tools/dispatch-admission.ts` | Inherited unchanged from the task that declared it | Legacy inference | All codes |
+| **`dispatch` mode compete, candidates** | `src/tools/dispatch-admission.ts` | Inherited unchanged from the single base task | Legacy inference | All codes. `verification` is refused for the mode (`verification_unsupported_for_mode`) |
+| **`dispatch` mode compete, judge** | `src/tools/dispatch-admission.ts` | None. The judge is a fresh read-only request | Legacy inference over the judge's own task | All codes |
+| **`dispatch` mode council, members** | `src/tools/dispatch-admission.ts` | Inherited, narrowed to read-only: declared write roots arrive as read roots | Legacy inference | All codes. `verification` is refused for the mode (`council_verification_unsupported`) |
+| **`dispatch` mode council, synthesis judge** | `src/tools/dispatch-admission.ts` | None. Fresh read-only request | Legacy inference over the judge's own task | All codes |
+| **`dispatch` review gate, builder** | `src/tools/dispatch-admission.ts` | Inherited unchanged | Legacy inference | All codes |
+| **`dispatch` review gate, reviewer** | `src/tools/dispatch-admission.ts` | None on the request. `expected_outputs` and `verification` reach the reviewer as rendered *requirements*, never as evidence | Legacy inference over the reviewer's own task | All codes |
+| **`dispatch` `apply_winner`** | `src/tools/dispatch-admission.ts` | Not applicable. Branch application runs no worker | Not applicable | Branch-shape refusals only |
+| **`from_scout` continuation** | `src/tools/dispatch-scout-admission.ts` | **None today.** The compiled continuation plan carries no intent | Legacy inference per step | Contradiction codes only |
+| **Fleet contract agent step (v4+ `writes:`)** | `src/domains/dispatch/fleet-run.ts` | Declared. The contract's `writes:` compiles to `relevant_paths` | Legacy inference for pre-v4 contracts and readonly steps | All codes |
+| **Fleet contract gate / plan step** | `src/domains/dispatch/fleet-run.ts` | Declared, same path (`writes` is the gate path or the plan step's boundary) | Legacy inference when undeclared | All codes |
+| **Fleet delegation-plan spliced step** | `src/domains/dispatch/fleet-run.ts` | Declared from the validated plan task's `writes` | Legacy inference when the task declares none | All codes |
+| **Fleet code step** | `src/domains/dispatch/code-step.ts` | Not applicable. Runs a declared command, not a worker | Not applicable | Not applicable |
+| **ACP delegation target** | `src/domains/dispatch/extension.ts` | Accepted and carried into the plan, but the external agent runs its own tool surface | Legacy inference | All codes, plus a hard refusal of any resolved `writeRoots` on this transport |
+| **Custom agent recipe** | `src/domains/agents/` | Not a producer. A recipe narrows the tool surface and capability class; it never declares dispatch scope | Not applicable | Not applicable |
+| **Extension-authored `DispatchRequest`** | Any `DispatchContract` consumer | Declared, if the extension builds one through `declaredScopeIntent()` or the normalizer | Legacy inference | All codes |
+| **`clio-coder run --agent`** | `src/cli/run.ts` | **None today** | Legacy inference | Contradiction codes only |
+| **`clio-coder wiki generate`** | `src/cli/wiki-generate.ts` | **None today.** Sets legacy `writeRoots` | Legacy inference plus a derived write boundary | Contradiction codes only |
+| **`clio-coder bootstrap generate`** | `src/cli/bootstrap-generate.ts` | **None today** | Legacy inference | Contradiction codes only |
+| **Interactive slash commands, overlays, watchdog** | `src/interactive/` | **None today** | Legacy inference | Contradiction codes only |
+
+"All codes" means every code in section 5 that can apply to the row's shape.
+"Contradiction codes only" means the row cannot declare intent, so only the
+`intent_absent_legacy_inference` warning and the legacy inference errors apply.
+
+---
+
+## 4. Persisted and Serialized Contract Table
+
+| Contract | Version | Carries intent | Migration policy |
+| :--- | :--- | :--- | :--- |
+| **`DispatchIntent`** | `2` | It *is* the intent | **Refused, never migrated.** Any other version fails admission with `intent_version_unsupported`. A stored declaration is restated on a fresh call. |
+| **`DispatchPathScopeProvenance`** | `1` | Resolved scope with field source and confidence, never source prose | Sealed inside the receipt; shares the receipt's policy. |
+| **Run Receipt** | `20` | `intent` and `pathScope`, both inside the integrity digest | **Refused, never migrated.** A receipt below v20 is reported as retired: intact, but never read as evidence. |
+| **`ResolvedDispatchPlanArtifact`** | `3` | `intent` and `resolvedVerification` per task | **Refused, never migrated.** `resolvedDispatchPlanFromArgs` returns `null` for any version but 3, and a task whose `intent` fails `isDispatchIntent` invalidates the whole artifact. The call falls back to unresolved admission rather than executing a half-understood plan. |
+| **Dispatch plan approval text and hash** | Rendered, hashed | `intent_sha256` for a declared task; the full inferred scope table for a legacy task | Not persisted across versions. The hash binds the exact rendering an operator approved. |
+| **Worker Spec** | `3` | **No.** Carries the *resolved* `writeRoots`, not the declaration | Fail-closed preflight rejection. Deliberate: a worker receives an enforced boundary, never a statement of intent it could reinterpret. |
+| **Execution Plan** | `4` | **No.** Carries per-step `writes` | Preflight rejects unsupported plan versions. Intent is built from `writes` at request construction, so the plan hash is unchanged by this. |
+| **Fleet Contract** | `1..5` | **No.** v4+ carries per-step `writes:` | Reader refuses contracts whose version features it does not support. A pre-v4 contract declares nothing and stays on inference. |
+| **Fleet Run Record** | `1` | **No** | Resume refuses a changed plan hash. Adding intent to steps does not change the hash, so existing records stay resumable. |
+| **Durable Assignment Store** | `1` | **No** | Unsupported or unreadable store reads as empty. |
+| **Detached Batch Store** | `1` | **No** | Unsupported version reads as empty. |
+| **Code Step Record** | `1` | **No.** Deterministic command, not a worker | Records at other versions are skipped. |
+
+Nothing is archived. Every affected structure either refuses an unsupported
+version or ignores the record; no reader rewrites a stored artifact in place, so
+a downgrade never encounters a file a newer build silently rewrote.
+
+### 4.1 Determinism across source and installed-package paths
+
+`intent-compatibility.ts` and the version rules in `intent.ts` read no
+filesystem, no clock, no environment, and no package layout. The supported
+version set is a compiled-in constant, not a lookup. A source checkout, a global
+npm install, and a bundled `dist/` therefore classify identical input
+identically, which is what makes the version policy verifiable rather than
+environmental. `tests/contracts/dispatch-intent-compatibility.test.ts` asserts it
+by classifying the same input from two different working directories.
+
+The one input that is legitimately environmental is the *verification catalog*:
+`check` ids resolve from the project's `package.json` scripts and
+`.clio-coder/verifiers.yaml`, which are properties of the workspace, not of the
+Clio installation. An undeclared id fails closed with
+`verification_check_undeclared` naming both sources.
+
+---
+
+## 5. Reason Codes
+
+Every code is stable and appears as the prefix of its diagnostic, in the form
+`<code>: <what is wrong and what to do about it>`.
+
+| Code | Decision | Meaning |
+| :--- | :--- | :--- |
+| `intent_absent_legacy_inference` | warn | No typed intent; scope came from legacy inference. |
+| `intent_partial_verification_absent` | warn | Declares tree-changing work with no verification requirement. |
+| `typed_scope_replaced_inferred_paths` | warn | Typed intent was declared, so prose-only paths took no part in scope. |
+| `legacy_scope_inferred` | warn | Legacy dispatch resolved policy-bearing scope with no declaration. |
+| `legacy_scope_empty` | warn | Legacy dispatch inferred no policy-bearing path at all. |
+| `intent_version_unsupported` | refuse | `intent.version` names a version this build does not speak. |
+| `intent_malformed` | refuse | Not a normalized intent for a reason other than its version. |
+| `intent_write_roots_contradiction` | refuse | Legacy `writeRoots` and `intent.write_roots` name different trees. |
+| `intent_outputs_outside_write_roots` | refuse | A declared output lies outside every declared write root. |
+| `intent_write_without_authority` | refuse | Write roots declared on a read-only request. |
+| `intent_scope_widening` | refuse | A narrowed intent reaches outside the intent it narrows. |
+| `intent_path_absolute` | refuse | A declared path is absolute rather than repository-relative. |
+| `intent_path_escapes_root` | refuse | A declared path escapes the repository root. |
+| `intent_path_malformed` | refuse | A declared path fails the boundary grammar. |
+| `intent_path_over_cap` | refuse | A list exceeds 32 entries or an entry exceeds 512 bytes. |
+| `verification_malformed` | refuse | A verification entry is not `{check, timeout_ms?}`. |
+| `verification_over_cap` | refuse | More than 8 verification entries. |
+| `verification_check_undeclared` | refuse | A `check` id is not declared by any catalog source. |
+| `gate_and_intent_verification_conflict` | refuse | `gate` combined with `intent.verification`. |
+| `legacy_scope_path_absolute` | refuse | Prose inference met an absolute path token. |
+| `legacy_scope_path_malformed` | refuse | Prose inference met a malformed path token. |
+
+---
+
+## 6. Examples
+
+Typed intent is the default for every example below. A call that omits it still
+works; it just resolves its scope from weaker evidence.
+
+### 6.1 Main-agent call, single writer
+
+```jsonc
+{
+  "agent": "coder",
+  "task": "Add the compatibility classifier and wire it into job-spec validation.",
+  "intent": {
+    "read_roots":     ["src/domains/dispatch/"],
+    "write_roots":    ["src/domains/dispatch/", "tests/contracts/"],
+    "expected_outputs": ["src/domains/dispatch/intent-compatibility.ts"],
+    "verification":   [{ "check": "typecheck" }, { "check": "lint" }]
+  }
+}
+```
+
+The `expected_outputs` entry sits under a declared write root, so it is
+producible. `verification` ids resolve before approval, and the orchestrator, not
+the worker, runs them.
+
+### 6.2 Batch with a shared ceiling and per-task narrowing
+
+```jsonc
+{
+  "agent": "coder",
+  "intent": { "read_roots": ["src/"], "write_roots": ["src/domains/"] },
+  "tasks": [
+    { "task": "Refactor the ledger hub.",  "intent": { "write_roots": ["src/domains/dispatch/"] } },
+    { "task": "Refactor rule selection.",  "intent": { "write_roots": ["src/domains/context/"] } }
+  ]
+}
+```
+
+Per-task intent shallow-merges over the top-level default and is then checked
+against it as a ceiling. `"write_roots": ["docs/"]` on a task would be refused
+with `intent_scope_widening`; the top-level declaration is the maximum.
+
+### 6.3 Read-only fan-out
+
+```jsonc
+{
+  "agent": "scout",
+  "tasks": [
+    { "task": "Map every reader of the fleet config and cite file paths.",
+      "intent": { "read_roots": ["src/domains/agents/", "src/cli/"] } }
+  ]
+}
+```
+
+Declaring `read_roots` on a read-only dispatch does not grant anything. It
+selects the project rules that apply to those trees and pins the worker's
+context, which is what stops an applicable rule from being missed because the
+task text happened not to spell a path.
+
+### 6.4 Fleet contract
+
+A fleet contract declares scope in its own artifact; no `intent` key is written
+by hand.
+
+```yaml
+version: 5
+name: refactor-dispatch
+steps:
+  - id: implement
+    kind: agent
+    agent: coder
+    scope: workspace
+    writes: ["src/domains/dispatch/", "tests/contracts/"]
+```
+
+`writes:` is compiled into the step's typed intent as `relevant_paths`, so the
+contract's declaration selects project rules and compiles worker context. The
+declaration keeps being *enforced* by the fleet write-boundary enforcer after
+the step, which is why it is not restated as `write_roots`: that would mint a
+second grant, enforced at the per-tool worker seam, which refuses outright on
+the subprocess and ACP runtimes a fleet may legitimately route a step to.
+
+### 6.5 Extension-authored request
+
+An extension holding repository-relative paths builds intent through the domain
+rather than assembling the normalized object by hand:
+
+```ts
+import { declaredScopeIntent } from "../domains/dispatch/index.js";
+
+const built = declaredScopeIntent({ readRoots: ["src/"], writeRoots: ["src/generated/"] });
+if (!built.ok) throw new Error(`${built.reason}: ${built.message}`);
+await dispatch.dispatch({ agentId: "coder", executionRole: "builder", task, intent: built.intent });
+```
+
+`declaredScopeIntent` runs the same normalization, caps, and provenance
+construction the dispatch tool uses, so an extension cannot mint an intent shape
+the tool could not. It deliberately does not accept `verification`: a declared
+check id means nothing until it is resolved against the workspace catalog, and
+that resolution belongs to the admission controller that owns the catalog.
+
+### 6.6 ACP delegation
+
+Typed intent is accepted on a delegation request and is rendered into the
+approval artifact, so an operator sees the declared scope before an external
+agent starts. It grants nothing on that transport: the external agent runs its
+own tool surface, Clio mediates no per-tool call, and any resolved `writeRoots`
+is refused outright rather than accepted and left unenforced.
+
+---
+
+## 7. Retirement Criterion for Legacy Inference
+
+Removing the inference fallback requires a later explicit issue. This is the
+gate that issue has to clear, and it is measured rather than argued.
+
+`pathScope.mode` is sealed on every receipt, so the share of dispatches still
+resolving policy-bearing scope from prose is a fact in the evidence store.
+`dispatchIntentAdoption()` in `src/domains/dispatch/intent-compatibility.ts`
+computes it, reading nothing but that mode field so the aggregate is safe to
+report from receipts whose prose must not be quoted.
+
+The criterion is met when, over a window of receipts:
+
+- at least `DISPATCH_INTENT_RETIREMENT_MIN_SAMPLE` (200) receipts carry a
+  resolved `pathScope`, and
+- at most `DISPATCH_INTENT_RETIREMENT_MAX_LEGACY_SHARE` (2%) of them have
+  `mode: "legacy-inferred"`.
+
+A window with no measured receipts reports `legacyShare: null` and is never
+ready, so an empty evidence store cannot read as full adoption. The producer
+rows in section 3 marked **None today** are the concrete work that has to land
+before the share can fall: each is a producer that cannot currently declare, so
+each one contributes to the legacy count no matter how the model behaves.

package/docs/documentation-coverage.md

@@ -1,6 +1,6 @@
 # Clio Coder Documentation Coverage Matrix
 
-This matrix maps every top-level directory in `src/` and every domain directory under `src/domains/` to its authoritative documentation page. It records coverage status (`documented`, `partial`, `undocumented`), missing concepts, and key source contracts for `v0.3.7`.
+This matrix maps every top-level directory in `src/` and every domain directory under `src/domains/` to its authoritative documentation page. It records coverage status (`documented`, `partial`, `undocumented`), missing concepts, and key source contracts for `v0.4.0`.
 
 ## Coverage Matrix
 
@@ -35,7 +35,7 @@ This matrix maps every top-level directory in `src/` and every domain directory
 | `src/domains/scheduling/` | Capacity lease acquisition, heartbeats, expiry, cross-process locks, cluster scheduling | [capacity-and-scheduling.md](capacity-and-scheduling.md), [fleet-dispatch.md](fleet-dispatch.md) | `documented` | Dedicated capacity leasing, heartbeat TTL, and cross-process lock reference. |
 | `src/domains/session/` | Session ledger format v4, tree branching (`/tree`), `/fork`, `/resume`, checkpoints, protected-artifact journal | [session-lifecycle.md](session-lifecycle.md), [context-working-set.md](context-working-set.md) | `documented` | Dedicated session lifecycle guide covering branching, journal, and recovery; the `contextEviction` and `contextRecall` records added at format v4 are specified in the working-set guide. |
 | `src/domains/share/` | Portable share archive bundles, manifest verification, import/export flows | [extensions-and-sharing.md](extensions-and-sharing.md) | `documented` | Share archives and portable bundle formats documented in extensions guide. |
-| `src/domains/webhook/` | Empty directory | None (Inert) | `inert` | Directory contains no active modules or exports in v0.3.7. |
+| `src/domains/webhook/` | Empty directory | None (Inert) | `inert` | Directory contains no active modules or exports in v0.4.0. |
 
 ## Cross-Cutting Reference Guides
 

package/docs/documentation-guide.md

@@ -1,7 +1,7 @@
 # Documentation Standards and Codebase Alignment
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive documentation link linter, phrasing/claim evaluator, and alignment portal is located at [docs/html/documentation_blueprint.html](html/documentation_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive documentation link linter, phrasing/claim evaluator, and alignment portal is located at [docs/html/documentation_blueprint.html](html/documentation_blueprint.html) (Version: 0.4.0).
 
 Clio Coder is an experimental community alpha. Documentation should help contributors and early users work from the source of truth without overstating maturity. When docs drift, prefer the current source and tests over older prose or aspirational roadmap notes.
 

package/docs/environment-variables.md

@@ -42,6 +42,7 @@ Durable values live in the `guardrails:` section of settings.yaml (see [configur
 | `CLIO_CODER_SKILL_CATALOG_DIR` | unset | Local skill-catalog directory override (`src/domains/resources/skills/marketplace.ts`). |
 | `CLIO_CODER_SKILL_MARKETPLACE_INDEX` | unset | Skill-marketplace index path override (`src/domains/resources/skills/marketplace.ts`). |
 | `CLIO_CODER_MODEL_CATALOG_DIRS` | unset | Extra model-catalog directories (`src/domains/providers/knowledge-base-path.ts`). |
+| `CLIO_CODER_ENDPOINT_SLOTS_TTL_MS` | 86400000 | How long a persisted endpoint slot count answers for an endpoint nothing has probed in this process. A record past the bound is ignored and pruned rather than allowed to over-admit (`src/domains/providers/endpoint-slots-store.ts`). |
 | `CLIO_CODER_NO_NETWORK_TOOLS` | off | `1` strips network tools from every registry in the process; the skills-eval harness sets it for hermetic arms; `--allow-network` clears it (`src/tools/network-policy.ts`). |
 | `CLIO_CODER_SMOOTH_STREAM` | settings value | Per-process override for `terminal.smoothStreaming`: `0`/`off`/`false`, `auto`, or `1`/`on`/`true`. A valid value wins over settings; an invalid value fails safely to `off`. |
 | `CLIO_CODER_REDUCE_MOTION` | off | `1` makes smooth-streaming `auto` use the immediate coalescer. Explicit `on` remains an operator request, while stdout backpressure still pauses frame production. |

package/docs/eval-runner.md

@@ -1,7 +1,7 @@
 # Clio Coder Local Evaluation Runner
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive task suite validator, subprocess execution simulator, and compare calculator is located at [docs/html/eval_blueprint.html](html/eval_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive task suite validator, subprocess execution simulator, and compare calculator is located at [docs/html/eval_blueprint.html](html/eval_blueprint.html) (Version: 0.4.0).
 
 The local evaluation runner executes repository-local YAML task suites as deterministic subprocess checks. It is useful for comparing harness changes, prompts, tools, or local workflows.
 

package/docs/evals-internal.md

@@ -1,7 +1,7 @@
 # Internal Eval Suites
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive blueprint is available at [docs/html/evals_internal_blueprint.html](html/evals_internal_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive blueprint is available at [docs/html/evals_internal_blueprint.html](html/evals_internal_blueprint.html) (Version: 0.4.0).
 
 Private suites should live outside this repository. Keep datasets, prompts,
 live fleet coordinates, calibration outputs, and raw run artifacts in a private

package/docs/evidence-and-memory.md

@@ -1,9 +1,9 @@
 # Evidence Corpus and Long-Term Memory
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.9). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.4.0). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
 
-Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.3.7, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
+Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.4.0, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.
 

package/docs/evolution.md

@@ -1,7 +1,7 @@
 # Evolution and Change Manifests
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive change manifest editor, authority risk assessor, and checklist workspace is located at [docs/html/evolution_blueprint.html](html/evolution_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive change manifest editor, authority risk assessor, and checklist workspace is located at [docs/html/evolution_blueprint.html](html/evolution_blueprint.html) (Version: 0.4.0).
 
 Clio Coder uses change manifests to make harness changes reviewable, falsifiable, and rollback-friendly. CLIO stands for Context Layer for Input/Output, named for the Greek muse of history. A manifest is JSON, generated or checked with `clio-coder evolve manifest`, and should describe what changed, why, what evidence supports it, what could regress, how to validate it, and how to roll it back.