@monoes/monograph 1.3.0 → 1.4.1

package/src/pipeline/phases/cross-file.ts

@@ -1,53 +1,101 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
 import type { PipelinePhase } from '../types.js';
 import type { MonographEdge } from '../../types.js';
 import { makeId, CONFIDENCE_SCORE } from '../../types.js';
 import { insertEdges } from '../../storage/edge-store.js';
 import type { ParseOutput } from './parse.js';
 import type { StructureOutput } from './structure.js';
+import { resolveModuleSpecifier, buildWorkspacePackageMap } from './scope-resolution.js';
 
 export interface CrossFileOutput {
   resolvedEdges: MonographEdge[];
 }
 
+// Mirrors parsers/extractor.ts's re-export detection regex — used here to recover
+// the ORIGINAL specifier string behind a RE_EXPORTS edge's mangled placeholder id
+// (makeId('import', specifier) is lossy: '/' and '.' are collapsed to '_', so the
+// placeholder can't be reversed directly — we re-derive it from source instead).
+const RE_EXPORT_RE = /export\s+(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/g;
+
 // monolean: IMPORTS name-matching removed — it matched import names against a
 // global symbol index (e.g. `import fs` → random Variable named `fs` in wrong file).
 // scope-resolution.ts now handles cross-file CALLS via source-parsed import maps.
 export const crossFilePhase: PipelinePhase<CrossFileOutput> = {
   name: 'cross-file',
   deps: ['parse', 'structure'],
-  async execute(_ctx, deps) {
+  async execute(ctx, deps) {
     const { allEdges } = deps.get('parse') as ParseOutput;
     const { fileNodes } = deps.get('structure') as StructureOutput;
 
-    function lastSegment(s: string): string {
-      const idx = s.lastIndexOf('/');
-      return idx === -1 ? s : s.slice(idx + 1);
-    }
+    const reExportEdges = allEdges.filter((e) => e.relation === 'RE_EXPORTS');
+    const resolvedEdges: MonographEdge[] = [];
 
-    function targetBasename(rawId: string): string {
-      const stripped = rawId.startsWith('import_') ? rawId.slice(7) : rawId;
-      return lastSegment(stripped);
-    }
+    if (reExportEdges.length > 0) {
+      // fileId <-> filePath maps for resolving edge endpoints to real file nodes.
+      const fileIdToPath = new Map<string, string>();
+      const knownFiles = new Set<string>();
+      for (const fileNode of fileNodes) {
+        if (fileNode.filePath) {
+          fileIdToPath.set(fileNode.id, fileNode.filePath);
+          knownFiles.add(fileNode.filePath);
+        }
+      }
+      const filePathToId = new Map<string, string>();
+      for (const [id, path] of fileIdToPath) filePathToId.set(path, id);
 
-    const fileBasenameIndex = new Map<string, string>();
-    for (const fileNode of fileNodes) {
-      const basename = lastSegment(fileNode.filePath ?? '').toLowerCase();
-      const dotIdx = basename.lastIndexOf('.');
-      const noExt = dotIdx === -1 ? basename : basename.slice(0, dotIdx);
-      fileBasenameIndex.set(basename, fileNode.id);
-      if (noExt !== basename) fileBasenameIndex.set(noExt, fileNode.id);
-    }
+      const workspaceMap = buildWorkspacePackageMap(ctx.repoPath);
 
-    const resolvedEdges: MonographEdge[] = [];
+      // Group by importing file so each source file is read at most once.
+      const edgesBySource = new Map<string, MonographEdge[]>();
+      for (const edge of reExportEdges) {
+        const arr = edgesBySource.get(edge.sourceId);
+        if (arr) arr.push(edge);
+        else edgesBySource.set(edge.sourceId, [edge]);
+      }
+
+      for (const [sourceId, edges] of edgesBySource) {
+        const filePath = fileIdToPath.get(sourceId);
+        if (!filePath) continue;
+
+        let source: string;
+        try {
+          source = readFileSync(join(ctx.repoPath, filePath), 'utf-8');
+        } catch {
+          continue;
+        }
+
+        // Recover each `export * / { ... } from '<specifier>'` string, keyed by the
+        // same mangled placeholder id the extractor used (makeId('import', specifier))
+        // so it can be matched back to the corresponding edge.
+        const specifierByPlaceholder = new Map<string, string>();
+        RE_EXPORT_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = RE_EXPORT_RE.exec(source)) !== null) {
+          const specifier = m[1]!;
+          specifierByPlaceholder.set(makeId('import', specifier), specifier);
+        }
+
+        for (const edge of edges) {
+          const specifier = specifierByPlaceholder.get(edge.targetId);
+          if (!specifier) continue;
+
+          // Resolve relative to THIS importing file's own directory (reusing the
+          // same resolver scope-resolution.ts uses for IMPORTS) instead of an
+          // ambiguous global basename lookup that collides on repeated basenames
+          // like index.ts / utils.ts across the repo.
+          const resolvedPath = resolveModuleSpecifier(
+            filePath,
+            specifier,
+            ctx.repoPath,
+            knownFiles,
+            workspaceMap,
+          );
+          if (!resolvedPath) continue;
 
-    for (const edge of allEdges) {
-      if (edge.relation === 'RE_EXPORTS') {
-        const basename = targetBasename(edge.targetId).toLowerCase();
-        const dotIdx = basename.lastIndexOf('.');
-        const noExt = dotIdx === -1 ? basename : basename.slice(0, dotIdx);
-        const resolvedId = fileBasenameIndex.get(basename) ?? fileBasenameIndex.get(noExt);
+          const resolvedId = filePathToId.get(resolvedPath);
+          if (!resolvedId || resolvedId === edge.targetId) continue;
 
-        if (resolvedId && resolvedId !== edge.targetId) {
           resolvedEdges.push({
             ...edge,
             id: makeId(edge.sourceId, resolvedId, 'reexports_resolved'),
@@ -59,8 +107,8 @@ export const crossFilePhase: PipelinePhase<CrossFileOutput> = {
       }
     }
 
-    if (_ctx.db && resolvedEdges.length > 0) {
-      insertEdges(_ctx.db, resolvedEdges);
+    if (ctx.db && resolvedEdges.length > 0) {
+      insertEdges(ctx.db, resolvedEdges);
     }
 
     return { resolvedEdges };

package/src/pipeline/phases/parse.ts

@@ -3,8 +3,8 @@ import { extname, join } from 'path';
 import type { PipelinePhase, PipelineContext } from '../types.js';
 import type { MonographNode, MonographEdge } from '../../types.js';
 import { parseFile } from '../../parsers/loader.js';
-import { insertNodes } from '../../storage/node-store.js';
-import { insertEdges } from '../../storage/edge-store.js';
+import { insertNodes, deleteNodesForFile } from '../../storage/node-store.js';
+import { insertEdges, deleteEdgesForFile } from '../../storage/edge-store.js';
 import type { StructureOutput } from './structure.js';
 import { extractVariables, variableToNode } from './variables.js';
 import { ExtractionCache } from '../../cache/extraction-cache.js';
@@ -24,8 +24,18 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
     const { fileNodes } = deps.get('structure') as StructureOutput;
     const symbolNodes: MonographNode[] = [];
     const allEdges: MonographEdge[] = [];
-    const freshNodes: MonographNode[] = [];
-    const freshEdges: MonographEdge[] = [];
+    // freshNodes/freshEdges (the cache-miss-only subset) are NOT accumulated in a
+    // parallel array during the loop — that duplicated every fresh node/edge object
+    // in memory for the entire pipeline run. Instead we record the [start, end)
+    // slice of symbolNodes/allEdges that each cache-miss file contributed, and
+    // materialize the fresh subset via a single slice pass at the end, only when
+    // it's actually needed (cacheHits > 0). On a cold build (cacheHits === 0) the
+    // fresh subset is never materialized at all, since nodesToInsert falls back to
+    // symbolNodes/allEdges directly in that case — eliminating the redundant
+    // allocation entirely for the memory-heaviest scenario.
+    const freshNodeRanges: Array<[number, number]> = [];
+    const freshEdgeRanges: Array<[number, number]> = [];
+    const staleFilePaths: string[] = [];
     const parseErrors: string[] = [];
     const fileContents = new Map<string, string>();
     let processed = 0;
@@ -39,8 +49,10 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
       const ext = extname(absPath).toLowerCase();
       if (ext === '.md' || ext === '.markdown') { processed++; continue; }
 
-      // Fast path: mtime+size check avoids reading file content entirely
-      const cached = cache.getWithStat(absPath);
+      // Fast path: mtime+size check avoids reading file content entirely.
+      // Skipped entirely under --force so a force rebuild is a genuine from-scratch
+      // parse, not a replay of whatever extraction the cache happens to hold.
+      const cached = ctx.options.force ? null : cache.getWithStat(absPath);
       if (cached) {
         symbolNodes.push(...cached.nodes);
         allEdges.push(...cached.edges);
@@ -54,7 +66,12 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
             continue;
           }
           source = readFileSync(absPath, 'utf-8');
-        } catch { continue; }
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException)?.code;
+          const detail = code || (err instanceof Error ? err.message : String(err));
+          parseErrors.push(`${fileNode.filePath}: unreadable (${detail})`);
+          continue;
+        }
         fileContents.set(fileNode.filePath ?? absPath, source);
         const result = await parseFile(absPath, source, fileNode.filePath ?? '');
         const fileSymbols: MonographNode[] = [...result.nodes];
@@ -98,10 +115,16 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
           const fileHash = cache.hashContent(source);
           cache.setDeferred(absPath, fileHash, fileSymbols, fileEdges);
         } catch { /* non-fatal */ }
+        const nodeStart = symbolNodes.length;
+        const edgeStart = allEdges.length;
         symbolNodes.push(...fileSymbols);
         allEdges.push(...fileEdges);
-        freshNodes.push(...fileSymbols);
-        freshEdges.push(...fileEdges);
+        freshNodeRanges.push([nodeStart, symbolNodes.length]);
+        freshEdgeRanges.push([edgeStart, allEdges.length]);
+        // This file was re-parsed (cache miss) — its OLD node/edge set (from the
+        // previous build) must be deleted before the fresh rows are inserted below,
+        // otherwise a renamed/removed symbol's old row survives forever (ghost rows).
+        if (fileNode.filePath) staleFilePaths.push(fileNode.filePath);
         cacheMisses++;
       }
       processed++;
@@ -114,16 +137,35 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
     cache.flush();
 
     if (ctx.db) {
+      const db = ctx.db;
       // Only insert freshly-parsed nodes — cached nodes are already in the DB
       // from the previous build (node IDs are deterministic from file_path + symbol).
-      // On first build (no cache hits), freshNodes === symbolNodes.
-      const nodesToInsert = cacheHits > 0 ? freshNodes : symbolNodes;
-      insertNodes(ctx.db, nodesToInsert);
+      // On first build (no cache hits), freshNodes === symbolNodes, so the fresh
+      // subset is never materialized — symbolNodes/allEdges are used directly.
+      const freshNodes = cacheHits > 0
+        ? freshNodeRanges.flatMap(([s, e]) => symbolNodes.slice(s, e))
+        : symbolNodes;
+      const freshEdges = cacheHits > 0
+        ? freshEdgeRanges.flatMap(([s, e]) => allEdges.slice(s, e))
+        : allEdges;
+      const nodesToInsert = freshNodes;
       const knownIds = new Set(symbolNodes.map(n => n.id));
-      const edgesToInsert = cacheHits > 0
-        ? freshEdges.filter(e => knownIds.has(e.targetId))
-        : allEdges.filter(e => knownIds.has(e.targetId));
-      insertEdges(ctx.db, edgesToInsert);
+      const edgesToInsert = freshEdges.filter(e => knownIds.has(e.targetId));
+
+      // For every cache-miss file, purge its OLD node/edge set BEFORE inserting the
+      // fresh parse results, inside the same transaction — otherwise a renamed or
+      // removed symbol's old row would survive forever (INSERT OR REPLACE only
+      // overwrites rows whose id still matches; it never deletes rows whose id
+      // disappeared because the symbol was renamed).
+      const writeAll = db.transaction(() => {
+        for (const filePath of staleFilePaths) {
+          deleteEdgesForFile(db, filePath);
+          deleteNodesForFile(db, filePath);
+        }
+        insertNodes(db, nodesToInsert);
+        insertEdges(db, edgesToInsert);
+      });
+      writeAll();
     }
 
     if (cacheHits > 0 && cacheMisses === 0) {
@@ -131,8 +173,9 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
     }
 
     if (cacheHits > 0) {
+      const freshNodeCount = freshNodeRanges.reduce((sum, [s, e]) => sum + (e - s), 0);
       ctx.onProgress?.({ phase: 'parse', filesProcessed: processed, totalFiles: fileNodes.length,
-        message: `cache: ${cacheHits} hits, ${cacheMisses} misses (${freshNodes.length} nodes inserted)` } as any);
+        message: `cache: ${cacheHits} hits, ${cacheMisses} misses (${freshNodeCount} nodes inserted)` } as any);
     }
 
     return { symbolNodes, allEdges, parseErrors, fileContents, cacheStats: { hits: cacheHits, misses: cacheMisses } };

package/src/pipeline/phases/scan.ts

@@ -1,4 +1,4 @@
-import { readdirSync, statSync, existsSync, readFileSync } from 'fs';
+import { readdirSync, statSync, lstatSync, existsSync, readFileSync } from 'fs';
 import { join, extname } from 'path';
 import micromatch from 'micromatch';
 import type { PipelinePhase, PipelineContext } from '../types.js';
@@ -50,16 +50,22 @@ export const scanPhase: PipelinePhase<ScanOutput> = {
     }
 
     function walk(dir: string) {
-      let entries: string[];
-      try { entries = readdirSync(dir); } catch { return; }
+      let dirents: import('fs').Dirent[];
+      try { dirents = readdirSync(dir, { withFileTypes: true }); } catch { return; }
 
-      for (const entry of entries) {
+      for (const dirent of dirents) {
+        const entry = dirent.name;
         if (ignoreDirs.has(entry)) continue;
         // Skip macOS AppleDouble resource fork files (._*) — common on ExFAT/network volumes
         if (entry.startsWith('._')) continue;
+        // Never follow symlinks — a symlink to an ancestor directory causes infinite
+        // recursion (stack overflow), and a symlink to a large external tree would
+        // get fully indexed as if it were part of the repo. Matches how most
+        // code-indexing tools behave by default.
+        if (dirent.isSymbolicLink()) continue;
         const fullPath = join(dir, entry);
         let stat: ReturnType<typeof statSync>;
-        try { stat = statSync(fullPath); } catch { continue; }
+        try { stat = lstatSync(fullPath); } catch { continue; }
 
         if (stat.isDirectory()) {
           // Always traverse directories — negation patterns may rescue files inside ignored dirs

package/src/pipeline/phases/scope-resolution.ts

@@ -286,11 +286,25 @@ const GO_RESOLVE_EXTS = ['.go'];
 const JAVA_RESOLVE_EXTS = ['.java'];
 const RUST_RESOLVE_EXTS = ['.rs'];
 
+const workspacePackageMapCache = new Map<string, Map<string, string>>();
+
+/** Invalidate the cached workspace package map for a repo — call at the start
+ * of each build so long-lived processes (watch mode) pick up package.json
+ * additions/removals instead of serving a stale map from a prior build. */
+export function clearWorkspacePackageMapCache(repoPath: string): void {
+  workspacePackageMapCache.delete(repoPath);
+}
+
 /**
  * Build package-name → directory map from workspace package.json files.
  * Scans packages/ for package.json and maps npm name to its relative src path.
+ * Cached per repoPath — multiple pipeline phases (cross-file, scope-resolution,
+ * the latter's own re-export loop) call this per-file/per-edge within the same
+ * build, and the workspace's package.json set doesn't change mid-build.
  */
-function buildWorkspacePackageMap(repoPath: string): Map<string, string> {
+export function buildWorkspacePackageMap(repoPath: string): Map<string, string> {
+  const cached = workspacePackageMapCache.get(repoPath);
+  if (cached) return cached;
   const result = new Map<string, string>();
   const packagesDir = join(repoPath, 'packages');
   try {
@@ -315,10 +329,11 @@ function buildWorkspacePackageMap(repoPath: string): Map<string, string> {
     };
     scanDirs(packagesDir, 0);
   } catch { /* no packages dir */ }
+  workspacePackageMapCache.set(repoPath, result);
   return result;
 }
 
-function resolveModuleSpecifier(
+export function resolveModuleSpecifier(
   importerPath: string,
   specifier: string,
   repoPath: string,
@@ -346,8 +361,8 @@ function resolveModuleSpecifier(
     return null;
   }
 
-  // Workspace package specifier: @monomind/hooks → packages/@monomind/hooks/src/index.ts
-  // Also handles subpath: @monomind/hooks/src/foo → packages/@monomind/hooks/src/foo.ts
+  // Workspace package specifier: @monoes/hooks → packages/@monomind/hooks/src/index.ts
+  // Also handles subpath: @monoes/hooks/src/foo → packages/@monomind/hooks/src/foo.ts
   for (const [pkgName, pkgDir] of workspaceMap) {
     if (specifier === pkgName) {
       // Bare import: resolve to package entry point (src/index.ts)

package/src/pipeline/types.ts

@@ -20,6 +20,8 @@ export interface PipelineOptions {
   ignore: string[];
   /** Max Section nodes to submit to LLM extraction (0 = disabled). Default 0. */
   llmMaxSections: number;
+  /** When true, bypass the on-disk extraction cache entirely and re-parse every file from scratch. Default false. */
+  force?: boolean;
 }
 
 export const DEFAULT_OPTIONS: PipelineOptions = {
@@ -29,6 +31,7 @@ export const DEFAULT_OPTIONS: PipelineOptions = {
   workerChunkBudgetBytes: 20971520,
   ignore: [],
   llmMaxSections: 0,
+  force: false,
 };
 
 export interface PipelinePhase<TOutput> {

package/src/reporting/graph-report.ts

@@ -54,16 +54,15 @@ function queryEdgesByRelation(db: MonographDb): EdgeRelationStat[] {
 
 function queryTopNodesByDegree(db: MonographDb, limit = 10): TopDegreeNode[] {
   const rows = db.prepare(`
-    SELECT
-      n.id,
-      n.name,
-      n.label,
-      (
-        SELECT COUNT(*) FROM edges WHERE source_id = n.id
-      ) + (
-        SELECT COUNT(*) FROM edges WHERE target_id = n.id
-      ) AS degree
+    SELECT n.id, n.name, n.label, COALESCE(d.degree, 0) AS degree
     FROM nodes n
+    LEFT JOIN (
+      SELECT node_id, SUM(cnt) AS degree FROM (
+        SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
+        UNION ALL
+        SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
+      ) GROUP BY node_id
+    ) d ON d.node_id = n.id
     ORDER BY degree DESC
     LIMIT ?
   `).all(limit) as TopDegreeNode[];

package/src/staleness/git-staleness.ts

@@ -28,10 +28,13 @@ export function checkStaleness(db: MonographDb, repoPath: string): StalenessRepo
   const indexedCommitShort = indexedCommitFull ? indexedCommitFull.slice(0, 7) : null;
   const currentCommitShort = currentCommit ? currentCommit.slice(0, 7) : null;
 
-  // 3. If no stored commit or short SHAs match, not stale
-  if (!indexedCommitFull || indexedCommitShort === currentCommitShort) {
+  // 3. If SHAs match → fresh. If no stored commit → staleness unknown (not "fresh").
+  if (indexedCommitShort === currentCommitShort) {
     return { isStale: false, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
   }
+  if (!indexedCommitFull) {
+    return { isStale: true, indexedAt: null, indexedCommit: null, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
+  }
 
   // Guard: indexedCommitFull is read from SQLite — validate before shell interpolation
   if (!/^[0-9a-f]{7,40}$/i.test(indexedCommitFull)) {

package/src/storage/db.ts

@@ -5,12 +5,31 @@ import {
   CREATE_NODES, CREATE_EDGES, CREATE_COMMUNITIES,
   CREATE_INDEX_META, CREATE_NODES_FTS, CREATE_INDEXES, FTS_SYNC_TRIGGERS,
   CREATE_EMBEDDINGS, CREATE_WIKI_PAGES,
+  CREATE_AGENT_INTERACTIONS, CREATE_AGENT_INTERACTIONS_IDX,
+  CREATE_AGENT_INTERACTIONS_ORG_IDX, CREATE_AGENT_INTERACTIONS_TYPE_IDX,
+  CREATE_AGENT_INTERACTIONS_TS_IDX,
 } from './schema.js';
 import { MonographError } from '../types.js';
 
 export type MonographDb = Database.Database;
 
-export function openDb(dbPath: string): MonographDb {
+export interface OpenDbOptions {
+  /**
+   * When true, throw a clear error instead of silently creating a fresh,
+   * empty-but-migrated database if `dbPath` doesn't exist yet. Defaults to
+   * false to preserve legacy build-time behavior (the `monograph build`
+   * codepath legitimately creates new DBs). Read-only analysis tools should
+   * pass `true` so pointing them at a repo whose real index lives elsewhere
+   * (e.g. running from a subdirectory) fails loudly instead of reporting
+   * fake-successful-looking empty results.
+   */
+  fileMustExist?: boolean;
+}
+
+export function openDb(dbPath: string, options: OpenDbOptions = {}): MonographDb {
+  if (options.fileMustExist && !existsSync(dbPath)) {
+    throw new MonographError(`Monograph database does not exist at ${dbPath}. Run monograph build first.`);
+  }
   try {
     mkdirSync(dirname(dbPath), { recursive: true });
     const db = new Database(dbPath);
@@ -45,6 +64,11 @@ function applyMigrations(db: MonographDb): void {
   db.exec(FTS_SYNC_TRIGGERS);
   db.exec(CREATE_EMBEDDINGS);
   db.exec(CREATE_WIKI_PAGES);
+  db.exec(CREATE_AGENT_INTERACTIONS);
+  db.exec(CREATE_AGENT_INTERACTIONS_IDX);
+  db.exec(CREATE_AGENT_INTERACTIONS_ORG_IDX);
+  db.exec(CREATE_AGENT_INTERACTIONS_TYPE_IDX);
+  db.exec(CREATE_AGENT_INTERACTIONS_TS_IDX);
 
   // Schema version table — tracks incremental column additions.
   db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY)`);
@@ -66,6 +90,16 @@ export function atomicRebuild(dbPath: string, buildFn: (db: MonographDb) => void
     buildFn(db);
     db.close();
     renameSync(tmpPath, dbPath);
+    // The old db's WAL-mode sidecar files belong to the file we just replaced —
+    // if left behind, the next process to open dbPath pairs the NEW db file with
+    // a STALE -wal/-shm whose salt/checkpoint state doesn't match, which can
+    // surface as "file is not a database" or subtle corruption.
+    for (const suffix of ['-wal', '-shm']) {
+      const sidecar = dbPath + suffix;
+      if (existsSync(sidecar)) {
+        try { unlinkSync(sidecar); } catch { /* best-effort cleanup */ }
+      }
+    }
   } catch (err) {
     db.close();
     if (existsSync(tmpPath)) {

package/src/storage/edge-store.ts

@@ -73,10 +73,17 @@ export function getEdgesForTarget(db: Database.Database, targetId: string): Mono
   return rows.map(rowToEdge);
 }
 
+/**
+ * Delete every edge that touches a node belonging to `filePath`, on either end.
+ * Must be called BEFORE the corresponding nodes are deleted (the subselects need
+ * the file's nodes to still exist to identify which edges to remove) — e.g.
+ * `deleteEdgesForFile` then `deleteNodesForFile`, never the reverse.
+ */
 export function deleteEdgesForFile(db: Database.Database, filePath: string): void {
   db.prepare(`
     DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file_path = ?)
-  `).run(filePath);
+       OR target_id IN (SELECT id FROM nodes WHERE file_path = ?)
+  `).run(filePath, filePath);
 }
 
 export function countEdges(db: Database.Database): number {

package/src/storage/fts-store.ts

@@ -13,6 +13,20 @@ export interface FtsResult {
   endLine: number | null;
 }
 
+/**
+ * Quote a single FTS5 search term as a string literal when it contains characters
+ * that would otherwise be parsed as FTS5 syntax (quotes, parens, boolean keywords
+ * like AND/OR/NOT, colons, hyphens, etc). Wrapping in double-quotes forces FTS5 to
+ * treat the term as a literal string; any literal `"` inside the term is escaped by
+ * doubling it, per FTS5's own string-literal quoting rules.
+ */
+function quoteFtsTerm(term: string): string {
+  // Bare alphanumeric/underscore terms need no quoting and are the common case.
+  if (/^[A-Za-z0-9_]+$/.test(term)) return term;
+  const escaped = term.replace(/"/g, '""');
+  return `"${escaped}"`;
+}
+
 export function ftsSearch(
   db: Database.Database,
   query: string,
@@ -24,8 +38,13 @@ export function ftsSearch(
   const safeQuery = query.replace(/[*]/g, ' ').trim();
   if (!safeQuery) return [];
 
-  // Trigram handles substring matching natively — no need to append * to each term
-  const ftsQuery = safeQuery.split(/\s+/).join(' ');
+  // Trigram handles substring matching natively — no need to append * to each term.
+  // Quote each term individually so characters like `"`, `(`, `)`, or bare boolean
+  // keywords (AND/OR/NOT) don't get parsed as FTS5 query syntax.
+  const ftsQuery = safeQuery
+    .split(/\s+/)
+    .map(quoteFtsTerm)
+    .join(' ');
 
   let matchSql = `
     SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
@@ -52,16 +71,19 @@ export function ftsSearch(
     // FTS MATCH can throw on malformed queries; fall through to LIKE path
   }
 
-  // For short queries (≤2 chars) trigram requires at least 3 characters to fire, so
-  // supplement with a LIKE fallback to catch single/double-character matches.
-  if (safeQuery.length <= 2) {
-    const escapedQuery = safeQuery.replace(/%/g, '\\%').replace(/_/g, '\\_');
+  // Run the LIKE fallback whenever MATCH threw (malformed/boolean-keyword query) or
+  // returned zero rows — not just for short (≤2 char) queries. Short queries need it
+  // because trigram requires ≥3 characters to fire; longer queries need it whenever
+  // MATCH couldn't handle the syntax, so a query-syntax failure doesn't silently read
+  // as "no results".
+  if (safeQuery.length <= 2 || matchRows.length === 0) {
+    const escapedQuery = safeQuery.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
     const likePattern = `%${escapedQuery}%`;
     let likeSql = `
       SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
              n.start_line, n.end_line, 0 AS rank
       FROM nodes n
-      WHERE (n.name LIKE ? OR n.norm_label LIKE ? OR n.file_path LIKE ?)
+      WHERE (n.name LIKE ? ESCAPE '\\' OR n.norm_label LIKE ? ESCAPE '\\' OR n.file_path LIKE ? ESCAPE '\\')
     `;
     const likeParams: unknown[] = [likePattern, likePattern, likePattern];
     if (label) {
@@ -186,13 +208,13 @@ export function hybridSearch(
   // ── Strategy 2: LIKE fallback ──────────────────────────────────────────────
   // Always run for short queries (≤3 chars) or when FTS returned nothing.
   if (safeQuery.length <= 3 || ftsRows.length === 0) {
-    const escapedSafeQuery = safeQuery.replace(/%/g, '\\%').replace(/_/g, '\\_');
+    const escapedSafeQuery = safeQuery.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
     const likePattern = `%${escapedSafeQuery}%`;
     let likeSql = `
       SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
              n.start_line, n.end_line
       FROM nodes n
-      WHERE (n.name LIKE ? OR n.norm_label LIKE ?)
+      WHERE (n.name LIKE ? ESCAPE '\\' OR n.norm_label LIKE ? ESCAPE '\\')
     `;
     const likeParams: unknown[] = [likePattern, likePattern];
     if (label) {

package/src/storage/schema.ts

@@ -124,6 +124,36 @@ export const CREATE_FILE_CACHE = `
   )
 `;
 
+export const CREATE_AGENT_INTERACTIONS = `
+CREATE TABLE IF NOT EXISTS agent_interactions (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  org_name TEXT,
+  agent_type TEXT NOT NULL,
+  parent_agent TEXT,
+  prompt_summary TEXT,
+  result_summary TEXT,
+  tokens_in INTEGER NOT NULL DEFAULT 0,
+  tokens_out INTEGER NOT NULL DEFAULT 0,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  success INTEGER NOT NULL DEFAULT 1,
+  duration_ms INTEGER NOT NULL DEFAULT 0,
+  timestamp INTEGER NOT NULL,
+  metadata TEXT
+)`;
+
+export const CREATE_AGENT_INTERACTIONS_IDX = `
+CREATE INDEX IF NOT EXISTS idx_agent_interactions_session ON agent_interactions(session_id)`;
+
+export const CREATE_AGENT_INTERACTIONS_ORG_IDX = `
+CREATE INDEX IF NOT EXISTS idx_agent_interactions_org ON agent_interactions(org_name)`;
+
+export const CREATE_AGENT_INTERACTIONS_TYPE_IDX = `
+CREATE INDEX IF NOT EXISTS idx_agent_interactions_type ON agent_interactions(agent_type)`;
+
+export const CREATE_AGENT_INTERACTIONS_TS_IDX = `
+CREATE INDEX IF NOT EXISTS idx_agent_interactions_ts ON agent_interactions(timestamp)`;
+
 export const FTS_SYNC_TRIGGERS = `
 CREATE TRIGGER IF NOT EXISTS nodes_fts_insert AFTER INSERT ON nodes BEGIN
   INSERT INTO nodes_fts(rowid, id, name, norm_label, file_path, label)

package/src/watch/watcher.ts

@@ -34,8 +34,17 @@ export async function watchAsync(
       do {
         rerun = false;
         opts.onProgress?.({ phase: 'watch', message: `Changed: ${files.slice(0, 3).join(', ')}` });
-        await buildAsync(repoPath, { onProgress: opts.onProgress, force: opts.force, codeOnly: opts.codeOnly, llmMaxSections: opts.llmMaxSections ?? 0 });
-        opts.onProgress?.({ phase: 'watch', message: 'Graph rebuilt.' });
+        try {
+          await buildAsync(repoPath, { onProgress: opts.onProgress, force: opts.force, codeOnly: opts.codeOnly, llmMaxSections: opts.llmMaxSections ?? 0 });
+          opts.onProgress?.({ phase: 'watch', message: 'Graph rebuilt.' });
+        } catch (err) {
+          // A rebuild failure (locked DB past busy_timeout, disk full, transient
+          // I/O error) must not crash the watch process — log it, notify listeners,
+          // and keep watching for the next change instead of letting an unhandled
+          // rejection escape this listener.
+          watcher.emit('monograph:error', err);
+          opts.onProgress?.({ phase: 'watch', message: `Rebuild failed: ${err instanceof Error ? err.message : String(err)}` });
+        }
       } while (rerun);
     } finally {
       building = false;

package/src/web/analyze-api.ts

@@ -52,11 +52,13 @@ async function handleAnalyze(req: IncomingMessage, res: ServerResponse): Promise
   }
 
   // Set SSE headers
+  const origin = req.headers['origin'] ?? '';
+  const allowedOrigin = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin) ? origin : '';
   res.writeHead(200, {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
     'Connection': 'keep-alive',
-    'Access-Control-Allow-Origin': 'http://localhost',
+    ...(allowedOrigin && { 'Access-Control-Allow-Origin': allowedOrigin }),
   });
 
   const dbPath = resolve(join(repoPath, '.monomind', 'monograph.db'));