prism-mcp-server 5.2.0 → 5.5.0

package/dist/tools/agentRegistryHandlers.js

@@ -112,12 +112,13 @@ export async function agentHeartbeatHandler(args) {
     }
     const effectiveRole = args.role || await getSetting("default_role", "global");
     const storage = await getStorage();
-    await storage.heartbeatAgent(args.project, PRISM_USER_ID, effectiveRole, args.current_task);
+    await storage.heartbeatAgent(args.project, PRISM_USER_ID, effectiveRole, args.current_task, args.expected_duration_minutes);
     return {
         content: [{
                 type: "text",
                 text: `💓 Heartbeat updated for **${escapeMd(effectiveRole)}** on \`${escapeMd(args.project)}\`.` +
-                    (args.current_task ? ` Task: ${escapeMd(args.current_task)}` : ""),
+                    (args.current_task ? ` Task: ${escapeMd(args.current_task)}` : "") +
+                    (args.expected_duration_minutes ? ` (ETA: ${args.expected_duration_minutes}m)` : ""),
             }],
     };
 }
@@ -138,25 +139,42 @@ export async function agentListTeamHandler(args) {
                 }],
         };
     }
+    // v5.3: Health-state indicator mapping
+    const statusIndicators = {
+        active: "🟢 Active",
+        idle: "💤 Idle",
+        shutdown: "⚫ Offline",
+        stale: "🟡 Stale",
+        frozen: "🔴 Frozen",
+        overdue: "⏰ Overdue",
+        looping: "🔄 Looping",
+    };
     const lines = team.map(agent => {
         const icon = getRoleIcon(agent.role);
         const ago = agent.last_heartbeat
             ? getTimeAgo(agent.last_heartbeat)
             : "unknown";
+        const healthIndicator = statusIndicators[agent.status] || `❓ ${agent.status}`;
         // escapeMd() applied to all user-controlled fields to prevent
         // markdown metacharacters in task descriptions from corrupting output
         return (`${icon} **${escapeMd(agent.role)}**` +
             (agent.agent_name ? ` (${escapeMd(agent.agent_name)})` : "") +
-            ` — ${escapeMd(agent.status)}` +
+            ` — ${healthIndicator}` +
             (agent.current_task ? ` | Task: ${escapeMd(agent.current_task)}` : "") +
+            (agent.loop_count && agent.loop_count >= 3 ? ` | 🔄 Loop: ${agent.loop_count}x` : "") +
             ` | Last seen: ${ago}`);
     });
+    // Count agents by health state for summary
+    const healthyCt = team.filter(a => a.status === "active" || a.status === "idle").length;
+    const warnCt = team.filter(a => ["stale", "overdue", "looping", "frozen"].includes(a.status)).length;
     return {
         content: [{
                 type: "text",
-                text: `## 🐝 Active Hivemind Team — \`${escapeMd(args.project)}\`\n\n` +
+                text: `## 🐝 Hivemind Team — \`${escapeMd(args.project)}\`\n\n` +
                     lines.join("\n") +
-                    `\n\n_${team.length} agent(s) active. Stale agents (>30min) auto-pruned._`,
+                    `\n\n_${team.length} agent(s) | ${healthyCt} healthy` +
+                    (warnCt > 0 ? ` | ⚠️ ${warnCt} need attention` : "") +
+                    `_\n_Watchdog monitoring active: health checked every 60s._`,
             }],
     };
 }

package/dist/tools/index.js

