gitnexus 1.6.13-rc.34 → 1.6.13-rc.35

package/README.md

@@ -2,7 +2,7 @@
 
 **Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
 
-Works with **Cursor**, **Claude Code**, **Antigravity** (Google), **Codex**, **Windsurf**, **Cline**, **OpenCode**, **CodeBuddy** (Tencent), **Qoder** (Alibaba), and any MCP-compatible tool.
+Works with **Cursor**, **Claude Code**, **Antigravity** (Google), **Codex**, **Factory** (Droid), **Windsurf**, **Cline**, **OpenCode**, **CodeBuddy** (Tencent), **Qoder** (Alibaba), and any MCP-compatible tool.
 
 [![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
@@ -44,12 +44,13 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Cursor**               | Yes | Yes    | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
 | **Antigravity** (Google) | Yes | Yes    | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))    | **Full**     |
 | **Codex**                | Yes | Yes    | Yes (PreToolUse + PostToolUse, [Codex hooks](https://developers.openai.com/codex/hooks))   | **Full**     |
+| **Factory** (Droid)      | Yes | Yes    | Yes (PostToolUse, [plugin](../gitnexus-factory-plugin/))                                   | **Full**     |
 | **OpenCode**             | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **CodeBuddy** (Tencent)  | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Qoder** (Alibaba)      | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 
-> **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
+> **Full** means MCP tools + agent skills + hooks that enrich searches with graph context. **Claude Code** and **Codex** go deepest: their PreToolUse hooks enrich the search before it runs, and their PostToolUse hooks also detect a stale index after commits and prompt the agent to reindex. **Cursor**, **Antigravity**, and **Factory** augment from a post-tool hook only, so they enrich the result rather than the query and do not carry the stale-index hint.
 
 ### Community Integrations
 
@@ -88,6 +89,33 @@ codex plugin marketplace add abhigyanpatwari/GitNexus
 
 > **Codex notes:** SessionStart is intentionally not registered — Codex reads [AGENTS.md natively](https://developers.openai.com/codex/guides/agents-md), which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via `/hooks` before they run. Pick **one** install route (`gitnexus setup -c codex` **or** the plugin): plugin hooks load alongside `~/.codex/hooks.json`, so installing both can fire duplicate hooks per tool call.
 
+### Factory (Droid) (full support — MCP + skills + hooks)
+
+`gitnexus setup -c droid` writes the MCP server to `~/.factory/mcp.json` and installs skills to
+`~/.factory/skills/`. To configure MCP by hand instead, add to `~/.factory/mcp.json`
+([user scope](https://docs.factory.ai/cli/configuration/mcp) — applies to all projects):
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+For the PostToolUse search-augment hook, install the bundled
+[`gitnexus-factory-plugin/`](../gitnexus-factory-plugin/) with `droid plugin install gitnexus@<marketplace>`
+from a marketplace that includes this repo, or point Droid at it via `extraKnownMarketplaces` in
+`.factory/settings.json`.
+
+> **Factory notes:** Droid reads [AGENTS.md natively](https://docs.factory.ai/), which already carries the
+> GitNexus context block, so no SessionStart hook is registered. Pick **one** install route
+> (`gitnexus setup -c droid` **or** the plugin) — the plugin ships its own MCP entry, so installing both
+> can register the server twice.
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):

package/dist/cli/editor-targets.d.ts

@@ -15,7 +15,7 @@
  * implementations remain behaviourally symmetrical on top of this shared
  * structure.
  */
-export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codebuddy' | 'qoder' | 'codex';
+export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codebuddy' | 'qoder' | 'codex' | 'droid';
 /** An editor whose MCP config is a JSONC document (server keyed by name). */
 export interface McpJsoncTarget {
     id: EditorId;

package/dist/cli/editor-targets.js

@@ -76,6 +76,15 @@ export function getEditorTargets(home = os.homedir()) {
             file: path.join(home, '.qoder.json'),
             keyPath: ['mcpServers', 'gitnexus'],
         },
+        {
+            id: 'droid',
+            label: 'Factory Droid',
+            // Factory's user-scope MCP config (https://docs.factory.ai/cli/configuration/mcp).
+            // Same `mcpServers` object shape as Cursor/Claude; user config takes
+            // precedence over project-level .factory/mcp.json.
+            file: path.join(home, '.factory', 'mcp.json'),
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
     ];
     const codex = {
         id: 'codex',
@@ -98,6 +107,9 @@ export function getEditorTargets(home = os.homedir()) {
         { id: 'qoder', label: 'Qoder', dir: path.join(home, '.qoder', 'skills') },
         // Codex reads skills from ~/.agents/skills (not ~/.codex).
         { id: 'codex', label: 'Codex', dir: path.join(home, '.agents', 'skills') },
+        // Factory Droid reads user-scope skills from ~/.factory/skills/{name}/SKILL.md
+        // (https://docs.factory.ai/cli/configuration/skills).
+        { id: 'droid', label: 'Factory Droid', dir: path.join(home, '.factory', 'skills') },
     ];
     const hooks = [
         {

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

@@ -152,7 +152,7 @@ export declare const en: {
     readonly 'help.command.help.description': 'display help for command';
     readonly 'help.option.help': 'display help for command';
     readonly 'help.option.version': 'output the version number';
-    readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex';
+    readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid';
     readonly 'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors';
     readonly 'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml';
     readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.';

package/dist/cli/i18n/en.js

@@ -154,7 +154,7 @@ export const en = {
     'help.command.help.description': 'display help for command',
     'help.option.help': 'display help for command',
     'help.option.version': 'output the version number',
-    'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex',
+    'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid',
     'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors',
     'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml',
     'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.',

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

@@ -153,7 +153,7 @@ export declare const cliResources: {
         readonly 'help.command.help.description': 'display help for command';
         readonly 'help.option.help': 'display help for command';
         readonly 'help.option.version': 'output the version number';
-        readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex';
+        readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid';
         readonly 'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors';
         readonly 'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml';
         readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.';

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

@@ -152,7 +152,7 @@ export const zhCN = {
     'help.command.help.description': '显示命令帮助',
     'help.option.help': '显示命令帮助',
     'help.option.version': '输出版本号',
-    'help.command.setup.description': '一次性设置：为 Cursor、Claude Code、Antigravity、OpenCode、CodeBuddy、Qoder、Codex 配置 MCP',
+    'help.command.setup.description': '一次性设置：为 Cursor、Claude Code、Antigravity、OpenCode、CodeBuddy、Qoder、Codex、Factory Droid 配置 MCP',
     'help.command.uninstall.description': '撤销 `setup`：从所有检测到的编辑器中移除 GitNexus 的 MCP 配置、技能和钩子',
     'help.command.autoSync.description': '控制基于 GITNEXUS_HOME/watch_config.yml 的定时 clone/pull 和分析',
     'help.autoSync.details': '\n操作：init、start（默认）、restart、stop、status、reset\n配置：GITNEXUS_HOME/watch_config.yml\n运行时文件：GITNEXUS_HOME/watch/watch.pid、watch.mutex、watch.owner.json、watch.status.json、auto-sync-state.json\n恢复：已验证 owner 退出的 mutex 会自动回收；无效或旧版 mutex 会安全拒绝，确认没有 watch 进程运行后再手动删除。\n写入：GITNEXUS_HOME/watch/project_commit_info.txt\n远程地址：仅允许 github.com、gitlab.com 和 gitee.com 上的 SSH 地址。\n启动后立即运行一次，之后按 sync_interval_minutes 重复。',

package/dist/cli/index.js

@@ -17,7 +17,7 @@ function collectCodingAgents(value, previous) {
 program.name('gitnexus').description('GitNexus local CLI and MCP server').version(packageVersion());
 program
     .command('setup')
-    .description('One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex')
+    .description('One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid')
     .option('-c, --coding-agent <agents>', 'Configure only these coding agents (comma-separated or repeatable)', collectCodingAgents)
     .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
 program

package/dist/cli/setup.js

@@ -70,6 +70,7 @@ const CODING_AGENT_IDS = {
     codebuddy: 'codebuddy',
     qoder: 'qoder',
     codex: 'codex',
+    droid: 'droid',
 };
 const SUPPORTED_CODING_AGENTS = Object.values(CODING_AGENT_IDS);
 function selectedCodingAgents(values) {
@@ -824,6 +825,55 @@ async function installQoderSkills(result) {
         result.errors.push(`Qoder skills: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/**
+ * Configure the GitNexus MCP server for Factory Droid.
+ *
+ * Factory stores user-scope MCP config in ~/.factory/mcp.json using the same
+ * `{ mcpServers: { <name>: {...} } }` JSONC shape as Cursor/Claude
+ * (https://docs.factory.ai/cli/configuration/mcp), so we reuse mergeJsoncFile
+ * rather than shelling out to `droid mcp add` — that keeps setup working even
+ * when the `droid` binary isn't on PATH.
+ */
+async function setupDroid(result) {
+    const factoryDir = path.join(os.homedir(), '.factory');
+    if (!(await dirExists(factoryDir))) {
+        result.skipped.push('Factory Droid (not installed)');
+        return;
+    }
+    const { file: mcpPath, keyPath } = mcpTarget('droid');
+    try {
+        const ok = await mergeJsoncFile(mcpPath, keyPath, getMcpEntry());
+        if (ok) {
+            result.configured.push('Factory Droid');
+        }
+        else {
+            result.errors.push('Factory Droid: mcp.json is corrupt — skipping to preserve existing content');
+        }
+    }
+    catch (err) {
+        result.errors.push(`Factory Droid: ${err.message}`);
+    }
+}
+/**
+ * Install global Factory Droid skills to ~/.factory/skills/{name}/SKILL.md
+ * (https://docs.factory.ai/cli/configuration/skills — same SKILL.md layout as
+ * Claude Code).
+ */
+async function installDroidSkills(result) {
+    const factoryDir = path.join(os.homedir(), '.factory');
+    if (!(await dirExists(factoryDir)))
+        return;
+    const skillsDir = skillTarget('droid').dir;
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Factory Droid skills (${installed.length} skills → ~/.factory/skills/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Factory Droid skills: ${err.message}`);
+    }
+}
 /**
  * Build a TOML section for Codex MCP config (~/.codex/config.toml).
  */
@@ -1107,6 +1157,8 @@ export const setupCommand = async (options) => {
         await setupQoder(result);
     if (selected.has('codex'))
         await setupCodex(result);
+    if (selected.has('droid'))
+        await setupDroid(result);
     // Install global skills for platforms that support them
     if (selected.has('claude')) {
         await installClaudeCodeSkills(result);
@@ -1128,6 +1180,11 @@ export const setupCommand = async (options) => {
         await installCodexSkills(result);
         await installClaudeSchemaHooks(result, 'codex');
     }
+    // MCP + skills only. Factory hooks (Execute matcher, PostToolUse) ship in the
+    // standalone gitnexus-factory-plugin instead of the setup path — add a droid
+    // hook target + adapter here if setup-installed hooks are wanted.
+    if (selected.has('droid'))
+        await installDroidSkills(result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');

package/hooks/claude/hook-db-lock-probe.cjs

@@ -80,9 +80,11 @@ function debugLog(msg) {
 
 function resolveHookBinary(tool) {
   const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH';
-  const fromEnv = process.env[envKey];
-  if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) {
-    return String(fromEnv);
+  // Trim once, exactly as hasMissingHookBinaryOverride does, so a padded but
+  // valid override (" /tmp/lsof ") is both accepted there and used here.
+  const fromEnv = process.env[envKey] ? String(process.env[envKey]).trim() : '';
+  if (fromEnv && fs.existsSync(fromEnv)) {
+    return fromEnv;
   }
   const candidates =
     tool === 'lsof'
@@ -177,7 +179,13 @@ function resolveUnixGuardTimeout() {
   const trimmed = fromEnv ? String(fromEnv).trim() : '';
   if (trimmed === 'disabled') return unixGuardTimeoutCache;
   const candidates = [];
-  if (trimmed && fs.existsSync(trimmed)) candidates.push(trimmed);
+  // Resolve the override against THIS process's cwd — the directory the
+  // existsSync check and the self-test run in — so the cached/returned path is
+  // always absolute. The adapters spawn the wrapper with a different `cwd`
+  // (the tool request's), where a relative value would resolve elsewhere
+  // (ENOENT), and a slashless name would switch to a PATH lookup.
+  const override = trimmed ? path.resolve(trimmed) : '';
+  if (override && fs.existsSync(override)) candidates.push(override);
   for (const builtin of [
     '/usr/bin/timeout',
     '/bin/timeout',
@@ -317,15 +325,30 @@ function getProcRoot() {
 // `node <abs path to .../node_modules/gitnexus/dist/cli/index.js> mcp` line
 // (the `mcp`/`serve` mode token lives at the very tail, so the cap must be large
 // enough to reach it — see PROC_CMDLINE_FLOOR escalation below). Overridable for
-// tests; never goes below PROC_CMDLINE_FLOOR.
+// tests via GITNEXUS_HOOK_PROC_CMDLINE_MAX: an integer in
+// [PROC_CMDLINE_FLOOR, PROC_CMDLINE_CEIL] is used as-is; a larger integer is
+// CLAMPED to PROC_CMDLINE_CEIL; anything else (below the floor, fractional,
+// non-numeric, Infinity) falls back to the 16 KiB default.
 const PROC_CMDLINE_FLOOR = 4096;
+// Upper bound for a single cmdline read chunk, and the absolute ceiling of the
+// escalation path in readLinuxCmdline (same 256 KiB — no single read may exceed
+// what the whole escalation is allowed to collect). Without it, an oversized
+// override (e.g. 2**40 — past buffer.constants.MAX_LENGTH on older Node lines
+// and unallocatable in practice on any) made Buffer.allocUnsafe throw; readLinuxCmdline's catch turned that into '' (a
+// NON-candidate), so a real server owner was silently missed (fail-OPEN, the
+// #1492 race). Oversized values are clamped rather than defaulted: the operator
+// asked for MORE bytes, and the ceiling is the most the read will ever collect
+// anyway, so clamping honours the intent while keeping allocation bounded.
+const PROC_CMDLINE_CEIL = 262144;
 function getCmdlineMaxBytes() {
   const raw = process.env.GITNEXUS_HOOK_PROC_CMDLINE_MAX;
   // Number() (not parseInt) so "8e3" reads as 8000, not 8 (parseInt stops at
   // 'e'). The `raw && String(raw).trim()` guard keeps empty/whitespace on the
   // default; trailing garbage ("8abc") now -> NaN -> default (stricter).
   const n = raw && String(raw).trim() ? Number(String(raw).trim()) : NaN;
-  if (Number.isFinite(n) && n >= PROC_CMDLINE_FLOOR) return n;
+  // Number.isInteger rejects NaN, +/-Infinity and fractions (a fractional
+  // Buffer/readSync length is not a byte count).
+  if (Number.isInteger(n) && n >= PROC_CMDLINE_FLOOR) return Math.min(n, PROC_CMDLINE_CEIL);
   return 16384;
 }
 
@@ -381,19 +404,24 @@ const CMDLINE_TIMEOUT = Symbol('gitnexus.cmdline.timeout');
 
 // Bounded /proc/<pid>/cmdline read for Phase 1. openSync+readSync (not
 // readFileSync) so a D-state holder cannot stall the hook on a huge or
-// never-EOF argv: we read at most `cap` bytes and stop. cmdline separates argv
-// with NULs; convert to spaces for isGitNexusServerCommand.
+// never-EOF argv: we read in `cap`-sized chunks and stop as soon as the text
+// holds both server tokens, at EOF, at PROC_CMDLINE_CEIL, or when the scan
+// budget runs out (see below). cmdline separates argv with NULs; convert to
+// spaces for isGitNexusServerCommand.
 //
 // Owner-miss guard for the 4 KB cap: the `gitnexus` token usually sits in the
 // first path component while the `mcp`/`serve` mode token is the LAST argv, so
 // a naive 4 KB read could clip the mode token off a server launched with a very
 // long interpreter path and silently miss a real owner. We mitigate two ways:
-// (a) the default cap (16 KiB) already clears realistic lines; (b) if the first
-// read fills the cap AND already contains the `gitnexus` token but no mode
-// token yet, we keep reading in bounded chunks (up to a hard ceiling) until the
-// mode token appears or the file ends — so a genuine server is never missed for
-// want of a few more bytes, while non-candidates still pay only the initial
-// bounded read.
+// (a) the default cap (16 KiB) already clears realistic lines, so almost every
+// process is decided by the first read hitting EOF; (b) a read that fills the
+// cap stops early ONLY once it holds BOTH tokens (decided owner). Holding one
+// token, or neither, decides nothing: interpreter flags can put a mode-looking
+// word first (`node --require mcp .../gitnexus/... serve`) or push the gitnexus
+// path past the first chunk. So we keep reading in cap-sized chunks until both
+// tokens appear, the file ends, or the hard ceiling is reached. Only processes
+// that passed the Phase 0 comm prefilter AND have a cmdline longer than the cap
+// ever escalate, and each escalation step is budget-gated (below).
 //
 // Budget (F3): the escalation loop above is the one place a SINGLE pathological
 // candidate could read up to HARD_CEIL (256 KiB) before the next scan-level
@@ -411,7 +439,7 @@ function readLinuxCmdline(procRoot, pidStr, cap, outOfBudget) {
     return '';
   }
   try {
-    const HARD_CEIL = 262144; // 256 KiB absolute ceiling for the escalation path
+    const HARD_CEIL = PROC_CMDLINE_CEIL; // 256 KiB absolute ceiling for the escalation path
     let collected = Buffer.alloc(0);
     let offset = 0;
     let chunkCap = cap;
@@ -425,16 +453,12 @@ function readLinuxCmdline(procRoot, pidStr, cap, outOfBudget) {
       collected = Buffer.concat([collected, buf.subarray(0, bytes)]);
       offset += bytes;
       const text = collected.toString('utf8').replace(/\0+/g, ' ');
-      // Stop early when we can already decide "owner": has both the gitnexus
-      // token and a mode token. Keep going only when gitnexus is present but
-      // the mode token might be just past the boundary.
-      const hasGitNexus =
-        /(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(text) ||
-        /node_modules[/\\]gitnexus[/\\]/.test(text);
-      const hasMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(text);
-      if (hasMode) break; // decided (positive); isGitNexusServerCommand re-checks below
+      // Stop early only when the partial read is DECIDED: both the gitnexus
+      // token and a mode token are present (isGitNexusServerCommand is exactly
+      // that conjunction). A partial read missing either token is undecided —
+      // the missing one may lie past the chunk boundary — so it keeps reading.
+      if (isGitNexusServerCommand(text)) break; // decided (positive)
       if (bytes < chunkCap) break; // EOF: full cmdline read, definitive
-      if (!hasGitNexus) break; // not a candidate; do not escalate the read
       if (offset >= HARD_CEIL) break; // bounded escalation only
       // Budget gate the escalation: a single huge-argv candidate must not burn
       // the whole scan deadline before we re-check. Return the timeout sentinel
@@ -578,17 +602,24 @@ function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
         );
         return 'timeout';
       }
-      // Any other shape (ENOTDIR — fd path is not a directory at all, so this
-      // is not a plausible live-procfs owner — and the long tail) is treated as
-      // "this candidate is not an owner": move to the next candidate instead of
-      // the old blanket 'owned'. If no other candidate owns the lbug the scan
-      // ends not-owned (dispatcher fail-open) — acceptable because ENOTDIR means
-      // the fd entry is structurally not a real /proc/<pid>/fd.
+      if (code === 'ENOTDIR') {
+        // The fd path is not a directory at all, so this is structurally not a
+        // real /proc/<pid>/fd — not a plausible live owner. Move on.
+        debugLog(
+          `fd dir not a directory for candidate pid ${pidStr} (ENOTDIR); ` +
+            `treating candidate as non-owner -> continue`,
+        );
+        continue;
+      }
+      // Any other error (EMFILE, ENFILE, ENOMEM, EINTR, no code, …) says nothing
+      // about whether this already-identified server candidate holds the lbug.
+      // Only ENOENT/ENOTDIR above establish non-ownership; everything else is
+      // inconclusive and fails closed via 'timeout', same as EACCES/EIO.
       debugLog(
-        `fd dir not a readable directory for candidate pid ${pidStr} ` +
-          `(${code || 'unknown'}); treating candidate as non-owner -> continue`,
+        `fd dir read failed for candidate pid ${pidStr} ` +
+          `(${code || 'unknown'}); probe inconclusive -> fail-closed (timeout)`,
       );
-      continue;
+      return 'timeout';
     }
     for (const fd of fds) {
       if (outOfBudget()) return 'timeout';
@@ -707,16 +738,12 @@ module.exports = {
   // name is pinned by a source-contract test.
   linuxProcScanFindGitNexusServer,
   // #2163 follow-up: the hook adapters wrap the augment CLI in the same
-  // guard. Returns a self-tested wrapper path — the built-in candidates are
-  // always absolute; a GITNEXUS_HOOK_TIMEOUT_PATH override is adopted as the
-  // exact string that passed the self-test. Same string is also the same
-  // RESOLUTION for absolute paths and for slashless names (PATH lookup is
-  // cwd-independent); a slash-containing RELATIVE override, however, is
-  // existsSync-checked and self-tested against this process's cwd while the
-  // adapters spawn the CLI with a `cwd` option (chdir-before-exec), so such
-  // a value can pass here yet ENOENT at the augment call site — set the
-  // override to an absolute path. Returns null when the wrapper is
-  // disabled/unavailable. Never call on win32 (see its JSDoc).
+  // guard. Returns a self-tested, always-ABSOLUTE wrapper path: the built-in
+  // candidates are absolute, and a GITNEXUS_HOOK_TIMEOUT_PATH override is
+  // path.resolve()d against this process's cwd before its existsSync check
+  // and self-test, so the adapters can spawn it under any `cwd` option.
+  // Returns null when the wrapper is disabled/unavailable. Never call on
+  // win32 (see its JSDoc).
   resolveUnixGuardTimeout,
   // Exported for white-box unit tests of the numeric-env parsing (#2183 review):
   // Number()-not-parseInt so "16e3" reads as 16000, plus the empty/whitespace
@@ -725,4 +752,8 @@ module.exports = {
   // otherwise only observable indirectly through scan timing/escalation.
   getCmdlineMaxBytes,
   resolveLinuxProcBudgetMs,
+  // Exported for white-box tests pinning that the override check and the
+  // override lookup agree on whitespace-padded GITNEXUS_HOOK_{LSOF,PS}_PATH.
+  resolveHookBinary,
+  hasMissingHookBinaryOverride,
 };

package/hooks/claude/hook-lock.cjs

@@ -1,3 +1,4 @@
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
@@ -5,6 +6,128 @@ const HOOK_LOCK_SUBDIR = '.hook-locks';
 const HOOK_LOCK_MAX_INFLIGHT = 3;
 const HOOK_LOCK_STALE_MS = 30000;
 
+// An evictor's claim marker older than this belongs to a crashed evictor.
+// The critical section it guards is a few syscalls (token read, lstat,
+// unlink), so any live evictor finishes orders of magnitude sooner; kept well
+// under HOOK_LOCK_STALE_MS so an orphan never blocks a slot for long.
+const HOOK_LOCK_EVICT_MARKER_STALE_MS = 5000;
+
+// Same file iff inode identity AND content metadata match. dev+ino alone is
+// not enough: filesystems reuse a freed inode number immediately (ext4), so a
+// file recreated after an unlink can carry the old file's ino. bigint stats
+// keep Windows' 64-bit file ids exact.
+function sameSlotFile(a, b) {
+  return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs;
+}
+
+function readMarkerToken(marker) {
+  try {
+    return fs.readFileSync(marker, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+// Stat and token of a marker, both taken from one open descriptor so they
+// describe the same file (a path stat followed by a path read could straddle
+// a replacement). O_NOFOLLOW where the platform has it: a marker is always a
+// regular file this module created. Returns null when there is no marker.
+function readMarkerSnapshot(marker) {
+  let fd;
+  try {
+    fd = fs.openSync(marker, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    return { stat: fs.fstatSync(fd, { bigint: true }), token: fs.readFileSync(fd, 'utf-8') };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+}
+
+// Break an evictor's claim marker only if it is an orphan: older than
+// HOOK_LOCK_EVICT_MARKER_STALE_MS, and still the exact file (identity and
+// owner token) judged old when it is re-checked just before the unlink. A
+// marker released and re-created by a new claimant in between is fresh, so
+// it fails the check and stays.
+function breakOrphanedMarker(marker) {
+  const seen = readMarkerSnapshot(marker);
+  if (!seen || Date.now() - Number(seen.stat.mtimeMs) <= HOOK_LOCK_EVICT_MARKER_STALE_MS) return;
+  const now = readMarkerSnapshot(marker);
+  if (!now || !sameSlotFile(now.stat, seen.stat) || now.token !== seen.token) return;
+  try {
+    fs.unlinkSync(marker);
+  } catch {
+    /* another contender already cleared it */
+  }
+}
+
+// Evict a slot judged stale from the `inspected` stat. A slot file is only
+// ever deleted, never moved, and only by the evictor holding the per-slot
+// `<slot>.evicting` marker, created O_EXCL with a token unique to this call.
+// Every destructive step verifies first:
+//  - the slot is unlinked only if the marker still carries our token (an
+//    evictor stalled long enough for its marker to be broken as an orphan has
+//    lost its claim and backs off) and the slot is still the exact file
+//    inspected — identical dev/ino/size/mtimeNs means its content and age are
+//    unchanged, so the stale verdict still holds, while a slot recreated since
+//    inspection fails the check and its lock stands;
+//  - our marker is removed only if it still carries our token, so a marker
+//    that has passed to another claimant is left alone;
+//  - an orphaned marker is broken only if it is still the old file it was
+//    judged to be (see breakOrphanedMarker).
+//
+// Residual windows. POSIX has no conditional unlink, so each check-then-
+// unlink pair keeps a gap of two adjacent syscalls:
+//  (a) Slot: between the lstat identity check and unlinkSync(slot), a live
+//      owner past HOOK_LOCK_STALE_MS could release and a new hook recreate the
+//      slot, whose fresh lock would then be deleted. The consequence is at
+//      most one extra concurrent augment beyond HOOK_LOCK_MAX_INFLIGHT for
+//      that run — the cap is a load guard, and no data or index state
+//      depends on it. The victim's release() sees a foreign or missing file
+//      and leaves it alone.
+//  (b) Marker: between the token re-read and unlinkSync(marker) (ours or an
+//      orphan's), the marker could pass to another claimant, whose claim would
+//      then be removed. That only re-opens the slot to one more evictor, which
+//      still has to pass the slot identity check before deleting anything.
+// Both need a stall of seconds landing on that exact syscall pair, and the
+// only thing lost is one run's cap accounting, so they are accepted rather
+// than traded for heavier machinery. A crash at any point orphans at most the
+// marker, which the next contender breaks after it expires.
+function evictStaleSlot(slotPath, inspected) {
+  const marker = `${slotPath}.evicting`;
+  breakOrphanedMarker(marker);
+  const token = `${process.pid}:${crypto.randomBytes(8).toString('hex')}`;
+  try {
+    fs.writeFileSync(marker, token, { flag: 'wx' });
+  } catch {
+    return; // Another evictor holds this slot — leave it to that evictor.
+  }
+  try {
+    if (
+      readMarkerToken(marker) === token &&
+      sameSlotFile(fs.lstatSync(slotPath, { bigint: true }), inspected)
+    ) {
+      fs.unlinkSync(slotPath);
+    }
+  } catch {
+    /* slot already gone — the retry claims it */
+  } finally {
+    if (readMarkerToken(marker) === token) {
+      try {
+        fs.unlinkSync(marker);
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+}
+
 function acquireHookSlot(gitNexusDir) {
   const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
   try {
@@ -28,6 +151,7 @@ function acquireHookSlot(gitNexusDir) {
         const release = () => {
           if (released) return;
           released = true;
+          process.removeListener('exit', release);
           try {
             // Only unlink if we still own the slot. If we appeared stale and
             // another hook took over, the file now belongs to it — leave alone.
@@ -52,8 +176,10 @@ function acquireHookSlot(gitNexusDir) {
         }
         let isLive = false;
         let mtimeMs = Date.now();
+        let inspected = null;
         try {
-          mtimeMs = fs.fstatSync(fd).mtimeMs;
+          inspected = fs.fstatSync(fd, { bigint: true });
+          mtimeMs = Number(inspected.mtimeMs);
           const buf = Buffer.alloc(32);
           const n = fs.readSync(fd, buf, 0, 32, 0);
           const ownerStr = buf.slice(0, n).toString('utf-8').trim();
@@ -98,11 +224,9 @@ function acquireHookSlot(gitNexusDir) {
           isLive = false;
         }
         if (isLive) break; // Try the next slot.
-        try {
-          fs.unlinkSync(slotPath);
-        } catch {
-          /* another hook beat us to it — retry will hit EEXIST */
-        }
+        // No stat means we cannot prove which file we judged stale; leave it
+        // (the retry re-inspects it) rather than risk deleting a fresh lock.
+        if (inspected) evictStaleSlot(slotPath, inspected);
         // Loop and retry this slot.
       }
     }