peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,147 @@
+import { listRequestArtifacts } from '../artifacts/request-artifact-service.js';
+import { scanOpenSpec } from '../openspec/openspec-scan-service.js';
+import { scanUnderstandAnything } from '../understand/understand-scan-service.js';
+import { seedCapabilityItems } from '../recommendations/capability-seed-items.js';
+import { requiredSkillNames } from 'peaks-loop-shared/paths';
+import { getSkillPresence } from '../skills/skill-presence-service.js';
+const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+/**
+ * Resolves the user-facing `ok` field. `workspace-only` (default) returns true
+ * when the runbook / workspace layout is healthy, even if 1-2 non-blocking
+ * doctor checks fail. `strict` returns false when the doctor aggregate fails.
+ * The CLI default is `workspace-only`; `peaks project dashboard --strict`
+ * restores the legacy aggregate semantics.
+ */
+export function resolveDashboardOk(args) {
+    if (args.okPolicy === 'strict') {
+        return { ok: args.doctor.ok && args.runbookHealth.ok, okPolicy: 'strict' };
+    }
+    return { ok: args.runbookHealth.ok, okPolicy: 'workspace-only' };
+}
+function defaultClock() {
+    return new Date().toISOString();
+}
+function groupRequestsByRole(items) {
+    const byRole = { prd: [], ui: [], rd: [], qa: [], sc: [] };
+    for (const item of items) {
+        byRole[item.role].push(item);
+    }
+    return byRole;
+}
+function countRequestsByState(items) {
+    const counts = {};
+    for (const item of items) {
+        counts[item.state] = (counts[item.state] ?? 0) + 1;
+    }
+    return counts;
+}
+async function loadDoctorAndRunbookHealth(doctorOverride, runbookOverride) {
+    if (doctorOverride !== undefined && runbookOverride !== undefined) {
+        return { doctor: doctorOverride, runbookHealth: runbookOverride };
+    }
+    if (doctorOverride !== undefined) {
+        return {
+            doctor: doctorOverride,
+            runbookHealth: { ok: true, required: 0, healthy: 0, missingRunbook: [], applyNoteFailed: [] }
+        };
+    }
+    const { runDoctor } = await import('../doctor/index.js');
+    const report = await runDoctor();
+    return {
+        doctor: { ok: report.summary.ok, passed: report.summary.passed, failed: report.summary.failed },
+        runbookHealth: runbookOverride ?? summarizeRunbookHealth(report.checks)
+    };
+}
+function summarizeRunbookHealth(checks) {
+    const missingRunbook = [];
+    const applyNoteFailed = [];
+    for (const check of checks) {
+        if (!check.ok && check.id.startsWith('skill-runbook:')) {
+            missingRunbook.push(check.id.slice('skill-runbook:'.length));
+        }
+        if (!check.ok && check.id.startsWith('skill-apply-note:')) {
+            applyNoteFailed.push(check.id.slice('skill-apply-note:'.length));
+        }
+    }
+    const required = requiredSkillNames.length;
+    const healthy = Math.max(0, required - missingRunbook.length - applyNoteFailed.length);
+    return {
+        ok: missingRunbook.length === 0 && applyNoteFailed.length === 0,
+        required,
+        healthy,
+        missingRunbook,
+        applyNoteFailed
+    };
+}
+function buildCapabilitiesSummary(sampleSize) {
+    const items = seedCapabilityItems;
+    return {
+        count: items.length,
+        sample: items.slice(0, sampleSize).map((item) => ({
+            capabilityId: item.capabilityId,
+            name: item.name,
+            itemType: item.itemType,
+            category: item.category
+        }))
+    };
+}
+function buildSkillPresenceSummary(presence, projectRoot) {
+    // When the caller doesn't supply presence, resolve it from the dashboard's
+    // project root rather than the process cwd.
+    const resolved = presence === undefined ? getSkillPresence(projectRoot) : presence;
+    if (resolved === null) {
+        return { active: false, fresh: true };
+    }
+    const setAtMs = Date.parse(resolved.setAt);
+    const fresh = !Number.isNaN(setAtMs) && Date.now() - setAtMs <= SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS;
+    return {
+        active: true,
+        fresh,
+        skill: resolved.skill,
+        ...(resolved.mode !== undefined ? { mode: resolved.mode } : {}),
+        ...(resolved.gate !== undefined ? { gate: resolved.gate } : {}),
+        setAt: resolved.setAt
+    };
+}
+export async function loadProjectDashboard(options) {
+    const clock = options.clock ?? defaultClock;
+    const sampleSize = options.sampleCapabilities ?? 8;
+    const okPolicy = options.okPolicy ?? 'workspace-only';
+    const [items, openspecReport, understandReport, doctorAndRunbook] = await Promise.all([
+        listRequestArtifacts({ projectRoot: options.projectRoot }),
+        scanOpenSpec({ openspecRoot: `${options.projectRoot}/openspec` }),
+        scanUnderstandAnything({ projectRoot: options.projectRoot }),
+        loadDoctorAndRunbookHealth(options.doctorReport, options.runbookHealth)
+    ]);
+    const okVerdict = resolveDashboardOk({
+        okPolicy,
+        doctor: doctorAndRunbook.doctor,
+        runbookHealth: doctorAndRunbook.runbookHealth
+    });
+    return {
+        generatedAt: clock(),
+        projectRoot: options.projectRoot,
+        ok: okVerdict.ok,
+        okPolicy: okVerdict.okPolicy,
+        requests: {
+            count: items.length,
+            byRole: groupRequestsByRole(items),
+            byState: countRequestsByState(items)
+        },
+        openspec: {
+            exists: openspecReport.exists,
+            count: openspecReport.changes.length,
+            changes: openspecReport.changes
+        },
+        understand: {
+            exists: understandReport.exists,
+            graphExists: understandReport.graph.exists,
+            graphPath: understandReport.graph.path,
+            ...(understandReport.graph.parseError !== undefined ? { parseError: understandReport.graph.parseError } : {})
+        },
+        doctor: doctorAndRunbook.doctor,
+        runbookHealth: doctorAndRunbook.runbookHealth,
+        capabilities: buildCapabilitiesSummary(sampleSize),
+        skillPresence: buildSkillPresenceSummary(options.skillPresence, options.projectRoot)
+    };
+}

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

