peaks-loop 4.0.54 → 4.1.0

package/dist/services/crystallization/index.d.ts

@@ -7,7 +7,7 @@
  * subpackage stays standalone and does NOT depend on the main
  * peaks-loop package (avoiding workspace:* circular trap).
  */
-export { CrystallizationService, CrystallizationIntegrityError, type CrystallizationOptions, type CrystallizationTaskState, } from './crystallization-service.js';
-export { ensureCrystallizationEventTable, insertCrystallizationEvent, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus, } from './crystallization-store.js';
-export { CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief, EvidenceBriefSchema, CrystallizationEventSchema, parseCrystallizationEvent, safeParseEvidenceBrief, safeParseCrystallizationEvent, hasAllFourBriefSections, type CrystallizationTrigger, type CrystallizationEvent, type CrystallizationEventInput, type CrystallizationEventStatus, type EvidenceBrief, } from './crystallization-types.js';
-export { BriefSectionError, renderRecommendationPayload, safeRenderRecommendationPayload, buildEvidenceBrief, type BriefTraceInput, } from './evidence-brief-builder.js';
+export { CrystallizationService, CrystallizationIntegrityError, type CrystallizationOptions, type CrystallizationTaskState } from './crystallization-service.js';
+export { ensureCrystallizationEventTable, insertCrystallizationEvent, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus } from './crystallization-store.js';
+export { CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief, EvidenceBriefSchema, CrystallizationEventSchema, parseCrystallizationEvent, safeParseEvidenceBrief, safeParseCrystallizationEvent, hasAllFourBriefSections, type CrystallizationTrigger, type CrystallizationEvent, type CrystallizationEventInput, type CrystallizationEventStatus, type EvidenceBrief } from './crystallization-types.js';
+export { BriefSectionError, renderRecommendationPayload, safeRenderRecommendationPayload, buildEvidenceBrief, type BriefTraceInput } from './evidence-brief-builder.js';

package/dist/services/crystallization/index.js

@@ -7,7 +7,7 @@
  * subpackage stays standalone and does NOT depend on the main
  * peaks-loop package (avoiding workspace:* circular trap).
  */
-export { CrystallizationService, CrystallizationIntegrityError, } from './crystallization-service.js';
-export { ensureCrystallizationEventTable, insertCrystallizationEvent, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus, } from './crystallization-store.js';
-export { CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief, EvidenceBriefSchema, CrystallizationEventSchema, parseCrystallizationEvent, safeParseEvidenceBrief, safeParseCrystallizationEvent, hasAllFourBriefSections, } from './crystallization-types.js';
-export { BriefSectionError, renderRecommendationPayload, safeRenderRecommendationPayload, buildEvidenceBrief, } from './evidence-brief-builder.js';
+export { CrystallizationService, CrystallizationIntegrityError } from './crystallization-service.js';
+export { ensureCrystallizationEventTable, insertCrystallizationEvent, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus } from './crystallization-store.js';
+export { CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief, EvidenceBriefSchema, CrystallizationEventSchema, parseCrystallizationEvent, safeParseEvidenceBrief, safeParseCrystallizationEvent, hasAllFourBriefSections } from './crystallization-types.js';
+export { BriefSectionError, renderRecommendationPayload, safeRenderRecommendationPayload, buildEvidenceBrief } from './evidence-brief-builder.js';

package/dist/services/dashboard/project-dashboard-service.js

@@ -21,7 +21,13 @@ function defaultClock() {
     return new Date().toISOString();
 }
 function groupRequestsByRole(items) {
-    const byRole = { prd: [], ui: [], rd: [], qa: [], sc: [] };
+    const byRole = {
+        prd: [],
+        ui: [],
+        rd: [],
+        qa: [],
+        sc: []
+    };
     for (const item of items) {
         byRole[item.role].push(item);
     }

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

@@ -0,0 +1,55 @@
+/**
+ * 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 declare function defaultReadOutcome(recordPath: string): {
+    status: string | null;
+    outcome: string | null;
+};
+/** One slot's mutable state — the value type of `awaitBatch`'s slot map. */
+export interface AwaitBatchSlot {
+    recordPath: string;
+    status: 'done' | 'failed' | 'cancelled' | 'timeout';
+    note: string | null;
+    finishedAt: number | null;
+    lastProgress: number;
+}
+/** The slot table plus the batch start time the watchdog and the notes read. */
+export interface AwaitBatchSlotTable {
+    readonly startedAt: number;
+    readonly slots: Map<number, AwaitBatchSlot>;
+    readonly lastProgressAt: Map<number, number>;
+}
+/** One per-dispatch result — the element type of `AwaitBatchResult.results`. */
+export interface AwaitBatchSlotResult {
+    readonly dispatchIndex: number;
+    readonly recordPath: string;
+    readonly status: 'done' | 'failed' | 'cancelled' | 'timeout';
+    readonly durationMs: number;
+    readonly note: string | null;
+}
+/**
+ * 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 declare function createSlotTable(recordPaths: readonly string[], startedAt: number): AwaitBatchSlotTable;
+/**
+ * One observation pass over the pending slots. Returns the `allDone` the loop
+ * branched on: `true` only when every slot reached a terminal state.
+ */
+export declare function pollSlotsOnce(table: AwaitBatchSlotTable, readOutcome: (recordPath: string) => string | null, readRecord: (recordPath: string) => {
+    status: string | null;
+    outcome: string | null;
+}, now: () => number): boolean;
+/**
+ * No-progress watchdog: every slot has been without observable
+ * progress for `noProgressBudget`, and there is at least one slot.
+ */
+export declare function hasNoProgress(table: AwaitBatchSlotTable, now: () => number, noProgressBudget: number): boolean;
+/** Sleep a tick on the resolved scheduler. */
+export declare function sleepTick(schedule: (cb: () => void, ms: number) => void): Promise<void>;
+/**
+ * Build the per-dispatch results in dispatchIndex order.
+ */
+export declare function buildBatchResults(table: AwaitBatchSlotTable, notePrefix: string | undefined, effectiveTimeoutMs: number): readonly AwaitBatchSlotResult[];

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). */