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

package/dist/kernel.js

@@ -62,6 +62,7 @@ exports.makePacketId = makePacketId;
 exports.parseFrontmatter = parseFrontmatter;
 exports.kageMemoryAccess = kageMemoryAccess;
 exports.kageMemoryLifecycle = kageMemoryLifecycle;
+exports.kageActivity = kageActivity;
 exports.kageMemoryReconciliation = kageMemoryReconciliation;
 exports.evaluateMemoryAdmission = evaluateMemoryAdmission;
 exports.validatePacket = validatePacket;
@@ -83,6 +84,7 @@ exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
 exports.gcProject = gcProject;
+exports.kageSuppressedMemory = kageSuppressedMemory;
 exports.verifyCitations = verifyCitations;
 exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
@@ -114,6 +116,8 @@ exports.kageMetrics = kageMetrics;
 exports.auditProject = auditProject;
 exports.memoryInbox = memoryInbox;
 exports.qualityReport = qualityReport;
+exports.benchmarkTrust = benchmarkTrust;
+exports.runDemo = runDemo;
 exports.benchmarkProject = benchmarkProject;
 exports.benchmarkCodingMemoryQuality = benchmarkCodingMemoryQuality;
 exports.benchmarkMemoryScale = benchmarkMemoryScale;
