gitnexus 1.6.8-rc.17 → 1.6.8-rc.19

package/dist/cli/help-i18n.js

@@ -27,6 +27,7 @@ const COMMAND_DESCRIPTION_KEYS = {
     impact: 'help.command.impact.description',
     cypher: 'help.command.cypher.description',
     'detect-changes': 'help.command.detectChanges.description',
+    check: 'help.command.check.description',
     'eval-server': 'help.command.evalServer.description',
     group: 'help.command.group.description',
     'group create': 'help.command.group.create.description',
@@ -117,6 +118,10 @@ const OPTION_DESCRIPTION_KEYS = {
     'detect-changes|-b, --base-ref <ref>': 'help.option.detectChanges.baseRef',
     'detect-changes|-r, --repo <name>': 'help.option.repo.target',
     'detect-changes|--branch <name>': 'help.option.branch',
+    'check|--cycles': 'help.option.check.cycles',
+    'check|--json': 'help.option.json',
+    'check|-r, --repo <name>': 'help.option.repo.target',
+    'check|--branch <name>': 'help.option.branch',
     'eval-server|-p, --port <port>': 'help.option.port',
     'eval-server|--host <host>': 'help.option.evalServer.host',
     'eval-server|--idle-timeout <seconds>': 'help.option.evalServer.idleTimeout',

package/dist/cli/i18n/en.d.ts

@@ -126,6 +126,7 @@ export declare const en: {
     readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
     readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
     readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
+    readonly 'help.command.check.description': "Run structural checks against the indexed graph";
     readonly 'help.command.evalServer.description': "Start lightweight HTTP server for fast tool calls during evaluation";
     readonly 'help.command.group.description': "Manage repository groups for cross-index impact analysis";
     readonly 'help.command.group.create.description': "Create a new group with template group.yaml";
@@ -200,6 +201,7 @@ export declare const en: {
     readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
     readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
     readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
+    readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
     readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
     readonly 'help.option.group.create.force': "Overwrite existing group";

package/dist/cli/i18n/en.js

@@ -126,6 +126,7 @@ export const en = {
     'help.command.impact.description': 'Blast radius analysis: what breaks if you change a symbol',
     'help.command.cypher.description': 'Execute raw Cypher query against the knowledge graph',
     'help.command.detectChanges.description': 'Map git diff hunks to indexed symbols and affected execution flows',
+    'help.command.check.description': 'Run structural checks against the indexed graph',
     'help.command.evalServer.description': 'Start lightweight HTTP server for fast tool calls during evaluation',
     'help.command.group.description': 'Manage repository groups for cross-index impact analysis',
     'help.command.group.create.description': 'Create a new group with template group.yaml',
@@ -200,6 +201,7 @@ export const en = {
     'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list',
     'help.option.detectChanges.scope': 'What to analyze: unstaged, staged, all, or compare',
     'help.option.detectChanges.baseRef': 'Branch/commit for compare scope (e.g. main)',
+    'help.option.check.cycles': 'Detect circular imports and fail when any are found',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
     'help.option.evalServer.idleTimeout': 'Auto-shutdown after N seconds idle (0 = disabled)',
     'help.option.group.create.force': 'Overwrite existing group',

package/dist/cli/i18n/resources.d.ts

@@ -127,6 +127,7 @@ export declare const cliResources: {
         readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
         readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
         readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
+        readonly 'help.command.check.description': "Run structural checks against the indexed graph";
         readonly 'help.command.evalServer.description': "Start lightweight HTTP server for fast tool calls during evaluation";
         readonly 'help.command.group.description': "Manage repository groups for cross-index impact analysis";
         readonly 'help.command.group.create.description': "Create a new group with template group.yaml";
@@ -201,6 +202,7 @@ export declare const cliResources: {
         readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
         readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
         readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
+        readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
         readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
         readonly 'help.option.group.create.force': "Overwrite existing group";
@@ -351,6 +353,7 @@ export declare const cliResources: {
         'help.command.impact.description': string;
         'help.command.cypher.description': string;
         'help.command.detectChanges.description': string;
+        'help.command.check.description': string;
         'help.command.evalServer.description': string;
         'help.command.group.description': string;
         'help.command.group.create.description': string;
@@ -425,6 +428,7 @@ export declare const cliResources: {
         'help.option.impact.summaryOnly': string;
         'help.option.detectChanges.scope': string;
         'help.option.detectChanges.baseRef': string;
+        'help.option.check.cycles': string;
         'help.option.evalServer.host': string;
         'help.option.evalServer.idleTimeout': string;
         'help.option.group.create.force': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -126,6 +126,7 @@ export declare const zhCN: {
     'help.command.impact.description': string;
     'help.command.cypher.description': string;
     'help.command.detectChanges.description': string;
+    'help.command.check.description': string;
     'help.command.evalServer.description': string;
     'help.command.group.description': string;
     'help.command.group.create.description': string;
@@ -200,6 +201,7 @@ export declare const zhCN: {
     'help.option.impact.summaryOnly': string;
     'help.option.detectChanges.scope': string;
     'help.option.detectChanges.baseRef': string;
+    'help.option.check.cycles': string;
     'help.option.evalServer.host': string;
     'help.option.evalServer.idleTimeout': string;
     'help.option.group.create.force': string;

package/dist/cli/i18n/zh-CN.js

@@ -126,6 +126,7 @@ export const zhCN = {
     'help.command.impact.description': '影响面分析：修改符号会影响什么',
     'help.command.cypher.description': '对知识图谱执行原始 Cypher 查询',
     'help.command.detectChanges.description': '将 git diff hunk 映射到已索引符号和受影响执行流程',
+    'help.command.check.description': '对已索引图谱运行结构检查',
     'help.command.evalServer.description': '启动轻量 HTTP 服务器，用于评测期间的快速工具调用',
     'help.command.group.description': '管理仓库组，用于跨索引影响分析',
     'help.command.group.create.description': '使用模板 group.yaml 创建新仓库组',
@@ -200,6 +201,7 @@ export const zhCN = {
     'help.option.impact.summaryOnly': '仅返回计数和风险等级，省略符号列表',
     'help.option.detectChanges.scope': '分析范围：unstaged、staged、all 或 compare',
     'help.option.detectChanges.baseRef': 'compare 范围的分支/提交（例如 main）',
+    'help.option.check.cycles': '检测循环导入，并在发现循环时失败',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',
     'help.option.evalServer.idleTimeout': '空闲 N 秒后自动关闭（0 = 禁用）',
     'help.option.group.create.force': '覆盖现有仓库组',

package/dist/cli/index.js

@@ -186,6 +186,14 @@ program
     .option('-r, --repo <name>', 'Target repository')
     .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
     .action(createLbugLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
+program
+    .command('check')
+    .description('Run structural checks against the indexed graph')
+    .option('--cycles', 'Detect circular imports and fail when any are found')
+    .option('--json', 'Emit machine-readable JSON')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
+    .action(createLbugLazyAction(() => import('./tool.js'), 'checkCommand'));
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 program
     .command('eval-server')

package/dist/cli/tool.d.ts

@@ -1,7 +1,7 @@
 /**
  * Direct CLI Tool Commands
  *
- * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Exposes GitNexus tools (query, context, impact, cypher, check) as direct CLI commands.
  * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
  *
  * Usage:
@@ -52,3 +52,9 @@ export declare function detectChangesCommand(options?: {
     repo?: string;
     branch?: string;
 }): Promise<void>;
+export declare function checkCommand(options?: {
+    cycles?: boolean;
+    json?: boolean;
+    repo?: string;
+    branch?: string;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -1,7 +1,7 @@
 /**
  * Direct CLI Tool Commands
  *
- * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Exposes GitNexus tools (query, context, impact, cypher, check) as direct CLI commands.
  * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
  *
  * Usage:
@@ -170,3 +170,38 @@ export async function detectChangesCommand(options) {
     });
     output(formatDetectChangesResult(result));
 }
+export async function checkCommand(options) {
+    if (!options?.cycles) {
+        process.stderr.write('Usage: gitnexus check --cycles [--json]\n');
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const backend = await getBackend();
+        const result = await backend.callTool('check', {
+            cycles: true,
+            repo: options.repo,
+            branch: options.branch,
+        });
+        if (result?.error) {
+            output(result);
+            process.exitCode = 1;
+            return;
+        }
+        if (options.json) {
+            output(result);
+        }
+        else if (result.cycleCount === 0) {
+            output('No circular imports found.');
+        }
+        else {
+            output(result.cycles.map((cycle) => cycle.files.join(' -> ')).join('\n'));
+        }
+        if (result.cycleCount > 0)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        output({ error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = 1;
+    }
+}

package/dist/core/graph/import-cycles.d.ts

@@ -0,0 +1,10 @@
+interface ImportEdge {
+    source: string;
+    target: string;
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export declare function findImportCycles(edges: ImportEdge[]): string[][];
+export {};

package/dist/core/graph/import-cycles.js

@@ -0,0 +1,103 @@
+function findCyclePath(component, adjacency) {
+    const allowed = new Set(component);
+    const start = component[0];
+    const parents = new Map([[start, null]]);
+    const queue = [start];
+    for (let index = 0; index < queue.length; index += 1) {
+        const node = queue[index];
+        for (const next of adjacency.get(node) ?? []) {
+            if (!allowed.has(next))
+                continue;
+            if (next === start) {
+                const path = [];
+                let cursor = node;
+                while (cursor !== null) {
+                    path.push(cursor);
+                    cursor = parents.get(cursor) ?? null;
+                }
+                path.reverse();
+                return [...path, start];
+            }
+            if (parents.has(next))
+                continue;
+            parents.set(next, node);
+            queue.push(next);
+        }
+    }
+    throw new Error('Invariant violation: no cycle found through SCC root.');
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export function findImportCycles(edges) {
+    const adjacency = new Map();
+    for (const { source, target } of edges) {
+        if (!source || !target)
+            continue;
+        const targets = adjacency.get(source) ?? new Set();
+        targets.add(target);
+        adjacency.set(source, targets);
+        if (!adjacency.has(target))
+            adjacency.set(target, new Set());
+    }
+    const sortedAdjacency = new Map([...adjacency].map(([node, targets]) => [node, [...targets].sort()]));
+    const reverseAdjacency = new Map();
+    for (const node of sortedAdjacency.keys())
+        reverseAdjacency.set(node, []);
+    for (const [source, targets] of sortedAdjacency) {
+        for (const target of targets)
+            reverseAdjacency.get(target).push(source);
+    }
+    for (const sources of reverseAdjacency.values())
+        sources.sort();
+    const visited = new Set();
+    const finishOrder = [];
+    const components = [];
+    for (const start of [...sortedAdjacency.keys()].sort()) {
+        if (visited.has(start))
+            continue;
+        visited.add(start);
+        const stack = [{ node: start, nextIndex: 0 }];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = sortedAdjacency.get(frame.node) ?? [];
+            if (frame.nextIndex < neighbors.length) {
+                const next = neighbors[frame.nextIndex++];
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    stack.push({ node: next, nextIndex: 0 });
+                }
+            }
+            else {
+                finishOrder.push(frame.node);
+                stack.pop();
+            }
+        }
+    }
+    visited.clear();
+    for (let index = finishOrder.length - 1; index >= 0; index -= 1) {
+        const start = finishOrder[index];
+        if (visited.has(start))
+            continue;
+        const component = [];
+        const stack = [start];
+        visited.add(start);
+        while (stack.length > 0) {
+            const node = stack.pop();
+            component.push(node);
+            for (const next of reverseAdjacency.get(node) ?? []) {
+                if (visited.has(next))
+                    continue;
+                visited.add(next);
+                stack.push(next);
+            }
+        }
+        component.sort();
+        components.push(component);
+    }
+    return components
+        .filter((component) => component.length > 1 || (sortedAdjacency.get(component[0]) ?? []).includes(component[0]))
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .map((component) => findCyclePath(component, sortedAdjacency));
+}

package/dist/mcp/local/local-backend.d.ts

@@ -337,6 +337,8 @@ export declare class LocalBackend {
      */
     private maybeWarnSiblingDrift;
     callTool(method: string, params: any): Promise<any>;
+    /** Check repository graph invariants that are suitable for CI gating. */
+    private check;
     /**
      * Query tool — process-grouped search.
      *

package/dist/mcp/local/local-backend.js

@@ -28,6 +28,7 @@ import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
 import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT } from '../tools.js';
+import { findImportCycles } from '../../core/graph/import-cycles.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -1037,6 +1038,8 @@ export class LocalBackend {
                 return this.impact(repo, params);
             case 'detect_changes':
                 return this.detectChanges(repo, params);
+            case 'check':
+                return this.check(repo, params);
             case 'rename':
                 return this.rename(repo, params);
             // Legacy aliases for backwards compatibility
@@ -1059,6 +1062,37 @@ export class LocalBackend {
         }
     }
     // ─── Tool Implementations ────────────────────────────────────────
+    /** Check repository graph invariants that are suitable for CI gating. */
+    async check(repo, params) {
+        if (params?.cycles === false) {
+            return { error: 'No checks selected. Set "cycles" to true.' };
+        }
+        await this.ensureInitialized(repo);
+        const rowLimit = 100_001;
+        const rows = await executeParameterized(repo.lbugPath, `MATCH (source:File)-[r:CodeRelation]->(target:File)
+       WHERE r.type = 'IMPORTS'
+         AND (r.reason IS NULL OR (
+           r.reason <> 'swift-scope: implicit module visibility'
+           AND r.reason <> 'markdown-link'
+         ))
+       RETURN source.filePath AS source, target.filePath AS target
+       LIMIT ${rowLimit}`, {});
+        if (rows.length === rowLimit) {
+            return {
+                error: `Import graph exceeds the ${rowLimit - 1} edge safety limit.`,
+                truncated: true,
+            };
+        }
+        const cycles = findImportCycles(rows.map((row) => ({
+            source: String(row.source ?? row[0] ?? ''),
+            target: String(row.target ?? row[1] ?? ''),
+        })));
+        return {
+            status: cycles.length === 0 ? 'clean' : 'cycles_found',
+            cycleCount: cycles.length,
+            cycles: cycles.map((files) => ({ files })),
+        };
+    }
     /**
      * Query tool — process-grouped search.
      *

package/dist/mcp/tools.js

@@ -277,6 +277,29 @@ Returns: changed symbols, affected processes, and a risk summary.`,
             required: [],
         },
     },
+    {
+        name: 'check',
+        description: `Run read-only structural checks against the indexed graph.
+
+Currently detects directed cycles between File nodes connected by IMPORTS edges.
+Returns deterministic cycle paths and a cycle count suitable for CI automation.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cycles: {
+                    type: 'boolean',
+                    description: 'Detect circular file imports (default: true).',
+                    default: true,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: [],
+        },
+    },
     {
         name: 'rename',
         description: `Multi-file coordinated rename using the knowledge graph + text search.
@@ -572,6 +595,7 @@ const BRANCH_SCOPED_TOOLS = new Set([
     'cypher',
     'context',
     'detect_changes',
+    'check',
     'impact',
     'rename',
     'route_map',

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

@@ -284,18 +284,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

@@ -259,22 +259,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 || '');

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.17",
+  "version": "1.6.8-rc.19",
   "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",