npm - @kage-core/kage-graph-mcp - Versions diffs - 2.0.1 → 2.1.0 - Mend

@kage-core/kage-graph-mcp 2.0.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/cli.js CHANGED Viewed

@@ -13,6 +13,7 @@ const graph_registry_js_1 = require("./graph-registry.js");
 const CORE_USAGE = `Kage — code-grounded memory for coding agents
 Core commands:
+  kage install [--project <dir>]             one-shot: init + index + auto-wire detected agents
   kage demo                                  30-second trust demo (temp dir)
   kage scan --project <dir>                  60-second truth report on any repo (zero setup)
   kage init --project <dir>                  create repo memory (.agent_memory only)
@@ -23,6 +24,7 @@ Core commands:
   kage verify --project <dir>                check memory citations against code
   kage setup <agent> --project <dir> --write wire your agent (claude-code, codex, cursor, ...)
   kage doctor --project <dir>                health check
+  kage repair --project <dir>                fix what doctor finds (indexes, broken packets, wiring)
   kage viewer --project <dir>                local dashboard
 Run 'kage help --all' for the full command list (lifecycle, CI, benchmarks, daemon, workspace).`;
@@ -32,9 +34,11 @@ Usage:
   kage index --project <dir>
   kage scan --project <dir> [--json]
   kage demo [--project <dir>]
+  kage install [--project <dir>] [--agents a,b] [--no-agents] [--json]
   kage init --project <dir> [--with-policy]
   kage policy --project <dir>
   kage doctor --project <dir>
+  kage repair --project <dir> [--json]
   kage setup list
   kage setup <agent> --project <dir> [--write] [--json]
   kage setup doctor --project <dir> [--json]
@@ -105,7 +109,8 @@ Usage:
   kage observe --project <dir> --event <json>
   kage sessions --project <dir> [--json]
   kage replay --project <dir> [--session <id>] [--limit <n>] [--json]
-  kage distill --project <dir> --session <id>
+  kage distill --project <dir> --session <id> [--auto] [--json]
+  kage resume --project <dir> [--json]
   kage learn --project <dir> --learning <text> [--title <title>] [--type <type>] [--evidence <text>] [--verified-by <text>] [--tags a,b] [--paths a,b] [--graph-nodes a,b] [--allow-missing-paths]
   kage feedback --project <dir> --packet <packet-id> --kind helpful|wrong|stale
   kage capture --project <dir> --title <title> --body <body> [--type <type>] [--summary <summary>] [--tags a,b] [--paths a,b] [--stack a,b] [--graph-nodes a,b] [--allow-missing-paths]
@@ -311,6 +316,72 @@ async function main() {
             process.exit(2);
         return;
     }
