@iowarp/clio-coder 0.4.1 → 0.4.3

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

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

package/docs/architecture/time-conventions.md

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

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

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

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

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

package/docs/{worker-dispatch-mechanics.md → architecture/worker-dispatch-mechanics.md}

@@ -1,17 +1,17 @@
 # Worker Dispatch Mechanics
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Worker Dispatch Mechanics visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/worker_dispatch_blueprint.html).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
 Source of truth:
-- Subprocess entry: [src/worker/entry.ts](../src/worker/entry.ts)
-- Input demultiplexing: [src/worker/stdin-demux.ts](../src/worker/stdin-demux.ts)
-- Heartbeat loop: [src/worker/heartbeat.ts](../src/worker/heartbeat.ts)
-- Spec contracts and exit codes: [src/worker/spec-contract.ts](../src/worker/spec-contract.ts)
-- Dispatch orchestrator: [src/domains/dispatch/index.ts](../src/domains/dispatch/index.ts)
-- Engine worker runtime: [src/engine/worker-runtime.ts](../src/engine/worker-runtime.ts)
+- Subprocess entry: [src/worker/entry.ts](../../src/worker/entry.ts)
+- Input demultiplexing: [src/worker/stdin-demux.ts](../../src/worker/stdin-demux.ts)
+- Heartbeat loop: [src/worker/heartbeat.ts](../../src/worker/heartbeat.ts)
+- Spec contracts and exit codes: [src/worker/spec-contract.ts](../../src/worker/spec-contract.ts)
+- Dispatch orchestrator: [src/domains/dispatch/index.ts](../../src/domains/dispatch/index.ts)
+- Engine worker runtime: [src/engine/worker-runtime.ts](../../src/engine/worker-runtime.ts)
 
 ---
 
@@ -71,7 +71,7 @@ The worker entry mounts a custom stdin demultiplexer (`createWorkerStdinDemux`)
 1. **Steering Commands:**
    `{"type": "steer", "text": "guidance message", "sequence": 1}`
    Instructs a live-input HTTP or SDK worker to alter course. Its runtime emits
-   the receipt-bearing `clio_steer_received` event only after accepting the
+   the receipt-bearing `clio_coder_steer_received` event only after accepting the
    message for the next turn boundary. Single-shot subprocess runtimes install
    no steering handler, drop unexpected guidance without claiming receipt, and
    are not offered steering by the dispatch contract or TUI.
