@kage-core/kage-graph-mcp 1.4.0 → 2.0.0

package/dist/kernel.js

@@ -62,6 +62,9 @@ exports.makePacketId = makePacketId;
 exports.parseFrontmatter = parseFrontmatter;
 exports.kageMemoryAccess = kageMemoryAccess;
 exports.kageMemoryLifecycle = kageMemoryLifecycle;
+exports.recordValueEvent = recordValueEvent;
+exports.valueSummary = valueSummary;
+exports.formatTokenCount = formatTokenCount;
 exports.kageActivity = kageActivity;
 exports.kageMemoryReconciliation = kageMemoryReconciliation;
 exports.evaluateMemoryAdmission = evaluateMemoryAdmission;
@@ -76,6 +79,8 @@ exports.kageMemoryAudit = kageMemoryAudit;
 exports.kageMemoryHandoff = kageMemoryHandoff;
 exports.buildStructuralFileForWorker = buildStructuralFileForWorker;
 exports.buildStructuralIndex = buildStructuralIndex;
+exports.treeSitterLanguagesForPaths = treeSitterLanguagesForPaths;
+exports.ensureTreeSitterLanguages = ensureTreeSitterLanguages;
 exports.writeLspSymbolIndex = writeLspSymbolIndex;
 exports.writeCodeIndex = writeCodeIndex;
 exports.buildCodeGraph = buildCodeGraph;
@@ -97,6 +102,7 @@ exports.kageTeammateBrief = kageTeammateBrief;
 exports.kageRisk = kageRisk;
 exports.kageDependencyPath = kageDependencyPath;
 exports.kageCleanupCandidates = kageCleanupCandidates;
+exports.truthReport = truthReport;
 exports.kageReviewerSuggestions = kageReviewerSuggestions;
 exports.kageContributors = kageContributors;
 exports.kageContextSlots = kageContextSlots;
@@ -138,19 +144,13 @@ exports.proposeFromDiff = proposeFromDiff;
 exports.buildBranchOverlay = buildBranchOverlay;
 exports.createReviewArtifact = createReviewArtifact;
 exports.prSummarize = prSummarize;
+exports.staleCatch = staleCatch;
+exports.formatStaleCatch = formatStaleCatch;
 exports.prCheck = prCheck;
 exports.kageHookStatus = kageHookStatus;
 exports.kageHookInstall = kageHookInstall;
 exports.kageHookUninstall = kageHookUninstall;
 exports.exportPublicBundle = exportPublicBundle;
-exports.orgStatus = orgStatus;
-exports.orgUploadPacket = orgUploadPacket;
-exports.orgReviewPacket = orgReviewPacket;
-exports.orgRecall = orgRecall;
-exports.layeredRecall = layeredRecall;
-exports.exportOrgRegistry = exportOrgRegistry;
-exports.buildMarketplace = buildMarketplace;
-exports.buildGlobalCdnBundle = buildGlobalCdnBundle;
 exports.recordFeedback = recordFeedback;
 exports.validateProject = validateProject;
 exports.initProject = initProject;
@@ -960,6 +960,169 @@ function recordRecallAccess(projectDir, results) {
         // Recall should never fail because local access telemetry could not be updated.
     }
 }
