peaks-loop 4.0.54 → 4.1.0

package/dist/services/dispatch/dispatch-record-upgrade-fields.js

@@ -0,0 +1,242 @@
+import { isDispatchStatus, isObject, isValidHeartbeat, isOutcome, stringField } from './dispatch-record-upgrade-guards.js';
+/**
+ * Parse the v1..v3.2 core fields of a legacy dispatch record.
+ * PRD-002b slice 6: extracted from `upgradeRecord` so the reader
+ * stays under the `max-lines-per-function: 50` ESLint ceiling.
+ * Behavior is byte-identical to the previous inline block.
+ */
+export function parseUpgradeRecordLegacyFields(obj) {
+    const role = stringField(obj, 'role');
+    const requestId = stringField(obj, 'requestId');
+    const sessionId = stringField(obj, 'sessionId');
+    const prompt = stringField(obj, 'prompt');
+    // Slice 2026-06-23-audit-4th #C2: preserve toolCallVersion on read.
+    const toolCall = parseLegacyToolCallField(obj);
+    const createdAt = stringField(obj, 'createdAt');
+    return { role, requestId, sessionId, prompt, toolCall, createdAt };
+}
+/**
+ * Slice 2026-06-23-audit-4th #C2 — pre-versioning records default to
+ * '2.0.0' (the pre-#C2 implicit shape; matches the version stamped by
+ * every current dispatcher). Throws exactly where the inline block threw.
+ */
+function parseLegacyToolCallField(obj) {
+    const rawToolCall = obj.toolCall;
+    if (!isObject(rawToolCall) || typeof rawToolCall.name !== 'string') {
+        throw new Error('Dispatch record toolCall must be { name, args }');
+    }
+    return {
+        name: rawToolCall.name,
+        args: isObject(rawToolCall.args) ? rawToolCall.args : {},
+        ...(typeof rawToolCall.toolCallVersion === 'string'
+            ? { toolCallVersion: rawToolCall.toolCallVersion }
+            : { toolCallVersion: '2.0.0' })
+    };
+}
+/**
+ * Default the G5/G6 lifecycle + heartbeat fields of a legacy record.
+ * All pure reads: no branch here throws, matching the previous inline block.
+ */
+function parseLegacyStateFields(obj) {
+    const heartbeats = Array.isArray(obj.heartbeats) ? obj.heartbeats.filter(isValidHeartbeat) : [];
+    const lastBeatAt = typeof obj.lastBeatAt === 'string' ? obj.lastBeatAt : null;
+    // Slice 2026-07-29-dispatch-stall-governance / S1 (UQ-1) — `no-execution`
+    // keeps its natural "dispatched, never executed" reading; an unparseable
+    // status field now resolves to a *distinct* `unreadable` label so the
+    // caller can tell "corrupt record" apart from "record written, no first
+    // heartbeat" (which is the new `never-started` state).
+    const status = isDispatchStatus(obj.status) ? obj.status : 'unreadable';
+    const completedAt = typeof obj.completedAt === 'string' ? obj.completedAt : null;
+    const outcome = isOutcome(obj.outcome) ? obj.outcome : 'no-execution';
+    const artifactPaths = Array.isArray(obj.artifactPaths)
+        ? obj.artifactPaths.filter((p) => typeof p === 'string')
+        : [];
+    const disposed = obj.disposed === true;
+    const disposedAt = typeof obj.disposedAt === 'string' ? obj.disposedAt : null;
+    const batchId = typeof obj.batchId === 'string' && obj.batchId.length > 0 ? obj.batchId : 'legacy-batch';
+    return {
+        heartbeats,
+        lastBeatAt,
+        status,
+        completedAt,
+        outcome,
+        artifactPaths,
+        disposed,
+        disposedAt,
+        batchId
+    };
+}
+/**
+ * Parse the post-v3 migration fields of a legacy dispatch record.
+ * PRD-002b slice 6: extracted from `upgradeRecord` so the reader
+ * stays under the `max-lines-per-function: 50` ESLint ceiling.
+ * Behavior is byte-identical to the previous inline block; the `vendor`
+ * field is NOT parsed here — it stays in `dispatch-record-upgrade.ts`
+ * because the vendor-neutral identity census pins that decision by path.
+ */
+export function parseUpgradeRecordMigrationFields(obj) {
+    const stall = parseStallGovernanceFields(obj);
+    const mergeBack = parseMergeBackFields(obj);
+    const workflow = parseWorkflowBindingFields(obj);
+    const autoCompact = parseAutoCompactEventsField(obj);
+    const tokenUsage = parseTokenUsageField(obj);
+    // Typed exactly as the previous inline block's explicit return type
+    // ('in-process' | 'detached'); without the annotation the ternary would
+    // widen to `string`.
+    const mode = obj.mode === 'detached' ? 'detached' : 'in-process';
+    return {
+        stage: stall.stage,
+        leaseId: stall.leaseId,
+        isolationStartedAt: stall.isolationStartedAt,
+        serviceKill: mergeBack.serviceKill,
+        mergeBackAttempts: mergeBack.mergeBackAttempts,
+        workflowId: workflow.workflowId,
+        graphNodeId: workflow.graphNodeId,
+        graphRef: workflow.graphRef,
+        // Phase A Task 8: 4.0.0 → 4.1.0 migration. Pre-4.1.0 records
+        // have no mode / vendor / autoCompactEvents / tokenUsage
+        // fields. Default to safe in-process / null / [] / null so
+        // legacy records upgrade transparently without breaking
+        // consumers (e.g. the dashboard, the merge-back-runner).
+        mode,
+        autoCompactEvents: autoCompact.autoCompactEvents,
+        tokenUsage: tokenUsage.tokenUsage
+    };
+}
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.1 / PB-2)
+ * — legacy records (pre-slice) had no `stage` field. The reader
+ * defaults to `null` so the watch surface can tell "no stage ever
+ * emitted" apart from "stage: ''" (which is itself a *valid*
+ * round-trip through the writer — an empty stage is rejected by
+ * `setStage`, but a record that round-tripped through a non-strict
+ * tool would land here).
+ * Slice 2026-07-29-worktree-l2-extended Part 3.A: legacy records
+ * have no `leaseId`; default to `null` so the auto-release hook
+ * in `markCompleted` is a clean no-op for them.
+ * Slice 2026-07-29-worktree-l2-extended Part 7: v3 → v3.1
+ * migration. Legacy records have no `isolationStartedAt`; default
+ * to `null`. v3.1 readers can treat the field as opt-in.
+ */
+function parseStallGovernanceFields(obj) {
+    return {
+        stage: typeof obj.stage === 'string' && obj.stage.length > 0 ? obj.stage : null,
+        leaseId: typeof obj.leaseId === 'string' && /^[a-f0-9]{16}$/.test(obj.leaseId) ? obj.leaseId : null,
+        isolationStartedAt: typeof obj.isolationStartedAt === 'string' && obj.isolationStartedAt.length > 0
+            ? obj.isolationStartedAt
+            : null
+    };
+}
+/**
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.1 → v3.2
+ * migration. Legacy v3.1 records have no `serviceKill` or
+ * `mergeBackAttempts` fields. Default to [] and 0 so the
+ * merge-back-runner (Task 9) can read either schema on disk.
+ */
+function parseMergeBackFields(obj) {
+    return {
+        serviceKill: Array.isArray(obj.serviceKill) ? obj.serviceKill.filter(isServiceKillEntry) : [],
+        mergeBackAttempts: typeof obj.mergeBackAttempts === 'number' &&
+            Number.isFinite(obj.mergeBackAttempts) &&
+            obj.mergeBackAttempts >= 0
+            ? Math.floor(obj.mergeBackAttempts)
+            : 0
+    };
+}
+function isServiceKillEntry(e) {
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const o = e;
+    return (typeof o.pid === 'number' &&
+        typeof o.name === 'string' &&
+        typeof o.signal === 'string' &&
+        (o.exitCode === null || typeof o.exitCode === 'number'));
+}
+// Slice 4.0.8: 3.2 → 4.0.0 migration. v3.2 records on disk
+// pre-date the workflow-graph binding; default all three
+// fields to `null` so a legacy record upgrades transparently.
+function parseWorkflowBindingFields(obj) {
+    return {
+        workflowId: typeof obj.workflowId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.workflowId)
+            ? obj.workflowId
+            : null,
+        graphNodeId: typeof obj.graphNodeId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.graphNodeId)
+            ? obj.graphNodeId
+            : null,
+        graphRef: typeof obj.graphRef === 'string' ? obj.graphRef : null
+    };
+}
+function parseAutoCompactEventsField(obj) {
+    return {
+        autoCompactEvents: Array.isArray(obj.autoCompactEvents)
+            ? obj.autoCompactEvents.filter(isAutoCompactEvent)
+            : []
+    };
+}
+function isAutoCompactEvent(e) {
+    return (typeof e?.at === 'number' &&
+        (e?.threshold === '0.85' || e?.threshold === '0.95') &&
+        typeof e?.tokensBefore === 'number' &&
+        typeof e?.tokensAfter === 'number');
+}
+function parseTokenUsageField(obj) {
+    return {
+        tokenUsage: typeof obj.tokenUsage === 'object' &&
+            obj.tokenUsage !== null &&
+            typeof obj.tokenUsage.promptTokens === 'number' &&
+            typeof obj.tokenUsage.completionTokens === 'number'
+            ? {
+                promptTokens: obj.tokenUsage.promptTokens,
+                completionTokens: obj.tokenUsage
+                    .completionTokens,
+                ...(typeof obj.tokenUsage.totalCostUsd === 'number'
+                    ? {
+                        totalCostUsd: obj.tokenUsage.totalCostUsd
+                    }
+                    : {})
+            }
+            : null
+    };
+}
+/**
+ * Assemble the normalized 4.1.0 record from the two parse passes. The
+ * returned object literal is byte-for-byte the previous `upgradeRecord`
+ * return literal (same key order) so a record re-serialized by the writer
+ * keeps its on-disk shape. `vendor` is threaded in from the upgrade module
+ * (see `parseUpgradeRecordMigrationFields` for why).
+ */
+export function buildUpgradedRecord(obj, vendor) {
+    const legacy = parseUpgradeRecordLegacyFields(obj);
+    const state = parseLegacyStateFields(obj);
+    const migration = parseUpgradeRecordMigrationFields(obj);
+    return {
+        version: '4.1.0',
+        createdAt: legacy.createdAt,
+        completedAt: state.completedAt,
+        outcome: state.outcome,
+        artifactPaths: state.artifactPaths,
+        disposed: state.disposed,
+        disposedAt: state.disposedAt,
+        role: legacy.role,
+        requestId: legacy.requestId,
+        sessionId: legacy.sessionId,
+        prompt: legacy.prompt,
+        toolCall: legacy.toolCall,
+        batchId: state.batchId,
+        heartbeats: state.heartbeats,
+        lastBeatAt: state.lastBeatAt,
+        status: state.status,
+        stage: migration.stage,
+        leaseId: migration.leaseId,
+        isolationStartedAt: migration.isolationStartedAt,
+        serviceKill: migration.serviceKill,
+        mergeBackAttempts: migration.mergeBackAttempts,
+        workflowId: migration.workflowId,
+        graphNodeId: migration.graphNodeId,
+        graphRef: migration.graphRef,
+        mode: migration.mode,
+        vendor,
+        autoCompactEvents: migration.autoCompactEvents,
+        tokenUsage: migration.tokenUsage
+    };
+}

package/dist/services/dispatch/dispatch-record-upgrade-guards.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Type-guard helpers for the dispatch-record upgrade path.
+ * C wave 1 / slice c1 (leaf c1w1-record-upgrade): extracted verbatim from
+ * `dispatch-record-upgrade.ts` so the reader module clears the line cap.
+ * Behavior is byte-identical to the previous in-file definitions; the
+ * `isDispatchStatus` / `isOutcome` re-export from the upgrade module keeps
+ * every existing importer (e.g. `dispatch-record-writer.ts`) resolving them
+ * at the original path.
+ */
+import type { DispatchOutcome, DispatchRecordStatus, Heartbeat } from './dispatch-record-types.js';
+export declare function isObject(v: unknown): v is Record<string, unknown>;
+export declare function stringField(obj: Record<string, unknown>, key: string): string;
+export declare function isValidHeartbeat(v: unknown): v is Heartbeat;
+export declare function isDispatchStatus(v: unknown): v is DispatchRecordStatus;
+export declare function isOutcome(v: unknown): v is DispatchOutcome;

package/dist/services/dispatch/dispatch-record-upgrade-guards.js

@@ -0,0 +1,55 @@
+export function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function stringField(obj, key) {
+    const v = obj[key];
+    if (typeof v !== 'string') {
+        throw new Error(`Dispatch record field '${key}' must be a string (got ${typeof v})`);
+    }
+    return v;
+}
+export function isValidHeartbeat(v) {
+    if (!isObject(v))
+        return false;
+    return (typeof v.at === 'string' &&
+        isHeartbeatStatus(v.status) &&
+        typeof v.progress === 'number' &&
+        (v.note === null || typeof v.note === 'string'));
+}
+function isHeartbeatStatus(v) {
+    return (v === 'queued' ||
+        v === 'running' ||
+        v === 'finalizing' ||
+        v === 'done' ||
+        v === 'failed' ||
+        v === 'stale' ||
+        // Slice 2026-07-29-dispatch-stall-governance / S2 — accept the
+        // S1 terminal members so a sub-agent can report `cancelled`,
+        // `no-execution`, `never-started`, or `unreadable` through the
+        // heartbeat CLI.
+        v === 'cancelled' ||
+        v === 'no-execution' ||
+        v === 'never-started' ||
+        v === 'unreadable');
+}
+export function isDispatchStatus(v) {
+    return (v === 'queued' ||
+        v === 'running' ||
+        v === 'finalizing' ||
+        v === 'done' ||
+        v === 'failed' ||
+        v === 'cancelled' ||
+        v === 'no-execution' ||
+        v === 'stale' ||
+        // Slice 2026-07-29-dispatch-stall-governance / S1 — accept the two
+        // new terminal members from the startup-timeout service.
+        v === 'never-started' ||
+        v === 'unreadable');
+}
+export function isOutcome(v) {
+    return (v === 'success' ||
+        v === 'failed' ||
+        v === 'timeout' ||
+        v === 'cancelled' ||
+        v === 'no-execution');
+}

package/dist/services/dispatch/dispatch-record-upgrade.d.ts

@@ -1,5 +1,3 @@
-import type { DispatchOutcome, DispatchRecord, DispatchRecordStatus } from './dispatch-record-types.js';
+import type { DispatchRecord } from './dispatch-record-types.js';
+export { isDispatchStatus, isOutcome } from './dispatch-record-upgrade-guards.js';
 export declare function upgradeRecord(parsed: unknown): DispatchRecord;
-declare function isDispatchStatus(v: unknown): v is DispatchRecordStatus;
-declare function isOutcome(v: unknown): v is DispatchOutcome;
-export { isDispatchStatus, isOutcome };

package/dist/services/dispatch/dispatch-record-upgrade.js

@@ -1,3 +1,6 @@
+import { buildUpgradedRecord } from './dispatch-record-upgrade-fields.js';
+import { isObject } from './dispatch-record-upgrade-guards.js';
+export { isDispatchStatus, isOutcome } from './dispatch-record-upgrade-guards.js';
 export function upgradeRecord(parsed) {
     if (!isObject(parsed)) {
         throw new Error('Dispatch record root must be an object');
@@ -8,223 +11,28 @@ export function upgradeRecord(parsed) {
     // v3.2 / v3.1 / 3 / 2 / 1 records are accepted transparently and
     // upgraded on read.
     const rawVersion = obj.version;
-    if (rawVersion !== '4.1.0' && rawVersion !== '4.0.0' && rawVersion !== '3.2' && rawVersion !== '3.1' && rawVersion !== 3 && rawVersion !== 2 && rawVersion !== 1) {
+    if (rawVersion !== '4.1.0' &&
+        rawVersion !== '4.0.0' &&
+        rawVersion !== '3.2' &&
+        rawVersion !== '3.1' &&
+        rawVersion !== 3 &&
+        rawVersion !== 2 &&
+        rawVersion !== 1) {
         throw new Error(`Dispatch record version mismatch: expected '4.1.0', '4.0.0', '3.2', '3.1', 3, 2, or 1, got ${JSON.stringify(rawVersion)}. ` +
             'The v1 → v4.1.0 migration is in-file; records from much older or newer builds must be regenerated.');
     }
-    const legacy = parseUpgradeRecordLegacyFields(obj);
-    const migration = parseUpgradeRecordMigrationFields(obj);
-    return {
-        version: '4.1.0',
-        createdAt: legacy.createdAt,
-        completedAt: legacy.completedAt,
-        outcome: legacy.outcome,
-        artifactPaths: legacy.artifactPaths,
-        disposed: legacy.disposed,
-        disposedAt: legacy.disposedAt,
-        role: legacy.role,
-        requestId: legacy.requestId,
-        sessionId: legacy.sessionId,
-        prompt: legacy.prompt,
-        toolCall: legacy.toolCall,
-        batchId: legacy.batchId,
-        heartbeats: legacy.heartbeats,
-        lastBeatAt: legacy.lastBeatAt,
-        status: legacy.status,
-        stage: migration.stage,
-        leaseId: migration.leaseId,
-        isolationStartedAt: migration.isolationStartedAt,
-        serviceKill: migration.serviceKill,
-        mergeBackAttempts: migration.mergeBackAttempts,
-        workflowId: migration.workflowId,
-        graphNodeId: migration.graphNodeId,
-        graphRef: migration.graphRef,
-        // Phase A Task 8: detached sub-agent fields. Legacy records
-        // (pre-4.1.0) default mode='in-process', vendor=null,
-        // autoCompactEvents=[], tokenUsage=null. See
-        // parseUpgradeRecordMigrationFields for the per-field
-        // validation rules.
-        mode: migration.mode,
-        vendor: migration.vendor,
-        autoCompactEvents: migration.autoCompactEvents,
-        tokenUsage: migration.tokenUsage
-    };
+    return buildUpgradedRecord(obj, readUpgradeRecordVendorField(obj));
 }
 /**
- * Parse the v1..v3.2 core fields of a legacy dispatch record.
- * PRD-002b slice 6: extracted from `upgradeRecord` so the reader
- * stays under the `max-lines-per-function: 50` ESLint ceiling.
- * Behavior is byte-identical to the previous inline block.
+ * Parse the 4.1.0 `vendor` migration field. It stays in this module —
+ * NOT in `dispatch-record-upgrade-fields.ts` — because the vendor-neutral
+ * identity guard (`tests/unit/runtime/vendor-neutral-identity-guard.test.ts`)
+ * pins the `vendor === 'codex'` comparison here by file path; moving the
+ * comparison would move a pinned census entry. Pure read; the original
+ * block defaulted anything else to `null`, exactly as here.
  */
-function parseUpgradeRecordLegacyFields(obj) {
-    const role = stringField(obj, 'role');
-    const requestId = stringField(obj, 'requestId');
-    const sessionId = stringField(obj, 'sessionId');
-    const prompt = stringField(obj, 'prompt');
-    // Slice 2026-06-23-audit-4th #C2: preserve toolCallVersion on read.
-    // Pre-versioning records default to '2.0.0' (the pre-#C2 implicit
-    // shape; matches the version stamped by every current dispatcher).
-    const rawToolCall = obj.toolCall;
-    if (!isObject(rawToolCall) || typeof rawToolCall.name !== 'string') {
-        throw new Error('Dispatch record toolCall must be { name, args }');
-    }
-    const toolCall = {
-        name: rawToolCall.name,
-        args: (isObject(rawToolCall.args) ? rawToolCall.args : {}),
-        ...(typeof rawToolCall.toolCallVersion === 'string' ? { toolCallVersion: rawToolCall.toolCallVersion } : { toolCallVersion: '2.0.0' })
-    };
-    const createdAt = stringField(obj, 'createdAt');
-    const heartbeats = Array.isArray(obj.heartbeats)
-        ? obj.heartbeats.filter(isValidHeartbeat)
-        : [];
-    const lastBeatAt = typeof obj.lastBeatAt === 'string' ? obj.lastBeatAt : null;
-    // Slice 2026-07-29-dispatch-stall-governance / S1 (UQ-1) — `no-execution`
-    // keeps its natural "dispatched, never executed" reading; an unparseable
-    // status field now resolves to a *distinct* `unreadable` label so the
-    // caller can tell "corrupt record" apart from "record written, no first
-    // heartbeat" (which is the new `never-started` state).
-    const status = isDispatchStatus(obj.status)
-        ? obj.status
-        : 'unreadable';
-    const completedAt = typeof obj.completedAt === 'string' ? obj.completedAt : null;
-    const outcome = isOutcome(obj.outcome) ? obj.outcome : 'no-execution';
-    const artifactPaths = Array.isArray(obj.artifactPaths)
-        ? obj.artifactPaths.filter((p) => typeof p === 'string')
-        : [];
-    const disposed = obj.disposed === true;
-    const disposedAt = typeof obj.disposedAt === 'string' ? obj.disposedAt : null;
-    const batchId = typeof obj.batchId === 'string' && obj.batchId.length > 0
-        ? obj.batchId
-        : 'legacy-batch';
-    return {
-        role,
-        requestId,
-        sessionId,
-        prompt,
-        toolCall,
-        createdAt,
-        heartbeats,
-        lastBeatAt,
-        status,
-        completedAt,
-        outcome,
-        artifactPaths,
-        disposed,
-        disposedAt,
-        batchId
-    };
-}
-/**
- * Parse the post-v3 migration fields of a legacy dispatch record.
- * PRD-002b slice 6: extracted from `upgradeRecord` so the reader
- * stays under the `max-lines-per-function: 50` ESLint ceiling.
- * Behavior is byte-identical to the previous inline block.
- */
-function parseUpgradeRecordMigrationFields(obj) {
-    return {
-        // Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.1 / PB-2)
-        // — legacy records (pre-slice) had no `stage` field. The reader
-        // defaults to `null` so the watch surface can tell "no stage ever
-        // emitted" apart from "stage: ''" (which is itself a *valid*
-        // round-trip through the writer — an empty stage is rejected by
-        // `setStage`, but a record that round-tripped through a non-strict
-        // tool would land here).
-        stage: typeof obj.stage === 'string' && obj.stage.length > 0 ? obj.stage : null,
-        // Slice 2026-07-29-worktree-l2-extended Part 3.A: legacy records
-        // have no `leaseId`; default to `null` so the auto-release hook
-        // in `markCompleted` is a clean no-op for them.
-        leaseId: typeof obj.leaseId === 'string' && /^[a-f0-9]{16}$/.test(obj.leaseId)
-            ? obj.leaseId
-            : null,
-        // Slice 2026-07-29-worktree-l2-extended Part 7: v3 → v3.1
-        // migration. Legacy records have no `isolationStartedAt`; default
-        // to `null`. v3.1 readers can treat the field as opt-in.
-        isolationStartedAt: typeof obj.isolationStartedAt === 'string' && obj.isolationStartedAt.length > 0
-            ? obj.isolationStartedAt
-            : null,
-        // Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.1 → v3.2
-        // migration. Legacy v3.1 records have no `serviceKill` or
-        // `mergeBackAttempts` fields. Default to [] and 0 so the
-        // merge-back-runner (Task 9) can read either schema on disk.
-        serviceKill: Array.isArray(obj.serviceKill)
-            ? (obj.serviceKill.filter((e) => {
-                if (typeof e !== 'object' || e === null)
-                    return false;
-                const o = e;
-                return typeof o.pid === 'number' && typeof o.name === 'string' && typeof o.signal === 'string' && (o.exitCode === null || typeof o.exitCode === 'number');
-            }))
-            : [],
-        mergeBackAttempts: typeof obj.mergeBackAttempts === 'number' && Number.isFinite(obj.mergeBackAttempts) && obj.mergeBackAttempts >= 0
-            ? Math.floor(obj.mergeBackAttempts)
-            : 0,
-        // Slice 4.0.8: 3.2 → 4.0.0 migration. v3.2 records on disk
-        // pre-date the workflow-graph binding; default all three
-        // fields to `null` so a legacy record upgrades transparently.
-        workflowId: typeof obj.workflowId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.workflowId) ? obj.workflowId : null,
-        graphNodeId: typeof obj.graphNodeId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.graphNodeId) ? obj.graphNodeId : null,
-        graphRef: typeof obj.graphRef === 'string' ? obj.graphRef : null,
-        // Phase A Task 8: 4.0.0 → 4.1.0 migration. Pre-4.1.0 records
-        // have no mode / vendor / autoCompactEvents / tokenUsage
-        // fields. Default to safe in-process / null / [] / null so
-        // legacy records upgrade transparently without breaking
-        // consumers (e.g. the dashboard, the merge-back-runner).
-        mode: obj.mode === 'detached' ? 'detached' : 'in-process',
-        vendor: obj.vendor === 'claude' || obj.vendor === 'codex' || obj.vendor === 'copilot' ? obj.vendor : null,
-        autoCompactEvents: Array.isArray(obj.autoCompactEvents)
-            ? obj.autoCompactEvents.filter((e) => typeof e?.at === 'number' &&
-                (e?.threshold === '0.85' || e?.threshold === '0.95') &&
-                typeof e?.tokensBefore === 'number' &&
-                typeof e?.tokensAfter === 'number')
-            : [],
-        tokenUsage: typeof obj.tokenUsage === 'object' && obj.tokenUsage !== null && typeof obj.tokenUsage.promptTokens === 'number' && typeof obj.tokenUsage.completionTokens === 'number'
-            ? {
-                promptTokens: obj.tokenUsage.promptTokens,
-                completionTokens: obj.tokenUsage.completionTokens,
-                ...(typeof obj.tokenUsage.totalCostUsd === 'number'
-                    ? { totalCostUsd: obj.tokenUsage.totalCostUsd }
-                    : {}),
-            }
-            : null
-    };
-}
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-function stringField(obj, key) {
-    const v = obj[key];
-    if (typeof v !== 'string') {
-        throw new Error(`Dispatch record field '${key}' must be a string (got ${typeof v})`);
-    }
-    return v;
-}
-function isValidHeartbeat(v) {
-    if (!isObject(v))
-        return false;
-    return (typeof v.at === 'string' &&
-        isHeartbeatStatus(v.status) &&
-        typeof v.progress === 'number' &&
-        (v.note === null || typeof v.note === 'string'));
-}
-function isHeartbeatStatus(v) {
-    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
-        v === 'done' || v === 'failed' || v === 'stale' ||
-        // Slice 2026-07-29-dispatch-stall-governance / S2 — accept the
-        // S1 terminal members so a sub-agent can report `cancelled`,
-        // `no-execution`, `never-started`, or `unreadable` through the
-        // heartbeat CLI.
-        v === 'cancelled' || v === 'no-execution' ||
-        v === 'never-started' || v === 'unreadable');
-}
-function isDispatchStatus(v) {
-    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
-        v === 'done' || v === 'failed' || v === 'cancelled' ||
-        v === 'no-execution' || v === 'stale' ||
-        // Slice 2026-07-29-dispatch-stall-governance / S1 — accept the two
-        // new terminal members from the startup-timeout service.
-        v === 'never-started' || v === 'unreadable');
-}
-function isOutcome(v) {
-    return (v === 'success' || v === 'failed' || v === 'timeout' ||
-        v === 'cancelled' || v === 'no-execution');
+function readUpgradeRecordVendorField(obj) {
+    return obj.vendor === 'claude' || obj.vendor === 'codex' || obj.vendor === 'copilot'
+        ? obj.vendor
+        : null;
 }
-export { isDispatchStatus, isOutcome };