@@ -870,6 +874,8 @@ function kageMemoryLifecycle(projectDir) {
         const item = {
             packet_id: packet.id,
             title: packet.title,
+            summary: packet.summary ?? "",
+            body: packet.body ?? "",
             type: packet.type,
             status: packet.status,
             health: action.health,
@@ -954,6 +960,54 @@ function recordRecallAccess(projectDir, results) {
         // Recall should never fail because local access telemetry could not be updated.
     }
 }
+const AUDIT_ACTIVITY_KIND = {
+    capture: "capture", approve: "capture", supersede: "supersede", deprecate: "deprecate",
+    update: "update", promote: "promote", feedback: "feedback",
+};
+function kageActivity(projectDir, options = {}) {
+    const limit = options.limit ?? 80;
+    const events = [];
+    let recalls = 0;
+    readMemoryAccessEntries(projectDir).forEach((entry) => {
+        (entry.recent ?? []).forEach((r) => {
+            if (!r || !r.at)
+                return;
+            recalls += 1;
+            events.push({ at: r.at, kind: "recall", title: entry.title, detail: `recalled · rank ${r.rank}` });
+        });
+    });
+    let captures = 0;
+    for (const audit of loadMemoryAuditEntries(projectDir)) {
+        const kind = AUDIT_ACTIVITY_KIND[audit.operation] ?? "other";
+        if (kind === "capture")
+            captures += 1;
+        const extra = audit.packet_titles.length > 1 ? ` (+${audit.packet_titles.length - 1} more)` : "";
+        events.push({ at: audit.timestamp, kind, title: (audit.packet_titles[0] ?? audit.operation) + extra, detail: audit.operation, actor: audit.actor });
+    }
+    events.sort((a, b) => (Date.parse(b.at) || 0) - (Date.parse(a.at) || 0));
+    const dayMap = new Map();
+    events.forEach((e) => { if (e.kind === "recall") {
+        const d = e.at.slice(0, 10);
+        dayMap.set(d, (dayMap.get(d) ?? 0) + 1);
+    } });
+    // Zero-fill the last 14 calendar days so the chart reads as a timeline, not a lone bar.
+    const daily = [];
+    for (let i = 13; i >= 0; i -= 1) {
+        const day = new Date(Date.now() - i * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+        daily.push({ day, recalls: dayMap.get(day) ?? 0 });
+    }
+    const cutoff7 = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    const recalls7d = events.filter((e) => e.kind === "recall" && (Date.parse(e.at) || 0) >= cutoff7).length;
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        window_days: ACCESS_WINDOW_DAYS,
+        totals: { events: events.length, recalls, captures, recalls_7d: recalls7d },
+        daily,
+        events: events.slice(0, limit),
+    };
+}
 function isGeneratedChangeMemory(packet) {
     return packet.type === "workflow"
         && packet.tags.includes("change-memory")
@@ -1119,7 +1173,7 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
         if (ageDays > ttlDays)
             reasons.push(`freshness ttl expired (${Math.floor(ageDays)}d old, ttl ${ttlDays}d)`);
     }
-    const paths = packet.paths.filter(meaningfulMemoryPath);
+    const paths = packet.paths.filter((path) => meaningfulMemoryPath(path) && !isGroundingIgnored(projectDir, path));
     const missingPaths = paths.filter((path) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, path)));
     if (paths.length > 0 && missingPaths.length === paths.length) {
         reasons.push(`all referenced paths are missing: ${missingPaths.slice(0, 4).join(", ")}`);
@@ -1130,6 +1184,7 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
     if (freshness.path_fingerprint_policy === "source_hash_staleness") {
         const storedFingerprints = packetStoredPathFingerprints(packet);
         const changedPaths = storedFingerprints
+            .filter((fingerprint) => !isGroundingIgnored(projectDir, fingerprint.path))
             .filter((fingerprint) => (0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, fingerprint.path)))
             .filter((fingerprint) => {
             const current = memoryPathFingerprint(projectDir, fingerprint.path, fingerprintCache);
@@ -2338,7 +2393,7 @@ function pathExistsInRepo(projectDir, packetPath) {
 }
 function packetGroundingWarnings(projectDir, packet, source) {
     const warnings = [];
-    const meaningfulPaths = packet.paths.filter((path) => path && path !== "root" && !shouldSkipRepoMemoryPath(path));
+    const meaningfulPaths = packet.paths.filter((path) => path && path !== "root" && !shouldSkipRepoMemoryPath(path) && !isGroundingIgnored(projectDir, path));
     const missingPaths = meaningfulPaths.filter((path) => !pathExistsInRepo(projectDir, path));
     if (meaningfulPaths.length && missingPaths.length === meaningfulPaths.length) {
         warnings.push(`${source}: none of the referenced paths exist in this repo: ${missingPaths.join(", ")}`);
@@ -2802,6 +2857,54 @@ function readKageIgnore(projectDir) {
         .map((line) => line.trim())
         .filter((line) => line.length > 0 && !line.startsWith("#"));
 }
+// A repo can declare non-knowledge paths (e.g. a presentation/visualization layer)
+// in .kageignore. Those paths must not count as memory grounding: memory should never
+// be anchored to, or marked stale by, files the repo says are not knowledge-bearing.
+function normalizeRelPath(path) {
+    return String(path).replace(/\\/g, "/").replace(/^\/+/, "");
+}
+function isGroundingIgnored(projectDir, path) {
+    const patterns = readKageIgnore(projectDir);
+    if (!patterns.length)
+        return false;
+    return isKageIgnored(normalizeRelPath(path), patterns);
+}
+// Strip .kageignore'd paths from a packet's grounding (paths, source refs, and
+// path fingerprints). Returns a new packet if anything changed, else null.
+function prunePacketGroundingPaths(packet, patterns) {
+    if (!patterns.length)
+        return null;
+    const ignored = (p) => typeof p === "string" && isKageIgnored(normalizeRelPath(p), patterns);
+    let changed = false;
+    const paths = packet.paths.filter((p) => (ignored(p) ? ((changed = true), false) : true));
+    const sourceRefs = packet.source_refs.map((ref) => {
+        const next = { ...ref };
+        if (ignored(next.path)) {
+            delete next.path;
+            changed = true;
+        }
+        if (Array.isArray(next.changed_files)) {
+            const kept = next.changed_files.filter((f) => !ignored(f));
+            if (kept.length !== next.changed_files.length) {
+                next.changed_files = kept;
+                changed = true;
+            }
+        }
+        return next;
+    });
+    const freshness = { ...(packet.freshness ?? {}) };
+    if (Array.isArray(freshness.path_fingerprints)) {
+        const fps = freshness.path_fingerprints;
+        const kept = fps.filter((f) => !ignored(f?.path));
+        if (kept.length !== fps.length) {
+            freshness.path_fingerprints = kept;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return null;
+    return { ...packet, paths, source_refs: sourceRefs, freshness };
+}
 function wildcardPattern(pattern) {
     const escaped = pattern
         .replace(/[.+^${}()|[\]\\]/g, "\\$&")
@@ -5444,13 +5547,18 @@ function refreshPacketStaleness(projectDir) {
     const findings = [];
     let updated = 0;
     const fingerprintCache = new Map();
+    const ignorePatterns = readKageIgnore(projectDir);
     for (const entry of loadPacketEntriesFromDir(packetsDir(projectDir))) {
-        const reasons = staleMemoryReasons(projectDir, entry.packet, fingerprintCache);
-        const oldQuality = (entry.packet.quality ?? {});
-        const oldFreshness = (entry.packet.freshness ?? {});
+        // Drop any .kageignore'd grounding (presentation layers etc.) from the stored packet
+        // so memory is never anchored to non-knowledge files.
+        const pruned = prunePacketGroundingPaths(entry.packet, ignorePatterns);
+        const packet = pruned ?? entry.packet;
+        const reasons = staleMemoryReasons(projectDir, packet, fingerprintCache);
+        const oldQuality = (packet.quality ?? {});
+        const oldFreshness = (packet.freshness ?? {});
         let nextQuality;
         if (reasons.length) {
-            const finding = staleFinding(entry.packet, reasons);
+            const finding = staleFinding(packet, reasons);
             findings.push(finding);
             nextQuality = {
                 ...oldQuality,
@@ -5464,11 +5572,12 @@ function refreshPacketStaleness(projectDir) {
             nextQuality = rest;
         }
         const nextFreshness = oldFreshness;
-        const changed = JSON.stringify(oldQuality) !== JSON.stringify(nextQuality)
+        const changed = pruned !== null
+            || JSON.stringify(oldQuality) !== JSON.stringify(nextQuality)
             || JSON.stringify(oldFreshness) !== JSON.stringify(nextFreshness);
         if (changed) {
             writeJson(entry.path, {
-                ...entry.packet,
+                ...packet,
                 freshness: nextFreshness,
                 quality: nextQuality,
                 updated_at: nowIso(),
@@ -5595,8 +5704,20 @@ 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.
+// The memory recall is actively WITHHOLDING from agents right now (hard-stale:
+// cited files deleted, ttl expired, or reported stale). This is the human-facing
+// counterpart to the silent recall-time exclusion — surfaced, never hidden.
+function kageSuppressedMemory(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const cache = new Map();
+    const items = loadApprovedPackets(projectDir)
+        .map((packet) => {
+        const reason = recallHardStaleReason(projectDir, packet, cache);
+        return reason ? { id: packet.id, title: packet.title, type: packet.type, reason, paths: packet.paths } : null;
+    })
+        .filter((entry) => entry !== null);
+    return { schema_version: 1, generated_at: nowIso(), count: items.length, items };
+}
 function verifyCitations(projectDir, options = {}) {
     ensureMemoryDirs(projectDir);
     const approved = loadApprovedPackets(projectDir);
@@ -9838,6 +9959,152 @@ function qualityReport(projectDir) {
         packets: rows,
     };
 }
+// The Trust Benchmark measures what retrieval benchmarks cannot: whether the memory
+// system can be TRUSTED — does it refuse to store hallucinated citations, does it
+// withhold memory whose evidence was deleted, and is live repo memory actually grounded.
+// Controlled gates run in an isolated sandbox; the grounding gate runs on the real repo.
+function benchmarkTrust(projectDir) {
+    const runDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-trust-"));
+    const sandbox = (0, node_path_1.join)(runDir, "project");
+    try {
+        ensureMemoryDirs(sandbox);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(sandbox, "src"), { recursive: true });
+        // Gate 1 — Hallucinated-citation rejection: a strict capture whose every cited path
+        // is missing must be rejected. (No competitor validates citations at write time.)
+        const hallucinationAttempts = 8;
+        let rejected = 0;
+        for (let i = 0; i < hallucinationAttempts; i += 1) {
+            const result = capture({
+                projectDir: sandbox,
+                title: `Hallucinated rule ${i}`,
+                body: `Use the helper in src/ghost-${i}.ts for retry handling.`,
+                type: "decision",
+                paths: [`src/ghost-${i}.ts`],
+                strictCitations: true,
+            });
+            if (!result.ok)
+                rejected += 1;
+        }
+        // Gate 2 — Stale-memory exclusion: memory grounded in real files at capture time
+        // must be withheld from recall once those files are deleted (the "deleted since
+        // capture" signal). We only count memories that were recallable BEFORE deletion.
+        const staleAttempts = 8;
+        const recallableBefore = [];
+        for (let i = 0; i < staleAttempts; i += 1) {
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(sandbox, "src", `widget-${i}.ts`), `export const widget${i} = ${i};\n`, "utf8");
+            capture({
+                projectDir: sandbox,
+                title: `Widget ${i} retry invariant`,
+                body: `Widget ${i} retries use idempotency token zeta${i} in src/widget-${i}.ts to avoid duplicate charges.`,
+                type: "decision",
+                paths: [`src/widget-${i}.ts`],
+            });
+        }
+        for (let i = 0; i < staleAttempts; i += 1) {
+            const before = recall(sandbox, `widget ${i} retry idempotency token zeta${i}`, 5, false, { trackAccess: false });
+            recallableBefore[i] = before.results.some((entry) => entry.packet.title === `Widget ${i} retry invariant`);
+        }
+        for (let i = 0; i < staleAttempts; i += 1) {
+            (0, node_fs_1.rmSync)((0, node_path_1.join)(sandbox, "src", `widget-${i}.ts`), { force: true });
+        }
+        let recallableCount = 0;
+        let excludedAfter = 0;
+        for (let i = 0; i < staleAttempts; i += 1) {
+            if (!recallableBefore[i])
+                continue;
+            recallableCount += 1;
+            const after = recall(sandbox, `widget ${i} retry idempotency token zeta${i}`, 5, false, { trackAccess: false });
+            const surfaced = after.results.some((entry) => entry.packet.title === `Widget ${i} retry invariant`);
+            if (!surfaced)
+                excludedAfter += 1;
+        }
+        // Gate 3 — Live grounding: how much of the real repo's approved memory is grounded
+        // (cited files exist) and not stale.
+        const verify = verifyCitations(projectDir);
+        const liveChecked = verify.checked;
+        const grounded = verify.packets.filter((entry) => entry.grounded && !entry.stale).length;
+        const hallucinationRate = percent(rejected, hallucinationAttempts);
+        const staleRate = percent(excludedAfter, recallableCount || staleAttempts);
+        const liveGroundingRate = liveChecked > 0 ? percent(grounded, liveChecked) : 100;
+        const wrongAdvicePrevented = percent(rejected + excludedAfter, hallucinationAttempts + (recallableCount || staleAttempts));
+        const gates = [
+            { name: "hallucinated_citation_rejection", target: 100, actual: hallucinationRate, unit: "percent", pass: hallucinationRate >= 100 },
+            { name: "stale_memory_exclusion", target: 100, actual: staleRate, unit: "percent", pass: staleRate >= 100 },
+            { name: "live_grounding_rate", target: 80, actual: liveGroundingRate, unit: "percent", pass: liveGroundingRate >= 80 },
+        ];
+        const trustScore = Math.round((hallucinationRate + staleRate + liveGroundingRate) / 3);
+        return {
+            schema_version: 1,
+            generated_at: nowIso(),
+            ok: gates.every((gate) => gate.pass),
+            trust_score: trustScore,
+            gates,
+            metrics: {
+                hallucinated_citation_rejection_rate: hallucinationRate,
+                stale_memory_exclusion_rate: staleRate,
+                live_grounding_rate: liveGroundingRate,
+                wrong_advice_prevented_rate: wrongAdvicePrevented,
+            },
+            detail: {
+                hallucination: { attempted: hallucinationAttempts, rejected },
+                staleness: { recallable_before: recallableCount, excluded_after: excludedAfter },
+                live_memory: { checked: liveChecked, grounded, stale: verify.stale },
+            },
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(runDir, { recursive: true, force: true });
+    }
+}
+// `kage demo`: a self-contained 60-second proof of the trust wedge. Seeds a tiny
+// repo with grounded memory, then shows Kage (1) reject a hallucinated citation,
+// (2) withhold a memory whose cited file was deleted, and (3) recall only grounded
+// memory — the three things that make agent memory trustworthy.
+function runDemo(demoDir) {
+    (0, node_fs_1.rmSync)(demoDir, { recursive: true, force: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(demoDir, "src"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(demoDir, "src", "auth.ts"), "export function validateToken() { return true; }\n", "utf8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(demoDir, "src", "payments.ts"), "export function charge() { return 'ok'; }\n", "utf8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(demoDir, "src", "legacy-retry.ts"), "export function retry() { return 1; }\n", "utf8");
+    ensureMemoryDirs(demoDir);
+    const captured = [];
+    for (const m of [
+        { title: "Auth uses jose, not jsonwebtoken", body: "Validate tokens with jose in src/auth.ts; jsonwebtoken was removed.", paths: ["src/auth.ts"] },
+        { title: "Payments must be idempotent", body: "charge() in src/payments.ts must be idempotent to avoid double charges.", paths: ["src/payments.ts"] },
+        { title: "Legacy retry helper is the fallback", body: "Old retry logic lives in src/legacy-retry.ts and is used as a fallback.", paths: ["src/legacy-retry.ts"] },
+    ]) {
+        const r = capture({ projectDir: demoDir, title: m.title, body: m.body, type: "decision", paths: m.paths });
+        if (r.ok && r.packet)
+            captured.push(r.packet.title);
+    }
+    // (2) delete a cited file → that memory becomes stale and is withheld from recall.
+    (0, node_fs_1.unlinkSync)((0, node_path_1.join)(demoDir, "src", "legacy-retry.ts"));
+    // (1) a hallucinated citation is rejected at write time.
+    const hallucinated = capture({
+        projectDir: demoDir,
+        title: "Use the helper in src/ghost.ts",
+        body: "Retry handling lives in src/ghost.ts.",
+        type: "decision",
+        paths: ["src/ghost.ts"],
+        strictCitations: true,
+    });
+    const rejected = hallucinated.ok ? null : { title: "Use the helper in src/ghost.ts", error: hallucinated.errors[0] ?? "rejected" };
+    // (3) recall surfaces grounded memory; the stale one is withheld.
+    const recall = recallWithVectorScores(demoDir, "auth token payments retry idempotency", 5, false, { trackAccess: false });
+    const recalled = recall.results.map((entry) => entry.packet.title);
+    const withheld = kageSuppressedMemory(demoDir).items.map((item) => ({ title: item.title, reason: item.reason }));
+    const trust = benchmarkTrust(demoDir);
+    return {
+        ok: true,
+        project_dir: demoDir,
+        captured,
+        rejected_hallucination: rejected,
+        recalled,
+        withheld,
+        trust_score: trust.trust_score,
+        viewer_command: `kage viewer --project ${demoDir}`,
+    };
+}
 function benchmarkProject(projectDir, inputs = {}) {
     ensureMemoryDirs(projectDir);
     const built = inputs.codeGraph && inputs.knowledgeGraph ? null : currentOrBuildGraphs(projectDir);
@@ -10736,8 +11003,11 @@ function capture(input) {
         };
     }
     const warnings = [];
-    const meaningfulPaths = (input.paths ?? [])
-        .filter((path) => path && meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+    // .kageignore'd paths (e.g. a presentation/visualization layer) are not knowledge-bearing,
+    // so they never become grounding for a packet — dropped before validation and storage.
+    const groundedPaths = (input.paths ?? []).filter((path) => path && !isGroundingIgnored(input.projectDir, path));
+    const meaningfulPaths = groundedPaths
+        .filter((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".
@@ -10776,7 +11046,7 @@ function capture(input) {
         status: "approved",
         confidence: DEFAULT_CONFIDENCE,
         tags: input.tags ?? [],
-        paths: input.paths ?? [],
+        paths: groundedPaths,
         stack: input.stack ?? [],
         source_refs: [
             {
@@ -10788,7 +11058,7 @@ function capture(input) {
         freshness: {
             ttl_days: 365,
             last_verified_at: createdAt,
-            path_fingerprints: memoryPathFingerprints(input.projectDir, input.paths ?? []),
+            path_fingerprints: memoryPathFingerprints(input.projectDir, groundedPaths),
             path_fingerprint_policy: "source_hash_staleness",
             verification: "repo_local_agent_capture",
         },
@@ -11150,6 +11420,10 @@ elif event_name == "PreCompact":
     payload = {"type": "session_end", "summary": "Claude Code is compacting context; distill durable observations before compaction."}
 elif event_name == "SessionEnd":
     payload = {"type": "session_end", "summary": "Claude Code session ended; distill durable observations for teammate handoff."}
+elif event_name == "SubagentStop":
+    payload = {"type": "session_end", "summary": "Subagent finished; distill durable observations from the subagent run."}
+elif event_name == "PreToolUse":
+    payload = {"type": "tool_use", "tool": tool, "path": path, "command": command, "summary": "About to run: " + compact(command or tool or d, 200)}
 else:
     payload = {"type": "tool_use", "tool": tool, "path": path, "command": command, "summary": compact(d, 320), "text": compact(d)}
 
@@ -11161,7 +11435,7 @@ if [[ -n "$OBSERVATION" ]]; then
   kage observe --project "$CWD" --event "$OBSERVATION" --json >/dev/null 2>&1 || true
 fi
 
-if [[ "$EVENT" == "PreCompact" || "$EVENT" == "SessionEnd" ]]; then
+if [[ "$EVENT" == "PreCompact" || "$EVENT" == "SessionEnd" || "$EVENT" == "SubagentStop" ]]; then
   kage distill --project "$CWD" --session "$SESSION" --json >/dev/null 2>&1 || true
 fi
 
@@ -11197,11 +11471,13 @@ exit 0
             hooks: {
                 SessionStart: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/session-start.sh", timeout: 5 }] }],
                 UserPromptSubmit: [{ hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 12 }] }],
+                PreToolUse: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
                 PostToolUse: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
                 PostToolUseFailure: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
                 PreCompact: [{ hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 20 }] }],
                 Stop: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/stop.sh", timeout: 20 }] }],
                 SessionEnd: [{ hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 20 }] }],
+                SubagentStop: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 20 }] }],
             },
         };
         setSnippet(path, JSON.stringify({ mcpServers: { kage: server } }, null, 2), [
@@ -12342,11 +12618,14 @@ function prCheck(projectDir) {
     const tree = gitTree(projectDir);
     const codeInputHash = currentCodeGraphInputHash(projectDir);
     const memoryInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
-    const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
+    const fpCache = new Map();
+    const staleEntries = 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));
+        .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet, fpCache), hard: recallHardStaleReason(projectDir, packet, fpCache) !== null }))
+        .filter((entry) => entry.reasons.length);
+    const stalePackets = staleEntries.map((entry) => staleFinding(entry.packet, entry.reasons));
+    const hardStaleCount = staleEntries.filter((entry) => entry.hard).length;
+    const softStaleCount = staleEntries.length - hardStaleCount;
     const memoryPacketChanges = unique(rawStatus
         .split(/\r?\n/)
         .map(parsePorcelainPath)
@@ -12359,13 +12638,18 @@ function prCheck(projectDir) {
     const errors = [...validation.errors];
     const warnings = [...validation.warnings];
     const requiredActions = [];
-    if (stalePackets.length) {
-        errors.push(`${stalePackets.length} stale memory packet(s) require update, verification, or supersession.`);
-        requiredActions.push("Run kage refresh, then update or supersede stale packets.");
+    // Block only on hard-stale memory (cited files deleted, ttl expired, reported
+    // stale). Soft-stale ("linked code changed since capture") is normal during
+    // active development — surface it as a warning, don't fail the gate.
+    if (hardStaleCount) {
+        errors.push(`${hardStaleCount} memory packet(s) are hard-stale (deleted citations, expired ttl, or reported) and must be updated or superseded.`);
+        requiredActions.push("Run kage compact (or kage gc), then update or supersede the affected packets.");
+    }
+    if (softStaleCount) {
+        warnings.push(`${softStaleCount} memory packet(s) reference code that changed since capture — review with kage verify (not blocking).`);
     }
     if (reconciliation.unresolved_count > 0) {
-        errors.push(`${reconciliation.unresolved_count} memory reconciliation item(s) require agent update or supersession.`);
-        requiredActions.push(...reconciliation.items.slice(0, 5).map((item) => item.next_action));
+        warnings.push(`${reconciliation.unresolved_count} memory reconciliation item(s) may need update after recent code changes (review on handoff; not blocking).`);
     }
     if (!codeGraphCurrent || !memoryGraphCurrent) {
         errors.push("Generated graph artifacts are missing or not current for this working tree content.");
@@ -12373,8 +12657,7 @@ function prCheck(projectDir) {
     }
     const distillableSessions = sessions.sessions.filter((session) => session.durable_observations > 0);
     if (distillableSessions.length) {
-        errors.push(`${distillableSessions.length} distillable session learning${distillableSessions.length === 1 ? "" : "s"} require review before merge.`);
-        requiredActions.push(...distillableSessions.slice(0, 5).map((session) => session.next_action));
+        warnings.push(`${distillableSessions.length} distillable session learning${distillableSessions.length === 1 ? "" : "s"} pending review (run kage distill; not blocking).`);
     }
     if (!memoryPacketChanges.length && overlay.changed_files.some((path) => !path.startsWith(".agent_memory/"))) {
         warnings.push("No repo memory packet changed for this branch. If durable knowledge was learned, run kage propose --from-diff or kage learn.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [