gitnexus 1.6.6-rc.99 → 1.6.6

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

@@ -7,6 +7,7 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
+import { createHash } from 'crypto';
 import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, } from '../../core/lbug/pool-adapter.js';
 import { isValidQueryParams } from '../../core/lbug/query-params.js';
 import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
@@ -142,7 +143,20 @@ function logQueryError(context, err) {
     const msg = err instanceof Error ? err.message : String(err);
     logger.error({ context, err: msg }, 'GitNexus query failed');
 }
-const isReadOnlyDbError = (err) => /read-only database/i.test(err instanceof Error ? err.message : String(err));
+const isReadOnlyDbError = (err) => {
+    // Walk the `cause` chain (bounded) so a wrapped read-only error (e.g. the
+    // pool adapter's `{ cause }` wrapper) is still detected here — this is the
+    // copy the MCP cypher handler uses to surface its curated read-only message
+    // (#2068 follow-up). Mirrors lbug-adapter's isReadOnlyDbError.
+    let cur = err;
+    for (let depth = 0; depth < 5 && cur != null; depth++) {
+        const msg = cur instanceof Error ? cur.message : String(cur);
+        if (/read-only database/i.test(msg))
+            return true;
+        cur = cur instanceof Error ? cur.cause : undefined;
+    }
+    return false;
+};
 /**
  * Per-query latency telemetry for production aggregation (#553).
  *
@@ -234,9 +248,16 @@ export function resolveWorktreeCwd(repoPath, launchCwd) {
     return repoPath;
 }
 /**
- * Length of the base64url path hash appended to a colliding repo id.
+ * Length of the path-derived suffix appended to a colliding repo id.
  * Exported so tests can pin the suffix shape without re-deriving the
- * literal; see `repoId()` and the hashed-id resolution tier (#1658).
+ * literal; see `assignRepoId()` and the hashed-id resolution tier (#1658).
+ *
+ * Note: base64url is an *encoding*, not a hash — it preserves byte order, so
+ * two paths that share a long common prefix (sibling clones under one parent)
+ * collapse to the same sliced suffix. `assignRepoId()` keeps the legacy
+ * base64url suffix only for the first colliding duplicate (id compatibility)
+ * and falls back to a content hash of the resolved path on a real collision
+ * (#2054).
  */
 export const REPO_ID_HASH_LENGTH = 6;
 export class LocalBackend {
@@ -296,10 +317,32 @@ export class LocalBackend {
      */
     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);
+        // Build the next map from scratch and swap it in atomically. Mutating the
+        // live map in place let stale entries influence fresh id assignment: a
+        // bare-name id, once handed to the first registry entry, stuck to it across
+        // refreshes and reorders, and colliding path suffixes silently overwrote
+        // each other so sibling clones disappeared from `list_repos` (#2054).
+        const nextRepos = new Map();
+        const nextContext = new Map();
+        const assigned = new Map(); // id -> resolved repo path
+        // Assign ids over a path-sorted view so a registered clone always gets the
+        // same id regardless of the registry's on-disk order: the bare name and
+        // each path-derived suffix become a pure function of the resolved-path set,
+        // not of iteration order, so a memorized id can't drift to a different
+        // clone after a registry reorder (#2067 follow-up).
+        const ordered = [...entries].sort((a, b) => {
+            const ra = path.resolve(a.path);
+            const rb = path.resolve(b.path);
+            return ra < rb ? -1 : ra > rb ? 1 : 0;
+        });
+        for (const entry of ordered) {
+            // path.resolve (not canonicalizePath) matches the pre-#2054 collision
+            // check and keeps refreshRepos free of mockable deps on the hot init
+            // path. registerRepo writes path.resolve'd paths (not realpath), and
+            // resolveRepoFromCache canonicalizes both sides when matching by path, so
+            // keying id assignment on path.resolve here is consistent and correct.
+            const resolved = path.resolve(entry.path);
+            const id = this.assignRepoId(entry.name, entry.path, resolved, assigned);
             const storagePath = entry.storagePath;
             const lbugPath = path.join(storagePath, 'lbug');
             // Clean up any leftover KuzuDB files from before the LadybugDB migration.
@@ -319,10 +362,10 @@ export class LocalBackend {
                 remoteUrl: entry.remoteUrl,
                 stats: entry.stats,
             };
-            this.repos.set(id, handle);
+            nextRepos.set(id, handle);
             // Build lightweight context (no LadybugDB needed)
             const s = entry.stats || {};
-            this.contextCache.set(id, {
+            nextContext.set(id, {
                 projectName: entry.name,
                 stats: {
                     fileCount: s.files || 0,
@@ -332,36 +375,78 @@ export class LocalBackend {
                 },
             });
         }
-        // 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);
-            }
+        // Prune per-clone pool state for databases that are no longer registered.
+        // The LadybugDB pool and the init/staleness/reinit maps are keyed by the
+        // immutable lbugPath (see ensureInitialized), so a repo id that merely
+        // moves to a different clone needs NO eviction — distinct clones have
+        // distinct lbugPaths and can never share a pool entry, which is what closes
+        // the resolve→query wrong-clone window for good (#2067). Only a path that
+        // dropped out of the registry must release its pooled connection + state.
+        const liveLbugPaths = new Set([...nextRepos.values()].map((h) => h.lbugPath));
+        for (const prev of this.repos.values()) {
+            if (liveLbugPaths.has(prev.lbugPath))
+                continue;
+            this.initializedRepos.delete(prev.lbugPath);
+            this.lastStalenessCheck.delete(prev.lbugPath);
+            this.reinitPromises.delete(prev.lbugPath);
+            closeLbug(prev.lbugPath).catch(() => { });
         }
+        this.repos = nextRepos;
+        this.contextCache = nextContext;
     }
     /**
-     * Generate a stable repo ID from name + path.
-     * If names collide, append a hash of the path.
+     * Assign a collision-free in-memory id for a registered repo.
+     *
+     * - Unique name → the bare lowercased name.
+     * - Duplicate name → a path-derived suffix. The *first* colliding clone keeps
+     *   the legacy `base64url(path)` suffix so ids generated before #2054 still
+     *   resolve (the #1658 hashed-id tier). base64url is an encoding, not a hash:
+     *   it preserves byte order, so sibling clones under one parent (e.g.
+     *   `.../REPO_2` and `.../REPO_3`) yield identical leading characters and thus
+     *   the same sliced suffix. Any further collision therefore falls back to a
+     *   content hash of the *resolved* path (order-insensitive), extended
+     *   deterministically until unique.
+     *
+     * `assigned` maps every id handed out in this refresh to its resolved path,
+     * so a candidate is "free" when it is unused or already owned by this exact
+     * path. This method records its own assignment into `assigned` before
+     * returning, so the map-update is the function's invariant, not a caller
+     * obligation. A returned id never overwrites a different path's handle (#2054).
      */
-    repoId(name, repoPath) {
+    assignRepoId(name, repoPath, resolved, assigned) {
         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
-                // Lowercase the hash so it survives the `paramLower` lookup in
-                // resolveRepoFromCache — base64url retains mixed case, but the id
-                // tier compares against `repoParam.toLowerCase()` (#1658 follow-up).
-                const hash = Buffer.from(repoPath)
-                    .toString('base64url')
-                    .slice(0, REPO_ID_HASH_LENGTH)
-                    .toLowerCase();
-                return `${base}-${hash}`;
-            }
-        }
-        return base;
+        const free = (id) => {
+            const owner = assigned.get(id);
+            return owner === undefined || owner === resolved;
+        };
+        // Record the assignment so subsequent entries in the same refresh see this
+        // id as taken (the function owns its own invariant).
+        const claim = (id) => {
+            assigned.set(id, resolved);
+            return id;
+        };
+        if (free(base))
+            return claim(base);
+        // Legacy suffix from the *raw* path — kept byte-for-byte so the first
+        // colliding duplicate keeps the id it had before #2054 (#1658 tier).
+        const legacy = `${base}-${Buffer.from(repoPath)
+            .toString('base64url')
+            .slice(0, REPO_ID_HASH_LENGTH)
+            .toLowerCase()}`;
+        if (free(legacy))
+            return claim(legacy);
+        // Real collision — hash the resolved path. Lowercase hex survives the
+        // `paramLower` lookup in resolveRepoFromCache.
+        const digest = createHash('sha256').update(resolved).digest('hex');
+        for (let len = REPO_ID_HASH_LENGTH; len <= digest.length; len++) {
+            const candidate = `${base}-${digest.slice(0, len)}`;
+            if (free(candidate))
+                return claim(candidate);
+        }
+        // Two distinct resolved paths sharing a full SHA-256 digest is a hash
+        // break, not a runtime condition — fail loudly rather than silently
+        // overwrite a different repo's handle (#2054 invariant).
+        throw new Error(`GitNexus internal: unable to assign a unique repo id for "${name}" at ${repoPath}`);
     }
     // ─── Repo Resolution ─────────────────────────────────────────────
     /**
@@ -521,44 +606,52 @@ export class LocalBackend {
         };
     }
     // ─── Lazy LadybugDB Init ────────────────────────────────────────────
-    async ensureInitialized(repoId) {
+    /**
+     * Ensure the LadybugDB pool is open for the *resolved* repo.
+     *
+     * Takes the `RepoHandle` the caller resolved — NOT a bare id — and keys the
+     * pool (and the init/staleness/reinit maps) by the immutable `lbugPath`. Two
+     * things matter for multi-clone correctness: (1) the handle is the one the
+     * caller resolved, so a concurrent `refreshRepos` can't substitute a different
+     * clone; (2) the pool key is the database path, so distinct clones never share
+     * a pool entry even when their name-derived id transiently collides (#2067).
+     */
+    async ensureInitialized(repo) {
+        const poolKey = repo.lbugPath;
         // If a reinit is already in progress for this repo, wait for it
-        const pending = this.reinitPromises.get(repoId);
+        const pending = this.reinitPromises.get(poolKey);
         if (pending)
             return pending;
-        const handle = this.repos.get(repoId);
-        if (!handle)
-            throw new Error(`Unknown repo: ${repoId}`);
         // Check if the index was rebuilt since we opened the connection (#297).
         // Throttle staleness checks to at most once per 5 seconds per repo to
         // avoid an fs.readFile round-trip on every tool invocation.
-        if (this.initializedRepos.has(repoId) && isLbugReady(repoId)) {
+        if (this.initializedRepos.has(poolKey) && isLbugReady(poolKey)) {
             const now = Date.now();
-            const lastCheck = this.lastStalenessCheck.get(repoId) ?? 0;
+            const lastCheck = this.lastStalenessCheck.get(poolKey) ?? 0;
             if (now - lastCheck < 5000)
                 return; // Checked recently — skip
-            this.lastStalenessCheck.set(repoId, now);
+            this.lastStalenessCheck.set(poolKey, now);
             try {
-                const metaPath = path.join(handle.storagePath, 'meta.json');
+                const metaPath = path.join(repo.storagePath, 'meta.json');
                 const metaRaw = await fs.readFile(metaPath, 'utf-8');
                 const meta = JSON.parse(metaRaw);
-                if (meta.indexedAt && meta.indexedAt !== handle.indexedAt) {
+                if (meta.indexedAt && meta.indexedAt !== repo.indexedAt) {
                     // Index was rebuilt — close stale connection and re-init.
                     // Wrap in reinitPromises to prevent TOCTOU race where concurrent
                     // callers both detect staleness and double-close the pool.
                     const reinit = (async () => {
                         try {
-                            await closeLbug(repoId);
-                            this.initializedRepos.delete(repoId);
-                            handle.indexedAt = meta.indexedAt;
-                            await initLbug(repoId, handle.lbugPath);
-                            this.initializedRepos.add(repoId);
+                            await closeLbug(poolKey);
+                            this.initializedRepos.delete(poolKey);
+                            repo.indexedAt = meta.indexedAt;
+                            await initLbug(poolKey, repo.lbugPath);
+                            this.initializedRepos.add(poolKey);
                         }
                         finally {
-                            this.reinitPromises.delete(repoId);
+                            this.reinitPromises.delete(poolKey);
                         }
                     })();
-                    this.reinitPromises.set(repoId, reinit);
+                    this.reinitPromises.set(poolKey, reinit);
                     return reinit;
                 }
                 else {
@@ -570,12 +663,12 @@ export class LocalBackend {
             }
         }
         try {
-            await initLbug(repoId, handle.lbugPath);
-            this.initializedRepos.add(repoId);
+            await initLbug(poolKey, repo.lbugPath);
+            this.initializedRepos.add(poolKey);
         }
         catch (err) {
             // If lock error, mark as not initialized so next call retries
-            this.initializedRepos.delete(repoId);
+            this.initializedRepos.delete(poolKey);
             throw err;
         }
     }
@@ -771,7 +864,7 @@ export class LocalBackend {
         if (!params.query?.trim()) {
             return { error: 'query parameter is required and cannot be empty.' };
         }
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const processLimit = params.limit || 5;
         const maxSymbolsPerProcess = params.max_symbols || 10;
         const includeContent = params.include_content ?? false;
@@ -846,7 +939,7 @@ export class LocalBackend {
             // Find processes this symbol participates in
             let processRows = [];
             try {
-                processRows = await executeParameterized(repo.id, `
+                processRows = await executeParameterized(repo.lbugPath, `
           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 });
@@ -858,7 +951,7 @@ export class LocalBackend {
             let cohesion = 0;
             let module;
             try {
-                const cohesionRows = await executeParameterized(repo.id, `
+                const cohesionRows = await executeParameterized(repo.lbugPath, `
           MATCH (n {id: $nodeId})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
           RETURN c.cohesion AS cohesion, c.heuristicLabel AS module
           LIMIT 1
@@ -875,7 +968,7 @@ export class LocalBackend {
             let content;
             if (includeContent) {
                 try {
-                    const contentRows = await executeParameterized(repo.id, `
+                    const contentRows = await executeParameterized(repo.lbugPath, `
             MATCH (n {id: $nodeId})
             RETURN n.content AS content
           `, { nodeId: sym.nodeId });
@@ -998,7 +1091,7 @@ export class LocalBackend {
         }
         let ftsResponse;
         try {
-            ftsResponse = await searchFTSFromLbug(query, limit, repo.id);
+            ftsResponse = await searchFTSFromLbug(query, limit, repo.lbugPath);
         }
         catch (err) {
             logger.error({ err: err.message }, 'GitNexus: BM25/FTS search failed (FTS indexes may not exist) -');
@@ -1017,12 +1110,12 @@ export class LocalBackend {
                 // the nodes that actually scored highest in the BM25 index.
                 const nodeIds = bm25Result.nodeIds?.length ? bm25Result.nodeIds : null;
                 const symbols = nodeIds
-                    ? await executeParameterized(repo.id, `
+                    ? await executeParameterized(repo.lbugPath, `
               MATCH (n)
               WHERE n.id IN $nodeIds
               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
             `, { nodeIds })
-                    : await executeParameterized(repo.id, `
+                    : await executeParameterized(repo.lbugPath, `
               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
@@ -1069,7 +1162,7 @@ export class LocalBackend {
     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:${EMBEDDING_TABLE_NAME}) RETURN COUNT(*) AS cnt LIMIT 1`);
+            const tableCheck = await executeQuery(repo.lbugPath, `MATCH (e:${EMBEDDING_TABLE_NAME}) 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');
@@ -1090,7 +1183,7 @@ export class LocalBackend {
                    emb.startLine AS startLine, emb.endLine AS endLine, distance
             ORDER BY distance
           `;
-                        const embResults = await executeQuery(repo.id, vectorQuery);
+                        const embResults = await executeQuery(repo.lbugPath, vectorQuery);
                         return embResults.map((row) => ({
                             nodeId: row.nodeId ?? row[0],
                             chunkIndex: row.chunkIndex ?? row[1] ?? 0,
@@ -1117,7 +1210,7 @@ export class LocalBackend {
                 const exactLimit = getExactScanLimit();
                 if (embeddingCount > exactLimit)
                     return [];
-                const rows = await executeQuery(repo.id, `
+                const rows = await executeQuery(repo.lbugPath, `
           MATCH (e:${EMBEDDING_TABLE_NAME})
           RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex,
                  e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding
@@ -1152,7 +1245,7 @@ export class LocalBackend {
                     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`;
-                    const nodeRows = await executeParameterized(repo.id, nodeQuery, { nodeId });
+                    const nodeRows = await executeParameterized(repo.lbugPath, nodeQuery, { nodeId });
                     if (nodeRows.length > 0) {
                         const nodeRow = nodeRows[0];
                         results.push({
@@ -1180,8 +1273,8 @@ export class LocalBackend {
         return this.cypher(repo, { query, params });
     }
     async cypher(repo, request) {
-        await this.ensureInitialized(repo.id);
-        if (!isLbugReady(repo.id)) {
+        await this.ensureInitialized(repo);
+        if (!isLbugReady(repo.lbugPath)) {
             return { error: 'LadybugDB not ready. Index may be corrupted.' };
         }
         if (request.params !== undefined && !isValidQueryParams(request.params)) {
@@ -1190,7 +1283,7 @@ export class LocalBackend {
             };
         }
         try {
-            const result = await executeParameterized(repo.id, request.query, request.params ?? {});
+            const result = await executeParameterized(repo.lbugPath, request.query, request.params ?? {});
             return result;
         }
         catch (err) {
@@ -1283,7 +1376,7 @@ export class LocalBackend {
             .sort((a, b) => b.symbolCount - a.symbolCount);
     }
     async overview(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const limit = params.limit || 20;
         const result = {
             repo: repo.name,
@@ -1296,7 +1389,7 @@ export class LocalBackend {
             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, `
+                const clusters = await executeQuery(repo.lbugPath, `
           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
@@ -1317,7 +1410,7 @@ export class LocalBackend {
         }
         if (params.showProcesses !== false) {
             try {
-                const processes = await executeQuery(repo.id, `
+                const processes = await executeQuery(repo.lbugPath, `
           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
@@ -1355,7 +1448,7 @@ export class LocalBackend {
         if (ids.length === 0)
             return;
         try {
-            const rows = await executeParameterized(repo.id, `
+            const rows = await executeParameterized(repo.lbugPath, `
         MATCH (n:\`Class\`) WHERE n.id IN $ids RETURN n.id AS id, 'Class' AS label
         UNION ALL
         MATCH (n:\`Interface\`) WHERE n.id IN $ids RETURN n.id AS id, 'Interface' AS label
@@ -1440,7 +1533,7 @@ export class LocalBackend {
         const selectClause = `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' : ''}`;
         // Direct UID — zero-ambiguity path.
         if (uid) {
-            const rows = await executeParameterized(repo.id, `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`, { uid });
+            const rows = await executeParameterized(repo.lbugPath, `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`, { uid });
             if (rows.length === 0)
                 return { kind: 'not_found' };
             const r = rows[0];
@@ -1476,7 +1569,7 @@ export class LocalBackend {
         }
         // LIMIT 20 (was 10) — scoring is the point now, so give the ranker
         // headroom instead of arbitrary truncation.
-        const rows = await executeParameterized(repo.id, `MATCH (n) ${whereClause} RETURN ${selectClause} LIMIT 20`, queryParams);
+        const rows = await executeParameterized(repo.lbugPath, `MATCH (n) ${whereClause} RETURN ${selectClause} LIMIT 20`, queryParams);
         if (rows.length === 0)
             return { kind: 'not_found' };
         // Normalise row shape across object / tuple returns from LadybugDB.
@@ -1509,7 +1602,7 @@ export class LocalBackend {
             if (ambiguousType) {
                 const candidateIds = normalized.map((s) => s.id).filter(Boolean);
                 for (const label of ['Class', 'Interface']) {
-                    const labelRows = await executeParameterized(repo.id, `MATCH (n:\`${label}\`) WHERE n.id IN $candidateIds RETURN n.id AS id LIMIT 1`, { candidateIds }).catch(() => []);
+                    const labelRows = await executeParameterized(repo.lbugPath, `MATCH (n:\`${label}\`) WHERE n.id IN $candidateIds RETURN n.id AS id LIMIT 1`, { candidateIds }).catch(() => []);
                     if (labelRows.length > 0) {
                         const preferredId = labelRows[0].id ?? labelRows[0][0];
                         const preferred = normalized.find((s) => s.id === preferredId);
@@ -1588,7 +1681,7 @@ export class LocalBackend {
         }
     }
     async _contextImpl(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const { name, uid, file_path, kind, include_content } = params;
         if (!name && !uid) {
             return { error: 'Either "name" or "uid" parameter is required.' };
@@ -1616,7 +1709,7 @@ export class LocalBackend {
         const resolvedLabel = outcome.resolvedLabel;
         const symId = sym.id;
         // Categorized incoming refs
-        const incomingRows = await executeParameterized(repo.id, `
+        const incomingRows = await executeParameterized(repo.lbugPath, `
       MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
       WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
       RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
@@ -1636,7 +1729,7 @@ export class LocalBackend {
         if (!isClassLike && symRawType === '') {
             try {
                 // Single UNION query instead of two serial round-trips.
-                const typeCheck = await executeParameterized(repo.id, `
+                const typeCheck = await executeParameterized(repo.lbugPath, `
           MATCH (n:Class) WHERE n.id = $symId RETURN 'Class' AS label LIMIT 1
           UNION ALL
           MATCH (n:Interface) WHERE n.id = $symId RETURN 'Interface' AS label LIMIT 1
@@ -1654,7 +1747,7 @@ export class LocalBackend {
             try {
                 // Run incoming-ref queries in parallel — they are independent.
                 const [ctorIncoming, fileIncoming, typedPropertyIncoming, typedProperties] = await Promise.all([
-                    executeParameterized(repo.id, `
+                    executeParameterized(repo.lbugPath, `
             MATCH (n)-[hm:CodeRelation]->(ctor:Constructor)
             WHERE n.id = $symId AND hm.type = 'HAS_METHOD'
             MATCH (caller)-[r:CodeRelation]->(ctor)
@@ -1662,7 +1755,7 @@ export class LocalBackend {
             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 }),
-                    executeParameterized(repo.id, `
+                    executeParameterized(repo.lbugPath, `
             MATCH (f:File)-[rel:CodeRelation]->(n)
             WHERE n.id = $symId AND rel.type = 'DEFINES'
             MATCH (caller)-[r:CodeRelation]->(f)
@@ -1670,7 +1763,7 @@ export class LocalBackend {
             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 }),
-                    executeParameterized(repo.id, `
+                    executeParameterized(repo.lbugPath, `
             MATCH (p:\`Property\`)
             WHERE p.declaredType = $name
                OR p.declaredType STARTS WITH $genericPrefix
@@ -1684,7 +1777,7 @@ export class LocalBackend {
                         genericPrefix: `${sym.name}<`,
                         genericArg: `<${sym.name}>`,
                     }),
-                    executeParameterized(repo.id, `
+                    executeParameterized(repo.lbugPath, `
             MATCH (p:\`Property\`)
             WHERE p.declaredType = $name
                OR p.declaredType STARTS WITH $genericPrefix
@@ -1716,7 +1809,7 @@ export class LocalBackend {
             }
         }
         // Categorized outgoing refs
-        const outgoingRows = await executeParameterized(repo.id, `
+        const outgoingRows = await executeParameterized(repo.lbugPath, `
       MATCH (n {id: $symId})-[r:CodeRelation]->(target)
       WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
       RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
@@ -1725,7 +1818,7 @@ export class LocalBackend {
         // Process participation
         let processRows = [];
         try {
-            processRows = await executeParameterized(repo.id, `
+            processRows = await executeParameterized(repo.lbugPath, `
         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 });
@@ -1756,7 +1849,7 @@ export class LocalBackend {
         let methodMetadata;
         if (isMethodLike) {
             try {
-                const metaRows = await executeParameterized(repo.id, `
+                const metaRows = await executeParameterized(repo.lbugPath, `
           MATCH (n {id: $symId})
           RETURN n.visibility AS visibility, n.isStatic AS isStatic, n.isAbstract AS isAbstract,
                  n.isFinal AS isFinal, n.isVirtual AS isVirtual, n.isOverride AS isOverride,
@@ -1821,13 +1914,13 @@ export class LocalBackend {
      * Routes cluster/process types to direct graph queries.
      */
     async explore(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const { name, type } = params;
         if (type === 'symbol') {
             return this.context(repo, { name });
         }
         if (type === 'cluster') {
-            const clusters = await executeParameterized(repo.id, `
+            const clusters = await executeParameterized(repo.lbugPath, `
         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
@@ -1847,7 +1940,7 @@ export class LocalBackend {
                 totalSymbols += s;
                 weightedCohesion += (c.cohesion || 0) * s;
             }
-            const members = await executeParameterized(repo.id, `
+            const members = await executeParameterized(repo.lbugPath, `
         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
@@ -1870,7 +1963,7 @@ export class LocalBackend {
             };
         }
         if (type === 'process') {
-            const processes = await executeParameterized(repo.id, `
+            const processes = await executeParameterized(repo.lbugPath, `
         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
@@ -1880,7 +1973,7 @@ export class LocalBackend {
                 return { error: `Process '${name}' not found` };
             const proc = processes[0];
             const procId = proc.id || proc[0];
-            const steps = await executeParameterized(repo.id, `
+            const steps = await executeParameterized(repo.lbugPath, `
         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
@@ -1908,7 +2001,7 @@ export class LocalBackend {
      * Maps changed lines to indexed symbols, then finds affected processes.
      */
     async detectChanges(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const scope = params.scope || 'unstaged';
         const { execFileSync } = await import('child_process');
         // Build git diff args based on scope (using execFileSync to avoid shell injection)
@@ -2019,7 +2112,7 @@ export class LocalBackend {
                n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
       `;
             try {
-                const rows = await executeParameterized(repo.id, symbolQuery, queryParams);
+                const rows = await executeParameterized(repo.lbugPath, symbolQuery, queryParams);
                 for (const sym of rows) {
                     changedSymbols.push({
                         id: sym.id || sym[0],
@@ -2040,7 +2133,7 @@ export class LocalBackend {
             const symIds = changedSymbols.map((s) => s.id);
             const symNameById = new Map(changedSymbols.map((s) => [s.id, s.name]));
             try {
-                const procs = await executeParameterized(repo.id, `
+                const procs = await executeParameterized(repo.lbugPath, `
           MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
           WHERE n.id IN $ids
           RETURN n.id AS nodeId, p.id AS pid, p.heuristicLabel AS label,
@@ -2093,7 +2186,7 @@ export class LocalBackend {
      * Additional refs found via text search are tagged "text_search" (lower confidence).
      */
     async rename(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const { new_name, file_path } = params;
         const dry_run = params.dry_run ?? true;
         if (!params.symbol_name && !params.symbol_uid) {
@@ -2275,7 +2368,7 @@ export class LocalBackend {
         }
     }
     async _impactImpl(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const { target, direction } = params;
         const maxDepth = params.maxDepth || 3;
         // Map legacy relation type names before filtering (backward compat for OVERRIDES → METHOD_OVERRIDES)
@@ -2403,14 +2496,14 @@ export class LocalBackend {
             try {
                 // Run both seed queries in parallel — they are independent.
                 const [ctorRows, fileRows] = await Promise.all([
-                    executeParameterized(repo.id, `
+                    executeParameterized(repo.lbugPath, `
             MATCH (n)-[hm:CodeRelation]->(c:Constructor)
             WHERE n.id = $symId AND hm.type = 'HAS_METHOD'
             RETURN c.id AS id, c.name AS name, labels(c)[0] AS type, c.filePath AS filePath
           `, { symId }),
                     // Restrict to DEFINES edges only — other File->Class edge types (if
                     // any) should not be treated as the owning file relationship.
-                    executeParameterized(repo.id, `
+                    executeParameterized(repo.lbugPath, `
             MATCH (f:File)-[rel:CodeRelation]->(n)
             WHERE n.id = $symId AND rel.type = 'DEFINES'
             RETURN f.id AS id, f.name AS name, labels(f)[0] AS type, f.filePath AS filePath
@@ -2430,7 +2523,7 @@ export class LocalBackend {
                         frontier.push(rid);
                     }
                 }
-                const typedPropertyRows = await executeParameterized(repo.id, `
+                const typedPropertyRows = await executeParameterized(repo.lbugPath, `
           MATCH (p:\`Property\`)
           WHERE p.declaredType = $name
              OR p.declaredType STARTS WITH $genericPrefix
@@ -2461,7 +2554,7 @@ export class LocalBackend {
                 ? `MATCH (caller)-[r:CodeRelation]->(n) WHERE n.id IN $frontierIds AND r.type IN $relTypes${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 $frontierIds AND r.type IN $relTypes${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 executeParameterized(repo.id, query, {
+                const related = await executeParameterized(repo.lbugPath, query, {
                     frontierIds: frontier,
                     relTypes: relationTypes,
                     ...(safeMinConfidence > 0 ? { minConfidence: safeMinConfidence } : {}),
@@ -2541,7 +2634,7 @@ export class LocalBackend {
                 const ids = chunk.map((item) => String(item.id ?? ''));
                 try {
                     // Use parameterized list to avoid building long query strings
-                    const rows = await executeParameterized(repo.id, `
+                    const rows = await executeParameterized(repo.lbugPath, `
             MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
             WHERE s.id IN $ids
             WITH p, COUNT(DISTINCT s.id) AS hits, MIN(r.step) AS minStep
@@ -2607,7 +2700,7 @@ export class LocalBackend {
                 try {
                     const pIds = Array.from(processesMissingMinStep);
                     const allImpactedIds = impacted.map((it) => String(it.id ?? ''));
-                    const missingRows = await executeParameterized(repo.id, `
+                    const missingRows = await executeParameterized(repo.lbugPath, `
             MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
             WHERE p.id IN $pIds AND s.id IN $ids
             RETURN p.id AS pid, MIN(r.step) AS minStep
@@ -2659,7 +2752,7 @@ export class LocalBackend {
                 if (!idsChunk || idsChunk.length === 0)
                     return;
                 try {
-                    const rows = await executeParameterized(repo.id, `
+                    const rows = await executeParameterized(repo.lbugPath, `
             MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
             WHERE s.id IN $ids
             RETURN c.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits
@@ -2688,7 +2781,7 @@ export class LocalBackend {
                 if (!idsChunk || idsChunk.length === 0)
                     return;
                 try {
-                    const rows = await executeParameterized(repo.id, `
+                    const rows = await executeParameterized(repo.lbugPath, `
             MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
             WHERE s.id IN $ids
             RETURN DISTINCT c.heuristicLabel AS name
@@ -2815,7 +2908,7 @@ export class LocalBackend {
             for (let i = 0; i < pageIdArr.length; i += CHUNK_SIZE) {
                 const chunkIds = pageIdArr.slice(i, i + CHUNK_SIZE);
                 try {
-                    const rows = await executeParameterized(repo.id, `
+                    const rows = await executeParameterized(repo.lbugPath, `
             MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
             WHERE s.id IN $ids
             RETURN s.id AS sid, p.id AS pid, p.heuristicLabel AS pName,
@@ -2876,20 +2969,25 @@ export class LocalBackend {
         // resolves the await regardless of how long this body runs.
         if (opts.signal?.aborted)
             return null;
+        let repo;
         try {
             await this.refreshRepos();
-            await this.ensureInitialized(repoId);
+            // Fetch the resolved handle BEFORE init and pass it through, so a
+            // concurrent refresh can't remap the id to a different clone (#2067).
+            repo = this.repos.get(repoId);
+            if (repo)
+                await this.ensureInitialized(repo);
         }
         catch {
             return null;
         }
-        const repo = this.repos.get(repoId);
         if (!repo)
-            return null;
+            return null; // unknown repo → null (preserves contract)
         const dir = direction === 'downstream' ? 'downstream' : 'upstream';
         let rows;
         try {
-            rows = await executeParameterized(repoId, `MATCH (n) WHERE n.id = $uid
+            rows = await executeParameterized(repo.lbugPath, // pool keyed by the resolved clone's path, not the id
+            `MATCH (n) WHERE n.id = $uid
          RETURN n.id AS id, n.name AS name, n.filePath AS filePath, labels(n)[0] AS type
          LIMIT 1`, { uid });
         }
@@ -3199,10 +3297,10 @@ export class LocalBackend {
         return result;
     }
     async routeMap(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const routeFilter = params.route ? `AND n.name CONTAINS $route` : '';
         const queryParams = params.route ? { route: params.route } : {};
-        const routes = await this.fetchRoutesWithConsumers(repo.id, routeFilter, queryParams);
+        const routes = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
         if (routes.length === 0) {
             return {
                 routes: [],
@@ -3212,7 +3310,7 @@ export class LocalBackend {
                     : 'No routes found in this project.',
             };
         }
-        const flowMap = await this.fetchLinkedFlowsBatch(repo.id, routes.map((r) => r.id));
+        const flowMap = await this.fetchLinkedFlowsBatch(repo.lbugPath, routes.map((r) => r.id));
         return {
             routes: routes.map((r) => ({
                 route: r.name,
@@ -3225,10 +3323,10 @@ export class LocalBackend {
         };
     }
     async shapeCheck(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const routeFilter = params.route ? `AND n.name CONTAINS $route` : '';
         const queryParams = params.route ? { route: params.route } : {};
-        const allRoutes = await this.fetchRoutesWithConsumers(repo.id, routeFilter, queryParams);
+        const allRoutes = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
         const results = allRoutes
             .filter((r) => ((r.responseKeys && r.responseKeys.length > 0) ||
             (r.errorKeys && r.errorKeys.length > 0)) &&
@@ -3291,10 +3389,10 @@ export class LocalBackend {
         };
     }
     async toolMap(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         const toolFilter = params.tool ? `AND n.name CONTAINS $tool` : '';
         const queryParams = params.tool ? { tool: params.tool } : {};
-        const rows = await executeParameterized(repo.id, `
+        const rows = await executeParameterized(repo.lbugPath, `
       MATCH (n:Tool)
       WHERE n.id STARTS WITH 'Tool:' ${toolFilter}
       RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description
@@ -3307,7 +3405,7 @@ export class LocalBackend {
             };
         }
         const toolIds = rows.map((r) => r.id ?? r[0]);
-        const flowMap = await this.fetchLinkedFlowsBatch(repo.id, toolIds);
+        const flowMap = await this.fetchLinkedFlowsBatch(repo.lbugPath, toolIds);
         return {
             tools: rows.map((r) => {
                 const id = r.id ?? r[0];
@@ -3322,7 +3420,7 @@ export class LocalBackend {
         };
     }
     async apiImpact(repo, params) {
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         if (!params.route && !params.file) {
             return { error: 'Either "route" or "file" parameter is required.' };
         }
@@ -3337,12 +3435,12 @@ export class LocalBackend {
             routeFilter = `AND n.filePath CONTAINS $file`;
             queryParams.file = params.file;
         }
-        const routes = await this.fetchRoutesWithConsumers(repo.id, routeFilter, queryParams);
+        const routes = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
         if (routes.length === 0) {
             const target = params.route || params.file;
             return { error: `No routes found matching "${target}".` };
         }
-        const flowMap = await this.fetchLinkedFlowsBatch(repo.id, routes.map((r) => r.id));
+        const flowMap = await this.fetchLinkedFlowsBatch(repo.lbugPath, routes.map((r) => r.id));
         // Count how many routes share the same handler file (for middleware partial detection)
         const routeCountByHandler = new Map();
         for (const r of routes) {
@@ -3451,10 +3549,10 @@ export class LocalBackend {
      */
     async queryClusters(repoName, limit = 100) {
         const repo = await this.resolveRepo(repoName);
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         try {
             const rawLimit = Math.max(limit * 5, 200);
-            const clusters = await executeQuery(repo.id, `
+            const clusters = await executeQuery(repo.lbugPath, `
         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
@@ -3479,9 +3577,9 @@ export class LocalBackend {
      */
     async queryProcesses(repoName, limit = 50) {
         const repo = await this.resolveRepo(repoName);
-        await this.ensureInitialized(repo.id);
+        await this.ensureInitialized(repo);
         try {
-            const processes = await executeQuery(repo.id, `
+            const processes = await executeQuery(repo.lbugPath, `
         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
@@ -3507,8 +3605,8 @@ export class LocalBackend {
      */
     async queryClusterDetail(name, repoName) {
         const repo = await this.resolveRepo(repoName);
-        await this.ensureInitialized(repo.id);
-        const clusters = await executeParameterized(repo.id, `
+        await this.ensureInitialized(repo);
+        const clusters = await executeParameterized(repo.lbugPath, `
       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
@@ -3528,7 +3626,7 @@ export class LocalBackend {
             totalSymbols += s;
             weightedCohesion += (c.cohesion || 0) * s;
         }
-        const members = await executeParameterized(repo.id, `
+        const members = await executeParameterized(repo.lbugPath, `
       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
@@ -3556,8 +3654,8 @@ export class LocalBackend {
      */
     async queryProcessDetail(name, repoName) {
         const repo = await this.resolveRepo(repoName);
-        await this.ensureInitialized(repo.id);
-        const processes = await executeParameterized(repo.id, `
+        await this.ensureInitialized(repo);
+        const processes = await executeParameterized(repo.lbugPath, `
       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
@@ -3567,7 +3665,7 @@ export class LocalBackend {
             return { error: `Process '${name}' not found` };
         const proc = processes[0];
         const procId = proc.id || proc[0];
-        const steps = await executeParameterized(repo.id, `
+        const steps = await executeParameterized(repo.lbugPath, `
       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