peaks-loop 4.0.53 → 4.1.0

package/dist/services/dispatch/await-batch-helpers.js

@@ -0,0 +1,206 @@
+/**
+ * Slice `strict-remediation-abc` (C wave 1, leaf `c1w1-await-batch`) — the
+ * per-slot half of `./await-batch.ts`, moved VERBATIM so that `awaitBatch`
+ * stops carrying a 155-line / complexity-40 body (`max-lines-per-function` is
+ * severity 2) and that module clears the 300 raw-line cap.
+ *
+ * What lives here: the slot table (one mutable entry per dispatch index), the
+ * one-tick observation pass, the no-progress watchdog predicate, the poll sleep
+ * and the per-dispatch result / note rendering. What stayed in
+ * `./await-batch.ts`: the public types, the options and budget resolution, the
+ * batch-outcome rules, the fail-fast de-escalation and the poll loop itself.
+ *
+ * No body here was rewritten. The predicates, the branch order, the `??`
+ * fallbacks, the `now()` call sites and the `readOutcome` / `readRecord` call
+ * counts are exactly the ones `awaitBatch` had before the move, because this is
+ * the READER side of the sub-agent dispatch-record contract and its behaviour
+ * is pinned from the outside by
+ * `tests/unit/services/dispatch/sub-agent-dispatchers.test.ts` (the
+ * stale-to-timeout mapping, the per-IDE note shapes, corrupt record → timeout)
+ * and by `tests/unit/cli/commands/sub-agent-await-commands.test.ts` (the CLI
+ * envelope over real record files).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * Read a dispatch record's `status` and `outcome` off disk. Missing or
+ * unreadable (including unparseable JSON) reads as `{ null, null }`, which is
+ * what keeps a corrupt record a timeout rather than a thrown error.
+ */
+export function defaultReadOutcome(recordPath) {
+    if (!recordPath)
+        return { status: null, outcome: null };
+    try {
+        if (!existsSync(recordPath))
+            return { status: null, outcome: null };
+        const raw = readFileSync(recordPath, 'utf8');
+        const obj = JSON.parse(raw);
+        const status = typeof obj.status === 'string' ? obj.status : null;
+        const outcome = typeof obj.outcome === 'string' ? obj.outcome : null;
+        return { status, outcome };
+    }
+    catch {
+        return { status: null, outcome: null };
+    }
+}
+const DEFAULT_POLL_INTERVAL_MS = 50;
+/**
+ * Seed one slot per record path, all of them `timeout` until a tick proves
+ * otherwise, plus the progress map the no-progress watchdog runs off.
+ */
+export function createSlotTable(recordPaths, startedAt) {
+    const slots = new Map();
+    for (let i = 0; i < recordPaths.length; i += 1) {
+        const recordPath = recordPaths[i] ?? '';
+        slots.set(i, {
+            recordPath,
+            status: 'timeout',
+            note: null,
+            finishedAt: null,
+            lastProgress: 0
+        });
+    }
+    // Track last observed progress per slot to power the no-progress
+    // watchdog. The watchdog advances on any per-tick observation
+    // change in the slot's progress hint (read from the file's
+    // `progress` field when available, else from the `heartbeats`
+    // array's last entry).
+    const lastProgressAt = new Map();
+    for (const [idx] of slots) {
+        lastProgressAt.set(idx, startedAt);
+    }
+    return { startedAt, slots, lastProgressAt };
+}
+/**
+ * Map an on-disk status onto the per-dispatch status union, or `null` when the
+ * dispatch has not reached a terminal state yet.
+ *
+ * The default readOutcome returns the on-disk `status`. We map
+ * a small set of values to the per-dispatch status union.
+ * Slice 2026-07-30-nightshift: also capture the optional
+ * `outcome` field so the per-IDE note can surface the human
+ * reason (e.g. "mock failure at leaf-2"). The `outcome` is read
+ * alongside the `status` via `readRecord` and surfaced into
+ * `slot.note` for failed dispatches; for done/cancelled the
+ * note is left null (matches the pre-nightshift contract).
+ * `stale` is mapped to `timeout` so the per-IDE note preserves
+ * the human-readable reason (cursor / claude-code both surface
+ * `stale` on the wire but the BatchResult.status union only
+ * knows `timeout`).
+ */
+function mapTerminalStatus(outcome, recordOutcome) {
+    if (outcome === 'done' || outcome === 'success') {
+        return { status: 'done', note: null };
+    }
+    if (outcome === 'failed') {
+        return { status: 'failed', note: recordOutcome ?? null };
+    }
+    if (outcome === 'cancelled') {
+        return { status: 'cancelled', note: null };
+    }
+    if (outcome === 'stale') {
+        return { status: 'timeout', note: 'stale' };
+    }
+    // Any other status (queued / running / finalizing /
+    // never-started / unreadable) means the dispatch has not
+    // reached a terminal state yet.
+    return null;
+}
+/**
+ * One observation pass over the pending slots. Returns the `allDone` the loop
+ * branched on: `true` only when every slot reached a terminal state.
+ */
+export function pollSlotsOnce(table, readOutcome, readRecord, now) {
+    let allDone = true;
+    for (const [idx, slot] of table.slots) {
+        if (slot.finishedAt !== null)
+            continue;
+        const outcome = readOutcome(slot.recordPath);
+        if (outcome === null) {
+            allDone = false;
+            continue;
+        }
+        const terminal = mapTerminalStatus(outcome, readRecord(slot.recordPath).outcome);
+        if (terminal === null) {
+            allDone = false;
+            continue;
+        }
+        slot.status = terminal.status;
+        slot.note = terminal.note;
+        slot.finishedAt = now();
+        table.lastProgressAt.set(idx, now());
+    }
+    return allDone;
+}
+/**
+ * No-progress watchdog: every slot has been without observable
+ * progress for `noProgressBudget`, and there is at least one slot.
+ */
+export function hasNoProgress(table, now, noProgressBudget) {
+    const allStalled = Array.from(table.slots.entries()).every(([idx, slot]) => slot.finishedAt !== null ||
+        now() - (table.lastProgressAt.get(idx) ?? table.startedAt) >= noProgressBudget);
+    return allStalled && table.slots.size > 0;
+}
+/** Sleep a tick on the resolved scheduler. */
+export function sleepTick(schedule) {
+    return new Promise((resolveSleep) => schedule(() => resolveSleep(), DEFAULT_POLL_INTERVAL_MS));
+}
+/**
+ * The per-IDE note for one slot.
+ *
+ * Slice 2026-07-30-nightshift: the per-IDE note construction is
+ * rewritten to match the 1.4 dogfood contract:
+ *   - claude-code (no notePrefix): note = slot.note (the raw
+ *     outcome, or null when done/cancelled)
+ *   - other IDEs (notePrefix set):
+ *       - on timeout:                  `${notePrefix} (timeout)`
+ *       - on failed (with outcome):    `${notePrefix} — ${outcome}`
+ *       - on failed (no outcome):      `${notePrefix}`
+ *       - on done / cancelled:         `${notePrefix}`
+ */
+function resolveSlotNote(slot, baseNote) {
+    let note;
+    if (baseNote === null) {
+        // Claude-Code path: surface the raw outcome (no per-IDE prefix).
+        note = slot.note;
+    }
+    else if (slot.finishedAt === null) {
+        // Timed-out slot: keep the legacy ` (timeout)` suffix.
+        note = `${baseNote} (timeout)`;
+    }
+    else if (slot.status === 'failed' && slot.note !== null && slot.note.length > 0) {
+        // Failed with a human reason: `${notePrefix} — ${outcome}`.
+        note = `${baseNote} — ${slot.note}`;
+    }
+    else if (slot.note !== null && slot.note.length > 0) {
+        // Non-failed terminal slot with a non-null note (e.g. cursor /
+        // claude-code `stale` → status=timeout, note='stale'):
+        // `${notePrefix} — ${note}` so the human reason is surfaced.
+        // Slice 2026-07-30-nightshift: previously this branch dropped
+        // the slot's note entirely (the bare-prefix else swallowed
+        // it). The 1.4 dogfood for `stale` flips the contract.
+        note = `${baseNote} — ${slot.note}`;
+    }
+    else {
+        // Done / cancelled / failed-without-reason: bare prefix.
+        note = baseNote;
+    }
+    return note;
+}
+/**
+ * Build the per-dispatch results in dispatchIndex order.
+ */
+export function buildBatchResults(table, notePrefix, effectiveTimeoutMs) {
+    const baseNote = notePrefix ?? null;
+    return Array.from(table.slots.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([idx, slot]) => {
+        const finishedAt = slot.finishedAt ?? table.startedAt + effectiveTimeoutMs;
+        return {
+            dispatchIndex: idx,
+            recordPath: slot.recordPath,
+            status: slot.status,
+            durationMs: finishedAt - table.startedAt,
+            note: resolveSlotNote(slot, baseNote)
+        };
+    });
+}