+// ---------------------------------------------------------------------------
+// Value ledger: persistent per-repo receipts of what the harness actually saved
+// or blocked — tokens not spent re-reading cited source, hard-stale memories
+// withheld from recall, caller-intent questions answered from the call graph.
+// Read by `kage gains` and the receipt lines appended to recall/context output.
+// ---------------------------------------------------------------------------
+const VALUE_LEDGER_SCHEMA_VERSION = 1;
+const VALUE_LEDGER_EVENT_CAP = 5000;
+// Rough Sonnet-class input price used for the dollar estimate: $15 per 1M tokens.
+const VALUE_DOLLARS_PER_MILLION_TOKENS = 15;
+function valueLedgerPath(projectDir) {
+    return (0, node_path_1.join)(reportsDir(projectDir), "value.json");
+}
+function emptyValueLedger() {
+    return {
+        schema_version: VALUE_LEDGER_SCHEMA_VERSION,
+        totals: { tokens_saved: 0, stale_withheld: 0, stale_caught: 0, recalls: 0, caller_answers: 0 },
+        events: [],
+    };
+}
+function nonNegativeCount(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+}
+function readValueLedger(projectDir) {
+    const path = valueLedgerPath(projectDir);
+    if (!(0, node_fs_1.existsSync)(path))
+        return emptyValueLedger();
+    try {
+        const raw = readJson(path);
+        const totals = (raw.totals ?? {});
+        const events = (Array.isArray(raw.events) ? raw.events : [])
+            .filter((event) => {
+            const candidate = event;
+            return Boolean(candidate)
+                && typeof candidate?.at === "string"
+                && Number.isFinite(Date.parse(candidate.at))
+                && (candidate.kind === "recall_served" || candidate.kind === "stale_withheld" || candidate.kind === "stale_caught" || candidate.kind === "caller_answered");
+        })
+            .slice(-VALUE_LEDGER_EVENT_CAP);
+        return {
+            schema_version: VALUE_LEDGER_SCHEMA_VERSION,
+            totals: {
+                tokens_saved: nonNegativeCount(totals.tokens_saved),
+                stale_withheld: nonNegativeCount(totals.stale_withheld),
+                stale_caught: nonNegativeCount(totals.stale_caught),
+                recalls: nonNegativeCount(totals.recalls),
+                caller_answers: nonNegativeCount(totals.caller_answers),
+            },
+            events,
+        };
+    }
+    catch {
+        return emptyValueLedger();
+    }
+}
+function recordValueEvents(projectDir, events) {
+    if (!events.length)
+        return;
+    try {
+        const ledger = readValueLedger(projectDir);
+        const at = nowIso();
+        for (const event of events) {
+            const record = { at, kind: event.kind };
+            if (event.kind === "recall_served") {
+                record.tokens_saved = nonNegativeCount(event.tokens_saved);
+                ledger.totals.tokens_saved += record.tokens_saved;
+                ledger.totals.recalls += 1;
+            }
+            else if (event.kind === "stale_withheld") {
+                record.packet_title = event.packet_title;
+                ledger.totals.stale_withheld += 1;
+            }
+            else if (event.kind === "stale_caught") {
+                record.packet_title = event.packet_title;
+                ledger.totals.stale_caught += 1;
+            }
+            else {
+                ledger.totals.caller_answers += 1;
+            }
+            ledger.events.push(record);
+        }
+        if (ledger.events.length > VALUE_LEDGER_EVENT_CAP)
+            ledger.events = ledger.events.slice(-VALUE_LEDGER_EVENT_CAP);
+        // Atomic read-modify-write: write to a temp file then rename so a crashed or
+        // concurrent writer can never leave a torn value.json behind.
+        const path = valueLedgerPath(projectDir);
+        ensureDir((0, node_path_1.dirname)(path));
+        const tmp = `${path}.${process.pid}.tmp`;
+        (0, node_fs_1.writeFileSync)(tmp, `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
+        (0, node_fs_1.renameSync)(tmp, path);
+    }
+    catch {
+        // Value telemetry must never break recall or code-graph queries.
+    }
+}
+function recordValueEvent(projectDir, event) {
+    recordValueEvents(projectDir, [event]);
+}
+function estimatedTokenDollars(tokensSaved) {
+    return Number(((tokensSaved / 1_000_000) * VALUE_DOLLARS_PER_MILLION_TOKENS).toFixed(2));
+}
+function summarizeValueWindow(events, cutoff) {
+    const window = { tokens_saved: 0, stale_withheld: 0, stale_caught: 0, recalls: 0, caller_answers: 0 };
+    for (const event of events) {
+        const at = Date.parse(event.at);
+        if (!Number.isFinite(at) || at < cutoff)
+            continue;
+        if (event.kind === "recall_served") {
+            window.recalls += 1;
+            window.tokens_saved += nonNegativeCount(event.tokens_saved);
+        }
+        else if (event.kind === "stale_withheld") {
+            window.stale_withheld += 1;
+        }
+        else if (event.kind === "stale_caught") {
+            window.stale_caught += 1;
+        }
+        else {
+            window.caller_answers += 1;
+        }
+    }
+    return { ...window, estimated_dollars: estimatedTokenDollars(window.tokens_saved) };
+}
+function valueSummary(projectDir) {
+    const ledger = readValueLedger(projectDir);
+    const todayStart = new Date();
+    todayStart.setHours(0, 0, 0, 0);
+    return {
+        schema_version: VALUE_LEDGER_SCHEMA_VERSION,
+        project_dir: (0, node_path_1.resolve)(projectDir),
+        today: summarizeValueWindow(ledger.events, todayStart.getTime()),
+        last_7d: summarizeValueWindow(ledger.events, Date.now() - 7 * 86_400_000),
+        all_time: { ...ledger.totals, estimated_dollars: estimatedTokenDollars(ledger.totals.tokens_saved) },
+    };
+}
+// Human display for ledger token counts: 412 -> "412", 412_345 -> "412K", 4_120_000 -> "4.1M".
+function formatTokenCount(tokens) {
+    const count = Math.max(0, Math.round(tokens));
+    if (count >= 1_000_000)
+        return `${(count / 1_000_000).toFixed(1)}M`;
+    if (count >= 1_000)
+        return `${Math.round(count / 1_000)}K`;
+    return String(count);
+}
+// Receipt math: tokens an agent would have spent reading the cited source files
+// of the served packets (bytes / 4) minus the tokens the recall context block
+// itself costs (length / 4). Floored at zero — a recall never "costs" savings.
+function recallTokensSaved(projectDir, results, contextBlock) {
+    const paths = unique(results.flatMap((entry) => entry.packet.paths).filter((path) => meaningfulMemoryPath(path)));
+    let sourceBytes = 0;
+    for (const path of paths) {
+        try {
+            const stats = (0, node_fs_1.statSync)((0, node_path_1.join)(projectDir, path));
+            if (stats.isFile())
+                sourceBytes += stats.size;
+        }
+        catch {
+            // Missing cited files save nothing.
+        }
+    }
+    return Math.max(0, Math.floor(sourceBytes / 4) - Math.floor(contextBlock.length / 4));
+}
 const AUDIT_ACTIVITY_KIND = {
     capture: "capture", approve: "capture", supersede: "supersede", deprecate: "deprecate",
     update: "update", promote: "promote", feedback: "feedback",
@@ -1104,6 +1267,10 @@ function fingerprintableMemoryPath(path) {
     const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
     return meaningfulMemoryPath(normalized) && !normalized.startsWith(".agent_memory/");
 }
+// Process-level fingerprint cache validated by mtime+size: staleness checks run on
+// every recall, and re-hashing every grounded file dominated recall latency on
+// repos with many packets. Content changes always re-hash (mtime/size moves).
+const fingerprintProcessCache = new Map();
 function memoryPathFingerprint(projectDir, path, cache) {
     const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
     if (!fingerprintableMemoryPath(normalized))
@@ -1118,11 +1285,17 @@ function memoryPathFingerprint(projectDir, path, cache) {
             cache?.set(cacheKey, null);
             return null;
         }
+        const warm = fingerprintProcessCache.get(cacheKey);
+        if (warm && warm.mtimeMs === stats.mtimeMs && warm.size === stats.size) {
+            cache?.set(cacheKey, warm.fingerprint);
+            return warm.fingerprint;
+        }
         const fingerprint = {
             path: normalized,
             sha256: sha256Hex((0, node_fs_1.readFileSync)(absolutePath)),
             size: stats.size,
         };
+        fingerprintProcessCache.set(cacheKey, { mtimeMs: stats.mtimeMs, size: stats.size, fingerprint });
         cache?.set(cacheKey, fingerprint);
         return fingerprint;
     }
@@ -2507,6 +2680,10 @@ function shouldSkipCodePath(relativePath) {
         .some((part) => [
         ".git",
         ".agent_memory",
+        // Agent working dirs: .claude holds settings AND worktrees/ (parallel agent
+        // checkouts) — indexing them pollutes the code graph with phantom duplicates.
+        ".claude",
+        ".codex",
         "node_modules",
         "vendor",
         ".venv",
@@ -2790,7 +2967,9 @@ function structuralFileCacheDir(projectDir) {
 function structuralPackedFileCachePath(projectDir) {
     return (0, node_path_1.join)(structuralIndexDir(projectDir), "file-cache.json");
 }
-const STRUCTURAL_EXTRACTOR_VERSION = 2;
+// Bump whenever symbol/call extraction changes, or cached per-file results
+// keep serving pre-change output and upgrades silently never land.
+const STRUCTURAL_EXTRACTOR_VERSION = 4; // v4: tree-sitter symbols for python/go/rust/java/ruby
 function structuralFileCachePath(projectDir, rel, hash) {
     return (0, node_path_1.join)(structuralFileCacheDir(projectDir), `v${STRUCTURAL_EXTRACTOR_VERSION}-${slugify(rel)}-${hash}.json`);
 }
@@ -3203,6 +3382,16 @@ function writeStructuralFileCachePack(projectDir, results) {
     packedStructuralCache.delete((0, node_path_1.resolve)(projectDir));
     (0, node_fs_1.rmSync)(structuralFileCacheDir(projectDir), { recursive: true, force: true });
 }
+// A regex-tier cache entry for a language whose tree-sitter grammar is now
+// loaded would pin weak symbols past the upgrade; treat it as a miss so the
+// file re-extracts at the stronger tier.
+function usableStructuralCache(rel, cached) {
+    if (!cached)
+        return null;
+    if (treeSitterParserFor(rel) && cached.symbols.some((symbol) => symbol.parser === "generic-static"))
+        return null;
+    return cached;
+}
 function buildStructuralFile(projectDir, absolutePath, knownFiles, prior) {
     const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
     const stats = (0, node_fs_1.statSync)(absolutePath);
@@ -3210,11 +3399,11 @@ function buildStructuralFile(projectDir, absolutePath, knownFiles, prior) {
     const canReuseHash = priorEntry && priorEntry.size_bytes === stats.size && Math.round(priorEntry.mtime_ms) === Math.round(stats.mtimeMs);
     let buffer = canReuseHash ? null : (0, node_fs_1.readFileSync)(absolutePath);
     let hash = canReuseHash ? priorEntry.hash : sha256Hex(buffer ?? "");
-    let cached = readCachedStructuralFile(projectDir, rel, hash);
+    let cached = usableStructuralCache(rel, readCachedStructuralFile(projectDir, rel, hash));
     if (!cached && !buffer) {
         buffer = (0, node_fs_1.readFileSync)(absolutePath);
         hash = sha256Hex(buffer);
-        cached = readCachedStructuralFile(projectDir, rel, hash);
+        cached = usableStructuralCache(rel, readCachedStructuralFile(projectDir, rel, hash));
     }
     const entry = {
         path: rel,
@@ -3236,7 +3425,7 @@ function buildStructuralFile(projectDir, absolutePath, knownFiles, prior) {
             rawImports.push(...extractImports(projectDir, rel, content, knownFiles));
         }
         else if (CODE_EXTENSIONS.has(extensionOf(rel))) {
-            rawSymbols.push(...extractGenericSymbols(rel, content));
+            rawSymbols.push(...(extractTreeSitterSymbols(rel, content) ?? extractGenericSymbols(rel, content)));
             rawImports.push(...extractGenericImports(projectDir, rel, content, knownFiles));
         }
     }
@@ -3658,6 +3847,20 @@ function extractSymbols(path, text) {
                 addSymbol(declaration.name.text, kind, declaration, exported, node.getText(sourceFile).split(/\r?\n/)[0]);
             }
         }
+        else if (ts.isExpressionStatement(node) &&
+            ts.isBinaryExpression(node.expression) &&
+            node.expression.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isPropertyAccessExpression(node.expression.left) &&
+            (ts.isFunctionExpression(node.expression.right) || ts.isArrowFunction(node.expression.right))) {
+            // Method-assignment pattern: `app.use = function use(fn) {…}`, `proto.handle = (req) => {…}`.
+            // Express/Koa-style APIs define most of their public surface this way; without this
+            // branch those symbols are invisible to the code graph.
+            const left = node.expression.left;
+            const receiver = left.expression.getText(sourceFile);
+            const exported = receiver === "exports" || receiver === "module.exports" || receiver.endsWith(".prototype");
+            const firstLine = `${left.getText(sourceFile)} = ${node.expression.right.getText(sourceFile).split(/\r?\n/)[0] ?? ""}`;
+            addSymbol(left.name.text, "method", node, exported, firstLine.trim().slice(0, 180));
+        }
         else if (codeFileKind(path) === "test" && ts.isCallExpression(node)) {
             const callee = propertyOrIdentifierName(node.expression);
             const first = stringLiteralValue(node.arguments[0]);
@@ -3669,6 +3872,255 @@ function extractSymbols(path, text) {
     visit(sourceFile);
     return symbols.sort((a, b) => a.line - b.line || a.name.localeCompare(b.name));
 }
+const TREE_SITTER_LANGUAGES = {
+    python: "python",
+    go: "go",
+    rust: "rust",
+    java: "java",
+    ruby: "ruby",
+};
+const treeSitterParsers = new Map();
+const treeSitterFailedLanguages = new Set();
+// web-tree-sitter mutates its CommonJS export during init, so the pre-init
+// Parser class is cached once instead of re-required per language.
+let treeSitterRuntime = null;
+function treeSitterLanguagesForPaths(paths) {
+    return [...new Set(paths.map((path) => codeLanguage(path)).filter((language) => language in TREE_SITTER_LANGUAGES))];
+}
+// web-tree-sitter only initializes asynchronously, so grammars are loaded here —
+// once per process, before any file loop — and per-file extraction stays
+// synchronous. A language whose grammar fails to load falls back to the regex
+// extractor instead of crashing or blocking.
+async function ensureTreeSitterLanguages(languages = Object.keys(TREE_SITTER_LANGUAGES)) {
+    const wanted = languages.filter((language) => language in TREE_SITTER_LANGUAGES && !treeSitterParsers.has(language) && !treeSitterFailedLanguages.has(language));
+    if (!wanted.length)
+        return;
+    if (!treeSitterRuntime) {
+        try {
+            const Parser = require("web-tree-sitter");
+            await Parser.init();
+            treeSitterRuntime = Parser;
+        }
+        catch {
+            for (const language of wanted)
+                treeSitterFailedLanguages.add(language);
+            return;
+        }
+    }
+    const runtime = treeSitterRuntime;
+    if (!runtime)
+        return;
+    for (const language of wanted) {
+        try {
+            const grammar = await runtime.Language.load(require.resolve(`tree-sitter-wasms/out/tree-sitter-${TREE_SITTER_LANGUAGES[language]}.wasm`));
+            const parser = new runtime();
+            parser.setLanguage(grammar);
+            treeSitterParsers.set(language, parser);
+        }
+        catch {
+            treeSitterFailedLanguages.add(language);
+        }
+    }
+}
+function treeSitterParserFor(path) {
+    if (TS_AST_EXTENSIONS.has(extensionOf(path)))
+        return null;
+    return treeSitterParsers.get(codeLanguage(path)) ?? null;
+}
+const TREE_SITTER_SYMBOL_NODE_TYPES = {
+    python: ["function_definition", "class_definition", "assignment"],
+    go: ["function_declaration", "method_declaration", "type_spec"],
+    rust: ["function_item", "function_signature_item", "struct_item", "enum_item", "trait_item"],
+    java: ["class_declaration", "interface_declaration", "enum_declaration", "method_declaration", "constructor_declaration"],
+    ruby: ["method", "singleton_method", "class", "module"],
+};
+const TREE_SITTER_CALL_NODE_TYPES = {
+    python: ["call"],
+    go: ["call_expression"],
+    rust: ["call_expression"],
+    java: ["method_invocation", "object_creation_expression"],
+    ruby: ["call"],
+};
+const TREE_SITTER_CLASS_ANCESTORS = {
+    python: new Set(["class_definition"]),
+    rust: new Set(["impl_item", "trait_item"]),
+    ruby: new Set(["class", "module"]),
+};
+function treeSitterHasClassAncestor(language, node) {
+    const types = TREE_SITTER_CLASS_ANCESTORS[language];
+    if (!types)
+        return false;
+    for (let current = node.parent; current; current = current.parent) {
+        if (types.has(current.type))
+            return true;
+    }
+    return false;
+}
+function treeSitterSymbolFromNode(language, node) {
+    if (language === "python") {
+        if (node.type === "assignment") {
+            const left = node.childForFieldName("left");
+            if (left?.type !== "identifier" || node.childForFieldName("right")?.type !== "lambda")
+                return null;
+            return { name: left.text, kind: "function", exported: !left.text.startsWith("_") };
+        }
+        const name = node.childForFieldName("name")?.text;
+        if (!name)
+            return null;
+        if (node.type === "class_definition")
+            return { name, kind: "class", exported: !name.startsWith("_") };
+        return { name, kind: treeSitterHasClassAncestor(language, node) ? "method" : "function", exported: !name.startsWith("_") };
+    }
+    if (language === "go") {
+        const name = node.childForFieldName("name")?.text;
+        if (!name)
+            return null;
+        const exported = /^[A-Z]/.test(name);
+        if (node.type === "method_declaration")
+            return { name, kind: "method", exported };
+        if (node.type === "type_spec") {
+            const typeNode = node.childForFieldName("type");
+            if (typeNode?.type !== "struct_type" && typeNode?.type !== "interface_type")
+                return null;
+            return { name, kind: "class", exported };
+        }
+        return { name, kind: "function", exported };
+    }
+    if (language === "rust") {
+        const name = node.childForFieldName("name")?.text;
+        if (!name)
+            return null;
+        const exported = node.namedChildren.some((child) => child.type === "visibility_modifier");
+        if (node.type === "struct_item" || node.type === "enum_item" || node.type === "trait_item")
+            return { name, kind: "class", exported };
+        return { name, kind: treeSitterHasClassAncestor(language, node) ? "method" : "function", exported };
+    }
+    if (language === "java") {
+        const name = node.childForFieldName("name")?.text;
+        if (!name)
+            return null;
+        const exported = node.namedChildren.some((child) => child.type === "modifiers" && /\bpublic\b/.test(child.text));
+        if (node.type === "method_declaration" || node.type === "constructor_declaration")
+            return { name, kind: "method", exported };
+        return { name, kind: "class", exported };
+    }
+    if (language === "ruby") {
+        const name = node.childForFieldName("name")?.text;
+        if (!name)
+            return null;
+        if (node.type === "class" || node.type === "module")
+            return { name, kind: "class", exported: true };
+        return { name, kind: treeSitterHasClassAncestor(language, node) ? "method" : "function", exported: !name.startsWith("_") };
+    }
+    return null;
+}
+function extractTreeSitterSymbols(path, text) {
+    const parser = treeSitterParserFor(path);
+    if (!parser)
+        return null;
+    const language = codeLanguage(path);
+    const fileKind = codeFileKind(path);
+    let tree;
+    try {
+        tree = parser.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const symbols = [];
+    try {
+        for (const node of tree.rootNode.descendantsOfType(TREE_SITTER_SYMBOL_NODE_TYPES[language] ?? [])) {
+            const fact = treeSitterSymbolFromNode(language, node);
+            if (!fact)
+                continue;
+            const kind = fact.kind !== "class" && fileKind === "test" && /^(test_|Test|it_|should_)/.test(fact.name) ? "test" : fact.kind;
+            const line = node.startPosition.row + 1;
+            symbols.push({
+                id: symbolId(path, fact.name, kind, line),
+                name: fact.name,
+                kind,
+                path,
+                language,
+                parser: "tree-sitter",
+                export: fact.exported,
+                line,
+                end_line: node.endPosition.row + 1,
+                signature: node.text.split("\n", 1)[0].trim().slice(0, 180),
+            });
+        }
+    }
+    finally {
+        tree.delete();
+    }
+    return symbols.sort((a, b) => a.line - b.line || a.name.localeCompare(b.name));
+}
+function treeSitterCalleeName(language, node) {
+    if (language === "java") {
+        if (node.type === "object_creation_expression")
+            return node.childForFieldName("type")?.text.split("<")[0].split(".").pop() ?? null;
+        return node.childForFieldName("name")?.text ?? null;
+    }
+    if (language === "ruby") {
+        const method = node.childForFieldName("method");
+        return method?.type === "identifier" ? method.text : null;
+    }
+    const callee = node.childForFieldName("function");
+    if (!callee)
+        return null;
+    if (callee.type === "identifier")
+        return callee.text;
+    if (callee.type === "attribute")
+        return callee.childForFieldName("attribute")?.text ?? null;
+    if (callee.type === "selector_expression" || callee.type === "field_expression")
+        return callee.childForFieldName("field")?.text ?? null;
+    if (callee.type === "scoped_identifier")
+        return callee.childForFieldName("name")?.text ?? null;
+    return null;
+}
+function extractTreeSitterCalls(path, text, symbols, symbolByName, context = EMPTY_CALL_RESOLUTION) {
+    const parser = treeSitterParserFor(path);
+    if (!parser)
+        return null;
+    const language = codeLanguage(path);
+    let tree;
+    try {
+        tree = parser.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const calls = [];
+    try {
+        for (const node of tree.rootNode.descendantsOfType(TREE_SITTER_CALL_NODE_TYPES[language] ?? [])) {
+            if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
+                break;
+            const name = treeSitterCalleeName(language, node);
+            if (!name || !/^[A-Za-z_]\w*$/.test(name))
+                continue;
+            const line = node.startPosition.row + 1;
+            const targets = symbolByName.get(name)?.filter((target) => target.path !== path || target.line !== line);
+            if (!targets?.length)
+                continue;
+            const caller = symbolAtLine(symbols, path, line);
+            for (const { target, confidence } of resolveCallTargets(name, path, targets, context, { local: 0.8, imported: 0.75, sameDir: 0.55, nameOnly: 0.32 })) {
+                if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
+                    break;
+                calls.push({
+                    from_symbol: caller?.id ?? null,
+                    to_symbol: target.id,
+                    path,
+                    line,
+                    confidence,
+                    resolution: "tree_sitter_name",
+                });
+            }
+        }
+    }
+    finally {
+        tree.delete();
+    }
+    return calls.sort((a, b) => a.line - b.line || a.to_symbol.localeCompare(b.to_symbol));
+}
 function extractGenericSymbols(path, text) {
     const symbols = [];
     const language = codeLanguage(path);
@@ -3908,7 +4360,7 @@ function normalizeCallConfidence(value, fallback) {
     return Number(Math.max(0, Math.min(1, numeric)).toFixed(2));
 }
 function normalizeCallResolution(value, fallback) {
-    return value === "typescript_ast_name" || value === "generic_static_name" || value === "external_index" ? value : fallback;
+    return value === "typescript_ast_name" || value === "tree_sitter_name" || value === "generic_static_name" || value === "external_index" ? value : fallback;
 }
 function normalizeCallEdge(call, fallback) {
     if (!isRecord(call) || typeof call.to_symbol !== "string")
@@ -3922,7 +4374,34 @@ function normalizeCallEdge(call, fallback) {
         resolution: normalizeCallResolution(call.resolution, fallback.resolution),
     };
 }
-function extractCalls(path, text, symbols, symbolByName) {
+const EMPTY_CALL_RESOLUTION = { importedPaths: new Set(), importedNames: new Map(), dir: "" };
+// Resolve a callee name to symbol targets through scope, not just name matching:
+// local file → explicit import binding → imported module → same directory →
+// (last resort) one name-only match at low confidence. A name imported from an
+// external package resolves to NO repo symbol — same-name repo symbols are not
+// the callee, and emitting them is how bogus cross-package edges were born.
+function resolveCallTargets(name, path, targets, context, confidences) {
+    const local = targets.filter((target) => target.path === path);
+    if (local.length)
+        return local.slice(0, 2).map((target) => ({ target, confidence: confidences.local }));
+    if (context.importedNames.has(name)) {
+        const toPath = context.importedNames.get(name) ?? null;
+        if (toPath === null)
+            return []; // imported from an external package
+        return targets
+            .filter((target) => target.path === toPath)
+            .slice(0, 2)
+            .map((target) => ({ target, confidence: confidences.imported }));
+    }
+    const viaImports = targets.filter((target) => context.importedPaths.has(target.path));
+    if (viaImports.length)
+        return viaImports.slice(0, 2).map((target) => ({ target, confidence: confidences.imported }));
+    const sameDir = targets.filter((target) => context.dir ? target.path.startsWith(`${context.dir}/`) : !target.path.includes("/"));
+    if (sameDir.length)
+        return sameDir.slice(0, 1).map((target) => ({ target, confidence: confidences.sameDir }));
+    return targets.slice(0, 1).map((target) => ({ target, confidence: confidences.nameOnly }));
+}
+function extractCalls(path, text, symbols, symbolByName, context = EMPTY_CALL_RESOLUTION) {
     const sourceFile = sourceFileFor(path, text);
     const calls = [];
     const visit = (node) => {
@@ -3944,7 +4423,7 @@ function extractCalls(path, text, symbols, symbolByName) {
         }
         const line = lineForNode(sourceFile, node);
         const caller = symbolAtLine(symbols, path, line);
-        for (const target of targets.slice(0, 3)) {
+        for (const { target, confidence } of resolveCallTargets(name, path, targets, context, { local: 0.9, imported: 0.85, sameDir: 0.6, nameOnly: 0.35 })) {
             if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
                 break;
             if (target.path === path && target.line === line)
@@ -3954,7 +4433,7 @@ function extractCalls(path, text, symbols, symbolByName) {
                 to_symbol: target.id,
                 path,
                 line,
-                confidence: target.path === path ? 0.9 : 0.75,
+                confidence,
                 resolution: "typescript_ast_name",
             });
         }
@@ -3977,7 +4456,7 @@ const GENERIC_CALL_STOP_WORDS = new Set([
     "switch",
     "while",
 ]);
-function extractGenericCalls(path, text, symbols, symbolByName) {
+function extractGenericCalls(path, text, symbols, symbolByName, context = EMPTY_CALL_RESOLUTION) {
     const calls = [];
     const lines = text.split(/\r?\n/);
     for (let index = 0; index < lines.length && calls.length < MAX_CODE_GRAPH_CALLS_PER_FILE; index += 1) {
@@ -3995,7 +4474,7 @@ function extractGenericCalls(path, text, symbols, symbolByName) {
             if (!targets?.length)
                 continue;
             const caller = symbolAtLine(symbols, path, line);
-            for (const target of targets.slice(0, 3)) {
+            for (const { target, confidence } of resolveCallTargets(name, path, targets, context, { local: 0.7, imported: 0.65, sameDir: 0.5, nameOnly: 0.3 })) {
                 if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
                     break;
                 calls.push({
@@ -4003,7 +4482,7 @@ function extractGenericCalls(path, text, symbols, symbolByName) {
                     to_symbol: target.id,
                     path,
                     line,
-                    confidence: target.path === path ? 0.7 : 0.55,
+                    confidence,
                     resolution: "generic_static_name",
                 });
             }
@@ -4239,8 +4718,16 @@ function fileInputEntries(projectDir, paths, kind) {
         sha256: sha256Hex((0, node_fs_1.readFileSync)(path)),
     }));
 }
+// Bump when call/route/test derivation logic changes so existing repos rebuild
+// their code graph on next index — otherwise builder fixes never reach users
+// whose files haven't changed.
+const CODE_GRAPH_BUILDER_VERSION = 3; // v3: tree-sitter calls for python/go/rust/java/ruby
+function codeGraphBuilderVersionEntry() {
+    return { kind: "code_graph_builder", path: "kage", sha256: String(CODE_GRAPH_BUILDER_VERSION) };
+}
 function codeGraphInputHash(projectDir, absoluteFiles = listCodeFiles(projectDir)) {
     return graphInputHash([
+        codeGraphBuilderVersionEntry(),
         ...fileInputEntries(projectDir, absoluteFiles, "code_file"),
         ...fileInputEntries(projectDir, externalIndexFiles(projectDir).map((index) => index.path), "external_code_index"),
     ]);
@@ -4250,6 +4737,7 @@ function codeGraphInputHashFromStructural(projectDir, structural) {
 }
 function codeGraphInputHashFromStructuralFingerprint(projectDir, fingerprint) {
     return graphInputHash([
+        codeGraphBuilderVersionEntry(),
         { kind: "code_graph_input", path: ".agent_memory/structural/fingerprint", sha256: fingerprint },
         ...fileInputEntries(projectDir, externalIndexFiles(projectDir).map((index) => index.path), "external_code_index"),
     ]);
@@ -4275,6 +4763,7 @@ function currentCodeGraphInputHash(projectDir) {
 }
 function codeGraphStructuralFingerprint(projectDir, structural) {
     const entries = [
+        `builder:${CODE_GRAPH_BUILDER_VERSION}`,
         `structural:${structural.manifest.fingerprint}`,
         ...externalIndexFiles(projectDir)
             .map((index) => index.path)
@@ -4730,6 +5219,11 @@ function buildCodeGraph(projectDir, options = {}) {
     writeCodeIndexManifest(projectDir, codeIndexManifestFromStructural(projectDir, structural, fingerprint, structural.manifest.cache));
     const externalFacts = loadExternalCodeFacts(projectDir);
     const fileByPath = new Map(files.map((file) => [file.path, file]));
+    for (const symbol of symbols) {
+        const file = fileByPath.get(symbol.path);
+        if (file)
+            file.parser = strongerParser(file.parser, symbol.parser);
+    }
     const addSymbol = (symbol) => {
         if (!fileByPath.has(symbol.path))
             return;
@@ -4770,9 +5264,21 @@ function buildCodeGraph(projectDir, options = {}) {
             break;
         const fileSymbols = symbols.filter((symbol) => symbol.path === rel);
         const fileImports = imports.filter((item) => item.from_path === rel);
+        const importedNames = new Map();
+        for (const item of fileImports) {
+            for (const importedName of item.imported) {
+                if (!importedNames.has(importedName))
+                    importedNames.set(importedName, item.to_path);
+            }
+        }
+        const resolution = {
+            importedPaths: new Set(fileImports.map((item) => item.to_path).filter((value) => Boolean(value))),
+            importedNames,
+            dir: rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "",
+        };
         const fileCalls = TS_AST_EXTENSIONS.has(extensionOf(rel))
-            ? extractCalls(rel, content, fileSymbols, symbolByName)
-            : extractGenericCalls(rel, content, fileSymbols, symbolByName);
+            ? extractCalls(rel, content, fileSymbols, symbolByName, resolution)
+            : extractTreeSitterCalls(rel, content, fileSymbols, symbolByName, resolution) ?? extractGenericCalls(rel, content, fileSymbols, symbolByName, resolution);
         calls.push(...fileCalls.slice(0, Math.max(0, MAX_CODE_GRAPH_CALLS - calls.length)));
         routes.push(...extractRoutes(rel, content, fileSymbols));
         tests.push(...extractTests(rel, content, fileSymbols, fileImports));
@@ -5496,7 +6002,10 @@ function buildIndexes(projectDir) {
 }
 function indexProjectDetailed(projectDir, options = {}) {
     ensureMemoryDirs(projectDir);
-    const policy = installAgentPolicy(projectDir);
+    // Indexing must never write agent-policy files into the user's repo.
+    // Policy installation is explicit: `kage policy`, `kage init --with-policy`,
+    // or the kage_install_policy MCP tool.
+    const existingPolicyPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const migrated = migrateLegacyMarkdown(projectDir);
     const overview = createRepoOverviewPacket(projectDir);
     if (overview)
@@ -5512,7 +6021,7 @@ function indexProjectDetailed(projectDir, options = {}) {
             packets: loadPacketsFromDir(packetsDir(projectDir)).length,
             migrated,
             indexes: indexes.map((path) => (0, node_path_1.relative)(projectDir, path)),
-            policyPath: (0, node_path_1.relative)(projectDir, policy.path),
+            policyPath: (0, node_fs_1.existsSync)(existingPolicyPath) ? (0, node_path_1.relative)(projectDir, existingPolicyPath) : undefined,
         },
         codeGraph: built?.codeGraph,
         knowledgeGraph: built?.knowledgeGraph,
@@ -6728,8 +7237,17 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
             }))
             : undefined,
     };
-    if (inputs.trackAccess !== false)
+    result.value_receipt = {
+        tokens_saved: scored.length ? recallTokensSaved(projectDir, result.results, result.context_block) : 0,
+        stale_withheld: suppressed.length,
+    };
+    if (inputs.trackAccess !== false) {
         recordRecallAccess(projectDir, result.results);
+        recordValueEvents(projectDir, [
+            ...suppressed.map((entry) => ({ kind: "stale_withheld", packet_title: entry.title })),
+            ...(scored.length ? [{ kind: "recall_served", tokens_saved: result.value_receipt.tokens_saved }] : []),
+        ]);
+    }
     return result;
 }
 function recall(projectDir, query, limit = 5, explain = false, inputs = {}) {
@@ -6782,20 +7300,35 @@ function boostTermScore(boost, term) {
 function queryCodeGraph(projectDir, query, limit = 10, graph) {
     graph = graph ?? readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const terms = tokenize(query);
+    // Implementation queries must rank core source above tests/examples/benchmarks.
+    // Without this, path-term matches let `test/` and `examples/` swamp `lib/` —
+    // the exact inversion that made code-graph answers lose to grep.
+    const testIntent = terms.some((term) => ["test", "tests", "spec", "coverage", "fixture"].includes(term));
+    const exampleIntent = terms.some((term) => ["example", "examples", "sample", "demo"].includes(term));
+    const pathKindWeight = (path) => {
+        const kind = codeFileKind(path);
+        if (kind === "test")
+            return testIntent ? 1.15 : 0.45;
+        if (/(^|\/)(examples?|samples?|demos?|fixtures?|benchmarks?)\//.test(path))
+            return exampleIntent ? 1.1 : 0.5;
+        if (kind === "source")
+            return 1.0;
+        return 0.85; // config/manifest/doc: useful, but below implementation
+    };
     const files = graph.files
-        .map((file) => ({ file, score: scoreText(terms, `${file.path} ${file.kind} ${file.language} ${file.parser}`, [file.path, file.language]) }))
+        .map((file) => ({ file, score: scoreText(terms, `${file.path} ${file.kind} ${file.language} ${file.parser}`, [file.path, file.language]) * pathKindWeight(file.path) }))
         .filter((entry) => entry.score > 0)
         .sort((a, b) => b.score - a.score || a.file.path.localeCompare(b.file.path))
         .slice(0, limit)
         .map((entry) => entry.file);
     const symbols = graph.symbols
-        .map((symbol) => ({ symbol, score: scoreText(terms, `${symbol.name} ${symbol.kind} ${symbol.path} ${symbol.language} ${symbol.signature}`, [symbol.name, symbol.path]) }))
+        .map((symbol) => ({ symbol, score: scoreText(terms, `${symbol.name} ${symbol.kind} ${symbol.path} ${symbol.language} ${symbol.signature}`, [symbol.name, symbol.path]) * pathKindWeight(symbol.path) }))
         .filter((entry) => entry.score > 0)
         .sort((a, b) => b.score - a.score || a.symbol.path.localeCompare(b.symbol.path) || a.symbol.line - b.symbol.line)
         .slice(0, limit)
         .map((entry) => entry.symbol);
     const routes = graph.routes
-        .map((route) => ({ route, score: scoreText(terms, `route routes endpoint api handler ${route.method} ${route.path} ${route.file_path} ${route.framework}`, [route.path, route.file_path]) }))
+        .map((route) => ({ route, score: scoreText(terms, `route routes endpoint api handler ${route.method} ${route.path} ${route.file_path} ${route.framework}`, [route.path, route.file_path]) * pathKindWeight(route.file_path) }))
         .filter((entry) => entry.score > 0)
         .sort((a, b) => b.score - a.score || a.route.path.localeCompare(b.route.path))
         .slice(0, limit)
@@ -6822,9 +7355,57 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         .slice(0, limit);
     const symbolIds = new Set(symbols.map((symbol) => symbol.id));
     const symbolNameById = new Map(graph.symbols.map((symbol) => [symbol.id, `${symbol.name} (${symbol.path}:${symbol.line})`]));
-    const calls = graph.calls
-        .filter((call) => symbolIds.has(call.to_symbol) || Boolean(call.from_symbol && symbolIds.has(call.from_symbol)))
-        .slice(0, limit);
+    // Caller-intent queries ("who calls X", "which functions call X", "usages of X")
+    // must be answered from the call-edge index — the one question a call graph is
+    // uniquely qualified to answer. Keyword scoring alone returns definitions instead.
+    const callerIntent = /\b(?:who|what|which)\b[^?]*\bcalls?\b|\bcallers?\s+(?:of|for)\b|\bcall\s*sites?\b|\busages?\s+of\b|\bwhere\s+is\b.+\b(?:called|invoked|used)\b/i.test(query);
+    const intentStopwords = new Set(["call", "calls", "called", "caller", "callers", "calling", "invoked", "invoke", "usage", "usages", "site", "sites", "who", "what", "which", "where", "function", "functions", "method", "methods", "file", "files", "of", "for", "is", "the", "in", "are", "do", "does"]);
+    let callerTargets = [];
+    if (callerIntent) {
+        const byName = new Map();
+        for (const symbol of graph.symbols) {
+            const key = symbol.name.toLowerCase();
+            const bucket = byName.get(key);
+            if (bucket)
+                bucket.push(symbol);
+            else
+                byName.set(key, [symbol]);
+        }
+        const rawWords = query.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? [];
+        const seen = new Set();
+        for (const word of rawWords) {
+            const key = word.toLowerCase();
+            if (seen.has(key) || intentStopwords.has(key))
+                continue;
+            const matches = byName.get(key);
+            if (!matches)
+                continue;
+            seen.add(key);
+            callerTargets.push(...matches.slice(0, 4));
+        }
+        callerTargets = callerTargets.slice(0, 8);
+    }
+    const callerTargetIds = new Set(callerTargets.map((symbol) => symbol.id));
+    const callerTargetNames = new Set(callerTargets.map((symbol) => symbol.name.toLowerCase()));
+    // Edges below 0.5 are name-only guesses; presenting them as callers destroys
+    // trust in the one answer a call graph exists to give.
+    const callerEdges = callerTargetIds.size
+        ? graph.calls
+            .filter((call) => call.confidence >= 0.5)
+            .filter((call) => callerTargetIds.has(call.to_symbol) || callerTargetNames.has((symbolNameById.get(call.to_symbol) ?? call.to_symbol).split(" ")[0]?.toLowerCase() ?? ""))
+            .slice(0, 20)
+        : [];
+    const calls = callerEdges.length
+        ? callerEdges
+        : graph.calls
+            .filter((call) => call.confidence >= 0.5)
+            .filter((call) => symbolIds.has(call.to_symbol) || Boolean(call.from_symbol && symbolIds.has(call.from_symbol)))
+            .slice(0, limit);
+    // Value ledger: a caller-intent query answered from the call-edge index is a
+    // grep/agent round-trip the user did not pay for. Only repos that already opted
+    // into Kage memory get the write — a bare code-graph query stays read-only.
+    if (callerEdges.length && (0, node_fs_1.existsSync)(memoryRoot(projectDir)))
+        recordValueEvent(projectDir, { kind: "caller_answered" });
     const structuralIndex = readCurrentStructuralIndex(projectDir);
     const graphPaths = new Set(graph.files.map((file) => file.path));
     const graphSymbolIds = new Set(graph.symbols.map((symbol) => symbol.id));
@@ -6843,7 +7424,7 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         ? structuralIndex.symbols
             .map((symbol) => ({
             symbol,
-            score: scoreText(terms, `${symbol.name} ${symbol.kind} ${symbol.path} ${symbol.language} ${symbol.parser}`, [symbol.name, symbol.path]),
+            score: scoreText(terms, `${symbol.name} ${symbol.kind} ${symbol.path} ${symbol.language} ${symbol.parser}`, [symbol.name, symbol.path]) * pathKindWeight(symbol.path),
         }))
             .filter((entry) => entry.score > 0 && !graphSymbolIds.has(entry.symbol.id))
             .sort((a, b) => b.score - a.score || a.symbol.path.localeCompare(b.symbol.path) || a.symbol.line - b.symbol.line)
@@ -6870,25 +7451,39 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         "",
         `Query: ${query}`,
         "",
+        ...(callerEdges.length
+            ? [
+                "## Callers (from the call-edge index)",
+                ...callerTargets.map((symbol) => `target: ${symbol.kind} ${symbol.name} defined in ${symbol.path}:${symbol.line}`),
+                ...callerEdges.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line}`),
+                "",
+            ]
+            : []),
         files.length || symbols.length || routes.length || tests.length ? "## Code Facts" : "No related source-derived code facts found.",
