@nxuss/lemma 1.9.1 → 1.11.0

package/dist/esm/mcp/tools.js

@@ -37,7 +37,14 @@ import { recordReceiptEvent, getReceiptSummary, getLedgerLength } from "../utils
 import { distillCommandOutput, buildDistillFooter, readRegion } from "../utils/CommandOutputDistiller.js";
 import { findMatch, reindentReplacement } from "../utils/PatchMatcher.js";
 import { searchWorkspace, groupSearchResults, parseExtensionFilter } from "../utils/WorkspaceSearch.js";
-import { checkAlreadySent, recordSent } from "../utils/ReadWorkspaceCache.js";
+import { rankCandidates } from "../utils/LocalPrefilter.js";
+import { checkAlreadySent, recordSent, getLastEmitted } from "../utils/ReadWorkspaceCache.js";
+import { shouldEmitDelta } from "../utils/OutputDelta.js";
+import { ledgerKey, checkOutput, recordOutput as recordLedgerOutput } from "../utils/OutputLedger.js";
+import { buildDepGraphMap, bfsDepGraph } from "../utils/DepGraph.js";
+import { getOrExtractSymbols } from "../utils/AstSymbolCache.js";
+import { warmNeighbors, registerSymbolExtractor } from "../utils/SpeculativeWarmer.js";
+import { findAffectedTests, formatAffectedTests } from "../utils/AffectedTests.js";
 import { mapSqueezedToOriginal, withLineNumbers, sequentialNumbers } from "../utils/LineNumberMap.js";
 import { fileOutline, formatOutline } from "../utils/FileOutline.js";
 import { getCachedSearch, setCachedSearch } from "../utils/SearchCache.js";
@@ -137,6 +144,30 @@ const toolDefinitions = [
                     description: "Symbols (not whole files) this answer depends on. Freshness is then judged by that symbol's own source, so edits elsewhere in the same file don't stale this memory out.",
                 },
                 outcome: { type: "string", enum: ["confirmed", "failed"], description: "Default 'confirmed' (a verified working solution). Set 'failed' to record a dead end — an approach ruled out, not one to recommend." },
+                claims: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            text: { type: "string", description: "One sub-statement from `response`, verifiable on its own (e.g. one sentence about one function)." },
+                            filePaths: { type: "array", items: { type: "string" }, description: "Paths this specific claim depends on." },
+                            symbols: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        filePath: { type: "string" },
+                                        symbolName: { type: "string" },
+                                    },
+                                    required: ["filePath", "symbolName"],
+                                },
+                                description: "Symbols this specific claim depends on.",
+                            },
+                        },
+                        required: ["text"],
+                    },
+                    description: "Split `response` into independently-verifiable sub-claims when it makes more than one assertion about different parts of the code. Each claim tracks its own filePaths/symbols, so one claim going stale (e.g. one function changed) doesn't discard the others that are still true. Skip this for a single-fact response — plain filePaths/symbols above already covers that case.",
+                },
             },
             required: ["query", "response"],
         },
