gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

package/dist/storage/repo-manager.js

@@ -11,6 +11,10 @@ import path from 'path';
 import os from 'os';
 import { getInferredRepoName, resolveRepoIdentityRoot } from './git.js';
 import { logger } from '../core/logger.js';
+import { branchSlug, BRANCHES_DIR, resolveBranchPlacement, } from './branch-index.js';
+// Re-export the #2106 branch primitives (extracted to branch-index.ts, R10) so
+// existing `repo-manager` import sites and tests keep working unchanged.
+export { branchSlug, resolveBranchPlacement };
 /**
  * Normalise a repo path for registry comparison across platforms
  * (#664 review feedback from @evander-wang).
@@ -64,14 +68,21 @@ export const getStoragePath = (repoPath) => {
     return path.join(path.resolve(repoPath), GITNEXUS_DIR);
 };
 /**
- * Get paths to key storage files
+ * Get paths to key storage files.
+ *
+ * `storagePath` is ALWAYS the flat `<repo>/.gitnexus` — content-addressed
+ * caches (`parse-cache/`, `parsedfile-store/`) live there and are shared
+ * across branches (#2106 KTD7). When `branch` is provided, only `lbugPath` and
+ * `metaPath` are scoped under `branches/<slug>/`; the flat call (no `branch`)
+ * returns byte-identical paths to the pre-multi-branch behavior.
  */
