peaks-loop 4.0.35 → 4.0.37

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-hint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Slice 2026-09-10-three-fixes (Slice 2) — proactive context-consumer hint.
+ *
+ * `peaks code context-audit` (Slice A, same day) already reports WHAT fills
+ * the window, but only when someone remembers to run it. The Step 0.8
+ * PreToolUse gate (`peaks code gate-step-08`) runs before every Bash call, so
+ * it is the natural place to surface the single largest consumer — provided
+ * that costs nothing measurable.
+ *
+ * Cost contract (the whole point of this module):
+ *   - The ratio probe is the cheap, adapter-driven `readContextPercent`
+ *     (env-var → statusline file read; the transcript fallback is a
+ *     bounded backwards scan, never a whole-file read).
+ *   - The expensive part — the transcript scan inside `auditContext` — runs
+ *     at most ONCE per TTL window. Its result is cached under
+ *     `.peaks/_runtime/<sid>/context-audit-hint.json`; a fresh entry
+ *     short-circuits the scan entirely.
+ *   - Every failure is fail-soft: a missing/corrupt cache, an unavailable
+ *     transcript, an adapter that cannot locate one — all yield `null`
+ *     (emit nothing). The gate never blocks and never gains more than ONE
+ *     line.
+ *
+ * The cache deliberately records FAILED audits too (with `available:false`),
+ * so a broken transcript cannot turn every Bash call back into a scan.
+ */
+import { type ContextAuditInput, type ContextAuditResult } from './context-audit.js';
+/** Only surface a hint once the window is this full. */
+export declare const CONTEXT_HINT_RATIO_THRESHOLD = 0.7;
+/** Minimum cache TTL — a fresh entry must skip the transcript scan. */
+export declare const CONTEXT_HINT_CACHE_TTL_MS: number;
+/** Per-session cache file name (under `.peaks/_runtime/<sid>/`). */
+export declare const CONTEXT_HINT_CACHE_FILE_NAME = "context-audit-hint.json";
+/** Cached top-consumer snapshot — one audit result, no transcript content. */
+export interface ContextHintCacheEntry {
+    /** Epoch ms when the audit ran (TTL anchor). */
+    readonly cachedAt: number;
+    /** False when the audit could not read the transcript. */
+    readonly available: boolean;
+    /** Ratio observed when the audit ran (informational). */
+    readonly ratio: number;
+    readonly tool: string | null;
+    readonly key: string | null;
+    readonly bytes: number;
+    readonly pctOfTotal: number;
+    readonly count: number;
+}
+export interface ContextAuditHintInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly outerSessionId?: string | null | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Clock override (test seam). */
+    readonly nowMs?: number | undefined;
+    /** Cache path override (test seam; default is per-session under `_runtime`). */
+    readonly cachePath?: string | undefined;
+    /** Ratio probe override (test seam). Returns null when unknown. */
+    readonly probeRatio?: (() => number | null) | undefined;
+    /** Audit runner override (test seam; lets a test count scans). */
+    readonly runAudit?: ((input: ContextAuditInput) => ContextAuditResult) | undefined;
+}
+/**
+ * `<projectRoot>/.peaks/_runtime/<sid>/context/context-audit-hint.json`
+ * (gitignored). The `context/` bucket mirrors the existing `<sid>/txt/`
+ * convention so session-id artifacts stay under `.peaks/_runtime/<sid>/`.
+ */
+export declare function contextHintCachePath(projectRoot: string, sessionId: string): string;
+/**
+ * The single line the gate may append. Names ONE consumer — the largest by
+ * tool-result bytes — plus the share and call count that justify the number.
+ */
+export declare function formatContextHintLine(entry: ContextHintCacheEntry): string;
+/**
+ * Build the ONE optional hint line for the Step 0.8 gate.
+ *
+ * Returns `null` when: the ratio is unknown or below 0.70, the cache (fresh)
+ * says the audit was unavailable, the fresh audit found no groups, or
+ * anything throws. Never throws, never blocks.
+ */
+export declare function buildContextAuditHint(input: ContextAuditHintInput): string | null;

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

