gitnexus 1.6.9-rc.29 → 1.6.9-rc.30

package/dist/core/group/bridge-db.d.ts

@@ -1,5 +1,51 @@
 import type { LbugValue } from '@ladybugdb/core';
 import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot } from './types.js';
+/**
+ * Serialize an operation on a cached handle's per-handle FIFO chain. Mirrors the
+ * promise-chain mechanic of `lbug/conn-lock.ts` (install a fresh unresolved
+ * tail, await the prior holder, release in `finally` so a throw never wedges the
+ * chain) — but keyed per handle, not a single global lock. No re-entry guard:
+ * `queryBridge` is a leaf (it never calls another locked bridge helper), and the
+ * native close runs outside the lock gated on `refs === 0`.
+ */
+export declare function withHandleLock<T>(lock: {
+    lockTail: Promise<void>;
+}, fn: () => Promise<T>): Promise<T>;
+/**
+ * Get or create a cached read-only bridge handle for `groupDir`.
+ *
+ * - First call: delegates to `openBridgeDbReadOnly`, records the file's
+ *   `mtimeMs`, and caches the handle.
+ * - Subsequent calls (mtime unchanged): returns the cached handle — no
+ *   reopen, no OS file-handle churn.
+ * - After the file's mtime changes (external writer, e.g. another process
+ *   ran `gitnexus group sync`): closes the stale handle, opens a fresh
+ *   one, and updates the cache.
+ * - After the file disappears (ENOENT): invalidates cache, returns null.
+ *
+ * Returns `null` when the bridge file is missing, has an incompatible
+ * schema version, or cannot be opened even after the retry loop in
+ * `openBridgeDbReadOnly`.
+ */
+export declare function getCachedBridgeReadOnly(groupDir: string): Promise<BridgeHandle | null>;
+/**
+ * Invalidate the cached read-only handle for `groupDir`. Drops it from the
+ * cache immediately; the native close is deferred until any in-flight reader
+ * leases drain (see {@link evictBridgeEntry}). With no concurrent reader this
+ * resolves only after the handle is actually closed — which is why
+ * `writeBridge` awaits it before its atomic rename (Windows: a still-open RO
+ * handle would block the rename with EBUSY).
+ */
+export declare function invalidateBridgeCache(groupDir: string): Promise<void>;
+/**
+ * Close ALL cached bridge handles. Call on process shutdown only — it force-
+ * closes regardless of refs (safe at `beforeExit`, which fires only at
+ * event-loop quiescence, so no query is in flight). Do NOT wire this to a
+ * SIGTERM/SIGINT handler that can fire mid-request: that would close a handle
+ * under a live query. Routes through `finalizeBridgeClose` for the close-once
+ * guarantee.
+ */
+export declare function closeAllCachedBridges(): Promise<void>;
 export declare function contractNodeId(repo: string, contractId: string, role: string, filePath: string): string;
 /**
  * In-memory index of contract node IDs keyed three ways, mirroring the
@@ -47,6 +93,22 @@ export declare function findContractNode(index: ContractLookupIndex, repo: strin
 export declare function openBridgeDb(dbPath: string): Promise<BridgeHandle>;
 export declare function ensureBridgeSchema(handle: BridgeHandle): Promise<void>;
 export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, params?: Record<string, LbugValue>): Promise<T[]>;
+/**
+ * Release a caller's reference to a bridge handle.
+ *
+ * - **Cache-owned handle** (returned by `getCachedBridgeReadOnly`): this is the
+ *   matching *release* for that acquire — it decrements the lease refcount, it
+ *   does NOT close the native handle. The cache owns the lifetime; the handle
+ *   closes on explicit `invalidateBridgeCache`, mtime-eviction, or process
+ *   shutdown. If the entry was already evicted and this is the last lease, the
+ *   deferred native close fires here (exactly once).
+ * - **Uncached/writable handle** (e.g. the `writeBridge` temp DB): closes the
+ *   native handle for real (CHECKPOINT-flush for writable handles).
+ *
+ * Contract: before renaming or deleting `bridge.lbug`, call
+ * `invalidateBridgeCache` (not this) — `closeBridgeDb` on a cache-owned handle
+ * is a lease release, so the file may stay open under other readers.
+ */
 export declare function closeBridgeDb(handle: BridgeHandle): Promise<void>;
 export declare function retryRename(src: string, dst: string, attempts?: number): Promise<void>;
 export declare function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void>;

