gitnexus 1.6.12-rc.40 → 1.6.12-rc.41

package/dist/core/lbug/lbug-adapter.js

@@ -26,7 +26,7 @@ import { extensionManager, getFtsCapability, resolveAnalyzeInstallPolicy, } from
 // Remedy classification for LOAD failures (#2374/#2383). Pure + node:fs only, so
 // this adds no cycle: `extension-loader.ts` already depends on it.
 import { diagnoseExtensionLoad } from './extension-load-error.js';
-import { classifyDeleteAllError, closeLbugConnection, HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, bufferPoolExhaustionRemedy, openLbugConnection, sleep, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
+import { classifyDeleteAllError, closeLbugConnection, HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, isDbBusyError, isOpenRetryExhausted, isStorageVersionMismatchError, isWalCorruptionError, throwIfStorageVersionMismatch, bufferPoolExhaustionRemedy, openLbugConnection, sleep, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
 import { cleanQuarantinedMissingShadowWals, finalizeLbugSidecarsAfterClose, guardWalQuarantine, isMissingShadowSidecarError, isReadOnlyShadowReplayError, lbugLockRemediation, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, sidecarPreflightDisabled, } from './sidecar-recovery.js';
 import { isProcessAlive } from '../../utils/process-identity.js';
 import { logger } from '../logger.js';
@@ -569,6 +569,11 @@ const runSchemaCreationQueries = async (dbPath) => {
                 throw new Error(`LadybugDB WAL corruption detected at ${dbPath}. ${WAL_RECOVERY_SUGGESTION}\n` +
                     `  Original error: ${msg.slice(0, 200)}`);
             }
+            if (isStorageVersionMismatchError(err)) {
+                await safeClose();
+                resetOpenConnectionState();
+                throwIfStorageVersionMismatch(err);
+            }
             if (!msg.includes('already exists') && !isDbBusyError(err) && !isReadOnlyDbError(err)) {
                 logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
             }
@@ -662,8 +667,28 @@ const doInitLbug = async (dbPath, options = {}) => {
             logger,
             allowQuarantine: false,
         });
-        const opened = await openLbugConnection(lbug, dbPath, { readOnly: true });
-        const usable = await ensureReadOnlyConnectionUsable(dbPath, opened);
+        let usable;
+        try {
+            const opened = await openLbugConnection(lbug, dbPath, { readOnly: true });
+            // The storage-version check isn't necessarily enforced by the native
+            // engine until the first real query runs (ensureReadOnlyConnectionUsable's
+            // own probe query) — openLbugConnection alone can succeed on a
+            // mismatched file. Wrap both.
+            usable = await ensureReadOnlyConnectionUsable(dbPath, opened);
+        }
+        catch (err) {
+            // Not retryable: the on-disk file's storage version doesn't change on
+            // its own, so withLbugDb's retry loop (which only handles
+            // isDbBusyError) would just repeat the same native exception. Fail
+            // immediately with an actionable message instead (review finding on
+            // PR #3189 — this became reachable once the pinned engine version can
+            // trail behind whatever version last wrote an index, e.g. after
+            // downgrading the dependency). Mirrors the pool-adapter.ts check for
+            // the same error, on the separate open path /api/graph and /api/query
+            // actually use (withLbugDb, not the pool).
+            throwIfStorageVersionMismatch(err);
+            throw err;
+        }
         db = usable.db;
         conn = usable.conn;
         currentDbReadOnly = true;
@@ -763,10 +788,19 @@ const doInitLbug = async (dbPath, options = {}) => {
                 logger,
                 allowQuarantine: true,
             });
