@iowarp/clio-coder 0.4.3 → 0.4.5

package/dist/{with-panes-4GCGSL7J.js → with-panes-OFTNAR4Y.js}

@@ -1,41 +1,42 @@
 import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
 import {
   createPanesRuntime
-} from "./chunk-3EBYEESD.js";
-import "./chunk-35MSIRKH.js";
-import "./chunk-VIA6RFQZ.js";
+} from "./chunk-A46ILRS2.js";
+import "./chunk-QUIJZSDW.js";
 import {
   createMuxDomainModule,
   createYaziSession,
   resolveYaziBinaries,
   watchViewerCommand
-} from "./chunk-KKOJXO6R.js";
+} from "./chunk-SRZOW5L2.js";
 import {
   ensureYaziProfile,
   yaziProfileDir
-} from "./chunk-3M6DQK6S.js";
-import "./chunk-LCGCVYZ4.js";
-import "./chunk-BMS5RKQY.js";
+} from "./chunk-T334FW2H.js";
+import "./chunk-UQIVHSE4.js";
+import "./chunk-LQTKDAUO.js";
+import "./chunk-JABWPKFY.js";
+import "./chunk-XCUDZQLX.js";
+import "./chunk-K2BLQC5E.js";
 import {
   sanitizeCallTargetText
-} from "./chunk-NEDJ26B5.js";
-import "./chunk-QSNYB6ZV.js";
-import "./chunk-QDC3K2U3.js";
-import "./chunk-D7E7WCDF.js";
-import "./chunk-BTK3SSSK.js";
+} from "./chunk-2GPGAE5W.js";
+import "./chunk-DVNAPPXU.js";
+import "./chunk-KMF54VH3.js";
+import "./chunk-EFSEIZE6.js";
 import {
   BusChannels
-} from "./chunk-F4EKGO4N.js";
-import "./chunk-IWHMRKLL.js";
+} from "./chunk-HL26ADLH.js";
+import "./chunk-E3LEPLQ2.js";
 import {
   clioCacheDir,
   clioConfigDir,
   clioDataDir,
   clioStateDir
-} from "./chunk-BYP5D4HI.js";
+} from "./chunk-CTTI7G3T.js";
 import {
   init_esm_shims
-} from "./chunk-3R73A4XB.js";
+} from "./chunk-ECBHH7LU.js";
 
 // src/entry/with-panes.ts
 init_esm_shims();
@@ -215,7 +216,8 @@ function createWatchPaneController(deps) {
       return false;
     }
   };