package/dist/core/group/bridge-db.js

@@ -6,7 +6,9 @@ import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js
 import { closeLbugConnection, openLbugConnection, } from '../lbug/lbug-config.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
 import { createLogger } from '../logger.js';
-const bridgeLogger = createLogger('bridge-db', { debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE' });
+const bridgeLogger = createLogger('bridge-db', {
+    debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE',
+});
 /**
  * Sidecar files that LadybugDB creates next to a `bridge.lbug` file.
  *
@@ -24,6 +26,294 @@ const bridgeLogger = createLogger('bridge-db', { debugEnvVar: 'GITNEXUS_DEBUG_BR
  * cleaned up explicitly or the next writer trips the database-id check.
  */
 const LBUG_SIDECAR_SUFFIXES = ['.wal', '.shadow'];
+/**
+ * Windows-only bound on how long `invalidateBridgeCache` waits for in-flight
+ * readers to release before letting `writeBridge` rename. Past this, it falls
+ * through and `retryRename` (EBUSY ×3) copes — so a pathologically long reader
+ * can never wedge `group_sync`. ponytail: fixed 5s ceiling; make it
+ * configurable if a real workload shows reads routinely outlasting it.
+ */
+const WINDOWS_DRAIN_TIMEOUT_MS = 5000;
+const cachedBridgeHandles = new Map();
+/**
+ * Reverse lookup: cache entry by its `BridgeHandle`. Lets `queryBridge` and
+ * `closeBridgeDb` find an entry from just the handle — including an *evicted*
+ * entry that is no longer in `cachedBridgeHandles` but whose native handle a
+ * lease still holds open. Uncached/writable handles (the `writeBridge` temp DB)
+ * are absent here, which is how those paths opt out of the lock and refcount.
+ */
+const bridgeEntryByHandle = new WeakMap();
+/**
+ * In-flight opens keyed by groupDir. Prevents the TOCTOU race where two
+ * concurrent cache-miss calls both open a fresh handle and the second
+ * overwrites the first in `cachedBridgeHandles` — leaking the first
+ * handle. Mirrors the `local-backend.ts:1293` reinitPromises pattern.
+ */
+const inFlightOpens = new Map();
+function bridgeCacheKey(groupDir) {
+    return path.resolve(groupDir);
+}
+/**
+ * Serialize an operation on a cached handle's per-handle FIFO chain. Mirrors the
+ * promise-chain mechanic of `lbug/conn-lock.ts` (install a fresh unresolved
+ * tail, await the prior holder, release in `finally` so a throw never wedges the
+ * chain) — but keyed per handle, not a single global lock. No re-entry guard:
+ * `queryBridge` is a leaf (it never calls another locked bridge helper), and the
+ * native close runs outside the lock gated on `refs === 0`.
+ */
+export async function withHandleLock(lock, fn) {
+    const prior = lock.lockTail;
+    let release;
+    lock.lockTail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await prior;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Close a cached entry's native handle exactly once. Guarded by `closeStarted`
+ * so the mtime-evict path, `invalidateBridgeCache`, the last lease release, and
+ * `closeAllCachedBridges` can all reach here and only one native close runs.
+ */
+async function finalizeBridgeClose(entry) {
+    if (entry.closeStarted)
+        return;
+    entry.closeStarted = true;
+    bridgeEntryByHandle.delete(entry.handle);
+    try {
+        await closeBridgeHandle(entry.handle);
+    }
+    finally {
+        entry.resolveDrained();
+    }
+}
+/**
+ * Remove an entry from the cache and release its native handle. The native
+ * close is DEFERRED until in-flight leases drain (`refs === 0`): closing a
+ * handle a concurrent `@group` reader is still querying is a native
+ * use-after-free (the `conn-lock.ts` hazard). When `refs === 0` (the common
+ * single-threaded case — e.g. `group_sync` with no concurrent read) the close
+ * runs now and the returned promise resolves when it completes, so
+ * `writeBridge`'s atomic rename never races a live RO handle on Windows.
+ *
+ * When `refs > 0` (a concurrent reader holds a lease), the native close is
+ * deferred to the last `closeBridgeDb` release — closing now would be a
+ * use-after-free. Platform split for the rename that follows:
+ *   - POSIX: return immediately. The rename succeeds over the still-open RO
+ *     handle (old inode survives for the reader); no wait, no starvation.
+ *   - Windows: a rename over an open handle fails (EBUSY), so wait — bounded by
+ *     `WINDOWS_DRAIN_TIMEOUT_MS` — for the reader to release and the deferred
+ *     close to complete, then the rename is clean. On timeout, fall through and
+ *     let `retryRename` cope, so a slow reader can never wedge `group_sync`.
+ *
+ * This is the single eviction path for BOTH the mtime-change branch and
+ * `invalidateBridgeCache`.
+ */
+async function evictBridgeEntry(key, entry) {
+    if (!entry.evicted) {
+        entry.evicted = true;
+        if (cachedBridgeHandles.get(key) === entry)
+            cachedBridgeHandles.delete(key);
+    }
+    if (entry.refs <= 0) {
+        await finalizeBridgeClose(entry);
+        return;
+    }
+    // refs > 0: close deferred to the last closeBridgeDb release.
+    if (process.platform === 'win32') {
+        // Windows needs the handle closed before writeBridge renames. Wait (bounded)
+        // for readers to drain; on timeout, retryRename handles the residual EBUSY.
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, WINDOWS_DRAIN_TIMEOUT_MS);
+        });
+        await Promise.race([entry.drained, timeout]).finally(() => clearTimeout(timer));
+    }
+}
+/**
+ * Close a BridgeHandle's native resources without touching the cache.
+ * Shared by `closeBridgeDb` (uncached handles) and the cache invalidation
+ * / shutdown paths so neither duplicates the close logic.
+ */
+async function closeBridgeHandle(handle) {
+    if (!handle._readOnly) {
+        try {
+            await handle._conn.query('CHECKPOINT');
+        }
+        catch {
+            /* ignore — older LadybugDB or schemaless DB may not accept it */
+        }
+    }
+    try {
+        await handle._conn.close();
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        await handle._db.close();
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Get or create a cached read-only bridge handle for `groupDir`.
+ *
+ * - First call: delegates to `openBridgeDbReadOnly`, records the file's
+ *   `mtimeMs`, and caches the handle.
+ * - Subsequent calls (mtime unchanged): returns the cached handle — no
+ *   reopen, no OS file-handle churn.
+ * - After the file's mtime changes (external writer, e.g. another process
+ *   ran `gitnexus group sync`): closes the stale handle, opens a fresh
+ *   one, and updates the cache.
+ * - After the file disappears (ENOENT): invalidates cache, returns null.
+ *
+ * Returns `null` when the bridge file is missing, has an incompatible
+ * schema version, or cannot be opened even after the retry loop in
+ * `openBridgeDbReadOnly`.
+ */
+export async function getCachedBridgeReadOnly(groupDir) {
+    const key = bridgeCacheKey(groupDir);
+    const dbPath = path.join(groupDir, 'bridge.lbug');
+    // Fast path: cache hit, unchanged mtime → lease the cached handle.
+    const entry = cachedBridgeHandles.get(key);
+    if (entry) {
+        try {
+            const stat = await fsp.stat(dbPath);
+            // Re-check `evicted` AFTER the await: a concurrent writeBridge/invalidate
+            // may have evicted this entry while we awaited `stat`. Leasing an evicted
+            // (closing) handle would be a use-after-close. The `refs++` is the first
+            // synchronous statement after the check, so no evictor can slip between.
+            if (!entry.evicted && stat.mtimeMs === entry.mtime) {
+                entry.refs++;
+                return entry.handle;
+            }
+        }
+        catch {
+            // File disappeared (ENOENT) — fall through to evict + reopen.
+        }
+        // mtime changed or file gone — evict (defers the native close if a
+        // concurrent reader still holds a lease; closes now otherwise).
+        if (!entry.evicted)
+            await evictBridgeEntry(key, entry);
+    }
+    // TOCTOU guard: if another caller is already opening for this key, await
+    // their in-flight promise and take a lease on the result instead of opening
+    // a second handle.
+    const inFlight = inFlightOpens.get(key);
+    if (inFlight) {
+        const handle = await inFlight;
+        if (!handle)
+            return null;
+        // Same post-await guard as the fast path: the opener's entry may have been
+        // evicted between caching and this awaiter resuming. Only lease a live,
+        // identity-matched entry; otherwise retry from the top for a fresh handle.
+        const opened = cachedBridgeHandles.get(key);
+        if (opened && !opened.evicted && opened.handle === handle) {
+            opened.refs++;
+            return handle;
+        }
+        return getCachedBridgeReadOnly(groupDir);
+    }
+    const openPromise = (async () => {
+        try {
+            const handle = await openBridgeDbReadOnly(groupDir);
+            if (!handle)
+                return null;
+            let mtime = 0;
+            try {
+                const stat = await fsp.stat(dbPath);
+                mtime = stat.mtimeMs;
+            }
+            catch {
+                // bridge.lbug not stat-able right after open (rare race). Leaving
+                // mtime at 0 means the next call's fast-path comparison won't match
+                // (a real file's mtime is never 0), so it re-opens. Benign: the handle
+                // still works for this caller; we just don't cache-reuse it until a
+                // later open records a real mtime.
+            }
+            let resolveDrained;
+            const drained = new Promise((resolve) => {
+                resolveDrained = resolve;
+            });
+            const newEntry = {
+                handle,
+                mtime,
+                refs: 0,
+                evicted: false,
+                closeStarted: false,
+                lockTail: Promise.resolve(),
+                drained,
+                resolveDrained,
+            };
+            cachedBridgeHandles.set(key, newEntry);
+            bridgeEntryByHandle.set(handle, newEntry);
+            return handle;
+        }
+        finally {
+            inFlightOpens.delete(key);
+        }
+    })();
+    inFlightOpens.set(key, openPromise);
+    // Each caller (the opener and every awaiter) takes exactly one lease here, so
+    // refs counts callers correctly even under inFlightOpens coalescing.
+    const handle = await openPromise;
+    if (!handle)
+        return null;
+    const opened = cachedBridgeHandles.get(key);
+    if (opened && !opened.evicted && opened.handle === handle) {
+        opened.refs++;
+        return handle;
+    }
+    return getCachedBridgeReadOnly(groupDir);
+}
+/**
+ * Invalidate the cached read-only handle for `groupDir`. Drops it from the
+ * cache immediately; the native close is deferred until any in-flight reader
+ * leases drain (see {@link evictBridgeEntry}). With no concurrent reader this
+ * resolves only after the handle is actually closed — which is why
+ * `writeBridge` awaits it before its atomic rename (Windows: a still-open RO
+ * handle would block the rename with EBUSY).
+ */
+export async function invalidateBridgeCache(groupDir) {
+    const key = bridgeCacheKey(groupDir);
+    const entry = cachedBridgeHandles.get(key);
+    if (entry)
+        await evictBridgeEntry(key, entry);
+}
+/**
+ * Close ALL cached bridge handles. Call on process shutdown only — it force-
+ * closes regardless of refs (safe at `beforeExit`, which fires only at
+ * event-loop quiescence, so no query is in flight). Do NOT wire this to a
+ * SIGTERM/SIGINT handler that can fire mid-request: that would close a handle
+ * under a live query. Routes through `finalizeBridgeClose` for the close-once
+ * guarantee.
+ */
+export async function closeAllCachedBridges() {
+    const entries = [...cachedBridgeHandles.values()];
+    cachedBridgeHandles.clear();
+    await Promise.all(entries.map((e) => finalizeBridgeClose(e)));
+}
+// Best-effort process-exit cleanup. 'beforeExit' fires before 'exit' and
+// lets async work drain (unlike 'exit' which is synchronous-only). It does
+// NOT fire on process.exit()/SIGTERM/SIGINT — but that is fine here: the OS
+// reclaims all handles on any exit path, and for read-only handles there is
+// no WAL to flush, so the only thing lost on signal death is a tidy close
+// (cosmetic). We deliberately do NOT register a SIGTERM/SIGINT handler: a
+// signal can fire mid-request, and closeAllCachedBridges force-closes
+// regardless of refs, which would close a handle under a live query. Shutdown
+// sequencing is the MCP server's responsibility — it should call
+// closeAllCachedBridges() at a quiescent point (also how tests get a
+// deterministic teardown).
+process.once('beforeExit', () => {
+    void closeAllCachedBridges();
+});
 async function removeLbugFile(basePath) {
     const candidates = [basePath, ...LBUG_SIDECAR_SUFFIXES.map((s) => `${basePath}${s}`)];
     for (const f of candidates) {
@@ -131,20 +421,29 @@ export async function ensureBridgeSchema(handle) {
     }
 }
 export async function queryBridge(handle, cypher, params) {
-    const conn = handle._conn;
-    if (params && Object.keys(params).length > 0) {
-        const stmt = await conn.prepare(cypher);
-        if (!stmt.isSuccess()) {
-            const errMsg = await stmt.getErrorMessage();
-            throw new Error(`Bridge query prepare failed: ${errMsg}`);
+    const run = async () => {
+        const conn = handle._conn;
+        if (params && Object.keys(params).length > 0) {
+            const stmt = await conn.prepare(cypher);
+            if (!stmt.isSuccess()) {
+                const errMsg = await stmt.getErrorMessage();
+                throw new Error(`Bridge query prepare failed: ${errMsg}`);
+            }
+            const queryResult = await conn.execute(stmt, params);
+            const result = unwrapQueryResult(queryResult);
+            return (await result.getAll());
         }
-        const queryResult = await conn.execute(stmt, params);
+        const queryResult = await conn.query(cypher);
         const result = unwrapQueryResult(queryResult);
         return (await result.getAll());
-    }
-    const queryResult = await conn.query(cypher);
-    const result = unwrapQueryResult(queryResult);
-    return (await result.getAll());
+    };
+    // Cached RO handles are shared across concurrent @group callers, so serialize
+    // conn ops per handle (a LadybugDB Connection is not safe for concurrent
+    // queries — conn-lock.ts). Uncached/writable handles (the writeBridge temp DB)
+    // are single-threaded — they're absent from bridgeEntryByHandle and skip the
+    // lock at zero cost.
+    const entry = bridgeEntryByHandle.get(handle);
+    return entry ? withHandleLock(entry, run) : run();
 }
 /**
  * LadybugDB's `conn.query` / `conn.execute` can return either a single
@@ -164,50 +463,54 @@ function unwrapQueryResult(queryResult) {
     }
     return queryResult;
 }
+/**
+ * Release a caller's reference to a bridge handle.
+ *
+ * - **Cache-owned handle** (returned by `getCachedBridgeReadOnly`): this is the
+ *   matching *release* for that acquire — it decrements the lease refcount, it
+ *   does NOT close the native handle. The cache owns the lifetime; the handle
+ *   closes on explicit `invalidateBridgeCache`, mtime-eviction, or process
+ *   shutdown. If the entry was already evicted and this is the last lease, the
+ *   deferred native close fires here (exactly once).
+ * - **Uncached/writable handle** (e.g. the `writeBridge` temp DB): closes the
+ *   native handle for real (CHECKPOINT-flush for writable handles).
+ *
+ * Contract: before renaming or deleting `bridge.lbug`, call
+ * `invalidateBridgeCache` (not this) — `closeBridgeDb` on a cache-owned handle
+ * is a lease release, so the file may stay open under other readers.
+ */
 export async function closeBridgeDb(handle) {
-    // CHECKPOINT before close so the WAL/.shadow contents are flushed into
-    // the main database file. Without this, LadybugDB 0.16.0's non-blocking
-    // checkpoint thread can outlive the close call and leave sidecar pages
-    // pending on disk, which makes a subsequent read-side open either race
-    // with the WAL replay or trip the database-id check on the sidecars.
-    // CHECKPOINT is a no-op when there's nothing pending, so it's cheap.
-    //
-    // ONLY on a writable handle. A read-only connection has nothing to flush,
-    // and issuing CHECKPOINT on it leaves a WAL/shadow lock artifact that makes
-    // the very next read-only open of the same path fail in-process — which broke
-    // repeated `@group` impact/trace calls in a long-lived MCP server (the read
-    // path opens read-only, queries, and closes per call).
-    if (!handle._readOnly) {
-        try {
-            await handle._conn.query('CHECKPOINT');
-        }
-        catch {
-            /* ignore — older LadybugDB or schemaless DB may not accept it */
-        }
-    }
-    try {
-        await handle._conn.close();
-    }
-    catch {
-        /* ignore */
-    }
-    try {
-        await handle._db.close();
-    }
-    catch {
-        /* ignore */
+    const entry = bridgeEntryByHandle.get(handle);
+    if (!entry) {
+        // Uncached or writable handle — close for real.
+        await closeBridgeHandle(handle);
+        return;
     }
-    // NOTE: Windows in-process write→read reopen of the SAME bridge.lbug is still a
-    // known limitation (the writable close's OS file handle is not released before
-    // the read open races; the existing open-side LBUG_OPEN_RETRY only retries
-    // lock-pattern errors, not the post-rename sidecar database-id mismatch). The
-    // bridge's close-then-reopen tests stay Windows-skipped. A close-side
-    // waitForWindowsHandleRelease + finalizeLbugSidecarsAfterClose probe (mirroring
-    // safeClose) was tried and did NOT close that gap on Windows CI, so it was
-    // removed rather than carry latency/duplication for no Windows benefit. The
-    // read-only CHECKPOINT skip above is the load-bearing fix and works on
-    // Linux/macOS (the platforms where in-process reopen is supported).
+    // Cache-owned handle: release this lease. Close only the evicted handle whose
+    // last lease just dropped (deferred-close completion); the live cached handle
+    // stays open for reuse.
+    if (entry.refs > 0)
+        entry.refs--;
+    if (entry.evicted && entry.refs <= 0)
+        await finalizeBridgeClose(entry);
 }
+// NOTE: Windows in-process write→read reopen of the SAME bridge.lbug is still a
+// known limitation (the writable close's OS file handle is not released before
+// the read open races; the existing open-side LBUG_OPEN_RETRY only retries
+// lock-pattern errors, not the post-rename sidecar database-id mismatch). The
+// bridge's close-then-reopen tests stay Windows-skipped. A close-side
+// waitForWindowsHandleRelease + finalizeLbugSidecarsAfterClose probe (mirroring
+// safeClose) was tried and did NOT close that gap on Windows CI, so it was
+// removed rather than carry latency/duplication for no Windows benefit.
+//
+// Scope of the RO bridge-handle cache (getCachedBridgeReadOnly): it removes the
+// PRODUCTION symptom — a long-lived MCP serve process reopening bridge.lbug on
+// every @group call — by keeping one RO handle alive for read→READ reuse.
+// It does NOT fix the write→READ reopen: the first @group read right after an
+// in-process group_sync is a cache miss → openBridgeDbReadOnly, i.e. the same
+// unfixed reopen, so on Windows that first post-sync read still returns null.
+// The read-only CHECKPOINT skip above remains the load-bearing fix on
+// Linux/macOS.
 /* ------------------------------------------------------------------ */
 /*  retryRename — handles transient EBUSY/EPERM/EACCES on Windows    */
 /* ------------------------------------------------------------------ */
@@ -278,6 +581,11 @@ function errMessage(err) {
 }
 export async function writeBridge(groupDir, input) {
     await fsp.mkdir(groupDir, { recursive: true });
+    // Invalidate the RO cache before writing. On Windows the cached handle
+    // would block the atomic rename (tmp → bridge.lbug) because the OS keeps
+    // a shared-mode lock on the open file. Closing it first guarantees the
+    // rename succeeds without EBUSY.
+    await invalidateBridgeCache(groupDir);
     const contracts = dedupeContracts(input.contracts);
     const crossLinks = dedupeCrossLinks(input.crossLinks);
     const finalPath = path.join(groupDir, 'bridge.lbug');
@@ -595,7 +903,12 @@ export async function openBridgeDbReadOnly(groupDir) {
             // (where we can retry) instead of on the first user query.
             await handle.db.init();
             await handle.conn.init();
-            return { _db: handle.db, _conn: handle.conn, groupDir, _readOnly: true };
+            return {
+                _db: handle.db,
+                _conn: handle.conn,
+                groupDir,
+                _readOnly: true,
+            };
         }
         catch (err) {
             lastErr = err;
@@ -613,7 +926,11 @@ export async function openBridgeDbReadOnly(groupDir) {
     // measure so CodeQL can see the taint flow is broken.
     const safeGroupDir = String(groupDir).replace(/[\r\n]/g, ' ');
     const safeErrMsg = lastErr instanceof Error ? String(lastErr.message).replace(/[\r\n]/g, ' ') : undefined;
-    bridgeLogger.debug({ groupDir: safeGroupDir, errMsg: safeErrMsg, attempts: LBUG_OPEN_RETRY_ATTEMPTS }, 'openBridgeDbReadOnly gave up');
+    bridgeLogger.debug({
+        groupDir: safeGroupDir,
+        errMsg: safeErrMsg,
+        attempts: LBUG_OPEN_RETRY_ATTEMPTS,
+    }, 'openBridgeDbReadOnly gave up');
     return null;
 }
 /* ------------------------------------------------------------------ */

package/dist/core/group/cross-impact.js

@@ -7,7 +7,7 @@ import path from 'node:path';
 import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getGroupDir } from './storage.js';
-import { closeBridgeDb, openBridgeDbReadOnly, queryBridge, readBridgeMeta } from './bridge-db.js';
+import { closeBridgeDb, getCachedBridgeReadOnly, queryBridge, readBridgeMeta, } from './bridge-db.js';
 import { BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
 // High limit for the local phase of group impact so collectImpactSymbolUids
 // sees (nearly) all symbols. Bypasses the MCP-facing default of 100.
@@ -283,7 +283,10 @@ export async function ensureBridgeReady(groupDir) {
             error: `No bridge.lbug in this group directory. Run gitnexus group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
         };
     }
-    const handle = await openBridgeDbReadOnly(groupDir);
+    // Use the cached read-only handle if available — avoids reopening the same
+    // bridge.lbug in a long-lived MCP server, which fails on Windows because
+    // the OS handle isn't fully released before the next open races in.
+    const handle = await getCachedBridgeReadOnly(groupDir);
     if (!handle) {
         return {
             error: `Could not open bridge.lbug read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run gitnexus group sync.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.29",
+  "version": "1.6.9-rc.30",
   "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",