gitnexus 1.6.8-rc.8 → 1.6.8

package/dist/storage/repo-manager.d.ts

@@ -74,16 +74,18 @@ export interface RepoMeta {
      */
     fileHashes?: Record<string, string>;
     /**
-     * Crash-recovery dirty flag. Written to meta.json BEFORE any
-     * destructive DB mutation in an incremental run; cleared on success
-     * by overwriting meta.json. If a run crashes between, the next run
-     * sees the flag and forces a full rebuild — the cheapest path back
-     * to a known-good index.
+     * Crash-recovery dirty flag — a generic marker written to meta.json
+     * BEFORE any destructive DB mutation by BOTH writeback branches
+     * (incremental since its introduction; full rebuilds over an existing
+     * meta since #2099 F1); cleared on success by overwriting meta.json.
+     * If a run crashes between, the next run sees the flag and forces a
+     * full rebuild — the cheapest path back to a known-good index.
      */
     incrementalInProgress?: {
-        /** When the incremental run started (epoch ms). */
+        /** When the run started (epoch ms). */
         startedAt: number;
-        /** Number of files in the writable set, for diagnostic logs. */
+        /** Number of files in the writable set, for diagnostic logs.
+         *  `0` on the full-rebuild path (no incremental write set exists). */
         toWriteCount: number;
     };
     /**
@@ -103,11 +105,113 @@ export interface RepoMeta {
      * branch's still-live shards. Additive/optional; absent in legacy metas.
      */
     cacheKeys?: string[];
+    /**
+     * The effective `--pdg` configuration this index's DB rows were built
+     * under (#2099 F1). Presence ≡ the BasicBlock/CFG layer exists in the DB;
+     * ABSENT ≡ pdg-off — which covers every legacy meta, since `--pdg`
+     * shipped opt-in. Caps are recorded RESOLVED (defaults applied) so an
+     * explicit-default run compares equal to a default run. run-analyze
+     * compares this against the requested options and forces a full
+     * writeback on any mismatch — the incremental path only persists
+     * changed-file nodes and would otherwise silently drop (or strand) the
+     * CFG layer on a mode flip. Additive/optional, no
+     * INCREMENTAL_SCHEMA_VERSION bump (a bump would force a one-time full
+     * rebuild for every user). NOTE the removal mechanism is load-bearing:
+     * the end-of-run meta is a fresh object literal, NOT a spread of the
+     * prior meta, so omitting this field on a pdg-off run is what clears
+     * the stamp after an on→off flip.
+     */
+    pdg?: {
+        /** Worker-side per-function source-line cap, resolved (0 = unlimited). */
+        maxFunctionLines: number;
+        /** Emit-side per-function CFG edge cap, resolved (0 = unlimited). */
+        maxEdgesPerFunction: number;
+        /**
+         * Emit-side per-function REACHING_DEF edge cap, resolved (0 = unlimited;
+         * #2082 M2). ABSENT on an M1-era stamp — which is exactly what makes
+         * `pdgModeMismatch` trip on the first M2 run over an M1 index and force
+         * the full writeback that populates REACHING_DEF rows. Optional in the
+         * type for that reason; resolved (always present) on every M2+ write.
+         */
+        maxReachingDefEdgesPerFunction?: number;
+        /**
+         * Emit-side per-function CDG (control-dependence) edge cap, resolved
+         * (0 = unlimited; #2085 M5). ABSENT on any pre-M5 stamp — that absence is
+         * what trips `pdgModeMismatch` on the first CDG-aware run and forces the
+         * full writeback that materialises CDG edges. Optional for that upgrade
+         * reason; resolved (always present) on every M5+ write.
+         */
+        maxCdgEdgesPerFunction?: number;
+        /**
+         * Per-function taint findings cap, resolved (0 = unlimited; #2083 M3).
+         * ABSENT on an M1/M2-era stamp — like `maxReachingDefEdgesPerFunction`,
+         * that absence is what trips `pdgModeMismatch` on the first M3 run and
+         * forces the full writeback that populates TAINTED/SANITIZES rows.
+         */
+        maxTaintFindingsPerFunction?: number;
+        /** Per-finding taint hop cap, resolved (0 = unlimited; #2083 M3 KTD6 —
+         *  bounds the persisted hop-encoded `reason`). Optional for the same
+         *  M2-era-stamp upgrade reason as the findings cap. */
+        maxTaintHops?: number;
+        /**
+         * Per-run cross-function caps, resolved (0 = unlimited; #2084 M4 review
+         * P1-3). ABSENT on an M3-era stamp — that absence trips `pdgModeMismatch`
+         * on the first run that adds them and forces the full writeback that
+         * re-materialises TAINT_PATH within bounds. Optional for that upgrade
+         * reason; resolved (always present) on every post-fix write.
+         */
+        maxInterprocFindings?: number;
+        maxInterprocHops?: number;
+        maxInterprocEdges?: number;
+        /**
+         * Digest of the built-in taint model the persisted findings were
+         * produced under (#2083 M3 KTD7/R7). Any model-content change ships a
+         * new digest → mismatch → full writeback repopulates taint edges
+         * without `--force`. Optional: absent on pre-M3 stamps.
+         */
+        taintModelVersion?: string;
+        /**
+         * Identity of the reaching-definitions solver the persisted REACHING_DEF
+         * rows were produced under (#2201 review R3). The SSA-sparse rewrite computes
+         * FULL facts for deep-loop functions the old dense worklist truncated to
+         * empty (the blocks×64 ceiling no longer fires) — but an existing `--pdg`
+         * index built under the old solver carries those truncated rows. ABSENT on
+         * any pre-#2201 stamp, so that absence trips `pdgModeMismatch` on the first
+         * upgraded run and forces the full writeback that recomputes the now-fuller
+         * REACHING_DEF coverage without `--force`. Bump the tag on any future change
+         * that alters which facts the solver emits. Optional for that upgrade reason;
+         * resolved (always present) on every post-#2201 write.
+         */
+        reachingDefSolver?: string;
+        /**
+         * Whether this `--pdg` index recorded the FU-C `CALL_SUMMARY` return-value
+         * ascent layer (per-callee param→return summary edges). `true` on every
+         * FU-C+ (v4) write. ABSENT on any pre-FU-C (v3) `--pdg` stamp — that absence
+         * is what tells `impact`'s PDG mode the index predates CALL_SUMMARY, so it
+         * surfaces a "no return-value ascent (re-index for CALL_SUMMARY)" note while
+         * STILL serving the intra slice. CALL_SUMMARY is deliberately NOT a required
+         * sub-layer for `pdgLayerStatus` to report `'ready'`: a v3 index stays fully
+         * usable for the intra-procedural statement slice; only the ascent upgrade is
+         * unavailable. Optional for that back-compat reason.
+         */
+        hasCallSummary?: boolean;
+    };
 }
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.
- */
-export declare const INCREMENTAL_SCHEMA_VERSION = 1;
+ * v2: `BasicBlock.callees` column added (statement-precise inter-procedural
+ * reach substrate) — an index built before this lacks the column, so a full
+ * re-analyze is required rather than an incremental top-up.
+ * v3: `BasicBlock.calleeIds` column added (sound resolved-callee-id parallel
+ * to `callees`, #2227) — same contract: an index built before this lacks the
+ * column, so a full re-analyze is forced rather than an incremental top-up.
+ * v4: `CALL_SUMMARY` relation type added (per-callee RETURN-VALUE ASCENT
+ * summary edges, PDG FU-C). A pre-v4 `--pdg` index has NO CALL_SUMMARY edges,
+ * so the engine would silently UNDER-REPORT return-value ascent on an
+ * incremental top-up; force a full re-analyze instead (same contract as v2/v3).
+ * This single bump covers the whole FU-C re-index window (and the later FU-B-2).
+ */
+export declare const INCREMENTAL_SCHEMA_VERSION = 4;
 export interface IndexedRepo {
     repoPath: string;
     storagePath: string;
@@ -459,7 +563,14 @@ export declare const assertSafeStoragePath: (entry: RegistryEntry) => void;
 export declare const resolveRegistryEntry: (entries: RegistryEntry[], target: string) => RegistryEntry;
 /**
  * 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 declare const listRegisteredRepos: (opts?: {
     validate?: boolean;

package/dist/storage/repo-manager.js

@@ -56,8 +56,19 @@ export const canonicalizePath = (p) => {
 };
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.
- */
-export const INCREMENTAL_SCHEMA_VERSION = 1;
+ * v2: `BasicBlock.callees` column added (statement-precise inter-procedural
+ * reach substrate) — an index built before this lacks the column, so a full
+ * re-analyze is required rather than an incremental top-up.
+ * v3: `BasicBlock.calleeIds` column added (sound resolved-callee-id parallel
+ * to `callees`, #2227) — same contract: an index built before this lacks the
+ * column, so a full re-analyze is forced rather than an incremental top-up.
+ * v4: `CALL_SUMMARY` relation type added (per-callee RETURN-VALUE ASCENT
+ * summary edges, PDG FU-C). A pre-v4 `--pdg` index has NO CALL_SUMMARY edges,
+ * so the engine would silently UNDER-REPORT return-value ascent on an
+ * incremental top-up; force a full re-analyze instead (same contract as v2/v3).
+ * This single bump covers the whole FU-C re-index window (and the later FU-B-2).
+ */
+export const INCREMENTAL_SCHEMA_VERSION = 4;
 const GITNEXUS_DIR = '.gitnexus';
 const GITNEXUS_EXCLUDE_ENTRY = `${GITNEXUS_DIR}/`;
 // ─── Local Storage Helpers ─────────────────────────────────────────────
@@ -862,7 +873,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();
@@ -875,8 +893,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/dist/types/pipeline.d.ts

@@ -2,6 +2,7 @@ import type { KnowledgeGraph } from '../core/graph/types.js';
 import { CommunityDetectionResult } from '../core/ingestion/community-processor.js';
 import { ProcessDetectionResult } from '../core/ingestion/process-processor.js';
 import type { ResolutionOutcome } from '../core/ingestion/scope-resolution/resolution-outcome.js';
+import type { PdgEmitManifest } from '../core/lbug/pdg-emit-sink.js';
 export interface PipelineResult {
     graph: KnowledgeGraph;
     /** Absolute path to the repo root — used for lazy file reads during LadybugDB loading */
@@ -25,4 +26,12 @@ export interface PipelineResult {
      * affordance so regression suites can prove the pool engaged.
      */
     usedWorkerPool: boolean;
+    /**
+     * Streamed PDG-emit COPY manifest (#2202). Present only when streaming/chunked
+     * PDG emit was active (full rebuild + `--pdg` + enabled): the BasicBlock node
+     * CSV + per-pair PDG-edge CSVs flushed to disk during the emit loop, for
+     * `loadGraphToLbug` to COPY alongside the structural CSVs. Absent ⇒ the PDG
+     * layer (if any) is resident in `graph` and persists via the whole-graph emit.
+     */
+    pdgEmitManifest?: PdgEmitManifest;
 }

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

@@ -24,7 +24,10 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
-const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const {
+  hasGitNexusDbLockedByGitNexusServer,
+  resolveUnixGuardTimeout,
+} = require('./hook-db-lock-probe.cjs');
 const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 function readInput() {
@@ -198,10 +201,73 @@ function resolveCliPath() {
   return cliPath;
 }
 
+// Debounce for the unguarded-CLI diagnostic below (#2163 follow-up review):
+// at most one line per (short-lived) hook process, even if a future change
+// runs the CLI more than once.
+let unguardedCliWarned = false;
+
+/**
+ * Unix orphan containment (#2163 follow-up): the augment CLI is the
+ * longest-lived hook child (inner spawnSync timeout 7s locally, 12s via
+ * npx), so on Unix it gets the same SIGKILL-surviving coreutils `timeout`
+ * wrapper as the probe's lsof/ps. The wrapper budget is ceil(inner/1000)+1
+ * seconds — STRICTLY greater than the inner spawnSync timeout, so on the
+ * supervised path Node's SIGTERM always fires first and the existing
+ * error/status contract is untouched. Once the hook itself has been
+ * SIGKILLed (exactly the orphan case the wrapper exists for), the guard
+ * semantics differ per branch:
+ *   - direct exec (the CLI is the guard's CHILD): `-k 1` TERM-first — a
+ *     SIGTERM-immune CLI can hold the guard ~1s past the inner timeout
+ *     before the `-k` SIGKILL escalation reaps it.
+ *   - npx (the CLI is a GRANDCHILD: guard → npx → CLI): `-s KILL` — the
+ *     budget expiry SIGKILLs the whole process group outright. TERM-first
+ *     would kill only the obedient npx parent, making `timeout` reap it and
+ *     return before the `-k` escalation ever fires, stranding a
+ *     SIGTERM-immune CLI grandchild unbounded (reproduced on coreutils
+ *     9.x). `-k 1` is retained alongside `-s KILL` as a harmless belt: with
+ *     `-s KILL` the `-k` escalation signal is also KILL. Two residual gaps
+ *     on this branch, both bounded by "no worse than pre-fix" (where the
+ *     grandchild received no signal at all): the group-wide SIGKILL is
+ *     coreutils semantics — a busybox `timeout` passes the self-test (it
+ *     has `-k` and propagates exit status) but signals only its direct
+ *     child, so a busybox guard cannot reach the grandchild; and on the
+ *     SUPERVISED path (hook alive, inner spawnSync timeout SIGTERMs the
+ *     guard) coreutils forwards TERM rather than the `-s` signal, npx dies,
+ *     and the guard exits before any KILL fires — so a SIGTERM-immune CLI
+ *     grandchild still escapes in those two cases.
+ * If the sibling probe predates the resolveUnixGuardTimeout export (version
+ * skew), the adapter degrades to the unwrapped invocation instead of
+ * throwing. Windows is deliberately NOT wrapped — there is no coreutils
+ * timeout to resolve there and the resolver's self-test spawns /bin/sh — so
+ * on win32 (the npx.cmd path) and whenever the guard resolves to null (e.g.
+ * macOS without Homebrew coreutils — reported once under GITNEXUS_DEBUG)
+ * the argv stays byte-identical to the pre-wrap invocation.
+ */
 function runGitNexusCli(cliPath, args, cwd, timeout) {
   const isWin = process.platform === 'win32';
+  // Version-skew guard (#2163 follow-up review): an older sibling probe
+  // without the resolveUnixGuardTimeout export must degrade to the unwrapped
+  // invocation — a TypeError here would be swallowed by the caller's catch
+  // and silently kill the augment.
+  const guard =
+    isWin || typeof resolveUnixGuardTimeout !== 'function' ? null : resolveUnixGuardTimeout();
+  if (!isWin && !guard && !unguardedCliWarned && isDebugEnabled()) {
+    // Diagnose the "stays unwrapped" Unix paths once per hook process: no
+    // usable coreutils timeout/gtimeout (e.g. macOS without Homebrew
+    // coreutils), GITNEXUS_HOOK_TIMEOUT_PATH=disabled, or probe skew above.
+    unguardedCliWarned = true;
+    process.stderr.write(
+      '[GitNexus hook] no usable timeout/gtimeout guard; augment CLI child runs unguarded\n',
+    );
+  }
   if (cliPath) {
-    return spawnSync(process.execPath, [cliPath, ...args], {
+    const [cmd, cmdArgs] = guard
+      ? [
+          guard,
+          ['-k', '1', String(Math.ceil(timeout / 1000) + 1), process.execPath, cliPath, ...args],
+        ]
+      : [process.execPath, [cliPath, ...args]];
+    return spawnSync(cmd, cmdArgs, {
       encoding: 'utf-8',
       timeout,
       cwd,
@@ -209,7 +275,27 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
       windowsHide: true,
     });
   }
-  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
+  // A non-null guard implies non-Windows, so the wrapped arm can hardcode
+  // plain `npx`. The wrapped arm leads with `-s KILL` (NOT TERM-first like
+  // the direct branch above): the CLI here is a grandchild behind npx — see
+  // the docblock.
+  const [cmd, cmdArgs] = guard
+    ? [
+        guard,
+        [
+          '-s',
+          'KILL',
+          '-k',
+          '1',
+          String(Math.ceil((timeout + 5000) / 1000) + 1),
+          'npx',
+          '-y',
+          'gitnexus',
+          ...args,
+        ],
+      ]
+    : [isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args]];
+  return spawnSync(cmd, cmdArgs, {
     encoding: 'utf-8',
     timeout: timeout + 5000,
     cwd,
@@ -284,18 +370,32 @@ function buildAfterToolContext(input) {
 }
 
 function runAugment(gitNexusDir, cwd, pattern) {
-  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.
+  // 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: MCP server owns DB\n');
+      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 || '');

package/hooks/claude/gitnexus-hook.cjs

@@ -15,7 +15,10 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
-const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const {
+  hasGitNexusDbLockedByGitNexusServer,
+  resolveUnixGuardTimeout,
+} = require('./hook-db-lock-probe.cjs');
 const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 /**
@@ -218,14 +221,76 @@ function resolveCliPath() {
   return cliPath;
 }
 
+// Debounce for the unguarded-CLI diagnostic below (#2163 follow-up review):
+// at most one line per (short-lived) hook process, even if a future change
+// runs the CLI more than once.
+let unguardedCliWarned = false;
+
 /**
  * Spawn a gitnexus CLI command synchronously.
  * Returns the stderr output (KuzuDB captures stdout at OS level).
+ *
+ * Unix orphan containment (#2163 follow-up): the augment CLI is the
+ * longest-lived hook child (inner spawnSync timeout 7s locally, 12s via
+ * npx), so on Unix it gets the same SIGKILL-surviving coreutils `timeout`
+ * wrapper as the probe's lsof/ps. The wrapper budget is ceil(inner/1000)+1
+ * seconds — STRICTLY greater than the inner spawnSync timeout, so on the
+ * supervised path Node's SIGTERM always fires first and the existing
+ * error/status contract is untouched. Once the hook itself has been
+ * SIGKILLed (exactly the orphan case the wrapper exists for), the guard
+ * semantics differ per branch:
+ *   - direct exec (the CLI is the guard's CHILD): `-k 1` TERM-first — a
+ *     SIGTERM-immune CLI can hold the guard ~1s past the inner timeout
+ *     before the `-k` SIGKILL escalation reaps it.
+ *   - npx (the CLI is a GRANDCHILD: guard → npx → CLI): `-s KILL` — the
+ *     budget expiry SIGKILLs the whole process group outright. TERM-first
+ *     would kill only the obedient npx parent, making `timeout` reap it and
+ *     return before the `-k` escalation ever fires, stranding a
+ *     SIGTERM-immune CLI grandchild unbounded (reproduced on coreutils
+ *     9.x). `-k 1` is retained alongside `-s KILL` as a harmless belt: with
+ *     `-s KILL` the `-k` escalation signal is also KILL. Two residual gaps
+ *     on this branch, both bounded by "no worse than pre-fix" (where the
+ *     grandchild received no signal at all): the group-wide SIGKILL is
+ *     coreutils semantics — a busybox `timeout` passes the self-test (it
+ *     has `-k` and propagates exit status) but signals only its direct
+ *     child, so a busybox guard cannot reach the grandchild; and on the
+ *     SUPERVISED path (hook alive, inner spawnSync timeout SIGTERMs the
+ *     guard) coreutils forwards TERM rather than the `-s` signal, npx dies,
+ *     and the guard exits before any KILL fires — so a SIGTERM-immune CLI
+ *     grandchild still escapes in those two cases.
+ * If the sibling probe predates the resolveUnixGuardTimeout export (version
+ * skew), the adapter degrades to the unwrapped invocation instead of
+ * throwing. Windows is deliberately NOT wrapped — there is no coreutils
+ * timeout to resolve there and the resolver's self-test spawns /bin/sh — so
+ * on win32 (the npx.cmd path) and whenever the guard resolves to null (e.g.
+ * macOS without Homebrew coreutils — reported once under GITNEXUS_DEBUG)
+ * the argv stays byte-identical to the pre-wrap invocation.
  */
 function runGitNexusCli(cliPath, args, cwd, timeout) {
   const isWin = process.platform === 'win32';
+  // Version-skew guard (#2163 follow-up review): an older sibling probe
+  // without the resolveUnixGuardTimeout export must degrade to the unwrapped
+  // invocation — a TypeError here would be swallowed by the caller's catch
+  // and silently kill the augment.
+  const guard =
+    isWin || typeof resolveUnixGuardTimeout !== 'function' ? null : resolveUnixGuardTimeout();
+  if (!isWin && !guard && !unguardedCliWarned && isDebugEnabled()) {
+    // Diagnose the "stays unwrapped" Unix paths once per hook process: no
+    // usable coreutils timeout/gtimeout (e.g. macOS without Homebrew
+    // coreutils), GITNEXUS_HOOK_TIMEOUT_PATH=disabled, or probe skew above.
+    unguardedCliWarned = true;
+    process.stderr.write(
+      '[GitNexus hook] no usable timeout/gtimeout guard; augment CLI child runs unguarded\n',
+    );
+  }
   if (cliPath) {
-    return spawnSync(process.execPath, [cliPath, ...args], {
+    const [cmd, cmdArgs] = guard
+      ? [
+          guard,
+          ['-k', '1', String(Math.ceil(timeout / 1000) + 1), process.execPath, cliPath, ...args],
+        ]
+      : [process.execPath, [cliPath, ...args]];
+    return spawnSync(cmd, cmdArgs, {
       encoding: 'utf-8',
       timeout,
       cwd,
@@ -233,8 +298,27 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
       windowsHide: true,
     });
   }
-  // On Windows, invoke npx.cmd directly (no shell needed)
-  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
+  // On Windows, invoke npx.cmd directly (no shell needed). A non-null guard
+  // implies non-Windows, so the wrapped arm can hardcode plain `npx`. The
+  // wrapped arm leads with `-s KILL` (NOT TERM-first like the direct branch
+  // above): the CLI here is a grandchild behind npx — see the docblock.
+  const [cmd, cmdArgs] = guard
+    ? [
+        guard,
+        [
+          '-s',
+          'KILL',
+          '-k',
+          '1',
+          String(Math.ceil((timeout + 5000) / 1000) + 1),
+          'npx',
+          '-y',
+          'gitnexus',
+          ...args,
+        ],
+      ]
+    : [isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args]];
+  return spawnSync(cmd, cmdArgs, {
     encoding: 'utf-8',
     timeout: timeout + 5000,
     cwd,
@@ -259,22 +343,35 @@ function handlePreToolUse(input) {
 
   const pattern = extractPattern(toolName, toolInput);
   if (!pattern || pattern.length < 3) return;
-  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.
+
+  // 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) {
+    // 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: MCP server owns DB\n');
+      process.stderr.write('[GitNexus] augment skipped: hook slots saturated\n');
     }
     return;
   }
 
-  const release = acquireHookSlot(gitNexusDir);
-  if (!release) 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 || '');