-        ...routes.map((route, index) => `${index + 1}. [route] ${route.method} ${route.path} in ${route.file_path}:${route.line}`),
+        // Compaction: when symbol hits are strong, supporting facts (routes/tests/files/
+        // imports) shrink to a few lines each. The block is agent fuel — every line that
+        // doesn't help locate the answer is tokens the agent pays for nothing.
         ...symbols.map((symbol, index) => `${index + 1}. [symbol] ${symbol.kind} ${symbol.name} in ${symbol.path}:${symbol.line} (${symbol.language}, ${symbol.parser})`),
-        ...tests.map((test, index) => `${index + 1}. [test] ${test.title} in ${test.test_path}:${test.line}${test.covers_symbol ? ` covers ${test.covers_symbol}` : ""}`),
-        ...files.slice(0, 5).map((file, index) => `${index + 1}. [file] ${file.path} (${file.kind}, ${file.language}, ${file.parser})`),
-        structuralFiles.length || structuralSymbols.length || structuralEdges.length ? "" : "",
-        structuralFiles.length || structuralSymbols.length || structuralEdges.length ? "## Structural Index" : "",
-        ...structuralSymbols.map((symbol, index) => `${index + 1}. [structural symbol] ${symbol.kind} ${symbol.name} in ${symbol.path}:${symbol.line} (${symbol.language}, ${symbol.parser})`),
-        ...structuralFiles.slice(0, 5).map((file, index) => `${index + 1}. [structural file] ${file.path} (${file.kind}, ${file.language}, ${file.extraction})`),
+        ...routes.slice(0, symbols.length >= 3 ? 3 : limit).map((route, index) => `${index + 1}. [route] ${route.method} ${route.path} in ${route.file_path}:${route.line}`),
+        ...tests.slice(0, symbols.length >= 3 ? 2 : limit).map((test, index) => `${index + 1}. [test] ${test.title} in ${test.test_path}:${test.line}${test.covers_symbol ? ` covers ${test.covers_symbol}` : ""}`),
+        ...files.slice(0, 3).map((file, index) => `${index + 1}. [file] ${file.path} (${file.kind}, ${file.language}, ${file.parser})`),
+        structuralFiles.length || structuralSymbols.length ? "" : "",
+        structuralFiles.length || structuralSymbols.length ? "## Structural Index" : "",
+        ...structuralSymbols.slice(0, symbols.length >= 3 ? 3 : limit).map((symbol, index) => `${index + 1}. [structural symbol] ${symbol.kind} ${symbol.name} in ${symbol.path}:${symbol.line} (${symbol.language}, ${symbol.parser})`),
+        ...structuralFiles.slice(0, 3).map((file, index) => `${index + 1}. [structural file] ${file.path} (${file.kind}, ${file.language}, ${file.extraction})`),
         ...structuralEdges
             .filter((edge) => edge.relation === "imports")