@@ -0,0 +1,70 @@
+export type AwaitBatchOutcome = 'completed' | 'timed-out' | 'clamped' | 'no-progress';
+export interface AwaitBatchOptions {
+    /** Caller-supplied per-IDE default when no timeoutMs is provided. */
+    readonly defaultTimeoutMs: number;
+    /** Hard cap on the effective wait, in ms. Default: 120_000. */
+    readonly hardCapMs?: number;
+    /** Optional per-IDE label written into result `note` for attribution. */
+    readonly notePrefix?: string;
+    /**
+     * No-progress watchdog. If a slot's progress is unchanged for
+     * `noProgressMs`, the batch escalates with outcome `no-progress`
+     * (and the slot's status is left as the caller would observe at
+     * that moment — typically still `running` or `queued`).
+     */
+    readonly noProgressMs?: number;
+    /**
+     * Test seam: override Date.now() and setTimeout's clock. Production
+     * callers leave this undefined.
+     */
+    readonly now?: () => number;
+    /**
+     * Test seam: override setTimeout / setInterval. Production callers
+     * leave this undefined.
+     */
+    readonly schedule?: (cb: () => void, ms: number) => void;
+    /**
+     * Test seam: how to read a record's status. Production callers
+     * leave this undefined (the default reads `status` from the file).
+     * Returning a plain string is treated as the record's status; the
+     * default reader also exposes the `outcome` field via the optional
+     * second tuple element (see `defaultReadOutcome`).
+     *
+     * Test-only escape hatch: callers that need to return both status
+     * and outcome can implement `readRecord` instead.
+     */
+    readonly readOutcome?: (recordPath: string) => string | null;
+    /**
+     * Test seam: read a record's status AND outcome together. When
+     * defined, this overrides `readOutcome`. Implementations should
+     * return `{ status: null, outcome: null }` when the file is missing
+     * or unreadable, and `{ status }` / `{ status, outcome }` otherwise.
+     */
+    readonly readRecord?: (recordPath: string) => {
+        status: string | null;
+        outcome: string | null;
+    };
+}
+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;
+    }>;
+    /** Batch-level outcome — distinct, machine-readable. */
+    readonly outcome: AwaitBatchOutcome;
+    /** What the caller asked for (or the IDE default, when omitted). */
+    readonly requestedTimeoutMs: number;
+    /** What the loop actually waited (≤ requestedTimeoutMs after clamp). */
+    readonly effectiveTimeoutMs: number;
+    /** The hard cap applied; equals `requestedTimeoutMs` if no clamp. */
+    readonly hardCapMs: number;
+}
+/**
+ * Run one awaitBatch. Pure (no module-level state); the two
+ * back-compat wrappers in sub-agent-dispatcher.ts call this.
+ */
+export declare function awaitBatch(dispatchCount: number, recordPaths: readonly string[], timeoutMs: number | undefined, options?: AwaitBatchOptions): Promise<AwaitBatchResult>;

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.d.ts

