prism-mcp-server 9.2.3 → 9.2.5

package/README.md

@@ -789,8 +789,9 @@ The Generator strips the `console.log`, resubmits, and the next `EVALUATE` retur
 
 ## 🆕 What's New
 
-> **Current release: v9.2.3 — Code Review Hardening**
+> **Current release: v9.2.4 — Cross-Backend Reconciliation**
 
+- 🔄 **v9.2.4 — Cross-Backend Reconciliation:** Automatic two-layer sync from Supabase → SQLite on startup. When Claude Desktop writes handoffs and ledger entries to Supabase, Antigravity (local SQLite) now automatically detects stale data and pulls newer handoffs + the 20 most recent ledger entries. 5-second timeout prevents startup freeze. Targeted ID lookups (not full table scans) keep it safe for large databases. 13 tests including malformed JSON resilience, multi-role dedup, and timeout handling.
 - 🔧 **v9.2.3 — Code Review Hardening:** 10x faster split-brain detection (lightweight direct queries replace full `StorageBackend` construction), variable shadowing fix in CLI, resource leak fix in SQLite alternate client.
 - 🚨 **v9.2.2 — Critical: Split-Brain Detection & Prevention:** When multiple MCP clients use different storage backends (e.g., Claude Desktop → Supabase, Antigravity → SQLite), session state could silently diverge, causing agents to act on stale TODOs and outdated context. **New: `--storage` flag** on `prism load` CLI lets callers explicitly select which backend to read from. **New: Split-Brain Drift Detection** in `session_load_context` — compares active and alternate backend versions at load time and warns prominently when they diverge. Session loader script updated to respect `PRISM_STORAGE` environment variable.
 - 💻 **v9.2.1 — CLI Full Feature Parity:** `prism load` text mode now delegates to the real `session_load_context` handler, giving CLI-only users the same enriched output as MCP clients: morning briefings, reality drift detection, SDM intuitive recall, visual memory index, role-scoped skill injection, behavioral warnings, importance scores, and agent identity. JSON mode now includes `agent_name` from dashboard settings. Session loader script PATH fix for Homebrew/nvm/volta environments.
@@ -1220,10 +1221,14 @@ Prism MCP is open-source and free for individual developers. For teams and enter
 
 ## 📦 Milestones & Roadmap
 
-> **Current: v9.1.0** — Task Router v2 & Local Agent Hardening ([CHANGELOG](CHANGELOG.md))
+> **Current: v9.2.4** — Cross-Backend Reconciliation ([CHANGELOG](CHANGELOG.md))
 
 | Release | Headline |
 |---------|----------|
+| **v9.2.4** | 🔄 Cross-Backend Reconciliation — automatic Supabase → SQLite sync on startup, two-layer (handoff + ledger), 5s timeout, 13 tests |
+| **v9.2.3** | 🔧 Code Review Hardening — 10x faster split-brain detection, variable shadowing fix, resource leak fix |
+| **v9.2.2** | 🚨 Split-Brain Detection & Prevention — `--storage` flag, drift detection, session loader hardening |
+| **v9.2.1** | 💻 CLI Full Feature Parity — text mode enrichments, agent identity, PATH fix |
 | **v9.1.0** | 🚦 Task Router v2 — file-type routing signal, 6-signal heuristics, local agent streaming buffer |
 | **v9.0.5** | 🔒 JWKS Auth Security Hardening — audience/issuer validation, JWT failure logging, typed agent identity |
 | **v9.0** | 🧠 Autonomous Cognitive OS — Surprisal Gate, Cognitive Budget, Affect-Tagged Memory |

package/dist/storage/index.js

@@ -60,6 +60,51 @@ export async function getStorage() {
             `Must be "local" or "supabase".`);
     }
     await storageInstance.initialize();
