From d48fd4712aef14fc4925e48bf780d3ef01917d23 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Fri, 17 Jul 2026 17:13:05 -0700
Subject: [PATCH 01/15] feat(setup): add Factory Droid (MCP + skills) to
 gitnexus setup

Register 'droid' in the editor-targets abstraction so `gitnexus setup -c droid`
writes the MCP server to ~/.factory/mcp.json and installs skills to
~/.factory/skills/ from the single canonical skills/ source (no per-editor
copies). uninstall.ts is target-driven, so removal is covered automatically.
Adds unit + round-trip coverage.
---
 gitnexus/src/cli/editor-targets.ts            | 15 +++-
 gitnexus/src/cli/index.ts                     |  2 +-
 gitnexus/src/cli/setup.ts                     | 59 +++++++++++++++
 .../setup-uninstall-roundtrip.test.ts         |  2 +-
 gitnexus/test/unit/setup-selection.test.ts    |  2 +-
 gitnexus/test/unit/setup.test.ts              | 73 +++++++++++++++++++
 6 files changed, 149 insertions(+), 4 deletions(-)

diff --git a/gitnexus/src/cli/editor-targets.ts b/gitnexus/src/cli/editor-targets.ts
index a4c511fa0..f46193c76 100644
--- a/gitnexus/src/cli/editor-targets.ts
+++ b/gitnexus/src/cli/editor-targets.ts
@@ -26,7 +26,8 @@ export type EditorId =
   | 'opencode'
   | 'codebuddy'
   | 'qoder'
