peaks-loop 4.0.54 → 4.1.0

package/dist/services/context/auto-compact-types.d.ts

@@ -36,52 +36,8 @@
  * harness — see `harness-window-config.ts`.
  */
 import type { HarnessWindowSyncResult } from './harness-window-config.js';
-export declare const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
-export declare const AUTO_COMPACT_AUTO_FIRE_RATIO = 0.8;
-export declare const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
-export declare const AUTO_COMPACT_RED_LINE_RATIO = 0.95;
-export declare const AUTO_COMPACT_THRESHOLD_RATIO = 0.8;
-/** Single source of truth for "what should we do at ratio X?" */
-export type CompactTrigger = {
-    kind: 'none';
-} | {
-    kind: 'soft-warn';
-    ratio: number;
-    message: string;
-}
-/**
- * Part 22: auto-fire zone (0.80 ≤ ratio < 0.85). peaks-loop
- * preempts and runs `peaks code auto-compact` itself
- * without LLM involvement. The LLM is not asked to "decide";
- * the toolkit is applied synchronously.
- */
- | {
-    kind: 'auto-fire';
-    ratio: number;
-    message: string;
-}
-/**
- * Pre-compact zone (0.85 ≤ ratio < 0.95): LLM-runner can still
- * pre-empt the compact for one in-flight sub-agent or one
- * todo row, but peaks-loop flags this as the last safe
- * window. Kept for backward compat; in practice peaks-loop
- * auto-fired at 0.80 already.
- */
- | {
-    kind: 'pre-compact';
-    ratio: number;
-    message: string;
-    toolkitReady: true;
-}
-/**
- * Red line (ratio ≥ 0.95): peaks-loop asks the harness to compact and says
- * it is waiting. Dispatch is NOT blocked — see `redLineRequested`.
- */
- | {
-    kind: 'red-line';
-    ratio: number;
-    message: string;
-};
+export { AUTO_COMPACT_SOFT_WARN_RATIO, AUTO_COMPACT_AUTO_FIRE_RATIO, AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_RED_LINE_RATIO, AUTO_COMPACT_THRESHOLD_RATIO } from './auto-compact-thresholds.js';
+export type { CompactTrigger } from './auto-compact-thresholds.js';
 /** Caller-side info about sub-agent batches in flight (D6.e). */
 export interface InFlightBatchProbe {
     readonly hasInFlightBatch: boolean;

package/dist/services/context/auto-compact-types.js

@@ -1,14 +1,4 @@
-export const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
-// Part 22: auto-fire threshold (was 0.85 pre-compact zone where
-// the LLM had to decide; LLM misjudged 0.85–0.95 and only fired
-// at 0.95, which let the LLM time the run anyway). Lowered to
-// 0.80 so peaks-loop auto-fires compact without LLM involvement
-// — the LLM keeps working, peaks-loop preempts when ratio crosses
-// the new threshold.
-export const AUTO_COMPACT_AUTO_FIRE_RATIO = 0.80;
-export const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
-export const AUTO_COMPACT_RED_LINE_RATIO = 0.95;
-export const AUTO_COMPACT_THRESHOLD_RATIO = AUTO_COMPACT_AUTO_FIRE_RATIO;
+export { AUTO_COMPACT_SOFT_WARN_RATIO, AUTO_COMPACT_AUTO_FIRE_RATIO, AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_RED_LINE_RATIO, AUTO_COMPACT_THRESHOLD_RATIO } from './auto-compact-thresholds.js';
 /**
  * Old → new map of envelope fields that were renamed but are still emitted
  * under their old name as deprecated aliases.

package/dist/services/context/build-dispatch-system-prompt.js

@@ -352,7 +352,7 @@ export const BINDING_RULE_TOKENS = [
     'do NOT invoke `npx <runner>`',
     '## Test Scope (mandatory)',
     'PEAKS_FULL_TEST=1',
-    'refused',
+    'refused'
 ];
 /**
  * The runner-direct-path tokens: the refusal example, the two direct paths
@@ -371,7 +371,7 @@ export const TEST_RUNNER_RULE_TOKENS = [
     'PB-5',
     '`peaks test --json`',
     'ask the user before assuming a runner',
-    '(Windows-aware)',
+    '(Windows-aware)'
 ];
 /**
  * Return the subset of `tokens` that `text` does NOT contain. Pure; used by

package/dist/services/context/collector.js

@@ -11,7 +11,7 @@ const CollectInputSchema = z.object({
     goal: z.string().min(1),
     project: z.string().min(1),
     depsMode: z.enum(['locked', 'latest']),
-    out: z.string().optional(),
+    out: z.string().optional()
 });
 function classifyKind(path) {
     if (path.includes('/__tests__/') || path.endsWith('.test.ts') || path.endsWith('.test.tsx')) {
@@ -47,7 +47,7 @@ async function scanFiles(root, exclude) {
                 path: rel,
                 kind: classifyKind(relative(root, full)),
                 lines: 0, // computed lazily; full line count is expensive
-                hash: '', // computed lazily via content-hash-cache-pattern
+                hash: '' // computed lazily via content-hash-cache-pattern
             });
         }
     }
@@ -61,7 +61,7 @@ async function readGitStatus(project) {
     return {
         branch: 'main',
         lastCommit: 'unknown',
-        dirty: false,
+        dirty: false
     };
 }
 async function readMemoryEntries(project) {
@@ -76,7 +76,7 @@ async function readMemoryEntries(project) {
             path: join('.peaks/memory', n),
             title: n,
             relevanceScore: 0,
-            excerptHash: '',
+            excerptHash: ''
         }));
     }
     catch {
@@ -110,24 +110,22 @@ async function readDeps(project, depsMode) {
         result[name] = {
             version,
             source: 'package.json',
-            resolved: '', // filled by lockfile parser in a later slice
+            resolved: '' // filled by lockfile parser in a later slice
         };
     }
     return result;
 }
 export async function collectContext(rawInput) {
     const input = CollectInputSchema.parse(rawInput);
-    const exclude = input.out !== undefined
-        ? relative(input.project, input.out).replaceAll('\\', '/')
-        : undefined;
+    const exclude = input.out !== undefined ? relative(input.project, input.out).replaceAll('\\', '/') : undefined;
     const [files, gitStatus, memoryEntries, deps] = await Promise.all([
         scanFiles(input.project, exclude),
         readGitStatus(input.project),
         readMemoryEntries(input.project),
-        readDeps(input.project, input.depsMode),
+        readDeps(input.project, input.depsMode)
     ]);
     return {
         goal: input.goal,
-        collector: { files, gitStatus, memoryEntries, deps },
+        collector: { files, gitStatus, memoryEntries, deps }
     };
 }

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

@@ -69,8 +69,10 @@ function readCache(cachePath) {
             tool: typeof parsed.tool === 'string' ? parsed.tool : null,
             key: typeof parsed.key === 'string' ? parsed.key : null,
             bytes: typeof parsed.bytes === 'number' && Number.isFinite(parsed.bytes) ? parsed.bytes : 0,
-            pctOfTotal: typeof parsed.pctOfTotal === 'number' && Number.isFinite(parsed.pctOfTotal) ? parsed.pctOfTotal : 0,
-            count: typeof parsed.count === 'number' && Number.isFinite(parsed.count) ? parsed.count : 0,
+            pctOfTotal: typeof parsed.pctOfTotal === 'number' && Number.isFinite(parsed.pctOfTotal)
+                ? parsed.pctOfTotal
+                : 0,
+            count: typeof parsed.count === 'number' && Number.isFinite(parsed.count) ? parsed.count : 0
         };
     }
     catch {
@@ -93,7 +95,7 @@ function probeRatioSafe(input) {
             projectRoot: input.projectRoot,
             sessionId: input.sessionId,
             outerSessionId: input.outerSessionId ?? undefined,
-            env: input.env ?? process.env,
+            env: input.env ?? process.env
         });
         return Number.isFinite(probe.ratio) ? probe.ratio : null;
     }
@@ -123,7 +125,7 @@ export function buildContextAuditHint(input) {
         // Cache miss / stale → at most one scan per TTL window.
         const result = (input.runAudit ?? auditContext)({
             outerSessionId: input.outerSessionId ?? null,
-            topN: 1,
+            topN: 1
         });
         const top = result.available ? (result.entries[0] ?? null) : null;
         const entry = {
@@ -134,7 +136,7 @@ export function buildContextAuditHint(input) {
             key: top?.key ?? null,
             bytes: top?.bytes ?? 0,
             pctOfTotal: top?.pctOfTotal ?? 0,
-            count: top?.count ?? 0,
+            count: top?.count ?? 0
         };
         try {
             atomicWriteJson(cachePath, entry);

package/dist/services/context/context-audit-keys.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Stable group-key builders for `peaks code context-audit` — the
+ * `(tool name, short input key)` half of the grouping contract.
+ *
+ * Moved out of `./context-audit.ts` (wave 3, eslint-family sweep). Every
+ * case body, predicate and clip budget below is copied EXACTLY from the
+ * original switch; the switch is only split into two sequential halves so
+ * no single function crosses the complexity ceiling. For every `(tool,
+ * input)` pair the returned key is identical to before the move.
+ */
+/**
+ * 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 declare function contextAuditKey(tool: string, input: unknown): string;

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

@@ -0,0 +1,77 @@
+/**
+ * Stable group-key builders for `peaks code context-audit` — the
+ * `(tool name, short input key)` half of the grouping contract.
+ *
+ * Moved out of `./context-audit.ts` (wave 3, eslint-family sweep). Every
+ * case body, predicate and clip budget below is copied EXACTLY from the
+ * original switch; the switch is only split into two sequential halves so
+ * no single function crosses the complexity ceiling. For every `(tool,
+ * input)` pair the returned key is identical to before the move.
+ */
+/** Max characters kept in a group key — keys are labels, not payloads. */
+const KEY_MAX_CHARS = 100;
+/** `Task` / `Agent` descriptions are kept even shorter (label, not payload). */
+const TASK_KEY_MAX_CHARS = 60;
+/** Budget for the JSON fallback used by unknown tools. */
+const FALLBACK_KEY_MAX_CHARS = 80;
+function readInputString(v) {
+    return typeof v === 'string' ? v : '';
+}
+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('/');
+}
+const NOT_A_KEY = null;
+/** First half of the original switch: execution / file / search tools. */
+function keyForKnownTool(tool, i) {
+    switch (tool) {
+        case 'Bash':
+            return clip(readInputString(i.command), KEY_MAX_CHARS);
+        case 'Read':
+        case 'Write':
+        case 'Edit':
+        case 'NotebookEdit':
+            return clip(tailPath(readInputString(i.file_path), 2), KEY_MAX_CHARS);
+        case 'Grep':
+        case 'Glob':
+            return clip(`${readInputString(i.pattern)} @ ${readInputString(i.path) || '.'}`, KEY_MAX_CHARS);
+        default:
+            return NOT_A_KEY;
+    }
+}
+/** Second half of the original switch: agent tools + unknown-tool fallback. */
+function keyForRemainingTool(tool, i) {
+    switch (tool) {
+        case 'Task':
+        case 'Agent':
+            return clip(readInputString(i.description) || readInputString(i.subagent_type), TASK_KEY_MAX_CHARS);
+        default: {
+            let json;
+            try {
+                json = JSON.stringify(i) ?? '';
+            }
+            catch {
+                json = '';
+            }
+            return clip(json, FALLBACK_KEY_MAX_CHARS);
+        }
+    }
+}
+/**
+ * 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) {
+    if (typeof input !== 'object' || input === null)
+        return '';
+    const i = input;
+    const known = keyForKnownTool(tool, i);
+    if (known !== NOT_A_KEY)
+        return known;
+    return keyForRemainingTool(tool, i);
+}

package/dist/services/context/context-audit-limits.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Size/limit constants and `--top` normalization for `peaks code
+ * context-audit`, moved VERBATIM out of `./context-audit.ts` (wave 3,
+ * eslint-family sweep) so that module stays under the 300 raw-line cap.
+ *
+ * The two transcript-size ceilings keep their exact previous values; they
+ * are written as a named 1 MiB constant times a named Mebibyte count
+ * because the `no-magic-numbers` family flags each factor of a literal
+ * product (`256 * 1024 * 1024`) but not a direct `const` assignment.
+ */
+/** Default number of top entries emitted. */
+export declare const CONTEXT_AUDIT_DEFAULT_TOP = 15;
+/** Hard ceiling for `--top` — the envelope must stay small by construction. */
+export declare const CONTEXT_AUDIT_MAX_TOP = 100;
+/** Transcripts larger than this are reported `available:false` (fail-soft). */
+export declare const CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES: number;
+/** Streaming chunk size (bounded memory on multi-MB transcripts) = 1 MiB. */
+export declare const CONTEXT_AUDIT_SCAN_CHUNK_BYTES = 1048576;
+/** Clamp a caller-supplied `--top` into the documented range. */
+export declare function normalizeTopN(value: unknown): number;

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

