@zuvia-software-solutions/code-mapper 1.4.0

package/dist/mcp/local/local-backend.js

@@ -0,0 +1,2759 @@
+// code-mapper/src/mcp/local/local-backend.ts
+/** @file local-backend.ts
+ *  @description Tool implementations using local .code-mapper/ indexes
+ *  Supports multiple indexed repositories via a global registry
+ *  LadybugDB connections are opened lazily per repo on first query */
+import fs from 'fs/promises';
+import path from 'path';
+import fsSync from 'fs';
+import { execFileSync } from 'child_process';
+import Parser from 'tree-sitter';
+import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady } from '../core/lbug-adapter.js';
+import { FileSystemWatcher } from '../../core/incremental/watcher.js';
+import { toRelativeFilePath, toRepoRoot } from '../../core/incremental/types.js';
+import { getLanguageFromFilename, getDefinitionNodeFromCaptures } from '../../core/ingestion/utils.js';
+import { loadParser, loadLanguage, isLanguageAvailable } from '../../core/tree-sitter/parser-loader.js';
+import { LANGUAGE_QUERIES } from '../../core/ingestion/tree-sitter-queries.js';
+import { getTreeSitterBufferSize, TREE_SITTER_MAX_BUFFER } from '../../core/ingestion/constants.js';
+import { generateId } from '../../lib/utils.js';
+import { NODE_TABLES, REL_TABLE_NAME } from '../../core/lbug/schema.js';
+import { FTS_TABLES } from '../../core/search/types.js';
+import { getTsgoService, stopTsgoService } from '../../core/semantic/tsgo-service.js';
+// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
+// at MCP server startup — crashes on unsupported Node ABI versions (#89)
+import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-manager.js';
+/** Quick test-file detection for filtering impact results across all supported languages */
+export function isTestFilePath(filePath) {
+    const p = filePath.toLowerCase().replace(/\\/g, '/');
+    return (p.includes('.test.') || p.includes('.spec.') ||
+        p.includes('__tests__/') || p.includes('__mocks__/') ||
+        p.includes('/test/') || p.includes('/tests/') ||
+        p.includes('/testing/') || p.includes('/fixtures/') ||
+        p.endsWith('_test.go') || p.endsWith('_test.py') ||
+        p.endsWith('_spec.rb') || p.endsWith('_test.rb') || p.includes('/spec/') ||
+        p.includes('/test_') || p.includes('/conftest.'));
+}
+/** Valid LadybugDB node labels for safe Cypher query construction */
+export const VALID_NODE_LABELS = new Set([
+    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement',
+    'Community', 'Process', 'Struct', 'Enum', 'Macro', 'Typedef', 'Union',
+    'Namespace', 'Trait', 'Impl', 'TypeAlias', 'Const', 'Static', 'Property',
+    'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module',
+]);
+/** Valid relation types for impact analysis filtering */
+export const VALID_RELATION_TYPES = new Set(['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'DEPENDS_ON', 'PROVIDES']);
+/** Regex to detect write operations in user-supplied Cypher queries */
+export const CYPHER_WRITE_RE = /\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH)\b/i;
+/** Check if a Cypher query contains write operations */
+export function isWriteQuery(query) {
+    return CYPHER_WRITE_RE.test(query);
+}
+/** Structured error logging for query failures — replaces empty catch blocks */
+function logQueryError(context, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Code Mapper [${context}]: ${msg}`);
+}
+export class LocalBackend {
+    repos = new Map();
+    contextCache = new Map();
+    initializedRepos = new Set();
+    watchers = new Map();
+    /** Per-repo promise chain that serializes ensureFresh calls.
+     *  Prevents race: Call 2 skipping refresh while Call 1 is still writing. */
+    refreshLocks = new Map();
+    /** Hard ceiling — beyond this, incremental is unreliable, warn prominently */
+    static MAX_INCREMENTAL_FILES = 200;
+    /** Optional tsgo LSP service for confidence-1.0 semantic resolution */
+    tsgoEnabled = false;
+    /** Start file system watcher for a repo to detect source changes */
+    startWatcher(repoId, handle) {
+        if (this.watchers.has(repoId))
+            return;
+        try {
+            const watcher = new FileSystemWatcher(toRepoRoot(handle.repoPath));
+            watcher.start();
+            this.watchers.set(repoId, watcher);
+        }
+        catch (err) {
+            // Watcher failure is non-fatal — tools still work, just without auto-refresh
+            console.error(`Code Mapper: Failed to start watcher for ${handle.name}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    /**
+     * Seed the watcher with file changes that happened while the MCP server was
+     * not running. Compares meta.json lastCommit against current git HEAD and
+     * injects any changed files as dirty entries.
+     */
+    seedWatcherFromGit(repoId, handle) {
+        if (!handle.lastCommit)
+            return;
+        const watcher = this.watchers.get(repoId);
+        if (!watcher)
+            return;
+        try {
+            const currentHead = execFileSync('git', ['rev-parse', 'HEAD'], {
+                cwd: handle.repoPath,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            if (currentHead === handle.lastCommit)
+                return;
+            const diffOutput = execFileSync('git', ['diff', '--name-status', `${handle.lastCommit}..HEAD`], { cwd: handle.repoPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            if (!diffOutput)
+                return;
+            const entries = [];
+            for (const line of diffOutput.split('\n')) {
+                if (!line)
+                    continue;
+                const [status, ...pathParts] = line.split('\t');
+                const filePath = pathParts.join('\t'); // handle tabs in filenames
+                if (!filePath)
+                    continue;
+                let changeKind;
+                if (status === 'D')
+                    changeKind = 'deleted';
+                else if (status === 'A')
+                    changeKind = 'created';
+                else
+                    changeKind = 'modified'; // M, R, C, etc.
+                try {
+                    entries.push({
+                        relativePath: toRelativeFilePath(filePath),
+                        changeKind,
+                    });
+                }
+                catch {
+                    // Skip absolute paths or other invalid entries
+                }
+            }
+            if (entries.length > 0) {
+                watcher.inject(entries);
+                console.error(`Code Mapper: Seeded ${entries.length} file change(s) from git (${handle.lastCommit.slice(0, 7)}..${currentHead.slice(0, 7)})`);
+            }
+        }
+        catch {
+            // Git command failed — non-fatal, watcher will catch future changes
+        }
+    }
+    /**
+     * Serialized entry point — ensures only one refresh runs per repo at a time.
+     * Call 2 waits for Call 1 to finish, then re-checks the watcher.
+     */
+    ensureFresh(repo) {
+        const key = repo.id;
+        const prev = this.refreshLocks.get(key) ?? Promise.resolve();
+        const next = prev.then(() => this.doEnsureFresh(repo));
+        // Store with swallowed errors so the chain doesn't break for future callers
+        this.refreshLocks.set(key, next.catch(() => { }));
+        return next;
+    }
+    /** Check for file changes and refresh the DB + embeddings before a tool call */
+    async doEnsureFresh(repo) {
+        const watcher = this.watchers.get(repo.id);
+        if (!watcher)
+            return;
+        // Flush pending debounce timers — edits within the 500ms window become
+        // visible immediately so no tool call can miss a recent save
+        await watcher.flush();
+        if (!watcher.hasDirtyFiles())
+            return;
+        const dirtyMap = watcher.drain();
+        if (!dirtyMap)
+            return;
+        const dirtyFiles = [...dirtyMap.values()];
+        const totalChanged = dirtyFiles.length;
+        // Hard ceiling — incremental is unreliable for huge diffs (branch switch, etc.)
+        if (totalChanged > LocalBackend.MAX_INCREMENTAL_FILES) {
+            // Re-inject so the files aren't lost; user must run full analyze
+            watcher.inject(dirtyFiles);
+            console.error(`Code Mapper: ${totalChanged} files changed — exceeds incremental limit (${LocalBackend.MAX_INCREMENTAL_FILES}), run: code-mapper analyze`);
+            // Don't silently serve stale — the staleness warning from getStalenessWarning
+            // will flag the tool response since git HEAD will differ from meta.lastCommit
+            return;
+        }
+        try {
+            // In-process incremental refresh — uses the existing read-write connection
+            // pool directly. No child process fork needed, no lock conflicts.
+            await this.ensureInitialized(repo.id);
+            const result = await this.inProcessRefresh(repo, dirtyFiles);
+            console.error(`Code Mapper: Refreshed ${result.filesProcessed} file(s) in ${result.durationMs}ms (${result.nodesInserted} nodes, ${result.edgesInserted} edges)`);
+            // Incremental embedding refresh — keep embeddings in sync with the graph
+            await this.refreshEmbeddings(repo, dirtyFiles);
+        }
+        catch (err) {
+            // Re-inject dirty files so the next tool call retries them
+            watcher.inject(dirtyFiles);
+            console.error(`Code Mapper: Incremental refresh failed (will retry next call): ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    /**
+     * Tables that are global metadata — NOT deleted per-file during incremental refresh.
+     */
+    static SKIP_DELETE_TABLES = new Set(['Community', 'Process']);
+    /** Tables requiring backtick-quoting in Cypher (reserved words) */
+    static BACKTICK_TABLES = new Set([
+        'Struct', 'Enum', 'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl',
+        'TypeAlias', 'Const', 'Static', 'Property', 'Record', 'Delegate', 'Annotation',
+        'Constructor', 'Template', 'Module',
+    ]);
+    static quoteTable(table) {
+        return LocalBackend.BACKTICK_TABLES.has(table) ? `\`${table}\`` : table;
+    }
+    static escapeCypher(value) {
+        return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    }
+    /**
+     * In-process incremental refresh — parses dirty files with tree-sitter and
+     * writes directly to the DB through the existing connection pool.
+     *
+     * This avoids the LadybugDB lock conflict that prevented the child-process
+     * approach from working: LadybugDB on macOS holds an exclusive file lock
+     * even for read-only connections, and db.close() segfaults via N-API.
+     */
+    async inProcessRefresh(repo, dirtyFiles) {
+        const t0 = Date.now();
+        const esc = LocalBackend.escapeCypher;
+        const qt = LocalBackend.quoteTable;
+        let nodesDeleted = 0;
+        let nodesInserted = 0;
+        let edgesInserted = 0;
+        let filesSkipped = 0;
+        // Phase 1: Delete old nodes for all dirty files
+        for (const entry of dirtyFiles) {
+            const escaped = esc(entry.relativePath);
+            for (const table of NODE_TABLES) {
+                if (LocalBackend.SKIP_DELETE_TABLES.has(table))
+                    continue;
+                try {
+                    await executeQuery(repo.id, `MATCH (n:${qt(table)}) WHERE n.filePath = '${escaped}' DETACH DELETE n`);
+                    nodesDeleted++;
+                }
+                catch (err) {
+                    console.error(`Code Mapper: [refresh] DELETE ${table} for ${entry.relativePath}: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+        }
+        // Phase 2: Parse modified/created files with tree-sitter
+        const parser = await loadParser();
+        const filesToProcess = dirtyFiles.filter(f => f.changeKind === 'modified' || f.changeKind === 'created');
+        const allDefinitions = [];
+        const callSites = [];
+        const insertedFilePaths = new Set();
+        for (const entry of filesToProcess) {
+            const relPath = entry.relativePath;
+            const absPath = path.resolve(repo.repoPath, relPath);
+            const language = getLanguageFromFilename(relPath);
+            if (!language || !isLanguageAvailable(language)) {
+                filesSkipped++;
+                continue;
+            }
+            let content;
+            try {
+                content = fsSync.readFileSync(absPath, 'utf-8');
+            }
+            catch {
+                filesSkipped++;
+                continue;
+            }
+            if (content.length > TREE_SITTER_MAX_BUFFER) {
+                filesSkipped++;
+                continue;
+            }
+            try {
+                await loadLanguage(language, relPath);
+            }
+            catch {
+                filesSkipped++;
+                continue;
+            }
+            let tree;
+            try {
+                tree = parser.parse(content, undefined, { bufferSize: getTreeSitterBufferSize(content.length) });
+            }
+            catch {
+                filesSkipped++;
+                continue;
+            }
+            const queryString = LANGUAGE_QUERIES[language];
+            if (!queryString) {
+                filesSkipped++;
+                continue;
+            }
+            let matches;
+            try {
+                const tsLang = parser.getLanguage();
+                const query = new Parser.Query(tsLang, queryString);
+                matches = query.matches(tree.rootNode);
+            }
+            catch {
+                filesSkipped++;
+                continue;
+            }
+            insertedFilePaths.add(relPath);
+            for (const match of matches) {
+                const captureMap = {};
+                for (const c of match.captures)
+                    captureMap[c.name] = c.node;
+                // Skip imports/heritage captures — only extract definitions and calls
+                if (captureMap['import'] || captureMap['import.source'])
+                    continue;
+                if (captureMap['heritage'] || captureMap['heritage.impl'])
+                    continue;
+                // Collect call sites for tsgo resolution
+                if (captureMap['call'] || captureMap['call.name']) {
+                    const callNameNode = captureMap['call.name'];
+                    if (callNameNode) {
+                        callSites.push({
+                            filePath: relPath,
+                            absPath: absPath,
+                            name: callNameNode.text,
+                            line: callNameNode.startPosition.row,
+                            character: callNameNode.startPosition.column,
+                        });
+                    }
+                    continue;
+                }
+                const nameNode = captureMap['name'];
+                if (!nameNode && !captureMap['definition.constructor'])
+                    continue;
+                const nodeName = nameNode ? nameNode.text : 'init';
+                let nodeLabel = 'CodeElement';
+                if (captureMap['definition.function'])
+                    nodeLabel = 'Function';
+                else if (captureMap['definition.class'])
+                    nodeLabel = 'Class';
+                else if (captureMap['definition.interface'])
+                    nodeLabel = 'Interface';
+                else if (captureMap['definition.method'])
+                    nodeLabel = 'Method';
+                else if (captureMap['definition.struct'])
+                    nodeLabel = 'Struct';
+                else if (captureMap['definition.enum'])
+                    nodeLabel = 'Enum';
+                else if (captureMap['definition.namespace'])
+                    nodeLabel = 'Namespace';
+                else if (captureMap['definition.module'])
+                    nodeLabel = 'Module';
+                else if (captureMap['definition.trait'])
+                    nodeLabel = 'Trait';
+                else if (captureMap['definition.impl'])
+                    nodeLabel = 'Impl';
+                else if (captureMap['definition.type'])
+                    nodeLabel = 'TypeAlias';
+                else if (captureMap['definition.const'])
+                    nodeLabel = 'Const';
+                else if (captureMap['definition.static'])
+                    nodeLabel = 'Static';
+                else if (captureMap['definition.typedef'])
+                    nodeLabel = 'Typedef';
+                else if (captureMap['definition.macro'])
+                    nodeLabel = 'Macro';
+                else if (captureMap['definition.union'])
+                    nodeLabel = 'Union';
+                else if (captureMap['definition.property'])
+                    nodeLabel = 'Property';
+                else if (captureMap['definition.record'])
+                    nodeLabel = 'Record';
+                else if (captureMap['definition.delegate'])
+                    nodeLabel = 'Delegate';
+                else if (captureMap['definition.annotation'])
+                    nodeLabel = 'Annotation';
+                else if (captureMap['definition.constructor'])
+                    nodeLabel = 'Constructor';
+                else if (captureMap['definition.template'])
+                    nodeLabel = 'Template';
+                const defNode = getDefinitionNodeFromCaptures(captureMap);
+                const startLine = defNode ? defNode.startPosition.row : (nameNode ? nameNode.startPosition.row : 0);
+                const endLine = defNode ? defNode.endPosition.row : startLine;
+                const nodeContent = defNode ? (defNode.text || '').slice(0, 50_000) : '';
+                allDefinitions.push({
+                    nodeId: generateId(nodeLabel, `${relPath}:${nodeName}`),
+                    name: nodeName,
+                    label: nodeLabel,
+                    filePath: relPath,
+                    startLine,
+                    endLine,
+                    content: nodeContent,
+                });
+            }
+        }
+        // Phase 3: Insert File nodes + symbol nodes
+        for (const filePath of insertedFilePaths) {
+            const fileId = generateId('File', filePath);
+            try {
+                await executeQuery(repo.id, `CREATE (n:File {id: '${esc(fileId)}', name: '${esc(path.basename(filePath))}', filePath: '${esc(filePath)}', content: ''})`);
+                nodesInserted++;
+            }
+            catch (err) {
+                console.error(`Code Mapper: [refresh] CREATE File ${filePath}: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        for (const def of allDefinitions) {
+            try {
+                await executeQuery(repo.id, `CREATE (n:${qt(def.label)} {id: '${esc(def.nodeId)}', name: '${esc(def.name)}', filePath: '${esc(def.filePath)}', startLine: ${def.startLine}, endLine: ${def.endLine}, content: '${esc(def.content)}', description: ''})`);
+                nodesInserted++;
+            }
+            catch (err) {
+                console.error(`Code Mapper: [refresh] CREATE ${def.label} ${def.name}: ${err instanceof Error ? err.message : err}`);
+            }
+            const fileId = generateId('File', def.filePath);
+            try {
+                await executeQuery(repo.id, `MATCH (a:File), (b:${qt(def.label)}) WHERE a.id = '${esc(fileId)}' AND b.id = '${esc(def.nodeId)}' CREATE (a)-[:${REL_TABLE_NAME} {type: 'DEFINES', confidence: 1.0, reason: '', step: 0}]->(b)`);
+                edgesInserted++;
+            }
+            catch (err) {
+                console.error(`Code Mapper: [refresh] CREATE DEFINES edge for ${def.name}: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        // Phase 4: Resolve call edges via tsgo (if enabled)
+        if (this.tsgoEnabled && callSites.length > 0) {
+            const tsgo = getTsgoService(repo.repoPath);
+            if (await tsgo.start()) {
+                // Notify tsgo about changed files so it has fresh state
+                for (const entry of filesToProcess) {
+                    const absPath = path.resolve(repo.repoPath, entry.relativePath);
+                    await tsgo.notifyFileChanged(absPath);
+                }
+                let tsgoResolved = 0;
+                for (const call of callSites) {
+                    try {
+                        const def = await tsgo.resolveDefinition(call.absPath, call.line, call.character);
+                        if (!def)
+                            continue;
+                        // Find the target node in the DB by file path + name match
+                        const targetRows = await executeQuery(repo.id, `MATCH (n) WHERE n.filePath = '${esc(def.filePath)}' AND n.startLine <= ${def.line} AND n.endLine >= ${def.line} RETURN n.id AS id LIMIT 1`);
+                        if (targetRows.length === 0)
+                            continue;
+                        const targetId = String(targetRows[0].id ?? '');
+                        if (!targetId)
+                            continue;
+                        // Find the caller node (the function/method containing this call site)
+                        const callerRows = await executeQuery(repo.id, `MATCH (n) WHERE n.filePath = '${esc(call.filePath)}' AND n.startLine <= ${call.line} AND n.endLine >= ${call.line} AND NOT n:File RETURN n.id AS id LIMIT 1`);
+                        const callerId = callerRows.length > 0
+                            ? String(callerRows[0].id ?? '')
+                            : generateId('File', call.filePath);
+                        if (callerId === targetId)
+                            continue; // self-call
+                        try {
+                            await executeQuery(repo.id, `MATCH (a), (b) WHERE a.id = '${esc(callerId)}' AND b.id = '${esc(targetId)}' CREATE (a)-[:${REL_TABLE_NAME} {type: 'CALLS', confidence: 1.0, reason: 'tsgo-semantic', step: 0}]->(b)`);
+                            edgesInserted++;
+                            tsgoResolved++;
+                        }
+                        catch { /* duplicate edge */ }
+                    }
+                    catch { /* resolution failed for this call */ }
+                }
+                if (tsgoResolved > 0) {
+                    console.error(`Code Mapper: tsgo resolved ${tsgoResolved}/${callSites.length} call(s) at confidence 1.0`);
+                }
+            }
+        }
+        // Phase 5: Rebuild FTS indexes
+        for (const { table, index } of FTS_TABLES) {
+            try {
+                await executeQuery(repo.id, `CALL DROP_FTS_INDEX('${table}', '${index}')`);
+            }
+            catch { /* may not exist */ }
+            try {
+                await executeQuery(repo.id, `CALL CREATE_FTS_INDEX('${table}', '${index}', ['name', 'content'], stemmer := 'porter')`);
+            }
+            catch { /* non-fatal */ }
+        }
+        return {
+            filesProcessed: filesToProcess.length,
+            filesSkipped,
+            nodesDeleted,
+            nodesInserted,
+            edgesInserted,
+            durationMs: Date.now() - t0,
+        };
+    }
+    /**
+     * Update CodeEmbedding rows for dirty files so semantic search is never stale.
+     *
+     * Runs ONLY when the repo previously had embeddings (stats.embeddings > 0).
+     * Steps:
+     *   1. Delete stale CodeEmbedding rows for all dirty file paths (always)
+     *   2. Query new embeddable nodes for modified/created files
+     *   3. Generate text → batch embed using the warm MCP singleton model
+     *   4. Insert new CodeEmbedding rows
+     *   5. Drop + recreate HNSW vector index
+     *
+     * If the embedding model fails to load, stale rows are still deleted —
+     * semantic search returns fewer results but never wrong ones.
+     */
+    async refreshEmbeddings(repo, dirtyFiles) {
+        if (!repo.stats?.embeddings || repo.stats.embeddings === 0)
+            return;
+        if (dirtyFiles.length === 0)
+            return;
+        const esc = LocalBackend.escapeCypher;
+        const dirtyRelPaths = dirtyFiles.map((f) => f.relativePath);
+        try {
+            // Step 1: Delete stale embeddings for all dirty files
+            for (const relPath of dirtyRelPaths) {
+                try {
+                    const rows = await executeQuery(repo.id, `MATCH (n) WHERE n.filePath = '${esc(relPath)}' RETURN n.id AS id`);
+                    for (const row of rows) {
+                        const nodeId = String(row.id ?? '');
+                        if (!nodeId)
+                            continue;
+                        try {
+                            await executeQuery(repo.id, `MATCH (e:CodeEmbedding) WHERE e.nodeId = '${esc(nodeId)}' DETACH DELETE e`);
+                        }
+                        catch { /* row may not exist */ }
+                    }
+                }
+                catch { /* file may not have nodes */ }
+            }
+            // Step 2: Query new embeddable nodes
+            const embeddableLabels = ['Function', 'Class', 'Method', 'Interface', 'File'];
+            const modifiedPaths = dirtyFiles
+                .filter((f) => f.changeKind === 'modified' || f.changeKind === 'created')
+                .map((f) => f.relativePath);
+            if (modifiedPaths.length === 0) {
+                await this.rebuildVectorIndex(repo.id);
+                return;
+            }
+            const newNodes = [];
+            for (const relPath of modifiedPaths) {
+                for (const label of embeddableLabels) {
+                    try {
+                        const q = label === 'File'
+                            ? `MATCH (n:File) WHERE n.filePath = '${esc(relPath)}' RETURN n.id AS id, n.name AS name, 'File' AS label, n.filePath AS filePath, n.content AS content`
+                            : `MATCH (n:${label}) WHERE n.filePath = '${esc(relPath)}' RETURN n.id AS id, n.name AS name, '${label}' AS label, n.filePath AS filePath, n.content AS content, n.startLine AS startLine, n.endLine AS endLine`;
+                        const rows = await executeQuery(repo.id, q);
+                        for (const row of rows) {
+                            const r = row;
+                            newNodes.push({
+                                id: String(r.id ?? ''), name: String(r.name ?? ''), label: String(r.label ?? label),
+                                filePath: String(r.filePath ?? ''), content: String(r.content ?? ''),
+                                startLine: r.startLine != null ? Number(r.startLine) : undefined,
+                                endLine: r.endLine != null ? Number(r.endLine) : undefined,
+                            });
+                        }
+                    }
+                    catch { /* table may not exist */ }
+                }
+            }
+            // Step 3: Embed + insert
+            if (newNodes.length > 0) {
+                try {
+                    const { generateEmbeddingText } = await import('../../core/embeddings/text-generator.js');
+                    const { embedBatch } = await import('../core/embedder.js');
+                    const texts = newNodes.map((node) => generateEmbeddingText(node));
+                    const embeddings = await embedBatch(texts);
+                    for (let i = 0; i < newNodes.length; i++) {
+                        const vecStr = `[${embeddings[i].join(',')}]`;
+                        try {
+                            await executeQuery(repo.id, `CREATE (e:CodeEmbedding {nodeId: '${esc(newNodes[i].id)}', embedding: CAST(${vecStr} AS FLOAT[256])})`);
+                        }
+                        catch { /* duplicate */ }
+                    }
+                    console.error(`Code Mapper: Embedded ${newNodes.length} node(s) incrementally`);
+                }
+                catch (err) {
+                    console.error(`Code Mapper: Incremental embedding failed (stale entries removed): ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            // Step 4: Rebuild vector index
+            await this.rebuildVectorIndex(repo.id);
+        }
+        catch (err) {
+            console.error(`Code Mapper: Embedding refresh failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    async rebuildVectorIndex(repoId) {
+        try {
+            await executeQuery(repoId, 'INSTALL VECTOR');
+        }
+        catch { }
+        try {
+            await executeQuery(repoId, 'LOAD EXTENSION VECTOR');
+        }
+        catch { }
+        try {
+            await executeQuery(repoId, `CALL DROP_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx')`);
+        }
+        catch { }
+        try {
+            const rows = await executeQuery(repoId, `MATCH (e:CodeEmbedding) RETURN COUNT(*) AS cnt`);
+            const cnt = Number(rows[0]?.cnt ?? 0);
+            if (cnt === 0)
+                return;
+        }
+        catch {
+            return;
+        }
+        try {
+            await executeQuery(repoId, `CALL CREATE_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 'embedding', metric := 'cosine')`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : '';
+            if (!msg.includes('already exists')) {
+                console.error(`Code Mapper: Vector index rebuild failed: ${msg}`);
+            }
+        }
+    }
+    // Initialization
+    /**
+     * Initialize from the global registry, returns true if at least one repo is available.
+     * @param opts.tsgo — Enable tsgo semantic resolution (confidence-1.0 call edges)
+     */
+    async init(opts) {
+        this.tsgoEnabled = opts?.tsgo ?? false;
+        await this.refreshRepos();
+        // Start file watchers for incremental refresh
+        for (const [id, handle] of this.repos) {
+            this.startWatcher(id, handle);
+            // Seed watcher with changes that happened while the server was down
+            this.seedWatcherFromGit(id, handle);
+            // Start tsgo LSP for semantic resolution (optional, non-blocking)
+            if (this.tsgoEnabled) {
+                const svc = getTsgoService(handle.repoPath);
+                svc.start().catch(() => { }); // warm up in background
+            }
+        }
+        return this.repos.size > 0;
+    }
+    /**
+     * Re-read the global registry and update the in-memory repo map
+     * LadybugDB connections for removed repos idle-timeout naturally
+     */
+    async refreshRepos() {
+        const entries = await listRegisteredRepos({ validate: true });
+        const freshIds = new Set();
+        for (const entry of entries) {
+            const id = this.repoId(entry.name, entry.path);
+            freshIds.add(id);
+            const storagePath = entry.storagePath;
+            const lbugPath = path.join(storagePath, 'lbug');
+            // Clean up leftover KuzuDB files from before the LadybugDB migration
+            // Warn if kuzu exists but lbug doesn't (re-analyze needed)
+            const kuzu = await cleanupOldKuzuFiles(storagePath);
+            if (kuzu.found && kuzu.needsReindex) {
+                console.error(`Code Mapper: "${entry.name}" has a stale KuzuDB index. Run: code-mapper analyze ${entry.path}`);
+            }
+            const handle = {
+                id,
+                name: entry.name,
+                repoPath: entry.path,
+                storagePath,
+                lbugPath,
+                indexedAt: entry.indexedAt,
+                lastCommit: entry.lastCommit,
+                stats: entry.stats,
+            };
+            this.repos.set(id, handle);
+            // Build lightweight context (no LadybugDB needed)
+            const s = entry.stats || {};
+            this.contextCache.set(id, {
+                projectName: entry.name,
+                stats: {
+                    fileCount: s.files || 0,
+                    functionCount: s.nodes || 0,
+                    communityCount: s.communities || 0,
+                    processCount: s.processes || 0,
+                },
+            });
+        }
+        // Prune repos that no longer exist in the registry
+        for (const id of this.repos.keys()) {
+            if (!freshIds.has(id)) {
+                this.repos.delete(id);
+                this.contextCache.delete(id);
+                this.initializedRepos.delete(id);
+            }
+        }
+    }
+    /** Generate a stable repo ID from name + path (appends hash on collision) */
+    repoId(name, repoPath) {
+        const base = name.toLowerCase();
+        // Check for name collision with a different path
+        for (const [id, handle] of this.repos) {
+            if (id === base && handle.repoPath !== path.resolve(repoPath)) {
+                // Collision — use path hash
+                const hash = Buffer.from(repoPath).toString('base64url').slice(0, 6);
+                return `${base}-${hash}`;
+            }
+        }
+        return base;
+    }
+    // Repo Resolution
+    /**
+     * Resolve which repo to use (by name, path, or single-repo default)
+     * Re-reads the registry once on miss in case a new repo was indexed
+     */
+    async resolveRepo(repoParam) {
+        const result = this.resolveRepoFromCache(repoParam);
+        if (result)
+            return result;
+        // Miss — refresh registry and try once more
+        await this.refreshRepos();
+        const retried = this.resolveRepoFromCache(repoParam);
+        if (retried)
+            return retried;
+        // Still no match — throw with helpful message
+        if (this.repos.size === 0) {
+            throw new Error('No indexed repositories. Run: code-mapper analyze');
+        }
+        if (repoParam) {
+            const names = [...this.repos.values()].map(h => h.name);
+            throw new Error(`Repository "${repoParam}" not found. Available: ${names.join(', ')}`);
+        }
+        const names = [...this.repos.values()].map(h => h.name);
+        throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${names.join(', ')}`);
+    }
+    /** Try to resolve a repo from the in-memory cache, returns null on miss */
+    resolveRepoFromCache(repoParam) {
+        if (this.repos.size === 0)
+            return null;
+        if (repoParam) {
+            const paramLower = repoParam.toLowerCase();
+            // Match by id
+            if (this.repos.has(paramLower))
+                return this.repos.get(paramLower);
+            // Match by name (case-insensitive)
+            for (const handle of this.repos.values()) {
+                if (handle.name.toLowerCase() === paramLower)
+                    return handle;
+            }
+            // Match by path (substring)
+            const resolved = path.resolve(repoParam);
+            for (const handle of this.repos.values()) {
+                if (handle.repoPath === resolved)
+                    return handle;
+            }
+            // Match by partial name
+            for (const handle of this.repos.values()) {
+                if (handle.name.toLowerCase().includes(paramLower))
+                    return handle;
+            }
+            return null;
+        }
+        if (this.repos.size === 1) {
+            return this.repos.values().next().value;
+        }
+        return null; // Multiple repos, no param — ambiguous
+    }
+    // Lazy LadybugDB Init
+    async ensureInitialized(repoId) {
+        // Always check the actual pool — the idle timer may have evicted the connection
+        if (this.initializedRepos.has(repoId) && isLbugReady(repoId))
+            return;
+        const handle = this.repos.get(repoId);
+        if (!handle)
+            throw new Error(`Unknown repo: ${repoId}`);
+        try {
+            await initLbug(repoId, handle.lbugPath);
+            this.initializedRepos.add(repoId);
+        }
+        catch (err) {
+            // If lock error, mark as not initialized so next call retries
+            this.initializedRepos.delete(repoId);
+            throw err;
+        }
+    }
+    // Public Getters
+    /** Get context for a specific repo (or the single repo if only one) */
+    getContext(repoId) {
+        if (repoId && this.contextCache.has(repoId)) {
+            return this.contextCache.get(repoId);
+        }
+        if (this.repos.size === 1) {
+            return this.contextCache.values().next().value ?? null;
+        }
+        return null;
+    }
+    /** List all registered repos, re-reading the registry to discover new ones */
+    async listRepos() {
+        await this.refreshRepos();
+        return [...this.repos.values()].map(h => ({
+            name: h.name,
+            path: h.repoPath,
+            indexedAt: h.indexedAt,
+            lastCommit: h.lastCommit,
+            stats: h.stats,
+        }));
+    }
+    // ── Compact text formatters — optimized for LLM token efficiency ────
+    /** Extract signature from content: the declaration line(s), not the full body */
+    extractSignature(content, name, _type) {
+        if (!content)
+            return name || '?';
+        const lines = content.split('\n');
+        const declKeywords = /^\s*(export\s+)?(default\s+)?(async\s+)?(function|class|interface|type|const|let|var|enum|struct|trait|impl|pub\s|fn\s|def\s|private|protected|public|static|abstract|override|readonly)/;
+        const namePattern = name ? new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`) : null;
+        // Helper: collect multi-line signature (for arrow functions with params on multiple lines)
+        const collectSignature = (startIdx) => {
+            let sig = lines[startIdx].trim();
+            // If the line ends with '(' or has unmatched parens, collect continuation lines
+            let openParens = (sig.match(/\(/g) || []).length - (sig.match(/\)/g) || []).length;
+            let i = startIdx + 1;
+            while (openParens > 0 && i < lines.length && i < startIdx + 8) {
+                const next = lines[i].trim();
+                if (!next || next.startsWith('//') || next.startsWith('*')) {
+                    i++;
+                    continue;
+                }
+                sig += ' ' + next;
+                openParens += (next.match(/\(/g) || []).length - (next.match(/\)/g) || []).length;
+                // Stop at => or { after parens are balanced
+                if (openParens <= 0)
+                    break;
+                i++;
+            }
+            // If we found the closing paren but there's a return type annotation, grab it
+            if (openParens <= 0 && i + 1 < lines.length) {
+                const nextLine = lines[i + 1]?.trim() || '';
+                if (nextLine.startsWith('):') || nextLine.startsWith('): ')) {
+                    sig += ' ' + nextLine;
+                }
+            }
+            return sig.replace(/\s*[{=]>\s*\{?\s*$/, '').replace(/\s+/g, ' ').trim();
+        };
+        // Strategy 1: Find the line containing the symbol name AND a declaration keyword
+        for (let i = 0; i < lines.length; i++) {
+            const trimmed = lines[i].trim();
+            if (namePattern && namePattern.test(trimmed) && (declKeywords.test(trimmed) || trimmed.includes('(') || trimmed.includes(':'))) {
+                return collectSignature(i);
+            }
+        }
+        // Strategy 2: Find any line with a declaration keyword
+        for (let i = 0; i < lines.length; i++) {
+            const trimmed = lines[i].trim();
+            if (declKeywords.test(trimmed)) {
+                return collectSignature(i);
+            }
+        }
+        // Strategy 3: Find any line containing the name
+        if (namePattern) {
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (namePattern.test(trimmed) && trimmed.length > 5 && !trimmed.startsWith('//') && !trimmed.startsWith('*')) {
+                    return trimmed.replace(/\s*\{?\s*$/, '').replace(/\s+/g, ' ');
+                }
+            }
+        }
+        return name || '?';
+    }
+    /** Short file path: strip common prefix if all paths share it */
+    shortPath(filePath) {
+        return filePath;
+    }
+    /** C2: Count how many initial steps two flows share (by symbol name) */
+    sharedPrefixLength(a, b) {
+        let i = 0;
+        while (i < a.length && i < b.length && (a[i].name === b[i].name))
+            i++;
+        return i;
+    }
+    /** D1: Generate a readable flow description from step names */
+    /** Generate readable flow description from step names.
+     *  Uses step 2 (first dispatch point) as the middle — it's where the entry
+     *  point specializes and is the most discriminating step in most flows. */
+    describeFlow(stepNames) {
+        if (stepNames.length === 0)
+            return '';
+        const humanize = (name) => name
+            .replace(/([a-z])([A-Z])/g, '$1 $2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+            .toLowerCase();
+        const first = humanize(stepNames[0]);
+        const last = humanize(stepNames[stepNames.length - 1]);
+        if (stepNames.length <= 2)
+            return `${first} → ${last}`;
+        // Step 2 is the dispatch point — where the flow specializes
+        const dispatch = humanize(stepNames[1]);
+        return `${first} → ${dispatch} → ${last}`;
+    }
+    formatQueryAsText(result) {
+        if (result.error)
+            return `Error: ${result.error}`;
+        const lines = [];
+        // Match quality signal
+        const allSymbols = [...(result.process_symbols || []), ...(result.definitions || [])];
+        const bothCount = allSymbols.filter((s) => s.matched_by === 'bm25 + semantic').length;
+        const total = allSymbols.length;
+        const quality = bothCount >= total * 0.5 ? 'strong' : bothCount >= total * 0.25 ? 'good' : 'partial';
+        lines.push(`match: ${quality} | ${bothCount}/${total} bm25+semantic`);
+        // Build flow and symbol data
+        const processes = result.processes || [];
+        const processSymbols = result.process_symbols || [];
+        const defs = result.definitions || [];
+        const flows = [];
+        if (processes.length > 0) {
+            for (const proc of processes) {
+                const syms = processSymbols
+                    .filter((s) => s.process_id === proc.id)
+                    .sort((a, b) => (a.step_index || 0) - (b.step_index || 0));
+                if (syms.length > 0)
+                    flows.push({ proc, syms });
+            }
+        }
+        // Check if any flow has step names that overlap with query terms
+        const searchQuery = result._searchQuery || '';
+        const qTerms = searchQuery.toLowerCase().split(/\s+/).filter((t) => t.length >= 3);
+        const anyFlowRelevant = flows.some(flow => {
+            const words = flow.syms.map((s) => (s.name || '').toLowerCase()
+                .replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_\-]/g, ' ')).join(' ');
+            return qTerms.some(t => words.includes(t));
+        });
+        // Helper to render symbols section
+        const renderSymbols = () => {
+            if (defs.length === 0)
+                return;
+            lines.push('');
+            lines.push('## Symbols');
+            for (const d of defs) {
+                const sig = d.signature || d.name;
+                const mod = d.module ? ` [${d.module}]` : '';
+                const start = d.startLine || 0;
+                const end = d.endLine || 0;
+                const isSmall = end > 0 && start > 0 && (end - start) < 10;
+                lines.push(`  ${sig} — ${d.type} @ ${this.shortPath(d.filePath)}:${start || '?'}${mod}`);
+                if (isSmall && d.content) {
+                    const src = String(d.content).trim();
+                    if (src.length < 500) {
+                        for (const srcLine of src.split('\n')) {
+                            lines.push(`    ${srcLine}`);
+                        }
+                    }
+                }
+            }
+        };
+        // Helper to render flows section
+        const formatStep = (sym) => {
+            const sig = sym.signature || sym.name;
+            const mod = sym.module ? ` [${sym.module}]` : '';
+            const matched = sym.matched_by ? ' ←' : '';
+            return `  [${sym.step_index}] ${sig} — ${sym.type} @ ${this.shortPath(sym.filePath)}:${sym.startLine || '?'}${mod}${matched}`;
+        };
+        const renderFlows = (maxFlows) => {
+            const toShow = maxFlows ? flows.slice(0, maxFlows) : flows;
+            let i = 0;
+            while (i < toShow.length) {
+                const group = [toShow[i]];
+                for (let j = i + 1; j < toShow.length; j++) {
+                    if (this.sharedPrefixLength(toShow[i].syms, toShow[j].syms) >= 3)
+                        group.push(toShow[j]);
+                }
+                if (group.length >= 2) {
+                    const prefixLen = this.sharedPrefixLength(group[0].syms, group[1].syms);
+                    const prefix = group[0].syms.slice(0, prefixLen);
+                    const desc = this.describeFlow(group[0].syms.map((s) => s.name));
+                    lines.push('');
+                    lines.push(`## ${group.length} flows: ${desc} (shared prefix: ${prefixLen} steps)`);
+                    for (const sym of prefix) {
+                        lines.push(formatStep(sym));
+                    }
+                    for (const flow of group) {
+                        const suffix = flow.syms.slice(prefixLen);
+                        if (suffix.length > 0) {
+                            lines.push(`  then → ${flow.proc.summary.split(' → ').pop()}`);
+                            for (const sym of suffix) {
+                                lines.push(formatStep(sym));
+                            }
+                        }
+                    }
+                    i += group.length;
+                }
+                else {
+                    const flow = toShow[i];
+                    const desc = this.describeFlow(flow.syms.map((s) => s.name));
+                    lines.push('');
+                    lines.push(`## ${flow.proc.summary}: ${desc} (${flow.proc.step_count} steps)`);
+                    for (const sym of flow.syms) {
+                        lines.push(formatStep(sym));
+                    }
+                    i++;
+                }
+            }
+        };
+        // When flows are relevant (step names match query), show flows first
+        // When flows are noise (no name overlap), show Symbols first, then max 2 flows
+        if (anyFlowRelevant) {
+            renderFlows();
+            renderSymbols();
+        }
+        else {
+            renderSymbols();
+            if (flows.length > 0) {
+                lines.push('');
+                lines.push(`## Related flows (${flows.length})`);
+                renderFlows(2);
+            }
+        }
+        return lines.join('\n');
+    }
+    formatContextAsText(result) {
+        if (result.error)
+            return `Error: ${result.error}`;
+        if (result.status === 'ambiguous') {
+            const lines = [`Ambiguous: ${result.candidates.length} matches for '${result.message}'`];
+            for (const c of result.candidates) {
+                lines.push(`  ${c.name} — ${c.kind} @ ${c.filePath}:${c.line || '?'}`);
+            }
+            return lines.join('\n');
+        }
+        const sym = result.symbol;
+        const lines = [];
+        // Header with signature + C5 module
+        const sig = sym.signature || sym.name;
+        const modTag = sym.module ? ` [${sym.module}]` : '';
+        lines.push(`## ${sym.name}`);
+        lines.push(`${sym.kind || sym.type || 'Symbol'} @ ${sym.filePath}:${sym.startLine || '?'}-${sym.endLine || '?'}${modTag}`);
+        if (sym.signature && sym.signature !== sym.name) {
+            lines.push(`\`${sym.signature}\``);
+        }
+        // Incoming refs (F3: with line numbers, F4: with kind, Fix 6: error-handler/conditional annotations)
+        const incoming = result.incoming || {};
+        const incomingEntries = Object.entries(incoming);
+        if (incomingEntries.length > 0) {
+            lines.push('');
+            for (const [relType, refs] of incomingEntries) {
+                const refList = refs;
+                lines.push(`### ${relType} (${refList.length} incoming)`);
+                for (const ref of refList) {
+                    const loc = ref.startLine ? `${ref.filePath}:${ref.startLine}` : (ref.filePath || '?');
+                    const annotation = ref.reason === 'error-handler' ? ' (error path)' : ref.reason === 'conditional' ? ' (conditional)' : '';
+                    lines.push(`  ${ref.name} — ${ref.kind || 'Symbol'} @ ${loc}${annotation}`);
+                }
+            }
+        }
+        // Outgoing refs — sorted by call site line number for execution order
+        const outgoing = result.outgoing || {};
+        const outgoingEntries = Object.entries(outgoing);
+        if (outgoingEntries.length > 0) {
+            lines.push('');
+            for (const [relType, refs] of outgoingEntries) {
+                const refList = refs.slice().sort((a, b) => (a.callLine || 9999) - (b.callLine || 9999));
+                lines.push(`### ${relType} (${refList.length} outgoing)`);
+                for (const ref of refList) {
+                    const loc = ref.startLine ? `${ref.filePath}:${ref.startLine}` : (ref.filePath || '?');
+                    const annotation = ref.reason === 'error-handler' ? ' (error path)' : ref.reason === 'conditional' ? ' (conditional)' : '';
+                    const linePrefix = ref.callLine ? `:${ref.callLine}` : '';
+                    lines.push(`  ${linePrefix ? `[${linePrefix}] ` : ''}${ref.name} — ${ref.kind || 'Symbol'} @ ${loc}${annotation}`);
+                }
+            }
+        }
+        // Process participation
+        const processes = result.processes || [];
+        if (processes.length > 0) {
+            lines.push('');
+            lines.push(`### Flows (${processes.length})`);
+            for (const p of processes) {
+                lines.push(`  ${p.name} (step ${p.step_index}/${p.step_count})`);
+            }
+        }
+        return lines.join('\n');
+    }
+    formatImpactAsText(result) {
+        if (result.error)
+            return `Error: ${result.error}`;
+        const lines = [];
+        const t = result.target;
+        lines.push(`## Impact: ${t.name} (${result.direction})`);
+        lines.push(`Risk: ${result.risk} | ${result.impactedCount} affected | ${result.summary.processes_affected} processes | ${result.summary.modules_affected} modules${result.truncated ? ' | TRUNCATED' : ''}`);
+        // By depth (F4: use actual type, F10: show non-CALLS relation types)
+        const byDepth = result.byDepth || {};
+        const depthLabels = { 1: 'WILL BREAK', 2: 'LIKELY AFFECTED', 3: 'MAY NEED TESTING' };
+        for (const [depth, items] of Object.entries(byDepth)) {
+            const d = Number(depth);
+            const label = depthLabels[d] || `depth ${d}`;
+            const itemList = items;
+            lines.push('');
+            lines.push(`### d=${d} ${label} (${itemList.length})`);
+            for (const item of itemList) {
+                // F10: show relationship type when not CALLS (the interesting cases)
+                const relInfo = item.relationType && item.relationType !== 'CALLS' ? ` via ${item.relationType}` : '';
+                const conf = item.confidence != null && item.confidence < 1 ? ` (${item.confidence})` : '';
+                lines.push(`  ${item.name} — ${item.type || 'Symbol'} @ ${this.shortPath(item.filePath)}${relInfo}${conf}`);
+            }
+        }
+        // F5: Cap affected processes at 7, group overflow
+        const procs = result.affected_processes || [];
+        if (procs.length > 0) {
+            const MAX_SHOWN_FLOWS = 7;
+            const shown = procs.slice(0, MAX_SHOWN_FLOWS);
+            const overflow = procs.length - MAX_SHOWN_FLOWS;
+            lines.push('');
+            lines.push(`### Affected flows (${procs.length})`);
+            for (const p of shown) {
+                lines.push(`  ${p.name} (${p.hits} hits, ${p.step_count} steps)`);
+            }
+            if (overflow > 0) {
+                lines.push(`  ... +${overflow} more flows`);
+            }
+        }
+        // Affected modules
+        const mods = result.affected_modules || [];
+        if (mods.length > 0) {
+            lines.push('');
+            lines.push(`### Modules: ${mods.map((m) => `${m.name} (${m.hits} ${m.impact})`).join(' | ')}`);
+        }
+        return lines.join('\n');
+    }
+    formatDetectChangesAsText(result) {
+        if (result.error)
+            return `Error: ${result.error}`;
+        const summary = result.summary;
+        if (summary.changed_count === 0)
+            return 'No changes detected.';
+        const lines = [];
+        lines.push(`## Changes (${summary.risk_level.toUpperCase()})`);
+        lines.push(`${summary.changed_files} files | ${summary.changed_count} symbols | ${summary.affected_count} processes`);
+        // Fix 7: Show interface change risk summary at the top
+        const interfaceChanges = (result.changed_symbols || []).filter((s) => s.change_type === 'interface changed');
+        if (interfaceChanges.length > 0) {
+            lines.push(`\u26A0 ${interfaceChanges.length} interface changes: ${interfaceChanges.slice(0, 5).map((s) => s.name).join(', ')}${interfaceChanges.length > 5 ? ` +${interfaceChanges.length - 5} more` : ''}`);
+        }
+        // Group changed symbols by file
+        const byFile = new Map();
+        for (const sym of (result.changed_symbols || [])) {
+            const fp = sym.filePath || '';
+            if (!byFile.has(fp))
+                byFile.set(fp, []);
+            byFile.get(fp).push(sym);
+        }
+        // Show files sorted by symbol count, F3: with diff stats
+        const diffStats = result.diff_stats || {};
+        const sortedFiles = Array.from(byFile.entries())
+            .sort((a, b) => b[1].length - a[1].length)
+            .slice(0, 30);
+        if (sortedFiles.length > 0) {
+            lines.push('');
+            lines.push(`### Changed files (${byFile.size})`);
+            for (const [fp, syms] of sortedFiles) {
+                const names = syms.slice(0, 5).map((s) => s.name).join(', ');
+                const more = syms.length > 5 ? ` +${syms.length - 5} more` : '';
+                const stat = diffStats[fp] || diffStats[fp.split('/').slice(-1)[0]] || '';
+                const statSuffix = stat ? ` (${stat})` : '';
+                lines.push(`  ${this.shortPath(fp)}${statSuffix} — ${syms.length} symbols: ${names}${more}`);
+            }
+        }
+        // Affected processes
+        const procs = result.affected_processes || [];
+        if (procs.length > 0) {
+            const topProcs = procs.sort((a, b) => b.changed_steps.length - a.changed_steps.length).slice(0, 15);
+            lines.push('');
+            lines.push(`### Affected flows (${procs.length})`);
+            for (const p of topProcs) {
+                const steps = p.changed_steps.map((s) => s.symbol).join(', ');
+                lines.push(`  ${p.name} — ${p.changed_steps.length} changed: ${steps}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    // ── Staleness check ────────────────────────────────────────────────
+    /** C3: Check if index is behind HEAD and return a warning prefix */
+    getStalenessWarning(repo) {
+        try {
+            const { checkStaleness } = require('../staleness.js');
+            const info = checkStaleness(repo.repoPath, repo.lastCommit);
+            if (info.isStale) {
+                return `⚠ index ${info.commitsBehind} commit${info.commitsBehind > 1 ? 's' : ''} behind HEAD\n\n`;
+            }
+        }
+        catch { }
+        return '';
+    }
+    // ── Tool Dispatch ─────────────────────────────────────────────────
+    async callTool(method, params) {
+        if (method === 'list_repos') {
+            return this.listRepos();
+        }
+        // Resolve repo from optional param (re-reads registry on miss)
+        const repo = await this.resolveRepo(params?.repo);
+        await this.ensureFresh(repo);
+        // C3: Prepend staleness warning to all tool responses
+        const staleWarning = this.getStalenessWarning(repo);
+        switch (method) {
+            case 'query':
+                return staleWarning + this.formatQueryAsText(await this.query(repo, params));
+            case 'cypher': {
+                const raw = await this.cypher(repo, params);
+                return this.formatCypherAsMarkdown(raw);
+            }
+            case 'context': {
+                // F5: Bulk context — if names array provided, fetch context for each
+                if (params?.names && Array.isArray(params.names) && params.names.length > 0) {
+                    const results = [];
+                    for (const name of params.names.slice(0, 5)) { // cap at 5 to prevent abuse
+                        const result = await this.context(repo, { ...params, name, names: undefined });
+                        results.push(this.formatContextAsText(result));
+                    }
+                    return staleWarning + results.join('\n\n---\n\n');
+                }
+                return staleWarning + this.formatContextAsText(await this.context(repo, params));
+            }
+            case 'impact':
+                return staleWarning + this.formatImpactAsText(await this.impact(repo, params));
+            case 'detect_changes':
+                return staleWarning + this.formatDetectChangesAsText(await this.detectChanges(repo, params));
+            case 'rename':
+                return this.rename(repo, params);
+            // Legacy aliases for backwards compatibility
+            case 'search':
+                return staleWarning + this.formatQueryAsText(await this.query(repo, params));
+            case 'explore':
+                return staleWarning + this.formatContextAsText(await this.context(repo, { name: params?.name, ...params }));
+            case 'overview':
+                return this.overview(repo, params);
+            default:
+                throw new Error(`Unknown tool: ${method}`);
+        }
+    }
+    // Tool Implementations
+    /**
+     * Query tool: process-grouped search
+     * Hybrid BM25+semantic search, trace to processes, rank by relevance + cohesion
+     */
+    async query(repo, params) {
+        if (!params.query?.trim()) {
+            return { error: 'query parameter is required and cannot be empty.' };
+        }
+        await this.ensureInitialized(repo.id);
+        const searchQuery = params.query.trim();
+        // Detect if query is a specific identifier vs natural language
+        // Identifiers: camelCase, PascalCase, snake_case, UPPER_CASE, or single words without spaces
+        const isIdentifierQuery = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(searchQuery) || /^[A-Z_][A-Z0-9_]*$/.test(searchQuery);
+        // Fix 8: Special case for "overview" / "architecture" queries
+        if (searchQuery.toLowerCase() === 'overview' || searchQuery.toLowerCase() === 'architecture') {
+            // Return top clusters with their key symbols instead of search results
+            const clusterResult = await this.queryClusters(repo.name, 10);
+            const lines = [`## Codebase Overview: ${repo.name}`];
+            for (const cluster of (clusterResult.clusters || []).slice(0, 8)) {
+                lines.push(`\n### ${cluster.heuristicLabel || cluster.label} (${cluster.symbolCount} symbols, cohesion: ${(cluster.cohesion || 0).toFixed(2)})`);
+                // Fetch top 5 symbols from this cluster
+                try {
+                    const members = await executeQuery(repo.id, `
+            MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community {heuristicLabel: '${(cluster.heuristicLabel || cluster.label || '').replace(/'/g, "''")}'})
+            RETURN n.name AS name, labels(n) AS type, n.filePath AS filePath
+            ORDER BY n.startLine
+            LIMIT 5
+          `);
+                    for (const m of members) {
+                        lines.push(`  ${m.name || m[0]} — ${m.type || m[1]} @ ${m.filePath || m[2]}`);
+                    }
+                }
+                catch { }
+            }
+            return lines.join('\n');
+        }
+        const { DEFAULT_PROCESS_LIMIT, DEFAULT_MAX_SYMBOLS_PER_PROCESS, DEFAULT_MAX_DEFINITIONS, COHESION_WEIGHT, MAX_BATCH_CANDIDATES, } = await import('../../core/search/types.js');
+        const { mergeWithRRF } = await import('../../core/search/hybrid-search.js');
+        const processLimit = params.limit || DEFAULT_PROCESS_LIMIT;
+        const maxSymbolsPerProcess = params.max_symbols || DEFAULT_MAX_SYMBOLS_PER_PROCESS;
+        const includeContent = params.include_content ?? false;
+        // Enrich semantic query with task_context/goal for better embeddings
+        const semanticQuery = [searchQuery, params.goal, params.task_context]
+            .filter(Boolean).join(' — ');
+        // Step 1: Hybrid search (BM25 + semantic in parallel)
+        // BM25 uses raw query (keyword matching); semantic uses enriched query (better embedding)
+        const searchLimit = processLimit * maxSymbolsPerProcess;
+        const [bm25Results, semanticResults] = await Promise.all([
+            this.bm25Search(repo, searchQuery, searchLimit),
+            this.semanticSearch(repo, semanticQuery, searchLimit),
+        ]);
+        // Step 2: Weighted RRF merge (single implementation — no duplication)
+        // BM25 now returns symbol-level results with nodeId, name, type
+        const bm25ForRRF = bm25Results.map((r, i) => ({
+            nodeId: String(r.nodeId ?? ''),
+            name: String(r.name ?? ''),
+            type: String(r.type ?? 'File'),
+            filePath: String(r.filePath ?? ''),
+            score: Number(r.bm25Score ?? 0),
+            rank: i + 1,
+            startLine: r.startLine,
+            endLine: r.endLine,
+        }));
+        const semanticForRRF = semanticResults.map((r) => ({
+            nodeId: String(r.nodeId ?? ''), name: String(r.name ?? ''), label: String(r.type ?? ''),
+            filePath: String(r.filePath ?? ''), distance: Number(r.distance ?? 1),
+            startLine: r.startLine, endLine: r.endLine,
+        }));
+        const rrfMerged = mergeWithRRF(bm25ForRRF, semanticForRRF, { limit: searchLimit });
+        // Build lookup from original search data (keyed by both nodeId and filePath for cross-referencing)
+        const searchDataMap = new Map();
+        for (const r of bm25Results) {
+            if (r.nodeId)
+                searchDataMap.set(r.nodeId, r);
+            if (r.filePath && !searchDataMap.has(r.filePath))
+                searchDataMap.set(r.filePath, r);
+        }
+        for (const r of semanticResults) {
+            const key = r.nodeId || r.filePath;
+            if (!searchDataMap.has(key))
+                searchDataMap.set(key, r);
+        }
+        let merged = rrfMerged.map(rrf => ({
+            score: rrf.score,
+            data: searchDataMap.get(rrf.nodeId ?? '') ?? searchDataMap.get(rrf.filePath) ?? {
+                name: rrf.name ?? rrf.filePath.split('/').pop(), type: rrf.label ?? 'File',
+                filePath: rrf.filePath, nodeId: rrf.nodeId,
+            },
+        }));
+        // Filter noise: remove test files, config files, docs from results by default
+        merged = merged.filter(item => {
+            const fp = String(item.data.filePath ?? '').toLowerCase();
+            if (isTestFilePath(fp))
+                return false;
+            if (fp.endsWith('.json') || fp.endsWith('.md') || fp.endsWith('.yml') || fp.endsWith('.yaml'))
+                return false;
+            if (fp.includes('/skills/') || fp.includes('/fixtures/') || fp.includes('/eval/'))
+                return false;
+            return true;
+        });
+        // F1 (new): File path filter — restrict results to a specific file
+        if (params.file_path) {
+            const fpFilter = params.file_path.toLowerCase();
+            merged = merged.filter(item => String(item.data.filePath ?? '').toLowerCase().includes(fpFilter));
+        }
+        // Exact name match boost: if a symbol name matches the query exactly, pin it high
+        const queryLower = searchQuery.toLowerCase();
+        for (const item of merged) {
+            const name = String(item.data.name ?? '').toLowerCase();
+            if (name === queryLower || name.includes(queryLower)) {
+                item.score *= 10; // strong boost for exact/substring match
+            }
+        }
+        // F7: Boost symbols whose name matches terms from goal/task_context
+        // e.g., goal="find timeout logic" boosts symbol named "withTimeout"
+        const contextTerms = [params.goal, params.task_context]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(t => t.length >= 3 && !['the', 'and', 'for', 'how', 'does', 'what', 'find', 'understand', 'where', 'when', 'with', 'from', 'that', 'this',
+            'extract', 'search', 'get', 'set', 'create', 'add', 'remove', 'delete', 'update', 'make', 'build',
+            'use', 'using', 'into', 'code', 'function', 'method', 'class', 'file', 'module', 'adding', 'could',
+            'logic', 'existing', 'current', 'new', 'all', 'any', 'should', 'want', 'need'].includes(t));
+        if (contextTerms.length > 0) {
+            for (const item of merged) {
+                const name = String(item.data.name ?? '').toLowerCase();
+                for (const term of contextTerms) {
+                    if (name.includes(term)) {
+                        item.score *= 5;
+                        break;
+                    }
+                }
+            }
+        }
+        merged.sort((a, b) => b.score - a.score);
+        // Step 2b: Cross-encoder re-ranking (optional, improves top-k precision)
+        // Uses enriched query (with goal/context) for better reranker scoring
+        if (merged.length > 1) {
+            try {
+                const rerankCandidates = merged.filter(m => m.data.nodeId).slice(0, 30);
+                if (rerankCandidates.length > 1) {
+                    const nodeIdList = rerankCandidates.map(c => `'${String(c.data.nodeId).replace(/'/g, "''")}'`).join(', ');
+                    const snippetRows = await executeQuery(repo.id, `
+            MATCH (n) WHERE n.id IN [${nodeIdList}]
+            RETURN n.id AS nodeId, COALESCE(n.content, n.name) AS snippet
+          `);
+                    const snippetMap = new Map();
+                    for (const row of snippetRows) {
+                        snippetMap.set(String(row.nodeId ?? row[0]), String(row.snippet ?? row[1] ?? ''));
+                    }
+                    const passages = rerankCandidates
+                        .map(c => ({ id: String(c.data.nodeId), text: snippetMap.get(c.data.nodeId) ?? String(c.data.name ?? '') }))
+                        .filter(p => p.text.length > 0);
+                    if (passages.length > 1) {
+                        const { rerank } = await import('../../core/search/reranker.js');
+                        // Use enriched query for reranker — goal/context improves cross-encoder precision
+                        const reranked = await rerank(semanticQuery, passages);
+                        const rerankedIds = new Set(reranked.map(r => r.id));
+                        const nonCandidates = merged.filter(m => !m.data.nodeId || !rerankedIds.has(m.data.nodeId));
+                        // C4: Simplified reranker blending — normalize both to [0,1], blend with alpha
+                        const maxRRF = Math.max(...rerankCandidates.map(c => c.score), 1e-9);
+                        const maxRerank = Math.max(...reranked.map(r => r.score), 1e-9);
+                        const minRerank = Math.min(...reranked.map(r => r.score), 0);
+                        const rerankRange = maxRerank - minRerank || 1;
+                        const rerankScoreMap = new Map(reranked.map(r => [
+                            r.id,
+                            (r.score - minRerank) / rerankRange, // normalized 0-1
+                        ]));
+                        const RERANKER_ALPHA = 0.6; // 60% RRF, 40% reranker
+                        const rerankedMerged = rerankCandidates
+                            .map(item => {
+                            const rrfNorm = item.score / maxRRF; // normalized 0-1
+                            const rerankNorm = rerankScoreMap.get(item.data.nodeId) ?? 0;
+                            return { ...item, score: RERANKER_ALPHA * rrfNorm + (1 - RERANKER_ALPHA) * rerankNorm };
+                        })
+                            .sort((a, b) => b.score - a.score);
+                        merged = [...rerankedMerged, ...nonCandidates];
+                    }
+                }
+            }
+            catch {
+                // Re-ranker is optional — fall back to RRF order silently
+            }
+        }
+        // Build matched_by lookup from RRF sources
+        const matchedByMap = new Map();
+        for (const rrf of rrfMerged) {
+            const key = rrf.nodeId || rrf.filePath;
+            matchedByMap.set(key, rrf.sources.join(' + '));
+        }
+        // Cap candidates before expensive batch lookups
+        merged = merged.slice(0, MAX_BATCH_CANDIDATES);
+        // Step 3: BATCHED process + cluster + content lookup (1-3 queries total, not N×3)
+        const symbolsWithNodeId = [];
+        const definitions = [];
+        for (const item of merged) {
+            const matchedBy = matchedByMap.get(item.data.nodeId ?? '') || matchedByMap.get(item.data.filePath ?? '') || 'bm25';
+            const type = String(item.data.type ?? 'File');
+            if (!item.data.nodeId || type === 'File') {
+                if (type !== 'File') {
+                    definitions.push({ name: item.data.name, type, filePath: item.data.filePath, matched_by: matchedBy });
+                }
+                else if (isIdentifierQuery) {
+                    // Include File results for identifier queries (e.g. "FTS_TABLES", "TYPE_WEIGHTS")
+                    // These help find constants, config, and non-function symbols
+                    definitions.push({ name: item.data.name, type: 'File', filePath: item.data.filePath, matched_by: matchedBy });
+                }
+                // Natural language queries: File-type results are noise, exclude them
+            }
+            else {
+                symbolsWithNodeId.push({ nodeId: item.data.nodeId, score: item.score, data: { ...item.data, matched_by: matchedBy } });
+            }
+        }
+        const processMap = new Map();
+        // Hoisted for F1 full-flow-steps access outside the if block
+        let signatureMap = new Map();
+        let clusterByNode = new Map();
+        if (symbolsWithNodeId.length > 0) {
+            const nodeIdList = symbolsWithNodeId.map(s => `'${String(s.nodeId).replace(/'/g, "''")}'`).join(', ');
+            // Batch process lookup
+            let processRows = [];
+            try {
+                processRows = await executeQuery(repo.id, `
+          MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE n.id IN [${nodeIdList}]
+          RETURN n.id AS nodeId, p.id AS pid, p.label AS label, p.heuristicLabel AS heuristicLabel,
+                 p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `);
+            }
+            catch (e) {
+                logQueryError('query:batch-process-lookup', e);
+            }
+            // Batch cluster lookup
+            let clusterRows = [];
+            try {
+                clusterRows = await executeQuery(repo.id, `
+          MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE n.id IN [${nodeIdList}]
+          RETURN n.id AS nodeId, c.cohesion AS cohesion, c.heuristicLabel AS module
+        `);
+            }
+            catch (e) {
+                logQueryError('query:batch-cluster-info', e);
+            }
+            // Always fetch content for signature extraction (eliminates follow-up Read calls)
+            const contentMap = new Map();
+            // signatureMap hoisted above for F1 access
+            try {
+                const contentRows = await executeQuery(repo.id, `
+          MATCH (n) WHERE n.id IN [${nodeIdList}] RETURN n.id AS nodeId, n.content AS content
+        `);
+                // Build a name lookup for signature extraction
+                const nodeNameMap = new Map();
+                for (const s of symbolsWithNodeId) {
+                    nodeNameMap.set(s.nodeId, String(s.data.name ?? ''));
+                }
+                for (const row of contentRows) {
+                    const nid = String(row.nodeId ?? row[0]);
+                    const cnt = row.content ?? row[1];
+                    if (cnt) {
+                        const full = String(cnt);
+                        // Extract signature: the declaration line only
+                        signatureMap.set(nid, this.extractSignature(full, nodeNameMap.get(nid) || '', ''));
+                        if (includeContent) {
+                            const lines = full.split('\n');
+                            let snippet = '';
+                            for (const line of lines) {
+                                snippet += (snippet ? '\n' : '') + line;
+                                if (snippet.length > 200 || line.includes('{') || line.includes('=>'))
+                                    break;
+                            }
+                            contentMap.set(nid, snippet);
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                logQueryError('query:batch-content-fetch', e);
+            }
+            // Index batched results by nodeId
+            const processRowsByNode = new Map();
+            for (const row of processRows) {
+                const nid = String(row.nodeId ?? row[0]);
+                if (!processRowsByNode.has(nid))
+                    processRowsByNode.set(nid, []);
+                processRowsByNode.get(nid).push(row);
+            }
+            // clusterByNode hoisted above for F1 access
+            for (const row of clusterRows) {
+                const nid = String(row.nodeId ?? row[0]);
+                if (!clusterByNode.has(nid)) {
+                    clusterByNode.set(nid, { cohesion: Number(row.cohesion ?? row[1] ?? 0), module: String(row.module ?? row[2] ?? '') });
+                }
+            }
+            // Assemble using batched data
+            for (const symInfo of symbolsWithNodeId) {
+                const cluster = clusterByNode.get(symInfo.nodeId);
+                const module = cluster?.module || undefined;
+                const content = contentMap.get(symInfo.nodeId);
+                const signature = signatureMap.get(symInfo.nodeId) || symInfo.data.name;
+                const symbolEntry = {
+                    name: symInfo.data.name, type: symInfo.data.type,
+                    filePath: symInfo.data.filePath, startLine: symInfo.data.startLine, endLine: symInfo.data.endLine,
+                    signature,
+                    ...(module ? { module } : {}),
+                    // F9: always include content for small symbols (< 10 lines) for inline display
+                    ...(content ? { content } : {}),
+                    matched_by: symInfo.data.matched_by,
+                };
+                const symProcessRows = processRowsByNode.get(symInfo.nodeId);
+                if (!symProcessRows || symProcessRows.length === 0) {
+                    definitions.push(symbolEntry);
+                }
+                else {
+                    for (const row of symProcessRows) {
+                        const pid = String(row.pid ?? row[1]);
+                        if (!processMap.has(pid)) {
+                            processMap.set(pid, {
+                                id: pid, label: String(row.label ?? row[2] ?? ''),
+                                heuristicLabel: String(row.heuristicLabel ?? row[3] ?? ''),
+                                processType: String(row.processType ?? row[4] ?? ''),
+                                stepCount: Number(row.stepCount ?? row[5] ?? 0),
+                                bestScore: 0, symbolScoreSum: 0, symbolCount: 0, cohesionBoost: 0, symbols: [],
+                            });
+                        }
+                        const proc = processMap.get(pid);
+                        proc.bestScore = Math.max(proc.bestScore, symInfo.score);
+                        proc.symbolScoreSum += symInfo.score;
+                        proc.symbolCount++;
+                        proc.cohesionBoost = Math.max(proc.cohesionBoost, cluster?.cohesion ?? 0);
+                        proc.symbols.push({ ...symbolEntry, process_id: pid, step_index: Number(row.step ?? row[6] ?? 0) });
+                    }
+                }
+            }
+        }
+        // Step 4: Rank processes — match density + name overlap + score + cohesion
+        // Split query into terms for flow-level name matching
+        const queryTerms = queryLower.split(/\s+/).filter(t => t.length >= 3);
+        const rankedProcesses = Array.from(processMap.values())
+            .map(p => {
+            const breadthBonus = p.symbolCount > 1
+                ? (p.symbolScoreSum - p.bestScore) / (p.symbolCount - 1) * 0.1 * (p.symbolCount - 1)
+                : 0;
+            const baseScore = p.bestScore + breadthBonus + (p.cohesionBoost * COHESION_WEIGHT);
+            // Match density: what fraction of steps in this process matched the search?
+            const matchedSteps = p.symbols.filter((s) => s.matched_by).length;
+            const density = p.stepCount > 0 ? matchedSteps / p.stepCount : 0;
+            // Flow name overlap: how many query terms appear in step names (camelCase split)?
+            const stepNames = p.symbols.map((s) => (s.name || '').toLowerCase()
+                .replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_\-]/g, ' ')).join(' ');
+            const nameOverlap = queryTerms.filter(t => stepNames.includes(t)).length;
+            const nameBoost = queryTerms.length > 0 ? nameOverlap / queryTerms.length : 0;
+            // Name overlap is the strongest relevance signal for flows.
+            // If zero step names overlap with query terms, the flow likely matched on
+            // generic BM25 content, not because it's about the queried concept.
+            const relevanceMult = nameBoost > 0
+                ? (1 + density) * (1 + nameBoost)
+                : 0.1; // 90% penalty — these flows are noise for this query
+            return { ...p, priority: baseScore * relevanceMult };
+        })
+            .sort((a, b) => b.priority - a.priority)
+            .slice(0, processLimit);
+        // Demote server/CLI entry flows for non-server queries
+        const queryMentionsServer = queryLower.includes('server') || queryLower.includes('mcp') || queryLower.includes('http') || queryLower.includes('api');
+        if (!queryMentionsServer && rankedProcesses.length > 1) {
+            const SERVER_ENTRY_PREFIXES = ['createserver', 'mcpcommand', 'startmcpserver', 'handlerequest', 'servecommand', 'setupcommand', 'statuscommand', 'listcommand', 'cleancommand'];
+            for (const proc of rankedProcesses) {
+                const entryName = (proc.heuristicLabel || proc.label || '').toLowerCase().split(' ')[0];
+                if (SERVER_ENTRY_PREFIXES.some(p => entryName.includes(p))) {
+                    proc.priority *= 0.5;
+                }
+            }
+            rankedProcesses.sort((a, b) => b.priority - a.priority);
+        }
+        const processes = rankedProcesses.map(p => ({
+            id: p.id, summary: p.heuristicLabel || p.label,
+            priority: Math.round(p.priority * 1000) / 1000,
+            symbol_count: p.symbols.length, process_type: p.processType, step_count: p.stepCount,
+        }));
+        // F1: Fetch ALL steps for top processes so LLM sees the full flow, not just matched symbols
+        const matchedNodeIds = new Set(symbolsWithNodeId.map(s => s.nodeId));
+        const topProcIds = rankedProcesses.map(p => p.id);
+        let allStepsMap = new Map(); // pid -> all steps
+        if (topProcIds.length > 0) {
+            try {
+                const procIdList = topProcIds.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
+                const allStepsRows = await executeQuery(repo.id, `
+          MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE p.id IN [${procIdList}]
+          RETURN s.id AS nodeId, s.name AS name, labels(s) AS type, s.filePath AS filePath, s.startLine AS startLine,
+                 p.id AS pid, r.step AS step
+          ORDER BY p.id, r.step
+        `);
+                for (const row of allStepsRows) {
+                    const pid = String(row.pid ?? row[5]);
+                    if (!allStepsMap.has(pid))
+                        allStepsMap.set(pid, []);
+                    const nodeId = String(row.nodeId ?? row[0]);
+                    const sig = signatureMap.get(nodeId);
+                    allStepsMap.get(pid).push({
+                        nodeId,
+                        name: String(row.name ?? row[1]),
+                        type: String(row.type ?? row[2] ?? 'Symbol'),
+                        filePath: String(row.filePath ?? row[3] ?? ''),
+                        startLine: row.startLine ?? row[4],
+                        step_index: Number(row.step ?? row[6] ?? 0),
+                        matched: matchedNodeIds.has(nodeId),
+                        signature: sig || String(row.name ?? row[1]),
+                        module: clusterByNode.get(nodeId)?.module,
+                    });
+                }
+            }
+            catch (e) {
+                logQueryError('query:full-flow-steps', e);
+            }
+        }
+        // Build full process symbols: matched symbols enriched, plus unmatched steps for context
+        const fullProcessSymbols = [];
+        for (const proc of rankedProcesses) {
+            const allSteps = allStepsMap.get(proc.id) || [];
+            const matchedSymMap = new Map(proc.symbols.map((s) => [s.step_index, s]));
+            if (allSteps.length > 0) {
+                // Use full steps, preferring matched symbol data where available
+                for (const step of allSteps.slice(0, maxSymbolsPerProcess)) {
+                    const matched = matchedSymMap.get(step.step_index);
+                    fullProcessSymbols.push(matched || { ...step, process_id: proc.id, matched_by: null });
+                }
+            }
+            else {
+                // Fallback: just use matched symbols
+                fullProcessSymbols.push(...proc.symbols.slice(0, maxSymbolsPerProcess));
+            }
+        }
+        const seen = new Set();
+        const dedupedSymbols = fullProcessSymbols.filter(s => {
+            const key = `${s.process_id || ''}:${s.nodeId || s.name}:${s.step_index}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+        return { processes, process_symbols: dedupedSymbols, definitions: definitions.slice(0, DEFAULT_MAX_DEFINITIONS), _searchQuery: searchQuery };
+    }
+    /**
+     * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
+     */
+    async bm25Search(repo, query, limit) {
+        const { searchFTSFromLbug } = await import('../../core/search/bm25-index.js');
+        const { expandQuery } = await import('../../core/search/query-expansion.js');
+        const { PRF_SPARSE_THRESHOLD, PRF_WEAK_SCORE_THRESHOLD } = await import('../../core/search/types.js');
+        try {
+            let results = await searchFTSFromLbug(query, limit, repo.id);
+            // Pseudo-relevance feedback: expand when results are sparse OR top score is weak
+            const topScore = results.length > 0 ? results[0].score : 0;
+            const shouldExpand = results.length > 0 && (results.length < PRF_SPARSE_THRESHOLD || topScore < PRF_WEAK_SCORE_THRESHOLD);
+            if (shouldExpand) {
+                const topSymbolNames = results.slice(0, 3).map(r => r.name);
+                const expandedQuery = expandQuery(query, topSymbolNames);
+                if (expandedQuery !== query) {
+                    const expandedResults = await searchFTSFromLbug(expandedQuery, limit, repo.id);
+                    const seen = new Set(results.map(r => r.nodeId));
+                    for (const r of expandedResults) {
+                        if (!seen.has(r.nodeId)) {
+                            results.push(r);
+                            seen.add(r.nodeId);
+                        }
+                    }
+                    results = results.slice(0, limit);
+                }
+            }
+            // Map to the shape expected by the query pipeline
+            return results.map(r => ({
+                nodeId: r.nodeId,
+                name: r.name,
+                type: r.type,
+                filePath: r.filePath,
+                startLine: r.startLine,
+                endLine: r.endLine,
+                bm25Score: r.score,
+            }));
+        }
+        catch (err) {
+            console.error('Code Mapper: BM25/FTS search failed (FTS indexes may not exist) -', err.message);
+            return [];
+        }
+    }
+    /**
+     * Semantic vector search helper
+     */
+    async semanticSearch(repo, query, limit) {
+        try {
+            // Check if embedding table exists before loading the model (avoids heavy model init when embeddings are off)
+            const tableCheck = await executeQuery(repo.id, `MATCH (e:CodeEmbedding) RETURN COUNT(*) AS cnt LIMIT 1`);
+            if (!tableCheck.length || (tableCheck[0].cnt ?? tableCheck[0][0]) === 0)
+                return [];
+            const { DEFAULT_MAX_SEMANTIC_DISTANCE } = await import('../../core/search/types.js');
+            const { embedQuery, getEmbeddingDims } = await import('../core/embedder.js');
+            const queryVec = await embedQuery(query);
+            const dims = getEmbeddingDims();
+            const queryVecStr = `[${queryVec.join(',')}]`;
+            const vectorQuery = `
+        CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx',
+          CAST(${queryVecStr} AS FLOAT[${dims}]), ${limit})
+        YIELD node AS emb, distance
+        RETURN emb.nodeId AS nodeId, distance
+        ORDER BY distance
+      `;
+            const embResults = await executeQuery(repo.id, vectorQuery);
+            if (embResults.length === 0)
+                return [];
+            // Filter by distance threshold — cut irrelevant results before RRF merge
+            const filteredResults = embResults.filter(r => Number(r.distance ?? r[1] ?? 1) < DEFAULT_MAX_SEMANTIC_DISTANCE);
+            if (filteredResults.length === 0)
+                return [];
+            // Batch metadata fetch — single query instead of N per-row queries
+            const nodeIds = filteredResults.map(r => String(r.nodeId ?? r[0]));
+            const distanceMap = new Map();
+            for (const r of filteredResults) {
+                distanceMap.set(String(r.nodeId ?? r[0]), Number(r.distance ?? r[1] ?? 1));
+            }
+            const idList = nodeIds.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
+            let metaRows = [];
+            try {
+                metaRows = await executeQuery(repo.id, `
+          MATCH (n) WHERE n.id IN [${idList}]
+          RETURN n.id AS nodeId, n.name AS name, labels(n) AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+        `);
+            }
+            catch { }
+            return metaRows.map(row => {
+                const nid = String(row.nodeId ?? row[0]);
+                return {
+                    nodeId: nid,
+                    name: String(row.name ?? row[1] ?? ''),
+                    type: String(row.type ?? row[2] ?? 'Unknown'),
+                    filePath: String(row.filePath ?? row[3] ?? ''),
+                    distance: distanceMap.get(nid) ?? 1,
+                    startLine: row.startLine ?? row[4],
+                    endLine: row.endLine ?? row[5],
+                };
+            });
+        }
+        catch {
+            // Expected when embeddings are disabled — silently fall back to BM25-only
+            return [];
+        }
+    }
+    async executeCypher(repoName, query) {
+        const repo = await this.resolveRepo(repoName);
+        return this.cypher(repo, { query });
+    }
+    async cypher(repo, params) {
+        await this.ensureInitialized(repo.id);
+        if (!isLbugReady(repo.id)) {
+            return { error: 'LadybugDB not ready. Index may be corrupted.' };
+        }
+        // Block write operations (defense-in-depth — DB is already read-only)
+        if (CYPHER_WRITE_RE.test(params.query)) {
+            return { error: 'Write operations (CREATE, DELETE, SET, MERGE, REMOVE, DROP, ALTER, COPY, DETACH) are not allowed. The knowledge graph is read-only.' };
+        }
+        try {
+            const result = await executeQuery(repo.id, params.query);
+            return result;
+        }
+        catch (err) {
+            return { error: err.message || 'Query failed' };
+        }
+    }
+    /** Format raw Cypher result rows as a markdown table, with raw fallback */
+    formatCypherAsMarkdown(result) {
+        if (!Array.isArray(result) || result.length === 0)
+            return result;
+        const firstRow = result[0];
+        if (typeof firstRow !== 'object' || firstRow === null)
+            return result;
+        const keys = Object.keys(firstRow);
+        if (keys.length === 0)
+            return result;
+        const header = '| ' + keys.join(' | ') + ' |';
+        const separator = '| ' + keys.map(() => '---').join(' | ') + ' |';
+        const dataRows = result.map((row) => '| ' + keys.map(k => {
+            const v = row[k];
+            if (v === null || v === undefined)
+                return '';
+            if (typeof v === 'object')
+                return JSON.stringify(v);
+            return String(v);
+        }).join(' | ') + ' |');
+        return {
+            markdown: [header, separator, ...dataRows].join('\n'),
+            row_count: result.length,
+        };
+    }
+    /** Aggregate same-named clusters by heuristicLabel, filtering tiny clusters (<5 symbols) */
+    aggregateClusters(clusters) {
+        const groups = new Map();
+        for (const c of clusters) {
+            const label = c.heuristicLabel || c.label || 'Unknown';
+            const symbols = c.symbolCount || 0;
+            const cohesion = c.cohesion || 0;
+            const existing = groups.get(label);
+            if (!existing) {
+                groups.set(label, { ids: [c.id], totalSymbols: symbols, weightedCohesion: cohesion * symbols, largest: c });
+            }
+            else {
+                existing.ids.push(c.id);
+                existing.totalSymbols += symbols;
+                existing.weightedCohesion += cohesion * symbols;
+                if (symbols > (existing.largest.symbolCount || 0)) {
+                    existing.largest = c;
+                }
+            }
+        }
+        return Array.from(groups.entries())
+            .map(([label, g]) => ({
+            id: g.largest.id,
+            label,
+            heuristicLabel: label,
+            symbolCount: g.totalSymbols,
+            cohesion: g.totalSymbols > 0 ? g.weightedCohesion / g.totalSymbols : 0,
+            subCommunities: g.ids.length,
+        }))
+            .filter(c => c.symbolCount >= 5)
+            .sort((a, b) => b.symbolCount - a.symbolCount);
+    }
+    async overview(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const limit = params.limit || 20;
+        const result = {
+            repo: repo.name,
+            repoPath: repo.repoPath,
+            stats: repo.stats,
+            indexedAt: repo.indexedAt,
+            lastCommit: repo.lastCommit,
+        };
+        if (params.showClusters !== false) {
+            try {
+                // Fetch more raw communities than the display limit so aggregation has enough data
+                const rawLimit = Math.max(limit * 5, 200);
+                const clusters = await executeQuery(repo.id, `
+          MATCH (c:Community)
+          RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+          ORDER BY c.symbolCount DESC
+          LIMIT ${rawLimit}
+        `);
+                const rawClusters = clusters.map((c) => ({
+                    id: c.id || c[0],
+                    label: c.label || c[1],
+                    heuristicLabel: c.heuristicLabel || c[2],
+                    cohesion: c.cohesion || c[3],
+                    symbolCount: c.symbolCount || c[4],
+                }));
+                result.clusters = this.aggregateClusters(rawClusters).slice(0, limit);
+            }
+            catch {
+                result.clusters = [];
+            }
+        }
+        if (params.showProcesses !== false) {
+            try {
+                const processes = await executeQuery(repo.id, `
+          MATCH (p:Process)
+          RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+          ORDER BY p.stepCount DESC
+          LIMIT ${limit}
+        `);
+                result.processes = processes.map((p) => ({
+                    id: p.id || p[0],
+                    label: p.label || p[1],
+                    heuristicLabel: p.heuristicLabel || p[2],
+                    processType: p.processType || p[3],
+                    stepCount: p.stepCount || p[4],
+                }));
+            }
+            catch {
+                result.processes = [];
+            }
+        }
+        return result;
+    }
+    /** Context tool: 360-degree symbol view with categorized refs and disambiguation */
+    async context(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { name, uid, file_path, include_content } = params;
+        if (!name && !uid) {
+            return { error: 'Either "name" or "uid" parameter is required.' };
+        }
+        // Step 1: Find the symbol
+        let symbols;
+        if (uid) {
+            // Always fetch content for signature extraction (token-efficient alternative to full Read calls)
+            symbols = await executeParameterized(repo.id, `
+        MATCH (n {id: $uid})
+        RETURN n.id AS id, n.name AS name, labels(n) AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content
+        LIMIT 1
+      `, { uid });
+        }
+        else {
+            const isQualified = name.includes('/') || name.includes(':');
+            let whereClause;
+            let queryParams;
+            if (file_path) {
+                whereClause = `WHERE n.name = $symName AND n.filePath CONTAINS $filePath`;
+                queryParams = { symName: name, filePath: file_path };
+            }
+            else if (isQualified) {
+                whereClause = `WHERE n.id = $symName OR n.name = $symName`;
+                queryParams = { symName: name };
+            }
+            else {
+                whereClause = `WHERE n.name = $symName`;
+                queryParams = { symName: name };
+            }
+            symbols = await executeParameterized(repo.id, `
+        MATCH (n) ${whereClause}
+        RETURN n.id AS id, n.name AS name, labels(n) AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content
+        LIMIT 10
+      `, queryParams);
+        }
+        if (symbols.length === 0) {
+            return { error: `Symbol '${name || uid}' not found` };
+        }
+        // Step 2: Disambiguation
+        if (symbols.length > 1 && !uid) {
+            return {
+                status: 'ambiguous',
+                message: `Found ${symbols.length} symbols matching '${name}'. Use uid or file_path to disambiguate.`,
+                candidates: symbols.map((s) => ({
+                    uid: s.id || s[0],
+                    name: s.name || s[1],
+                    kind: s.type || s[2],
+                    filePath: s.filePath || s[3],
+                    line: s.startLine || s[4],
+                })),
+            };
+        }
+        // Step 3: Build full context
+        const sym = symbols[0];
+        const symId = sym.id || sym[0];
+        // Categorized incoming refs (F3: line numbers, E1: UNION ALL for single round-trip)
+        // KuzuDB bug: `r.type IN [list]` drops results. Use UNION ALL as workaround.
+        const REL_TYPES = ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'DEPENDS_ON', 'PROVIDES'];
+        // Incoming: use lower confidence threshold (0.5) — callers are more important to see even if fuzzy
+        const incomingUnion = REL_TYPES.map(t => `MATCH (caller)-[r:CodeRelation {type: '${t}'}]->(n {id: '${symId.replace(/'/g, "''")}'}) WHERE r.confidence >= 0.5 RETURN '${t}' AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller) AS kind, caller.startLine AS startLine, r.reason AS reason LIMIT 15`).join(' UNION ALL ');
+        let incomingRows = [];
+        try {
+            incomingRows = await executeQuery(repo.id, incomingUnion);
+        }
+        catch { }
+        // Outgoing refs — lower threshold to 0.5 so dynamic imports (global tier) show up,
+        // but exclude generic method names that produce false positives at low confidence
+        const GENERIC_NAMES_EXCLUDE = ['has', 'get', 'set', 'add', 'remove', 'delete', 'close', 'stop', 'clear', 'reset', 'toString', 'valueOf', 'push', 'pop', 'entries', 'keys', 'values'];
+        const genericExclude = GENERIC_NAMES_EXCLUDE.map(n => `'${n}'`).join(', ');
+        const outgoingUnion = REL_TYPES.map(t => `MATCH (n {id: '${symId.replace(/'/g, "''")}'} )-[r:CodeRelation {type: '${t}'}]->(target) WHERE r.confidence >= 0.5 AND NOT target.name IN [${genericExclude}] RETURN '${t}' AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target) AS kind, target.startLine AS startLine, r.reason AS reason, r.callLine AS callLine LIMIT 15`).join(' UNION ALL ');
+        let outgoingRows = [];
+        try {
+            outgoingRows = await executeQuery(repo.id, outgoingUnion);
+        }
+        catch { }
+        // Process participation
+        let processRows = [];
+        try {
+            processRows = await executeParameterized(repo.id, `
+        MATCH (n {id: $symId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+        RETURN p.id AS pid, p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
+      `, { symId });
+        }
+        catch (e) {
+            logQueryError('context:process-participation', e);
+        }
+        // C5: Module/cluster membership
+        let module;
+        try {
+            const clusterRows = await executeParameterized(repo.id, `
+        MATCH (n {id: $symId})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+        RETURN c.heuristicLabel AS module
+        LIMIT 1
+      `, { symId });
+            if (clusterRows.length > 0) {
+                module = String(clusterRows[0].module ?? clusterRows[0][0] ?? '');
+            }
+        }
+        catch { }
+        // Helper to categorize refs
+        const categorize = (rows) => {
+            const cats = {};
+            for (const row of rows) {
+                const relType = (row.relType || row[0] || '').toLowerCase();
+                const entry = {
+                    uid: row.uid || row[1],
+                    name: row.name || row[2],
+                    filePath: row.filePath || row[3],
+                    kind: row.kind || row[4] || 'Symbol',
+                    startLine: row.startLine ?? row[5],
+                    reason: row.reason || row[6] || '',
+                    callLine: row.callLine ?? row[7],
+                };
+                if (!cats[relType])
+                    cats[relType] = [];
+                cats[relType].push(entry);
+            }
+            return cats;
+        };
+        // Always extract signature for compact display
+        const rawContent = sym.content || sym[6] || '';
+        const signature = rawContent ? this.extractSignature(String(rawContent), sym.name || sym[1], sym.type || sym[2]) : (sym.name || sym[1]);
+        return {
+            status: 'found',
+            symbol: {
+                uid: sym.id || sym[0],
+                name: sym.name || sym[1],
+                kind: sym.type || sym[2],
+                filePath: sym.filePath || sym[3],
+                startLine: sym.startLine || sym[4],
+                endLine: sym.endLine || sym[5],
+                signature,
+                ...(module ? { module } : {}),
+                ...(include_content && rawContent ? { content: rawContent } : {}),
+            },
+            incoming: categorize(incomingRows),
+            outgoing: categorize(outgoingRows),
+            processes: processRows.map((r) => ({
+                id: r.pid || r[0],
+                name: r.label || r[1],
+                step_index: r.step || r[2],
+                step_count: r.stepCount || r[3],
+            })),
+        };
+    }
+    /** Legacy explore for backwards compatibility with resources.ts */
+    async explore(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { name, type } = params;
+        if (type === 'symbol') {
+            return this.context(repo, { name });
+        }
+        if (type === 'cluster') {
+            const clusters = await executeParameterized(repo.id, `
+        MATCH (c:Community)
+        WHERE c.label = $clusterName OR c.heuristicLabel = $clusterName
+        RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+      `, { clusterName: name });
+            if (clusters.length === 0)
+                return { error: `Cluster '${name}' not found` };
+            const rawClusters = clusters.map((c) => ({
+                id: c.id || c[0], label: c.label || c[1], heuristicLabel: c.heuristicLabel || c[2],
+                cohesion: c.cohesion || c[3], symbolCount: c.symbolCount || c[4],
+            }));
+            let totalSymbols = 0, weightedCohesion = 0;
+            for (const c of rawClusters) {
+                const s = c.symbolCount || 0;
+                totalSymbols += s;
+                weightedCohesion += (c.cohesion || 0) * s;
+            }
+            const members = await executeParameterized(repo.id, `
+        MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+        WHERE c.label = $clusterName OR c.heuristicLabel = $clusterName
+        RETURN DISTINCT n.name AS name, labels(n) AS type, n.filePath AS filePath
+        LIMIT 30
+      `, { clusterName: name });
+            return {
+                cluster: {
+                    id: rawClusters[0].id,
+                    label: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                    heuristicLabel: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                    cohesion: totalSymbols > 0 ? weightedCohesion / totalSymbols : 0,
+                    symbolCount: totalSymbols,
+                    subCommunities: rawClusters.length,
+                },
+                members: members.map((m) => ({
+                    name: m.name || m[0], type: m.type || m[1], filePath: m.filePath || m[2],
+                })),
+            };
+        }
+        if (type === 'process') {
+            const processes = await executeParameterized(repo.id, `
+        MATCH (p:Process)
+        WHERE p.label = $processName OR p.heuristicLabel = $processName
+        RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+        LIMIT 1
+      `, { processName: name });
+            if (processes.length === 0)
+                return { error: `Process '${name}' not found` };
+            const proc = processes[0];
+            const procId = proc.id || proc[0];
+            const steps = await executeParameterized(repo.id, `
+        MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p {id: $procId})
+        RETURN n.name AS name, labels(n) AS type, n.filePath AS filePath, r.step AS step
+        ORDER BY r.step
+      `, { procId });
+            return {
+                process: {
+                    id: procId, label: proc.label || proc[1], heuristicLabel: proc.heuristicLabel || proc[2],
+                    processType: proc.processType || proc[3], stepCount: proc.stepCount || proc[4],
+                },
+                steps: steps.map((s) => ({
+                    step: s.step || s[3], name: s.name || s[0], type: s.type || s[1], filePath: s.filePath || s[2],
+                })),
+            };
+        }
+        return { error: 'Invalid type. Use: symbol, cluster, or process' };
+    }
+    /** Detect changes: git-diff impact analysis mapping changed lines to symbols and processes */
+    async detectChanges(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const scope = params.scope || 'unstaged';
+        const { execFileSync } = await import('child_process');
+        // Build git diff args based on scope (using execFileSync to avoid shell injection)
+        let diffArgs;
+        switch (scope) {
+            case 'staged':
+                diffArgs = ['diff', '--staged', '--name-only'];
+                break;
+            case 'all':
+                diffArgs = ['diff', 'HEAD', '--name-only'];
+                break;
+            case 'compare':
+                if (!params.base_ref)
+                    return { error: 'base_ref is required for "compare" scope' };
+                diffArgs = ['diff', params.base_ref, '--name-only'];
+                break;
+            case 'unstaged':
+            default:
+                diffArgs = ['diff', '--name-only'];
+                break;
+        }
+        let changedFiles;
+        let diffStatMap = new Map(); // file -> "+N/-M"
+        try {
+            const output = execFileSync('git', diffArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
+            changedFiles = output.trim().split('\n').filter(f => f.length > 0);
+        }
+        catch (err) {
+            return { error: `Git diff failed: ${err.message}` };
+        }
+        // F3: Get line-level diff stats per file
+        try {
+            const statArgs = [...diffArgs.filter(a => a !== '--name-only'), '--numstat'];
+            const statOutput = execFileSync('git', statArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
+            for (const line of statOutput.trim().split('\n')) {
+                const parts = line.split('\t');
+                if (parts.length >= 3) {
+                    const added = parts[0] === '-' ? '?' : parts[0];
+                    const removed = parts[1] === '-' ? '?' : parts[1];
+                    diffStatMap.set(parts[2], `+${added}/-${removed}`);
+                }
+            }
+        }
+        catch { }
+        if (changedFiles.length === 0) {
+            return {
+                summary: { changed_count: 0, affected_count: 0, risk_level: 'none', message: 'No changes detected.' },
+                changed_symbols: [],
+                affected_processes: [],
+            };
+        }
+        // Map changed files to indexed symbols
+        const changedSymbols = [];
+        for (const file of changedFiles) {
+            const normalizedFile = file.replace(/\\/g, '/');
+            try {
+                const symbols = await executeParameterized(repo.id, `
+          MATCH (n) WHERE n.filePath CONTAINS $filePath
+          RETURN n.id AS id, n.name AS name, labels(n) AS type, n.filePath AS filePath, n.startLine AS startLine
+          LIMIT 20
+        `, { filePath: normalizedFile });
+                for (const sym of symbols) {
+                    changedSymbols.push({
+                        id: sym.id || sym[0],
+                        name: sym.name || sym[1],
+                        type: sym.type || sym[2],
+                        filePath: sym.filePath || sym[3],
+                        startLine: sym.startLine ?? sym[4],
+                        change_type: 'Modified',
+                    });
+                }
+            }
+            catch (e) {
+                logQueryError('detect-changes:file-symbols', e);
+            }
+        }
+        // Fix 7: Detect REAL interface changes by comparing signature text
+        // Read each changed file from disk and compare the declaration line against
+        // the stored n.content signature. Only flags symbols whose actual signature changed,
+        // not just any symbol on a line that git touched.
+        const fileContentCache = new Map();
+        const readFileContent = async (fp) => {
+            if (fileContentCache.has(fp))
+                return fileContentCache.get(fp);
+            try {
+                const full = path.resolve(repo.repoPath, fp);
+                const content = await fs.readFile(full, 'utf-8');
+                fileContentCache.set(fp, content);
+                return content;
+            }
+            catch {
+                return null;
+            }
+        };
+        // Batch-fetch stored signatures from graph for changed symbols
+        const symIds = changedSymbols.filter(s => s.id).map(s => `'${String(s.id).replace(/'/g, "''")}'`);
+        const storedSigs = new Map();
+        if (symIds.length > 0) {
+            try {
+                const sigRows = await executeParameterized(repo.id, `
+          MATCH (n) WHERE n.id IN [${symIds.join(', ')}]
+          RETURN n.id AS id, n.content AS content
+        `, {});
+                for (const row of sigRows) {
+                    const id = String(row.id ?? row[0]);
+                    const content = row.content ?? row[1];
+                    if (content) {
+                        storedSigs.set(id, this.extractSignature(String(content), '', ''));
+                    }
+                }
+            }
+            catch { }
+        }
+        // Compare stored signatures against current file content
+        for (const sym of changedSymbols) {
+            if (!sym.id || !sym.filePath || !sym.name)
+                continue;
+            const storedSig = storedSigs.get(sym.id);
+            if (!storedSig)
+                continue;
+            const content = await readFileContent(sym.filePath);
+            if (!content)
+                continue;
+            // Find the current declaration line near the symbol's startLine
+            const lines = content.split('\n');
+            const searchStart = Math.max(0, (sym.startLine || 1) - 6);
+            const searchEnd = Math.min(lines.length, (sym.startLine || 1) + 6);
+            let currentSig = null;
+            const namePattern = new RegExp(`\\b${sym.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+            for (let i = searchStart; i < searchEnd; i++) {
+                if (namePattern.test(lines[i])) {
+                    currentSig = this.extractSignature(lines.slice(Math.max(0, i - 1), i + 5).join('\n'), sym.name, sym.type);
+                    break;
+                }
+            }
+            if (currentSig && storedSig !== currentSig) {
+                sym.change_type = 'interface changed';
+            }
+        }
+        // Find affected processes
+        const affectedProcesses = new Map();
+        for (const sym of changedSymbols) {
+            try {
+                const procs = await executeParameterized(repo.id, `
+          MATCH (n {id: $nodeId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          RETURN p.id AS pid, p.heuristicLabel AS label, p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `, { nodeId: sym.id });
+                for (const proc of procs) {
+                    const pid = proc.pid || proc[0];
+                    if (!affectedProcesses.has(pid)) {
+                        affectedProcesses.set(pid, {
+                            id: pid,
+                            name: proc.label || proc[1],
+                            process_type: proc.processType || proc[2],
+                            step_count: proc.stepCount || proc[3],
+                            changed_steps: [],
+                        });
+                    }
+                    affectedProcesses.get(pid).changed_steps.push({
+                        symbol: sym.name,
+                        step: proc.step || proc[4],
+                    });
+                }
+            }
+            catch (e) {
+                logQueryError('detect-changes:process-lookup', e);
+            }
+        }
+        const processCount = affectedProcesses.size;
+        const risk = processCount === 0 ? 'low' : processCount <= 5 ? 'medium' : processCount <= 15 ? 'high' : 'critical';
+        return {
+            summary: {
+                changed_count: changedSymbols.length,
+                affected_count: processCount,
+                changed_files: changedFiles.length,
+                risk_level: risk,
+            },
+            changed_symbols: changedSymbols,
+            affected_processes: Array.from(affectedProcesses.values()),
+            diff_stats: Object.fromEntries(diffStatMap), // F3: line stats per file
+        };
+    }
+    /** Rename tool: multi-file coordinated rename using graph (high confidence) + text search */
+    async rename(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { new_name, file_path } = params;
+        const dry_run = params.dry_run ?? true;
+        if (!params.symbol_name && !params.symbol_uid) {
+            return { error: 'Either symbol_name or symbol_uid is required.' };
+        }
+        /** Guard: ensure a file path resolves within the repo root (prevents path traversal) */
+        const assertSafePath = (filePath) => {
+            const full = path.resolve(repo.repoPath, filePath);
+            if (!full.startsWith(repo.repoPath + path.sep) && full !== repo.repoPath) {
+                throw new Error(`Path traversal blocked: ${filePath}`);
+            }
+            return full;
+        };
+        // Step 1: Find the target symbol (reuse context's lookup)
+        const lookupResult = await this.context(repo, {
+            name: params.symbol_name,
+            uid: params.symbol_uid,
+            file_path,
+        });
+        if (lookupResult.status === 'ambiguous') {
+            return lookupResult; // pass disambiguation through
+        }
+        if (lookupResult.error) {
+            return lookupResult;
+        }
+        const sym = lookupResult.symbol;
+        const oldName = sym.name;
+        if (oldName === new_name) {
+            return { error: 'New name is the same as the current name.' };
+        }
+        // Step 2: Collect edits from graph (high confidence)
+        const changes = new Map();
+        const addEdit = (filePath, line, oldText, newText, confidence) => {
+            if (!changes.has(filePath)) {
+                changes.set(filePath, { file_path: filePath, edits: [] });
+            }
+            changes.get(filePath).edits.push({ line, old_text: oldText, new_text: newText, confidence });
+        };
+        // The definition itself
+        if (sym.filePath && sym.startLine) {
+            try {
+                const content = await fs.readFile(assertSafePath(sym.filePath), 'utf-8');
+                const lines = content.split('\n');
+                const lineIdx = sym.startLine - 1;
+                if (lineIdx >= 0 && lineIdx < lines.length && lines[lineIdx].includes(oldName)) {
+                    const defRegex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+                    addEdit(sym.filePath, sym.startLine, lines[lineIdx].trim(), lines[lineIdx].replace(defRegex, new_name).trim(), 'graph');
+                }
+            }
+            catch (e) {
+                logQueryError('rename:read-definition', e);
+            }
+        }
+        // All incoming refs from graph (callers, importers, etc.)
+        const allIncoming = [
+            ...(lookupResult.incoming.calls || []),
+            ...(lookupResult.incoming.imports || []),
+            ...(lookupResult.incoming.extends || []),
+            ...(lookupResult.incoming.implements || []),
+        ];
+        let graphEdits = changes.size > 0 ? 1 : 0; // count definition edit
+        for (const ref of allIncoming) {
+            if (!ref.filePath)
+                continue;
+            try {
+                const content = await fs.readFile(assertSafePath(ref.filePath), 'utf-8');
+                const lines = content.split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].includes(oldName)) {
+                        addEdit(ref.filePath, i + 1, lines[i].trim(), lines[i].replace(new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g'), new_name).trim(), 'graph');
+                        graphEdits++;
+                        break; // one edit per file from graph refs
+                    }
+                }
+            }
+            catch (e) {
+                logQueryError('rename:read-ref', e);
+            }
+        }
+        // Step 3: Text search for refs the graph might have missed
+        let astSearchEdits = 0;
+        const graphFiles = new Set([sym.filePath, ...allIncoming.map(r => r.filePath)].filter(Boolean));
+        // Simple text search across the repo for the old name (in files not already covered by graph)
+        try {
+            const { execFileSync } = await import('child_process');
+            const rgArgs = [
+                '-l',
+                '--type-add', 'code:*.{ts,tsx,js,jsx,py,go,rs,java,c,h,cpp,cc,cxx,hpp,hxx,hh,cs,php,swift}',
+                '-t', 'code',
+                `\\b${oldName}\\b`,
+                '.',
+            ];
+            const output = execFileSync('rg', rgArgs, { cwd: repo.repoPath, encoding: 'utf-8', timeout: 5000 });
+            const files = output.trim().split('\n').filter(f => f.length > 0);
+            for (const file of files) {
+                const normalizedFile = file.replace(/\\/g, '/').replace(/^\.\//, '');
+                if (graphFiles.has(normalizedFile))
+                    continue; // already covered by graph
+                try {
+                    const content = await fs.readFile(assertSafePath(normalizedFile), 'utf-8');
+                    const lines = content.split('\n');
+                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+                    for (let i = 0; i < lines.length; i++) {
+                        regex.lastIndex = 0;
+                        if (regex.test(lines[i])) {
+                            regex.lastIndex = 0;
+                            addEdit(normalizedFile, i + 1, lines[i].trim(), lines[i].replace(regex, new_name).trim(), 'text_search');
+                            astSearchEdits++;
+                        }
+                    }
+                }
+                catch (e) {
+                    logQueryError('rename:text-search-read', e);
+                }
+            }
+        }
+        catch (e) {
+            logQueryError('rename:ripgrep', e);
+        }
+        // Step 4: Apply or preview
+        const allChanges = Array.from(changes.values());
+        const totalEdits = allChanges.reduce((sum, c) => sum + c.edits.length, 0);
+        if (!dry_run) {
+            // Apply edits to files
+            for (const change of allChanges) {
+                try {
+                    const fullPath = assertSafePath(change.file_path);
+                    let content = await fs.readFile(fullPath, 'utf-8');
+                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+                    content = content.replace(regex, new_name);
+                    await fs.writeFile(fullPath, content, 'utf-8');
+                }
+                catch (e) {
+                    logQueryError('rename:apply-edit', e);
+                }
+            }
+        }
+        return {
+            status: 'success',
+            old_name: oldName,
+            new_name,
+            files_affected: allChanges.length,
+            total_edits: totalEdits,
+            graph_edits: graphEdits,
+            text_search_edits: astSearchEdits,
+            changes: allChanges,
+            applied: !dry_run,
+        };
+    }
+    async impact(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { target, direction } = params;
+        const maxDepth = params.maxDepth || 3;
+        const rawRelTypes = params.relationTypes && params.relationTypes.length > 0
+            ? params.relationTypes.filter(t => VALID_RELATION_TYPES.has(t))
+            : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'DEPENDS_ON', 'PROVIDES'];
+        const relationTypes = rawRelTypes.length > 0 ? rawRelTypes : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'DEPENDS_ON', 'PROVIDES'];
+        const includeTests = params.includeTests ?? false;
+        const minConfidence = params.minConfidence ?? 0.6;
+        // d=1 uses lower threshold (0.5) — direct callers are critical, even dynamic imports
+        // d=2+ uses 0.6 to avoid noise explosion from transitive fuzzy edges
+        const d1Confidence = Math.min(minConfidence, 0.5);
+        // C6: Use OR chain instead of IN list — KuzuDB IN list silently drops results
+        const relTypeFilter = relationTypes.map(t => `r.type = '${t}'`).join(' OR ');
+        // Generic method names that produce false positives at low confidence
+        const IMPACT_GENERIC_NAMES = new Set(['has', 'get', 'set', 'add', 'remove', 'delete', 'close', 'stop', 'clear', 'reset', 'toString', 'valueOf', 'push', 'pop', 'entries', 'keys', 'values']);
+        const targets = await executeParameterized(repo.id, `
+      MATCH (n)
+      WHERE n.name = $targetName
+      RETURN n.id AS id, n.name AS name, labels(n) AS type, n.filePath AS filePath
+      LIMIT 1
+    `, { targetName: target });
+        if (targets.length === 0)
+            return { error: `Target '${target}' not found` };
+        const sym = targets[0];
+        const symId = sym.id || sym[0];
+        // Safety caps: prevent OOM / segfaults on high-fan-in graphs.
+        // Without caps, a hub with 50 callers explodes: d1=50, d2=1500, d3=45000,
+        // producing ~400KB Cypher WHERE-IN clauses that crash LadybugDB.
+        const MAX_IMPACTED = 500;
+        const MAX_FRONTIER_PER_DEPTH = 200;
+        const impacted = [];
+        const visited = new Set([symId]);
+        let frontier = [symId];
+        let truncated = false;
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+            const nextFrontier = [];
+            // Cap frontier to prevent massive Cypher queries
+            const effectiveFrontier = frontier.length > MAX_FRONTIER_PER_DEPTH
+                ? (truncated = true, frontier.slice(0, MAX_FRONTIER_PER_DEPTH))
+                : frontier;
+            // Batch frontier nodes into a single Cypher query per depth level
+            const idList = effectiveFrontier.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
+            // Per-depth confidence: d=1 uses lower threshold to catch dynamic imports
+            const depthConfidence = depth === 1 ? d1Confidence : minConfidence;
+            const confidenceFilter = depthConfidence > 0 ? ` AND r.confidence >= ${depthConfidence}` : '';
+            const query = direction === 'upstream'
+                ? `MATCH (caller)-[r:CodeRelation]->(n) WHERE n.id IN [${idList}] AND (${relTypeFilter})${confidenceFilter} RETURN n.id AS sourceId, caller.id AS id, caller.name AS name, labels(caller) AS nodeType, caller.filePath AS filePath, r.type AS relType, r.confidence AS confidence`
+                : `MATCH (n)-[r:CodeRelation]->(callee) WHERE n.id IN [${idList}] AND (${relTypeFilter})${confidenceFilter} RETURN n.id AS sourceId, callee.id AS id, callee.name AS name, labels(callee) AS nodeType, callee.filePath AS filePath, r.type AS relType, r.confidence AS confidence`;
+            try {
+                const related = await executeQuery(repo.id, query);
+                for (const rel of related) {
+                    const relId = rel.id || rel[1];
+                    const filePath = rel.filePath || rel[4] || '';
+                    if (!includeTests && isTestFilePath(filePath))
+                        continue;
+                    // Skip generic method names at low confidence (false positives like Map.has → type-env.has)
+                    const relName = rel.name || rel[2] || '';
+                    const relConf = rel.confidence || rel[6] || 1.0;
+                    if (relConf < 0.6 && IMPACT_GENERIC_NAMES.has(relName))
+                        continue;
+                    if (!visited.has(relId)) {
+                        visited.add(relId);
+                        nextFrontier.push(relId);
+                        impacted.push({
+                            depth,
+                            id: relId,
+                            name: rel.name || rel[2],
+                            type: rel.nodeType || rel[3] || 'Symbol',
+                            filePath,
+                            relationType: rel.relType || rel[5],
+                            confidence: rel.confidence || rel[6] || 1.0,
+                        });
+                        // Cap total impacted count
+                        if (impacted.length >= MAX_IMPACTED) {
+                            truncated = true;
+                            break;
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                logQueryError('impact:depth-traversal', e);
+            }
+            if (impacted.length >= MAX_IMPACTED)
+                break;
+            frontier = nextFrontier;
+        }
+        const grouped = {};
+        for (const item of impacted) {
+            if (!grouped[item.depth])
+                grouped[item.depth] = [];
+            grouped[item.depth].push(item);
+        }
+        // ── Enrichment: affected processes, modules, risk ──────────────
+        const directCount = (grouped[1] || []).length;
+        let affectedProcesses = [];
+        let affectedModules = [];
+        if (impacted.length > 0) {
+            const allIds = impacted.map(i => `'${i.id.replace(/'/g, "''")}'`).join(', ');
+            const d1Ids = (grouped[1] || []).map((i) => `'${i.id.replace(/'/g, "''")}'`).join(', ');
+            // Affected processes: which execution flows are broken and at which step
+            const [processRows, moduleRows, directModuleRows] = await Promise.all([
+                executeQuery(repo.id, `
+          MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE s.id IN [${allIds}]
+          RETURN p.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits, MIN(r.step) AS minStep, p.stepCount AS stepCount
+          ORDER BY hits DESC
+          LIMIT 20
+        `).catch(() => []),
+                executeQuery(repo.id, `
+          MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE s.id IN [${allIds}]
+          RETURN c.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits
+          ORDER BY hits DESC
+          LIMIT 20
+        `).catch(() => []),
+                d1Ids ? executeQuery(repo.id, `
+          MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE s.id IN [${d1Ids}]
+          RETURN DISTINCT c.heuristicLabel AS name
+          LIMIT 20
+        `).catch(() => []) : Promise.resolve([]),
+            ]);
+            affectedProcesses = processRows.map((r) => ({
+                name: r.name || r[0],
+                hits: r.hits || r[1],
+                broken_at_step: r.minStep ?? r[2],
+                step_count: r.stepCount ?? r[3],
+            }));
+            const directModuleSet = new Set(directModuleRows.map((r) => r.name || r[0]));
+            affectedModules = moduleRows.map((r) => {
+                const name = r.name || r[0];
+                return {
+                    name,
+                    hits: r.hits || r[1],
+                    impact: directModuleSet.has(name) ? 'direct' : 'indirect',
+                };
+            });
+        }
+        // Risk scoring
+        const processCount = affectedProcesses.length;
+        const moduleCount = affectedModules.length;
+        let risk = 'LOW';
+        if (directCount >= 30 || processCount >= 5 || moduleCount >= 5 || impacted.length >= 200) {
+            risk = 'CRITICAL';
+        }
+        else if (directCount >= 15 || processCount >= 3 || moduleCount >= 3 || impacted.length >= 100) {
+            risk = 'HIGH';
+        }
+        else if (directCount >= 5 || impacted.length >= 30) {
+            risk = 'MEDIUM';
+        }
+        return {
+            target: {
+                id: symId,
+                name: sym.name || sym[1],
+                type: sym.type || sym[2],
+                filePath: sym.filePath || sym[3],
+            },
+            direction,
+            impactedCount: impacted.length,
+            risk,
+            ...(truncated ? { truncated: true } : {}),
+            summary: {
+                direct: directCount,
+                processes_affected: processCount,
+                modules_affected: moduleCount,
+            },
+            affected_processes: affectedProcesses,
+            affected_modules: affectedModules,
+            byDepth: grouped,
+        };
+    }
+    // Direct Graph Queries (for resources.ts)
+    /** Query clusters (communities) directly from graph for getClustersResource */
+    async queryClusters(repoName, limit = 100) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        try {
+            const rawLimit = Math.max(limit * 5, 200);
+            const clusters = await executeQuery(repo.id, `
+        MATCH (c:Community)
+        RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+        ORDER BY c.symbolCount DESC
+        LIMIT ${rawLimit}
+      `);
+            const rawClusters = clusters.map((c) => ({
+                id: c.id || c[0],
+                label: c.label || c[1],
+                heuristicLabel: c.heuristicLabel || c[2],
+                cohesion: c.cohesion || c[3],
+                symbolCount: c.symbolCount || c[4],
+            }));
+            return { clusters: this.aggregateClusters(rawClusters).slice(0, limit) };
+        }
+        catch {
+            return { clusters: [] };
+        }
+    }
+    /** Query processes directly from graph for getProcessesResource */
+    async queryProcesses(repoName, limit = 50) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        try {
+            const processes = await executeQuery(repo.id, `
+        MATCH (p:Process)
+        RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+        ORDER BY p.stepCount DESC
+        LIMIT ${limit}
+      `);
+            return {
+                processes: processes.map((p) => ({
+                    id: p.id || p[0],
+                    label: p.label || p[1],
+                    heuristicLabel: p.heuristicLabel || p[2],
+                    processType: p.processType || p[3],
+                    stepCount: p.stepCount || p[4],
+                })),
+            };
+        }
+        catch {
+            return { processes: [] };
+        }
+    }
+    /** Query cluster detail (members) for getClusterDetailResource */
+    async queryClusterDetail(name, repoName) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        const clusters = await executeParameterized(repo.id, `
+      MATCH (c:Community)
+      WHERE c.label = $clusterName OR c.heuristicLabel = $clusterName
+      RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+    `, { clusterName: name });
+        if (clusters.length === 0)
+            return { error: `Cluster '${name}' not found` };
+        const rawClusters = clusters.map((c) => ({
+            id: c.id || c[0], label: c.label || c[1], heuristicLabel: c.heuristicLabel || c[2],
+            cohesion: c.cohesion || c[3], symbolCount: c.symbolCount || c[4],
+        }));
+        let totalSymbols = 0, weightedCohesion = 0;
+        for (const c of rawClusters) {
+            const s = c.symbolCount || 0;
+            totalSymbols += s;
+            weightedCohesion += (c.cohesion || 0) * s;
+        }
+        const members = await executeParameterized(repo.id, `
+      MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+      WHERE c.label = $clusterName OR c.heuristicLabel = $clusterName
+      RETURN DISTINCT n.name AS name, labels(n) AS type, n.filePath AS filePath
+      LIMIT 30
+    `, { clusterName: name });
+        return {
+            cluster: {
+                id: rawClusters[0].id,
+                label: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                heuristicLabel: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                cohesion: totalSymbols > 0 ? weightedCohesion / totalSymbols : 0,
+                symbolCount: totalSymbols,
+                subCommunities: rawClusters.length,
+            },
+            members: members.map((m) => ({
+                name: m.name || m[0], type: m.type || m[1], filePath: m.filePath || m[2],
+            })),
+        };
+    }
+    /** Query process detail (steps) for getProcessDetailResource */
+    async queryProcessDetail(name, repoName) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        const processes = await executeParameterized(repo.id, `
+      MATCH (p:Process)
+      WHERE p.label = $processName OR p.heuristicLabel = $processName
+      RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+      LIMIT 1
+    `, { processName: name });
+        if (processes.length === 0)
+            return { error: `Process '${name}' not found` };
+        const proc = processes[0];
+        const procId = proc.id || proc[0];
+        const steps = await executeParameterized(repo.id, `
+      MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p {id: $procId})
+      RETURN n.name AS name, labels(n) AS type, n.filePath AS filePath, r.step AS step
+      ORDER BY r.step
+    `, { procId });
+        return {
+            process: {
+                id: procId, label: proc.label || proc[1], heuristicLabel: proc.heuristicLabel || proc[2],
+                processType: proc.processType || proc[3], stepCount: proc.stepCount || proc[4],
+            },
+            steps: steps.map((s) => ({
+                step: s.step || s[3], name: s.name || s[0], type: s.type || s[1], filePath: s.filePath || s[2],
+            })),
+        };
+    }
+    async disconnect() {
+        for (const watcher of this.watchers.values())
+            watcher.stop();
+        this.watchers.clear();
+        stopTsgoService();
+        await closeLbug(); // close all connections
+        // Note: we intentionally do NOT call disposeEmbedder() here.
+        // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs,
+        // and importing the embedder module on Node v24+ crashes if onnxruntime
+        // was never loaded during the session. Since process.exit(0) follows
+        // immediately after disconnect(), the OS reclaims everything. See #38, #89.
+        this.repos.clear();
+        this.contextCache.clear();
+        this.initializedRepos.clear();
+    }
+}