+    if (command === "install") {
+        const project = projectArg(args);
+        const agentsFlag = takeArg(args, "--agents");
+        const skipAgents = args.includes("--no-agents");
+        const json = args.includes("--json");
+        const home = (0, node_os_1.homedir)();
+        // Detection is config-dir presence, not PATH: agents like Cursor never expose a binary.
+        const probes = [
+            { agent: "claude-code", paths: [(0, node_path_1.join)(home, ".claude.json"), (0, node_path_1.join)(home, ".claude")] },
+            { agent: "codex", paths: [(0, node_path_1.join)(home, ".codex")] },
+            { agent: "cursor", paths: [(0, node_path_1.join)(home, ".cursor")] },
+            { agent: "windsurf", paths: [(0, node_path_1.join)(home, ".codeium", "windsurf")] },
+            { agent: "gemini-cli", paths: [(0, node_path_1.join)(home, ".gemini")] },
+            { agent: "opencode", paths: [(0, node_path_1.join)(home, ".config", "opencode"), (0, node_path_1.join)(home, ".opencode")] },
+            { agent: "goose", paths: [(0, node_path_1.join)(home, ".config", "goose")] },
+            { agent: "aider", paths: [(0, node_path_1.join)(home, ".aider.conf.yml")] },
+        ];
+        const requested = agentsFlag
+            ? agentsFlag.split(",").map((a) => a.trim()).filter((a) => kernel_js_1.SETUP_AGENTS.includes(a))
+            : null;
+        const detected = requested ?? probes.filter((p) => p.paths.some((path) => (0, node_fs_1.existsSync)(path))).map((p) => p.agent);
+        const init = (0, kernel_js_1.initProject)(project, { policy: false });
+        const wired = [];
+        if (!skipAgents) {
+            for (const agent of detected) {
+                try {
+                    const result = (0, kernel_js_1.setupAgent)(agent, project, { write: true });
+                    wired.push({ agent, ok: result.wrote, config_path: result.config_path ?? undefined, error: result.wrote || result.write_supported ? undefined : `config is print-only — run: kage setup ${agent} --project . and paste it` });
+                }
+                catch (error) {
+                    wired.push({ agent, ok: false, error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+        }
+        if (json) {
+            console.log(JSON.stringify({ project_dir: init.index.projectDir, packets: init.index.packets, validation_ok: init.validation.ok, agents: wired }, null, 2));
+            if (!init.validation.ok)
+                process.exit(2);
+            return;
+        }
+        console.log(`Kage installed in ${init.index.projectDir}\n`);
+        console.log("  Memory      .agent_memory/ created — packets are plain files, reviewable in git");
+        console.log(`  Indexes     ${init.index.indexes.length} built (code graph, recall, structure)`);
+        if (skipAgents) {
+            console.log("  Agents      skipped (--no-agents)");
+        }
+        else if (!wired.length) {
+            console.log("  Agents      none detected — wire one manually: kage setup <agent> --project . --write");
+        }
+        else {
+            for (const w of wired) {
+                if (w.ok)
+                    console.log(`  Agents      ${w.agent} ✓ wired${w.config_path ? ` (${w.config_path})` : ""}`);
+                else
+                    console.log(`  Agents      ${w.agent} ✗ ${w.error ?? "print-only; run kage setup " + w.agent + " --project . --write"}`);
+            }
+        }
+        console.log("\nNext:");
+        console.log("  restart your agent — memory now recalls automatically at session start");
+        console.log("  kage scan --project .      60-second Truth Report on this repo");
+        console.log("  kage viewer --project .    local dashboard (gains, packets, graph)");
+        console.log("\nVersion control: commit .agent_memory/packets/, ignore .agent_memory/indexes/ and reports/.");
+        if (!init.validation.ok)
+            process.exit(2);
+        return;
+    }
     if (command === "policy") {
         const result = (0, kernel_js_1.installAgentPolicy)(projectArg(args));
         console.log(`${result.created ? "Created" : result.updated ? "Updated" : "Already current"} agent policy: ${result.path}`);
@@ -340,7 +411,36 @@ async function main() {
             console.log(`Warnings:\n${result.validation.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         console.log("\nRecall smoke test:\n");
         console.log(result.sampleRecall);
-        if (!result.validation.ok)
+        if (!result.validation.ok) {
+            console.log("\nSomething broken? kage repair --project .");
+            process.exit(2);
+        }
+        return;
+    }
+    if (command === "repair") {
+        const result = (0, kernel_js_1.repairProject)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.ok || !result.validation.ok)
+                process.exit(2);
+            return;
+        }
+        console.log(`Kage repair — ${result.project_dir}\n`);
+        const areaLabel = { packets: "Memory", indexes: "Indexes", locks: "Locks", agents: "Agents" };
+        for (const action of result.actions) {
+            const mark = action.status === "fixed" ? "✓" : action.status === "failed" ? "✗" : "•";
+            console.log(`  ${(areaLabel[action.area] ?? action.area).padEnd(12)}${mark} ${action.target} — ${action.detail}`);
+        }
+        console.log(`\n${result.fixed} fixed, ${result.skipped} already healthy, ${result.failed} failed`);
+        if (result.removed_packets.length) {
+            console.log(`\nRemoved ${result.removed_packets.length} unrecoverable packet(s) — backups kept in .agent_memory/backup/:`);
+            for (const removed of result.removed_packets)
+                console.log(`  ${removed}`);
+        }
+        console.log(result.validation.ok ? "Validation: passed" : "Validation: still failing");
+        if (result.validation.errors.length)
+            console.log(`Errors:\n${result.validation.errors.map((error) => `  - ${error}`).join("\n")}`);
+        if (!result.ok || !result.validation.ok)
             process.exit(2);
         return;
     }
@@ -1831,9 +1931,18 @@ async function main() {
         const sessionId = takeArg(args, "--session");
         if (!sessionId)
             usage();
-        const result = (0, kernel_js_1.distillSession)(projectArg(args), sessionId);
+        const project = projectArg(args);
+        const auto = args.includes("--auto");
+        const result = (0, kernel_js_1.distillSession)(project, sessionId, { auto });
         if (args.includes("--json"))
             console.log(JSON.stringify(result, null, 2));
+        else if (auto) {
+            // Auto mode is quiet: no output for empty or already-captured sessions; one line otherwise.
+            const drafted = result.candidates.filter((candidate) => candidate.ok).length;
+            if (!result.skipped_reason && drafted > 0) {
+                console.log(`Auto-distilled ${drafted} pending draft${drafted === 1 ? "" : "s"} from session ${sessionId}. Review with: kage review --project ${project}`);
+            }
+        }
         else {
             console.log(`Distilled session: ${sessionId}`);
             console.log(`Observations: ${result.observations}`);
@@ -1841,10 +1950,21 @@ async function main() {
             if (result.errors.length)
                 console.log(`Errors:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
         }
-        if (!result.ok)
+        if (!result.ok && !auto)
             process.exit(2);
         return;
     }
+    if (command === "resume") {
+        const result = (0, kernel_js_1.kageResume)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        // Prints nothing when there is no prior session data, so hooks can append output verbatim.
+        if (result.has_content && result.context_block)
+            console.log(result.context_block);
+        return;
+    }
     if (command === "feedback") {
         const id = takeArg(args, "--packet");
         const kind = takeArg(args, "--kind");
@@ -1936,7 +2056,10 @@ async function main() {
     }
     usage();
 }
+// Remediation-first failure: lead with the message, follow with exactly ONE
+// copy-pasteable next command. Exit code stays 1, same as before.
 main().catch((error) => {
-    console.error(error);
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error(`\nTry:\n  ${(0, kernel_js_1.remediationFor)(error)}`);
     process.exit(1);
 });

package/dist/daemon.js CHANGED Viewed

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.viewerStaticHeaders = viewerStaticHeaders;
 exports.viewerRedirectLocation = viewerRedirectLocation;
 exports.viewerReportPaths = viewerReportPaths;
+exports.startLiveFeed = startLiveFeed;
 exports.viewerUrl = viewerUrl;
 exports.viewerBenchmarkReport = viewerBenchmarkReport;
 exports.daemonContextReport = daemonContextReport;
@@ -105,6 +106,152 @@ function viewerReportPaths(projectRoot) {
         value: (0, node_path_1.join)(reportsDir, "value.json"),
     };
 }
+const LIVE_FEED_HEARTBEAT_MS = 25_000;
+const LIVE_FEED_DEBOUNCE_MS = 100;
+function readPacketTitle(filePath) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf8"));
+        return typeof parsed.title === "string" && parsed.title ? parsed.title : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Streams memory/value activity to viewer clients over SSE (GET /kage/events).
+// The engine already writes packets and the value ledger to .agent_memory/, so a
+// filesystem watch is the lightest possible event source — no queue, no new deps.
+function startLiveFeed(projectRoot, options = {}) {
+    const heartbeatMs = options.heartbeatMs ?? LIVE_FEED_HEARTBEAT_MS;
+    const debounceMs = options.debounceMs ?? LIVE_FEED_DEBOUNCE_MS;
+    const packetsDir = (0, node_path_1.join)(projectRoot, ".agent_memory", "packets");
+    const reportsDir = (0, node_path_1.join)(projectRoot, ".agent_memory", "reports");
+    const valuePath = (0, node_path_1.join)(reportsDir, "value.json");
+    const clients = new Set();
+    const watchers = [];
+    const timers = new Map();
+    const knownPackets = new Set();
+    try {
+        (0, node_fs_1.mkdirSync)(packetsDir, { recursive: true });
+        for (const name of (0, node_fs_1.readdirSync)(packetsDir))
+            knownPackets.add(name);
+    }
+    catch {
+        // packets dir unavailable: packet events simply won't fire
+    }
+    function readValueEvents() {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(valuePath, "utf8"));
+            return Array.isArray(parsed.events) ? parsed.events : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    let seenValueEvents = readValueEvents().length;
+    function broadcast(event) {
+        const payload = `data: ${JSON.stringify(event)}\n\n`;
+        for (const res of clients)
+            res.write(payload);
+    }
+    function onPacketChange(name) {
+        const filePath = (0, node_path_1.join)(packetsDir, name);
+        if (!(0, node_fs_1.existsSync)(filePath)) {
+            knownPackets.delete(name);
+            return;
+        }
+        const isNew = !knownPackets.has(name);
+        knownPackets.add(name);
+        broadcast({
+            type: isNew ? "packet_written" : "packet_updated",
+            title: readPacketTitle(filePath) ?? name.replace(/\.json$/, ""),
+            path: (0, node_path_1.join)(".agent_memory", "packets", name),
+            ts: new Date().toISOString(),
+        });
+    }
+    function onValueChange() {
+        const events = readValueEvents();
+        if (events.length < seenValueEvents)
+            seenValueEvents = 0; // ledger trimmed or rewritten
+        for (const event of events.slice(seenValueEvents)) {
+            broadcast({
+                type: "value_event",
+                title: typeof event.packet_title === "string" ? event.packet_title : undefined,
+                path: (0, node_path_1.join)(".agent_memory", "reports", "value.json"),
+                event,
+                ts: typeof event.at === "string" ? event.at : new Date().toISOString(),
+            });
+        }
+        seenValueEvents = events.length;
+    }
+    // fs.watch fires bursts of duplicate events for one logical write; collapse
+    // them per file with a short debounce before reading and broadcasting.
+    function debounced(key, run) {
+        const existing = timers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        timers.set(key, setTimeout(() => {
+            timers.delete(key);
+            try {
+                run();
+            }
+            catch {
+                // keep the feed alive even if a read races a write
+            }
+        }, debounceMs));
+    }
+    try {
+        watchers.push((0, node_fs_1.watch)(packetsDir, (_event, filename) => {
+            const name = String(filename ?? "");
+            if (!name.endsWith(".json"))
+                return;
+            debounced(`packet:${name}`, () => onPacketChange(name));
+        }));
+    }
+    catch {
+        // packets dir missing: no packet events
+    }
+    try {
+        (0, node_fs_1.mkdirSync)(reportsDir, { recursive: true });
+        watchers.push((0, node_fs_1.watch)(reportsDir, (_event, filename) => {
+            if (String(filename ?? "") !== "value.json")
+                return;
+            debounced("value", onValueChange);
+        }));
+    }
+    catch {
+        // reports dir missing: no value events
+    }
+    const heartbeat = setInterval(() => {
+        for (const res of clients)
+            res.write(`: heartbeat ${Date.now()}\n\n`);
+    }, heartbeatMs);
+    heartbeat.unref();
+    function handleRequest(req, res) {
+        res.writeHead(200, {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache, no-transform",
+            connection: "keep-alive",
+            "x-accel-buffering": "no",
+        });
+        res.write(": connected\n\n");
+        clients.add(res);
+        req.on("close", () => {
+            clients.delete(res);
+        });
+    }
+    function close() {
+        clearInterval(heartbeat);
+        for (const timer of timers.values())
+            clearTimeout(timer);
+        timers.clear();
+        for (const watcher of watchers)
+            watcher.close();
+        for (const res of clients)
+            res.end();
+        clients.clear();
+    }
+    return { handleRequest, broadcast, clientCount: () => clients.size, close };
+}
 function viewerUrl(host, port, projectRoot) {
     const query = Object.entries(viewerReportPaths(projectRoot))
         .map(([name, path]) => `${name}=${encodeURIComponent(path)}`)
@@ -633,8 +780,13 @@ async function startViewer(projectDir, options = {}) {
         // non-fatal: viewer will show 404 for reports if generation fails
     }
     const url = viewerUrl(host, port, projectRoot);
+    const liveFeed = startLiveFeed(projectRoot);
     const server = (0, node_http_1.createServer)((req, res) => {
         const requestUrl = new URL(req.url ?? "/", `http://${host}:${port}`);
+        if (req.method === "GET" && requestUrl.pathname === "/kage/events") {
+            liveFeed.handleRequest(req, res);
+            return;
+        }
         let filePath = null;
         const redirectLocation = viewerRedirectLocation(requestUrl.pathname, requestUrl.search, new URL(url).search);
         if (redirectLocation) {
@@ -673,6 +825,7 @@ async function startViewer(projectDir, options = {}) {
     await new Promise((resolveListen) => server.listen(port, host, resolveListen));
     console.log(`Kage viewer listening on ${url}`);
     process.on("SIGTERM", () => {
+        liveFeed.close();
         server.close(() => process.exit(0));
     });
     return { ok: true, project_dir: projectRoot, host, port, url };

package/dist/kernel.js CHANGED Viewed

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SETUP_AGENTS = exports.MEMORY_TYPES = exports.PACKET_SCHEMA_VERSION = void 0;
+exports.AUTO_DISTILL_TAG = exports.SETUP_AGENTS = exports.MEMORY_TYPES = exports.PACKET_SCHEMA_VERSION = void 0;
 exports.memoryRoot = memoryRoot;
 exports.packetsDir = packetsDir;
 exports.pendingDir = pendingDir;
@@ -70,6 +70,7 @@ exports.kageMemoryReconciliation = kageMemoryReconciliation;
 exports.evaluateMemoryAdmission = evaluateMemoryAdmission;
 exports.validatePacket = validatePacket;
 exports.scanSensitiveText = scanSensitiveText;
+exports.stripPrivateSpans = stripPrivateSpans;
 exports.catalogDomainNodeCount = catalogDomainNodeCount;
 exports.ensureMemoryDirs = ensureMemoryDirs;
 exports.loadApprovedPackets = loadApprovedPackets;
@@ -140,6 +141,7 @@ exports.kageSessionCaptureReport = kageSessionCaptureReport;
 exports.kageSessionReplay = kageSessionReplay;
 exports.kageSessionLearningLedger = kageSessionLearningLedger;
 exports.distillSession = distillSession;
+exports.kageResume = kageResume;
 exports.proposeFromDiff = proposeFromDiff;
 exports.buildBranchOverlay = buildBranchOverlay;
 exports.createReviewArtifact = createReviewArtifact;
@@ -155,6 +157,9 @@ exports.recordFeedback = recordFeedback;
 exports.validateProject = validateProject;
 exports.initProject = initProject;
 exports.doctorProject = doctorProject;
+exports.splitConflictSides = splitConflictSides;
+exports.repairProject = repairProject;
+exports.remediationFor = remediationFor;
 exports.approvePending = approvePending;
 exports.rejectPending = rejectPending;
 exports.changelog = changelog;
@@ -1784,6 +1789,28 @@ function scanSensitiveText(text) {
     ];
     return patterns.filter(([, pattern]) => pattern.test(text)).map(([name]) => name);
 }
+// Privacy tags: anything wrapped in <private>...</private> is redacted to
+// "[private]" BEFORE a packet or observation is written, so the content never
+// reaches disk. Matching is case-insensitive and spans newlines; an unclosed
+// <private> redacts to the end of the string so a malformed tag cannot leak.
+const PRIVATE_SPAN_PATTERN = /<private>[\s\S]*?(?:<\/private>|$)/gi;
+function stripPrivateSpans(text) {
+    if (!text || text.toLowerCase().indexOf("<private>") === -1)
+        return text;
+    return text.replace(PRIVATE_SPAN_PATTERN, "[private]");
+}
+function stripPrivateFromContext(context) {
+    const sanitized = { ...context };
+    for (const key of ["fact", "why", "trigger", "action", "verification", "risk_if_forgotten", "stale_when"]) {
+        const value = sanitized[key];
+        if (typeof value === "string")
+            sanitized[key] = stripPrivateSpans(value);
+    }
+    if (sanitized.rejected_alternatives) {
+        sanitized.rejected_alternatives = sanitized.rejected_alternatives.map((entry) => stripPrivateSpans(entry));
+    }
+    return sanitized;
+}
 function catalogDomainNodeCount(domain) {
     return domain.nodes ?? domain.node_count ?? 0;
 }
@@ -1861,8 +1888,11 @@ function loadApprovedPackets(projectDir) {
 function loadPendingPackets(projectDir) {
     return loadPacketsFromDir(pendingDir(projectDir));
 }
+// Hook-driven auto-distilled drafts carry this tag so they are distinguishable from
+// agent-reviewed memory and never surface in recall until a human or agent approves them.
+exports.AUTO_DISTILL_TAG = "auto-distill";
 function recallablePendingPackets(projectDir) {
-    return loadPendingPackets(projectDir).filter((packet) => !packet.tags.includes("diff-proposal"));
+    return loadPendingPackets(projectDir).filter((packet) => !packet.tags.includes("diff-proposal") && !packet.tags.includes(exports.AUTO_DISTILL_TAG));
 }
 function writePacket(projectDir, packet, statusDir) {
     const dir = statusDir === "packets" ? packetsDir(projectDir) : pendingDir(projectDir);
@@ -11951,6 +11981,15 @@ function hasStructuredEngineeringContext(packet) {
     return Boolean(context.why || context.verification || context.risk_if_forgotten || context.stale_when || context.trigger || context.action);
 }
 function learn(input) {
+    // Redact <private> spans before deriving the title/summary so private text
+    // never leaks into derived fields; capture() re-applies the same sanitizer.
+    input = {
+        ...input,
+        learning: stripPrivateSpans(input.learning),
+        title: input.title === undefined ? undefined : stripPrivateSpans(input.title),
+        evidence: input.evidence === undefined ? undefined : stripPrivateSpans(input.evidence),
+        verifiedBy: input.verifiedBy === undefined ? undefined : stripPrivateSpans(input.verifiedBy),
+    };
     const type = inferLearningType(input);
     const title = input.title?.trim() || titleFromLearning(input.learning);
     const body = [
@@ -11971,10 +12010,20 @@ function learn(input) {
         allowMissingPaths: input.allowMissingPaths,
         strictCitations: input.strictCitations,
         graphNodes: input.graphNodes,
+        pendingReview: input.pendingReview,
     });
 }
 function capture(input) {
     ensureMemoryDirs(input.projectDir);
+    // Privacy tags: redact <private> spans from every text field before any
+    // validation, scanning, or storage — private content must never hit disk.
+    input = {
+        ...input,
+        title: stripPrivateSpans(input.title),
+        summary: input.summary === undefined ? undefined : stripPrivateSpans(input.summary),
+        body: stripPrivateSpans(input.body),
+        context: input.context ? stripPrivateFromContext(input.context) : input.context,
+    };
     const type = input.type ?? "reference";
     if (!exports.MEMORY_TYPES.includes(type)) {
         return { ok: false, errors: [`Invalid memory type: ${type}`] };
@@ -12027,7 +12076,7 @@ function capture(input) {
         scope: "repo",
         visibility: "team",
         sensitivity: "internal",
-        status: "approved",
+        status: input.pendingReview ? "pending" : "approved",
         confidence: DEFAULT_CONFIDENCE,
         tags: input.tags ?? [],
         paths: groundedPaths,
@@ -12068,7 +12117,7 @@ function capture(input) {
         ...packet.quality,
         ...evaluateMemoryQuality(input.projectDir, packet),
     };
-    const path = writePacket(input.projectDir, packet, "packets");
+    const path = writePacket(input.projectDir, packet, input.pendingReview ? "pending" : "packets");
     recordMemoryAudit(input.projectDir, "capture", [packet], {
         type: packet.type,
         status: packet.status,
@@ -12297,6 +12346,16 @@ Before finishing a task that changed files: kage_pr_summarize or kage_propose_fr
 If recalled memory helped: kage_feedback helpful. If wrong or stale: kage_feedback wrong or stale."
 fi
+# Session continuity: append a compact "previously…" digest when prior session data exists.
+if command -v kage >/dev/null 2>&1; then
+  PREVIOUSLY="$(kage resume --project "$CWD" 2>/dev/null || true)"
+  if [[ -n "$PREVIOUSLY" ]]; then
+    POLICY="$POLICY
+$PREVIOUSLY"
+  fi
+fi
 KAGE_MSG="$POLICY" python3 -c "import json,os; print(json.dumps({'systemMessage': os.environ['KAGE_MSG']}))"
 `;
         const stopHookScript = `#!/usr/bin/env bash
@@ -12333,6 +12392,20 @@ print(d.get("agent_instruction") or "Kage memory reconciliation required before
   fi
 fi
+# Automatic capture fallback: if this session recorded observations but produced no new
+# memory packets, quietly distill them into pending drafts for later review. Best-effort;
+# kage distill --auto is silent on empty or already-captured sessions and never blocks.
+SESSION="$(printf "%s" "$PAYLOAD" | python3 -c 'import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    d = {}
+print(d.get("session_id") or d.get("sessionId") or "")
+' 2>/dev/null || echo "")"
+if [[ -n "$SESSION" && -d "$CWD/.agent_memory/observations" ]]; then
+  kage distill --project "$CWD" --session "$SESSION" --auto --json >/dev/null 2>&1 || true
+fi
 exit 0
 `;
         const observeHookScript = `#!/usr/bin/env bash
@@ -12742,6 +12815,14 @@ function observationHash(projectDir, event) {
 }
 function observe(projectDir, event) {
     ensureMemoryDirs(projectDir);
+    // Privacy tags: redact <private> spans from free-text fields before hashing,
+    // scanning, or persisting the observation record.
+    event = {
+        ...event,
+        text: event.text === undefined ? undefined : stripPrivateSpans(event.text),
+        summary: event.summary === undefined ? undefined : stripPrivateSpans(event.summary),
+        command: event.command === undefined ? undefined : stripPrivateSpans(event.command),
+    };
     const allowed = ["session_start", "user_prompt", "tool_use", "tool_result", "file_change", "command_result", "test_result", "session_end"];
     if (!allowed.includes(event.type))
         return { ok: false, stored: false, duplicate: false, errors: [`Invalid observation type: ${event.type}`] };
@@ -13244,8 +13325,32 @@ function kageSessionLearningLedger(projectDir, options = {}) {
         context_block: learningLedgerContextBlock(reportWithoutBlock),
     };
 }
-function distillSession(projectDir, sessionId) {
+// Mechanical packets (branch change memory, prior auto-distilled drafts) never count as the
+// agent having captured memory; only deliberate captures/learns/distills suppress the
+// Stop-hook auto-distill fallback.
+function sessionAlreadyCaptured(projectDir, sessionId, observations) {
+    const firstAt = observations[0]?.timestamp ?? "";
+    const mechanicalTags = ["diff-proposal", "change-memory", exports.AUTO_DISTILL_TAG];
+    return [...loadApprovedPackets(projectDir), ...loadPendingPackets(projectDir)].some((packet) => {
+        if (packet.source_refs.some((ref) => ref.kind === "observation_session" && ref.session_id === sessionId))
+            return true;
+        if (packet.type === "repo_map" || packet.quality?.reviewer === "kage-indexer")
+            return false; // generated by indexing
+        if (packet.tags.some((tag) => mechanicalTags.includes(tag)))
+            return false;
+        return Boolean(firstAt) && packet.created_at >= firstAt;
+    });
+}
+function distillSession(projectDir, sessionId, options = {}) {
+    const auto = Boolean(options.auto);
+    const mode = auto ? "auto" : "manual";
     const observations = loadObservations(projectDir, sessionId);
+    if (auto && observations.length === 0) {
+        return { ok: true, session_id: sessionId, observations: 0, candidates: [], errors: [], mode, skipped_reason: "no_observations" };
+    }
+    if (auto && sessionAlreadyCaptured(projectDir, sessionId, observations)) {
+        return { ok: true, session_id: sessionId, observations: observations.length, candidates: [], errors: [], mode, skipped_reason: "session_already_captured" };
+    }
     const candidates = [];
     const errors = [];
     const observationIds = observations.map((event) => event.id);
@@ -13262,13 +13367,14 @@ function distillSession(projectDir, sessionId) {
         ];
         result.packet.quality = {
             ...result.packet.quality,
-            distillation: "automatic_observation_candidate",
+            distillation: auto ? "auto_distill" : "automatic_observation_candidate",
             admission: evaluateMemoryAdmission(projectDir, result.packet),
             suggested_review_action: suggestedAction(classifyPacket(projectDir, result.packet), result.packet.status),
         };
         writeJson(result.path, result.packet);
         return result;
     };
+    const autoTags = auto ? [exports.AUTO_DISTILL_TAG] : [];
     const commandEvents = observations.filter((event) => event.type === "command_result" && event.command);
     const fileEvents = observations.filter((event) => event.type === "file_change" && event.path);
     const promptEvents = observations.filter((event) => event.type === "user_prompt" && (event.text || event.summary));
@@ -13284,8 +13390,9 @@ function distillSession(projectDir, sessionId) {
             summary: `Observed commands: ${commands.slice(0, 3).join(", ")}`,
             body: `Reusable command observation distilled from session ${sessionId}:\n\n${meaningfulCommandEvents.map((item) => `- ${item.reusable.command}: ${item.reusable.learning}`).join("\n")}\n\nReview before approving as a durable runbook.`,
             type: "runbook",
-            tags: ["observed-session", "commands", "runbook"],
+            tags: ["observed-session", "commands", "runbook", ...autoTags],
             paths: unique(meaningfulCommandEvents.map((item) => item.event.path).filter(Boolean)),
+            pendingReview: auto,
         })));
     }
     const meaningfulFileEvents = fileEvents
@@ -13300,8 +13407,9 @@ function distillSession(projectDir, sessionId) {
             summary: lead,
             body: `Reusable file observation distilled from session ${sessionId}:\n\n${meaningfulFileEvents.map((item) => `- ${item.event.path}: ${item.learning}`).join("\n")}\n\nReview before approving as durable repo memory.`,
             type: "workflow",
-            tags: ["observed-session", "workflow"],
+            tags: ["observed-session", "workflow", ...autoTags],
             paths,
+            pendingReview: auto,
         })));
     }
     if (promptEvents.length) {
@@ -13312,13 +13420,94 @@ function distillSession(projectDir, sessionId) {
                 title: titleFromLearning(text),
                 learning: text,
                 evidence: `Observation session: ${sessionId}`,
-                tags: ["observed-session", "intent"],
+                tags: ["observed-session", "intent", ...autoTags],
+                pendingReview: auto,
             })));
     }
     for (const result of candidates)
         if (!result.ok)
             errors.push(...result.errors);
-    return { ok: errors.length === 0, session_id: sessionId, observations: observations.length, candidates, errors };
+    return { ok: errors.length === 0, session_id: sessionId, observations: observations.length, candidates, errors, mode };
+}
+// Session continuity: a compact "previously…" digest the SessionStart hook injects so a new
+// session starts with last session's context instead of cold. Empty when there is no prior data.
+function kageResume(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const pending = loadPendingPackets(projectDir);
+    const observations = loadObservations(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 latestRows = Array.from(bySession.values())
+        .sort((a, b) => (b.at(-1)?.timestamp ?? "").localeCompare(a.at(-1)?.timestamp ?? ""))[0];
+    const lastSession = latestRows?.length
+        ? (() => {
+            const sessionId = latestRows[0].session_id;
+            const distilledTitles = [...approved, ...pending]
+                .filter((packet) => packet.source_refs.some((ref) => ref.kind === "observation_session" && ref.session_id === sessionId))
+                .map((packet) => packet.title);
+            return {
+                session_id: sessionId,
+                first_at: latestRows[0]?.timestamp ?? "",
+                last_at: latestRows.at(-1)?.timestamp ?? "",
+                observations: latestRows.length,
+                paths: unique(latestRows.map((event) => event.path).filter(Boolean)).slice(0, 6),
+                commands: unique(latestRows.map((event) => event.command).filter(Boolean)).slice(0, 3),
+                distilled_titles: unique(distilledTitles).slice(0, 3),
+            };
+        })()
+        : undefined;
+    const changeMemory = approved
+        .filter((packet) => packet.tags.includes("change-memory"))
+        .sort((a, b) => b.updated_at.localeCompare(a.updated_at))[0];
+    const lastChangeMemory = changeMemory
+        ? { id: changeMemory.id, title: changeMemory.title, summary: changeMemory.summary, updated_at: changeMemory.updated_at }
+        : undefined;
+    const pendingAutoDistilled = pending.filter((packet) => packet.tags.includes(exports.AUTO_DISTILL_TAG)).length;
+    const reconciliation = kageMemoryReconciliation(projectDir, { limit: 5 });
+    const reconciliationItems = reconciliation.items.map((item) => ({ packet_id: item.packet_id, title: item.title }));
+    const hasContent = Boolean(lastSession || lastChangeMemory || pendingAutoDistilled || reconciliation.unresolved_count);
+    const lines = [];
+    if (hasContent) {
+        lines.push("# Previously (Kage)");
+        if (lastSession) {
+            lines.push(`Last session ${lastSession.session_id} (${lastSession.observations} observation${lastSession.observations === 1 ? "" : "s"}, ended ${lastSession.last_at}).`);
+            if (lastSession.paths.length)
+                lines.push(`Worked on: ${lastSession.paths.join(", ")}`);
+            if (lastSession.commands.length)
+                lines.push(`Commands: ${lastSession.commands.join("; ")}`);
+            if (lastSession.distilled_titles.length)
+                lines.push(`Learned: ${lastSession.distilled_titles.join("; ")}`);
+        }
+        if (lastChangeMemory) {
+            lines.push(`Change memory: ${lastChangeMemory.title} — ${lastChangeMemory.summary}`);
+        }
+        if (pendingAutoDistilled) {
+            lines.push(`Pending: ${pendingAutoDistilled} auto-distilled draft${pendingAutoDistilled === 1 ? "" : "s"} awaiting review — run: kage review --project ${projectDir}`);
+        }
+        if (reconciliation.unresolved_count) {
+            lines.push(`Reconcile: ${reconciliation.unresolved_count} linked memory item${reconciliation.unresolved_count === 1 ? "" : "s"} need update — run: kage reconcile --project ${projectDir}`);
+            for (const item of reconciliationItems.slice(0, 3))
+                lines.push(`  - ${item.packet_id}: ${item.title}`);
+        }
+    }
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        has_content: hasContent,
+        last_session: lastSession,
+        last_change_memory: lastChangeMemory,
+        pending_auto_distilled: pendingAutoDistilled,
+        pending_total: pending.length,
+        ...(pendingAutoDistilled ? { review_command: `kage review --project ${projectDir}` } : {}),
+        reconciliation: { unresolved_count: reconciliation.unresolved_count, items: reconciliationItems },
+        context_block: lines.slice(0, 15).join("\n"),
+    };
 }
 function createDiffChangeMemory(projectDir, summary) {
     const branch = summary.branch ?? "detached";
@@ -14234,6 +14423,279 @@ function doctorProject(projectDir) {
         sampleRecall: sampleRecall.context_block,
     };
 }
+function repairBackupDir(projectDir) {
+    return (0, node_path_1.join)(memoryRoot(projectDir), "backup");
+}
+// Split a git merge-conflicted file into its two sides. Returns null when no
+// complete conflict block is present. diff3-style base sections (`|||||||`)
+// belong to neither side and are dropped.
+function splitConflictSides(content) {
+    let section = "both";
+    let conflicts = 0;
+    const ours = [];
+    const theirs = [];
+    for (const line of content.split("\n")) {
+        if (section === "both" && /^<{7}(\s|$)/.test(line)) {
+            section = "ours";
+            conflicts += 1;
+            continue;
+        }
+        if (section === "ours" && /^\|{7}(\s|$)/.test(line)) {
+            section = "base";
+            continue;
+        }
+        if ((section === "ours" || section === "base") && /^={7}$/.test(line.trimEnd())) {
+            section = "theirs";
+            continue;
+        }
+        if (section === "theirs" && /^>{7}(\s|$)/.test(line)) {
+            section = "both";
+            continue;
+        }
+        if (section === "both") {
+            ours.push(line);
+            theirs.push(line);
+        }
+        else if (section === "ours")
+            ours.push(line);
+        else if (section === "theirs")
+            theirs.push(line);
+    }
+    if (!conflicts || section !== "both")
+        return null;
+    return { ours: ours.join("\n"), theirs: theirs.join("\n") };
+}
+function packetRecency(packet) {
+    return String(packet.updated_at ?? packet.created_at ?? "");
+}
+// Auto-resolve a merge-conflicted packet by keeping the newest side — but only
+// when that side parses as JSON. Anything less certain stays a removal.
+function resolveConflictedPacket(content) {
+    const sides = splitConflictSides(content);
+    if (!sides)
+        return null;
+    const candidates = [];
+    for (const side of [sides.ours, sides.theirs]) {
+        try {
+            const parsed = JSON.parse(side);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                candidates.push(parsed);
+        }
+        catch {
+            // This side does not parse; the other side may still win.
+        }
+    }
+    if (!candidates.length)
+        return null;
+    candidates.sort((a, b) => packetRecency(b).localeCompare(packetRecency(a)));
+    return candidates[0];
+}
+function repairProject(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const actions = [];
+    const removedPackets = [];
+    let packetsTouched = false;
+    // 1. Unparseable packet JSON (merge conflicts, torn writes, hand edits).
+    //    Always back up the broken original before changing anything.
+    let brokenFound = 0;
+    const packetDirs = [
+        [packetsDir(projectDir), "packets"],
+        [pendingDir(projectDir), "pending"],
+        [publicCandidatesDir(projectDir), "public-candidates"],
+    ];
+    for (const [dir, label] of packetDirs) {
+        for (const path of walkFiles(dir, (candidate) => candidate.endsWith(".json"))) {
+            const target = `${label}/${(0, node_path_1.basename)(path)}`;
+            let raw;
+            try {
+                raw = (0, node_fs_1.readFileSync)(path, "utf8");
+            }
+            catch (error) {
+                actions.push({ area: "packets", target, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+                continue;
+            }
+            try {
+                JSON.parse(raw);
+                continue; // healthy packet
+            }
+            catch {
+                // fall through to repair
+            }
+            brokenFound += 1;
+            try {
+                ensureDir(repairBackupDir(projectDir));
+                const backupPath = (0, node_path_1.join)(repairBackupDir(projectDir), `${(0, node_path_1.basename)(path)}.broken`);
+                (0, node_fs_1.writeFileSync)(backupPath, raw, "utf8");
+                const resolved = resolveConflictedPacket(raw);
+                if (resolved) {
+                    writeJson(path, resolved);
+                    packetsTouched = true;
+                    actions.push({
+                        area: "packets",
+                        target,
+                        status: "fixed",
+                        detail: `merge conflict auto-resolved, kept newest side — original saved to ${(0, node_path_1.relative)(projectDir, backupPath)}`,
+                    });
+                }
+                else {
+                    (0, node_fs_1.unlinkSync)(path);
+                    packetsTouched = true;
+                    removedPackets.push(target);
+                    actions.push({
+                        area: "packets",
+                        target,
+                        status: "fixed",
+                        detail: `REMOVED unparseable packet — original preserved at ${(0, node_path_1.relative)(projectDir, backupPath)}; restore it by hand if it mattered`,
+                    });
+                }
+            }
+            catch (error) {
+                actions.push({ area: "packets", target, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    if (!brokenFound) {
+        actions.push({ area: "packets", target: "memory packets", status: "skipped", detail: "all packet files parse cleanly" });
+    }
+    // 2. Stale lock/temp files left behind by crashed writers, plus a daemon
+    //    status file whose pid is no longer running.
+    let lockFindings = 0;
+    for (const path of walkFiles(memoryRoot(projectDir), (candidate) => candidate.endsWith(".tmp") || candidate.endsWith(".lock"))) {
+        lockFindings += 1;
+        try {
+            (0, node_fs_1.unlinkSync)(path);
+            actions.push({ area: "locks", target: (0, node_path_1.relative)(projectDir, path), status: "fixed", detail: "removed leftover temp/lock file" });
+        }
+        catch (error) {
+            actions.push({ area: "locks", target: (0, node_path_1.relative)(projectDir, path), status: "failed", detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const daemonStatusPath = (0, node_path_1.join)(daemonDir(projectDir), "status.json");
+    if ((0, node_fs_1.existsSync)(daemonStatusPath)) {
+        let stale = true;
+        let pidLabel = "unknown";
+        try {
+            const status = readJson(daemonStatusPath);
+            if (typeof status.pid === "number") {
+                pidLabel = String(status.pid);
+                try {
+                    process.kill(status.pid, 0);
+                    stale = false;
+                }
+                catch {
+                    stale = true;
+                }
+            }
+        }
+        catch {
+            stale = true; // unreadable status file is stale by definition
+        }
+        if (stale) {
+            lockFindings += 1;
+            try {
+                (0, node_fs_1.unlinkSync)(daemonStatusPath);
+                actions.push({ area: "locks", target: (0, node_path_1.relative)(projectDir, daemonStatusPath), status: "fixed", detail: `removed stale daemon status (pid ${pidLabel} is not running)` });
+            }
+            catch (error) {
+                actions.push({ area: "locks", target: (0, node_path_1.relative)(projectDir, daemonStatusPath), status: "failed", detail: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        else {
+            lockFindings += 1;
+            actions.push({ area: "locks", target: (0, node_path_1.relative)(projectDir, daemonStatusPath), status: "skipped", detail: `daemon pid ${pidLabel} is alive — left alone` });
+        }
+    }
+    if (!lockFindings) {
+        actions.push({ area: "locks", target: "lock/temp files", status: "skipped", detail: "no stale lock or temp files" });
+    }
+    // 3. Missing or stale indexes — rebuild. Packet surgery above also forces a
+    //    rebuild so the catalog never disagrees with what is on disk.
+    const expectedIndexes = ["catalog.json", "by-path.json", "by-tag.json", "by-type.json", "vector-local.json", "graph.json", "code-graph.json"];
+    const missingIndexes = expectedIndexes.filter((name) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(indexesDir(projectDir), name)));
+    let staleCatalog = false;
+    const catalogPath = (0, node_path_1.join)(indexesDir(projectDir), "catalog.json");
+    if ((0, node_fs_1.existsSync)(catalogPath)) {
+        try {
+            const catalog = readJson(catalogPath);
+            staleCatalog = catalog.packet_count !== loadPacketsFromDir(packetsDir(projectDir)).length;
+        }
+        catch {
+            staleCatalog = true;
+        }
+    }
+    if (missingIndexes.length || staleCatalog || packetsTouched) {
+        try {
+            const rebuilt = indexProject(projectDir);
+            const reason = missingIndexes.length
+                ? `${missingIndexes.length} missing: ${missingIndexes.join(", ")}`
+                : staleCatalog
+                    ? "catalog was out of date"
+                    : "packets changed during repair";
+            actions.push({ area: "indexes", target: "indexes + graphs", status: "fixed", detail: `rebuilt ${rebuilt.indexes.length} indexes (${reason})` });
+        }
+        catch (error) {
+            actions.push({ area: "indexes", target: "indexes + graphs", status: "failed", detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    else {
+        actions.push({ area: "indexes", target: "indexes + graphs", status: "skipped", detail: "present and current" });
+    }
+    // 4. Agent wiring drift — re-run the write path ONLY for agents that are
+    //    already configured (config file exists) but whose hook scripts went
+    //    missing. Repair never wires new agents.
+    try {
+        const doctor = setupDoctor(projectDir, { homeDir: options.homeDir, serverPath: options.serverPath });
+        let drifted = 0;
+        for (const item of doctor) {
+            // "Already configured" means the agent's config file exists AND already
+            // mentions the Kage MCP server. A bare config (every Claude Code user
+            // has ~/.claude.json) is NOT configured — repair never wires new agents.
+            const configured = Boolean(item.config_path && (0, node_fs_1.existsSync)(item.config_path)) && configMentionsKage(item.config_path);
+            if (!configured)
+                continue;
+            if (!item.hook_summary || item.hook_summary.ready)
+                continue;
+            drifted += 1;
+            try {
+                const rewired = setupAgent(item.agent, projectDir, { write: true, homeDir: options.homeDir, serverPath: options.serverPath });
+                actions.push({
+                    area: "agents",
+                    target: item.agent,
+                    status: rewired.wrote ? "fixed" : "failed",
+                    detail: rewired.wrote
+                        ? `re-ran setup, restored missing hooks (${item.hook_summary.missing.join(", ")})`
+                        : `setup did not write — run: kage setup ${item.agent} --project . --write`,
+                });
+            }
+            catch (error) {
+                actions.push({ area: "agents", target: item.agent, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        if (!drifted) {
+            actions.push({ area: "agents", target: "agent wiring", status: "skipped", detail: "configured agents look intact" });
+        }
+    }
+    catch (error) {
+        actions.push({ area: "agents", target: "agent wiring", status: "failed", detail: error instanceof Error ? error.message : String(error) });
+    }
+    const validation = validateProject(projectDir);
+    const fixed = actions.filter((action) => action.status === "fixed").length;
+    const skipped = actions.filter((action) => action.status === "skipped").length;
+    const failed = actions.filter((action) => action.status === "failed").length;
+    return { project_dir: projectDir, ok: failed === 0, actions, fixed, skipped, failed, removed_packets: removedPackets, validation };
+}
+// Map a CLI failure to ONE copy-pasteable next command. Pure on purpose:
+// remediation must be unit-testable without throwing real errors.
+function remediationFor(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    if (/ENOENT/i.test(text) && /\.agent_memory/.test(text))
+        return "kage init --project .";
+    if (/Unexpected token|Unexpected end of JSON|is not valid JSON|JSON\.parse|in JSON at position/i.test(text))
+        return "kage repair --project .";
+    if (/\bindex(es)?\b|\bgraph\b/i.test(text))
+        return "kage index --project .";
+    return "kage doctor --project .";
+}
 function approvePending(projectDir, id) {
     const pendingFiles = walkFiles(pendingDir(projectDir), (path) => path.endsWith(".json"));
     for (const path of pendingFiles) {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [
@@ -49,4 +49,4 @@
     "node": ">=18"
   },
   "mcpName": "com.kage-core/kage"
-}
+}

package/viewer/console.js CHANGED Viewed

@@ -780,4 +780,65 @@
     fitView();
     cancelAnimationFrame(G.raf); tick();
   }
+  // ---- live feed (SSE from the local viewer daemon) ----
+  // Connects to /kage/events when this page is served by `kage viewer`. The
+  // hosted demo on GitHub Pages has no daemon: the stream never opens, so the
+  // panel stays hidden and the dashboard is otherwise unchanged.
+  var LIVE_CAP = 30;
+  var LIVE_LABEL = {
+    packet_written: ["＋", "Memory written"],
+    packet_updated: ["✎", "Memory updated"],
+    recall_served: ["✓", "Recall served"],
+    stale_withheld: ["⊘", "Stale memory withheld"],
+    caller_answered: ["◆", "Graph answer served"],
+    stale_caught: ["⊘", "Stale memory caught"],
+  };
+  function liveRow(e) {
+    var kind = e.type === "value_event" ? ((e.event && e.event.kind) || "value_event") : e.type;
+    var meta = LIVE_LABEL[kind] || ["•", String(kind).replace(/_/g, " ")];
+    var row = el("div", "vev fresh " + kind);
+    row.appendChild(el("span", "vi", meta[0]));
+    var mid = el("div", "vt");
+    mid.appendChild(document.createTextNode(meta[1]));
+    if (kind === "recall_served" && e.event && e.event.tokens_saved > 0) {
+      mid.appendChild(document.createTextNode(" — saved "));
+      mid.appendChild(el("b", null, "~" + fmt(e.event.tokens_saved) + " tokens"));
+    } else if (e.title) {
+      mid.appendChild(document.createTextNode(" — "));
+      mid.appendChild(el("b", null, e.title));
+    }
+    row.appendChild(mid);
+    row.appendChild(el("span", "when", relTime(e.ts) || "just now"));
+    return row;
+  }
+  function initLive() {
+    if (typeof window.EventSource === "undefined") return;
+    var panel = document.getElementById("livePanel"), feed = document.getElementById("liveFeed");
+    if (!panel || !feed) return;
+    var es;
+    try { es = new EventSource("/kage/events"); } catch (err) { return; }
+    var opened = false;
+    es.onopen = function () {
+      opened = true;
+      panel.hidden = false;
+      if (!feed.childNodes.length) feed.appendChild(el("div", "empty", "Connected. New memories and value events stream in here live."));
+    };
+    es.onerror = function () {
+      // Never connected (no daemon behind this page): close and hide quietly.
+      // After a successful open, EventSource reconnects on its own — keep the panel.
+      if (!opened) { es.close(); panel.hidden = true; }
+    };
+    es.onmessage = function (msg) {
+      var e;
+      try { e = JSON.parse(msg.data); } catch (err) { return; }
+      if (!e || !e.type) return;
+      var placeholder = feed.querySelector(".empty");
+      if (placeholder) feed.removeChild(placeholder);
+      feed.className = "vfeed";
+      feed.insertBefore(liveRow(e), feed.firstChild);
+      while (feed.childNodes.length > LIVE_CAP) feed.removeChild(feed.lastChild);
+    };
+  }
+  initLive();
 })();

package/viewer/index.html CHANGED Viewed

@@ -95,6 +95,14 @@
       .receipt .r-line b.warn { color: var(--warn); } .receipt .r-line b.gain { color: var(--gain); }
       .receipt .r-foot { border-top: 1px dashed var(--line-strong); padding: 11px 24px; color: var(--faint); font: 400 11px/1.5 var(--mono); }
+      /* live feed (SSE from the local daemon; hidden on the hosted demo) */
+      .livedot { display: inline-block; width: 8px; height: 8px; border-radius: 99px; background: var(--gain); margin-right: 9px; animation: livepulse 2s ease infinite; }
+      @keyframes livepulse { 0%, 100% { box-shadow: 0 0 0 0 var(--gain-soft); } 50% { box-shadow: 0 0 0 6px var(--gain-soft); } }
+      .vev.fresh { animation: levin 1.2s ease; }
+      @keyframes levin { from { background: var(--gain-soft); } to { background: transparent; } }
+      .vev.packet_written .vi, .vev.packet_updated .vi { color: var(--memory); }
+      .vev.stale_caught .vi { color: var(--warn); }
       /* gains timeline */
       .vfeed { display: grid; }
       .vev { display: grid; grid-template-columns: 20px 1fr auto; gap: 0 13px; align-items: baseline; padding: 11px 4px; border-top: 1px solid var(--line); }
@@ -298,6 +306,7 @@
           <section class="section active" id="section-gains">
             <div class="receipt" id="gainsHero"></div>
             <div class="tiles" id="gainsTiles"></div>
+            <div class="panel" id="livePanel" hidden><h2><span class="livedot" aria-hidden="true"></span>Live <span class="sub">— memories and value events as they happen</span></h2><div id="liveFeed"></div></div>
             <div class="panel"><h2>Value timeline <span class="sub">— every saved recall and withheld stale memory, as it happened</span></h2><div id="gainsTimeline"></div></div>
           </section>
@@ -361,6 +370,6 @@
     </div>
     <div class="drawer-backdrop" id="detailBackdrop"></div>
     <aside class="drawer" id="detail" aria-hidden="true"></aside>
-    <script src="./console.js?v=16"></script>
+    <script src="./console.js?v=17"></script>
   </body>
 </html>