peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,690 @@
+/**
+ * Dispatch record writer — slice 2026-06-07-sub-agent-dispatch-decouple (G2 + G5 + G6).
+ *
+ * Owns the on-disk format of `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json`:
+ *   - G2: atomic write helper (mkdirSync recursive + tmp + rename) and
+ *     R-2 guard (path must live under `.peaks/_sub_agents/<sid>/`).
+ *   - G5: lifecycle schema (`createdAt` / `completedAt` / `outcome` /
+ *     `artifactPaths` / `disposed` / `disposedAt`) per AC-26 + RL-6..RL-9.
+ *   - G6: heartbeat schema upgrade per AC-33/AC-34 — `heartbeats[]` +
+ *     `lastBeatAt` + `status` aggregate. Read-side backward compat
+ *     supplies defaults for old records missing the G6 fields.
+ *
+ * The write helpers are intentionally small and pure:
+ *   - `writeInitialDispatchRecord`: append a new dispatch record at the
+ *     start of a sub-agent dispatch (called by `peaks sub-agent dispatch`).
+ *   - `appendHeartbeat`: append one heartbeat to an existing record
+ *     (called by `peaks sub-agent heartbeat`).
+ *   - `markCompleted` / `markFailed` / `markCancelled` / `markNoExecution`:
+ *     lifecycle transitions called by the reducer.
+ *
+ * All writes are atomic (tmp + rename) so a process crash mid-write
+ * cannot leave a half-truncated JSON file. All reads tolerate missing
+ * G6 fields (backward compat) and the G5 schema fields default to
+ * `null` / `false` / `'no-execution'` if the file was written by an
+ * older peaks build.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { assertSafeDispatchRecordPath, dispatchRecordPath } from '../security/safe-settings-path.js';
+import { withFileLockSync } from 'peaks-loop-shared-channel';
+import { isStageLabel } from './stage-enum.js';
+import { emitLeaseEvent } from '../observability/observability-service.js';
+const MAX_PROMPT_BYTES = 256 * 1024;
+/** Write a new dispatch record (G2 + G5 + G6). Returns the absolute path. */
+export function writeInitialDispatchRecord(input) {
+    const { projectRoot, sessionId, requestId, role, prompt, toolCall, batchId } = input;
+    const now = input.now ?? (() => new Date());
+    if (prompt.length > MAX_PROMPT_BYTES) {
+        const err = new Error(`prompt exceeds ${MAX_PROMPT_BYTES} bytes (got ${prompt.length}); ` +
+            `truncate or split into multiple dispatches`);
+        err.code = 'PROMPT_TOO_LARGE';
+        throw err;
+    }
+    const path = dispatchRecordPath(projectRoot, sessionId, requestId, now());
+    const safePath = assertSafeDispatchRecordPath(path, projectRoot);
+    const record = {
+        version: '3.1',
+        createdAt: now().toISOString(),
+        completedAt: null,
+        outcome: 'no-execution',
+        artifactPaths: [],
+        disposed: false,
+        disposedAt: null,
+        role,
+        requestId,
+        sessionId,
+        prompt,
+        // Slice 2026-06-23-audit-4th #C2: propagate toolCallVersion.
+        // The dispatcher's buildToolCall already stamps it (claude-code 2.0.0
+        // etc.); we re-default to '2.0.0' if absent so the on-disk record
+        // is self-describing without reading the dispatcher source.
+        toolCall: { ...toolCall, toolCallVersion: toolCall.toolCallVersion ?? '2.0.0' },
+        batchId,
+        heartbeats: [],
+        lastBeatAt: null,
+        status: 'queued',
+        // Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.1) — new
+        // records start with `stage: null`; the sub-agent promotes it
+        // through `setStage` / the heartbeat CLI's `--stage` flag.
+        stage: null,
+        // Slice 2026-07-29-worktree-l2-extended Part 3.A: when the
+        // dispatch was issued with --isolation worktree, persist the
+        // lease id so the finalize-time release hook in markCompleted
+        // can fire. Validation is the same 16-hex regex the gate uses
+        // (gate-commands.ts), so an attacker-controlled toolCall.env
+        // cannot inject a non-hex value and get the release path to
+        // misfire.
+        leaseId: typeof input.leaseId === 'string' && /^[a-f0-9]{16}$/.test(input.leaseId)
+            ? input.leaseId
+            : null,
+        // Slice 2026-07-29-worktree-l2-extended Part 7: v3.1 field.
+        // ISO timestamp when the isolation mode was set up. Default
+        // null when the dispatch did not request isolation. We do
+        // NOT validate the format — the writer is the source of
+        // truth here, and any ISO 8601 string Date.parse() can
+        // handle is acceptable for the dashboard.
+        isolationStartedAt: typeof input.isolationStartedAt === 'string' && input.isolationStartedAt.length > 0
+            ? input.isolationStartedAt
+            : null
+    };
+    writeAtomic(safePath, record);
+    // Slice 2026-06-23-audit-4th #A4: register the path in the
+    // session's active-dispatches index so a future restart can
+    // discover in-flight records without scanning the directory.
+    // The index is best-effort (no lock): the on-disk record is the
+    // source of truth; the index is purely a hint for the LLM-side
+    // runner. A crash between writeAtomic and the index write is
+    // non-fatal — the next restart scans the directory anyway.
+    registerActiveDispatch({
+        projectRoot,
+        sessionId,
+        recordPath: safePath,
+        requestId,
+        role,
+        batchId,
+        now
+    });
+    return { path: safePath, record };
+}
+function activeDispatchIndexPath(projectRoot, sessionId) {
+    return resolve(projectRoot, '.peaks', '_sub_agents', sessionId, 'active-dispatches.json');
+}
+function registerActiveDispatch(input) {
+    const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
+    const dir = dirname(indexPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    let index = {};
+    try {
+        if (existsSync(indexPath)) {
+            const raw = readFileSync(indexPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === 'object' && parsed !== null) {
+                for (const [k, v] of Object.entries(parsed)) {
+                    if (typeof v === 'object' && v !== null && 'recordPath' in v) {
+                        index[k] = v;
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Corrupt index — start fresh. The on-disk record is the source of truth.
+        index = {};
+    }
+    index[input.recordPath] = {
+        recordPath: input.recordPath,
+        requestId: input.requestId,
+        role: input.role,
+        batchId: input.batchId,
+        createdAt: input.now().toISOString(),
+        status: 'queued'
+    };
+    const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
+    renameSync(tmp, indexPath);
+}
+function unregisterActiveDispatch(input) {
+    const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
+    if (!existsSync(indexPath))
+        return;
+    let index = {};
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null) {
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === 'object' && v !== null && 'recordPath' in v) {
+                    index[k] = v;
+                }
+            }
+        }
+    }
+    catch {
+        return;
+    }
+    if (input.recordPath in index) {
+        index[input.recordPath] = { ...index[input.recordPath], status: input.status };
+        // Slice 2026-07-29-dispatch-stall-governance / S1 — `never-started`
+        // and `unreadable` are terminal (the startup-timeout service writes
+        // them as terminal markers). Unregister on the full terminal set.
+        if (input.status === 'done' ||
+            input.status === 'failed' ||
+            input.status === 'cancelled' ||
+            input.status === 'no-execution' ||
+            input.status === 'never-started' ||
+            input.status === 'unreadable') {
+            delete index[input.recordPath];
+        }
+        const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
+        renameSync(tmp, indexPath);
+    }
+}
+/**
+ * Slice 2026-06-23-audit-4th #A4: read the active-dispatches index
+ * for a session. Returns the current map<recordPath, entry>. Used
+ * by the LLM-side runner to discover in-flight records on restart.
+ * Returns an empty map when the index file is missing or corrupt
+ * (the on-disk records directory is the next fallback).
+ */
+export function readActiveDispatchIndex(projectRoot, sessionId) {
+    const indexPath = activeDispatchIndexPath(projectRoot, sessionId);
+    if (!existsSync(indexPath))
+        return {};
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === 'object' && v !== null && 'recordPath' in v && 'role' in v) {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Slice 2026-06-23-audit-4th #A3: default TTL for dispatch records. */
+export const DISPATCH_RECORD_TTL_DAYS = 30;
+/**
+ * Slice 2026-06-23-audit-4th #A3: is this dispatch record an orphan
+ * (older than DISPATCH_RECORD_TTL_DAYS or already GC'd)? Mirrors
+ * `isOrphanChannel` in shared-channel.ts so a future
+ * `peaks sub-agent cleanup` umbrella can run all three sweeps
+ * (shared channel + dispatch record + contract) in one pass.
+ */
+export function isOrphanDispatchRecord(opts) {
+    if (!existsSync(opts.recordPath))
+        return true;
+    const s = statSync(opts.recordPath);
+    const now = opts.now ?? new Date();
+    const ageMs = now.getTime() - s.mtimeMs;
+    const ttlMs = DISPATCH_RECORD_TTL_DAYS * 24 * 60 * 60 * 1000;
+    return ageMs > ttlMs;
+}
+/** Append a heartbeat (G6). Idempotent on (at, status) — append-only. */
+export function appendHeartbeat(input) {
+    const { recordPath, status, progress, note } = input;
+    const now = input.now ?? (() => new Date());
+    if (!Number.isInteger(progress) || progress < 0 || progress > 100) {
+        const err = new Error(`progress must be integer 0..100 (got ${progress})`);
+        err.code = 'INVALID_PROGRESS';
+        throw err;
+    }
+    if (note !== undefined && note.length > 200) {
+        const err = new Error(`note must be ≤ 200 chars (got ${note.length})`);
+        err.code = 'NOTE_TOO_LONG';
+        throw err;
+    }
+    const existing = readRecord(recordPath);
+    const entry = {
+        at: now().toISOString(),
+        status,
+        progress,
+        note: note ?? null
+    };
+    const { heartbeats, truncated } = applyTruncation([...existing.heartbeats, entry]);
+    const next = {
+        ...existing,
+        heartbeats,
+        lastBeatAt: entry.at,
+        status: mapStatusToAggregate(status, existing.status)
+    };
+    // Slice 2026-06-23-audit-3rd #3: wrap the read-then-write in a file
+    // lock. Without the lock, a heartbeat arriving 100ms before
+    // markCompleted can be silently discarded — the parent's view of the
+    // sub-agent shows "completed" but the last progress update is lost.
+    return withFileLockSync(recordPath, () => {
+        // Re-read under the lock — the file may have been mutated between
+        // our pre-lock `readRecord` above and lock acquisition (heartbeats
+        // and markCompleted share the same record file).
+        const lockedExisting = readRecord(recordPath);
+        const lockedHeartbeats = applyTruncation([
+            ...lockedExisting.heartbeats,
+            entry
+        ]).heartbeats;
+        const lockedNext = {
+            ...lockedExisting,
+            heartbeats: lockedHeartbeats,
+            lastBeatAt: entry.at,
+            status: mapStatusToAggregate(status, lockedExisting.status)
+        };
+        writeAtomic(recordPath, lockedNext);
+        // Recompute truncated flag from the locked-read result so the
+        // caller sees the actual post-lock truncation state.
+        return {
+            record: lockedNext,
+            truncated: lockedHeartbeats.length < lockedExisting.heartbeats.length + 1
+        };
+    });
+}
+/** Apply truncation: keep most recent 100, mark truncated flag. */
+export function applyTruncation(entries) {
+    if (entries.length <= 100) {
+        return { heartbeats: [...entries], truncated: false };
+    }
+    return { heartbeats: entries.slice(-100), truncated: true };
+}
+function mapStatusToAggregate(latest, current) {
+    // 'stale' is a poller-driven warning and must not be overwritten by
+    // a normal heartbeat that arrives after the stale flag was set.
+    if (current === 'stale') {
+        return 'stale';
+    }
+    return latest;
+}
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 3.A: fire-and-forget
+ * auto-release for the lease owned by a dispatch. Called from
+ * `markCompleted` (terminal status) and from the heartbeat CLI
+ * (`--status done`).
+ *
+ * Design:
+ * - The release subprocess is spawned ASYNC and detached. The
+ *   finalize-time caller (heartbeat / share / dispatch reducer)
+ *   does NOT await it; the caller's job is to record the
+ *   finalization, not to wait for the lease cleanup.
+ * - Failures are swallowed (best-effort, same as `git worktree
+ *   remove` inside `peaks worktree release` itself). The next
+ *   `peaks worktree gc` pass is the safety net.
+ * - Idempotent: re-calling with the same leaseId is a no-op on
+ *   the release side (the CLI refuses to re-release an already-
+ *   released lease; see Part 1 release command).
+ * - The leaseId MUST be 16-hex (same regex the gate uses). Any
+ *   other value is silently ignored — we never shell out to
+ *   `peaks worktree release` with attacker-controlled input.
+ */
+export function tryAutoReleaseLease(args) {
+    if (typeof args.leaseId !== 'string' || !/^[a-f0-9]{16}$/.test(args.leaseId)) {
+        return;
+    }
+    if (typeof args.projectRoot !== 'string' || args.projectRoot.length === 0) {
+        return;
+    }
+    // Spawn detached. The CLI itself runs `git worktree remove` and
+    // marks the lease released; we trust its at-least-once semantics.
+    // `node:child_process` is loaded via dynamic import so this module
+    // remains ESM-compatible (the compiled heartbeat CLI throws
+    // `require is not defined` if we use `require` here).
+    void (async () => {
+        let spawned = false;
+        try {
+            const cp = await import('node:child_process');
+            const child = cp.spawn(process.execPath, [
+                process.argv[1] ?? '',
+                'worktree', 'release',
+                '--lease-id', args.leaseId,
+                '--project', args.projectRoot,
+                '--session', args.sessionId,
+                '--json'
+            ], 
+            // `pipe` rather than `ignore` so a spawn failure (e.g. ENOENT
+            // on process.argv[1] in a test) shows up on stderr instead
+            // of vanishing into the void. The release CLI is short-lived
+            // so buffering is irrelevant.
+            { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: true });
+            spawned = true;
+            if (process.env.PEAKS_WORKTREE_LEASE_DEBUG) {
+                child.stderr?.on('data', (d) => process.stderr.write(`[release] ${d.toString('utf8')}`));
+                child.stdout?.on('data', (d) => process.stderr.write(`[release] ${d.toString('utf8')}`));
+                child.on('error', (e) => process.stderr.write(`[release error] ${e.message}\n`));
+                child.on('exit', (code) => process.stderr.write(`[release exit] code=${code}\n`));
+            }
+            else {
+                child.stderr?.on('data', () => { });
+                child.stdout?.on('data', () => { });
+                child.on('error', () => { });
+            }
+            child.unref();
+        }
+        catch (e) {
+            // Slice 2026-07-29-worktree-l2-extended Part 4.A: surface
+            // auto-release failures to the observability stream so the
+            // dashboard can alert. The spawn-attempt itself threw (not
+            // a child-process exit-code failure — those are not
+            // catchable from the parent because the child is detached
+            // and unref'd). emitLeaseEvent is fire-and-forget; it
+            // returns a result we don't inspect.
+            emitLeaseEvent({
+                sessionId: args.sessionId,
+                projectRoot: args.projectRoot,
+                kind: 'autoRelease-failed',
+                leaseId: args.leaseId,
+                reason: e.message
+            });
+        }
+        if (spawned) {
+            // Record the success path. Idempotent with the manual
+            // `peaks worktree release` metric — the release CLI itself
+            // emits a 'release' event when it runs and lands. Two
+            // events for one logical release is acceptable; the
+            // dashboard can dedup or count both under
+            // lease.autoRelease.count.
+            emitLeaseEvent({
+                sessionId: args.sessionId,
+                projectRoot: args.projectRoot,
+                kind: 'autoRelease',
+                leaseId: args.leaseId
+            });
+        }
+    })();
+    // NB: we deliberately do NOT log per-call here — every heartbeat
+    // that reports done in a busy session would otherwise spam the
+    // log. The release CLI itself emits a structured envelope on
+    // success; that's the audit record.
+    if (args.logger !== undefined) {
+        args.logger(`peaks.worktree.autoRelease leaseId=${args.leaseId} sessionId=${args.sessionId}`);
+    }
+}
+/** Mark a record as completed (success / failed / cancelled / no-execution). */
+export function markCompleted(input) {
+    // Slice 2026-06-23-audit-3rd #3: lock + re-read so a concurrent
+    // heartbeat arriving just before markCompleted is preserved in the
+    // final record.
+    const result = withFileLockSync(input.recordPath, () => {
+        const existing = readRecord(input.recordPath);
+        const next = {
+            ...existing,
+            completedAt: (input.now ?? (() => new Date()))().toISOString(),
+            outcome: input.outcome,
+            status: input.status,
+            artifactPaths: input.artifactPaths ?? existing.artifactPaths
+        };
+        writeAtomic(input.recordPath, next);
+        return { record: next };
+    });
+    // Slice 2026-06-23-audit-4th #A4: update the active-dispatches
+    // index. Best-effort (the on-disk record is the source of truth);
+    // we only attempt the update when the trusted projectRoot is
+    // available so a malicious recordPath cannot redirect the index
+    // write (audit-3rd #1 anti-pattern).
+    if (typeof input.projectRoot === 'string' && input.projectRoot.length > 0) {
+        try {
+            unregisterActiveDispatch({
+                projectRoot: input.projectRoot,
+                sessionId: result.record.sessionId,
+                recordPath: input.recordPath,
+                status: input.status
+            });
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            /* best-effort */
+        }
+    }
+    // Slice 2026-07-29-worktree-l2-extended Part 3.A: finalize-time
+    // lease release. The terminal status (done/failed/cancelled/
+    // no-execution) means the sub-agent is no longer using the
+    // worktree; auto-release closes the loop. The release is detached
+    // and best-effort; a crash here cannot roll back the markCompleted
+    // write (we already returned from the lock). The next gc pass is
+    // the safety net.
+    if (result.record.leaseId !== null && typeof input.projectRoot === 'string' && input.projectRoot.length > 0) {
+        try {
+            tryAutoReleaseLease({
+                projectRoot: input.projectRoot,
+                sessionId: result.record.sessionId,
+                leaseId: result.record.leaseId
+            });
+        }
+        catch { // best-effort; release is async anyway
+            /* swallow */
+        }
+    }
+    return result;
+}
+/** Mark a record as disposed (reducer ran). */
+export function markDisposed(recordPath, now = () => new Date()) {
+    // Lock + re-read (see markCompleted).
+    return withFileLockSync(recordPath, () => {
+        const existing = readRecord(recordPath);
+        const next = {
+            ...existing,
+            disposed: true,
+            disposedAt: now().toISOString()
+        };
+        writeAtomic(recordPath, next);
+        return { record: next };
+    });
+}
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.1) — promote
+ * the record's `stage` field. Rejects unknown values with
+ * `INVALID_STAGE`; the LLM-side runner surfaces the error so the
+ * sub-agent can pick from the bounded enum in ./stage-enum.ts.
+ *
+ * Atomic via the same `withFileLockSync` lock as `appendHeartbeat` /
+ * `markCompleted`. `null` is a valid argument ("clear the stage")
+ * but unknown strings are not.
+ */
+export function setStage(input) {
+    if (input.stage !== null && !isStageLabel(input.stage)) {
+        const err = new Error(`stage must be one of the bounded stage labels (got: ${JSON.stringify(input.stage)})`);
+        err.code = 'INVALID_STAGE';
+        throw err;
+    }
+    return withFileLockSync(input.recordPath, () => {
+        const existing = readRecord(input.recordPath);
+        const next = {
+            ...existing,
+            stage: input.stage
+        };
+        writeAtomic(input.recordPath, next);
+        return { record: next };
+    });
+}
+/**
+ * Read a dispatch record with backward-compat defaults. Old records
+ * missing G5 / G6 fields are upgraded on read (no error, no overwrite).
+ */
+export function readRecord(recordPath) {
+    if (!existsSync(recordPath)) {
+        const err = new Error(`Dispatch record not found: ${recordPath}`);
+        err.code = 'RECORD_NOT_FOUND';
+        err.path = recordPath;
+        throw err;
+    }
+    const raw = readFileSync(recordPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const err = new Error(`Invalid dispatch record JSON: ${error.message}`);
+        err.code = 'INVALID_RECORD_JSON';
+        throw err;
+    }
+    return upgradeRecord(parsed);
+}
+/** Read multiple records from a list of paths. Tolerates missing files. */
+export function readRecords(paths) {
+    const out = [];
+    for (const p of paths) {
+        try {
+            out.push(readRecord(p));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'RECORD_NOT_FOUND') {
+                continue;
+            }
+            throw error;
+        }
+    }
+    return out;
+}
+function upgradeRecord(parsed) {
+    if (!isObject(parsed)) {
+        throw new Error('Dispatch record root must be an object');
+    }
+    const obj = parsed;
+    // Slice 2026-07-29-rid-prose-only-sweep Part 34: the version
+    // field is now the literal '3.1'. Legacy v2 and v3 records
+    // (version: 2 or version: 3) are accepted transparently and
+    // upgraded to v3.1 on read. The forward-compat check rejects
+    // records with an unknown version string (which would
+    // indicate either a much-older build or a much-newer one
+    // with a schema we have not implemented). v1 records
+    // (pre-audit-trail) must be regenerated.
+    const rawVersion = obj.version;
+    if (rawVersion !== '3.1' && rawVersion !== 3 && rawVersion !== 2 && rawVersion !== 1) {
+        throw new Error(`Dispatch record version mismatch: expected '3.1', 3, 2, or 1, got ${JSON.stringify(rawVersion)}. ` +
+            'The v1 → v3.1 migration is in-file; records from much older or newer builds must be regenerated.');
+    }
+    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 {
+        version: '3.1',
+        createdAt,
+        completedAt,
+        outcome,
+        artifactPaths,
+        disposed,
+        disposedAt,
+        role,
+        requestId,
+        sessionId,
+        prompt,
+        toolCall,
+        batchId,
+        heartbeats,
+        lastBeatAt,
+        status,
+        // 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
+    };
+}
+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');
+}
+export { isDispatchStatus, isOutcome };
+function writeAtomic(path, record) {
+    const dir = dirname(path);
+    // Slice 2026-06-23-audit-3rd #11: skip mkdirSync when the dir already
+    // exists (every heartbeat + every dispatch read-modify-write).
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    const safeTmp = resolve(dir, tmp.split(/[\\/]/).pop());
+    writeFileSync(safeTmp, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    renameSync(safeTmp, path);
+}