@@ -0,0 +1,31 @@
+/**
+ * Size/limit constants and `--top` normalization for `peaks code
+ * context-audit`, moved VERBATIM out of `./context-audit.ts` (wave 3,
+ * eslint-family sweep) so that module stays under the 300 raw-line cap.
+ *
+ * The two transcript-size ceilings keep their exact previous values; they
+ * are written as a named 1 MiB constant times a named Mebibyte count
+ * because the `no-magic-numbers` family flags each factor of a literal
+ * product (`256 * 1024 * 1024`) but not a direct `const` assignment.
+ */
+/** 1 MiB = 1024 × 1024 bytes. */
+const MEBIBYTE = 1048576;
+/** Mebibytes of transcript the audit is still willing to stream (256 MiB). */
+const MAX_TRANSCRIPT_MEBIBYTES = 256;
+/** 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 = MAX_TRANSCRIPT_MEBIBYTES * MEBIBYTE;
+/** Streaming chunk size (bounded memory on multi-MB transcripts) = 1 MiB. */
+export const CONTEXT_AUDIT_SCAN_CHUNK_BYTES = MEBIBYTE;
+/** 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);
+}

package/dist/services/context/context-audit-scan.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Transcript scan + envelope assembly for `peaks code context-audit`.
+ *
+ * Moved out of `./context-audit.ts` (wave 3, eslint-family sweep). The
+ * streaming loop, the fold bookkeeping, the `pctOfTotal` rounding and the
+ * group ordering are the report's contract: every line below is copied
+ * exactly — same predicates, same throw points, same accumulator updates in
+ * the same positions. Only pure sub-blocks whose control flow copies 1:1
+ * were extracted; the read-accumulator loop and the per-line delta
+ * accumulation stay in the functions that own them.
+ */
+import type { ContextAuditResult } from './context-audit-types.js';
+/** Fail-soft envelope: every field zeroed/emptied, only the partial set. */
+export declare function emptyResult(partial: Partial<ContextAuditResult>): ContextAuditResult;
+/**
+ * Stat, size-check and stream a resolved transcript. Fail-soft: every stat
+ * / open / read failure maps to its documented reason via `errorAuditReason`.
+ */
+export declare function auditTranscriptFile(transcriptPath: string, maxBytes: number, topN: number): ContextAuditResult;

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

