@phren/cli 0.0.28 → 0.0.33

package/mcp/dist/{shared-index.js → shared/index.js}

@@ -3,21 +3,22 @@ import * as path from "path";
 import * as os from "os";
 import * as crypto from "crypto";
 import { globSync } from "glob";
-import { debugLog, appendIndexEvent, getProjectDirs, collectNativeMemoryFiles, runtimeFile, homeDir, readRootManifest, } from "./shared.js";
-import { getIndexPolicy, withFileLock } from "./shared-governance.js";
-import { stripTaskDoneSection } from "./shared-content.js";
-import { isInactiveFindingLine } from "./finding-lifecycle.js";
-import { invalidateDfCache } from "./shared-search-fallback.js";
-import { errorMessage } from "./utils.js";
-import { beginUserFragmentBuildCache, endUserFragmentBuildCache, extractAndLinkFragments, ensureGlobalEntitiesTable, } from "./shared-fragment-graph.js";
-import { bootstrapSqlJs } from "./shared-sqljs.js";
-import { getProjectOwnershipMode, getProjectSourcePath, readProjectConfig } from "./project-config.js";
-import { buildSourceDocKey, queryDocBySourceKey, queryDocRows, } from "./index-query.js";
-import { classifyTopicForText, readProjectTopics, } from "./project-topics.js";
-export { porterStem } from "./shared-stemmer.js";
-export { cosineFallback } from "./shared-search-fallback.js";
-export { queryFragmentLinks, queryFragmentLinks as queryEntityLinks, getFragmentBoostDocs, getFragmentBoostDocs as getEntityBoostDocs, ensureGlobalEntitiesTable, queryCrossProjectFragments, logFragmentMiss, logFragmentMiss as logEntityMiss, extractFragmentNames, extractFragmentNames as extractEntityNames, } from "./shared-fragment-graph.js";
-export { buildSourceDocKey, decodeFiniteNumber, decodeStringRow, extractSnippet, getDocSourceKey, normalizeMemoryId, queryDocBySourceKey, queryDocRows, queryRows, rowToDoc, rowToDocWithRowid, } from "./index-query.js";
+import { debugLog, appendIndexEvent, getProjectDirs, collectNativeMemoryFiles, runtimeFile, homeDir, readRootManifest, } from "../shared.js";
+import { getIndexPolicy, withFileLock } from "./governance.js";
+import { stripTaskDoneSection } from "./content.js";
+import { isInactiveFindingLine } from "../finding/lifecycle.js";
+import { invalidateDfCache } from "./search-fallback.js";
+import { errorMessage } from "../utils.js";
+import { logger } from "../logger.js";
+import { beginUserFragmentBuildCache, endUserFragmentBuildCache, extractAndLinkFragments, ensureGlobalEntitiesTable, } from "./fragment-graph.js";
+import { bootstrapSqlJs } from "./sqljs.js";
+import { getProjectOwnershipMode, getProjectSourcePath, readProjectConfig } from "../project-config.js";
+import { buildSourceDocKey, queryDocBySourceKey, queryDocRows, } from "../index-query.js";
+import { classifyTopicForText, readProjectTopics, } from "../project-topics.js";
+export { porterStem } from "./stemmer.js";
+export { cosineFallback } from "./search-fallback.js";
+export { queryFragmentLinks, getFragmentBoostDocs, ensureGlobalEntitiesTable, queryCrossProjectFragments, logFragmentMiss, extractFragmentNames, } from "./fragment-graph.js";
+export { buildSourceDocKey, decodeFiniteNumber, decodeStringRow, extractSnippet, getDocSourceKey, normalizeMemoryId, queryDocBySourceKey, queryDocRows, queryRows, rowToDoc, rowToDocWithRowid, } from "../index-query.js";
 // ── Async embedding queue ───────────────────────────────────────────────────
 const _embQueue = new Map();
 let _embTimer = null;