@@ -110,7 +110,7 @@ stateDiagram-v2
 
     state EscalatePosture {
         [*] --> ParkCall
-        ParkCall --> EmitEscalatedEvent : stdout <- clio_permission_escalated
+        ParkCall --> EmitEscalatedEvent : stdout <- clio_coder_permission_escalated
         EmitEscalatedEvent --> WaitForInput
         WaitForInput --> ResolveApprove : stdin -> permission_decision (approve)
         WaitForInput --> ResolveDeny : stdin -> permission_decision (deny)
@@ -126,7 +126,7 @@ stateDiagram-v2
 2. **Fail:** Terminate the run immediately, exiting the worker subprocess with exit code `3` (`WORKER_EXIT_PERMISSION_REQUIRED`).
 3. **Escalate (Parking Loop):**
    - The worker parks the tool execution thread.
-   - It generates a unique `requestId` and emits a `clio_permission_escalated` event to `stdout`.
+   - It generates a unique `requestId` and emits a `clio_coder_permission_escalated` event to `stdout`.
    - The parent process intercepts this event, displays the approval prompt in the interactive TUI, and waits for the operator.
    - If the operator selects approve or deny, the parent writes `{"type":"permission_decision", "requestId":"...", "decision":"..."}` to the worker's `stdin`.
    - The demuxer resolves the parked promise, resuming tool execution.
@@ -157,7 +157,7 @@ stream ends when the assignment settles, not when one attempt's worker exits,
 so a consumer that drains it has seen exactly the run the terminal receipt
 describes. A canceled assignment ends its stream immediately.
 
-Retry timing is governed by `workers.maxRetries` and exponential backoff alone.
+Retry timing is governed by `fleet.retry.maxRetries` and exponential backoff alone.
 Target cooldowns gate *new* dispatches to a known-bad target and are not
 applied to retries of an in-flight assignment, whose retry budget already
 bounds it. A retry refused at admission settles the assignment failed and
@@ -207,7 +207,7 @@ The coordinator classifies failures into 13 explicit categories (`src/domains/di
 
 ### 5.2 Canonical Receipt Integrity Serialization
 
-Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 19`); any other version is invalid. It computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`).
+Receipts carry the current integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 20`). Verification computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`). A pre-v20 receipt is retired and cannot be read as current evidence; a malformed or digest-mismatched v20 receipt is invalid.
 
 - **Object Key Sorting**: Keys are sorted lexicographically before serialization (`Object.keys(obj).sort()`).
 - **Strict Primitive Handling**: `undefined` object properties are omitted; non-finite numbers (`NaN`, `Infinity`) or `bigint` throw an explicit serialization error.
@@ -225,23 +225,20 @@ state vocabulary and compatibility map are documented in
 
 ### 5.3 Acceptance Coverage
 
-The assignment contract's acceptance scenarios map to deterministic contract
-tests as follows:
-
-| # | Scenario | Contract test |
-| --- | --- | --- |
-| 1 | Remote stall, approved local fallback, attached success | `dispatch-envelope.test.ts`: "falls back from remote to local only within an approved envelope" |
-| 2 | Detached collection returns successful terminal fallback | `dispatch-assignment-detached.test.ts`: "collects the terminal retry…" |
-| 3 | Pipeline consumes terminal fallback output | `dispatch-assignment-detached.test.ts`: "threads the successful retry output…" |
-| 4 | Failed attempt remains visible and integrity-verifiable | `dispatch-assignment.test.ts`: "resolves attached dispatch…" (also covered by detached collection) |
-| 5 | Cancellation starts no retry | `dispatch-assignment.test.ts`: "canceling the root attempt starts no retry" |
-| 6 | Cancellation does not cool the target | `dispatch-failure-class.test.ts`: "keeps cancellation and permission neutral…" |
-| 7 | Permission/policy rejection is retry- and breaker-neutral | `dispatch-failure-class.test.ts`: classification/decision table and neutral-target test |
-| 8 | Node-channel failure changes node but retains model | `dispatch-failure-class.test.ts`: "moves only the node…" |
-| 9 | Rate limit retains agent/model and delays or changes target | `dispatch-failure-class.test.ts`: "changes target after rate limiting…" |
-| 10 | Exhaustion returns one failure with all attempt receipts | `dispatch-assignment.test.ts`: "settles exhausted retries…" |
-| 11 | Exact manual pin never falls back | `dispatch-envelope.test.ts`: "keeps a manual exact pin fail-closed…" |
-| 12 | Approved envelope never spawns outside its candidate list | `dispatch-envelope.test.ts`: "settles failed instead of spawning an unlisted candidate" |
+The current reduced contract suite divides dispatch coverage by ownership:
+
+| Contract | Current executable coverage |
+| --- | --- |
+| `tests/contracts/dispatch-lifecycle.test.ts` | Attached and detached lifecycle deduplication, durable transitions, terminal finalization, and orphan recovery from durable attempts. |
+| `tests/contracts/dispatch-admission.test.ts` | Typed-scope authority, capability pairing, deterministic capacity admission, conservative slot defaults, and ACP authority boundaries. |
+| `tests/contracts/dispatch-schema.test.ts` | Capability-shaped model schema, referenced `$defs`, and hidden-field compatibility. |
+
+Earlier releases carried separate envelope, assignment, detached-assignment,
+and failure-class test files for the detailed retry scenarios. Those files are
+not present in the current tree, so this page does not cite them as executable
+coverage. Retry and failover behavior remains owned by the dispatch source and
+the three maintained contracts above cover only the responsibilities stated in
+this table.
 
 ## 6. Worker Exit Codes