@@ -0,0 +1,150 @@
+/**
+ * Slice 2026-09-10-three-fixes (Slice 2) — proactive context-consumer hint.
+ *
+ * `peaks code context-audit` (Slice A, same day) already reports WHAT fills
+ * the window, but only when someone remembers to run it. The Step 0.8
+ * PreToolUse gate (`peaks code gate-step-08`) runs before every Bash call, so
+ * it is the natural place to surface the single largest consumer — provided
+ * that costs nothing measurable.
+ *
+ * Cost contract (the whole point of this module):
+ *   - The ratio probe is the cheap, adapter-driven `readContextPercent`
+ *     (env-var → statusline file read; the transcript fallback is a
+ *     bounded backwards scan, never a whole-file read).
+ *   - The expensive part — the transcript scan inside `auditContext` — runs
+ *     at most ONCE per TTL window. Its result is cached under
+ *     `.peaks/_runtime/<sid>/context-audit-hint.json`; a fresh entry
+ *     short-circuits the scan entirely.
+ *   - Every failure is fail-soft: a missing/corrupt cache, an unavailable
+ *     transcript, an adapter that cannot locate one — all yield `null`
+ *     (emit nothing). The gate never blocks and never gains more than ONE
+ *     line.
+ *
+ * The cache deliberately records FAILED audits too (with `available:false`),
+ * so a broken transcript cannot turn every Bash call back into a scan.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteJson } from '../ide/shared/atomic-json.js';
+import { readContextPercent } from './auto-compact-reader.js';
+import { auditContext } from './context-audit.js';
+/** Only surface a hint once the window is this full. */
+export const CONTEXT_HINT_RATIO_THRESHOLD = 0.7;
+/** Minimum cache TTL — a fresh entry must skip the transcript scan. */
+export const CONTEXT_HINT_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Per-session cache file name (under `.peaks/_runtime/<sid>/`). */
+export const CONTEXT_HINT_CACHE_FILE_NAME = 'context-audit-hint.json';
+/**
+ * `<projectRoot>/.peaks/_runtime/<sid>/context/context-audit-hint.json`
+ * (gitignored). The `context/` bucket mirrors the existing `<sid>/txt/`
+ * convention so session-id artifacts stay under `.peaks/_runtime/<sid>/`.
+ */
+export function contextHintCachePath(projectRoot, sessionId) {
+    const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+    return join(projectRoot, '.peaks', '_runtime', safeSessionId.length > 0 ? safeSessionId : 'unknown', 'context', CONTEXT_HINT_CACHE_FILE_NAME);
+}
+/**
+ * The single line the gate may append. Names ONE consumer — the largest by
+ * tool-result bytes — plus the share and call count that justify the number.
+ */
+export function formatContextHintLine(entry) {
+    const ratioPct = (entry.ratio * 100).toFixed(1);
+    const sharePct = entry.pctOfTotal.toFixed(1);
+    const calls = entry.count === 1 ? '1 call' : `${entry.count} calls`;
+    return `Context ${ratioPct}% used — top consumer: ${entry.tool} \`${entry.key}\` (${sharePct}% of tool-result bytes, ${calls}). Run \`peaks code context-audit\` for the full breakdown.`;
+}
+function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath, 'utf8'));
+        if (typeof parsed.cachedAt !== 'number' || !Number.isFinite(parsed.cachedAt))
+            return null;
+        if (typeof parsed.available !== 'boolean')
+            return null;
+        return {
+            cachedAt: parsed.cachedAt,
+            available: parsed.available,
+            ratio: typeof parsed.ratio === 'number' && Number.isFinite(parsed.ratio) ? parsed.ratio : 0,
+            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,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Never throws: an unavailable ratio probe degrades to "no hint". */
+function probeRatioSafe(input) {
+    if (input.probeRatio !== undefined) {
+        try {
+            const value = input.probeRatio();
+            return typeof value === 'number' && Number.isFinite(value) ? value : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const probe = readContextPercent({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            outerSessionId: input.outerSessionId ?? undefined,
+            env: input.env ?? process.env,
+        });
+        return Number.isFinite(probe.ratio) ? probe.ratio : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the ONE optional hint line for the Step 0.8 gate.
+ *
+ * Returns `null` when: the ratio is unknown or below 0.70, the cache (fresh)
+ * says the audit was unavailable, the fresh audit found no groups, or
+ * anything throws. Never throws, never blocks.
+ */
+export function buildContextAuditHint(input) {
+    try {
+        const nowMs = input.nowMs ?? Date.now();
+        const ratio = probeRatioSafe(input);
+        if (ratio === null || ratio < CONTEXT_HINT_RATIO_THRESHOLD)
+            return null;
+        const cachePath = input.cachePath ?? contextHintCachePath(input.projectRoot, input.sessionId);
+        const cached = readCache(cachePath);
+        // Fresh entry → the transcript scan is skipped entirely (cost guard).
+        if (cached !== null && nowMs - cached.cachedAt < CONTEXT_HINT_CACHE_TTL_MS) {
+            return cached.available && cached.tool !== null ? formatContextHintLine(cached) : null;
+        }
+        // Cache miss / stale → at most one scan per TTL window.
+        const result = (input.runAudit ?? auditContext)({
+            outerSessionId: input.outerSessionId ?? null,
+            topN: 1,
+        });
+        const top = result.available ? (result.entries[0] ?? null) : null;
+        const entry = {
+            cachedAt: nowMs,
+            available: result.available,
+            ratio,
+            tool: top?.tool ?? null,
+            key: top?.key ?? null,
+            bytes: top?.bytes ?? 0,
+            pctOfTotal: top?.pctOfTotal ?? 0,
+            count: top?.count ?? 0,
+        };
+        try {
+            atomicWriteJson(cachePath, entry);
+        }
+        catch {
+            // Fail-soft: an unwritable cache must not lose this turn's hint.
+        }
+        return top !== null ? formatContextHintLine(entry) : null;
+    }
+    catch {
+        return null;
+    }
+}

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;