@@ -32,8 +33,8 @@ function scheduleEmbedding(phrenPath, docPath, content) {
 async function _drainEmbQueue() {
     if (_embQueue.size === 0)
         return;
-    const { embedText, getEmbeddingModel } = await import("./shared-ollama.js");
-    const { getEmbeddingCache } = await import("./shared-embedding-cache.js");
+    const { embedText, getEmbeddingModel } = await import("./ollama.js");
+    const { getEmbeddingCache } = await import("./embedding-cache.js");
     const entries = [..._embQueue.entries()];
     _embQueue.clear();
     // Group by phrenPath so we flush each cache once after all its entries are set.
@@ -49,8 +50,7 @@ async function _drainEmbQueue() {
             await cache.load();
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] embeddingQueue cacheLoad: ${errorMessage(err)}\n`);
+            logger.debug("embeddingQueue cacheLoad", errorMessage(err));
         }
         const model = getEmbeddingModel();
         for (const { docPath, content } of docs) {
@@ -62,16 +62,14 @@ async function _drainEmbQueue() {
                     cache.set(docPath, getEmbeddingModel(), vec);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] embeddingQueue embedText: ${errorMessage(err)}\n`);
+                logger.debug("embeddingQueue embedText", errorMessage(err));
             }
         }
         try {
             await cache.flush();
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] embeddingQueue cacheFlush: ${errorMessage(err)}\n`);
+            logger.debug("embeddingQueue cacheFlush", errorMessage(err));
         }
     }
 }
@@ -133,8 +131,7 @@ function _resolveImportsRecursive(content, phrenPath, seen, depth) {
             normalized = fs.realpathSync.native(resolved);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] resolveImports realpath: ${errorMessage(err)}\n`);
+            logger.debug("resolveImports realpath", errorMessage(err));
             return `<!-- @import not found: ${trimmed} -->`;
         }
         let normalizedGlobalRoot = globalRoot;
@@ -158,8 +155,7 @@ function _resolveImportsRecursive(content, phrenPath, seen, depth) {
             return _resolveImportsRecursive(imported, phrenPath, childSeen, depth + 1);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] resolveImports fileRead: ${errorMessage(err)}\n`);
+            logger.debug("resolveImports fileRead", errorMessage(err));
             return `<!-- @import error: ${trimmed} -->`;
         }
     });
@@ -169,6 +165,7 @@ function _resolveImportsRecursive(content, phrenPath, seen, depth) {
  * The import path is resolved relative to the phren root (e.g. `shared/foo.md` -> `~/.phren/global/shared/foo.md`).
  * Circular imports are detected and skipped. Depth is capped to prevent runaway recursion.
  */
+/** @internal Exported for tests. */
 export function resolveImports(content, phrenPath) {
     return _resolveImportsRecursive(content, phrenPath, new Set(), 0);
 }
@@ -180,8 +177,7 @@ function touchSentinel(phrenPath) {
         fs.writeFileSync(sentinelPath, Date.now().toString());
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] touchSentinel: ${errorMessage(err)}\n`);
+        logger.debug("touchSentinel", errorMessage(err));
     }
 }
 function computePhrenHash(phrenPath, profile, preGlobbed) {
@@ -197,8 +193,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
                 hash.update(`${f}:${stat.mtimeMs}:${stat.size}`);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] computePhrenHash skip: ${errorMessage(err)}\n`);
+                logger.debug("computePhrenHash skip", errorMessage(err));
             }
         }
         for (const configPath of topicConfigEntries) {
@@ -207,8 +202,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
                 hash.update(`topic-config:${configPath}:${stat.mtimeMs}:${stat.size}`);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] computePhrenHash topicConfig: ${errorMessage(err)}\n`);
+                logger.debug("computePhrenHash topicConfig", errorMessage(err));
             }
         }
     }
@@ -239,8 +233,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
                 }
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] computePhrenHash globDir: ${errorMessage(err)}\n`);
+                logger.debug("computePhrenHash globDir", errorMessage(err));
             }
         }
         files.sort();
@@ -250,8 +243,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
                 hash.update(`${f}:${stat.mtimeMs}:${stat.size}`);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] computePhrenHash skip: ${errorMessage(err)}\n`);
