gitnexus 1.6.8-rc.2 → 1.6.8-rc.4

package/README.md

@@ -436,6 +436,26 @@ After scope resolution, analyze prunes inert block-local value symbols (a functi
 
 Programmatic callers can pass `keepLocalValueSymbols: true` in `PipelineOptions` instead of setting the env var.
 
+### Hook augmentation/notifications are silently skipped
+
+The Claude Code / Antigravity hooks intentionally stay **silent** on normal skip
+paths so strict hook runners (e.g. Codex `PreToolUse`) never see unexpected
+output. A search may not be augmented — or a stale-index reminder may not appear
+on stderr — when the GitNexus MCP server owns the repo DB, when the DB-lock probe
+times out and fails closed, or when the index is already current.
+
+To see why a hook skipped, set `GITNEXUS_DEBUG=1` and re-run the action — the hook
+writes the reason (e.g. `[GitNexus] augment skipped: MCP server owns DB`) and the
+stale-index hint to its stderr:
+
+```bash
+GITNEXUS_DEBUG=1 <your command>   # surfaces hook skip/diagnostic reasons on stderr
+```
+
+Only `GITNEXUS_DEBUG=1` and `GITNEXUS_DEBUG=true` enable diagnostics; every other
+value (including `0` and `false`) is treated as off. Diagnostics go to stderr
+only — the hook's structured stdout (the JSON the agent consumes) is unaffected.
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/core/embeddings/embedding-pipeline.js

@@ -16,8 +16,8 @@ import { extractStructuralNames } from './structural-extractor.js';
 import { EMBEDDABLE_LABELS, isShortLabel, LABEL_METHOD, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
 import { resolveEmbeddingConfig } from './config.js';
 import { rankExactEmbeddingRows } from './exact-search.js';
-import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from '../lbug/schema.js';
-import { loadVectorExtension } from '../lbug/lbug-adapter.js';
+import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, STALE_HASH_SENTINEL } from '../lbug/schema.js';
+import { loadVectorExtension, createVectorIndex } from '../lbug/lbug-adapter.js';
 import { getExactScanLimit } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 const isDev = process.env.NODE_ENV === 'development';
@@ -153,24 +153,35 @@ export const batchInsertEmbeddings = async (executeWithReusedStatement, updates)
     await executeWithReusedStatement(cypher, paramsList);
 };
 /**
- * Create the vector index for semantic search
-
- * Now indexes the separate CodeEmbedding table.
- * Delegates extension loading to lbug-adapter's loadVectorExtension(),
- * which owns the VECTOR extension lifecycle and state tracking.
-
+ * Create the vector index for semantic search (indexes the CodeEmbedding table).
+ *
+ * Keeps the embedding-specific extension-install policy gate here
+ * (ensureVectorExtensionAvailable → resolveEmbeddingInstallPolicy, default
+ * `auto` for the analyze write path), then delegates the actual
+ * `CALL CREATE_VECTOR_INDEX(...)` to the adapter, which runs it through the
+ * unprepared `conn.query()` path. It must NOT go through the injected
+ * `executeQuery` (prepared `conn.prepare()`): LadybugDB cannot prepare that
+ * procedure and fails with "We do not support prepare multiple statements" —
+ * the silent degrade in #2114.
  */
