gitnexus 1.6.5-rc.8 → 1.6.5

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

@@ -1,5 +1,5 @@
 import fs from 'fs/promises';
-import { createReadStream, createWriteStream } from 'fs';
+import { createReadStream, createWriteStream, constants as fsConstants } from 'fs';
 import { createInterface } from 'readline';
 import { once } from 'events';
 import { finished } from 'stream/promises';
@@ -152,6 +152,136 @@ export const isReadOnlyDbError = (err) => {
     const msg = err instanceof Error ? err.message : String(err);
     return /read-only database/i.test(msg);
 };
+const isMissingFileError = (err) => {
+    const errno = err;
+    return errno?.code === 'ENOENT';
+};
+const extractErrnoCode = (err) => {
+    const errno = err;
+    return errno?.code;
+};
+const MAX_LOGGED_ERROR_MESSAGE_LENGTH = 160;
+const summarizeError = (err) => (err instanceof Error ? err.message : String(err)).slice(0, MAX_LOGGED_ERROR_MESSAGE_LENGTH);
+// ---------------------------------------------------------------------------
+// Cross-process init lock
+//
+// Prevents a TOCTOU race in orphan sidecar cleanup: between checking that
+// the main DB file is missing and unlinking sidecars, another process could
+// create a fresh DB. The lock file (`${dbPath}.init.lock`) is created with
+// O_CREAT | O_EXCL (atomic create-or-fail) and contains the owning PID +
+// timestamp so stale locks from crashed processes can be reclaimed.
+// ---------------------------------------------------------------------------
+/** Maximum age (ms) before an init lock is considered stale. */
+const INIT_LOCK_STALE_MS = 30_000;
+/** Maximum attempts to acquire the init lock before giving up. */
+const INIT_LOCK_MAX_ATTEMPTS = 6;
+/** Delay between lock-acquisition retries (ms). */
+const INIT_LOCK_RETRY_DELAY_MS = 500;
+const initLockPath = (dbPath) => `${dbPath}.init.lock`;
+/**
+ * Returns true when the process identified by `pid` is still running.
+ * Uses `process.kill(pid, 0)` which sends signal 0 (a no-op probe) —
+ * it throws ESRCH when the process does not exist.
+ */
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Try to break a stale lock whose owning process has exited.
+ * Returns `true` if the stale lock was removed (caller should retry acquire).
+ * Returns `false` if the lock is still valid (another live process owns it).
+ */
+const tryBreakStaleLock = async (lockPath) => {
+    try {
+        const content = await fs.readFile(lockPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        // If the owning process is still alive AND the lock is not stale, don't break.
+        if (typeof parsed.pid === 'number' && isProcessAlive(parsed.pid)) {
+            // Even a live process's lock can be stale if it's been held too long
+            // (e.g. the process is hung). Check the timestamp.
+            if (typeof parsed.ts === 'number' && Date.now() - parsed.ts < INIT_LOCK_STALE_MS) {
+                return false;
+            }
+        }
+        // PID is gone or lock exceeded INIT_LOCK_STALE_MS — reclaim it.
+        await fs.unlink(lockPath);
+        logger.warn(`GitNexus: removed stale init lock (pid=${parsed.pid ?? '?'}, age=${typeof parsed.ts === 'number' ? `${Date.now() - parsed.ts}ms` : '?'})`);
+        return true;
+    }
+    catch (err) {
+        // Lock file disappeared between our read and unlink, or is unreadable.
+        // Either way, let the caller retry the acquire.
+        if (isMissingFileError(err))
+            return true;
+        // Permission error or corrupt content — log and let caller retry.
+        const code = extractErrnoCode(err);
+        logger.warn(`GitNexus: unable to inspect init lock (${code ?? 'UNKNOWN'}): ${summarizeError(err)}`);
+        return false;
+    }
+};
+/**
+ * Acquire a cross-process init lock for `dbPath`.
+ * Uses `O_CREAT | O_EXCL` for atomic create-or-fail semantics.
+ *
+ * Returns a release function that removes the lock file. The release
+ * function is idempotent and safe to call even if the lock was already
+ * cleaned up externally.
+ *
+ * Throws if the lock cannot be acquired after `INIT_LOCK_MAX_ATTEMPTS`.
+ */
+export const acquireInitLock = async (dbPath) => {
+    const lockPath = initLockPath(dbPath);
+    const payload = JSON.stringify({ pid: process.pid, ts: Date.now() });
+    // Ensure the parent directory exists before creating the lock file.
+    // On a fresh repo the `.gitnexus/` directory may not exist yet, and
+    // fs.open with O_CREAT | O_EXCL would fail with ENOENT.
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    for (let attempt = 1; attempt <= INIT_LOCK_MAX_ATTEMPTS; attempt++) {
+        try {
+            const handle = await fs.open(lockPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY);
+            await handle.writeFile(payload);
+            await handle.close();
+            // Return the idempotent release function
+            return async () => {
+                try {
+                    await fs.unlink(lockPath);
+                }
+                catch (err) {
+                    if (!isMissingFileError(err)) {
+                        const code = extractErrnoCode(err);
+                        logger.warn(`GitNexus: failed to release init lock (${code ?? 'UNKNOWN'}): ${summarizeError(err)}`);
+                    }
+                }
+            };
+        }
+        catch (err) {
+            if (err?.code !== 'EEXIST') {
+                throw err; // Unexpected error — propagate immediately
+            }
+            // Lock file exists — check if it's stale
+            const broken = await tryBreakStaleLock(lockPath);
+            if (broken && attempt < INIT_LOCK_MAX_ATTEMPTS) {
+                continue; // Stale lock removed — retry immediately
+            }
+            if (attempt === INIT_LOCK_MAX_ATTEMPTS) {
+                throw new Error(`GitNexus: unable to acquire init lock after ${INIT_LOCK_MAX_ATTEMPTS} attempts — ` +
+                    `another gitnexus process may be initializing the same database (${lockPath})`);
+            }
+            // Live process holds the lock — wait and retry
+            await new Promise((resolve) => setTimeout(resolve, INIT_LOCK_RETRY_DELAY_MS));
+        }
+    }
+    // Unreachable — loop always throws or returns
+    throw new Error('GitNexus: init lock acquisition failed unexpectedly');
+};
+/** Exported for testing — returns the lock file path for a given dbPath. */
+export const _initLockPathForTest = initLockPath;
 const runWithSessionLock = async (operation) => {
     const previous = sessionLock;
     let release = null;
@@ -167,6 +297,65 @@ const runWithSessionLock = async (operation) => {
     }
 };
 const normalizeCopyPath = (filePath) => filePath.replace(/\\/g, '/');
+const closeQueryResult = async (result) => {
+    try {
+        await result.close();
+    }
+    catch {
+        // Best-effort cleanup only.
+    }
+};
+const drainQueryResult = async (queryResult) => {
+    const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+    let firstError;
+    let hasError = false;
+    for (const result of results) {
+        try {
+            await result.getAll();
+        }
+        catch (err) {
+            if (!hasError) {
+                firstError = err;
+                hasError = true;
+            }
+        }
+        finally {
+            await closeQueryResult(result);
+        }
+    }
+    if (hasError)
+        throw firstError;
+};
+const readQueryRows = async (queryResult) => {
+    const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+    let rows = [];
+    let firstError;
+    let hasError = false;
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        try {
+            const resultRows = await result.getAll();
+            if (i === 0)
+                rows = resultRows;
+        }
+        catch (err) {
+            if (!hasError) {
+                firstError = err;
+                hasError = true;
+            }
+        }
+        finally {
+            await closeQueryResult(result);
+        }
+    }
+    if (hasError)
+        throw firstError;
+    return rows;
+};
+const queryAndDrain = async (targetConn, cypher) => {
+    const queryResult = await targetConn.query(cypher);
+    await drainQueryResult(queryResult);
+};
 export const initLbug = async (dbPath) => {
     return runWithSessionLock(() => ensureLbugInitialized(dbPath));
 };
