npm - @kage-core/kage-graph-mcp - Versions diffs - 2.0.2 → 2.2.0 - Mend

@kage-core/kage-graph-mcp 2.0.2 → 2.2.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 (7) hide show

package/dist/cli.js CHANGED Viewed

@@ -24,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).`;
@@ -37,6 +38,7 @@ Usage:
   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]
@@ -49,7 +51,8 @@ Usage:
   kage hook install --project <dir> [--json]
   kage hook status --project <dir> [--json]
   kage hook uninstall --project <dir> [--json]
-  kage refresh --project <dir> [--full] [--json]
+  kage refresh --project <dir> [--full] [--force] [--json]
+  kage merge-packet <ours> <base> <theirs>      git merge driver for .agent_memory/packets/*.json
   kage gc --project <dir> [--dry-run] [--force] [--json]
   kage compact --project <dir> [--dry-run] [--json]
   kage verify --project <dir> [--id <packet-id>] [--json]
@@ -83,6 +86,7 @@ Usage:
   kage workspace --project <workspace-dir> [--json]
   kage workspace recall "<query>" --project <workspace-dir> [--json]
   kage audit --project <dir> [--json]
+  kage audit-claude-mem [--store <path>] [--project <dir>] [--json]
   kage inbox --project <dir> [--json]
   kage quality --project <dir> [--json]
   kage benchmark --project <dir> [--json]
@@ -104,11 +108,16 @@ Usage:
   kage graph-registry --project <dir> [--json]
   kage embeddings build --project <dir> [--model Xenova/all-MiniLM-L6-v2] [--json]
   kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings] [--max-context-tokens <n>] [--structural-hops <n>]
+  kage file-context --project <dir> --path <file> [--json]
   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 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 distill --project <dir> --session <id> [--auto] [--json]
+  kage resume --project <dir> [--json]
+  kage learn --project <dir> --learning <text> [--personal] [--title <title>] [--type <type>] [--evidence <text>] [--verified-by <text>] [--tags a,b] [--paths a,b] [--graph-nodes a,b] [--discovery-tokens <n>] [--allow-missing-paths]
+  kage sync setup --remote <git-url>            init ~/.kage/memory as a git repo wired to your private remote
+  kage sync [--json]                            commit + pull --rebase + push personal memory (newest-wins conflicts)
+  kage sync --status [--json]                   ahead/behind/dirty for the personal store (fetch only)
   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]
   kage propose --project <dir> --from-diff
@@ -204,6 +213,74 @@ async function main() {
         console.log(args.includes("--all") ? FULL_USAGE : CORE_USAGE);
         return;
     }
+    if (command === "merge-packet") {
+        // Git merge driver (%A %O %B): runs before any heavy setup — merge drivers
+        // must be fast and dependency-free. Exit 0 = merged, 1 = leave conflict.
+        const [ours, base, theirs] = [args[1], args[2], args[3]];
+        if (!ours || !base || !theirs) {
+            console.error("Usage: kage merge-packet <ours> <base> <theirs>");
+            console.error(`Enable once per clone: ${kernel_js_1.PACKET_MERGE_DRIVER_CONFIG}`);
+            process.exit(1);
+        }
+        const result = (0, kernel_js_1.mergePacketFiles)(ours, base, theirs);
+        console.error(result.detail);
+        process.exit(result.ok ? 0 : 1);
+    }
+    if (command === "sync") {
+        // Personal-store sync (docs/CLOUD.md v1): plain git under the hood, no
+        // tree-sitter or repo indexes needed, so it runs before the heavy setup.
+        if (args[1] === "setup") {
+            const remote = takeArg(args, "--remote");
+            if (!remote) {
+                console.error("Usage: kage sync setup --remote <git-url>");
+                process.exit(2);
+            }
+            const result = (0, kernel_js_1.syncSetup)(remote);
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                process.exit(result.ok ? 0 : 2);
+            }
+            if (!result.ok) {
+                console.error(`kage sync setup failed:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+                process.exit(2);
+            }
+            console.log(`Personal memory store: ${result.memory_dir}${result.initialized ? " (new git repo)" : ""}`);
+            console.log(`Remote: ${result.remote}${result.remote_updated ? " (updated)" : ""}`);
+            console.log(`Pushed ${result.branch ?? "HEAD"} to origin. Run \`kage sync\` on any machine to stay in sync.`);
+            return;
+        }
+        if (args.includes("--status")) {
+            const result = (0, kernel_js_1.syncStatus)();
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                process.exit(result.ok ? 0 : 2);
+            }
+            if (!result.ok) {
+                console.error(`kage sync status failed:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+                process.exit(2);
+            }
+            console.log(`Personal memory store: ${result.memory_dir}`);
+            console.log(`Remote: ${result.remote} (branch ${result.branch ?? "unknown"})`);
+            console.log(`Ahead ${result.ahead}, behind ${result.behind}, ${result.dirty ? "uncommitted local changes" : "clean"}`);
+            for (const warning of result.warnings)
+                console.log(`Warning: ${warning}`);
+            return;
+        }
+        const result = (0, kernel_js_1.syncPersonal)();
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(result.ok ? 0 : 2);
+        }
+        if (!result.ok) {
+            console.error(`kage sync failed:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+            process.exit(2);
+        }
+        console.log(`kage sync: pushed ${result.pushed}, pulled ${result.pulled}, resolved ${result.resolved}`);
+        if (result.conflict_backups.length) {
+            console.log(`Conflict losers preserved:\n${result.conflict_backups.map((path) => `  - ${path}`).join("\n")}`);
+        }
+        return;
+    }
     await (0, kernel_js_1.ensureTreeSitterLanguages)();
     if (command === "index") {
         const result = (0, kernel_js_1.indexProject)(projectArg(args));
@@ -287,6 +364,7 @@ async function main() {
         console.log(`Initialized Kage memory for ${result.index.projectDir}`);
         console.log("\nCreated:");
         console.log("  .agent_memory/            memory packets + indexes (only directory Kage owns)");
+        console.log(`  .gitattributes            kage-packet merge driver for packet JSON${result.gitAttributes.changed ? "" : " (already current)"}`);
         if (result.policyInstalled) {
             console.log("  AGENTS.md, CLAUDE.md      agent policy (requested via --with-policy)");
             console.log("  .claude/settings.json     allowed kage tools (requested via --with-policy)");
@@ -302,6 +380,8 @@ async function main() {
         console.log("\nTip — version control:");
         console.log("  commit  .agent_memory/packets/    (your team's reviewed memory)");
         console.log("  ignore  .agent_memory/indexes/ .agent_memory/reports/    (regenerated)");
+        console.log("\nEnable the packet merge driver once per clone:");
+        console.log(`  ${kernel_js_1.PACKET_MERGE_DRIVER_CONFIG}`);
         if (!result.policyInstalled) {
             console.log("\nNot written (opt-in): agent policy files. Add them with `kage policy --project .`");
             console.log("or rerun `kage init --with-policy` when you're ready to commit them.");
@@ -375,6 +455,8 @@ async function main() {
         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/.");
+        console.log("Enable the packet merge driver once per clone:");
+        console.log(`  ${kernel_js_1.PACKET_MERGE_DRIVER_CONFIG}`);
         if (!init.validation.ok)
             process.exit(2);
         return;
@@ -408,7 +490,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;
     }
@@ -666,7 +777,7 @@ async function main() {
         return;
     }
     if (command === "refresh") {
-        const result = (0, kernel_js_1.refreshProject)(projectArg(args), { full: args.includes("--full") });
+        const result = (0, kernel_js_1.refreshProject)(projectArg(args), { full: args.includes("--full"), force: args.includes("--force") });
         if (args.includes("--json")) {
             console.log(JSON.stringify(result, null, 2));
             if (!result.ok)
@@ -674,6 +785,8 @@ async function main() {
             return;
         }
         console.log(`Refreshed ${result.project_dir}`);
+        if (result.quiet_refresh)
+            console.log("Quiet refresh (non-default branch): packet metadata not rewritten on disk; use --force to persist.");
         console.log(`Packets indexed: ${result.index.packets}`);
         console.log(`Packet metadata updated: ${result.updated_packets}`);
         console.log(`Code graph: ${result.code_graph.files} files, ${result.code_graph.symbols} symbols, ${result.code_graph.imports} imports, ${result.code_graph.calls} calls`);
@@ -1155,6 +1268,23 @@ async function main() {
             `${window.caller_answers} caller ${plural(window.caller_answers, "answer", "answers")}`;
         console.log(windowLine("Today:   ", summary.today));
         console.log(windowLine("All time:", summary.all_time));
+        if (summary.all_time.replay_tokens > 0) {
+            console.log(`Knowledge replay value: ~${(0, kernel_js_1.formatTokenCount)(week.replay_tokens)} tokens this week · ` +
+                `~${(0, kernel_js_1.formatTokenCount)(summary.all_time.replay_tokens)} all time ` +
+                `(discovery cost of served memories vs their compressed read cost)`);
+        }
+        return;
+    }
+    if (command === "file-context") {
+        const path = takeArg(args, "--path");
+        if (!path)
+            usage();
+        const result = (0, kernel_js_1.kageFileContext)(projectArg(args), path);
+        if (args.includes("--json"))
+            console.log(JSON.stringify(result, null, 2));
+        else if (result.context_block)
+            console.log(result.context_block);
+        // No verified packets cite this file: print nothing so hooks can gate on empty output.
         return;
     }
     if (command === "memory-access") {
@@ -1502,6 +1632,21 @@ async function main() {
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         return;
     }
+    if (command === "audit-claude-mem") {
+        const projectDir = projectArg(args);
+        const storePath = takeArg(args, "--store") ?? (0, kernel_js_1.defaultClaudeMemStorePath)();
+        const result = (0, kernel_js_1.auditClaudeMemStore)(projectDir, { storePath });
+        if (!result.ok) {
+            console.error(result.error);
+            process.exit(2);
+        }
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result.report, null, 2));
+            return;
+        }
+        console.log((0, kernel_js_1.renderClaudeMemAuditReceipt)(result.report));
+        return;
+    }
     if (command === "audit") {
         const result = (0, kernel_js_1.auditProject)(projectArg(args));
         if (args.includes("--json")) {
@@ -1699,7 +1844,8 @@ async function main() {
         const learning = takeArg(args, "--learning");
         if (!learning)
             usage();
-        const result = (0, kernel_js_1.learn)({
+        const personal = args.includes("--personal");
+        const result = (personal ? kernel_js_1.learnPersonal : kernel_js_1.learn)({
             projectDir: projectArg(args),
             learning,
             title: takeArg(args, "--title"),
@@ -1712,15 +1858,18 @@ async function main() {
             graphNodes: listArg(takeArg(args, "--graph-nodes")),
             allowMissingPaths: args.includes("--allow-missing-paths"),
             strictCitations: true,
+            discoveryTokens: args.includes("--discovery-tokens") ? numberArg(args, "--discovery-tokens", 0) : undefined,
         });
         if (!result.ok) {
             console.error(`Learning capture blocked:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
             process.exit(2);
         }
-        console.log(`Captured session learning: ${result.path}`);
+        console.log(`Captured ${personal ? "personal" : "session"} learning: ${result.path}`);
         if (result.warnings?.length)
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
-        console.log("Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");
+        console.log(personal
+            ? "Personal memory is recalled with lower trust and never enters repo review flows. Sync it across machines with `kage sync`."
+            : "Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");
         return;
     }
     if (command === "propose") {
@@ -1899,9 +2048,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}`);
@@ -1909,10 +2067,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");
@@ -2004,7 +2173,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/index.js CHANGED Viewed

@@ -75,6 +75,15 @@ function riskContextBlock(result) {
     return `\n## Risk Signals\n${lines.join("\n")}`;
 }
 const server = new index_js_1.Server({ name: "kage-graph", version: "2.0.0" }, { capabilities: { tools: {} } });
+// Workflow pseudo-tool: the description itself is the documentation, so agents
+// absorb the loop just by listing tools. The handler returns the same text.
+const KAGE_WORKFLOW_TEXT = "Kage memory workflow (this tool performs no action; it returns this loop). " +
+    "1) Start every task with kage_context (project_dir + the task as query): it validates memory, recalls relevant packets, and queries the code and knowledge graphs in one call. " +
+    "2) Do the work, preferring repo memory over public context. " +
+    "3) Capture reusable learnings with kage_learn — bug causes and verified fixes, conventions, decisions, gotchas, run/test/build commands. Wrap anything that must never leave the repo in <private>...</private> tags; private spans are stripped before sharing. " +
+    "4) After meaningful file changes, call kage_refresh so indexes, graphs, and stale-memory checks stay current. " +
+    "5) Before finishing a branch, call kage_pr_summarize then kage_pr_check. " +
+    "Recall receipts show estimated tokens saved versus rediscovery; report memory quality with kage_feedback (helpful/wrong/stale).";
 function listTools() {
     return [
         {
@@ -457,15 +466,25 @@ function listTools() {
         },
         {
             name: "kage_refresh",
-            description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh.",
+            description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh. On non-default git branches metadata-only packet rewrites are skipped (quiet refresh) to avoid merge conflicts; pass force to persist them anyway.",
             inputSchema: {
                 type: "object",
                 properties: {
                     project_dir: { type: "string" },
+                    force: { type: "boolean", description: "Persist packet metadata rewrites even on a non-default branch" },
                 },
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_workflow",
+            description: KAGE_WORKFLOW_TEXT,
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
         {
             name: "kage_pr_summarize",
             description: "Create a PR/branch memory summary from local git diff metadata and write repo-local change memory. Use when a branch is ready to hand off.",
@@ -685,6 +704,7 @@ function listTools() {
                     stack: { type: "array", items: { type: "string" } },
                     graph_nodes: { type: "array", items: { type: "string" } },
                     allow_missing_paths: { type: "boolean" },
+                    discovery_tokens: { type: "number", description: "Approximate token cost of producing this knowledge (exploration + reasoning). Stored on the packet so recall receipts can report replay value; a conservative per-type default is estimated when omitted." },
                 },
                 required: ["project_dir", "learning"],
             },
@@ -1243,12 +1263,17 @@ async function callTool(name, args) {
         };
     }
     if (name === "kage_refresh") {
-        const result = (0, kernel_js_1.refreshProject)(String(args?.project_dir ?? ""), { full: Boolean(args?.full) });
+        const result = (0, kernel_js_1.refreshProject)(String(args?.project_dir ?? ""), { full: Boolean(args?.full), force: Boolean(args?.force) });
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             isError: !result.ok,
         };
     }
+    if (name === "kage_workflow") {
+        return {
+            content: [{ type: "text", text: KAGE_WORKFLOW_TEXT }],
+        };
+    }
     if (name === "kage_pr_summarize") {
         const result = (0, kernel_js_1.prSummarize)(String(args?.project_dir ?? ""));
         return {
@@ -1349,6 +1374,7 @@ async function callTool(name, args) {
             graphNodes: arrayArg(args?.graph_nodes),
             allowMissingPaths: Boolean(args?.allow_missing_paths),
             strictCitations: true,
+            discoveryTokens: args?.discovery_tokens === undefined ? undefined : Number(args.discovery_tokens),
         });
         const learnWarnings = result.warnings?.length ? `\nWarnings:\n${result.warnings.map((warning) => `- ${warning}`).join("\n")}` : "";
         return {