@@ -26,8 +26,8 @@ export { webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, br
 // This file always exports them — server.ts decides whether to include them in the tool list.
 //
 // v0.4.0: Added SESSION_COMPACT_LEDGER_TOOL and SESSION_SEARCH_MEMORY_TOOL
-export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_FORGET_MEMORY_TOOL, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, isDeepStoragePurgeArgs } from "./sessionMemoryDefinitions.js";
-export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler, sessionForgetMemoryHandler, knowledgeSetRetentionHandler, sessionSaveExperienceHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, knowledgeSyncRulesHandler, sessionExportMemoryHandler, deepStoragePurgeHandler } from "./sessionMemoryHandlers.js";
+export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_FORGET_MEMORY_TOOL, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, SESSION_INTUITIVE_RECALL_TOOL, isDeepStoragePurgeArgs } from "./sessionMemoryDefinitions.js";
+export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler, sessionForgetMemoryHandler, knowledgeSetRetentionHandler, sessionSaveExperienceHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, knowledgeSyncRulesHandler, sessionExportMemoryHandler, deepStoragePurgeHandler, sessionIntuitiveRecallHandler } from "./sessionMemoryHandlers.js";
 // ── Compaction Handler (v0.4.0 — Enhancement #2) ──
 // The compaction handler is in a separate file because it's significantly
 // more complex than the other session memory handlers (chunked Gemini

package/dist/tools/sessionMemoryDefinitions.js

@@ -55,6 +55,9 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
     description: "Upsert the latest project handoff state for the next session to consume on boot. " +
         "This is the 'live context' that gets loaded when a new session starts. " +
         "Calling this replaces the previous handoff for the same project (upsert on project).\n\n" +
+        "**v5.4 CRDT Merge**: On version conflict, a CRDT OR-Map engine automatically merges " +
+        "your changes with concurrent work (Add-Wins OR-Set for arrays, Last-Writer-Wins for scalars). " +
+        "Pass expected_version to enable concurrency control.\n\n" +
         "**v0.4.0 OCC**: If you received a version number from session_load_context, " +
         "/resume_session prompt, or memory resource attachment, you MUST pass it as " +
         "expected_version to prevent overwriting another session's changes.",
@@ -92,6 +95,10 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
                 type: "string",
                 description: "Optional. Agent role for Hivemind scoping (e.g., 'dev', 'qa', 'pm'). Omit to let the server auto-resolve from dashboard settings.",
             },
+            disable_merge: {
+                type: "boolean",
+                description: "Set to true to disable automatic CRDT merging and fail strictly on version conflict (original OCC behavior). Default: false.",
+            },
         },
         required: ["project"],
     },
@@ -369,6 +376,7 @@ export function isSessionSaveLedgerArgs(args) {
 }
 // REVIEWER NOTE: v0.4.0 adds expected_version to the type guard
 // for optimistic concurrency control. It's optional for backward compat.
+// v5.4: Added disable_merge for CRDT bypass.
 export function isSessionSaveHandoffArgs(args) {
     return (typeof args === "object" &&
         args !== null &&
@@ -902,7 +910,44 @@ export function isDeepStoragePurgeArgs(args) {
         return false;
     if (a.older_than_days !== undefined && typeof a.older_than_days !== "number")
         return false;
-    if (a.dry_run !== undefined && typeof a.dry_run !== "boolean")
+    return true;
+}
+// ─── v5.5: SDM Intuitive Recall Tool ──────────────────────────
+export const SESSION_INTUITIVE_RECALL_TOOL = {
+    name: "session_intuitive_recall",
+    description: "Manually trigger the Sparse Distributed Memory (SDM) Intuitive Recall to surface latent patterns " +
+        "and related memories for a given query without blowing up the context window. " +
+        "Uses high-speed JS-space Hamming distance scanning on compressed embeddings.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project identifier.",
+            },
+            query: {
+                type: "string",
+                description: "The text query or context to trigger the recall.",
+            },
+            limit: {
+                type: "integer",
+                description: "Maximum number of latent patterns to surface (default: 3).",
+            },
+            threshold: {
+                type: "number",
+                description: "Similarity threshold 0-1 (default: 0.55).",
+            },
+        },
+        required: ["project", "query"],
+    },
+};
+export function isSessionIntuitiveRecallArgs(args) {
+    if (typeof args !== "object" || args === null)
+        return false;
+    const a = args;
+    if (typeof a.project !== "string")
+        return false;
+    if (typeof a.query !== "string")
         return false;
     return true;
 }

package/dist/tools/sessionMemoryHandlers.js

@@ -21,6 +21,7 @@ import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
 import { getCurrentGitState, getGitDrift } from "../utils/git.js";
 import { getSetting, getAllSettings } from "../storage/configStorage.js";
