peaks-loop 4.0.29 → 4.0.30

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

@@ -0,0 +1,278 @@
+import type { SubAgentToolCall } from './sub-agent-dispatcher.js';
+/** G6.3 Heartbeat entry — single update written by a running sub-agent. */
+export interface Heartbeat {
+    readonly at: string;
+    readonly status: HeartbeatStatus;
+    readonly progress: number;
+    readonly note: string | null;
+}
+export type HeartbeatStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'stale' | 'cancelled' | 'no-execution' | 'never-started' | 'unreadable';
+export type DispatchRecordStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'no-execution' | 'stale' | 'never-started' | 'unreadable';
+export type DispatchOutcome = 'success' | 'failed' | 'timeout' | 'cancelled' | 'no-execution';
+/** G2+G5+G6 dispatch record schema (AC-26 + AC-34). */
+export interface DispatchRecord {
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 4.C: schema v3 makes
+     * `leaseId` a structurally required field (was `leaseId?: string | null`
+     * in v2). The v3 upgrade is a "fill in" migration: every dispatch
+     * writer knows its lease id at construction time (Part 2.C's
+     * --isolation worktree spawns it; non-isolation dispatches stamp
+     * `null`). Readers tolerate both v2 and v3 on disk (see
+     * `upgradeRecord`); the `?` was a Part 4.A ergonomic concession
+     * to keep 4 unit-test literal sites from breaking the build. v3
+     * moves the optional off the type and adds the field to the
+     * 4 literal sites in one pass.
+     *
+     * Slice 2026-07-29-worktree-l2-extended Part 7: schema v3.1 adds
+     * `isolationStartedAt: string | null` for the L4 isolation
+     * bridge (Part 8 container POC). It's the ISO timestamp of
+     * when the isolation mode was set up (e.g. when the worktree
+     * was spawned). `null` means the dispatch did not request
+     * isolation. The `version` field stays at 3 because the
+     * v3 → v3.1 transition is additive; the new field is
+     * defaulted to `null` on read so v3 records upgrade cleanly.
+     */
+    /**
+     * Phase A Task 8: schema bumped to v4.1.0 (additive). The bump
+     * is purely additive — new fields (`mode`, `vendor`,
+     * `autoCompactEvents`, `tokenUsage`) all default safely on
+     * read for legacy v4.0.0 / v3.2 / v3.1 / v3 / v2 / v1 records.
+     * No existing field semantics changed.
+     */
+    readonly version: '4.1.0';
+    readonly createdAt: string;
+    readonly completedAt: string | null;
+    readonly outcome: DispatchOutcome;
+    readonly artifactPaths: readonly string[];
+    readonly disposed: boolean;
+    readonly disposedAt: string | null;
+    readonly role: string;
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly prompt: string;
+    readonly toolCall: SubAgentToolCall;
+    /** G5 batch id (AC-27) — uuid-like opaque token grouping one batch. */
+    readonly batchId: string;
+    /** G6 fields (AC-34) — backward compat: defaults on read. */
+    readonly heartbeats: readonly Heartbeat[];
+    readonly lastBeatAt: string | null;
+    readonly status: DispatchRecordStatus;
+    readonly stage: string | null;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 3.A + Part 4.C: the
+     * worktree lease id stamped on this dispatch (via `peaks sub-agent
+     * dispatch --isolation worktree`). The release hook (see
+     * markCompleted + `peaks sub-agent heartbeat --status done`)
+     * reads this field to auto-call `peaks worktree release` when
+     * the sub-agent finalizes. `null` means the dispatch did not
+     * request isolation and no release will fire. Persisted for
+     * audit + idempotency so a re-read of an old record still
+     * surfaces the lease id even if the on-disk lease file has since
+     * been gc'd.
+     *
+     * v3 (Part 4.C) makes this structurally required. v2 records
+     * missing the field upgrade to `null` on read (see
+     * `upgradeRecord`).
+     */
+    readonly leaseId: string | null;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 7: ISO timestamp of
+     * when the isolation mode was set up. For `--isolation worktree`
+     * this is the moment `peaks worktree spawn` returned; for
+     * `--isolation container` (Part 8) it's when the container
+     * runtime reported the container as running. `null` when the
+     * dispatch did not request isolation. Lets the dashboard
+     * compute isolation duration (now - isolationStartedAt) without
+     * cross-referencing the metrics stream.
+     */
+    readonly isolationStartedAt: string | null;
+    /**
+     * Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.2 schema
+     * bump. One entry per pid the parent best-effort-killed during
+     * the service-shutdown phase of the merge-back pipeline (see
+     * src/services/dispatch/service-shutdown.ts). Empty array when
+     * the sub-agent did not register any services. The shape is the
+     * union of ServiceKillOutcome (skipped=false) and
+     * ServiceKillSkipped (skipped=true) — kept as a plain object
+     * here so the on-disk schema does not lock onto the helper's
+     * narrower union. The reader (merge-back-runner.ts) interprets
+     * each entry based on the `skipped` field.
+     */
+    readonly serviceKill: ReadonlyArray<{
+        readonly pid: number;
+        readonly name: string;
+        readonly signal: string;
+        readonly exitCode: number | null;
+        readonly skipped?: boolean;
+        readonly reason?: string;
+    }>;
+    /**
+     * Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.2 schema
+     * bump. Counts how many merge attempts the parent session has
+     * made against this dispatch's branch. The conflict-replay
+     * orchestrator bumps this on each retry (bounded to ONE re-dispatch
+     * per merge attempt; multi-conflict cases escalate). Persisted so
+     * the dashboard can render the retry count without replaying the
+     * merge transcript.
+     */
+    readonly mergeBackAttempts: number;
+    /**
+     * Slice 4.0.8 RD §4 D4c (presence-lease-graph): the workflow id +
+     * graph node id + graphRef this dispatch is bound to. Persisted
+     * directly in the dispatch record (NOT in a sidecar) so the
+     * envelope-writer `markCompleted` can auto-transition the bound
+     * graph node to `envelope-received` with `ackStatus=pending` in
+     * one protected update.
+     *
+     * The schema bump from `3.2 → 4.0.0` is BREAKING in the sense
+     * that the literal type is narrowed. The optional `?` keeps back-
+     * compat for old records that pre-date the binding (the
+     * `upgradeRecord` reader defaults them to `null`).
+     */
+    readonly workflowId: string | null;
+    readonly graphNodeId: string | null;
+    readonly graphRef: string | null;
+    /**
+     * Phase A Task 8: dispatch execution mode. `in-process` is the
+     * current behavior (LLM-side runner, no separate OS process).
+     * `detached` is the new path: `peaks sub-agent dispatch --mode
+     * detached` spawns a real child OS process running a different
+     * LLM vendor (claude / codex / copilot) and reports back via
+     * the dispatch record. v4.1.0 is the additive bump; legacy v4.0.0
+     * records upgrade to `in-process` on read.
+     */
+    readonly mode: 'in-process' | 'detached';
+    /**
+     * Phase A Task 8: vendor id when `mode='detached'`. `null` when
+     * the dispatch is in-process. Reserved for future use; current
+     * detached sub-agents use `claude` but the schema also accepts
+     * `codex` and `copilot` for the vendor-neutral adapter layer.
+     */
+    readonly vendor: 'claude' | 'codex' | 'copilot' | null;
+    /**
+     * Phase A Task 8: G8 autoCompact events accumulated by the child
+     * LLM during a detached run. Each event records the threshold
+     * that fired (0.85 = first warning, 0.95 = second warning) plus
+     * token counts before/after. Empty for in-process dispatches
+     * and for legacy records upgraded on read.
+     */
+    readonly autoCompactEvents: ReadonlyArray<{
+        readonly at: number;
+        readonly threshold: '0.85' | '0.95';
+        readonly tokensBefore: number;
+        readonly tokensAfter: number;
+        readonly scratchFile?: string;
+    }>;
+    /**
+     * Phase A Task 8: G8 token-usage accounting for detached sub-agents.
+     * Detached runs have "unlimited spend but recorded" semantics —
+     * the cost is recorded for audit but not enforced. `null` when
+     * the dispatch is in-process (no detached accounting) or for
+     * legacy records upgraded on read.
+     */
+    readonly tokenUsage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+        readonly totalCostUsd?: number;
+    } | null;
+}
+/** Input for the initial write. */
+export type WriteInitialDispatchInput = {
+    projectRoot: string;
+    sessionId: string;
+    requestId: string;
+    role: string;
+    prompt: string;
+    toolCall: SubAgentToolCall;
+    batchId: string;
+    /** Override the timestamp (testing). */
+    now?: () => Date;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 3.A: the worktree
+     * lease id this dispatch owns (set by `peaks sub-agent dispatch
+     * --isolation worktree`). Persisted so the finalize-time release
+     * hook in `markCompleted` can fire even after the dispatch
+     * process exits. Optional; absent when the dispatch did not
+     * request isolation.
+     */
+    leaseId?: string | null;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 7: ISO timestamp
+     * when the isolation mode was set up. Optional on the input
+     * (defaults to `null`); dispatch-commands.ts passes the spawn
+     * time when `--isolation` is requested.
+     */
+    isolationStartedAt?: string | null;
+    /**
+     * Slice 4.0.8: workflow graph binding for the dispatch. Defaults
+     * to `null` so a non-graph dispatch (legacy CLI flow, ad-hoc
+     * dispatch) still writes a v4.0.0 record.
+     */
+    workflowId?: string | null;
+    graphNodeId?: string | null;
+    graphRef?: string | null;
+    /**
+     * Phase A Task 8: dispatch execution mode. Default `'in-process'`
+     * preserves the current LLM-side runner behavior. `'detached'`
+     * triggers the new real-OS-process path via
+     * `peaks sub-agent dispatch --mode detached`.
+     */
+    mode?: 'in-process' | 'detached';
+    /**
+     * Phase A Task 8: vendor id when `mode='detached'`. Required by
+     * the adapter layer to know which CLI / runtime to spawn. The
+     * schema accepts the three vendors peaks-loop has adapters for
+     * (claude / codex / copilot). Ignored when `mode='in-process'`.
+     */
+    vendor?: 'claude' | 'codex' | 'copilot';
+    /**
+     * Phase A Task 8: G8 autoCompact events accumulated by the child
+     * LLM. Optional on input — most dispatches start with an empty
+     * array and the detached runner appends events as they fire.
+     */
+    autoCompactEvents?: Array<{
+        at: number;
+        threshold: '0.85' | '0.95';
+        tokensBefore: number;
+        tokensAfter: number;
+        scratchFile?: string;
+    }>;
+    /**
+     * Phase A Task 8: G8 token-usage accounting. Detached runs
+     * record spend for audit (unlimited, but persisted). Optional
+     * on input; the detached runner fills this in as it streams
+     * usage from the vendor API.
+     */
+    tokenUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalCostUsd?: number;
+    };
+};
+/** Heartbeat write input. */
+export type AppendHeartbeatInput = {
+    recordPath: string;
+    status: HeartbeatStatus;
+    progress: number;
+    note?: string;
+    now?: () => Date;
+};
+/** Lifecycle transition input. */
+export type LifecycleInput = {
+    recordPath: string;
+    outcome: DispatchOutcome;
+    status: DispatchRecordStatus;
+    artifactPaths?: readonly string[];
+    now?: () => Date;
+    /**
+     * Slice 2026-06-23-audit-4th #A4: trusted project root. Required
+     * so the active-dispatches index can be updated without deriving
+     * the root from the recordPath (the same anti-pattern that
+     * audit-3rd #1 fixed for heartbeat). The CLI / LLM-side runner
+     * passes this from `--project` or `process.cwd()`.
+     */
+    projectRoot?: string;
+};
+export declare const MAX_PROMPT_BYTES: number;
+export declare const NOTE_MAX_CHARS = 200;
+export declare const MS_PER_DAY: number;

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

