gnosys 5.11.4 → 5.12.2

package/dist/index.js

@@ -10,6 +10,7 @@
 // MCP stdio JSON protocol. parse() is a pure function with no side effects.
 import dotenv from "dotenv";
 import path from "path";
+import { AsyncLocalStorage } from "async_hooks";
 import { readFileSync, realpathSync } from "fs";
 import { fileURLToPath } from "url";
 const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
@@ -49,15 +50,20 @@ import { groupByPeriod, computeStats } from "./lib/timeline.js";
 import { buildLinkGraph, getBacklinks, getOutgoingLinks, formatGraphSummary } from "./lib/wikilinks.js";
 import { loadConfig, DEFAULT_CONFIG } from "./lib/config.js";
 import { getLLMProvider } from "./lib/llm.js";
-import { recall, formatRecall } from "./lib/recall.js";
+import { recall, formatRecall, } from "./lib/recall.js";
 import { initAudit, readAuditLog, formatAuditTimeline } from "./lib/audit.js";
+import { logError } from "./lib/log.js";
 import { GnosysDB } from "./lib/db.js";
 import { syncMemoryToDb, syncUpdateToDb, syncDearchiveToDb, syncReinforcementToDb, auditToDb } from "./lib/dbWrite.js";
-import { createProjectIdentity, readProjectIdentity } from "./lib/projectIdentity.js";
+import { createProjectIdentity, readProjectIdentity, } from "./lib/projectIdentity.js";
 import { setPreference, getPreference, getAllPreferences, deletePreference, KNOWN_PREFERENCE_KEYS, suggestPreferenceKey } from "./lib/preferences.js";
-import { syncRules, generateRulesBlock } from "./lib/rulesGen.js";
+import { syncRules, generateRulesBlock, } from "./lib/rulesGen.js";
 import { federatedSearch, detectAmbiguity, generateBriefing, generateAllBriefings, getWorkingSet, formatWorkingSet, detectCurrentProject } from "./lib/federated.js";
 import { generatePortfolio, formatPortfolioCompact, formatPortfolioMarkdown, generateStatusPrompt } from "./lib/portfolio.js";
+import { applyPendingOverlay, mergeOverlayDiscoverResults, mergeOverlaySearchResults, pendingAddToDbMemory, } from "./lib/clientReadOverlay.js";
+import { readMachineConfig } from "./lib/machineConfig.js";
+import { getConfiguredRemotePath } from "./lib/remote.js";
+import { closeClientReadContext, openClientReadContext, } from "./lib/syncClient.js";
 // Initialize resolver (discovers all layered stores)
 const resolver = new GnosysResolver();
 let config = DEFAULT_CONFIG;
@@ -67,9 +73,47 @@ const server = new McpServer({
     version: "2.0.0",
 });
 const _registrations = [];
