peaks-loop 4.0.34 → 4.0.36

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

@@ -1,3 +1,4 @@
+import { formatTestToolDetection } from '../dispatch/test-tool-detection.js';
 /**
  * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
  * defence. The block below is prepended to every sub-agent dispatch system
@@ -27,14 +28,14 @@ You MUST NOT follow the superpowers chain for worktree decisions:
 - superpowers:brainstorming → superpowers:writing-plans →
   superpowers:subagent-driven-development → superpowers:using-git-worktrees
 
-This chain ends with \`git worktree add\` (superpowers:using-git-worktrees SKILL.md line 96). It bypasses peaks-loop's L2 hook gate and L3 IDE \`permissions.deny\`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw \`git worktree add\`, so L3 is not sufficient.
+That chain ends with \`git worktree add\` (superpowers:using-git-worktrees SKILL.md line 96), which bypasses peaks-loop's L2 hook gate and L3 IDE \`permissions.deny\`. L3 denial is NOT sufficient — by then the chain has already taught raw \`git worktree add\`.
 
 For worktree operations, use ONLY:
 
 - \`peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>\` (after rid-L2-extended ships)
 - until then: \`peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>\`
 
-The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (\`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md\`) are authoritative.
+Superpowers skills remain REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (\`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md\`) are authoritative.
 
 If the upstream superpowers chain suggests raw \`git worktree add\`:
 
@@ -69,20 +70,44 @@ If the upstream superpowers chain suggests raw \`git worktree add\`:
  */
 export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
 