package/dist/services/dispatch/await-batch.d.ts

@@ -1,3 +1,52 @@
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S4 — unified batch
+ * awaiter.
+ *
+ * Pre-S4, `awaitClaudeCodeBatch` and `pollDispatchRecords` were two
+ * near-identical poll loops with two subtle differences:
+ *   - awaitClaudeCodeBatch clamped with `Math.min(deadline, 120_000)`
+ *   - pollDispatchRecords clamped with
+ *     `Math.min(Math.max(deadline, 0), 120_000)`
+ * and different default-fallback sources. The PRD R4 records the
+ * resulting failure shape: a fix applied to one path did not
+ * propagate to the other (per
+ * .peaks/memory/2026-07-26-peaks-code-concurrent-subagent-coordination.md).
+ *
+ * This file is the single implementation. Both `awaitClaudeCodeBatch`
+ * and `pollDispatchRecords` (kept exported for back-compat with the
+ * existing tests) thin-wrap this.
+ *
+ * S4 also closes the silent-timeout return:
+ *   - the result shape now includes a typed `outcome` field that is
+ *     one of 'completed' | 'timed-out' | 'clamped' | 'no-progress'.
+ *     A caller that asks for `timeoutMs: 600_000` and the loop clamps
+ *     to the hard cap sees `outcome: 'clamped'` and the requested /
+ *     effective budgets on the result.
+ *   - the loop no longer returns a success-shaped result on full
+ *     timeout. A timed-out slot still appears in the per-dispatch
+ *     results array, but the *batch* outcome is `timed-out`.
+ *   - the no-progress watchdog (a new option) raises the `no-progress`
+ *     outcome before the full deadline elapses if a bounded window
+ *     passes with no observable progress (e.g. a slot's `lastBeatAt`
+ *     has not advanced).
+ *
+ * The de-escalation flag is `PEAKS_DISPATCH_DISABLE_FAILFAST` (read
+ * from process.env at module load). When set, the loop falls back to
+ * the pre-S4 silent return so a stuck session can be unblocked by
+ * flipping the env var rather than rebuilding.
+ *
+ * Slice `strict-remediation-abc` (C wave 1, leaf `c1w1-await-batch`): the
+ * per-slot half of the loop — record reader, slot table, one-tick observation
+ * pass, no-progress predicate, poll sleep, result/note rendering — moved
+ * VERBATIM into `./await-batch-helpers.ts`. `awaitBatch` was 155 lines at
+ * complexity 40, so it held a `max-lines-per-function` error AND a `complexity`
+ * warning; that pairing is why no declaration hoist could shorten this file.
+ * The bodies did not change. `awaitBatch` keeps this export path because
+ * `tests/unit/services/dispatch/sub-agent-dispatcher-timeouts.test.ts` stubs
+ * `~/src/services/dispatch/await-batch.js` by path; the budget and outcome
+ * rules stay here because they are what the public types above describe.
+ */
+import { type AwaitBatchSlotResult } from './await-batch-helpers.js';
 export type AwaitBatchOutcome = 'completed' | 'timed-out' | 'clamped' | 'no-progress';
 export interface AwaitBatchOptions {
     /** Caller-supplied per-IDE default when no timeoutMs is provided. */
@@ -47,13 +96,7 @@ export interface AwaitBatchOptions {
 }
 export interface AwaitBatchResult {
     /** Per-dispatch slot, in dispatchIndex order. */
-    readonly results: ReadonlyArray<{
-        readonly dispatchIndex: number;
-        readonly recordPath: string;
-        readonly status: 'done' | 'failed' | 'cancelled' | 'timeout';
-        readonly durationMs: number;
-        readonly note: string | null;
-    }>;
+    readonly results: ReadonlyArray<AwaitBatchSlotResult>;
     /** Batch-level outcome — distinct, machine-readable. */
     readonly outcome: AwaitBatchOutcome;
     /** What the caller asked for (or the IDE default, when omitted). */

package/dist/services/dispatch/await-batch.js

@@ -34,11 +34,21 @@
  * from process.env at module load). When set, the loop falls back to
  * the pre-S4 silent return so a stuck session can be unblocked by
  * flipping the env var rather than rebuilding.
+ *
+ * Slice `strict-remediation-abc` (C wave 1, leaf `c1w1-await-batch`): the
+ * per-slot half of the loop — record reader, slot table, one-tick observation
+ * pass, no-progress predicate, poll sleep, result/note rendering — moved
+ * VERBATIM into `./await-batch-helpers.ts`. `awaitBatch` was 155 lines at
+ * complexity 40, so it held a `max-lines-per-function` error AND a `complexity`
+ * warning; that pairing is why no declaration hoist could shorten this file.
+ * The bodies did not change. `awaitBatch` keeps this export path because
+ * `tests/unit/services/dispatch/sub-agent-dispatcher-timeouts.test.ts` stubs
+ * `~/src/services/dispatch/await-batch.js` by path; the budget and outcome
+ * rules stay here because they are what the public types above describe.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { buildBatchResults, createSlotTable, defaultReadOutcome, hasNoProgress, pollSlotsOnce, sleepTick } from './await-batch-helpers.js';
 const DEFAULT_HARD_CAP_MS = 120_000;
 const DEFAULT_NO_PROGRESS_MS = 60_000;
-const DEFAULT_POLL_INTERVAL_MS = 50;
 /**
  * Fail-fast de-escalation: the env var is read once at module load
  * (matches the pre-S4 env-var-loading semantics for `peaks`
@@ -55,218 +65,111 @@ const FAILFAST_DISABLED = (() => {
  */
 export async function awaitBatch(dispatchCount, recordPaths, timeoutMs, options = { defaultTimeoutMs: 60_000 }) {
     if (dispatchCount <= 0 || recordPaths.length === 0) {
-        const requested = timeoutMs ?? options.defaultTimeoutMs;
-        return {
-            results: [],
-            outcome: 'completed',
-            requestedTimeoutMs: requested,
-            effectiveTimeoutMs: 0,
-            hardCapMs: options.hardCapMs ?? DEFAULT_HARD_CAP_MS
-        };
-    }
-    const hardCap = options.hardCapMs ?? DEFAULT_HARD_CAP_MS;
-    const requested = timeoutMs ?? options.defaultTimeoutMs;
-    // S4 (AC-3.2) — surface the clamp. A caller-supplied timeout above
-    // the hard cap is reported as `clamped`; the effective budget is
-    // what the loop actually waited.
-    const requestedClamped = requested > hardCap;
-    const effective = Math.min(Math.max(requested, 0), hardCap);
-    const noProgressBudget = options.noProgressMs ?? DEFAULT_NO_PROGRESS_MS;
-    const now = options.now ?? (() => Date.now());
-    const schedule = options.schedule ?? ((cb, ms) => {
-        const t = setTimeout(cb, ms);
-        t.unref?.();
-        return t;
-    });
-    const readOutcome = options.readOutcome ?? ((p) => defaultReadOutcome(p).status);
-    const readRecord = options.readRecord ?? defaultReadOutcome;
-    const startedAt = now();
-    const slots = new Map();
-    for (let i = 0; i < recordPaths.length; i += 1) {
-        const recordPath = recordPaths[i] ?? '';
-        slots.set(i, {
-            recordPath,
-            status: 'timeout',
-            note: null,
-            finishedAt: null,
-            lastProgress: 0
-        });
-    }
-    // Track last observed progress per slot to power the no-progress
-    // watchdog. The watchdog advances on any per-tick observation
-    // change in the slot's progress hint (read from the file's
-    // `progress` field when available, else from the `heartbeats`
-    // array's last entry).
-    const lastProgressAt = new Map();
-    for (const [idx] of slots) {
-        lastProgressAt.set(idx, startedAt);
+        return emptyBatchResult(timeoutMs, options);
     }
+    const budgets = resolveBudgets(timeoutMs, options);
+    const seams = resolveSeams(options);
+    const startedAt = seams.now();
+    const table = createSlotTable(recordPaths, startedAt);
     let batchOutcome = 'completed';
-    while (slots.size > 0 && now() - startedAt < effective) {
-        let allDone = true;
-        for (const [idx, slot] of slots) {
-            if (slot.finishedAt !== null)
-                continue;
-            const outcome = readOutcome(slot.recordPath);
-            if (outcome === null) {
-                allDone = false;
-                continue;
-            }
-            // The default readOutcome returns the on-disk `status`. We map
-            // a small set of values to the per-dispatch status union.
-            // Slice 2026-07-30-nightshift: also capture the optional
-            // `outcome` field so the per-IDE note can surface the human
-            // reason (e.g. "mock failure at leaf-2"). The `outcome` is read
-            // alongside the `status` via `readRecord` and surfaced into
-            // `slot.note` for failed dispatches; for done/cancelled the
-            // note is left null (matches the pre-nightshift contract).
-            // `stale` is mapped to `timeout` so the per-IDE note preserves
-            // the human-readable reason (cursor / claude-code both surface
-            // `stale` on the wire but the BatchResult.status union only
-            // knows `timeout`).
-            const record = readRecord(slot.recordPath);
-            if (outcome === 'done' || outcome === 'success') {
-                slot.status = 'done';
-                slot.note = null;
-                slot.finishedAt = now();
-                lastProgressAt.set(idx, now());
-            }
-            else if (outcome === 'failed') {
-                slot.status = 'failed';
-                slot.note = record.outcome ?? null;
-                slot.finishedAt = now();
-                lastProgressAt.set(idx, now());
-            }
-            else if (outcome === 'cancelled') {
-                slot.status = 'cancelled';
-                slot.note = null;
-                slot.finishedAt = now();
-                lastProgressAt.set(idx, now());
-            }
-            else if (outcome === 'stale') {
-                slot.status = 'timeout';
-                slot.note = 'stale';
-                slot.finishedAt = now();
-                lastProgressAt.set(idx, now());
-            }
-            else {
-                // Any other status (queued / running / finalizing /
-                // never-started / unreadable) means the dispatch has not
-                // reached a terminal state yet.
-                allDone = false;
-            }
-        }
-        if (allDone)
+    while (table.slots.size > 0 && seams.now() - startedAt < budgets.effective) {
+        if (pollSlotsOnce(table, seams.readOutcome, seams.readRecord, seams.now)) {
             break;
-        // No-progress watchdog: if every slot has been without observable
-        // progress for `noProgressBudget`, escalate.
-        if (now() - startedAt < effective) {
-            const allStalled = Array.from(slots.entries()).every(([idx, slot]) => slot.finishedAt !== null || (now() - (lastProgressAt.get(idx) ?? startedAt)) >= noProgressBudget);
-            if (allStalled && slots.size > 0) {
+        }
+        // No-progress watchdog: only while the effective budget still holds.
+        if (seams.now() - startedAt < budgets.effective) {
+            if (hasNoProgress(table, seams.now, budgets.noProgressBudget)) {
                 batchOutcome = 'no-progress';
                 break;
             }
         }
         // Sleep a tick.
-        await new Promise((resolveSleep) => schedule(() => resolveSleep(), DEFAULT_POLL_INTERVAL_MS));
-    }
-    // Post-loop batch outcome:
-    //   - `completed` — every slot reached a terminal state
-    //   - `timed-out` — at least one slot is still pending and the
-    //     effective budget elapsed
-    //   - `clamped` — the caller's `requestedTimeoutMs` exceeded the
-    //     hard cap (AC-3.2). The loop still ran the effective budget;
-    //     `clamped` takes precedence over `timed-out` because the
-    //     caller specifically asked for more than the cap and the
-    //     caller needs to know the cap was applied (the timeout is
-    //     secondary information).
-    //   - `no-progress` — the watchdog fired (AC-3.4)
-    if (batchOutcome === 'completed' && slots.size > 0) {
-        const allReached = Array.from(slots.values()).every((s) => s.finishedAt !== null);
-        if (!allReached) {
-            batchOutcome = requestedClamped ? 'clamped' : 'timed-out';
-        }
-    }
-    if (batchOutcome === 'completed' && requestedClamped) {
-        batchOutcome = 'clamped';
+        await sleepTick(seams.schedule);
     }
+    batchOutcome = resolveBatchOutcome(batchOutcome, table.slots, budgets.requestedClamped);
     // Build the per-dispatch results in dispatchIndex order.
-    // Slice 2026-07-30-nightshift: the per-IDE note construction is
-    // rewritten to match the 1.4 dogfood contract:
-    //   - claude-code (no notePrefix): note = slot.note (the raw
-    //     outcome, or null when done/cancelled)
-    //   - other IDEs (notePrefix set):
-    //       - on timeout:                  `${notePrefix} (timeout)`
-    //       - on failed (with outcome):    `${notePrefix} — ${outcome}`
-    //       - on failed (no outcome):      `${notePrefix}`
-    //       - on done / cancelled:         `${notePrefix}`
-    const results = Array.from(slots.entries())
-        .sort(([a], [b]) => a - b)
-        .map(([idx, slot]) => {
-        const finishedAt = slot.finishedAt ?? startedAt + effective;
-        const baseNote = options.notePrefix ?? null;
-        let note;
-        if (baseNote === null) {
-            // Claude-Code path: surface the raw outcome (no per-IDE prefix).
-            note = slot.note;
-        }
-        else if (slot.finishedAt === null) {
-            // Timed-out slot: keep the legacy ` (timeout)` suffix.
-            note = `${baseNote} (timeout)`;
-        }
-        else if (slot.status === 'failed' && slot.note !== null && slot.note.length > 0) {
-            // Failed with a human reason: `${notePrefix} — ${outcome}`.
-            note = `${baseNote} — ${slot.note}`;
-        }
-        else if (slot.note !== null && slot.note.length > 0) {
-            // Non-failed terminal slot with a non-null note (e.g. cursor /
-            // claude-code `stale` → status=timeout, note='stale'):
-            // `${notePrefix} — ${note}` so the human reason is surfaced.
-            // Slice 2026-07-30-nightshift: previously this branch dropped
-            // the slot's note entirely (the bare-prefix else swallowed
-            // it). The 1.4 dogfood for `stale` flips the contract.
-            note = `${baseNote} — ${slot.note}`;
-        }
-        else {
-            // Done / cancelled / failed-without-reason: bare prefix.
-            note = baseNote;
-        }
-        return {
-            dispatchIndex: idx,
-            recordPath: slot.recordPath,
-            status: slot.status,
-            durationMs: finishedAt - startedAt,
-            note
-        };
-    });
+    const results = buildBatchResults(table, options.notePrefix, budgets.effective);
     // Fail-fast de-escalation: when the env var is set, surface the
     // typed outcome but do not let it influence the per-dispatch
     // results. This preserves the pre-S4 silent-return shape so a
     // stuck session can be unblocked by flipping the flag.
-    if (FAILFAST_DISABLED && (batchOutcome === 'timed-out' || batchOutcome === 'no-progress' || batchOutcome === 'clamped')) {
-        batchOutcome = 'completed';
-    }
+    batchOutcome = deescalateOutcome(batchOutcome, FAILFAST_DISABLED);
     return {
         results,
         outcome: batchOutcome,
+        requestedTimeoutMs: budgets.requested,
+        effectiveTimeoutMs: budgets.effective,
+        hardCapMs: budgets.hardCap
+    };
+}
+/** The zero-slot return: nothing to poll, so nothing was waited. */
+function emptyBatchResult(timeoutMs, options) {
+    const requested = timeoutMs ?? options.defaultTimeoutMs;
+    return {
+        results: [],
+        outcome: 'completed',
         requestedTimeoutMs: requested,
-        effectiveTimeoutMs: effective,
-        hardCapMs: hardCap
+        effectiveTimeoutMs: 0,
+        hardCapMs: options.hardCapMs ?? DEFAULT_HARD_CAP_MS
     };
 }
-function defaultReadOutcome(recordPath) {
-    if (!recordPath)
-        return { status: null, outcome: null };
-    try {
-        if (!existsSync(recordPath))
-            return { status: null, outcome: null };
-        const raw = readFileSync(recordPath, 'utf8');
-        const obj = JSON.parse(raw);
-        const status = typeof obj.status === 'string' ? obj.status : null;
-        const outcome = typeof obj.outcome === 'string' ? obj.outcome : null;
-        return { status, outcome };
+/**
+ * The wait budget. S4 (AC-3.2) — surface the clamp. A caller-supplied
+ * timeout above the hard cap is reported as `clamped`; the effective
+ * budget is what the loop actually waited.
+ */
+function resolveBudgets(timeoutMs, options) {
+    const hardCap = options.hardCapMs ?? DEFAULT_HARD_CAP_MS;
+    const requested = timeoutMs ?? options.defaultTimeoutMs;
+    const requestedClamped = requested > hardCap;
+    const effective = Math.min(Math.max(requested, 0), hardCap);
+    const noProgressBudget = options.noProgressMs ?? DEFAULT_NO_PROGRESS_MS;
+    return { hardCap, requested, requestedClamped, effective, noProgressBudget };
+}
+/** Resolve the test seams, keeping the production defaults. */
+function resolveSeams(options) {
+    const now = options.now ?? (() => Date.now());
+    const schedule = options.schedule ??
+        ((cb, ms) => {
+            const t = setTimeout(cb, ms);
+            t.unref?.();
+            return t;
+        });
+    const readOutcome = options.readOutcome ?? ((p) => defaultReadOutcome(p).status);
+    const readRecord = options.readRecord ?? defaultReadOutcome;
+    return { now, schedule, readOutcome, readRecord };
+}
+/**
+ * Post-loop batch outcome:
+ *   - `completed` — every slot reached a terminal state
+ *   - `timed-out` — at least one slot is still pending and the
+ *     effective budget elapsed
+ *   - `clamped` — the caller's `requestedTimeoutMs` exceeded the
+ *     hard cap (AC-3.2). The loop still ran the effective budget;
+ *     `clamped` takes precedence over `timed-out` because the
+ *     caller specifically asked for more than the cap and the
+ *     caller needs to know the cap was applied (the timeout is
+ *     secondary information).
+ *   - `no-progress` — the watchdog fired (AC-3.4)
+ */
+function resolveBatchOutcome(batchOutcome, slots, requestedClamped) {
+    let outcome = batchOutcome;
+    if (outcome === 'completed' && slots.size > 0) {
+        const allReached = Array.from(slots.values()).every((s) => s.finishedAt !== null);
+        if (!allReached) {
+            outcome = requestedClamped ? 'clamped' : 'timed-out';
+        }
+    }
+    if (outcome === 'completed' && requestedClamped) {
+        outcome = 'clamped';
     }
-    catch {
-        return { status: null, outcome: null };
+    return outcome;
+}
+/** The de-escalation itself: the flag only ever downgrades to `completed`. */
+function deescalateOutcome(batchOutcome, failfastDisabled) {
+    if (failfastDisabled &&
+        (batchOutcome === 'timed-out' || batchOutcome === 'no-progress' || batchOutcome === 'clamped')) {
+        return 'completed';
     }
+    return batchOutcome;
 }

package/dist/services/dispatch/batch-counter.js

@@ -95,7 +95,8 @@ export function resetBatch(projectRoot, sid, batchId) {
             const { unlinkSync } = require('node:fs');
             unlinkSync(path);
         }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        catch {
+            // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
             /* best-effort; counter file is informational */
         }
     }

package/dist/services/dispatch/conflict-replay.js

@@ -22,7 +22,7 @@
 const INSTRUCTIONS = [
     'A previous merge into the caller branch conflicted. Resolve the conflict preserving the intent of both your prior work and the caller branch.',
     'Do NOT introduce new functionality or refactor outside the conflict.',
-    'Re-run the dispatch and report the new conflict state. The parent will retry the merge.',
+    'Re-run the dispatch and report the new conflict state. The parent will retry the merge.'
 ];
 export function buildConflictReplay(input) {
     const prompt = [
@@ -38,7 +38,7 @@ export function buildConflictReplay(input) {
         '### Conflict diff',
         '```diff',
         input.conflictDiff,
-        '```',
+        '```'
     ].join('\n');
     return { prompt, instructions: INSTRUCTIONS };
 }

package/dist/services/dispatch/contract-store.js

@@ -19,6 +19,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isArray } from '../../shared/array-guards.js';
 /** Thrown when contract IO fails. */
 export class ContractStoreError extends Error {
     code = 'CONTRACT_STORE_ERROR';
@@ -86,7 +87,7 @@ export function writeContract(projectRoot, sessionId, input) {
     if (!input.sliceId || input.sliceId.length === 0) {
         throw new ContractStoreError('sliceId is required');
     }
-    if (!Array.isArray(input.exports) || !Array.isArray(input.types) || !Array.isArray(input.publicSignatures)) {
+    if (!isArray(input.exports) || !isArray(input.types) || !isArray(input.publicSignatures)) {
         throw new ContractStoreError('exports, types, publicSignatures must be arrays');
     }
     const completedAt = input.completedAt ?? new Date().toISOString();
@@ -147,7 +148,9 @@ export function listContracts(projectRoot, sessionId) {
 export function formatContractInjection(contracts) {
     if (contracts.length === 0)
         return '';
-    const blocks = ['## Ancestor slice contracts (do not import source — use this surface)'];
+    const blocks = [
+        '## Ancestor slice contracts (do not import source — use this surface)'
+    ];
     for (const c of contracts) {
         blocks.push('', `### slice ${c.sliceId} (completed ${c.completedAt}, hash=${c.contractHash.slice(0, 12)})`, `- exports: ${c.exports.length === 0 ? '(none)' : c.exports.join(', ')}`, `- types: ${c.types.length === 0 ? '(none)' : c.types.join(', ')}`, '- publicSignatures:', ...(c.publicSignatures.length === 0
             ? ['  - (none)']