@iowarp/clio-coder 0.4.1 → 0.4.2

package/dist/chunk-UOV2BYIW.js

@@ -1,107 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  init_esm_shims
-} from "./chunk-3R73A4XB.js";
-
-// src/domains/safety/loop-detector.ts
-init_esm_shims();
-var DEFAULT_WINDOW_MS = 3e4;
-var DEFAULT_MAX_REPEATS = 3;
-var DEFAULT_KEEP_LAST_ATTEMPTS = 4;
-function createLoopState(opts) {
-  const windowMs = opts?.windowMs ?? DEFAULT_WINDOW_MS;
-  const maxRepeats = opts?.maxRepeats ?? DEFAULT_MAX_REPEATS;
-  const keepLastAttempts = opts?.keepLastAttempts ?? DEFAULT_KEEP_LAST_ATTEMPTS;
-  return { recent: [], windowMs, maxRepeats, keepLastAttempts };
-}
-function hashToolCall(tool, args) {
-  let argPart;
-  try {
-    argPart = canonicalSerialize(args ?? {}, /* @__PURE__ */ new WeakSet());
-  } catch {
-    argPart = "<unrepresentable>";
-  }
-  return `${tool}${argPart}`;
-}
-function canonicalSerialize(value, seen) {
-  if (value === null) return "null";
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) {
-      throw new Error(`canonicalSerialize: non-finite number ${String(value)} is not representable`);
-    }
-    return JSON.stringify(value);
-  }
-  if (typeof value === "string" || typeof value === "boolean") {
-    return JSON.stringify(value);
-  }
-  if (typeof value === "bigint") {
-    throw new Error("canonicalSerialize: bigint is not representable");
-  }
-  if (typeof value === "symbol" || typeof value === "function" || value === void 0) {
-    throw new Error(`canonicalSerialize: ${typeof value} is not representable`);
-  }
-  if (Array.isArray(value)) {
-    if (seen.has(value)) throw new Error("canonicalSerialize: circular reference is not representable");
-    seen.add(value);
-    try {
-      const parts = [];
-      for (let i = 0; i < value.length; i++) {
-        if (!(i in value) || value[i] === void 0) {
-          parts.push("null");
-          continue;
-        }
-        parts.push(canonicalSerialize(value[i], seen));
-      }
-      return `[${parts.join(",")}]`;
-    } finally {
-      seen.delete(value);
-    }
-  }
-  if (typeof value === "object") {
-    if (value instanceof Date) {
-      const jsonValue = value.toJSON();
-      return jsonValue === null ? "null" : JSON.stringify(jsonValue);
-    }
-    if (seen.has(value)) throw new Error("canonicalSerialize: circular reference is not representable");
-    seen.add(value);
-    const obj = value;
-    try {
-      const keys = Object.keys(obj).sort();
-      const parts = [];
-      for (const key of keys) {
-        const child = obj[key];
-        if (child === void 0) continue;
-        parts.push(`${JSON.stringify(key)}:${canonicalSerialize(child, seen)}`);
-      }
-      return `{${parts.join(",")}}`;
-    } finally {
-      seen.delete(value);
-    }
-  }
-  throw new Error(`canonicalSerialize: unsupported value of type ${typeof value}`);
-}
-function observe(state, key, now) {
-  const cutoff = now - state.windowMs;
-  const keepLast = state.keepLastAttempts ?? DEFAULT_KEEP_LAST_ATTEMPTS;
-  const appended = [...state.recent, { key, at: now }];
-  const floorStart = Math.max(0, appended.length - keepLast);
-  const next = appended.filter((entry, index) => index >= floorStart || entry.at >= cutoff);
-  let count = 0;
-  for (const entry of next) {
-    if (entry.key === key) count += 1;
-  }
-  const looping = count >= state.maxRepeats;
-  const newState = {
-    recent: next,
-    windowMs: state.windowMs,
-    maxRepeats: state.maxRepeats
-  };
-  return [newState, { looping, key, count }];
-}
-
-export {
-  createLoopState,
-  hashToolCall,
-  observe
-};
-//# sourceMappingURL=chunk-UOV2BYIW.js.map

package/dist/chunk-WR6U3OVP.js

@@ -1,45 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  PANES_PRESET_IDS
-} from "./chunk-GIZNH63R.js";
-import {
-  typebox_exports
-} from "./chunk-5B2AEOW5.js";
-import {
-  ToolNames
-} from "./chunk-K6BSR66V.js";
-import {
-  StringEnum
-} from "./chunk-VXMFAE2W.js";
-import {
-  init_esm_shims
-} from "./chunk-3R73A4XB.js";
-
-// src/tools/panes-surface.ts
-init_esm_shims();
-var panesToolSurface = {
-  name: ToolNames.Panes,
-  description: `Look at, focus, and manage the terminal panes Clio owns beside this session. Use show to bring a dispatched run's live viewer pane to the front when the operator asks to see an agent ("show me the tester"). open starts one of the fixed utility presets; there is no way to run an arbitrary command. close removes a pane Clio created. list reports the current inventory and the pane layer's health.`,
-  parameters: typebox_exports.Object({
-    action: StringEnum(["show", "open", "close", "list"], {
-      description: "show focuses a run's viewer pane; open starts a preset utility pane; close removes a Clio-owned pane; list reports the inventory."
-    }),
-    target: typebox_exports.Optional(
-      typebox_exports.String({
-        description: 'action=show: an agent id or run id prefix, most recent match wins. action=close: a pane id, a pane label, an agent id, or "all".'
-      })
-    ),
-    preset: typebox_exports.Optional(
-      StringEnum([...PANES_PRESET_IDS], {
-        description: "action=open: which fixed utility pane to start."
-      })
-    )
-  }),
-  baseActionClass: "read",
-  executionMode: "sequential"
-};
-
-export {
-  panesToolSurface
-};
-//# sourceMappingURL=chunk-WR6U3OVP.js.map

package/docs/artifact-versions.md