+                logger.debug("computePhrenHash skip", errorMessage(err));
             }
         }
         for (const configPath of topicConfigEntries) {
@@ -260,8 +252,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
                 hash.update(`topic-config:${configPath}:${stat.mtimeMs}:${stat.size}`);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] computePhrenHash topicConfig: ${errorMessage(err)}\n`);
+                logger.debug("computePhrenHash topicConfig", errorMessage(err));
             }
         }
     }
@@ -271,8 +262,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
             hash.update(`native:${mem.fullPath}:${stat.mtimeMs}:${stat.size}`);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] computePhrenHash skip: ${errorMessage(err)}\n`);
+            logger.debug("computePhrenHash skip", errorMessage(err));
         }
     }
     // Include global/ files (pulled via @import) so changes invalidate the cache
@@ -286,8 +276,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
                 hash.update(`global:${f}:${stat.mtimeMs}:${stat.size}`);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] computePhrenHash skip: ${errorMessage(err)}\n`);
+                logger.debug("computePhrenHash skip", errorMessage(err));
             }
         }
     }
@@ -299,8 +288,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
             hash.update(`manual-links:${stat.mtimeMs}:${stat.size}`);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] computePhrenHash skip: ${errorMessage(err)}\n`);
+            logger.debug("computePhrenHash skip", errorMessage(err));
         }
     }
     const indexPolicyPath = path.join(phrenPath, ".config", "index-policy.json");
@@ -310,8 +298,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
             hash.update(`index-policy-file:${stat.mtimeMs}:${stat.size}`);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] computePhrenHash skip: ${errorMessage(err)}\n`);
+            logger.debug("computePhrenHash skip", errorMessage(err));
         }
     }
     if (profile)
@@ -334,12 +321,11 @@ function loadHashMap(phrenPath) {
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] loadHashMap: ${errorMessage(err)}\n`);
+        logger.debug("loadHashMap", errorMessage(err));
     }
     return { hashes: {} };
 }
-function saveHashMap(phrenPath, hashes) {
+function saveHashMap(phrenPath, hashes, knownPaths) {
     const runtimeDir = path.join(phrenPath, ".runtime");
     try {
         fs.mkdirSync(runtimeDir, { recursive: true });
@@ -355,13 +341,14 @@ function saveHashMap(phrenPath, hashes) {
                     existing = data.hashes;
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] saveHashMap readExisting: ${errorMessage(err)}\n`);
+                logger.debug("saveHashMap readExisting", errorMessage(err));
             }
             const merged = { ...existing, ...hashes };
-            // Remove entries for paths that no longer exist on disk
+            // Remove entries for paths that no longer exist. When knownPaths is provided
+            // (build passes supply the full file list), use set membership instead of
+            // hitting the filesystem — avoids N sync stat calls inside the lock.
             for (const filePath of Object.keys(merged)) {
-                if (!fs.existsSync(filePath)) {
+                if (knownPaths ? !knownPaths.has(filePath) : !fs.existsSync(filePath)) {
                     delete merged[filePath];
                 }
             }
@@ -494,8 +481,7 @@ function insertFileIntoIndex(db, entry, phrenPath, opts) {
         return true;
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] insertFileIntoIndex: ${errorMessage(err)}\n`);
+        logger.debug("insertFileIntoIndex", errorMessage(err));
         return false;
     }
 }
@@ -575,8 +561,7 @@ function deleteEntityLinksForDocPath(db, phrenPath, docPath, fallbackProject, fa
         db.run("DELETE FROM global_entities WHERE doc_key = ?", [sourceDoc]);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] deleteEntityLinksForDocPath globalEntities: ${errorMessage(err)}\n`);
+        logger.debug("deleteEntityLinksForDocPath globalEntities", errorMessage(err));
     }
 }
 /**
@@ -591,15 +576,13 @@ export function updateFileInIndex(db, filePath, phrenPath) {
         deleteEntityLinksForDocPath(db, phrenPath, resolvedPath);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] updateFileInIndex deleteEntityLinks: ${errorMessage(err)}\n`);