-export const getStoragePaths = (repoPath) => {
+export const getStoragePaths = (repoPath, branch) => {
     const storagePath = getStoragePath(repoPath);
+    const baseDir = branch ? path.join(storagePath, BRANCHES_DIR, branchSlug(branch)) : storagePath;
     return {
         storagePath,
-        lbugPath: path.join(storagePath, 'lbug'),
-        metaPath: path.join(storagePath, 'meta.json'),
+        lbugPath: path.join(baseDir, 'lbug'),
+        metaPath: path.join(baseDir, 'meta.json'),
     };
 };
 /**
@@ -310,7 +321,13 @@ export const readRegistry = async () => {
 const writeRegistry = async (entries) => {
     const dir = getGlobalDir();
     await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(getGlobalRegistryPath(), JSON.stringify(entries, null, 2), 'utf-8');
+    // Atomic tmp+rename (mirrors saveMeta): a crash mid-write can never leave a
+    // truncated/half-written registry.json that the next load would treat as
+    // empty and silently drop every registered repo (#2106 R9).
+    const target = getGlobalRegistryPath();
+    const tmp = `${target}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(entries, null, 2), 'utf-8');
+    await fs.rename(tmp, target);
 };
 /**
  * Thrown by {@link registerRepo} when a requested name is already in
@@ -466,22 +483,89 @@ export const registerRepo = async (repoPath, meta, opts) => {
             throw new RegistryNameCollisionError(name, collidingEntry.path, resolved);
         }
     }
-    const entry = {
-        name,
-        path: resolved,
-        storagePath,
-        indexedAt: meta.indexedAt,
-        lastCommit: meta.lastCommit,
-        remoteUrl: meta.remoteUrl,
-        stats: meta.stats,
-    };
-    if (existingIdx >= 0) {
-        entries[existingIdx] = entry;
+    // This run's branch summary (non-primary runs only); hoisted so the
+    // re-read-before-write merge below can re-apply it against a fresh snapshot.
+    const summary = opts?.branch
+        ? {
+            branch: opts.branch,
+            indexedAt: meta.indexedAt,
+            lastCommit: meta.lastCommit,
+            stats: meta.stats,
+        }
+        : null;
+    let entry;
+    if (summary) {
+        // Non-primary branch run (#2106): keep the primary's top-level fields and
+        // upsert this branch into branches[]. One entry per path is preserved.
+        // When the registry entry is missing (lost/rebuilt registry.json), rebuild
+        // the primary top-level from the FLAT meta.json rather than this branch's
+        // meta, so `--branch <primary>` can still resolve (#2106 review).
+        const flatMeta = existing ? null : await loadMeta(storagePath);
+        const base = existing ?? {
+            name,
+            path: resolved,
+            storagePath,
+            indexedAt: flatMeta?.indexedAt ?? meta.indexedAt,
+            lastCommit: flatMeta?.lastCommit ?? meta.lastCommit,
+            remoteUrl: flatMeta?.remoteUrl ?? meta.remoteUrl,
+            stats: flatMeta?.stats ?? meta.stats,
+            ...(flatMeta?.branch ? { branch: flatMeta.branch } : {}),
+        };
+        const branches = (base.branches ?? []).filter((b) => b.branch !== summary.branch);
+        branches.push(summary);
+        entry = { ...base, name, branches };
     }
     else {
-        entries.push(entry);
+        // Primary/flat run: refresh top-level fields, preserve any branch summaries
+        // already recorded for this path so a primary re-analyze does not drop them.
+        entry = {
+            name,
+            path: resolved,
+            storagePath,
+            indexedAt: meta.indexedAt,
+            lastCommit: meta.lastCommit,
+            remoteUrl: meta.remoteUrl,
+            stats: meta.stats,
+            ...(meta.branch ? { branch: meta.branch } : {}),
+            ...(existing?.branches ? { branches: existing.branches } : {}),
+        };
+    }
+    // Re-read immediately before writing to narrow the lost-update window (#2106
+    // R9): re-derive THIS run's delta against the FRESHEST snapshot so a
+    // concurrent change to the OTHER axis (a branch upsert vs a primary refresh)
+    // survives instead of being clobbered by a stale entry-time view.
+    const fresh = await readRegistry();
+    const freshIdx = fresh.findIndex((e) => {
+        const a = canonicalizePath(e.path);
+        return process.platform === 'win32'
+            ? a.toLowerCase() === canonicalInput.toLowerCase()
+            : a === canonicalInput;
+    });
+    const freshExisting = freshIdx >= 0 ? fresh[freshIdx] : null;
+    let merged;
+    if (summary) {
+        // Branch run: keep the FRESH top-level + branches, just upsert our summary.
+        const base = freshExisting ?? entry;
+        const branches = (base.branches ?? []).filter((b) => b.branch !== summary.branch);
+        branches.push(summary);
+        merged = { ...base, name, branches };
     }
-    await writeRegistry(entries);
+    else {
+        // Primary run: apply our refreshed top-level, but defer to the FRESH
+        // branches[] (a concurrent branch upsert or `clean --branch` wins).
+        merged = { ...entry };
+        if (freshExisting?.branches)
+            merged.branches = freshExisting.branches;
+        else
+            delete merged.branches;
+    }
+    if (freshIdx >= 0) {
+        fresh[freshIdx] = merged;
+    }
+    else {
+        fresh.push(merged);
+    }
+    await writeRegistry(fresh);
     return name;
 };
 /**
@@ -500,6 +584,36 @@ export const unregisterRepo = async (repoPath) => {
     const filtered = entries.filter((e) => !matches(canonicalizePath(e.path), resolved));
     await writeRegistry(filtered);
 };
+/**
+ * Remove a single non-primary branch's summary from a repo's registry entry
+ * (#2106 R7). Called by `gitnexus clean --branch`. Returns `true` when a
+ * matching `branches[]` summary was found and removed; `false` otherwise (so
+ * the CLI can report "no such indexed branch" without crashing). The top-level
+ * primary entry is left intact; an empty `branches[]` is dropped to keep the
+ * registry shape legacy-clean.
+ */
+export const removeBranchIndex = async (repoPath, branch) => {
+    const resolved = canonicalizePath(repoPath);
+    const matches = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+    const entries = await readRegistry();
+    const idx = entries.findIndex((e) => matches(canonicalizePath(e.path), resolved));
+    if (idx < 0)
+        return false;
+    const entry = entries[idx];
+    const before = entry.branches?.length ?? 0;
+    if (!entry.branches || before === 0)
+        return false;
+    const remaining = entry.branches.filter((b) => b.branch !== branch);
+    if (remaining.length === before)
+        return false; // branch not recorded
+    if (remaining.length > 0)
+        entry.branches = remaining;
+    else
+        delete entry.branches;
+    entries[idx] = entry;
+    await writeRegistry(entries);
+    return true;
+};
 /**
  * Thrown by {@link resolveRegistryEntry} when no registered repo matches
  * the caller's target string (by alias, basename, remote-inferred name,
@@ -748,7 +862,14 @@ export const resolveRegistryEntry = (entries, target) => {
 };
 /**
  * List all registered repos from the global registry.
- * Optionally validates that each entry's .gitnexus/ still exists.
+ *
+ * With `validate: true`, prunes only entries whose index is *provably* gone
+ * (fs.access on .gitnexus/meta.json fails with ENOENT or ENOTDIR) and persists
+ * the result. Entries that are merely "not provably absent" — any other
+ * fs.access failure (EIO/EAGAIN/EBUSY/EACCES, etc.) — are KEPT, so a transient
+ * I/O storm cannot wipe the registry. A kept entry is therefore "not confirmed
+ * present," not "confirmed present"; downstream DB opens are independently and
+ * lazily guarded.
  */
 export const listRegisteredRepos = async (opts) => {
     const entries = await readRegistry();
@@ -761,8 +882,28 @@ export const listRegisteredRepos = async (opts) => {
             await fs.access(path.join(entry.storagePath, 'meta.json'));
             valid.push(entry);
         }
-        catch {
-            // Index no longer exists — skip
+        catch (err) {
+            // Prune ONLY when the index is provably gone: ENOENT (file absent) or
+            // ENOTDIR (a path component is no longer a directory). Every other
+            // fs.access failure keeps the entry, because the file may well still
+            // exist and we must not wipe the registry on a transient I/O storm
+            // (EIO/EAGAIN/EBUSY under swap pressure, NFS hiccups, etc.).
+            //
+            // Note: some kept codes are NOT necessarily transient — EACCES, for
+            // example, can be permanent (a chmod'd directory). Keeping is still the
+            // correct conservative choice: a stale-but-kept entry is harmless (DB
+            // opens are lazily guarded) and removable via `gitnexus remove`, whereas
+            // an over-eager prune destroys data. When in doubt, keep.
+            if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') {
+                // Index genuinely removed — safe to prune
+            }
+            else {
+                // Not provably absent — keep entry to prevent mass registry wipe.
+                // Warn so an I/O storm becomes observable instead of silently
+                // keeping (or, pre-fix, silently wiping) entries.
+                logger.warn({ name: entry.name, storagePath: entry.storagePath, code: err?.code }, 'Keeping registry entry despite fs.access failure (not provably absent); not pruning to avoid mass registry wipe.');
+                valid.push(entry);
+            }
         }
     }
     // If we pruned any entries, save the cleaned registry

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`);
+        }
       }
     }
   }
@@ -268,14 +284,32 @@ function buildAfterToolContext(input) {
 }
 
 function runAugment(gitNexusDir, cwd, pattern) {
-  if (hasGitNexusServerOwner(gitNexusDir)) {
-    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+  // Acquire the per-repo slot BEFORE the DB-owner probe (#2163): the probe
+  // itself spawns lsof/ps, so it must be bounded by the same ≤3-per-repo cap
+  // as the augment, or concurrent sessions fan out unbounded probe
+  // subprocesses. The cheap guards (extractPattern, gitNexusDir lookup) run in
+  // buildAfterToolContext before this — moving the acquire any earlier would
+  // churn slot files on tool calls that never probe.
+  const release = acquireHookSlot(gitNexusDir);
+  if (!release) {
+    // Normal skip path: all per-repo hook slots are held by concurrent
+    // sessions. Stay silent for strict hook runners (issue #1913); surface
+    // the reason only under GITNEXUS_DEBUG.
+    if (isDebugEnabled()) {
+      process.stderr.write('[GitNexus] augment skipped: hook slots saturated\n');
+    }
     return '';
   }
-  const release = acquireHookSlot(gitNexusDir);
-  if (!release) return '';
-  const cliPath = resolveCliPath();
   try {
+    if (hasGitNexusServerOwner(gitNexusDir)) {
+      // 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 cliPath = resolveCliPath();
     const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
     if (!child.error && child.status === 0) {
       return extractAugmentContext(child.stderr || '');
@@ -338,7 +372,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
@@ -249,17 +259,35 @@ 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');
-    return;
-  }
 
+  // Acquire the per-repo slot BEFORE the DB-owner probe (#2163): the probe
+  // itself spawns lsof/ps, so it must be bounded by the same ≤3-per-repo cap
+  // as the augment, or concurrent sessions fan out unbounded probe
+  // subprocesses. Keep the acquire right after the cheap guards above —
+  // moving it earlier would churn slot files on tool calls that never probe.
   const release = acquireHookSlot(gitNexusDir);
-  if (!release) return;
+  if (!release) {
+    // Normal skip path: all per-repo hook slots are held by concurrent
+    // sessions. 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: hook slots saturated\n');
+    }
+    return;
+  }
 
-  const cliPath = resolveCliPath();
   let result = '';
   try {
+    if (hasGitNexusServerOwner(gitNexusDir)) {
+      // 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;
+    }
+    const cliPath = resolveCliPath();
     const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
     if (!child.error && child.status === 0) {
       result = extractAugmentContext(child.stderr || '');
@@ -361,7 +389,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/hooks/claude/hook-db-lock-probe.cjs

@@ -11,6 +11,22 @@
  *
  * Fail-open on most errors; fail-closed only on lsof ETIMEDOUT (Unix) or
  * PowerShell ETIMEDOUT (Windows), matching the hook contract.
+ *
+ * Unix subprocess containment contract (#2163):
+ * - lsof/ps are wrapped in coreutils `timeout`/`gtimeout` when a working
+ *   wrapper is found (`timeout -k 1 <budget> lsof ...`). If this hook process
+ *   is itself SIGKILLed (e.g. by the runner's 10s hook timeout) the wrapper
+ *   survives, SIGTERMs its child at the budget (2s lsof / 1s ps) and SIGKILLs
+ *   it 1s later — orphan lifetime is bounded at ~3s instead of unbounded.
+ * - GITNEXUS_HOOK_TIMEOUT_PATH: the sentinel value `disabled` switches the
+ *   wrapper off deterministically; any other value is adopted only when it
+ *   exists AND passes a one-shot `-k` self-test — otherwise resolution FALLS
+ *   THROUGH to the built-in candidate list (first self-test pass wins), so
+ *   no malformed value of any shape can silently disable orphan containment.
+ * - The gitnexus server is lazy-open + sticky-hold: an idle MCP server holds
+ *   ZERO lbug fds until the repo's first MCP query, then keeps the fd open.
+ *   A probe before that first query is therefore always false — a known,
+ *   pre-existing race, not a bug in this probe.
  */
 
 const fs = require('fs');
@@ -46,6 +62,80 @@ function resolveHookBinary(tool) {
   return tool;
 }
 
+// Sentinel:
+//   undefined = not resolved yet (resolve lazily, on first lsof/ps fallback)
+//   string    = self-tested coreutils timeout/gtimeout path (use as wrapper)
+//   null      = no usable wrapper (disabled, none found, or self-test failed)
+let unixGuardTimeoutCache;
+
+/**
+ * Resolve a coreutils `timeout`/`gtimeout` binary to wrap lsof/ps with
+ * (#2163). Dead code on Windows (the win32 dispatch returns earlier).
+ *
+ * GITNEXUS_HOOK_TIMEOUT_PATH semantics: the sentinel `disabled` turns the
+ * wrapper off; any other value is only a CANDIDATE — an existing file path
+ * is tried first, but it must pass the `-k` self-test to be adopted. On any
+ * failure (non-existent path, directory, non-executable file, wrapper
+ * without `-k` support, …) resolution falls through to the built-in
+ * candidates below, tried in order, first self-test pass wins. This is
+ * strictly stronger than the sibling GITNEXUS_HOOK_LSOF_PATH /
+ * GITNEXUS_HOOK_PS_PATH overrides (which only check existence): no bad env
+ * value of ANY shape can silently disable orphan containment.
+ *
+ * Lazy self-test: candidates are probed only when the lsof/ps fallback is
+ * first reached, and the result is memoized. A candidate is adopted only
+ * when `timeout -k 1 1 /bin/sh -c :` exits 0. This rejects wrappers that do
+ * not support the coreutils `-k` flag — busybox <1.34, toybox, broken
+ * symlinks — which would otherwise exit with a usage error without ever
+ * running lsof, silently converting the lsof-ETIMEDOUT fail-closed contract
+ * into fail-open (#1492 regression). Only when EVERY candidate fails does
+ * the probe fall back to the unwrapped status quo (memoized null).
+ * busybox ≥1.34 passes the test and is fully usable (capability, not
+ * identity, decides).
+ */
+function passesGuardSelfTest(guard) {
+  try {
+    const selfTest = spawnSync(guard, ['-k', '1', '1', '/bin/sh', '-c', ':'], {
+      encoding: 'utf-8',
+      timeout: 3000,
+      stdio: ['ignore', 'ignore', 'ignore'],
+      windowsHide: true,
+    });
+    return !selfTest.error && selfTest.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function resolveUnixGuardTimeout() {
+  if (unixGuardTimeoutCache !== undefined) return unixGuardTimeoutCache;
+  unixGuardTimeoutCache = null;
+  const fromEnv = process.env.GITNEXUS_HOOK_TIMEOUT_PATH;
+  const trimmed = fromEnv ? String(fromEnv).trim() : '';
+  if (trimmed === 'disabled') return unixGuardTimeoutCache;
+  const candidates = [];
+  if (trimmed && fs.existsSync(trimmed)) candidates.push(trimmed);
+  for (const builtin of [
+    '/usr/bin/timeout',
+    '/bin/timeout',
+    '/opt/homebrew/bin/gtimeout',
+    '/usr/local/bin/gtimeout',
+  ]) {
+    try {
+      if (fs.existsSync(builtin)) candidates.push(builtin);
+    } catch {
+      /* ignore */
+    }
+  }
+  for (const candidate of candidates) {
+    if (passesGuardSelfTest(candidate)) {
+      unixGuardTimeoutCache = candidate;
+      break;
+    }
+  }
+  return unixGuardTimeoutCache;
+}
+
 function resolveWindowsPowerShellPath() {
   const fromEnv = process.env.GITNEXUS_HOOK_POWERSHELL_PATH;
   if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv).trim())) {
@@ -188,20 +278,46 @@ function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
 }
 
 function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
+  const guard = resolveUnixGuardTimeout();
   const lsofPath = resolveHookBinary('lsof');
-  const lsof = spawnSync(lsofPath, ['-nP', '-t', '--', dbPathAbs], {
+  // The spawnSync timeouts below (lsof 1000ms / ps 500ms) are deliberately
+  // SHORTER than the wrapper budgets (2s / 1s): on the supervised path Node's
+  // SIGTERM always fires first, so `error.code === 'ETIMEDOUT'` and the
+  // fail-closed contract are untouched. The wrapper only matters once this
+  // hook process has been SIGKILLed and can no longer deliver that SIGTERM.
+  const [lsofCmd, lsofArgs] = guard
+    ? [guard, ['-k', '1', '2', lsofPath, '-nP', '-t', '--', dbPathAbs]]
+    : [lsofPath, ['-nP', '-t', '--', dbPathAbs]];
+  const lsof = spawnSync(lsofCmd, lsofArgs, {
     encoding: 'utf-8',
     timeout: 1000,
     stdio: ['ignore', 'pipe', 'ignore'],
     windowsHide: true,
   });
   if (lsof.error) return lsof.error.code === 'ETIMEDOUT';
+  // Guard-mediated deaths map to "unresponsive holder" (fail-closed). Three
+  // result shapes, verified against coreutils 9.1:
+  //   - signal-death: when `-k` escalates to SIGKILL, coreutils timeout
+  //     SELF-RAISES the signal, so spawnSync reports {status: null, signal}
+  //     with no .error (spawnSync's own ETIMEDOUT was handled above). The
+  //     same shape appears when this hook is frozen >2s (SIGSTOP, laptop
+  //     suspend) and the guard expires while it sleeps. By construction, a
+  //     guard-wrapped probe that died by signal without spawnSync ETIMEDOUT
+  //     is a budget/kill outcome.
+  //   - 124: budget expired and the child exited after the plain SIGTERM.
+  //   - 137: NOT the coreutils -k path — only exit-code-propagating wrappers,
+  //     or a child SIGKILLed externally (e.g. the OOM killer).
+  if (guard && lsof.status === null && lsof.signal) return true;
+  if (guard && (lsof.status === 124 || lsof.status === 137)) return true;
 
   const pids = (lsof.stdout || '').split(/\s+/).filter(Boolean);
   const psPath = resolveHookBinary('ps');
   for (const pid of pids) {
     if (Number(pid) === myPid) continue;
-    const ps = spawnSync(psPath, ['-p', pid, '-o', 'command='], {
+    const [psCmd, psArgs] = guard
+      ? [guard, ['-k', '1', '1', psPath, '-p', pid, '-o', 'command=']]
+      : [psPath, ['-p', pid, '-o', 'command=']];
+    const ps = spawnSync(psCmd, psArgs, {
       encoding: 'utf-8',
       timeout: 500,
       stdio: ['ignore', 'pipe', 'ignore'],
@@ -211,6 +327,11 @@ function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
       if (ps.error.code === 'ETIMEDOUT') return true;
       continue;
     }
+    // Same guard-mediated-death mapping as the lsof call above (signal-death
+    // from the -k escalation or a frozen hook; 124 budget expiry; 137 only
+    // for exit-code-propagating wrappers / external SIGKILL).
+    if (guard && ps.status === null && ps.signal) return true;
+    if (guard && (ps.status === 124 || ps.status === 137)) return true;
     if (isGitNexusServerCommand(ps.stdout || '')) return true;
   }
   return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.2",
+  "version": "1.6.8-rc.21",
   "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",
@@ -49,7 +49,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:cross-platform": "tsx scripts/run-cross-platform.ts",
-    "postinstall": "node scripts/materialize-vendor-grammars.cjs && node scripts/build-tree-sitter-grammars.cjs",
+    "postinstall": "node scripts/build-tree-sitter-grammars.cjs",
     "assert-publish-coverage": "node scripts/assert-publish-grammar-coverage.cjs",
     "prepare": "node scripts/build.js",
     "prepack": "node scripts/assert-publish-grammar-coverage.cjs && node scripts/build.js"
@@ -59,6 +59,7 @@
     "@ladybugdb/core": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
+    "busboy": "^1.6.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
     "cors": "^2.8.5",
@@ -93,6 +94,7 @@
     "uuid": "^14.0.0"
   },
   "devDependencies": {
+    "@types/busboy": "^1.5.4",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.6",

package/scripts/assert-publish-grammar-coverage.cjs

@@ -112,6 +112,24 @@ function findCoverageProblems({ grammars }) {
   return problems;
 }
 
+/**
+ * Stray local source-build outputs under `vendor/<name>/build/`. These would
+ * ship in the tarball (`files: ["vendor"]` overrides .gitignore/.npmignore) AND
+ * shadow the committed prebuilds — `node-gyp-build` resolves `build/Release`
+ * BEFORE `prebuilds/`, so a consumer on the publisher's platform would load the
+ * stray (possibly stale/wrong) binding instead of the curated prebuild. The
+ * build dir is gitignored and only appears if a maintainer source-built locally
+ * (e.g. on a no-prebuild platform); refuse to publish it. (#2144 review.)
+ */
+function findStrayBuildArtifacts(vendorDir) {
+  if (!fs.existsSync(vendorDir)) return [];
+  return fs
+    .readdirSync(vendorDir)
+    .filter((d) => /^tree-sitter-/.test(d))
+    .filter((d) => fs.existsSync(path.join(vendorDir, d, 'build')))
+    .map((d) => `vendor/${d}/build`);
+}
+
 function collectGrammars(vendorDir, shipsVendorSource) {
   if (!fs.existsSync(vendorDir)) return [];
   return fs
@@ -141,6 +159,18 @@ function main() {
     process.exit(1);
   }
 
+  const stray = findStrayBuildArtifacts(vendorDir);
+  if (stray.length > 0) {
+    console.error(
+      '[publish-guard] Refusing to publish — stray source-build output under vendor/ would\n' +
+        'ship and shadow the committed prebuilds (node-gyp-build loads build/Release before\n' +
+        'prebuilds/):',
+    );
+    for (const s of stray) console.error(`  - ${s}`);
+    console.error('\nFix: remove it before packing, e.g. `rm -rf gitnexus/vendor/*/build`.');
+    process.exit(1);
+  }
+
   const problems = findCoverageProblems({ grammars });
   if (problems.length > 0) {
     console.error('[publish-guard] Refusing to publish — a vendored grammar would ship unusable:');
@@ -163,6 +193,7 @@ if (require.main === module) main();
 
 module.exports = {
   findCoverageProblems,
+  findStrayBuildArtifacts,
   filesShipsVendorSource,
   isBuildableFromSource,
   sourceBuildSet,