-            const opened = await openLbugConnection(lbug, dbPath);
-            db = opened.db;
-            conn = opened.conn;
-            currentDbReadOnly = false;
+            try {
+                const opened = await openLbugConnection(lbug, dbPath);
+                db = opened.db;
+                conn = opened.conn;
+                currentDbReadOnly = false;
+            }
+            catch (err) {
+                // Incremental analyze can hit a storage-version mismatch on construct
+                // or (more often) on the first schema query below. Fail immediately
+                // with the rebuild hint instead of warn-and-continue.
+                throwIfStorageVersionMismatch(err);
+                throw err;
+            }
         }
         finally {
             await releaseInitLock();

package/dist/core/lbug/lbug-config.d.ts

@@ -125,6 +125,10 @@ export declare const getEffectiveBufferPoolSize: () => number;
 export declare const bufferPoolExhaustionRemedy: (message: string, pageSize?: number | undefined) => string | undefined;
 export declare const WAL_RECOVERY_SUGGESTION = "WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.";
 export declare function isWalCorruptionError(err: unknown): boolean;
+export declare const STORAGE_VERSION_MISMATCH_SUGGESTION = "This index was written by a different @ladybugdb/core build (a different storage version) than the one currently installed. Run `gitnexus analyze --force` on this repo to rebuild it with the current engine.";
+export declare function isStorageVersionMismatchError(err: unknown): boolean;
+/** Throws the rebuild-hint Error when `err` is a storage-version mismatch. */
+export declare function throwIfStorageVersionMismatch(err: unknown): void;
 /**
  * True when `err` looks like a Ladybug WAL-checkpoint rotation/remove IO
  * failure. Tries strict matchers first (renames + removes), then falls

package/dist/core/lbug/lbug-config.js

@@ -513,6 +513,27 @@ export function isWalCorruptionError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return WAL_CORRUPTION_RE.test(msg);
 }
+/** Matches a LadybugDB storage-version mismatch: the on-disk file was
+ *  written by a different @ladybugdb/core build (a different storage
+ *  version) than the one currently installed — e.g. an index built by a
+ *  newer engine, opened after downgrading the pinned dependency. Example:
+ *  "Runtime exception: Trying to read a database file with a different
+ *  version. Database file version: 43, Current build storage version: 42" */
+const STORAGE_VERSION_MISMATCH_RE = /database file with a different version/i;
+export const STORAGE_VERSION_MISMATCH_SUGGESTION = 'This index was written by a different @ladybugdb/core build (a different storage version) than the one currently installed. Run `gitnexus analyze --force` on this repo to rebuild it with the current engine.';
+export function isStorageVersionMismatchError(err) {
+    if (!err)
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    return STORAGE_VERSION_MISMATCH_RE.test(msg);
+}
+/** Throws the rebuild-hint Error when `err` is a storage-version mismatch. */
+export function throwIfStorageVersionMismatch(err) {
+    if (!isStorageVersionMismatchError(err))
+        return;
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`${STORAGE_VERSION_MISMATCH_SUGGESTION} (${msg})`);
+}
 // ─── Ladybug WAL checkpoint IO error matchers ───────────────────────────────
 //
 // Matched against LadybugDB v0.18.0 (see `gitnexus/package.json`

package/dist/core/lbug/pool-adapter.d.ts

@@ -99,10 +99,13 @@ export declare function restoreStdout(): void;
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
  *