-            .slice(0, 5)
+            .slice(0, symbols.length >= 3 ? 2 : 5)
             .map((edge, index) => `${index + 1}. [structural import] ${edge.source_file}${edge.source_location ? `:${edge.source_location.replace(/^L/, "")}` : ""} -> ${edge.target} (${edge.confidence})`),
         imports.length ? "" : "",
         imports.length ? "## Imports" : "",
-        ...imports.map(({ item }, index) => `${index + 1}. ${item.from_path}:${item.line} ${item.kind} ${item.specifier}${item.to_path ? ` -> ${item.to_path}` : ""}`),
-        calls.length ? "" : "",
-        calls.length ? "## Calls" : "",
-        ...calls.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line} (${call.resolution}, confidence ${call.confidence.toFixed(2)})`),
+        ...imports.slice(0, symbols.length >= 3 ? 3 : limit).map(({ item }, index) => `${index + 1}. ${item.from_path}:${item.line} ${item.kind} ${item.specifier}${item.to_path ? ` -> ${item.to_path}` : ""}`),
+        // When caller intent was answered above, don't repeat the same edges here.
+        calls.length && !callerEdges.length ? "" : "",
+        calls.length && !callerEdges.length ? "## Calls" : "",
+        ...(callerEdges.length
+            ? []
+            : calls.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line} (${call.resolution}, confidence ${call.confidence.toFixed(2)})`)),
     ];
     return {
         query,
@@ -7703,6 +8298,377 @@ function kageCleanupCandidates(projectDir) {
         summary: `${candidates.length} conservative cleanup candidate(s), ${skippedEntryPoints.length} entrypoint-like source file(s) skipped, ${skippedRuntimeReferences.length} runtime reference(s) skipped.`,
     };
 }
