peaks-cli 1.3.2 → 1.3.4

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

@@ -0,0 +1,285 @@
+/**
+ * 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, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { assertSafeSharedChannelPath, sharedChannelPath } from './dispatch-context-guard.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);
+    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 = {
+        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 {
+        const { unlinkSync } = require('node:fs');
+        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 stat = require('node:fs');
+    const s = stat.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;
+    return (typeof v.at === 'string' &&
+        typeof v.from === 'string' &&
+        typeof v.key === 'string' &&
+        isObject(v.value) &&
+        typeof v.valueSize === 'number');
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function writeAtomic(path, channel) {
+    const dir = dirname(path);
+    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/context/threshold.d.ts

@@ -0,0 +1,35 @@
+/**
+ * G9.3 — forced compression gate threshold constants + tier evaluation.
+ *
+ * 256K default context capacity is a conservative proxy. The LLM's real
+ * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
+ * inherited from slice #009); we use prompt size as the gate signal.
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
+ * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
+ */
+export declare const CONTEXT_CAPACITY_DEFAULT_BYTES: number;
+export declare const THRESHOLD_SOFT_WARN_RATIO = 0.5;
+export declare const THRESHOLD_NEAR_LIMIT_RATIO = 0.75;
+export declare const THRESHOLD_HARD_REJECT_RATIO = 0.8;
+export declare const THRESHOLD_EMERGENCY_RATIO = 0.9;
+export type ThresholdTier = 'ok' | 'soft-warn' | 'near-limit' | 'hard-reject' | 'emergency';
+export interface ThresholdEvaluation {
+    readonly tier: ThresholdTier;
+    readonly ratio: number;
+    readonly bytesUsed: number;
+    readonly capacityBytes: number;
+    readonly warnings: readonly string[];
+}
+/**
+ * Compute the threshold tier for a given prompt size. Pure function
+ * (no IO, no side effects). The `capacityBytes` parameter lets callers
+ * override the default 256K proxy (e.g. for testing or for a future
+ * per-IDE capacity override).
+ */
+export declare function evaluateThresholdTier(promptSize: number, capacityBytes?: number): ThresholdEvaluation;
+/**
+ * Convert a threshold tier to a machine-readable code suitable for the
+ * CLI envelope's `code` field. Used by both the CLI and the hook layer.
+ */
+export declare function tierToCode(tier: ThresholdTier): string;

package/dist/src/services/context/threshold.js

@@ -0,0 +1,76 @@
+/**
+ * G9.3 — forced compression gate threshold constants + tier evaluation.
+ *
+ * 256K default context capacity is a conservative proxy. The LLM's real
+ * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
+ * inherited from slice #009); we use prompt size as the gate signal.
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
+ * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
+ */
+export const CONTEXT_CAPACITY_DEFAULT_BYTES = 256 * 1024; // 256K
+export const THRESHOLD_SOFT_WARN_RATIO = 0.5; // 50%
+export const THRESHOLD_NEAR_LIMIT_RATIO = 0.75; // 75% — user red line
+export const THRESHOLD_HARD_REJECT_RATIO = 0.80; // 80%
+export const THRESHOLD_EMERGENCY_RATIO = 0.90; // 90%
+/**
+ * Compute the threshold tier for a given prompt size. Pure function
+ * (no IO, no side effects). The `capacityBytes` parameter lets callers
+ * override the default 256K proxy (e.g. for testing or for a future
+ * per-IDE capacity override).
+ */
+export function evaluateThresholdTier(promptSize, capacityBytes = CONTEXT_CAPACITY_DEFAULT_BYTES) {
+    if (!Number.isFinite(promptSize) || promptSize < 0) {
+        throw new Error(`evaluateThresholdTier: promptSize must be ≥ 0 (got ${promptSize})`);
+    }
+    if (!Number.isFinite(capacityBytes) || capacityBytes <= 0) {
+        throw new Error(`evaluateThresholdTier: capacityBytes must be > 0 (got ${capacityBytes})`);
+    }
+    const ratio = promptSize / capacityBytes;
+    const warnings = [];
+    let tier;
+    if (ratio >= THRESHOLD_EMERGENCY_RATIO) {
+        tier = 'emergency';
+        warnings.push('PROMPT_EMERGENCY');
+    }
+    else if (ratio >= THRESHOLD_HARD_REJECT_RATIO) {
+        tier = 'hard-reject';
+        warnings.push('PROMPT_TOO_LARGE');
+    }
+    else if (ratio >= THRESHOLD_NEAR_LIMIT_RATIO) {
+        tier = 'near-limit';
+        warnings.push('CONTEXT_NEAR_LIMIT');
+    }
+    else if (ratio >= THRESHOLD_SOFT_WARN_RATIO) {
+        tier = 'soft-warn';
+        warnings.push('CONTEXT_SOFT_WARN');
+    }
+    else {
+        tier = 'ok';
+    }
+    return {
+        tier,
+        ratio,
+        bytesUsed: promptSize,
+        capacityBytes,
+        warnings
+    };
+}
+/**
+ * Convert a threshold tier to a machine-readable code suitable for the
+ * CLI envelope's `code` field. Used by both the CLI and the hook layer.
+ */
+export function tierToCode(tier) {
+    switch (tier) {
+        case 'ok':
+            return 'OK';
+        case 'soft-warn':
+            return 'CONTEXT_SOFT_WARN';
+        case 'near-limit':
+            return 'CONTEXT_NEAR_LIMIT';
+        case 'hard-reject':
+            return 'PROMPT_TOO_LARGE';
+        case 'emergency':
+            return 'PROMPT_EMERGENCY';
+    }
+}