- * Concurrent calls for the same repoId are deduplicated — the second caller
- * awaits the first's in-progress init rather than starting a redundant one.
- */
-/**
+ * Concurrent calls (for the same repoId or different ones) serialize on
+ * poolLock below for evict / close / native open / register, so a second
+ * caller for a repo already being initialized waits its turn and then hits
+ * the "existing" fast path — no separate per-repoId dedup needed. Lock-retry
+ * *sleeps* run outside the mutex so one analyze-locked repo does not block
+ * every other pool init for LOCK_RETRY_DELAY_MS * attempt.
+ *
  * Returns `true` when this call (re)opened a fresh handle onto the current
  * on-disk file, `false` when it reused/served the existing handle (unchanged,
  * or changed-but-a-query-is-in-flight). Callers that gate their own freshness

package/dist/core/lbug/pool-adapter.js

@@ -19,7 +19,7 @@ import lbug from '@ladybugdb/core';
 import { isReadOnlyDbError, loadFTSExtension, loadVectorExtension } from './lbug-adapter.js';
 import { closeQueryResults } from './query-result-utils.js';
 import { warnIfQueryTextUnbounded } from './query-batch.js';
-import { createLbugDatabase, isWalCorruptionError, toNativeSafePath, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
+import { createLbugDatabase, isWalCorruptionError, sleep, throwIfStorageVersionMismatch, toNativeSafePath, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
 import { guardWalQuarantine, isMissingFsError, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, statIfExists, } from './sidecar-recovery.js';
 export async function statDbIdentity(dbPath) {
     try {
@@ -124,7 +124,37 @@ function ensureIdleTimer() {
             if (pinnedRepos.has(repoId))
                 continue;
             if (now - entry.lastUsed > IDLE_TIMEOUT_MS && entry.checkedOut === 0) {
-                closeOne(repoId);
+                // Routed through the same mutex as initLbug (not awaited here — this
+                // sweep is periodic best-effort cleanup with nothing waiting on it).
+                // closeOne now removes the pool entry before its awaited db.close(),
+                // so an unsynchronized idle close racing a concurrent initLbug for
+                // the same repoId would let that init treat the repo as absent and
+                // open a fresh native handle on the same file while the idle close's
+                // checkpoint is still in flight — reopening the exact race this pool
+                // rework exists to close, just via the idle path instead of LRU
+                // eviction (review finding on PR #3187). withPoolLock serializes it
+                // against every initLbug call the same way evictLRU already is.
+                //
+                // This callback can now sit queued behind an in-progress initLbug
+                // before its turn comes, and that init's existing-entry path (or a
+                // concurrent touchRepo()) can refresh lastUsed in the meantime — so
+                // the repo may no longer be idle by the time this actually runs.
+                // Re-check inside the lock, right before closing, instead of trusting
+                // the snapshot taken above (second review finding on PR #3187).
+                // Also re-check pinnedRepos: the outer loop's check above is the
+                // same kind of stale snapshot — pinRepo() can run while this
+                // callback is queued behind an in-progress initLbug, and closing a
+                // repo the caller just pinned would drop that lease entirely
+                // (review finding on PR #3189).
+                withPoolLock(async () => {
+                    const current = pool.get(repoId);
+                    if (current &&
+                        !pinnedRepos.has(repoId) &&
+                        Date.now() - current.lastUsed > IDLE_TIMEOUT_MS &&
+                        current.checkedOut === 0) {
+                        await closeOne(repoId);
+                    }
+                });
             }
         }
     }, 60_000);
@@ -202,7 +232,7 @@ export const getMaxResidentRepos = () => MAX_POOL_SIZE;
  * entry is pinned, no eviction occurs and the pool transiently exceeds
  * MAX_POOL_SIZE (see the pinnedRepos docstring).
  */
-function evictLRU() {
+async function evictLRU() {
     if (pool.size < MAX_POOL_SIZE)
         return;
     let oldestId = null;
@@ -216,7 +246,12 @@ function evictLRU() {
         }
     }
     if (oldestId) {
-        closeOne(oldestId);
+        // Awaited: the caller opens a new connection right after evicting one, and
+        // closeOne's db.close() below triggers a checkpoint. A fire-and-forget close
+        // here let that new open race the still-in-flight checkpoint of the evicted
+        // repo, surfacing as "Cannot open database in read-only mode while checkpoint
+        // is in progress" on the read path.
+        await closeOne(oldestId);
     }
 }
 /**
@@ -224,7 +259,7 @@ function evictLRU() {
  * shared Database ref.  Only closes the Database when no other repoIds
  * reference it (refCount === 0).
  */
