peaks-loop 4.0.35 → 4.0.36

package/dist/services/context/context-audit.js

@@ -0,0 +1,322 @@
+/**
+ * `peaks code context-audit` — what actually fills the orchestrator's window.
+ *
+ * Slice 2026-09-10-context-audit-and-discipline (Slice A).
+ *
+ * Why this exists: `peaks code context-now` reports a RATIO only. Nothing
+ * reported WHAT occupies the window, so the same 40K-token mistake (dumping a
+ * full `peaks memory reindex --json` array four times in one session) was
+ * invisible until the window was 68% gone. The IDE transcript already holds
+ * per-message tool results, so the breakdown is derivable locally, with zero
+ * tokens spent asking a model.
+ *
+ * Contract:
+ *   - READ-ONLY. The transcript is never modified.
+ *   - FAIL-SOFT. A missing / oversized / corrupt transcript yields
+ *     `available: false` plus a machine-readable `reason`. Never throws,
+ *     never blocks a workflow, never exits non-zero on its own.
+ *   - NO CONTENT. The envelope carries tool names, short command/path keys
+ *     and byte counts — never the tool result text itself (dumping it would
+ *     re-create the very problem this command measures).
+ *   - BOUNDED MEMORY. The transcript can be tens of MB; it is streamed in
+ *     fixed-size chunks with a carried partial line, never read whole.
+ *
+ * Grouping key = `(tool name, short input key)`. The key is a *stable
+ * summary* of the tool input — the Bash command line, the file path tail, the
+ * grep pattern — so "4 × the same 40KB reindex dump" collapses into ONE row
+ * with `count: 4` instead of four anonymous entries.
+ */
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { getAdapter } from '../ide/ide-registry.js';
+import { detectIdeFromEnv } from './ide-detect.js';
+/** Default number of top entries emitted. */
+export const CONTEXT_AUDIT_DEFAULT_TOP = 15;
+/** Hard ceiling for `--top` — the envelope must stay small by construction. */
+export const CONTEXT_AUDIT_MAX_TOP = 100;
+/** Transcripts larger than this are reported `available:false` (fail-soft). */
+export const CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES = 256 * 1024 * 1024;
+/** Streaming chunk size (bounded memory on multi-MB transcripts). */
+const SCAN_CHUNK_BYTES = 1024 * 1024;
+/** Max characters kept in a group key — keys are labels, not payloads. */
+const KEY_MAX_CHARS = 100;
+/** Clamp a caller-supplied `--top` into the documented range. */
+export function normalizeTopN(value) {
+    const n = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : CONTEXT_AUDIT_DEFAULT_TOP;
+    if (n < 1)
+        return CONTEXT_AUDIT_DEFAULT_TOP;
+    return Math.min(n, CONTEXT_AUDIT_MAX_TOP);
+}
+function clip(text, max) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= max ? collapsed : `${collapsed.slice(0, max - 1)}…`;
+}
+/** Last `n` path segments — keeps `Read` / `Edit` keys short but identifiable. */
+function tailPath(value, n) {
+    const parts = value.split(/[\\/]/).filter((p) => p.length > 0);
+    return parts.slice(Math.max(0, parts.length - n)).join('/');
+}
+/**
+ * Build the stable group key for one tool call. Unknown tools fall back to a
+ * clipped JSON rendering of their input so the group is still recognizable.
+ */
+export function contextAuditKey(tool, input) {
+    const read = (v) => (typeof v === 'string' ? v : '');
+    if (typeof input !== 'object' || input === null)
+        return '';
+    const i = input;
+    switch (tool) {
+        case 'Bash':
+            return clip(read(i.command), KEY_MAX_CHARS);
+        case 'Read':
+        case 'Write':
+        case 'Edit':
+        case 'NotebookEdit':
+            return clip(tailPath(read(i.file_path), 2), KEY_MAX_CHARS);
+        case 'Grep':
+        case 'Glob':
+            return clip(`${read(i.pattern)} @ ${read(i.path) || '.'}`, KEY_MAX_CHARS);
+        case 'Task':
+        case 'Agent':
+            return clip(read(i.description) || read(i.subagent_type), 60);
+        default: {
+            let json;
+            try {
+                json = JSON.stringify(input) ?? '';
+            }
+            catch {
+                json = '';
+            }
+            return clip(json, 80);
+        }
+    }
+}
+/** UTF-8 size of a `tool_result.content` payload (string | array | object). */
+function toolResultBytes(content) {
+    if (typeof content === 'string')
+        return Buffer.byteLength(content, 'utf8');
+    if (Array.isArray(content)) {
+        let total = 0;
+        for (const part of content) {
+            if (typeof part === 'string') {
+                total += Buffer.byteLength(part, 'utf8');
+            }
+            else if (typeof part === 'object' && part !== null) {
+                const text = part.text;
+                total += typeof text === 'string'
+                    ? Buffer.byteLength(text, 'utf8')
+                    : Buffer.byteLength(JSON.stringify(part) ?? '', 'utf8');
+            }
+        }
+        return total;
+    }
+    if (content === undefined || content === null)
+        return 0;
+    try {
+        return Buffer.byteLength(JSON.stringify(content) ?? '', 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
+function emptyResult(partial) {
+    return {
+        available: false,
+        reason: null,
+        transcriptPath: null,
+        totalBytes: 0,
+        entryCount: 0,
+        groupCount: 0,
+        topN: CONTEXT_AUDIT_DEFAULT_TOP,
+        entries: [],
+        ...partial,
+    };
+}
+/**
+ * Stream the transcript once, folding every tool result into its
+ * `(tool, key)` group. Pure bookkeeping — no content is retained.
+ */
+function scanTranscript(filePath, topN) {
+    const toolUses = new Map();
+    const groups = new Map();
+    let totalBytes = 0;
+    let entryCount = 0;
+    const fd = openSync(filePath, 'r');
+    try {
+        const size = statSync(filePath).size;
+        let position = 0;
+        let carry = '';
+        while (position < size) {
+            const readLen = Math.min(SCAN_CHUNK_BYTES, size - position);
+            const buf = Buffer.alloc(readLen);
+            const bytesRead = readSync(fd, buf, 0, readLen, position);
+            if (bytesRead <= 0)
+                break;
+            position += bytesRead;
+            const lines = (carry + buf.toString('utf8', 0, bytesRead)).split('\n');
+            // The last element is a partial line (or the trailing empty string).
+            carry = lines.pop() ?? '';
+            for (const line of lines) {
+                if (line.length === 0)
+                    continue;
+                const folded = foldLine(line, toolUses, groups);
+                totalBytes += folded.bytes;
+                entryCount += folded.count;
+            }
+        }
+        if (carry.length > 0) {
+            const folded = foldLine(carry, toolUses, groups);
+            totalBytes += folded.bytes;
+            entryCount += folded.count;
+        }
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* best-effort close */
+        }
+    }
+    const entries = [...groups.values()]
+        .map((g) => ({
+        tool: g.tool,
+        key: g.key,
+        bytes: g.bytes,
+        // Percentage in [0, 100], one decimal — see ContextAuditEntry.pctOfTotal.
+        pctOfTotal: totalBytes > 0 ? Math.round((g.bytes / totalBytes) * 1000) / 10 : 0,
+        count: g.count,
+    }))
+        .sort((a, b) => b.bytes - a.bytes || a.tool.localeCompare(b.tool) || a.key.localeCompare(b.key));
+    return {
+        available: true,
+        reason: null,
+        transcriptPath: filePath,
+        totalBytes,
+        entryCount,
+        groupCount: entries.length,
+        topN,
+        entries: entries.slice(0, topN),
+    };
+}
+/**
+ * Fold ONE jsonl line into the running state. Returns the byte/count delta
+ * contributed by this line. Corrupt / non-JSON lines are skipped silently —
+ * a truncated tail must not fail the audit.
+ */
+function foldLine(line, toolUses, groups) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { bytes: 0, count: 0 };
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return { bytes: 0, count: 0 };
+    const record = parsed;
+    const message = record.message;
+    if (typeof message !== 'object' || message === null)
+        return { bytes: 0, count: 0 };
+    const content = message.content;
+    if (!Array.isArray(content))
+        return { bytes: 0, count: 0 };
+    let bytes = 0;
+    let count = 0;
+    for (const part of content) {
+        if (typeof part !== 'object' || part === null)
+            continue;
+        const item = part;
+        if (item.type === 'tool_use') {
+            const id = item.id;
+            const name = item.name;
+            if (typeof id === 'string' && typeof name === 'string') {
+                toolUses.set(id, { name, input: item.input });
+            }
+            continue;
+        }
+        if (item.type !== 'tool_result')
+            continue;
+        const ref = typeof item.tool_use_id === 'string' ? toolUses.get(item.tool_use_id) : undefined;
+        const tool = ref?.name ?? 'unknown';
+        const key = ref === undefined ? '' : contextAuditKey(tool, ref.input);
+        const size = toolResultBytes(item.content);
+        const groupKey = `${tool}${key}`;
+        const group = groups.get(groupKey);
+        if (group === undefined) {
+            groups.set(groupKey, { tool, key, bytes: size, count: 1 });
+        }
+        else {
+            group.bytes += size;
+            group.count += 1;
+        }
+        bytes += size;
+        count += 1;
+    }
+    return { bytes, count };
+}
+/**
+ * Audit the CURRENT session's transcript. Never throws.
+ *
+ * Unavailability reasons (all return `available: false`, exit code stays 0):
+ *   - `no-outer-session-id`  — the peaks session has no bound outer id
+ *   - `transcript-locator-unavailable` — the active IDE adapter does not
+ *                              declare `compact.resolveTranscriptPath`
+ *   - `transcript-not-found` — the adapter locator returned null
+ *   - `transcript-too-large` — above `CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES`
+ *   - `transcript-unreadable`— stat/open failed
+ *   - `audit-failed`         — any unexpected internal error
+ */
+export function auditContext(input = {}) {
+    const topN = normalizeTopN(input.topN);
+    const explicit = input.transcriptPath;
+    let transcriptPath = null;
+    if (typeof explicit === 'string' && explicit.length > 0) {
+        transcriptPath = explicit;
+    }
+    else {
+        const outerSessionId = input.outerSessionId;
+        if (typeof outerSessionId !== 'string' || outerSessionId.length === 0) {
+            return emptyResult({ reason: 'no-outer-session-id', topN });
+        }
+        // Vendor-neutral: the adapter owns the on-disk layout. Mirrors
+        // `readContextPercent`'s narrowing of the detected kind to a
+        // registered adapter id ('unknown' → claude-code default). Both the
+        // registry lookup and the locator call are guarded — an unregistered
+        // detected id (e.g. an IDE without a peaks adapter yet) or an adapter
+        // bug must degrade, never throw.
+        let transcriptPathOrNull;
+        try {
+            const detected = detectIdeFromEnv(input.env ?? process.env);
+            const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+            const locate = getAdapter(ideId).compact?.resolveTranscriptPath;
+            if (locate === undefined) {
+                return emptyResult({ reason: 'transcript-locator-unavailable', topN });
+            }
+            transcriptPathOrNull = locate(outerSessionId);
+        }
+        catch {
+            return emptyResult({ reason: 'transcript-locator-unavailable', topN });
+        }
+        if (transcriptPathOrNull === null) {
+            return emptyResult({ reason: 'transcript-not-found', topN });
+        }
+        transcriptPath = transcriptPathOrNull;
+    }
+    const maxBytes = typeof input.maxTranscriptBytes === 'number' && Number.isFinite(input.maxTranscriptBytes) && input.maxTranscriptBytes >= 0
+        ? input.maxTranscriptBytes
+        : CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES;
+    try {
+        const size = statSync(transcriptPath).size;
+        if (size > maxBytes) {
+            return emptyResult({ reason: 'transcript-too-large', transcriptPath, topN });
+        }
+        return scanTranscript(transcriptPath, topN);
+    }
+    catch (err) {
+        const code = err.code;
+        const reason = code === 'ENOENT' ? 'transcript-not-found'
+            : code === 'EACCES' || code === 'EPERM' ? 'transcript-unreadable'
+                : 'audit-failed';
+        return emptyResult({ reason, transcriptPath, topN });
+    }
+}

package/dist/services/context/summary-view.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `--summary` — bounded, additive views of large CLI envelopes.
+ *
+ * Slice 2026-09-10-context-audit-and-discipline (Slice B, part 1).
+ *
+ * Rationale (measured, session 2026-09-07-session-245530): dumping a full
+ * `peaks memory reindex --json` array four times cost ≈ 160 KB ≈ 40K tokens
+ * of orchestrator context — roughly 4% of a 1M window for ONE command
+ * repeated. The default envelopes stay exactly as they are (back-compat);
+ * `--summary` is an OPT-IN view that keeps counts + names-of-first-N and
+ * drops the per-entry bodies, which remain on disk and are re-readable with
+ * the full command. No information is destroyed — only the in-context copy
+ * shrinks.
+ *
+ * Byte bound: every summary object is passed through `fitSummaryToBytes`,
+ * which shrinks string arrays (longest first) until the JSON serialization is
+ * ≤ `SUMMARY_DATA_MAX_BYTES` (2 KB minus a small envelope reserve, so the
+ * PRINTED envelope stays ≤ `SUMMARY_MAX_BYTES`). Scalars are never touched,
+ * so counts and paths stay exact.
+ */
+/** Hard ceiling for the PRINTED `--summary` envelope, in UTF-8 bytes. */
+export declare const SUMMARY_MAX_BYTES = 2048;
+/**
+ * Reserve for the envelope wrapper (`ok`/`command`/`warnings`/`nextActions`/
+ * error fields) that the CLI adds around `data`. The builders cap `data` at
+ * `SUMMARY_DATA_MAX_BYTES` so the whole printed envelope stays ≤ 2 KB.
+ */
+export declare const SUMMARY_ENVELOPE_RESERVE_BYTES = 512;
+/** Cap applied to the summary `data` object itself (pretty-printed size). */
+export declare const SUMMARY_DATA_MAX_BYTES: number;
+/** Per-name character cap — a name is a label, not a document. */
+export declare const SUMMARY_NAME_MAX_CHARS = 120;
+/** How many names each command asks for before the byte fitter trims. */
+export declare const SUMMARY_INITIAL_NAMES = 40;
+/** A bounded `{count, names}` view: `count` is the true total, `names` a prefix. */
+export interface BoundedNames {
+    readonly count: number;
+    readonly names: readonly string[];
+}
+/**
+ * Build a `{count, names}` view. `count` is always the full length; `names`
+ * carries the first `SUMMARY_INITIAL_NAMES` (clipped) entries — the byte
+ * fitter may trim further.
+ */
+export declare function boundedNames(names: readonly string[]): BoundedNames;
+/**
+ * Shrink `data` (in place on a clone) until its JSON form fits `maxBytes`.
+ *
+ * Algorithm: repeatedly find the LONGEST nested array and drop its last
+ * element. Scalars are never modified, so `count` fields stay truthful; the
+ * `names` arrays simply show fewer names. Returns the input unchanged when it
+ * already fits or when there is no array left to trim.
+ */
+export declare function fitSummaryToBytes<T extends Record<string, unknown>>(data: T, maxBytes?: number): T;

package/dist/services/context/summary-view.js

@@ -0,0 +1,114 @@
+/**
+ * `--summary` — bounded, additive views of large CLI envelopes.
+ *
+ * Slice 2026-09-10-context-audit-and-discipline (Slice B, part 1).
+ *
+ * Rationale (measured, session 2026-09-07-session-245530): dumping a full
+ * `peaks memory reindex --json` array four times cost ≈ 160 KB ≈ 40K tokens
+ * of orchestrator context — roughly 4% of a 1M window for ONE command
+ * repeated. The default envelopes stay exactly as they are (back-compat);
+ * `--summary` is an OPT-IN view that keeps counts + names-of-first-N and
+ * drops the per-entry bodies, which remain on disk and are re-readable with
+ * the full command. No information is destroyed — only the in-context copy
+ * shrinks.
+ *
+ * Byte bound: every summary object is passed through `fitSummaryToBytes`,
+ * which shrinks string arrays (longest first) until the JSON serialization is
+ * ≤ `SUMMARY_DATA_MAX_BYTES` (2 KB minus a small envelope reserve, so the
+ * PRINTED envelope stays ≤ `SUMMARY_MAX_BYTES`). Scalars are never touched,
+ * so counts and paths stay exact.
+ */
+/** Hard ceiling for the PRINTED `--summary` envelope, in UTF-8 bytes. */
+export const SUMMARY_MAX_BYTES = 2048;
+/**
+ * Reserve for the envelope wrapper (`ok`/`command`/`warnings`/`nextActions`/
+ * error fields) that the CLI adds around `data`. The builders cap `data` at
+ * `SUMMARY_DATA_MAX_BYTES` so the whole printed envelope stays ≤ 2 KB.
+ */
+export const SUMMARY_ENVELOPE_RESERVE_BYTES = 512;
+/** Cap applied to the summary `data` object itself (pretty-printed size). */
+export const SUMMARY_DATA_MAX_BYTES = SUMMARY_MAX_BYTES - SUMMARY_ENVELOPE_RESERVE_BYTES;
+/** Per-name character cap — a name is a label, not a document. */
+export const SUMMARY_NAME_MAX_CHARS = 120;
+/** How many names each command asks for before the byte fitter trims. */
+export const SUMMARY_INITIAL_NAMES = 40;
+function clipName(name, maxChars) {
+    const collapsed = name.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= maxChars ? collapsed : `${collapsed.slice(0, maxChars - 1)}…`;
+}
+/**
+ * Build a `{count, names}` view. `count` is always the full length; `names`
+ * carries the first `SUMMARY_INITIAL_NAMES` (clipped) entries — the byte
+ * fitter may trim further.
+ */
+export function boundedNames(names) {
+    return {
+        count: names.length,
+        names: names.slice(0, SUMMARY_INITIAL_NAMES).map((n) => clipName(n, SUMMARY_NAME_MAX_CHARS)),
+    };
+}
+/**
+ * Size of the value AS PRINTED — `printResult` serializes with `null, 2`, so
+ * the bound must be measured on the pretty form, not the compact one.
+ */
+function byteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value, null, 2) ?? '', 'utf8');
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+/** Collect every array (with its key path) nested in `node`. */
+function collectArrays(node, path, out) {
+    if (Array.isArray(node)) {
+        out.push({ path, array: node });
+        return;
+    }
+    if (typeof node !== 'object' || node === null)
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        collectArrays(value, path === '' ? key : `${path}.${key}`, out);
+    }
+}
+/**
+ * Shrink `data` (in place on a clone) until its JSON form fits `maxBytes`.
+ *
+ * Algorithm: repeatedly find the LONGEST nested array and drop its last
+ * element. Scalars are never modified, so `count` fields stay truthful; the
+ * `names` arrays simply show fewer names. Returns the input unchanged when it
+ * already fits or when there is no array left to trim.
+ */
+export function fitSummaryToBytes(data, maxBytes = SUMMARY_DATA_MAX_BYTES) {
+    let out;
+    try {
+        out = structuredClone(data);
+    }
+    catch {
+        try {
+            out = JSON.parse(JSON.stringify(data));
+        }
+        catch {
+            return data; // not serializable — leave the caller's object alone
+        }
+    }
+    // Each iteration removes one element, so the bound is the total element
+    // count — a cheap upper limit that can never spin forever.
+    for (let guard = 0; guard < 100_000; guard++) {
+        if (byteLength(out) <= maxBytes)
+            return out;
+        const arrays = [];
+        collectArrays(out, '', arrays);
+        let longest = null;
+        for (const candidate of arrays) {
+            if (candidate.array.length === 0)
+                continue;
+            if (longest === null || candidate.array.length > longest.array.length)
+                longest = candidate;
+        }
+        if (longest === null)
+            return out; // nothing left to shrink
+        longest.array.pop();
+    }
+    return out;
+}