@@ -165,7 +196,7 @@ const toolDefinitions = [
     },
     {
         name: "read_workspace_file",
-        description: "Read a file inside the workspace. Compresses comments/whitespace and scrubs API keys. Every line carries its REAL line number in the original file (compression removes lines, it never renumbers them), so you can cite file:line and patch precisely without re-reading. The header lists which imports were compressed away. Use offset/limit to read a line range of a large file. If this exact view was already read this session and hasn't changed on disk, returns an UNCHANGED marker plus a symbol outline — reuse your copy, or pass force:true if it's no longer in your context.",
+        description: "Read a file inside the workspace. Compresses comments/whitespace and scrubs API keys. Every line carries its REAL line number in the original file (compression removes lines, it never renumbers them), so you can cite file:line and patch precisely without re-reading. The header lists which imports were compressed away. Use offset/limit to read a line range of a large file. If this exact view was already read this session and hasn't changed on disk, returns an UNCHANGED marker plus a symbol outline. If it changed only slightly, returns a CHANGED marker with a unified diff to apply to the copy you already hold. Either way, pass force:true to get the full file when it is no longer in your context.",
         inputSchema: {
             type: "object",
             properties: {
@@ -373,7 +404,7 @@ const toolDefinitions = [
     },
     {
         name: "prune_conversation_history",
-        description: "Compress conversation history by decimating old turns and compacting large code blocks in historical messages. Keeps recent context intact.",
+        description: "Compress conversation history by decimating old turns and compacting large code blocks in historical messages. Keeps recent context intact. Refuses to mutate anything by default because pruning invalidates the prompt-cache prefix, which is usually a net loss — pass force:true to actually apply it, or call without force to just get the estimated cache-invalidation cost back.",
         inputSchema: {
             type: "object",
             properties: {
@@ -382,6 +413,11 @@ const toolDefinitions = [
                     items: { type: "object" },
                     description: "Array of conversation messages with role + content",
                 },
+                force: {
+                    type: "boolean",
+                    description: "Actually apply the prune despite the prompt-cache-invalidation cost. Default false — the call is a dry run that reports cacheInvalidationEstimate instead.",
+                    default: false,
+                },
             },
             required: ["messages"],
         },
@@ -707,6 +743,17 @@ const toolDefinitions = [
             required: ["filePath"],
         },
     },
+    {
+        name: "affected_tests",
+        description: "Given the current diff (or an explicit file list), returns only the test files that transitively import the changed code, plus the exact command to run just those. Uses the TypeScript import graph — zero LLM calls. Run this instead of the full suite after an edit: fewer minutes, and far less test output in context. Reports honestly when the full suite is the right answer (unbounded change, runtime-only coupling, most of the suite affected).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                files: { type: "array", items: { type: "string" }, description: "Explicit changed files, relative to workspace root. Omit to read the diff from git (working tree + untracked)." },
+                baseRef: { type: "string", description: "Additional git ref to diff against, e.g. 'main'. The working tree is always included." },
+            },
+        },
+    },
     {
         name: "refactor",
         description: "Declarative multi-file codemod engine. Rename symbols across the entire workspace or move files updating all imports. Uses TypeScript Compiler API — zero LLM calls. Supports dry-run diff preview and post-refactor tsc verification.",
@@ -1139,6 +1186,7 @@ const toolHandlers = {
     pr_status: handlePRStatus,
     generate_pr_workflow: handleGeneratePRWorkflow,
     depgraph: handleDepgraph,
+    affected_tests: handleAffectedTests,
     refactor: handleRefactor,
     smart_file_slice: handleSmartFileSlice,
     test_oracle: handleTestOracle,
@@ -1239,6 +1287,7 @@ function receiptLabelMeta(name, args) {
     return meta;
 }
 export function setupToolsHandlers(server, onToolCall) {
+    registerSymbolExtractor(extractSymbolsWithTsCompiler);
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitionsArray,
     }));
@@ -1348,7 +1397,16 @@ async function handleSearchMemory(args) {
         }
         const fresh = results.filter((r) => r.fresh);
         const stale = results.filter((r) => !r.fresh);
-        const formatResult = (r, i) => `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)${r.outcome === "failed" ? "\n⚠️ TAGGED AS A FAILED ATTEMPT — this was tried before and did NOT work. Do not repeat it; treat this as a warning, not a suggestion." : ""}\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}`;
+        const formatClaims = (r) => {
+            if (!Array.isArray(r.claims) || r.claims.length === 0)
+                return "";
+            const lines = r.claims.map((c) => c.fresh
+                ? `  ✓ fresh: ${c.text}`
+                : `  ✗ STALE (${(c.staleFiles || []).join(", ")}): ${c.text}`);
+            const staleCount = r.claims.filter((c) => !c.fresh).length;
+            return `\nClaims (${r.claims.length - staleCount}/${r.claims.length} still fresh — trust only the ✓ ones):\n${lines.join("\n")}`;
+        };
+        const formatResult = (r, i) => `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)${r.outcome === "failed" ? "\n⚠️ TAGGED AS A FAILED ATTEMPT — this was tried before and did NOT work. Do not repeat it; treat this as a warning, not a suggestion." : ""}\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}${formatClaims(r)}`;
         if (fresh.length > 0) {
             // Only a fresh hit (or an untracked, purely conceptual entry) counts as a real
             // avoided re-investigation — this is the only case worth crediting as savings.
@@ -1393,11 +1451,14 @@ async function handleStoreMemory(args) {
     const symbols = Array.isArray(args?.symbols)
         ? args.symbols.filter((s) => s?.filePath && s?.symbolName)
         : undefined;
+    const claims = Array.isArray(args?.claims)
+        ? args.claims.filter((c) => c?.text)
+        : undefined;
     if (!query || !responseText)
         throw new Error("Query and response are required");
     try {
         const brain = getBrain();
-        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths, undefined, outcome, symbols);
+        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths, undefined, outcome, symbols, claims);
         // Storing a memory saves nothing — it only creates the chance of a saving later.
         // Crediting tokens here inflated the ledger on write and then credited the same
         // answer again on every read. The saving is booked by search_memory on a fresh hit.
@@ -1409,7 +1470,8 @@ async function handleStoreMemory(args) {
         const trackingNote = filePaths && filePaths.length > 0 ? ` Tracking freshness against ${filePaths.length} file(s) — this memory auto-invalidates if they change.` : "";
         const symbolNote = symbols && symbols.length > 0 ? ` Tracking freshness against ${symbols.length} symbol(s) specifically — unrelated edits elsewhere in those files won't stale this out.` : "";
         const outcomeNote = outcome === "failed" ? " Tagged as a FAILED attempt — future searches will surface it as a warning, not a suggestion." : "";
-        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}${symbolNote}${outcomeNote}` }] };
+        const claimsNote = claims && claims.length > 0 ? ` Split into ${claims.length} independently-verifiable claim(s) — a future search can trust the ones still fresh even if another goes stale.` : "";
+        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}${symbolNote}${outcomeNote}${claimsNote}` }] };
     }
     catch (e) {
         logError("store_memory", e);
@@ -1539,7 +1601,44 @@ async function handleReadWorkspaceFile(args) {
         }
         if (numbers)
             content = withLineNumbers(content, numbers);
-        recordSent(resolved, view, dedup.hash);
+        // The file changed, but usually only slightly — the common case in an edit loop is a
+        // few lines moving in a file the model already holds in full. Re-sending everything
+        // charges for the whole file (and keeps charging, since tool results stay in the
+        // transcript). A diff against the exact text we last emitted covers the same ground
+        // for a fraction of the tokens; `shouldEmitDelta` declines whenever it wouldn't.
+        if (!force) {
+            const previousEmitted = getLastEmitted(resolved, view);
+            if (previousEmitted !== null) {
+                const delta = shouldEmitDelta(previousEmitted, content);
+                if (delta.emit) {
+                    reportSavings({
+                        source: "contextSqueeze",
+                        charsBefore: content.length,
+                        charsAfter: delta.body.length,
+                        toolName: "read_workspace_file",
+                        filePath,
+                    });
+                    recordSent(resolved, view, dedup.hash, content);
+                    warmNeighbors(workspaceRoot, resolved);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: [
+                                    `CHANGED: ${filePath} — ${delta.hunkCount} hunk(s), +${delta.added}/-${delta.removed} since you last read it.`,
+                                    `Apply this diff to the copy you already have. Line numbers are real positions in the file on disk.`,
+                                    `If you no longer hold that copy, re-fetch with force:true.`,
+                                    ``,
+                                    delta.body,
+                                ].join("\n"),
+                            },
+                        ],
+                    };
+                }
+            }
+        }
+        recordSent(resolved, view, dedup.hash, content);
+        warmNeighbors(workspaceRoot, resolved);
         return { content: [{ type: "text", text: rangeHeader + content }] };
     }
     catch (err) {
@@ -1758,9 +1857,35 @@ async function handleRunWorkspaceCommand(args) {
                 handle: distilled.handle,
             });
         }