@@ -1,67 +0,0 @@
-# Artifact Versions & Serialization Contracts
-
-This document is the canonical registry of all versioned file formats, serialized data structures, integrity digests, and migration rules across Clio Coder in `v0.4.0`.
-
----
-
-## 1. Versioned Artifacts Registry
-
-Clio Coder strictly versions every persistent or network-transported data structure. When a reader encounters an incompatible version, it either executes an automated migration or fails closed with a typed error.
-
-| Artifact / Subsystem | Current Version | Symbol / Type & Source Location | Persisted Path / Wire Location | Schema Semantics & Version Differences | Mismatch Handling |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| **Run Receipt** | `20` | `RUN_RECEIPT_INTEGRITY_VERSION = 20`<br>`src/domains/dispatch/receipt-integrity.ts:13` | `<stateDir>/receipts/<runId>.json` | Cryptographically sealed run record. Version 20 adds `pathProvenance` on dispatch intent and the resolved `pathScope`, over the v19 base of provenance fields, routing intent, quality labels, `validationGrounding`, `capabilityMismatch`, council provenance, and fleet gate provenance. | Fail-closed. A receipt below v20 is reported as retired rather than invalid, is never read as evidence, and is never migrated; a malformed or tampered v20 receipt fails verification. |
-| **Dispatch Intent** | `2` | `DISPATCH_INTENT_VERSION = 2`, `DISPATCH_INTENT_SUPPORTED_VERSIONS = [2]`<br>`src/domains/dispatch/intent-compatibility.ts` | Inside the resolved dispatch plan artifact, the `JobSpec`/`DispatchRequest`, and the sealed run receipt | Typed model- and producer-declared scope: `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and declared-id `verification`, plus the `pathProvenance` binding every policy-bearing path to the field that declared it. Version 2 adds `pathProvenance` over the v1 path-and-output shape. | Fail-closed, never migrated. The supported set is a membership list, not a range: any other version is refused with `intent_version_unsupported` and the caller restates the fields on a fresh dispatch call. Omitted intent is accepted through the separately tracked legacy inference path; contradictory intent is a terminal refusal. See [dispatch-typed-intent.md](dispatch-typed-intent.md). |
-| **Dispatch Path Scope Provenance** | `1` | `version: 1` in `interface DispatchPathScopeProvenance`<br>`src/domains/dispatch/path-scope.ts` | `pathScope` on the sealed run receipt | Resolved policy-bearing paths with per-field provenance (`declared`/`derived`/`inferred`), source, and confidence. Never carries the task or briefing prose an inferred path came from. | Sealed inside the receipt integrity digest; shares the receipt's fail-closed policy. |
-| **Resolved Dispatch Plan Artifact** | `3` | `version: 3` in `interface ResolvedDispatchPlanArtifact`<br>`src/tools/dispatch-plan.ts:122` | Trusted admission-time tool argument, rendered and hashed into the plan approval | Pinned agent/target/model/node per task plus the sealed `intent` and admission-resolved `resolvedVerification`. The rendered artifact carries `intent_sha256` for a declared task and the full inferred scope table for a legacy one. | Fail-closed. Any version but 3 parses as `null`, as does any task whose `intent` is not a normalized v2 intent; the call falls back to unresolved admission rather than executing a half-understood plan. |
-| **Session Ledger** | `3` | `CURRENT_SESSION_FORMAT_VERSION = 3`<br>`src/engine/session.ts:66` | `<stateDir>/sessions/<cwdHash>/<sessionId>/` (`meta.json`, `current.jsonl`, `tree.json`) | Append-only ledger format with UUIDv7 turn IDs, session header line, and tree graph linkage. | Automated migration via `src/domains/session/migrations/` on `/resume`. Earlier unmigratable versions rejected. |
-| **Worker Spec** | `3` | `WORKER_SPEC_VERSION = 3`<br>`src/worker/spec-contract.ts:22` | Subprocess `stdin` control plane JSON payload | Worker invocation parameters, tool surface profile, and execution bounds. | Fail-closed preflight rejection before worker activation. |
-| **Worker Runtime Descriptor** | `2` | `WORKER_RUNTIME_DESCRIPTOR_VERSION = 2`<br>`src/worker/spec-contract.ts:23` | Worker attestation descriptor payload | Attestation descriptor for worker runtime environment and hardware facts. | Attestation mismatch causes immediate process termination. |
-| **Worker Protected Artifact State** | `1` | `WORKER_PROTECTED_ARTIFACT_STATE_VERSION = 1`<br>`src/worker/spec-contract.ts:24` | Worker spec initialization snapshot | Snapshot of active protected artifact paths and validation commands passed to worker. | Worker fails closed before executing mutations. |
-| **Fleet Contract** | `1 \| 2 \| 3 \| 4 \| 5` (Current: `5`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4 \| 5`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`FLEET_DYNAMIC_STEP_VERSION = 5`<br>`src/domains/agents/fleet-contract.ts` | `.clio-coder/fleets/<name>.yaml`, `.clio-coder/fleets/<name>.yml`, or built-in recipes | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops and commit steps; v4 adds declared per-step write boundaries; v5 adds plan steps, gate steps, per-step target or profile routing, and the single-writer declaration. | Reader refuses contracts whose version features it does not support. |
-| **Execution Plan** | `4` | `version: 4` in `interface ExecutionPlan`<br>`src/domains/dispatch/execution-plan.ts:98` | Statically compiled DAG representation in dispatch memory and receipts | Statically unrolled, deterministically hashed execution plan. v4 adds bounded loop nodes, verification staleness tracking, and commit nodes. | Preflight validation rejects unsupported plan versions. |
-| **Eval Artifact** | `4` | `version: 4` in `interface EvalArtifactV4`<br>`src/domains/eval/schema/artifact.ts:51-52` | `<stateDir>/evals/<evalId>.json` | Stored eval results with suite provenance, matrix parameters, and itemized metric outcomes. Note: `EVAL_ARTIFACT_VERSION = 1` in `src/domains/eval/types.ts:2` is legacy/dead code. | Incompatible eval artifacts are rejected during `clio-coder eval report` and `compare`. |
-| **Prompt Manifest** | `2` | `PROMPT_MANIFEST_VERSION = 2`<br>`src/domains/session/prompt-manifest.ts:30` | `<stateDir>/sessions/<cwdHash>/<sessionId>/prompt-manifest.jsonl` | Per-session record of the compiled system prompt: fragment ids, relative paths, content hashes, section token estimates, and the composition hash. Version 2 is the stable-prefix-first ordering with one `# Memory` header and records `contextWindowSource` beside the window the prompt states (#249). | Additive. A record without a `version` field predates the field and reads as version 1, so a 0.3.8 manifest still parses; the version explains the single `promptRecompiled` entry a resumed session's first compile writes. |
-| **Eval Verdict Envelope** | `clio.eval.verdict.v1` | `EVAL_VERDICT_SCHEMA_V1`<br>`src/domains/eval/schema/verdict.ts:1` | Inside the Eval Artifact at `<stateDir>/evals/<evalId>.json` | Fail-closed verdict identity with ledger- and receipt-sourced performance metrics, per-scenario pass and distribution aggregates, and serving-configuration provenance (#252). One pass decision: the code grader's outcome is part of `result.pass`. | Fail-closed. `eval compare` refuses serving-configuration drift unless explicitly allowed; an artifact without a parseable verdict envelope is rejected rather than read as passing. |
-| **Behavioral Scenario & Result** | `clio.eval.scenario.v1`, `clio.eval.behavior.v1` | `EVAL_BEHAVIOR_SCENARIO_SCHEMA_V1`, `EVAL_BEHAVIOR_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral.ts:4-5` | Suite v2 task declarations; additive sibling inside the Eval Artifact | Versioned behavioral contract: bounded expected and forbidden rules across tool choice, exploration, delegation, safety comprehension, claim grounding, denied-tool recovery, completion behavior, and task correctness, with deterministic judge inputs canonicalized from transcript, tool, receipt, and grader facts (#156). References the unchanged `clio.eval.verdict.v1` identity. | Fail-closed. `unknown`, `unmeasured`, `behavioral_failure`, and `infrastructure_failure` stay distinct; a malformed, partial, contradictory, or cross-linked verdict cannot parse as a pass. Existing artifact readers are unaffected because the sibling is additive. |
-| **Behavioral Metrics Projection** | `clio.eval.behavior.metrics.v1` | `EVAL_BEHAVIOR_METRICS_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral-metrics.ts:4` | Additive role- and target/model-bound projection inside the Eval Artifact | Ten sourced metric families (correctness, safety, label violations, tool-call efficiency, unnecessary exploration, delegation quality, unsupported claims, tokens, latency, cost, and repeat variability) with coverage, min/max, p90, population variance, and standard deviation per distribution (#161). | Unmeasured observations stay typed `null` and never become zero violations. A baseline hard metric that becomes unmeasured fails the comparison closed, and `--metric` filtering cannot hide a hard failure. |
-| **Execution Envelope** | `clio.eval.execution-envelope.v1` | `EVAL_EXECUTION_ENVELOPE_SCHEMA_V1`<br>`src/domains/eval/schema/execution-envelope.ts:1` | On every new behavioral result inside the Eval Artifact | Strictly parsed binding of prompt fragment ids, versions, and content hashes, composition hash, recipe identity and content hash, target, wire model, runtime, thinking level, tool signature, autonomy, policy hashes, project-context provenance, and corpus id and version (#164). Suites declare which matrix dimensions may vary. | Fail-closed. Comparisons mark rows incomparable on any undeclared envelope drift, refuse one-sided envelopes and within-run variance, and name every prompt- or recipe-affected corpus result. |
-| **Trace Database** | `1` | `TRACE_SCHEMA_VERSION = 1`<br>`src/domains/observability/trace-store.ts:23` | `<stateDir>/trace.sqlite` (`meta` table `schema_version`) | Schema version for the 7 SQLite trace mirror tables (`runs`, `phases`, `events`, `envelopes`, `gate_results`, `agent_sessions`, `processes`). | Log warning (`[clio:trace]`), trace writing degrades without failing the parent run. |
-| **Capacity State File** | `2` | `version: 2` in `interface CapacityStateFile`<br>`src/domains/dispatch/capacity-lease.ts:40` | `<stateDir>/dispatch-admission.json` | Active capacity leases, drain status, and cross-process lock state. | Corrupted or unparseable state file causes admission to fail closed. |
-| **Protected Artifact Journal** | `1` | `version: 1` in `interface PendingProtectedArtifactRecord`<br>`src/domains/session/protected-artifact-journal.ts:22` | `<stateDir>/protected-artifact-pending/<key>/<id>.json` | Write-ahead durability records for pending protected artifacts. | Leftover records reconciled during session initialization. |
-| **Fleet Run Record** | `1` | `version: 1` in `interface FleetRunRecord`<br>`src/domains/dispatch/fleet-run.ts` | `<stateDir>/fleet-runs/<runId>.json` | Durable record of one fleet run: contract name, plan hash, static step ids and steps, `--var` values, replayed and settled step results, and the delegation plan hash a `kind: plan` step produced. Read by `fleet run --resume`. | Resume refuses a changed plan hash with a per-step diff and refuses differing `--var` values. |
-| **Durable Assignment Store** | `1` | `version: 1` in `interface AssignmentStoreFile`<br>`DurableAssignmentRecord`<br>`src/domains/dispatch/assignment-store.ts` | `<stateDir>/assignments.json` | Machine-wide logical-dispatch records: assignment id, attempt ids, terminal run id, status, optional fleet verdict owner, and—while running—`processOwner {pid, processBirthToken, acquiredAt}`. The owner is cleared on a true terminal transition. | A live sibling owner keeps the row running; a genuinely dead or legacy ownerless row is reconciled. An unsupported or unreadable store is treated as empty, and malformed records are ignored. |
-| **Checkout Writer Lease** | `1` | `version: 1` in `interface CheckoutWriterLeaseRecord`<br>`src/domains/dispatch/checkout-writer-lease.ts` | `<stateDir>/checkout-writer-leases/<key>.json` (key derived from the canonical checkout path) | Cross-process single-writer lease: checkout path, pid, process birth token, acquisition time. | A live sibling holder is refused with `checkout_writer_lease_held`; a dead owner is reclaimed; a malformed record is treated as absent. |
-| **Out-of-turn Usage Ledger** | unversioned JSONL | `OutOfTurnUsageRow`<br>`src/domains/observability/out-of-turn-usage.ts` | `<stateDir>/usage/out-of-turn.jsonl` | One row per priced `/btw` or `/handoff` call: label, session id, repo identity, timestamp, target, attributed model, provider usage. Bounded ring of `MAX_OUT_OF_TURN_USAGE_ROWS = 1000`, rewritten atomically under the state-file lock. | Unparseable rows are skipped and counted by `usage report`; the session ledger is never affected. |
-| **Library Pins** | unversioned YAML map | `readLibraryPins`<br>`src/domains/resources/library.ts` | `<configDir>/library-pins.yaml` | Typed ref (`skill:x`, `agent:y`, `prompt:p`, `fleet:z`) to `{sha256, sourceUrl}` for every resource `library add` or the Skills Hub installed. | A non-map document reads as empty; an entry whose installed file is missing is reported as available, not installed. |
-
----
-
-## 2. Integrity Verification Contracts
-
-### Receipt Integrity (Version 20)
-
-Receipt integrity authenticates that a sealed receipt matches its ledger envelope without modification. Verification reproduces the canonical JSON serialization and computes the SHA-256 digest:
-
-```typescript
-export function computeReceiptDigest(receipt: RunReceiptV15): string {
-  const canonical = serializeCanonicalReceipt(receipt);
-  return createHash("sha256").update(canonical, "utf8").digest("hex");
-}
-```
-
-Receipt verification checks:
-1. `integrity.version === 20`. A receipt sealed at a lower version is reported as retired rather than invalid: it is intact, but is not read as evidence and is never migrated.
-2. Calculated SHA-256 matches `integrity.digest`.
-3. All optional fields present in the schema (`validationGrounding`, `capabilityMismatch`, `steering`, `gate`, `fleetGate`, `council`, `plan`, `briefing`) conform to the strict v20 specification.
-
----
-
-## 3. Migration Mechanics
-
-Session migrations execute automatically when resuming a session whose `meta.json` format version is less than `CURRENT_SESSION_FORMAT_VERSION = 3`:
-
-1. **Discovery**: `src/domains/session/migrations/index.ts:runMigrations` reads the recorded `sessionFormatVersion`.
-2. **Step Execution**: Sequentially runs migration passes (e.g. `v1 -> v2`, `v2 -> v3`), transforming `current.jsonl` entries and reconstructing `tree.json` linkages.
-3. **Atomic Commit**: Staged migrations are written to temporary files, fsync'd, and atomically renamed over the original session files.
-4. **Metadata Update**: `meta.sessionFormatVersion` is updated to `3` and committed to `meta.json`.

package/docs/documentation-coverage.md

@@ -1,46 +0,0 @@
-# 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.4.0`.
-
-## Coverage Matrix
-
-| Source Area | Primary Subsystems / Modules | Owning Documentation | Status | Coverage Details & Gap Analysis |
-| :--- | :--- | :--- | :--- | :--- |
-| `src/cli/` | Command line routing, subcommands, flag parsing, exit codes, machine-readable JSON streaming | [commands-and-modes.md](commands-and-modes.md), [exit-codes-and-output.md](exit-codes-and-output.md) | `documented` | Covered by CLI reference and the dedicated exit codes and machine-readable output contract guide. |
-| `src/core/` | Invariants, constants, configuration defaults, headless permissions, tool definitions, response schema contracts | [architecture.md](architecture.md), [configuration-and-targets.md](configuration-and-targets.md), [installation-and-lifecycle.md](installation-and-lifecycle.md), [safety-model.md](safety-model.md) | `documented` | Fully documented across architecture, configuration, lifecycle, and safety model pages. |
-| `src/engine/` (Core) | Engine turn loop, prompt priming, streaming message adapters, turn execution | [architecture.md](architecture.md), [context-engine.md](context-engine.md) | `documented` | Documented across architecture and context engine guides. |
-| `src/engine/acp/` | ACP protocol server, transport adapters, tool mediators, permission forwarding, error taxonomy | [acp.md](acp.md) | `documented` | Dedicated ACP specification covering server wiring, permission mediation, timeouts, error taxonomy, and security boundaries. |
-| `src/entry/` | Application bootstrapping, CLI router, interactive loop entry point | [architecture.md](architecture.md), [installation-and-lifecycle.md](installation-and-lifecycle.md) | `documented` | Documented in architecture compilation boundaries and lifecycle guides. |
-| `src/interactive/` | TUI architecture, screens, overlays, keybindings, panels, theme tokens, width matrices, prompt pre-warm rounds and their gating, expected-cold reason stamping | [tui-design.md](tui-design.md), [commands-and-modes.md](commands-and-modes.md), [context-engine.md](context-engine.md) | `documented` | Fully documented in TUI design specification and commands reference; the pre-warm and the cache-honesty surfaces `/context` renders are in the context engine reference. |
-| `src/tools/` | 20 built-in tools across 7 planes, registry, policy engine bindings, observation envelope bounds | [tool-usage.md](tool-usage.md), [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `documented` | Comprehensive 20-tool reference with schemas, examples, and envelope size constraints. |
-| `src/utils/` | Image manipulation, photon operations, git execution utilities | [architecture.md](architecture.md), [tool-usage.md](tool-usage.md) | `documented` | Utility helpers documented within tool usage and architectural boundaries. |
-| `src/worker/` | Worker subprocess lifecycle, NDJSON transport, heartbeat timers, control lane demuxing, spec contracts | [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) | `documented` | Complete reference for NDJSON socket protocols, watchdog timers, and exit status mapping. |
-| `src/domains/agents/` | 12 built-in recipes, agent catalog, recipe schema, fleet commands, fleet contract v4 | [built-in-agents.md](built-in-agents.md), [fleet-dispatch.md](fleet-dispatch.md) | `documented` | Documented in built-in agent recipes guide and fleet dispatch architecture. |
-| `src/domains/components/` | Component scanning, snapshots, hashing, diffing | [middleware-and-components.md](middleware-and-components.md) | `documented` | Documented in active component snapshot and middleware guide. |
-| `src/domains/config/` | Configuration contracts, file watcher, keybinding definitions, setting classifiers | [configuration-and-targets.md](configuration-and-targets.md), [commands-and-modes.md](commands-and-modes.md) | `documented` | Documented in configuration targets and command/keybinding reference. |
-| `src/domains/context/` | `CLIO-CODER.md` bootstrap, codewiki generation, prompt context assembly, project rules, non-destructive working-set eviction (`age-horizon` and `structural-v1` policies, protection predicates, path index, byte-stable markers, recall by ref) | [context-engine.md](context-engine.md), [context-working-set.md](context-working-set.md) | `documented` | Context window, token accounting, and the three compaction mechanisms in the engine reference; the working-set layer has its own guide covering the vocabulary, both ledger record kinds and format v4, the marker contract, both policies with their rule order, recall semantics, and the operator surfaces. |
-| `src/domains/dispatch/` | Fleet orchestration, assignment store, batch tracker, admission, route planner, receipt integrity v16 | [fleet-dispatch.md](fleet-dispatch.md), [dispatch-architecture-rationale.md](dispatch-architecture-rationale.md), [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) | `documented` | Multi-node fleet dispatch, admission invariants, and receipt verification fully documented. |
-| `src/domains/eval/` | Suite v2 YAML schema, eval runner, `clio.eval.verdict.v1` envelope and its Suite v2 adapter, tracked metrics and scenario aggregates, serving-configuration provenance, reporters, workspace sandboxing | [eval-runner.md](eval-runner.md), [evals-internal.md](evals-internal.md) | `documented` | Product evals are documented independently from external benchmarks. The verdict envelope, `trackedMetrics` and their sources, `--trials`, and the config-drift and estimated-versus-measured refusals are in the runner reference. |
-| `src/domains/evidence/` | Evidence bundles, findings taxonomy, provenance store, failure attribution | [evidence-and-memory.md](evidence-and-memory.md) | `documented` | Documented in evidence directory structures and memory retrieval guide. |
-| `src/domains/evolution/` | Falsifiable Change Manifest JSON templates and `clio-coder evolve` self-edit gates | [evolution.md](evolution.md) | `documented` | Documented in evolution manifest reference and mutation validation rules. |
-| `src/domains/extensions/` | Extension manifest schemas, resource roots, portable share archives | [extensions-and-sharing.md](extensions-and-sharing.md) | `documented` | Documented in extensions and sharing guide. |
-| `src/domains/lifecycle/` | Platform initialization, upgrade, reset, uninstall, migrations, doctor diagnostics | [installation-and-lifecycle.md](installation-and-lifecycle.md) | `documented` | Platform directories, permissions, initialization, and diagnostic commands documented. |
-| `src/domains/memory/` | Proactive task memory, three-tier bank, two-phase policy grammar, handoffs | [proactive-memory.md](proactive-memory.md), [evidence-and-memory.md](evidence-and-memory.md) | `documented` | Proactive task bank, intervention rules, and persistence fully documented. |
-| `src/domains/middleware/` | Middleware hooks (`turn_start`, `tool_call`, `tool_result`, `turn_end`), reminders, budgets | [middleware-and-components.md](middleware-and-components.md) | `documented` | Documented in middleware hooks and active component snapshot guide. |
-| `src/domains/observability/` | Trace store (`node:sqlite` WAL mirror), metrics, cost accounting, evidence index | [trace-store.md](trace-store.md), [observability.md](observability.md) | `documented` | Database schema, rowid cursor queries, and receipt provenance documented. |
-| `src/domains/prompts/` | Prompt compiler, fragment loaders, static cache stability, memory intervention injection | [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `documented` | Documented in prompt envelope and tool delivery guide. |
-| `src/domains/providers/` | Runtime adapters, capability probes, model catalog and its per-family `measuredUnder` provenance, canonical endpoint keys and per-endpoint request-slot capacity, thinking control, ALCF OAuth | [configuration-and-targets.md](configuration-and-targets.md), [model-catalog.md](model-catalog.md), [provider-adapter-cookbook.md](provider-adapter-cookbook.md), [alcf-provider.md](alcf-provider.md) | `documented` | Complete provider adapter contracts, model catalogs, and ALCF Globus targets documented. |
-| `src/domains/resources/` | Skill package discovery, marketplace index resolution, prompt resources | [skills-marketplace.md](skills-marketplace.md), [extensions-and-sharing.md](extensions-and-sharing.md) | `documented` | Skills marketplace, publishing flows, and resource managers documented. |
-| `src/domains/safety/` | Policy engine, action classifiers, damage-control rules, path policies, finish contract, audit log | [safety-model.md](safety-model.md), [scientific-validation.md](scientific-validation.md) | `documented` | Policy evaluation order, 10-step sequence, write containment, and finish contract documented. |
-| `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.4.0. |
-
-## Cross-Cutting Reference Guides
-
-In addition to source subsystem mappings, the documentation set includes cross-cutting contracts:
-
-1. [artifact-versions.md](artifact-versions.md): Canonical version registry and migration contract for all 9 serialized artifact schemas across Clio Coder.
-2. [glossary.md](glossary.md): Formal definitions of 45 core architectural concepts mapped to their TypeScript types in `src/`.
-3. [troubleshooting.md](troubleshooting.md): Comprehensive diagnostic and remediation guide keyed by exact user-facing error strings.

package/docs/documentation-guide.md

@@ -1,167 +0,0 @@
-# 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.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.
-
----
-
-## Source-first documentation rule
-
-Before changing public docs, inspect the relevant implementation:
-
-1. `git log --oneline -- <area>` for recent intent and release context.
-2. `src/**` for current behavior.
-3. `tests/**` for executable contracts and edge cases.
-4. `README.md`, `CHANGELOG.md`, and `docs/*.md` for existing public wording.
-
-Classify claims clearly:
-
-| Claim class | How to word it |
-| --- | --- |
-| Shipped and tested | State directly and link to source/tests. |
-| Implemented but experimental | Say alpha/experimental and name sharp edges. |
-| Typed contract exists, default runtime is inert | Say the schema exists but no public loader/rules are active. |
-| Planned/future | Put in roadmap language; do not present as available behavior. |
-
----
-
-## Documentation map
-
-| Guide | Primary source references | What it should cover |
-| --- | --- | --- |
-| [README.md](../README.md) | `CHANGELOG.md`, package metadata, release receipts | Product overview, install, first run, alpha framing, and release status. |
-| [docs/README.md](README.md) | This docs directory | Documentation hub. |
-| [commands-and-modes.md](commands-and-modes.md) | `src/cli/index.ts`, `src/cli/args.ts`, `src/interactive/slash-commands.ts`, `src/domains/dispatch/**` | CLI commands, headless run flags (`--session`, `--continue`, `--json-events`), session continuity, `--json` wire projection promise, slash commands, keybindings, live steering. |
-| [context-engine.md](context-engine.md) | `src/domains/context/**`, `src/domains/session/context-accounting.ts`, `src/domains/session/context-ledger.ts`, `src/domains/session/compaction/` | Context window resolution, per-model probe capabilities, token accounting, snapshots, the three compaction mechanisms, model-driven `clio-coder context init`, format v4 session enforcement. |
-| [context-working-set.md](context-working-set.md) | `src/domains/context/working-set/**`, `src/domains/session/entries.ts`, `src/interactive/turn-context.ts` | Working-set vocabulary, eviction as a projection, the `contextEviction` / `contextRecall` records, the marker contract, the `age-horizon` and `structural-v1` policies, recall semantics, and the operator surfaces. |
-| [architecture.md](architecture.md) | `tests/boundaries/check-boundaries.ts`, `src/core/domain-loader.ts`, `src/engine/**`, `src/worker/**` | Source layout, 5 enforced boundary rules (dependency direction vs import form), runtime flow mermaid diagram, event/audit model, detect-and-rollback write boundaries. |
-| [dispatch-architecture-rationale.md](dispatch-architecture-rationale.md) | `src/domains/dispatch/**`, `tests/boundaries/check-boundaries.ts` | Design rationale, not behavior: invariants that cross the seams a dispatch split would use, what any future split must preserve, the one dispatch→eval import, and the closed barrel-import decision. |
-| [configuration-and-targets.md](configuration-and-targets.md) | `src/core/defaults.ts`, `src/core/config.ts`, `src/domains/providers/**`, `src/cli/configure.ts`, `src/cli/targets.ts`, `src/cli/models.ts`, `src/cli/auth.ts` | TargetDescriptor, contextWindowProvenance (`configured`, `discovered`, `catalog`, `runtime-default`), settings.yaml, strict validation, saved defaults vs live routing. |
-| [safety-model.md](safety-model.md) | `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/policy.ts`, `src/tools/verify/**`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts` | Operating posture, `resolveEffectiveAutonomy` / `resolveBaselineAutonomy`, detect-and-rollback write boundaries, approval axes, damage control, typed validation. |
-| [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `src/domains/prompts/compiler.ts`, `src/interactive/chat-loop.ts`, `src/core/tool-names.ts`, `src/tools/registry.ts`, `src/tools/observation.ts`, `src/tools/agent-tools.ts` | Prompt envelope reuse, canonical tool delivery via single `agent-tools.ts` adapter, seven-plane tool surface, observation envelope, strict `ToolName` keying. |
-| [tool-usage.md](tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 20 worker tools: parameters, typical payloads, `prepareArguments` normalizers, and error examples. |
-| [provider-adapter-cookbook.md](provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
-| [alcf-provider.md](alcf-provider.md) | `src/domains/providers/runtimes/cloud/alcf.ts`, `src/engine/alcf-oauth.ts` | Globus PKCE OAuth, openAuthStorage(), Sophia vLLM, Metis API, chatTemplateKwargsUnsupported. |
-| [environment-variables.md](environment-variables.md) | `src/core/guardrails.ts`, `src/core/xdg.ts`, `src/domains/providers/knowledge-base-path.ts` | Comprehensive env var matrix: guardrail overrides, directory layout (CLIO_CODER_HOME), debug toggles, and internal plumbing. |
-| [built-in-agents.md](built-in-agents.md) | `src/domains/agents/**`, `src/domains/agents/builtins/*.md`, `src/domains/dispatch/**` | Builtin agent recipes, discovery roots, frontmatter schema, fleet contract shadowing (`.clio-coder/fleets/<name>.md`), active route automation. |
-| [fleet-dispatch.md](fleet-dispatch.md) | `src/domains/dispatch/**` | Multi-node SSH dispatch: process-safe admission, capacity leases, Contract v4 write boundaries (detect-and-rollback), bounded check/repair loops (`loop_bound_exhausted`), deterministic code steps, attestation, receipts v16. |
-| [capacity-and-scheduling.md](capacity-and-scheduling.md) | `src/domains/scheduling/**`, `src/domains/dispatch/capacity-lease.ts`, `src/domains/dispatch/reservation-store.ts` | Multi-process capacity leases (`dispatch-admission.json`), heartbeat TTLs, cross-process transaction locks (`dispatch-admission.json.lock`), and cluster drain controls. |
-| [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) | `src/worker/**` | NDJSON parent-child socket protocols, control/bulk lane demuxing, watchdog timers, worker attestation (13 protocol fields), permission parking, exit codes. |
-| [fleet-demo-runbook.md](fleet-demo-runbook.md) | `src/domains/dispatch/**` | Multi-node fleet demo: SSH setup, C++ build/repair workflow, reviewer gates, receipt verification v16. |
-| [session-lifecycle.md](session-lifecycle.md) | `src/engine/session.ts`, `src/domains/session/**` | Session lifecycle, on-disk ledger format v4 (`current.jsonl`), tree branching (`tree.json`), active-path lineage selection, `/fork`, `/resume`, checkpoints, and write-ahead protected-artifact journal. |
-| [acp.md](acp.md) | `src/engine/acp/**`, `src/cli/acp.ts` | Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permission handling, timeout bounds, and error taxonomy. |
-| [artifact-versions.md](artifact-versions.md) | `src/domains/dispatch/receipt-integrity.ts`, `src/engine/session.ts`, `src/worker/spec-contract.ts`, `src/domains/agents/fleet-contract.ts`, `src/domains/eval/schema/`, `src/domains/observability/trace-store.ts` | Version registry and migration policies for all 9 serialized artifact schemas across Clio Coder. |
-| [exit-codes-and-output.md](exit-codes-and-output.md) | `src/cli/**`, `src/entry/**` | Global process exit codes (0, 1, 2, 3), `--help` standard on stdout, machine-readable JSON streaming (`--json`, `--json-events`), and headless stdout deliverable contracts. |
-| [troubleshooting.md](troubleshooting.md) | `src/core/**`, `src/cli/**`, `src/domains/**` | Actionable error remediation and diagnostics keyed by exact user-facing messages. |
-| [glossary.md](glossary.md) | `src/domains/dispatch/types.ts`, `src/tools/**`, `src/domains/agents/**`, `src/core/**` | Canonical definitions of 45 core architectural concepts mapped to `src/` types. |
-| [documentation-coverage.md](documentation-coverage.md) | `src/**` | Complete source-to-documentation mapping matrix and subsystem coverage status. |
-| [tui-design.md](tui-design.md) | `src/interactive/theme/tokens.ts`, `src/interactive/theme/glyphs.ts` | TUI color system, glyph vocabulary (`contextReserve`), structural layouts, state choreography, code ink. |
-| [installation-and-lifecycle.md](installation-and-lifecycle.md) | `src/cli/paths.ts`, `src/cli/doctor.ts`, `src/cli/uninstall.ts`, `src/cli/removal.ts` | Installation, upgrade, reset, uninstallation, launcher ownership and what `--remove-binary` will and will not remove, partial-failure behavior, configuration folders (`credentials.yaml` `0o600`), and permissions. |
-| [release-cut-checklist.md](release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/pack-install.test.ts`, `benchmarks/internal/`, `package.json` | Ordered release-cut steps with an explicit authorization boundary: everything external or irreversible is marked not run and needs an operator decision. |
-| [observability.md](observability.md) | `src/domains/observability/**`, `src/interactive/view/**`, `src/domains/dispatch/**`, `src/core/bus-events.ts` | `/view` artifact browsing, receipt verification, worker diagnostics, event routing, and cost snapshots. |
-| [evidence-and-memory.md](evidence-and-memory.md) | `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, `src/cli/memory.ts` | Evidence corpus layout, findings, memory lifecycle and prompt injection. |
-| [proactive-memory.md](proactive-memory.md) | `src/domains/memory/**` | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying. |
-| [trace-store.md](trace-store.md) | `src/cli/trace.ts`, `src/domains/observability/trace-store.ts` | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, 6 `clio-coder trace` subcommands (`runs`, `phases`, `tail`, `procs`, read-only `sql` SELECT, `ui`). |
-| [eval-runner.md](eval-runner.md) | `src/domains/eval/**`, `src/cli/eval.ts` | Local YAML eval tasks, dual token accountings (`tokens.*` wire vs `receiptUsage.*` journal), fail-closed null totals, EvalArtifactV4 format, `verify.measure` task outcome recording. |
-| [evals-internal.md](evals-internal.md) | `src/domains/eval/**` | Private context index determinism and target smoke matrices. External model benchmarks are documented under `benchmarks/`. |
-| [extensions-and-sharing.md](extensions-and-sharing.md) | `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, `src/cli/share.ts` | Prompt and skill resources, extension manifests, portable share archives. |
-| [skills-marketplace.md](skills-marketplace.md) | `src/interactive/overlays/skills-hub.ts`, `src/domains/resources/skills/marketplace.ts` | Skills Hub marketplace discovery through the install resolver, empty state, install actions, publishing flow. |
-| [model-catalog.md](model-catalog.md) | `src/domains/providers/catalog.ts`, `src/domains/providers/models/**`, `src/domains/providers/probe/**`, `src/domains/providers/model-capabilities.ts` | Model catalog, live probes (`--offline` toggle), exact-id selector `probeCapabilitiesForModel`, field-note promotion. |
-| [middleware-and-components.md](middleware-and-components.md) | `src/domains/components/**`, `src/domains/middleware/**`, `src/cli/components.ts` | Active component snapshots, phase-aware middleware hook budgets (`DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS`). |
-| [scientific-validation.md](scientific-validation.md) | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract.ts` | Advisory validation-contract patterns for scientific artifacts and HPC assumptions. |
-| [evolution.md](evolution.md) | `src/domains/evolution/**`, `src/cli/evolve.ts` | Falsifiable Change Manifest JSON templates, evidence-linked validation, and `clio-coder evolve`. |
-| [config-knobs-audit.md](config-knobs-audit.md) | `src/cli/config.ts` | Point-in-time inventory of legacy environment variables (Historical Appendix). |
-
----
-
-## Style conventions
-
-### Alpha framing
-
-Use direct, honest language:
-
-- "experimental community alpha"
-- "source-build path"
-- "current runtime is conservative/inert"
-- "advisory contract"
-- "planned/future milestone"
-
-Avoid phrases that imply managed production stability, full plugin maturity, or automatic scientific validation when the current code does not provide it.
-
-### Markdown structure
-
-- Prefer short sections with tables for command and schema references.
-- Use fenced examples that can be copied.
-- Keep links relative and repository-portable; do not use absolute `file:///home/...` links.
-- Mention source file paths in backticks instead of editor-specific absolute URLs.
-
-### GitHub alerts
-
-Use alerts sparingly:
-
-> [!NOTE]
-> Context or caveats that prevent misinterpretation.
-
-> [!WARNING]
-> Sharp edges, alpha limitations, or behavior that can surprise contributors.
-
-> [!CAUTION]
-> Safety, data loss, or security-sensitive constraints.
-
----
-
-## Blueprint Coverage & Format Strategy
-
-Clio Coder maintains two complementary documentation formats:
-
-1. **Markdown Documents (`docs/*.md`)**: The single canonical reference for coding agents, developers, and maintainers. They optimize for retrievability, exact enumerations, schema tables, typed TypeScript contracts, and source citations (`src/...:line`).
-2. **Interactive HTML Blueprints (`docs/html/*.html`)**: Visual reference cards and client-side simulators designed for human operators exploring dynamic behaviors (such as safety rule evaluation, token compaction calculation, YAML target validation, and prompt structure).
-
-### Blueprint Creation Policy
-
-Not every markdown document earns a standalone interactive HTML blueprint. Reference specifications—such as `artifact-versions.md`, `exit-codes-and-output.md`, `glossary.md`, `troubleshooting.md`, `session-lifecycle.md`, `acp.md`, `capacity-and-scheduling.md`, and `documentation-coverage.md`—are authoritative tabular contracts and state machine specifications. Building client-side JavaScript simulators for these documents would duplicate runtime validation logic and introduce synchronization hazards across releases. These pages are therefore linked directly from `docs/html/index.html` as Markdown Reference Specifications with explicit visual distinction from interactive simulator blueprints.
-
----
-
-## Update checklist
-
-When a feature changes:
-
-1. Identify the source owner (`src/cli`, `src/interactive`, `src/tools`, or a domain).
-2. Check whether public CLI help changed.
-3. Update the mapped guide in the same PR.
-4. If behavior affects safety, sessions, receipts, prompts, targets, or dispatch, update both README-level user docs and the deeper guide.
-5. Run a lightweight link check for changed Markdown.
-6. For release docs, verify version badges/sections match `package.json` and `CHANGELOG.md`.
-
-Suggested local link check:
-
-```bash
-python3 - <<'PY'
-import pathlib, re
-for md in list(pathlib.Path('docs').glob('*.md')) + [pathlib.Path('README.md')]:
-    text = md.read_text()
-    for m in re.finditer(r'\[[^\]]+\]\(([^)]+)\)', text):
-        link = m.group(1)
-        if link.startswith(('http://', 'https://', 'mailto:', '#')):
-            continue
-        target = link.split('#')[0]
-        if target and not (md.parent / target).exists():
-            line = text.count('\n', 0, m.start()) + 1
-            print(f'{md}:{line}: missing {link}')
-PY
-```
-
----
-
-## Community documentation priorities
-
-Clio users tend to be early adopters running real repositories, local models, and scientific/HPC code. Good docs should therefore prioritize:
-
-- reproducible first-run and target configuration;
-- local model/runtime field notes with exact versions and serving settings;
-- safety receipts and redaction guidance for issue reports;
-- small examples for project-local `CLIO-CODER.md`, `.clio-coder/safety.yaml`, prompts, skills, and agents;
-- clear labels for experimental surfaces such as middleware and scientific validation contracts.

package/docs/time-conventions.md

@@ -1,101 +0,0 @@
-# Time and Clock Conventions
-
-This document defines the canonical time and clock conventions for `clio-coder`. These policies establish consistent rules for measuring durations, recording instants, converting timezones, and managing concurrency across the codebase.
-
-This policy is promoted from Section 10 of the repository time audit conducted on 2026-08-15.
-
----
-
-## 1. Which Clock for What Purpose
-
-### Monotonic clocks for durations
-
-All durations must be measured using `performance.now()` without exception. This rule applies to latency measurements, elapsed run times, time-to-first-token (TTFT), execution budgets, timeouts, stall watchdogs, retry backoff intervals, and rendering metrics.
-
-Whenever a value answers the question "how long did this take" or "how long until", it must originate from the monotonic clock. Monotonic clocks are unaffected by Network Time Protocol (NTP) adjustments, system suspend or resume events, and Daylight Saving Time (DST) transitions.
-
-### Wall clocks for anchored instants
-
-Wall clock reads via `Date.now()` or `new Date()` are reserved exclusively for anchoring instants that a human operator or an external machine will inspect. These include timestamps such as `startedAt`, `endedAt`, `createdAt`, and `expiresAt`. Wall clocks must never be used to measure durations or elapsed intervals.
-
-### Combined anchor and span pattern
-
-When both an anchor instant and a duration are required, code must follow the pattern established in `src/domains/dispatch/code-step.ts:291-306`:
-
-```ts
-const startedAtMs = Date.now();                      // wall anchor, for the record
-const clock = process.hrtime.bigint();               // monotonic span
-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 wall clock anchors the starting instant for human correlation. The monotonic clock measures the elapsed span. The ending timestamp `endedAt` is derived by adding the monotonic span to the initial wall anchor. This derivation guarantees that `endedAt - startedAt === durationMs` remains true regardless of any wall-clock adjustments that occur during execution.
-
-### Injectable clock seams
-
-Every module that reads a clock must accept an optional injectable clock interface in its configuration or options, defaulting to the system clock. Injectable clock seams allow test suites to run deterministically without relying on real-time passage or introducing timing races.
-
-### Cross-host timestamp boundaries
-
-A timestamp produced on one host must never be compared directly against a clock read on another host. Systems must receive-stamp incoming events upon arrival on the local host, maintain an explicit clock offset, or order events using sequence numbers rather than timestamps. Code must never subtract timestamps across host boundaries.
-
-### Sequence numbers over timestamps for ordering
-
-When ordering operations under concurrency, code must prefer monotonic sequence numbers over timestamps. Components such as the agent ledger (`src/domains/session/agent-ledger-store.ts`) and the execution scheduler (`src/domains/dispatch/execution-scheduler.ts`) rely on sequence numbers to remain correct by construction. Timestamps are reserved for human display and coarse windowing. Any attribution logic that relies on timestamps must report ambiguity explicitly rather than returning null.
-
----
-
-## 2. Where UTC Is Converted
-
-### Storage, transport, and comparisons in UTC
-
-The system stores UTC, transports UTC, and compares UTC. Conversion to local time occurs once, strictly at the render call site.
-
-1. On disk and across the wire, timestamps are always represented as canonical ISO-8601 strings produced by `toISOString()`. Every store validates timestamps upon reading using the exact round-trip check from `src/domains/dispatch/capacity-lease.ts:80-84`.
-2. In memory, instants are stored as epoch milliseconds or canonical ISO-8601 strings. Localized or pre-formatted date strings must not be held in memory models.
-3. At the user interface render boundary, UTC instants are converted to the operator's local timezone.
-4. Whenever a converted local timestamp is displayed, the underlying canonical UTC instant must remain accessible. For example, a table row displays local time while the associated detail pane preserves the exact ISO-8601 string so that the two representations can always be reconciled.
-
----
-
-## 3. Formatter Policy
-
-All operator-facing time formatting is consolidated in `src/interactive/format-time.ts`. The module provides three standardized formatting functions:
-
-| Function | Output Format | Timezone and Locale Frame | Purpose |
-|---|---|---|---|
-| `clockLocal(instant)` | `HH:MM:SS` | Operator local timezone using `en-GB` locale with 24-hour cycle (`hourCycle: "h23"`) | Renders time-of-day for logs, tree selectors, and message pickers |
-| `dateLocal(instant)` | `YYYY-MM-DD` | Operator local timezone using `en-CA` locale | Renders calendar dates for session selectors, welcome dashboards, and export filenames |
-| `relative(instant, now)` | `"3m ago"` (falls back to `dateLocal`) | Operator local timezone | Renders relative recency ladders with automatic fallback to calendar dates |
-
-Both `Intl.DateTimeFormat` instances are constructed at module scope. The module automatically rebuilds formatters if `process.env.TZ` changes during runtime.
-
-Machine surfaces such as filenames, IDs, structured log fields, and receipt records bypass the formatting module entirely and use canonical `toISOString()`.
-
----
-
-## 4. Test Determinism and Receipt Integrity
-
-### Test clock harness
-
-Test suites must rely on the steppable clock helper in `tests/harness/clock.ts`. Every factory function that reads a clock must default to the harness clock in test environments. Real-time passage in tests is opt-in and requires explicit configuration.
-
-### Receipt integrity digests
-
-Persisted fields such as `startedAt` and `endedAt` participate in receipt integrity digests (`src/domains/dispatch/receipt-integrity.ts`). Any timestamp normalization, derivation, or adjustment must occur before the receipt digest is sealed. Timestamps must never be rewritten after receipt creation.
-
----
-
-## 5. State-Root and Audit-Filename Assumptions
-
-### Host-scoped state root and coordination
-
-The state root directory is host-scoped. Durable locks and capacity leases carry a metadata payload containing `{host, pid, birthToken}`.
-
-A coordination record created by a foreign host is never adjudicated against the local process table. This follows the host-scoping pattern implemented in `src/tools/compete-worktrees.ts:207-215`, `src/domains/dispatch/orphan-recovery.ts:140-149`, and `src/core/run-identity.ts:23`.
-
-### Audit filename semantics
-
-The date in an audit log filename (such as `audit-YYYY-MM-DD.jsonl`) is a human-facing label indicating the local calendar date on which the audit log was opened. It does not represent machine-read data. All individual audit event records contained within the file store canonical UTC ISO-8601 timestamps.