gitnexus 1.6.13-rc.33 → 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/dist/mcp/local/query-process-attaches.d.ts

@@ -5,6 +5,8 @@
  * Aggregation already pushes a hub onto every owning process. This helper
  * is the last shaping step: slice each process to `max_symbols`, keep one
  * row per `(id, process_id)`, then set `symbol_count` from those rows.
+ * `content` stays only on the first row for each symbol id so a hub in
+ * many flows does not repeat its source text.
  */
 export type QueryProcessAttach = {
     id: string;

package/dist/mcp/local/query-process-attaches.js

@@ -5,6 +5,8 @@
  * Aggregation already pushes a hub onto every owning process. This helper
  * is the last shaping step: slice each process to `max_symbols`, keep one
  * row per `(id, process_id)`, then set `symbol_count` from those rows.
+ * `content` stays only on the first row for each symbol id so a hub in
+ * many flows does not repeat its source text.
  */
 /**
  * Pair key for attach rows. Both `id` and `process_id` routinely contain
@@ -16,6 +18,7 @@ function attachPairKey(id, processId) {
 export function shapeQueryProcessAttaches(rankedProcesses, options) {
     const { maxSymbolsPerProcess, chainByProcessId } = options;
     const seen = new Set();
+    const contentSeen = new Set();
     const process_symbols = [];
     const countByProcess = new Map();
     for (const p of rankedProcesses) {
@@ -24,7 +27,18 @@ export function shapeQueryProcessAttaches(rankedProcesses, options) {
             if (seen.has(key))
                 continue;
             seen.add(key);
-            const row = p.entryPointId && s.id === p.entryPointId ? { ...s, is_entry_point: true } : s;
+            let row = s;
+            if (s.content !== undefined) {
+                if (contentSeen.has(s.id)) {
+                    const { content: _content, ...rest } = s;
+                    row = rest;
+                }
+                else {
+                    contentSeen.add(s.id);
+                }
+            }
+            if (p.entryPointId && s.id === p.entryPointId)
+                row = { ...row, is_entry_point: true };
             process_symbols.push(row);
             countByProcess.set(s.process_id, (countByProcess.get(s.process_id) ?? 0) + 1);
         }

package/dist/mcp/server.js

@@ -38,7 +38,7 @@ function getNextStepHint(toolName, args) {
         case 'list_repos':
             return `\n\n---\n**Next:** READ gitnexus://repo/{name}/context for any repo above to get its overview and check staleness. If pagination.hasMore is true, call list_repos again with offset set to pagination.nextOffset to fetch the rest.`;
         case 'query':
-            return `\n\n---\n**Next:** To understand a specific symbol in depth, use context({name: "<symbol_name>"${repoParam}}) to see categorized refs and process participation.`;
+            return `\n\n---\n**Next:** To understand a specific symbol in depth, use context({name: "<symbol_name>"${repoParam}}) to see categorized refs and process participation.${args?.include_content === true ? ` For source of a process_symbols row without content, use context({uid: "<id>", include_content: true${repoParam}}).` : ''}`;
         case 'context':
             return `\n\n---\n**Next:** If planning changes, use impact({target: "${args?.name || '<name>'}", direction: "upstream"${repoParam}}) to check blast radius. To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;
         case 'impact':

package/dist/mcp/tools.js

@@ -103,11 +103,11 @@ specify the "repo" parameter explicitly.`,
 Returns ranked processes plus a flat process_symbols list. Join processes[].id to process_symbols[].process_id.
 
 WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
-AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
+AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs). With include_content, context() also returns that symbol's source.
 
 Returns results grouped by process (execution flow):
 - processes: ranked execution flows with relevance priority. When a process has an HTTP endpoint, each item includes route and method string aliases plus routes: [{ url, method? }] (same shape as context). When chain_depth > 0, each item also includes chain — layered upstream callers + downstream callees from the process entry symbol (same BFS as context({chain_depth})).
-- process_symbols: search-hit symbols in those flows with file locations and module (functional area). On the single-repo envelope { processes, process_symbols, definitions }: One row per (id, process_id) — the same symbol id may appear under more than one process. Join a process to its rows by process_id; symbol_count is the number of those rows. When the process entry is among those hits, it is marked is_entry_point: true. A repo of "@<group>" returns { group, query, results, per_repo } and does not include process_symbols. results[].symbol_count is the member's post-slice attach count; when service is set, it counts only attaches under that prefix. To get process_symbols for one member, query again with repo "@<group>/<memberPath>" (member path from group.yaml, or results[]._repo).
+- process_symbols: search-hit symbols in those flows with file locations and module (functional area). On the single-repo envelope { processes, process_symbols, definitions }: One row per (id, process_id) — the same symbol id may appear under more than one process. Join a process to its rows by process_id; symbol_count is the number of those rows. When the process entry is among those hits, it is marked is_entry_point: true. With include_content, content appears only on the first row for each symbol id across the whole process_symbols array, not per process; later rows for that id omit it, even under a different process_id. To get content for a row without it, find the earlier row with the same id, or call context({uid: "<id>", include_content: true}). A repo of "@<group>" returns { group, query, results, per_repo } and does not include process_symbols. results[].symbol_count is the member's post-slice attach count; when service is set, it counts only attaches under that prefix. To get process_symbols for one member, query again with repo "@<group>/<memberPath>" (member path from group.yaml, or results[]._repo).
 - definitions: standalone types/interfaces not in any process. Keyword hits on Route URLs (route_fts) are bridged to their handler via HANDLES_ROUTE (handlerSymbolId, routes) when the edge exists; use route_map({route}) for the full HTTP surface.
 
 Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.
@@ -153,7 +153,7 @@ ${HOT_READ_STALENESS_NOTE}`,
                 },
                 include_content: {
                     type: 'boolean',
-                    description: 'Include source text retained for matching symbols (default: false). The response reports contentAvailability; indexes built with content retention "none" explicitly report unavailable content.',
+                    description: 'Include source text retained for matching symbols (default: false). The response reports contentAvailability; indexes built with content retention "none" explicitly report unavailable content. Content is sent once per symbol id, on its first process_symbols row; context({uid: "<id>", include_content: true}) returns it for any row.',
                     default: false,
                 },
                 chain_depth: {

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,
 };