prism-mcp-server 9.2.0 → 9.2.2

package/README.md

@@ -278,6 +278,13 @@ bash ~/.gemini/antigravity/scratch/prism_session_loader.sh my-project
 
 The CLI uses the same storage layer as the MCP tool (SQLite or Supabase).
 
+> ⚠️ **CRITICAL (v9.2.2): Split-Brain Prevention**
+> If your MCP server is configured with `PRISM_STORAGE=local` but Supabase credentials are also set, the CLI may read from the **wrong backend** (Supabase) while the server writes to SQLite. This causes stale TODOs and divergent state. Always pass `--storage local` explicitly when using the CLI in a local-mode environment:
+> ```bash
+> prism load my-project --storage local --json
+> ```
+> The `prism_session_loader.sh` wrapper handles this automatically since v9.2.2.
+
 </details>
 
 <details>
@@ -295,6 +302,10 @@ SUMMARY=$(echo "$CONTEXT" | jq -r '.handoff[0].last_summary')
 VERSION=$(echo "$CONTEXT" | jq -r '.handoff[0].version')
 echo "Project at v$VERSION: $SUMMARY"
 
+# Explicit storage backend (v9.2.2 — prevents split-brain)
+prism load my-project --storage local --json
+prism load my-project --storage supabase --json
+
 # Role-scoped loading
 prism load my-project --role qa --json
 
@@ -778,8 +789,10 @@ The Generator strips the `console.log`, resubmits, and the next `EVALUATE` retur
 
 ## 🆕 What's New
 
-> **Current release: v9.1.0 — Task Router v2 & Local Agent Hardening**
+> **Current release: v9.2.2 — Critical Split-Brain Fix**
 