@@ -0,0 +1,246 @@
+/**
+ * Transcript scan + envelope assembly for `peaks code context-audit`.
+ *
+ * Moved out of `./context-audit.ts` (wave 3, eslint-family sweep). The
+ * streaming loop, the fold bookkeeping, the `pctOfTotal` rounding and the
+ * group ordering are the report's contract: every line below is copied
+ * exactly — same predicates, same throw points, same accumulator updates in
+ * the same positions. Only pure sub-blocks whose control flow copies 1:1
+ * were extracted; the read-accumulator loop and the per-line delta
+ * accumulation stay in the functions that own them.
+ */
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { contextAuditKey } from './context-audit-keys.js';
+import { CONTEXT_AUDIT_DEFAULT_TOP, CONTEXT_AUDIT_SCAN_CHUNK_BYTES } from './context-audit-limits.js';
+/** Divisor that renders a ratio as a one-decimal percentage (× 100 / × 10). */
+const ONE_DECIMAL_DIVISOR = 10;
+/** Fail-soft envelope: every field zeroed/emptied, only the partial set. */
+export function emptyResult(partial) {
+    return {
+        available: false,
+        reason: null,
+        transcriptPath: null,
+        totalBytes: 0,
+        entryCount: 0,
+        groupCount: 0,
+        topN: CONTEXT_AUDIT_DEFAULT_TOP,
+        entries: [],
+        ...partial
+    };
+}
+/**
+ * Map an `auditTranscriptFile` failure to its machine-readable
+ * unavailability reason. Same ENOENT / EACCES+EPERM / other ternary chain
+ * and reason strings as before the move.
+ */
+function errorAuditReason(err) {
+    const code = err.code;
+    return code === 'ENOENT'
+        ? 'transcript-not-found'
+        : code === 'EACCES' || code === 'EPERM'
+            ? 'transcript-unreadable'
+            : 'audit-failed';
+}
+/** UTF-8 size of a JSON value that survived neither the string nor array path. */
+function jsonBytes(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
+/** Byte size of one `tool_result.content` array element (same fall-through). */
+function contentPartBytes(part) {
+    if (typeof part === 'string') {
+        return Buffer.byteLength(part, 'utf8');
+    }
+    if (typeof part === 'object' && part !== null) {
+        const text = part.text;
+        return typeof text === 'string'
+            ? Buffer.byteLength(text, 'utf8')
+            : Buffer.byteLength(JSON.stringify(part) ?? '', 'utf8');
+    }
+    return 0;
+}
+/** 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) {
+            total += contentPartBytes(part);
+        }
+        return total;
+    }
+    if (content === undefined || content === null)
+        return 0;
+    return jsonBytes(content);
+}
+/** Pull `message.content` out of a parsed record; `null` when shape differs. */
+function extractMessageContent(parsed) {
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const record = parsed;
+    const message = record.message;
+    if (typeof message !== 'object' || message === null)
+        return null;
+    const content = message.content;
+    if (!Array.isArray(content))
+        return null;
+    return content;
+}
+function rememberToolUse(item, toolUses) {
+    const id = item.id;
+    const name = item.name;
+    if (typeof id === 'string' && typeof name === 'string') {
+        toolUses.set(id, { name, input: item.input });
+    }
+}
+/** Fold one `tool_result` part into its group; returns the byte delta. */
+function addToolResult(item, toolUses, groups) {
+    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;
+    }
+    return size;
+}
+/**
+ * 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 };
+    }
+    const content = extractMessageContent(parsed);
+    if (content === null)
+        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') {
+            rememberToolUse(item, toolUses);
+            continue;
+        }
+        if (item.type !== 'tool_result')
+            continue;
+        const size = addToolResult(item, toolUses, groups);
+        bytes += size;
+        count += 1;
+    }
+    return { bytes, count };
+}
+/** Percentage in [0, 100], one decimal — see ContextAuditEntry.pctOfTotal. */
+function percentOfTotal(bytes, totalBytes) {
+    return totalBytes > 0 ? Math.round((bytes / totalBytes) * 1000) / ONE_DECIMAL_DIVISOR : 0;
+}
+/** Group → entries, sorted by bytes descending (ties: tool, then key). */
+function rankGroups(groups, totalBytes) {
+    const entries = [...groups]
+        .map((g) => ({
+        tool: g.tool,
+        key: g.key,
+        bytes: g.bytes,
+        pctOfTotal: percentOfTotal(g.bytes, totalBytes),
+        count: g.count
+    }))
+        .sort((a, b) => b.bytes - a.bytes || a.tool.localeCompare(b.tool) || a.key.localeCompare(b.key));
+    return entries;
+}
+/**
+ * Stream the transcript once, folding every tool result into its
+ * `(tool, key)` group. Pure bookkeeping — no content is retained.
+ */
+function streamTranscript(filePath, toolUses, groups) {
+    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(CONTEXT_AUDIT_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 */
+        }
+    }
+    return { totalBytes, entryCount };
+}
+function scanTranscript(filePath, topN) {
+    const toolUses = new Map();
+    const groups = new Map();
+    const totals = streamTranscript(filePath, toolUses, groups);
+    const entries = rankGroups(groups.values(), totals.totalBytes);
+    return {
+        available: true,
+        reason: null,
+        transcriptPath: filePath,
+        totalBytes: totals.totalBytes,
+        entryCount: totals.entryCount,
+        groupCount: entries.length,
+        topN,
+        entries: entries.slice(0, topN)
+    };
+}
+/**
+ * Stat, size-check and stream a resolved transcript. Fail-soft: every stat
+ * / open / read failure maps to its documented reason via `errorAuditReason`.
+ */
+export function auditTranscriptFile(transcriptPath, maxBytes, topN) {
+    try {
+        const size = statSync(transcriptPath).size;
+        if (size > maxBytes) {
+            return emptyResult({ reason: 'transcript-too-large', transcriptPath, topN });
+        }
+        return scanTranscript(transcriptPath, topN);
+    }
+    catch (err) {
+        return emptyResult({ reason: errorAuditReason(err), transcriptPath, topN });
+    }
+}