-const createVectorIndex = async (executeQuery) => {
+const buildVectorIndex = async () => {
+    // This pre-check applies the embedding-specific install policy
+    // (resolveEmbeddingInstallPolicy, default `auto` for analyze) before reaching
+    // the adapter. The adapter's createVectorIndex() calls loadVectorExtension()
+    // again, but that's a no-op here: once this gate loads VECTOR the module-level
+    // `vectorExtensionLoaded` flag is set, so the adapter's second call
+    // short-circuits without re-resolving the policy — no double install.
     if (!(await ensureVectorExtensionAvailable()))
         return false;
     try {
-        await executeQuery(CREATE_VECTOR_INDEX_QUERY);
-        return true;
+        return await createVectorIndex();
     }
     catch (error) {
-        if (isDev) {
-            logger.warn({ error }, 'Vector index creation warning:');
-        }
+        // Surface this even outside dev: it silently downgrades a user-requested
+        // feature (semantic search) to exact scan. Log under `err` so pino's
+        // standard serializer captures the message/stack — logging under `error`
+        // serialized an Error to `{}` (the empty `{"error":{}}` reported in #2114).
+        logger.warn({ err: error }, 'Vector index creation failed; semantic search will use exact-scan fallback');
         return false;
     }
 };
@@ -283,7 +294,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             // Ensure the vector index exists even when no new nodes need embedding.
             // A prior crash or first-time incremental run may have left CodeEmbedding
             // rows without ever reaching index creation.
-            const vectorIndexReady = await createVectorIndex(executeQuery);
+            const vectorIndexReady = await buildVectorIndex();
             onProgress({
                 phase: 'ready',
                 percent: 100,
@@ -403,7 +414,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         if (isDev) {
             logger.info('📇 Creating vector index...');
         }
-        const vectorIndexReady = await createVectorIndex(executeQuery);
+        const vectorIndexReady = await buildVectorIndex();
         onProgress({
             phase: 'ready',
             percent: 100,

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

@@ -233,6 +233,25 @@ export declare const loadVectorExtension: (targetConn?: lbug.Connection, opts?:
  * @param stemmer - Stemming algorithm (default: 'porter')
  */
 export declare const createFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
+/**
+ * Create the HNSW vector index on the CodeEmbedding table.
+ *
+ * MUST run via `conn.query()` (here through `queryAndDrain`), NOT through the
+ * prepared `executeQuery`/`conn.prepare()` path: `CALL CREATE_VECTOR_INDEX(...)`
+ * compiles to multiple statements, which LadybugDB cannot prepare — it fails
+ * with "Connection Exception: We do not support prepare multiple statements."
+ * Routing index creation through `executeQuery` (prepared) is exactly what
+ * broke vector-index creation during `analyze` (#2114; the singleton
+ * `executeQuery` was switched to the prepared path in #1655 while FTS index
+ * creation kept using `conn.query()`, which is why FTS survived and VECTOR did
+ * not). Mirrors `createFTSIndex` above.
+ *
+ * Returns `true` on success (or when the index already exists — idempotent so
+ * incremental re-runs don't spuriously downgrade to exact scan), `false` when
+ * the VECTOR extension is unavailable or the connection is read-only. Any other
+ * failure propagates so the caller can log it.
+ */
+export declare const createVectorIndex: () => Promise<boolean>;
 /**
  * Lazy-create an FTS index, caching the fact in-process.
  *

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

@@ -8,7 +8,7 @@ import os from 'os';
 import crypto from 'crypto';
 import lbug from '@ladybugdb/core';
 import { closeQueryResults } from './query-result-utils.js';
-import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
+import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
 import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, toNativeSafePath, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
@@ -119,6 +119,11 @@ let currentDbPath = null;
 let currentDbReadOnly = false;
 let ftsLoaded = false;
 let vectorExtensionLoaded = false;
+// In-process guard so a repeated createVectorIndex() within one connection
+// lifetime skips the DB round-trip (mirrors ensuredFTSIndexes). Reset wherever
+// vectorExtensionLoaded resets, so it can never stay true against a swapped or
+// closed connection.
+let vectorIndexEnsured = false;
 /**
  * In-process cache of FTS indexes observed against the current singleton
  * connection. Avoids repeated `CALL CREATE_FTS_INDEX` calls, which can trip
@@ -494,6 +499,7 @@ const resetOpenConnectionState = () => {
     currentDbPath = null;
     ftsLoaded = false;
     vectorExtensionLoaded = false;
+    vectorIndexEnsured = false;
     ensuredFTSIndexes.clear();
 };
 const runSchemaCreationQueries = async (dbPath) => {
@@ -572,6 +578,7 @@ export const withLbugDb = async (dbPath, operation, options = {}) => {
                 currentDbPath = null;
                 ftsLoaded = false;
                 vectorExtensionLoaded = false;
+                vectorIndexEnsured = false;
                 ensuredFTSIndexes.clear();
             });
             // Sleep outside the lock — no need to block others while waiting
@@ -596,6 +603,7 @@ const doInitLbug = async (dbPath, readOnly = false) => {
         currentDbPath = null;
         ftsLoaded = false;
         vectorExtensionLoaded = false;
+        vectorIndexEnsured = false;
         ensuredFTSIndexes.clear();
     }
     // ---------------------------------------------------------------------------
@@ -1476,6 +1484,7 @@ export const closeLbug = async () => {
     currentDbPath = null;
     ftsLoaded = false;
     vectorExtensionLoaded = false;
+    vectorIndexEnsured = false;
     ensuredFTSIndexes.clear();
 };
 export const isLbugReady = () => conn !== null && db !== null;
@@ -1708,6 +1717,52 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
         throw e;
     }
 };
+/**
+ * Create the HNSW vector index on the CodeEmbedding table.
+ *
+ * MUST run via `conn.query()` (here through `queryAndDrain`), NOT through the
+ * prepared `executeQuery`/`conn.prepare()` path: `CALL CREATE_VECTOR_INDEX(...)`
+ * compiles to multiple statements, which LadybugDB cannot prepare — it fails
+ * with "Connection Exception: We do not support prepare multiple statements."
+ * Routing index creation through `executeQuery` (prepared) is exactly what
+ * broke vector-index creation during `analyze` (#2114; the singleton
+ * `executeQuery` was switched to the prepared path in #1655 while FTS index
+ * creation kept using `conn.query()`, which is why FTS survived and VECTOR did
+ * not). Mirrors `createFTSIndex` above.
+ *
+ * Returns `true` on success (or when the index already exists — idempotent so
+ * incremental re-runs don't spuriously downgrade to exact scan), `false` when
+ * the VECTOR extension is unavailable or the connection is read-only. Any other
+ * failure propagates so the caller can log it.
+ */
+export const createVectorIndex = async () => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    // Already built on this connection — skip the round-trip (mirrors createFTSIndex).
+    if (vectorIndexEnsured)
+        return true;
+    if (!(await loadVectorExtension())) {
+        return false;
+    }
+    try {
+        await queryAndDrain(conn, CREATE_VECTOR_INDEX_QUERY);
+        vectorIndexEnsured = true;
+        return true;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        // Idempotent: a prior analyze already built the HNSW index.
+        if (msg.includes('already exists')) {
+            vectorIndexEnsured = true;
+            return true;
+        }
+        // Read-only DB (e.g. the MCP query pool): writable analyze owns creation.
+        if (isReadOnlyDbError(e))
+            return false;
+        throw e;
+    }
+};
 /**
  * Lazy-create an FTS index, caching the fact in-process.
  *

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -91,10 +91,20 @@ function hasGitNexusServerOwner(gitNexusDir) {
   return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
 }
 
+/**
+ * Whether opt-in diagnostics should be written to the hook's stderr. Strict
+ * hook runners validate hook output, so normal, non-error skip paths must stay
+ * silent unless the operator explicitly asks for diagnostics via GITNEXUS_DEBUG.
+ * See issue #1913.
+ */
+function isDebugEnabled() {
+  return process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+}
+
 function extractAugmentContext(stderr) {
   const output = (stderr || '').trim();
   const marker = output.indexOf('[GitNexus]');
-  const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+  const debug = isDebugEnabled();
   if (debug && output.length > 0) {
     // Emit the FULL discarded prefix (everything before the marker, or all of
     // it when no marker is present) so suppressed diagnostics — LadybugDB lock
@@ -258,8 +268,14 @@ function buildAfterToolContext(input) {
     if (/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(command)) {
       const hint = buildStaleIndexHint(gitNexusDir, cwd);
       if (hint) {
-        process.stderr.write(`${hint}\n`);
+        // The hint always reaches the agent via additionalContext (parts). Mirror
+        // it to stderr (for terminal users) only under GITNEXUS_DEBUG, so strict
+        // hook runners see no unexpected output on this normal path (#1913). The
+        // claude hook never mirrored this to stderr — this aligns the two adapters.
         parts.push(hint);
+        if (isDebugEnabled()) {
+          process.stderr.write(`${hint}\n`);
+        }
       }
     }
   }
@@ -269,7 +285,11 @@ function buildAfterToolContext(input) {
 
 function runAugment(gitNexusDir, cwd, pattern) {
   if (hasGitNexusServerOwner(gitNexusDir)) {
-    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    // Normal skip path: the MCP server owns the DB. Stay silent for strict
+    // hook runners (issue #1913); surface the reason only under GITNEXUS_DEBUG.
+    if (isDebugEnabled()) {
+      process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    }
     return '';
   }
   const release = acquireHookSlot(gitNexusDir);
@@ -338,7 +358,7 @@ function main() {
     const handler = handlers[input.hook_event_name || ''];
     if (handler) handler(input);
   } catch (err) {
-    if (process.env.GITNEXUS_DEBUG) {
+    if (isDebugEnabled()) {
       console.error('GitNexus antigravity hook error:', (err.message || '').slice(0, 200));
     }
   }

package/hooks/claude/gitnexus-hook.cjs

@@ -110,10 +110,20 @@ function hasGitNexusServerOwner(gitNexusDir) {
   return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
 }
 
+/**
+ * Whether opt-in diagnostics should be written to the hook's stderr. Strict
+ * hook runners (e.g. Codex `PreToolUse`) validate hook output, so normal,
+ * non-error skip paths must stay silent unless the operator explicitly asks
+ * for diagnostics via GITNEXUS_DEBUG. See issue #1913.
+ */
+function isDebugEnabled() {
+  return process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+}
+
 function extractAugmentContext(stderr) {
   const output = (stderr || '').trim();
   const marker = output.indexOf('[GitNexus]');
-  const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+  const debug = isDebugEnabled();
   if (debug && output.length > 0) {
     // Emit the FULL discarded prefix (everything before the marker, or all of
     // it when no marker is present) so suppressed diagnostics — KuzuDB lock
@@ -250,7 +260,12 @@ function handlePreToolUse(input) {
   const pattern = extractPattern(toolName, toolInput);
   if (!pattern || pattern.length < 3) return;
   if (hasGitNexusServerOwner(gitNexusDir)) {
-    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    // Normal skip path: the MCP server owns the DB, so the CLI augment would
+    // contend on the lock. Stay silent for strict hook runners (issue #1913);
+    // surface the reason only when diagnostics are explicitly requested.
+    if (isDebugEnabled()) {
+      process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    }
     return;
   }
 
@@ -361,7 +376,7 @@ function main() {
     const handler = handlers[input.hook_event_name || ''];
     if (handler) handler(input);
   } catch (err) {
-    if (process.env.GITNEXUS_DEBUG) {
+    if (isDebugEnabled()) {
       console.error('GitNexus hook error:', (err.message || '').slice(0, 200));
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.2",
+  "version": "1.6.8-rc.4",
   "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",