-  | 'codex';
+  | 'codex'
+  | 'droid';
 
 /** An editor whose MCP config is a JSONC document (server keyed by name). */
 export interface McpJsoncTarget {
@@ -145,6 +146,15 @@ export function getEditorTargets(home: string = os.homedir()): EditorTargets {
       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: CodexMcpTarget = {
@@ -169,6 +179,9 @@ export function getEditorTargets(home: string = os.homedir()): EditorTargets {
     { 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: HookTarget[] = [
diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts
index b92cc5a26..d3a3a48ac 100644
--- a/gitnexus/src/cli/index.ts
+++ b/gitnexus/src/cli/index.ts
@@ -24,7 +24,7 @@ program.name('gitnexus').description('GitNexus local CLI and MCP server').versio
 program
   .command('setup')
   .description(
-    'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex',
+    'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid',
   )
   .option(
     '-c, --coding-agent <agents>',
diff --git a/gitnexus/src/cli/setup.ts b/gitnexus/src/cli/setup.ts
index 3088ec3da..12e617f24 100644
--- a/gitnexus/src/cli/setup.ts
+++ b/gitnexus/src/cli/setup.ts
@@ -95,6 +95,7 @@ const CODING_AGENT_IDS = {
   codebuddy: 'codebuddy',
   qoder: 'qoder',
   codex: 'codex',
+  droid: 'droid',
 } as const satisfies Record<EditorId, EditorId>;
 const SUPPORTED_CODING_AGENTS = Object.values(CODING_AGENT_IDS);
 
@@ -951,6 +952,59 @@ async function installQoderSkills(result: SetupResult): Promise<void> {
   }
 }
 
+/**
+ * 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: SetupResult): Promise<void> {
+  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: any) {
+    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: SetupResult): Promise<void> {
+  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: any) {
+    result.errors.push(`Factory Droid skills: ${err.message}`);
+  }
+}
+
 /**
  * Build a TOML section for Codex MCP config (~/.codex/config.toml).
  */
@@ -1197,6 +1251,7 @@ export const setupCommand = async (options?: { codingAgent?: string[] | string }
   if (selected.has('codebuddy')) await setupCodeBuddy(result);
   if (selected.has('qoder')) 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')) {
@@ -1215,6 +1270,10 @@ export const setupCommand = async (options?: { codingAgent?: string[] | string }
     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) {
diff --git a/gitnexus/test/integration/setup-uninstall-roundtrip.test.ts b/gitnexus/test/integration/setup-uninstall-roundtrip.test.ts
index b72774372..100b1007a 100644
--- a/gitnexus/test/integration/setup-uninstall-roundtrip.test.ts
+++ b/gitnexus/test/integration/setup-uninstall-roundtrip.test.ts
@@ -82,7 +82,7 @@ describe('setup → uninstall round-trip', () => {
     process.env.USERPROFILE = tempHome;
 
     // Mark every editor as "installed" so setup configures all of them.
-    for (const dir of ['.cursor', '.claude', '.codex', '.codebuddy', '.qoder']) {
+    for (const dir of ['.cursor', '.claude', '.codex', '.codebuddy', '.qoder', '.factory']) {
       await fs.mkdir(path.join(tempHome, dir), { recursive: true });
     }
     await fs.mkdir(path.join(tempHome, '.gemini', 'antigravity'), { recursive: true });
diff --git a/gitnexus/test/unit/setup-selection.test.ts b/gitnexus/test/unit/setup-selection.test.ts
index 7978ec2dc..a57689550 100644
--- a/gitnexus/test/unit/setup-selection.test.ts
+++ b/gitnexus/test/unit/setup-selection.test.ts
@@ -101,7 +101,7 @@ describe('setupCommand coding-agent selection', () => {
     expect(process.exitCode).toBe(1);
     expect(stderr).toHaveBeenCalledWith(
       expect.stringContaining(
-        'Valid values: cursor, claude, antigravity, opencode, codebuddy, qoder, codex',
+        'Valid values: cursor, claude, antigravity, opencode, codebuddy, qoder, codex, droid',
       ),
     );
     await expect(
diff --git a/gitnexus/test/unit/setup.test.ts b/gitnexus/test/unit/setup.test.ts
index 448074669..314b771cc 100644
--- a/gitnexus/test/unit/setup.test.ts
+++ b/gitnexus/test/unit/setup.test.ts
@@ -715,6 +715,79 @@ describe('setupQoder', () => {
   });
 });
 
+describe('setupDroid (Factory)', () => {
+  let tempHome: string;
+  let originalHome: string | undefined;
+  let originalUserProfile: string | undefined;
+
+  const configPath = () => path.join(tempHome, '.factory', 'mcp.json');
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+
+    originalHome = process.env.HOME;
+    originalUserProfile = process.env.USERPROFILE;
+    tempHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-droid-setup-'));
+    process.env.HOME = tempHome;
+    process.env.USERPROFILE = tempHome;
+
+    // Only create ~/.factory so other editors skip and don't pollute assertions.
+    await fs.mkdir(path.join(tempHome, '.factory'), { recursive: true });
+
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    process.env.HOME = originalHome;
+    process.env.USERPROFILE = originalUserProfile;
+    await fs.rm(tempHome, { recursive: true, force: true });
+  });
+
+  it('writes the MCP entry to ~/.factory/mcp.json under mcpServers', async () => {
+    const { setupCommand } = await import('../../src/cli/setup.js');
+    await setupCommand();
+
+    const config = JSON.parse(await fs.readFile(configPath(), 'utf-8'));
+    expect(config.mcpServers.gitnexus).toBeDefined();
+  });
+
+  it('preserves existing servers in ~/.factory/mcp.json', async () => {
+    await fs.writeFile(
+      configPath(),
+      JSON.stringify({ mcpServers: { other: { command: 'foo' } } }),
+      'utf-8',
+    );
+
+    const { setupCommand } = await import('../../src/cli/setup.js');
+    await setupCommand();
+
+    const config = JSON.parse(await fs.readFile(configPath(), 'utf-8'));
+    expect(config.mcpServers.other).toEqual({ command: 'foo' });
+    expect(config.mcpServers.gitnexus).toBeDefined();
+  });
+
+  it('skips when ~/.factory directory does not exist', async () => {
+    await fs.rm(path.join(tempHome, '.factory'), { recursive: true, force: true });
+
+    const { setupCommand } = await import('../../src/cli/setup.js');
+    await setupCommand();
+
+    await expect(fs.access(configPath())).rejects.toThrow();
+  });
+
+  it('leaves a corrupt ~/.factory/mcp.json untouched', async () => {
+    const corrupt = '{ this is not valid json !!!';
+    await fs.writeFile(configPath(), corrupt, 'utf-8');
+
+    const { setupCommand } = await import('../../src/cli/setup.js');
+    await setupCommand();
+
+    expect(await fs.readFile(configPath(), 'utf-8')).toBe(corrupt);
+  });
+});
+
 describe('Codex hooks (installClaudeSchemaHooks)', () => {
   let tempHome: string;
   let originalHome: string | undefined;

From 17473b9c3b74e4fa2d1bfe40b772e18b7807236a Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Fri, 17 Jul 2026 17:24:59 -0700
Subject: [PATCH 02/15] feat(plugin): add gitnexus-factory-plugin for droid
 plugin install

---
 .../.factory-plugin/plugin.json               |  11 ++
 .../hooks/gitnexus-hook.js                    | 174 ++++++++++++++++++
 gitnexus-factory-plugin/hooks/hooks.json      |  14 ++
 gitnexus-factory-plugin/mcp.json              |   8 +
 4 files changed, 207 insertions(+)
 create mode 100644 gitnexus-factory-plugin/.factory-plugin/plugin.json
 create mode 100644 gitnexus-factory-plugin/hooks/gitnexus-hook.js
 create mode 100644 gitnexus-factory-plugin/hooks/hooks.json
 create mode 100644 gitnexus-factory-plugin/mcp.json

diff --git a/gitnexus-factory-plugin/.factory-plugin/plugin.json b/gitnexus-factory-plugin/.factory-plugin/plugin.json
new file mode 100644
index 000000000..ace058dad
--- /dev/null
+++ b/gitnexus-factory-plugin/.factory-plugin/plugin.json
@@ -0,0 +1,11 @@
+{
+  "name": "gitnexus",
+  "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
+  "version": "1.6.9",
+  "author": {
+    "name": "GitNexus"
+  },
+  "homepage": "https://github.com/abhigyanpatwari/GitNexus",
+  "repository": "https://github.com/abhigyanpatwari/GitNexus",
+  "keywords": ["code-intelligence", "knowledge-graph", "mcp", "static-analysis"]
+}
diff --git a/gitnexus-factory-plugin/hooks/gitnexus-hook.js b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
new file mode 100644
index 000000000..05aa4368e
--- /dev/null
+++ b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * GitNexus Factory AI (Droid) Plugin Hook
+ *
+ * PostToolUse handler — augments Grep/Glob/Execute searches with graph
+ * context from the GitNexus index. Self-contained: reads the tool payload from
+ * stdin, resolves a search pattern, and appends `gitnexus augment` output via
+ * hookSpecificOutput.additionalContext. No external dependencies (no jq).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Read JSON input from stdin synchronously.
+ */
+function readInput() {
+  try {
+    const data = fs.readFileSync(0, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Check if a directory (or ancestor) has a .gitnexus index.
+ */
+function findGitNexusIndex(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(dir, '.gitnexus'))) {
+      return true;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+/**
+ * Extract search pattern from tool input.
+ */
+function extractPattern(toolName, toolInput) {
+  if (toolName === 'Grep') {
+    return toolInput.pattern || null;
+  }
+
+  if (toolName === 'Glob') {
+    const raw = toolInput.pattern || '';
+    const match = raw.match(/[*\/]([a-zA-Z][a-zA-Z0-9_-]{2,})/);
+    return match ? match[1] : null;
+  }
+
+  if (toolName === 'Execute') {
+    const cmd = toolInput.command || '';
+    if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
+
+    const tokens = cmd.split(/\s+/);
+    let foundCmd = false;
+    let skipNext = false;
+    const flagsWithValues = new Set([
+      '-e',
+      '-f',
+      '-m',
+      '-A',
+      '-B',
+      '-C',
+      '-g',
+      '--glob',
+      '-t',
+      '--type',
+      '--include',
+      '--exclude',
+    ]);
+
+    for (const token of tokens) {
+      if (skipNext) {
+        skipNext = false;
+        continue;
+      }
+      if (!foundCmd) {
+        if (/\brg\b|\bgrep\b/.test(token)) foundCmd = true;
+        continue;
+      }
+      if (token.startsWith('-')) {
+        if (flagsWithValues.has(token)) skipNext = true;
+        continue;
+      }
+      const cleaned = token.replace(/['"]/g, '');
+      return cleaned.length >= 3 ? cleaned : null;
+    }
+    return null;
+  }
+
+  return null;
+}
+
+function main() {
+  try {
+    const input = readInput();
+    const hookEvent = input.hook_event_name || '';
+
+    if (hookEvent !== 'PostToolUse') return;
+
+    const cwd = input.cwd || process.cwd();
+    if (!findGitNexusIndex(cwd)) return;
+
+    const toolName = input.tool_name || '';
+    const toolInput = input.tool_input || {};
+
+    if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Execute') return;
+
+    const pattern = extractPattern(toolName, toolInput);
+    if (!pattern || pattern.length < 3) return;
+
+    // augment CLI writes result to stderr (KuzuDB's native module captures
+    // stdout fd at OS level, making it unusable in subprocess contexts).
+    let result = '';
+
+    const isWin = process.platform === 'win32';
+
+    // Try direct gitnexus binary first (faster if globally installed)
+    try {
+      const child = spawnSync('gitnexus', ['augment', pattern], {
+        encoding: 'utf-8',
+        timeout: 8000,
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: isWin,
+      });
+      if (child.status === 0 && child.stderr && child.stderr.trim()) {
+        result = child.stderr;
+      }
+    } catch {
+      /* not on PATH */
+    }
+
+    // Fallback to npx if direct binary didn't produce output
+    if (!result || !result.trim()) {
+      try {
+        const child = spawnSync('npx', ['-y', 'gitnexus', 'augment', pattern], {
+          encoding: 'utf-8',
+          timeout: 8000,
+          cwd,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          shell: isWin,
+        });
+        if (child.status === 0 && child.stderr && child.stderr.trim()) {
+          result = child.stderr;
+        }
+      } catch {
+        /* graceful failure */
+      }
+    }
+
+    if (result && result.trim()) {
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PostToolUse',
+            additionalContext: result.trim(),
+          },
+        }),
+      );
+    }
+  } catch {
+    // Graceful failure
+  }
+}
+
+main();
diff --git a/gitnexus-factory-plugin/hooks/hooks.json b/gitnexus-factory-plugin/hooks/hooks.json
new file mode 100644
index 000000000..4659a18e5
--- /dev/null
+++ b/gitnexus-factory-plugin/hooks/hooks.json
@@ -0,0 +1,14 @@
+{
+  "PostToolUse": [
+    {
+      "matcher": "Grep|Glob|Execute",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node ${DROID_PLUGIN_ROOT}/hooks/gitnexus-hook.js",
+          "timeout": 10
+        }
+      ]
+    }
+  ]
+}
diff --git a/gitnexus-factory-plugin/mcp.json b/gitnexus-factory-plugin/mcp.json
new file mode 100644
index 000000000..cd02d4285
--- /dev/null
+++ b/gitnexus-factory-plugin/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

From f7ba4f10545026a42c950f0f943c43c60905b859 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Fri, 17 Jul 2026 17:24:59 -0700
Subject: [PATCH 03/15] docs: add Factory Droid to editor support table and
 setup docs

---
 README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/README.md b/README.md
index cb4ac5fac..2642878c4 100644
--- a/README.md
+++ b/README.md
@@ -205,6 +205,7 @@ flowchart TB
 | **OpenCode**             | Yes | Yes    | —                                                                                                                 | MCP + Skills |
 | **CodeBuddy** (Tencent)  | Yes | Yes    | —                                                                                                                 | MCP + Skills |
 | **Qoder** (Alibaba)      | Yes | Yes    | —                                                                                                                 | MCP + Skills |
+| **Factory** (Droid)      | Yes | Yes    | Yes (PostToolUse, [plugin](gitnexus-factory-plugin/))                                                              | **Full**     |
 | **Windsurf**             | Yes | —      | —                                                                                                                 | MCP          |
 
 > **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
@@ -251,6 +252,21 @@ 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) — MCP + skills via `gitnexus setup -c droid`, or add the server manually 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"]
+    }
+  }
+}
+```
+
+`gitnexus setup -c droid` also installs skills to `~/.factory/skills/`. For the PostToolUse search-augment hook, install the bundled [`gitnexus-factory-plugin/`](gitnexus-factory-plugin/) — from a marketplace that includes this repo, run `droid plugin install gitnexus@<marketplace>`, or point Droid at it via `extraKnownMarketplaces` in `.factory/settings.json`. Factory reads [`AGENTS.md` natively](https://docs.factory.ai/), which already carries the GitNexus context block.
+
 **Cursor** (`~/.cursor/mcp.json` — global, works for all projects):
 
 ```json

From 5da8fceab15b811b22c77e9b8f5329fec11ce6bd Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Sun, 19 Jul 2026 15:51:16 -0700
Subject: [PATCH 04/15] fix(factory-plugin): guard augment hook against fan-out
 and DB contention

Reuse the Claude adapter's acquireHookSlot and LadybugDB owner probe
(bundled byte-identical, kept in lockstep by a drift test) instead of
running an unguarded augment. Add direct tests for the hook and manifests.
---
 .../hooks/gitnexus-hook.js                    | 164 ++--
 .../hooks/hook-db-lock-probe.cjs              | 728 ++++++++++++++++++
 gitnexus-factory-plugin/hooks/hook-lock.js    | 119 +++
 .../hooks/win-rm-list-json.ps1                |  76 ++
 gitnexus/test/unit/factory-plugin.test.ts     | 336 ++++++++
 5 files changed, 1370 insertions(+), 53 deletions(-)
 create mode 100644 gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
 create mode 100644 gitnexus-factory-plugin/hooks/hook-lock.js
 create mode 100644 gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
 create mode 100644 gitnexus/test/unit/factory-plugin.test.ts

diff --git a/gitnexus-factory-plugin/hooks/gitnexus-hook.js b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
index 05aa4368e..248680e86 100644
--- a/gitnexus-factory-plugin/hooks/gitnexus-hook.js
+++ b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
@@ -2,15 +2,29 @@
 /**
  * GitNexus Factory AI (Droid) Plugin Hook
  *
- * PostToolUse handler — augments Grep/Glob/Execute searches with graph
- * context from the GitNexus index. Self-contained: reads the tool payload from
- * stdin, resolves a search pattern, and appends `gitnexus augment` output via
- * hookSpecificOutput.additionalContext. No external dependencies (no jq).
+ * PostToolUse — augments Grep/Glob/Execute searches with graph context from
+ * the GitNexus index and returns it via hookSpecificOutput.additionalContext.
+ *
+ * Reuses the same guards as the Claude/Codex adapter (bundled byte-identical,
+ * kept in lockstep by test/unit/factory-plugin.test.ts):
+ *   - acquireHookSlot  — per-repo cap on concurrent augment children so
+ *     parallel sessions can't fan out unbounded `gitnexus augment` spawns
+ *     (#1486).
+ *   - LadybugDB owner probe — skips the CLI augment when a GitNexus MCP/serve
+ *     process already holds the single-writer DB lock, avoiding contention
+ *     (#2396); the in-session MCP tools cover augmentation instead.
+ *
+ * The augment CLI child is NOT wrapped in the coreutils `timeout`
+ * orphan-containment guard the full Claude adapter uses (#2163) — same scope
+ * as the Cursor integration. Add it (resolveUnixGuardTimeout is exported by
+ * the bundled probe) if orphaned augment children become a problem here.
  */
 
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { acquireHookSlot } = require('./hook-lock.js');
+const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
 
 /**
  * Read JSON input from stdin synchronously.
@@ -25,23 +39,42 @@ function readInput() {
 }
 
 /**
- * Check if a directory (or ancestor) has a .gitnexus index.
+ * A `.gitnexus/` that holds `registry.json`/`repos` (and no per-repo index
+ * metadata) is the global registry, not a repo index — never augment against
+ * it. Mirrors the Claude adapter's guard.
  */
-function findGitNexusIndex(startDir) {
+function isGlobalRegistryDir(candidate) {
+  if (
+    fs.existsSync(path.join(candidate, 'gitnexus.json')) ||
+    fs.existsSync(path.join(candidate, 'meta.json'))
+  ) {
+    return false;
+  }
+  return (
+    fs.existsSync(path.join(candidate, 'registry.json')) ||
+    fs.existsSync(path.join(candidate, 'repos'))
+  );
+}
+
+/**
+ * Walk up from startDir looking for a non-registry `.gitnexus/` folder. Returns
+ * the path to `.gitnexus/` or null if not found within 5 levels.
+ */
+function findGitNexusDir(startDir) {
   let dir = startDir || process.cwd();
   for (let i = 0; i < 5; i++) {
-    if (fs.existsSync(path.join(dir, '.gitnexus'))) {
-      return true;
-    }
+    const candidate = path.join(dir, '.gitnexus');
+    if (fs.existsSync(candidate) && !isGlobalRegistryDir(candidate)) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return false;
+  return null;
 }
 
 /**
- * Extract search pattern from tool input.
+ * Extract a search pattern from a Factory tool payload. Factory's shell tool is
+ * `Execute` (Claude's is `Bash`); Grep/Glob match Claude's.
  */
 function extractPattern(toolName, toolInput) {
   if (toolName === 'Grep') {
@@ -98,62 +131,87 @@ function extractPattern(toolName, toolInput) {
   return null;
 }
 
+/**
+ * Run `gitnexus augment` for `pattern` and return its stderr (the augment CLI
+ * writes results to stderr; LadybugDB's native module captures stdout at the OS
+ * fd level, making it unusable in subprocess contexts). Tries a PATH-installed
+ * binary first, then falls back to npx.
+ *
+ * SECURITY: `pattern` is passed after the `--` end-of-options marker and never
+ * through a shell — the Windows npx fallback invokes `npx.cmd` directly rather
+ * than `shell: true`, so a pattern like `-rf` or `$(...)` is inert.
+ */
+function runAugment(pattern, cwd) {
+  const isWin = process.platform === 'win32';
+  const spawnOpts = {
+    encoding: 'utf-8',
+    timeout: 8000,
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  };
+
+  try {
+    const child = spawnSync(
+      isWin ? 'gitnexus.cmd' : 'gitnexus',
+      ['augment', '--', pattern],
+      spawnOpts,
+    );
+    if (!child.error && child.status === 0 && child.stderr && child.stderr.trim()) {
+      return child.stderr;
+    }
+  } catch {
+    /* not on PATH — fall through to npx */
+  }
+
+  try {
+    const child = spawnSync(
+      isWin ? 'npx.cmd' : 'npx',
+      ['-y', 'gitnexus', 'augment', '--', pattern],
+      spawnOpts,
+    );
+    if (!child.error && child.status === 0 && child.stderr && child.stderr.trim()) {
+      return child.stderr;
+    }
+  } catch {
+    /* graceful failure */
+  }
+
+  return '';
+}
+
 function main() {
   try {
     const input = readInput();
-    const hookEvent = input.hook_event_name || '';
-
-    if (hookEvent !== 'PostToolUse') return;
+    if ((input.hook_event_name || '') !== 'PostToolUse') return;
 
     const cwd = input.cwd || process.cwd();
-    if (!findGitNexusIndex(cwd)) return;
+    if (!path.isAbsolute(cwd)) return;
+    const gitNexusDir = findGitNexusDir(cwd);
+    if (!gitNexusDir) return;
 
     const toolName = input.tool_name || '';
-    const toolInput = input.tool_input || {};
-
     if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Execute') return;
 
-    const pattern = extractPattern(toolName, toolInput);
+    const pattern = extractPattern(toolName, input.tool_input || {});
     if (!pattern || pattern.length < 3) return;
 
-    // augment CLI writes result to stderr (KuzuDB's native module captures
-    // stdout fd at OS level, making it unusable in subprocess contexts).
+    const release = acquireHookSlot(gitNexusDir);
+    if (!release) return; // all per-repo augment slots held by concurrent sessions
+
     let result = '';
-
-    const isWin = process.platform === 'win32';
-
-    // Try direct gitnexus binary first (faster if globally installed)
     try {
-      const child = spawnSync('gitnexus', ['augment', pattern], {
-        encoding: 'utf-8',
-        timeout: 8000,
-        cwd,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        shell: isWin,
-      });
-      if (child.status === 0 && child.stderr && child.stderr.trim()) {
-        result = child.stderr;
+      if (hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid)) {
+        // #2396: a GitNexus MCP/serve process owns the single-writer DB, so a
+        // competing CLI augment would only contend on the lock. The session's
+        // MCP tools cover augmentation instead — skip silently.
+        return;
       }
+      result = runAugment(pattern, cwd);
     } catch {
-      /* not on PATH */
-    }
-
-    // Fallback to npx if direct binary didn't produce output
-    if (!result || !result.trim()) {
-      try {
-        const child = spawnSync('npx', ['-y', 'gitnexus', 'augment', pattern], {
-          encoding: 'utf-8',
-          timeout: 8000,
-          cwd,
-          stdio: ['pipe', 'pipe', 'pipe'],
-          shell: isWin,
-        });
-        if (child.status === 0 && child.stderr && child.stderr.trim()) {
-          result = child.stderr;
-        }
-      } catch {
-        /* graceful failure */
-      }
+      /* graceful failure */
+    } finally {
+      release();
     }
 
     if (result && result.trim()) {
@@ -167,7 +225,7 @@ function main() {
       );
     }
   } catch {
-    // Graceful failure
+    /* never let the hook break the tool call */
   }
 }
 
diff --git a/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
new file mode 100644
index 000000000..4376795e2
--- /dev/null
+++ b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
@@ -0,0 +1,728 @@
+/**
+ * Cross-platform best-effort probe: does another process hold dbPath open
+ * with a command line that looks like a GitNexus MCP/serve server?
+ *
+ * Backends (no user-installed Sysinternals):
+ * - Linux: cmdline-first procfs scan under /proc, no lsof at all (#2180). Three
+ *   phases, cheapest first: (0) read /proc/<pid>/comm — a tiny task->comm read
+ *   that never touches the target's mm — and keep only PIDs whose comm is a
+ *   plausible node/gitnexus server; (1) read up to GITNEXUS_HOOK_PROC_CMDLINE_MAX
+ *   bytes of /proc/<pid>/cmdline via openSync+readSync (bounded, so a D-state
+ *   holder stuck on mmap_lock or a giant argv can't wedge the hook) and prefilter
+ *   with isGitNexusServerCommand; (2) only for the 0..N survivors, stat their
+ *   /proc/<pid>/fd/* and compare dev+inode against the target lbug. The lbug
+ *   handle is fd-visible (a @ladybugdb/core property), so this finds every real
+ *   owner without scanning every fd of every process.
+ * - macOS / *BSD / etc.: trusted lsof + ps (absolute paths first).
+ * - Windows: Restart Manager (rstrtmgr) via bundled PowerShell script +
+ *   Win32_Process for command lines; trusted powershell.exe under %SystemRoot%.
+ *
+ * Fail matrix:
+ * - Linux proc scan: owner found -> fail-closed (skip augment); budget exhausted
+ *   (GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS) -> fail-CLOSED (#2180). This is a
+ *   deliberate change from the old "timeout -> fail-open then try lsof" path.
+ *   End-to-end the busy-host outcome is unchanged: the old code's lsof fallback
+ *   ETIMEDOUT'd on the very hosts where the scan ran out of budget and ALSO
+ *   failed closed there — the lsof leg only ever added 1-2s of dead work plus
+ *   the orphan-storm risk it caused (#2163). What changes is that an overloaded
+ *   host now self-throttles immediately (the throttle the incident needed)
+ *   instead of paying for a doomed lsof. Mid-load hosts that used to fall
+ *   through to a successful lsof now answer from the scan directly (faster) or,
+ *   if even the scan can't finish in budget, fail closed (self-throttle) — a
+ *   bounded, documented tradeoff, never an orphan.
+ * - macOS / other Unix: fail-open on most errors; fail-closed only on lsof
+ *   ETIMEDOUT, matching the hook contract.
+ * - Windows: fail-closed only on PowerShell ETIMEDOUT.
+ *
+ * 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` exit-propagation 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.
+ * - resolveUnixGuardTimeout is exported so the hook adapters can wrap the
+ *   `gitnexus augment` CLI child — the longest-lived hook subprocess (7s
+ *   local / 12s npx inner budgets) — in the same guard; see runGitNexusCli
+ *   in the adapters (#2163 follow-up).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function isGitNexusServerCommand(command) {
+  const hasServerMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(command);
+  const hasGitNexus =
+    /(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(command) ||
+    /node_modules[/\\]gitnexus[/\\]/.test(command);
+  return hasServerMode && hasGitNexus;
+}
+
+// GITNEXUS_DEBUG-gated stderr diagnostics. Reuses the exact gating predicate the
+// Windows ps1-load warning already uses (===' 1' / ==='true') so there is one
+// debug convention in this file, and writes via process.stderr.write (NOT a
+// spawn) so it never perturbs the windowsHide spawn-count invariant.
+function debugLog(msg) {
+  if (process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true') {
+    process.stderr.write(`[GitNexus hook] ${msg}\n`);
+  }
+}
+
+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);
+  }
+  const candidates =
+    tool === 'lsof'
+      ? ['/usr/bin/lsof', '/usr/sbin/lsof', '/sbin/lsof', tool]
+      : ['/bin/ps', '/usr/bin/ps', tool];
+  for (const candidate of candidates) {
+    if (candidate === tool) return tool;
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      /* ignore */
+    }
+  }
+  return tool;
+}
+
+function hasMissingHookBinaryOverride(tool) {
+  const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH';
+  const fromEnv = process.env[envKey];
+  if (!fromEnv || !String(fromEnv).trim()) return false;
+  try {
+    return !fs.existsSync(String(fromEnv).trim());
+  } catch {
+    return true;
+  }
+}
+
+// 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). Unix-only by contract: the probe's win32 dispatch returns before
+ * reaching it, and the exported callers (the adapters' runGitNexusCli,
+ * #2163 follow-up) must check the platform first — the self-test below
+ * spawns /bin/sh. The memoized result is module-wide, so probe and adapter
+ * share one lazy self-test per hook process.
+ *
+ * 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` exit-propagation self-test to
+ * be adopted. On any failure (non-existent path, directory, non-executable
+ * file, wrapper without `-k` support, always-exit-0 stub, …) 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 'exit 42'` exits 42 — i.e. it must RUN
+ * the wrapped command AND PROPAGATE its exit status. This rejects two
+ * failure shapes: wrappers without the coreutils `-k` flag — busybox <1.34,
+ * toybox, broken symlinks — which would exit with a usage error without
+ * ever running lsof, silently converting the lsof-ETIMEDOUT fail-closed
+ * contract into fail-open (#1492 regression); and always-exit-0 stubs
+ * (/bin/true shapes), which would otherwise be adopted and "succeed" every
+ * wrapped spawn instantly without running it — a constant no-owner probe
+ * answer and, worse, a silently dead augment (status 0, empty stderr passes
+ * the adapters' success check with no context; #2163 follow-up review).
+ * 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 for everything THIS file spawns (lsof/ps are the guard's direct
+ * children) and for the adapters' direct-exec arm. The adapters' npx arm
+ * additionally relies on coreutils' process-GROUP signalling for its
+ * `-s KILL` grandchild reaping; busybox signals only its direct child, and
+ * this self-test deliberately does not probe that capability — see the
+ * adapter docblocks for the residual-gap statement.
+ */
+function passesGuardSelfTest(guard) {
+  try {
+    const selfTest = spawnSync(guard, ['-k', '1', '1', '/bin/sh', '-c', 'exit 42'], {
+      encoding: 'utf-8',
+      timeout: 3000,
+      stdio: ['ignore', 'ignore', 'ignore'],
+      windowsHide: true,
+    });
+    return !selfTest.error && selfTest.status === 42;
+  } 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())) {
+    return String(fromEnv).trim();
+  }
+  const root = process.env.SystemRoot || 'C:\\Windows';
+  const ps = path.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  if (fs.existsSync(ps)) return ps;
+  const psWow = path.join(root, 'SysWOW64', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  if (fs.existsSync(psWow)) return psWow;
+  return 'powershell.exe';
+}
+
+// Sentinel:
+//   undefined = not loaded yet (try the read)
+//   string    = encoded PowerShell command (successful load)
+//   null      = load attempted and failed (do not retry; warning already emitted)
+let windowsRmListPsEncodedCommandCache;
+let windowsRmListPsLoadFailureWarned = false;
+function getWindowsRmListEncodedCommand() {
+  if (windowsRmListPsEncodedCommandCache !== undefined) {
+    return windowsRmListPsEncodedCommandCache;
+  }
+  try {
+    const ps1Path = path.join(__dirname, 'win-rm-list-json.ps1');
+    const src = fs
+      .readFileSync(ps1Path, 'utf8')
+      .replace(/^\uFEFF/, '')
+      .replace(/\r\n/g, '\n');
+    windowsRmListPsEncodedCommandCache = Buffer.from(src, 'utf16le').toString('base64');
+  } catch (err) {
+    windowsRmListPsEncodedCommandCache = null;
+    if (
+      !windowsRmListPsLoadFailureWarned &&
+      (process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true')
+    ) {
+      windowsRmListPsLoadFailureWarned = true;
+      const msg = err && err.message ? String(err.message).slice(0, 200) : 'unknown';
+      process.stderr.write(`[GitNexus hook] win-rm-list-json.ps1 load failed: ${msg}\n`);
+    }
+  }
+  return windowsRmListPsEncodedCommandCache;
+}
+
+function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) {
+  const encoded = getWindowsRmListEncodedCommand();
+  if (!encoded) return false;
+  const psExe = resolveWindowsPowerShellPath();
+  const r = spawnSync(
+    psExe,
+    [
+      '-NoProfile',
+      '-NonInteractive',
+      '-ExecutionPolicy',
+      'Bypass',
+      '-STA',
+      '-EncodedCommand',
+      encoded,
+    ],
+    {
+      encoding: 'utf-8',
+      timeout: 6000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+      env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs },
+    },
+  );
+  // ETIMEDOUT means the PowerShell probe didn't return in time; treat as 'unresponsive process holds DB' → fail-closed (skip augment).
+  if (r.error) return r.error.code === 'ETIMEDOUT';
+  if (r.status !== 0) return false;
+  let rows;
+  try {
+    rows = JSON.parse(String(r.stdout || '').trim() || '[]');
+  } catch {
+    return false;
+  }
+  if (!Array.isArray(rows)) return false;
+  for (const row of rows) {
+    const procId = Number(row.pid);
+    const cmd = String(row.cmd || '');
+    if (!Number.isFinite(procId) || procId === myPid) continue;
+    if (isGitNexusServerCommand(cmd)) return true;
+  }
+  return false;
+}
+
+// The procfs root every Linux scan path reads from. Production is always /proc;
+// GITNEXUS_HOOK_PROC_ROOT only exists so unit tests can inject a fixture tree
+// (comm + cmdline + fd symlinks) and assert the three-phase logic without
+// scanning the real, ~hundreds-of-process /proc of the test host.
+//
+// Test-only gate (F4): the override is honored ONLY under a test runner —
+// vitest injects VITEST="true" and NODE_ENV="test" into every worker (verified;
+// a production hook is `node <file>.cjs` with neither set). Without the gate, a
+// production env that accidentally leaked GITNEXUS_HOOK_PROC_ROOT (pointing at an
+// empty/bad tree) would make readdirSync find no pids -> 'not-owned' -> Linux
+// owner detection silently OFF (fail-OPEN: augment races the real server for the
+// lbug, the #1492 class). Gating to the test signal makes that leak inert in
+// production (always /proc) while the fake-procfs unit tests, which run under
+// vitest, still inject freely. Unset env (or non-test context) => /proc, so the
+// production path is byte-for-byte the historical behavior.
+function isTestContext() {
+  return (
+    process.env.VITEST === 'true' || process.env.VITEST === '1' || process.env.NODE_ENV === 'test'
+  );
+}
+function getProcRoot() {
+  if (!isTestContext()) return '/proc';
+  const raw = process.env.GITNEXUS_HOOK_PROC_ROOT;
+  return raw && String(raw).trim() ? String(raw) : '/proc';
+}
+
+// Max bytes read from /proc/<pid>/cmdline in Phase 1. Bounded by default so a
+// D-state holder wedged on mmap_lock, or a process with a pathological multi-MB
+// argv, can't stall the hook. 16 KiB comfortably clears a realistic
+// `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.
+const PROC_CMDLINE_FLOOR = 4096;
+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;
+  return 16384;
+}
+
+// Phase 0 comm prefilter. /proc/<pid>/comm is the kernel task->comm string,
+// capped at 16 bytes INCLUDING the trailing NUL — i.e. at most 15 visible
+// chars, truncated by the kernel with no marker. So a process whose real name
+// is longer than 15 chars shows a 15-char prefix here. The match below is
+// therefore truncation-safe in BOTH directions (a whitelist name that is a
+// prefix of comm, or comm that is a prefix of a whitelist name, both count) to
+// guarantee we never drop a real owner at this cheap stage — Phase 2's dev+ino
+// fd check is the real authority; Phase 0/1 only exist to skip the overwhelming
+// majority (kernel threads, shells, editors) cheaply.
+//
+// The whitelist is calibrated against what a real `gitnexus mcp`/`serve` server
+// actually reports for comm. Observed on production hosts: the server renames
+// its main thread, so comm reads `MainThread` (via @ladybugdb/core's
+// worker_threads setup), NOT `node` — omitting it would blind the probe to
+// every real server (#1492-class owner miss). We also keep the plausible
+// launcher/runtime basenames in case a future build does not rename the thread.
+// Conservative by design: over-collecting a few extra candidates only costs a
+// bounded number of Phase 1 cmdline reads.
+const COMM_CANDIDATES = ['node', 'gitnexus', 'bun', 'deno', 'npm', 'npx', 'MainThread'];
+function commLooksLikeServer(comm) {
+  const c = comm.trim();
+  if (!c) return false;
+  for (const name of COMM_CANDIDATES) {
+    if (name === c || name.startsWith(c) || c.startsWith(name)) return true;
+  }
+  return false;
+}
+
+function readProcComm(procRoot, pidStr) {
+  try {
+    return fs
+      .readFileSync(path.join(procRoot, pidStr, 'comm'), 'utf8')
+      .replace(/\0+/g, '')
+      .trim();
+  } catch {
+    return '';
+  }
+}
+
+// Timeout sentinel for readLinuxCmdline (F3). MUST be distinct from the
+// "unreadable/empty" return value (''): '' flows through isGitNexusServerCommand
+// as a NON-candidate (both regexes are false on ''), so the Phase 1 caller
+// `continue`s past it — correct for a raced/openSync-failed pid, but a FAIL-OPEN
+// bug if it ever meant "I ran out of budget mid-read" (a real owner whose
+// escalation timed out would be silently dropped, racing the lbug -> #1492). A
+// unique Symbol can never collide with any cmdline string, so the caller can
+// branch on it explicitly and map a mid-read timeout to the tri-state 'timeout'
+// (fail-CLOSED) instead of swallowing it as a non-candidate.
+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.
+//
+// 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.
+//
+// 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
+// budget check, weakening the timeout contract. `outOfBudget` (the scan's shared
+// deadline callback) is checked once per escalation iteration; on expiry we
+// return CMDLINE_TIMEOUT (NOT '') so the caller can fail-closed honestly rather
+// than mistake the partial read for a non-candidate. Reads that simply can't
+// open / error out still return '' (genuinely "not a readable candidate").
+function readLinuxCmdline(procRoot, pidStr, cap, outOfBudget) {
+  const file = path.join(procRoot, pidStr, 'cmdline');
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch {
+    return '';
+  }
+  try {
+    const HARD_CEIL = 262144; // 256 KiB absolute ceiling for the escalation path
+    let collected = Buffer.alloc(0);
+    let offset = 0;
+    let chunkCap = cap;
+    for (;;) {
+      // allocUnsafe is safe here: readSync fills exactly [0, bytes), only
+      // buf.subarray(0, bytes) is consumed, and Buffer.concat deep-copies that
+      // slice into `collected`, so the uninitialized tail never reaches decode.
+      const buf = Buffer.allocUnsafe(chunkCap);
+      const bytes = fs.readSync(fd, buf, 0, chunkCap, offset);
+      if (bytes <= 0) break;
+      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
+      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
+      // (never '') so the caller fails closed instead of treating us as a
+      // non-candidate. The sole caller (linuxProcScanFindGitNexusServer) always
+      // passes outOfBudget, so no presence guard is needed.
+      if (outOfBudget()) return CMDLINE_TIMEOUT;
+      chunkCap = cap; // keep reading more in cap-sized chunks
+    }
+    return collected.toString('utf8').replace(/\0+/g, ' ').trim();
+  } catch {
+    return '';
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function resolveLinuxProcBudgetMs() {
+  const raw = process.env.GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS;
+  // Gate on the STRING's emptiness, NOT the parsed number's truthiness — the
+  // old `Number(raw && trim()) ? ... : 1200` form treated "0" as falsy and
+  // silently fell back to 1200 (#2180). Use Number() (not parseInt) so "16e3"
+  // reads as 16000, not 16 (parseInt stops at 'e'). The `&& String(raw).trim()`
+  // guard is load-bearing: without it a set-but-empty/whitespace value would be
+  // `Number("")===0` => budget 0 => immediate fail-CLOSED timeout (augment
+  // permanently skipped). With it, ''/whitespace => NaN => 1200 default, while a
+  // finite "0" still parses to an explicit, deterministic "no budget" =>
+  // immediate timeout. Non-numeric / unset => default 1200.
+  const n = raw != null && String(raw).trim() ? Number(String(raw).trim()) : NaN;
+  if (!Number.isFinite(n)) return 1200;
+  return n; // may be <= 0, meaning "out of budget on the first check"
+}
+
+// Returns one of: 'owned' (a non-self process with a GitNexus-server cmdline
+// holds the target lbug fd), 'not-owned' (scan completed, no such owner), or
+// 'timeout' (the per-scan budget was exhausted before a verdict). The name is
+// pinned by a source-contract test; only the return TYPE changed (#2180:
+// boolean -> tri-state, so the dispatcher can fail-closed on 'timeout').
+function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
+  const budget = resolveLinuxProcBudgetMs();
+  // A non-positive budget is an explicit, deterministic "no time to scan" =>
+  // immediate timeout (the #2180 test vector, and the only correct reading of
+  // the fixed parse: "0" must NOT mean 1200). Returning before any procfs read
+  // keeps it instantaneous regardless of host load.
+  if (budget <= 0) return 'timeout';
+  const procRoot = getProcRoot();
+  const cmdlineCap = getCmdlineMaxBytes();
+  const start = Date.now();
+  const outOfBudget = () => Date.now() - start > budget;
+
+  let targetStat;
+  try {
+    targetStat = fs.statSync(dbPathAbs);
+  } catch {
+    // Caller already existsSync'd the path; a stat failure here is a transient
+    // race, treat as no owner (historical semantics).
+    return 'not-owned';
+  }
+
+  let procEntries;
+  try {
+    procEntries = fs.readdirSync(procRoot, { withFileTypes: true });
+  } catch {
+    return 'not-owned';
+  }
+
+  // Phase 0 + Phase 1: collect the few PIDs whose comm AND cmdline look like a
+  // GitNexus server, without touching any fd yet.
+  const candidates = [];
+  for (const ent of procEntries) {
+    if (outOfBudget()) return 'timeout';
+    if (!ent.isDirectory() || !/^\d+$/.test(ent.name)) continue;
+    const pid = Number.parseInt(ent.name, 10);
+    if (!Number.isFinite(pid) || pid === myPid) continue;
+
+    // Phase 0: cheap comm prefilter.
+    const comm = readProcComm(procRoot, ent.name);
+    if (!comm) continue; // unreadable comm (kernel thread, raced exit) -> skip
+    if (!commLooksLikeServer(comm)) continue;
+
+    // Phase 1: bounded cmdline read + isGitNexusServerCommand prefilter.
+    if (outOfBudget()) return 'timeout';
+    const cmdline = readLinuxCmdline(procRoot, ent.name, cmdlineCap, outOfBudget);
+    // F3: a mid-read budget timeout returns the CMDLINE_TIMEOUT sentinel (a
+    // Symbol, never a string). Fail CLOSED on it rather than letting it fall
+    // through isGitNexusServerCommand as a non-candidate — a real owner whose
+    // escalation timed out must not be silently dropped (would fail-OPEN).
+    if (cmdline === CMDLINE_TIMEOUT) return 'timeout';
+    if (!isGitNexusServerCommand(cmdline)) continue;
+    candidates.push(ent.name);
+  }
+
+  // Phase 2: only now stat the fds of the (typically 0-2) survivors.
+  for (const pidStr of candidates) {
+    if (outOfBudget()) return 'timeout';
+    const fdDir = path.join(procRoot, pidStr, 'fd');
+    let fds;
+    try {
+      fds = fs.readdirSync(fdDir);
+    } catch (err) {
+      // F1: the old code returned 'owned' for EVERY non-ENOENT error. That was
+      // a correctness bug: /proc/<pid>/fd is owner-only (mode 0500), so a
+      // cross-user/root `gitnexus mcp` serving a DIFFERENT repo passes Phase 0+1
+      // (its cmdline matches) and then EACCES'es here — yet its dev+ino was
+      // NEVER compared against THIS lbug. Claiming 'owned' lets it permanently,
+      // silently suppress augment for a repo it does not actually lock. We now
+      // distinguish the failure shapes (all still fail-closed where we can't
+      // prove non-ownership, but 'timeout' is the HONEST verdict for
+      // "inconclusive", not the false-positive 'owned'):
+      const code = err && err.code;
+      if (code === 'ENOENT') {
+        // Process raced away between the candidate scan and now -> genuinely no
+        // longer an owner. Move on.
+        continue;
+      }
+      if (code === 'EACCES' || code === 'EPERM') {
+        // Permission-denied fd dir: cannot read fds, so ownership is
+        // UNVERIFIABLE. Fail closed honestly via 'timeout' (the dispatcher maps
+        // timeout -> true, same protective skip as before) WITHOUT lying that we
+        // confirmed ownership. Do NOT degrade to not-owned/fail-open: if this
+        // really is the owner, fail-open re-opens the #1492 lbug race; augment
+        // is optional context, so a conservative skip costs little.
+        debugLog(
+          `fd dir unreadable for candidate pid ${pidStr} (${code}); ownership ` +
+            `unverifiable, probe inconclusive -> fail-closed (timeout)`,
+        );
+        return 'timeout';
+      }
+      if (code === 'EIO' || code === 'ESTALE') {
+        // Genuine transient I/O against this candidate's fd dir — not evidence
+        // it does NOT hold the lbug. Treat as inconclusive and fail closed
+        // (timeout) rather than continue, so a real owner mid-I/O-blip is not
+        // dropped (would fail-open).
+        debugLog(
+          `fd dir transient I/O error for candidate pid ${pidStr} (${code}); ` +
+            `probe inconclusive -> fail-closed (timeout)`,
+        );
+        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.
+      debugLog(
+        `fd dir not a readable directory for candidate pid ${pidStr} ` +
+          `(${code || 'unknown'}); treating candidate as non-owner -> continue`,
+      );
+      continue;
+    }
+    for (const fd of fds) {
+      if (outOfBudget()) return 'timeout';
+      try {
+        const st = fs.statSync(path.join(fdDir, fd));
+        if (st.dev === targetStat.dev && st.ino === targetStat.ino) {
+          return 'owned';
+        }
+      } catch {
+        /* fd raced closed; ignore */
+      }
+    }
+  }
+
+  return 'not-owned';
+}
+
+function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
+  const guard = resolveUnixGuardTimeout();
+  // An explicit missing override models ENOENT and must fail open instead of
+  // falling through to a host binary with different process-table visibility.
+  if (hasMissingHookBinaryOverride('lsof')) return false;
+  const lsofPath = resolveHookBinary('lsof');
+  // 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 psMissing = hasMissingHookBinaryOverride('ps');
+  const psPath = resolveHookBinary('ps');
+  for (const pid of pids) {
+    if (Number(pid) === myPid) continue;
+    // Missing ps means we cannot verify that this pid is a GitNexus server.
+    if (psMissing) continue;
+    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'],
+      windowsHide: true,
+    });
+    if (ps.error) {
+      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;
+}
+
+/**
+ * @param {string} dbPath Absolute or relative path to the DB file (e.g. .../lbug).
+ * @param {number} myPid Current process PID (hook runner), excluded from matches.
+ */
+function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) {
+  if (!fs.existsSync(dbPath)) return false;
+  const dbPathAbs = path.resolve(dbPath);
+
+  if (process.platform === 'win32') {
+    return hasGitNexusServerOwnerWindows(dbPathAbs, myPid);
+  }
+
+  if (process.platform === 'linux') {
+    // #2180: cmdline-first procfs scan, no lsof. 'timeout' fails CLOSED
+    // (overloaded host self-throttles — the throttle the orphan-storm incident
+    // needed; the old lsof fallback ETIMEDOUT'd and failed closed on these same
+    // hosts anyway, only slower and with the orphan risk). 'not-owned' is the
+    // only false. See the fail matrix in the file header.
+    const verdict = linuxProcScanFindGitNexusServer(dbPathAbs, myPid);
+    return verdict !== 'not-owned';
+  }
+
+  return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
+}
+
+module.exports = {
+  hasGitNexusDbLockedByGitNexusServer,
+  // Exported for white-box unit tests that must assert the tri-state verdict
+  // ('owned' | 'not-owned' | 'timeout') directly — the dispatcher collapses
+  // timeout and owned to the same boolean true, so the boolean API alone cannot
+  // distinguish the F1 EACCES->timeout fix from the old EACCES->owned bug. The
+  // Probe interface already declares this optional. Linux-only by contract; the
+  // 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).
+  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
+  // guard that keeps a set-but-empty budget on the 1200 default instead of an
+  // immediate fail-closed timeout. Tested directly because the values are
+  // otherwise only observable indirectly through scan timing/escalation.
+  getCmdlineMaxBytes,
+  resolveLinuxProcBudgetMs,
+};
diff --git a/gitnexus-factory-plugin/hooks/hook-lock.js b/gitnexus-factory-plugin/hooks/hook-lock.js
new file mode 100644
index 000000000..759856384
--- /dev/null
+++ b/gitnexus-factory-plugin/hooks/hook-lock.js
@@ -0,0 +1,119 @@
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_LOCK_SUBDIR = '.hook-locks';
+const HOOK_LOCK_MAX_INFLIGHT = 3;
+const HOOK_LOCK_STALE_MS = 30000;
+
+function acquireHookSlot(gitNexusDir) {
+  const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
+  try {
+    fs.mkdirSync(lockDir, { recursive: true });
+  } catch {
+    // Cannot create lock dir (read-only fs, cross-user perm denial, out of
+    // inodes, etc.) — fail closed by returning null. Caller skips augment.
+    // Fail-open here would let N concurrent hooks all proceed unguarded and
+    // reintroduce the #1486 fan-out the guard exists to prevent.
+    return null;
+  }
+
+  const myPidStr = String(process.pid);
+
+  for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
+    const slotPath = path.join(lockDir, `slot-${slot}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
+        let released = false;
+        const release = () => {
+          if (released) return;
+          released = true;
+          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.
+            const content = fs.readFileSync(slotPath, 'utf-8').trim();
+            if (content === myPidStr) fs.unlinkSync(slotPath);
+          } catch {
+            /* already removed or unreadable */
+          }
+        };
+        process.on('exit', release);
+        return release;
+      } catch {
+        // Slot exists. Decide whether to take it over.
+        // Open once and inspect mtime + content via the same fd so there's
+        // no TOCTOU between the metadata check and the content read
+        // (codeql js/file-system-race).
+        let fd;
+        try {
+          fd = fs.openSync(slotPath, 'r');
+        } catch {
+          continue; // Vanished between EEXIST and open — retry this slot.
+        }
+        let isLive = false;
+        let mtimeMs = Date.now();
+        try {
+          mtimeMs = fs.fstatSync(fd).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();
+          if (ownerStr === '') {
+            // Owner created the file but hasn't written its PID yet. The
+            // wx open+write window is microseconds; give it the benefit
+            // of the doubt and treat as live.
+            isLive = true;
+          } else {
+            const owner = Number.parseInt(ownerStr, 10);
+            if (Number.isFinite(owner) && owner > 0) {
+              try {
+                process.kill(owner, 0);
+                isLive = true;
+              } catch (e) {
+                // ESRCH = process gone → treat as dead. EPERM = process exists
+                // but owned by another user (cross-user lock dir) → still alive,
+                // keep the slot. Anything else: be conservative, assume alive.
+                if (e && e.code === 'ESRCH') {
+                  isLive = false;
+                } else {
+                  isLive = true;
+                }
+              }
+            }
+          }
+        } catch {
+          /* unreadable — treat as dead */
+        } finally {
+          try {
+            fs.closeSync(fd);
+          } catch {
+            /* already closed */
+          }
+        }
+        // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
+        // a slow-but-alive hook is never wrongly evicted. For older slots,
+        // age is the final arbiter as a defense against PID reuse on long-
+        // abandoned slots. 30s >> the 7s augment timeout, so a healthy run
+        // never crosses this threshold.
+        if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
+          isLive = false;
+        }
+        if (isLive) break; // Try the next slot.
+        try {
+          fs.unlinkSync(slotPath);
+        } catch {
+          /* another hook beat us to it — retry will hit EEXIST */
+        }
+        // Loop and retry this slot.
+      }
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  HOOK_LOCK_SUBDIR,
+  HOOK_LOCK_MAX_INFLIGHT,
+  HOOK_LOCK_STALE_MS,
+  acquireHookSlot,
+};
diff --git a/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
new file mode 100644
index 000000000..5c1564e30
--- /dev/null
+++ b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
@@ -0,0 +1,76 @@
+$ErrorActionPreference = 'Stop'
+$target = $env:GITNEXUS_HOOK_RM_TARGET
+if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
+$target = (Resolve-Path -LiteralPath $target).ProviderPath
+
+if (-not ([Management.Automation.PSTypeName]'GitNexusHookRm.Native').Type) {
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+namespace GitNexusHookRm {
+  public static class Native {
+    public const int ErrorMoreData = 234;
+    [StructLayout(LayoutKind.Sequential, Pack = 4)]
+    public struct RM_UNIQUE_PROCESS {
+      public int dwProcessId;
+      public long ProcessStartTime;
+    }
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    public struct RM_PROCESS_INFO {
+      public RM_UNIQUE_PROCESS Process;
+      [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
+      public string strAppName;
+      [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)]
+      public string strServiceShortName;
+      public uint ApplicationType;
+      public uint AppStatus;
+      public uint TSSessionId;
+      public uint bRestartable;
+    }
+    [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
+    public static extern int RmStartSession(out uint pSessionHandle, uint dwSessionFlags, string strSessionKey);
+    [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
+    public static extern int RmRegisterResources(uint pSessionHandle, uint nFiles, string[] rgsFileNames, uint nApplications, IntPtr rgApplications, uint nServices, string[] rgsServiceNames);
+    [DllImport("rstrtmgr.dll")]
+    public static extern int RmGetList(uint dwSessionHandle, out uint pnProcInfoNeeded, ref uint pnProcInfo, [In, Out] RM_PROCESS_INFO[] rgAffectedApps, ref uint lpdwRebootReasons);
+    [DllImport("rstrtmgr.dll")]
+    public static extern int RmEndSession(uint pSessionHandle);
+  }
+}
+'@
+}
+
+$h = [uint32]0
+$key = [guid]::NewGuid().ToString('N')
+$rmErr = [GitNexusHookRm.Native]::RmStartSession([ref]$h, 0, $key)
+if ($rmErr -ne 0) { Write-Output '[]'; exit 0 }
+$files = @($target)
+$err = [GitNexusHookRm.Native]::RmRegisterResources($h, 1, $files, 0, [IntPtr]::Zero, 0, $null)
+if ($err -ne 0) {
+  [void][GitNexusHookRm.Native]::RmEndSession($h)
+  Write-Output '[]'
+  exit 0
+}
+$need = [uint32]0
+$n = [uint32]0
+$reboot = [uint32]0
+$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $null, [ref]$reboot)
+if ($err -ne [GitNexusHookRm.Native]::ErrorMoreData) {
+  [void][GitNexusHookRm.Native]::RmEndSession($h)
+  Write-Output '[]'
+  exit 0
+}
+$n = $need
+$buf = New-Object GitNexusHookRm.Native+RM_PROCESS_INFO[] ([int]$n)
+$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $buf, [ref]$reboot)
+[void][GitNexusHookRm.Native]::RmEndSession($h)
+if ($err -ne 0) { Write-Output '[]'; exit 0 }
+
+$out = @()
+for ($i = 0; $i -lt [int]$n; $i++) {
+  $procId = $buf[$i].Process.dwProcessId
+  $p = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$procId" -ErrorAction SilentlyContinue
+  $cmd = if ($p) { $p.CommandLine } else { '' }
+  $out += [PSCustomObject]@{ pid = [int]$procId; cmd = $cmd }
+}
+ConvertTo-Json -InputObject @($out) -Compress
diff --git a/gitnexus/test/unit/factory-plugin.test.ts b/gitnexus/test/unit/factory-plugin.test.ts
new file mode 100644
index 000000000..4d6f836e3
--- /dev/null
+++ b/gitnexus/test/unit/factory-plugin.test.ts
@@ -0,0 +1,336 @@
+/**
+ * Tests: GitNexus Factory AI (Droid) plugin
+ *
+ * Covers the standalone `gitnexus-factory-plugin/` used by `droid plugin
+ * install`:
+ * - manifest + hook wiring (plugin.json / mcp.json / hooks.json)
+ * - the PostToolUse search-augment hook's guard reuse and early-exit behavior
+ * - a drift guard proving the bundled guard modules are byte-identical to the
+ *   canonical Claude-adapter copies (so a fix to one can't silently skip the
+ *   other)
+ *
+ * The augment fan-out guard (acquireHookSlot) and the LadybugDB owner probe are
+ * the exact modules the Claude/Codex adapter ships; their internals are covered
+ * by hooks.test.ts and hook-db-lock-probe.test.ts. Here we assert the Factory
+ * hook WIRES them and behaves correctly on the Factory-specific paths.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import {
+  runHook,
+  parseHookOutput,
+  createHookToolDir,
+  hookEnv,
+} from '../utils/hook-test-helpers.js';
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const PLUGIN_DIR = path.join(REPO_ROOT, 'gitnexus-factory-plugin');
+const HOOK = path.join(PLUGIN_DIR, 'hooks', 'gitnexus-hook.js');
+const HOOKS_JSON = path.join(PLUGIN_DIR, 'hooks', 'hooks.json');
+const PLUGIN_JSON = path.join(PLUGIN_DIR, '.factory-plugin', 'plugin.json');
+const MCP_JSON = path.join(PLUGIN_DIR, 'mcp.json');
+const CLAUDE_HOOKS = path.join(REPO_ROOT, 'gitnexus-claude-plugin', 'hooks');
+
+// Guard modules bundled into the Factory plugin, kept byte-identical to the
+// canonical Claude-adapter copies.
+const BUNDLED_GUARDS = ['hook-lock.js', 'hook-db-lock-probe.cjs', 'win-rm-list-json.ps1'] as const;
+
+// ─── Manifest / file presence ───────────────────────────────────────
+
+describe('Factory plugin files', () => {
+  it('ships the hook, its guards, and both manifests', () => {
+    for (const p of [
+      HOOK,
+      HOOKS_JSON,
+      PLUGIN_JSON,
+      MCP_JSON,
+      ...BUNDLED_GUARDS.map((f) => path.join(PLUGIN_DIR, 'hooks', f)),
+    ]) {
+      expect(fs.existsSync(p), `${p} should exist`).toBe(true);
+    }
+  });
+
+  it('.factory-plugin holds only plugin.json (Factory manifest contract)', () => {
+    expect(fs.readdirSync(path.join(PLUGIN_DIR, '.factory-plugin'))).toEqual(['plugin.json']);
+  });
+});
+
+// ─── Drift guard: bundled guards === canonical Claude copies ─────────
+
+describe('Factory plugin bundled guards stay in lockstep with the Claude adapter', () => {
+  for (const f of BUNDLED_GUARDS) {
+    it(`${f} is byte-identical to the canonical copy`, () => {
+      const bundled = fs.readFileSync(path.join(PLUGIN_DIR, 'hooks', f));
+      const canonical = fs.readFileSync(path.join(CLAUDE_HOOKS, f));
+      expect(bundled.equals(canonical)).toBe(true);
+    });
+  }
+});
+
+// ─── plugin.json ────────────────────────────────────────────────────
+
+describe('Factory plugin.json', () => {
+  const manifest = JSON.parse(fs.readFileSync(PLUGIN_JSON, 'utf-8'));
+
+  it('is named gitnexus', () => {
+    expect(manifest.name).toBe('gitnexus');
+  });
+
+  it('version matches gitnexus/package.json (single source of truth)', () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, 'gitnexus', 'package.json'), 'utf-8'),
+    );
+    expect(manifest.version).toBe(pkg.version);
+  });
+});
+
+// ─── mcp.json ───────────────────────────────────────────────────────
+
+describe('Factory mcp.json', () => {
+  const mcp = JSON.parse(fs.readFileSync(MCP_JSON, 'utf-8'));
+
+  it('registers the gitnexus MCP server under mcpServers', () => {
+    expect(mcp.mcpServers?.gitnexus?.command).toBe('npx');
+    expect(mcp.mcpServers.gitnexus.args).toContain('mcp');
+  });
+});
+
+// ─── hooks.json wiring ──────────────────────────────────────────────
+
+describe('Factory hooks.json wiring', () => {
+  const manifest = JSON.parse(fs.readFileSync(HOOKS_JSON, 'utf-8'));
+  const entry = manifest.PostToolUse[0];
+
+  it('registers a PostToolUse hook', () => {
+    expect(Array.isArray(manifest.PostToolUse)).toBe(true);
+  });
+
+  it('matches Factory search tools (Grep, Glob, Execute — not Bash)', () => {
+    expect(entry.matcher).toBe('Grep|Glob|Execute');
+    expect(entry.matcher).not.toMatch(/\bBash\b/);
+  });
+
+  it('invokes the hook via the ${DROID_PLUGIN_ROOT} plugin-root variable', () => {
+    const command: string = entry.hooks[0].command;
+    expect(command).toContain('${DROID_PLUGIN_ROOT}');
+    expect(command).toContain('hooks/gitnexus-hook.js');
+  });
+
+  it('declares timeout in seconds (not milliseconds)', () => {
+    const timeout: number = entry.hooks[0].timeout;
+    expect(typeof timeout).toBe('number');
+    expect(timeout).toBeGreaterThan(0);
+    expect(timeout).toBeLessThan(120);
+  });
+});
+
+// ─── Source regressions ─────────────────────────────────────────────
+
+describe('Factory hook source regressions', () => {
+  const source = fs.readFileSync(HOOK, 'utf-8');
+
+  it('wires the augment fan-out guard (acquireHookSlot + finally release)', () => {
+    expect(source).toContain("require('./hook-lock.js')");
+    expect(source).toContain('acquireHookSlot(');
+    expect(source).toMatch(/finally\s*\{[^}]*release\(\)/s);
+  });
+
+  it('wires the LadybugDB owner probe before running augment', () => {
+    expect(source).toContain("require('./hook-db-lock-probe.cjs')");
+    expect(source).toContain('hasGitNexusDbLockedByGitNexusServer(');
+  });
+
+  it('never passes shell: true / shell: isWin to spawnSync (injection risk)', () => {
+    for (const line of source.split('\n')) {
+      const t = line.trim();
+      if (t.startsWith('//') || t.startsWith('*')) continue;
+      expect(/shell:\s*(true|isWin)/.test(line), `injection risk: ${t}`).toBe(false);
+    }
+  });
+
+  it('invokes npx.cmd directly on Windows instead of a shell', () => {
+    expect(source).toContain('npx.cmd');
+  });
+
+  it('passes the pattern after the -- end-of-options marker', () => {
+    expect(source).toMatch(/'augment',\s*'--',\s*pattern/);
+  });
+
+  it('validates cwd is absolute and gates on a non-registry .gitnexus dir', () => {
+    expect(source).toMatch(/path\.isAbsolute\(cwd\)/);
+    expect(source).toContain('isGlobalRegistryDir');
+  });
+
+  it('emits Factory-shape hookSpecificOutput.additionalContext', () => {
+    expect(source).toContain('hookSpecificOutput');
+    expect(source).toContain('additionalContext');
+  });
+
+  it('rejects patterns shorter than 3 chars', () => {
+    expect(source).toMatch(/length\s*<\s*3/);
+  });
+});
+
+// ─── Behavior: early-exit paths (no augment spawned) ────────────────
+
+describe('Factory hook behavior — early exits', () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-factory-early-'));
+  });
+  afterAll(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+  it('exits cleanly on empty stdin', () => {
+    const r = spawnSync(process.execPath, [HOOK], {
+      input: '',
+      encoding: 'utf-8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe('');
+  });
+
+  it('exits cleanly on invalid JSON stdin', () => {
+    const r = spawnSync(process.execPath, [HOOK], {
+      input: 'not json',
+      encoding: 'utf-8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe('');
+  });
+
+  it('ignores non-PostToolUse events', () => {
+    const r = runHook(HOOK, {
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Grep',
+      tool_input: { pattern: 'validateUser' },
+      cwd: tmpDir,
+    });
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe('');
+  });
+
+  it('produces no output when cwd is relative', () => {
+    const r = runHook(HOOK, {
+      hook_event_name: 'PostToolUse',
+      tool_name: 'Grep',
+      tool_input: { pattern: 'validateUser' },
+      cwd: 'relative/path',
+    });
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe('');
+  });
+
+  it('produces no output when cwd has no .gitnexus index', () => {
+    const r = runHook(HOOK, {
+      hook_event_name: 'PostToolUse',
+      tool_name: 'Grep',
+      tool_input: { pattern: 'validateUser' },
+      cwd: tmpDir,
+    });
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe('');
+  });
+
+  it('produces no output for unmatched tools or Execute without rg/grep', () => {
+    for (const input of [
+      { tool_name: 'MadeUpTool', tool_input: { foo: 'bar' } },
+      { tool_name: 'Execute', tool_input: { command: 'ls -la' } },
+      { tool_name: 'Grep', tool_input: { pattern: 'is' } }, // < 3 chars
+    ]) {
+      const r = runHook(HOOK, { hook_event_name: 'PostToolUse', cwd: tmpDir, ...input });
+      expect(r.status).toBe(0);
+      expect(r.stdout.trim()).toBe('');
+    }
+  });
+});
+
+// ─── Behavior: happy path (augment via a fake gitnexus on PATH) ─────
+
+describe('Factory hook behavior — augment', () => {
+  let repoDir: string;
+  let binDir: string;
+
+  beforeAll(() => {
+    repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-factory-repo-'));
+    // Bare .gitnexus/ (no registry.json/repos) → treated as a repo index; no
+    // `lbug` file → the DB-owner probe short-circuits false and augment runs.
+    fs.mkdirSync(path.join(repoDir, '.gitnexus'), { recursive: true });
+    binDir = createHookToolDir({ gitnexusStderr: '[GitNexus] graph context for validateUser' });
+  });
+  afterAll(() => {
+    fs.rmSync(repoDir, { recursive: true, force: true });
+    fs.rmSync(binDir, { recursive: true, force: true });
+  });
+
+  it('emits augment stderr as additionalContext for a Grep search', () => {
+    const r = runHook(
+      HOOK,
+      {
+        hook_event_name: 'PostToolUse',
+        tool_name: 'Grep',
+        tool_input: { pattern: 'validateUser' },
+        cwd: repoDir,
+      },
+      undefined,
+      { env: hookEnv(binDir) },
+    );
+    expect(r.status).toBe(0);
+    const out = parseHookOutput(r.stdout);
+    expect(out?.hookEventName).toBe('PostToolUse');
+    expect(out?.additionalContext).toContain('graph context for validateUser');
+  });
+});
+
+// ─── Behavior: fan-out guard skips when all slots are held ──────────
+
+describe('Factory hook behavior — augment fan-out guard', () => {
+  it('exits silently when all MAX_INFLIGHT slots hold live pids', async () => {
+    const repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-factory-slots-'));
+    const lockDir = path.join(repoDir, '.gitnexus', '.hook-locks');
+    fs.mkdirSync(lockDir, { recursive: true });
+    const binDir = createHookToolDir({ gitnexusStderr: 'should never be emitted' });
+
+    const { spawn } = await import('child_process');
+    const sleepers = [0, 1, 2].map(() =>
+      spawn(process.execPath, ['-e', 'setTimeout(()=>{},60000)'], { stdio: 'ignore' }),
+    );
+    try {
+      sleepers.forEach((s, i) =>
+        fs.writeFileSync(path.join(lockDir, `slot-${i}.lock`), String(s.pid)),
+      );
+
+      const r = runHook(
+        HOOK,
+        {
+          hook_event_name: 'PostToolUse',
+          tool_name: 'Grep',
+          tool_input: { pattern: 'validateUser' },
+          cwd: repoDir,
+        },
+        undefined,
+        { env: hookEnv(binDir) },
+      );
+
+      expect(r.status).toBe(0);
+      expect(r.stdout.trim()).toBe('');
+    } finally {
+      for (const s of sleepers) {
+        try {
+          s.kill();
+        } catch {
+          /* ignore */
+        }
+      }
+      fs.rmSync(repoDir, { recursive: true, force: true });
+      fs.rmSync(binDir, { recursive: true, force: true });
+    }
+  });
+});

From 2bfb276eb622901276dff5aa6174c62789602f37 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Sun, 19 Jul 2026 15:51:16 -0700
Subject: [PATCH 05/15] docs: align Factory row in editor support table

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2642878c4..6bd6dbcbc 100644
--- a/README.md
+++ b/README.md
@@ -205,7 +205,7 @@ flowchart TB
 | **OpenCode**             | Yes | Yes    | —                                                                                                                 | MCP + Skills |
 | **CodeBuddy** (Tencent)  | Yes | Yes    | —                                                                                                                 | MCP + Skills |
 | **Qoder** (Alibaba)      | Yes | Yes    | —                                                                                                                 | MCP + Skills |
-| **Factory** (Droid)      | Yes | Yes    | Yes (PostToolUse, [plugin](gitnexus-factory-plugin/))                                                              | **Full**     |
+| **Factory** (Droid)      | Yes | Yes    | Yes (PostToolUse, [plugin](gitnexus-factory-plugin/))                                                             | **Full**     |
 | **Windsurf**             | Yes | —      | —                                                                                                                 | MCP          |
 
 > **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.

From b813d3966631c270918fa6bfc685c3e107ffa242 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Tue, 21 Jul 2026 11:42:20 -0700
Subject: [PATCH 06/15] fix(factory-plugin): honor GITNEXUS_HOOK_CLI_PATH so
 augment runs on Windows

---
 .../hooks/gitnexus-hook.js                    | 31 +++++++++++++------
 gitnexus/test/unit/factory-plugin.test.ts     |  8 +++++
 2 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/gitnexus-factory-plugin/hooks/gitnexus-hook.js b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
index 248680e86..80eb79e83 100644
--- a/gitnexus-factory-plugin/hooks/gitnexus-hook.js
+++ b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
@@ -137,12 +137,18 @@ function extractPattern(toolName, toolInput) {
  * fd level, making it unusable in subprocess contexts). Tries a PATH-installed
  * binary first, then falls back to npx.
  *
+ * Honors GITNEXUS_HOOK_CLI_PATH first, same as the Claude adapter: it runs the
+ * CLI as `node <path>`, which is the only branch that works on Windows, where
+ * Node refuses to spawn the `.cmd` launcher shims below without a shell
+ * (CVE-2024-27980). Falls back to a PATH binary, then npx.
+ *
  * SECURITY: `pattern` is passed after the `--` end-of-options marker and never
  * through a shell — the Windows npx fallback invokes `npx.cmd` directly rather
  * than `shell: true`, so a pattern like `-rf` or `$(...)` is inert.
  */
 function runAugment(pattern, cwd) {
   const isWin = process.platform === 'win32';
+  const args = ['augment', '--', pattern];
   const spawnOpts = {
     encoding: 'utf-8',
     timeout: 8000,
@@ -151,12 +157,21 @@ function runAugment(pattern, cwd) {
     windowsHide: true,
   };
 
+  const hookCli = process.env.GITNEXUS_HOOK_CLI_PATH;
+  if (hookCli && String(hookCli).trim() && fs.existsSync(String(hookCli))) {
+    try {
+      const child = spawnSync(process.execPath, [String(hookCli), ...args], spawnOpts);
+      if (!child.error && child.status === 0 && child.stderr && child.stderr.trim()) {
+        return child.stderr;
+      }
+    } catch {
+      /* graceful failure */
+    }
+    return '';
+  }
+
   try {
-    const child = spawnSync(
-      isWin ? 'gitnexus.cmd' : 'gitnexus',
-      ['augment', '--', pattern],
-      spawnOpts,
-    );
+    const child = spawnSync(isWin ? 'gitnexus.cmd' : 'gitnexus', args, spawnOpts);
     if (!child.error && child.status === 0 && child.stderr && child.stderr.trim()) {
       return child.stderr;
     }
@@ -165,11 +180,7 @@ function runAugment(pattern, cwd) {
   }
 
   try {
-    const child = spawnSync(
-      isWin ? 'npx.cmd' : 'npx',
-      ['-y', 'gitnexus', 'augment', '--', pattern],
-      spawnOpts,
-    );
+    const child = spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], spawnOpts);
     if (!child.error && child.status === 0 && child.stderr && child.stderr.trim()) {
       return child.stderr;
     }
diff --git a/gitnexus/test/unit/factory-plugin.test.ts b/gitnexus/test/unit/factory-plugin.test.ts
index 4d6f836e3..3a62b628a 100644
--- a/gitnexus/test/unit/factory-plugin.test.ts
+++ b/gitnexus/test/unit/factory-plugin.test.ts
@@ -155,6 +155,14 @@ describe('Factory hook source regressions', () => {
     expect(source).toContain('npx.cmd');
   });
 
+  // Windows regression: Node refuses to spawn the .cmd launcher shims without a
+  // shell (CVE-2024-27980), so `node <cliPath>` is the only branch that runs
+  // there. Same escape hatch the Claude adapter honors.
+  it('prefers GITNEXUS_HOOK_CLI_PATH via process.execPath', () => {
+    expect(source).toContain('GITNEXUS_HOOK_CLI_PATH');
+    expect(source).toMatch(/spawnSync\(\s*process\.execPath/);
+  });
+
   it('passes the pattern after the -- end-of-options marker', () => {
     expect(source).toMatch(/'augment',\s*'--',\s*pattern/);
   });

From 550ee29e9e1cb405e52f0434b20b523f982f1fbf Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Tue, 21 Jul 2026 11:57:22 -0700
Subject: [PATCH 07/15] docs(hooks): point bundled guard copies at their drift
 tests

---
 gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs  | 4 ++++
 gitnexus-claude-plugin/hooks/hook-lock.js            | 4 ++++
 gitnexus-claude-plugin/hooks/win-rm-list-json.ps1    | 4 ++++
 gitnexus-cursor-integration/hooks/hook-lock.cjs      | 4 ++++
 gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs | 4 ++++
 gitnexus-factory-plugin/hooks/hook-lock.js           | 4 ++++
 gitnexus-factory-plugin/hooks/win-rm-list-json.ps1   | 4 ++++
 gitnexus/hooks/claude/hook-db-lock-probe.cjs         | 4 ++++
 gitnexus/hooks/claude/hook-lock.cjs                  | 4 ++++
 gitnexus/hooks/claude/win-rm-list-json.ps1           | 4 ++++
 10 files changed, 40 insertions(+)

diff --git a/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
index 4376795e2..94c6848e4 100644
--- a/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
+++ b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
@@ -1,3 +1,7 @@
+// Bundled byte-identical into every hook adapter directory — each one installs
+// standalone and cannot import across packages. Drift guards in
+// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+// copies diverge; fix them together.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus-claude-plugin/hooks/hook-lock.js b/gitnexus-claude-plugin/hooks/hook-lock.js
index 759856384..03ac738f9 100644
--- a/gitnexus-claude-plugin/hooks/hook-lock.js
+++ b/gitnexus-claude-plugin/hooks/hook-lock.js
@@ -1,3 +1,7 @@
+// Bundled byte-identical into every hook adapter directory — each one installs
+// standalone and cannot import across packages. Drift guards in
+// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+// copies diverge; fix them together.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
index 5c1564e30..0745148f7 100644
--- a/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
+++ b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
@@ -1,3 +1,7 @@
+# Bundled byte-identical into every hook adapter directory — each one installs
+# standalone and cannot import across packages. Drift guards in
+# gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+# copies diverge; fix them together.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
diff --git a/gitnexus-cursor-integration/hooks/hook-lock.cjs b/gitnexus-cursor-integration/hooks/hook-lock.cjs
index 759856384..03ac738f9 100644
--- a/gitnexus-cursor-integration/hooks/hook-lock.cjs
+++ b/gitnexus-cursor-integration/hooks/hook-lock.cjs
@@ -1,3 +1,7 @@
+// Bundled byte-identical into every hook adapter directory — each one installs
+// standalone and cannot import across packages. Drift guards in
+// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+// copies diverge; fix them together.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
index 4376795e2..94c6848e4 100644
--- a/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
+++ b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
@@ -1,3 +1,7 @@
+// Bundled byte-identical into every hook adapter directory — each one installs
+// standalone and cannot import across packages. Drift guards in
+// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+// copies diverge; fix them together.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus-factory-plugin/hooks/hook-lock.js b/gitnexus-factory-plugin/hooks/hook-lock.js
index 759856384..03ac738f9 100644
--- a/gitnexus-factory-plugin/hooks/hook-lock.js
+++ b/gitnexus-factory-plugin/hooks/hook-lock.js
@@ -1,3 +1,7 @@
+// Bundled byte-identical into every hook adapter directory — each one installs
+// standalone and cannot import across packages. Drift guards in
+// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+// copies diverge; fix them together.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
index 5c1564e30..0745148f7 100644
--- a/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
+++ b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
@@ -1,3 +1,7 @@
+# Bundled byte-identical into every hook adapter directory — each one installs
+# standalone and cannot import across packages. Drift guards in
+# gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+# copies diverge; fix them together.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
diff --git a/gitnexus/hooks/claude/hook-db-lock-probe.cjs b/gitnexus/hooks/claude/hook-db-lock-probe.cjs
index 4376795e2..94c6848e4 100644
--- a/gitnexus/hooks/claude/hook-db-lock-probe.cjs
+++ b/gitnexus/hooks/claude/hook-db-lock-probe.cjs
@@ -1,3 +1,7 @@
+// Bundled byte-identical into every hook adapter directory — each one installs
+// standalone and cannot import across packages. Drift guards in
+// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+// copies diverge; fix them together.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus/hooks/claude/hook-lock.cjs b/gitnexus/hooks/claude/hook-lock.cjs
index 759856384..03ac738f9 100644
--- a/gitnexus/hooks/claude/hook-lock.cjs
+++ b/gitnexus/hooks/claude/hook-lock.cjs
@@ -1,3 +1,7 @@
+// Bundled byte-identical into every hook adapter directory — each one installs
+// standalone and cannot import across packages. Drift guards in
+// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+// copies diverge; fix them together.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus/hooks/claude/win-rm-list-json.ps1 b/gitnexus/hooks/claude/win-rm-list-json.ps1
index 5c1564e30..0745148f7 100644
--- a/gitnexus/hooks/claude/win-rm-list-json.ps1
+++ b/gitnexus/hooks/claude/win-rm-list-json.ps1
@@ -1,3 +1,7 @@
+# Bundled byte-identical into every hook adapter directory — each one installs
+# standalone and cannot import across packages. Drift guards in
+# gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
+# copies diverge; fix them together.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }

From bffd641610db656a65154c7d5643620cfc784f95 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Tue, 21 Jul 2026 11:57:22 -0700
Subject: [PATCH 08/15] docs(factory-plugin): note the Execute tokenizer's
 quoting limit

---
 gitnexus-factory-plugin/hooks/gitnexus-hook.js | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/gitnexus-factory-plugin/hooks/gitnexus-hook.js b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
index 80eb79e83..6bae2d588 100644
--- a/gitnexus-factory-plugin/hooks/gitnexus-hook.js
+++ b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
@@ -91,6 +91,12 @@ function extractPattern(toolName, toolInput) {
     const cmd = toolInput.command || '';
     if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
 
+    // NOTE: split(/\s+/) cannot handle shell quoting, same as the Cursor
+    // integration. `rg "User Service" src/` yields "User" (first token after
+    // rg/grep, quotes stripped) rather than the full phrase — BM25 is already
+    // token-tolerant, so the multi-word pattern is deliberately not
+    // reconstructed. Worst case is augment context for a narrower term than
+    // the agent searched. Quoted single tokens (`rg "validateUser"`) are exact.
     const tokens = cmd.split(/\s+/);
     let foundCmd = false;
     let skipNext = false;

From 4892b4ec7167d313e18e9f333e82649e2fae39c1 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Tue, 21 Jul 2026 11:57:22 -0700
Subject: [PATCH 09/15] docs(readme): clarify the Full tier and group the
 Factory row

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ea2f9f7c5..c388b3414 100644
--- a/README.md
+++ b/README.md
@@ -208,13 +208,13 @@ flowchart TB
 | **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/))[¹](#fn-antigravity-hooks) | **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 |
-| **Factory** (Droid)      | Yes | Yes    | Yes (PostToolUse, [plugin](gitnexus-factory-plugin/))                                                             | **Full**     |
 | **Windsurf**             | Yes | —      | —                                                                                                                 | MCP          |
 
-> **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with 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.
 
 <a id="fn-antigravity-hooks"></a>
 

From 384d72df0e499ea4edb1062453edcc459c7c563d Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Thu, 23 Jul 2026 13:18:49 -0700
Subject: [PATCH 10/15] docs(hooks): trim drift note to a single line

---
 gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs  | 5 +----
 gitnexus-claude-plugin/hooks/hook-lock.js            | 5 +----
 gitnexus-claude-plugin/hooks/win-rm-list-json.ps1    | 5 +----
 gitnexus-cursor-integration/hooks/hook-lock.cjs      | 5 +----
 gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs | 5 +----
 gitnexus-factory-plugin/hooks/hook-lock.js           | 5 +----
 gitnexus-factory-plugin/hooks/win-rm-list-json.ps1   | 5 +----
 gitnexus/hooks/claude/hook-db-lock-probe.cjs         | 5 +----
 gitnexus/hooks/claude/hook-lock.cjs                  | 5 +----
 gitnexus/hooks/claude/win-rm-list-json.ps1           | 5 +----
 10 files changed, 10 insertions(+), 40 deletions(-)

diff --git a/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
index 94c6848e4..eb0709758 100644
--- a/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
+++ b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
@@ -1,7 +1,4 @@
-// Bundled byte-identical into every hook adapter directory — each one installs
-// standalone and cannot import across packages. Drift guards in
-// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-// copies diverge; fix them together.
+// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus-claude-plugin/hooks/hook-lock.js b/gitnexus-claude-plugin/hooks/hook-lock.js
index 03ac738f9..d9c5913bc 100644
--- a/gitnexus-claude-plugin/hooks/hook-lock.js
+++ b/gitnexus-claude-plugin/hooks/hook-lock.js
@@ -1,7 +1,4 @@
-// Bundled byte-identical into every hook adapter directory — each one installs
-// standalone and cannot import across packages. Drift guards in
-// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-// copies diverge; fix them together.
+// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
index 0745148f7..0db965080 100644
--- a/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
+++ b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
@@ -1,7 +1,4 @@
-# Bundled byte-identical into every hook adapter directory — each one installs
-# standalone and cannot import across packages. Drift guards in
-# gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-# copies diverge; fix them together.
+# Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
diff --git a/gitnexus-cursor-integration/hooks/hook-lock.cjs b/gitnexus-cursor-integration/hooks/hook-lock.cjs
index 03ac738f9..d9c5913bc 100644
--- a/gitnexus-cursor-integration/hooks/hook-lock.cjs
+++ b/gitnexus-cursor-integration/hooks/hook-lock.cjs
@@ -1,7 +1,4 @@
-// Bundled byte-identical into every hook adapter directory — each one installs
-// standalone and cannot import across packages. Drift guards in
-// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-// copies diverge; fix them together.
+// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
index 94c6848e4..eb0709758 100644
--- a/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
+++ b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
@@ -1,7 +1,4 @@
-// Bundled byte-identical into every hook adapter directory — each one installs
-// standalone and cannot import across packages. Drift guards in
-// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-// copies diverge; fix them together.
+// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus-factory-plugin/hooks/hook-lock.js b/gitnexus-factory-plugin/hooks/hook-lock.js
index 03ac738f9..d9c5913bc 100644
--- a/gitnexus-factory-plugin/hooks/hook-lock.js
+++ b/gitnexus-factory-plugin/hooks/hook-lock.js
@@ -1,7 +1,4 @@
-// Bundled byte-identical into every hook adapter directory — each one installs
-// standalone and cannot import across packages. Drift guards in
-// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-// copies diverge; fix them together.
+// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
index 0745148f7..0db965080 100644
--- a/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
+++ b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
@@ -1,7 +1,4 @@
-# Bundled byte-identical into every hook adapter directory — each one installs
-# standalone and cannot import across packages. Drift guards in
-# gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-# copies diverge; fix them together.
+# Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
diff --git a/gitnexus/hooks/claude/hook-db-lock-probe.cjs b/gitnexus/hooks/claude/hook-db-lock-probe.cjs
index 94c6848e4..eb0709758 100644
--- a/gitnexus/hooks/claude/hook-db-lock-probe.cjs
+++ b/gitnexus/hooks/claude/hook-db-lock-probe.cjs
@@ -1,7 +1,4 @@
-// Bundled byte-identical into every hook adapter directory — each one installs
-// standalone and cannot import across packages. Drift guards in
-// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-// copies diverge; fix them together.
+// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus/hooks/claude/hook-lock.cjs b/gitnexus/hooks/claude/hook-lock.cjs
index 03ac738f9..d9c5913bc 100644
--- a/gitnexus/hooks/claude/hook-lock.cjs
+++ b/gitnexus/hooks/claude/hook-lock.cjs
@@ -1,7 +1,4 @@
-// Bundled byte-identical into every hook adapter directory — each one installs
-// standalone and cannot import across packages. Drift guards in
-// gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-// copies diverge; fix them together.
+// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus/hooks/claude/win-rm-list-json.ps1 b/gitnexus/hooks/claude/win-rm-list-json.ps1
index 0745148f7..0db965080 100644
--- a/gitnexus/hooks/claude/win-rm-list-json.ps1
+++ b/gitnexus/hooks/claude/win-rm-list-json.ps1
@@ -1,7 +1,4 @@
-# Bundled byte-identical into every hook adapter directory — each one installs
-# standalone and cannot import across packages. Drift guards in
-# gitnexus/test/unit/hooks.test.ts and test/unit/factory-plugin.test.ts fail if the
-# copies diverge; fix them together.
+# Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }

From f922ee3dde806300c8b2b80e260a668f46a60546 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Thu, 23 Jul 2026 13:23:50 -0700
Subject: [PATCH 11/15] test(ci): run factory-plugin tests on the windows
 cross-platform lane

---
 gitnexus/scripts/cross-platform-tests.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/gitnexus/scripts/cross-platform-tests.ts b/gitnexus/scripts/cross-platform-tests.ts
index 5d6b177f5..79e0962dd 100644
--- a/gitnexus/scripts/cross-platform-tests.ts
+++ b/gitnexus/scripts/cross-platform-tests.ts
@@ -48,6 +48,7 @@ const PLATFORM_LOGIC = [
   'test/unit/hooks.test.ts',
   'test/unit/hook-db-lock-probe.test.ts',
   'test/unit/cursor-hook.test.ts',
+  'test/unit/factory-plugin.test.ts',
   'test/unit/sidecar-recovery.test.ts',
   'test/unit/pool-wal-recovery.test.ts',
   'test/unit/lbug-adapter-wal-schema.test.ts',

From a262dfbaaa86bce7f8fa5da95336fb17238d4022 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Sat, 22 Aug 2026 20:05:58 -0700
Subject: [PATCH 12/15] refactor(hooks): drop the drift-note comments, the
 tests already enforce it

---
 gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs  | 1 -
 gitnexus-claude-plugin/hooks/hook-lock.js            | 1 -
 gitnexus-claude-plugin/hooks/win-rm-list-json.ps1    | 1 -
 gitnexus-cursor-integration/hooks/hook-lock.cjs      | 1 -
 gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs | 1 -
 gitnexus-factory-plugin/hooks/hook-lock.js           | 1 -
 gitnexus-factory-plugin/hooks/win-rm-list-json.ps1   | 1 -
 gitnexus/hooks/claude/hook-db-lock-probe.cjs         | 1 -
 gitnexus/hooks/claude/hook-lock.cjs                  | 1 -
 gitnexus/hooks/claude/win-rm-list-json.ps1           | 1 -
 10 files changed, 10 deletions(-)

diff --git a/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
index eb0709758..4376795e2 100644
--- a/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
+++ b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
@@ -1,4 +1,3 @@
-// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus-claude-plugin/hooks/hook-lock.js b/gitnexus-claude-plugin/hooks/hook-lock.js
index d9c5913bc..759856384 100644
--- a/gitnexus-claude-plugin/hooks/hook-lock.js
+++ b/gitnexus-claude-plugin/hooks/hook-lock.js
@@ -1,4 +1,3 @@
-// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
index 0db965080..5c1564e30 100644
--- a/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
+++ b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1
@@ -1,4 +1,3 @@
-# Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
diff --git a/gitnexus-cursor-integration/hooks/hook-lock.cjs b/gitnexus-cursor-integration/hooks/hook-lock.cjs
index d9c5913bc..759856384 100644
--- a/gitnexus-cursor-integration/hooks/hook-lock.cjs
+++ b/gitnexus-cursor-integration/hooks/hook-lock.cjs
@@ -1,4 +1,3 @@
-// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
index eb0709758..4376795e2 100644
--- a/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
+++ b/gitnexus-factory-plugin/hooks/hook-db-lock-probe.cjs
@@ -1,4 +1,3 @@
-// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus-factory-plugin/hooks/hook-lock.js b/gitnexus-factory-plugin/hooks/hook-lock.js
index d9c5913bc..759856384 100644
--- a/gitnexus-factory-plugin/hooks/hook-lock.js
+++ b/gitnexus-factory-plugin/hooks/hook-lock.js
@@ -1,4 +1,3 @@
-// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
index 0db965080..5c1564e30 100644
--- a/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
+++ b/gitnexus-factory-plugin/hooks/win-rm-list-json.ps1
@@ -1,4 +1,3 @@
-# Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
diff --git a/gitnexus/hooks/claude/hook-db-lock-probe.cjs b/gitnexus/hooks/claude/hook-db-lock-probe.cjs
index eb0709758..4376795e2 100644
--- a/gitnexus/hooks/claude/hook-db-lock-probe.cjs
+++ b/gitnexus/hooks/claude/hook-db-lock-probe.cjs
@@ -1,4 +1,3 @@
-// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 /**
  * Cross-platform best-effort probe: does another process hold dbPath open
  * with a command line that looks like a GitNexus MCP/serve server?
diff --git a/gitnexus/hooks/claude/hook-lock.cjs b/gitnexus/hooks/claude/hook-lock.cjs
index d9c5913bc..759856384 100644
--- a/gitnexus/hooks/claude/hook-lock.cjs
+++ b/gitnexus/hooks/claude/hook-lock.cjs
@@ -1,4 +1,3 @@
-// Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 const fs = require('fs');
 const path = require('path');
 
diff --git a/gitnexus/hooks/claude/win-rm-list-json.ps1 b/gitnexus/hooks/claude/win-rm-list-json.ps1
index 0db965080..5c1564e30 100644
--- a/gitnexus/hooks/claude/win-rm-list-json.ps1
+++ b/gitnexus/hooks/claude/win-rm-list-json.ps1
@@ -1,4 +1,3 @@
-# Byte-identical across all hook adapter dirs; drift-guarded by hooks.test.ts / factory-plugin.test.ts. Edit all copies.
 $ErrorActionPreference = 'Stop'
 $target = $env:GITNEXUS_HOOK_RM_TARGET
 if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }

From 848ed2a0b638235d68fcc53b4940a72ebdde66f0 Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Sat, 22 Aug 2026 20:06:45 -0700
Subject: [PATCH 13/15] fix(factory-plugin): pin CLI version and parse quoted
 shell patterns

- Pin mcp.json and the hook's npx fallback to gitnexus@<version> from
  the plugin manifest, registered with the release sync script so a
  mutable @latest can never execute on MCP connect or augment fallback
- Port the #2938 shell tokenizer (tokenizeShellWords + parseRgGrepPattern)
  so quoted, backslash-escaped, --regexp=, -eVALUE, and -- patterns survive
- Add the #2938 regression matrix and pin assertions to factory-plugin.test.ts
---
 .../hooks/gitnexus-hook.js                    | 257 ++++++++++++------
 gitnexus-factory-plugin/mcp.json              |   2 +-
 gitnexus/scripts/sync-plugin-manifests.mjs    |   8 +
 gitnexus/test/unit/factory-plugin.test.ts     |  46 ++++
 .../test/unit/sync-plugin-manifests.test.ts   |  22 +-
 5 files changed, 238 insertions(+), 97 deletions(-)

diff --git a/gitnexus-factory-plugin/hooks/gitnexus-hook.js b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
index 6bae2d588..e57bae9cb 100644
--- a/gitnexus-factory-plugin/hooks/gitnexus-hook.js
+++ b/gitnexus-factory-plugin/hooks/gitnexus-hook.js
@@ -1,23 +1,17 @@
 #!/usr/bin/env node
 /**
- * GitNexus Factory AI (Droid) Plugin Hook
+ * GitNexus Factory AI (Droid) plugin hook.
  *
- * PostToolUse — augments Grep/Glob/Execute searches with graph context from
- * the GitNexus index and returns it via hookSpecificOutput.additionalContext.
+ * PostToolUse — augments Grep/Glob/Execute searches with graph context and
+ * returns it via hookSpecificOutput.additionalContext.
  *
- * Reuses the same guards as the Claude/Codex adapter (bundled byte-identical,
- * kept in lockstep by test/unit/factory-plugin.test.ts):
- *   - acquireHookSlot  — per-repo cap on concurrent augment children so
- *     parallel sessions can't fan out unbounded `gitnexus augment` spawns
- *     (#1486).
- *   - LadybugDB owner probe — skips the CLI augment when a GitNexus MCP/serve
- *     process already holds the single-writer DB lock, avoiding contention
- *     (#2396); the in-session MCP tools cover augmentation instead.
+ * Reuses the Claude adapter's guards, bundled byte-identical: acquireHookSlot
+ * caps concurrent augment children per repo (#1486), and the LadybugDB owner
+ * probe skips the CLI augment when an MCP/serve process already holds the
+ * single-writer lock (#2396).
  *
- * The augment CLI child is NOT wrapped in the coreutils `timeout`
- * orphan-containment guard the full Claude adapter uses (#2163) — same scope
- * as the Cursor integration. Add it (resolveUnixGuardTimeout is exported by
- * the bundled probe) if orphaned augment children become a problem here.
+ * The augment child is not wrapped in the coreutils `timeout` orphan guard the
+ * full Claude adapter uses (#2163) — same scope as the Cursor integration.
  */
 
 const fs = require('fs');
@@ -26,22 +20,22 @@ const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.js');
 const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
 
-/**
- * Read JSON input from stdin synchronously.
- */
+// Pin the CLI instead of tracking `latest`: npm versions are immutable, so only
+// a plugin revision can change what the fallback below executes. The release
+// stamps this manifest (gitnexus/scripts/sync-plugin-manifests.mjs).
+const { version: PINNED_VERSION } = require('../.factory-plugin/plugin.json');
+
 function readInput() {
   try {
-    const data = fs.readFileSync(0, 'utf-8');
-    return JSON.parse(data);
+    return JSON.parse(fs.readFileSync(0, 'utf-8'));
   } catch {
     return {};
   }
 }
 
 /**
- * A `.gitnexus/` that holds `registry.json`/`repos` (and no per-repo index
- * metadata) is the global registry, not a repo index — never augment against
- * it. Mirrors the Claude adapter's guard.
+ * A `.gitnexus/` holding `registry.json`/`repos` (and no per-repo index
+ * metadata) is the global registry, not a repo index — never augment against it.
  */
 function isGlobalRegistryDir(candidate) {
   if (
@@ -56,10 +50,7 @@ function isGlobalRegistryDir(candidate) {
   );
 }
 
-/**
- * Walk up from startDir looking for a non-registry `.gitnexus/` folder. Returns
- * the path to `.gitnexus/` or null if not found within 5 levels.
- */
+/** Walk up from startDir for a non-registry `.gitnexus/`, at most 5 levels. */
 function findGitNexusDir(startDir) {
   let dir = startDir || process.cwd();
   for (let i = 0; i < 5; i++) {
@@ -73,9 +64,138 @@ function findGitNexusDir(startDir) {
 }
 
 /**
- * Extract a search pattern from a Factory tool payload. Factory's shell tool is
- * `Execute` (Claude's is `Bash`); Grep/Glob match Claude's.
+ * Split a command the way a POSIX shell would, so quoted and backslash-escaped
+ * patterns survive as one token. Kept identical to the Cursor adapter's
+ * tokenizer (#2938) so the two can collapse into a shared module later.
  */
+function tokenizeShellWords(command) {
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  let escaped = false;
+  let hasToken = false;
+
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (escaped) {
+      current += char;
+      escaped = false;
+      hasToken = true;
+      continue;
+    }
+
+    if (quote === "'") {
+      if (char === "'") quote = null;
+      else current += char;
+      hasToken = true;
+      continue;
+    }
+
+    if (quote === '"') {
+      if (char === '"') {
+        quote = null;
+      } else if (char === '\\') {
+        const next = command[index + 1];
+        // Inside double quotes a backslash only escapes these four; otherwise
+        // it is a literal character (so Windows paths survive intact).
+        if (next === '$' || next === '`' || next === '"' || next === '\\') {
+          escaped = true;
+        } else {
+          current += '\\';
+        }
+      } else {
+        current += char;
+      }
+      hasToken = true;
+      continue;
+    }
+
+    if (char === '\\') {
+      escaped = true;
+      hasToken = true;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+      hasToken = true;
+    } else if (/\s/.test(char)) {
+      if (hasToken) tokens.push(current);
+      current = '';
+      hasToken = false;
+    } else {
+      current += char;
+      hasToken = true;
+    }
+  }
+
+  if (escaped) current += '\\';
+  if (hasToken) tokens.push(current);
+  return tokens;
+}
+
+/** Recover the search pattern from an `rg`/`grep` command line. */
+function parseRgGrepPattern(cmd) {
+  const tokens = tokenizeShellWords(cmd);
+  let foundCmd = false;
+  let skipNext = false;
+  let skipNextAsPattern = false;
+  let endOfOptions = false;
+  const flagsWithValues = new Set([
+    '-e',
+    '-f',
+    '-m',
+    '-A',
+    '-B',
+    '-C',
+    '-g',
+    '--glob',
+    '-t',
+    '--type',
+    '--include',
+    '--exclude',
+  ]);
+  const patternFlags = new Set(['-e', '--regexp']);
+
+  for (const token of tokens) {
+    if (skipNext) {
+      skipNext = false;
+      if (skipNextAsPattern) {
+        return token.length >= 3 ? token : null;
+      }
+      continue;
+    }
+    if (!foundCmd) {
+      // Match on the basename so absolute paths (`/usr/bin/rg`) and Windows
+      // `rg.exe` count as the command.
+      const commandName = token
+        .split(/[\\/]/)
+        .pop()
+        ?.replace(/\.exe$/i, '');
+      if (commandName === 'rg' || commandName === 'grep') foundCmd = true;
+      continue;
+    }
+    if (endOfOptions) {
+      return token.length >= 3 ? token : null;
+    }
+    if (token === '--') {
+      endOfOptions = true;
+      continue;
+    }
+    if (token.startsWith('-')) {
+      const attachedPattern = token.match(/^--regexp=(.+)$/) || token.match(/^-e(.+)$/);
+      if (attachedPattern) {
+        return attachedPattern[1].length >= 3 ? attachedPattern[1] : null;
+      }
+      if (flagsWithValues.has(token) || patternFlags.has(token)) {
+        skipNext = true;
+        skipNextAsPattern = patternFlags.has(token);
+      }
+      continue;
+    }
+    return token.length >= 3 ? token : null;
+  }
+  return null;
+}
+
+/** Factory's shell tool is `Execute` (Claude's is `Bash`); Grep/Glob match Claude's. */
 function extractPattern(toolName, toolInput) {
   if (toolName === 'Grep') {
     return toolInput.pattern || null;
@@ -90,67 +210,24 @@ function extractPattern(toolName, toolInput) {
   if (toolName === 'Execute') {
     const cmd = toolInput.command || '';
     if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
-
-    // NOTE: split(/\s+/) cannot handle shell quoting, same as the Cursor
-    // integration. `rg "User Service" src/` yields "User" (first token after
-    // rg/grep, quotes stripped) rather than the full phrase — BM25 is already
-    // token-tolerant, so the multi-word pattern is deliberately not
-    // reconstructed. Worst case is augment context for a narrower term than
-    // the agent searched. Quoted single tokens (`rg "validateUser"`) are exact.
-    const tokens = cmd.split(/\s+/);
-    let foundCmd = false;
-    let skipNext = false;
-    const flagsWithValues = new Set([
-      '-e',
-      '-f',
-      '-m',
-      '-A',
-      '-B',
-      '-C',
-      '-g',
-      '--glob',
-      '-t',
-      '--type',
-      '--include',
-      '--exclude',
-    ]);
-
-    for (const token of tokens) {
-      if (skipNext) {
-        skipNext = false;
-        continue;
-      }
-      if (!foundCmd) {
-        if (/\brg\b|\bgrep\b/.test(token)) foundCmd = true;
-        continue;
-      }
-      if (token.startsWith('-')) {
-        if (flagsWithValues.has(token)) skipNext = true;
-        continue;
-      }
-      const cleaned = token.replace(/['"]/g, '');
-      return cleaned.length >= 3 ? cleaned : null;
-    }
-    return null;
+    return parseRgGrepPattern(cmd);
   }
 
   return null;
 }
 
 /**
- * Run `gitnexus augment` for `pattern` and return its stderr (the augment CLI
- * writes results to stderr; LadybugDB's native module captures stdout at the OS
- * fd level, making it unusable in subprocess contexts). Tries a PATH-installed
- * binary first, then falls back to npx.
+ * Run `gitnexus augment` for `pattern` and return its stderr — the augment CLI
+ * writes results there because LadybugDB's native module captures stdout at the
+ * OS fd level.
  *
- * Honors GITNEXUS_HOOK_CLI_PATH first, same as the Claude adapter: it runs the
- * CLI as `node <path>`, which is the only branch that works on Windows, where
- * Node refuses to spawn the `.cmd` launcher shims below without a shell
- * (CVE-2024-27980). Falls back to a PATH binary, then npx.
+ * GITNEXUS_HOOK_CLI_PATH is tried first and run as `node <path>`, the only form
+ * that works on Windows, where Node refuses to spawn the `.cmd` shims without a
+ * shell (CVE-2024-27980). Then a PATH binary, then a version-pinned npx.
  *
- * SECURITY: `pattern` is passed after the `--` end-of-options marker and never
- * through a shell — the Windows npx fallback invokes `npx.cmd` directly rather
- * than `shell: true`, so a pattern like `-rf` or `$(...)` is inert.
+ * SECURITY: `pattern` follows the `--` end-of-options marker and never reaches a
+ * shell (the Windows fallback invokes `npx.cmd` directly rather than
+ * `shell: true`), so `-rf` or `$(...)` is inert.
  */
 function runAugment(pattern, cwd) {
   const isWin = process.platform === 'win32';
@@ -186,7 +263,11 @@ function runAugment(pattern, cwd) {
   }
 
   try {
-    const child = spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], spawnOpts);
+    const child = spawnSync(
+      isWin ? 'npx.cmd' : 'npx',
+      ['-y', `gitnexus@${PINNED_VERSION}`, ...args],
+      spawnOpts,
+    );
     if (!child.error && child.status === 0 && child.stderr && child.stderr.trim()) {
       return child.stderr;
     }
@@ -219,9 +300,9 @@ function main() {
     let result = '';
     try {
       if (hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid)) {
-        // #2396: a GitNexus MCP/serve process owns the single-writer DB, so a
-        // competing CLI augment would only contend on the lock. The session's
-        // MCP tools cover augmentation instead — skip silently.
+        // #2396: an MCP/serve process owns the single-writer DB, so a competing
+        // CLI augment would only contend on the lock. Its MCP tools cover
+        // augmentation instead — skip silently.
         return;
       }
       result = runAugment(pattern, cwd);
@@ -246,4 +327,6 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) main();
+
+module.exports = { parseRgGrepPattern, tokenizeShellWords };
diff --git a/gitnexus-factory-plugin/mcp.json b/gitnexus-factory-plugin/mcp.json
index cd02d4285..4fe6590dd 100644
--- a/gitnexus-factory-plugin/mcp.json
+++ b/gitnexus-factory-plugin/mcp.json
@@ -2,7 +2,7 @@
   "mcpServers": {
     "gitnexus": {
       "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
+      "args": ["-y", "gitnexus@1.6.9", "mcp"]
     }
   }
 }
diff --git a/gitnexus/scripts/sync-plugin-manifests.mjs b/gitnexus/scripts/sync-plugin-manifests.mjs
index 5bcc8f29c..44ca89f92 100644
--- a/gitnexus/scripts/sync-plugin-manifests.mjs
+++ b/gitnexus/scripts/sync-plugin-manifests.mjs
@@ -13,6 +13,8 @@
  *   - gitnexus-claude-plugin/.codex-plugin/plugin.json    (top-level version)
  *   - .agents/plugins/marketplace.json                    (plugins[gitnexus])
  *   - gitnexus-claude-plugin/skills/<skill>/mcp.json      (gitnexus@<version> launch arg, x10)
+ *   - gitnexus-factory-plugin/.factory-plugin/plugin.json (top-level version)
+ *   - gitnexus-factory-plugin/mcp.json                    (gitnexus@<version> launch arg)
  *
  * Modes:
  *   node scripts/sync-plugin-manifests.mjs           rewrite stale surfaces
@@ -54,6 +56,12 @@ const MANIFEST_SURFACES = [
     file: `gitnexus-claude-plugin/skills/${name}/mcp.json`,
     kind: 'mcp',
   })),
+  // The Factory plugin's manifest is also its pin source at runtime: the
+  // PostToolUse hook reads this version to build its `npx -y gitnexus@<version>`
+  // fallback, so stamping it here keeps the hook and the MCP entry on the same
+  // released CLI.
+  { file: 'gitnexus-factory-plugin/.factory-plugin/plugin.json', kind: 'plugin' },
+  { file: 'gitnexus-factory-plugin/mcp.json', kind: 'mcp' },
 ];
 
 const PLUGIN_NAME = 'gitnexus';
diff --git a/gitnexus/test/unit/factory-plugin.test.ts b/gitnexus/test/unit/factory-plugin.test.ts
index 3a62b628a..990342853 100644
--- a/gitnexus/test/unit/factory-plugin.test.ts
+++ b/gitnexus/test/unit/factory-plugin.test.ts
@@ -16,6 +16,7 @@
  */
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { spawnSync } from 'child_process';
+import { createRequire } from 'module';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -38,6 +39,11 @@ const CLAUDE_HOOKS = path.join(REPO_ROOT, 'gitnexus-claude-plugin', 'hooks');
 // canonical Claude-adapter copies.
 const BUNDLED_GUARDS = ['hook-lock.js', 'hook-db-lock-probe.cjs', 'win-rm-list-json.ps1'] as const;
 
+const require_ = createRequire(import.meta.url);
+const { parseRgGrepPattern } = require_(HOOK) as {
+  parseRgGrepPattern: (command: string) => string | null;
+};
+
 // ─── Manifest / file presence ───────────────────────────────────────
 
 describe('Factory plugin files', () => {
@@ -96,6 +102,16 @@ describe('Factory mcp.json', () => {
     expect(mcp.mcpServers?.gitnexus?.command).toBe('npx');
     expect(mcp.mcpServers.gitnexus.args).toContain('mcp');
   });
+
+  // Executed state, not quickstart docs: `@latest` would let a future registry
+  // upload run on MCP connect without a plugin revision.
+  it('pins the CLI to the released version instead of a mutable tag', () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, 'gitnexus', 'package.json'), 'utf-8'),
+    );
+    expect(mcp.mcpServers.gitnexus.args).toContain(`gitnexus@${pkg.version}`);
+    expect(JSON.stringify(mcp)).not.toContain('gitnexus@latest');
+  });
 });
 
 // ─── hooks.json wiring ──────────────────────────────────────────────
@@ -155,6 +171,14 @@ describe('Factory hook source regressions', () => {
     expect(source).toContain('npx.cmd');
   });
 
+  // The npx fallback runs on ordinary tool calls whenever the CLI is not on
+  // PATH, so an unpinned ref would execute whatever currently owns the tag.
+  it('pins the npx fallback to the manifest version, never a mutable tag', () => {
+    expect(source).not.toContain('gitnexus@latest');
+    expect(source).toContain("require('../.factory-plugin/plugin.json')");
+    expect(source).toContain('`gitnexus@${PINNED_VERSION}`');
+  });
+
   // Windows regression: Node refuses to spawn the .cmd launcher shims without a
   // shell (CVE-2024-27980), so `node <cliPath>` is the only branch that runs
   // there. Same escape hatch the Claude adapter honors.
@@ -182,6 +206,28 @@ describe('Factory hook source regressions', () => {
   });
 });
 