+import { mergeHandoff, dbToHandoffSchema } from "../utils/crdtMerge.js";
 // ─── Phase 1: Explainability & Memory Lineage ────────────────
 // These utilities provide structured tracing metadata for search operations.
 // When `enable_trace: true` is passed to session_search_memory or knowledge_search,
@@ -39,11 +40,13 @@ isSessionSaveExperienceArgs, isKnowledgeVoteArgs,
 // v4.2: Sync Rules type guard
 isKnowledgeSyncRulesArgs, 
 // v5.1: Deep Storage Mode type guard
-isDeepStoragePurgeArgs, } from "./sessionMemoryDefinitions.js";
+isDeepStoragePurgeArgs, 
+// v5.5: SDM Intuitive Recall type guard
+isSessionIntuitiveRecallArgs, } from "./sessionMemoryDefinitions.js";
 // v4.2: File system access for knowledge_sync_rules
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { join, dirname, resolve, isAbsolute, sep } from "node:path";
+import { join, dirname, resolve, isAbsolute, relative } from "node:path";
 // v3.1: In-memory debounce lock for auto-compaction.
 // Prevents multiple concurrent Gemini compaction tasks for the same project
 // when many agents call session_save_ledger at the same time.
@@ -201,7 +204,7 @@ export async function sessionSaveHandoffHandler(args, server) {
         `(expected_version=${expected_version ?? "none"})`);
     // Auto-extract keywords from summary + context for knowledge accumulation
     const combinedText = [last_summary || "", key_context || ""].filter(Boolean).join(" ");
-    const keywords = combinedText ? toKeywordArray(combinedText) : undefined;
+    let keywords = combinedText ? toKeywordArray(combinedText) : undefined;
     if (keywords) {
         debugLog(`[session_save_handoff] Extracted ${keywords.length} keywords: ${keywords.slice(0, 5).join(", ")}...`);
     }
@@ -215,7 +218,7 @@ export async function sessionSaveHandoffHandler(args, server) {
     }
     // Save via storage backend (OCC-aware)
     const effectiveRole = role || await getSetting("default_role", "global");