-function closeOne(repoId) {
+async function closeOne(repoId) {
     const entry = pool.get(repoId);
     if (!entry)
         return;
@@ -251,6 +286,27 @@ function closeOne(repoId) {
     entry.available.length = 0;
     // Checked-out connections can't be closed here — they're in-flight.
     // The checkin() function detects entry.closed and closes them on return.
+    // Remove the entry — and clear its pin, and notify listeners — BEFORE the
+    // possible await below. `available` is already empty and `closed` is
+    // already set, so nothing further to lose; but `shared.db.close()` can
+    // suspend, and until this repoId is actually gone from `pool`,
+    // `isLbugReady(repoId)` (a bare `pool.has`) still reports true. A
+    // concurrent same-repo `initLbug`/query during that window would see a
+    // "ready" pool entry with no available connections and no in-flight
+    // open — a zombie that `checkout` can only fail on with a misleading
+    // "pool integrity error" instead of just reopening. Deleting first makes
+    // that window disappear: any concurrent caller instead sees "not
+    // initialized" and takes the normal fresh-open path.
+    pool.delete(repoId);
+    pinnedRepos.delete(repoId);
+    for (const listener of poolCloseListeners) {
+        try {
+            listener(repoId);
+        }
+        catch {
+            // Isolate listener failures — teardown must complete.
+        }
+    }
     // Only close the Database when no other repoIds reference it.
     // External databases (injected via initLbugWithDb) are never closed here —
     // the core adapter owns them and handles their lifecycle.
@@ -268,26 +324,19 @@ function closeOne(repoId) {
                 shared.vectorLoadPromise = undefined;
             }
             else {
-                shared.db.close().catch(() => { });
+                // Awaited (unlike the per-connection closes above): this is the shared
+                // Database handle whose close() drives the checkpoint that the caller's
+                // subsequent reopen (evictLRU / the "idle & changed" path below) must not
+                // race. See the awaited call site in evictLRU for the full rationale.
+                await shared.db.close().catch(() => { });
                 dbCache.delete(entry.dbPath);
             }
         }
     }
-    pool.delete(repoId);
-    // Clear any eviction pin — the entry is gone, so the pin is meaningless and
-    // would otherwise leak across operations in a long-lived process. Teardown
-    // is authoritative: an explicit close always wins over a pin.
+    // Close yields on native db.close() above. A pinRepo during that await
+    // would otherwise survive teardown and apply to the next init, contradicting
+    // the documented lease contract (pins do not outlive closeOne).
     pinnedRepos.delete(repoId);
-    // Notify listeners AFTER the pool entry is gone so any cache-invalidation
-    // they perform is consistent with `isLbugReady(repoId) === false`.
-    for (const listener of poolCloseListeners) {
-        try {
-            listener(repoId);
-        }
-        catch {
-            // Isolate listener failures — teardown must complete.
-        }
-    }
     traceRss('close', repoId);
 }
 /**
@@ -529,16 +578,31 @@ async function tryQuarantineAndReopen(dbPath, repoId) {
         `Run \`gitnexus analyze\` to rebuild the index.\n`);
     return await openReadOnlyDatabase(dbPath);
 }
-/** Deduplicates concurrent initLbug calls for the same repoId */
-const initPromises = new Map();
+// Serializes pool mutations (evict / close / native open / register) across
+// concurrent callers. Awaiting closeOne/evictLRU closes the race within a
+// single call; this mutex makes those mutations mutually exclusive across
+// repos so two inits cannot race each other's checkpoint.
+let poolLock = Promise.resolve();
+function withPoolLock(fn) {
+    const run = poolLock.then(fn, fn);
+    poolLock = run.then(() => undefined, () => undefined);
+    return run;
+}
+function ladybugUnavailableError(repoId, err) {
+    return new Error(`LadybugDB unavailable for ${repoId}. Another process may be rebuilding the index. ` +
+        `Retry later. (${err?.message || 'unknown error'})`);
+}
 /**
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
  *
- * Concurrent calls for the same repoId are deduplicated — the second caller
- * awaits the first's in-progress init rather than starting a redundant one.
- */
-/**
+ * Concurrent calls (for the same repoId or different ones) serialize on
+ * poolLock below for evict / close / native open / register, so a second
+ * caller for a repo already being initialized waits its turn and then hits
+ * the "existing" fast path — no separate per-repoId dedup needed. Lock-retry
+ * *sleeps* run outside the mutex so one analyze-locked repo does not block
+ * every other pool init for LOCK_RETRY_DELAY_MS * attempt.
+ *
  * Returns `true` when this call (re)opened a fresh handle onto the current
  * on-disk file, `false` when it reused/served the existing handle (unchanged,
  * or changed-but-a-query-is-in-flight). Callers that gate their own freshness
@@ -546,6 +610,19 @@ const initPromises = new Map();
  * return value; callers that only need the pool ready can ignore it.
  */
 export const initLbug = async (repoId, dbPath) => {
+    let lastError;
+    for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
+        const result = await withPoolLock(() => initLbugInner(repoId, dbPath));
+        if (result.status === 'done')
+            return result.reopened;
+        lastError = result.error;
+        if (attempt === LOCK_RETRY_ATTEMPTS)
+            break;
+        await sleep(LOCK_RETRY_DELAY_MS * attempt);
+    }
+    throw ladybugUnavailableError(repoId, lastError);
+};
+const initLbugInner = async (repoId, dbPath) => {
     const existing = pool.get(repoId);
     if (existing) {
         existing.lastUsed = Date.now();
@@ -554,8 +631,9 @@ export const initLbug = async (repoId, dbPath) => {
         // unlinked-but-open) inode until LRU/idle eviction — a stale-read window
         // of up to IDLE_TIMEOUT_MS after analyze finishes.
         const current = await statDbIdentity(dbPath);
-        if (!dbIdentityChanged(existing.dbIdentity, current))
-            return false; // unchanged → reuse
+        if (!dbIdentityChanged(existing.dbIdentity, current)) {
+            return { status: 'done', reopened: false }; // unchanged → reuse
+        }
         // A query is in flight on this entry; closing its connection (and the
         // shared Database at refCount 0) mid-use is a native use-after-free. Serve
         // the current handle for this dispatch — the next initLbug that finds the
@@ -567,26 +645,11 @@ export const initLbug = async (repoId, dbPath) => {
         // freshness THROUGH initLbug (rather than calling closeLbug directly) get
         // this guard for free; that is why LocalBackend delegates here (#2614).
         if (existing.checkedOut > 0)
-            return false;
-        closeOne(repoId); // idle & changed → evict, then fall through to reopen the new file
-    }
-    // Deduplicate concurrent init calls for the same repoId —
-    // prevents double-init race when multiple parallel tool calls
-    // trigger initialization for the same repo simultaneously.
-    const pending = initPromises.get(repoId);
-    if (pending) {
-        await pending;
-        return true;
+            return { status: 'done', reopened: false };
+        // Awaited: see the rationale on the evictLRU call site in doInitLbug below.
+        await closeOne(repoId); // idle & changed → evict, then fall through to reopen the new file
     }
-    const promise = doInitLbug(repoId, dbPath);
-    initPromises.set(repoId, promise);
-    try {
-        await promise;
-    }
-    finally {
-        initPromises.delete(repoId);
-    }
-    return true;
+    return doInitLbug(repoId, dbPath);
 };
 /**
  * Internal init — creates DB, pre-warms connections, loads FTS, then registers pool.
@@ -601,7 +664,15 @@ async function doInitLbug(repoId, dbPath) {
     catch {
         throw new Error(`LadybugDB not found at ${dbPath}. Run: gitnexus analyze`);
     }
-    evictLRU();
+    // Awaited: without this, the connection opened just below could race the
+    // checkpoint from the LRU victim's still-in-flight close (see evictLRU /
+    // closeOne). The caller holds withPoolLock for this attempt, so this await
+    // only covers this call's own evict-then-reopen — not other callers.
+    // Lock-retry re-enters this function after sleeping *outside* the mutex.
+    // evictLRU is a no-op unless the pool is full again (another repo may have
+    // taken the slot we freed on a prior attempt). Skipping it on retry would
+    // let a 6th native open race a still-resident victim's checkpoint.
+    await evictLRU();
     // Reuse an existing native Database if another repoId already opened this path.
     // This prevents buffer manager exhaustion from multiple mmap regions on the same file.
     let shared = dbCache.get(dbPath);
@@ -623,51 +694,48 @@ async function doInitLbug(repoId, dbPath) {
     if (!shared) {
         // Open in read-only mode — MCP server never writes to the database.
         // This allows multiple MCP server instances to read concurrently, and
-        // avoids lock conflicts when `gitnexus analyze` is writing.
-        let lastError = null;
-        for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
-            try {
-                const db = await openReadOnlyDatabase(dbPath);
-                shared = { db, refCount: 0, ftsLoaded: false, dbIdentity: await statDbIdentity(dbPath) };
-                dbCache.set(dbPath, shared);
-                break;
-            }
-            catch (err) {
-                lastError = err instanceof Error ? err : new Error(String(err));
-                if (isWalCorruptionError(lastError)) {
-                    try {
-                        const db = await tryQuarantineAndReopen(dbPath, repoId);
-                        shared = {
-                            db,
-                            refCount: 0,
-                            ftsLoaded: false,
-                            dbIdentity: await statDbIdentity(dbPath),
-                        };
-                        dbCache.set(dbPath, shared);
-                        break;
-                    }
-                    catch (retryErr) {
-                        throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ${WAL_RECOVERY_SUGGESTION} ` +
-                            `(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`);
-                    }
+        // avoids lock conflicts when `gitnexus analyze` is writing. This attempt
+        // is one native open; lock-retry backoff lives in initLbug.
+        try {
+            const db = await openReadOnlyDatabase(dbPath);
+            shared = { db, refCount: 0, ftsLoaded: false, dbIdentity: await statDbIdentity(dbPath) };
+            dbCache.set(dbPath, shared);
+        }
+        catch (err) {
+            const lastError = err instanceof Error ? err : new Error(String(err));
+            // Not retryable: the on-disk file's storage version doesn't change
+            // on its own. Fail immediately with an actionable message.
+            throwIfStorageVersionMismatch(lastError);
+            if (isWalCorruptionError(lastError)) {
+                try {
+                    const db = await tryQuarantineAndReopen(dbPath, repoId);
+                    shared = {
+                        db,
+                        refCount: 0,
+                        ftsLoaded: false,
+                        dbIdentity: await statDbIdentity(dbPath),
+                    };
+                    dbCache.set(dbPath, shared);
+                }
+                catch (retryErr) {
+                    throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ${WAL_RECOVERY_SUGGESTION} ` +
+                        `(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`);
                 }
+            }
+            if (!shared) {
                 if (lastError.message.startsWith('LadybugDB checkpoint sidecar is missing') ||
                     lastError.message.startsWith('LadybugDB checkpoint sidecar is present but unreachable') ||
                     lastError.message.startsWith('GitNexus could not move the LadybugDB WAL sidecar') ||
                     isMissingShadowSidecarError(lastError)) {
                     throw lastError;
                 }
-                const isLockError = lastError.message.includes('Could not set lock') ||
-                    /\block(\b|ed|ing)/i.test(lastError.message);
-                if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS)
-                    break;
-                await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS * attempt));
+                if (lastError.message.includes('Could not set lock') ||
+                    /\block(\b|ed|ing)/i.test(lastError.message)) {
+                    return { status: 'retry', error: lastError };
+                }
+                throw ladybugUnavailableError(repoId, lastError);
             }
         }
-        if (!shared) {
-            throw new Error(`LadybugDB unavailable for ${repoId}. Another process may be rebuilding the index. ` +
-                `Retry later. (${lastError?.message || 'unknown error'})`);
-        }
     }
     shared.refCount++;
     const db = shared.db;
@@ -711,6 +779,7 @@ async function doInitLbug(repoId, dbPath) {
     });
     ensureIdleTimer();
     traceRss('init', repoId);
+    return { status: 'done', reopened: true };
 }
 /**
  * Initialize a pool entry from a pre-existing Database object.
@@ -724,6 +793,9 @@ async function doInitLbug(repoId, dbPath) {
  * repoId already injected it), the existing entry is reused.
  */
 export async function initLbugWithDb(repoId, existingDb, dbPath) {
+    return withPoolLock(() => initLbugWithDbInner(repoId, existingDb, dbPath));
+}
+async function initLbugWithDbInner(repoId, existingDb, dbPath) {
     const existing = pool.get(repoId);
     if (existing) {
         existing.lastUsed = Date.now();
@@ -1060,12 +1132,29 @@ export const executeParameterized = async (repoId, cypher, params) => {
  */
 export const closeLbug = async (repoId) => {
     if (repoId) {
-        closeOne(repoId);
+        // Locked: closeOne now deletes the pool entry before its awaited
+        // db.close() finishes, so an unlocked call here could race a concurrent
+        // initLbug(repoId, ...) — that init could acquire the lock right after
+        // the delete, see no cached entry, and start opening a fresh connection
+        // while this close's checkpoint is still in flight, reopening the exact
+        // race withPoolLock exists to close (review finding on PR #3189).
+        // Awaited: closeOne is now async (see evictLRU's rationale); callers of
+        // closeLbug rely on pool.delete() having already run — e.g. isLbugReady()
+        // returning false — by the time this promise resolves.
+        await withPoolLock(() => closeOne(repoId));
         return;
     }
-    for (const id of [...pool.keys()]) {
-        closeOne(id);
-    }
+    // Locked for the same reason as the per-repoId branch above, plus: without
+    // this, an initLbug that runs while this loop is mid-await (closeOne
+    // yields during the native close) can register a fresh pool entry after
+    // `pool.keys()` was already snapshotted, so a caller expecting closeLbug()
+    // to mean "pool is now empty" would find that new entry still resident
+    // (review finding on PR #3187).
+    await withPoolLock(async () => {
+        for (const id of [...pool.keys()]) {
+            await closeOne(id);
+        }
+    });
     if (idleTimer) {
         clearInterval(idleTimer);
         idleTimer = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.12-rc.40",
+  "version": "1.6.12-rc.41",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -57,7 +57,7 @@
     "version": "node scripts/sync-plugin-manifests.mjs"
   },
   "dependencies": {
-    "@ladybugdb/core": "^0.19.0",
+    "@ladybugdb/core": "0.18.3",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "busboy": "^1.6.0",