@@ -0,0 +1,27 @@
+export declare const BATCH_LIMIT = 6;
+export declare const BATCH_OVER_LIMIT_CODE = "BATCH_OVER_LIMIT";
+export type BatchCounterWarning = {
+    readonly code: typeof BATCH_OVER_LIMIT_CODE;
+    readonly batchId: string;
+    readonly dispatched: number;
+    readonly limit: number;
+    readonly message: string;
+};
+/** Build the per-batch counter file path. */
+export declare function batchCounterPath(projectRoot: string, sid: string, batchId: string): string;
+/** A single batch counter record. */
+export interface BatchCounterRecord {
+    readonly batchId: string;
+    readonly sessionId: string;
+    readonly createdAt: string;
+    readonly count: number;
+}
+/** Read the current counter; returns 0 if no file yet. */
+export declare function readBatchCount(projectRoot: string, sid: string, batchId: string): number;
+/** Increment the counter and return the new value (with any warning). */
+export declare function noteDispatched(projectRoot: string, sid: string, batchId: string, now?: () => Date): {
+    count: number;
+    warning: BatchCounterWarning | null;
+};
+/** Reset a batch counter (called by the reducer when starting a new batch). */
+export declare function resetBatch(projectRoot: string, sid: string, batchId: string): void;

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

@@ -0,0 +1,102 @@
+/**
+ * G5.1 / RL-1 — batch size counter.
+ *
+ * Empirical upper bound for one Dispatcher × one batch: 6 sub-agents.
+ * Above 6, the LLM / human is encouraged to split into multiple
+ * batches with an explicit reducer step in between. peaks-code's
+ * swarm phase dispatches 3; peaks-rd's 4-way fan-out dispatches 4;
+ * peaks-qa's 3-way fan-out dispatches 3. The 6 limit leaves headroom
+ * for "qa-business-api" / "qa-business-frontend" / "qa-business-regression"
+ * subdivisions (3-way + 3-way = 6) without crossing the line.
+ *
+ * The counter is in-memory per process. The Dispatcher is expected
+ * to call `noteDispatched` once per `peaks sub-agent dispatch` and
+ * reset between batches. The CLI also persists a small per-sid
+ * counter file so that sub-agent spawns invoked across multiple
+ * `peaks sub-agent dispatch` processes within the same batch can be
+ * tallied (the batch id ties them together).
+ *
+ * `BATCH_OVER_LIMIT` is a warning, not a hard fail. The user has been
+ * explicit: "RL-1 is empirical; if you have a real reason to go to 7,
+ * that's your call". A warning is the right surface — let the LLM /
+ * human read the reason and decide.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+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. */
+export function batchCounterPath(projectRoot, sid, batchId) {
+    return resolve(projectRoot, '.peaks', '_sub_agents', sid, `batch-${batchId}.counter.json`);
+}
+/** Read the current counter; returns 0 if no file yet. */
+export function readBatchCount(projectRoot, sid, batchId) {
+    const path = batchCounterPath(projectRoot, sid, batchId);
+    if (!existsSync(path))
+        return 0;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed.count === 'number' && parsed.count >= 0 ? parsed.count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Increment the counter and return the new value (with any warning). */
+export function noteDispatched(projectRoot, sid, batchId, now = () => new Date()) {
+    const path = batchCounterPath(projectRoot, sid, batchId);
+    // Slice 2026-06-23-audit-4th #A1: wrap the read-modify-write in a
+    // file lock. Two concurrent `peaks sub-agent dispatch` invocations
+    // for the same (sid, batchId) would otherwise race — both call
+    // readBatchCount first, both see the same N, both write N+1, and
+    // the second write clobbers the first (lost update). The BATCH_OVER_LIMIT
+    // warning fires for the wrong threshold when this happens. The lock
+    // serializes the writes; contention is rare (only when a single
+    // batch is dispatched in parallel from the same LLM) so the spin-wait
+    // cost is bounded by MAX_LOCK_RETRIES * LOCK_RETRY_MAX_MS.
+    return withFileLockSync(path, () => {
+        const previous = readBatchCount(projectRoot, sid, batchId);
+        const next = {
+            batchId,
+            sessionId: sid,
+            createdAt: now().toISOString(),
+            count: previous + 1
+        };
+        // mkdirSync is conditional via the lock helper (it ensures the
+        // parent dir exists), but the counter file may live in a session
+        // sub-dir that the lock helper's recursive mkdir handles. Belt +
+        // suspenders: keep the explicit mkdir here so the path resolves
+        // even if withFileLockSync's mkdir is bypassed in the future.
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+        if (next.count > BATCH_LIMIT) {
+            return {
+                count: next.count,
+                warning: {
+                    code: BATCH_OVER_LIMIT_CODE,
+                    batchId,
+                    dispatched: next.count,
+                    limit: BATCH_LIMIT,
+                    message: `per RL-1, batch size 6 is empirical upper bound; you have ` +
+                        `${next.count}. If you need more, split into multiple batches ` +
+                        `with an explicit reducer step between them.`
+                }
+            };
+        }
+        return { count: next.count, warning: null };
+    });
+}
+/** Reset a batch counter (called by the reducer when starting a new batch). */
+export function resetBatch(projectRoot, sid, batchId) {
+    const path = batchCounterPath(projectRoot, sid, batchId);
+    if (existsSync(path)) {
+        try {
+            const { unlinkSync } = require('node:fs');
+            unlinkSync(path);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            /* best-effort; counter file is informational */
+        }
+    }
+}