prism-mcp-server 4.0.0 → 4.3.0

package/dist/dashboard/ui.js

@@ -696,6 +696,19 @@ export function renderDashboardHTML(version) {
           </select>
         </div>
 
+        <div class="setting-row">
+          <div>
+            <div class="setting-label">Token Budget</div>
+            <div class="setting-desc">Max tokens for session_load_context (0 = unlimited)</div>
+          </div>
+          <input type="number" id="input-max-tokens"
+            placeholder="0"
+            min="0" max="100000" step="500"
+            style="padding: 0.2rem 0.5rem; background: var(--bg-hover); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; font-size: 0.85rem; font-family: var(--font-mono); width: 90px; text-align: right;"
+            onchange="saveSetting('max_tokens', this.value)"
+            oninput="clearTimeout(this._t); this._t=setTimeout(()=>saveSetting('max_tokens',this.value),800)" />
+        </div>
+
         <div class="setting-section">Boot Settings <span class="boot-badge">Restart Required</span></div>
 
         <div class="setting-row">
@@ -716,6 +729,26 @@ export function renderDashboardHTML(version) {
           </select>
         </div>
 
+        <div class="setting-row" style="align-items:flex-start">
+          <div>
+            <div class="setting-label">Auto-Load Projects</div>
+            <div class="setting-desc">Select projects to auto-push context on startup</div>
+          </div>
+          <div id="autoload-checkboxes" style="display:flex;flex-direction:column;gap:4px;font-size:0.85rem;font-family:var(--font-mono);max-height:120px;overflow-y:auto;">
+            <span style="color:var(--text-muted);font-size:0.8rem">Loading…</span>
+          </div>
+        </div>
+
+        <div class="setting-row" style="align-items:flex-start">
+          <div>
+            <div class="setting-label">Project Repo Paths</div>
+            <div class="setting-desc">Map each project to its repo directory for save validation</div>
+          </div>
+          <div id="repopath-inputs" style="display:flex;flex-direction:column;gap:6px;font-size:0.85rem;max-height:160px;overflow-y:auto;">
+            <span style="color:var(--text-muted);font-size:0.8rem">Loading…</span>
+          </div>
+        </div>
+
         <div class="setting-section">Agent Identity</div>
 
         <div class="setting-row">
@@ -1278,6 +1311,88 @@ Example:\n## Dev Rules\n- Always write tests first\n- Use TypeScript strict mode
     }
 
 
+    // ─── Auto-Load Checkboxes (v4.1) ─────────────────────────────────
+    async function loadAutoloadCheckboxes() {
+      var container = document.getElementById('autoload-checkboxes');
+      if (!container) return;
+      try {
+        var projRes = await fetch('/api/projects');
+        var projData = await projRes.json();
+        var projects = projData.projects || [];
+
+        var settRes = await fetch('/api/settings');
+        var settData = await settRes.json();
+        var saved = (settData.settings || {}).autoload_projects || '';
+        var selected = saved.split(',').map(function(s){ return s.trim(); }).filter(Boolean);
+
+        if (projects.length === 0) {
+          container.innerHTML = '<span style="color:var(--text-muted);font-size:0.8rem">No projects found</span>';
+          return;
+        }
+
+        container.innerHTML = projects.map(function(p) {
+          var checked = selected.indexOf(p) !== -1 ? ' checked' : '';
+          return '<label style="display:flex;align-items:center;gap:6px;cursor:pointer;color:var(--text-primary)">' +
+            '<input type="checkbox" value="' + escapeHtml(p) + '"' + checked +
+            ' onchange="onAutoloadToggle()"' +
+            ' style="accent-color:var(--accent-purple);cursor:pointer" />' +
+            escapeHtml(p) + '</label>';
+        }).join('');
+      } catch(e) {
+        container.innerHTML = '<span style="color:var(--accent-rose);font-size:0.8rem">Failed to load</span>';
+      }
+    }
+
+    function onAutoloadToggle() {
+      var container = document.getElementById('autoload-checkboxes');
+      if (!container) return;
+      var boxes = container.querySelectorAll('input[type=checkbox]');
+      var selected = [];
+      for (var i = 0; i < boxes.length; i++) {
+        if (boxes[i].checked) selected.push(boxes[i].value);
+      }
+      saveBootSetting('autoload_projects', selected.join(','));
+    }
+
+    // ─── Project Repo Paths (v4.2) ─────────────────────────────────
+    async function loadRepoPathInputs() {
+      var container = document.getElementById('repopath-inputs');
+      if (!container) return;
+      try {
+        var projRes = await fetch('/api/projects');
+        var projData = await projRes.json();
+        var projects = projData.projects || [];
+
+        var settRes = await fetch('/api/settings');
+        var settData = await settRes.json();
+        var settings = settData.settings || {};
+
+        if (projects.length === 0) {
+          container.innerHTML = '<span style="color:var(--text-muted);font-size:0.8rem">No projects found</span>';
+          return;
+        }
+
+        container.innerHTML = projects.map(function(p) {
+          var savedPath = settings['repo_path:' + p] || '';
+          return '<div style="display:flex;align-items:center;gap:6px">' +
+            '<span style="min-width:100px;color:var(--text-secondary);font-family:var(--font-mono);font-size:0.8rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escapeHtml(p) + '">' + escapeHtml(p) + '</span>' +
+            '<input type="text" value="' + escapeHtml(savedPath) + '"' +
+            ' placeholder="/path/to/repo"' +
+            ' data-project="' + escapeHtml(p) + '"' +
+            ' style="flex:1;min-width:140px;padding:0.2rem 0.4rem;background:var(--bg-primary);color:var(--text-primary);border:1px solid var(--border-glass);border-radius:4px;font-size:0.8rem;font-family:var(--font-mono)"' +
+            ' onchange="saveRepoPath(this.dataset.project, this.value)"' +
+            ' oninput="clearTimeout(this._t); var self=this; this._t=setTimeout(function(){saveRepoPath(self.dataset.project, self.value)},1200)" />' +
+            '</div>';
+        }).join('');
+      } catch(e) {
+        container.innerHTML = '<span style="color:var(--accent-rose);font-size:0.8rem">Failed to load</span>';
+      }
+    }
+
+    async function saveRepoPath(project, path) {
+      await saveSetting('repo_path:' + project, path.trim());
+    }
+
       async function loadSettings() {
       try {
         var res = await fetch('/api/settings');
@@ -1304,6 +1419,11 @@ Example:\n## Dev Rules\n- Always write tests first\n- Use TypeScript strict mode
         // Agent Identity
         if (s.default_role) document.getElementById('select-default-role').value = s.default_role;
         if (s.agent_name) document.getElementById('input-agent-name').value = s.agent_name;
+        if (s.max_tokens) document.getElementById('input-max-tokens').value = s.max_tokens;
+        // Autoload checkboxes are loaded dynamically
+        loadAutoloadCheckboxes();
+        // Repo path inputs are loaded dynamically
+        loadRepoPathInputs();
       } catch(e) { console.warn('Settings load failed:', e); }
     }
 

package/dist/lifecycle.js

@@ -0,0 +1,164 @@
+/**
+ * Server Lifecycle Management
+ * Handles singleton PID locking, graceful shutdown, and SQLite handle cleanup.
+ *
+ * CRITICAL: All logging MUST use console.error() (stderr).
+ * Using console.log() (stdout) will corrupt the MCP JSON-RPC stream.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { execSync } from "child_process";
+import { closeConfigStorage } from "./storage/configStorage.js";
+import { getStorage } from "./storage/index.js";
+const PRISM_DIR = path.join(os.homedir(), ".prism-mcp");
+/**
+ * Instance-aware PID file.
+ * Set PRISM_INSTANCE env var to run multiple Prism MCP servers
+ * side-by-side (e.g. "athena-public" and "prism-mcp").
+ * Each instance gets its own PID file to prevent lock conflicts.
+ */
+const INSTANCE_NAME = process.env.PRISM_INSTANCE || "default";
+const PID_FILE = path.join(PRISM_DIR, `server-${INSTANCE_NAME}.pid`);
+function log(msg) {
+    console.error(`[Prism Lifecycle] ${msg}`);
+}
+/**
+ * Checks if a process is an orphan (adopted by init/launchd, PPID=1).
+ * Returns false on Windows (PID logic is different there).
+ */
+function isOrphanProcess(pid) {
+    if (process.platform === "win32") {
+        // Windows doesn't have reliable PPID checks via 'ps'. 
+        // Safer to assume it's NOT an orphan to avoid killing valid instances.
+        return false;
+    }
+    try {
+        // 'ps -o ppid= -p PID' returns just the parent PID
+        const ppid = execSync(`ps -o ppid= -p ${pid}`, { encoding: "utf8" }).trim();
+        return ppid === "1";
+    }
+    catch {
+        // If ps fails (e.g. process gone), assume it's safe to claim
+        return true;
+    }
+}
+/**
+ * Ensures valid server execution state.
+ *
+ * LOGIC:
+ * 1. If --no-lock is passed, skip everything (testing mode).
+ * 2. If PID file exists:
+ *    - If process is dead: Overwrite lock.
+ *    - If process is alive AND is an orphan (PPID=1): Kill it (Zombie), then overwrite.
+ *    - If process is alive AND has a parent: Log warning, allow coexistence (don't kill).
+ */
+export function acquireLock() {
+    if (process.argv.includes("--no-lock")) {
+        log("Lock acquisition skipped (--no-lock flag)");
+        return;
+    }
+    if (!fs.existsSync(PRISM_DIR)) {
+        fs.mkdirSync(PRISM_DIR, { recursive: true });
+    }
+    if (fs.existsSync(PID_FILE)) {
+        try {
+            const oldPid = parseInt(fs.readFileSync(PID_FILE, "utf8").trim(), 10);
+            if (oldPid && oldPid !== process.pid) {
+                let isAlive = false;
+                try {
+                    process.kill(oldPid, 0); // 0 signal checks for existence
+                    isAlive = true;
+                }
+                catch {
+                    isAlive = false;
+                }
+                if (isAlive) {
+                    // Process exists. Is it a zombie?
+                    if (isOrphanProcess(oldPid)) {
+                        log(`Found zombie process (PID ${oldPid}, PPID=1). Terminating...`);
+                        try {
+                            process.kill(oldPid, "SIGTERM");
+                            // Give it 100ms to die, then force kill if needed
+                            setTimeout(() => {
+                                try {
+                                    process.kill(oldPid, "SIGKILL");
+                                }
+                                catch { }
+                            }, 100);
+                        }
+                        catch (e) {
+                            log(`Failed to kill zombie: ${e}`);
+                        }
+                    }
+                    else {
+                        // It has a parent (e.g., another VS Code window or Claude Desktop)
+                        log(`Existing server (PID ${oldPid}) is active and managed. Coexisting...`);
+                        // We do NOT overwrite the PID file here. 
+                        // If we overwrite it, the *active* server will fail to clean up 
+                        // the PID file when it eventually shuts down.
+                        return;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            log(`Warning: Failed to process existing PID file: ${err}`);
+        }
+    }
+    // Claim the lock for this process
+    try {
+        fs.writeFileSync(PID_FILE, process.pid.toString(), "utf8");
+        log(`Acquired singleton lock (PID ${process.pid})`);
+    }
+    catch (err) {
+        log(`Warning: Failed to write PID file: ${err}`);
+    }
+}
+/**
+ * Registers handlers to close SQLite file handles cleanly when the server stops.
+ */
+export function registerShutdownHandlers() {
+    let shuttingDown = false;
+    const shutdown = async (reason) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log(`Shutting down gracefully (${reason})...`);
+        try {
+            // 1. Close system settings DB
+            closeConfigStorage();
+            // 2. Close main ledger DB
+            const storage = await getStorage();
+            if (storage && typeof storage.close === "function") {
+                await storage.close();
+            }
+            // 3. Remove PID lockfile (only if WE own it)
+            if (fs.existsSync(PID_FILE)) {
+                try {
+                    const storedPid = parseInt(fs.readFileSync(PID_FILE, "utf8").trim(), 10);
+                    if (storedPid === process.pid) {
+                        fs.unlinkSync(PID_FILE);
+                    }
+                }
+                catch {
+                    // Ignore read errors during shutdown
+                }
+            }
+        }
+        catch (err) {
+            log(`Error during shutdown cleanup: ${err}`);
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    // OS Signals
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGHUP", () => shutdown("SIGHUP"));
+    // MCP Client Disconnect (CRITICAL)
+    process.stdin.on("close", () => {
+        shutdown("CLIENT_DISCONNECTED_STDIN_CLOSED");
+    });
+}

package/dist/server.js

@@ -61,6 +61,7 @@ SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/
 import { SERVER_CONFIG, SESSION_MEMORY_ENABLED, PRISM_USER_ID, PRISM_ENABLE_HIVEMIND } from "./config.js";
 import { getSyncBus } from "./sync/factory.js";
 import { startDashboardServer } from "./dashboard/server.js";
+import { acquireLock, registerShutdownHandlers } from "./lifecycle.js";
 // ─── v2.3.6 FIX: Use Storage Abstraction for Prompts/Resources ───
 // CRITICAL FIX: Previously imported supabaseRpc/supabaseGet directly,
 // which bypassed the storage abstraction layer and caused the server
@@ -101,6 +102,8 @@ sessionForgetMemoryHandler,
 knowledgeSetRetentionHandler, 
 // v4.0: Active Behavioral Memory handlers
 sessionSaveExperienceHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, 
+// v4.2: Knowledge Sync Rules
+KNOWLEDGE_SYNC_RULES_TOOL, knowledgeSyncRulesHandler, 
 // ─── v3.0: Agent Hivemind tools ───
 AGENT_REGISTRY_TOOLS, agentRegisterHandler, agentHeartbeatHandler, agentListTeamHandler, } from "./tools/index.js";
 // ─── Dynamic Tool Registration ───────────────────────────────────
@@ -114,43 +117,54 @@ const BASE_TOOLS = [
     BRAVE_ANSWERS_TOOL, // brave_answers — AI-grounded answers
     RESEARCH_PAPER_ANALYSIS_TOOL, // gemini_research_paper_analysis — paper analysis
 ];
-// Session memory tools: only added when SUPABASE_URL + SUPABASE_KEY are set
-// REVIEWER NOTE: v0.4.0 adds 2 new tools here:
-//   - session_compact_ledger (Enhancement #2): auto-rollup of old ledger entries
-//   - session_search_memory (Enhancement #4): semantic search via pgvector embeddings
-const SESSION_MEMORY_TOOLS = [
-    SESSION_SAVE_LEDGER_TOOL, // session_save_ledger — append immutable session log
-    SESSION_SAVE_HANDOFF_TOOL, // session_save_handoff — upsert latest project state (now with OCC)
-    SESSION_LOAD_CONTEXT_TOOL, // session_load_context — progressive context loading
-    KNOWLEDGE_SEARCH_TOOL, // knowledge_search — search accumulated knowledge
-    KNOWLEDGE_FORGET_TOOL, // knowledge_forget — prune bad/old memories
-    SESSION_COMPACT_LEDGER_TOOL, // session_compact_ledger — auto-compact old ledger entries (v0.4.0)
-    SESSION_SEARCH_MEMORY_TOOL, // session_search_memory — semantic search via embeddings (v0.4.0)
-    MEMORY_HISTORY_TOOL, // memory_history — view version timeline (v2.0)
-    MEMORY_CHECKOUT_TOOL, // memory_checkout — revert to past version (v2.0)
-    // ─── v2.0: Visual Memory tools ───
-    SESSION_SAVE_IMAGE_TOOL, // session_save_image — save image to media vault (v2.0)
-    SESSION_VIEW_IMAGE_TOOL, // session_view_image — retrieve image from vault (v2.0)
-    // ─── v2.2.0: Health Check tool ───
-    SESSION_HEALTH_CHECK_TOOL, // session_health_check — brain integrity checker (v2.2.0)
-    // ─── Phase 2: GDPR Memory Deletion tool ───
-    SESSION_FORGET_MEMORY_TOOL, // session_forget_memory — GDPR-compliant memory deletion (Phase 2)
-    // ─── v3.1: TTL Retention tool ───
-    KNOWLEDGE_SET_RETENTION_TOOL, // knowledge_set_retention — set auto-expiry TTL for a project
-    // ─── v4.0: Active Behavioral Memory tools ───
-    SESSION_SAVE_EXPERIENCE_TOOL, // session_save_experience — record typed experience events
-    KNOWLEDGE_UPVOTE_TOOL, // knowledge_upvote — increase entry importance
-    KNOWLEDGE_DOWNVOTE_TOOL, // knowledge_downvote — decrease entry importance
-];
-// Combine: always list ALL tools so scanners (Glama, Smithery, MCP Registry)
-// can enumerate the full capability set. Runtime guards in the CallTool handler
-// still prevent execution without valid Supabase credentials.
-const ALL_TOOLS = [
-    ...BASE_TOOLS,
-    ...SESSION_MEMORY_TOOLS,
-    // v3.0: Agent Hivemind tools — only when PRISM_ENABLE_HIVEMIND=true
-    ...(PRISM_ENABLE_HIVEMIND ? AGENT_REGISTRY_TOOLS : []),
-];
+// ─── v4.1 FIX: Build Session Memory Tools dynamically ────────
+// The session_load_context tool description is dynamically modified
+// to include auto-load project instructions. Tool descriptions are
+// the ONLY mechanism guaranteed by ALL MCP clients (Antigravity,
+// Claude Code, Claude CLI). The `instructions` field and
+// sendLoggingMessage are NOT reliably surfaced by any client.
+//
+// buildSessionMemoryTools() is called inside createServer() AFTER
+// initConfigStorage() has run, so getSettingSync() returns real
+// dashboard config values.
+function buildSessionMemoryTools(autoloadList) {
+    // Dynamically inject auto-load instruction into session_load_context description
+    let loadContextTool = SESSION_LOAD_CONTEXT_TOOL;
+    if (autoloadList.length > 0) {
+        const projectList = autoloadList.join(", ");
+        loadContextTool = {
+            ...SESSION_LOAD_CONTEXT_TOOL,
+            description: SESSION_LOAD_CONTEXT_TOOL.description +
+                `\n\nIMPORTANT: At the start of every conversation, you MUST call this tool for each of these projects: ${projectList}. Do this before any other work. Load level should be "standard" unless the user specifies otherwise.`,
+        };
+    }
+    return [
+        SESSION_SAVE_LEDGER_TOOL, // session_save_ledger — append immutable session log
+        SESSION_SAVE_HANDOFF_TOOL, // session_save_handoff — upsert latest project state (now with OCC)
+        loadContextTool, // session_load_context — progressive context loading (+ auto-load instruction)
+        KNOWLEDGE_SEARCH_TOOL, // knowledge_search — search accumulated knowledge
+        KNOWLEDGE_FORGET_TOOL, // knowledge_forget — prune bad/old memories
+        SESSION_COMPACT_LEDGER_TOOL, // session_compact_ledger — auto-compact old ledger entries (v0.4.0)
+        SESSION_SEARCH_MEMORY_TOOL, // session_search_memory — semantic search via embeddings (v0.4.0)
+        MEMORY_HISTORY_TOOL, // memory_history — view version timeline (v2.0)
+        MEMORY_CHECKOUT_TOOL, // memory_checkout — revert to past version (v2.0)
+        // ─── v2.0: Visual Memory tools ───
+        SESSION_SAVE_IMAGE_TOOL, // session_save_image — save image to media vault (v2.0)
+        SESSION_VIEW_IMAGE_TOOL, // session_view_image — retrieve image from vault (v2.0)
+        // ─── v2.2.0: Health Check tool ───
+        SESSION_HEALTH_CHECK_TOOL, // session_health_check — brain integrity checker (v2.2.0)
+        // ─── Phase 2: GDPR Memory Deletion tool ───
+        SESSION_FORGET_MEMORY_TOOL, // session_forget_memory — GDPR-compliant memory deletion (Phase 2)
+        // ─── v3.1: TTL Retention tool ───
+        KNOWLEDGE_SET_RETENTION_TOOL, // knowledge_set_retention — set auto-expiry TTL for a project
+        // ─── v4.0: Active Behavioral Memory tools ───
+        SESSION_SAVE_EXPERIENCE_TOOL, // session_save_experience — record typed experience events
+        KNOWLEDGE_UPVOTE_TOOL, // knowledge_upvote — increase entry importance
+        KNOWLEDGE_DOWNVOTE_TOOL, // knowledge_downvote — decrease entry importance
+        // ─── v4.2: Knowledge Sync Rules tool ───
+        KNOWLEDGE_SYNC_RULES_TOOL, // knowledge_sync_rules — sync graduated insights to IDE rules files
+    ];
+}
 // ─── v0.4.0: Resource Subscription Tracking ──────────────────────
 // REVIEWER NOTE: We track which project URIs clients have subscribed
 // to. When sessionSaveHandoffHandler successfully updates a project,
@@ -194,6 +208,35 @@ export function notifyResourceUpdate(project, server) {
  *                with subscribe support for live refresh
  */
 export function createServer() {
+    // ─── v4.1 FIX: Auto-Load via Dynamic Tool Descriptions ────────
+    // Read auto-load projects EXCLUSIVELY from dashboard config
+    // (available after initConfigStorage() in startServer).
+    //
+    // ARCHITECTURE DECISION: We inject the auto-load instruction into
+    // the session_load_context TOOL DESCRIPTION, not into `instructions`
+    // or `sendLoggingMessage`. Tool descriptions are the ONLY mechanism
+    // guaranteed by ALL MCP clients (Antigravity, Claude Code, Claude CLI).
+    //
+    // The PRISM_AUTOLOAD_PROJECTS env var has been removed — the dashboard
+    // is the single source of truth. This prevents mismatches between
+    // env var and dashboard settings causing duplicate project loads.
+    const dashboardAutoload = getSettingSync("autoload_projects", "");
+    const autoloadList = dashboardAutoload
+        .split(",").map(p => p.trim()).filter(Boolean);
+    if (autoloadList.length > 0) {
+        console.error(`[Prism] Auto-load projects (dashboard): ${autoloadList.join(', ')}`);
+    }
+    // Build the dynamic tool list with auto-load instruction injected
+    const SESSION_MEMORY_TOOLS = buildSessionMemoryTools(autoloadList);
+    // Combine: always list ALL tools so scanners (Glama, Smithery, MCP Registry)
+    // can enumerate the full capability set. Runtime guards in the CallTool handler
+    // still prevent execution without valid Supabase credentials.
+    const ALL_TOOLS = [
+        ...BASE_TOOLS,
+        ...SESSION_MEMORY_TOOLS,
+        // v3.0: Agent Hivemind tools — only when PRISM_ENABLE_HIVEMIND=true
+        ...(PRISM_ENABLE_HIVEMIND ? AGENT_REGISTRY_TOOLS : []),
+    ];
     const server = new Server({
         name: SERVER_CONFIG.name,
         version: SERVER_CONFIG.version,
@@ -201,21 +244,13 @@ export function createServer() {
         capabilities: {
             tools: {},
             // ─── v0.4.0: Prompt capability (Enhancement #1) ───
-            // REVIEWER NOTE: Declaring `prompts: {}` tells Claude Desktop
-            // that we support the prompts/list and prompts/get methods.
-            // This enables the /resume_session slash command in the UI.
-            // Only enabled when Supabase is configured (prompts need
-            // session data to be useful).
             ...(SESSION_MEMORY_ENABLED ? { prompts: {} } : {}),
             // ─── v0.4.0: Resource capability (Enhancement #3) ───
-            // REVIEWER NOTE: Setting subscribe: true tells Claude Desktop
-            // that we support resource subscriptions. When a user attaches
-            // memory://project/handoff and the LLM later updates it,
-            // we push an update notification so the attached context
-            // is silently refreshed. Without subscribe:true, the
-            // paperclipped context would become stale.
             ...(SESSION_MEMORY_ENABLED ? { resources: { subscribe: true } } : {}),
         },
+        // Supplementary signal — not all clients support this field.
+        // Primary mechanism is the dynamic tool description above.
+        instructions: `Prism MCP — The Mind Palace for AI Agents. This server provides persistent session memory, knowledge search, and context management tools. Use session_load_context to recover previous work state, session_save_ledger to log completed work, and session_save_handoff to preserve state for the next session.`,
     });
     // ── Handler: Initialize ──
     // NOTE: The SDK's built-in _oninitialize() handles the Initialize request.
@@ -607,6 +642,11 @@ export function createServer() {
                     if (!SESSION_MEMORY_ENABLED)
                         throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
                     return await knowledgeDownvoteHandler(args);
+                // ─── v4.2: Knowledge Sync Rules Tool ───
+                case "knowledge_sync_rules":
+                    if (!SESSION_MEMORY_ENABLED)
+                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                    return await knowledgeSyncRulesHandler(args);
                 // ─── v3.0: Agent Hivemind Tools ───
                 case "agent_register":
                     if (!SESSION_MEMORY_ENABLED)
@@ -666,7 +706,7 @@ export function createSandboxServer() {
     });
     // Register all tool listings unconditionally
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: [...BASE_TOOLS, ...SESSION_MEMORY_TOOLS, ...AGENT_REGISTRY_TOOLS],
+        tools: [...BASE_TOOLS, ...buildSessionMemoryTools([]), ...AGENT_REGISTRY_TOOLS],
     }));
     // Register prompts listing so scanners see resume_session
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({
@@ -715,6 +755,9 @@ export function createSandboxServer() {
  * responses to stdout. Log messages go to stderr.
  */
 export async function startServer() {
+    // MUST BE FIRST: Kill any zombie processes and acquire the singleton PID lock
+    // before touching SQLite. This prevents lock contention on prism-config.db.
+    acquireLock();
     // Pre-warm the config settings cache BEFORE connecting the MCP transport.
     // This ensures getSettingSync() returns real values (agent_name, default_role)
     // during the Initialize handshake — zero extra latency for resource reads.
@@ -723,6 +766,10 @@ export async function startServer() {
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Register graceful shutdown handlers (SIGTERM, SIGINT, SIGHUP, stdin close).
+    // The stdin close handler is critical — when MCP clients disconnect, they
+    // often just close the pipe without sending a signal, leaving zombie processes.
+    registerShutdownHandlers();
     // Pre-warm storage AFTER connecting — fired async so we never block the
     // stdio handshake. Supabase REST initialization can take 500ms–5s; blocking
     // on it before server.connect() was the root cause of the 1m 56s CLI delay.
@@ -740,6 +787,18 @@ export async function startServer() {
         ]).catch(err => {
             console.error(`[Prism] Storage pre-warm failed (non-fatal): ${err}`);
         });
+        // ─── v4.1: Auto-Load is handled via dynamic tool descriptions ──
+        // The session_load_context tool description is dynamically modified
+        // in createServer() → buildSessionMemoryTools() to include the
+        // auto-load projects list. This is the ONLY universally reliable
+        // mechanism — tool descriptions are surfaced by ALL MCP clients.
+        //
+        // Previous approaches that FAILED:
+        //   - sendLoggingMessage: goes to debug logs, not AI conversation
+        //   - instructions field: not supported by Claude Code or Claude CLI
+        //
+        // No runtime code needed here — the instruction is baked into the
+        // tool schema returned by ListTools.
     }
     // ─── v2.0 Step 6: Initialize SyncBus (Telepathy) ───
     // Fire-and-forget — SyncBus is non-critical for startup.

package/dist/storage/configStorage.js

@@ -102,17 +102,36 @@ export async function getSetting(key, defaultValue = "") {
 export async function setSetting(key, value) {
     await initConfigStorage();
     const client = getClient();
-    await client.execute({
-        sql: `
-      INSERT INTO system_settings (key, value, updated_at) 
-      VALUES (?, ?, CURRENT_TIMESTAMP)
-      ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP
-    `,
-        args: [key, value],
-    });
-    // Keep the cache in sync so getSettingSync() reflects the new value immediately.
-    if (settingsCache) {
-        settingsCache[key] = value;
+    // Retry with exponential backoff for SQLITE_BUSY (concurrent writes).
+    // The dashboard and load tests can fire many parallel setting saves.
+    const MAX_RETRIES = 5;
+    const BASE_DELAY_MS = 20;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            await client.execute({
+                sql: `
+          INSERT INTO system_settings (key, value, updated_at) 
+          VALUES (?, ?, CURRENT_TIMESTAMP)
+          ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP
+        `,
+                args: [key, value],
+            });
+            // Keep the cache in sync so getSettingSync() reflects the new value immediately.
+            if (settingsCache) {
+                settingsCache[key] = value;
+            }
+            return; // Success — exit
+        }
+        catch (err) {
+            const isBusy = err?.code === "SQLITE_BUSY" || err?.rawCode === 5;
+            if (isBusy && attempt < MAX_RETRIES) {
+                // Exponential backoff + jitter
+                const delay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * 10;
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            throw err; // Not SQLITE_BUSY or retries exhausted
+        }
     }
 }
 export async function getAllSettings() {
@@ -129,3 +148,17 @@ export async function getAllSettings() {
     }
     return settings;
 }
+/**
+ * Closes the config SQLite client to release the file handle on prism-config.db.
+ * Called by the lifecycle module during graceful shutdown.
+ */
+export function closeConfigStorage() {
+    if (configClient) {
+        try {
+            configClient.close();
+        }
+        catch (e) {
+            console.error(`[ConfigStorage] Error closing db:`, e);
+        }
+    }
+}

package/dist/storage/sqlite.js

@@ -1391,4 +1391,35 @@ export class SqliteStorage {
         });
         debugLog(`[SqliteStorage] Adjusted importance for ${id} by ${delta > 0 ? "+" : ""}${delta}`);
     }
+    // ─── v4.2: Graduated Insights Query ──────────────────────────
+    //
+    // Returns ledger entries that have "graduated" — i.e., their
+    // importance score has reached the threshold (default 7).
+    // Used by knowledge_sync_rules to physically write insights
+    // into .cursorrules / .clauderules files at the project repo path.
+    async getGraduatedInsights(project, userId, minImportance = 7) {
+        const result = await this.db.execute({
+            sql: `SELECT id, project, user_id, role, summary, importance,
+                   event_type, decisions, created_at
+            FROM session_ledger
+            WHERE project = ? AND user_id = ?
+              AND importance >= ?
+              AND deleted_at IS NULL
+              AND archived_at IS NULL
+            ORDER BY importance DESC, created_at DESC`,
+            args: [project, userId, minImportance],
+        });
+        return result.rows.map(row => ({
+            id: row.id,
+            project: row.project,
+            user_id: row.user_id,
+            role: row.role || "global",
+            summary: row.summary,
+            importance: Number(row.importance),
+            event_type: row.event_type || "session",
+            decisions: this.parseJsonColumn(row.decisions),
+            created_at: row.created_at,
+            conversation_id: "",
+        }));
+    }
 }