+- 🚨 **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.
 - 🚦 **v9.1.0 — Task Router v2:** File-type complexity signal for intelligent code-vs-config routing, 6-signal weighted heuristic engine, multi-step false-positive fix, expanded file extension classification. Local agent hardened with buffered streaming, system prompts, memory trimming, and stateful `/api/chat` API.
 - 🔒 **v9.0.5 — JWKS Auth Security Hardening:** JWT audience/issuer claim validation (`PRISM_JWT_AUDIENCE`, `PRISM_JWT_ISSUER`), structured error logging for JWT failures, typed `PrismAuthenticatedRequest` interface, 11 new JWKS unit tests, Smithery server card fix. Vendor-neutral — tested with Auth0, AgentLair ([llms.txt](https://agentlair.com/llms.txt)), Keycloak, and custom JWKS endpoints.
 - 🧠 **v9.0.0 — Autonomous Cognitive OS:** Token-Economic Reinforcement Learning (Surprisal Gate + Cognitive Budget), Affect-Tagged Memory (valence-scored retrieval), and Episodic→Semantic Consolidation. Your agents learn compression and develop intuition. → [Cognitive OS](#-autonomous-cognitive-os-v90)
@@ -844,12 +857,16 @@ Every other AI coding pipeline has a fatal flaw: it asks the same model that wro
 
 ## 💻 CLI Reference
 
-Prism includes a CLI for environments where MCP tools aren't available (CI/CD pipelines, Bash scripts, non-MCP IDEs like Antigravity):
+Prism includes a CLI for environments where MCP tools aren't available (CI/CD pipelines, Bash scripts, non-MCP IDEs like Antigravity).
+
+**Text mode** delegates to the real `session_load_context` handler — full feature parity with MCP clients, including morning briefings, reality drift detection, SDM intuitive recall, visual memory, role-scoped skills, behavioral warnings, and agent identity.
+
+**JSON mode** emits a structured envelope for programmatic consumption (scripts, CI/CD, session loaders).
 
 ```bash
-# Load session context (same output as session_load_context MCP tool)
+# Load session context (full enrichments — same as MCP tool)
 prism load my-project                          # Human-readable, standard depth
-prism load my-project --level deep             # Full context
+prism load my-project --level deep             # Full context with all enrichments
 prism load my-project --level quick --json     # Machine-readable JSON
 prism load my-project --role dev --json        # Role-scoped loading
 

package/dist/cli.js

@@ -7,6 +7,7 @@ import { getStorage, closeStorage } from './storage/index.js';
 import { getSetting } from './storage/configStorage.js';
 import { PRISM_USER_ID, SERVER_CONFIG } from './config.js';
 import { getCurrentGitState } from './utils/git.js';
+import { sessionLoadContextHandler } from './tools/ledgerHandlers.js';
 const program = new Command();
 program
     .name('prism')
@@ -17,41 +18,64 @@ program
 // session_load_context tool. Works with both SQLite and Supabase.
 // Designed for environments that cannot use MCP tools directly
 // (Antigravity, Bash scripts, CI/CD pipelines).
+//
+// CRITICAL: --storage flag (v9.2.2)
+// When multiple MCP clients use different storage backends (e.g.
+// Claude Desktop → Supabase, Antigravity → SQLite), the CLI must
+// be told which backend to read from. Without this, the CLI
+// inherits PRISM_STORAGE from the shell env (defaulting to
+// supabase), which may differ from the MCP server's config.
+// This causes a "split-brain" where the CLI returns stale state
+// from the wrong backend.
+//
+// TEXT MODE: Delegates to the real sessionLoadContextHandler for
+// full feature parity — morning briefing, reality drift detection,
+// SDM recall, visual memory, skill injection, behavioral warnings,
+// importance scores, recent validations. Any future MCP enrichments
+// automatically appear in CLI too.
+//
+// JSON MODE: Structured envelope for programmatic consumption
+// (session loader scripts, CI/CD pipelines, etc.).
 program
     .command('load <project>')
     .description('Load session context for a project (same output as session_load_context MCP tool)')
     .option('-l, --level <level>', 'Context depth: quick, standard, deep', 'standard')
     .option('-r, --role <role>', 'Role scope for context loading')
+    .option('-s, --storage <backend>', 'Storage backend: local (SQLite) or supabase. Overrides PRISM_STORAGE env var.')
     .option('--json', 'Emit machine-readable JSON instead of formatted text')
     .action(async (project, options) => {
     try {
-        const { level, role, json: jsonOutput } = options;
+        const { level, role, storage, json: jsonOutput } = options;
+        // v9.2.2: --storage flag overrides PRISM_STORAGE env var to prevent
+        // split-brain when CLI environment differs from MCP server config.
+        if (storage) {
+            const validStorages = ['local', 'supabase'];
+            if (!validStorages.includes(storage)) {
+                console.error(`Error: Invalid storage "${storage}". Must be one of: ${validStorages.join(', ')}`);
+                process.exit(1);
+            }
+            process.env.PRISM_STORAGE = storage;
+        }
         const validLevels = ['quick', 'standard', 'deep'];
         if (!validLevels.includes(level)) {
             console.error(`Error: Invalid level "${level}". Must be one of: ${validLevels.join(', ')}`);
             process.exit(1);
         }
-        // Use the shared storage singleton (respects PRISM_STORAGE, dashboard config, etc.)
-        const storage = await getStorage();
-        const effectiveRole = role || await getSetting('default_role', '') || undefined;
-        const data = await storage.loadContext(project, level, PRISM_USER_ID, effectiveRole);
-        if (!data) {
-            if (jsonOutput) {
+        if (jsonOutput) {
+            // ── JSON mode: structured output for programmatic consumption ──
+            const storageBackend = await getStorage();
+            const effectiveRole = role || await getSetting('default_role', '') || undefined;
+            const agentName = await getSetting('agent_name', '') || undefined;
+            const data = await storageBackend.loadContext(project, level, PRISM_USER_ID, effectiveRole);
+            if (!data) {
                 console.log(JSON.stringify({ error: `No session context found for project "${project}"` }));
+                await closeStorage();
+                process.exit(0);
             }
-            else {
-                console.log(`No session context found for project "${project}" at level ${level}.`);
-                console.log('This project has no previous session history. Starting fresh.');
-            }
-            await closeStorage();
-            process.exit(0);
-        }
-        const d = data;
-        // Gather git state for enrichment
-        const gitState = getCurrentGitState();
-        if (jsonOutput) {
-            // Machine-readable JSON envelope — matches what prism_session_loader.sh produced
+            const d = data;
+            const gitState = getCurrentGitState();
             const output = {
+                agent_name: agentName || null,
                 handoff: [{
                         project,
                         role: effectiveRole || d.role || 'global',
@@ -77,29 +101,23 @@ program
             console.log(JSON.stringify(output, null, 2));
         }
         else {
-            // Human-readable formatted output (same format as MCP tool)
-            let output = `📋 Session context for "${project}" (${level}):\n\n`;
-            if (d.last_summary)
-                output += `📝 Last Summary: ${d.last_summary}\n`;
-            if (d.active_branch)
-                output += `🌿 Active Branch: ${d.active_branch}\n`;
-            if (d.key_context)
-                output += `💡 Key Context: ${d.key_context}\n`;
-            if (d.pending_todo?.length) {
-                output += `\n✅ Open TODOs:\n` + d.pending_todo.map((t) => `  - ${t}`).join('\n') + '\n';
-            }
-            if (d.active_decisions?.length) {
-                output += `\n⚖️ Active Decisions:\n` + d.active_decisions.map((dec) => `  - ${dec}`).join('\n') + '\n';
-            }
-            if (d.keywords?.length) {
-                output += `\n🔑 Keywords: ${d.keywords.join(', ')}\n`;
-            }
-            if (d.recent_sessions?.length) {
-                output += `\n⏳ Recent Sessions:\n` + d.recent_sessions.map((s) => `  [${s.session_date?.split('T')[0]}] ${s.summary}`).join('\n') + '\n';
+            // ── Text mode: full parity with MCP session_load_context ──
+            // Delegates to the real handler so all enrichments (morning briefing,
+            // reality drift, SDM recall, visual memory, skill injection,
+            // behavioral warnings, etc.) are included automatically.
+            const result = await sessionLoadContextHandler({ project, level, role });
+            // Surface handler-level errors (e.g. invalid args, storage failures)
+            if (result.isError) {
+                console.error(result.content[0]?.text || 'Unknown error loading context');
+                await closeStorage();
+                process.exit(1);
             }
-            if (d.version != null) {
-                output += `\n🔑 Session version: ${d.version}. Pass expected_version: ${d.version} when saving handoff.`;
+            let output = '';
+            if (result.content?.[0]) {
+                output = result.content[0].text;
             }
+            // Append git state (not included in the MCP handler output)
+            const gitState = getCurrentGitState();
             if (gitState.isRepo) {
                 output += `\n\n🔧 Git: ${gitState.branch} @ ${gitState.commitSha?.substring(0, 7)} (Prism v${SERVER_CONFIG.version})`;
             }

package/dist/tools/ledgerHandlers.js

@@ -23,7 +23,7 @@ import { buildVaultDirectory } from "../utils/vaultExporter.js";
  * ═══════════════════════════════════════════════════════════════════
  */
 import { debugLog } from "../utils/logger.js";
-import { getStorage } from "../storage/index.js";
+import { getStorage, activeStorageBackend } from "../storage/index.js";
 import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
 import { getCurrentGitState, getGitDrift } from "../utils/git.js";
@@ -524,6 +524,67 @@ export async function sessionLoadContextHandler(args) {
     const versionNote = version
         ? `\n\n🔑 Session version: ${version}. Pass expected_version: ${version} when saving handoff.`
         : "";
+    // ─── v9.2.2: Split-Brain Drift Detection ───────────────────
+    // When using one storage backend (e.g. SQLite), check if an
+    // alternate backend (e.g. Supabase) exists with a different
+    // version. This prevents agents from unknowingly acting on
+    // stale state from a diverged backend.
+    //
+    // PERF NOTE: We do NOT construct a full StorageBackend for the
+    // alternate check — that would trigger full migrations/schema
+    // validation on every load (~200-1000ms). Instead we use
+    // lightweight direct queries: REST GET for Supabase, raw SQL
+    // for SQLite. This keeps the check under ~100ms.
+    let splitBrainWarning = "";
+    try {
+        const { SUPABASE_CONFIGURED, SUPABASE_URL, SUPABASE_KEY } = await import("../config.js");
+        if (activeStorageBackend === "local" && SUPABASE_CONFIGURED && SUPABASE_URL && SUPABASE_KEY) {
+            // Lightweight Supabase version check via REST (no full init/migrations)
+            const { supabaseGet } = await import("../utils/supabaseApi.js");
+            const rows = await supabaseGet("session_handoffs", {
+                project: `eq.${project}`,
+                select: "version",
+                limit: "1",
+            });
+            const altVersion = Array.isArray(rows) && rows[0] ? rows[0].version : null;
+            if (altVersion && altVersion !== version) {
+                splitBrainWarning = `\n\n⚠️ **SPLIT-BRAIN DETECTED** (v${version} local vs v${altVersion} cloud)\n` +
+                    `Your local SQLite state (v${version}) differs from the Supabase cloud state (v${altVersion}). ` +
+                    `This means another client (e.g. Claude Desktop) has saved state that this environment cannot see. ` +
+                    `TODOs, summaries, and decisions may be stale. Please reconcile by running:\n` +
+                    `  \`prism load ${project} --storage supabase\` to see the cloud state.`;
+                debugLog(`[session_load_context] SPLIT-BRAIN: local v${version} vs supabase v${altVersion}`);
+            }
+        }
+        else if (activeStorageBackend === "supabase") {
+            // Lightweight SQLite version check via direct file query (no full init/migrations)
+            const dbPath = nodePath.join(os.homedir(), ".prism-mcp", "data.db");
+            if (fs.existsSync(dbPath)) {
+                let altClient = null;
+                try {
+                    const { createClient } = await import("@libsql/client");
+                    altClient = createClient({ url: `file:${dbPath}` });
+                    const result = await altClient.execute(`SELECT version FROM session_handoffs WHERE project = ? LIMIT 1`, [project]);
+                    const altVersion = result.rows?.[0]?.version;
+                    if (altVersion && altVersion !== version) {
+                        splitBrainWarning = `\n\n⚠️ **SPLIT-BRAIN DETECTED** (v${version} cloud vs v${altVersion} local)\n` +
+                            `Your Supabase cloud state (v${version}) differs from the local SQLite state (v${altVersion}). ` +
+                            `This means another client has saved state that this environment cannot see. ` +
+                            `TODOs, summaries, and decisions may be stale. Please reconcile by running:\n` +
+                            `  \`prism load ${project} --storage local\` to see the local state.`;
+                        debugLog(`[session_load_context] SPLIT-BRAIN: supabase v${version} vs local v${altVersion}`);
+                    }
+                }
+                finally {
+                    if (altClient)
+                        altClient.close();
+                }
+            }
+        }
+    }
+    catch (err) {
+        debugLog(`[session_load_context] Split-brain check failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    }
     // ─── Reality Drift Detection (v2.0 Step 5) ───
     // Check if the developer changed code since the last handoff save.
     let driftReport = "";
@@ -721,7 +782,7 @@ export async function sessionLoadContextHandler(args) {
         }
     }
     // Build the response object before v4.0 augmentations
-    let responseText = `📋 Session context for "${project}" (${level}):\n\n${formattedContext.trim()}${driftReport}${briefingBlock}${sdmRecallBlock}${greetingBlock}${visualMemoryBlock}${skillBlock}${versionNote}`;
+    let responseText = `📋 Session context for "${project}" (${level}):\n\n${formattedContext.trim()}${splitBrainWarning}${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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "9.2.0",
+  "version": "9.2.2",
   "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",