+        logger.debug("updateFileInIndex deleteEntityLinks", errorMessage(err));
     }
     try {
         db.run("DELETE FROM docs WHERE path = ?", [resolvedPath]);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] updateFileInIndex deleteDocs: ${errorMessage(err)}\n`);
+        logger.debug("updateFileInIndex deleteDocs", errorMessage(err));
     }
     // Re-insert if file still exists
     if (fs.existsSync(resolvedPath)) {
@@ -618,8 +601,7 @@ export function updateFileInIndex(db, filePath, phrenPath) {
                     extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
                 }
                 catch (err) {
-                    if ((process.env.PHREN_DEBUG))
-                        process.stderr.write(`[phren] updateFileInIndex entityExtraction: ${errorMessage(err)}\n`);
+                    logger.debug("updateFileInIndex entityExtraction", errorMessage(err));
                 }
             }
         }
@@ -630,22 +612,20 @@ export function updateFileInIndex(db, filePath, phrenPath) {
             saveHashMap(phrenPath, hashData.hashes);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] updateFileInIndex hashMap: ${errorMessage(err)}\n`);
+            logger.debug("updateFileInIndex hashMap", errorMessage(err));
         }
     }
     else {
         // Remove stale embedding if file was deleted
         void (async () => {
             try {
-                const { getEmbeddingCache } = await import("./shared-embedding-cache.js");
+                const { getEmbeddingCache } = await import("./embedding-cache.js");
                 const c = getEmbeddingCache(phrenPath);
                 c.delete(resolvedPath);
                 await c.flush();
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] updateFileInIndex embeddingDelete: ${errorMessage(err)}\n`);
+                logger.debug("updateFileInIndex embeddingDelete", errorMessage(err));
             }
         })();
     }
@@ -664,8 +644,7 @@ function readHashSentinel(phrenPath) {
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] readHashSentinel: ${errorMessage(err)}\n`);
+        logger.debug("readHashSentinel", errorMessage(err));
     }
     return null;
 }
@@ -675,8 +654,7 @@ function writeHashSentinel(phrenPath, hash) {
         fs.writeFileSync(sentinelPath, JSON.stringify({ hash, computedAt: Date.now() }));
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] writeHashSentinel: ${errorMessage(err)}\n`);
+        logger.debug("writeHashSentinel", errorMessage(err));
     }
 }
 function isSentinelFresh(phrenPath, sentinel) {
@@ -693,8 +671,7 @@ function isSentinelFresh(phrenPath, sentinel) {
                 return false;
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] isSentinelFresh statDir: ${errorMessage(err)}\n`);
+            logger.debug("isSentinelFresh statDir", errorMessage(err));
         }
     }
     return true;
@@ -715,8 +692,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
                 return fs.statSync(f.fullPath).mtimeMs > graphMtime;
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] loadCachedEntityGraph statFile: ${errorMessage(err)}\n`);
+                logger.debug("loadCachedEntityGraph statFile", errorMessage(err));
                 return true;
             }
         });
@@ -743,8 +719,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
                         db.run("INSERT OR IGNORE INTO global_entities (entity, project, doc_key) VALUES (?, ?, ?)", [entity, project, docKey]);
                     }
                     catch (err) {
-                        if ((process.env.PHREN_DEBUG))
-                            process.stderr.write(`[phren] loadCachedEntityGraph globalEntitiesInsert2: ${errorMessage(err)}\n`);
+                        logger.debug("loadCachedEntityGraph globalEntitiesInsert2", errorMessage(err));
                     }
                 }
             }
@@ -762,23 +737,20 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
                                 db.run("INSERT OR IGNORE INTO global_entities (entity, project, doc_key) VALUES (?, ?, ?)", [name, proj, sourceDoc]);
                             }
                             catch (err) {
-                                if ((process.env.PHREN_DEBUG))
-                                    process.stderr.write(`[phren] loadCachedEntityGraph globalEntitiesInsert: ${errorMessage(err)}\n`);
+                                logger.debug("loadCachedEntityGraph globalEntitiesInsert", errorMessage(err));
                             }
                         }
                     }
                 }
                 catch (err) {
-                    if ((process.env.PHREN_DEBUG))
-                        process.stderr.write(`[phren] entityGraph globalEntitiesRestore: ${errorMessage(err)}\n`);
+                    logger.debug("entityGraph globalEntitiesRestore", errorMessage(err));
                 }
             }
             return true;
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] entityGraph cacheLoad: ${errorMessage(err)}\n`);
+        logger.debug("entityGraph cacheLoad", errorMessage(err));
     }
     return false;
 }