-    const data = await storage.saveHandoff({
+    let data = await storage.saveHandoff({
         project,
         user_id: PRISM_USER_ID,
         last_summary: last_summary ?? null,
@@ -227,32 +230,99 @@ export async function sessionSaveHandoffHandler(args, server) {
         metadata,
         role: effectiveRole, // v3.0: Hivemind role scoping (dashboard fallback)
     }, expected_version ?? null);
-    // ─── Handle version conflict ───
+    // ─── v5.4: CRDT Auto-Merge Resolution Loop ──────────────────
+    //
+    // Instead of returning a conflict error, we now:
+    //   1. Fetch the base state (the version the incoming agent read)
+    //   2. Fetch the current DB state (what beat the incoming agent)
+    //   3. Run a 3-way CRDT merge (OR-Set for arrays, LWW for scalars)
+    //   4. Retry the save with the merged state
+    //
+    // This converts what was previously an error into an automatic merge.
+    // The loop handles the rare case where ANOTHER save sneaks in during
+    // our merge (up to MAX_ATTEMPTS retries before giving up).
+    const MAX_MERGE_ATTEMPTS = 3;
+    let mergeAttempts = 0;
+    let isMerged = false;
+    let mergeStrategy = null;
+    while (data.status === "conflict" && mergeAttempts < MAX_MERGE_ATTEMPTS) {
+        // If the user explicitly disabled CRDT merging, return old OCC error
+        if (args.disable_merge) {
+            debugLog(`[session_save_handoff] VERSION CONFLICT for "${project}": ` +
+                `expected=${expected_version}, current=${data.current_version} (merge disabled)`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `⚠️ Version conflict detected for project "${project}"!\n\n` +
+                            `You sent version ${expected_version}, but the current version is ${data.current_version}.\n` +
+                            `Auto-merge is disabled. Please call session_load_context to see the latest changes, ` +
+                            `then manually merge your updates and try saving again.`,
+                    }],
+                isError: true,
+            };
+        }
+        debugLog(`[session_save_handoff] CRDT merge attempt ${mergeAttempts + 1}/${MAX_MERGE_ATTEMPTS} ` +
+            `for "${project}" (expected=${expected_version}, current=${data.current_version})`);
+        // Step 1: Fetch the base state (what the incoming agent originally read)
+        const baseDbState = expected_version
+            ? await storage.getHandoffAtVersion(project, expected_version, PRISM_USER_ID)
+            : null;
+        const baseState = dbToHandoffSchema(baseDbState);
+        // Step 2: Fetch current DB state (what beat us to the save)
+        const currentDbState = await storage.loadContext(project, "standard", PRISM_USER_ID);
+        const currentState = dbToHandoffSchema(currentDbState);
+        if (!currentState || !currentDbState) {
+            debugLog("[session_save_handoff] CRDT merge failed: could not load current state");
+            break; // Safety fallback — can't merge without both sides
+        }
+        // Step 3: Build the incoming state from the original args
+        const incomingState = {
+            summary: last_summary || "",
+            active_branch: active_branch,
+            key_context: key_context,
+            pending_todo: open_todos,
+            active_decisions: undefined,
+            keywords: keywords,
+        };
+        // Step 4: Run 3-way CRDT merge
+        const crdt = mergeHandoff(baseState, incomingState, currentState);
+        mergeStrategy = crdt.strategy;
+        isMerged = true;
+        debugLog(`[session_save_handoff] CRDT merge strategy: ${JSON.stringify(crdt.strategy)}`);
+        // Step 5: Build merged handoff and retry save
+        const mergedExpectedVersion = currentDbState.version;
+        data = await storage.saveHandoff({
+            project,
+            user_id: PRISM_USER_ID,
+            last_summary: crdt.merged.summary ?? null,
+            pending_todo: crdt.merged.pending_todo ?? null,
+            active_decisions: crdt.merged.active_decisions ?? null,
+            keywords: crdt.merged.keywords ?? null,
+            key_context: crdt.merged.key_context ?? null,
+            active_branch: crdt.merged.active_branch ?? null,
+            metadata: {
+                ...metadata,
+                crdt_merge_count: (currentDbState.metadata?.crdt_merge_count || 0) + 1,
+                last_merge_strategy: crdt.strategy,
+            },
+            role: effectiveRole,
+        }, mergedExpectedVersion ?? null);
+        // Update these for the snapshot/notification blocks below
+        if (data.status !== "conflict") {
+            // Merge succeeded — update local vars for the success path
+            keywords = crdt.merged.keywords ?? keywords;
+        }
+        mergeAttempts++;
+    }
+    // After all merge attempts exhausted, still a conflict → give up
     if (data.status === "conflict") {
-        debugLog(`[session_save_handoff] VERSION CONFLICT for "${project}": ` +
-            `expected=${expected_version}, current=${data.current_version}`);
+        debugLog(`[session_save_handoff] CRDT merge exhausted after ${MAX_MERGE_ATTEMPTS} attempts for "${project}"`);
         return {
             content: [{
                     type: "text",
-                    text: `⚠️ Version conflict detected for project "${project}"!\n\n` +
-                        `You sent version ${expected_version}, but the current version is ${data.current_version}.\n` +
-                        `Another session has updated this project since you loaded context.\n\n` +
-                        `Please call session_load_context to see what changed, then merge ` +
-                        `it with your attempted updates:\n` +
-                        (last_summary
-                            ? `  Your attempted summary: ${last_summary}\n`
-                            : "") +
-                        (open_todos?.length
-                            ? `  Your attempted TODOs: ${JSON.stringify(open_todos)}\n`
-                            : "") +
-                        (key_context
-                            ? `  Your attempted key_context: ${key_context}\n`
-                            : "") +
-                        (active_branch
-                            ? `  Your attempted active_branch: ${active_branch}\n`
-                            : "") +
-                        `\nAfter reviewing the latest state, call session_save_handoff again ` +
-                        `with the updated expected_version.`,
+                    text: `⚠️ CRDT auto-merge failed for "${project}" after ${MAX_MERGE_ATTEMPTS} attempts ` +
+                        `due to high contention. Please run session_load_context to see the latest state ` +
+                        `and try saving again.`,
                 }],
             isError: true,
         };
@@ -388,16 +458,24 @@ export async function sessionSaveHandoffHandler(args, server) {
         // Dynamic import itself failed — module not found or similar
         console.error("[FactMerger] Module load failed (non-fatal): " + err));
     }
+    // Build response text based on whether a CRDT merge occurred
+    const responseText = isMerged
+        ? `🔄 Auto-merged conflict for "${project}" (v${expected_version} → v${newVersion})\n` +
+            `Strategy: ${JSON.stringify(mergeStrategy)}\n` +
+            (last_summary ? `Summary: ${last_summary}\n` : "") +
+            `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
+            `to maintain concurrency control.`
+        : `✅ Handoff ${data.status || "saved"} for project "${project}" ` +
+            `(version: ${newVersion})\n` +
+            (last_summary ? `Last summary: ${last_summary}\n` : "") +
+            (open_todos?.length ? `Open TODOs: ${open_todos.length} items\n` : "") +
+            (active_branch ? `Active branch: ${active_branch}\n` : "") +
+            `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
+            `to maintain concurrency control.`;
     return {
         content: [{
                 type: "text",
-                text: `✅ Handoff ${data.status || "saved"} for project "${project}" ` +
-                    `(version: ${newVersion})\n` +
-                    (last_summary ? `Last summary: ${last_summary}\n` : "") +
-                    (open_todos?.length ? `Open TODOs: ${open_todos.length} items\n` : "") +
-                    (active_branch ? `Active branch: ${active_branch}\n` : "") +
-                    `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
-                    `to maintain concurrency control.`,
+                text: responseText,
             }],
         isError: false,
     };
@@ -587,8 +665,36 @@ export async function sessionLoadContextHandler(args) {
         const skillPart = skillLoaded ? ` · 📜 \`${effectiveRole}\` skill loaded` : (effectiveRole ? " · 📜 No skill configured" : "");
         greetingBlock = `\n\n[👤 AGENT IDENTITY]\n${namePart}${rolePart}${skillPart}`;
     }
+    // ─── SDM Intuitive Recall (v5.5) ───
+    // Generate embedding of current context and fetch latent SDM patterns
+    let sdmRecallBlock = "";
+    if (level !== "quick" && GOOGLE_API_KEY) {
+        try {
+            const activeText = [d.last_summary, d.key_context, ...(d.keywords || [])].filter(Boolean).join(" ");
+            if (activeText.length > 10) {
+                // v2.1 LLM factory handles the API call
+                const queryVector = await getLLMProvider().generateEmbedding(activeText);
+                // Lazy-load to avoid blocking server boot
+                const { getSdmEngine } = await import("../sdm/sdmEngine.js");
+                const { decodeSdmVector } = await import("../sdm/sdmDecoder.js");
+                const sdmEngine = getSdmEngine(project);
+                const targetVector = sdmEngine.read(new Float32Array(queryVector));
+                const topMatches = await decodeSdmVector(project, targetVector, 3, 0.55);
+                if (topMatches.length > 0) {
+                    sdmRecallBlock = `\n\n[🧠 INTUITIVE RECALL]\nThe deeper Superposed Memory matrix resonated with your current task and surfaced these latent patterns:\n`;
+                    for (const match of topMatches) {
+                        sdmRecallBlock += `- [Sim: ${(match.similarity * 100).toFixed(1)}%] ${match.summary}\n`;
+                    }
+                    debugLog(`[session_load_context] SDM Recall surfaced ${topMatches.length} latent patterns`);
+                }
+            }
+        }
+        catch (err) {
+            debugLog(`[session_load_context] SDM Recall failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+        }
+    }
     // Build the response object before v4.0 augmentations
-    let responseText = `📋 Session context for "${project}" (${level}):\n\n${formattedContext.trim()}${driftReport}${briefingBlock}${greetingBlock}${visualMemoryBlock}${skillBlock}${versionNote}`;
+    let responseText = `📋 Session context for "${project}" (${level}):\n\n${formattedContext.trim()}${driftReport}${briefingBlock}${sdmRecallBlock}${greetingBlock}${visualMemoryBlock}${skillBlock}${versionNote}`;
     // ─── v4.0: Behavioral Warnings Injection ───────────────────
     // If loadContext returned behavioral_warnings, add them to the
     // formatted output so the agent sees them prominently.
@@ -1059,10 +1165,13 @@ export async function backfillEmbeddingsHandler(args) {
         "embedding": "is.null",
         "archived_at": "is.null",
         user_id: `eq.${PRISM_USER_ID}`,
-        order: "created_at.desc",
+        order: "id.asc",
         limit: String(safeLimit),
         select: "id,summary,decisions,project",
     };
+    if (args._cursor_id) {
+        params.id = `gt.${args._cursor_id}`;
+    }
     if (project) {
         params.project = `eq.${project}`;
     }
@@ -1143,6 +1252,7 @@ export async function backfillEmbeddingsHandler(args) {
                         : `All entries now have embeddings for semantic search.`),
             }],
         isError: false,
+        _stats: { repaired, failed, last_id: entries[entries.length - 1]?.id },
     };
 }
 // ─── Memory History Handler (v2.0 — Time Travel) ─────────────
@@ -1482,8 +1592,28 @@ export async function sessionHealthCheckHandler(args) {
             if (embeddingIssue && embeddingIssue.count > 0) {
                 debugLog("[Health Check] Auto-fixing " + embeddingIssue.count + " missing embeddings...");
                 try {
-                    await backfillEmbeddingsHandler({ dry_run: false, limit: 50 });
-                    fixedCount += embeddingIssue.count;
+                    let hasMore = true;
+                    let cursorId = undefined;
+                    while (hasMore) {
+                        const result = await backfillEmbeddingsHandler({ dry_run: false, limit: 50, _cursor_id: cursorId });
+                        const stats = result._stats;
+                        if (stats) {
+                            fixedCount += stats.repaired;
+                            if (stats.last_id) {
+                                cursorId = stats.last_id;
+                            }
+                            else {
+                                hasMore = false;
+                            }
+                            // If we repaired + failed less than 50, we're done
+                            if ((stats.repaired + stats.failed) < 50) {
+                                hasMore = false;
+                            }
+                        }
+                        else {
+                            hasMore = false; // Fallback if no stats returned
+                        }
+                    }
                     debugLog("[Health Check] Backfill complete.");
                 }
                 catch (err) {
@@ -1940,9 +2070,10 @@ export async function knowledgeSyncRulesHandler(args) {
     // Resolve both paths to their canonical forms, then assert containment
     const resolvedRepo = resolve(normalizedRepoPath);
     const targetPath = resolve(resolvedRepo, target_file);
+    const relativePath = relative(resolvedRepo, targetPath);
     // Ensure the resolved target is strictly inside the repo root
     // (handles "../../../etc/hosts" style traversal)
-    if (!targetPath.startsWith(resolvedRepo + sep)) {
+    if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
         return {
             content: [{
                     type: "text",
@@ -2224,3 +2355,44 @@ export async function deepStoragePurgeHandler(args) {
         isError: false,
     };
 }
+// ─── v5.5: SDM Intuitive Recall Handler ───────────────────────
+export async function sessionIntuitiveRecallHandler(args) {
+    if (!isSessionIntuitiveRecallArgs(args)) {
+        return {
+            content: [{ type: "text", text: "Invalid arguments for session_intuitive_recall" }],
+            isError: true,
+        };
+    }
+    try {
+        const { getSdmEngine } = await import("../sdm/sdmEngine.js");
+        const { decodeSdmVector } = await import("../sdm/sdmDecoder.js");
+        const queryVector = await getLLMProvider().generateEmbedding(args.query);
+        const sdmEngine = getSdmEngine(args.project);
+        const targetVector = sdmEngine.read(new Float32Array(queryVector));
+        const limit = args.limit ?? 3;
+        const threshold = args.threshold ?? 0.55;
+        const topMatches = await decodeSdmVector(args.project, targetVector, limit, threshold);
+        let recallBlock = `🧠 **SDM Intuitive Recall for "${args.project}"**\n\n`;
+        recallBlock += `Query: "${args.query}"\n`;
+        recallBlock += `Target vector generated. Scanning ${topMatches.length > 0 ? topMatches.length + " latents surfaced." : "No strong patterns surfaced."}\n\n`;
+        if (topMatches.length === 0) {
+            recallBlock += `*No stored patterns resonated above the ${(threshold * 100).toFixed(1)}% similarity threshold.*`;
+        }
+        else {
+            for (const match of topMatches) {
+                recallBlock += `- [Similarity: ${(match.similarity * 100).toFixed(1)}%] ${match.summary}\n`;
+            }
+        }
+        return {
+            content: [{ type: "text", text: recallBlock }],
+            isError: false,
+        };
+    }
+    catch (err) {
+        debugLog(`[session_intuitive_recall] Failed: ${err}`);
+        return {
+            content: [{ type: "text", text: `Error triggering Intuitive Recall: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+}

package/dist/utils/briefing.js

@@ -6,7 +6,7 @@
  *
  * ═══════════════════════════════════════════════════════════════════
  * DESIGN DECISIONS:
- *   - Uses gemini-2.0-flash for max speed (~2-3s generation)
+ *   - Uses gemini-2.5-flash for max speed (~2-3s generation)
  *   - Graceful fallback if no API key or Gemini call fails
  *   - Prompt is tuned for brevity — exactly 3 bullets, no fluff
  *   - Reuses GOOGLE_API_KEY from config.ts (same key as embeddings)

package/dist/utils/crdtMerge.js

@@ -0,0 +1,152 @@
+/**
+ * CRDT Handoff Merge Engine (v5.4 Phase 2)
+ *
+ * Provides a zero-dependency, in-memory OR-Map implementation for resolving
+ * concurrent agent state changes deterministically.
+ *
+ * Design:
+ * - Arrays (TODOs, decisions, keywords) use Add-Wins OR-Set semantics.
+ * - Tombstones are ephemeral: calculated via 3-way diff against the base state.
+ * - Scalars (summary, context) use Last-Writer-Wins (LWW) Register semantics.
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * REVIEWER NOTE (v5.4):
+ *
+ * WHY BESPOKE, NOT YJS/AUTOMERGE?
+ * - Our merge surface is tiny: 6 fields (3 arrays, 2 scalars, 1 optional map).
+ * - Yjs adds ~50-200KB to the bundle and requires a stateful document model.
+ * - Automerge's WASM runtime would break MCP cold-start (<1s requirement).
+ * - This module is ~100 LOC, zero deps, and fully deterministic.
+ *
+ * TOMBSTONE STRATEGY:
+ * Tombstones are computed in-memory by diffing the `base` state against each
+ * agent's submission. They exist only for the duration of the merge operation —
+ * no database columns, no growing tombstone tables, no cleanup cron jobs.
+ * This works because handoff state is a live document (upserted, not appended).
+ * ═══════════════════════════════════════════════════════════════════
+ */
+// ─── OR-Set Logic (Add-Wins) ────────────────────────────────────
+//
+// 3-way set merge:
+//   added_by_incoming = incoming - base
+//   removed_by_incoming = base - incoming
+//   added_by_current = current - base
+//   removed_by_current = base - current
+//   result = (base - removals) ∪ all_adds
+//
+// "Add-Wins" means: if Agent A removes "X" and Agent B adds "X",
+// the add wins. This is safe for TODOs (better to have a duplicate
+// than lose work) and keywords (idempotent).
+function mergeArray(b = [], i = [], c = []) {
+    const bSet = new Set(b);
+    const iSet = new Set(i);
+    const cSet = new Set(c);
+    const removals = new Set();
+    const adds = new Set();
+    // Items explicitly removed by either agent
+    for (const item of bSet) {
+        if (!iSet.has(item))
+            removals.add(item);
+        if (!cSet.has(item))
+            removals.add(item);
+    }
+    // Items freshly added by either agent
+    for (const item of iSet)
+        if (!bSet.has(item))
+            adds.add(item);
+    for (const item of cSet)
+        if (!bSet.has(item))
+            adds.add(item);
+    // Final state: (Base - Removals) ∪ Adds
+    const result = new Set();
+    for (const item of bSet)
+        if (!removals.has(item))
+            result.add(item);
+    for (const item of adds)
+        result.add(item);
+    return Array.from(result);
+}
+// ─── LWW Register Logic ────────────────────────────────────────
+//
+// If the incoming agent changed a scalar, its value wins (latest intent).
+// If the incoming agent left it untouched, the current DB value wins.
+// If both changed it, incoming wins (the caller is the latest writer).
+function mergeScalar(b, i, c) {
+    const incomingChanged = i !== b;
+    const currentChanged = c !== b;
+    if (!incomingChanged && !currentChanged) {
+        return { value: c, winner: "no-change" };
+    }
+    if (incomingChanged) {
+        return { value: i, winner: "lww-incoming" };
+    }
+    return { value: c, winner: "lww-current" };
+}
+// ─── Main Merge Function ────────────────────────────────────────
+/**
+ * 3-Way CRDT Merge for Handoff State.
+ *
+ * @param base     The state both agents read (at the conflicting version).
+ *                 If null, treated as an empty state (first handoff).
+ * @param incoming The state submitted by the agent that lost the OCC race.
+ * @param current  The state currently in the DB (the OCC winner).
+ * @returns        The conflict-free merged state + per-field audit trail.
+ */
+export function mergeHandoff(base, incoming, current) {
+    const safeBase = base || { summary: "" };
+    const strategy = {};
+    // ─── Scalars (LWW) ───
+    const summaryMerge = mergeScalar(safeBase.summary, incoming.summary, current.summary);
+    const branchMerge = mergeScalar(safeBase.active_branch, incoming.active_branch, current.active_branch);
+    const contextMerge = mergeScalar(safeBase.key_context, incoming.key_context, current.key_context);
+    strategy.summary = summaryMerge.winner;
+    strategy.active_branch = branchMerge.winner;
+    strategy.key_context = contextMerge.winner;
+    // ─── Arrays (OR-Set) ───
+    const mergedTodos = mergeArray(safeBase.pending_todo || [], incoming.pending_todo || [], current.pending_todo || []);
+    const mergedDecisions = mergeArray(safeBase.active_decisions || [], incoming.active_decisions || [], current.active_decisions || []);
+    const mergedKeywords = mergeArray(safeBase.keywords || [], incoming.keywords || [], current.keywords || []);
+    strategy.pending_todo = "or-set-union";
+    strategy.active_decisions = "or-set-union";
+    strategy.keywords = "or-set-union";
+    const merged = {
+        summary: summaryMerge.value || current.summary || "",
+        active_branch: branchMerge.value,
+        key_context: contextMerge.value,
+        pending_todo: mergedTodos,
+        active_decisions: mergedDecisions,
+        keywords: mergedKeywords,
+    };
+    return { merged, strategy };
+}
+// ─── Adapter: DB Record → HandoffSchema ─────────────────────────
+//
+// Extracts the merge-relevant fields from either a loadContext result
+// or a history snapshot. Tolerant of both {last_summary} and {summary}
+// naming conventions (handler vs. DB column inconsistency).
+export function dbToHandoffSchema(dbState) {
+    if (!dbState)
+        return null;
+    const toStringArray = (v) => {
+        if (Array.isArray(v))
+            return v;
+        if (typeof v === "string") {
+            try {
+                const parsed = JSON.parse(v);
+                return Array.isArray(parsed) ? parsed : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    };
+    return {
+        summary: dbState.last_summary || dbState.summary || "",
+        active_branch: dbState.active_branch ?? null,
+        key_context: dbState.key_context ?? null,
+        pending_todo: toStringArray(dbState.pending_todo),
+        active_decisions: toStringArray(dbState.active_decisions),
+        keywords: toStringArray(dbState.keywords),
+    };
+}