-  const openPane = () => deps.mux.openUtilityPane({
+  const openPane = (onFailure) => deps.mux.openUtilityPane({
+    ...onFailure ? { onFailure } : {},
     argv: command(selectionPath, dirs),
     cwd: deps.getCwd(),
     label: "watch",
@@ -243,9 +245,21 @@ function createWatchPaneController(deps) {
       const scanned = await adoptExistingPane();
       if (!scanned) await adoptExistingPane();
       if (paneId !== null) return { status: "watching", runId, paneId, opened: false };
-      const opened = await openPane();
+      let reason = "cannot open the watch pane: no failure reason was supplied by the pane host; check /panes before trying again";
+      const opened = await openPane((failure) => {
+        if (failure.source === "local") {
+          reason = `cannot open the watch pane locally: ${failure.message}`;
+        } else {
+          const details = [
+            `kind=${failure.kind}`,
+            ...failure.wireCode === null ? [] : [`code=${failure.wireCode}`],
+            ...failure.method === null ? [] : [`method=${failure.method}`]
+          ];
+          reason = `cannot open the watch pane (${details.join(", ")}): ${failure.message || "no failure message was supplied by the pane host"}`;
+        }
+      });
       if (opened === null) {
-        return { status: "unavailable", reason: "the pane host refused to open the watch pane" };
+        return { status: "unavailable", reason };
       }
       paneId = opened.paneId;
       return { status: "watching", runId, paneId, opened: true };
@@ -611,4 +625,4 @@ export {
   createWatchPaneController,
   createYaziBridge
 };
-//# sourceMappingURL=with-panes-4GCGSL7J.js.map
+//# sourceMappingURL=with-panes-OFTNAR4Y.js.map

package/dist/worker/entry.js

@@ -17,25 +17,19 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-GI7YYQ3F.js";
+} from "../chunk-U2JOLB7O.js";
+import "../chunk-JABWPKFY.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-2UG5F4C5.js";
-import {
-  CONFIRMED_SCOPE,
-  READONLY_SCOPE,
-  WORKSPACE_SCOPE,
-  isSubset
-} from "../chunk-5PSMVOLM.js";
-import "../chunk-BMS5RKQY.js";
-import "../chunk-2WZ546HR.js";
-import "../chunk-MCEPRMZW.js";
-import "../chunk-ZDN3Y73Y.js";
-import "../chunk-64I3JVYM.js";
-import "../chunk-VG7TBQIY.js";
-import "../chunk-IUE3Y34X.js";
+} from "../chunk-DRD2A54W.js";
+import "../chunk-BBV5TKE6.js";
+import "../chunk-GXCCHKN6.js";
+import "../chunk-PWWSIB2A.js";
+import "../chunk-KTFSFCVN.js";
+import "../chunk-XCUDZQLX.js";
+import "../chunk-K2BLQC5E.js";
 import {
   DEFAULT_ESCALATION_FALLBACK,
   DEFAULT_ESCALATION_TIMEOUT_MS,
@@ -52,41 +46,52 @@ import {
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-PAJQJ7BS.js";
-import "../chunk-EKCHAPYA.js";
-import "../chunk-L47TF46W.js";
+} from "../chunk-TZ7MFRG4.js";
 import {
+  CONFIRMED_SCOPE,
+  READONLY_SCOPE,
+  WORKSPACE_SCOPE,
   createLoopState,
+  isSubset,
   observe
-} from "../chunk-RSJ25QSL.js";
-import {
-  createSafetyPolicyEngine
-} from "../chunk-XIVNBFZS.js";
+} from "../chunk-KF6GFW6O.js";
+import "../chunk-K2HL3GBL.js";
+import "../chunk-7HBHHVCK.js";
 import {
   describeCallTarget
-} from "../chunk-NEDJ26B5.js";
-import "../chunk-42FMPA75.js";
-import "../chunk-H7IXIC72.js";
-import "../chunk-7DICMOS6.js";
-import "../chunk-OQE5J4C6.js";
-import "../chunk-HHV2GANA.js";
+} from "../chunk-2GPGAE5W.js";
+import "../chunk-SL2RDHKO.js";
+import "../chunk-YGDMBK7O.js";
+import "../chunk-V552WL53.js";
+import "../chunk-RLTT5GVY.js";
+import "../chunk-KECNXMDE.js";
+import {
+  createSafetyPolicyEngine
+} from "../chunk-4SVIVOMC.js";
+import "../chunk-NTK3WTHM.js";
+import "../chunk-WXA2CFJO.js";
+import "../chunk-CBSKDFWL.js";
+import "../chunk-LY4N4TTL.js";
 import {
   RESULT_CONTRACT_REPAIR_LIMIT,
-  classify,
   parseWorkerResultContract,
   resultContractRepairMessages,
   validateResultContract
-} from "../chunk-B4OAX3SI.js";
+} from "../chunk-OQM5IVJY.js";
+import {
+  classify
+} from "../chunk-LUL5Z66S.js";
 import {
   protectedArtifactMutationBlockReason
-} from "../chunk-I7ZPNEJM.js";
-import "../chunk-GYV6VZOC.js";
-import "../chunk-UL3WSD3F.js";
-import "../chunk-JDAY6FIL.js";
-import "../chunk-OZNBF4L3.js";
-import "../chunk-ECH6PKUQ.js";
-import "../chunk-6XLNIQDB.js";
-import "../chunk-5B2AEOW5.js";
+} from "../chunk-M6TAYK66.js";
+import "../chunk-KQ6IDQIB.js";
+import "../chunk-L4N3DWNW.js";
+import "../chunk-WJIMKGD6.js";
+import "../chunk-MDU3C27C.js";
+import "../chunk-R2P2U3ZS.js";
+import "../chunk-NTTS3O53.js";
+import "../chunk-M4KFUXS7.js";
+import "../chunk-GH5ZR6JP.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
@@ -101,17 +106,17 @@ import {
   toolSignatureOf,
   withinFrameBudget,
   workerSpecDigest
-} from "../chunk-VAVR4IJY.js";
-import "../chunk-QSNYB6ZV.js";
+} from "../chunk-VQD7NH7Z.js";
+import "../chunk-O3VV6IVK.js";
 import {
   DEFAULT_AUTONOMY_LEVEL,
   agentSkillToolPolicy
-} from "../chunk-JGRC33J2.js";
-import "../chunk-4BJ5BYCE.js";
+} from "../chunk-5ZMXGW7P.js";
+import "../chunk-B6UM3OZC.js";
+import "../chunk-MYI32N4R.js";
 import {
   ToolNames
-} from "../chunk-K6BSR66V.js";
-import "../chunk-QDC3K2U3.js";
+} from "../chunk-EHOSNVVM.js";
 import {
   FileKnowledgeBase,
   applyModelCapabilityPatch,
@@ -122,68 +127,69 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-XPWWI35G.js";
-import "../chunk-CFGTUFWB.js";
-import "../chunk-NZMNUPZZ.js";
-import "../chunk-2JH2WHGE.js";
-import "../chunk-HAXOFFRH.js";
-import "../chunk-R346GLFC.js";
-import "../chunk-KXDSS5WJ.js";
+} from "../chunk-TEG3RYVZ.js";
+import "../chunk-MCJKEGHO.js";
+import "../chunk-77CZRFTE.js";
+import "../chunk-J2FYEQ5L.js";
 import {
   readSettings,
   validateSettingsFile
-} from "../chunk-GHS5EBTQ.js";
-import "../chunk-D7E7WCDF.js";
-import "../chunk-BTK3SSSK.js";
-import "../chunk-NMJXSHBJ.js";
-import "../chunk-PMZVFWSR.js";
-import "../chunk-F4EKGO4N.js";
-import "../chunk-65DEGPJ6.js";
+} from "../chunk-FKIOX6DS.js";
+import "../chunk-DVNAPPXU.js";
+import "../chunk-5CY4Q6QI.js";
+import "../chunk-FQOOGXBH.js";
+import "../chunk-UHW5V7HC.js";
+import "../chunk-KMF54VH3.js";
+import "../chunk-5A6XR3RJ.js";
+import "../chunk-EFSEIZE6.js";
+import "../chunk-B5ZTR6KZ.js";
+import "../chunk-HL26ADLH.js";
+import "../chunk-3A3CUMKA.js";
 import {
   readClioVersion
-} from "../chunk-IWHMRKLL.js";
+} from "../chunk-E3LEPLQ2.js";
 import {
   registerBuiltinRuntimes
-} from "../chunk-VW6DOEDG.js";
-import "../chunk-UXCU4E3T.js";
-import "../chunk-LL4KHSZI.js";
-import "../chunk-JSC3U7TI.js";
+} from "../chunk-ICO4TQ2F.js";
+import "../chunk-SE4ZKILO.js";
+import "../chunk-U2MSJ57E.js";
 import {
   configureGuardrails,
   guardrailValuesFromSettings,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
-} from "../chunk-S66XZJOF.js";
+} from "../chunk-C27U2TYG.js";
+import "../chunk-GJ24ODAX.js";
 import {
   setGitCommitAttributionEnabled,
   withManagedGitCommitAttributionEnvironment
-} from "../chunk-JIEGK6UF.js";
-import "../chunk-EBY63B7G.js";
+} from "../chunk-LTR5QCLS.js";
+import "../chunk-6EXUUOSN.js";
 import {
   AI_AGENT_NAME
-} from "../chunk-6EJMN2Y3.js";
-import "../chunk-LLDJM5XK.js";
-import "../chunk-ID64D7PE.js";
-import "../chunk-336NSSKI.js";
-import "../chunk-IKCO5N3L.js";
-import "../chunk-3I7MS7N2.js";
-import "../chunk-APJ265NV.js";
-import "../chunk-WEPFGWHJ.js";
+} from "../chunk-ZTNFYMIO.js";
+import "../chunk-HHVJNVUJ.js";
+import "../chunk-HXHFDHB6.js";
+import "../chunk-VNBICSS2.js";
+import "../chunk-2QPI3TR3.js";
+import "../chunk-TK2BMCBZ.js";
+import "../chunk-B5GGDIHT.js";
+import "../chunk-ZZFWWYLX.js";
 import {
   getRuntimeRegistry
-} from "../chunk-NUGM5KR6.js";
-import "../chunk-5OIVVPHF.js";
+} from "../chunk-SRCEQKQS.js";
+import "../chunk-TN5FW4XY.js";
 import {
   registerFauxFromEnv
-} from "../chunk-YPC6ZR5L.js";
-import "../chunk-YXLYO42X.js";
+} from "../chunk-5CMARGPF.js";
+import "../chunk-DXVMLM3Z.js";
 import {
   deleteInjectedCompileCacheFrom
-} from "../chunk-2LEAKD4C.js";
-import "../chunk-BYP5D4HI.js";
+} from "../chunk-CKK25WN3.js";
+import "../chunk-CTTI7G3T.js";
 import {
   init_esm_shims
-} from "../chunk-3R73A4XB.js";
+} from "../chunk-ECBHH7LU.js";
 
 // src/worker/entry.ts
 init_esm_shims();
