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

package/dist/kernel.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTO_DISTILL_TAG = exports.SETUP_AGENTS = exports.MEMORY_TYPES = exports.PACKET_SCHEMA_VERSION = void 0;
+exports.PACKET_MERGE_DRIVER_CONFIG = exports.PACKET_MERGE_ATTRIBUTE_LINE = exports.AUTO_DISTILL_SIGNAL_THRESHOLD = 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;
@@ -65,6 +65,7 @@ exports.kageMemoryLifecycle = kageMemoryLifecycle;
 exports.recordValueEvent = recordValueEvent;
 exports.valueSummary = valueSummary;
 exports.formatTokenCount = formatTokenCount;
+exports.kageFileContext = kageFileContext;
 exports.kageActivity = kageActivity;
 exports.kageMemoryReconciliation = kageMemoryReconciliation;
 exports.evaluateMemoryAdmission = evaluateMemoryAdmission;
@@ -104,6 +105,14 @@ exports.kageRisk = kageRisk;
 exports.kageDependencyPath = kageDependencyPath;
 exports.kageCleanupCandidates = kageCleanupCandidates;
 exports.truthReport = truthReport;
+exports.defaultClaudeMemStorePath = defaultClaudeMemStorePath;
+exports.claudeMemProjectKey = claudeMemProjectKey;
+exports.parseClaudeMemFileList = parseClaudeMemFileList;
+exports.readClaudeMemObservations = readClaudeMemObservations;
+exports.buildClaudeMemChangeSignal = buildClaudeMemChangeSignal;
+exports.classifyClaudeMemObservations = classifyClaudeMemObservations;
+exports.auditClaudeMemStore = auditClaudeMemStore;
+exports.renderClaudeMemAuditReceipt = renderClaudeMemAuditReceipt;
 exports.kageReviewerSuggestions = kageReviewerSuggestions;
 exports.kageContributors = kageContributors;
 exports.kageContextSlots = kageContextSlots;
@@ -137,6 +146,7 @@ exports.setupAgent = setupAgent;
 exports.setupDoctor = setupDoctor;
 exports.verifyAgentActivation = verifyAgentActivation;
 exports.observe = observe;
+exports.observationSignalScore = observationSignalScore;
 exports.kageSessionCaptureReport = kageSessionCaptureReport;
 exports.kageSessionReplay = kageSessionReplay;
 exports.kageSessionLearningLedger = kageSessionLearningLedger;
@@ -158,6 +168,8 @@ exports.validateProject = validateProject;
 exports.initProject = initProject;
 exports.doctorProject = doctorProject;
 exports.splitConflictSides = splitConflictSides;
+exports.mergePacketFiles = mergePacketFiles;
+exports.ensurePacketMergeAttributes = ensurePacketMergeAttributes;
 exports.repairProject = repairProject;
 exports.remediationFor = remediationFor;
 exports.approvePending = approvePending;
@@ -166,6 +178,16 @@ exports.changelog = changelog;
 exports.supersedeMemory = supersedeMemory;
 exports.kageMemoryLineage = kageMemoryLineage;
 exports.kageMemoryTimeline = kageMemoryTimeline;