@@ -797,8 +769,7 @@ function mergeManualLinks(db, phrenPath) {
                 // Validate: skip manual links whose sourceDoc no longer exists in the index
                 const docCheck = queryDocBySourceKey(db, phrenPath, link.sourceDoc);
                 if (!docCheck) {
-                    if ((process.env.PHREN_DEBUG))
-                        process.stderr.write(`[phren] manualLinks: pruning stale link to "${link.sourceDoc}"\n`);
+                    logger.debug("manualLinks", `pruning stale link to "${link.sourceDoc}"`);
                     pruned = true;
                     continue;
                 }
@@ -819,14 +790,12 @@ function mergeManualLinks(db, phrenPath) {
                         db.run("INSERT OR IGNORE INTO global_entities (entity, project, doc_key) VALUES (?, ?, ?)", [link.entity, projectMatch[1], link.sourceDoc]);
                     }
                     catch (err) {
-                        if ((process.env.PHREN_DEBUG))
-                            process.stderr.write(`[phren] manualLinks globalEntities: ${errorMessage(err)}\n`);
+                        logger.debug("manualLinks globalEntities", errorMessage(err));
                     }
                 }
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] manualLinks entry: ${errorMessage(err)}\n`);
+                logger.debug("manualLinks entry", errorMessage(err));
             }
         }
         // Rewrite manual-links.json if stale entries were pruned
@@ -839,19 +808,18 @@ function mergeManualLinks(db, phrenPath) {
                 });
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] manualLinks prune write: ${errorMessage(err)}\n`);
+                logger.debug("manualLinks prune write", errorMessage(err));
             }
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] mergeManualLinks: ${errorMessage(err)}\n`);
+        logger.debug("mergeManualLinks", errorMessage(err));
     }
 }
 async function buildIndexImpl(phrenPath, profile) {
     const t0 = Date.now();
-    beginUserFragmentBuildCache(phrenPath, getProjectDirs(phrenPath, profile).map(dir => path.basename(dir)));
+    const projectDirs = getProjectDirs(phrenPath, profile);
+    beginUserFragmentBuildCache(phrenPath, projectDirs.map(dir => path.basename(dir)));
     try {
         // ── Cache dir + hash sentinel ─────────────────────────────────────────────
         let userSuffix;
@@ -859,8 +827,7 @@ async function buildIndexImpl(phrenPath, profile) {
             userSuffix = String(os.userInfo().uid);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] buildIndexImpl userInfo: ${errorMessage(err)}\n`);
+            logger.debug("buildIndexImpl userInfo", errorMessage(err));
             userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
         }
         const cacheDir = path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
@@ -965,8 +932,7 @@ async function buildIndexImpl(phrenPath, profile) {
                             }
                         }
                         catch (err) {
-                            if ((process.env.PHREN_DEBUG))
-                                process.stderr.write(`[phren] buildIndex hashFile: ${errorMessage(err)}\n`);
+                            logger.debug("buildIndex hashFile", errorMessage(err));
                         }
                     }
                     // Check for files missing from the index (deleted files)
