gitnexus 1.6.4-rc.26 → 1.6.4-rc.27

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

@@ -3,7 +3,36 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import lbug from '@ladybugdb/core';
 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';
+/**
+ * Sidecar files that LadybugDB creates next to a `bridge.lbug` file.
+ *
+ * - `.wal` — write-ahead log; persists across opens but must be associated
+ *   with the same database instance (LadybugDB 0.16.0 enforces this via a
+ *   database-id check and rejects opens with the diagnostic
+ *   `"Database ID for temporary file 'X.wal' does not match the current
+ *   database. This file may have been left behind from a previous database
+ *   with the same name"`).
+ * - `.shadow` — non-blocking concurrent checkpoint sidecar (added in
+ *   LadybugDB 0.15.4); same pairing constraint as `.wal`.
+ *
+ * `bridge-db` writes to a `bridge.lbug.tmp` file and then atomically renames
+ * it into place. The rename only moves the main file; sidecars must be
+ * cleaned up explicitly or the next writer trips the database-id check.
+ */
+const LBUG_SIDECAR_SUFFIXES = ['.wal', '.shadow'];
+async function removeLbugFile(basePath) {
+    const candidates = [basePath, ...LBUG_SIDECAR_SUFFIXES.map((s) => `${basePath}${s}`)];
+    for (const f of candidates) {
+        try {
+            await fsp.rm(f, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort: caller will surface real errors via the open path */
+        }
+    }
+}
 export function contractNodeId(repo, contractId, role, filePath) {
     return createHash('sha256').update(`${repo}\0${contractId}\0${role}\0${filePath}`).digest('hex');
 }
@@ -74,8 +103,7 @@ export function findContractNode(index, repo, role, symbolUid, filePath, symbolN
 export async function openBridgeDb(dbPath) {
     const parentDir = path.dirname(dbPath);
     await fsp.mkdir(parentDir, { recursive: true });
-    const db = new lbug.Database(dbPath, 0, false, false); // writable
-    const conn = new lbug.Connection(db);
+    const { db, conn } = await openLbugConnection(lbug, dbPath);
     return { _db: db, _conn: conn, groupDir: parentDir };
 }
 /**
@@ -135,6 +163,18 @@ function unwrapQueryResult(queryResult) {
     return queryResult;
 }
 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.
+    try {
+        await handle._conn.query('CHECKPOINT');
+    }
+    catch {
+        /* ignore — older LadybugDB or schemaless DB may not accept it */
+    }
     try {
         await handle._conn.close();
     }
@@ -221,13 +261,11 @@ export async function writeBridge(groupDir, input) {
             report.sampleErrors.push({ kind, id, message: errMessage(err) });
         }
     };
-    // Clean up any leftover tmp
-    try {
-        await fsp.rm(tmpPath, { recursive: true, force: true });
-    }
-    catch {
-        /* ignore */
-    }
+    // Clean up any leftover tmp main file AND its `.wal` / `.shadow` sidecars.
+    // LadybugDB 0.16.0 rejects opening a database whose sidecars belong to a
+    // different database instance (database-id check), so any stale sidecar
+    // from a crashed previous run will fail the next writeBridge.
+    await removeLbugFile(tmpPath);
     // 1. Create temp DB, insert all data.
     //
     // Everything after `openBridgeDb` must run inside a try/finally so that
@@ -368,20 +406,46 @@ export async function writeBridge(groupDir, input) {
         }
     }
     // 3. Atomic swap: old→.bak, tmp→final, rm .bak
+    //
+    // The current database file (with its `.wal` / `.shadow` sidecars) is
+    // moved aside, then the freshly built tmp database takes its place.
+    // We move the sidecars together with the main file so the open below
+    // and any external readers see a consistent set; orphan sidecars from
+    // the tmp namespace are then removed because LadybugDB looks for them
+    // under the renamed-to base name and would reject mismatching IDs.
     try {
         await fsp.access(finalPath);
         await retryRename(finalPath, bakPath);
+        for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+            try {
+                await fsp.access(`${finalPath}${suffix}`);
+                await retryRename(`${finalPath}${suffix}`, `${bakPath}${suffix}`);
+            }
+            catch {
+                /* sidecar absent — nothing to move */
+            }
+        }
     }
     catch {
         /* no existing db */
     }
     await retryRename(tmpPath, finalPath);
