@kage-core/kage-graph-mcp 1.1.37 → 1.2.0

package/dist/kernel.js

@@ -83,12 +83,15 @@ exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
 exports.gcProject = gcProject;
+exports.verifyCitations = verifyCitations;
+exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
 exports.recall = recall;
 exports.recallWithEmbeddings = recallWithEmbeddings;
 exports.queryCodeGraph = queryCodeGraph;
+exports.kageTeammateBrief = kageTeammateBrief;
 exports.kageRisk = kageRisk;
 exports.kageDependencyPath = kageDependencyPath;
 exports.kageCleanupCandidates = kageCleanupCandidates;
@@ -102,6 +105,7 @@ exports.kageCapabilityAudit = kageCapabilityAudit;
 exports.kageDecisionIntelligence = kageDecisionIntelligence;
 exports.kageModuleHealth = kageModuleHealth;
 exports.kageGraphInsights = kageGraphInsights;
+exports.kageRepoXray = kageRepoXray;
 exports.kageWorkspace = kageWorkspace;
 exports.kageWorkspaceRecall = kageWorkspaceRecall;
 exports.queryGraph = queryGraph;
@@ -124,6 +128,7 @@ exports.verifyAgentActivation = verifyAgentActivation;
 exports.observe = observe;
 exports.kageSessionCaptureReport = kageSessionCaptureReport;
 exports.kageSessionReplay = kageSessionReplay;
+exports.kageSessionLearningLedger = kageSessionLearningLedger;
 exports.distillSession = distillSession;
 exports.proposeFromDiff = proposeFromDiff;
 exports.buildBranchOverlay = buildBranchOverlay;
@@ -177,6 +182,27 @@ exports.MEMORY_TYPES = [
     "negative_result",
     "constraint",
 ];