+// ─── Execute pattern parsing (shares the Cursor adapter's #2938 matrix) ─
+
+describe('Factory Execute pattern parser', () => {
+  it.each([
+    ['rg "User Service" src/', 'User Service'],
+    ["grep 'error boundary' -- src/", 'error boundary'],
+    ['rg User\\ Service src/', 'User Service'],
+    [String.raw`rg "C:\Users" src/`, String.raw`C:\Users`],
+    ['rg -e "User Service" src/', 'User Service'],
+    ['rg --regexp=UserService src/', 'UserService'],
+    ['grep -eUserService src/', 'UserService'],
+    ['/usr/bin/rg -- "User Service" src/', 'User Service'],
+    ['rg -- -error src/', '-error'],
+    ['rg "validateUser"', 'validateUser'],
+    ['rg -t ts UserService src/', 'UserService'],
+    ['rg --glob "*.ts" UserService', 'UserService'],
+    ['rg ab src/', null],
+  ])('extracts %j from %j', (command, expected) => {
+    expect(parseRgGrepPattern(command)).toBe(expected);
+  });
+});
+
 // ─── Behavior: early-exit paths (no augment spawned) ────────────────
 
 describe('Factory hook behavior — early exits', () => {
diff --git a/gitnexus/test/unit/sync-plugin-manifests.test.ts b/gitnexus/test/unit/sync-plugin-manifests.test.ts
index e932bad4a..b750e879d 100644
--- a/gitnexus/test/unit/sync-plugin-manifests.test.ts
+++ b/gitnexus/test/unit/sync-plugin-manifests.test.ts
@@ -9,8 +9,11 @@ const SURFACES = [
   '.claude-plugin/marketplace.json',
   'gitnexus-claude-plugin/.codex-plugin/plugin.json',
   '.agents/plugins/marketplace.json',
+  'gitnexus-factory-plugin/.factory-plugin/plugin.json',
 ] as const;
 
+const FACTORY_MCP = 'gitnexus-factory-plugin/mcp.json';
+
 const MCP_SKILL_DIRS = [
   'gitnexus-plan',
   'gitnexus-work',
@@ -24,7 +27,7 @@ const MCP_SKILL_DIRS = [
   'gitnexus-refactoring',
 ] as const;
 
-const TOTAL_SURFACES = SURFACES.length + MCP_SKILL_DIRS.length;
+const TOTAL_SURFACES = SURFACES.length + MCP_SKILL_DIRS.length + 1;
 
 function mcpPath(dir: string): string {
   return `gitnexus-claude-plugin/skills/${dir}/mcp.json`;
@@ -56,8 +59,9 @@ function makeRoot(packageVersion: string, manifestVersion: string): string {
     name: 'gitnexus-marketplace',
     plugins: [{ name: 'gitnexus', version: manifestVersion, category: 'Developer Tools' }],
   });
-  for (const dir of MCP_SKILL_DIRS) {
-    writeJson(root, mcpPath(dir), {
+  writeJson(root, SURFACES[4], { name: 'gitnexus', version: manifestVersion });
+  for (const dir of [...MCP_SKILL_DIRS.map(mcpPath), FACTORY_MCP]) {
+    writeJson(root, dir, {
       mcpServers: {
         gitnexus: { command: 'npx', args: ['-y', `gitnexus@${manifestVersion}`, 'mcp'] },
       },
@@ -89,19 +93,19 @@ describe('syncPluginManifests (#2445)', () => {
     expect(result.version).toBe('1.6.10-rc.29');
     expect(result.synced).toHaveLength(TOTAL_SURFACES);
     expect(result.stale.map(({ from }) => from)).toEqual(Array(TOTAL_SURFACES).fill('1.6.9'));
-    expect(readVersions(root)).toEqual(Array(4).fill('1.6.10-rc.29'));
+    expect(readVersions(root)).toEqual(Array(SURFACES.length).fill('1.6.10-rc.29'));
   });
 
-  it('pins the gitnexus@<version> launch arg in every plugin skill mcp.json', () => {
+  it('pins the gitnexus@<version> launch arg in every executable mcp.json', () => {
     const root = makeRoot('1.6.10-rc.29', '1.6.9');
 
     syncPluginManifests(root);
 
-    for (const dir of MCP_SKILL_DIRS) {
-      const mcp = JSON.parse(readFileSync(path.join(root, mcpPath(dir)), 'utf8')) as {
+    for (const file of [...MCP_SKILL_DIRS.map(mcpPath), FACTORY_MCP]) {
+      const mcp = JSON.parse(readFileSync(path.join(root, file), 'utf8')) as {
         mcpServers: { gitnexus: { args: string[] } };
       };
-      expect(mcp.mcpServers.gitnexus.args).toEqual(['-y', 'gitnexus@1.6.10-rc.29', 'mcp']);
+      expect(mcp.mcpServers.gitnexus.args, file).toEqual(['-y', 'gitnexus@1.6.10-rc.29', 'mcp']);
     }
   });
 
@@ -131,7 +135,7 @@ describe('syncPluginManifests (#2445)', () => {
 
     expect(result.stale).toHaveLength(TOTAL_SURFACES);
     expect(result.synced).toHaveLength(0);
-    expect(readVersions(root)).toEqual(Array(4).fill('1.6.9'));
+    expect(readVersions(root)).toEqual(Array(SURFACES.length).fill('1.6.9'));
   });
 
   it('changes only the version text and preserves the surrounding formatting', () => {

From 6649ce109eefbef4524d57ed7776e49be33f868f Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Sat, 22 Aug 2026 20:06:54 -0700
Subject: [PATCH 14/15] docs: add Factory Droid to published npm README

---
 gitnexus/README.md | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/gitnexus/README.md b/gitnexus/README.md
index db24b2693..abde4cd33 100644
--- a/gitnexus/README.md
+++ b/gitnexus/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):

From 54870b41c7f6f92b2a378b02bb4223429b662cfa Mon Sep 17 00:00:00 2001
From: joseph02 <joseph02@uw.edu>
Date: Sat, 22 Aug 2026 20:41:17 -0700
Subject: [PATCH 15/15] fix(factory-plugin): wire marketplace so droid installs
 the Factory plugin

Add .factory-plugin/marketplace.json sourcing ./gitnexus-factory-plugin.
Droid reads it before .claude-plugin/marketplace.json, so
`droid plugin install` now delivers the Factory plugin (Execute matcher,
pinned mcp.json) instead of the translated Claude plugin (Bash matcher,
gitnexus@latest). Register the surface in the version-sync script and
cover the wiring in the factory and sync test suites.
---
 .factory-plugin/marketplace.json              | 19 +++++++++++++++++++
 gitnexus/scripts/sync-plugin-manifests.mjs    |  5 +++++
 gitnexus/test/unit/factory-plugin.test.ts     | 17 +++++++++++++++++
 .../test/unit/sync-plugin-manifests.test.ts   |  5 +++++
 4 files changed, 46 insertions(+)
 create mode 100644 .factory-plugin/marketplace.json

diff --git a/.factory-plugin/marketplace.json b/.factory-plugin/marketplace.json
new file mode 100644
index 000000000..56fd22ffd
--- /dev/null
+++ b/.factory-plugin/marketplace.json
@@ -0,0 +1,19 @@
+{
+  "name": "gitnexus-marketplace",
+  "owner": {
+    "name": "GitNexus",
+    "email": "nico@gitnexus.dev"
+  },
+  "metadata": {
+    "description": "Code intelligence powered by a knowledge graph — execution flows, blast radius, and semantic search",
+    "homepage": "https://github.com/nicosxt/gitnexus"
+  },
+  "plugins": [
+    {
+      "name": "gitnexus",
+      "version": "1.6.9",
+      "source": "./gitnexus-factory-plugin",
+      "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase."
+    }
+  ]
+}
diff --git a/gitnexus/scripts/sync-plugin-manifests.mjs b/gitnexus/scripts/sync-plugin-manifests.mjs
index 44ca89f92..3858cfd06 100644
--- a/gitnexus/scripts/sync-plugin-manifests.mjs
+++ b/gitnexus/scripts/sync-plugin-manifests.mjs
@@ -15,6 +15,7 @@
  *   - gitnexus-claude-plugin/skills/<skill>/mcp.json      (gitnexus@<version> launch arg, x10)
  *   - gitnexus-factory-plugin/.factory-plugin/plugin.json (top-level version)
  *   - gitnexus-factory-plugin/mcp.json                    (gitnexus@<version> launch arg)
+ *   - .factory-plugin/marketplace.json                    (plugins[gitnexus])
  *
  * Modes:
  *   node scripts/sync-plugin-manifests.mjs           rewrite stale surfaces
@@ -62,6 +63,10 @@ const MANIFEST_SURFACES = [
   // released CLI.
   { file: 'gitnexus-factory-plugin/.factory-plugin/plugin.json', kind: 'plugin' },
   { file: 'gitnexus-factory-plugin/mcp.json', kind: 'mcp' },
+  // Droid reads .factory-plugin/marketplace.json before .claude-plugin's, so
+  // this entry is what makes `droid plugin install` deliver the Factory plugin
+  // (Execute matcher, pinned mcp.json) instead of the translated Claude one.
+  { file: '.factory-plugin/marketplace.json', kind: 'marketplace' },
 ];
 
 const PLUGIN_NAME = 'gitnexus';
diff --git a/gitnexus/test/unit/factory-plugin.test.ts b/gitnexus/test/unit/factory-plugin.test.ts
index 990342853..a38432592 100644
--- a/gitnexus/test/unit/factory-plugin.test.ts
+++ b/gitnexus/test/unit/factory-plugin.test.ts
@@ -64,6 +64,23 @@ describe('Factory plugin files', () => {
   });
 });
 
+// ─── Marketplace wiring ─────────────────────────────────────────────
+
+// Droid reads .factory-plugin/marketplace.json before .claude-plugin's, so this
+// is what makes `droid plugin install` deliver this Factory plugin instead of
+// the translated Claude one (Bash matcher, gitnexus@latest MCP).
+describe('Factory marketplace wiring', () => {
+  const marketplace = JSON.parse(
+    fs.readFileSync(path.join(REPO_ROOT, '.factory-plugin', 'marketplace.json'), 'utf-8'),
+  );
+
+  it('exposes a single gitnexus plugin sourced from ./gitnexus-factory-plugin', () => {
+    const entries = marketplace.plugins.filter((p: { name: string }) => p.name === 'gitnexus');
+    expect(entries).toHaveLength(1);
+    expect(entries[0].source).toBe('./gitnexus-factory-plugin');
+  });
+});
+
 // ─── Drift guard: bundled guards === canonical Claude copies ─────────
 
 describe('Factory plugin bundled guards stay in lockstep with the Claude adapter', () => {
diff --git a/gitnexus/test/unit/sync-plugin-manifests.test.ts b/gitnexus/test/unit/sync-plugin-manifests.test.ts
index b750e879d..39296f29c 100644
--- a/gitnexus/test/unit/sync-plugin-manifests.test.ts
+++ b/gitnexus/test/unit/sync-plugin-manifests.test.ts
@@ -10,6 +10,7 @@ const SURFACES = [
   'gitnexus-claude-plugin/.codex-plugin/plugin.json',
   '.agents/plugins/marketplace.json',
   'gitnexus-factory-plugin/.factory-plugin/plugin.json',
+  '.factory-plugin/marketplace.json',
 ] as const;
 
 const FACTORY_MCP = 'gitnexus-factory-plugin/mcp.json';
@@ -60,6 +61,10 @@ function makeRoot(packageVersion: string, manifestVersion: string): string {
     plugins: [{ name: 'gitnexus', version: manifestVersion, category: 'Developer Tools' }],
   });
   writeJson(root, SURFACES[4], { name: 'gitnexus', version: manifestVersion });
+  writeJson(root, SURFACES[5], {
+    name: 'gitnexus-marketplace',
+    plugins: [{ name: 'gitnexus', version: manifestVersion, source: './gitnexus-factory-plugin' }],
+  });
   for (const dir of [...MCP_SKILL_DIRS.map(mcpPath), FACTORY_MCP]) {
     writeJson(root, dir, {
       mcpServers: {