-    try {
-        await fsp.rm(bakPath, { recursive: true, force: true });
-    }
-    catch {
-        /* ignore */
+    for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+        // Rename — not delete — so the WAL (which may carry uncommitted-at-
+        // close-time pages on a graceful close, depending on
+        // `autoCheckpoint` / `checkpointThreshold`) and the `.shadow`
+        // checkpoint snapshot stay paired with the database file under its
+        // final name. LadybugDB 0.16.0's database-id check rejects an open
+        // when the sidecars belong to a different base name.
+        try {
+            await fsp.access(`${tmpPath}${suffix}`);
+            await retryRename(`${tmpPath}${suffix}`, `${finalPath}${suffix}`);
+        }
+        catch {
+            /* sidecar absent — nothing to move */
+        }
     }
+    await removeLbugFile(bakPath);
     // 4. Write meta.json
     await writeBridgeMeta(groupDir, {
         version: BRIDGE_SCHEMA_VERSION,
@@ -393,10 +457,35 @@ export async function writeBridge(groupDir, input) {
 /* ------------------------------------------------------------------ */
 /*  openBridgeDbReadOnly                                               */
 /* ------------------------------------------------------------------ */
-export async function openBridgeDbReadOnly(groupDir) {
+/**
+ * Substrings observed in the message of an `Error` raised by the LadybugDB
+ * native open path when Windows still holds an exclusive lock on the file
+ * after a writer's `Database.close()` returned. LadybugDB 0.16.0's
+ * non-blocking checkpoint thread can briefly outlive the close call, so a
+ * read-side opener that races in immediately afterwards sees Win32 error
+ * 33 ("The process cannot access the file because another process has
+ * locked a portion of the file"). Retrying with a small back-off lets the
+ * background thread settle and the OS release the handle.
+ */
+const LBUG_OPEN_RETRY_PATTERNS = [
+    'process cannot access the file',
+    'another process has locked',
+    'could not set lock',
+    'lock held by another process',
+];
+const LBUG_OPEN_RETRY_ATTEMPTS = 10;
+const LBUG_OPEN_RETRY_BASE_MS = 100;
+/** Cap individual back-off delays so the total wait is bounded (~3s). */
+const LBUG_OPEN_RETRY_MAX_MS = 500;
+function isTransientLockError(err) {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return LBUG_OPEN_RETRY_PATTERNS.some((p) => msg.includes(p));
+}
+async function ensureBridgeDbFileAvailable(groupDir) {
     const dbPath = path.join(groupDir, 'bridge.lbug');
     try {
         await fsp.access(dbPath);
+        return true;
     }
     catch {
         // Check for .bak recovery. Use `retryRename` (not `fsp.rename`) for the
@@ -408,53 +497,68 @@ export async function openBridgeDbReadOnly(groupDir) {
         try {
             await fsp.access(bakPath);
             await retryRename(bakPath, dbPath);
+            for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+                try {
+                    await fsp.access(`${bakPath}${suffix}`);
+                    await retryRename(`${bakPath}${suffix}`, `${dbPath}${suffix}`);
+                }
+                catch {
+                    /* sidecar absent */
+                }
+            }
+            return true;
         }
         catch {
-            return null;
+            return false;
         }
     }
+}
+export async function openBridgeDbReadOnly(groupDir) {
+    const dbPath = path.join(groupDir, 'bridge.lbug');
+    if (!(await ensureBridgeDbFileAvailable(groupDir)))
+        return null;
     // Version gate: check meta.json version compatibility
     const meta = await readBridgeMeta(groupDir);
     if (meta.version > 0 && meta.version !== BRIDGE_SCHEMA_VERSION) {
         return null; // incompatible schema version — fallback to JSON or re-sync
     }
-    // Open the native handle. If Connection construction throws AFTER
-    // Database was successfully allocated, we'd leak the native Database
-    // object. Wrap each step separately and tear down the partial handle.
-    let db;
-    let conn;
-    try {
-        db = new lbug.Database(dbPath, 0, false, true); // readOnly
-        conn = new lbug.Connection(db);
-        return { _db: db, _conn: conn, groupDir };
-    }
-    catch {
-        if (conn) {
-            try {
-                await conn.close();
-            }
-            catch {
-                /* ignore */
-            }
+    // Open the native handle with a bounded retry on transient OS-level file
+    // locks (see LBUG_OPEN_RETRY_PATTERNS). If Connection construction throws
+    // AFTER Database was successfully allocated, we'd leak the native Database
+    // object — wrap each step separately and tear down the partial handle.
+    let lastErr;
+    for (let attempt = 1; attempt <= LBUG_OPEN_RETRY_ATTEMPTS; attempt++) {
+        let handle;
+        try {
+            handle = await openLbugConnection(lbug, dbPath, { readOnly: true });
+            // Force the lazy native init now so a transient lock surfaces here
+            // (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 };
         }
-        if (db) {
-            try {
-                await db.close();
-            }
-            catch {
-                /* ignore */
-            }
+        catch (err) {
+            lastErr = err;
+            if (handle)
+                await closeLbugConnection(handle);
+            if (!isTransientLockError(err) || attempt === LBUG_OPEN_RETRY_ATTEMPTS)
+                break;
+            const delay = Math.min(LBUG_OPEN_RETRY_BASE_MS * attempt, LBUG_OPEN_RETRY_MAX_MS);
+            await new Promise((r) => setTimeout(r, delay));
         }
-        return null;
     }
+    if (process.env.GITNEXUS_DEBUG_BRIDGE) {
+        console.warn(`[bridge-db] openBridgeDbReadOnly(${groupDir}) gave up after ` +
+            `${LBUG_OPEN_RETRY_ATTEMPTS} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+    }
+    return null;
 }
 /* ------------------------------------------------------------------ */
 /*  bridgeExists                                                       */
 /* ------------------------------------------------------------------ */
 export async function bridgeExists(groupDir) {
-    const handle = await openBridgeDbReadOnly(groupDir);
-    if (!handle)
+    if (!(await ensureBridgeDbFileAvailable(groupDir)))
         return false;
-    await closeBridgeDb(handle);
-    return true;
+    const meta = await readBridgeMeta(groupDir);
+    return meta.version === 0 || meta.version === BRIDGE_SCHEMA_VERSION;
 }

package/dist/core/lbug/extension-loader.d.ts

@@ -33,7 +33,7 @@ export interface ExtensionManagerOptions {
     warn?: (message: string) => void;
 }
 export declare const getExtensionInstallTimeoutMs: () => number;
-export declare const getExtensionInstallChildProcessArgs: (extensionName: string) => string[];
+export declare const getExtensionInstallChildProcessArgs: (extensionName: string, maxDbSize?: number) => string[];
 /**
  * Run `INSTALL <extension>` in a short-lived child Node process so the parent
  * event loop is never blocked by DuckDB's synchronous network call.

package/dist/core/lbug/extension-loader.js

@@ -1,5 +1,6 @@
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'node:url';
+import { LBUG_MAX_DB_SIZE } from './lbug-config.js';
 const DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS = 15_000;
 const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 const alreadyAvailable = (message) => message.includes('already loaded') ||
@@ -16,9 +17,9 @@ export const getExtensionInstallTimeoutMs = () => {
     const parsed = raw ? Number(raw) : NaN;
     return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS;
 };
-export const getExtensionInstallChildProcessArgs = (extensionName) => {
+export const getExtensionInstallChildProcessArgs = (extensionName, maxDbSize = LBUG_MAX_DB_SIZE) => {
     const childScript = new URL('../../../scripts/install-duckdb-extension.mjs', import.meta.url);
-    return [fileURLToPath(childScript), extensionName];
+    return [fileURLToPath(childScript), extensionName, String(maxDbSize)];
 };
 /**
  * Run `INSTALL <extension>` in a short-lived child Node process so the parent

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

@@ -38,6 +38,15 @@ export declare const getDatabase: () => lbug.Database | null;
  * `gitnexus serve` running at the same time).
  */
 export declare const isDbBusyError: (err: unknown) => boolean;
+/**
+ * Return true when the error message indicates a write was attempted against
+ * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
+ * so any path that calls a `CREATE_*` procedure there will surface this
+ * (e.g. defensive `ensureFTSIndex` calls). Owners of the writable analyze
+ * path should ignore this error — index creation is owned by `gitnexus
+ * analyze` and either already happened or will happen on the next run.
+ */
+export declare const isReadOnlyDbError: (err: unknown) => boolean;
 export declare const initLbug: (dbPath: string) => Promise<{
     db: lbug.Database;
     conn: lbug.Connection;
@@ -158,6 +167,13 @@ export declare const createFTSIndex: (tableName: string, indexName: string, prop
  *
  * Safe to call repeatedly — the in-process Set guarantees only the first
  * call hits LadybugDB. `closeLbug` clears the cache so re-init starts fresh.
+ *
+ * Defense in depth: if the active connection is read-only (e.g. the MCP
+ * pool adapter), `CREATE_FTS_INDEX` will fail with "Cannot execute write
+ * operations in a read-only database". Treat that as a no-op and cache
+ * the key so callers don't loop on a path that can never succeed here —
+ * the index is owned by `gitnexus analyze` (writable) and either already
+ * exists or will be created on the next analyze.
  */
 export declare const ensureFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
 /**

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

@@ -8,6 +8,7 @@ import lbug from '@ladybugdb/core';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
+import { closeLbugConnection, openLbugConnection, } from './lbug-config.js';
 import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 /**
  * Split a relationship CSV into per-label-pair files on disk.
@@ -150,6 +151,18 @@ export const isDbBusyError = (err) => {
         msg.includes('already in use') ||
         msg.includes('could not set lock'));
 };
+/**
+ * Return true when the error message indicates a write was attempted against
+ * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
+ * so any path that calls a `CREATE_*` procedure there will surface this
+ * (e.g. defensive `ensureFTSIndex` calls). Owners of the writable analyze
+ * path should ignore this error — index creation is owned by `gitnexus
+ * analyze` and either already happened or will happen on the next run.
+ */
+export const isReadOnlyDbError = (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /read-only database/i.test(msg);
+};
 const runWithSessionLock = async (operation) => {
     const previous = sessionLock;
     let release = null;
@@ -275,14 +288,14 @@ const doInitLbug = async (dbPath) => {
     // Ensure parent directory exists
     const parentDir = path.dirname(dbPath);
     await fs.mkdir(parentDir, { recursive: true });
-    db = new lbug.Database(dbPath);
-    conn = new lbug.Connection(db);
+    const opened = await openLbugConnection(lbug, dbPath);
+    db = opened.db;
+    conn = opened.conn;
     for (const schemaQuery of SCHEMA_QUERIES) {
         try {
             await conn.query(schemaQuery);
         }
         catch (err) {
-            // Only ignore "already exists" errors - log everything else
             const msg = err instanceof Error ? err.message : String(err);
             if (!msg.includes('already exists')) {
                 console.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
@@ -587,21 +600,13 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         }
         // Use per-query connection if dbPath provided (avoids lock conflicts)
         if (targetDbPath) {
-            const tempDb = new lbug.Database(targetDbPath);
-            const tempConn = new lbug.Connection(tempDb);
+            const tempHandle = await openLbugConnection(lbug, targetDbPath);
             try {
-                await tempConn.query(query);
+                await tempHandle.conn.query(query);
                 return true;
             }
             finally {
-                try {
-                    await tempConn.close();
-                }
-                catch { }
-                try {
-                    await tempDb.close();
-                }
-                catch { }
+                await closeLbugConnection(tempHandle);
             }
         }
         else if (conn) {
@@ -635,8 +640,8 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
         return `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/\n/g, '\\n').replace(/\r/g, '\\r')}'`;
     };
     // Open a single connection for all inserts
-    const tempDb = new lbug.Database(dbPath);
-    const tempConn = new lbug.Connection(tempDb);
+    const tempHandle = await openLbugConnection(lbug, dbPath);
+    const tempConn = tempHandle.conn;
     let inserted = 0;
     let failed = 0;
     try {
@@ -679,14 +684,7 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
         }
     }
     finally {
-        try {
-            await tempConn.close();
-        }
-        catch { }
-        try {
-            await tempDb.close();
-        }
-        catch { }
+        await closeLbugConnection(tempHandle);
     }
     return { inserted, failed };
 };
@@ -960,12 +958,12 @@ export const isLbugReady = () => conn !== null && db !== null;
 export const deleteNodesForFile = async (filePath, dbPath) => {
     const usePerQuery = !!dbPath;
     // Set up connection (either use existing or create per-query)
-    let tempDb = null;
+    let tempHandle = null;
     let tempConn = null;
     let targetConn = conn;
     if (usePerQuery) {
-        tempDb = new lbug.Database(dbPath);
-        tempConn = new lbug.Connection(tempDb);
+        tempHandle = await openLbugConnection(lbug, dbPath);
+        tempConn = tempHandle.conn;
         targetConn = tempConn;
     }
     else if (!conn) {
@@ -1008,18 +1006,8 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
     }
     finally {
         // Close per-query connection if used
-        if (tempConn) {
-            try {
-                await tempConn.close();
-            }
-            catch { }
-        }
-        if (tempDb) {
-            try {
-                await tempDb.close();
-            }
-            catch { }
-        }
+        if (tempHandle)
+            await closeLbugConnection(tempHandle);
     }
 };
 export const getEmbeddingTableName = () => EMBEDDING_TABLE_NAME;
@@ -1105,13 +1093,32 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
  *
  * Safe to call repeatedly — the in-process Set guarantees only the first
  * call hits LadybugDB. `closeLbug` clears the cache so re-init starts fresh.
+ *
+ * Defense in depth: if the active connection is read-only (e.g. the MCP
+ * pool adapter), `CREATE_FTS_INDEX` will fail with "Cannot execute write
+ * operations in a read-only database". Treat that as a no-op and cache
+ * the key so callers don't loop on a path that can never succeed here —
+ * the index is owned by `gitnexus analyze` (writable) and either already
+ * exists or will be created on the next analyze.
  */
 export const ensureFTSIndex = async (tableName, indexName, properties, stemmer = 'porter') => {
     const key = `${tableName}:${indexName}`;
     if (ensuredFTSIndexes.has(key))
         return;
-    await createFTSIndex(tableName, indexName, properties, stemmer);
-    ensuredFTSIndexes.add(key);
+    try {
+        await createFTSIndex(tableName, indexName, properties, stemmer);
+        ensuredFTSIndexes.add(key);
+    }
+    catch (e) {
+        // Read-only DB: writable analyze owns index creation; silently skip
+        // and cache so callers don't loop on a path that can never succeed
+        // here (the MCP query pool opens DBs read-only by design).
+        if (isReadOnlyDbError(e)) {
+            ensuredFTSIndexes.add(key);
+            return;
+        }
+        throw e;
+    }
 };
 /**
  * Query a full-text search index

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

@@ -0,0 +1,46 @@
+import type lbug from '@ladybugdb/core';
+/**
+ * Shared configuration for `@ladybugdb/core` `Database` construction.
+ *
+ * Two values changed meaningfully in `@ladybugdb/core` 0.16.0 and need to be
+ * pinned explicitly by every caller, otherwise GitNexus regresses:
+ *
+ * 1. `maxDBSize` defaults to `0`, which the native runtime interprets as
+ *    "use the platform's full mmap address space" — typically 8 TB on
+ *    64-bit Linux. Constrained environments (CI runners, containers, WSL)
+ *    cannot reserve that much address space and crash with
+ *    `Buffer manager exception: Mmap for size 8796093022208 failed.`
+ *    See LadybugDB upstream JSDoc:
+ *    > "introduced temporarily for now to get around with the default 8TB
+ *    > mmap address space limit some environment".
+ *
+ * 2. `enableCompression` flipped its default from `false` (0.15.x) to
+ *    `true` (0.16.0). Existing call sites that relied on the positional
+ *    default must now pass `false` explicitly to preserve behaviour.
+ *
+ * Putting both in one shared module guarantees every `new lbug.Database(...)`
+ * call site agrees on the same ceiling and behaviour.
+ */
+/**
+ * Upper bound for any single GitNexus LadybugDB file (graph index, group
+ * bridge, install scratch, test fixture). 16 GiB is intentionally generous
+ * for real-world code graphs (the GitNexus self-index uses < 50 MiB) while
+ * remaining far below any 64-bit OS mmap ceiling.
+ *
+ * Override with the `GITNEXUS_LBUG_MAX_DB_SIZE` environment variable when
+ * indexing genuinely huge monorepos. Values are coerced to a positive
+ * integer; anything invalid falls back to the default.
+ */
+export declare const LBUG_MAX_DB_SIZE: number;
+type LbugModule = typeof lbug;
+export interface LbugDatabaseOptions {
+    readOnly?: boolean;
+}
+export interface LbugConnectionHandle {
+    db: lbug.Database;
+    conn: lbug.Connection;
+}
+export declare function createLbugDatabase(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): lbug.Database;
+export declare function openLbugConnection(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): Promise<LbugConnectionHandle>;
+export declare function closeLbugConnection(handle: LbugConnectionHandle): Promise<void>;
+export {};

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

@@ -0,0 +1,60 @@
+/**
+ * Shared configuration for `@ladybugdb/core` `Database` construction.
+ *
+ * Two values changed meaningfully in `@ladybugdb/core` 0.16.0 and need to be
+ * pinned explicitly by every caller, otherwise GitNexus regresses:
+ *
+ * 1. `maxDBSize` defaults to `0`, which the native runtime interprets as
+ *    "use the platform's full mmap address space" — typically 8 TB on
+ *    64-bit Linux. Constrained environments (CI runners, containers, WSL)
+ *    cannot reserve that much address space and crash with
+ *    `Buffer manager exception: Mmap for size 8796093022208 failed.`
+ *    See LadybugDB upstream JSDoc:
+ *    > "introduced temporarily for now to get around with the default 8TB
+ *    > mmap address space limit some environment".
+ *
+ * 2. `enableCompression` flipped its default from `false` (0.15.x) to
+ *    `true` (0.16.0). Existing call sites that relied on the positional
+ *    default must now pass `false` explicitly to preserve behaviour.
+ *
+ * Putting both in one shared module guarantees every `new lbug.Database(...)`
+ * call site agrees on the same ceiling and behaviour.
+ */
+/**
+ * Upper bound for any single GitNexus LadybugDB file (graph index, group
+ * bridge, install scratch, test fixture). 16 GiB is intentionally generous
+ * for real-world code graphs (the GitNexus self-index uses < 50 MiB) while
+ * remaining far below any 64-bit OS mmap ceiling.
+ *
+ * Override with the `GITNEXUS_LBUG_MAX_DB_SIZE` environment variable when
+ * indexing genuinely huge monorepos. Values are coerced to a positive
+ * integer; anything invalid falls back to the default.
+ */
+export const LBUG_MAX_DB_SIZE = (() => {
+    const raw = process.env.GITNEXUS_LBUG_MAX_DB_SIZE;
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed);
+    }
+    return 16 * 1024 * 1024 * 1024;
+})();
+export function createLbugDatabase(lbugModule, databasePath, options = {}) {
+    return new lbugModule.Database(databasePath, 0, false, options.readOnly ?? false, LBUG_MAX_DB_SIZE);
+}
+export async function openLbugConnection(lbugModule, databasePath, options = {}) {
+    let db;
+    try {
+        db = createLbugDatabase(lbugModule, databasePath, options);
+        return { db, conn: new lbugModule.Connection(db) };
+    }
+    catch (err) {
+        if (db)
+            await db.close().catch(() => { });
+        throw err;
+    }
+}
+export async function closeLbugConnection(handle) {
+    await handle.conn.close().catch(() => { });
+    await handle.db.close().catch(() => { });
+}

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

@@ -17,6 +17,7 @@
 import fs from 'fs/promises';
 import lbug from '@ladybugdb/core';
 import { loadFTSExtension } from './lbug-adapter.js';
+import { createLbugDatabase } from './lbug-config.js';
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -243,9 +244,7 @@ async function doInitLbug(repoId, dbPath) {
         for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
             silenceStdout();
             try {
-                const db = new lbug.Database(dbPath, 0, // bufferManagerSize (default)
-                false, // enableCompression (default)
-                true);
+                const db = createLbugDatabase(lbug, dbPath, { readOnly: true });
                 restoreStdout();
                 shared = { db, refCount: 0, ftsLoaded: false };
                 dbCache.set(dbPath, shared);

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

@@ -928,12 +928,11 @@ export class LocalBackend {
             }
             else if (!this.warnedVectorUnsupported) {
                 // Rare diagnostic: surface why we fell back to the exact scan path so
-                // operators can see at a glance that the VECTOR extension is missing on
-                // this runtime (e.g. Windows builds without the optional native
-                // dependency). Emitted once per `LocalBackend` instance lifetime to
-                // avoid noisy stderr on hot semantic-search paths (DoD §2.8).
+                // operators can see at a glance that VECTOR is disabled by platform
+                // policy. Emitted once per `LocalBackend` instance lifetime to avoid
+                // noisy stderr on hot semantic-search paths (DoD §2.8).
                 this.warnedVectorUnsupported = true;
-                console.error('GitNexus [query:vector]: VECTOR index unavailable for this runtime; using exact scan fallback');
+                console.error('GitNexus [query:vector]: VECTOR extension not supported on this platform; using exact scan fallback');
             }
             if (bestChunks.size === 0) {
                 const embeddingCount = Number(tableCheck[0].cnt ?? tableCheck[0][0] ?? 0);

package/hooks/claude/gitnexus-hook.cjs

@@ -39,8 +39,12 @@ function isGlobalRegistryDir(candidate) {
   );
 }
 
-function findGitNexusDir(startDir) {
-  let dir = startDir || process.cwd();
+/**
+ * Walk up from `startDir` looking for a non-registry `.gitnexus/` folder.
+ * Returns the path to `.gitnexus/` or null if not found within 5 levels.
+ */
+function walkForGitNexusDir(startDir) {
+  let dir = startDir;
   for (let i = 0; i < 5; i++) {
     const candidate = path.join(dir, '.gitnexus');
     if (fs.existsSync(candidate)) {
@@ -53,6 +57,51 @@ function findGitNexusDir(startDir) {
   return null;
 }
 
+/**
+ * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside
+ * any git working tree — including a *linked* worktree created via
+ * `git worktree add`. Linked worktrees never contain `.gitnexus/`, so the
+ * upward walk from cwd alone misses the index. Returns null when `cwd` is
+ * not inside a git repo or `git` is not available.
+ *
+ * Implementation: `git rev-parse --git-common-dir` resolves to the canonical
+ * `.git/` directory (or `.git/worktrees/...` parent) that is shared across
+ * all linked worktrees. The canonical repo root is its parent directory.
+ */
+function findCanonicalRepoRoot(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf-8',
+      timeout: 2000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error || result.status !== 0) return null;
+    const commonDir = (result.stdout || '').trim();
+    if (!commonDir || !path.isAbsolute(commonDir)) return null;
+    return path.dirname(commonDir);
+  } catch {
+    return null;
+  }
+}
+
+function findGitNexusDir(startDir) {
+  const cwd = startDir || process.cwd();
+
+  // Fast path: the cwd is inside the canonical repo (most common case).
+  const fromCwd = walkForGitNexusDir(cwd);
+  if (fromCwd) return fromCwd;
+
+  // Fallback: cwd may be inside a linked git worktree whose `.gitnexus/`
+  // only lives in the canonical repo root. Resolve the shared git dir
+  // and retry from there.
+  const canonicalRoot = findCanonicalRepoRoot(cwd);
+  if (canonicalRoot && canonicalRoot !== cwd) {
+    return walkForGitNexusDir(canonicalRoot);
+  }
+  return null;
+}
+
 /**
  * Extract search pattern from tool input.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.4-rc.26",
+  "version": "1.6.4-rc.27",
   "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",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.15.2",
+    "@ladybugdb/core": "^0.16.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",

package/scripts/install-duckdb-extension.mjs

@@ -6,6 +6,14 @@ import { createRequire } from 'node:module';
 
 const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 
+function parseLbugMaxDbSize(raw) {
+  const parsed = raw ? Number(raw) : NaN;
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid LadybugDB max DB size for extension installer: ${raw ?? '<missing>'}`);
+  }
+  return Math.floor(parsed);
+}
+
 async function installDuckDbExtension(extensionName) {
   if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
     throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
@@ -14,6 +22,9 @@ async function installDuckDbExtension(extensionName) {
   const require = createRequire(import.meta.url);
   const lbugModule = require('@ladybugdb/core');
   const lbug = lbugModule.default ?? lbugModule;
+  const lbugMaxDbSize = parseLbugMaxDbSize(
+    process.argv[3] ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE,
+  );
 
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ext-install-'));
   const dbPath = path.join(tmpDir, 'install.lbug');
@@ -21,7 +32,7 @@ async function installDuckDbExtension(extensionName) {
   let conn;
 
   try {
-    db = new lbug.Database(dbPath);
+    db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
     conn = new lbug.Connection(db);
     await conn.query(`INSTALL ${extensionName}`);
   } finally {