+    // ─── v9.2.4: Cross-Backend Handoff Reconciliation ──────────────
+    // When running on local SQLite but Supabase credentials exist,
+    // pull any newer handoffs from Supabase into SQLite. This fixes
+    // the split-brain where Claude Desktop writes go to Supabase but
+    // Antigravity reads from SQLite and sees stale data.
+    //
+    // IMPORTANT: The supabaseReady check above only resolves dashboard
+    // credentials when requestedBackend==="supabase". For reconciliation
+    // we need credentials even when backend is "local", so we do a
+    // second probe here.
+    if (activeStorageBackend === "local") {
+        let canReconcile = supabaseReady;
+        if (!canReconcile) {
+            // Probe dashboard config for Supabase credentials
+            const dashUrl = await getSetting("SUPABASE_URL");
+            const dashKey = await getSetting("SUPABASE_KEY");
+            if (dashUrl && dashKey) {
+                try {
+                    const parsed = new URL(dashUrl);
+                    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+                        canReconcile = true;
+                        process.env.SUPABASE_URL = dashUrl;
+                        process.env.SUPABASE_KEY = dashKey;
+                        debugLog("[Prism Storage] Reconciliation: using Supabase credentials from dashboard config");
+                    }
+                }
+                catch {
+                    // Invalid URL — skip reconciliation
+                }
+            }
+        }
+        if (canReconcile) {
+            try {
+                const { reconcileHandoffs } = await import("./reconcile.js");
+                const { SqliteStorage } = await import("./sqlite.js");
+                const sqliteInstance = storageInstance;
+                const getTimestamps = () => sqliteInstance.getHandoffTimestamps();
+                await reconcileHandoffs(storageInstance, getTimestamps);
+            }
+            catch (err) {
+                // Non-fatal: reconciliation is best-effort
+                debugLog(`[Prism Storage] Reconciliation skipped: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
     return storageInstance;
 }
 /**

package/dist/storage/reconcile.js

@@ -0,0 +1,237 @@
+/**
+ * Cross-Backend Handoff & Ledger Reconciliation (v9.2.4)
+ *
+ * Fixes the split-brain data inconsistency where writes made via
+ * Claude Desktop (Supabase) are invisible to Antigravity (local SQLite).
+ *
+ * SYNCS TWO LAYERS:
+ *   1. session_handoffs — latest project state (TODOs, summary, decisions)
+ *   2. session_ledger   — recent session history (used by standard/deep loads)
+ *
+ * WHEN THIS RUNS:
+ *   - Automatically during getStorage() initialization when:
+ *     1. The active backend is "local" (SQLite), AND
+ *     2. Supabase credentials are available (env or dashboard config)
+ *
+ * PERFORMANCE:
+ *   - 2 Supabase REST calls per synced project:
+ *     - session_handoffs: 1-5 rows (~1KB) → instant
+ *     - session_ledger: last 20 entries per stale project (~50KB) → fast
+ *   - Local SQLite: bulk timestamp check + targeted ID lookups + N upserts
+ *   - Total: ~300-800ms (dominated by network, not DB)
+ *   - Safe for databases with millions of entries — scoped queries only
+ *
+ * DESIGN:
+ *   - Read-only on Supabase (never writes to remote)
+ *   - Last-writer-wins by updated_at/created_at timestamp
+ *   - Non-blocking: wrapped in try/catch, errors downgraded to debug log
+ *   - Idempotent: safe to run on every boot (ledger uses ID dedup)
+ *   - 5-second timeout on Supabase calls to prevent startup freeze
+ */
+import { supabaseGet } from "../utils/supabaseApi.js";
+import { debugLog } from "../utils/logger.js";
+import { PRISM_USER_ID } from "../config.js";
+/** Timeout for each Supabase REST call (ms). Prevents startup freeze. */
+const RECONCILE_TIMEOUT_MS = 5_000;
+/**
+ * Safely parse a JSON array field from Supabase.
+ * Handles: arrays (pass-through), JSON strings (parse), garbage (empty array).
+ * Never throws.
+ */
+function safeParseArray(val) {
+    if (Array.isArray(val))
+        return val;
+    if (typeof val === "string") {
+        try {
+            const parsed = JSON.parse(val);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+/**
+ * Wrap a promise with a timeout. Rejects with AbortError if exceeded.
+ */
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`[Reconcile] Timeout after ${ms}ms: ${label}`)), ms);
+        promise.then((val) => { clearTimeout(timer); resolve(val); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
+/**
+ * Pull newer handoffs AND recent ledger entries from Supabase into local SQLite.
+ *
+ * @param localStorage - The initialized SqliteStorage instance
+ * @param getLocalTimestamps - Function to bulk-read local handoff timestamps
+ * @returns Summary of what was synced
+ */
+export async function reconcileHandoffs(localStorage, getLocalTimestamps) {
+    const result = { checked: 0, synced: 0, projects: [], ledgerEntriesSynced: 0 };
+    try {
+        // ═══════════════════════════════════════════════════════════
+        // LAYER 1: Handoff Reconciliation (session_handoffs)
+        // ═══════════════════════════════════════════════════════════
+        // Step 1: Fetch all handoffs from Supabase (single REST call, ~1-5 rows)
+        // Timeout prevents startup freeze if Supabase is slow/unreachable.
+        const remoteHandoffs = await withTimeout(supabaseGet("session_handoffs", {
+            user_id: `eq.${PRISM_USER_ID}`,
+            select: "*",
+        }), RECONCILE_TIMEOUT_MS, "fetch handoffs");
+        if (!Array.isArray(remoteHandoffs) || remoteHandoffs.length === 0) {
+            debugLog("[Reconcile] No remote handoffs found — nothing to sync");
+            return result;
+        }
+        result.checked = remoteHandoffs.length;
+        // Step 2: Get all local handoff timestamps in one query (not per-project)
+        let localTimestamps;
+        if (getLocalTimestamps) {
+            localTimestamps = await getLocalTimestamps();
+        }
+        else {
+            // Fallback: empty map means all remotes will be synced
+            localTimestamps = new Map();
+        }
+        // Step 3: Compare and sync only stale handoffs
+        // Use a Set to deduplicate projects with multiple roles (FIX #6)
+        const syncedProjectsSet = new Set();
+        for (const remote of remoteHandoffs) {
+            const project = remote.project;
+            const role = remote.role || "global";
+            const key = `${project}::${role}`;
+            const remoteUpdatedAt = remote.updated_at;
+            const localUpdatedAt = localTimestamps.get(key);
+            // Sync if: local doesn't exist, or remote is newer
+            const needsSync = !localUpdatedAt
+                || (remoteUpdatedAt && new Date(remoteUpdatedAt) > new Date(localUpdatedAt));
+            if (needsSync) {
+                // FIX #4: safeParseArray prevents JSON.parse crash from aborting all projects
+                await localStorage.saveHandoff({
+                    project,
+                    user_id: PRISM_USER_ID,
+                    role,
+                    last_summary: remote.last_summary ?? null,
+                    pending_todo: safeParseArray(remote.pending_todo),
+                    active_decisions: safeParseArray(remote.active_decisions),
+                    keywords: safeParseArray(remote.keywords),
+                    key_context: remote.key_context ?? null,
+                    active_branch: remote.active_branch ?? null,
+                    metadata: typeof remote.metadata === "object" && remote.metadata !== null ? remote.metadata : {},
+                });
+                result.synced++;
+                result.projects.push(project);
+                syncedProjectsSet.add(project); // FIX #6: dedup multi-role projects
+                debugLog(`[Reconcile] Synced handoff "${project}" (role: ${role}) — ` +
+                    `remote: ${remoteUpdatedAt}, local: ${localUpdatedAt || "missing"}`);
+            }
+        }
+        // ═══════════════════════════════════════════════════════════
+        // LAYER 2: Recent Ledger Reconciliation (session_ledger)
+        //
+        // For any project whose handoff was stale, also pull recent
+        // ledger entries so that standard/deep context loads include
+        // session history written via Supabase.
+        //
+        // We only pull the last 20 entries per project (not the full
+        // history) — this covers standard/deep context needs without
+        // doing a bulk data migration.
+        // ═══════════════════════════════════════════════════════════
+        if (syncedProjectsSet.size > 0) {
+            result.ledgerEntriesSynced = await reconcileLedger(localStorage, [...syncedProjectsSet]);
+        }
+        if (result.synced > 0) {
+            // FIX #7: Use debugLog instead of console.error for non-error output
+            debugLog(`[Prism Reconcile] Synced ${result.synced} handoff(s)` +
+                `${result.ledgerEntriesSynced > 0 ? ` + ${result.ledgerEntriesSynced} ledger entries` : ""}` +
+                ` from Supabase → SQLite: ${result.projects.join(", ")}`);
+        }
+        else {
+            debugLog("[Reconcile] All local data is up-to-date with Supabase");
+        }
+    }
+    catch (err) {
+        // Non-fatal: log and continue. Supabase may be unreachable (offline mode).
+        debugLog(`[Reconcile] Failed to reconcile (non-fatal): ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+    return result;
+}
+/**
+ * Pull recent ledger entries from Supabase for the given projects.
+ *
+ * Uses targeted ID lookup for dedup: only queries the specific IDs
+ * returned from Supabase, not the entire local ledger. (FIX #2)
+ *
+ * @param localStorage - The initialized StorageBackend (SQLite)
+ * @param projects - Deduplicated list of projects with stale handoffs
+ * @returns Number of ledger entries synced
+ */
+async function reconcileLedger(localStorage, projects) {
+    let totalSynced = 0;
+    for (const project of projects) {
+        try {
+            // Fetch the 20 most recent ledger entries for this project
+            // Timeout prevents hang if Supabase is slow (FIX #3)
+            const remoteLedger = await withTimeout(supabaseGet("session_ledger", {
+                user_id: `eq.${PRISM_USER_ID}`,
+                project: `eq.${project}`,
+                archived_at: "is.null",
+                deleted_at: "is.null",
+                select: "id,project,conversation_id,summary,user_id,role,todos,files_changed,decisions,keywords,event_type,importance,created_at,session_date",
+                order: "created_at.desc",
+                limit: "20",
+            }), RECONCILE_TIMEOUT_MS, `fetch ledger for ${project}`);
+            if (!Array.isArray(remoteLedger) || remoteLedger.length === 0) {
+                continue;
+            }
+            // FIX #2: Only query the specific IDs we need to check — not the entire ledger.
+            // This is O(remote_count) not O(total_ledger_entries).
+            const remoteIds = remoteLedger.map(e => e.id);
+            const existingEntries = await localStorage.getLedgerEntries({
+                ids: remoteIds,
+                select: "id",
+            });
+            const existingIds = new Set((Array.isArray(existingEntries) ? existingEntries : [])
+                .map((e) => e.id));
+            // Insert only entries that don't exist locally
+            for (const entry of remoteLedger) {
+                if (existingIds.has(entry.id)) {
+                    continue; // Already exists locally
+                }
+                try {
+                    await localStorage.saveLedger({
+                        id: entry.id,
+                        project: entry.project,
+                        conversation_id: entry.conversation_id || "reconciled",
+                        summary: entry.summary,
+                        user_id: PRISM_USER_ID,
+                        role: entry.role || "global",
+                        todos: safeParseArray(entry.todos),
+                        files_changed: safeParseArray(entry.files_changed),
+                        decisions: safeParseArray(entry.decisions),
+                        keywords: safeParseArray(entry.keywords),
+                        event_type: entry.event_type || "session",
+                        importance: entry.importance || 0,
+                    });
+                    totalSynced++;
+                }
+                catch (insertErr) {
+                    // Skip entries that fail (e.g., UNIQUE constraint = already exists)
+                    const msg = insertErr instanceof Error ? insertErr.message : String(insertErr);
+                    if (!msg.includes("UNIQUE") && !msg.includes("constraint")) {
+                        debugLog(`[Reconcile] Failed to insert ledger entry ${entry.id}: ${msg}`);
+                    }
+                }
+            }
+            debugLog(`[Reconcile] Ledger sync for "${project}": ${remoteLedger.length} remote, ` +
+                `${existingIds.size} already local, ${totalSynced} new`);
+        }
+        catch (err) {
+            debugLog(`[Reconcile] Ledger sync failed for "${project}" (non-fatal): ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return totalSynced;
+}

package/dist/storage/sqlite.js

@@ -1049,6 +1049,24 @@ export class SqliteStorage {
         });
         debugLog(`[SqliteStorage] Hard-deleted ledger entry ${id}`);
     }
+    // ─── v9.2.4: Cross-Backend Reconciliation Helper ───────────
+    //
+    // Returns a Map of "project::role" → "updated_at" for all local handoffs.
+    // Used by reconcileHandoffs() for lightweight timestamp comparison.
+    // Single SELECT on session_handoffs — no joins, no ledger access.
+    async getHandoffTimestamps() {
+        const result = await this.db.execute(`SELECT project, role, updated_at FROM session_handoffs`);
+        const map = new Map();
+        for (const row of result.rows) {
+            const project = row.project;
+            const role = row.role || "global";
+            const updatedAt = row.updated_at;
+            if (updatedAt) {
+                map.set(`${project}::${role}`, updatedAt);
+            }
+        }
+        return map;
+    }
     // ─── Handoff Operations (OCC) ──────────────────────────────
     async saveHandoff(handoff, expectedVersion) {
         const role = handoff.role || "global"; // v3.0: default to 'global'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "9.2.3",
+  "version": "9.2.5",
   "mcpName": "io.github.dcostenco/prism-mcp",
   "description": "The Mind Palace for AI Agents — a true Cognitive Architecture with Hebbian learning (episodic→semantic consolidation), ACT-R spreading activation (multi-hop causal reasoning), uncertainty-aware rejection gates (agents that know when they don't know), adversarial evaluation (anti-sycophancy), fail-closed Dark Factory pipelines, persistent memory (SQLite/Supabase), multi-agent Hivemind, time travel & visual dashboard. Zero-config local mode.",
   "module": "index.ts",