package/dist/services/dispatch/file-overlap-wave-planner.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §3 — file-overlap-aware
+ * parallel scheduling.
+ *
+ * Problem: fan-out is mandatory, but the orchestrator serializes whenever
+ * two slices touch the same file (observed 2026-09-07: two slices both
+ * edited `src/cli/commands/code-runtime-commands.ts`, forcing a wait).
+ * Topological DAG levels do not know about files, so a "parallel" level can
+ * still contain a write/write conflict.
+ *
+ * Solution: a pure planner over slice descriptors `{ id, files[] }` that
+ * returns WAVES. Every slice in a wave has a file set pairwise disjoint
+ * from every other slice in that wave. A slice whose files collide with an
+ * earlier wave is deferred to a later wave, and the plan records WHICH file
+ * collided with WHICH already-scheduled slice — so the caller can explain
+ * the serialization instead of silently waiting.
+ *
+ * Pure: no I/O, no clock, deterministic for a given input.
+ *
+ * Relationship to `planDispatchWaves` (dag-orchestrator.ts): that planner
+ * chunks a topological level by `maxConcurrency` only. This planner is
+ * orthogonal — it refines a level (or any slice set) by file overlap. The
+ * `--from-dag` path uses this one additively (see `firstLevelWaves` in the
+ * dispatch envelope); the topological scheduler itself is unchanged.
+ */
+/** One unit of work and the files it is expected to touch. */
+export interface SliceFileDescriptor {
+    readonly id: string;
+    readonly files: readonly string[];
+}
+/** Why a slice did not land in the first wave it was considered for. */
+export interface WaveDeferral {
+    readonly id: string;
+    /** Wave the slice was placed in. */
+    readonly waveIndex: number;
+    /** The file that collided. */
+    readonly collidingFile: string;
+    /** The slice already scheduled in an earlier wave that holds that file. */
+    readonly collidedWith: string;
+    /** Human-readable one-liner (stable wording). */
+    readonly reason: string;
+}
+export interface FileOverlapWave {
+    readonly waveIndex: number;
+    /** Slice ids in input order. */
+    readonly slices: readonly string[];
+    /** Union of the wave's files, sorted. */
+    readonly files: readonly string[];
+    /** Deferrals resolved INTO this wave. */
+    readonly deferred: readonly WaveDeferral[];
+}
+export interface FileOverlapWavePlan {
+    readonly waves: readonly FileOverlapWave[];
+    /** Slice ids that appeared more than once; only the first is scheduled. */
+    readonly duplicateIds: readonly string[];
+    /** Number of distinct slices scheduled. */
+    readonly sliceCount: number;
+}
+/**
+ * Plan waves such that no two slices in the same wave share a file.
+ *
+ * Greedy, input-order stable: each slice goes into the earliest existing
+ * wave whose files are disjoint from its own; otherwise a new wave is
+ * opened. A slice with no files never collides.
+ *
+ * Duplicate ids: the FIRST descriptor wins; later ones are reported in
+ * `duplicateIds` and not scheduled (scheduling the same slice twice would
+ * double-dispatch it).
+ */
+export declare function planFileOverlapWaves(slices: readonly SliceFileDescriptor[]): FileOverlapWavePlan;