+const TRUTH_REPORT_MAX_FINDINGS = 12;
+const TRUTH_REPORT_AI_ERA_DAYS = 120;
+// Symbol names too generic to mean "two teams built the same thing".
+const TRUTH_COMMON_SYMBOL_NAMES = new Set([
+    "main", "init", "run", "setup", "start", "stop", "open", "close", "create", "destroy",
+    "constructor", "tostring", "render", "handler", "handle", "execute", "default", "index",
+    "build", "parse", "load", "save", "update", "delete", "remove", "test", "validate",
+    "format", "process", "next", "send", "write", "read", "config", "helper", "util",
+]);
+function truthExcludedPath(path) {
+    return /(^|\/)(tests?|__tests__|specs?|examples?|fixtures?|benchmarks?|mocks?|__mocks__|vendor|node_modules|dist|build)\//i.test(path)
+        || /\.(test|spec)\.[^.]+$/i.test(path)
+        || /(^|\/)test[^/]*\.[^.]+$/i.test(path);
+}
+const TRUTH_DOC_PATH_EXTENSIONS = "ts|tsx|js|jsx|mjs|cjs|json|md|yml|yaml|toml|py|rb|go|rs|java|kt|sh|bash|css|scss|html|sql|proto|graphql|c|h|cpp|hpp|cs|txt";
+function truthDocPathCandidates(line) {
+    const candidates = new Set();
+    for (const match of line.matchAll(/`([^`\n]+)`/g)) {
+        const token = match[1].trim();
+        if (new RegExp(`^(?:\\./)?[\\w.-]+(?:/[\\w.-]+)+\\.(?:${TRUTH_DOC_PATH_EXTENSIONS})$`).test(token))
+            candidates.add(token.replace(/^\.\//, ""));
+    }
+    for (const match of line.matchAll(new RegExp(`(?:^|[\\s("'\\[])((?:\\./)?[\\w.-]+(?:/[\\w.-]+)+\\.(?:${TRUTH_DOC_PATH_EXTENSIONS}))(?=$|[\\s)"'\\],.:;])`, "g"))) {
+        candidates.add(match[1].replace(/^\.\//, ""));
+    }
+    return [...candidates].filter((candidate) => !/[*<>{}$\\]/.test(candidate)
+        && !candidate.startsWith("http")
+        && !candidate.includes("node_modules")
+        && !candidate.startsWith(".agent_memory"));
+}
+function truthReport(projectDir) {
+    const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
+    const warnings = [];
+    const fileByPath = new Map(graph.files.map((file) => [file.path, file]));
+    const sourceFiles = graph.files.filter((file) => file.kind === "source" && !truthExcludedPath(file.path));
+    // Single git pass: per-file distinct authors, total commit count, newest commit epoch.
+    const hasGit = Boolean(gitHead(projectDir));
+    if (!hasGit)
+        warnings.push("Git history is unavailable; bus-factor, churn, and recency signals are skipped.");
+    const shallowGit = hasGit && readGit(projectDir, ["rev-parse", "--is-shallow-repository"]) === "true";
+    if (shallowGit)
+        warnings.push("Git history is shallow (partial clone); churn, bus-factor, and recency findings undercount reality.");
+    const fileAuthors = new Map();
+    const fileCommits = new Map();
+    const fileNewestEpoch = new Map();
+    if (hasGit) {
+        const raw = readGit(projectDir, ["log", "--no-renames", "--format=__KAGE_SCAN__%x1f%ae%x1f%ct", "--name-only"]) ?? "";
+        // Resolve the repo->project prefix once; gitPathToProjectRelative spawns git per call,
+        // which is far too slow for a full-history name-only walk.
+        const projectPrefix = readGit(projectDir, ["rev-parse", "--show-prefix"])?.replace(/\\/g, "/").replace(/\/+$/, "") ?? "";
+        let author = "";
+        let epoch = 0;
+        for (const rawLine of raw.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            if (line.startsWith("__KAGE_SCAN__")) {
+                const parts = line.split("\x1f");
+                author = (parts[1] ?? "").toLowerCase();
+                epoch = Number(parts[2] ?? 0) || 0;
+                continue;
+            }
+            if (!author)
+                continue;
+            const normalized = line.replace(/\\/g, "/").replace(/^\/+/, "");
+            const path = projectPrefix && normalized.startsWith(`${projectPrefix}/`) ? normalized.slice(projectPrefix.length + 1) : normalized;
+            if (!fileByPath.has(path))
+                continue;
+            const authors = fileAuthors.get(path) ?? new Set();
+            authors.add(author);
+            fileAuthors.set(path, authors);
+            fileCommits.set(path, (fileCommits.get(path) ?? 0) + 1);
+            // git log is newest-first, so the first sighting is the newest commit touching the file.
+            if (!fileNewestEpoch.has(path))
+                fileNewestEpoch.set(path, epoch);
+        }
+    }
+    // Centrality: import + call edges touching the file.
+    const centrality = new Map();
+    const bumpCentrality = (path) => {
+        if (!path || !fileByPath.has(path))
+            return;
+        centrality.set(path, (centrality.get(path) ?? 0) + 1);
+    };
+    for (const edge of graph.imports) {
+        bumpCentrality(edge.from_path);
+        bumpCentrality(edge.to_path);
+    }
+    for (const call of graph.calls)
+        bumpCentrality(call.path);
+    const nowEpoch = Math.floor(Date.now() / 1000);
+    const aiEraCutoff = nowEpoch - TRUTH_REPORT_AI_ERA_DAYS * 24 * 3600;
+    // 1a. Duplicate implementations: same-name symbols spread across directories.
+    const symbolsByName = new Map();
+    for (const symbol of graph.symbols) {
+        if (!["function", "class", "method"].includes(symbol.kind))
+            continue;
+        if (symbol.name.length < 4 || TRUTH_COMMON_SYMBOL_NAMES.has(symbol.name.toLowerCase()))
+            continue;
+        if (truthExcludedPath(symbol.path) || fileByPath.get(symbol.path)?.kind !== "source")
+            continue;
+        const list = symbolsByName.get(symbol.name.toLowerCase()) ?? [];
+        list.push(symbol);
+        symbolsByName.set(symbol.name.toLowerCase(), list);
+    }
+    const duplicateFindings = [];
+    for (const [, members] of symbolsByName) {
+        const dirs = new Set(members.map((member) => (0, node_path_1.dirname)(member.path)));
+        const paths = new Set(members.map((member) => member.path));
+        if (dirs.size < 2 || paths.size < 2)
+            continue;
+        const signatureCounts = new Map();
+        for (const member of members) {
+            const normalized = member.signature.replace(/\s+/g, "");
+            signatureCounts.set(normalized, (signatureCounts.get(normalized) ?? 0) + 1);
+        }
+        const signatureMatch = [...signatureCounts.values()].some((count) => count >= 2);
+        const newestEpoch = Math.max(0, ...members.map((member) => fileNewestEpoch.get(member.path) ?? 0));
+        const recent = hasGit && newestEpoch > aiEraCutoff;
+        duplicateFindings.push({
+            kind: "duplicate_cluster",
+            title: `${members[0].name} — ${paths.size} implementations across ${dirs.size} directories${recent ? " [recent, likely AI-era]" : ""}`,
+            detail: signatureMatch
+                ? "Same name AND near-identical signature: almost certainly parallel implementations of the same idea."
+                : "Same name in unrelated directories: agents and humans may be solving the same problem twice.",
+            evidence: members.slice(0, 5).map((member) => `${member.path}:${member.line}  ${member.kind} ${member.signature.slice(0, 80)}`),
+            surprise: Math.min(100, 45 + paths.size * 8 + (signatureMatch ? 15 : 0) + (recent ? 20 : 0)),
+        });
+    }
+    duplicateFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // 1b. Ghost knowledge: exported symbols nothing in this repo calls or imports by name.
+    const referenced = new Set();
+    for (const call of graph.calls)
+        referenced.add(call.to_symbol);
+    for (const edge of graph.imports)
+        for (const name of edge.imported)
+            referenced.add(name);
+    for (const route of graph.routes)
+        if (route.handler_symbol)
+            referenced.add(route.handler_symbol);
+    for (const test of graph.tests)
+        if (test.covers_symbol)
+            referenced.add(test.covers_symbol);
+    const ghostCandidates = [];
+    for (const symbol of graph.symbols) {
+        if (!symbol.export || !["function", "class", "method"].includes(symbol.kind))
+            continue;
+        if (truthExcludedPath(symbol.path) || isEntrypointLike(symbol.path))
+            continue;
+        if (fileByPath.get(symbol.path)?.kind !== "source")
+            continue;
+        if (referenced.has(symbol.id) || referenced.has(symbol.name))
+            continue;
+        ghostCandidates.push(symbol);
+    }
+    // Graph edges miss dynamic/property references, so a ghost claim must survive a raw-text
+    // check: the name may appear nowhere in the repo outside its own file.
+    const truthTextCache = new Map();
+    const truthFileText = (path) => {
+        const cached = truthTextCache.get(path);
+        if (cached !== undefined)
+            return cached;
+        const file = fileByPath.get(path);
+        const text = file && file.size_bytes <= 512 * 1024 ? safeReadText((0, node_path_1.join)(projectDir, path)) ?? "" : "";
+        truthTextCache.set(path, text);
+        return text;
+    };
+    const ghostFindings = ghostCandidates.slice(0, 60).flatMap((symbol) => {
+        const namePattern = new RegExp(`(^|[^A-Za-z0-9_$])${escapeRegex(symbol.name)}([^A-Za-z0-9_$]|$)`);
+        const mentionedElsewhere = graph.files.some((file) => file.path !== symbol.path
+            && (file.kind === "source" || file.kind === "test")
+            && namePattern.test(truthFileText(file.path)));
+        if (mentionedElsewhere)
+            return [];
+        const fileCentrality = centrality.get(symbol.path) ?? 0;
+        return [{
+                kind: "ghost_export",
+                title: `${symbol.name} — exported, never called`,
+                detail: "No call edge, no import, and the name appears in no other file. Dead code, or knowledge nobody wired in.",
+                evidence: [`${symbol.path}:${symbol.line}  ${symbol.kind} ${symbol.signature.slice(0, 80)}`],
+                surprise: Math.min(100, 35 + Math.min(30, fileCentrality)),
+            }];
+    });
+    ghostFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // 1c. Knowledge concentration: single-author files ranked by graph centrality.
+    const busFindings = [];
+    let singleAuthorCount = 0;
+    if (hasGit) {
+        for (const file of sourceFiles) {
+            const authors = fileAuthors.get(file.path);
+            if (!authors || authors.size !== 1)
+                continue;
+            singleAuthorCount += 1;
+            const commits = fileCommits.get(file.path) ?? 0;
+            const fileCentrality = centrality.get(file.path) ?? 0;
+            if (commits < 2 || fileCentrality < 1)
+                continue;
+            busFindings.push({
+                kind: "bus_factor",
+                title: `${file.path} — bus factor 1`,
+                detail: `Every one of ${commits} commit(s) came from ${[...authors][0]}. ${fileCentrality} graph edge(s) depend on a file only one person has ever touched.`,
+                evidence: [`${file.path}:1  sole author ${[...authors][0]}, ${commits} commit(s), centrality ${fileCentrality}`],
+                surprise: Math.min(100, 30 + Math.min(40, fileCentrality) + Math.min(20, commits)),
+            });
+        }
+        if (!shallowGit && sourceFiles.length >= 5 && singleAuthorCount >= sourceFiles.length * 0.9) {
+            warnings.push("Nearly every file has a single author; this looks like a solo-maintained repo, so bus-factor-1 is the baseline, not the exception.");
+        }
+    }
+    busFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // 1d. Knowledge void: high churn x high centrality, zero memory packets, zero doc mentions.
+    const packets = loadApprovedPackets(projectDir);
+    const packetCovers = (path) => packets.some((packet) => packet.paths.some((cited) => {
+        const normalized = cited.replace(/\/+$/, "");
+        return normalized === path || path.startsWith(`${normalized}/`) || normalized.startsWith(`${path}/`);
+    }));
+    const docFiles = [];
+    for (const candidate of ["README.md", "readme.md", "Readme.md"]) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, candidate))) {
+            docFiles.push(candidate);
+            break;
+        }
+    }
+    const docsDir = (0, node_path_1.join)(projectDir, "docs");
+    if (safeStat(docsDir)?.isDirectory()) {
+        for (const name of (0, node_fs_1.readdirSync)(docsDir).filter((entry) => entry.endsWith(".md")).sort().slice(0, 20)) {
+            docFiles.push((0, node_path_1.join)("docs", name));
+        }
+    }
+    const docLines = [];
+    for (const doc of docFiles) {
+        const text = safeReadText((0, node_path_1.join)(projectDir, doc));
+        if (!text)
+            continue;
+        text.split(/\r?\n/).forEach((line, index) => docLines.push({ doc, line: index + 1, text: line }));
+    }
+    const docsText = docLines.map((entry) => entry.text).join("\n");
+    const voidFindings = [];
+    if (hasGit) {
+        for (const file of sourceFiles) {
+            const commits = fileCommits.get(file.path) ?? 0;
+            const fileCentrality = centrality.get(file.path) ?? 0;
+            if (commits < 5 || fileCentrality < 3)
+                continue;
+            if (packetCovers(file.path) || docsText.includes(file.path))
+                continue;
+            voidFindings.push({
+                kind: "knowledge_void",
+                title: `${file.path} — knowledge void`,
+                detail: `${commits} commits of accumulated decisions, ${fileCentrality} graph edge(s) depending on it — and zero memory packets or doc mentions. Agents and new hires fly blind here.`,
+                evidence: [`${file.path}:1  churn ${commits} x centrality ${fileCentrality}, memory packets citing it: 0`],
+                surprise: Math.min(100, 25 + Math.min(45, Math.round(Math.sqrt(commits * fileCentrality))) + Math.min(20, fileCentrality)),
+            });
+        }
+    }
+    voidFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // 2. Doc-truth: checkable claims in README/docs vs reality.
+    const docLieFindings = [];
+    if (docLines.length) {
+        const seenLies = new Set();
+        const packageJsonText = safeReadText((0, node_path_1.join)(projectDir, "package.json"));
+        let scripts = {};
+        let binNames = [];
+        if (packageJsonText) {
+            try {
+                const parsed = JSON.parse(packageJsonText);
+                scripts = parsed.scripts ?? {};
+                binNames = typeof parsed.bin === "string" ? [parsed.name ?? ""].filter(Boolean) : Object.keys(parsed.bin ?? {});
+            }
+            catch {
+                warnings.push("package.json could not be parsed; npm-script doc checks skipped.");
+            }
+        }
+        // CLI claims are only checkable when there is obvious CLI source to check them against.
+        const cliSourceText = binNames.length
+            ? graph.files
+                .filter((file) => file.kind === "source" && (/(^|\/)(cli|bin|commands?)[^/]*\.[^.]+$/i.test(file.path) || /(^|\/)(cli|bin|commands)\//i.test(file.path)))
+                .slice(0, 30)
+                .map((file) => safeReadText((0, node_path_1.join)(projectDir, file.path)) ?? "")
+                .join("\n")
+            : "";
+        for (const entry of docLines) {
+            for (const candidate of truthDocPathCandidates(entry.text)) {
+                const key = `path:${candidate}`;
+                if (seenLies.has(key) || (0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, candidate)))
+                    continue;
+                seenLies.add(key);
+                docLieFindings.push({
+                    kind: "doc_lie",
+                    title: `${entry.doc}:${entry.line} cites ${candidate} — reality: file does not exist`,
+                    detail: `"${entry.text.trim().slice(0, 100)}"`,
+                    evidence: [`${entry.doc}:${entry.line}`],
+                    surprise: 70,
+                });
+            }
+            if (packageJsonText && Object.keys(scripts).length) {
+                for (const match of entry.text.matchAll(/\bnpm run ([A-Za-z0-9:_-]+)/g)) {
+                    const script = match[1];
+                    const key = `script:${script}`;
+                    if (seenLies.has(key) || scripts[script])
+                        continue;
+                    seenLies.add(key);
+                    docLieFindings.push({
+                        kind: "doc_lie",
+                        title: `${entry.doc}:${entry.line} says \`npm run ${script}\` — reality: no "${script}" script in package.json`,
+                        detail: `"${entry.text.trim().slice(0, 100)}"`,
+                        evidence: [`${entry.doc}:${entry.line}`],
+                        surprise: 75,
+                    });
+                }
+            }
+            if (cliSourceText) {
+                for (const bin of binNames) {
+                    for (const match of entry.text.matchAll(new RegExp(`\`${bin} ([a-z][a-z0-9-]+)`, "g"))) {
+                        const subcommand = match[1];
+                        const key = `cli:${subcommand}`;
+                        if (seenLies.has(key) || cliSourceText.includes(`"${subcommand}"`) || cliSourceText.includes(`'${subcommand}'`))
+                            continue;
+                        seenLies.add(key);
+                        docLieFindings.push({
+                            kind: "doc_lie",
+                            title: `${entry.doc}:${entry.line} documents \`${bin} ${subcommand}\` — reality: no such command in CLI source`,
+                            detail: `"${entry.text.trim().slice(0, 100)}"`,
+                            evidence: [`${entry.doc}:${entry.line}`],
+                            surprise: 80,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    docLieFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // Cap per category so one noisy category cannot drown the report, then rank globally.
+    const findings = [
+        ...duplicateFindings.slice(0, 4),
+        ...ghostFindings.slice(0, 4),
+        ...busFindings.slice(0, 4),
+        ...voidFindings.slice(0, 4),
+        ...docLieFindings.slice(0, 4),
+    ].sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title)).slice(0, TRUTH_REPORT_MAX_FINDINGS);
+    const headlineParts = [
+        `${duplicateFindings.length} duplicate cluster${duplicateFindings.length === 1 ? "" : "s"}`,
+        `${ghostFindings.length} ghost export${ghostFindings.length === 1 ? "" : "s"}`,
+        `${busFindings.length} bus-factor-1 hot file${busFindings.length === 1 ? "" : "s"}`,
+        `${voidFindings.length} knowledge void${voidFindings.length === 1 ? "" : "s"}`,
+        ...(docLines.length ? [`${docLieFindings.length} doc lie${docLieFindings.length === 1 ? "" : "s"}`] : []),
+    ];
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        totals: {
+            files_scanned: graph.files.length,
+            symbols_scanned: graph.symbols.length,
+            duplicate_clusters: duplicateFindings.length,
+            ghost_exports: ghostFindings.length,
+            bus_factor_files: busFindings.length,
+            knowledge_voids: voidFindings.length,
+            doc_lies: docLieFindings.length,
+            docs_scanned: docFiles.length,
+        },
+        headline: headlineParts.join(" · "),
+        findings,
+        warnings,
+        next_actions: [
+            "kage init --project <dir>     create repo memory so this knowledge stops living in one head",
+            "kage learn --project <dir> --learning \"...\" --paths <file>     capture what only your team knows",
+            "kage viewer --project <dir>     watch the void close",
+        ],
+    };
+}
 function kageReviewerSuggestions(projectDir, targets = [], changedFiles = []) {
     const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const graphPaths = new Set(graph.files.map((file) => file.path));
@@ -11232,8 +12198,18 @@ function setupAgent(agent, projectDir, options = {}) {
     if (!exports.SETUP_AGENTS.includes(agent))
         throw new Error(`Unsupported agent: ${agent}`);
     const serverPath = options.serverPath ?? (0, node_path_1.join)(__dirname, "index.js");
-    const serverCommand = "node";
-    const serverArgs = [serverPath];
+    // An npx cache path (~/.npm/_npx/<hash>/...) is ephemeral — npx prunes it and
+    // the configured MCP server silently dies. Point such configs at the package
+    // runner instead so they survive cache eviction.
+    const ephemeralNpxPath = serverPath.includes(`${node_path_1.sep}_npx${node_path_1.sep}`);
+    const serverCommand = ephemeralNpxPath ? "npx" : "node";
+    const serverArgs = ephemeralNpxPath ? ["-y", "@kage-core/kage-graph-mcp"] : [serverPath];
+    if (options.write) {
+        // `setup <agent> --write` is an explicit wiring action: the harness policy
+        // (AGENTS.md / CLAUDE.md) is part of that wiring, unlike plain init/index
+        // which must not touch repo-visible files.
+        installAgentPolicy(projectDir);
+    }
     const home = options.homeDir ?? process.env.HOME ?? "~";
     const universal = JSON.stringify({ mcpServers: { kage: { command: serverCommand, args: serverArgs } } }, null, 2);
     const result = {
@@ -11256,7 +12232,7 @@ function setupAgent(agent, projectDir, options = {}) {
     };
     if (agent === "codex") {
         const path = (0, node_path_1.join)(home, ".codex", "config.toml");
-        const config = `[mcp_servers.kage]\ncommand = "node"\nargs = ["${serverPath}"]\n`;
+        const config = `[mcp_servers.kage]\ncommand = "${serverCommand}"\nargs = [${serverArgs.map((arg) => JSON.stringify(arg)).join(", ")}]\n`;
         setSnippet(path, config, ["Add this block to ~/.codex/config.toml, then restart Codex.", "Run `kage init --project <repo>` inside each repo."], true);
         if (options.write) {
             ensureDir((0, node_path_1.dirname)(path));
@@ -12610,6 +13586,71 @@ function prSummarize(projectDir) {
         warnings,
     };
 }
+// Working-tree changes vs HEAD: unstaged + staged + untracked. Outside a git
+// repo (or before the first commit) this degrades to "nothing changed".
+function workingTreeChangedFiles(projectDir) {
+    const sections = [
+        readGit(projectDir, ["diff", "--name-only", "HEAD"]),
+        readGit(projectDir, ["diff", "--name-only", "--cached"]),
+        readGit(projectDir, ["ls-files", "--others", "--exclude-standard"]),
+    ];
+    return unique(sections
+        .filter((section) => Boolean(section))
+        .flatMap((section) => section.split(/\r?\n/))
+        .map((path) => path.trim())
+        .filter(Boolean)
+        .map((path) => gitPathToProjectRelative(projectDir, path))
+        .filter((path) => Boolean(path)));
+}
+function staleCatch(projectDir, changedFiles) {
+    const changed = new Set((changedFiles?.length ? changedFiles : workingTreeChangedFiles(projectDir))
+        .map((path) => path.replace(/\\/g, "/").replace(/^\/+/, ""))
+        .filter(Boolean));
+    const invalidated = [];
+    if (changed.size) {
+        const fpCache = new Map();
+        for (const packet of loadPacketsFromDir(packetsDir(projectDir))) {
+            if (packet.status !== "approved" && packet.status !== "pending")
+                continue;
+            for (const stored of packetStoredPathFingerprints(packet)) {
+                if (!changed.has(stored.path) || isGroundingIgnored(projectDir, stored.path))
+                    continue;
+                const current = memoryPathFingerprint(projectDir, stored.path, fpCache);
+                if (current === null) {
+                    invalidated.push({ packet_id: packet.id, packet_title: packet.title, cited_path: stored.path, reason: "cited file was deleted" });
+                }
+                else if (current.sha256 !== stored.sha256) {
+                    invalidated.push({ packet_id: packet.id, packet_title: packet.title, cited_path: stored.path, reason: "content changed since this memory was verified" });
+                }
+            }
+        }
+    }
+    if (invalidated.length) {
+        recordValueEvents(projectDir, invalidated.map((item) => ({ kind: "stale_caught", packet_title: item.packet_title })));
+    }
+    const summary = invalidated.length
+        ? `Your changes invalidated ${invalidated.length} team ${invalidated.length === 1 ? "memory" : "memories"}.`
+        : "No team memory invalidated by this change.";
+    return {
+        ok: true,
+        project_dir: (0, node_path_1.resolve)(projectDir),
+        changed_files: [...changed].sort(),
+        invalidated,
+        summary,
+    };
+}
+// Shared human rendering for the stale-catch moment (CLI pr check, kage
+// staleguard, and the kage_pr_check MCP tool all print the exact same lines).
+function formatStaleCatch(result) {
+    if (!result.invalidated.length)
+        return ["✓ No team memory invalidated by this change"];
+    const count = result.invalidated.length;
+    return [
+        `⚠ Your changes invalidated ${count} team ${count === 1 ? "memory" : "memories"}:`,
+        ...result.invalidated.map((item) => `  • ${item.packet_title} — cites ${item.cited_path} (${item.reason})`),
+        "  fix: kage learn (update) | kage supersede --packet <id>",
+    ];
+}
 function prCheck(projectDir) {
     ensureMemoryDirs(projectDir);
     const overlay = buildBranchOverlay(projectDir);
@@ -12976,150 +14017,6 @@ function recallFromPackets(query, packets, limit, label) {
         results: scored,
     };
 }
-function orgStatus(projectDir, org) {
-    ensureDir(orgInboxDir(projectDir, org));
-    ensureDir(orgPacketsDir(projectDir, org));
-    ensureDir(orgRejectedDir(projectDir, org));
-    return {
-        org: slugify(org),
-        path: orgRootDir(projectDir, org),
-        inbox: loadOrgInboxPackets(projectDir, org).length,
-        approved: loadOrgApprovedPackets(projectDir, org).length,
-        rejected: loadPacketsFromDir(orgRejectedDir(projectDir, org)).length,
-        audit_events: orgAuditCount(projectDir, org),
-        registry_path: (0, node_fs_1.existsSync)((0, node_path_1.join)(orgRootDir(projectDir, org), "registry.json")) ? (0, node_path_1.join)(orgRootDir(projectDir, org), "registry.json") : undefined,
-    };
-}
-function orgUploadPacket(projectDir, org, id) {
-    ensureMemoryDirs(projectDir);
-    ensureDir(orgInboxDir(projectDir, org));
-    const source = loadApprovedPackets(projectDir).find((packet) => packet.id === id);
-    if (!source)
-        return { ok: false, errors: [`Approved packet not found: ${id}`] };
-    if (["blocked", "confidential"].includes(source.sensitivity)) {
-        return { ok: false, errors: [`Packet sensitivity cannot be uploaded to org memory: ${source.sensitivity}`] };
-    }
-    const findings = scanSensitiveText(`${source.title}\n${source.summary}\n${source.body}\n${source.paths.join("\n")}`);
-    if (findings.length)
-        return { ok: false, errors: [`Sensitive content blocked: ${unique(findings).join(", ")}`] };
-    const createdAt = nowIso();
-    const packet = {
-        ...source,
-        id: `org:${slugify(org)}:${(0, node_crypto_1.createHash)("sha256").update(source.id).digest("hex").slice(0, 16)}:${slugify(source.title)}`,
-        scope: "org",
-        visibility: "org",
-        sensitivity: source.sensitivity === "public" ? "public" : "internal",
-        status: "pending",
-        tags: unique([...source.tags, "org-candidate"]).sort(),
-        source_refs: [
-            ...source.source_refs,
-            {
-                kind: "org_upload_candidate",
-                source_packet_id: source.id,
-                repo_key: repoKey(projectDir),
-            },
-        ],
-        quality: {
-            ...source.quality,
-            org_review_required: true,
-            source_packet_id: source.id,
-        },
-        created_at: createdAt,
-        updated_at: createdAt,
-    };
-    const validation = validatePacket(packet, "org candidate");
-    if (!validation.ok)
-        return { ok: false, errors: validation.errors };
-    const path = (0, node_path_1.join)(orgInboxDir(projectDir, org), packetFileName(packet));
-    writeJson(path, packet);
-    appendOrgAudit(projectDir, org, { action: "upload_candidate", packet_id: packet.id, source_packet_id: source.id });
-    return { ok: true, packet, path, errors: [] };
-}
-function orgReviewPacket(projectDir, org, id, action) {
-    ensureDir(orgInboxDir(projectDir, org));
-    ensureDir(orgPacketsDir(projectDir, org));
-    ensureDir(orgRejectedDir(projectDir, org));
-    const sourcePath = walkFiles(orgInboxDir(projectDir, org), (path) => path.endsWith(".json"))
-        .find((path) => readJson(path).id === id);
-    if (!sourcePath)
-        return { ok: false, errors: [`Org inbox packet not found: ${id}`] };
-    const packet = readJson(sourcePath);
-    packet.status = action === "approve" ? "approved" : "deprecated";
-    packet.updated_at = nowIso();
-    packet.quality = {
-        ...packet.quality,
-        org_reviewed_at: packet.updated_at,
-        org_review_action: action,
-    };
-    const targetDir = action === "approve" ? orgPacketsDir(projectDir, org) : orgRejectedDir(projectDir, org);
-    const targetPath = (0, node_path_1.join)(targetDir, packetFileName(packet));
-    writeJson(targetPath, packet);
-    (0, node_fs_1.renameSync)(sourcePath, `${sourcePath}.reviewed`);
-    appendOrgAudit(projectDir, org, { action: `review_${action}`, packet_id: packet.id });
-    exportOrgRegistry(projectDir, org);
-    return { ok: true, path: targetPath, errors: [] };
-}
-function orgRecall(projectDir, org, query, limit = 5) {
-    return recallFromPackets(query, loadOrgApprovedPackets(projectDir, org), limit, `Org:${slugify(org)}`);
-}
-function layeredRecall(projectDir, query, options = {}) {
-    const limit = options.limit ?? 5;
-    const repo = recall(projectDir, query, limit, true);
-    const org = options.org ? orgRecall(projectDir, options.org, query, limit) : undefined;
-    const global = options.includeGlobal ? recallFromPackets(query, loadPacketsFromDir(publicCandidatesDir(projectDir)), limit, "Global") : undefined;
-    const blocks = [
-        "# Kage Layered Recall",
-        "",
-        "Priority: branch > repo local > org > global",
-        "",
-        repo.context_block,
-        org ? `\n---\n\n${org.context_block}` : "",
-        global ? `\n---\n\n${global.context_block}` : "",
-    ].filter(Boolean);
-    return {
-        query,
-        priority_order: ["branch", "repo", ...(org ? ["org"] : []), ...(global ? ["global"] : [])],
-        context_block: blocks.join("\n"),
-        repo,
-        ...(org ? { org } : {}),
-        ...(global ? { global } : {}),
-    };
-}
-function exportOrgRegistry(projectDir, org) {
-    const packets = loadOrgApprovedPackets(projectDir, org);
-    const payload = {
-        schema_version: 1,
-        org: slugify(org),
-        repo_key: repoKey(projectDir),
-        generated_at: nowIso(),
-        metrics: {
-            packets: packets.length,
-            by_type: countBy(packets, (packet) => packet.type),
-            by_repo_path: countBy(packets.flatMap((packet) => packet.paths), (path) => path),
-        },
-        packets: packets.map((packet) => ({
-            id: packet.id,
-            title: packet.title,
-            summary: packet.summary,
-            type: packet.type,
-            tags: packet.tags,
-            paths: packet.paths,
-            source_refs: packet.source_refs,
-            updated_at: packet.updated_at,
-            content_sha256: (0, node_crypto_1.createHash)("sha256").update(canonicalPacketText(packet)).digest("hex"),
-        })),
-    };
-    const manifest = (0, index_js_1.createSignedManifest)({
-        kind: "org_registry",
-        name: `${slugify(org)} org memory`,
-        version: nowIso().slice(0, 10),
-        keyId: `${slugify(org)}-local`,
-        payload,
-    });
-    writeJson((0, node_path_1.join)(orgRootDir(projectDir, org), "registry.json"), manifest);
-    appendOrgAudit(projectDir, org, { action: "export_registry", packets: packets.length });
-    return orgStatus(projectDir, org);
-}
 function canonicalPacketText(packet) {
     return JSON.stringify({
         title: packet.title,
@@ -13130,86 +14027,6 @@ function canonicalPacketText(packet) {
         paths: packet.paths,
     });
 }
-function buildMarketplace(projectDir) {
-    ensureMemoryDirs(projectDir);
-    const packs = registryRecommendations(projectDir).map((item) => ({
-        ...item,
-        source: "repo_metadata",
-    }));
-    const manifest = {
-        schema_version: 1,
-        project_dir: projectDir,
-        generated_at: nowIso(),
-        packs,
-        install_policy: "explicit_human_approval_required",
-    };
-    const path = (0, node_path_1.join)(marketplaceDir(projectDir), "manifest.json");
-    writeJson(path, manifest);
-    const planLines = [
-        "# Kage Marketplace Install Plan",
-        "",
-        "Kage never installs marketplace assets automatically. Review each pack, then install it with your agent's normal trusted setup flow.",
-        "",
-        ...packs.flatMap((pack) => [
-            `## ${pack.title}`,
-            "",
-            `- ID: \`${pack.id}\``,
-            `- Kind: \`${pack.kind}\``,
-            `- Trust: \`${pack.trust}\``,
-            `- Install policy: \`${pack.install}\``,
-            `- Matched: ${pack.matched.join(", ") || "(repo metadata)"}`,
-            "",
-            pack.summary,
-            "",
-        ]),
-    ];
-    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(marketplaceDir(projectDir), "install-plan.md"), `${planLines.join("\n").trim()}\n`, "utf8");
-    return { ok: true, path, packs, errors: [] };
-}
-function buildGlobalCdnBundle(projectDir, org = "local") {
-    ensureMemoryDirs(projectDir);
-    const publicBundle = exportPublicBundle(projectDir);
-    if (!publicBundle.ok) {
-        return { ok: false, root: globalCdnDir(projectDir), packet_count: 0, marketplace_packs: 0, errors: publicBundle.errors };
-    }
-    const marketplace = buildMarketplace(projectDir);
-    const publicManifest = readJson(publicBundle.path);
-    const registryManifest = (0, index_js_1.generateOrgRegistryManifest)({
-        org: slugify(org),
-        version: nowIso().slice(0, 10),
-        keyId: `${slugify(org)}-global-local`,
-        bundles: [publicManifest],
-    });
-    const root = globalCdnDir(projectDir);
-    const digest = registryManifest.signature.payload_sha256.slice(0, 16);
-    const manifestPath = (0, node_path_1.join)(root, `registry.${digest}.json`);
-    const aliasPath = (0, node_path_1.join)(root, "latest.json");
-    writeJson(manifestPath, registryManifest);
-    writeJson((0, node_path_1.join)(root, "registry.json"), registryManifest);
-    writeJson((0, node_path_1.join)(root, "revocations.json"), {
-        schema_version: 1,
-        generated_at: nowIso(),
-        revoked: [],
-    });
-    writeJson(aliasPath, {
-        schema_version: 1,
-        registry: (0, node_path_1.relative)(root, manifestPath),
-        marketplace: (0, node_path_1.relative)(root, marketplace.path),
-        payload_sha256: registryManifest.signature.payload_sha256,
-        generated_at: registryManifest.generated_at,
-        rollback_ready: true,
-    });
-    return {
-        ok: true,
-        root,
-        manifest_path: manifestPath,
-        alias_path: aliasPath,
-        marketplace_path: marketplace.path,
-        packet_count: registryManifest.payload.metrics.entry_count,
-        marketplace_packs: marketplace.packs.length,
-        errors: [],
-    };
-}
 function recordFeedback(projectDir, id, feedback) {
     ensureMemoryDirs(projectDir);
     if (!["helpful", "wrong", "stale"].includes(feedback)) {
@@ -13360,13 +14177,19 @@ function installClaudeSettings(projectDir) {
     settings.allowedTools = merged;
     writeJson(settingsPath, settings);
 }
-function initProject(projectDir) {
-    installAgentPolicy(projectDir);
-    installClaudeSettings(projectDir);
+function initProject(projectDir, options = {}) {
+    // Default init touches ONLY .agent_memory/. Agent-policy files (AGENTS.md,
+    // CLAUDE.md) and .claude/settings.json are repo-visible and reviewable, so
+    // writing them requires explicit opt-in (`kage init --with-policy` or `kage policy`).
+    const policyInstalled = options.policy === true;
+    if (policyInstalled) {
+        installAgentPolicy(projectDir);
+        installClaudeSettings(projectDir);
+    }
     const index = indexProject(projectDir, { graphs: false });
     const validation = validateProject(projectDir);
     const sampleRecall = recallFromPackets("how do I run tests", loadApprovedPackets(projectDir), 5, "Repo Memory");
-    return { index, validation, sampleRecall };
+    return { index, validation, sampleRecall, policyInstalled };
 }
 function doctorProject(projectDir) {
     ensureMemoryDirs(projectDir);