+// v5.12.1 reliability: every tool handler resolves a ToolContext whose
+// clientRead (v13 sync) may own a DB handle. Historically only 8 of 52
+// handlers released it, leaking handles on every early return. Enforce
+// release centrally: resolveToolContext() registers each context in the
+// per-call AsyncLocalStorage store, and withContextRelease() (wrapped around
+// every tool handler at registration) releases them when the handler settles
+// — every return path, every throw, every future tool, no per-handler code.
+const activeToolContexts = new AsyncLocalStorage();
+function withContextRelease(handler, toolName) {
+    return (...hargs) => {
+        const opened = [];
+        return activeToolContexts.run(opened, async () => {
+            try {
+                return await handler(...hargs);
+            }
+            catch (err) {
+                // v5.12.x observability: last-resort error envelope. 19 of 52 tools
+                // had no catch at all — a throw reached the SDK as a raw JSON-RPC
+                // error with no corruption-recovery guidance. Per-tool catches with
+                // more specific messages still take precedence; this only sees what
+                // they let through. Logged to stderr (stdout is JSON-RPC).
+                logError(err, { module: "mcp", op: toolName });
+                return {
+                    content: [{ type: "text", text: formatMcpError(`in ${toolName}`, err) }],
+                    isError: true,
+                };
+            }
+            finally {
+                for (const c of opened)
+                    releaseClientReadFromContext(c);
+            }
+        });
+    };
+}
 // Typed to the McpServer methods so call-site generic inference (Zod schema →
 // handler arg types) is preserved; the body just collects a replay thunk.
 const regTool = ((...args) => {
+    const last = args.length - 1;
+    if (typeof args[last] === "function") {
+        args[last] = withContextRelease(args[last], typeof args[0] === "string" ? args[0] : "tool");
+    }
     _registrations.push((s) => s.tool(...args));
 });
 const regPrompt = ((...args) => {
@@ -136,14 +180,46 @@ let askEngine = null;
 let gnosysDb = null;
 /** v3.0: Central DB at ~/.gnosys/gnosys.db */
 let centralDb = null;
-/** v2.0: Dream scheduler (idle-time consolidation) */
-let dreamScheduler = null;
 // ─── Multi-Project Support ───────────────────────────────────────────────
 // Each tool call can optionally pass a `projectRoot` to target a specific
 // project's .gnosys store. This is STATELESS — no race conditions when
 // multiple agents call tools in parallel.
 /** Common Zod schema fragment for projectRoot parameter */
 const projectRootParam = z.string().optional().describe("Optional project root path for multi-project support. When provided, this tool operates on projectRoot/.gnosys instead of the default store. Use gnosys_stores to see all available stores.");
+function applyClientReadToCentralDb(localDb) {
+    if (!localDb?.isAvailable()) {
+        return { centralDb: localDb, clientRead: null };
+    }
+    const mc = readMachineConfig();
+    if (!mc?.remote.enabled || mc.remote.role !== "client") {
+        return { centralDb: localDb, clientRead: null };
+    }
+    const masterPath = getConfiguredRemotePath(localDb);
+    if (!masterPath)
+        return { centralDb: localDb, clientRead: null };
+    const clientRead = openClientReadContext(localDb, masterPath, mc.machineId);
+    return { centralDb: clientRead.db, clientRead };
+}
+/** Idempotent: safe to call from both a handler's own finally and the central
+ *  withContextRelease wrapper. */
+function releaseClientReadFromContext(ctx) {
+    if (ctx.clientRead) {
+        closeClientReadContext(ctx.clientRead);
+        ctx.clientRead = null;
+    }
+    // v5.12.x perf/leak: projectRoot-scoped contexts open their own
+    // GnosysSearch (SQLite handle to <store>/.config/search.db) per call.
+    if (ctx.ownsSearch && ctx.search) {
+        try {
+            ctx.search.close();
+        }
+        catch {
+            // already closed / never opened — fine
+        }
+        ctx.search = null;
+        ctx.ownsSearch = false;
+    }
+}
 async function resolveToolContext(projectRoot) {
     if (!projectRoot) {
         // Default context — use module-level state
@@ -155,16 +231,20 @@ async function resolveToolContext(projectRoot) {
             const identity = await readProjectIdentity(parentDir);
             projectId = identity?.projectId || null;
         }
-        return {
+        const applied = applyClientReadToCentralDb(centralDb);
+        const ctx = {
             resolver,
             store: writeTarget?.store || null,
             storePath: writeTarget?.store.getStorePath() || "",
             config,
             search,
             gnosysDb,
-            centralDb,
+            centralDb: applied.centralDb,
             projectId,
+            clientRead: applied.clientRead,
         };
+        activeToolContexts.getStore()?.push(ctx);
+        return ctx;
     }
     // Scoped context — resolve for this specific project
     const scopedResolver = await GnosysResolver.resolveForProject(projectRoot);
@@ -192,16 +272,21 @@ async function resolveToolContext(projectRoot) {
         // Removed: new GnosysDB(scopedStorePath) which created an empty
         // gnosys.db in the project's .gnosys/ directory.
     }
-    return {
+    const applied = applyClientReadToCentralDb(centralDb);
+    const ctx = {
         resolver: scopedResolver,
         store: scopedWriteTarget?.store || null,
         storePath: scopedStorePath,
         config: scopedConfig,
         search: scopedSearch,
         gnosysDb: scopedDb,
-        centralDb,
+        centralDb: applied.centralDb,
         projectId,
+        clientRead: applied.clientRead,
+        ownsSearch: scopedSearch !== null,
     };
+    activeToolContexts.getStore()?.push(ctx);
+    return ctx;
 }
 /**
  * v5.7.1 (#13): Resolve scope + projectId for a memory write.
@@ -244,50 +329,65 @@ regTool("gnosys_discover", "Discover relevant memories by describing what you're
     projectRoot: projectRootParam,
 }, async ({ query, limit, projectRoot }) => {
     const ctx = await resolveToolContext(projectRoot);
-    // v2.0 DB-backed fast path
-    if (ctx.centralDb?.isAvailable() && ctx.centralDb?.isMigrated()) {
-        const results = ctx.centralDb.discoverFts(query, limit || 20);
+    try {
+        // v2.0 DB-backed fast path
+        if (ctx.centralDb?.isAvailable() && ctx.centralDb?.isMigrated()) {
+            const lim = limit || 20;
+            let results = ctx.centralDb.discoverFts(query, lim);
+            if (ctx.clientRead?.pendingOverlay.length) {
+                results = mergeOverlayDiscoverResults(results, ctx.clientRead.pendingOverlay, query, lim, (p) => ({
+                    id: p.id,
+                    title: p.title,
+                    relevance: "",
+                    rank: 0,
+                    project_id: p.project_id,
+                }));
+            }
+            if (results.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No memories found for "${query}". Try different keywords.` }],
+                };
+            }
+            const formatted = results
+                .map((r) => `**${r.title}**\n  ID: ${r.id}${r.relevance ? `\n  Relevance: ${r.relevance}` : ""}`)
+                .join("\n\n");
+            return {
+                content: [{ type: "text", text: `Found ${results.length} relevant memories for "${query}":\n\n${formatted}\n\nUse gnosys_read to load any of these.` }],
+            };
+        }
+        // v1.x legacy path
+        if (!ctx.search) {
+            return {
+                content: [{ type: "text", text: "Search index not initialized." }],
+                isError: true,
+            };
+        }
+        const results = ctx.search.discover(query, limit || 20);
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No memories found for "${query}". Try different keywords.` }],
+                content: [
+                    {
+                        type: "text",
+                        text: `No memories found for "${query}". Try different keywords or use gnosys_search for full-text search.`,
+                    },
+                ],
             };
         }
         const formatted = results
-            .map((r) => `**${r.title}**\n  ID: ${r.id}${r.relevance ? `\n  Relevance: ${r.relevance}` : ""}`)
+            .map((r) => `**${r.title}**\n  Path: ${r.relative_path}${r.relevance ? `\n  Relevance: ${r.relevance}` : ""}`)
             .join("\n\n");
-        return {
-            content: [{ type: "text", text: `Found ${results.length} relevant memories for "${query}":\n\n${formatted}\n\nUse gnosys_read to load any of these.` }],
-        };
-    }
-    // v1.x legacy path
-    if (!ctx.search) {
-        return {
-            content: [{ type: "text", text: "Search index not initialized." }],
-            isError: true,
-        };
-    }
-    const results = ctx.search.discover(query, limit || 20);
-    if (results.length === 0) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `No memories found for "${query}". Try different keywords or use gnosys_search for full-text search.`,
+                    text: `Found ${results.length} relevant memories for "${query}":\n\n${formatted}\n\nUse gnosys_read to load any of these.`,
                 },
             ],
         };
     }
-    const formatted = results
-        .map((r) => `**${r.title}**\n  Path: ${r.relative_path}${r.relevance ? `\n  Relevance: ${r.relevance}` : ""}`)
-        .join("\n\n");
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Found ${results.length} relevant memories for "${query}":\n\n${formatted}\n\nUse gnosys_read to load any of these.`,
-            },
-        ],
-    };
+    finally {
+        releaseClientReadFromContext(ctx);
+    }
 });
 // ─── Tool: gnosys_read ───────────────────────────────────────────────────
 regTool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., 'arch-012') or layer-prefixed path (e.g., 'project:decisions/why-not-rag.md'). Without a prefix, searches all stores in precedence order.", {
@@ -295,62 +395,72 @@ regTool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., 'arch
     projectRoot: projectRootParam,
 }, async ({ path: memPath, projectRoot }) => {
     const ctx = await resolveToolContext(projectRoot);
-    // v2.0 DB-backed fast path: try reading by memory ID from gnosys.db first
-    if (ctx.centralDb?.isAvailable() && ctx.centralDb?.isMigrated()) {
-        const dbMem = ctx.centralDb.getMemory(memPath);
-        if (dbMem) {
-            const tags = dbMem.tags || "[]";
-            const headerLines = [
-                `---`,
-                `id: ${dbMem.id}`,
-                `title: '${dbMem.title}'`,
-                `category: ${dbMem.category}`,
-                `tags: ${tags}`,
-                `relevance: ${dbMem.relevance}`,
-                `author: ${dbMem.author}`,
-                `authority: ${dbMem.authority}`,
-                `confidence: ${dbMem.confidence}`,
-                `status: ${dbMem.status}`,
-                `tier: ${dbMem.tier}`,
-                `created: '${dbMem.created}'`,
-                `modified: '${dbMem.modified}'`,
-            ];
-            if (dbMem.source_file) {
-                headerLines.push(`source_file: ${dbMem.source_file}${dbMem.source_page != null ? ` (page ${Number(dbMem.source_page)})` : ""}`);
+    try {
+        // v2.0 DB-backed fast path: try reading by memory ID from gnosys.db first
+        if (ctx.centralDb?.isAvailable() && ctx.centralDb?.isMigrated()) {
+            let dbMem = ctx.centralDb.getMemory(memPath);
+            if (!dbMem && ctx.clientRead?.pendingOverlay.length) {
+                const pending = ctx.clientRead.pendingOverlay.find((p) => p.id === memPath);
+                if (pending)
+                    dbMem = pendingAddToDbMemory(pending);
             }
-            if (dbMem.source_path)
-                headerLines.push(`source_path: ${dbMem.source_path}`);
-            headerLines.push(`---`);
-            const header = headerLines.join("\n");
+            if (dbMem) {
+                const tags = dbMem.tags || "[]";
+                const headerLines = [
+                    `---`,
+                    `id: ${dbMem.id}`,
+                    `title: '${dbMem.title}'`,
+                    `category: ${dbMem.category}`,
+                    `tags: ${tags}`,
+                    `relevance: ${dbMem.relevance}`,
+                    `author: ${dbMem.author}`,
+                    `authority: ${dbMem.authority}`,
+                    `confidence: ${dbMem.confidence}`,
+                    `status: ${dbMem.status}`,
+                    `tier: ${dbMem.tier}`,
+                    `created: '${dbMem.created}'`,
+                    `modified: '${dbMem.modified}'`,
+                ];
+                if (dbMem.source_file) {
+                    headerLines.push(`source_file: ${dbMem.source_file}${dbMem.source_page != null ? ` (page ${Number(dbMem.source_page)})` : ""}`);
+                }
+                if (dbMem.source_path)
+                    headerLines.push(`source_path: ${dbMem.source_path}`);
+                headerLines.push(`---`);
+                const header = headerLines.join("\n");
+                return {
+                    content: [{ type: "text", text: `[Source: gnosys.db]\n\n${header}\n\n${dbMem.content}` }],
+                };
+            }
+            // Not found in db — fall through to legacy path
+        }
+        // v1.x legacy path
+        const memory = await ctx.resolver.readMemory(memPath);
+        if (!memory) {
             return {
-                content: [{ type: "text", text: `[Source: gnosys.db]\n\n${header}\n\n${dbMem.content}` }],
+                content: [{ type: "text", text: `Memory not found: ${memPath}` }],
+                isError: true,
             };
         }
-        // Not found in db — fall through to legacy path
-    }
-    // v1.x legacy path
-    const memory = await ctx.resolver.readMemory(memPath);
-    if (!memory) {
+        let raw;
+        try {
+            raw = await fs.readFile(memory.filePath, "utf-8");
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: formatMcpError("reading memory", err) }], isError: true };
+        }
         return {
-            content: [{ type: "text", text: `Memory not found: ${memPath}` }],
-            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `[Source: ${memory.sourceLabel}]\n\n${raw}`,
+                },
+            ],
         };
     }
-    let raw;
-    try {
-        raw = await fs.readFile(memory.filePath, "utf-8");
-    }
-    catch (err) {
-        return { content: [{ type: "text", text: formatMcpError("reading memory", err) }], isError: true };
+    finally {
+        releaseClientReadFromContext(ctx);
     }
-    return {
-        content: [
-            {
-                type: "text",
-                text: `[Source: ${memory.sourceLabel}]\n\n${raw}`,
-            },
-        ],
-    };
 });
 // ─── Tool: gnosys_search ─────────────────────────────────────────────────
 regTool("gnosys_search", "Search memories by keyword across all stores. Returns matching file paths with relevance snippets.", {
@@ -359,50 +469,65 @@ regTool("gnosys_search", "Search memories by keyword across all stores. Returns
     projectRoot: projectRootParam,
 }, async ({ query, limit, projectRoot }) => {
     const ctx = await resolveToolContext(projectRoot);
-    // v2.0 DB-backed fast path
-    if (ctx.centralDb?.isAvailable() && ctx.centralDb?.isMigrated()) {
-        const results = ctx.centralDb.searchFts(query, limit || 20);
+    try {
+        // v2.0 DB-backed fast path
+        if (ctx.centralDb?.isAvailable() && ctx.centralDb?.isMigrated()) {
+            const lim = limit || 20;
+            let results = ctx.centralDb.searchFts(query, lim);
+            if (ctx.clientRead?.pendingOverlay.length) {
+                results = mergeOverlaySearchResults(results, ctx.clientRead.pendingOverlay, query, lim, (p) => ({
+                    id: p.id,
+                    title: p.title,
+                    snippet: p.content.substring(0, 200),
+                    rank: 0,
+                    project_id: p.project_id,
+                }));
+            }
+            if (results.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No results for "${query}". Try different keywords.` }],
+                };
+            }
+            const formatted = results
+                .map((r) => `**${r.title}** (${r.id})\n${r.snippet.replace(/>>>/g, "**").replace(/<<</g, "**")}`)
+                .join("\n\n");
+            return {
+                content: [{ type: "text", text: `Found ${results.length} results for "${query}":\n\n${formatted}` }],
+            };
+        }
+        // v1.x legacy path
+        if (!ctx.search) {
+            return {
+                content: [{ type: "text", text: "Search index not initialized." }],
+                isError: true,
+            };
+        }
+        const results = ctx.search.search(query, limit || 20);
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No results for "${query}". Try different keywords.` }],
+                content: [
+                    {
+                        type: "text",
+                        text: `No results for "${query}". Try different keywords or use gnosys_discover.`,
+                    },
+                ],
             };
         }
         const formatted = results
-            .map((r) => `**${r.title}** (${r.id})\n${r.snippet.replace(/>>>/g, "**").replace(/<<</g, "**")}`)
+            .map((r) => `**${r.title}** (${r.relative_path})\n${r.snippet.replace(/>>>/g, "**").replace(/<<</g, "**")}`)
             .join("\n\n");
-        return {
-            content: [{ type: "text", text: `Found ${results.length} results for "${query}":\n\n${formatted}` }],
-        };
-    }
-    // v1.x legacy path
-    if (!ctx.search) {
-        return {
-            content: [{ type: "text", text: "Search index not initialized." }],
-            isError: true,
-        };
-    }
-    const results = ctx.search.search(query, limit || 20);
-    if (results.length === 0) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `No results for "${query}". Try different keywords or use gnosys_discover.`,
+                    text: `Found ${results.length} results for "${query}":\n\n${formatted}`,
                 },
             ],
         };
     }
-    const formatted = results
-        .map((r) => `**${r.title}** (${r.relative_path})\n${r.snippet.replace(/>>>/g, "**").replace(/<<</g, "**")}`)
-        .join("\n\n");
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Found ${results.length} results for "${query}":\n\n${formatted}`,
-            },
-        ],
-    };
+    finally {
+        releaseClientReadFromContext(ctx);
+    }
 });
 // ─── Tool: gnosys_list ───────────────────────────────────────────────────
 regTool("gnosys_list", "List memories across all stores, optionally filtered by category, tag, or store layer.", {
@@ -413,41 +538,76 @@ regTool("gnosys_list", "List memories across all stores, optionally filtered by
     projectRoot: projectRootParam,
 }, async ({ category, tag, store: storeFilter, status, projectRoot }) => {
     const ctx = await resolveToolContext(projectRoot);
-    // DB-first: read from central DB instead of scanning markdown files
-    const db = ctx.centralDb;
-    if (db?.isAvailable()) {
-        let dbMemories = status === "active" || !status
-            ? db.getActiveMemories()
-            : db.getAllMemories();
-        // Apply filters on DB results
-        if (status && status !== "active") {
-            dbMemories = dbMemories.filter((m) => m.status === status);
+    try {
+        // DB-first: read from central DB instead of scanning markdown files
+        const db = ctx.centralDb;
+        if (db?.isAvailable()) {
+            let dbMemories = status === "active" || !status
+                ? db.getActiveMemories()
+                : db.getAllMemories();
+            if (ctx.clientRead?.pendingOverlay.length && (status === "active" || !status)) {
+                dbMemories = applyPendingOverlay(dbMemories, ctx.clientRead.pendingOverlay, new Set()).memories;
+            }
+            // Apply filters on DB results
+            if (status && status !== "active") {
+                dbMemories = dbMemories.filter((m) => m.status === status);
+            }
+            if (storeFilter) {
+                dbMemories = dbMemories.filter((m) => m.scope === storeFilter);
+            }
+            if (category) {
+                dbMemories = dbMemories.filter((m) => m.category === category);
+            }
+            if (tag) {
+                dbMemories = dbMemories.filter((m) => {
+                    try {
+                        const parsed = JSON.parse(m.tags || "[]");
+                        const tagList = Array.isArray(parsed)
+                            ? parsed
+                            : Object.values(parsed).flat();
+                        return tagList.includes(tag);
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            // Filter by project if we have a project ID (so scoped queries only see their project)
+            if (ctx.projectId && !storeFilter) {
+                dbMemories = dbMemories.filter((m) => m.project_id === ctx.projectId || m.scope !== "project");
+            }
+            const lines = dbMemories.map((m) => `- [${m.scope}] **${m.title}** (${m.category}/${m.id}) [${m.status}]`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: lines.length > 0
+                            ? `${lines.length} memories:\n\n${lines.join("\n")}`
+                            : "No memories match the filter.",
+                    },
+                ],
+            };
         }
+        // Fallback: read from markdown files if central DB unavailable
+        let memories = await ctx.resolver.getAllMemories();
         if (storeFilter) {
-            dbMemories = dbMemories.filter((m) => m.scope === storeFilter);
+            memories = memories.filter((m) => m.sourceLayer === storeFilter || m.sourceLabel === storeFilter);
         }
         if (category) {
-            dbMemories = dbMemories.filter((m) => m.category === category);
+            memories = memories.filter((m) => m.frontmatter.category === category);
         }
         if (tag) {
-            dbMemories = dbMemories.filter((m) => {
-                try {
-                    const parsed = JSON.parse(m.tags || "[]");
-                    const tagList = Array.isArray(parsed)
-                        ? parsed
-                        : Object.values(parsed).flat();
-                    return tagList.includes(tag);
-                }
-                catch {
-                    return false;
-                }
+            memories = memories.filter((m) => {
+                const tags = Array.isArray(m.frontmatter.tags)
+                    ? m.frontmatter.tags
+                    : Object.values(m.frontmatter.tags).flat();
+                return tags.includes(tag);
             });
         }
-        // Filter by project if we have a project ID (so scoped queries only see their project)
-        if (ctx.projectId && !storeFilter) {
-            dbMemories = dbMemories.filter((m) => m.project_id === ctx.projectId || m.scope !== "project");
+        if (status) {
+            memories = memories.filter((m) => m.frontmatter.status === status);
         }
-        const lines = dbMemories.map((m) => `- [${m.scope}] **${m.title}** (${m.category}/${m.id}) [${m.status}]`);
+        const lines = memories.map((m) => `- [${m.sourceLabel}] **${m.frontmatter.title}** (${m.relativePath}) [${m.frontmatter.status}]`);
         return {
             content: [
                 {
@@ -459,36 +619,9 @@ regTool("gnosys_list", "List memories across all stores, optionally filtered by
             ],
         };
     }
-    // Fallback: read from markdown files if central DB unavailable
-    let memories = await ctx.resolver.getAllMemories();
-    if (storeFilter) {
-        memories = memories.filter((m) => m.sourceLayer === storeFilter || m.sourceLabel === storeFilter);
-    }
-    if (category) {
-        memories = memories.filter((m) => m.frontmatter.category === category);
-    }
-    if (tag) {
-        memories = memories.filter((m) => {
-            const tags = Array.isArray(m.frontmatter.tags)
-                ? m.frontmatter.tags
-                : Object.values(m.frontmatter.tags).flat();
-            return tags.includes(tag);
-        });
-    }
-    if (status) {
-        memories = memories.filter((m) => m.frontmatter.status === status);
+    finally {
+        releaseClientReadFromContext(ctx);
     }
-    const lines = memories.map((m) => `- [${m.sourceLabel}] **${m.frontmatter.title}** (${m.relativePath}) [${m.frontmatter.status}]`);
-    return {
-        content: [
-            {
-                type: "text",
-                text: lines.length > 0
-                    ? `${lines.length} memories:\n\n${lines.join("\n")}`
-                    : "No memories match the filter.",
-            },
-        ],
-    };
 });
 // ─── Tool: gnosys_add ────────────────────────────────────────────────────
 regTool("gnosys_add", "Add a new memory. Accepts raw text — an LLM structures it into an atomic memory. Writes to the project store by default. Use store='personal' for cross-project knowledge, or store='global' to explicitly write to shared org knowledge.", {
@@ -1560,7 +1693,7 @@ regTool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) into Gn
     const effectiveMode = mode || "structured";
     try {
         // v5.9.1 (#100): import.js pulls mammoth + pdf-parse + turndown.
-        const { performImport, formatImportSummary, estimateDuration } = await import("./lib/import.js");
+        const { performImport, formatImportSummary } = await import("./lib/import.js");
         const result = await performImport(writeTarget.store, ingestion, {
             format: format,
             data,
@@ -1585,7 +1718,6 @@ regTool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) into Gn
         // Smart threshold guidance
         if (effectiveMode === "llm" &&
             result.totalProcessed > 100) {
-            const estimate = estimateDuration(result.totalProcessed, "llm", concurrency || 5);
             response += `\n\n💡 Tip: For large LLM imports, the CLI offers progress tracking and resume:\n  gnosys import ${data.length < 100 ? data : "<file>"} --format ${format} --mode llm --skip-existing`;
         }
         return { content: [{ type: "text", text: response }] };
@@ -1895,7 +2027,7 @@ regTool("gnosys_dream", "Run a Dream Mode cycle — idle-time consolidation that
 }, async (params) => {
     try {
         const ctx = await resolveToolContext(params.projectRoot);
-        if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+        if (!ctx.centralDb?.isAvailable() || !ctx.centralDb.isMigrated()) {
             return {
                 content: [
                     {
@@ -1905,8 +2037,6 @@ regTool("gnosys_dream", "Run a Dream Mode cycle — idle-time consolidation that
                 ],
             };
         }
-        // Record activity to reset idle timer (if scheduler is running)
-        dreamScheduler?.recordActivity();
         const dreamConfig = {
             enabled: true,
             idleMinutes: 0, // Run immediately (manual trigger)
@@ -1924,6 +2054,34 @@ regTool("gnosys_dream", "Run a Dream Mode cycle — idle-time consolidation that
         const report = await engine.dream((phase, detail) => {
             console.error(`[dream:${phase}] ${detail}`);
         });
+        const { appendDreamRun } = await import("./lib/dreamRunLog.js");
+        appendDreamRun({
+            ...report,
+            id: report.id || `dream-${Date.now()}`,
+            trigger: report.trigger || "manual",
+            status: report.aborted ? "aborted" : report.errors.length > 0 ? "failed" : "completed",
+            machine: report.machine || { hostname: "unknown" },
+            provider: report.provider || dreamConfig.provider,
+            phases: report.phases || [],
+            llmCalls: report.llmCalls || [],
+            totals: report.totals || {
+                llmCallsMade: 0,
+                llmCallsSkipped: 0,
+                estimatedInputTokens: 0,
+                estimatedOutputTokens: 0,
+                estimatedCostUsd: 0,
+            },
+            effectiveness: report.effectiveness || {
+                usefulOutputScore: 0,
+                costPerUsefulOutput: null,
+                decaysApplied: report.decayUpdated,
+                summariesGenerated: report.summariesGenerated,
+                summariesUpdated: report.summariesUpdated,
+                reviewSuggestions: report.reviewSuggestions.length,
+                relationshipsDiscovered: report.relationshipsDiscovered,
+            },
+            gates: [],
+        });
         return {
             content: [
                 {
@@ -1949,7 +2107,7 @@ regTool("gnosys_export", "Export gnosys.db to Obsidian-compatible vault — atom
 }, async (params) => {
     try {
         const ctx = await resolveToolContext(params.projectRoot);
-        if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+        if (!ctx.centralDb?.isAvailable() || !ctx.centralDb.isMigrated()) {
             return {
                 content: [
                     {
@@ -2072,8 +2230,6 @@ regResource("gnosys_recall", "gnosys://recall", {
         priority: 1, // Highest priority — always inject
     },
 }, async () => {
-    // Record activity for dream scheduler (this fires on every turn)
-    dreamScheduler?.recordActivity();
     if (!search) {
         return {
             contents: [
@@ -2086,23 +2242,31 @@ regResource("gnosys_recall", "gnosys://recall", {
         };
     }
     const storePath = resolver.getWriteTarget()?.store.getStorePath() || "";
-    const result = await recall("*", {
-        limit: config.recall?.maxMemories || 8,
-        search,
-        resolver,
-        storePath,
-        recallConfig: config.recall,
-        gnosysDb: gnosysDb || undefined,
-    });
-    return {
-        contents: [
-            {
-                uri: "gnosys://recall",
-                mimeType: "text/markdown",
-                text: formatRecall(result),
-            },
-        ],
-    };
+    const applied = applyClientReadToCentralDb(centralDb);
+    try {
+        const result = await recall("*", {
+            limit: config.recall?.maxMemories || 8,
+            search,
+            resolver,
+            storePath,
+            recallConfig: config.recall,
+            gnosysDb: applied.centralDb || undefined,
+            pendingOverlay: applied.clientRead?.pendingOverlay,
+        });
+        return {
+            contents: [
+                {
+                    uri: "gnosys://recall",
+                    mimeType: "text/markdown",
+                    text: formatRecall(result),
+                },
+            ],
+        };
+    }
+    finally {
+        if (applied.clientRead)
+            closeClientReadContext(applied.clientRead);
+    }
 });
 // ─── Tool: gnosys_recall (query-specific fallback) ──────────────────────
 // For hosts that don't support MCP Resources, or when the agent wants to
@@ -2118,28 +2282,34 @@ regTool("gnosys_recall", "Fast memory recall — inject relevant memories as con
 }, async ({ query, limit, traceId, aggressive, projectRoot }) => {
     try {
         const ctx = await resolveToolContext(projectRoot);
-        if (!ctx.search) {
+        try {
+            if (!ctx.search) {
+                return {
+                    content: [{ type: "text", text: "<gnosys: no-strong-recall-needed>" }],
+                };
+            }
+            const storePath = ctx.resolver.getWriteTarget()?.store.getStorePath() || "";
+            const recallConfig = {
+                ...ctx.config.recall,
+                ...(aggressive !== undefined ? { aggressive } : {}),
+            };
+            const result = await recall(query, {
+                limit: Math.min(limit || recallConfig.maxMemories, 15),
+                search: ctx.search,
+                resolver: ctx.resolver,
+                storePath,
+                traceId,
+                recallConfig,
+                gnosysDb: ctx.centralDb || undefined,
+                pendingOverlay: ctx.clientRead?.pendingOverlay,
+            });
             return {
-                content: [{ type: "text", text: "<gnosys: no-strong-recall-needed>" }],
+                content: [{ type: "text", text: formatRecall(result) }],
             };
         }
-        const storePath = ctx.resolver.getWriteTarget()?.store.getStorePath() || "";
-        const recallConfig = {
-            ...ctx.config.recall,
-            ...(aggressive !== undefined ? { aggressive } : {}),
-        };
-        const result = await recall(query, {
-            limit: Math.min(limit || recallConfig.maxMemories, 15),
-            search: ctx.search,
-            resolver: ctx.resolver,
-            storePath,
-            traceId,
-            recallConfig,
-            gnosysDb: ctx.centralDb || undefined,
-        });
-        return {
-            content: [{ type: "text", text: formatRecall(result) }],
-        };
+        finally {
+            releaseClientReadFromContext(ctx);
+        }
     }
     catch (err) {
         return { content: [{ type: "text", text: formatMcpError("recalling memories", err) }], isError: true };
@@ -2383,28 +2553,34 @@ regTool("gnosys_federated_search", "Search across all scopes (project → user
     projectRoot: z.string().optional().describe("Project root directory for context detection"),
     includeGlobal: z.boolean().optional().describe("Include global-scope memories (default: true)"),
 }, async ({ query, limit, projectRoot, includeGlobal }) => {
-    if (!centralDb?.isAvailable()) {
-        return { content: [{ type: "text", text: "Central DB not available. Run gnosys_init first." }], isError: true };
+    const ctx = await resolveToolContext(projectRoot);
+    try {
+        if (!ctx.centralDb?.isAvailable()) {
+            return { content: [{ type: "text", text: "Central DB not available. Run gnosys_init first." }], isError: true };
+        }
+        // Auto-detect current project
+        const projectId = await detectCurrentProject(ctx.centralDb, projectRoot || undefined);
+        const results = federatedSearch(ctx.centralDb, query, {
+            limit: limit || 20,
+            projectId,
+            includeGlobal: includeGlobal !== false,
+        });
+        if (results.length === 0) {
+            return { content: [{ type: "text", text: `No results for "${query}" across any scope.` }] };
+        }
+        const lines = results.map((r, i) => {
+            const projectLabel = r.projectName ? ` [${r.projectName}]` : "";
+            const boostLabel = r.boosts.length > 0 ? ` (${r.boosts.join(", ")})` : "";
+            return `${i + 1}. **${r.title}** (${r.category})${projectLabel}\n   scope: ${r.scope} | score: ${r.score.toFixed(4)}${boostLabel}\n   ${r.snippet}`;
+        });
+        const contextNote = projectId ? `Context: project ${projectId}` : "Context: no project detected";
+        return {
+            content: [{ type: "text", text: `${contextNote}\n\n${lines.join("\n\n")}` }],
+        };
     }
-    // Auto-detect current project
-    const projectId = await detectCurrentProject(centralDb, projectRoot || undefined);
-    const results = federatedSearch(centralDb, query, {
-        limit: limit || 20,
-        projectId,
-        includeGlobal: includeGlobal !== false,
-    });
-    if (results.length === 0) {
-        return { content: [{ type: "text", text: `No results for "${query}" across any scope.` }] };
+    finally {
+        releaseClientReadFromContext(ctx);
     }
-    const lines = results.map((r, i) => {
-        const projectLabel = r.projectName ? ` [${r.projectName}]` : "";
-        const boostLabel = r.boosts.length > 0 ? ` (${r.boosts.join(", ")})` : "";
-        return `${i + 1}. **${r.title}** (${r.category})${projectLabel}\n   scope: ${r.scope} | score: ${r.score.toFixed(4)}${boostLabel}\n   ${r.snippet}`;
-    });
-    const contextNote = projectId ? `Context: project ${projectId}` : "Context: no project detected";
-    return {
-        content: [{ type: "text", text: `${contextNote}\n\n${lines.join("\n\n")}` }],
-    };
 });
 // ─── Tool: gnosys_detect_ambiguity ──────────────────────────────────────
 regTool("gnosys_detect_ambiguity", "Check if a query matches memories in multiple projects. Use before write operations to confirm the target project when ambiguity exists.", {
@@ -2500,7 +2676,8 @@ regTool("gnosys_remote_status", "Check the status of remote sync (multi-machine)
         if (!localDb.isAvailable()) {
             return { content: [{ type: "text", text: "Local DB not available." }], isError: true };
         }
-        const remotePath = localDb.getMeta("remote_path");
+        const { getConfiguredRemotePath } = await import("./lib/remote.js");
+        const remotePath = getConfiguredRemotePath(localDb);
         if (!remotePath) {
             return {
                 content: [{
@@ -2509,6 +2686,14 @@ regTool("gnosys_remote_status", "Check the status of remote sync (multi-machine)
                     }],
             };
         }
+        const { readMachineConfig } = await import("./lib/machineConfig.js");
+        if (readMachineConfig()?.remote.role) {
+            const { getV13SyncStatus } = await import("./lib/syncClient.js");
+            const v13 = getV13SyncStatus(localDb);
+            return {
+                content: [{ type: "text", text: JSON.stringify(v13, null, 2) }],
+            };
+        }
         const { RemoteSync } = await import("./lib/remote.js");
         const sync = new RemoteSync(localDb, remotePath);
         const status = await sync.getStatus();
@@ -2595,6 +2780,106 @@ regTool("gnosys_remote_resolve", "Resolve a sync conflict by choosing which vers
         localDb.close();
     }
 });
+// ─── Tool: gnosys_attach ────────────────────────────────────────────────
+regTool("gnosys_attach", "Attach a small binary file (logo, diagram, screenshot, small PDF) directly to a memory. The bytes are stored inline in the memory row, so the attachment travels machine-to-machine over the normal sync and works with a remote/dockerized server (no shared filesystem). Limit ~10MB — use gnosys_ingest_file for large media.", {
+    memoryId: z.string().describe("Memory ID to attach the file to (e.g., 'deci-052')"),
+    filePath: z.string().describe("Absolute path to the file to attach"),
+    projectRoot: projectRootParam,
+}, async ({ memoryId, filePath, projectRoot }) => {
+    const ctx = await resolveToolContext(projectRoot);
+    if (!ctx.centralDb?.isAvailable()) {
+        return {
+            content: [{ type: "text", text: "Database not available. Cannot attach file." }],
+            isError: true,
+        };
+    }
+    try {
+        const { attachFileToMemory } = await import("./lib/attachments.js");
+        const result = await attachFileToMemory(ctx.centralDb, memoryId, filePath);
+        auditToDb(ctx.centralDb, "write", memoryId, {
+            tool: "gnosys_attach",
+            name: result.name,
+            mime: result.mime,
+            sizeBytes: result.sizeBytes,
+            unchanged: result.unchanged,
+        });
+        const sizeKb = (result.sizeBytes / 1024).toFixed(1);
+        const verb = result.unchanged ? "already attached (no change)" : "attached";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `File ${verb}: ${result.name} (${result.mime}, ${sizeKb} KB)\nMemory: ${memoryId}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: formatMcpError("attaching file", err) }],
+            isError: true,
+        };
+    }
+});
+// ─── Tool: gnosys_get_attachment ────────────────────────────────────────
+regTool("gnosys_get_attachment", "Retrieve the binary attachment stored on a memory. By default returns the bytes (base64, plus an inline image when the attachment is an image). Pass outputPath to write the file to disk instead.", {
+    memoryId: z.string().describe("Memory ID that holds the attachment"),
+    outputPath: z.string().optional().describe("If provided, write the attachment to this absolute path instead of returning bytes"),
+    projectRoot: projectRootParam,
+}, async ({ memoryId, outputPath, projectRoot }) => {
+    const ctx = await resolveToolContext(projectRoot);
+    if (!ctx.centralDb?.isAvailable()) {
+        return {
+            content: [{ type: "text", text: "Database not available." }],
+            isError: true,
+        };
+    }
+    try {
+        const { getMemoryAttachment } = await import("./lib/attachments.js");
+        const att = getMemoryAttachment(ctx.centralDb, memoryId);
+        if (!att) {
+            return {
+                content: [{ type: "text", text: `No attachment found on memory: ${memoryId}` }],
+                isError: true,
+            };
+        }
+        if (outputPath) {
+            const { writeFile } = await import("fs/promises");
+            await writeFile(outputPath, att.data);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Wrote ${att.name} (${att.mime}, ${att.data.length} bytes) to ${outputPath}`,
+                    },
+                ],
+            };
+        }
+        const base64 = att.data.toString("base64");
+        if (att.mime.startsWith("image/")) {
+            return {
+                content: [
+                    { type: "image", data: base64, mimeType: att.mime },
+                    { type: "text", text: `${att.name} (${att.mime}, ${att.data.length} bytes)` },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${att.name} (${att.mime}, ${att.data.length} bytes)\n\nbase64:\n${base64}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: formatMcpError("reading attachment", err) }],
+            isError: true,
+        };
+    }
+});
 // ─── Tool: gnosys_update_status ─────────────────────────────────────────
 regTool("gnosys_update_status", "Get the prompt/template for writing a dashboard-compatible status memory for this project. Returns instructions for creating a landscape memory with the correct heading format so the portfolio dashboard can parse it. Run this, then follow the instructions to analyze and write the status.", {
     projectRoot: z.string().optional().describe("Project root for auto-detection"),
@@ -2887,11 +3172,10 @@ async function initHeavyDeps() {
     const embCount = embeddings.hasEmbeddings() ? embeddings.count() : 0;
     console.error(`Hybrid search: ${embCount > 0 ? `ready (${embCount} embeddings)` : "available (run gnosys_reindex to build embeddings)"}`);
     console.error(`Ask engine: ${askEngine.isLLMAvailable ? `ready (${askEngine.providerName}/${askEngine.modelName})` : "disabled (configure LLM provider)"}`);
-    // Dream mode (only constructed if enabled; designation gate inside start()).
+    // Dream mode scheduling is machine-level now (`gnosys dream run --scheduled`
+    // via launchd). MCP may still run manual dream tool calls, but it no longer
+    // owns an idle timer per connection.
     if (gnosysDb && config.dream?.enabled) {
-        const { GnosysDreamEngine, DreamScheduler } = await import("./lib/dream.js");
-        const dreamEngine = new GnosysDreamEngine(gnosysDb, config, config.dream);
-        dreamScheduler = new DreamScheduler(dreamEngine, config.dream);
         // Layer 3: probe the dream provider if this machine is the dream node.
         try {
             const designated = gnosysDb.getDreamMachineId();
@@ -2933,9 +3217,8 @@ async function initHeavyDeps() {
             }
         }
         catch {
-            // Probe failed — non-fatal. Continue with scheduler start.
+            // Probe failed — non-fatal.
         }
-        dreamScheduler.start();
         const designated = gnosysDb.getDreamMachineId();
         const localId = gnosysDb.getMeta("machine_id");
         if (!designated) {
@@ -2945,7 +3228,7 @@ async function initHeavyDeps() {
             console.error(`Dream Mode: enabled — designated to '${designated}'. This machine (${localId || "?"}) will not dream.`);
         }
         else {
-            console.error(`Dream Mode: enabled on this machine (idle ${config.dream.idleMinutes}min, max ${config.dream.maxRuntimeMinutes}min)`);
+            console.error(`Dream Mode: enabled on this machine (scheduled outside MCP via launchd, max ${config.dream.maxRuntimeMinutes}min)`);
         }
     }
     else {
@@ -2957,6 +3240,15 @@ async function initHeavyDeps() {
 // ─── Start the server ────────────────────────────────────────────────────
 /** Start the MCP server (stdio or http). Called by `gnosys serve` and when invoked as `gnosys-mcp`. */
 export async function startMcpServer() {
+    // v5.12.1 reliability: an escaped async error must not kill the server.
+    // Log to stderr (stdout is JSON-RPC in stdio mode) and keep serving —
+    // all persistent state is transactional SQLite, so survivors are safe.
+    process.on("unhandledRejection", (reason) => {
+        console.error(`Gnosys MCP: unhandled rejection — ${reason instanceof Error ? reason.stack || reason.message : String(reason)}`);
+    });
+    process.on("uncaughtException", (err) => {
+        console.error(`Gnosys MCP: uncaught exception — ${err.stack || err.message}`);
+    });
     // v5.7.1 (#15): start the upgrade-marker watcher BEFORE anything else.
     // If `gnosys upgrade` was run on this machine while the MCP was idle,
     // pick that up immediately instead of serving stale tool handlers.
@@ -2985,6 +3277,12 @@ export async function startMcpServer() {
     console.error("Gnosys MCP server starting.");
     console.error("Active stores:");
     console.error(resolver.getSummary());
+    // v13: background ingest sweep on master-role MCP startup (non-blocking).
+    void import("./lib/syncIngestStartup.js")
+        .then(({ maybeRunStartupIngestSweep }) => maybeRunStartupIngestSweep())
+        .catch((err) => {
+        console.error(`[sync] Startup ingest sweep failed: ${err instanceof Error ? err.message : err}`);
+    });
     // Initialize search from the first writable store. Everything in this
     // block is FAST — opening the search index + tag registry + loading
     // gnosys.json. The slow stuff (LLM providers, transformers embeddings,