peaks-loop 4.0.0-beta.9 → 4.0.3

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

@@ -0,0 +1,272 @@
+/**
+ * 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.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+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`
+ * debug). Setting it falls back to the silent-return behavior so a
+ * stuck session can be unblocked without a rebuild.
+ */
+const FAILFAST_DISABLED = (() => {
+    const v = process.env.PEAKS_DISPATCH_DISABLE_FAILFAST;
+    return v === '1' || v === 'true';
+})();
+/**
+ * Run one awaitBatch. Pure (no module-level state); the two
+ * back-compat wrappers in sub-agent-dispatcher.ts call this.
+ */
+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);
+    }
+    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)
+            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) {
+                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';
+    }
+    // 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
+        };
+    });
+    // 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';
+    }
+    return {
+        results,
+        outcome: batchOutcome,
+        requestedTimeoutMs: requested,
+        effectiveTimeoutMs: effective,
+        hardCapMs: hardCap
+    };
+}
+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 };
+    }
+}

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

@@ -23,7 +23,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { withFileLockSync } from '../filesystem/file-lock.js';
+import { withFileLockSync } from 'peaks-loop-shared-channel';
 export const BATCH_LIMIT = 6;
 export const BATCH_OVER_LIMIT_CODE = 'BATCH_OVER_LIMIT';
 /** Build the per-batch counter file path. */

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

@@ -1,4 +1,5 @@
 import type { SubAgentToolCall } from './sub-agent-dispatcher.js';
+import { type StageLabel } from './stage-enum.js';
 /** G6.3 Heartbeat entry — single update written by a running sub-agent. */
 export interface Heartbeat {
     readonly at: string;
@@ -6,12 +7,43 @@ export interface Heartbeat {
     readonly progress: number;
     readonly note: string | null;
 }
-export type HeartbeatStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'stale';
-export type DispatchRecordStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'no-execution' | 'stale';
+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 {
-    readonly version: 2;
+    /**
+     * 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.
+     */
+    /**
+     * Slice 2026-07-29-rid-prose-only-sweep Part 34: schema v3.1
+     * is the explicit minor bump that records the
+     * `isolationStartedAt` (Part 7) and `leaseId` (Part 3.A.1 +
+     * Part 4.C) fields as part of the canonical schema. v3
+     * records on disk upgrade transparently — see `upgradeRecord`
+     * in this file. The literal type ('3.1') is the source of
+     * truth for "this record is v3.1-form"; readers check
+     * `version === '3.1'` for forward-compatible dispatching.
+     */
+    readonly version: '3.1';
     readonly createdAt: string;
     readonly completedAt: string | null;
     readonly outcome: DispatchOutcome;
@@ -29,6 +61,35 @@ export interface DispatchRecord {
     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;
 }
 /** Input for the initial write. */
 export type WriteInitialDispatchInput = {
@@ -41,6 +102,22 @@ export type WriteInitialDispatchInput = {
     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;
 };
 /** Heartbeat write input. */
 export type AppendHeartbeatInput = {
@@ -82,7 +159,7 @@ export interface ActiveDispatchEntry {
     readonly role: string;
     readonly batchId: string;
     readonly createdAt: string;
-    readonly status: 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'stale' | 'no-execution';
+    readonly status: 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'stale' | 'no-execution' | 'never-started' | 'unreadable';
 }
 /**
  * Slice 2026-06-23-audit-4th #A4: read the active-dispatches index
@@ -118,6 +195,34 @@ export declare function applyTruncation(entries: readonly Heartbeat[]): {
     heartbeats: Heartbeat[];
     truncated: boolean;
 };
+/**
+ * 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 declare function tryAutoReleaseLease(args: {
+    projectRoot: string;
+    sessionId: string;
+    leaseId: string;
+    /** Best-effort logging hook (e.g. logger.writeLogEntry). Returns null on failure. */
+    logger?: (line: string) => void;
+}): void;
 /** Mark a record as completed (success / failed / cancelled / no-execution). */
 export declare function markCompleted(input: LifecycleInput): {
     record: DispatchRecord;
@@ -126,6 +231,23 @@ export declare function markCompleted(input: LifecycleInput): {
 export declare function markDisposed(recordPath: string, now?: () => Date): {
     record: DispatchRecord;
 };
+/**
+ * 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 declare function setStage(input: {
+    recordPath: string;
+    stage: StageLabel | null;
+    now?: () => Date;
+}): {
+    record: DispatchRecord;
+};
 /**
  * Read a dispatch record with backward-compat defaults. Old records
  * missing G5 / G6 fields are upgraded on read (no error, no overwrite).