@@ -1001,28 +967,24 @@ async function buildIndexImpl(phrenPath, profile) {
                                     deleteEntityLinksForDocPath(db, phrenPath, missingPath);
                                 }
                                 catch (err) {
-                                    if ((process.env.PHREN_DEBUG))
-                                        process.stderr.write(`[phren] buildIndex deleteEntityLinksForMissing: ${errorMessage(err)}\n`);
+                                    logger.debug("buildIndex deleteEntityLinksForMissing", errorMessage(err));
                                 }
                                 try {
                                     db.run("DELETE FROM docs WHERE path = ?", [missingPath]);
                                 }
                                 catch (err) {
-                                    if ((process.env.PHREN_DEBUG))
-                                        process.stderr.write(`[phren] buildIndex deleteDocForMissing: ${errorMessage(err)}\n`);
+                                    logger.debug("buildIndex deleteDocForMissing", errorMessage(err));
                                 }
                             }
                             db.run("COMMIT");
                         }
                         catch (err) {
-                            if ((process.env.PHREN_DEBUG))
-                                process.stderr.write(`[phren] buildIndex incrementalDeleteCommit: ${errorMessage(err)}\n`);
+                            logger.debug("buildIndex incrementalDeleteCommit", errorMessage(err));
                             try {
                                 db.run("ROLLBACK");
                             }
                             catch (e2) {
-                                if ((process.env.PHREN_DEBUG))
-                                    process.stderr.write(`[phren] buildIndex incrementalDeleteRollback: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+                                logger.debug("buildIndex incrementalDeleteRollback", e2 instanceof Error ? e2.message : String(e2));
                             }
                         }
                         let updatedCount = 0;
@@ -1058,13 +1020,12 @@ async function buildIndexImpl(phrenPath, profile) {
                                     db.run("ROLLBACK");
                                 }
                                 catch (e2) {
-                                    if ((process.env.PHREN_DEBUG))
-                                        process.stderr.write(`[phren] buildIndex perFileRollback: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+                                    logger.debug("buildIndex perFileRollback", e2 instanceof Error ? e2.message : String(e2));
                                 }
                                 throw err;
                             }
                         }
-                        saveHashMap(phrenPath, currentHashes);
+                        saveHashMap(phrenPath, currentHashes, new Set(Object.keys(currentHashes)));
                         touchSentinel(phrenPath);
                         invalidateDfCache();
                         // Save updated cache
@@ -1073,8 +1034,7 @@ async function buildIndexImpl(phrenPath, profile) {
                             fs.writeFileSync(cacheFile, db.export());
                         }
                         catch (err) {
-                            if ((process.env.PHREN_DEBUG))
-                                process.stderr.write(`[phren] buildIndex incrementalCacheSave: ${errorMessage(err)}\n`);
+                            logger.debug("buildIndex incrementalCacheSave", errorMessage(err));
                         }
                         const incMs = Date.now() - t0;
                         debugLog(`Incremental FTS update: ${updatedCount} changed, ${missingFromIndex.length} removed in ${incMs}ms`);
@@ -1131,8 +1091,7 @@ async function buildIndexImpl(phrenPath, profile) {
                 newHashes[entry.fullPath] = hashFileContent(entry.fullPath);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] computePhrenHash skip: ${errorMessage(err)}\n`);
+                logger.debug("computePhrenHash skip", errorMessage(err));
             }
             if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
                 fileCount++;
@@ -1159,26 +1118,25 @@ async function buildIndexImpl(phrenPath, profile) {
                 fs.writeFileSync(graphPath, JSON.stringify({ entities: entityRows, links: linkRows, globalEntities: globalEntityRows, ts: Date.now() }));
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] buildIndex entityGraphPersist: ${errorMessage(err)}\n`);
+                logger.debug("buildIndex entityGraphPersist", errorMessage(err));
             }
         }
         // Always merge manual links (survive rebuild)
         mergeManualLinks(db, phrenPath);
         // ── Finalize: persist hashes, save cache, log ─────────────────────────────
-        saveHashMap(phrenPath, newHashes);
+        saveHashMap(phrenPath, newHashes, new Set(Object.keys(newHashes)));
         touchSentinel(phrenPath);
         invalidateDfCache();
         const buildMs = Date.now() - t0;
-        debugLog(`Built FTS index: ${fileCount} files from ${getProjectDirs(phrenPath, profile).length} projects in ${buildMs}ms`);
+        debugLog(`Built FTS index: ${fileCount} files from ${projectDirs.length} projects in ${buildMs}ms`);
         if ((process.env.PHREN_DEBUG))
