peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

package/dist/src/services/context/shared-channel.d.ts

@@ -1,93 +0,0 @@
-export interface SharedChannelEntry {
-    readonly version: 1;
-    readonly at: string;
-    readonly from: string;
-    readonly key: string;
-    readonly value: Readonly<Record<string, unknown>>;
-    readonly valueSize: number;
-}
-export interface SharedChannel {
-    readonly batchId: string;
-    readonly createdAt: string;
-    readonly updatedAt: string;
-    readonly entries: Readonly<Record<string, SharedChannelEntry>>;
-}
-export declare const SHARED_CHANNEL_MAX_VALUE_BYTES: number;
-export declare const SHARED_CHANNEL_SOFT_VALUE_WARN = 1024;
-export declare const SHARED_CHANNEL_MAX_FILE_BYTES: number;
-export declare const SHARED_CHANNEL_TTL_DAYS = 30;
-export type WriteSharedEntryResult = {
-    readonly ok: true;
-    readonly entry: SharedChannelEntry;
-    readonly channelSize: number;
-    readonly lastWriteWins: boolean;
-    readonly softWarning: boolean;
-} | {
-    readonly ok: false;
-    readonly code: 'VALUE_TOO_LARGE' | 'INVALID_BATCH_ID' | 'WRITE_ERROR';
-    readonly message: string;
-};
-/**
- * Write a shared entry to the per-batch channel file. Atomic-write
- * (tmp + rename). Returns the new entry + channel size + last-write-wins
- * flag (true if the key already existed; the new value overwrites).
- *
- * RL-25 size limit: `value ≥ 64KB` is hard-rejected with `VALUE_TOO_LARGE`.
- * `value > 1KB and < 64KB` is a soft warning (returned in the result).
- */
-export declare function writeSharedEntry(opts: {
-    projectRoot: string;
-    sid: string;
-    rid: string;
-    batchId: string;
-    key: string;
-    from: string;
-    value: Record<string, unknown>;
-}): WriteSharedEntryResult;
-/**
- * Read the shared channel for a batch. Returns the channel with all
- * matching entries. Filters: `--since` (ISO8601) and `--key` (glob
- * pattern; simple `*` wildcard, no regex).
- *
- * If the channel file does not exist, returns an empty channel
- * (this is the dispatcher's "fresh batch" view).
- */
-export declare function readSharedChannel(opts: {
-    projectRoot: string;
-    sid: string;
-    rid: string;
-    batchId: string;
-    since?: string;
-    keyPattern?: string;
-}): SharedChannel;
-/**
- * Garbage-collect a single channel. Returns true if the file was
- * deleted, false if it did not exist.
- */
-export declare function gcChannel(opts: {
-    projectRoot: string;
-    sid: string;
-    rid: string;
-    batchId: string;
-}): boolean;
-/**
- * Check if a channel file is older than `SHARED_CHANNEL_TTL_DAYS` days
- * and should be GC'd as an orphan. Returns true if file is missing
- * (already GC'd) or older than TTL.
- */
-export declare function isOrphanChannel(opts: {
-    projectRoot: string;
-    sid: string;
-    rid: string;
-    batchId: string;
-    now?: Date;
-}): boolean;
-/**
- * Compile a simple key pattern with `*` wildcards to a matcher. Only
- * `*` is special; everything else is a literal. `*` matches zero or
- * more characters. Examples:
- *   "rd.*"       matches "rd.completed", "rd.found-blocker"
- *   "*.completed" matches "rd.completed", "qa.completed"
- *   "*"           matches everything
- */
-export declare function compileKeyPattern(pattern: string): (key: string) => boolean;

package/dist/src/services/context/shared-channel.js