package/dist/services/dispatch/file-overlap-wave-planner.js

@@ -0,0 +1,119 @@
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §3 — file-overlap-aware
+ * parallel scheduling.
+ *
+ * Problem: fan-out is mandatory, but the orchestrator serializes whenever
+ * two slices touch the same file (observed 2026-09-07: two slices both
+ * edited `src/cli/commands/code-runtime-commands.ts`, forcing a wait).
+ * Topological DAG levels do not know about files, so a "parallel" level can
+ * still contain a write/write conflict.
+ *
+ * Solution: a pure planner over slice descriptors `{ id, files[] }` that
+ * returns WAVES. Every slice in a wave has a file set pairwise disjoint
+ * from every other slice in that wave. A slice whose files collide with an
+ * earlier wave is deferred to a later wave, and the plan records WHICH file
+ * collided with WHICH already-scheduled slice — so the caller can explain
+ * the serialization instead of silently waiting.
+ *
+ * Pure: no I/O, no clock, deterministic for a given input.
+ *
+ * Relationship to `planDispatchWaves` (dag-orchestrator.ts): that planner
+ * chunks a topological level by `maxConcurrency` only. This planner is
+ * orthogonal — it refines a level (or any slice set) by file overlap. The
+ * `--from-dag` path uses this one additively (see `firstLevelWaves` in the
+ * dispatch envelope); the topological scheduler itself is unchanged.
+ */
+/**
+ * Plan waves such that no two slices in the same wave share a file.
+ *
+ * Greedy, input-order stable: each slice goes into the earliest existing
+ * wave whose files are disjoint from its own; otherwise a new wave is
+ * opened. A slice with no files never collides.
+ *
+ * Duplicate ids: the FIRST descriptor wins; later ones are reported in
+ * `duplicateIds` and not scheduled (scheduling the same slice twice would
+ * double-dispatch it).
+ */
+export function planFileOverlapWaves(slices) {
+    const duplicateIds = [];
+    const seenIds = new Set();
+    const ordered = [];
+    for (const slice of slices) {
+        if (typeof slice?.id !== 'string' || slice.id.length === 0)
+            continue;
+        if (seenIds.has(slice.id)) {
+            duplicateIds.push(slice.id);
+            continue;
+        }
+        seenIds.add(slice.id);
+        ordered.push({ id: slice.id, files: normalizeFiles(slice.files) });
+    }
+    const waves = [];
+    for (const slice of ordered) {
+        // First wave whose file set is disjoint from this slice's.
+        let placedAt = -1;
+        let collision = null;
+        for (let w = 0; w < waves.length; w += 1) {
+            const wave = waves[w];
+            if (wave === undefined)
+                continue;
+            let hit = null;
+            for (const file of slice.files) {
+                const owner = wave.owner.get(file);
+                if (owner !== undefined) {
+                    hit = { file, withSlice: owner };
+                    break;
+                }
+            }
+            if (hit === null) {
+                placedAt = w;
+                break;
+            }
+            // Remember the FIRST collision (earliest wave) for the reason string.
+            if (collision === null) {
+                collision = { file: hit.file, withSlice: hit.withSlice, waveIndex: w };
+            }
+        }
+        if (placedAt === -1) {
+            placedAt = waves.length;
+            waves.push({ slices: [], files: new Set(), owner: new Map(), deferred: [] });
+        }
+        const target = waves[placedAt];
+        if (target === undefined)
+            continue; // unreachable; satisfies strict TS
+        target.slices.push(slice.id);
+        for (const file of slice.files) {
+            target.files.add(file);
+            target.owner.set(file, slice.id);
+        }
+        if (collision !== null && placedAt > 0) {
+            target.deferred.push({
+                id: slice.id,
+                waveIndex: placedAt,
+                collidingFile: collision.file,
+                collidedWith: collision.withSlice,
+                reason: `deferred to wave ${placedAt}: file "${collision.file}" already scheduled in wave ${collision.waveIndex} by slice "${collision.withSlice}"`
+            });
+        }
+    }
+    return {
+        waves: waves.map((w, index) => ({
+            waveIndex: index,
+            slices: w.slices,
+            files: [...w.files].sort(),
+            deferred: w.deferred
+        })),
+        duplicateIds,
+        sliceCount: ordered.length
+    };
+}
+function normalizeFiles(files) {
+    if (!Array.isArray(files))
+        return [];
+    const set = new Set();
+    for (const f of files) {
+        if (typeof f === 'string' && f.length > 0)
+            set.add(f);
+    }
+    return [...set].sort();
+}