package/dist/src/services/dashboard/project-dashboard-service.d.ts

@@ -27,6 +27,26 @@ export type ProjectDashboardDoctor = {
     ok: boolean;
     passed: number;
     failed: number;
+    okCount?: number;
+    failCount?: number;
+    lastRunAt?: string;
+    checkIds?: string[];
+};
+export type DashboardOkPolicy = 'workspace-only' | 'strict';
+/**
+ * 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 declare function resolveDashboardOk(args: {
+    okPolicy: DashboardOkPolicy;
+    doctor: ProjectDashboardDoctor;
+    runbookHealth: ProjectDashboardRunbookHealth;
+}): {
+    ok: boolean;
+    okPolicy: DashboardOkPolicy;
 };
 export type ProjectDashboardRunbookHealth = {
     ok: boolean;
@@ -51,6 +71,8 @@ export type ProjectDashboardSkillPresence = {
 export type ProjectDashboard = {
     generatedAt: string;
     projectRoot: string;
+    ok: boolean;
+    okPolicy: DashboardOkPolicy;
     requests: ProjectDashboardRequests;
     openspec: ProjectDashboardOpenSpec;
     understand: ProjectDashboardUnderstand;
@@ -71,5 +93,6 @@ export type LoadProjectDashboardOptions = {
     };
     runbookHealth?: ProjectDashboardRunbookHealth;
     skillPresence?: SkillPresence | null;
+    okPolicy?: DashboardOkPolicy;
 };
 export declare function loadProjectDashboard(options: LoadProjectDashboardOptions): Promise<ProjectDashboard>;

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

@@ -6,6 +6,19 @@ 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();
 }
@@ -95,6 +108,7 @@ function buildSkillPresenceSummary(presence, projectRoot) {
 export async function loadProjectDashboard(options) {
     const clock = options.clock ?? defaultClock;
     const sampleSize = options.sampleCapabilities ?? 8;
+    const okPolicy = options.okPolicy ?? 'workspace-only';
     const [items, openspecReport, mcpReport, understandReport, doctorAndRunbook] = await Promise.all([
         listRequestArtifacts({ projectRoot: options.projectRoot }),
         scanOpenSpec({ openspecRoot: `${options.projectRoot}/openspec` }),
@@ -102,9 +116,16 @@ export async function loadProjectDashboard(options) {
         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),

package/dist/src/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/src/services/dispatch/batch-counter.js

@@ -0,0 +1,85 @@
+/**
+ * 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-solo'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';
+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);
+    mkdirSync(dirname(path), { recursive: true });
+    const previous = readBatchCount(projectRoot, sid, batchId);
+    const next = {
+        batchId,
+        sessionId: sid,
+        createdAt: now().toISOString(),
+        count: previous + 1
+    };
+    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 {
+            /* best-effort; counter file is informational */
+        }
+    }
+}