+exports.kageHomeDir = kageHomeDir;
+exports.personalMemoryDir = personalMemoryDir;
+exports.personalPacketsDir = personalPacketsDir;
+exports.personalConflictsDir = personalConflictsDir;
+exports.loadPersonalPackets = loadPersonalPackets;
+exports.learnPersonal = learnPersonal;
+exports.capturePersonal = capturePersonal;
+exports.syncSetup = syncSetup;
+exports.syncStatus = syncStatus;
+exports.syncPersonal = syncPersonal;
 const node_crypto_1 = require("node:crypto");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -981,7 +1003,7 @@ function valueLedgerPath(projectDir) {
 function emptyValueLedger() {
     return {
         schema_version: VALUE_LEDGER_SCHEMA_VERSION,
-        totals: { tokens_saved: 0, stale_withheld: 0, stale_caught: 0, recalls: 0, caller_answers: 0 },
+        totals: { tokens_saved: 0, replay_tokens: 0, stale_withheld: 0, stale_caught: 0, recalls: 0, caller_answers: 0 },
         events: [],
     };
 }
@@ -1009,6 +1031,7 @@ function readValueLedger(projectDir) {
             schema_version: VALUE_LEDGER_SCHEMA_VERSION,
             totals: {
                 tokens_saved: nonNegativeCount(totals.tokens_saved),
+                replay_tokens: nonNegativeCount(totals.replay_tokens),
                 stale_withheld: nonNegativeCount(totals.stale_withheld),
                 stale_caught: nonNegativeCount(totals.stale_caught),
                 recalls: nonNegativeCount(totals.recalls),
@@ -1031,7 +1054,9 @@ function recordValueEvents(projectDir, events) {
             const record = { at, kind: event.kind };
             if (event.kind === "recall_served") {
                 record.tokens_saved = nonNegativeCount(event.tokens_saved);
+                record.replay_tokens = nonNegativeCount(event.replay_tokens);
                 ledger.totals.tokens_saved += record.tokens_saved;
+                ledger.totals.replay_tokens += record.replay_tokens;
                 ledger.totals.recalls += 1;
             }
             else if (event.kind === "stale_withheld") {
@@ -1068,7 +1093,7 @@ function estimatedTokenDollars(tokensSaved) {
     return Number(((tokensSaved / 1_000_000) * VALUE_DOLLARS_PER_MILLION_TOKENS).toFixed(2));
 }
 function summarizeValueWindow(events, cutoff) {
-    const window = { tokens_saved: 0, stale_withheld: 0, stale_caught: 0, recalls: 0, caller_answers: 0 };
+    const window = { tokens_saved: 0, replay_tokens: 0, stale_withheld: 0, stale_caught: 0, recalls: 0, caller_answers: 0 };
     for (const event of events) {
         const at = Date.parse(event.at);
         if (!Number.isFinite(at) || at < cutoff)
@@ -1076,6 +1101,7 @@ function summarizeValueWindow(events, cutoff) {
         if (event.kind === "recall_served") {
             window.recalls += 1;
             window.tokens_saved += nonNegativeCount(event.tokens_saved);
+            window.replay_tokens += nonNegativeCount(event.replay_tokens);
         }
         else if (event.kind === "stale_withheld") {
             window.stale_withheld += 1;
@@ -1128,6 +1154,89 @@ function recallTokensSaved(projectDir, results, contextBlock) {
     }
     return Math.max(0, Math.floor(sourceBytes / 4) - Math.floor(contextBlock.length / 4));
 }
+// Conservative per-type defaults for discovery_tokens — the approximate exploration +
+// reasoning tokens an agent typically burns to produce knowledge of this type — used
+// when a capture does not report its actual discovery cost. Deliberately low so
+// knowledge-replay receipts under-claim rather than over-claim.
+const DEFAULT_DISCOVERY_TOKENS = {
+    bug_fix: 8000,
+    gotcha: 8000,
+    decision: 4000,
+};
+const DEFAULT_DISCOVERY_TOKENS_FALLBACK = 2000;
+function defaultDiscoveryTokens(type) {
+    return DEFAULT_DISCOVERY_TOKENS[type] ?? DEFAULT_DISCOVERY_TOKENS_FALLBACK;
+}
+function packetDiscoveryTokens(packet) {
+    const value = Number(packet.quality?.discovery_tokens);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+// Knowledge replay value: the tokens originally spent discovering the served packets'
+// knowledge minus the compressed cost of re-reading them as context. Floored at zero.
+// Recall receipts take the max of this and the read-vs-source estimate, so reported
+// savings never drop below the pre-discovery_tokens behavior and never go negative.
+function replayTokensSaved(packets, contextBlock) {
+    const discovery = packets.reduce((sum, packet) => sum + packetDiscoveryTokens(packet), 0);
+    if (discovery <= 0)
+        return 0;
+    return Math.max(0, discovery - estimateTokens(contextBlock));
+}
+const FILE_CONTEXT_PACKET_CAP = 3;
+// PreToolUse(Read) injection: verified memory at the moment of relevance. Returns at
+// most three currently-verified packets that cite the file an agent is about to read,
+// as a compact context block. Reuses the same staleness machinery as recall — a packet
+// with ANY stale reason (deprecated/superseded, reported stale, ttl expired, missing or
+// changed citations) is never injected, so the block only ever carries verified memory.
+function kageFileContext(projectDir, filePath) {
+    const result = {
+        schema_version: 1,
+        project_dir: (0, node_path_1.resolve)(projectDir),
+        path: "",
+        packets: [],
+        context_block: "",
+    };
+    if (!filePath || !filePath.trim())
+        return result;
+    let rel = filePath.trim().replace(/\\/g, "/");
+    if ((0, node_path_1.isAbsolute)(rel))
+        rel = (0, node_path_1.relative)((0, node_path_1.resolve)(projectDir), rel).replace(/\\/g, "/");
+    rel = rel.replace(/^\.\//, "").replace(/^\/+/, "");
+    result.path = rel;
+    // Files outside the project (or an uninitialized project) never produce context.
+    if (!rel || rel.startsWith("..") || !(0, node_fs_1.existsSync)(memoryRoot(projectDir)))
+        return result;
+    const fingerprintCache = new Map();
+    const qualityScore = (packet) => {
+        const score = Number(packet.quality?.score);
+        return Number.isFinite(score) ? score : 0;
+    };
+    const verified = loadApprovedPackets(projectDir)
+        .filter((packet) => packetPathSet(packet).has(rel))
+        .filter((packet) => staleMemoryReasons(projectDir, packet, fingerprintCache).length === 0)
+        .sort((a, b) => qualityScore(b) - qualityScore(a) || b.updated_at.localeCompare(a.updated_at) || a.title.localeCompare(b.title))
+        .slice(0, FILE_CONTEXT_PACKET_CAP);
+    if (!verified.length)
+        return result;
+    const lines = [
+        `# Kage File Context: ${rel}`,
+        ...verified.flatMap((packet, index) => [
+            `${index + 1}. [${packet.type} | confidence ${packet.confidence.toFixed(2)}] ${packet.title}`,
+            `   ${packet.summary}`,
+        ]),
+        `_${verified.length} verified memor${verified.length === 1 ? "y" : "ies"} citing this file (citations checked, not stale)._`,
+    ];
+    result.context_block = lines.join("\n");
+    result.packets = verified.map((packet) => ({
+        id: packet.id,
+        title: packet.title,
+        type: packet.type,
+        summary: packet.summary,
+        confidence: packet.confidence,
+    }));
+    const replay = replayTokensSaved(verified, result.context_block);
+    recordValueEvent(projectDir, { kind: "recall_served", tokens_saved: replay, replay_tokens: replay });
+    return result;
+}
 const AUDIT_ACTIVITY_KIND = {
     capture: "capture", approve: "capture", supersede: "supersede", deprecate: "deprecate",
     update: "update", promote: "promote", feedback: "feedback",
@@ -2232,6 +2341,28 @@ function safeReadText(path) {
 function gitBranch(projectDir) {
     return readGit(projectDir, ["branch", "--show-current"]) || readGit(projectDir, ["rev-parse", "--short", "HEAD"]);
 }
+function gitDefaultBranch(projectDir) {
+    // Prefer the remote's view of the default branch (origin/HEAD), then fall
+    // back to whichever of master/main exists locally.
+    const originHead = readGit(projectDir, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+    if (originHead)
+        return originHead.replace(/^origin\//, "");
+    for (const candidate of ["master", "main"]) {
+        if (readGit(projectDir, ["rev-parse", "--verify", "--quiet", `refs/heads/${candidate}`]) !== null)
+            return candidate;
+    }
+    return null;
+}
+// True only when we are confident the working tree is on a non-default branch.
+// Unknown states (not a git repo, detached HEAD, undeterminable default branch)
+// return false so refresh keeps its full-rewrite behavior.
+function onNonDefaultBranch(projectDir) {
+    const current = readGit(projectDir, ["branch", "--show-current"]);
+    if (!current)
+        return false;
+    const defaultBranch = gitDefaultBranch(projectDir);
+    return defaultBranch !== null && current !== defaultBranch;
+}
 function gitHead(projectDir) {
     return readGit(projectDir, ["rev-parse", "HEAD"]);
 }
@@ -6082,7 +6213,12 @@ function staleFinding(packet, reasons) {
         suggested_action: staleSuggestedAction(reasons),
     };
 }
-function refreshPacketStaleness(projectDir) {
+// quiet: compute staleness fully (findings still drive recall withholding) but
+// skip pure-metadata rewrites (stale flags / updated_at recomputation) on disk.
+// Used on non-default git branches so concurrent branches stop conflicting on
+// cosmetic packet churn. Content changes (pruned grounding paths, i.e. the
+// citation set changed) are still persisted even in quiet mode.
+function refreshPacketStaleness(projectDir, options = {}) {
     const findings = [];
     let updated = 0;
     const fingerprintCache = new Map();
@@ -6111,10 +6247,11 @@ function refreshPacketStaleness(projectDir) {
             nextQuality = rest;
         }
         const nextFreshness = oldFreshness;
-        const changed = pruned !== null
+        const contentChanged = pruned !== null;
+        const changed = contentChanged
             || JSON.stringify(oldQuality) !== JSON.stringify(nextQuality)
             || JSON.stringify(oldFreshness) !== JSON.stringify(nextFreshness);
-        if (changed) {
+        if (changed && (!options.quiet || contentChanged)) {
             writeJson(entry.path, {
                 ...packet,
                 freshness: nextFreshness,
@@ -6127,11 +6264,17 @@ function refreshPacketStaleness(projectDir) {
     return { findings, updated };
 }
 function refreshProject(projectDir, options = {}) {
+    // Quiet-refresh on non-default branches: staleness is still computed (and
+    // recall withholding still works — it recomputes staleness in memory), but
+    // metadata-only packet rewrites are not persisted, so concurrent branches
+    // stop generating merge conflicts on .agent_memory/packets/*.json.
+    // --force restores full rewrites anywhere.
+    const quiet = !options.force && onNonDefaultBranch(projectDir);
     const detailedIndex = indexProjectDetailed(projectDir, { full: options.full });
     const index = detailedIndex.result;
     let codeGraph = detailedIndex.codeGraph;
     let knowledgeGraph = detailedIndex.knowledgeGraph;
-    const stale = refreshPacketStaleness(projectDir);
+    const stale = refreshPacketStaleness(projectDir, { quiet });
     let indexes = index.indexes;
     if (stale.updated > 0) {
         const rebuilt = buildGraphIndexes(projectDir, { forceCodeGraph: options.full });
@@ -6145,6 +6288,9 @@ function refreshProject(projectDir, options = {}) {
     writeJson((0, node_path_1.join)(reportsDir(projectDir), "context-slots.json"), kageContextSlots(projectDir));
     writeJson((0, node_path_1.join)(reportsDir(projectDir), "handoff.json"), kageMemoryHandoff(projectDir));
     const nextActions = [];
+    if (quiet && stale.findings.length) {
+        nextActions.push("Quiet refresh (non-default branch): stale flags were computed in memory but not written to packet files. Run `kage refresh --force` to persist them.");
+    }
     if (stale.findings.length)
         nextActions.push("Update, verify, or supersede stale repo memories before relying on them.");
     if (!validation.ok)
@@ -6157,6 +6303,7 @@ function refreshProject(projectDir, options = {}) {
         ok: validation.ok,
         project_dir: projectDir,
         generated_at: nowIso(),
+        quiet_refresh: quiet,
         index,
         validation,
         metrics,
@@ -7202,6 +7349,11 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         return true;
     })
         .slice(0, 3);
+    // Personal memory (~/.kage/memory): a clearly separated, lower-trust section
+    // appended AFTER every repo section — repo memory always ranks first. Cited
+    // personal packets are re-verified against this checkout (hard-stale ones are
+    // withheld, same as repo memory); citation-free ones are labeled unverifiable.
+    const personalEntries = personalRecallEntries(projectDir, terms, 3);
     const graphContext = queryGraph(projectDir, query, 5, knowledgeGraph);
     const codeContext = queryCodeGraph(projectDir, query, 5, codeGraph);
     const pinnedContext = renderPinnedRepoContext(readContextSlots(projectDir));
@@ -7250,6 +7402,20 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ...(suppressed.length
             ? ["", `_${suppressed.length} stale memory packet(s) excluded from recall. Run kage verify for details._`]
             : []),
+        ...(personalEntries.length
+            ? [
+                "",
+                "## Personal Memory",
+                "_Cross-machine personal store (~/.kage/memory). Lower trust than repo memory: not repo-reviewed — verify before relying on it. Repo memory above takes precedence on conflict._",
+                ...personalEntries.flatMap((entry, index) => [
+                    "",
+                    `${index + 1}. [personal] [${entry.packet.type} | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
+                    `   [personal] Summary: ${entry.packet.summary}`,
+                    `   [personal] Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
+                    `   [personal] Verification: ${entry.unverifiable ? "unverifiable (citation-free personal note)" : "citations re-verified against this checkout"}`,
+                ]),
+            ]
+            : []),
     ];
     const assembledBlock = lines.join("\n");
     const result = {
@@ -7257,6 +7423,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         context_block: inputs.maxContextTokens ? boundContextBlock(assembledBlock, inputs.maxContextTokens) : assembledBlock,
         results: scored,
         suppressed: suppressed.length ? suppressed : undefined,
+        personal: personalEntries.length ? personalEntries : undefined,
         explanations: explain
             ? scored.map((entry) => ({
                 packet_id: entry.packet.id,
@@ -7267,15 +7434,20 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
             }))
             : undefined,
     };
+    // Per-recall savings: never less than the read-vs-source estimate (prior behavior),
+    // raised to the knowledge-replay value when served packets carry discovery_tokens.
+    const readVsSourceTokens = scored.length ? recallTokensSaved(projectDir, result.results, result.context_block) : 0;
+    const replayTokens = scored.length ? replayTokensSaved(scored.map((entry) => entry.packet), result.context_block) : 0;
     result.value_receipt = {
-        tokens_saved: scored.length ? recallTokensSaved(projectDir, result.results, result.context_block) : 0,
+        tokens_saved: Math.max(readVsSourceTokens, replayTokens),
         stale_withheld: suppressed.length,
+        ...(replayTokens > 0 ? { replay_tokens: replayTokens } : {}),
     };
     if (inputs.trackAccess !== false) {
         recordRecallAccess(projectDir, result.results);
         recordValueEvents(projectDir, [
             ...suppressed.map((entry) => ({ kind: "stale_withheld", packet_title: entry.title })),
-            ...(scored.length ? [{ kind: "recall_served", tokens_saved: result.value_receipt.tokens_saved }] : []),
+            ...(scored.length ? [{ kind: "recall_served", tokens_saved: result.value_receipt.tokens_saved, replay_tokens: replayTokens }] : []),
         ]);
     }
     return result;
@@ -8717,6 +8889,276 @@ function truthReport(projectDir) {
         ],
     };
 }
+function defaultClaudeMemStorePath() {
+    const dataDir = process.env.CLAUDE_MEM_DATA_DIR || (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude-mem");
+    return (0, node_path_1.join)(dataDir, "claude-mem.db");
+}
+function claudeMemProjectKey(projectDir) {
+    // claude-mem derives the project name from the git repo root basename so it
+    // stays stable across subdirectories and worktrees; mirror that here.
+    const repoRoot = readGit(projectDir, ["rev-parse", "--show-toplevel"]);
+    return (0, node_path_1.basename)(repoRoot || (0, node_path_1.resolve)(projectDir));
+}
+// Mirrors claude-mem's own lenient parseFileList: JSON array of strings, with
+// non-JSON values treated as a single raw path.
+function parseClaudeMemFileList(value) {
+    if (!value)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        parsed = [value];
+    }
+    const list = Array.isArray(parsed) ? parsed : [parsed];
+    return list
+        .map((item) => String(item).trim())
+        .filter((item) => item.length > 0 && !/^\[.*\]$/.test(item));
+}
+// Read-only SELECT against a claude-mem store. Prefers the built-in node:sqlite
+// module (Node 22+); falls back to the sqlite3 CLI with -json output. The
+// project key is inlined with quote-escaping for the CLI path because the CLI
+// has no parameter binding.
+function queryClaudeMemStore(storePath, sqlFor, projectKey) {
+    let nodeSqliteError = null;
+    try {
+        // Guarded require: node:sqlite only exists on Node 22.5+, and this package
+        // supports Node 18+. Compiled output is CJS, so require is available.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { DatabaseSync } = require("node:sqlite");
+        const db = new DatabaseSync(storePath, { readOnly: true });
+        try {
+            const statement = db.prepare(sqlFor("?"));
+            const rows = (projectKey === null ? statement.all() : statement.all(projectKey));
+            return { ok: true, mechanism: "node:sqlite", rows };
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (error) {
+        nodeSqliteError = error instanceof Error ? error.message : String(error);
+    }
+    try {
+        const escaped = projectKey === null ? "''" : `'${projectKey.replace(/'/g, "''")}'`;
+        const out = (0, node_child_process_1.execFileSync)("sqlite3", ["-readonly", "-json", storePath, sqlFor(escaped)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const trimmed = out.trim();
+        return { ok: true, mechanism: "sqlite3-cli", rows: trimmed ? JSON.parse(trimmed) : [] };
+    }
+    catch {
+        return {
+            ok: false,
+            error: [
+                `Cannot read the claude-mem store at ${storePath}.`,
+                "Kage needs one of:",
+                "  - Node 22+ (ships the built-in node:sqlite module), or",
+                "  - the `sqlite3` command-line tool on PATH (with -json support, sqlite 3.33+).",
+                `node:sqlite said: ${nodeSqliteError ?? "unavailable"}`,
+                "The store is opened read-only either way — Kage never writes to it.",
+            ].join("\n"),
+        };
+    }
+}
+function readClaudeMemObservations(storePath, projectKey) {
+    if (!(0, node_fs_1.existsSync)(storePath)) {
+        return {
+            ok: false,
+            error: `No claude-mem store found at ${storePath}. Pass --store <path> if yours lives elsewhere (claude-mem default: ~/.claude-mem/claude-mem.db, or $CLAUDE_MEM_DATA_DIR/claude-mem.db).`,
+        };
+    }
+    const result = queryClaudeMemStore(storePath, (key) => `SELECT id, project, type, title, subtitle, files_read, files_modified, created_at, created_at_epoch FROM observations WHERE project = ${key} ORDER BY created_at_epoch ASC`, projectKey);
+    if (!result.ok)
+        return result;
+    return { ok: true, mechanism: result.mechanism, rows: result.rows };
+}
+function readClaudeMemProjectNames(storePath) {
+    const result = queryClaudeMemStore(storePath, () => "SELECT DISTINCT project FROM observations ORDER BY project", null);
+    if (!result.ok)
+        return [];
+    return result.rows.map((row) => String(row.project ?? "")).filter(Boolean);
+}
+// claude-mem stores created_at_epoch in milliseconds; tolerate seconds too.
+function claudeMemObservationEpochSeconds(row) {
+    const epoch = Number(row.created_at_epoch);
+    if (Number.isFinite(epoch) && epoch > 0)
+        return epoch > 1e12 ? Math.floor(epoch / 1000) : Math.floor(epoch);
+    if (row.created_at) {
+        const parsed = Date.parse(row.created_at);
+        if (Number.isFinite(parsed))
+            return Math.floor(parsed / 1000);
+    }
+    return null;
+}
+// One git pass over the whole history (same approach as truthReport): the
+// newest commit touching each path is its last-change signal. mtime is the
+// fallback for untracked or out-of-repo paths — fresh checkouts reset mtimes,
+// so git wins whenever it knows the path.
+function buildClaudeMemChangeSignal(projectDir) {
+    const absProject = (0, node_path_1.resolve)(projectDir);
+    const newestEpochByPath = new Map();
+    if (gitHead(projectDir)) {
+        const raw = readGit(projectDir, ["log", "--no-renames", "--format=__KAGE_CM__%x1f%ct", "--name-only"]) ?? "";
+        const projectPrefix = gitProjectPrefix(projectDir) ?? "";
+        let epoch = 0;
+        for (const rawLine of raw.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            if (line.startsWith("__KAGE_CM__")) {
+                epoch = Number(line.split("\x1f")[1] ?? 0) || 0;
+                continue;
+            }
+            const normalized = line.replace(/\\/g, "/").replace(/^\/+/, "");
+            const path = projectPrefix && normalized.startsWith(`${projectPrefix}/`) ? normalized.slice(projectPrefix.length + 1) : normalized;
+            // git log is newest-first: first sighting is the newest commit for the path.
+            if (!newestEpochByPath.has(path))
+                newestEpochByPath.set(path, epoch);
+        }
+    }
+    const resolveCited = (citedPath) => {
+        const cleaned = citedPath.replace(/\\/g, "/");
+        if (/^(?:[A-Za-z]:)?\//.test(cleaned) || cleaned.startsWith("~/")) {
+            const abs = (0, node_path_1.resolve)(cleaned.startsWith("~/") ? (0, node_path_1.join)((0, node_os_1.homedir)(), cleaned.slice(2)) : cleaned);
+            const rel = abs === absProject ? "" : abs.startsWith(absProject + node_path_1.sep) ? (0, node_path_1.relative)(absProject, abs).replace(/\\/g, "/") : null;
+            return { abs, rel };
+        }
+        const rel = cleaned.replace(/^\.\//, "");
+        return { abs: (0, node_path_1.join)(absProject, rel), rel };
+    };
+    return {
+        exists: (citedPath) => (0, node_fs_1.existsSync)(resolveCited(citedPath).abs),
+        lastChangedEpoch: (citedPath) => {
+            const { abs, rel } = resolveCited(citedPath);
+            if (rel !== null) {
+                const fromGit = newestEpochByPath.get(rel);
+                if (fromGit !== undefined)
+                    return fromGit;
+            }
+            const stat = safeStat(abs);
+            return stat ? Math.floor(stat.mtimeMs / 1000) : null;
+        },
+    };
+}
+// Pure classifier over parsed rows: VERIFIED (all cited paths exist and are
+// unchanged since capture), DRIFTED (a cited path changed after capture), GONE
+// (a cited path no longer exists), UNCITED (no file citations at all).
+// GONE outranks DRIFTED outranks VERIFIED when citations disagree.
+function classifyClaudeMemObservations(rows, signal, nowEpochSeconds = Math.floor(Date.now() / 1000)) {
+    return rows.map((row) => {
+        const cited = unique([...parseClaudeMemFileList(row.files_read), ...parseClaudeMemFileList(row.files_modified)]);
+        const obsEpoch = claudeMemObservationEpochSeconds(row);
+        const ageDays = obsEpoch === null ? null : Math.max(0, Math.floor((nowEpochSeconds - obsEpoch) / 86400));
+        const title = (row.title ?? "").trim() || (row.subtitle ?? "").trim() || `observation #${row.id}`;
+        if (!cited.length) {
+            return { id: row.id, type: row.type ?? null, title, status: "uncited", created_at: row.created_at ?? null, age_days: ageDays, citations: [] };
+        }
+        const citations = cited.map((path) => {
+            if (!signal.exists(path))
+                return { path, status: "gone", changed_at: null };
+            const changedEpoch = signal.lastChangedEpoch(path);
+            if (changedEpoch !== null && obsEpoch !== null && changedEpoch > obsEpoch) {
+                return { path, status: "drifted", changed_at: new Date(changedEpoch * 1000).toISOString() };
+            }
+            return { path, status: "verified", changed_at: null };
+        });
+        const status = citations.some((c) => c.status === "gone")
+            ? "gone"
+            : citations.some((c) => c.status === "drifted")
+                ? "drifted"
+                : "verified";
+        return { id: row.id, type: row.type ?? null, title, status, created_at: row.created_at ?? null, age_days: ageDays, citations };
+    });
+}
+function auditClaudeMemStore(projectDir, options = {}) {
+    const storePath = options.storePath ?? defaultClaudeMemStorePath();
+    const projectKey = claudeMemProjectKey(projectDir);
+    const read = readClaudeMemObservations(storePath, projectKey);
+    if (!read.ok)
+        return { ok: false, error: read.error };
+    const warnings = [];
+    if (!read.rows.length) {
+        const others = readClaudeMemProjectNames(storePath);
+        warnings.push(others.length
+            ? `No observations for project "${projectKey}". The store has: ${others.slice(0, 12).join(", ")}${others.length > 12 ? ", …" : ""}. Run from the matching directory or pass --project.`
+            : "The store has no observations at all.");
+    }
+    if (!gitHead(projectDir)) {
+        warnings.push("Git history is unavailable for this project; change detection falls back to file mtimes, which fresh checkouts reset.");
+    }
+    const nowEpoch = Math.floor(Date.now() / 1000);
+    const entries = classifyClaudeMemObservations(read.rows, buildClaudeMemChangeSignal(projectDir), nowEpoch);
+    const count = (status) => entries.filter((entry) => entry.status === status).length;
+    const epochs = read.rows.map((row) => claudeMemObservationEpochSeconds(row)).filter((epoch) => epoch !== null);
+    const spanDays = epochs.length ? Math.max(1, Math.ceil((Math.max(...epochs) - Math.min(...epochs)) / 86400)) : 0;
+    const worstOffenders = entries
+        .filter((entry) => entry.status === "drifted" || entry.status === "gone")
+        .sort((a, b) => (b.age_days ?? 0) - (a.age_days ?? 0) || a.id - b.id)
+        .slice(0, 5)
+        .map((entry) => {
+        const offending = entry.citations.find((c) => c.status === entry.status) ?? entry.citations[0];
+        const whatChanged = offending.status === "gone"
+            ? "file no longer exists"
+            : `changed ${offending.changed_at?.slice(0, 10) ?? "after capture"}${entry.created_at ? ` (captured ${entry.created_at.slice(0, 10)})` : ""}`;
+        return { id: entry.id, title: entry.title, status: entry.status, age_days: entry.age_days, path: offending.path, what_changed: whatChanged };
+    });
+    return {
+        ok: true,
+        report: {
+            schema_version: 1,
+            store_path: storePath,
+            project_dir: projectDir,
+            project_key: projectKey,
+            generated_at: nowIso(),
+            reader: read.mechanism,
+            totals: {
+                observations: entries.length,
+                verified: count("verified"),
+                drifted: count("drifted"),
+                gone: count("gone"),
+                uncited: count("uncited"),
+            },
+            span_days: spanDays,
+            worst_offenders: worstOffenders,
+            observations: entries,
+            warnings,
+        },
+    };
+}
+function renderClaudeMemAuditReceipt(report) {
+    const lines = [];
+    lines.push(`Kage audit — claude-mem store for ${report.project_key}`);
+    const total = report.totals.observations;
+    lines.push(`${total} observation${total === 1 ? "" : "s"} · captured over ${report.span_days} day${report.span_days === 1 ? "" : "s"}`);
+    if (total > 0) {
+        const pct = (n) => `${Math.round((n / total) * 100)}%`;
+        const row = (label, n, note) => `■ ${label.padEnd(10)} ${String(n).padStart(3)} (${pct(n)})  ${note}`;
+        lines.push(row("VERIFIED", report.totals.verified, "still match your code"));
+        lines.push(row("DRIFTED", report.totals.drifted, "cite files that changed since capture — may be stale"));
+        lines.push(row("GONE", report.totals.gone, "cite files that no longer exist"));
+        lines.push(row("UNCITED", report.totals.uncited, "no file citations — unverifiable by construction"));
+    }
+    if (report.worst_offenders.length) {
+        lines.push("");
+        lines.push("Worst offenders:");
+        for (const offender of report.worst_offenders) {
+            lines.push(`  • "${offender.title}" — ${offender.status.toUpperCase()}${offender.age_days !== null ? `, ${offender.age_days}d old` : ""}`);
+            lines.push(`    ${offender.path} — ${offender.what_changed}`);
+        }
+    }
+    if (report.warnings.length) {
+        lines.push("");
+        for (const warning of report.warnings)
+            lines.push(`Warning: ${warning}`);
+    }
+    lines.push("");
+    lines.push("claude-mem remembers everything. Kage tells you what's still true.");
+    lines.push("Import coming soon — https://kage-core.github.io/Kage/");
+    return lines.join("\n");
+}
 function kageReviewerSuggestions(projectDir, targets = [], changedFiles = []) {
     const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const graphPaths = new Set(graph.files.map((file) => file.path));
@@ -11997,6 +12439,20 @@ function learn(input) {
         input.evidence ? `\nEvidence: ${input.evidence.trim()}` : "",
         input.verifiedBy ? `\nVerified by: ${input.verifiedBy.trim()}` : "",
     ].join("").trim();
+    // Strict (agent/CLI) repo learnings must be grounded: a learning with no cited
+    // paths at all is rejected. Citation-free notes are allowed only in the
+    // personal store (`kage learn --personal` / learnPersonal), where recall
+    // labels them unverifiable instead of trusting them as repo facts.
+    if (input.strictCitations && !(input.paths ?? []).filter(Boolean).length && !input.allowMissingPaths) {
+        return {
+            ok: false,
+            errors: [
+                "Citation required: repo learnings must cite at least one path (--paths) so the memory stays verifiable. " +
+                    "Pass allow_missing_paths for a file you are about to create, or use kage learn --personal for a cross-repo, citation-free personal note.",
+            ],
+            warnings: [],
+        };
+    }
     return capture({
         projectDir: input.projectDir,
         title,
@@ -12011,6 +12467,7 @@ function learn(input) {
         strictCitations: input.strictCitations,
         graphNodes: input.graphNodes,
         pendingReview: input.pendingReview,
+        discoveryTokens: input.discoveryTokens,
     });
 }
 function capture(input) {
@@ -12104,6 +12561,12 @@ function capture(input) {
             reports_stale: 0,
             review_boundary: "git_or_pr",
             promotion_requires_review: true,
+            // Discovery cost receipt: what producing this knowledge cost (exploration +
+            // reasoning tokens). Caller-reported when available; otherwise a conservative
+            // per-type default, flagged estimated so receipts can qualify the claim.
+            ...(Number.isFinite(Number(input.discoveryTokens)) && Number(input.discoveryTokens) > 0
+                ? { discovery_tokens: Math.floor(Number(input.discoveryTokens)), discovery_tokens_estimated: false }
+                : { discovery_tokens: defaultDiscoveryTokens(type), discovery_tokens_estimated: true }),
         },
         created_at: createdAt,
         updated_at: createdAt,
@@ -12531,6 +12994,71 @@ print(json.dumps({"additionalContext": os.environ.get("KAGE_CONTEXT", "")}))
   fi
 fi
 
+exit 0
+`;
+        const readContextHookScript = `#!/usr/bin/env bash
+# Kage PreToolUse(Read) hook — injects verified file-linked memory right before the agent reads a file.
+# Only currently-verified packets (citations checked, not stale) are ever injected.
+# Silent if Kage is not initialized in the current project. Never blocks the Read.
+set -euo pipefail
+
+PAYLOAD="$(cat || true)"
+CWD="$(PAYLOAD="$PAYLOAD" python3 -c 'import json, os
+try:
+    d = json.loads(os.environ.get("PAYLOAD") or "{}")
+except Exception:
+    d = {}
+print(d.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or "")
+' 2>/dev/null || echo "")"
+
+[[ -d "$CWD/.agent_memory" ]] || exit 0
+command -v kage >/dev/null 2>&1 || exit 0
+
+FILE_PATH="$(PAYLOAD="$PAYLOAD" python3 -c 'import json, os
+try:
+    d = json.loads(os.environ.get("PAYLOAD") or "{}")
+except Exception:
+    d = {}
+tool_input = d.get("tool_input") or d.get("toolInput") or {}
+path = tool_input.get("file_path") if isinstance(tool_input, dict) else ""
+print(path or "")
+' 2>/dev/null || echo "")"
+[[ -n "$FILE_PATH" ]] || exit 0
+[[ "$FILE_PATH" = /* ]] || FILE_PATH="$CWD/$FILE_PATH"
+
+# Skip files outside the project: memory is repo-scoped.
+case "$FILE_PATH" in
+  "$CWD"/*) ;;
+  *) exit 0 ;;
+esac
+
+SESSION="$(PAYLOAD="$PAYLOAD" python3 -c 'import json, os
+try:
+    d = json.loads(os.environ.get("PAYLOAD") or "{}")
+except Exception:
+    d = {}
+print(d.get("session_id") or d.get("sessionId") or "default")
+' 2>/dev/null || echo "default")"
+
+# Dedup: inject at most once per file per session via a tiny /tmp state file
+# keyed by session_id+path. Failure to track must never block the Read.
+STATE_DIR="/tmp/kage-read-context"
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+KEY="$(printf "%s|%s" "$SESSION" "$FILE_PATH" | python3 -c 'import hashlib, sys
+print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest()[:24])
+' 2>/dev/null || echo "")"
+if [[ -n "$KEY" && -d "$STATE_DIR" ]]; then
+  [[ -e "$STATE_DIR/$KEY" ]] && exit 0
+  : > "$STATE_DIR/$KEY" 2>/dev/null || true
+fi
+
+CONTEXT="$(kage file-context --project "$CWD" --path "$FILE_PATH" 2>/dev/null || true)"
+if [[ -n "$CONTEXT" ]]; then
+  KAGE_CONTEXT="$CONTEXT" python3 -c 'import json, os
+print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": os.environ.get("KAGE_CONTEXT", "")}}))
+' 2>/dev/null || true
+fi
+
 exit 0
 `;
         const settingsPath = (0, node_path_1.join)(home, ".claude", "settings.json");
@@ -12538,7 +13066,11 @@ 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 }] }],
+                PreToolUse: [
+                    { matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] },
+                    // Verified memory at the moment of relevance: short timeout, never blocks the Read.
+                    { matcher: "Read", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/kage-read-context.sh", timeout: 6 }] },
+                ],
                 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 }] }],
@@ -12550,7 +13082,7 @@ exit 0
         setSnippet(path, JSON.stringify({ mcpServers: { kage: server } }, null, 2), [
             "Add the MCP server to ~/.claude.json, then restart Claude Code.",
             "alwaysLoad: true makes Kage tools immediately visible without requiring ToolSearch.",
-            `Also create ${hookDir}/session-start.sh, observe.sh, and stop.sh with the hook scripts and add SessionStart/UserPromptSubmit/PostToolUse/PostToolUseFailure/PreCompact/Stop/SessionEnd hooks to ~/.claude/settings.json.`,
+            `Also create ${hookDir}/session-start.sh, observe.sh, kage-read-context.sh, and stop.sh with the hook scripts and add SessionStart/UserPromptSubmit/PreToolUse/PostToolUse/PostToolUseFailure/PreCompact/Stop/SessionEnd hooks to ~/.claude/settings.json.`,
             "Run `kage init --project <repo>` inside each repo to install the ambient memory policy.",
         ], true);
         if (options.write) {
@@ -12559,6 +13091,7 @@ exit 0
             (0, node_fs_1.mkdirSync)(hookDir, { recursive: true });
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "session-start.sh"), hookScript, { mode: 0o755 });
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "observe.sh"), observeHookScript, { mode: 0o755 });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "kage-read-context.sh"), readContextHookScript, { mode: 0o755 });
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "stop.sh"), stopHookScript, { mode: 0o755 });
             upsertJsonSettings(settingsPath, hookEntry);
             result.wrote = true;
@@ -12699,7 +13232,7 @@ function claudeHookEventConfigured(settings, event) {
 function claudeAmbientHookSummary(homeDir) {
     const settingsPath = (0, node_path_1.join)(homeDir, ".claude", "settings.json");
     const hookDir = (0, node_path_1.join)(homeDir, ".claude", "kage", "hooks");
-    const scriptPaths = [(0, node_path_1.join)(hookDir, "session-start.sh"), (0, node_path_1.join)(hookDir, "observe.sh"), (0, node_path_1.join)(hookDir, "stop.sh")];
+    const scriptPaths = [(0, node_path_1.join)(hookDir, "session-start.sh"), (0, node_path_1.join)(hookDir, "observe.sh"), (0, node_path_1.join)(hookDir, "kage-read-context.sh"), (0, node_path_1.join)(hookDir, "stop.sh")];
     let settings = {};
     if ((0, node_fs_1.existsSync)(settingsPath)) {
         const parsed = readJson(settingsPath);
@@ -12835,6 +13368,9 @@ function observe(projectDir, event) {
     if ((0, node_fs_1.existsSync)(path))
         return { ok: true, stored: false, duplicate: true, path, errors: [] };
     const timestamp = event.timestamp ? new Date(event.timestamp).toISOString() : nowIso();
+    // Tag low-signal events at ingestion (manual learn/capture is never gated, but
+    // auto-distill skips tagged events cheaply without rescoring).
+    const lowSignal = observationSignalScore(event) < exports.AUTO_DISTILL_SIGNAL_THRESHOLD;
     const record = {
         ...event,
         schema_version: 1,
@@ -12844,6 +13380,7 @@ function observe(projectDir, event) {
         session_id: event.session_id || "default",
         timestamp,
         stored_at: nowIso(),
+        ...(lowSignal ? { low_signal: true } : {}),
     };
     writeJson(path, record);
     return { ok: true, stored: true, duplicate: false, record, path, errors: [] };
@@ -12855,6 +13392,143 @@ function loadObservations(projectDir, sessionId) {
         .filter((record) => !sessionId || record.session_id === sessionId)
         .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
 }
+// Auto-distill quality gate. Observations must score at least this (0..1) on
+// observationSignalScore before they may seed an auto-distilled draft. 0.4 was picked
+// so genuine learnings clear it comfortably (causal prose plus a path, command, or
+// code identifier lands around 0.45-0.65) while machine noise hard-rejects to 0:
+// raw JSON payloads, hook/system envelopes, flag-token dumps, sub-50-char fragments,
+// and echoes of Kage's own demo/receipt output. Manual `kage learn`/`kage capture`
+// and manual `kage distill` are never gated — explicit intent outranks the heuristic.
+exports.AUTO_DISTILL_SIGNAL_THRESHOLD = 0.4;
+// Markers of hook/system plumbing payloads that sometimes leak into observation text
+// (e.g. a raw <task-notification> block stored as a "user prompt").
+const HOOK_PAYLOAD_MARKERS = [
+    "task-notification",
+    "task_notification",
+    "tool-use-id",
+    "tool_use_id",
+    "toolu_",
+    "system-reminder",
+    "system_reminder",
+    "hookspecificoutput",
+    "hook_event_name",
+    "stop_hook_active",
+    "sessionstart hook",
+];
+// Markers of Kage's own output being echoed back as "memory" (truth-report headers,
+// demo proof lines, value-receipt fields). Storing our own output is feedback noise.
+const KAGE_ECHO_MARKERS = [
+    "truth report",
+    "hallucinated citations never enter storage",
+    "hallucinated citation",
+    "value_receipt",
+    "stale_withheld",
+    "# previously (kage)",
+];
+function jsonNoiseText(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            JSON.parse(trimmed);
+            return true;
+        }
+        catch {
+            // Not parseable; fall through to the density heuristics.
+        }
+    }
+    // Three or more quoted-key patterns reads as serialized data, not prose.
+    if ((text.match(/"[\w$.-]+"\s*:/g) ?? []).length >= 3)
+        return true;
+    const dense = text.replace(/\s+/g, "");
+    if (!dense.length)
+        return true;
+    const jsonPunctuation = (text.match(/[{}[\]":,]/g) ?? []).length;
+    return jsonPunctuation / dense.length > 0.5;
+}
+function flagTokenNoise(lower) {
+    // Dumps like "interrupted false isImage false noOutputExpected false" or
+    // "x=false y=true": several key/boolean pairs making up a large share of the text.
+    const pairs = (lower.match(/\b[a-z][\w-]*\s*[=:]?\s*(true|false|null|undefined)\b/g) ?? []).length;
+    if (pairs < 2)
+        return false;
+    const words = lower.split(/\s+/).filter(Boolean).length;
+    return words > 0 && (pairs * 2) / words >= 0.4;
+}
+// Imperative/causal vocabulary that marks durable, future-facing knowledge.
+const SIGNAL_CAUSAL_MARKERS = [
+    "fixed",
+    "because",
+    "use ",
+    "instead",
+    "run ",
+    "must",
+    "should",
+    "requires",
+    "prefer",
+    "avoid",
+    "fail",
+    "caused",
+    "root cause",
+    "why",
+    "decision",
+    "convention",
+    "gotcha",
+    "workaround",
+    "hypothesis",
+    "issue",
+    "explains",
+    "invariant",
+    "maps ",
+    "after changing",
+    "when changing",
+    "never",
+    "always",
+];
+/**
+ * Pure 0..1 signal score for an observation: how likely its text is durable,
+ * human-meaningful repo knowledge rather than machine noise. Hard rejects (0):
+ * raw JSON / key-value noise, hook or system payloads, echoes of Kage's own
+ * output, flag-token dumps, and fragments under 50 chars. Positive signal:
+ * imperative/causal language, file path citations, code identifiers, commands.
+ */
+function observationSignalScore(observation) {
+    const prose = [observation.summary, observation.text].filter(Boolean).join("\n").trim();
+    const combined = [prose, observation.command].filter(Boolean).join("\n").trim();
+    if (combined.length < 50)
+        return 0;
+    const lower = combined.toLowerCase();
+    if (HOOK_PAYLOAD_MARKERS.some((marker) => lower.includes(marker)))
+        return 0;
+    if (KAGE_ECHO_MARKERS.some((marker) => lower.includes(marker)))
+        return 0;
+    if (jsonNoiseText(combined))
+        return 0;
+    if (flagTokenNoise(lower))
+        return 0;
+    let score = 0;
+    const causalHits = SIGNAL_CAUSAL_MARKERS.filter((marker) => lower.includes(marker)).length;
+    if (causalHits > 0)
+        score += Math.min(0.35, 0.25 + (causalHits - 1) * 0.05);
+    const citesPath = Boolean(observation.path)
+        || /\b[\w.-]+\/[\w./-]+\b/.test(prose)
+        || /\b[\w-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|json|ya?ml|toml|md|sh|css|html|sql)\b/i.test(prose);
+    if (citesPath)
+        score += 0.2;
+    const codeIdentifier = /\b[a-z][a-z0-9]*[A-Z]\w*\b/.test(prose) // camelCase
+        || /\b[a-z0-9]+_[a-z0-9_]+\b/.test(prose) // snake_case
+        || /`[^`]+`/.test(prose)
+        || /\b\w+\(\)/.test(prose);
+    if (codeIdentifier)
+        score += 0.15;
+    const commandLine = Boolean(observation.command)
+        || /(^|\s)(npm|pnpm|yarn|npx|node|git|cargo|make|pytest|go|tsc|kage)\s+[\w.-]/.test(prose);
+    if (commandLine)
+        score += 0.15;
+    const words = combined.split(/\s+/).filter(Boolean).length;
+    if (combined.length >= 80 && words >= 10)
+        score += 0.1;
+    return Math.min(1, score);
+}
 function reusableFileObservation(event) {
     const text = `${event.summary ?? ""}\n${event.text ?? ""}`.trim();
     if (!text)
@@ -13346,14 +14020,18 @@ function distillSession(projectDir, sessionId, options = {}) {
     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" };
+        return { ok: true, session_id: sessionId, observations: 0, candidates: [], errors: [], mode, skipped_reason: "no_observations", skipped_low_signal: 0 };
     }
     if (auto && sessionAlreadyCaptured(projectDir, sessionId, observations)) {
-        return { ok: true, session_id: sessionId, observations: observations.length, candidates: [], errors: [], mode, skipped_reason: "session_already_captured" };
+        return { ok: true, session_id: sessionId, observations: observations.length, candidates: [], errors: [], mode, skipped_reason: "session_already_captured", skipped_low_signal: 0 };
     }
     const candidates = [];
     const errors = [];
     const observationIds = observations.map((event) => event.id);
+    // Discovery cost of distilled knowledge: the token estimate of the session material
+    // that produced it. Still an estimate (the agent's reasoning tokens are unknown),
+    // so it stays flagged discovery_tokens_estimated.
+    const sessionDiscoveryTokens = observations.reduce((sum, event) => sum + estimateTokens([event.summary, event.text, event.command, event.path].filter(Boolean).join(" ")), 0);
     const annotate = (result) => {
         if (!result.ok || !result.packet || !result.path)
             return result;
@@ -13367,6 +14045,9 @@ function distillSession(projectDir, sessionId, options = {}) {
         ];
         result.packet.quality = {
             ...result.packet.quality,
+            ...(sessionDiscoveryTokens > 0
+                ? { discovery_tokens: sessionDiscoveryTokens, discovery_tokens_estimated: true }
+                : {}),
             distillation: auto ? "auto_distill" : "automatic_observation_candidate",
             admission: evaluateMemoryAdmission(projectDir, result.packet),
             suggested_review_action: suggestedAction(classifyPacket(projectDir, result.packet), result.packet.status),
@@ -13375,9 +14056,24 @@ function distillSession(projectDir, sessionId, options = {}) {
         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));
+    // Auto-distill quality gate: drafts may only be seeded by observations scoring at
+    // least AUTO_DISTILL_SIGNAL_THRESHOLD. Events tagged low_signal at ingestion skip
+    // cheaply; untagged (older) records are scored here. Manual distill is not gated.
+    let skippedLowSignal = 0;
+    const signalGate = (events) => {
+        if (!auto)
+            return events;
+        return events.filter((event) => {
+            const lowSignal = event.low_signal === true
+                || (event.low_signal === undefined && observationSignalScore(event) < exports.AUTO_DISTILL_SIGNAL_THRESHOLD);
+            if (lowSignal)
+                skippedLowSignal += 1;
+            return !lowSignal;
+        });
+    };
+    const commandEvents = signalGate(observations.filter((event) => event.type === "command_result" && event.command));
+    const fileEvents = signalGate(observations.filter((event) => event.type === "file_change" && event.path));
+    const promptEvents = signalGate(observations.filter((event) => event.type === "user_prompt" && (event.text || event.summary)));
     const meaningfulCommandEvents = commandEvents
         .map((event) => ({ event, reusable: reusableCommandObservation(event, knownRepoCommands(projectDir)) }))
         .filter((item) => Boolean(item.reusable));
@@ -13427,10 +14123,38 @@ function distillSession(projectDir, sessionId, options = {}) {
     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, mode };
+    return {
+        ok: errors.length === 0,
+        session_id: sessionId,
+        observations: observations.length,
+        candidates,
+        errors,
+        mode,
+        ...(auto ? { skipped_low_signal: skippedLowSignal } : {}),
+    };
 }
 // 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 humanPacketAge(iso) {
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return "age unknown";
+    const minutes = Math.max(0, Math.floor((Date.now() - then) / 60000));
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 60)
+        return `${days}d ago`;
+    return `${Math.floor(days / 30)}mo ago`;
+}
+// Timeline-as-index: resume shows a compact one-line-per-packet index of recent
+// memory instead of full packets — the agent recalls details on demand.
+const RESUME_TIMELINE_LIMIT = 15;
+const RESUME_TIMELINE_DETAILED = 3;
+const RESUME_CONTEXT_TOKEN_BUDGET = 800;
 function kageResume(projectDir) {
     ensureMemoryDirs(projectDir);
     const approved = loadApprovedPackets(projectDir);
@@ -13470,7 +14194,18 @@ function kageResume(projectDir) {
     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 recentPackets = [...approved, ...pending]
+        .sort((a, b) => packetRecency(b).localeCompare(packetRecency(a)))
+        .slice(0, RESUME_TIMELINE_LIMIT);
+    const recentMemory = recentPackets.map((packet) => ({
+        id: packet.id,
+        type: packet.type,
+        title: packet.title,
+        updated_at: packetRecency(packet),
+        age: humanPacketAge(packetRecency(packet)),
+    }));
+    const hasSessionContent = Boolean(lastSession || lastChangeMemory || pendingAutoDistilled || reconciliation.unresolved_count);
+    const hasContent = hasSessionContent || recentMemory.length > 0;
     const lines = [];
     if (hasContent) {
         lines.push("# Previously (Kage)");
@@ -13495,6 +14230,22 @@ function kageResume(projectDir) {
                 lines.push(`  - ${item.packet_id}: ${item.title}`);
         }
     }
+    // Compact timeline index: one line per recent packet, full detail (summary)
+    // only for the newest few, hard-capped to the resume token budget.
+    const block = lines.slice(0, 15);
+    if (recentPackets.length) {
+        block.push("", "## Recent memory");
+        recentPackets.forEach((packet, position) => {
+            const entry = `[${packet.id.slice(0, 12)}] ${packet.type} ${packet.title} (${humanPacketAge(packetRecency(packet))})`;
+            const candidate = [entry];
+            if (position < RESUME_TIMELINE_DETAILED && packet.summary) {
+                const summary = packet.summary.replace(/\s+/g, " ").trim();
+                candidate.push(`    ${summary.length > 160 ? `${summary.slice(0, 157)}...` : summary}`);
+            }
+            if (estimateTokens([...block, ...candidate].join("\n")) <= RESUME_CONTEXT_TOKEN_BUDGET)
+                block.push(...candidate);
+        });
+    }
     return {
         schema_version: 1,
         project_dir: projectDir,
@@ -13506,7 +14257,8 @@ function kageResume(projectDir) {
         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"),
+        recent_memory: recentMemory,
+        context_block: block.join("\n"),
     };
 }
 function createDiffChangeMemory(projectDir, summary) {
@@ -14385,18 +15137,21 @@ function installClaudeSettings(projectDir) {
     writeJson(settingsPath, settings);
 }
 function initProject(projectDir, options = {}) {
-    // Default init touches ONLY .agent_memory/. Agent-policy files (AGENTS.md,
-    // CLAUDE.md) and .claude/settings.json are repo-visible and reviewable, so
-    // writing them requires explicit opt-in (`kage init --with-policy` or `kage policy`).
+    // Default init touches ONLY .agent_memory/ plus a one-line .gitattributes
+    // entry wiring the kage-packet merge driver (idempotent; ends hand-resolved
+    // packet JSON conflicts). Agent-policy files (AGENTS.md, CLAUDE.md) and
+    // .claude/settings.json are repo-visible and reviewable, so writing them
+    // requires explicit opt-in (`kage init --with-policy` or `kage policy`).
     const policyInstalled = options.policy === true;
     if (policyInstalled) {
         installAgentPolicy(projectDir);
         installClaudeSettings(projectDir);
     }
+    const gitAttributes = ensurePacketMergeAttributes(projectDir);
     const index = indexProject(projectDir, { graphs: false });
     const validation = validateProject(projectDir);
     const sampleRecall = recallFromPackets("how do I run tests", loadApprovedPackets(projectDir), 5, "Repo Memory");
-    return { index, validation, sampleRecall, policyInstalled };
+    return { index, validation, sampleRecall, policyInstalled, gitAttributes };
 }
 function doctorProject(projectDir) {
     ensureMemoryDirs(projectDir);
@@ -14490,6 +15245,82 @@ function resolveConflictedPacket(content) {
     candidates.sort((a, b) => packetRecency(b).localeCompare(packetRecency(a)));
     return candidates[0];
 }
+// ---------------------------------------------------------------------------
+// Packet merge driver. `kage merge-packet <ours> <base> <theirs>` follows the
+// git merge-driver convention (%A %O %B: write the result to the ours path,
+// exit 0 on success, non-zero to leave the conflict). v1 policy is whole-file
+// newest-wins by updated_at — packets are single facts, so field-level merges
+// buy little over taking the most recently verified side.
+exports.PACKET_MERGE_ATTRIBUTE_LINE = ".agent_memory/packets/*.json merge=kage-packet";
+exports.PACKET_MERGE_DRIVER_CONFIG = 'git config merge.kage-packet.driver "npx -y @kage-core/kage-graph-mcp merge-packet %A %O %B"';
+function mergePacketFiles(oursPath, basePath, theirsPath) {
+    void basePath; // Reserved for a future field-level three-way merge.
+    const readSide = (path) => {
+        const raw = safeReadText(path);
+        if (raw === null)
+            return null;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return { raw, packet: parsed };
+            }
+        }
+        catch {
+            // A side that carries committed conflict markers (the exact failure mode
+            // this driver exists to end) can often be recovered with repair's
+            // conflict-splitting logic before giving up on it.
+            const recovered = resolveConflictedPacket(raw);
+            if (recovered)
+                return { raw: `${JSON.stringify(recovered, null, 2)}\n`, packet: recovered };
+        }
+        return null;
+    };
+    const ours = readSide(oursPath);
+    const theirs = readSide(theirsPath);
+    if (!ours && !theirs) {
+        return { ok: false, winner: null, detail: "kage merge-packet: neither side parses as packet JSON; leaving the conflict for manual resolution." };
+    }
+    let winner;
+    if (ours && theirs) {
+        winner = packetRecency(theirs.packet).localeCompare(packetRecency(ours.packet)) > 0 ? "theirs" : "ours";
+    }
+    else {
+        winner = ours ? "ours" : "theirs";
+    }
+    const winning = winner === "ours" ? ours : theirs;
+    try {
+        (0, node_fs_1.writeFileSync)(oursPath, winning.raw, "utf8");
+    }
+    catch (error) {
+        return { ok: false, winner: null, detail: `kage merge-packet: failed to write merge result: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const recency = packetRecency(winning.packet);
+    return {
+        ok: true,
+        winner,
+        detail: `kage merge-packet: kept ${winner} side (newest updated_at${recency ? ` ${recency}` : ""}).`,
+    };
+}
+// Idempotently wire .gitattributes so packet JSON uses the kage-packet merge
+// driver. Re-runs never duplicate the line; a stale driver value on the same
+// pattern is replaced in place.
+function ensurePacketMergeAttributes(projectDir) {
+    const path = (0, node_path_1.join)(projectDir, ".gitattributes");
+    const existing = safeReadText(path) ?? "";
+    const lines = existing.split(/\r?\n/);
+    const pattern = /^\.agent_memory\/packets\/\*\.json\s+merge=/;
+    const index = lines.findIndex((line) => pattern.test(line.trim()));
+    if (index !== -1) {
+        if (lines[index].trim() === exports.PACKET_MERGE_ATTRIBUTE_LINE)
+            return { path, changed: false };
+        lines[index] = exports.PACKET_MERGE_ATTRIBUTE_LINE;
+        (0, node_fs_1.writeFileSync)(path, `${lines.join("\n").replace(/\n+$/, "")}\n`, "utf8");
+        return { path, changed: true };
+    }
+    const prefix = existing.length ? (existing.endsWith("\n") ? existing : `${existing}\n`) : "";
+    (0, node_fs_1.writeFileSync)(path, `${prefix}${exports.PACKET_MERGE_ATTRIBUTE_LINE}\n`, "utf8");
+    return { path, changed: true };
+}
 function repairProject(projectDir, options = {}) {
     ensureMemoryDirs(projectDir);
     const actions = [];
@@ -15045,3 +15876,525 @@ function kageMemoryTimeline(projectDir, days = 14) {
         recommendations,
     };
 }
+// ---------------------------------------------------------------------------
+// Personal memory (~/.kage/memory) + kage sync — cross-machine continuity
+// (docs/CLOUD.md v1). Repo memory follows the repo through git; personal
+// memory follows the PERSON: packets live in the user's home store and sync
+// through the user's own private git remote. Trust rules stay structural:
+// personal packets may cite the current project's files (validated and
+// fingerprinted exactly like repo memory, re-verified against the local
+// checkout on every recall, in any clone) or carry no citations at all —
+// allowed ONLY here, and labeled unverifiable on recall. Personal packets
+// never enter repo flows (pr-check, stale-catch, refresh, access tracking).
+// ---------------------------------------------------------------------------
+function kageHomeDir() {
+    const override = process.env.KAGE_HOME?.trim();
+    return override ? (0, node_path_1.resolve)(override) : (0, node_path_1.join)((0, node_os_1.homedir)(), ".kage");
+}
+function personalMemoryDir() {
+    return (0, node_path_1.join)(kageHomeDir(), "memory");
+}
+function personalPacketsDir() {
+    return (0, node_path_1.join)(personalMemoryDir(), "packets");
+}
+function personalConflictsDir() {
+    return (0, node_path_1.join)(personalMemoryDir(), "conflicts");
+}
+function loadPersonalPackets() {
+    return loadPacketsFromDir(personalPacketsDir()).filter((packet) => packet.status === "approved");
+}
+function makePersonalPacketId(type, title, suffix) {
+    return `personal:${type}:${slugify(`${title}-${suffix}`)}`;
+}
+function learnPersonal(input) {
+    // Same privacy guarantee as repo learn: <private> spans never reach disk.
+    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 = [
+        input.learning.trim(),
+        input.evidence ? `\nEvidence: ${input.evidence.trim()}` : "",
+        input.verifiedBy ? `\nVerified by: ${input.verifiedBy.trim()}` : "",
+    ].join("").trim();
+    return capturePersonal({
+        projectDir: input.projectDir,
+        title,
+        summary: summarize(input.learning),
+        body,
+        type,
+        tags: unique(["personal", ...(input.tags ?? [])]),
+        paths: input.paths,
+        stack: input.stack,
+        context: input.context,
+        allowMissingPaths: input.allowMissingPaths,
+        discoveryTokens: input.discoveryTokens,
+    });
+}
+function capturePersonal(input) {
+    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}`] };
+    }
+    // Personal memory syncs to a remote, so the secret scan matters MORE here, not less.
+    const scanFindings = scanSensitiveText([input.title, input.summary ?? "", input.body].join("\n"));
+    if (scanFindings.length) {
+        return { ok: false, errors: [`Sensitive content blocked: ${unique(scanFindings).join(", ")}`] };
+    }
+    const warnings = [];
+    const citedPaths = (input.paths ?? []).filter((path) => path && !isGroundingIgnored(input.projectDir, path));
+    const meaningfulPaths = citedPaths.filter((path) => meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+    const missingPaths = meaningfulPaths.filter((path) => !pathExistsInRepo(input.projectDir, path));
+    // Cited personal packets follow the SAME write-time rule as repo memory: a packet
+    // whose every cited path is missing from the current project is a hallucinated
+    // citation and is rejected. The citation-FREE case below is the only personal escape.
+    if (meaningfulPaths.length && missingPaths.length === meaningfulPaths.length && !input.allowMissingPaths) {
+        return {
+            ok: false,
+            errors: [
+                `Citation validation failed: none of the referenced paths exist in this project: ${missingPaths.join(", ")}. ` +
+                    `Fix the paths, drop them for a citation-free personal note, or pass allow_missing_paths.`,
+            ],
+            warnings: [],
+        };
+    }
+    if (missingPaths.length) {
+        warnings.push(`Some referenced paths do not exist in this project: ${missingPaths.join(", ")}`);
+    }
+    const createdAt = nowIso();
+    const fingerprints = memoryPathFingerprints(input.projectDir, citedPaths);
+    // Citation-free personal packets are allowed but structurally second-class:
+    // marked unverifiable at write time so recall can label them as such.
+    const unverifiable = fingerprints.length === 0;
+    if (unverifiable) {
+        warnings.push("Personal packet has no verifiable citations; recall will label it unverifiable.");
+    }
+    const packet = {
+        schema_version: exports.PACKET_SCHEMA_VERSION,
+        id: makePersonalPacketId(type, input.title, String(Date.now())),
+        title: input.title.trim(),
+        summary: (input.summary?.trim() || summarize(input.body)),
+        body: input.body.trim(),
+        type,
+        scope: "personal",
+        visibility: "private",
+        sensitivity: "internal",
+        status: "approved",
+        confidence: DEFAULT_CONFIDENCE,
+        tags: input.tags ?? [],
+        paths: citedPaths,
+        stack: input.stack ?? [],
+        source_refs: [
+            {
+                kind: "personal_capture",
+                captured_at: createdAt,
+                project: repoDisplayName(input.projectDir),
+            },
+        ],
+        context: inferEngineeringContext({ title: input.title, body: input.body, context: input.context }),
+        freshness: {
+            ttl_days: 365,
+            last_verified_at: createdAt,
+            path_fingerprints: fingerprints,
+            path_fingerprint_policy: "source_hash_staleness",
+            verification: unverifiable ? "unverifiable_personal" : "personal_capture_cited",
+        },
+        edges: [],
+        quality: {
+            reviewer: "personal",
+            votes_up: 0,
+            votes_down: 0,
+            uses_30d: 0,
+            reports_stale: 0,
+            unverifiable,
+            review_boundary: "personal_store",
+            promotion_requires_review: true,
+            ...(Number.isFinite(Number(input.discoveryTokens)) && Number(input.discoveryTokens) > 0
+                ? { discovery_tokens: Math.floor(Number(input.discoveryTokens)), discovery_tokens_estimated: false }
+                : { discovery_tokens: defaultDiscoveryTokens(type), discovery_tokens_estimated: true }),
+        },
+        created_at: createdAt,
+        updated_at: createdAt,
+        author_branch: null,
+    };
+    const validation = validatePacket(packet);
+    if (!validation.ok)
+        return { ok: false, errors: validation.errors, warnings };
+    ensureDir(personalPacketsDir());
+    const path = (0, node_path_1.join)(personalPacketsDir(), packetFileName(packet));
+    writeJson(path, packet);
+    return { ok: true, packet, path, errors: [], warnings };
+}
+// Personal-memory candidates for a repo recall. Cited packets are re-verified
+// against THIS checkout (relative paths + content fingerprints), so the same
+// packet that recalls fine in one clone is withheld in a repo where its
+// evidence does not exist — the docs/CLOUD.md "verified sync" rule.
+function personalRecallEntries(projectDir, terms, limit = 3) {
+    const packets = loadPersonalPackets();
+    if (!packets.length)
+        return [];
+    const cache = new Map();
+    const eligible = packets.filter((packet) => recallHardStaleReason(projectDir, packet, cache) === null);
+    if (!eligible.length)
+        return [];
+    const scores = scorePacketsBm25(terms, eligible);
+    return eligible
+        .map((packet) => {
+        const { score, why } = scores.get(packet.id) ?? { score: 0, why: [] };
+        return {
+            packet,
+            score,
+            why_matched: why,
+            unverifiable: packetStoredPathFingerprints(packet).length === 0,
+        };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.packet.title.localeCompare(b.packet.title))
+        .slice(0, Math.max(1, limit));
+}
+function runSyncGit(cwd, args) {
+    try {
+        const stdout = (0, node_child_process_1.execFileSync)("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        return { ok: true, stdout: String(stdout ?? "").trim(), stderr: "" };
+    }
+    catch (error) {
+        const failed = error;
+        return {
+            ok: false,
+            stdout: String(failed.stdout ?? "").trim(),
+            stderr: String(failed.stderr ?? failed.message ?? "git command failed").trim(),
+        };
+    }
+}
+// Commits must work on machines without a global git identity (fresh CI boxes,
+// brand-new laptops); fall back to a kage-sync identity instead of failing.
+function syncIdentityArgs(memoryDir) {
+    const email = runSyncGit(memoryDir, ["config", "user.email"]);
+    return email.ok && email.stdout ? [] : ["-c", "user.name=kage-sync", "-c", "user.email=kage-sync@localhost"];
+}
+const SYNC_SETUP_HINT = "Run: kage sync setup --remote <git-url>";
+function syncPacketFile(file) {
+    return file.startsWith("packets/") && file.endsWith(".json");
+}
+function countSyncPacketFiles(namesOutput) {
+    return namesOutput
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter(syncPacketFile)
+        .length;
+}
+function syncRemoteDefaultBranch(memoryDir) {
+    // "ref: refs/heads/<branch>\tHEAD" — empty remotes return nothing.
+    const result = runSyncGit(memoryDir, ["ls-remote", "--symref", "origin", "HEAD"]);
+    if (!result.ok)
+        return null;
+    const match = result.stdout.match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD/m);
+    return match?.[1] ?? null;
+}
+// Auto-resolve a rebase conflict on a packet file: newest updated_at wins
+// (same policy as the kage-packet merge driver), the losing version is
+// preserved under conflicts/<name>.<unix-ts>.json so no data is ever lost,
+// and the worktree file is rewritten as clean JSON — never conflict markers.
+function resolvePacketSyncConflict(memoryDir, file) {
+    // During a rebase, stage 2 ("ours") is the upstream side already in the new
+    // history; stage 3 ("theirs") is the local commit being replayed.
+    const readStage = (stage) => {
+        const show = runSyncGit(memoryDir, ["show", `:${stage}:${file}`]);
+        if (!show.ok)
+            return null;
+        try {
+            const parsed = JSON.parse(show.stdout);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // An unparsable side loses to a parsable one.
+        }
+        return null;
+    };
+    const upstreamSide = readStage(2);
+    const localSide = readStage(3);
+    if (!upstreamSide && !localSide) {
+        return { ok: false, error: `kage sync: neither side of ${file} parses as packet JSON; resolve manually in ${memoryDir}.` };
+    }
+    const localWins = Boolean(localSide && (!upstreamSide || packetRecency(localSide).localeCompare(packetRecency(upstreamSide)) > 0));
+    const winner = localWins ? localSide : upstreamSide;
+    const loser = localWins ? upstreamSide : localSide;
+    writeJson((0, node_path_1.join)(memoryDir, file), winner);
+    let backupPath;
+    if (loser) {
+        ensureDir(personalConflictsDir());
+        const base = (0, node_path_1.basename)(file, ".json");
+        let candidate = (0, node_path_1.join)(personalConflictsDir(), `${base}.${Math.floor(Date.now() / 1000)}.json`);
+        let counter = 1;
+        while ((0, node_fs_1.existsSync)(candidate)) {
+            candidate = (0, node_path_1.join)(personalConflictsDir(), `${base}.${Math.floor(Date.now() / 1000)}-${counter}.json`);
+            counter += 1;
+        }
+        writeJson(candidate, loser);
+        backupPath = candidate;
+    }
+    return { ok: true, backupPath };
+}
+function rebaseOntoUpstream(memoryDir, upstream) {
+    const conflictBackups = [];
+    let resolved = 0;
+    let step = runSyncGit(memoryDir, [...syncIdentityArgs(memoryDir), "-c", "core.editor=true", "rebase", upstream]);
+    while (!step.ok) {
+        const conflicted = runSyncGit(memoryDir, ["diff", "--name-only", "--diff-filter=U"])
+            .stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+        if (!conflicted.length) {
+            // The resolved commit became empty (we kept the upstream side wholesale).
+            const skip = runSyncGit(memoryDir, [...syncIdentityArgs(memoryDir), "-c", "core.editor=true", "rebase", "--skip"]);
+            if (skip.ok) {
+                step = skip;
+                continue;
+            }
+            runSyncGit(memoryDir, ["rebase", "--abort"]);
+            return { ok: false, resolved, conflictBackups, error: `git rebase failed: ${step.stderr || skip.stderr}` };
+        }
+        for (const file of conflicted) {
+            if (!syncPacketFile(file)) {
+                runSyncGit(memoryDir, ["rebase", "--abort"]);
+                return { ok: false, resolved, conflictBackups, error: `kage sync only auto-resolves packets/*.json conflicts; ${file} needs manual resolution in ${memoryDir}.` };
+            }
+            const resolution = resolvePacketSyncConflict(memoryDir, file);
+            if (!resolution.ok) {
+                runSyncGit(memoryDir, ["rebase", "--abort"]);
+                return { ok: false, resolved, conflictBackups, error: resolution.error };
+            }
+            if (resolution.backupPath)
+                conflictBackups.push(resolution.backupPath);
+            resolved += 1;
+            const toAdd = [file, ...(resolution.backupPath ? [(0, node_path_1.relative)(memoryDir, resolution.backupPath)] : [])];
+            runSyncGit(memoryDir, ["add", "--", ...toAdd]);
+        }
+        step = runSyncGit(memoryDir, [...syncIdentityArgs(memoryDir), "-c", "core.editor=true", "rebase", "--continue"]);
+    }
+    return { ok: true, resolved, conflictBackups };
+}
+function syncSetup(remoteUrl) {
+    const memoryDir = personalMemoryDir();
+    ensureDir(personalPacketsDir());
+    const result = {
+        ok: false,
+        memory_dir: memoryDir,
+        remote: remoteUrl,
+        initialized: false,
+        remote_updated: false,
+        branch: null,
+        pushed: false,
+        errors: [],
+    };
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(memoryDir, ".git"))) {
+        const init = runSyncGit(memoryDir, ["init"]);
+        if (!init.ok) {
+            result.errors.push(`git init failed: ${init.stderr}`);
+            return result;
+        }
+        result.initialized = true;
+    }
+    // Keep the packets dir trackable even before the first capture.
+    const keep = (0, node_path_1.join)(personalPacketsDir(), ".gitkeep");
+    if (!(0, node_fs_1.existsSync)(keep))
+        (0, node_fs_1.writeFileSync)(keep, "", "utf8");
+    const currentRemote = runSyncGit(memoryDir, ["remote", "get-url", "origin"]);
+    if (!currentRemote.ok) {
+        const added = runSyncGit(memoryDir, ["remote", "add", "origin", remoteUrl]);
+        if (!added.ok) {
+            result.errors.push(`git remote add failed: ${added.stderr}`);
+            return result;
+        }
+        result.remote_updated = true;
+    }
+    else if (currentRemote.stdout !== remoteUrl) {
+        const updated = runSyncGit(memoryDir, ["remote", "set-url", "origin", remoteUrl]);
+        if (!updated.ok) {
+            result.errors.push(`git remote set-url failed: ${updated.stderr}`);
+            return result;
+        }
+        result.remote_updated = true;
+    }
+    // Commit local state before aligning with the remote.
+    runSyncGit(memoryDir, ["add", "-A"]);
+    const status = runSyncGit(memoryDir, ["status", "--porcelain"]);
+    const hasHead = runSyncGit(memoryDir, ["rev-parse", "--verify", "--quiet", "HEAD"]).ok;
+    if (status.stdout || !hasHead) {
+        const commit = runSyncGit(memoryDir, [
+            ...syncIdentityArgs(memoryDir),
+            "commit",
+            "-m",
+            "kage sync setup",
+            ...(status.stdout ? [] : ["--allow-empty"]),
+        ]);
+        if (!commit.ok) {
+            result.errors.push(`git commit failed: ${commit.stderr}`);
+            return result;
+        }
+    }
+    const fetch = runSyncGit(memoryDir, ["fetch", "origin"]);
+    if (!fetch.ok) {
+        result.errors.push(`git fetch failed: ${fetch.stderr}`);
+        return result;
+    }
+    // A second machine pointing at an existing remote must converge on the
+    // remote's branch instead of pushing a parallel one: rename the local branch
+    // to match and rebase local commits (the setup commit) on top.
+    const remoteBranch = syncRemoteDefaultBranch(memoryDir);
+    if (remoteBranch && runSyncGit(memoryDir, ["rev-parse", "--verify", "--quiet", `origin/${remoteBranch}`]).ok) {
+        const renamed = runSyncGit(memoryDir, ["branch", "-M", remoteBranch]);
+        if (!renamed.ok) {
+            result.errors.push(`git branch -M failed: ${renamed.stderr}`);
+            return result;
+        }
+        const rebase = rebaseOntoUpstream(memoryDir, `origin/${remoteBranch}`);
+        if (!rebase.ok) {
+            result.errors.push(rebase.error ?? "git rebase failed");
+            return result;
+        }
+    }
+    result.branch = runSyncGit(memoryDir, ["rev-parse", "--abbrev-ref", "HEAD"]).stdout || null;
+    let push = runSyncGit(memoryDir, ["push", "-u", "origin", "HEAD"]);
+    if (!push.ok && /non-fast-forward|behind|fetch first/i.test(push.stderr)) {
+        // Some git versions leave the local branch behind the remote after the
+        // convergence rebase (observed on CI's git, not on macOS). A second
+        // fetch + rebase fast-forwards a behind branch, after which push succeeds.
+        runSyncGit(memoryDir, ["fetch", "origin"]);
+        const retryBranch = syncRemoteDefaultBranch(memoryDir) ?? result.branch;
+        if (retryBranch && runSyncGit(memoryDir, ["rev-parse", "--verify", "--quiet", `origin/${retryBranch}`]).ok) {
+            runSyncGit(memoryDir, ["branch", "-M", retryBranch]);
+            const retryRebase = rebaseOntoUpstream(memoryDir, `origin/${retryBranch}`);
+            if (retryRebase.ok)
+                push = runSyncGit(memoryDir, ["push", "-u", "origin", "HEAD"]);
+        }
+    }
+    if (!push.ok) {
+        const state = runSyncGit(memoryDir, ["log", "--oneline", "--all", "--decorate", "-n", "8"]).stdout;
+        result.errors.push(`git push failed: ${push.stderr}${state ? `
+repo state:
+${state}` : ""}`);
+        return result;
+    }
+    result.pushed = true;
+    result.ok = true;
+    return result;
+}
+function syncStatus() {
+    const memoryDir = personalMemoryDir();
+    const result = {
+        ok: false,
+        memory_dir: memoryDir,
+        remote: null,
+        branch: null,
+        ahead: 0,
+        behind: 0,
+        dirty: false,
+        warnings: [],
+        errors: [],
+    };
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(memoryDir, ".git"))) {
+        result.errors.push(`Personal memory store is not set up for sync. ${SYNC_SETUP_HINT}`);
+        return result;
+    }
+    const remote = runSyncGit(memoryDir, ["remote", "get-url", "origin"]);
+    if (!remote.ok) {
+        result.errors.push(`No sync remote configured. ${SYNC_SETUP_HINT}`);
+        return result;
+    }
+    result.remote = remote.stdout;
+    // Status is read-only on the network: fetch only, never pull/push.
+    const fetch = runSyncGit(memoryDir, ["fetch", "origin"]);
+    if (!fetch.ok)
+        result.warnings.push(`git fetch failed (showing last-known remote state): ${fetch.stderr}`);
+    result.branch = runSyncGit(memoryDir, ["rev-parse", "--abbrev-ref", "HEAD"]).stdout || null;
+    const upstream = result.branch ? `origin/${result.branch}` : null;
+    if (upstream && runSyncGit(memoryDir, ["rev-parse", "--verify", "--quiet", upstream]).ok) {
+        const counts = runSyncGit(memoryDir, ["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+        if (counts.ok) {
+            const [ahead, behind] = counts.stdout.split(/\s+/).map((value) => Number(value));
+            result.ahead = Number.isFinite(ahead) ? ahead : 0;
+            result.behind = Number.isFinite(behind) ? behind : 0;
+        }
+    }
+    result.dirty = Boolean(runSyncGit(memoryDir, ["status", "--porcelain"]).stdout);
+    result.ok = true;
+    return result;
+}
+function syncPersonal() {
+    const memoryDir = personalMemoryDir();
+    const result = {
+        ok: false,
+        memory_dir: memoryDir,
+        remote: null,
+        pushed: 0,
+        pulled: 0,
+        resolved: 0,
+        conflict_backups: [],
+        errors: [],
+    };
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(memoryDir, ".git"))) {
+        result.errors.push(`Personal memory store is not set up for sync. ${SYNC_SETUP_HINT}`);
+        return result;
+    }
+    const remote = runSyncGit(memoryDir, ["remote", "get-url", "origin"]);
+    if (!remote.ok) {
+        result.errors.push(`No sync remote configured. ${SYNC_SETUP_HINT}`);
+        return result;
+    }
+    result.remote = remote.stdout;
+    // 1. Commit local packet changes.
+    runSyncGit(memoryDir, ["add", "-A"]);
+    if (runSyncGit(memoryDir, ["status", "--porcelain"]).stdout) {
+        const commit = runSyncGit(memoryDir, [...syncIdentityArgs(memoryDir), "commit", "-m", `kage sync ${nowIso()}`]);
+        if (!commit.ok) {
+            result.errors.push(`git commit failed: ${commit.stderr}`);
+            return result;
+        }
+    }
+    // 2. Pull --rebase (split into fetch + rebase so the receipt can count what came in).
+    const fetch = runSyncGit(memoryDir, ["fetch", "origin"]);
+    if (!fetch.ok) {
+        result.errors.push(`git fetch failed: ${fetch.stderr}`);
+        return result;
+    }
+    const branch = runSyncGit(memoryDir, ["rev-parse", "--abbrev-ref", "HEAD"]).stdout;
+    const upstream = `origin/${branch}`;
+    const hasUpstream = Boolean(branch) && runSyncGit(memoryDir, ["rev-parse", "--verify", "--quiet", upstream]).ok;
+    if (hasUpstream) {
+        // Their side of the merge base: packet files this sync will bring in.
+        const incoming = runSyncGit(memoryDir, ["diff", "--name-only", `HEAD...${upstream}`]);
+        result.pulled = countSyncPacketFiles(incoming.stdout);
+        const rebase = rebaseOntoUpstream(memoryDir, upstream);
+        result.resolved = rebase.resolved;
+        result.conflict_backups = rebase.conflictBackups;
+        if (!rebase.ok) {
+            result.errors.push(rebase.error ?? "git rebase failed");
+            return result;
+        }
+    }
+    // 3. Push (first push sets the upstream).
+    const outgoing = hasUpstream
+        ? runSyncGit(memoryDir, ["diff", "--name-only", `${upstream}..HEAD`])
+        : runSyncGit(memoryDir, ["ls-tree", "-r", "--name-only", "HEAD"]);
+    result.pushed = countSyncPacketFiles(outgoing.stdout);
+    const push = runSyncGit(memoryDir, ["push", "-u", "origin", "HEAD"]);
+    if (!push.ok) {
+        result.errors.push(`git push failed: ${push.stderr}`);
+        return result;
+    }
+    result.ok = true;
+    return result;
+}