+        // A debug loop runs the same command repeatedly and the output barely moves between
+        // runs. The header is part of the compared text on purpose: a pass/fail flip must never
+        // be reported as "identical", even in the rare case where the body alone matches.
+        // The footer is deliberately excluded and always re-appended — it carries this run's
+        // `output_region` handle, which is different every time and must stay usable.
+        const body = `${header}\n\nOutput:\n${distilled.text}`;
+        const footer = buildDistillFooter(distilled);
+        const key = ledgerKey("run_workspace_command", { command, cwd: workspaceRoot, raw: args?.raw === true });
+        const ledger = checkOutput(key, body, {
+            label: `\`${command}\``,
+            rerunHint: "The command did run again — this reports its result, it does not skip execution.",
+        });
+        recordLedgerOutput(key, body);
+        if (ledger.replacement) {
+            reportSavings({
+                source: "contextSqueeze",
+                charsBefore: body.length,
+                charsAfter: ledger.replacement.length,
+                toolName: "run_workspace_command",
+            });
+            recordReceiptEvent("tool_call", `run_workspace_command ${ledger.status} vs. earlier run`, {
+                command,
+                savedChars: ledger.savedChars,
+            });
+            return { content: [{ type: "text", text: ledger.replacement + footer }] };
+        }
         return {
             content: [
-                { type: "text", text: `${header}\n\nOutput:\n${distilled.text}${buildDistillFooter(distilled)}` },
+                { type: "text", text: body + footer },
             ],
         };
     }