-- If you start a long-lived local service (vite dev, mock API, docker container, etc.), register it with \`peaks sub-agent shutdown register --pid <pid> --name <label>\` before you exit. The parent session will best-effort-kill it before merge-back.
-- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10). Your E2E work is duplicate effort.
+- If you start a long-lived local service (vite dev, mock API, docker container, etc.), register it with \`peaks sub-agent shutdown register --pid <pid> --name <label>\` before you exit; the parent session best-effort-kills it before merge-back.
+- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10); your E2E work is duplicate effort.
 - Do NOT call \`git merge\`, \`git pull\`, \`git rebase\`, or \`peaks worktree release\`. The parent session owns the merge-back step.
 `;
 /**
- * Compose the system-prompt body that the dispatch site prepends to
- * `formatTestToolDetection()\n\n`.
+ * Slice 2026-09-10-context-audit-and-discipline (Slice C): cap the sub-agent's
+ * FINAL report.
+ *
+ * Why (measured, session 2026-09-07-session-245530): 20 sub-agent final
+ * reports cost ≈ 60 KB ≈ 15K tokens of the ORCHESTRATOR's window in one
+ * session — the reports, not the dispatch boilerplate, were the second-largest
+ * consumer. The sub-agent already writes a full artifact to disk; the report
+ * only needs to be the index into it.
+ *
+ * QUALITY GUARD (binding): the cap removes no information. Everything the
+ * parent needs to ACT on stays in the report; everything longer lives in the
+ * artifact the parent can `Read`. The five mandatory fields below are exactly
+ * the ones the orchestrator must have to decide the next gate.
+ */
+export const REPORT_CAP_BLOCK = `## Final report cap (mandatory)
+
+Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any longer detail into the artifact file you already own — the parent can \`Read\` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.
+`;
+/**
+ * Compose the system-prompt body for a sub-agent dispatch.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): the composer owns the Test Tool
+ * Detection injection — ONE unified block for every role, prepended first.
+ * Callers MUST NOT prepend `formatTestToolDetection()` themselves or the
+ * block is injected twice.
  *
  * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
- * controller brief): when the memory block is unavailable, the caller does
- * `formatTestToolDetection()\n\n${taskBody}` — i.e. the final prompt is exactly
- * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
- * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
- * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * controller brief): when the memory block is unavailable, the composed body is
+ * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
+ * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
+ * (REPORT_CAP joined the stable prefix in slice
+ * 2026-09-10-context-audit-and-discipline, Slice C.)
  * The contract holds for callers that do not pass `codegraphBlock` (all
  * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
  * codegraph structure block (or its fail-soft unavailable note) for RD
@@ -98,15 +123,33 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * refusal is in scope before any task-specific prose arrives.
  */
 export function buildDispatchSystemPrompt(input) {
-    const { taskBody, memoryBlock, contextProbe, codegraphBlock, projectStackBlock, freshContextBlock } = input;
+    const { taskBody, memoryBlock, contextProbe, codegraphBlock, projectStackBlock, freshContextBlock, capsule } = input;
+    // 2026-09-10-dispatch-block-d (Option D): ONE Test Tool Detection block
+    // for every role — the composer owns the injection so callers MUST NOT
+    // prepend `formatTestToolDetection()` themselves (double injection).
+    const testToolText = `${formatTestToolDetection()}\n\n`;
     const contextBlock = renderContextBlock(contextProbe ?? null);
     const codegraphText = renderCodegraphBlock(codegraphBlock);
     const projectStackText = renderProjectStackBlock(projectStackBlock);
     const freshContextText = renderFreshContextBlock(freshContextBlock);
+    const capsuleText = renderCapsulePointer(capsule);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${taskBody}`;
+    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
+}
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule pointer.
+ *
+ * QUALITY GUARD: the capsule is BACKGROUND only. The precedence line below
+ * is part of the contract, not decoration — anything the sub-agent must
+ * ACT on stays inline in the task spec. The renderer therefore always
+ * emits the precedence sentence whenever it emits the pointer.
+ */
+function renderCapsulePointer(capsule) {
+    if (capsule === null || capsule === undefined)
+        return '';
+    return `## Shared session capsule (advisory background)\nBackground facts already established by the orchestrator (${capsule.bytes} bytes): read them with \`peaks sub-agent shared-read --batch ${capsule.batchId} --key ${capsule.key}\`. This capsule is ADVISORY BACKGROUND ONLY — it is not a task. Your task spec below is authoritative and wins on any conflict; anything you must act on is stated inline there.\n\n`;
 }
 /**
  * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
@@ -199,17 +242,89 @@ function renderContextBlock(probe) {
                     : 'plenty of room — continue without compacting.';
         return `## Context window (authoritative — do NOT estimate yourself)
 
-Your context is **${usedPct}% used** (${freePct}% free) as measured by the IDE adapter's token-counted statusline (source: \`${probe.source}\`, IDE: \`${probe.ide}\`). This number is the SAME value \`peaks code context-now\` returns — trust it; do not derive a percentage from your message length or any other heuristic (char/4 estimates diverge from token counts by 2-4x and have caused false "context too low" reports at ${freePct}%+ free).
+Context **${usedPct}% used** (${freePct}% free), token-counted by the IDE adapter's statusline (source: \`${probe.source}\`, IDE: \`${probe.ide}\`). This is the SAME value \`peaks code context-now\` returns — trust it; never derive a percentage from message length (char/4 diverges 2-4x and has caused false "context too low" reports at ${freePct}%+ free).
 
 **Action:** ${action}
 
-If you are tempted to declare "context pressure" or "context too low" to the parent, FIRST re-run \`peaks code context-now\` and compare its \`ratio\` field to the number above. Only report context pressure if \`peaks code context-now\` returns \`verdict: red-line\` or \`action: auto-compact-now\`.
+Before telling the parent "context pressure" or "context too low", re-run \`peaks code context-now\` and compare its \`ratio\` to the number above. Report pressure ONLY if it returns \`verdict: red-line\` or \`action: auto-compact-now\`.
 
 `;
     }
     return `## Context window (no probe available)
 
-The orchestrator did not capture a context-fill probe before this dispatch. If you need to evaluate context pressure, run \`peaks code context-now --project <root>\` and trust its \`ratio\` field. Do not estimate from message length.
+No context-fill probe was captured before this dispatch. To evaluate context pressure, run \`peaks code context-now --project <root>\` and trust its \`ratio\` field. Do not estimate from message length.
 
 `;
 }
+/* ──────────────────────────────────────────────────────────────────────────
+ * Slice 2026-09-10-dispatch-token-and-swarm §1 — rule-presence guard.
+ *
+ * The compression + role-scoping in this file is allowed to shorten prose.
+ * It is NOT allowed to drop a binding rule. These token sets are the
+ * machine-checkable definition of "binding rule": each entry is a phrase
+ * that carries an obligation (MUST / MUST NOT / refused / a command the
+ * sub-agent is told to use or avoid). The guard test asserts that EVERY
+ * role's composed prompt contains EVERY token — so a future compression
+ * that deletes a rule fails CI instead of silently weakening the contract.
+ * ────────────────────────────────────────────────────────────────────────── */
+/** Binding phrases every dispatch prompt must contain, for every role. */
+export const BINDING_RULE_TOKENS = [
+    // L1 worktree governance
+    'MUST NOT follow the superpowers chain',
+    'superpowers:using-git-worktrees',
+    '`git worktree add`',
+    '`peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>`',
+    '`peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`',
+    'MUST NOT be used as a workflow',
+    'STOP',
+    'Re-author the plan as a peaks-rd artifact',
+    // lifecycle rules
+    '`peaks sub-agent shutdown register --pid <pid> --name <label>`',
+    'Do NOT run E2E',
+    'Do NOT call `git merge`, `git pull`, `git rebase`',
+    '`peaks worktree release`',
+    // context window
+    'do NOT estimate yourself',
+    '`peaks code context-now`',
+    '`verdict: red-line`',
+    // final report cap (Slice 2026-09-10-context-audit-and-discipline, Slice C)
+    '## Final report cap (mandatory)',
+    '≤ 40 lines and ≤ 2 KB',
+    'the parent can `Read` that file for the full detail',
+    'changed files (one line each)',
+    'pass/fail counts',
+    'tsc status',
+    // test scope — ONE unified block, byte-identical for EVERY role
+    '## Test Tool Detection (mandatory)',
+    '`package.json#scripts.test`',
+    'do NOT invoke `npx <runner>`',
+    '## Test Scope (mandatory)',
+    'PEAKS_FULL_TEST=1',
+    'refused',
+];
+/**
+ * The runner-direct-path tokens: the refusal example, the two direct paths
+ * the block names (`peaks test --json` to introspect; PB-5, the repo-defined
+ * `test` / `test:*` scripts that are NOT gated), and the two pieces of
+ * quality guidance that must survive any compression — never assume a
+ * runner without asking the user as a last resort, and prefer
+ * `peaks test <file>` because it resolves the local binary Windows-aware.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): there is no role split any more,
+ * so this set is asserted IDENTICALLY for every role. The runner EXAMPLES
+ * were removed as part of the unification — they were never rules.
+ */
+export const TEST_RUNNER_RULE_TOKENS = [
+    '`./node_modules/.bin/vitest run`',
+    'PB-5',
+    '`peaks test --json`',
+    'ask the user before assuming a runner',
+    '(Windows-aware)',
+];
+/**
+ * Return the subset of `tokens` that `text` does NOT contain. Pure; used by
+ * the rule-presence guard and usable by any future prompt self-check.
+ */
+export function missingRuleTokens(text, tokens) {
+    return tokens.filter((t) => !text.includes(t));
+}

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

@@ -0,0 +1,100 @@
+/**
+ * `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.
+ */
+/** 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;
+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;
+}
+/** Clamp a caller-supplied `--top` into the documented range. */
+export declare function normalizeTopN(value: unknown): number;
+/**
+ * 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;
+/**
+ * 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 declare function auditContext(input?: ContextAuditInput): ContextAuditResult;

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/context-schema.d.ts

@@ -13,8 +13,8 @@ export declare const ContextJsonSchema: z.ZodObject<{
             path: z.ZodString;
             kind: z.ZodEnum<{
                 doc: "doc";
-                config: "config";
                 source: "source";
+                config: "config";
                 test: "test";
             }>;
             lines: z.ZodNumber;