@@ -0,0 +1,15 @@
+/**
+ * PRD-002b slice 2 — extract dispatch-record size budgets (max-prompt
+ * bytes, note truncation cap) + time-math primitives so the
+ * no-magic-numbers rule stops flagging the writer pipeline.
+ */
+const BYTES_PER_KB = 1024;
+const MAX_PROMPT_KB = 256;
+export const MAX_PROMPT_BYTES = MAX_PROMPT_KB * BYTES_PER_KB;
+export const NOTE_MAX_CHARS = 200;
+const MS_PER_SECOND = 1_000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+const HOURS_PER_DAY = 24;
+export const MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
+const REDACTION_MAX_SCAN_DEPTH = 20;

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

@@ -0,0 +1,5 @@
+import type { DispatchOutcome, DispatchRecord, DispatchRecordStatus } from './dispatch-record-types.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

@@ -0,0 +1,230 @@
+export function upgradeRecord(parsed) {
+    if (!isObject(parsed)) {
+        throw new Error('Dispatch record root must be an object');
+    }
+    const obj = parsed;
+    // Slice 4.0.8: 3.2 → 4.0.0 schema bump. Phase A Task 8: 4.0.0 → 4.1.0
+    // (additive). The literal type narrows to '4.1.0' but legacy v4.0.0 /
+    // 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) {
+        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
+    };
+}
+/**
+ * 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.
+ */
+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');
+}
+export { isDispatchStatus, isOutcome };