@duytransipher/gitnexus 1.4.6-sipher.0

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

@@ -0,0 +1,1722 @@
+/**
+ * Local Backend (Multi-Repo)
+ *
+ * Provides tool implementations using local .gitnexus/ 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 { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady } from '../core/lbug-adapter.js';
+// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
+// at MCP server startup — crashes on unsupported Node ABI versions (#89)
+// git utilities available if needed
+// import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
+import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-manager.js';
+import { ensureUnrealStorage, getUnrealStoragePaths, loadUnrealAssetManifest, loadUnrealConfig, } from '../../unreal/config.js';
+import { expandBlueprintChain, findNativeBlueprintReferences, syncUnrealAssetManifest, } from '../../unreal/bridge.js';
+// AI context generation is CLI-only (gitnexus analyze)
+// import { generateAIContextFiles } from '../../cli/ai-context.js';
+/**
+ * Quick test-file detection for filtering impact results.
+ * Matches common test file patterns 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', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']);
+/** 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(`GitNexus [${context}]: ${msg}`);
+}
+export class LocalBackend {
+    repos = new Map();
+    contextCache = new Map();
+    initializedRepos = new Set();
+    // ─── Initialization ──────────────────────────────────────────────
+    /**
+     * Initialize from the global registry.
+     * Returns true if at least one repo is available.
+     */
+    async init() {
+        await this.refreshRepos();
+        return this.repos.size > 0;
+    }
+    /**
+     * Re-read the global registry and update the in-memory repo map.
+     * New repos are added, existing repos are updated, removed repos are pruned.
+     * LadybugDB connections for removed repos are NOT closed (they 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 any leftover KuzuDB files from before the LadybugDB migration.
+            // If kuzu exists but lbug doesn't, warn so the user knows to re-analyze.
+            const kuzu = await cleanupOldKuzuFiles(storagePath);
+            if (kuzu.found && kuzu.needsReindex) {
+                console.error(`GitNexus: "${entry.name}" has a stale KuzuDB index. Run: gitnexus 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.
+     * If names collide, append a hash of the path.
+     */
+    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.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If 0 or multiple without param, throw with helpful message
+     *
+     * On a miss, re-reads the registry once in case a new repo was indexed
+     * while the MCP server was running.
+     */
+    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: gitnexus 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 with their metadata.
+     * Re-reads the global registry so newly indexed repos are discovered
+     * without restarting the MCP server.
+     */
+    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,
+        }));
+    }
+    // ─── 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);
+        switch (method) {
+            case 'query':
+                return this.query(repo, params);
+            case 'cypher': {
+                const raw = await this.cypher(repo, params);
+                return this.formatCypherAsMarkdown(raw);
+            }
+            case 'context':
+                return this.context(repo, params);
+            case 'impact':
+                return this.impact(repo, params);
+            case 'detect_changes':
+                return this.detectChanges(repo, params);
+            case 'rename':
+                return this.rename(repo, params);
+            case 'sync_unreal_asset_manifest':
+                return this.syncUnrealAssetManifestTool(repo);
+            case 'find_native_blueprint_references':
+                return this.findNativeBlueprintReferencesTool(repo, params);
+            case 'expand_blueprint_chain':
+                return this.expandBlueprintChainTool(repo, params);
+            case 'find_blueprints_derived_from_native_class':
+                return this.findBlueprintsDerivedFromNativeClassTool(repo, params);
+            // Legacy aliases for backwards compatibility
+            case 'search':
+                return this.query(repo, params);
+            case 'explore':
+                return this.context(repo, { name: params?.name, ...params });
+            case 'overview':
+                return this.overview(repo, params);
+            default:
+                throw new Error(`Unknown tool: ${method}`);
+        }
+    }
+    // ─── Tool Implementations ────────────────────────────────────────
+    async resolveNativeFunctionTarget(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const qualifiedInput = params.function?.trim() || '';
+        const explicitClass = params.class_name?.trim()
+            || (qualifiedInput.includes('::') ? qualifiedInput.split('::').slice(0, -1).join('::') : '');
+        const symbolName = params.symbol_uid
+            ? ''
+            : (qualifiedInput.includes('::') ? qualifiedInput.split('::').at(-1) : qualifiedInput);
+        if (!params.symbol_uid && !symbolName) {
+            return { error: 'Either "function" or "symbol_uid" is required.' };
+        }
+        const rows = await executeParameterized(repo.id, `
+      MATCH (n)
+      WHERE labels(n)[0] IN ['Function', 'Method']
+        AND (($symbolId = '') OR n.id = $symbolId)
+        AND (($symbolName = '') OR n.name = $symbolName)
+        AND (($filePath = '') OR n.filePath = $filePath)
+      OPTIONAL MATCH (owner)-[:CodeRelation {type: 'HAS_METHOD'}]->(n)
+      RETURN
+        n.id AS symbolId,
+        n.name AS symbolName,
+        labels(n)[0] AS symbolType,
+        n.filePath AS filePath,
+        n.startLine AS startLine,
+        owner.name AS ownerClass
+      LIMIT 25
+    `, {
+            symbolId: params.symbol_uid || '',
+            symbolName,
+            filePath: params.file_path || '',
+        });
+        const normalizedClass = explicitClass.toLowerCase();
+        const candidates = rows
+            .map((row) => {
+            const ownerClass = row.ownerClass || row[5] || undefined;
+            const qualifiedName = ownerClass ? `${ownerClass}::${row.symbolName || row[1]}` : (row.symbolName || row[1]);
+            return {
+                symbol_id: row.symbolId || row[0],
+                symbol_name: row.symbolName || row[1],
+                symbol_type: row.symbolType || row[2],
+                class_name: ownerClass,
+                file_path: row.filePath || row[3],
+                start_line: row.startLine || row[4],
+                symbol_key: qualifiedName,
+                qualified_name: qualifiedName,
+            };
+        })
+            .filter((candidate) => {
+            if (!normalizedClass)
+                return true;
+            return (candidate.class_name || '').toLowerCase() === normalizedClass;
+        });
+        if (candidates.length === 0) {
+            return { error: `Native function '${qualifiedInput || params.symbol_uid}' not found.` };
+        }
+        if (candidates.length > 1) {
+            return {
+                status: 'ambiguous',
+                candidates: candidates.map(candidate => ({
+                    symbol_id: candidate.symbol_id,
+                    symbol_key: candidate.symbol_key,
+                    class_name: candidate.class_name,
+                    file_path: candidate.file_path,
+                    start_line: candidate.start_line,
+                })),
+            };
+        }
+        return { target: candidates[0] };
+    }
+    shortlistBlueprintCandidates(target, manifest, maxCandidates = 200) {
+        const normalizedClass = (target.class_name || '').toLowerCase();
+        const normalizedQualified = target.qualified_name.toLowerCase();
+        const normalizedSymbol = target.symbol_key.toLowerCase();
+        const normalizedName = target.symbol_name.toLowerCase();
+        const scored = manifest.assets.map((asset) => {
+            const nativeParents = (asset.native_parents || []).map(v => v.toLowerCase());
+            const nativeFunctionRefs = (asset.native_function_refs || []).map(v => v.toLowerCase());
+            const dependencies = (asset.dependencies || []).map(v => v.toLowerCase());
+            let score = 0;
+            let reason = 'manifest';
+            if (normalizedClass && nativeParents.some(parent => parent === normalizedClass || parent.endsWith(`.${normalizedClass}`))) {
+                score = 90;
+                reason = 'native_parent';
+            }
+            if (nativeFunctionRefs.some(ref => ref === normalizedQualified || ref === normalizedSymbol || ref === normalizedName || ref.endsWith(normalizedQualified))) {
+                score = 120;
+                reason = 'native_function_ref';
+            }
+            if (dependencies.some(dep => dep.includes(normalizedQualified) || dep.includes(normalizedSymbol) || (normalizedClass && dep.includes(normalizedClass)))) {
+                score = Math.max(score, 75);
+                if (reason !== 'native_function_ref') {
+                    reason = 'dependency';
+                }
+            }
+            if (score === 0 && normalizedClass && (asset.parent_class || '').toLowerCase().includes(normalizedClass)) {
+                score = 60;
+            }
+            return {
+                score,
+                candidate: {
+                    asset_path: asset.asset_path,
+                    generated_class: asset.generated_class,
+                    parent_class: asset.parent_class,
+                    reason,
+                },
+            };
+        });
+        const filtered = scored.filter(item => item.score > 0).sort((a, b) => b.score - a.score);
+        if (filtered.length === 0) {
+            return manifest.assets.slice(0, maxCandidates).map(asset => ({
+                asset_path: asset.asset_path,
+                generated_class: asset.generated_class,
+                parent_class: asset.parent_class,
+                reason: 'manifest',
+            }));
+        }
+        return filtered.slice(0, maxCandidates).map(item => item.candidate);
+    }
+    async ensureUnrealReady(repo, refreshManifest = false) {
+        const config = await loadUnrealConfig(repo.storagePath);
+        if (!config) {
+            const paths = getUnrealStoragePaths(repo.storagePath);
+            return {
+                error: `Unreal analyzer is not configured for this repo. Create ${paths.config_path} with editor_cmd and project_path.`,
+            };
+        }
+        await ensureUnrealStorage(repo.storagePath);
+        const paths = getUnrealStoragePaths(repo.storagePath);
+        let manifest = refreshManifest ? null : await loadUnrealAssetManifest(repo.storagePath);
+        let manifestRefreshed = false;
+        if (!manifest) {
+            const syncResult = await syncUnrealAssetManifest(repo.storagePath, config);
+            if (syncResult.status === 'error') {
+                return { error: syncResult.error || 'Failed to build Unreal asset manifest.' };
+            }
+            manifest = await loadUnrealAssetManifest(repo.storagePath);
+            manifestRefreshed = true;
+        }
+        if (!manifest) {
+            return { error: 'Unreal asset manifest is missing after sync.' };
+        }
+        return {
+            config,
+            manifest,
+            manifestPath: paths.manifest_path,
+            manifestRefreshed,
+        };
+    }
+    async syncUnrealAssetManifestTool(repo) {
+        const config = await loadUnrealConfig(repo.storagePath);
+        if (!config) {
+            const paths = getUnrealStoragePaths(repo.storagePath);
+            return {
+                error: `Unreal analyzer is not configured for this repo. Create ${paths.config_path} with editor_cmd and project_path.`,
+            };
+        }
+        return syncUnrealAssetManifest(repo.storagePath, config);
+    }
+    async findNativeBlueprintReferencesTool(repo, params) {
+        const targetResult = await this.resolveNativeFunctionTarget(repo, params);
+        if (targetResult.error || targetResult.status === 'ambiguous') {
+            return targetResult;
+        }
+        const unrealState = await this.ensureUnrealReady(repo, params.refresh_manifest ?? false);
+        if ('error' in unrealState) {
+            return unrealState;
+        }
+        const candidateAssets = this.shortlistBlueprintCandidates(targetResult.target, unrealState.manifest, params.max_candidates || 200);
+        const result = await findNativeBlueprintReferences(repo.storagePath, unrealState.config, targetResult.target, candidateAssets, unrealState.manifestPath);
+        return {
+            ...result,
+            manifest_refreshed: unrealState.manifestRefreshed,
+        };
+    }
+    async expandBlueprintChainTool(repo, params) {
+        if (!params.asset_path || !params.chain_anchor_id) {
+            return { error: '"asset_path" and "chain_anchor_id" are required.' };
+        }
+        const unrealState = await this.ensureUnrealReady(repo, false);
+        if ('error' in unrealState) {
+            return unrealState;
+        }
+        return expandBlueprintChain(repo.storagePath, unrealState.config, params.asset_path, params.chain_anchor_id, params.direction || 'downstream', params.max_depth || 5);
+    }
+    async findBlueprintsDerivedFromNativeClassTool(repo, params) {
+        if (!params.class_name?.trim()) {
+            return { error: '"class_name" is required.' };
+        }
+        const unrealState = await this.ensureUnrealReady(repo, params.refresh_manifest ?? false);
+        if ('error' in unrealState) {
+            return unrealState;
+        }
+        const normalizedClass = params.class_name.trim().toLowerCase();
+        const matches = unrealState.manifest.assets
+            .filter(asset => (asset.native_parents || []).some(parent => {
+            const normalizedParent = parent.toLowerCase();
+            return normalizedParent === normalizedClass || normalizedParent.endsWith(`.${normalizedClass}`);
+        }))
+            .slice(0, params.max_results || 200)
+            .map(asset => ({
+            asset_path: asset.asset_path,
+            generated_class: asset.generated_class,
+            parent_class: asset.parent_class,
+            reason: 'native_parent',
+        }));
+        return {
+            class_name: params.class_name.trim(),
+            manifest_path: unrealState.manifestPath,
+            manifest_refreshed: unrealState.manifestRefreshed,
+            blueprints: matches,
+        };
+    }
+    /**
+     * Query tool — process-grouped search.
+     *
+     * 1. Hybrid search (BM25 + semantic) to find matching symbols
+     * 2. Trace each match to its process(es) via STEP_IN_PROCESS
+     * 3. Group by process, rank by aggregate relevance + internal cluster cohesion
+     * 4. Return: { processes, process_symbols, definitions }
+     */
+    async query(repo, params) {
+        if (!params.query?.trim()) {
+            return { error: 'query parameter is required and cannot be empty.' };
+        }
+        await this.ensureInitialized(repo.id);
+        const processLimit = params.limit || 5;
+        const maxSymbolsPerProcess = params.max_symbols || 10;
+        const includeContent = params.include_content ?? false;
+        const searchQuery = params.query.trim();
+        // Step 1: Run hybrid search to get matching symbols
+        const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
+        const [bm25Results, semanticResults] = await Promise.all([
+            this.bm25Search(repo, searchQuery, searchLimit),
+            this.semanticSearch(repo, searchQuery, searchLimit),
+        ]);
+        // Merge via reciprocal rank fusion
+        const scoreMap = new Map();
+        for (let i = 0; i < bm25Results.length; i++) {
+            const result = bm25Results[i];
+            const key = result.nodeId || result.filePath;
+            const rrfScore = 1 / (60 + i);
+            const existing = scoreMap.get(key);
+            if (existing) {
+                existing.score += rrfScore;
+            }
+            else {
+                scoreMap.set(key, { score: rrfScore, data: result });
+            }
+        }
+        for (let i = 0; i < semanticResults.length; i++) {
+            const result = semanticResults[i];
+            const key = result.nodeId || result.filePath;
+            const rrfScore = 1 / (60 + i);
+            const existing = scoreMap.get(key);
+            if (existing) {
+                existing.score += rrfScore;
+            }
+            else {
+                scoreMap.set(key, { score: rrfScore, data: result });
+            }
+        }
+        const merged = Array.from(scoreMap.entries())
+            .sort((a, b) => b[1].score - a[1].score)
+            .slice(0, searchLimit);
+        // Step 2: For each match with a nodeId, trace to process(es)
+        const processMap = new Map();
+        const definitions = []; // standalone symbols not in any process
+        for (const [_, item] of merged) {
+            const sym = item.data;
+            if (!sym.nodeId) {
+                // File-level results go to definitions
+                definitions.push({
+                    name: sym.name,
+                    type: sym.type || 'File',
+                    filePath: sym.filePath,
+                });
+                continue;
+            }
+            // Find processes this symbol participates in
+            let processRows = [];
+            try {
+                processRows = await executeParameterized(repo.id, `
+          MATCH (n {id: $nodeId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          RETURN p.id AS pid, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `, { nodeId: sym.nodeId });
+            }
+            catch (e) {
+                logQueryError('query:process-lookup', e);
+            }
+            // Get cluster membership + cohesion (cohesion used as internal ranking signal)
+            let cohesion = 0;
+            let module;
+            try {
+                const cohesionRows = await executeParameterized(repo.id, `
+          MATCH (n {id: $nodeId})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          RETURN c.cohesion AS cohesion, c.heuristicLabel AS module
+          LIMIT 1
+        `, { nodeId: sym.nodeId });
+                if (cohesionRows.length > 0) {
+                    cohesion = (cohesionRows[0].cohesion ?? cohesionRows[0][0]) || 0;
+                    module = cohesionRows[0].module ?? cohesionRows[0][1];
+                }
+            }
+            catch (e) {
+                logQueryError('query:cluster-info', e);
+            }
+            // Optionally fetch content
+            let content;
+            if (includeContent) {
+                try {
+                    const contentRows = await executeParameterized(repo.id, `
+            MATCH (n {id: $nodeId})
+            RETURN n.content AS content
+          `, { nodeId: sym.nodeId });
+                    if (contentRows.length > 0) {
+                        content = contentRows[0].content ?? contentRows[0][0];
+                    }
+                }
+                catch (e) {
+                    logQueryError('query:content-fetch', e);
+                }
+            }
+            const symbolEntry = {
+                id: sym.nodeId,
+                name: sym.name,
+                type: sym.type,
+                filePath: sym.filePath,
+                startLine: sym.startLine,
+                endLine: sym.endLine,
+                ...(module ? { module } : {}),
+                ...(includeContent && content ? { content } : {}),
+            };
+            if (processRows.length === 0) {
+                // Symbol not in any process — goes to definitions
+                definitions.push(symbolEntry);
+            }
+            else {
+                // Add to each process it belongs to
+                for (const row of processRows) {
+                    const pid = row.pid ?? row[0];
+                    const label = row.label ?? row[1];
+                    const hLabel = row.heuristicLabel ?? row[2];
+                    const pType = row.processType ?? row[3];
+                    const stepCount = row.stepCount ?? row[4];
+                    const step = row.step ?? row[5];
+                    if (!processMap.has(pid)) {
+                        processMap.set(pid, {
+                            id: pid,
+                            label,
+                            heuristicLabel: hLabel,
+                            processType: pType,
+                            stepCount,
+                            totalScore: 0,
+                            cohesionBoost: 0,
+                            symbols: [],
+                        });
+                    }
+                    const proc = processMap.get(pid);
+                    proc.totalScore += item.score;
+                    proc.cohesionBoost = Math.max(proc.cohesionBoost, cohesion);
+                    proc.symbols.push({
+                        ...symbolEntry,
+                        process_id: pid,
+                        step_index: step,
+                    });
+                }
+            }
+        }
+        // Step 3: Rank processes by aggregate score + internal cohesion boost
+        const rankedProcesses = Array.from(processMap.values())
+            .map(p => ({
+            ...p,
+            priority: p.totalScore + (p.cohesionBoost * 0.1), // cohesion as subtle ranking signal
+        }))
+            .sort((a, b) => b.priority - a.priority)
+            .slice(0, processLimit);
+        // Step 4: Build response
+        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,
+        }));
+        const processSymbols = rankedProcesses.flatMap(p => p.symbols.slice(0, maxSymbolsPerProcess).map(s => ({
+            ...s,
+            // remove internal fields
+        })));
+        // Deduplicate process_symbols by id
+        const seen = new Set();
+        const dedupedSymbols = processSymbols.filter(s => {
+            if (seen.has(s.id))
+                return false;
+            seen.add(s.id);
+            return true;
+        });
+        return {
+            processes,
+            process_symbols: dedupedSymbols,
+            definitions: definitions.slice(0, 20), // cap standalone definitions
+        };
+    }
+    /**
+     * 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');
+        let bm25Results;
+        try {
+            bm25Results = await searchFTSFromLbug(query, limit, repo.id);
+        }
+        catch (err) {
+            console.error('GitNexus: BM25/FTS search failed (FTS indexes may not exist) -', err.message);
+            return [];
+        }
+        const results = [];
+        for (const bm25Result of bm25Results) {
+            const fullPath = bm25Result.filePath;
+            try {
+                const symbols = await executeParameterized(repo.id, `
+          MATCH (n)
+          WHERE n.filePath = $filePath
+          RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+          LIMIT 3
+        `, { filePath: fullPath });
+                if (symbols.length > 0) {
+                    for (const sym of symbols) {
+                        results.push({
+                            nodeId: sym.id || sym[0],
+                            name: sym.name || sym[1],
+                            type: sym.type || sym[2],
+                            filePath: sym.filePath || sym[3],
+                            startLine: sym.startLine || sym[4],
+                            endLine: sym.endLine || sym[5],
+                            bm25Score: bm25Result.score,
+                        });
+                    }
+                }
+                else {
+                    const fileName = fullPath.split('/').pop() || fullPath;
+                    results.push({
+                        name: fileName,
+                        type: 'File',
+                        filePath: bm25Result.filePath,
+                        bm25Score: bm25Result.score,
+                    });
+                }
+            }
+            catch {
+                const fileName = fullPath.split('/').pop() || fullPath;
+                results.push({
+                    name: fileName,
+                    type: 'File',
+                    filePath: bm25Result.filePath,
+                    bm25Score: bm25Result.score,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * 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 { 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
+        WITH emb, distance
+        WHERE distance < 0.6
+        RETURN emb.nodeId AS nodeId, distance
+        ORDER BY distance
+      `;
+            const embResults = await executeQuery(repo.id, vectorQuery);
+            if (embResults.length === 0)
+                return [];
+            const results = [];
+            for (const embRow of embResults) {
+                const nodeId = embRow.nodeId ?? embRow[0];
+                const distance = embRow.distance ?? embRow[1];
+                const labelEndIdx = nodeId.indexOf(':');
+                const label = labelEndIdx > 0 ? nodeId.substring(0, labelEndIdx) : 'Unknown';
+                // Validate label against known node types to prevent Cypher injection
+                if (!VALID_NODE_LABELS.has(label))
+                    continue;
+                try {
+                    const nodeQuery = label === 'File'
+                        ? `MATCH (n:File {id: $nodeId}) RETURN n.name AS name, n.filePath AS filePath`
+                        : `MATCH (n:\`${label}\` {id: $nodeId}) RETURN n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
+                    const nodeRows = await executeParameterized(repo.id, nodeQuery, { nodeId });
+                    if (nodeRows.length > 0) {
+                        const nodeRow = nodeRows[0];
+                        results.push({
+                            nodeId,
+                            name: nodeRow.name ?? nodeRow[0] ?? '',
+                            type: label,
+                            filePath: nodeRow.filePath ?? nodeRow[1] ?? '',
+                            distance,
+                            startLine: label !== 'File' ? (nodeRow.startLine ?? nodeRow[2]) : undefined,
+                            endLine: label !== 'File' ? (nodeRow.endLine ?? nodeRow[3]) : undefined,
+                        });
+                    }
+                }
+                catch { }
+            }
+            return results;
+        }
+        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 for LLM readability.
+     * Falls back to raw result if rows aren't tabular objects.
+     */
+    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: group by heuristicLabel, sum symbols,
+     * weighted-average cohesion, filter out tiny clusters (<5 symbols).
+     * Raw communities stay intact in LadybugDB for Cypher queries.
+     */
+    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.
+     * Disambiguation when multiple symbols share a name.
+     * UID-based direct lookup. No cluster in output.
+     */
+    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) {
+            symbols = await executeParameterized(repo.id, `
+        MATCH (n {id: $uid})
+        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', 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)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', 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
+        const incomingRows = await executeParameterized(repo.id, `
+      MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']
+      RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
+      LIMIT 30
+    `, { symId });
+        // Categorized outgoing refs
+        const outgoingRows = await executeParameterized(repo.id, `
+      MATCH (n {id: $symId})-[r:CodeRelation]->(target)
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']
+      RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
+      LIMIT 30
+    `, { symId });
+        // 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);
+        }
+        // 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],
+                };
+                if (!cats[relType])
+                    cats[relType] = [];
+                cats[relType].push(entry);
+            }
+            return cats;
+        };
+        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],
+                ...(include_content && (sym.content || sym[6]) ? { content: sym.content || sym[6] } : {}),
+            },
+            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 — kept for backwards compatibility with resources.ts.
+     * Routes cluster/process types to direct graph queries.
+     */
+    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)[0] 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)[0] 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 based impact analysis.
+     * Maps changed lines to indexed symbols, then finds affected 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;
+        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}` };
+        }
+        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)[0] AS type, n.filePath AS filePath
+          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],
+                        change_type: 'Modified',
+                    });
+                }
+            }
+            catch (e) {
+                logQueryError('detect-changes:file-symbols', e);
+            }
+        }
+        // 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()),
+        };
+    }
+    /**
+     * Rename tool — multi-file coordinated rename using graph + text search.
+     * Graph refs are tagged "graph" (high confidence).
+     * Additional refs found via text search are tagged "text_search" (lower confidence).
+     */
+    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) {
+        try {
+            return await this._impactImpl(repo, params);
+        }
+        catch (err) {
+            // Return structured error instead of crashing (#321)
+            return {
+                error: (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed',
+                target: { name: params.target },
+                direction: params.direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+                suggestion: 'The graph query failed — try gitnexus context <symbol> as a fallback',
+            };
+        }
+    }
+    async _impactImpl(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'];
+        const relationTypes = rawRelTypes.length > 0 ? rawRelTypes : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS'];
+        const includeTests = params.includeTests ?? false;
+        const minConfidence = params.minConfidence ?? 0;
+        const relTypeFilter = relationTypes.map(t => `'${t}'`).join(', ');
+        const confidenceFilter = minConfidence > 0 ? ` AND r.confidence >= ${minConfidence}` : '';
+        const targets = await executeParameterized(repo.id, `
+      MATCH (n)
+      WHERE n.name = $targetName
+      RETURN n.id AS id, n.name AS name, labels(n)[0] 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];
+        const impacted = [];
+        const visited = new Set([symId]);
+        let frontier = [symId];
+        let traversalComplete = true;
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+            const nextFrontier = [];
+            // Batch frontier nodes into a single Cypher query per depth level
+            const idList = frontier.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
+            const query = direction === 'upstream'
+                ? `MATCH (caller)-[r:CodeRelation]->(n) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, caller.id AS id, caller.name AS name, labels(caller)[0] AS type, caller.filePath AS filePath, r.type AS relType, r.confidence AS confidence`
+                : `MATCH (n)-[r:CodeRelation]->(callee) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, callee.id AS id, callee.name AS name, labels(callee)[0] AS type, 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;
+                    if (!visited.has(relId)) {
+                        visited.add(relId);
+                        nextFrontier.push(relId);
+                        impacted.push({
+                            depth,
+                            id: relId,
+                            name: rel.name || rel[2],
+                            type: rel.type || rel[3],
+                            filePath,
+                            relationType: rel.relType || rel[5],
+                            confidence: rel.confidence || rel[6] || 1.0,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                logQueryError('impact:depth-traversal', e);
+                // Break out of depth loop on query failure but return partial results
+                // collected so far, rather than silently swallowing the error (#321)
+                traversalComplete = false;
+                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
+        `).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,
+            ...(!traversalComplete && { partial: 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.
+     * Used by getClustersResource — avoids legacy overview() dispatch.
+     */
+    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.
+     * Used by getProcessesResource — avoids legacy overview() dispatch.
+     */
+    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) directly from graph.
+     * Used by 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)[0] 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) directly from graph.
+     * Used by 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)[0] 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() {
+        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();
+    }
+}