@@ -264,7 +270,10 @@ function createWorkerSafety(options = {}) {
     },
     scopes: { readonly: READONLY_SCOPE, workspace: WORKSPACE_SCOPE, confirmed: CONFIRMED_SCOPE },
     isSubset,
-    policy: { metadata: (posture) => policyEngine.metadata(posture) },
+    policy: {
+      metadata: (posture) => policyEngine.metadata(posture),
+      allowsObservationPath: (path2) => policyEngine.evaluate({ tool: "read", args: { path: path2 } }).reasonCode !== "path-policy:zeroAccessPaths"
+    },
     audit: { recordCount: () => 0 }
   };
 }
@@ -566,6 +575,7 @@ function createClaudeWorkerBudgetGate(budget, onBoundary, onHardCap, deliveryToo
   let admitted = 0;
   let locked = false;
   const phaseDecision = (canonicalToolName) => {
+    if (budget.mode === "advisory") return { kind: "allow" };
     const reserveAdmits = isReserveAdmittedTool(canonicalToolName, deliveryTools);
     if (locked || admitted >= budget.toolCalls) {
       if (deliveryTools.length > 0 && !locked) {
@@ -593,7 +603,7 @@ function createClaudeWorkerBudgetGate(budget, onBoundary, onHardCap, deliveryToo
   return {
     attempt(canonicalToolName) {
       attempts += 1;
-      if (attempts > budget.hardCap) {
+      if (budget.mode !== "advisory" && attempts > budget.hardCap) {
         onHardCap();
         return { kind: "deny", reason: `workerToolCallCap reached (${budget.hardCap}); abort run` };
       }
@@ -603,7 +613,7 @@ function createClaudeWorkerBudgetGate(budget, onBoundary, onHardCap, deliveryToo
       const phase = phaseDecision(canonicalToolName);
       if (phase.kind === "deny") return phase;
       admitted += 1;
-      if (admitted >= budget.toolCalls && deliveryTools.length === 0) {
+      if (budget.mode !== "advisory" && admitted >= budget.toolCalls && deliveryTools.length === 0) {
         locked = true;
         onBoundary();
       }
@@ -895,6 +905,8 @@ function assistantMessageText(message) {
 }
 function isTerminalAssistantMessage(message) {
   if (!isAssistantMessage(message)) return false;
+  if (message.stopReason === "length" && Array.isArray(message.content) && message.content.some((block) => block.type === "toolCall"))
+    return false;
   return message.stopReason !== "toolUse" && message.stopReason !== "error";
 }
 function terminalContractViolation(contract, message, cwd, observedReadRanges, observedRunEffects) {
@@ -1031,6 +1043,7 @@ function startWorkerRun(input, emit) {
   const loopGuardRegistration = createLoopGuardRegistration({
     safety,
     toolCallCap: workerBudget.hardCap,
+    toolBudgetAdvisory: workerBudget.mode === "advisory",
     toolCallSoftLimit: workerBudget.toolCalls,
     // A worker's blocks all land in one run-long bucket, so the bound on
     // them is a statement about this run's length, not about a turn.
@@ -1154,6 +1167,7 @@ function startWorkerRun(input, emit) {
     invokeOptions: () => ({
       correlationId: `worker-model-round-${workerModelRound}`,
       toolResultMaxBytes: workerSettings.context.toolResultMaxBytes,
+      supportsImages: model.input.includes("image"),
       ...agentSkillPolicy ? { pendingSkillPolicy: agentSkillPolicy } : {}
     })
   });
@@ -1248,7 +1262,7 @@ function startWorkerRun(input, emit) {
               stopAfterToolResultCallId = null;
             }
           }
-          const revisionToolsAvailable = resultContractRevisionActive && !synthesisToolLock;
+          const revisionToolsAvailable = (workerBudget.mode === "advisory" || resultContractRevisionActive) && !synthesisToolLock;
           if (!revisionToolsAvailable) synthesisToolLock = true;
           const repair = resultContractRepairMessages(
             {

package/dist/{workspace-ZJ6BFM3Q.js → workspace-DZ7JADBG.js}

@@ -6,11 +6,11 @@ import {
   probeGitStatusAsync,
   probeWorkspace,
   probeWorkspaceAsync
-} from "./chunk-HVDIIIQW.js";
-import "./chunk-XAKHZX5N.js";
-import "./chunk-33YXPOE3.js";
-import "./chunk-7CR24IG7.js";
-import "./chunk-3R73A4XB.js";
+} from "./chunk-DNHVRBH4.js";
+import "./chunk-CVDAFGPW.js";
+import "./chunk-PPEZJWUG.js";
+import "./chunk-WDV62RKY.js";
+import "./chunk-ECBHH7LU.js";
 export {
   emptyWorkspaceSnapshot,
   probeGit,
@@ -19,4 +19,4 @@ export {
   probeWorkspace,
   probeWorkspaceAsync
 };
-//# sourceMappingURL=workspace-ZJ6BFM3Q.js.map
+//# sourceMappingURL=workspace-DZ7JADBG.js.map

package/docs/README.md

@@ -135,31 +135,33 @@ repository.
 
 The [configuration-knob audit](history/config-knobs-audit.md) is a dated historical
 inventory, not the current settings reference. The
-[v0.4.1 release-cut checklist](history/release-cut-checklist.md) is retained as release
-engineering history and must not be reused unchanged for a future release.
+[release-cut checklist](process/release-cut-checklist.md) is the current release
+procedure; the earlier [v0.4.1 release-cut checklist](history/release-cut-checklist.md)
+is retained as release engineering history.
 
 ## Developer quick start
 
 ```bash
 git clone https://github.com/iowarp/clio-coder.git
 cd clio-coder
-npm ci
-npm run build
+corepack enable pnpm
+pnpm install --frozen-lockfile
+pnpm run build
 node dist/cli/index.js --help
 ```
 
 For a persistent local command:
 
 ```bash
-npm run install:local
+pnpm run install:local
 export PATH="$HOME/.local/bin:$PATH"
 hash -r
 clio-coder --version
 ```
 
-Use `npm run dev` for a watch build. Before handing back a change, run the
-focused test while iterating and `npm run ci` for the deterministic repository
-gate. Maintainers use `npm run ci:release` to add the distribution and package
+Use `pnpm run dev` for a watch build. Before handing back a change, run the
+focused test while iterating and `pnpm run ci` for the deterministic repository
+gate. Maintainers use `pnpm run ci:release` to add the distribution and package
 audit.
 
 ## Project context in a source checkout

package/docs/architecture/acp.md

@@ -330,3 +330,30 @@ export class AcpProcessError extends AcpError {
   }
 }
 ```
+
+---
+
+## 9. Registry Submission
+
+To list Clio Coder in the upstream Agent Client Protocol registry (such as the registry used by the Zed editor), repository submission assets are maintained under `assets/acp-registry/`:
+
+- `assets/acp-registry/agent.json`: Agent registry manifest containing the agent identifier, display name, release version, description, repository URLs, and distribution specification launching `clio-coder acp`.
+- `assets/acp-registry/icon.svg`: A 16x16 monochrome icon using `currentColor` stroke and fill derived from the Clio logo.
+
+The submission procedure follows these steps:
+
+1. Fork the upstream registry repository at `https://github.com/agentclientprotocol/registry`.
+2. Create an entry directory matching the agent identifier: `mkdir clio-coder`.
+3. Copy `assets/acp-registry/agent.json` and `assets/acp-registry/icon.svg` into that directory.
+4. Verify that `agent.json` adheres to the registry schema and that `icon.svg` remains monochrome with viewBox `0 0 16 16`.
+5. Submit a pull request to the upstream registry repository. Once merged, clients that consume the ACP registry discover and install Clio Coder automatically.
+
+## Independent lifecycle coverage
+
+Workbench host replacement and direct ACP session isolation are separate checks. For the supported host API lifecycle, open a session and complete a turn, close, then use New and complete another turn. Close retires child A and initializes unbound child B; New binds B without a third launch. Record actual PIDs and host generations: both must change. A reused session ID alone cannot prove child replacement.
+
+For direct ACP isolation, keep one stdio child alive through new, turn, close, new, and turn. Record the same live PID and distinct session IDs. Check that the second request and persisted ledger exclude first-session history and turn ancestry and that the actual tasks list has no board. Explicitly resuming the first session must restore its own history and task state without second-session text. Record bounded teardown and child exit.
+
+The Workbench host contract uses a fixture subprocess; the direct ACP smoke uses built Clio with a loopback provider. Neither establishes browser interaction or live-provider behavior. The GUI has no close control, and the host API retires its child on close. Record host restart and direct same-child isolation independently, with the actions, process identities, evidence mode, and limits.
+
+ACP delegation receipts preserve peer-reported token totals, including explicit zero usage, and supported cost provenance without double-counting event metering. A peer total is used when supplied; otherwise components determine the total. Unknown cost is not evidence of free execution.

package/docs/architecture/architecture.md

@@ -184,7 +184,7 @@ and `src/tools/dispatch.ts` owns a separate cached dynamic import of
 
 ## Boundary invariants
 
-`npm run lint` executes the boundary checker (`tests/boundaries/check-boundaries.ts`, imported by `scripts/check-hygiene.ts`). Treat these checks as executable specifications.
+`pnpm run lint` executes the boundary checker (`tests/boundaries/check-boundaries.ts`, imported by `scripts/check-hygiene.ts`). Treat these checks as executable specifications.
 
 The enforced import rules below are complemented by the maintained
 [Pi SDK boundary table](pi-boundary.md), which records the semantic owner of
@@ -334,10 +334,10 @@ Interactive slash commands in Clio Coder are governed by a unified declarative c
 ## Verification commands
 
 ```bash
-npm run lint
-npm run typecheck
-npm run test
-npm run build
+pnpm run lint
+pnpm run typecheck
+pnpm run test
+pnpm run build
 ```
 
 Run the focused boundary check before editing `src/engine/**`, `src/worker/**`, or cross-domain imports. Run the full test/build gate before release-facing documentation or behavior changes.

package/docs/architecture/artifact-versions.md

@@ -43,7 +43,7 @@ normalization.
 | **Capacity State File** | `2` | `version: 2` in `interface CapacityStateFile`<br>`src/domains/dispatch/capacity-lease.ts:56` | `<stateDir>/dispatch-admission.json` | Active capacity leases, drain status, and whole-plan reservations. The cross-process advisory lock lives in a separate `.lock` file. | 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:21` | `<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/state.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. |
-| **Dispatch Run Ledger** | unversioned JSON array | `RunEnvelope`<br>`src/domains/dispatch/state.ts` | `<stateDir>/runs.json` | In-memory mirror of recent dispatch runs (id, agent, target, model, runtime, status, timing, receipt path, budget/briefing/steering provenance), newest-first, persisted as a settings-bounded ring (default 1000 runs). Read by the eval, evidence, CLI (`usage`), and TUI (Dispatch Board) domains, among others. | A missing file reads as empty; a non-array top-level JSON value reads as empty; malformed JSON throws. There is no per-record version field to check or reject on, since `RunEnvelope` carries none. |
+| **Dispatch Run Ledger** | `1` | `version: 1` in `interface RunEnvelope`<br>`src/domains/dispatch/state.ts` | `<stateDir>/runs.json` | In-memory mirror of recent dispatch runs (id, agent, target, model, runtime, status, timing, receipt path, budget/briefing/steering provenance), newest-first, persisted as a settings-bounded ring (default 1000 runs). Read by the eval, evidence, CLI (`usage`), and TUI (Dispatch Board) domains, among others. | A missing file reads as empty; a non-array top-level JSON value reads as empty; malformed JSON throws. A missing record version is treated as 1; records with any other version are skipped. |
 | **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 or unreadable record throws and fails admission closed. |
 | **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 recorded side question, handoff, prompt prewarm, background-memory call, or summary stream in an unsuccessful compaction. Labels are `side-question`, `handoff`, `prewarm`, `background-memory`, and `failed-compaction`; rows retain session/repository identity, timestamp, selected target/model, and observed usage. New failed-compaction rows add `callOutcome`, nullable unknown usage fields, and estimated/unknown cost provenance; legacy numeric rows remain readable. Successful compactions keep usage on their checkpoint. The ledger is a 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. |