@@ -1,308 +0,0 @@
-/**
- * G8 — cross sub-agent shared channel (RL-23..RL-26, AC-47..AC-49).
- *
- * Dispatcher-mediated indirect signal: sub-agent A writes a shared entry,
- * the dispatcher stores it in a per-batch JSON file, sub-agent B (still
- * in flight) reads it. A and B never directly talk. This is the
- * pseudo-swarm property 3 upgrade; it is NOT peer-to-peer messaging.
- *
- * Path convention (G8.3):
- *   `.peaks/_sub_agents/<sid>/shared/<rid>-<batchId>.json`
- *
- * The file is atomic-write (tmp + rename). Last-write-wins by key. Value
- * size limit: ≤ 1KB soft warn, ≥ 64KB hard reject. File size cap: 1MB
- * with LRU eviction.
- *
- * See: `.peaks/memory/sub-agent-shared-channel-cross-completion.md` for
- * the full G8 rule.
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { assertSafeSharedChannelPath, sharedChannelPath } from './dispatch-context-guard.js';
-import { withFileLockSync } from '../filesystem/file-lock.js';
-export const SHARED_CHANNEL_MAX_VALUE_BYTES = 64 * 1024; // 64KB hard reject
-export const SHARED_CHANNEL_SOFT_VALUE_WARN = 1024; // 1KB soft warning
-export const SHARED_CHANNEL_MAX_FILE_BYTES = 1024 * 1024; // 1MB LRU cap
-export const SHARED_CHANNEL_TTL_DAYS = 30; // 30-day TTL on orphan channels
-/**
- * Write a shared entry to the per-batch channel file. Atomic-write
- * (tmp + rename). Returns the new entry + channel size + last-write-wins
- * flag (true if the key already existed; the new value overwrites).
- *
- * RL-25 size limit: `value ≥ 64KB` is hard-rejected with `VALUE_TOO_LARGE`.
- * `value > 1KB and < 64KB` is a soft warning (returned in the result).
- */
-export function writeSharedEntry(opts) {
-    if (typeof opts.key !== 'string' || opts.key.length === 0) {
-        return { ok: false, code: 'INVALID_BATCH_ID', message: 'key must be non-empty' };
-    }
-    if (typeof opts.from !== 'string' || opts.from.length === 0) {
-        return { ok: false, code: 'INVALID_BATCH_ID', message: 'from must be non-empty' };
-    }
-    if (opts.value === null || typeof opts.value !== 'object' || Array.isArray(opts.value)) {
-        return {
-            ok: false,
-            code: 'INVALID_BATCH_ID',
-            message: 'value must be a JSON object (not array, not primitive)'
-        };
-    }
-    const valueSize = Buffer.byteLength(JSON.stringify(opts.value), 'utf8');
-    if (valueSize >= SHARED_CHANNEL_MAX_VALUE_BYTES) {
-        return {
-            ok: false,
-            code: 'VALUE_TOO_LARGE',
-            message: `value size ${valueSize} bytes exceeds limit ${SHARED_CHANNEL_MAX_VALUE_BYTES} bytes (RL-25)`
-        };
-    }
-    const softWarning = valueSize > SHARED_CHANNEL_SOFT_VALUE_WARN;
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    assertSafeSharedChannelPath(channelFile, opts.projectRoot);
-    // Slice 2026-06-23-audit-3rd #2: the read-modify-write sequence below
-    // is wrapped in withFileLockSync to prevent lost updates from two
-    // concurrent `peaks sub-agent share` calls landing on the same batch.
-    // Without the lock, the second writer's read sees a stale channel,
-    // and its renameSync silently overwrites the first writer's entry.
-    return withFileLockSync(channelFile, () => {
-        let channel;
-        try {
-            channel = readChannelOrEmpty(channelFile, opts.batchId);
-        }
-        catch (err) {
-            return {
-                ok: false,
-                code: 'WRITE_ERROR',
-                message: `failed to read existing channel: ${err.message}`
-            };
-        }
-        const lastWriteWins = Object.prototype.hasOwnProperty.call(channel.entries, opts.key);
-        // LRU eviction: if writing would push the file over the 1MB cap,
-        // evict oldest entries until the new write fits.
-        const entry = {
-            version: 1,
-            at: new Date().toISOString(),
-            from: opts.from,
-            key: opts.key,
-            value: Object.freeze({ ...opts.value }),
-            valueSize
-        };
-        const projectedChannel = {
-            ...channel,
-            updatedAt: entry.at,
-            entries: { ...channel.entries, [opts.key]: entry }
-        };
-        const projectedSize = JSON.stringify(projectedChannel).length;
-        let lruEvicted = 0;
-        if (projectedSize > SHARED_CHANNEL_MAX_FILE_BYTES) {
-            const sortedKeys = Object.keys(projectedChannel.entries).sort((a, b) => {
-                const ea = projectedChannel.entries[a];
-                const eb = projectedChannel.entries[b];
-                if (!ea || !eb)
-                    return 0;
-                return ea.at.localeCompare(eb.at);
-            });
-            let working = projectedChannel;
-            while (JSON.stringify(working).length > SHARED_CHANNEL_MAX_FILE_BYTES &&
-                sortedKeys.length > 0) {
-                const oldestKey = sortedKeys.shift();
-                if (oldestKey === opts.key) {
-                    // Don't evict the entry we just wrote.
-                    break;
-                }
-                const nextEntries = {};
-                for (const [k, v] of Object.entries(working.entries)) {
-                    if (k !== oldestKey) {
-                        nextEntries[k] = v;
-                    }
-                }
-                working = { ...working, entries: nextEntries };
-                lruEvicted += 1;
-            }
-            try {
-                writeAtomic(channelFile, working);
-            }
-            catch (err) {
-                return {
-                    ok: false,
-                    code: 'WRITE_ERROR',
-                    message: `failed to write channel after LRU eviction: ${err.message}`
-                };
-            }
-            return {
-                ok: true,
-                entry,
-                channelSize: JSON.stringify(working).length,
-                lastWriteWins,
-                softWarning
-            };
-        }
-        try {
-            writeAtomic(channelFile, projectedChannel);
-        }
-        catch (err) {
-            return {
-                ok: false,
-                code: 'WRITE_ERROR',
-                message: `failed to write channel: ${err.message}`
-            };
-        }
-        // lruEvicted is 0 here; expose the count through the size of the
-        // returned channel for caller diagnostics.
-        void lruEvicted;
-        return {
-            ok: true,
-            entry,
-            channelSize: projectedSize,
-            lastWriteWins,
-            softWarning
-        };
-    });
-}
-/**
- * Read the shared channel for a batch. Returns the channel with all
- * matching entries. Filters: `--since` (ISO8601) and `--key` (glob
- * pattern; simple `*` wildcard, no regex).
- *
- * If the channel file does not exist, returns an empty channel
- * (this is the dispatcher's "fresh batch" view).
- */
-export function readSharedChannel(opts) {
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    assertSafeSharedChannelPath(channelFile, opts.projectRoot);
-    const channel = readChannelOrEmpty(channelFile, opts.batchId);
-    const since = opts.since;
-    const pattern = opts.keyPattern;
-    if (!since && !pattern) {
-        return channel;
-    }
-    const filteredEntries = {};
-    const matcher = pattern ? compileKeyPattern(pattern) : null;
-    for (const [k, v] of Object.entries(channel.entries)) {
-        if (since && v.at < since)
-            continue;
-        if (matcher && !matcher(k))
-            continue;
-        filteredEntries[k] = v;
-    }
-    return { ...channel, entries: filteredEntries };
-}
-/**
- * Garbage-collect a single channel. Returns true if the file was
- * deleted, false if it did not exist.
- */
-export function gcChannel(opts) {
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    if (!existsSync(channelFile)) {
-        return false;
-    }
-    // Best-effort delete; R-2 guard not strictly needed (we built the path)
-    // but kept for safety.
-    assertSafeSharedChannelPath(channelFile, opts.projectRoot);
-    try {
-        unlinkSync(channelFile);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Check if a channel file is older than `SHARED_CHANNEL_TTL_DAYS` days
- * and should be GC'd as an orphan. Returns true if file is missing
- * (already GC'd) or older than TTL.
- */
-export function isOrphanChannel(opts) {
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    if (!existsSync(channelFile)) {
-        return true;
-    }
-    const s = statSync(channelFile);
-    const now = opts.now ?? new Date();
-    const ageMs = now.getTime() - s.mtimeMs;
-    const ttlMs = SHARED_CHANNEL_TTL_DAYS * 24 * 60 * 60 * 1000;
-    return ageMs > ttlMs;
-}
-// ─── internals ───────────────────────────────────────────────────────
-function readChannelOrEmpty(channelFile, batchId) {
-    if (!existsSync(channelFile)) {
-        const now = new Date().toISOString();
-        return { batchId, createdAt: now, updatedAt: now, entries: {} };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(channelFile, 'utf8'));
-    }
-    catch {
-        const now = new Date().toISOString();
-        return { batchId, createdAt: now, updatedAt: now, entries: {} };
-    }
-    if (!isObject(parsed)) {
-        const now = new Date().toISOString();
-        return { batchId, createdAt: now, updatedAt: now, entries: {} };
-    }
-    const obj = parsed;
-    const batchIdField = typeof obj.batchId === 'string' ? obj.batchId : batchId;
-    const createdAt = typeof obj.createdAt === 'string' ? obj.createdAt : new Date().toISOString();
-    const updatedAt = typeof obj.updatedAt === 'string' ? obj.updatedAt : createdAt;
-    const entriesField = isObject(obj.entries) ? obj.entries : {};
-    const entries = {};
-    for (const [k, v] of Object.entries(entriesField)) {
-        if (isValidEntry(v)) {
-            entries[k] = v;
-        }
-    }
-    return { batchId: batchIdField, createdAt, updatedAt, entries };
-}
-function isValidEntry(v) {
-    if (!isObject(v))
-        return false;
-    // Slice 2026-06-23-audit-4th #E2: pre-versioning records (no
-    // `version` field) are still accepted on read for backward compat.
-    // The writer stamps `version: 1` going forward; readers default
-    // missing/legacy entries to version 1 in memory.
-    if (!('version' in v) || v.version === 1) {
-        return (typeof v.at === 'string' &&
-            typeof v.from === 'string' &&
-            typeof v.key === 'string' &&
-            isObject(v.value) &&
-            typeof v.valueSize === 'number');
-    }
-    // Future versions: read-side handler can branch on `v.version` once
-    // v2 lands. For now, anything other than 1 is rejected.
-    return false;
-}
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-function writeAtomic(path, channel) {
-    const dir = dirname(path);
-    // Slice 2026-06-23-audit-3rd #11: skip mkdirSync when the dir already
-    // exists. The `recursive: true` mkdir is a syscall (~50µs on macOS,
-    // ~10ms on cold Windows cache); the `existsSync` short-circuit saves
-    // it on the hot path (every `peaks sub-agent share` + every
-    // `peaks sub-agent heartbeat`).
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, JSON.stringify(channel, null, 2) + '\n', 'utf8');
-    renameSync(tmp, path);
-}
-/**
- * Compile a simple key pattern with `*` wildcards to a matcher. Only
- * `*` is special; everything else is a literal. `*` matches zero or
- * more characters. Examples:
- *   "rd.*"       matches "rd.completed", "rd.found-blocker"
- *   "*.completed" matches "rd.completed", "qa.completed"
- *   "*"           matches everything
- */
-export function compileKeyPattern(pattern) {
-    if (pattern === '*') {
-        return () => true;
-    }
-    const escaped = pattern
-        .split('*')
-        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
-        .join('.*');
-    const re = new RegExp(`^${escaped}$`);
-    return (key) => re.test(key);
-}

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

@@ -1,147 +0,0 @@
-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 '../../shared/paths.js';
-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/doctor-service.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/src/services/dispatch/batch-counter.js

@@ -1,102 +0,0 @@
-/**
- * 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 '../filesystem/file-lock.js';
-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 */
-        }
-    }
-}