@@ -251,18 +440,62 @@ const doInitLbug = async (dbPath) => {
         }
         // If it's a file, assume it's an existing LadybugDB database - LadybugDB will open it
     }
-    catch {
+    catch (err) {
+        if (!isMissingFileError(err)) {
+            throw err;
+        }
         // Path doesn't exist, which is what LadybugDB wants for a new database
     }
-    // Ensure parent directory exists
-    const parentDir = path.dirname(dbPath);
-    await fs.mkdir(parentDir, { recursive: true });
-    const opened = await openLbugConnection(lbug, dbPath);
-    db = opened.db;
-    conn = opened.conn;
+    // ---------------------------------------------------------------------------
+    // Cross-process critical section: acquire init lock, clean orphan sidecars,
+    // and open the database. The lock prevents a TOCTOU race where another
+    // process could create a fresh DB between our access() check and the
+    // unlink() of stale sidecars.
+    // ---------------------------------------------------------------------------
+    const releaseInitLock = await acquireInitLock(dbPath);
+    try {
+        // Crash-recovery cleanup: if the main DB file is missing, stale sidecars
+        // from an interrupted run can block fresh opens indefinitely.
+        try {
+            await fs.access(dbPath);
+        }
+        catch (err) {
+            if (isMissingFileError(err)) {
+                // `.shadow` is documented by LadybugDB checkpointing and `.wal.checkpoint`
+                // was observed in the #1618 crash loop that motivated this recovery path.
+                const orphanSidecars = [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`];
+                for (const sidecar of orphanSidecars) {
+                    try {
+                        await fs.unlink(sidecar);
+                        logger.warn(`GitNexus: removed orphan sidecar ${path.basename(sidecar)} (no main DB file present)`);
+                    }
+                    catch (err) {
+                        if (isMissingFileError(err)) {
+                            continue;
+                        }
+                        const code = extractErrnoCode(err);
+                        logger.warn(`GitNexus: failed to remove orphan sidecar ${path.basename(sidecar)} (${code ?? 'UNKNOWN'}) while main DB file is missing; LadybugDB open may still fail: ${summarizeError(err)}`);
+                    }
+                }
+            }
+            else {
+                const code = extractErrnoCode(err);
+                logger.warn(`GitNexus: unable to verify main DB file before orphan sidecar cleanup (${code ?? 'UNKNOWN'}); skipping cleanup: ${summarizeError(err)}`);
+            }
+        }
+        // Ensure parent directory exists
+        const parentDir = path.dirname(dbPath);
+        await fs.mkdir(parentDir, { recursive: true });
+        const opened = await openLbugConnection(lbug, dbPath);
+        db = opened.db;
+        conn = opened.conn;
+    }
+    finally {
+        await releaseInitLock();
+    }
     for (const schemaQuery of SCHEMA_QUERIES) {
         try {
-            await conn.query(schemaQuery);
+            await queryAndDrain(conn, schemaQuery);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -312,12 +545,12 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
         const normalizedPath = normalizeCopyPath(csvPath);
         const copyQuery = getCopyQuery(table, normalizedPath);
         try {
-            await conn.query(copyQuery);
+            await queryAndDrain(conn, copyQuery);
         }
         catch (err) {
             try {
                 const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
-                await conn.query(retryQuery);
+                await queryAndDrain(conn, retryQuery);
             }
             catch (retryErr) {
                 const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
@@ -350,12 +583,12 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
                 log(`Loading edges: ${pairIdx}/${relsByPairMeta.size} types (${fromLabel} -> ${toLabel})`);
             }
             try {
-                await conn.query(copyQuery);
+                await queryAndDrain(conn, copyQuery);
             }
             catch (err) {
                 try {
                     const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
-                    await conn.query(retryQuery);
+                    await queryAndDrain(conn, retryQuery);
                 }
                 catch (retryErr) {
                     const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
@@ -475,7 +708,7 @@ const fallbackRelationshipInserts = async (validRelLines, validTables, getNodeLa
             const confidence = parseFloat(confidenceStr) || 1.0;
             const step = parseInt(stepStr) || 0;
             const esc = (s) => s.replace(/'/g, "''").replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r');
-            await conn.query(`
+            await queryAndDrain(conn, `
         MATCH (a:${escapeLabel(fromLabel)} {id: '${esc(fromId)}' }),
               (b:${escapeLabel(toLabel)} {id: '${esc(toId)}' })
         CREATE (a)-[:${REL_TABLE_NAME} {type: '${esc(relType)}', confidence: ${confidence}, reason: '${esc(reason)}', step: ${step}}]->(b)
@@ -589,7 +822,7 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         if (targetDbPath) {
             const tempHandle = await openLbugConnection(lbug, targetDbPath);
             try {
-                await tempHandle.conn.query(query);
+                await queryAndDrain(tempHandle.conn, query);
                 return true;
             }
             finally {
@@ -598,7 +831,7 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         }
         else if (conn) {
             // Use existing persistent connection (when called from analyze)
-            await conn.query(query);
+            await queryAndDrain(conn, query);
             return true;
         }
         return false;
@@ -667,7 +900,7 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                         : '';
                     query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
                 }
-                await tempConn.query(query);
+                await queryAndDrain(tempConn, query);
                 inserted++;
             }
             catch (e) {
@@ -686,19 +919,17 @@ export const executeQuery = async (cypher) => {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
     const queryResult = await conn.query(cypher);
-    // LadybugDB uses getAll() instead of hasNext()/getNext()
-    // Query returns QueryResult for single queries, QueryResult[] for multi-statement
-    const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-    const rows = await result.getAll();
-    return rows;
+    return await readQueryRows(queryResult);
 };
 export const streamQuery = async (cypher, onRow) => {
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
     const queryResult = await conn.query(cypher);
-    const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+    const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+    const result = results[0];
     let rowCount = 0;
+    let streamError;
     try {
         while (await result.hasNext()) {
             const row = await result.getNext();
@@ -707,12 +938,17 @@ export const streamQuery = async (cypher, onRow) => {
         }
         return rowCount;
     }
+    catch (err) {
+        streamError = err;
+        throw err;
+    }
     finally {
         try {
-            await result.close();
+            await drainQueryResult(results);
         }
-        catch {
-            // Best-effort cleanup only.
+        catch (err) {
+            if (streamError === undefined)
+                throw err;
         }
     }
 };
@@ -730,8 +966,7 @@ export const executePrepared = async (cypher, params) => {
         throw new Error(`Prepare failed: ${errMsg}`);
     }
     const queryResult = await conn.execute(stmt, params);
-    const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-    return await result.getAll();
+    return await readQueryRows(queryResult);
 };
 export const executeWithReusedStatement = async (cypher, paramsList) => {
     if (!conn) {
@@ -749,7 +984,7 @@ export const executeWithReusedStatement = async (cypher, paramsList) => {
         }
         try {
             for (const params of subBatch) {
-                await conn.execute(stmt, params);
+                await drainQueryResult(await conn.execute(stmt, params));
             }
         }
         catch (e) {
@@ -767,8 +1002,7 @@ export const getLbugStats = async () => {
     for (const tableName of NODE_TABLES) {
         try {
             const queryResult = await conn.query(`MATCH (n:${escapeTableName(tableName)}) RETURN count(n) AS cnt`);
-            const nodeResult = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-            const nodeRows = await nodeResult.getAll();
+            const nodeRows = await readQueryRows(queryResult);
             if (nodeRows.length > 0) {
                 totalNodes += Number(nodeRows[0]?.cnt ?? nodeRows[0]?.[0] ?? 0);
             }
@@ -780,8 +1014,7 @@ export const getLbugStats = async () => {
     let totalEdges = 0;
     try {
         const queryResult = await conn.query(`MATCH ()-[r:${REL_TABLE_NAME}]->() RETURN count(r) AS cnt`);
-        const edgeResult = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-        const edgeRows = await edgeResult.getAll();
+        const edgeRows = await readQueryRows(queryResult);
         if (edgeRows.length > 0) {
             totalEdges = Number(edgeRows[0]?.cnt ?? edgeRows[0]?.[0] ?? 0);
         }
@@ -810,8 +1043,7 @@ export const loadCachedEmbeddings = async () => {
         // If the query fails (column missing), we return empty cache to force a full rebuild.
         try {
             const check = await conn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex LIMIT 1`);
-            const checkResult = Array.isArray(check) ? check[0] : check;
-            await checkResult.getAll();
+            await readQueryRows(check);
         }
         catch {
             return { embeddingNodeIds: new Set(), embeddings: [] };
@@ -833,8 +1065,7 @@ export const loadCachedEmbeddings = async () => {
                 throw err;
             }
         }
-        const result = Array.isArray(rows) ? rows[0] : rows;
-        for (const row of await result.getAll()) {
+        for (const row of await readQueryRows(rows)) {
             const nodeId = String(row.nodeId ?? row[0] ?? '');
             if (!nodeId)
                 continue;
@@ -938,7 +1169,8 @@ export const flushWAL = async () => {
     if (!conn)
         return;
     try {
-        await conn.query('CHECKPOINT');
+        const checkpointResult = await conn.query('CHECKPOINT');
+        await drainQueryResult(checkpointResult);
     }
     catch {
         /* ignore — older LadybugDB or schemaless DB may not accept it */
@@ -1036,12 +1268,11 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
                 // First count how many we'll delete
                 const tn = escapeTableName(tableName);
                 const countResult = await targetConn.query(`MATCH (n:${tn}) WHERE n.filePath = '${escapedPath}' RETURN count(n) AS cnt`);
-                const result = Array.isArray(countResult) ? countResult[0] : countResult;
-                const rows = await result.getAll();
+                const rows = await readQueryRows(countResult);
                 const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0);
                 if (count > 0) {
                     // Delete nodes (and implicitly their relationships via DETACH)
-                    await targetConn.query(`MATCH (n:${tn}) WHERE n.filePath = '${escapedPath}' DETACH DELETE n`);
+                    await queryAndDrain(targetConn, `MATCH (n:${tn}) WHERE n.filePath = '${escapedPath}' DETACH DELETE n`);
                     deletedNodes += count;
                 }
             }
@@ -1051,7 +1282,7 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
         }
         // Also delete any embeddings for nodes in this file
         try {
-            await targetConn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) WHERE e.nodeId STARTS WITH '${escapedPath}' DELETE e`);
+            await queryAndDrain(targetConn, `MATCH (e:${EMBEDDING_TABLE_NAME}) WHERE e.nodeId STARTS WITH '${escapedPath}' DELETE e`);
         }
         catch {
             // Embedding table may not exist or nodeId format may differ
@@ -1065,6 +1296,76 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
     }
 };
 export const getEmbeddingTableName = () => EMBEDDING_TABLE_NAME;
+/**
+ * Return the distinct repo-relative paths of files that import
+ * `targetFilePath` according to the IMPORTS edges currently in the
+ * DB. Used by the incremental writeback path to expand the
+ * "files-to-rewrite" set so that files importing a changed file get
+ * their edges (which may have been refined by cross-file resolution)
+ * re-emitted, rather than left stale in the DB.
+ *
+ * The DB query reads the *previous* run's state — pre-pipeline, before
+ * any nodes are deleted — so the returned importers are "files that
+ * USED TO import the target". That's the right set to invalidate:
+ * those are the files whose edges in the DB might no longer match
+ * what cross-file resolution produces given the changed file's new
+ * exports.
+ */
+export const queryImporters = async (targetFilePath) => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const escaped = targetFilePath.replace(/'/g, "''");
+    const cypher = `
+    MATCH (a)-[r:${REL_TABLE_NAME}]->(b)
+    WHERE r.type = 'IMPORTS' AND b.filePath = '${escaped}'
+    RETURN DISTINCT a.filePath AS importer
+  `;
+    try {
+        const queryResult = await conn.query(cypher);
+        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+        const rows = await result.getAll();
+        const out = [];
+        for (const row of rows) {
+            const v = row.importer;
+            if (typeof v === 'string' && v.length > 0)
+                out.push(v);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Drop every Community and Process node (and their MEMBER_OF /
+ * STEP_IN_PROCESS edges via DETACH DELETE). Used at the start of an
+ * incremental run so the communities and processes phases regenerate
+ * them from scratch on the merged graph — required for the
+ * "Leiden runs on the FULL graph" correctness invariant.
+ */
+export const deleteAllCommunitiesAndProcesses = async () => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    let nodesDeleted = 0;
+    for (const label of ['Community', 'Process']) {
+        try {
+            const countResult = await conn.query(`MATCH (n:${label}) RETURN count(n) AS cnt`);
+            const result = Array.isArray(countResult) ? countResult[0] : countResult;
+            const rows = await result.getAll();
+            const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0);
+            if (count > 0) {
+                await conn.query(`MATCH (n:${label}) DETACH DELETE n`);
+                nodesDeleted += count;
+            }
+        }
+        catch {
+            // Table may not exist yet on a freshly-initialized DB — fine.
+        }
+    }
+    return { nodesDeleted };
+};
 // ============================================================================
 // Full-Text Search (FTS) Functions
 // ============================================================================
@@ -1088,7 +1389,7 @@ export const loadFTSExtension = async (targetConn, opts = {}) => {
     if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    const loaded = await extensionManager.ensure((sql) => c.query(sql), 'fts', 'FTS', opts);
+    const loaded = await extensionManager.ensure((sql) => queryAndDrain(c, sql), 'fts', 'FTS', opts);
     if (loaded && useModuleState)
         ftsLoaded = true;
     return loaded;
@@ -1116,7 +1417,7 @@ export const loadVectorExtension = async (targetConn, opts = {}) => {
     if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    const loaded = await extensionManager.ensure((sql) => c.query(sql), 'VECTOR', 'VECTOR', opts);
+    const loaded = await extensionManager.ensure((sql) => queryAndDrain(c, sql), 'VECTOR', 'VECTOR', opts);
     if (loaded && useModuleState)
         vectorExtensionLoaded = true;
     return loaded;
@@ -1141,7 +1442,7 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
     const propList = properties.map((p) => `'${p}'`).join(', ');
     const query = `CALL CREATE_FTS_INDEX('${tableName}', '${indexName}', [${propList}], stemmer := '${stemmer}')`;
     try {
-        await conn.query(query);
+        await queryAndDrain(conn, query);
         ensuredFTSIndexes.add(key);
     }
     catch (e) {
@@ -1210,8 +1511,7 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
   `;
     try {
         const queryResult = await conn.query(cypher);
-        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-        const rows = await result.getAll();
+        const rows = await readQueryRows(queryResult);
         return rows.map((row) => {
             const node = row.node || row[0] || {};
             const score = row.score ?? row[1] ?? 0;
@@ -1240,7 +1540,7 @@ export const dropFTSIndex = async (tableName, indexName) => {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
     try {
-        await conn.query(`CALL DROP_FTS_INDEX('${tableName}', '${indexName}')`);
+        await queryAndDrain(conn, `CALL DROP_FTS_INDEX('${tableName}', '${indexName}')`);
     }
     catch {
         // Index may not exist

package/dist/core/run-analyze.d.ts

@@ -42,6 +42,8 @@ export interface AnalyzeOptions {
     skipAgentsMd?: boolean;
     /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
     noStats?: boolean;
+    /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
+    skipSkills?: boolean;
     /**
      * User-provided alias for the registry `name` (#829). When set,
      * forwarded to `registerRepo` so the indexed repo is stored under