peaks-loop 4.0.0-beta.9 → 4.0.3

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

@@ -27,7 +27,9 @@
 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 '../filesystem/file-lock.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) {
@@ -42,7 +44,7 @@ export function writeInitialDispatchRecord(input) {
     const path = dispatchRecordPath(projectRoot, sessionId, requestId, now());
     const safePath = assertSafeDispatchRecordPath(path, projectRoot);
     const record = {
-        version: 2,
+        version: '3.1',
         createdAt: now().toISOString(),
         completedAt: null,
         outcome: 'no-execution',
@@ -61,7 +63,30 @@ export function writeInitialDispatchRecord(input) {
         batchId,
         heartbeats: [],
         lastBeatAt: null,
-        status: 'queued'
+        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
@@ -142,7 +167,15 @@ function unregisterActiveDispatch(input) {
     }
     if (input.recordPath in index) {
         index[input.recordPath] = { ...index[input.recordPath], status: input.status };
-        if (input.status === 'done' || input.status === 'failed' || input.status === 'cancelled' || input.status === 'no-execution') {
+        // 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()}`;
@@ -267,6 +300,109 @@ function mapStatusToAggregate(latest, current) {
     }
     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
@@ -302,6 +438,25 @@ export function markCompleted(input) {
             /* 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). */
@@ -318,6 +473,32 @@ export function markDisposed(recordPath, now = () => new Date()) {
         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).
@@ -363,6 +544,19 @@ function upgradeRecord(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');
@@ -384,7 +578,14 @@ function upgradeRecord(parsed) {
         ? obj.heartbeats.filter(isValidHeartbeat)
         : [];
     const lastBeatAt = typeof obj.lastBeatAt === 'string' ? obj.lastBeatAt : null;
-    const status = isDispatchStatus(obj.status) ? obj.status : 'no-execution';
+    // 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)
@@ -396,7 +597,7 @@ function upgradeRecord(parsed) {
         ? obj.batchId
         : 'legacy-batch';
     return {
-        version: 2,
+        version: '3.1',
         createdAt,
         completedAt,
         outcome,
@@ -411,7 +612,27 @@ function upgradeRecord(parsed) {
         batchId,
         heartbeats,
         lastBeatAt,
-        status
+        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) {
@@ -434,12 +655,21 @@ function isValidHeartbeat(v) {
 }
 function isHeartbeatStatus(v) {
     return (v === 'queued' || v === 'running' || v === 'finalizing' ||
-        v === 'done' || v === 'failed' || v === 'stale');
+        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');
+        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' ||

package/dist/services/dispatch/slice-dag.d.ts

@@ -79,3 +79,49 @@ export declare function sliceReadyToRun(dag: SliceDag, completed: ReadonlySet<st
 export declare function serializeDag(dag: SliceDag): string;
 /** SHA-256 hash of the serialized DAG. Stable across runs. */
 export declare function hashDag(dag: SliceDag): string;
+/**
+ * Knobs for wave planning + artifact-pass behaviour.
+ *
+ * - `maxConcurrency`: hard cap on how many slices a single Wave can hold.
+ *   Each topological level is chunked into Waves of at most this many
+ *   slice IDs (default 6 per `2026-07-28-24h-loop-audit.md` E direction).
+ * - `passArtifacts`: when true, each Wave's prompt is augmented with a
+ *   `WaveArtifact` envelope (contracts of preceding Waves). Default
+ *   false — the existing `runDag` ancestor-injection path already covers
+ *   per-slice contract coverage.
+ */
+export interface WaveOptions {
+    readonly maxConcurrency: number;
+    readonly passArtifacts: boolean;
+}
+/** Default wave options: 6 leaves per wave; artifact-pass off. */
+export declare const DEFAULT_MAX_CONCURRENCY = 6;
+export declare const DEFAULT_WAVE_OPTIONS: WaveOptions;
+/**
+ * Artifact envelope emitted when a Wave completes successfully.
+ *
+ * - `waveIndex`: sequential, 0-based across the whole plan.
+ * - `completedLeaves`: slice IDs that finished (`status: 'done'`). Failed
+ *    or cancelled leaves are NOT included.
+ * - `contracts`: per-slice public contract snapshot (sliceId → record).
+ *    Stored verbatim so a downstream Wave can re-inject this without
+ *    re-reading the disk-side contract store.
+ * - `passedAt`: ISO timestamp of Wave completion (caller-supplied to keep
+ *    the surface pure).
+ */
+export interface WaveArtifact {
+    readonly waveIndex: number;
+    readonly completedLeaves: readonly string[];
+    readonly contracts: Readonly<Record<string, unknown>>;
+    readonly passedAt: string;
+}
+/**
+ * A single dispatch Wave. Holds the slice IDs that must execute together,
+ * respecting `WaveOptions.maxConcurrency`. Waves are emitted in
+ * topological order; downstream consumers may treat `waveIndex` as a
+ * monotonic cursor.
+ */
+export interface Wave {
+    readonly waveIndex: number;
+    readonly slices: readonly string[];
+}

package/dist/services/dispatch/slice-dag.js

@@ -236,3 +236,9 @@ export function serializeDag(dag) {
 export function hashDag(dag) {
     return createHash('sha256').update(serializeDag(dag)).digest('hex');
 }
+/** Default wave options: 6 leaves per wave; artifact-pass off. */
+export const DEFAULT_MAX_CONCURRENCY = 6;
+export const DEFAULT_WAVE_OPTIONS = {
+    maxConcurrency: DEFAULT_MAX_CONCURRENCY,
+    passArtifacts: false
+};

package/dist/services/dispatch/stage-enum.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 — bounded stage
+ * vocabulary.
+ *
+ * Why a bounded enum (not a free-form string):
+ *   - a free-form `stage` recreates the `note` field, which already
+ *     exists and did not solve visibility.
+ *   - the watch surface renders a stage label inline (`role 30%
+ *     (5s ago) [planning]`); an unbounded vocabulary would let typos
+ *     and near-duplicates spread across the swarm.
+ *   - the LLM-side runner can validate the stage at write time
+ *     (`setStage` rejects unknown values with `INVALID_STAGE`).
+ *
+ * The enum is intentionally small and stable. Adding a new stage is a
+ * deliberate code change (this file + the `setStage` validation) so a
+ * future user cannot accidentally flood the watch with `awaiting-coffee`
+ * or `idk`.
+ *
+ * `null` is NOT a stage — it is the absence of a stage. Records that
+ * have not yet been promoted carry `stage: null`; the watch surface
+ * renders no marker.
+ */
+export declare const STAGE_LABELS: readonly ["intake", "planning", "gathering", "analyzing", "writing", "testing", "reviewing", "finalizing"];
+export type StageLabel = (typeof STAGE_LABELS)[number];
+export declare const DEFAULT_STAGE_LABELS: readonly StageLabel[];
+export declare function isStageLabel(value: unknown): value is StageLabel;
+export declare function normalizeStage(value: string | null | undefined): StageLabel | null;

package/dist/services/dispatch/stage-enum.js

@@ -0,0 +1,48 @@
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 — bounded stage
+ * vocabulary.
+ *
+ * Why a bounded enum (not a free-form string):
+ *   - a free-form `stage` recreates the `note` field, which already
+ *     exists and did not solve visibility.
+ *   - the watch surface renders a stage label inline (`role 30%
+ *     (5s ago) [planning]`); an unbounded vocabulary would let typos
+ *     and near-duplicates spread across the swarm.
+ *   - the LLM-side runner can validate the stage at write time
+ *     (`setStage` rejects unknown values with `INVALID_STAGE`).
+ *
+ * The enum is intentionally small and stable. Adding a new stage is a
+ * deliberate code change (this file + the `setStage` validation) so a
+ * future user cannot accidentally flood the watch with `awaiting-coffee`
+ * or `idk`.
+ *
+ * `null` is NOT a stage — it is the absence of a stage. Records that
+ * have not yet been promoted carry `stage: null`; the watch surface
+ * renders no marker.
+ */
+export const STAGE_LABELS = [
+    'intake',
+    'planning',
+    'gathering',
+    'analyzing',
+    'writing',
+    'testing',
+    'reviewing',
+    'finalizing'
+];
+export const DEFAULT_STAGE_LABELS = STAGE_LABELS;
+export function isStageLabel(value) {
+    return typeof value === 'string' && STAGE_LABELS.includes(value);
+}
+export function normalizeStage(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (isStageLabel(trimmed))
+        return trimmed;
+    return null;
+}

package/dist/services/dispatch/startup-timeout.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S1 — startup-timeout service.
+ *
+ * Why a separate module (vs adding the logic inline to
+ * `dispatch-record-writer.ts`):
+ *   - the writer is the on-disk format owner; the eval logic is a small
+ *     pure function over a `DispatchRecord` snapshot.
+ *   - keeps the writer surface unchanged (no extra `markStartupTimeout`
+ *     method) so other consumers (heartbeat, watch, batch poller) do not
+ *     have to learn a new mutation API.
+ *   - a future `markStartupTimeout` writer helper, if added, would import
+ *     this module's STARTUP_OUTCOME / DEFAULT_STARTUP_BUDGET_MS so the
+ *     CLI help text and the eval share a single source of truth.
+ *
+ * Contract (see tests/unit/dispatch/startup-timeout.test.ts for the
+ * pinned assertions):
+ *
+ *   evaluateStartupTimeout(record, now, opts) → StartupTimeoutEvaluation
+ *
+ *     - `outcome: 'within-budget' | 'never-started' | 'unreadable'`
+ *     - `targetStatus: DispatchRecordStatus` — the status to write when
+ *       `marked === true`. Distinct from `stale` (heartbeat seen, gone
+ *       quiet) and from `no-execution` (the pre-slice silent default).
+ *     - `marked: boolean` — whether the caller should write
+ *       `targetStatus` to the record.
+ *     - `reason: string` — short human-readable rationale, rendered in
+ *       the watcher text line and in the dispatch envelope's
+ *       `notes[]`.
+ *
+ *   DEFAULT_STARTUP_BUDGET_MS = 60_000
+ *     - 1 order of magnitude above the measured 4–6s cold-start figure
+ *       from .peaks/memory/2026-07-28-sub-agent-visibility-issue.md
+ *     - well below the 5-minute heartbeat stale threshold so this
+ *       fires first
+ *     - configurable via opts.budgetMs
+ *
+ *   STARTUP_OUTCOME = { NEVER_STARTED: 'never-started', UNREADABLE:
+ *   'unreadable' }
+ *     - exported so the CLI help text, the watch command, and the
+ *       reader's legacy fallback all reference the same strings.
+ */
+import type { DispatchRecord, DispatchRecordStatus } from './dispatch-record-writer.js';
+/**
+ * Default budget: 60s. 1 order of magnitude above the measured 4–6s
+ * cold-start figure from .peaks/memory/2026-07-28-sub-agent-visibility-
+ * issue.md; well below the 5-min heartbeat stale threshold so this
+ * fires first.
+ */
+export declare const DEFAULT_STARTUP_BUDGET_MS = 60000;
+/**
+ * String constants for the new terminal statuses. Distinct from the
+ * pre-slice `stale` (heartbeat seen, then quiet) and `no-execution`
+ * (legacy silent fallback). These are added to the writer's
+ * `DispatchRecordStatus` union in the same slice; the constants here
+ * are the canonical source so the CLI help / watch / writer all
+ * reference the same strings.
+ */
+export declare const STARTUP_OUTCOME: {
+    readonly NEVER_STARTED: "never-started";
+    readonly UNREADABLE: "unreadable";
+};
+export type StartupTimeoutOutcome = 'within-budget' | 'never-started' | 'unreadable';
+export interface StartupTimeoutOptions {
+    /** Override the default 60s budget. */
+    readonly budgetMs?: number;
+    /**
+     * Test seam: when true, the record is treated as if its body is
+     * corrupt (status field unparseable). The function returns
+     * `{ outcome: 'unreadable', ... }` and recommends writing the
+     * `unreadable` status. The CLI never sets this; the read path does.
+     */
+    readonly corrupt?: boolean;
+}
+export interface StartupTimeoutEvaluation {
+    readonly outcome: StartupTimeoutOutcome;
+    readonly marked: boolean;
+    readonly targetStatus: DispatchRecordStatus;
+    readonly reason: string;
+    readonly ageMs: number;
+    readonly budgetMs: number;
+}
+/**
+ * Pure eval. Returns a typed triple; the caller decides whether to
+ * write `targetStatus` to the record.
+ */
+export declare function evaluateStartupTimeout(record: DispatchRecord, now?: () => Date, options?: StartupTimeoutOptions): StartupTimeoutEvaluation;

package/dist/services/dispatch/startup-timeout.js

@@ -0,0 +1,97 @@
+/**
+ * Default budget: 60s. 1 order of magnitude above the measured 4–6s
+ * cold-start figure from .peaks/memory/2026-07-28-sub-agent-visibility-
+ * issue.md; well below the 5-min heartbeat stale threshold so this
+ * fires first.
+ */
+export const DEFAULT_STARTUP_BUDGET_MS = 60_000;
+/**
+ * String constants for the new terminal statuses. Distinct from the
+ * pre-slice `stale` (heartbeat seen, then quiet) and `no-execution`
+ * (legacy silent fallback). These are added to the writer's
+ * `DispatchRecordStatus` union in the same slice; the constants here
+ * are the canonical source so the CLI help / watch / writer all
+ * reference the same strings.
+ */
+export const STARTUP_OUTCOME = {
+    NEVER_STARTED: 'never-started',
+    UNREADABLE: 'unreadable'
+};
+/**
+ * Pure eval. Returns a typed triple; the caller decides whether to
+ * write `targetStatus` to the record.
+ */
+export function evaluateStartupTimeout(record, now = () => new Date(), options = {}) {
+    const budgetMs = options.budgetMs ?? DEFAULT_STARTUP_BUDGET_MS;
+    const safeBudget = Number.isFinite(budgetMs) && budgetMs > 0 ? budgetMs : DEFAULT_STARTUP_BUDGET_MS;
+    const createdAt = parseIsoOrFallback(record.createdAt, now);
+    const ageMs = Math.max(0, now().getTime() - createdAt.getTime());
+    if (options.corrupt === true) {
+        return {
+            outcome: 'unreadable',
+            marked: true,
+            targetStatus: 'unreadable',
+            reason: `record body is corrupt (status field unparseable) at age ${ageMs}ms`,
+            ageMs,
+            budgetMs: safeBudget
+        };
+    }
+    // A record that already reached `running` (or beyond) is by definition
+    // not a startup-timeout candidate. `stale` (heartbeat seen, then
+    // quiet) is its own ladder; we do not reclassify it.
+    if (record.status === 'running' || record.status === 'finalizing') {
+        return {
+            outcome: 'within-budget',
+            marked: false,
+            targetStatus: record.status,
+            reason: `record is ${record.status} and not eligible for startup timeout`,
+            ageMs,
+            budgetMs: safeBudget
+        };
+    }
+    // A terminal record is not eligible either (the marker functions own
+    // the terminal transition; this evaluator is a read-only gate).
+    const TERMINAL = [
+        'done',
+        'failed',
+        'cancelled',
+        'no-execution',
+        'stale',
+        'never-started',
+        'unreadable'
+    ];
+    if (TERMINAL.includes(record.status)) {
+        return {
+            outcome: 'within-budget',
+            marked: false,
+            targetStatus: record.status,
+            reason: `record is terminal (${record.status}) and not eligible for startup timeout`,
+            ageMs,
+            budgetMs: safeBudget
+        };
+    }
+    if (ageMs < safeBudget) {
+        return {
+            outcome: 'within-budget',
+            marked: false,
+            targetStatus: record.status,
+            reason: `record age ${ageMs}ms is within ${safeBudget}ms startup budget`,
+            ageMs,
+            budgetMs: safeBudget
+        };
+    }
+    return {
+        outcome: 'never-started',
+        marked: true,
+        targetStatus: 'never-started',
+        reason: `record stayed ${record.status} for ${ageMs}ms (budget ${safeBudget}ms) without a first heartbeat`,
+        ageMs,
+        budgetMs: safeBudget
+    };
+}
+function parseIsoOrFallback(iso, now) {
+    const d = new Date(iso);
+    if (!Number.isNaN(d.getTime()))
+        return d;
+    return new Date(now().getTime());
+}