@@ -1851,6 +1976,67 @@ async function handleListWorkspaceDir(args) {
         return { content: [{ type: "text", text: `Error listing directory: ${err.message}` }] };
     }
 }
+/** Files shown after a successful local ranking; the rest are named, not silently dropped. */
+const PREFILTER_FILES_SHOWN = 12;
+/**
+ * Rank matching files with the local model and show only the top ones.
+ *
+ * Ranking happens per file, not per match: the model is choosing which files are worth
+ * reading, and ranking 200 individual lines would ask it a question it cannot answer as
+ * well. On any failure — disabled, no Ollama, unparseable reply — this returns the input
+ * untouched, which is the behaviour with the feature off.
+ */
+async function prefilterSearchMatches(query, matches) {
+    const byFile = new Map();
+    for (const m of matches) {
+        const list = byFile.get(m.filePath);
+        if (list)
+            list.push(m);
+        else
+            byFile.set(m.filePath, [m]);
+    }
+    const totalFiles = byFile.size;
+    const untouched = { matches, totalFiles, note: "", applied: false };
+    if (totalFiles <= PREFILTER_FILES_SHOWN)
+        return untouched;
+    try {
+        const candidates = [...byFile.entries()].map(([filePath, fileMatches]) => ({
+            id: filePath,
+            summary: `${filePath} (${fileMatches.length} match${fileMatches.length === 1 ? "" : "es"}): ${fileMatches[0].text.trim().slice(0, 120)}`,
+        }));
+        const ranked = await rankCandidates(query, candidates);
+        if (!ranked)
+            return untouched;
+        const shown = ranked.order.slice(0, PREFILTER_FILES_SHOWN);
+        const withheld = ranked.order.slice(PREFILTER_FILES_SHOWN);
+        if (withheld.length === 0)
+            return untouched;
+        const shownSet = new Set(shown);
+        const kept = matches.filter((m) => shownSet.has(m.filePath));
+        const note = [
+            ``,
+            `── ${withheld.length} more file(s) matched but were ranked lower by a local model (${ranked.model}) running on this machine:`,
+            ...withheld.slice(0, 25).map((f) => `   ${f}`),
+            ...(withheld.length > 25 ? [`   … and ${withheld.length - 25} more`] : []),
+            `This ranking is a local model's judgement, not a filter on relevance — if what you need`,
+            `is not above, re-run this search with maxResults raised or a narrower query to see the`,
+            `full results, or read one of the files listed here directly.`,
+        ].join("\n");
+        reportSavings({
+            source: "contextSqueeze",
+            charsBefore: matches.reduce((n, m) => n + m.text.length, 0),
+            charsAfter: kept.reduce((n, m) => n + m.text.length, 0),
+            toolName: "search_workspace",
+            query: query.substring(0, 100),
+        });
+        return { matches: kept, totalFiles, note, applied: true };
+    }
+    catch (err) {
+        // The prefilter is an optimization. It must never be the reason a search returns less.
+        logWarn("search_workspace", "local prefilter failed, returning unranked results");
+        return untouched;
+    }
+}
 async function handleSearchWorkspace(args) {
     const query = args?.query;
     const extension = args?.extension;
@@ -1861,29 +2047,62 @@ async function handleSearchWorkspace(args) {
     try {
         const extensions = parseExtensionFilter(extension);
         const cached = getCachedSearch(workspaceRoot, query, extensions, maxResults);
+        // `SearchCache` spares the filesystem walk, but it still hands back the full result
+        // text — and re-emitting an identical wall of matches costs exactly as many tokens as
+        // producing it did. The ledger below is what turns that into a saving, so both the
+        // cached and freshly-computed paths converge on one `resultText` first.
+        let resultText;
         if (cached.text !== null) {
             reportSavings({ source: "cache", tokens: Math.floor(cached.text.length / 4), toolName: "search_workspace", query: query.substring(0, 100) });
-            return { content: [{ type: "text", text: cached.text }] };
-        }
-        const { matches, truncated } = searchWorkspace(workspaceRoot, query, extensions, maxResults);
-        if (matches.length === 0) {
-            const emptyText = `No matches found in the workspace for "${query}".`;
-            setCachedSearch(query, extensions, maxResults, cached.fingerprint, emptyText);
-            return { content: [{ type: "text", text: emptyText }] };
+            resultText = cached.text;
         }
-        const grouped = groupSearchResults(matches, truncated, undefined, workspaceRoot);
-        let formatted = grouped.formatted;
-        try {
-            const scrubber = new SemanticScrubber();
-            const { maskedPrompt } = scrubber.mask(formatted);
-            formatted = maskedPrompt;
+        else {
+            const { matches, truncated } = searchWorkspace(workspaceRoot, query, extensions, maxResults);
+            if (matches.length === 0) {
+                resultText = `No matches found in the workspace for "${query}".`;
+                setCachedSearch(query, extensions, maxResults, cached.fingerprint, resultText);
+            }
+            else {
+                // Opt-in: a local model ranks the matching files so the expensive model only reads
+                // the ones likely to matter. It only ever reorders and truncates with disclosure —
+                // and returns null on any doubt, in which case `matches` is used untouched.
+                const prefilter = await prefilterSearchMatches(query, matches);
+                const grouped = groupSearchResults(prefilter.matches, truncated, undefined, workspaceRoot);
+                let formatted = grouped.formatted + prefilter.note;
+                try {
+                    const scrubber = new SemanticScrubber();
+                    const { maskedPrompt } = scrubber.mask(formatted);
+                    formatted = maskedPrompt;
+                }
+                catch (err) {
+                    logWarn("search_workspace", "SemanticScrubber failed, returning raw results");
+                }
+                const truncationNote = grouped.truncated ? ` (truncated at ${maxResults} matches — narrow your query or extension filter for the rest)` : "";
+                // The header reports what the search actually found, not what survived the
+                // prefilter — otherwise a ranked-down file would vanish from the count as well as
+                // from the list, and nothing would tell the reader it ever existed.
+                resultText = `Found ${matches.length} matches across ${prefilter.totalFiles} files${truncationNote}:\n\n${formatted}`;
+                // A ranked-down result is never cached: it would then be replayed to a later call
+                // whose local model was unavailable, silently serving a subset as if it were the
+                // whole search. Repeats are handled by the output ledger below instead.
+                if (!prefilter.applied) {
+                    setCachedSearch(query, extensions, maxResults, cached.fingerprint, resultText);
+                }
+            }
         }
-        catch (err) {
-            logWarn("search_workspace", "SemanticScrubber failed, returning raw results");
+        const key = ledgerKey("search_workspace", { query, extension: extension ?? null, maxResults, cwd: workspaceRoot });
+        const ledger = checkOutput(key, resultText, { label: `search for "${query}"` });
+        recordLedgerOutput(key, resultText);
+        if (ledger.replacement) {
+            reportSavings({
+                source: "contextSqueeze",
+                charsBefore: resultText.length,
+                charsAfter: ledger.replacement.length,
+                toolName: "search_workspace",
+                query: query.substring(0, 100),
+            });
+            return { content: [{ type: "text", text: ledger.replacement }] };
         }
-        const truncationNote = grouped.truncated ? ` (truncated at ${maxResults} matches — narrow your query or extension filter for the rest)` : "";
-        const resultText = `Found ${grouped.totalMatches} matches across ${grouped.filesMatched} files${truncationNote}:\n\n${formatted}`;
-        setCachedSearch(query, extensions, maxResults, cached.fingerprint, resultText);
         return {
             content: [
                 {
@@ -2157,7 +2376,7 @@ function walkDirForHologram(dir, rel, extensions, stats) {
                 const ext = entry.name.split(".").pop() || "";
                 if (extensions.includes(ext)) {
                     stats.filesScanned++;
-                    allSymbols = allSymbols.concat(extractSymbolsWithTsCompiler(fullPath, relPath, stats.parseErrors));
+                    allSymbols = allSymbols.concat(getOrExtractSymbols(fullPath, relPath, extractSymbolsWithTsCompiler, stats.parseErrors));
                 }
             }
         }
@@ -2428,13 +2647,16 @@ async function handlePruneConversationHistory(args) {
     const messages = args?.messages;
     if (!messages)
         throw new Error("messages is required");
+    const force = !!args?.force;
     try {
-        const result = pruneHistoryMessages(messages);
-        reportSavings({
-            source: "historyPrune",
-            tokens: result.tokensSavedEstimate,
-            toolName: "prune_conversation_history",
-        });
+        const result = pruneHistoryMessages(messages, { force });
+        if (result.applied) {
+            reportSavings({
+                source: "historyPrune",
+                tokens: result.tokensSavedEstimate,
+                toolName: "prune_conversation_history",
+            });
+        }
         return {
             content: [
                 {
@@ -2442,6 +2664,9 @@ async function handlePruneConversationHistory(args) {
                     text: JSON.stringify({
                         messages: result.messages,
                         tokensSavedEstimate: result.tokensSavedEstimate,
+                        cacheInvalidationEstimate: result.cacheInvalidationEstimate,
+                        applied: result.applied,
+                        ...(result.reason ? { reason: result.reason } : {}),
                     }, null, 2),
                 },
             ],
@@ -3769,113 +3994,9 @@ function generateAzurePipelineYaml(threshold) {
         `      AZURE_DEVOPS_TOKEN: \$(AZURE_DEVOPS_TOKEN)`,
     ].join("\n");
 }
-function buildDepGraphMap(workspaceRoot) {
-    const map = new Map();
-    const IGNORE_DG = new Set(["node_modules", ".git", "dist", "chroma_data", ".lemma", "build", "coverage", ".next"]);
-    function walkDG(dir) {
-        let entries = [];
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const e of entries) {
-            if (IGNORE_DG.has(e.name))
-                continue;
-            const abs = path.join(dir, e.name);
-            if (e.isDirectory()) {
-                walkDG(abs);
-            }
-            else if (/\.(ts|tsx|js|jsx)$/.test(e.name) && !e.name.endsWith(".d.ts")) {
-                const rel = path.relative(workspaceRoot, abs).replace(/\\/g, "/");
-                map.set(rel, { rel, abs, imports: [], importedBy: [], externalImports: [], exports: [] });
-            }
-        }
-    }
-    walkDG(workspaceRoot);
-    for (const [, node] of map) {
-        try {
-            const src = fs.readFileSync(node.abs, "utf8");
-            const sf = ts.createSourceFile(node.abs, src, ts.ScriptTarget.Latest, true);
-            ts.forEachChild(sf, (n) => {
-                if (ts.isImportDeclaration(n) && ts.isStringLiteral(n.moduleSpecifier)) {
-                    const spec = n.moduleSpecifier.text;
-                    if (spec.startsWith(".")) {
-                        const dir = path.dirname(node.abs);
-                        let resolved = path.resolve(dir, spec);
-                        for (const ext of [".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.tsx", "/index.js"]) {
-                            if (fs.existsSync(resolved + ext)) {
-                                resolved += ext;
-                                break;
-                            }
-                        }
-                        const rel = path.relative(workspaceRoot, resolved).replace(/\\/g, "/");
-                        if (!node.imports.includes(rel))
-                            node.imports.push(rel);
-                    }
-                    else {
-                        const pkg = spec.split("/")[0];
-                        if (!node.externalImports.includes(pkg))
-                            node.externalImports.push(pkg);
-                    }
-                }
-                const hasExportMod = (nd) => ts.canHaveModifiers(nd) &&
-                    (ts.getModifiers(nd) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
-                if (hasExportMod(n)) {
-                    if (ts.isFunctionDeclaration(n) && n.name)
-                        node.exports.push(n.name.text);
-                    else if (ts.isClassDeclaration(n) && n.name)
-                        node.exports.push(n.name.text);
-                    else if (ts.isVariableStatement(n)) {
-                        for (const decl of n.declarationList.declarations) {
-                            if (ts.isIdentifier(decl.name))
-                                node.exports.push(decl.name.text);
-                        }
-                    }
-                    else if (ts.isInterfaceDeclaration(n))
-                        node.exports.push(n.name.text);
-                    else if (ts.isTypeAliasDeclaration(n))
-                        node.exports.push(n.name.text);
-                    else if (ts.isEnumDeclaration(n))
-                        node.exports.push(n.name.text);
-                }
-                if (ts.isExportDeclaration(n) && n.exportClause && ts.isNamedExports(n.exportClause)) {
-                    for (const el of n.exportClause.elements)
-                        node.exports.push(el.name.text);
-                }
-            });
-        }
-        catch { /* skip unparseable */ }
-    }
-    for (const [, node] of map) {
-        for (const imp of node.imports) {
-            const target = map.get(imp);
-            if (target && !target.importedBy.includes(node.rel))
-                target.importedBy.push(node.rel);
-        }
-    }
-    return map;
-}
-function bfsDepGraph(map, startRel, direction, maxDepth) {
-    const visited = new Map();
-    const queue = [{ rel: startRel, depth: 0 }];
-    while (queue.length > 0) {
-        const item = queue.shift();
-        if (visited.has(item.rel) || item.depth > maxDepth)
-            continue;
-        const node = map.get(item.rel);
-        if (!node)
-            continue;
-        visited.set(item.rel, { node, depth: item.depth });
-        if (item.depth < maxDepth) {
-            const neighbors = direction === "forward" ? node.imports : node.importedBy;
-            for (const n of neighbors)
-                queue.push({ rel: n, depth: item.depth + 1 });
-        }
-    }
-    return visited;
-}
+// ═══════════════════════════════════════════════════════════════════════════════
+// ─── depgraph ─────────────────────────────────────────────────────────────────
+// ═══════════════════════════════════════════════════════════════════════════════
 function detectDepCycles(map, subset) {
     const cycles = [];
     const visited = new Set();
@@ -4080,13 +4201,46 @@ async function handleDepgraph(args) {
             output = formatDGText(targetNode, forwardVisited, backwardVisited, cycles, includeExternal, showReverse);
         }
         const stats = `\n\n📊 Stats: ${forwardVisited.size} nodos forward, ${backwardVisited.size} nodos reverse, depth=${depth}`;
-        return { content: [{ type: "text", text: output + (format === "json" ? "" : stats) }] };
+        const finalText = output + (format === "json" ? "" : stats);
+        const key = ledgerKey("depgraph", { file: relTarget, depth, format, showReverse, includeExternal, detectCircular, cwd: workspaceRoot });
+        const ledger = checkOutput(key, finalText, { label: `depgraph for ${relTarget}` });
+        recordLedgerOutput(key, finalText);
+        if (ledger.replacement) {
+            reportSavings({ source: "contextSqueeze", charsBefore: finalText.length, charsAfter: ledger.replacement.length, toolName: "depgraph", filePath: relTarget });
+            return { content: [{ type: "text", text: ledger.replacement }] };
+        }
+        return { content: [{ type: "text", text: finalText }] };
     }
     catch (err) {
         logError("depgraph", err);
         return { content: [{ type: "text", text: `depgraph failed: ${err.message}` }] };
     }
 }
+async function handleAffectedTests(args) {
+    const workspaceRoot = process.cwd();
+    try {
+        const files = Array.isArray(args?.files) ? args.files.filter((f) => typeof f === "string") : undefined;
+        const result = findAffectedTests({ workspaceRoot, files, baseRef: args?.baseRef });
+        const text = formatAffectedTests(result);
+        // Worth recording even when it narrows nothing: the receipt is the record of what this
+        // tool actually did, and "recommended the full suite" is as much a result as a subset.
+        recordReceiptEvent("tool_call", "affected_tests", {
+            changed: result.changed.length,
+            affected: result.affected.length,
+            totalTests: result.totalTests,
+            narrowed: result.command !== null,
+        });
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        logError("affected_tests", err);
+        // Failing here must never look like "nothing is affected" — that would talk a caller
+        // out of running tests at all.
+        return {
+            content: [{ type: "text", text: `affected_tests failed: ${err.message}\nFall back to running the full suite.` }],
+        };
+    }
+}
 // ═══════════════════════════════════════════════════════════════════════════════
 // ─── refactor ─────────────────────────────────────────────────────────────────
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -4584,10 +4738,13 @@ async function handleSmartFileSlice(args) {
 async function handleTestOracle(args) {
     const command = args.command || "npm test";
     const workspaceRoot = process.cwd();
-    // Run tests, check errors
+    // A failing test suite is re-run more than any other command in a session, and the
+    // failure list barely moves between runs. Both branches funnel into one `resultText` so
+    // the ledger can answer a repeat with a diff instead of the same stack traces again.
+    let resultText;
     try {
         const out = execSync(command, { cwd: workspaceRoot, encoding: "utf8", timeout: 30000 });
-        return { content: [{ type: "text", text: `All tests passed!\n\nOutput:\n${out.substring(0, 1000)}` }] };
+        resultText = `All tests passed!\n\nOutput:\n${out.substring(0, 1000)}`;
     }
     catch (e) {
         const stdout = e.stdout || "";
@@ -4597,8 +4754,19 @@ async function handleTestOracle(args) {
             .split("\n")
             .filter((l) => l.includes("fail") || l.includes("Error") || l.includes("at ") || l.includes("✗") || l.includes("Stack"));
         const summary = failureLines.slice(0, 80).join("\n") || `Test execution failed:\n${stdout.substring(0, 800)}\n${stderr.substring(0, 800)}`;
-        return { content: [{ type: "text", text: `Tests Failed. Compressed failures:\n\n${summary}` }] };
+        resultText = `Tests Failed. Compressed failures:\n\n${summary}`;
+    }
+    const key = ledgerKey("test_oracle", { command, cwd: workspaceRoot });
+    const ledger = checkOutput(key, resultText, {
+        label: `\`${command}\``,
+        rerunHint: "The suite did run again — this reports its result, it does not skip execution.",
+    });
+    recordLedgerOutput(key, resultText);
+    if (ledger.replacement) {
+        reportSavings({ source: "contextSqueeze", charsBefore: resultText.length, charsAfter: ledger.replacement.length, toolName: "test_oracle" });
+        return { content: [{ type: "text", text: ledger.replacement }] };
     }
+    return { content: [{ type: "text", text: resultText }] };
 }
 // ── Schema Extract ───────────────────────────────────────────────────
 async function handleSchemaExtract(args) {