@phren/cli 0.0.1

package/mcp/dist/shared-index.js

@@ -0,0 +1,1334 @@
+import * as fs from "fs";
+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 { 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, queryDocRows, queryRows, } 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";
+// ── Async embedding queue ───────────────────────────────────────────────────
+const _embQueue = new Map();
+let _embTimer = null;
+function scheduleEmbedding(phrenPath, docPath, content) {
+    _embQueue.set(docPath, { phrenPath, content });
+    if (_embTimer)
+        clearTimeout(_embTimer);
+    _embTimer = setTimeout(() => { _embTimer = null; void _drainEmbQueue(); }, 500);
+    // Unref so the timer doesn't keep short-lived CLI processes alive
+    _embTimer.unref();
+}
+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 entries = [..._embQueue.entries()];
+    _embQueue.clear();
+    // Group by phrenPath so we flush each cache once after all its entries are set.
+    const byPhrenPath = new Map();
+    for (const [docPath, { phrenPath, content }] of entries) {
+        const bucket = byPhrenPath.get(phrenPath) ?? [];
+        bucket.push({ docPath, content });
+        byPhrenPath.set(phrenPath, bucket);
+    }
+    for (const [phrenPath, docs] of byPhrenPath) {
+        const cache = getEmbeddingCache(phrenPath);
+        try {
+            await cache.load();
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] embeddingQueue cacheLoad: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        const model = getEmbeddingModel();
+        for (const { docPath, content } of docs) {
+            try {
+                if (cache.get(docPath, model))
+                    continue;
+                const vec = await embedText(content);
+                if (vec)
+                    cache.set(docPath, getEmbeddingModel(), vec);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] embeddingQueue embedText: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        try {
+            await cache.flush();
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] embeddingQueue cacheFlush: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+}
+const FILE_TYPE_MAP = {
+    "claude.md": "claude",
+    "summary.md": "summary",
+    "findings.md": "findings",
+    "reference.md": "reference",
+    "tasks.md": "task",
+    "changelog.md": "changelog",
+    "canonical_memories.md": "canonical",
+    "memory_queue.md": "memory-queue",
+};
+function pathHasSegment(relPath, segment) {
+    const parts = relPath.replace(/\\/g, "/").split("/").filter(Boolean);
+    return parts.includes(segment);
+}
+export function classifyFile(filename, relPath) {
+    // Directory takes priority over filename-based classification
+    if (pathHasSegment(relPath, "reference"))
+        return "reference";
+    if (pathHasSegment(relPath, "skills"))
+        return "skill";
+    const mapped = FILE_TYPE_MAP[filename.toLowerCase()];
+    if (mapped)
+        return mapped;
+    return "other";
+}
+const IMPORT_RE = /^@import\s+(.+)$/gm;
+const MAX_IMPORT_DEPTH = 5;
+/**
+ * Internal recursive helper for resolveImports. Tracks `seen` (cycle detection) and `depth` (runaway
+ * recursion guard) — callers should never pass these; use the public `resolveImports` instead.
+ */
+function _resolveImportsRecursive(content, phrenPath, seen, depth) {
+    if (depth >= MAX_IMPORT_DEPTH)
+        return content;
+    return content.replace(IMPORT_RE, (_match, importPath) => {
+        const trimmed = importPath.trim();
+        const globalRoot = path.resolve(phrenPath, "global");
+        const resolved = path.join(globalRoot, trimmed);
+        // Use lexical resolution first for the prefix check
+        const lexical = path.resolve(resolved);
+        if (lexical !== globalRoot && !lexical.startsWith(globalRoot + path.sep)) {
+            return `<!-- @import blocked: path traversal -->`;
+        }
+        // Dereference symlinks before the prefix check to prevent symlink traversal attacks
+        // (e.g. global/evil -> /etc/passwd would pass the lexical check but fail here).
+        let normalized;
+        try {
+            normalized = fs.realpathSync.native(resolved);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] resolveImports realpath: ${err instanceof Error ? err.message : String(err)}\n`);
+            return `<!-- @import not found: ${trimmed} -->`;
+        }
+        let normalizedGlobalRoot = globalRoot;
+        try {
+            normalizedGlobalRoot = fs.realpathSync.native(globalRoot);
+        }
+        catch {
+            // Fall back to the lexical global path if the root cannot be resolved.
+        }
+        if (normalized !== normalizedGlobalRoot &&
+            !normalized.startsWith(normalizedGlobalRoot + path.sep)) {
+            return `<!-- @import blocked: symlink traversal -->`;
+        }
+        if (seen.has(normalized)) {
+            return `<!-- @import cycle: ${trimmed} -->`;
+        }
+        try {
+            const childSeen = new Set(seen);
+            childSeen.add(normalized);
+            const imported = fs.readFileSync(normalized, "utf-8");
+            return _resolveImportsRecursive(imported, phrenPath, childSeen, depth + 1);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] resolveImports fileRead: ${err instanceof Error ? err.message : String(err)}\n`);
+            return `<!-- @import error: ${trimmed} -->`;
+        }
+    });
+}
+/**
+ * Resolve `@import shared/file.md` directives in document content.
+ * 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.
+ */
+export function resolveImports(content, phrenPath) {
+    return _resolveImportsRecursive(content, phrenPath, new Set(), 0);
+}
+function touchSentinel(phrenPath) {
+    const dir = path.join(phrenPath, ".runtime");
+    const sentinelPath = path.join(dir, "phren-sentinel");
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(sentinelPath, Date.now().toString());
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] touchSentinel: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+function computePhrenHash(phrenPath, profile, preGlobbed) {
+    const policy = getIndexPolicy(phrenPath);
+    const hash = crypto.createHash("sha1");
+    const topicConfigEntries = getProjectDirs(phrenPath, profile)
+        .map((dir) => path.join(dir, "topic-config.json"))
+        .filter((configPath) => fs.existsSync(configPath));
+    if (preGlobbed) {
+        for (const f of preGlobbed) {
+            try {
+                const stat = fs.statSync(f);
+                hash.update(`${f}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] computePhrenHash skip: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        for (const configPath of topicConfigEntries) {
+            try {
+                const stat = fs.statSync(configPath);
+                hash.update(`topic-config:${configPath}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] computePhrenHash topicConfig: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+    }
+    else {
+        const projectDirs = getProjectDirs(phrenPath, profile);
+        const files = [];
+        for (const dir of projectDirs) {
+            const projectName = path.basename(dir);
+            const config = readProjectConfig(phrenPath, projectName);
+            const ownership = getProjectOwnershipMode(phrenPath, projectName, config);
+            try {
+                const matched = new Set();
+                for (const pattern of policy.includeGlobs) {
+                    const dot = policy.includeHidden || pattern.startsWith(".") || pattern.includes("/.");
+                    const mdFiles = globSync(pattern, { cwd: dir, nodir: true, dot, ignore: policy.excludeGlobs });
+                    for (const f of mdFiles)
+                        matched.add(f);
+                }
+                for (const f of matched) {
+                    if (ownership === "repo-managed" && path.basename(f).toLowerCase() === "claude.md")
+                        continue;
+                    files.push(path.join(dir, f));
+                }
+                if (ownership === "repo-managed") {
+                    for (const entry of getRepoManagedInstructionEntries(phrenPath, projectName)) {
+                        files.push(entry.fullPath);
+                    }
+                }
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] computePhrenHash globDir: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        files.sort();
+        for (const f of files) {
+            try {
+                const stat = fs.statSync(f);
+                hash.update(`${f}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] computePhrenHash skip: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        for (const configPath of topicConfigEntries) {
+            try {
+                const stat = fs.statSync(configPath);
+                hash.update(`topic-config:${configPath}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] computePhrenHash topicConfig: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+    }
+    for (const mem of collectNativeMemoryFiles()) {
+        try {
+            const stat = fs.statSync(mem.fullPath);
+            hash.update(`native:${mem.fullPath}:${stat.mtimeMs}:${stat.size}`);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] computePhrenHash skip: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    // Include global/ files (pulled via @import) so changes invalidate the cache
+    const globalDir = path.join(phrenPath, "global");
+    if (fs.existsSync(globalDir)) {
+        const globalFiles = globSync("**/*.md", { cwd: globalDir, nodir: true }).sort();
+        for (const f of globalFiles) {
+            try {
+                const fp = path.join(globalDir, f);
+                const stat = fs.statSync(fp);
+                hash.update(`global:${f}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] computePhrenHash skip: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+    }
+    // Include manual entity links so graph changes invalidate the cache
+    const manualLinksPath = runtimeFile(phrenPath, "manual-links.json");
+    if (fs.existsSync(manualLinksPath)) {
+        try {
+            const stat = fs.statSync(manualLinksPath);
+            hash.update(`manual-links:${stat.mtimeMs}:${stat.size}`);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] computePhrenHash skip: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    const indexPolicyPath = path.join(phrenPath, ".governance", "index-policy.json");
+    if (fs.existsSync(indexPolicyPath)) {
+        try {
+            const stat = fs.statSync(indexPolicyPath);
+            hash.update(`index-policy-file:${stat.mtimeMs}:${stat.size}`);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] computePhrenHash skip: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    if (profile)
+        hash.update(`profile:${profile}`);
+    hash.update(`index-policy:${JSON.stringify(policy)}`);
+    return hash.digest("hex").slice(0, 16);
+}
+const INDEX_HASHES_FILENAME = "index-hashes.json";
+const INDEX_SCHEMA_VERSION = 3; // bump when FTS schema changes to force full rebuild
+function hashFileContent(filePath) {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function loadHashMap(phrenPath) {
+    const runtimeDir = path.join(phrenPath, ".runtime");
+    const hashFile = path.join(runtimeDir, INDEX_HASHES_FILENAME);
+    try {
+        if (fs.existsSync(hashFile)) {
+            return JSON.parse(fs.readFileSync(hashFile, "utf-8"));
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] loadHashMap: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return { hashes: {} };
+}
+function saveHashMap(phrenPath, hashes) {
+    const runtimeDir = path.join(phrenPath, ".runtime");
+    try {
+        fs.mkdirSync(runtimeDir, { recursive: true });
+        const hashFile = path.join(runtimeDir, INDEX_HASHES_FILENAME);
+        withFileLock(hashFile, () => {
+            // Read-merge-write: load existing hashes, merge new values (new wins), then write.
+            // Prune entries for files that no longer exist to prevent ghost paths from causing
+            // repeated full rebuilds when deleted files are found in the hash map.
+            let existing = {};
+            try {
+                const data = JSON.parse(fs.readFileSync(hashFile, "utf-8"));
+                if (data.hashes && typeof data.hashes === "object")
+                    existing = data.hashes;
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] saveHashMap readExisting: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            const merged = { ...existing, ...hashes };
+            // Remove entries for paths that no longer exist on disk
+            for (const filePath of Object.keys(merged)) {
+                if (!fs.existsSync(filePath)) {
+                    delete merged[filePath];
+                }
+            }
+            fs.writeFileSync(hashFile, JSON.stringify({ version: INDEX_SCHEMA_VERSION, hashes: merged }, null, 2));
+        });
+    }
+    catch (err) {
+        debugLog(`Failed to save index hash map: ${errorMessage(err)}`);
+    }
+}
+const LEGACY_TOPIC_REFERENCE_RE = /^reference[\\/]+topics[\\/]+([a-z0-9_-]+)\.md$/i;
+function normalizeDocSegment(value) {
+    return value.replace(/\\/g, "/").replace(/^\/+/, "");
+}
+function getEntrySourceDocKey(entry, phrenPath) {
+    if (entry.relFile) {
+        return `${normalizeDocSegment(entry.project)}/${normalizeDocSegment(entry.relFile)}`;
+    }
+    return buildSourceDocKey(entry.project, entry.fullPath, phrenPath, entry.filename);
+}
+function getRepoManagedInstructionEntries(phrenPath, project) {
+    const repoDir = getProjectSourcePath(phrenPath, project);
+    if (!repoDir)
+        return [];
+    const candidates = ["CLAUDE.md", path.join(".claude", "CLAUDE.md")];
+    const entries = [];
+    for (const relFile of candidates) {
+        const fullPath = path.join(repoDir, relFile);
+        if (!fs.existsSync(fullPath))
+            continue;
+        const filename = path.basename(relFile);
+        entries.push({
+            fullPath,
+            project,
+            filename,
+            type: classifyFile(filename, relFile),
+            relFile,
+        });
+    }
+    return entries;
+}
+function globAllFiles(phrenPath, profile) {
+    const projectDirs = getProjectDirs(phrenPath, profile);
+    const indexPolicy = getIndexPolicy(phrenPath);
+    const entries = [];
+    const allAbsolutePaths = [];
+    for (const dir of projectDirs) {
+        const projectName = path.basename(dir);
+        const config = readProjectConfig(phrenPath, projectName);
+        const ownership = getProjectOwnershipMode(phrenPath, projectName, config);
+        const mdFilesSet = new Set();
+        for (const pattern of indexPolicy.includeGlobs) {
+            const dot = indexPolicy.includeHidden || pattern.startsWith(".") || pattern.includes("/.");
+            const matched = globSync(pattern, {
+                cwd: dir,
+                nodir: true,
+                dot,
+                ignore: indexPolicy.excludeGlobs,
+            });
+            for (const rel of matched)
+                mdFilesSet.add(rel);
+        }
+        const relFiles = [...mdFilesSet].sort();
+        for (const relFile of relFiles) {
+            const filename = path.basename(relFile);
+            if (ownership === "repo-managed" && filename.toLowerCase() === "claude.md")
+                continue;
+            const fullPath = path.join(dir, relFile);
+            const type = classifyFile(filename, relFile);
+            entries.push({ fullPath, project: projectName, filename, type, relFile });
+            allAbsolutePaths.push(fullPath);
+        }
+        if (ownership === "repo-managed") {
+            for (const entry of getRepoManagedInstructionEntries(phrenPath, projectName)) {
+                entries.push(entry);
+                allAbsolutePaths.push(entry.fullPath);
+            }
+        }
+    }
+    // Index global skills so search_knowledge can find them
+    const globalSkillsDir = path.join(phrenPath, "global", "skills");
+    if (fs.existsSync(globalSkillsDir)) {
+        const skillFiles = globSync("**/*.md", { cwd: globalSkillsDir, nodir: true });
+        for (const relFile of skillFiles) {
+            const fullPath = path.join(globalSkillsDir, relFile);
+            const filename = path.basename(relFile);
+            entries.push({ fullPath, project: "global", filename, type: "skill", relFile: `skills/${relFile}` });
+            allAbsolutePaths.push(fullPath);
+        }
+    }
+    for (const mem of collectNativeMemoryFiles()) {
+        entries.push({ fullPath: mem.fullPath, project: mem.project, filename: mem.file, type: "findings" });
+        allAbsolutePaths.push(mem.fullPath);
+    }
+    allAbsolutePaths.sort();
+    return { filePaths: allAbsolutePaths, entries };
+}
+export function listIndexedDocumentPaths(phrenPath, profile) {
+    return globAllFiles(phrenPath, profile).filePaths;
+}
+export function normalizeIndexedContent(content, type, phrenPath, maxChars) {
+    let normalized = content
+        .replace(/<!-- phren:archive:start -->[\s\S]*?<!-- phren:archive:end -->/g, "")
+        .replace(/<details>[\s\S]*?<\/details>/gi, "")
+        .replace(/<!--\s*created:\s*.*?-->/g, "")
+        .replace(/<!--\s*source:\s*.*?-->/g, "")
+        .replace(/<!--\s*phren:cite\s+\{[\s\S]*?\}\s*-->/g, "");
+    normalized = resolveImports(normalized, phrenPath);
+    if (type === "task") {
+        normalized = stripTaskDoneSection(normalized);
+    }
+    if (typeof maxChars === "number" && maxChars >= 0) {
+        normalized = normalized.slice(0, maxChars);
+    }
+    return normalized;
+}
+function insertFileIntoIndex(db, entry, phrenPath, opts) {
+    try {
+        const raw = fs.readFileSync(entry.fullPath, "utf-8");
+        const content = normalizeIndexedContent(raw, entry.type, phrenPath);
+        const indexedContent = applyReferenceTopicHints(entry, content, phrenPath);
+        db.run("INSERT INTO docs (project, filename, type, content, path) VALUES (?, ?, ?, ?, ?)", [entry.project, entry.filename, entry.type, indexedContent, entry.fullPath]);
+        if (opts?.scheduleEmbeddings) {
+            scheduleEmbedding(phrenPath, entry.fullPath, indexedContent.slice(0, 8000));
+        }
+        return true;
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] insertFileIntoIndex: ${err instanceof Error ? err.message : String(err)}\n`);
+        return false;
+    }
+}
+function normalizeTopicTokenSegment(raw) {
+    return raw.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function extractLegacyTopicSlug(entry) {
+    const rel = (entry.relFile || "").replace(/\\/g, "/");
+    const match = rel.match(LEGACY_TOPIC_REFERENCE_RE);
+    if (!match)
+        return null;
+    return match[1].toLowerCase();
+}
+function detectReferenceTopics(entry, content, phrenPath) {
+    if (entry.type !== "reference")
+        return [];
+    const { topics } = readProjectTopics(phrenPath, entry.project);
+    if (!topics.length)
+        return [];
+    const topicBySlug = new Map(topics.map((topic) => [topic.slug, topic]));
+    const lower = content.toLowerCase();
+    const matchedByContent = topics.filter((topic) => {
+        if (topic.slug === "general")
+            return false;
+        return topic.keywords.some((keyword) => keyword && lower.includes(keyword));
+    });
+    const selected = [];
+    const pushUnique = (topic) => {
+        if (!topic)
+            return;
+        if (selected.some((item) => item.slug === topic.slug))
+            return;
+        selected.push(topic);
+    };
+    // Backward compatibility: keep legacy topic docs pinned to their filename slug
+    // when that slug still exists in topic-config (or built-in topics).
+    const legacySlug = extractLegacyTopicSlug(entry);
+    if (legacySlug)
+        pushUnique(topicBySlug.get(legacySlug));
+    // Content-based topic tags for any reference doc shape (not only reference/topics/<slug>.md).
+    for (const topic of matchedByContent)
+        pushUnique(topic);
+    // Preserve previous behavior: always include at least one topic hint.
+    if (!selected.length) {
+        pushUnique(classifyTopicForText(content, topics));
+    }
+    return selected;
+}
+function applyReferenceTopicHints(entry, content, phrenPath) {
+    const topics = detectReferenceTopics(entry, content, phrenPath);
+    if (!topics.length)
+        return content;
+    const hintTokens = new Set();
+    for (const topic of topics) {
+        const slugToken = normalizeTopicTokenSegment(topic.slug) || "general";
+        hintTokens.add(`phrentopic${slugToken}`);
+        for (const keyword of topic.keywords) {
+            const keywordToken = normalizeTopicTokenSegment(keyword);
+            if (!keywordToken)
+                continue;
+            hintTokens.add(`phrentopickeyword${keywordToken}`);
+        }
+    }
+    return `${content}\n\n${Array.from(hintTokens).join(" ")}`.trimEnd();
+}
+function deleteEntityLinksForDocPath(db, phrenPath, docPath, fallbackProject, fallbackFilename) {
+    const docRows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE path = ? LIMIT 1", [docPath]);
+    const project = docRows?.[0]?.project ?? fallbackProject;
+    if (!project)
+        return;
+    const filename = docRows?.[0]?.filename ?? fallbackFilename;
+    const sourceDoc = buildSourceDocKey(project, docPath, phrenPath, filename);
+    db.run("DELETE FROM entity_links WHERE source_doc = ?", [sourceDoc]);
+    // Q19: also purge global_entities rows for this doc so cross_project_entities
+    // never returns deleted/stale documents.
+    try {
+        db.run("DELETE FROM global_entities WHERE doc_key = ?", [sourceDoc]);
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] deleteEntityLinksForDocPath globalEntities: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * Incrementally update a single file in the FTS index.
+ * Deletes the old record for the file, re-reads and re-inserts it.
+ * Touches the sentinel file to invalidate caches.
+ */
+export function updateFileInIndex(db, filePath, phrenPath) {
+    const resolvedPath = path.resolve(filePath);
+    // Delete old record
+    try {
+        deleteEntityLinksForDocPath(db, phrenPath, resolvedPath);
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] updateFileInIndex deleteEntityLinks: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    try {
+        db.run("DELETE FROM docs WHERE path = ?", [resolvedPath]);
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] updateFileInIndex deleteDocs: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    // Re-insert if file still exists
+    if (fs.existsSync(resolvedPath)) {
+        const filename = path.basename(resolvedPath);
+        // Determine project from path: the file should be under phrenPath/<project>/
+        const rel = path.relative(path.resolve(phrenPath), resolvedPath);
+        const project = rel.split(path.sep)[0];
+        const relFile = rel.split(path.sep).slice(1).join(path.sep);
+        const type = classifyFile(filename, relFile);
+        const entry = { fullPath: resolvedPath, project, filename, type, relFile };
+        if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
+            // Re-extract entities for finding files
+            if (type === "findings") {
+                try {
+                    const content = fs.readFileSync(resolvedPath, "utf-8");
+                    extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
+                }
+                catch (err) {
+                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        process.stderr.write(`[phren] updateFileInIndex entityExtraction: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+        }
+        // Update hash map for this file
+        try {
+            const hashData = loadHashMap(phrenPath);
+            hashData.hashes[resolvedPath] = hashFileContent(resolvedPath);
+            saveHashMap(phrenPath, hashData.hashes);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] updateFileInIndex hashMap: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    else {
+        // Remove stale embedding if file was deleted
+        void (async () => {
+            try {
+                const { getEmbeddingCache } = await import("./shared-embedding-cache.js");
+                const c = getEmbeddingCache(phrenPath);
+                c.delete(resolvedPath);
+                await c.flush();
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] updateFileInIndex embeddingDelete: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        })();
+    }
+    touchSentinel(phrenPath);
+    invalidateDfCache();
+}
+/** Read/write a sentinel that caches the phren hash to skip full recomputation. */
+function readHashSentinel(phrenPath) {
+    try {
+        const sentinelPath = runtimeFile(phrenPath, "index-sentinel.json");
+        if (!fs.existsSync(sentinelPath))
+            return null;
+        const data = JSON.parse(fs.readFileSync(sentinelPath, "utf-8"));
+        if (typeof data.hash === "string" && typeof data.computedAt === "number") {
+            return { hash: data.hash, computedAt: data.computedAt };
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] readHashSentinel: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return null;
+}
+function writeHashSentinel(phrenPath, hash) {
+    try {
+        const sentinelPath = runtimeFile(phrenPath, "index-sentinel.json");
+        fs.writeFileSync(sentinelPath, JSON.stringify({ hash, computedAt: Date.now() }));
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] writeHashSentinel: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+function isSentinelFresh(phrenPath, sentinel) {
+    // Check mtime of key directories — if any are newer than the sentinel, it's stale
+    const dirsToCheck = [
+        phrenPath,
+        path.join(phrenPath, ".governance"),
+        path.join(phrenPath, ".runtime"),
+    ];
+    for (const dir of dirsToCheck) {
+        try {
+            const stat = fs.statSync(dir);
+            if (stat.mtimeMs > sentinel.computedAt)
+                return false;
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] isSentinelFresh statDir: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    return true;
+}
+/**
+ * Attempt to restore the entity graph (entities, entity_links, global_entities) from a
+ * previously persisted JSON snapshot. Returns true if the graph was loaded, false if the
+ * caller must run full extraction instead.
+ */
+function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
+    if (!fs.existsSync(graphPath))
+        return false;
+    try {
+        const graph = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
+        const graphMtime = fs.statSync(graphPath).mtimeMs;
+        const anyNewer = allFiles.some(f => {
+            try {
+                return fs.statSync(f.fullPath).mtimeMs > graphMtime;
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] loadCachedEntityGraph statFile: ${err instanceof Error ? err.message : String(err)}\n`);
+                return true;
+            }
+        });
+        if (!anyNewer && graph.entities && graph.links) {
+            // Build set of valid source doc keys from current file set
+            const validDocKeys = new Set(allFiles.map(f => getEntrySourceDocKey(f, phrenPath)));
+            for (const [id, name, type] of graph.entities) {
+                db.run("INSERT OR IGNORE INTO entities (id, name, type, first_seen_at) VALUES (?, ?, ?, ?)", [id, name, type, new Date().toISOString().slice(0, 10)]);
+            }
+            for (const [sourceId, targetId, relType, sourceDoc] of graph.links) {
+                // Skip links for docs that no longer exist in the current file set
+                if (sourceDoc && !validDocKeys.has(sourceDoc))
+                    continue;
+                db.run("INSERT OR IGNORE INTO entity_links (source_id, target_id, rel_type, source_doc) VALUES (?, ?, ?, ?)", [sourceId, targetId, relType, sourceDoc]);
+            }
+            // Q19: also restore global_entities from cached graph so cross_project_entities
+            // is not empty after a cached-graph rebuild path.
+            if (Array.isArray(graph.globalEntities)) {
+                for (const [entity, project, docKey] of graph.globalEntities) {
+                    // Skip global entities whose source doc no longer exists
+                    if (docKey && !validDocKeys.has(docKey))
+                        continue;
+                    try {
+                        db.run("INSERT OR IGNORE INTO global_entities (entity, project, doc_key) VALUES (?, ?, ?)", [entity, project, docKey]);
+                    }
+                    catch (err) {
+                        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                            process.stderr.write(`[phren] loadCachedEntityGraph globalEntitiesInsert2: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+            }
+            else {
+                // Older cache without globalEntities: re-derive from entity_links + entities
+                try {
+                    const rows = db.exec(`SELECT e.name, el.source_doc FROM entity_links el
+             JOIN entities e ON el.target_id = e.id
+             WHERE el.source_doc IS NOT NULL`)[0]?.values ?? [];
+                    for (const [name, sourceDoc] of rows) {
+                        const projectMatch = typeof sourceDoc === "string" ? sourceDoc.match(/^([^/]+)\//) : null;
+                        const proj = projectMatch ? projectMatch[1] : null;
+                        if (proj && name) {
+                            try {
+                                db.run("INSERT OR IGNORE INTO global_entities (entity, project, doc_key) VALUES (?, ?, ?)", [name, proj, sourceDoc]);
+                            }
+                            catch (err) {
+                                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                    process.stderr.write(`[phren] loadCachedEntityGraph globalEntitiesInsert: ${err instanceof Error ? err.message : String(err)}\n`);
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        process.stderr.write(`[phren] entityGraph globalEntitiesRestore: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            return true;
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] entityGraph cacheLoad: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return false;
+}
+/** Merge manual entity links (written by link_findings tool) into the live DB. Always runs on
+ * every build so hand-authored links survive a full index rebuild. */
+function mergeManualLinks(db, phrenPath) {
+    const manualLinksPath = runtimeFile(phrenPath, 'manual-links.json');
+    if (!fs.existsSync(manualLinksPath))
+        return;
+    try {
+        const manualLinks = JSON.parse(fs.readFileSync(manualLinksPath, 'utf8'));
+        let pruned = false;
+        const validLinks = [];
+        for (const link of manualLinks) {
+            try {
+                // Validate: skip manual links whose sourceDoc no longer exists in the index
+                const docCheck = queryRows(db, "SELECT 1 FROM docs WHERE source_key = ? LIMIT 1", [link.sourceDoc]);
+                if (!docCheck || docCheck.length === 0) {
+                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        process.stderr.write(`[phren] manualLinks: pruning stale link to "${link.sourceDoc}"\n`);
+                    pruned = true;
+                    continue;
+                }
+                validLinks.push(link);
+                db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [link.entity, link.entityType, new Date().toISOString().slice(0, 10)]);
+                db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [link.sourceDoc, "document", new Date().toISOString().slice(0, 10)]);
+                const eRes = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [link.entity, link.entityType]);
+                const dRes = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [link.sourceDoc, "document"]);
+                const eId = eRes?.[0]?.values?.[0]?.[0];
+                const dId = dRes?.[0]?.values?.[0]?.[0];
+                if (eId != null && dId != null) {
+                    db.run("INSERT OR IGNORE INTO entity_links (source_id, target_id, rel_type, source_doc) VALUES (?, ?, ?, ?)", [dId, eId, link.relType, link.sourceDoc]);
+                }
+                // Also populate global_entities so manual links are discoverable via cross_project_entities
+                const projectMatch = link.sourceDoc.match(/^([^/]+)\//);
+                if (projectMatch) {
+                    try {
+                        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.env.PHREN_DEBUG))
+                            process.stderr.write(`[phren] manualLinks globalEntities: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] manualLinks entry: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        // Rewrite manual-links.json if stale entries were pruned
+        if (pruned) {
+            try {
+                withFileLock(manualLinksPath, () => {
+                    const tmpPath = manualLinksPath + `.tmp-${crypto.randomUUID()}`;
+                    fs.writeFileSync(tmpPath, JSON.stringify(validLinks, null, 2));
+                    fs.renameSync(tmpPath, manualLinksPath);
+                });
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] manualLinks prune write: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] mergeManualLinks: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+async function buildIndexImpl(phrenPath, profile) {
+    const t0 = Date.now();
+    beginUserFragmentBuildCache(phrenPath, getProjectDirs(phrenPath, profile).map(dir => path.basename(dir)));
+    try {
+        // ── Cache dir + hash sentinel ─────────────────────────────────────────────
+        let userSuffix;
+        try {
+            userSuffix = String(os.userInfo().uid);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] buildIndexImpl userInfo: ${err instanceof Error ? err.message : String(err)}\n`);
+            userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
+        }
+        const cacheDir = path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
+        // Fast path: if the sentinel is fresh, skip the expensive glob + hash computation
+        const sentinel = readHashSentinel(phrenPath);
+        let hash;
+        let globResult;
+        if (sentinel && isSentinelFresh(phrenPath, sentinel)) {
+            hash = sentinel.hash;
+            const cacheFile = path.join(cacheDir, `${hash}.db`);
+            if (fs.existsSync(cacheFile)) {
+                // Sentinel cache hit — defer full glob until we actually need it
+                globResult = globAllFiles(phrenPath, profile);
+            }
+            else {
+                // Cache file was cleaned up, fall through to full computation
+                globResult = globAllFiles(phrenPath, profile);
+                hash = computePhrenHash(phrenPath, profile, globResult.filePaths);
+                writeHashSentinel(phrenPath, hash);
+            }
+        }
+        else {
+            globResult = globAllFiles(phrenPath, profile);
+            hash = computePhrenHash(phrenPath, profile, globResult.filePaths);
+            writeHashSentinel(phrenPath, hash);
+        }
+        const cacheFile = path.join(cacheDir, `${hash}.db`);
+        const SQL = await bootstrapSqlJs();
+        // ── Incremental update (cache hit path) ───────────────────────────────────
+        // Load saved per-file hashes for incremental updates
+        const savedHashData = loadHashMap(phrenPath);
+        const savedHashes = savedHashData.hashes;
+        const schemaChanged = savedHashData.version !== INDEX_SCHEMA_VERSION;
+        // Try loading cached DB for incremental update
+        if (!schemaChanged && fs.existsSync(cacheFile)) {
+            try {
+                const cached = fs.readFileSync(cacheFile);
+                let db;
+                let shouldCloseDb = true;
+                try {
+                    db = new SQL.Database(cached);
+                    // If OS cleaned /tmp and the file was recreated as empty, the DB will have
+                    // 0 docs even though savedHashes has full content. Treat as cache miss so
+                    // the stale hash map doesn't drive an incremental update against an empty DB.
+                    const docCountResult = db.exec("SELECT COUNT(*) FROM docs");
+                    const docCount = docCountResult?.[0]?.values?.[0]?.[0] ?? 0;
+                    if (docCount === 0 && globResult.entries.length > 0) {
+                        throw new Error("cached DB is empty, forcing full rebuild");
+                    }
+                    // Schema migration: add first_seen_at column if missing
+                    try {
+                        db.run("ALTER TABLE entities ADD COLUMN first_seen_at TEXT");
+                    }
+                    catch { /* column already exists — expected */ }
+                    // Compute current file hashes and determine what changed
+                    const allFiles = globResult.entries;
+                    const currentHashes = {};
+                    const changedFiles = [];
+                    const newFiles = [];
+                    for (const entry of allFiles) {
+                        try {
+                            const fileHash = hashFileContent(entry.fullPath);
+                            currentHashes[entry.fullPath] = fileHash;
+                            if (!(entry.fullPath in savedHashes)) {
+                                newFiles.push(entry);
+                            }
+                            else if (savedHashes[entry.fullPath] !== fileHash) {
+                                changedFiles.push(entry);
+                            }
+                        }
+                        catch (err) {
+                            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                process.stderr.write(`[phren] buildIndex hashFile: ${err instanceof Error ? err.message : String(err)}\n`);
+                        }
+                    }
+                    // Check for files missing from the index (deleted files)
+                    const currentPaths = new Set(Object.keys(currentHashes));
+                    const missingFromIndex = Object.keys(savedHashes).filter(p => !currentPaths.has(p));
+                    // Force full rebuild if >20% of saved files are missing
+                    const totalSaved = Object.keys(savedHashes).length;
+                    if (totalSaved > 0 && missingFromIndex.length / totalSaved > 0.2) {
+                        debugLog(`>20% files missing (${missingFromIndex.length}/${totalSaved}), forcing full rebuild`);
+                        // Fall through to full rebuild below
+                    }
+                    else if (changedFiles.length === 0 && newFiles.length === 0 && missingFromIndex.length === 0) {
+                        // Nothing changed, pure cache hit
+                        debugLog(`Loaded FTS index from cache (${hash.slice(0, 8)}) in ${Date.now() - t0}ms`);
+                        appendIndexEvent(phrenPath, {
+                            event: "build_index",
+                            cache: "hit",
+                            hash: hash.slice(0, 12),
+                            elapsedMs: Date.now() - t0,
+                            profile: profile || "",
+                        });
+                        shouldCloseDb = false;
+                        return db;
+                    }
+                    else {
+                        // Incremental update: apply each file change atomically to avoid losing docs on crash.
+                        const changedPaths = new Set(changedFiles.map(entry => entry.fullPath));
+                        db.run("BEGIN");
+                        try {
+                            for (const missingPath of missingFromIndex) {
+                                try {
+                                    deleteEntityLinksForDocPath(db, phrenPath, missingPath);
+                                }
+                                catch (err) {
+                                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                        process.stderr.write(`[phren] buildIndex deleteEntityLinksForMissing: ${err instanceof Error ? err.message : String(err)}\n`);
+                                }
+                                try {
+                                    db.run("DELETE FROM docs WHERE path = ?", [missingPath]);
+                                }
+                                catch (err) {
+                                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                        process.stderr.write(`[phren] buildIndex deleteDocForMissing: ${err instanceof Error ? err.message : String(err)}\n`);
+                                }
+                            }
+                            db.run("COMMIT");
+                        }
+                        catch (err) {
+                            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                process.stderr.write(`[phren] buildIndex incrementalDeleteCommit: ${err instanceof Error ? err.message : String(err)}\n`);
+                            try {
+                                db.run("ROLLBACK");
+                            }
+                            catch (e2) {
+                                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                    process.stderr.write(`[phren] buildIndex incrementalDeleteRollback: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+                            }
+                        }
+                        let updatedCount = 0;
+                        for (const entry of [...changedFiles, ...newFiles]) {
+                            db.run("BEGIN");
+                            try {
+                                if (changedPaths.has(entry.fullPath)) {
+                                    const sourceDocKey = getEntrySourceDocKey(entry, phrenPath);
+                                    db.run("DELETE FROM entity_links WHERE source_doc = ?", [sourceDocKey]);
+                                    // Q19: keep global_entities in sync with entity_links on updates
+                                    try {
+                                        db.run("DELETE FROM global_entities WHERE doc_key = ?", [sourceDocKey]);
+                                    }
+                                    catch { /* table may not exist in older cached DBs */ }
+                                    db.run("DELETE FROM docs WHERE path = ?", [entry.fullPath]);
+                                }
+                                if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
+                                    updatedCount++;
+                                    if (entry.type === "findings") {
+                                        try {
+                                            const content = fs.readFileSync(entry.fullPath, "utf-8");
+                                            extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
+                                        }
+                                        catch (err) {
+                                            debugLog(`entity extraction failed: ${errorMessage(err)}`);
+                                        }
+                                    }
+                                }
+                                db.run("COMMIT");
+                            }
+                            catch (err) {
+                                try {
+                                    db.run("ROLLBACK");
+                                }
+                                catch (e2) {
+                                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                        process.stderr.write(`[phren] buildIndex perFileRollback: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+                                }
+                                throw err;
+                            }
+                        }
+                        saveHashMap(phrenPath, currentHashes);
+                        touchSentinel(phrenPath);
+                        invalidateDfCache();
+                        // Save updated cache
+                        try {
+                            fs.mkdirSync(cacheDir, { recursive: true });
+                            fs.writeFileSync(cacheFile, db.export());
+                        }
+                        catch (err) {
+                            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                process.stderr.write(`[phren] buildIndex incrementalCacheSave: ${err instanceof Error ? err.message : String(err)}\n`);
+                        }
+                        const incMs = Date.now() - t0;
+                        debugLog(`Incremental FTS update: ${updatedCount} changed, ${missingFromIndex.length} removed in ${incMs}ms`);
+                        appendIndexEvent(phrenPath, {
+                            event: "build_index",
+                            cache: "incremental",
+                            hash: hash.slice(0, 12),
+                            files: updatedCount,
+                            removed: missingFromIndex.length,
+                            elapsedMs: incMs,
+                            profile: profile || "",
+                        });
+                        shouldCloseDb = false;
+                        return db;
+                    }
+                }
+                finally {
+                    if (shouldCloseDb) {
+                        db?.close();
+                    }
+                }
+            }
+            catch (err) {
+                debugLog(`Cache load failed, rebuilding index: ${errorMessage(err)}`);
+            }
+        }
+        // ── Full rebuild ──────────────────────────────────────────────────────────
+        const db = new SQL.Database();
+        db.run(`
+    CREATE VIRTUAL TABLE docs USING fts5(
+      project, filename, type, content, path,
+      tokenize = "porter unicode61"
+    );
+  `);
+        // Entity graph tables for lightweight reference graph
+        db.run(`CREATE TABLE IF NOT EXISTS entities (id INTEGER PRIMARY KEY, name TEXT NOT NULL, type TEXT NOT NULL, first_seen_at TEXT, UNIQUE(name, type))`);
+        db.run(`CREATE TABLE IF NOT EXISTS entity_links (source_id INTEGER REFERENCES entities(id), target_id INTEGER REFERENCES entities(id), rel_type TEXT NOT NULL, source_doc TEXT, PRIMARY KEY (source_id, target_id, rel_type))`);
+        // Q20: Cross-project entity index
+        ensureGlobalEntitiesTable(db);
+        const allFiles = globResult.entries;
+        const newHashes = {};
+        let fileCount = 0;
+        // Try loading cached entity graph
+        const graphPath = runtimeFile(phrenPath, 'entity-graph.json');
+        const entityGraphLoaded = loadCachedEntityGraph(db, graphPath, allFiles, phrenPath);
+        for (const entry of allFiles) {
+            try {
+                newHashes[entry.fullPath] = hashFileContent(entry.fullPath);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] computePhrenHash skip: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
+                fileCount++;
+                // Extract entities from finding files (if not loaded from cache)
+                if (!entityGraphLoaded && entry.type === "findings") {
+                    try {
+                        const content = fs.readFileSync(entry.fullPath, "utf-8");
+                        extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
+                    }
+                    catch (err) {
+                        debugLog(`entity extraction failed: ${errorMessage(err)}`);
+                    }
+                }
+            }
+        }
+        // Persist entity graph for next build
+        if (!entityGraphLoaded) {
+            try {
+                const entityRows = db.exec("SELECT id, name, type FROM entities")[0]?.values ?? [];
+                const linkRows = db.exec("SELECT source_id, target_id, rel_type, source_doc FROM entity_links")[0]?.values ?? [];
+                // Q19: also persist global_entities so the cached-graph rebuild path can
+                // restore it without re-running extraction on every file.
+                const globalEntityRows = db.exec("SELECT entity, project, doc_key FROM global_entities")[0]?.values ?? [];
+                fs.writeFileSync(graphPath, JSON.stringify({ entities: entityRows, links: linkRows, globalEntities: globalEntityRows, ts: Date.now() }));
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] buildIndex entityGraphPersist: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        // Always merge manual links (survive rebuild)
+        mergeManualLinks(db, phrenPath);
+        // ── Finalize: persist hashes, save cache, log ─────────────────────────────
+        saveHashMap(phrenPath, newHashes);
+        touchSentinel(phrenPath);
+        invalidateDfCache();
+        const buildMs = Date.now() - t0;
+        debugLog(`Built FTS index: ${fileCount} files from ${getProjectDirs(phrenPath, profile).length} projects in ${buildMs}ms`);
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            console.error(`Indexed ${fileCount} files from ${getProjectDirs(phrenPath, profile).length} projects`);
+        appendIndexEvent(phrenPath, {
+            event: "build_index",
+            cache: "miss",
+            hash: hash.slice(0, 12),
+            files: fileCount,
+            projects: getProjectDirs(phrenPath, profile).length,
+            elapsedMs: buildMs,
+            profile: profile || "",
+        });
+        try {
+            fs.mkdirSync(cacheDir, { recursive: true });
+            fs.writeFileSync(cacheFile, db.export());
+            for (const f of fs.readdirSync(cacheDir)) {
+                if (!f.endsWith(".db") || f === `${hash}.db`)
+                    continue;
+                try {
+                    fs.unlinkSync(path.join(cacheDir, f));
+                }
+                catch (err) {
+                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        process.stderr.write(`[phren] buildIndex staleCacheCleanup: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            debugLog(`Saved FTS index cache (${hash.slice(0, 8)}) — total ${Date.now() - t0}ms`);
+        }
+        catch (err) {
+            debugLog(`Failed to save FTS index cache: ${errorMessage(err)}`);
+        }
+        return db;
+    }
+    finally {
+        endUserFragmentBuildCache(phrenPath);
+    }
+}
+function createEmptyIndexDb(SQL) {
+    const db = new SQL.Database();
+    db.run(`
+    CREATE VIRTUAL TABLE docs USING fts5(
+      project, filename, type, content, path,
+      tokenize = "porter unicode61"
+    );
+  `);
+    db.run(`CREATE TABLE IF NOT EXISTS entities (id INTEGER PRIMARY KEY, name TEXT NOT NULL, type TEXT NOT NULL, first_seen_at TEXT, UNIQUE(name, type))`);
+    db.run(`CREATE TABLE IF NOT EXISTS entity_links (source_id INTEGER REFERENCES entities(id), target_id INTEGER REFERENCES entities(id), rel_type TEXT NOT NULL, source_doc TEXT, PRIMARY KEY (source_id, target_id, rel_type))`);
+    ensureGlobalEntitiesTable(db);
+    return db;
+}
+function isRebuildLockHeld(phrenPath) {
+    const lockTarget = runtimeFile(phrenPath, "index-rebuild");
+    const lockPath = lockTarget + ".lock";
+    try {
+        const stat = fs.statSync(lockPath);
+        const staleThreshold = Number.parseInt((process.env.PHREN_FILE_LOCK_STALE_MS) || "30000", 10) || 30000;
+        return Date.now() - stat.mtimeMs <= staleThreshold;
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] isRebuildLockHeld stat: ${err instanceof Error ? err.message : String(err)}\n`);
+        return false;
+    }
+}
+async function loadIndexSnapshotOrEmpty(phrenPath, profile) {
+    const SQL = await bootstrapSqlJs();
+    let userSuffix;
+    try {
+        userSuffix = String(os.userInfo().uid);
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] loadIndexSnapshotOrEmpty userInfo: ${err instanceof Error ? err.message : String(err)}\n`);
+        userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
+    }
+    const cacheDir = path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
+    const globResult = globAllFiles(phrenPath, profile);
+    const hash = computePhrenHash(phrenPath, profile, globResult.filePaths);
+    const cacheFile = path.join(cacheDir, `${hash}.db`);
+    if (fs.existsSync(cacheFile)) {
+        try {
+            return new SQL.Database(fs.readFileSync(cacheFile));
+        }
+        catch (err) {
+            debugLog(`Failed to open cached FTS snapshot while rebuild lock held: ${errorMessage(err)}`);
+        }
+    }
+    debugLog("FTS rebuild already in progress; returning empty snapshot");
+    return createEmptyIndexDb(SQL);
+}
+// Serialize concurrent in-process buildIndex calls to prevent SQLite corruption
+let buildLock = Promise.resolve(null);
+// Staleness debounce: if the index was rebuilt within this window, return the
+// cached DB immediately without re-running the expensive glob + hash pipeline.
+// Configurable via PHREN_INDEX_DEBOUNCE_MS (default 5000ms).
+const INDEX_DEBOUNCE_DEFAULT_MS = 5000;
+let _lastBuiltDb = null;
+let _lastBuildTimestamp = 0;
+let _lastBuildKey = "";
+function getIndexDebounceMs() {
+    const raw = (process.env.PHREN_INDEX_DEBOUNCE_MS);
+    if (!raw)
+        return INDEX_DEBOUNCE_DEFAULT_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isNaN(parsed) || parsed < 0)
+        return INDEX_DEBOUNCE_DEFAULT_MS;
+    return Math.min(parsed, 60000);
+}
+function isDbOpen(db) {
+    try {
+        db.exec("SELECT 1");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function buildIndex(phrenPath, profile) {
+    const debounceMs = getIndexDebounceMs();
+    const buildKey = `${phrenPath}|${profile ?? ""}`;
+    if (debounceMs > 0 &&
+        _lastBuiltDb !== null &&
+        _lastBuildKey === buildKey &&
+        Date.now() - _lastBuildTimestamp < debounceMs &&
+        isDbOpen(_lastBuiltDb)) {
+        debugLog(`buildIndex debounce hit (${Date.now() - _lastBuildTimestamp}ms < ${debounceMs}ms)`);
+        return _lastBuiltDb;
+    }
+    const result = buildLock.then(() => _buildIndexGuarded(phrenPath, profile));
+    // Update the lock chain; swallow rejections so the chain doesn't stall
+    buildLock = result.catch(() => null);
+    const db = await result;
+    _lastBuiltDb = db;
+    _lastBuildTimestamp = Date.now();
+    _lastBuildKey = buildKey;
+    return db;
+}
+async function _buildIndexGuarded(phrenPath, profile) {
+    const lockTarget = runtimeFile(phrenPath, "index-rebuild");
+    if (isRebuildLockHeld(phrenPath)) {
+        return loadIndexSnapshotOrEmpty(phrenPath, profile);
+    }
+    try {
+        return await withFileLock(lockTarget, async () => {
+            let timer;
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("buildIndex timed out after 30s")), 30000);
+            });
+            try {
+                return await Promise.race([buildIndexImpl(phrenPath, profile), timeout]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        });
+    }
+    catch (err) {
+        const message = errorMessage(err);
+        if (message.includes("could not acquire lock")) {
+            debugLog(`FTS rebuild skipped because another process holds the rebuild lock: ${message}`);
+            return loadIndexSnapshotOrEmpty(phrenPath, profile);
+        }
+        throw err;
+    }
+}
+/** Find the FTS cache file for a specific phrenPath+profile. Returns exists + size. */
+export function findFtsCacheForPath(phrenPath, profile) {
+    let userSuffix;
+    try {
+        userSuffix = String(os.userInfo().uid);
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] findFtsCacheForPath userInfo: ${err instanceof Error ? err.message : String(err)}\n`);
+        userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
+    }
+    const cacheDir = path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
+    try {
+        const globResult = globAllFiles(phrenPath, profile);
+        const hash = computePhrenHash(phrenPath, profile, globResult.filePaths);
+        const cacheFile = path.join(cacheDir, `${hash}.db`);
+        if (fs.existsSync(cacheFile)) {
+            const stat = fs.statSync(cacheFile);
+            return { exists: true, sizeBytes: stat.size };
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] findFtsCacheForPath: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return { exists: false };
+}
+export function detectProject(phrenPath, cwd, profile) {
+    const manifest = readRootManifest(phrenPath);
+    if (manifest?.installMode === "project-local") {
+        return manifest.primaryProject || null;
+    }
+    const projectDirs = getProjectDirs(phrenPath, profile);
+    const resolvedCwd = path.resolve(cwd);
+    let bestMatch = null;
+    for (const dir of projectDirs) {
+        const projectName = path.basename(dir);
+        const sourcePath = getProjectSourcePath(phrenPath, projectName);
+        if (!sourcePath)
+            continue;
+        const matches = resolvedCwd === sourcePath || resolvedCwd.startsWith(sourcePath + path.sep);
+        if (!matches)
+            continue;
+        if (!bestMatch || sourcePath.length > bestMatch.length) {
+            bestMatch = { project: projectName, length: sourcePath.length };
+        }
+    }
+    return bestMatch?.project || null;
+}