cgraphx 2.0.2 → 2.0.6

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

@@ -0,0 +1,973 @@
+"use strict";
+/**
+ * LadybugDB connection pool (core). Used by MCP, sync, search, wiki, etc.
+ *
+ * LadybugDB Adapter (Connection Pool)
+ *
+ * Manages a pool of LadybugDB databases keyed by repoId, each with
+ * multiple Connection objects for safe concurrent query execution.
+ *
+ * LadybugDB Connections are NOT thread-safe — a single Connection
+ * segfaults if concurrent .query() calls hit it simultaneously.
+ * This adapter provides a checkout/return connection pool so each
+ * concurrent query gets its own Connection from the same Database.
+ *
+ * @see https://docs.ladybugdb.com/concurrency — multiple Connections
+ * from the same Database is the officially supported concurrency pattern.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLbugReady = exports.closeLbug = exports.executeParameterized = exports.executeQuery = exports.initLbug = exports.getMaxResidentRepos = exports.unpinRepo = exports.pinRepo = exports.touchRepo = exports.setActiveStdoutWrite = exports.realStderrWrite = exports.realStdoutWrite = void 0;
+exports.statDbIdentity = statDbIdentity;
+exports.dbIdentityChanged = dbIdentityChanged;
+exports.addPoolCloseListener = addPoolCloseListener;
+exports.silenceStdout = silenceStdout;
+exports.restoreStdout = restoreStdout;
+exports.initLbugWithDb = initLbugWithDb;
+const promises_1 = __importDefault(require("fs/promises"));
+const lbug = __importStar(require("@ladybugdb/core"));
+const lbug_adapter_js_1 = require("./lbug-adapter.js");
+const query_result_utils_js_1 = require("./query-result-utils.js");
+const lbug_config_js_1 = require("./lbug-config.js");
+const sidecar_recovery_js_1 = require("./sidecar-recovery.js");
+async function statDbIdentity(dbPath) {
+    try {
+        const s = await promises_1.default.stat(dbPath);
+        return { ino: s.ino, mtimeMs: s.mtimeMs, size: s.size };
+    }
+    catch {
+        return null;
+    }
+}
+/** True only when both identities are known AND differ. A stat failure
+ *  (ENOENT during the brief unlink window of a full rebuild) yields false, so
+ *  the reader keeps serving its still-valid open inode until the NEW file
+ *  appears with a different identity — avoiding a churn into a failed reopen
+ *  mid-rebuild. */
+function dbIdentityChanged(prev, next) {
+    if (!prev || !next)
+        return false;
+    return prev.ino !== next.ino || prev.mtimeMs !== next.mtimeMs || prev.size !== next.size;
+}
+const pool = new Map();
+const poolCloseListeners = new Set();
+/**
+ * Subscribe to pool-close events. Returns a disposer that removes the
+ * listener (handy for tests).
+ */
+function addPoolCloseListener(listener) {
+    poolCloseListeners.add(listener);
+    return () => {
+        poolCloseListeners.delete(listener);
+    };
+}
+const dbCache = new Map();
+/** Max repos in the pool (LRU eviction) */
+const MAX_POOL_SIZE = 5;
+/** Idle timeout before closing a repo's connections */
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+/** Max connections per repo (caps concurrent queries per repo) */
+const MAX_CONNS_PER_REPO = 8;
+/**
+ * Repos exempt from AUTOMATIC eviction (LRU + idle timeout) until explicitly
+ * unpinned. Used by bounded multi-repo operations like `group sync`, which
+ * initializes one pool per repo and then resolves cross-repo manifest/workspace
+ * links against ALL of those pools after the init loop. Without pinning, a
+ * group larger than MAX_POOL_SIZE would LRU-evict the earliest repos before
+ * resolution runs, leaving the deferred executor closures pointing at dead pool
+ * entries (issue #2189).
+ *
+ * Pins are REFERENCE-COUNTED: the map holds repoId → active lease count. This
+ * lets overlapping holders (two windows of one sync, or two concurrent
+ * `group sync` calls sharing a repo) coexist safely — the repo stays exempt
+ * until the LAST holder releases. A boolean Set could not represent "two
+ * holders," so the first release would wrongly clear a pin another holder still
+ * needs (PR #2191 review, Finding 1).
+ *
+ * Pins block only automatic eviction (LRU + idle). Explicit teardown
+ * (closeOne / closeLbug) always closes the entry and force-clears its count —
+ * teardown is authoritative. A present key always means count ≥ 1. While every
+ * pooled repo is pinned, evictLRU finds no eligible victim and the pool may
+ * transiently exceed MAX_POOL_SIZE — the same soft-cap behavior that already
+ * occurs when every entry is checked out.
+ */
+const pinnedRepos = new Map();
+// 行为中性的 RSS 追踪，服务于池级 evict→reload 内存复现。两个不变量保证它在
+// pool init/close 热路径上安全：只写 stderr（避免污染 stdout 的结果输出）；
+// CGRAPH_POOL_RSS_TRACE 门控使其默认 no-op——每次调用仅一次环境变量比较，
+// 除非有 harness 显式开启。
+function traceRss(event, repoId) {
+    if (process.env.CGRAPH_POOL_RSS_TRACE !== '1')
+        return;
+    const rssMb = Math.round(process.memoryUsage().rss / (1024 * 1024));
+    process.stderr.write(`[pool-rss] ${event} repo=${repoId} pool=${pool.size} dbCache=${dbCache.size} rssMB=${rssMb}\n`);
+}
+let idleTimer = null;
+// Stdout 捕获状态位于 `cgraph/src/core/lbug/stdio-capture.ts` —— 一个零非
+// `node:` 导入的叶子模块。这里重新导出相同符号，使既有的测试 mock 接缝
+//（`cgraph/src/mcp/core/lbug-adapter.ts` 对本文件做 `export *`，8+ 个测试
+// 文件用该路径 `vi.mock(...)`）无需改动即可继续工作。事实来源是那个叶子
+// 模块；此处的再导出只是兼容 shim。
+//
+// 为什么单独拆叶子模块：PR #1383 的对抗评审发现，把这份状态放进
+// pool-adapter.ts 会把 `@ladybugdb/core` 拖进 CLI 入口的静态导入闭包，
+// 在 stdout 保护就绪前污染 stdout。经叶子模块中转即可断链（MCP 协议层
+// 裁剪后哨兵注册方已移除，但该结构保留）。
+var stdio_capture_js_1 = require("./stdio-capture.js");
+Object.defineProperty(exports, "realStdoutWrite", { enumerable: true, get: function () { return stdio_capture_js_1.realStdoutWrite; } });
+Object.defineProperty(exports, "realStderrWrite", { enumerable: true, get: function () { return stdio_capture_js_1.realStderrWrite; } });
+Object.defineProperty(exports, "setActiveStdoutWrite", { enumerable: true, get: function () { return stdio_capture_js_1.setActiveStdoutWrite; } });
+const stdio_capture_js_2 = require("./stdio-capture.js");
+let stdoutSilenceCount = 0;
+/** True while pre-warming connections — prevents watchdog from prematurely restoring stdout */
+let preWarmActive = false;
+/**
+ * Start the idle cleanup timer (runs every 60s)
+ */
+function ensureIdleTimer() {
+    if (idleTimer)
+        return;
+    idleTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [repoId, entry] of pool) {
+            if (pinnedRepos.has(repoId))
+                continue;
+            if (now - entry.lastUsed > IDLE_TIMEOUT_MS && entry.checkedOut === 0) {
+                closeOne(repoId);
+            }
+        }
+    }, 60_000);
+    if (idleTimer && typeof idleTimer === 'object' && 'unref' in idleTimer) {
+        idleTimer.unref();
+    }
+}
+/**
+ * Touch a repo to reset its idle timeout.
+ * Call this during long-running operations to prevent the connection from being closed.
+ */
+const touchRepo = (repoId) => {
+    const entry = pool.get(repoId);
+    if (entry) {
+        entry.lastUsed = Date.now();
+    }
+};
+exports.touchRepo = touchRepo;
+/**
+ * Acquire one eviction-exemption lease on a repo (LRU + idle timeout) by
+ * incrementing its reference count. The repoId must match the key passed to
+ * initLbug (e.g. group sync leases by handle.id — the same id it inits with).
+ * Leasing a repoId before it enters the pool is allowed and protects the entry
+ * once it is created, but the lease does NOT survive a teardown: closeOne
+ * force-clears the count, so a later re-init of the same repoId starts
+ * unpinned. Each pinRepo MUST be balanced by exactly one release (the repo
+ * stays exempt until the last lease is released). See the pinnedRepos docstring
+ * for the full contract.
+ *
+ * Returns a `release` disposer (mirroring addPoolCloseListener) that releases
+ * THIS lease exactly once — calling it twice is a no-op, so it can never
+ * over-decrement a sibling holder's count. Prefer the disposer
+ * (`const release = pinRepo(id); try { … } finally { release(); }`) so the
+ * pin/release pair is leak-proof; unpinRepo remains available for callers that
+ * pair explicitly.
+ */
+const pinRepo = (repoId) => {
+    pinnedRepos.set(repoId, (pinnedRepos.get(repoId) ?? 0) + 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        (0, exports.unpinRepo)(repoId);
+    };
+};
+exports.pinRepo = pinRepo;
+/**
+ * Release one eviction-exemption lease on a repo. The repo becomes eligible for
+ * automatic eviction again only once its count reaches 0 (the key is deleted).
+ * Idempotent at the floor: releasing a repo with no active lease is a no-op (no
+ * negative counts). Does NOT close the repo's pool.
+ */
+const unpinRepo = (repoId) => {
+    const count = pinnedRepos.get(repoId);
+    if (count === undefined)
+        return;
+    if (count <= 1) {
+        pinnedRepos.delete(repoId);
+    }
+    else {
+        pinnedRepos.set(repoId, count - 1);
+    }
+};
+exports.unpinRepo = unpinRepo;
+/**
+ * Maximum number of repos a bounded multi-repo operation (e.g. group sync's
+ * windowed manifest resolution) should hold resident at once. Equals
+ * MAX_POOL_SIZE today, but exposed under an intent-named accessor so callers
+ * size their working set against "max repos a bounded op should hold" rather
+ * than coupling to the LRU eviction-cap constant, which may be tuned
+ * independently.
+ */
+const getMaxResidentRepos = () => MAX_POOL_SIZE;
+exports.getMaxResidentRepos = getMaxResidentRepos;
+/**
+ * Evict the least-recently-used repo if pool is at capacity.
+ * Pinned repos are never chosen as the eviction victim — when every eligible
+ * entry is pinned, no eviction occurs and the pool transiently exceeds
+ * MAX_POOL_SIZE (see the pinnedRepos docstring).
+ */
+function evictLRU() {
+    if (pool.size < MAX_POOL_SIZE)
+        return;
+    let oldestId = null;
+    let oldestTime = Infinity;
+    for (const [id, entry] of pool) {
+        if (pinnedRepos.has(id))
+            continue;
+        if (entry.checkedOut === 0 && entry.lastUsed < oldestTime) {
+            oldestTime = entry.lastUsed;
+            oldestId = id;
+        }
+    }
+    if (oldestId) {
+        closeOne(oldestId);
+    }
+}
+/**
+ * Remove a repo from the pool, close its connections, and release its
+ * shared Database ref.  Only closes the Database when no other repoIds
+ * reference it (refCount === 0).
+ */
+function closeOne(repoId) {
+    const entry = pool.get(repoId);
+    if (!entry)
+        return;
+    entry.closed = true;
+    // Reject any callers still queued for a connection: the pool is going away
+    // (re-init / teardown / LRU eviction), so they must fail fast with an
+    // actionable error instead of hanging until WAITER_TIMEOUT_MS and then
+    // surfacing a misleading "pool exhausted" (#2068 follow-up). Draining the
+    // queue also guarantees checkin() below finds no waiter expecting a
+    // connection, so a connection returned after close is simply closed.
+    if (entry.waiters.length > 0) {
+        const closedErr = new Error(`LadybugDB connection pool closed for repo "${repoId}" (re-init/teardown); retry the query.`);
+        for (const waiter of entry.waiters)
+            waiter.reject(closedErr);
+        entry.waiters.length = 0;
+    }
+    // Close available connections — fire-and-forget with .catch() to prevent
+    // unhandled rejections.  Native close() returns Promise<void> but can crash
+    // the N-API destructor on macOS/Windows; deferring to process exit lets
+    // dangerouslyIgnoreUnhandledErrors absorb the crash.
+    for (const conn of entry.available) {
+        conn.close().catch(() => { });
+    }
+    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.
+    // 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.
+    const shared = dbCache.get(entry.dbPath);
+    if (shared) {
+        shared.refCount--;
+        if (shared.refCount === 0) {
+            if (shared.external) {
+                // External databases are owned by the core adapter — don't close
+                // or remove from cache.  Keep the entry so future initLbug() calls
+                // for the same dbPath reuse it instead of hitting a file lock.
+                shared.refCount = 0;
+                shared.vectorLoaded = false;
+            }
+            else {
+                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.
+    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);
+}
+/**
+ * Create a new Connection from a repo's Database.
+ * Silences stdout to prevent native module output from corrupting MCP stdio.
+ */
+let activeQueryCount = 0;
+/**
+ * Silence stdout by replacing process.stdout.write with a no-op.
+ * Uses a reference counter so nested silence/restore pairs are safe.
+ * Exported so other modules (e.g. embedder) use the same mechanism instead
+ * of independently patching stdout, which causes restore-order conflicts.
+ */
+function silenceStdout() {
+    if (stdoutSilenceCount++ === 0) {
+        // eslint-disable-next-line no-restricted-syntax -- silencing infrastructure; replacement is a no-op
+        process.stdout.write = (() => true);
+    }
+}
+function restoreStdout() {
+    if (--stdoutSilenceCount <= 0) {
+        stdoutSilenceCount = 0;
+        // eslint-disable-next-line no-restricted-syntax -- restoring the active stdout-write handler is the silencing API contract
+        process.stdout.write = (0, stdio_capture_js_2.getActiveStdoutWrite)();
+    }
+}
+// Safety watchdog: restore stdout if it gets stuck silenced (e.g. native crash
+// inside createConnection before restoreStdout runs).
+// Exempts active queries and pre-warm — these legitimately hold silence for
+// longer than 1 second (queries can take up to QUERY_TIMEOUT_MS = 30s).
+setInterval(() => {
+    if (stdoutSilenceCount > 0 && !preWarmActive && activeQueryCount === 0) {
+        stdoutSilenceCount = 0;
+        // eslint-disable-next-line no-restricted-syntax -- watchdog recovery for stuck silencing
+        process.stdout.write = (0, stdio_capture_js_2.getActiveStdoutWrite)();
+    }
+}, 1000).unref();
+function createConnection(db) {
+    silenceStdout();
+    try {
+        const conn = new lbug.Connection(db);
+        // Bound a single query at the engine level so a pathological query cannot
+        // hang a pooled connection past the JS-side Promise.race guard (which frees
+        // the waiter but not the native call). Matches QUERY_TIMEOUT_MS. Guarded so
+        // test doubles that don't model the engine method don't break connection
+        // creation.
+        if (typeof conn.setQueryTimeout === 'function') {
+            conn.setQueryTimeout(QUERY_TIMEOUT_MS);
+        }
+        return conn;
+    }
+    finally {
+        restoreStdout();
+    }
+}
+/** Query timeout in milliseconds */
+const QUERY_TIMEOUT_MS = 30_000;
+/** Waiter queue timeout in milliseconds */
+const WAITER_TIMEOUT_MS = 15_000;
+// Read-only open retry while `cgraph analyze` writes. Catalogued as entry 4
+// of the lbug-config retry-budget registry.
+const LOCK_RETRY_ATTEMPTS = 3;
+const LOCK_RETRY_DELAY_MS = 2000;
+// determinism: probe — existence only. `probeDatabaseForShadowReplay` calls
+// `getAll()` purely to force the shadow replay and then discards the result;
+// the function returns void, so no row ever reaches a caller.
+const SHADOW_REPLAY_PROBE_QUERY = 'MATCH (n) RETURN n LIMIT 1';
+const poolSidecarLogger = {
+    warn: (message) => {
+        (0, stdio_capture_js_2.realStderrWrite)(`${message}\n`);
+    },
+    debug: (_message) => { },
+    info: (message) => {
+        (0, stdio_capture_js_2.realStderrWrite)(`${message}\n`);
+    },
+};
+/**
+ * Pool-local quarantine guard that tolerates the concurrent-peer race the
+ * direct adapter does NOT face (the direct adapter holds `acquireInitLock`,
+ * a cross-process file lock, around its quarantine calls — so any ENOENT
+ * there is a real bug, not a benign race).
+ *
+ * On ENOENT from `fs.rename`, re-inspects via `statIfExists` to confirm the
+ * WAL really is gone. If gone, returns `{ kind: 'peer-handled' }`. If the
+ * WAL is somehow still present after the ENOENT (filesystem race we don't
+ * fully model), re-throws as a classified error rather than silently
+ * returning success — preserves the lock-invariant principle at the pool
+ * sites too.
+ *
+ * On any non-ENOENT failure, classifies through `renameFailureMessage`:
+ * EACCES/EPERM/EBUSY → permission-specific message; everything else
+ * (including the LadybugDB missing-shadow error if it ever propagates here)
+ * → `shadowSidecarRecoveryMessage`.
+ *
+ * See plan: docs/plans/2026-05-21-001-fix-pr-1747-quarantine-enoent-and-large-wal-plan.md (U2)
+ */
+async function tryQuarantineForMissingShadow(dbPath, opts) {
+    // Refuse (throw) before renaming a live WAL when the shadow is present on
+    // disk or the orphan WAL is too large — parity with the serve path's
+    // refuseLargeWalQuarantine (issue #2382 review, Finding B). Kept OUTSIDE the
+    // try so the actionable recovery message propagates to the MCP caller rather
+    // than being re-wrapped as a rename failure.
+    await (0, sidecar_recovery_js_1.guardWalQuarantine)(dbPath, opts.reason, opts.err, poolSidecarLogger);
+    try {
+        const quarantinePath = await (0, sidecar_recovery_js_1.quarantineWalForMissingShadow)(dbPath, {
+            logger: poolSidecarLogger,
+            level: 'warn',
+            reason: opts.reason,
+        });
+        return { kind: 'quarantined', path: quarantinePath };
+    }
+    catch (err) {
+        if ((0, sidecar_recovery_js_1.isMissingFsError)(err)) {
+            const walStat = await (0, sidecar_recovery_js_1.statIfExists)(`${dbPath}.wal`);
+            if (walStat === null) {
+                return { kind: 'peer-handled' };
+            }
+            // Defensive: ENOENT during rename but WAL still present afterwards.
+            // Don't silently swallow — surface a classified error. ENOENT falls
+            // through to shadowSidecarRecoveryMessage in renameFailureMessage.
+            throw new Error((0, sidecar_recovery_js_1.renameFailureMessage)(dbPath, err));
+        }
+        // Classify the rename failure itself — EACCES/EPERM/EBUSY get the
+        // permission-specific message; everything else falls through.
+        throw new Error((0, sidecar_recovery_js_1.renameFailureMessage)(dbPath, err));
+    }
+}
+async function probeDatabaseForShadowReplay(db) {
+    const conn = createConnection(db);
+    try {
+        const queryResult = await conn.query(SHADOW_REPLAY_PROBE_QUERY);
+        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+        await result.getAll();
+        result.close?.();
+    }
+    finally {
+        await conn.close().catch(() => { });
+    }
+}
+async function replayShadowPagesWithWritableOpen(dbPath) {
+    let db;
+    try {
+        db = (0, lbug_config_js_1.createLbugDatabase)(lbug, (0, lbug_config_js_1.toNativeSafePath)(dbPath), { throwOnWalReplayFailure: false });
+        await db.init();
+        await probeDatabaseForShadowReplay(db);
+    }
+    catch (err) {
+        if ((0, sidecar_recovery_js_1.isMissingShadowSidecarError)(err)) {
+            await tryQuarantineForMissingShadow(dbPath, {
+                reason: 'pool writable replay recovery',
+                err,
+            });
+            return;
+        }
+        throw err;
+    }
+    finally {
+        if (db)
+            await db.close().catch(() => { });
+    }
+}
+async function openReadOnlyDatabase(dbPath) {
+    let db;
+    silenceStdout();
+    try {
+        await (0, sidecar_recovery_js_1.preflightLbugSidecars)(dbPath, {
+            mode: 'read-only',
+            logger: poolSidecarLogger,
+            allowQuarantine: true,
+        });
+        db = (0, lbug_config_js_1.createLbugDatabase)(lbug, (0, lbug_config_js_1.toNativeSafePath)(dbPath), {
+            readOnly: true,
+            throwOnWalReplayFailure: false,
+        });
+        await db.init();
+        try {
+            await probeDatabaseForShadowReplay(db);
+        }
+        catch (err) {
+            if ((0, sidecar_recovery_js_1.isMissingShadowSidecarError)(err)) {
+                await db.close().catch(() => { });
+                db = undefined;
+                await tryQuarantineForMissingShadow(dbPath, {
+                    reason: 'pool read-only recovery',
+                    err,
+                });
+                await (0, sidecar_recovery_js_1.preflightLbugSidecars)(dbPath, {
+                    mode: 'read-only',
+                    logger: poolSidecarLogger,
+                    allowQuarantine: true,
+                });
+                db = (0, lbug_config_js_1.createLbugDatabase)(lbug, (0, lbug_config_js_1.toNativeSafePath)(dbPath), {
+                    readOnly: true,
+                    throwOnWalReplayFailure: false,
+                });
+                await db.init();
+                await probeDatabaseForShadowReplay(db);
+                return db;
+            }
+            if (!(0, sidecar_recovery_js_1.isReadOnlyShadowReplayError)(err)) {
+                throw err;
+            }
+            await db.close().catch(() => { });
+            db = undefined;
+            await replayShadowPagesWithWritableOpen(dbPath);
+            db = (0, lbug_config_js_1.createLbugDatabase)(lbug, (0, lbug_config_js_1.toNativeSafePath)(dbPath), {
+                readOnly: true,
+                throwOnWalReplayFailure: false,
+            });
+            await db.init();
+            await probeDatabaseForShadowReplay(db);
+        }
+        return db;
+    }
+    catch (err) {
+        if (db)
+            await db.close().catch(() => { });
+        throw err;
+    }
+    finally {
+        restoreStdout();
+    }
+}
+/**
+ * Quarantine the .wal file and retry opening the database.
+ * Used when the initial open fails with a WAL corruption error.
+ */
+async function tryQuarantineAndReopen(dbPath, repoId) {
+    const walPath = dbPath + '.wal';
+    const quarantineName = `${walPath}.corrupt.${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await promises_1.default.rename(walPath, quarantineName);
+    }
+    catch {
+        throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ` +
+            `Run \`cgraph analyze\` to rebuild the index. (quarantine failed)`);
+    }
+    (0, stdio_capture_js_2.realStderrWrite)(`GitNexus: LadybugDB WAL quarantined for ${repoId}; graph may be stale. ` +
+        `Run \`cgraph analyze\` to rebuild the index.\n`);
+    return await openReadOnlyDatabase(dbPath);
+}
+/** Deduplicates concurrent initLbug calls for the same repoId */
+const initPromises = new Map();
+/**
+ * Initialize (or reuse) a Database + connection pool for a specific repo.
+ * Retries on lock errors (e.g., when `cgraph 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.
+ */
+/**
+ * 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
+ * bookkeeping on "did the pool actually roll over" (LocalBackend) use the
+ * return value; callers that only need the pool ready can ignore it.
+ */
+const initLbug = async (repoId, dbPath) => {
+    const existing = pool.get(repoId);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        // Detect an index that `analyze` rebuilt or mutated under this live read
+        // pool. Without this, the pool keeps serving the old (POSIX:
+        // 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
+        // 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
+        // entry idle (checkedOut === 0) reopens, since the identity stays divergent
+        // until then. Under sustained overlapping queries `checkedOut` may never
+        // reach 0 and `lastUsed` keeps the idle timer from evicting, so this window
+        // is bounded by the load, not IDLE_TIMEOUT_MS — the data stays consistent
+        // (a complete older snapshot), just not the newest. Callers that route
+        // 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;
+    }
+    const promise = doInitLbug(repoId, dbPath);
+    initPromises.set(repoId, promise);
+    try {
+        await promise;
+    }
+    finally {
+        initPromises.delete(repoId);
+    }
+    return true;
+};
+exports.initLbug = initLbug;
+/**
+ * Internal init — creates DB, pre-warms connections, loads optional extensions,
+ * then registers pool. Pool entry is registered LAST so concurrent executeQuery
+ * calls see either "not initialized" (and throw) or a fully ready pool — never
+ * a half-built one.
+ */
+async function doInitLbug(repoId, dbPath) {
+    // Check if database exists
+    try {
+        await promises_1.default.stat(dbPath);
+    }
+    catch {
+        throw new Error(`LadybugDB not found at ${dbPath}. Run: cgraph analyze`);
+    }
+    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);
+    if (shared && !shared.external && shared.dbIdentity) {
+        // #2614 F2: a cached read-only Database is keyed by dbPath and shared across
+        // pool consumers. If the on-disk index was rebuilt/swapped (new inode) while
+        // ANOTHER consumer still holds this handle (refCount kept it alive), reusing
+        // it serves a superseded index. Unreachable via the MCP backend (one
+        // consumer per lbugPath ⇒ refCount hits 0 ⇒ closeOne reopens fresh); a
+        // complete fix needs per-inode handles rather than a dbPath-keyed cache.
+        // Surface it so the corner is observable instead of silently stale.
+        const current = await statDbIdentity(dbPath);
+        if (dbIdentityChanged(shared.dbIdentity, current)) {
+            (0, stdio_capture_js_2.realStderrWrite)(`GitNexus: reusing a shared read-only handle for ${dbPath} whose on-disk ` +
+                `index was rebuilt while another consumer holds it — results may be stale ` +
+                `until that consumer releases it.\n`);
+        }
+    }
+    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 `cgraph 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, dbIdentity: await statDbIdentity(dbPath) };
+                dbCache.set(dbPath, shared);
+                break;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if ((0, lbug_config_js_1.isWalCorruptionError)(lastError)) {
+                    try {
+                        const db = await tryQuarantineAndReopen(dbPath, repoId);
+                        shared = {
+                            db,
+                            refCount: 0,
+                            dbIdentity: await statDbIdentity(dbPath),
+                        };
+                        dbCache.set(dbPath, shared);
+                        break;
+                    }
+                    catch (retryErr) {
+                        throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ${lbug_config_js_1.WAL_RECOVERY_SUGGESTION} ` +
+                            `(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`);
+                    }
+                }
+                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') ||
+                    (0, sidecar_recovery_js_1.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 (!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;
+    // Pre-create the full pool upfront so createConnection() (which silences
+    // stdout) is never called lazily during active query execution.
+    // Mark preWarmActive so the watchdog timer doesn't interfere.
+    preWarmActive = true;
+    const available = [];
+    try {
+        for (let i = 0; i < MAX_CONNS_PER_REPO; i++) {
+            available.push(createConnection(db));
+        }
+    }
+    finally {
+        preWarmActive = false;
+    }
+    // Load the VECTOR extension once per shared Database, BEFORE pool
+    // registration so no concurrent checkout can grab the connection while the
+    // async load is in progress. Extension load scope is per-Database, so this
+    // one load makes QUERY_VECTOR_INDEX legal on every pooled connection.
+    // policy: 'load-only' — the read pool must never trigger a network install;
+    // analyze owns extension installation. On failure the semantic-query lane
+    // falls back to the exact scan with its own diagnostic (#2623 follow-up).
+    if (!shared.vectorLoaded) {
+        shared.vectorLoaded = await (0, lbug_adapter_js_1.loadVectorExtension)(available[0], { policy: 'load-only' });
+    }
+    // Register pool entry only after all connections are pre-warmed and the
+    // extension is loaded.  Concurrent executeQuery calls see either "not initialized"
+    // (and throw cleanly) or a fully ready pool — never a half-built one.
+    // Record the on-disk identity so a later initLbug can detect an analyze
+    // rebuild/mutation and re-open onto the new file (pool staleness invalidation).
+    const dbIdentity = await statDbIdentity(dbPath);
+    pool.set(repoId, {
+        db,
+        available,
+        checkedOut: 0,
+        waiters: [],
+        lastUsed: Date.now(),
+        dbPath,
+        dbIdentity,
+        closed: false,
+    });
+    ensureIdleTimer();
+    traceRss('init', repoId);
+}
+/**
+ * Initialize a pool entry from a pre-existing Database object.
+ *
+ * Used in tests to avoid the writable→close→read-only cycle that crashes
+ * on macOS due to N-API destructor segfaults.  The pool adapter reuses
+ * the core adapter's writable Database instead of opening a new read-only one.
+ *
+ * The Database is registered in the shared dbCache so closeOne() decrements
+ * the refCount correctly.  If the Database is already cached (e.g. another
+ * repoId already injected it), the existing entry is reused.
+ */
+async function initLbugWithDb(repoId, existingDb, dbPath) {
+    const existing = pool.get(repoId);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        return;
+    }
+    // Register in dbCache with external: true so other initLbug() calls
+    // for the same dbPath reuse this Database instead of trying to open
+    // a new one (which would fail with a file lock error).
+    // closeOne() respects the external flag and skips db.close().
+    let shared = dbCache.get(dbPath);
+    if (!shared) {
+        shared = { db: existingDb, refCount: 0, external: true };
+        dbCache.set(dbPath, shared);
+    }
+    shared.refCount++;
+    const available = [];
+    preWarmActive = true;
+    try {
+        for (let i = 0; i < MAX_CONNS_PER_REPO; i++) {
+            available.push(createConnection(existingDb));
+        }
+    }
+    finally {
+        preWarmActive = false;
+    }
+    // Load the VECTOR extension if not already loaded on this Database.
+    // policy: 'load-only' — same contract as initLbug above; the read pool
+    // must not block on a network install during query execution
+    // (#2623 follow-up).
+    if (!shared.vectorLoaded) {
+        shared.vectorLoaded = await (0, lbug_adapter_js_1.loadVectorExtension)(available[0], { policy: 'load-only' });
+    }
+    pool.set(repoId, {
+        db: existingDb,
+        available,
+        checkedOut: 0,
+        waiters: [],
+        lastUsed: Date.now(),
+        dbPath,
+        // Injected/external DB (tests) — not tracked for rebuild invalidation.
+        dbIdentity: null,
+        closed: false,
+    });
+    ensureIdleTimer();
+    traceRss('init', repoId);
+}
+/**
+ * Checkout a connection from the pool.
+ * Returns an available connection, or creates a new one if under the cap.
+ * If all connections are busy and at cap, queues the caller until one is returned.
+ */
+function checkout(entry) {
+    // Fast path: grab an available connection
+    if (entry.available.length > 0) {
+        entry.checkedOut++;
+        return Promise.resolve(entry.available.pop());
+    }
+    // Pool was pre-warmed to MAX_CONNS_PER_REPO during init.  If we're here
+    // with fewer total connections, something leaked — surface the bug rather
+    // than silently creating a connection (which would silence stdout mid-query).
+    const totalConns = entry.available.length + entry.checkedOut;
+    if (totalConns < MAX_CONNS_PER_REPO) {
+        throw new Error(`Connection pool integrity error: expected ${MAX_CONNS_PER_REPO} ` +
+            `connections but found ${totalConns} (${entry.available.length} available, ` +
+            `${entry.checkedOut} checked out)`);
+    }
+    // At capacity — queue the caller with a timeout.
+    return new Promise((resolve, reject) => {
+        const waiter = {
+            resolve: (conn) => {
+                clearTimeout(timer);
+                resolve(conn);
+            },
+            reject: (err) => {
+                clearTimeout(timer);
+                reject(err);
+            },
+        };
+        const timer = setTimeout(() => {
+            const idx = entry.waiters.indexOf(waiter);
+            if (idx !== -1)
+                entry.waiters.splice(idx, 1);
+            waiter.reject(new Error(`Connection pool exhausted: timed out after ${WAITER_TIMEOUT_MS}ms waiting for a free connection`));
+        }, WAITER_TIMEOUT_MS);
+        entry.waiters.push(waiter);
+    });
+}
+/**
+ * Return a connection to the pool after use.
+ * If the pool entry was closed while the connection was checked out (e.g.
+ * LRU eviction), close the orphaned connection instead of returning it.
+ * If there are queued waiters, hand the connection directly to the next one
+ * instead of putting it back in the available array (avoids race conditions).
+ */
+function checkin(entry, conn) {
+    if (entry.closed) {
+        // Pool entry was deleted during checkout — close the orphaned connection
+        conn.close().catch(() => { });
+        return;
+    }
+    if (entry.waiters.length > 0) {
+        // Hand directly to the next waiter — no intermediate available state
+        const waiter = entry.waiters.shift();
+        waiter.resolve(conn);
+    }
+    else {
+        entry.checkedOut--;
+        entry.available.push(conn);
+    }
+}
+/**
+ * Execute a query on a specific repo's connection pool.
+ * Automatically checks out a connection, runs the query, and returns it.
+ */
+/** Race a promise against a timeout */
+function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+const executeQuery = async (repoId, cypher) => {
+    return await (0, exports.executeParameterized)(repoId, cypher, {});
+};
+exports.executeQuery = executeQuery;
+/**
+ * Execute a parameterized query on a specific repo's connection pool.
+ * Uses prepare/execute pattern to prevent Cypher injection.
+ */
+const executeParameterized = async (repoId, cypher, params) => {
+    const entry = pool.get(repoId);
+    if (!entry) {
+        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
+    }
+    entry.lastUsed = Date.now();
+    const conn = await checkout(entry);
+    silenceStdout();
+    activeQueryCount++;
+    let queryResult;
+    try {
+        const stmt = await withTimeout(conn.prepare(cypher), QUERY_TIMEOUT_MS, 'Prepare');
+        if (!stmt.isSuccess()) {
+            const errMsg = await stmt.getErrorMessage();
+            throw new Error(`Prepare failed: ${errMsg}`);
+        }
+        queryResult = await withTimeout(conn.execute(stmt, params), QUERY_TIMEOUT_MS, 'Execute');
+        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+        const rows = await result.getAll();
+        return rows;
+    }
+    catch (err) {
+        if ((0, lbug_adapter_js_1.isReadOnlyDbError)(err)) {
+            // Preserve the native error as `cause` so the original frame/message is
+            // not lost behind the friendly read-only message (#2068 follow-up).
+            throw new Error('Write operations are not allowed. The pool adapter is read-only.', {
+                cause: err,
+            });
+        }
+        throw err;
+    }
+    finally {
+        // Close the native QueryResult cursor(s) before returning the connection —
+        // getAll() drains rows but does not release the native cursor, so without
+        // this the cursor leaks for the connection's lifetime (#2068 follow-up).
+        // Best-effort via the shared helper; never masks the query result or a real
+        // error.
+        if (queryResult)
+            await (0, query_result_utils_js_1.closeQueryResults)(queryResult);
+        activeQueryCount--;
+        restoreStdout();
+        checkin(entry, conn);
+    }
+};
+exports.executeParameterized = executeParameterized;
+/**
+ * Close one or all repo pools.
+ * If repoId is provided, close only that repo's connections.
+ * If omitted, close all repos.
+ */
+const closeLbug = async (repoId) => {
+    if (repoId) {
+        closeOne(repoId);
+        return;
+    }
+    for (const id of [...pool.keys()]) {
+        closeOne(id);
+    }
+    if (idleTimer) {
+        clearInterval(idleTimer);
+        idleTimer = null;
+    }
+};
+exports.closeLbug = closeLbug;
+/**
+ * Check if a specific repo's pool is active
+ */
+const isLbugReady = (repoId) => pool.has(repoId);
+exports.isLbugReady = isLbugReady;