-            console.error(`Indexed ${fileCount} files from ${getProjectDirs(phrenPath, profile).length} projects`);
+            console.error(`Indexed ${fileCount} files from ${projectDirs.length} projects`);
         appendIndexEvent(phrenPath, {
             event: "build_index",
             cache: "miss",
             hash: hash.slice(0, 12),
             files: fileCount,
-            projects: getProjectDirs(phrenPath, profile).length,
+            projects: projectDirs.length,
             elapsedMs: buildMs,
             profile: profile || "",
         });
@@ -1192,8 +1150,7 @@ async function buildIndexImpl(phrenPath, profile) {
                     fs.unlinkSync(path.join(cacheDir, f));
                 }
                 catch (err) {
-                    if ((process.env.PHREN_DEBUG))
-                        process.stderr.write(`[phren] buildIndex staleCacheCleanup: ${errorMessage(err)}\n`);
+                    logger.debug("buildIndex staleCacheCleanup", errorMessage(err));
                 }
             }
             debugLog(`Saved FTS index cache (${hash.slice(0, 8)}) — total ${Date.now() - t0}ms`);
@@ -1229,8 +1186,7 @@ function isRebuildLockHeld(phrenPath) {
         return Date.now() - stat.mtimeMs <= staleThreshold;
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] isRebuildLockHeld stat: ${errorMessage(err)}\n`);
+        logger.debug("isRebuildLockHeld stat", errorMessage(err));
         return false;
     }
 }
@@ -1241,8 +1197,7 @@ async function loadIndexSnapshotOrEmpty(phrenPath, profile) {
         userSuffix = String(os.userInfo().uid);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] loadIndexSnapshotOrEmpty userInfo: ${errorMessage(err)}\n`);
+        logger.debug("loadIndexSnapshotOrEmpty userInfo", errorMessage(err));
         userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
     }
     const cacheDir = path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
@@ -1257,7 +1212,27 @@ async function loadIndexSnapshotOrEmpty(phrenPath, profile) {
             debugLog(`Failed to open cached FTS snapshot while rebuild lock held: ${errorMessage(err)}`);
         }
     }
-    debugLog("FTS rebuild already in progress; returning empty snapshot");
+    // Before returning empty, try to load any stale-but-usable cache file
+    try {
+        if (fs.existsSync(cacheDir)) {
+            const cacheFiles = fs.readdirSync(cacheDir)
+                .filter(f => f.endsWith(".db"))
+                .map(f => ({ name: f, mtime: fs.statSync(path.join(cacheDir, f)).mtimeMs }))
+                .sort((a, b) => b.mtime - a.mtime);
+            for (const cf of cacheFiles) {
+                try {
+                    const staleDb = new SQL.Database(fs.readFileSync(path.join(cacheDir, cf.name)));
+                    debugLog(`FTS rebuild in progress; falling back to stale cache: ${cf.name}`);
+                    return staleDb;
+                }
+                catch { /* try next */ }
+            }
+        }
+    }
+    catch (err) {
+        debugLog(`Failed to scan stale FTS caches: ${errorMessage(err)}`);
+    }
+    debugLog("FTS rebuild already in progress; no usable cache found, returning empty snapshot");
     return createEmptyIndexDb(SQL);
 }
 // Serialize concurrent in-process buildIndex calls to prevent SQLite corruption
@@ -1342,8 +1317,7 @@ export function findFtsCacheForPath(phrenPath, profile) {
         userSuffix = String(os.userInfo().uid);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] findFtsCacheForPath userInfo: ${errorMessage(err)}\n`);
+        logger.debug("findFtsCacheForPath userInfo", errorMessage(err));
         userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
     }
     const cacheDir = path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
@@ -1357,8 +1331,7 @@ export function findFtsCacheForPath(phrenPath, profile) {
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] findFtsCacheForPath: ${errorMessage(err)}\n`);
+        logger.debug("findFtsCacheForPath", errorMessage(err));
     }
     return { exists: false };
 }