package/dist/services/context/context-audit-types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Public envelope types for `peaks code context-audit`, plus the two
+ * module-internal shapes shared by the scan/fold machinery.
+ *
+ * Moved VERBATIM out of `./context-audit.ts` (wave 3, eslint-family sweep)
+ * so that module stays under the 300 raw-line cap. Mechanical move only —
+ * field order, optionality and doc comments are unchanged; the three public
+ * interfaces are re-exported from `./context-audit.ts` unchanged.
+ */
+export interface ContextAuditEntry {
+    /** Tool name (`Bash`, `Read`, `Grep`, …), or `unknown` when unmatched. */
+    readonly tool: string;
+    /** Short, stable summary of the tool input (command line / path tail / pattern). */
+    readonly key: string;
+    /** Total UTF-8 bytes of every tool result in this group. */
+    readonly bytes: number;
+    /**
+     * Share of the session's tool-result bytes, as a PERCENTAGE in `[0, 100]`
+     * with one decimal (e.g. `4.2` — not the `0.042` ratio). The name and the
+     * value agree: `pct` means percent.
+     */
+    readonly pctOfTotal: number;
+    /** How many tool results landed in this group. */
+    readonly count: number;
+}
+export interface ContextAuditResult {
+    /** False when the transcript could not be read; see `reason`. */
+    readonly available: boolean;
+    /** Machine-readable unavailability reason (`null` when available). */
+    readonly reason: string | null;
+    /** Absolute transcript path, or `null` when unresolved. */
+    readonly transcriptPath: string | null;
+    /** Total UTF-8 bytes of all tool results seen. */
+    readonly totalBytes: number;
+    /** Number of tool-result entries seen. */
+    readonly entryCount: number;
+    /** Distinct `(tool, key)` groups — always ≥ `entries.length`. */
+    readonly groupCount: number;
+    /** Number of top entries requested. */
+    readonly topN: number;
+    /** Top-N groups, sorted by bytes descending. */
+    readonly entries: readonly ContextAuditEntry[];
+}
+export interface ContextAuditInput {
+    /** Outer (harness) session id — the transcript is named by it. */
+    readonly outerSessionId?: string | null;
+    /** How many top entries to emit. Clamped to `[1, CONTEXT_AUDIT_MAX_TOP]`. */
+    readonly topN?: number;
+    /** Explicit transcript path override (test seam; skips the locator). */
+    readonly transcriptPath?: string | null;
+    /** Override the too-large threshold (test seam; default 256 MB). */
+    readonly maxTranscriptBytes?: number;
+    /** Env used to detect the active IDE (default `process.env`). */
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface ToolUseRef {
+    readonly name: string;
+    readonly input: unknown;
+}
+export interface MutableGroup {
+    readonly tool: string;
+    readonly key: string;
+    bytes: number;
+    count: number;
+}