+// Bounded context assembly (PRD Feature 2: "inject only the relevant rule + structural
+// map, dropping the rest"). Opt-in: when a token budget is set, keep the highest-priority
+// sections (preamble + code graph + memory come first in the block) and drop trailing
+// lower-priority sections until the estimate fits. Default (no budget) is unchanged.
+function boundContextBlock(block, budget) {
+    if (!Number.isFinite(budget) || budget <= 0 || estimateTokens(block) <= budget)
+        return block;
+    const parts = block.split(/\n(?=## )/);
+    const kept = [parts[0]];
+    let dropped = 0;
+    for (const section of parts.slice(1)) {
+        if (estimateTokens([...kept, section].join("\n")) <= budget)
+            kept.push(section);
+        else
+            dropped += 1;
+    }
+    const result = kept.join("\n");
+    return dropped
+        ? `${result}\n\n_Context trimmed to ~${budget} tokens; ${dropped} lower-priority section(s) dropped._`
+        : result;
+}
 const graphMemoryCache = new Map();
 exports.SETUP_AGENTS = [
     "codex",
@@ -1116,6 +1142,52 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
     }
     return unique(reasons);
 }
+// Classifies stale reasons into severity. "hard" reasons (deprecated status, user
+// reported stale, ttl expired, all citations deleted) mean the memory should be
+// excluded from recall; "soft" reasons (some citations missing, a linked file
+// changed) mean keep-but-flag — the memory may just need review, not suppression.
+function staleSeverity(reasons) {
+    if (!reasons.length)
+        return "none";
+    const hard = reasons.some((reason) => reason.startsWith("packet status is") ||
+        reason.startsWith("user or agent reported") ||
+        reason.startsWith("freshness ttl expired") ||
+        reason.startsWith("all referenced paths are missing"));
+    return hard ? "hard" : "soft";
+}
+// Decides whether a packet should be excluded from the recall payload (PRD Feature 3:
+// "deleted or heavily refactored since the timestamp"). Distinct from staleMemoryReasons:
+// a citation that NEVER existed (no stored fingerprint) is an ungrounded write — guarded
+// at capture time — not recall-time staleness, so it does NOT trigger exclusion here.
+// Returns a reason string when the memory is hard-stale, otherwise null.
+function recallHardStaleReason(projectDir, packet, cache) {
+    if (packet.status === "deprecated" || packet.status === "superseded")
+        return `packet status is ${packet.status}`;
+    const quality = (packet.quality ?? {});
+    if (Number(quality.reports_stale ?? 0) > 0)
+        return "user or agent reported this memory stale";
+    const freshness = (packet.freshness ?? {});
+    const ttlDays = Number(freshness.ttl_days ?? freshness.ttlDays ?? 0);
+    const verifiedAt = Date.parse(String(freshness.last_verified_at ?? packet.updated_at ?? packet.created_at));
+    if (Number.isFinite(ttlDays) && ttlDays > 0 && Number.isFinite(verifiedAt)) {
+        const ageDays = (Date.now() - verifiedAt) / (1000 * 60 * 60 * 24);
+        if (ageDays > ttlDays)
+            return `freshness ttl expired (${Math.floor(ageDays)}d old, ttl ${ttlDays}d)`;
+    }
+    // Only paths that existed at capture get a stored fingerprint; if every one of them is
+    // now gone, the memory's evidence was deleted out from under it.
+    const stored = packetStoredPathFingerprints(packet);
+    if (stored.length) {
+        const deleted = stored.filter((fingerprint) => {
+            const current = memoryPathFingerprint(projectDir, fingerprint.path, cache);
+            return current === null;
+        });
+        if (deleted.length === stored.length) {
+            return `all cited files deleted since capture: ${deleted.slice(0, 4).map((fingerprint) => fingerprint.path).join(", ")}`;
+        }
+    }
+    return null;
+}
 function changedPathsFromStaleReasons(reasons) {
     return unique(reasons.flatMap((reason) => {
         const match = reason.match(/^linked path changed since memory was verified: (.+)$/);
@@ -1520,13 +1592,28 @@ function walkFiles(root, predicate) {
     }
     return out.sort();
 }
+// Tolerant packet read: a single corrupt or merge-conflicted packet (e.g. an
+// unresolved `<<<<<<<` from a teammate's git merge) must not take down all of
+// recall/verify/compact. Skip the bad file with a warning and keep going.
+function tryReadPacket(path) {
+    try {
+        return readJson(path);
+    }
+    catch (error) {
+        process.stderr.write(`kage: skipping unreadable memory packet ${path}: ${error.message}\n`);
+        return null;
+    }
+}
 function loadPacketsFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
         return [];
     return (0, node_fs_1.readdirSync)(dir)
         .filter((name) => name.endsWith(".json"))
         .sort()
-        .map((name) => readJson((0, node_path_1.join)(dir, name)));
+        .flatMap((name) => {
+        const packet = tryReadPacket((0, node_path_1.join)(dir, name));
+        return packet ? [packet] : [];
+    });
 }
 function loadPacketEntriesFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
@@ -1534,9 +1621,10 @@ function loadPacketEntriesFromDir(dir) {
     return (0, node_fs_1.readdirSync)(dir)
         .filter((name) => name.endsWith(".json"))
         .sort()
-        .map((name) => {
+        .flatMap((name) => {
         const path = (0, node_path_1.join)(dir, name);
-        return { path, packet: readJson(path) };
+        const packet = tryReadPacket(path);
+        return packet ? [{ path, packet }] : [];
     });
 }
 function loadApprovedPackets(projectDir) {
@@ -5507,6 +5595,115 @@ function gcProject(projectDir, options = {}) {
         total_scanned: packetEntries.length,
     };
 }
+// On-demand citation/freshness check the agent can call before trusting a memory.
+// Pass an id to verify one packet, or omit to audit all approved memory.
+function verifyCitations(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const targets = options.id ? approved.filter((packet) => packet.id === options.id) : approved;
+    if (options.id && !targets.length) {
+        return { ok: false, project_dir: projectDir, checked: 0, valid: 0, stale: 0, ungrounded: 0, packets: [], errors: [`Approved packet not found: ${options.id}`] };
+    }
+    const cache = new Map();
+    const packets = targets.map((packet) => {
+        const meaningful = packet.paths.filter((path) => meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+        const missing = meaningful.filter((path) => !pathExistsInRepo(projectDir, path));
+        const reasons = staleMemoryReasons(projectDir, packet, cache);
+        const severity = staleSeverity(reasons);
+        const grounded = packetGroundingWarnings(projectDir, packet, "packet").length === 0;
+        return {
+            id: packet.id,
+            title: packet.title,
+            status: packet.status,
+            paths: packet.paths,
+            missing_paths: missing,
+            grounded,
+            stale: severity !== "none",
+            stale_severity: severity,
+            stale_reasons: reasons,
+        };
+    });
+    return {
+        ok: true,
+        project_dir: projectDir,
+        checked: packets.length,
+        valid: packets.filter((entry) => !entry.stale && entry.grounded).length,
+        stale: packets.filter((entry) => entry.stale).length,
+        ungrounded: packets.filter((entry) => !entry.grounded).length,
+        packets,
+        errors: [],
+    };
+}
+// Deterministic memory consolidation (no hosted LLM — preserves the no-API-key promise):
+//  1. prune dead citations from packets and refresh their path fingerprints,
+//  2. deprecate hard-stale packets (delegating to the same severity rules as recall/gc),
+//  3. surface near-duplicate clusters for an agent to merge via kage_supersede.
+function compactProject(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const dryRun = options.dryRun === true;
+    const entries = loadPacketEntriesFromDir(packetsDir(projectDir));
+    const prunedCitations = [];
+    const deprecated = [];
+    const cache = new Map();
+    for (const { path, packet } of entries) {
+        if (packet.status === "deprecated" || packet.status === "superseded")
+            continue;
+        const hardReason = recallHardStaleReason(projectDir, packet, cache);
+        if (hardReason) {
+            deprecated.push({ id: packet.id, title: packet.title, reason: hardReason });
+            if (!dryRun)
+                writeJson(path, { ...packet, status: "deprecated", updated_at: nowIso() });
+            continue;
+        }
+        const meaningful = packet.paths.filter((p) => meaningfulMemoryPath(p) && !shouldSkipRepoMemoryPath(p));
+        const missing = meaningful.filter((p) => !pathExistsInRepo(projectDir, p));
+        if (missing.length) {
+            const keptPaths = packet.paths.filter((p) => !missing.includes(p));
+            prunedCitations.push({ id: packet.id, title: packet.title, removed_paths: missing });
+            if (!dryRun) {
+                writeJson(path, {
+                    ...packet,
+                    paths: keptPaths,
+                    freshness: {
+                        ...(packet.freshness ?? {}),
+                        path_fingerprints: memoryPathFingerprints(projectDir, keptPaths),
+                        last_verified_at: nowIso(),
+                    },
+                    updated_at: nowIso(),
+                });
+            }
+        }
+    }
+    // Cluster near-duplicate approved packets (report only — merging is an agent decision).
+    const context = memoryQualityContext(projectDir);
+    const approved = context.packets.filter((packet) => packet.status === "approved");
+    const seen = new Set();
+    const clusters = [];
+    for (const packet of approved) {
+        if (seen.has(packet.id))
+            continue;
+        const dupes = duplicateCandidatesWithContext(packet, context, 0.6).filter((dupe) => dupe.status === "approved");
+        if (!dupes.length)
+            continue;
+        const members = [{ id: packet.id, title: packet.title }, ...dupes.map((dupe) => ({ id: dupe.id, title: dupe.title }))];
+        members.forEach((member) => seen.add(member.id));
+        clusters.push({ score: Math.max(...dupes.map((dupe) => dupe.score)), packets: members });
+    }
+    if (!dryRun && (prunedCitations.length || deprecated.length)) {
+        const rebuilt = buildGraphIndexes(projectDir);
+        writeJson((0, node_path_1.join)(memoryRoot(projectDir), "metrics.json"), kageMetricsShallow(projectDir, rebuilt));
+    }
+    return {
+        ok: true,
+        project_dir: projectDir,
+        dry_run: dryRun,
+        pruned_citations: prunedCitations,
+        deprecated,
+        duplicate_clusters: clusters,
+        total_scanned: entries.length,
+        errors: [],
+    };
+}
 function installAgentPolicy(projectDir) {
     const agentsPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const claudePath = (0, node_path_1.join)(projectDir, "CLAUDE.md");
@@ -6274,7 +6471,23 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         })()
         : recallQueryExpansion(query);
     const terms = expansion.terms;
-    const approvedPackets = loadApprovedPackets(projectDir);
+    const allApprovedPackets = loadApprovedPackets(projectDir);
+    const includeStale = inputs.includeStale === true;
+    const staleFingerprintCache = new Map();
+    const suppressed = [];
+    // Just-in-time staleness gate: hard-stale memory (deleted citations, expired ttl,
+    // reported stale) is excluded from the recall payload so the agent never sees it
+    // as valid. Suppression is recorded (not silent) so `kage verify` can explain it.
+    const approvedPackets = includeStale
+        ? allApprovedPackets
+        : allApprovedPackets.filter((packet) => {
+            const reason = recallHardStaleReason(projectDir, packet, staleFingerprintCache);
+            if (reason) {
+                suppressed.push({ id: packet.id, title: packet.title, reason });
+                return false;
+            }
+            return true;
+        });
     const baseScores = scorePacketsBm25(expansion.baseTerms, approvedPackets);
     const temporalScores = scorePacketsBm25(expansion.temporalTerms, approvedPackets);
     const semanticScores = scorePacketsBm25(expansion.semanticTerms, approvedPackets);
@@ -6332,6 +6545,13 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
     const graphContext = queryGraph(projectDir, query, 5, knowledgeGraph);
     const codeContext = queryCodeGraph(projectDir, query, 5, codeGraph);
     const pinnedContext = renderPinnedRepoContext(readContextSlots(projectDir));
+    // PRD Feature 2: traverse the code graph outward from the recalled memory's files
+    // (the semantic entry point) to assemble a bounded structural blast radius. Opt-in
+    // via inputs.structuralHops so default recall output is unchanged.
+    const structuralHops = inputs.structuralHops ?? 0;
+    const blastRadius = structuralHops > 0
+        ? structuralBlastRadius(codeGraph, unique(scored.flatMap((entry) => entry.packet.paths).filter((path) => meaningfulMemoryPath(path))), structuralHops)
+        : [];
     const lines = [
         `# Kage Context`,
         "",
@@ -6344,6 +6564,9 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ...codeContext.tests.slice(0, 3).map((test, index) => `${index + 1}. [test] ${test.title} in ${test.test_path}:${test.line}${test.covers_symbol ? ` covers ${test.covers_symbol}` : ""}`),
         ...(!codeContext.symbols.length && !codeContext.routes.length && !codeContext.tests.length ? codeContext.files.slice(0, 3).map((file, index) => `${index + 1}. [file] ${file.path} (${file.kind})`) : []),
         "",
+        ...(blastRadius.length
+            ? [`## Structural Blast Radius (${structuralHops}-hop)`, ...blastRadius.map((path, index) => `${index + 1}. ${path}`), ""]
+            : []),
         scored.length ? "## Relevant Memory" : "No relevant repo memory found.",
         ...scored.flatMap((entry, index) => [
             "",
@@ -6364,11 +6587,16 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         "",
         graphContext.edges.length ? "## Related Graph Facts" : "",
         ...graphContext.edges.slice(0, 5).map((edge, index) => `${index + 1}. ${edge.fact} (evidence: ${edge.evidence.join(", ")})`),
+        ...(suppressed.length
+            ? ["", `_${suppressed.length} stale memory packet(s) excluded from recall. Run kage verify for details._`]
+            : []),
     ];
+    const assembledBlock = lines.join("\n");
     const result = {
         query,
-        context_block: lines.join("\n"),
+        context_block: inputs.maxContextTokens ? boundContextBlock(assembledBlock, inputs.maxContextTokens) : assembledBlock,
         results: scored,
+        suppressed: suppressed.length ? suppressed : undefined,
         explanations: explain
             ? scored.map((entry) => ({
                 packet_id: entry.packet.id,
@@ -6555,6 +6783,112 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         structural_edges: structuralEdges,
     };
 }
+function fileHintsFromText(text) {
+    const matches = text.match(/[A-Za-z0-9_./@-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|kts|rb|php|cs|c|h|cc|cpp|hpp|swift|json|md)\b/g) ?? [];
+    return [...new Set(matches.map((match) => match.replace(/^\.\//, "")).filter((match) => !/^https?:\/\//.test(match)))];
+}
+function dedupeStrings(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function teammateBriefLines(brief) {
+    const verification = brief.verification_contract;
+    const lines = [
+        "\n## Teammate Brief",
+        "Purpose: reduce verification debt and context loss for this task.",
+        "",
+        "### Verification Contract",
+    ];
+    if (verification.focus_files.length) {
+        lines.push(`Focus files: ${verification.focus_files.join(", ")}`);
+    }
+    if (verification.related_tests.length) {
+        lines.push("Related tests:");
+        for (const test of verification.related_tests.slice(0, 5)) {
+            lines.push(`- ${test.test_path}${test.title ? ` - ${test.title}` : ""}${test.covers ? ` (covers ${test.covers})` : ""}`);
+        }
+    }
+    else if (verification.focus_files.length) {
+        lines.push("Related tests: none found in the current code graph.");
+    }
+    if (verification.test_gap_files.length) {
+        lines.push(`Test gaps: ${verification.test_gap_files.join(", ")}`);
+    }
+    if (brief.memory_warnings.length) {
+        lines.push("", "### Memory Warnings", ...brief.memory_warnings.slice(0, 5).map((warning) => `- ${warning}`));
+    }
+    lines.push("", "### Next Actions");
+    for (const action of brief.next_actions.slice(0, 6)) {
+        lines.push(`- ${action}`);
+    }
+    return lines;
+}
+function kageTeammateBrief(projectDir, options) {
+    const query = options.query;
+    const focusFiles = dedupeStrings([
+        ...(options.targets ?? []),
+        ...(options.changedFiles ?? []),
+        ...fileHintsFromText(query),
+    ]);
+    const codeQuery = dedupeStrings([query, ...focusFiles]).join(" ");
+    const code = queryCodeGraph(projectDir, codeQuery || query, 12);
+    const relatedTests = code.tests
+        .map((test) => ({
+        test_path: test.test_path,
+        title: test.title,
+        covers: test.covers_path ?? test.covers_symbol ?? null,
+    }))
+        .filter((test, index, all) => all.findIndex((item) => item.test_path === test.test_path && item.title === test.title) === index);
+    const riskTargets = options.riskResult ? Object.values(options.riskResult.targets) : [];
+    const testGapFiles = dedupeStrings([
+        ...riskTargets.filter((target) => target.test_gap).map((target) => target.target),
+        ...(focusFiles.length && !relatedTests.length ? focusFiles : []),
+    ]);
+    const memoryWarnings = [
+        ...((options.recallResult?.results ?? [])
+            .filter((entry) => Boolean((entry.packet.quality ?? {}).stale))
+            .map((entry) => `Recalled memory may be stale: ${entry.packet.title}.`)),
+        ...(options.reconciliation?.unresolved_count
+            ? [`${options.reconciliation.unresolved_count} linked memory item(s) need update, supersede, or stale marking before handoff.`]
+            : []),
+    ];
+    const requiredActions = [
+        ...(relatedTests.length
+            ? [`Run or account for related test coverage: ${relatedTests.slice(0, 3).map((test) => test.test_path).join(", ")}.`]
+            : focusFiles.length
+                ? ["No related tests were found; identify the correct verification before claiming completion."]
+                : ["Identify task-specific verification before claiming completion."]),
+        ...testGapFiles.map((file) => `Resolve test-gap risk for ${file} or explain why existing verification is sufficient.`),
+        ...(memoryWarnings.length ? ["Resolve memory warnings before final handoff."] : []),
+    ];
+    const nextActions = dedupeStrings([
+        ...requiredActions,
+        ...(riskTargets.length
+            ? riskTargets
+                .filter((target) => target.co_change_warnings.length)
+                .slice(0, 2)
+                .map((target) => `Review co-change partners for ${target.target}: ${target.co_change_warnings.slice(0, 3).map((item) => item.file_path).join(", ")}.`)
+            : []),
+        "Keep any durable lesson evidence-backed; future agents should inherit only verified repo knowledge.",
+    ]);
+    const briefWithoutBlock = {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        query,
+        verification_contract: {
+            focus_files: focusFiles,
+            related_tests: relatedTests,
+            test_gap_files: testGapFiles,
+            required_actions: requiredActions,
+        },
+        memory_warnings: memoryWarnings,
+        next_actions: nextActions,
+    };
+    return {
+        ...briefWithoutBlock,
+        context_block: teammateBriefLines(briefWithoutBlock).join("\n"),
+    };
+}
 function gitLines(projectDir, args) {
     return (readGit(projectDir, args) ?? "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
 }
@@ -6662,7 +6996,7 @@ function gitFileSignal(projectDir, path, graphPaths) {
 }
 function gitChangedFiles(projectDir) {
     return gitLines(projectDir, ["status", "--porcelain", "-uall"])
-        .map((line) => line.slice(3).trim().split(" -> ").at(-1) ?? "")
+        .map((line) => parsePorcelainPath(line).split(" -> ").at(-1) ?? "")
         .filter(Boolean)
         .map((path) => gitPathToProjectRelative(projectDir, path) ?? path)
         .filter((path) => !isNoisePath(path));
@@ -6721,6 +7055,45 @@ function codeDependents(graph) {
     }
     return dependents;
 }
+// Bounded N-hop structural traversal from a set of seed files (the files the recalled
+// memory is about) — the PRD's "structural blast radius". Walks both import directions
+// (who-depends-on and what-it-depends-on), excludes the seeds, and ranks by how many
+// files depend on each node. Pure graph traversal; no full-repo scan.
+function structuralBlastRadius(graph, seedPaths, hops, limit = 8) {
+    const seeds = seedPaths.filter(Boolean);
+    if (!seeds.length || hops <= 0)
+        return [];
+    const dependents = codeDependents(graph);
+    const dependencies = new Map();
+    for (const edge of graph.imports) {
+        if (!edge.from_path || !edge.to_path)
+            continue;
+        const list = dependencies.get(edge.from_path) ?? new Set();
+        list.add(edge.to_path);
+        dependencies.set(edge.from_path, list);
+    }
+    const seedSet = new Set(seeds);
+    const visited = new Set();
+    let frontier = new Set(seeds);
+    for (let depth = 0; depth < hops; depth += 1) {
+        const next = new Set();
+        for (const node of frontier) {
+            for (const neighbor of [...(dependents.get(node) ?? []), ...(dependencies.get(node) ?? [])]) {
+                if (seedSet.has(neighbor) || visited.has(neighbor))
+                    continue;
+                visited.add(neighbor);
+                next.add(neighbor);
+            }
+        }
+        frontier = next;
+    }
+    const score = new Map();
+    for (const [path, incoming] of dependents.entries())
+        score.set(path, incoming.size);
+    return [...visited]
+        .sort((a, b) => (score.get(b) ?? 0) - (score.get(a) ?? 0) || a.localeCompare(b))
+        .slice(0, limit);
+}
 function impactSurface(target, dependents, graph) {
     const visited = new Set();
     let frontier = new Set([target]);
@@ -7562,7 +7935,7 @@ function kageProjectProfile(projectDir) {
     }
     const memoryConceptCounts = new Map();
     for (const packet of approved) {
-        for (const tag of packet.tags.filter((item) => item && !["session-learning", "agentmemory-comparison"].includes(item))) {
+        for (const tag of packet.tags.filter((item) => item && !["session-learning", "external-comparison"].includes(item))) {
             memoryConceptCounts.set(tag, (memoryConceptCounts.get(tag) ?? 0) + 1);
         }
     }
@@ -8307,13 +8680,261 @@ function kageGraphInsights(projectDir) {
         summary: `${centralFiles.length} central file(s), ${cycles.length} dependency cycle(s), ${communities.length} communit${communities.length === 1 ? "y" : "ies"}, ${flows.length} entry flow(s).`,
     };
 }
+function xrayItem(input) {
+    return {
+        ...input,
+        strength: Math.max(1, Math.min(100, Math.round(input.strength ?? 50))),
+        status: input.status ?? "ok",
+    };
+}
+function uniqueXrayItems(items) {
+    const byPath = new Map();
+    for (const item of items) {
+        const existing = byPath.get(item.path);
+        if (!existing || item.strength > existing.strength || (item.status === "risk" && existing.status !== "risk")) {
+            byPath.set(item.path, item);
+        }
+    }
+    return [...byPath.values()].sort((a, b) => b.strength - a.strength || a.path.localeCompare(b.path));
+}
+function isXrayCodePath(path, graphPaths) {
+    const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
+    return graphPaths.has(normalized) && !normalized.startsWith(".agent_memory/") && !normalized.startsWith("agent_memory/");
+}
+function kageRepoXray(projectDir) {
+    const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
+    const profile = kageProjectProfile(projectDir);
+    const risk = kageRisk(projectDir);
+    const health = kageModuleHealth(projectDir);
+    const insights = kageGraphInsights(projectDir);
+    const decisions = kageDecisionIntelligence(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const graphPaths = new Set(graph.files.map((file) => file.path));
+    const routeCounts = countBy(graph.routes, (route) => route.file_path);
+    const testsBySource = new Map();
+    for (const test of graph.tests) {
+        const key = test.covers_path ?? test.covers_symbol ?? "";
+        if (!key)
+            continue;
+        const list = testsBySource.get(key) ?? [];
+        list.push(test);
+        testsBySource.set(key, list);
+    }
+    const entryItems = uniqueXrayItems([
+        ...graph.routes.map((route) => xrayItem({
+            label: `${route.method} ${route.path}`,
+            path: route.file_path,
+            kind: "route",
+            strength: 90,
+            status: "ok",
+            evidence: [`Route handler in ${route.file_path}`, `${route.method} ${route.path}`],
+            action: "Start here to understand request flow before changing runtime behavior.",
+        })),
+        ...insights.entry_flows.map((flow) => xrayItem({
+            label: flow.entry,
+            path: flow.entry,
+            kind: "entry_flow",
+            strength: Math.min(96, 64 + flow.path.length * 6),
+            status: "ok",
+            evidence: [`Entry flow: ${flow.path.slice(0, 5).join(" -> ")}`],
+            action: "Trace this entry flow before editing shared dependencies.",
+        })),
+        ...profile.run_commands.slice(0, 4).map((command) => xrayItem({
+            label: command.name,
+            path: "package.json",
+            kind: "script",
+            strength: 58,
+            status: "ok",
+            evidence: [`package script: ${command.name} = ${command.command}`],
+            action: "Use this command evidence when verifying changes.",
+        })),
+    ]).slice(0, 8);
+    const centralByPath = new Map(insights.central_files.map((file) => [file.path, file]));
+    const coreItems = uniqueXrayItems([
+        ...profile.key_files.map((file) => {
+            const central = centralByPath.get(file.path);
+            return xrayItem({
+                label: file.path,
+                path: file.path,
+                kind: file.kind,
+                strength: Math.min(100, file.score + (central ? central.dependents * 6 : 0)),
+                status: "ok",
+                evidence: unique([
+                    ...file.why,
+                    ...(central ? [`centrality ${central.pagerank}, ${central.dependents} dependent(s)`] : []),
+                ]).slice(0, 4),
+                action: "Inspect this file early; Kage sees it as a central part of the repo.",
+            });
+        }),
+        ...insights.central_files.slice(0, 8).map((file) => xrayItem({
+            label: file.path,
+            path: file.path,
+            kind: file.kind,
+            strength: Math.min(100, 45 + file.dependents * 8 + file.imports * 3),
+            status: "ok",
+            evidence: [`${file.dependents} dependent(s)`, `${file.imports} outgoing import(s)`],
+            action: "Use this as a structural orientation point before following dependencies.",
+        })),
+    ]).slice(0, 10);
+    const riskTargets = Object.values(risk.targets).filter((target) => isXrayCodePath(target.target, graphPaths));
+    const riskHotspots = risk.global_hotspots.filter((hotspot) => isXrayCodePath(hotspot.file_path, graphPaths));
+    const riskItems = uniqueXrayItems([
+        ...riskTargets.map((target) => xrayItem({
+            label: target.target,
+            path: target.target,
+            kind: target.risk_type,
+            strength: Math.max(30, Math.round(target.hotspot_score * 100), target.dependents_count * 12, target.test_gap ? 70 : 0),
+            status: target.test_gap || target.risk_type === "single-owner" || target.risk_type === "churn-heavy" ? "risk" : "watch",
+            evidence: [
+                `${target.dependents_count} direct dependent(s)`,
+                `${target.git.commit_count_90d} commit(s) in 90d`,
+                target.test_gap ? "test gap" : "test signal found",
+            ],
+            action: "Review dependents, tests, and owners before editing this path.",
+        })),
+        ...riskHotspots.slice(0, 8).map((hotspot) => xrayItem({
+            label: hotspot.file_path,
+            path: hotspot.file_path,
+            kind: "hotspot",
+            strength: Math.round(hotspot.hotspot_score * 100),
+            status: "risk",
+            evidence: [`${hotspot.commit_count_90d} commit(s) in 90d`, `primary owner ${hotspot.primary_owner ?? "unknown"}`],
+            action: "Treat this as a change hotspot; ask Kage for risk before editing.",
+        })),
+        ...health.modules.filter((module) => module.grade === "C" || module.grade === "D").slice(0, 5).map((module) => xrayItem({
+            label: module.module,
+            path: module.module === "(root)" ? "." : module.module,
+            kind: "module",
+            strength: 100 - module.score,
+            status: module.grade === "D" ? "risk" : "watch",
+            evidence: module.reasons.slice(0, 3),
+            action: "Use module health reasons to decide tests and review scope.",
+        })),
+    ]).slice(0, 10);
+    const testItems = uniqueXrayItems([
+        ...graph.tests.map((test) => xrayItem({
+            label: test.title || test.test_path,
+            path: test.test_path,
+            kind: "test",
+            strength: 78,
+            status: "ok",
+            evidence: [`covers ${test.covers_path ?? test.covers_symbol ?? "repo behavior"}`],
+            action: "Run or account for this test when changing the covered code.",
+        })),
+        ...graph.files
+            .filter((file) => file.kind === "source" && !hasTestCoverage(file.path, graph))
+            .slice(0, 8)
+            .map((file) => xrayItem({
+            label: file.path,
+            path: file.path,
+            kind: "test_gap",
+            strength: routeCounts[file.path] ? 82 : 58,
+            status: "watch",
+            evidence: routeCounts[file.path] ? [`${routeCounts[file.path]} route(s), no direct test signal`] : ["no direct test signal"],
+            action: "Identify the right verification path before claiming a change here is safe.",
+        })),
+    ]).slice(0, 12);
+    const memoryByPath = new Map();
+    for (const packet of approved) {
+        for (const path of packet.paths.filter((item) => graphPaths.has(item))) {
+            const list = memoryByPath.get(path) ?? [];
+            list.push(packet);
+            memoryByPath.set(path, list);
+        }
+    }
+    const memoryItems = uniqueXrayItems([...memoryByPath.entries()].map(([path, packets]) => xrayItem({
+        label: path,
+        path,
+        kind: "memory_overlay",
+        strength: Math.min(100, packets.length * 22 + (testsBySource.get(path)?.length ?? 0) * 8 + (routeCounts[path] ?? 0) * 8),
+        status: "ok",
+        evidence: packets.slice(0, 3).map((packet) => `${packet.type}: ${packet.title}`),
+        action: "Read linked memory before editing; this is repo lore attached to code.",
+    }))).slice(0, 10);
+    const gapItems = uniqueXrayItems(decisions.coverage_gaps.slice(0, 10).map((gap) => xrayItem({
+        label: gap.path,
+        path: gap.path,
+        kind: "knowledge_gap",
+        strength: Math.min(100, gap.dependents * 16 + gap.churn_90d * 8 + 24),
+        status: "watch",
+        evidence: [gap.reason, `${gap.dependents} dependent(s)`, `${gap.churn_90d} commit(s) in 90d`],
+        action: "Capture why-memory here when the next session learns reusable context.",
+    })));
+    const layers = [
+        {
+            id: "entry_points",
+            title: "Entry Points",
+            summary: entryItems.length ? "Where runtime behavior appears to start." : "No route, script, or entry-flow signals found yet.",
+            items: entryItems,
+        },
+        {
+            id: "core_modules",
+            title: "Core Modules",
+            summary: coreItems.length ? "Files Kage would inspect first to understand this repo." : "No central code files found yet.",
+            items: coreItems,
+        },
+        {
+            id: "change_risk",
+            title: "Change Risk",
+            summary: riskItems.length ? "Hotspots, low-health modules, and risky change targets." : "No local risk signals found yet.",
+            items: riskItems,
+        },
+        {
+            id: "test_map",
+            title: "Test Map",
+            summary: testItems.length ? "Verification paths and code with missing direct test signals." : "No tests found in the code graph.",
+            items: testItems,
+        },
+        {
+            id: "memory_overlay",
+            title: "Memory Overlay",
+            summary: memoryItems.length ? "Repo knowledge already attached to code." : "No code-linked memory yet.",
+            items: memoryItems,
+        },
+        {
+            id: "knowledge_gaps",
+            title: "Knowledge Gaps",
+            summary: gapItems.length ? "High-signal code paths that need why-memory." : "No decision-memory coverage gaps detected.",
+            items: gapItems,
+        },
+    ];
+    const script = [
+        "I mapped your repo.",
+        `I found ${entryItems.length} entry point(s), ${coreItems.length} core code signal(s), ${riskItems.length} risk signal(s), and ${testItems.length} verification signal(s).`,
+        memoryItems.length
+            ? `${memoryItems.length} code area(s) already have attached repo memory.`
+            : "I do not see much code-linked repo memory yet, so I will learn carefully during the session.",
+        "Click any X-Ray item to focus the graph and see the evidence.",
+    ];
+    const nextActions = [
+        ...(entryItems.length ? [`Start orientation from ${entryItems[0].path}.`] : ["Run kage refresh so entry points can be indexed."]),
+        ...(riskItems.length ? [`Review highest-risk area ${riskItems[0].path} before making edits.`] : []),
+        ...(testItems.some((item) => item.kind === "test_gap") ? ["Resolve test-map gaps by identifying task-specific verification before handoff."] : []),
+        ...(gapItems.length ? ["Capture why-memory for knowledge gaps when the session uncovers durable context."] : []),
+    ];
+    const warnings = unique([
+        ...profile.warnings,
+        ...risk.warnings,
+        ...health.warnings,
+        ...insights.warnings,
+        ...decisions.warnings,
+    ]);
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        summary: `Repo X-Ray mapped ${graph.files.length} file(s), ${graph.symbols.length} symbol(s), ${graph.routes.length} route(s), ${graph.tests.length} test signal(s), and ${approved.length} memory packet(s).`,
+        first_use_script: script,
+        layers,
+        next_actions: unique(nextActions),
+        warnings,
+    };
+}
 const WORKSPACE_SKIP_DIRS = new Set([
     ".agent_memory",
     ".git",
     ".hg",
     ".next",
-    ".repowise",
-    ".repowise-workspace",
     "coverage",
     "dist",
     "node_modules",
@@ -10096,6 +10717,9 @@ function learn(input) {
         paths: input.paths,
         stack: input.stack,
         context: input.context,
+        allowMissingPaths: input.allowMissingPaths,
+        strictCitations: input.strictCitations,
+        graphNodes: input.graphNodes,
     });
 }
 function capture(input) {
@@ -10111,7 +10735,34 @@ function capture(input) {
             errors: [`Sensitive content blocked: ${unique(scanFindings).join(", ")}`],
         };
     }
+    const warnings = [];
+    const meaningfulPaths = (input.paths ?? [])
+        .filter((path) => path && meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+    const missingPaths = meaningfulPaths.filter((path) => !pathExistsInRepo(input.projectDir, path));
+    // Citation validation. Strict mode (agent-facing record_memory tools / CLI) rejects a
+    // write whose every cited path is missing — the PRD's "reject if citations don't exist".
+    // The core library stays permissive (warn-only) for programmatic callers and migrations.
+    if (input.strictCitations && meaningfulPaths.length && missingPaths.length === meaningfulPaths.length && !input.allowMissingPaths) {
+        return {
+            ok: false,
+            errors: [
+                `Citation validation failed: none of the referenced paths exist in this repo: ${missingPaths.join(", ")}. ` +
+                    `Fix the paths, or pass allow_missing_paths to record anyway (e.g. for a file you are about to create).`,
+            ],
+            warnings: [],
+        };
+    }
+    if (missingPaths.length) {
+        warnings.push(`Some referenced paths do not exist in this repo: ${missingPaths.join(", ")}`);
+    }
     const createdAt = nowIso();
+    // Agent-asserted links to code-graph nodes (PRD `graph_nodes`): the agent recording the
+    // memory knows which symbol/route/file the rule is about, so let it declare them instead
+    // of relying solely on background derivation.
+    const graphEdges = unique(input.graphNodes ?? [])
+        .map((node) => node.trim())
+        .filter(Boolean)
+        .map((node) => ({ relation: "references_code", to: node, evidence: "agent_capture", created_at: createdAt }));
     const packet = {
         schema_version: exports.PACKET_SCHEMA_VERSION,
         id: makePacketId(input.projectDir, type, input.title, String(Date.now())),
@@ -10153,10 +10804,12 @@ function capture(input) {
         },
         created_at: createdAt,
         updated_at: createdAt,
+        author_branch: gitBranch(input.projectDir),
     };
+    packet.edges = graphEdges;
     const validation = validatePacket(packet);
     if (!validation.ok)
-        return { ok: false, errors: validation.errors };
+        return { ok: false, errors: validation.errors, warnings };
     packet.quality = {
         ...packet.quality,
         ...evaluateMemoryQuality(input.projectDir, packet),
@@ -10168,7 +10821,7 @@ function capture(input) {
         path: (0, node_path_1.relative)(input.projectDir, path),
         source_kind: packet.source_refs[0]?.kind ?? "explicit_capture",
     });
-    return { ok: true, packet, path, errors: [] };
+    return { ok: true, packet, path, errors: [], warnings };
 }
 function createPublicCandidate(projectDir, id) {
     ensureMemoryDirs(projectDir);
@@ -11156,6 +11809,171 @@ function kageSessionReplay(projectDir, options = {}) {
             : "No durable candidates in this digest yet; keep observing or capture reusable learnings with kage learn.",
     };
 }
+function distilledObservationSessions(projectDir) {
+    const ids = new Set();
+    for (const packet of [...loadApprovedPackets(projectDir), ...loadPendingPackets(projectDir)]) {
+        for (const ref of packet.source_refs) {
+            if (ref.kind === "observation_session" && typeof ref.session_id === "string" && ref.session_id.trim()) {
+                ids.add(ref.session_id.trim());
+            }
+        }
+    }
+    return ids;
+}
+function eventLearningCandidate(event, knownCommands) {
+    if (event.type === "command_result") {
+        if (typeof event.exit_code === "number" && event.exit_code !== 0 && !`${event.summary ?? ""}\n${event.text ?? ""}`.trim()) {
+            return null;
+        }
+        const reusable = reusableCommandObservation(event, knownCommands);
+        if (reusable)
+            return { memory_type: "runbook", reason: reusable.learning };
+    }
+    if (event.type === "file_change") {
+        const learning = reusableFileObservation(event);
+        if (learning)
+            return { memory_type: "workflow", reason: learning };
+    }
+    if (event.type === "user_prompt") {
+        const learning = reusablePromptObservation(event);
+        if (learning)
+            return { memory_type: "decision", reason: learning };
+    }
+    return null;
+}
+function ignoredObservationReason(event) {
+    if (event.type === "tool_use" || event.type === "tool_result")
+        return "Tool telemetry helps replay the session but is not durable repo knowledge by itself.";
+    if (event.type === "command_result" || event.type === "test_result")
+        return "Verification evidence is useful for this session but needs a reusable cause, fix, or runbook before saving.";
+    if (event.type === "file_change")
+        return "The file touch is generic; save only if it explains a convention, workflow, bug, or invariant.";
+    if (event.type === "user_prompt")
+        return "The prompt is episodic; save only decisions, policies, gotchas, or reusable context.";
+    return "Session bookkeeping is not durable repo memory.";
+}
+function learningLedgerContextBlock(report) {
+    const lines = ["\n## Session Learning Ledger"];
+    if (!report.sessions.length) {
+        lines.push("No observed session events found.");
+        return lines.join("\n");
+    }
+    lines.push(`Save candidates: ${report.totals.save_candidates}`);
+    lines.push(`Needs evidence: ${report.totals.needs_evidence}`);
+    if (report.totals.already_distilled)
+        lines.push(`Already distilled: ${report.totals.already_distilled}`);
+    lines.push("");
+    lines.push("### Memory Decisions");
+    for (const session of report.sessions.slice(0, 3)) {
+        lines.push(`Session ${session.session_id}: ${session.save_candidates} save, ${session.needs_evidence} needs evidence, ${session.ignore_items} ignore.`);
+        for (const decision of session.decisions.filter((item) => item.disposition !== "ignore").slice(0, 4)) {
+            lines.push(`- ${decision.disposition}: ${decision.memory_type ?? decision.event_type} - ${decision.evidence}`);
+        }
+    }
+    lines.push("", "### Next Actions");
+    for (const action of unique(report.sessions.map((session) => session.next_action)).slice(0, 4)) {
+        lines.push(`- ${action}`);
+    }
+    return lines.join("\n");
+}
+function kageSessionLearningLedger(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const limit = Math.max(1, Math.min(200, Math.floor(options.limit ?? 50)));
+    const observations = loadObservations(projectDir, options.sessionId);
+    const knownCommands = knownRepoCommands(projectDir);
+    const distilledSessions = distilledObservationSessions(projectDir);
+    const bySession = new Map();
+    for (const observation of observations) {
+        const rows = bySession.get(observation.session_id) ?? [];
+        rows.push(observation);
+        bySession.set(observation.session_id, rows);
+    }
+    const sessions = Array.from(bySession.entries()).map(([sessionId, rows]) => {
+        const sorted = rows.slice().sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        const alreadyDistilled = distilledSessions.has(sessionId);
+        const distillCommand = `kage distill --project . --session ${sessionId}`;
+        const decisions = sorted.map((event) => {
+            const candidate = eventLearningCandidate(event, knownCommands);
+            const failingEvidence = (event.type === "command_result" || event.type === "test_result") && typeof event.exit_code === "number" && event.exit_code !== 0;
+            const evidence = summarize(observationDigestSummary(event)).slice(0, 220);
+            if (candidate) {
+                return {
+                    observation_id: event.id,
+                    timestamp: event.timestamp,
+                    session_id: event.session_id,
+                    event_type: event.type,
+                    disposition: alreadyDistilled ? "already_distilled" : "save",
+                    memory_type: candidate.memory_type,
+                    reason: alreadyDistilled ? "A memory packet already references this observed session." : candidate.reason,
+                    evidence,
+                    ...(event.path ? { path: event.path } : {}),
+                    ...(event.command ? { command: normalizeCommandText(event.command) } : {}),
+                    ...(typeof event.exit_code === "number" ? { exit_code: event.exit_code } : {}),
+                    distill_command: distillCommand,
+                };
+            }
+            return {
+                observation_id: event.id,
+                timestamp: event.timestamp,
+                session_id: event.session_id,
+                event_type: event.type,
+                disposition: failingEvidence ? "needs_evidence" : "ignore",
+                reason: failingEvidence ? "A failure happened, but the observation does not yet explain a reusable cause, fix, workaround, or runbook." : ignoredObservationReason(event),
+                evidence,
+                ...(event.path ? { path: event.path } : {}),
+                ...(event.command ? { command: normalizeCommandText(event.command) } : {}),
+                ...(typeof event.exit_code === "number" ? { exit_code: event.exit_code } : {}),
+                ...(failingEvidence ? { distill_command: distillCommand } : {}),
+            };
+        });
+        const saveCandidates = decisions.filter((decision) => decision.disposition === "save").length;
+        const needsEvidence = decisions.filter((decision) => decision.disposition === "needs_evidence").length;
+        const ignoreItems = decisions.filter((decision) => decision.disposition === "ignore").length;
+        const alreadyDistilledCount = decisions.filter((decision) => decision.disposition === "already_distilled").length;
+        const nextAction = saveCandidates > 0
+            ? `${distillCommand} and review save candidates before handoff.`
+            : needsEvidence > 0
+                ? "Add a concise cause/fix summary for failing observations before deciding whether to save them."
+                : alreadyDistilledCount > 0
+                    ? "Session learning already has memory packets; update or supersede them only if the facts changed."
+                    : "No save-worthy session fact yet; keep observing without creating memory noise.";
+        return {
+            session_id: sessionId,
+            first_at: sorted[0]?.timestamp ?? "",
+            last_at: sorted.at(-1)?.timestamp ?? "",
+            observations: sorted.length,
+            save_candidates: saveCandidates,
+            ignore_items: ignoreItems,
+            needs_evidence: needsEvidence,
+            already_distilled: alreadyDistilledCount,
+            commands: unique(sorted.map((event) => event.command).filter(Boolean)).slice(0, 8),
+            paths: unique(sorted.map((event) => event.path).filter(Boolean)).slice(0, 12),
+            decisions: decisions.slice(0, limit),
+            next_action: nextAction,
+        };
+    }).sort((a, b) => b.last_at.localeCompare(a.last_at));
+    const totals = {
+        sessions: sessions.length,
+        observations: observations.length,
+        save_candidates: sessions.reduce((sum, session) => sum + session.save_candidates, 0),
+        ignore_items: sessions.reduce((sum, session) => sum + session.ignore_items, 0),
+        needs_evidence: sessions.reduce((sum, session) => sum + session.needs_evidence, 0),
+        already_distilled: sessions.reduce((sum, session) => sum + session.already_distilled, 0),
+    };
+    const reportWithoutBlock = {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        ...(options.sessionId ? { selected_session_id: options.sessionId } : {}),
+        totals,
+        sessions,
+        privacy_model: "The ledger classifies privacy-scanned observation metadata into save, ignore, needs-evidence, and already-distilled decisions; raw transcript text is not the product surface.",
+    };
+    return {
+        ...reportWithoutBlock,
+        context_block: learningLedgerContextBlock(reportWithoutBlock),
+    };
+}
 function distillSession(projectDir, sessionId) {
     const observations = loadObservations(projectDir, sessionId);
     const candidates = [];
@@ -11525,6 +12343,7 @@ function prCheck(projectDir) {
     const codeInputHash = currentCodeGraphInputHash(projectDir);
     const memoryInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
     const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
+        .filter((packet) => packet.status === "approved" || packet.status === "pending")
         .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet) }))
         .filter((entry) => entry.reasons.length)
         .map((entry) => staleFinding(entry.packet, entry.reasons));
@@ -11587,12 +12406,65 @@ function regexpEscape(value) {
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\"'\"'")}'`;
 }
-function gitHookPath(projectDir) {
-    const raw = readGit(projectDir, ["rev-parse", "--git-path", "hooks/post-commit"]);
+function gitHookPath(projectDir, hookName = "post-commit") {
+    const raw = readGit(projectDir, ["rev-parse", "--git-path", `hooks/${hookName}`]);
     if (!raw)
         return null;
     return (0, node_path_1.resolve)(projectDir, raw);
 }
+// Hooks that fire after history changes underfoot (git pull / merge / checkout):
+// re-index repo memory so newly pulled teammate packets are immediately recallable.
+const KAGE_SYNC_HOOKS = ["post-merge", "post-checkout"];
+function kageSyncHookBlock(projectDir) {
+    const project = shellQuote((0, node_path_1.resolve)(projectDir));
+    return [
+        KAGE_POST_COMMIT_HOOK_START,
+        "# Kage sync hook: re-index repo memory after pull/merge/checkout.",
+        "# Set KAGE_SKIP_HOOK=1 to bypass, or KAGE_BIN=/path/to/kage to override.",
+        "if [ \"${KAGE_SKIP_HOOK:-0}\" != \"1\" ]; then",
+        "  KAGE_BIN=\"${KAGE_BIN:-kage}\"",
+        "  if command -v \"$KAGE_BIN\" >/dev/null 2>&1; then",
+        "    (",
+        `      "$KAGE_BIN" index --project ${project} --json >/dev/null 2>&1 || true`,
+        "    ) &",
+        "  fi",
+        "fi",
+        KAGE_POST_COMMIT_HOOK_END,
+    ].join("\n");
+}
+function installSyncHooks(projectDir) {
+    const installed = [];
+    for (const hookName of KAGE_SYNC_HOOKS) {
+        const hookPath = gitHookPath(projectDir, hookName);
+        if (!hookPath)
+            continue;
+        ensureDir((0, node_path_1.dirname)(hookPath));
+        const existing = safeReadText(hookPath) ?? "";
+        const base = stripKageHookBlock(existing);
+        const prefix = base.trim() ? base.trimEnd() : "#!/bin/sh";
+        const next = `${prefix}\n\n${kageSyncHookBlock(projectDir)}\n`;
+        if (existing !== next)
+            (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
+        (0, node_fs_1.chmodSync)(hookPath, 0o755);
+        installed.push(hookPath);
+    }
+    return installed;
+}
+function uninstallSyncHooks(projectDir) {
+    const removed = [];
+    for (const hookName of KAGE_SYNC_HOOKS) {
+        const hookPath = gitHookPath(projectDir, hookName);
+        if (!hookPath)
+            continue;
+        const existing = safeReadText(hookPath) ?? "";
+        if (!hasKageHookBlock(existing))
+            continue;
+        (0, node_fs_1.writeFileSync)(hookPath, stripKageHookBlock(existing), "utf8");
+        (0, node_fs_1.chmodSync)(hookPath, 0o755);
+        removed.push(hookPath);
+    }
+    return removed;
+}
 function hasKageHookBlock(content) {
     return content.includes(KAGE_POST_COMMIT_HOOK_START) && content.includes(KAGE_POST_COMMIT_HOOK_END);
 }
@@ -11668,20 +12540,24 @@ function kageHookInstall(projectDir) {
     const base = stripKageHookBlock(existing);
     const prefix = base.trim() ? base.trimEnd() : "#!/bin/sh";
     const next = `${prefix}\n\n${kagePostCommitHookBlock(projectDir)}\n`;
-    const changed = existing !== next;
-    if (changed)
+    const commitChanged = existing !== next;
+    if (commitChanged)
         (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
     (0, node_fs_1.chmodSync)(hookPath, 0o755);
+    const syncHooks = installSyncHooks(projectDir);
     return {
         ok: true,
         action: "install",
         project_dir: projectDir,
         hook_path: hookPath,
         installed: true,
-        changed,
-        message: changed ? "Installed Kage post-commit hook." : "Kage post-commit hook is already current.",
+        changed: commitChanged,
+        message: commitChanged
+            ? "Installed Kage post-commit hook and pull/merge sync hooks."
+            : "Kage post-commit and sync hooks are already current.",
         errors: [],
         warnings: [],
+        additional_hooks: syncHooks,
     };
 }
 function kageHookUninstall(projectDir) {
@@ -11717,6 +12593,7 @@ function kageHookUninstall(projectDir) {
     const next = stripKageHookBlock(existing);
     (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
     (0, node_fs_1.chmodSync)(hookPath, 0o755);
+    const removedSyncHooks = uninstallSyncHooks(projectDir);
     return {
         ok: true,
         action: "uninstall",
@@ -11724,9 +12601,10 @@ function kageHookUninstall(projectDir) {
         hook_path: hookPath,
         installed: false,
         changed: true,
-        message: "Removed Kage post-commit hook.",
+        message: "Removed Kage post-commit and sync hooks.",
         errors: [],
         warnings: [],
+        additional_hooks: removedSyncHooks,
     };
 }
 function exportPublicBundle(projectDir) {