@sdsrs/code-graph 0.31.0 → 0.32.3

package/claude-plugin/scripts/lifecycle.test.js

@@ -266,11 +266,52 @@ test('statusline-chain CLI register/unregister/list + reserved-id guard', (t) =>
   assert.match(un, /unregistered gsd/);
 });
 
-test('install() removes legacy code-graph hooks from settings.json without re-registering', (t) => {
+// ════════════════════════════════════════════════════════════════════
+// v0.32.0 — settings.json hook registration (replaces the v0.8.3 strip)
+// ════════════════════════════════════════════════════════════════════
+
+test('install() registers PreToolUse/PostToolUse/UserPromptSubmit hooks in settings.json', (t) => {
   const homeDir = mkHome(t);
   const settingsPath = path.join(homeDir, '.claude', 'settings.json');
   writeJson(settingsPath, {
     statusLine: { type: 'command', command: 'echo previous-status' },
+  });
+
+  execFileSync(process.execPath, [lifecyclePath, 'install'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+
+  const after = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  assert.ok(after.hooks, 'install() must add hooks block');
+  assert.ok(after.hooks.PreToolUse, 'PreToolUse must be registered');
+  assert.ok(after.hooks.PostToolUse, 'PostToolUse must be registered');
+  assert.ok(after.hooks.UserPromptSubmit, 'UserPromptSubmit must be registered');
+
+  // Verify the matchers we promised exist
+  const ptuMatchers = after.hooks.PreToolUse.map(e => e.matcher);
+  for (const m of ['Edit', 'Bash', 'Read']) {
+    assert.ok(ptuMatchers.includes(m), `PreToolUse matcher ${m} missing; got ${JSON.stringify(ptuMatchers)}`);
+  }
+
+  // Every registered entry must carry the description marker for cleanup
+  for (const entries of Object.values(after.hooks)) {
+    for (const e of entries) {
+      if (e.description) {
+        assert.ok(e.description.includes('[code-graph-mcp'),
+          `entry without our marker leaked through: ${JSON.stringify(e.description)}`);
+      }
+    }
+  }
+
+  // statusLine composite still set
+  assert.match(after.statusLine.command, /statusline-composite/);
+});
+
+test('install() strips legacy code-graph hooks AND writes fresh ones (migration path)', (t) => {
+  const homeDir = mkHome(t);
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+  // Seed with v0.8.2-era legacy entries that should be cleaned up
+  writeJson(settingsPath, {
     hooks: legacyHooksFromPlugin(),
   });
 
@@ -279,10 +320,344 @@ test('install() removes legacy code-graph hooks from settings.json without re-re
   });
 
   const after = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-  // No code-graph hook entries should remain — cache hooks.json is authoritative now.
+  // Legacy stale paths should be gone — no `/stale/cache/0.8.2/` survivors
   const serialized = JSON.stringify(after.hooks || {});
-  assert.ok(!serialized.includes('code-graph'), 'settings.json must not retain code-graph hook entries');
-  assert.ok(!serialized.includes('session-init.js'), 'settings.json must not retain session-init.js paths');
-  // StatusLine composite is still registered (only channel available).
-  assert.match(after.statusLine.command, /statusline-composite/);
+  assert.ok(!serialized.includes('/stale/cache/'),
+    'legacy stale paths must be evicted: ' + serialized);
+  // BUT fresh entries (v0.32.0 markers) should be present
+  assert.ok(serialized.includes('[code-graph-mcp v0.32+]'),
+    'fresh v0.32+ entries should be installed');
+});
+
+test('install() is idempotent on settings.json (second call no-op)', (t) => {
+  const homeDir = mkHome(t);
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+
+  execFileSync(process.execPath, [lifecyclePath, 'install'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+  const first = fs.readFileSync(settingsPath, 'utf8');
+
+  execFileSync(process.execPath, [lifecyclePath, 'install'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+  const second = fs.readFileSync(settingsPath, 'utf8');
+
+  assert.equal(first, second, 'second install() must produce byte-identical settings.json');
+});
+
+test('install() preserves foreign plugin hooks (other plugins\' entries survive)', (t) => {
+  const homeDir = mkHome(t);
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+  // Seed with an unrelated plugin's hooks alongside ours
+  writeJson(settingsPath, {
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Bash',
+        description: 'some-other-plugin Bash inspector',
+        hooks: [{ type: 'command', command: 'node /opt/other-plugin/bash-check.js', timeout: 3 }],
+      }],
+      PostToolUse: [{
+        matcher: '*',
+        description: 'foreign post-tool logger',
+        hooks: [{ type: 'command', command: 'bash /opt/foreign/post.sh', timeout: 5 }],
+      }],
+    },
+  });
+
+  execFileSync(process.execPath, [lifecyclePath, 'install'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+
+  const after = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  // Foreign entries must still be there
+  const ptu = after.hooks.PreToolUse;
+  const otherBash = ptu.find(e => e.description === 'some-other-plugin Bash inspector');
+  assert.ok(otherBash, 'foreign Bash hook was stripped — never strip non-code-graph entries');
+
+  const ptoFor = after.hooks.PostToolUse.find(e => e.description === 'foreign post-tool logger');
+  assert.ok(ptoFor, 'foreign PostToolUse hook was stripped');
+
+  // Ours are also there
+  assert.ok(after.hooks.PreToolUse.some(e => e.matcher === 'Edit' && e.description?.includes('[code-graph-mcp')));
+});
+
+test('registerHooksToSettings is idempotent when called directly', () => {
+  // Pure-function direct call, no process spawn
+  const { registerHooksToSettings } = require('./lifecycle.js');
+  const settings = {};
+  const changed1 = registerHooksToSettings(settings);
+  const snapshot1 = JSON.stringify(settings);
+  const changed2 = registerHooksToSettings(settings);
+  const snapshot2 = JSON.stringify(settings);
+  assert.equal(changed1, true, 'first call must report change');
+  assert.equal(changed2, false, 'second call must report no-change (idempotent)');
+  assert.equal(snapshot1, snapshot2, 'settings must be byte-identical after second call');
+});
+
+test('removeHooksFromSettings cleans up v0.32+ entries (uninstall path)', () => {
+  const { registerHooksToSettings, removeHooksFromSettings } = require('./lifecycle.js');
+  const settings = {};
+  registerHooksToSettings(settings);
+  // Sanity: have entries
+  assert.ok(settings.hooks.PreToolUse && settings.hooks.PreToolUse.length > 0);
+
+  const changed = removeHooksFromSettings(settings);
+  assert.equal(changed, true);
+  assert.ok(!settings.hooks || Object.keys(settings.hooks).length === 0,
+    'all our entries must be removed; got: ' + JSON.stringify(settings.hooks));
+});
+
+test('uninstall() removes settings.json hook entries end-to-end', (t) => {
+  const homeDir = mkHome(t);
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+
+  execFileSync(process.execPath, [lifecyclePath, 'install'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+  const afterInstall = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  assert.ok(afterInstall.hooks?.PreToolUse, 'install must have created hooks');
+
+  execFileSync(process.execPath, [lifecyclePath, 'uninstall'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+  const afterUninstall = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  // Our hooks should be gone (foreign ones would survive but we didn't seed any)
+  const serialized = JSON.stringify(afterUninstall.hooks || {});
+  assert.ok(!serialized.includes('[code-graph-mcp'),
+    'uninstall must strip all our entries; got: ' + serialized);
+});
+
+test('hook commands use absolute paths (no ${CLAUDE_PLUGIN_ROOT} in settings.json)', (t) => {
+  // settings.json hook commands run with env-pollution risk per
+  // feedback_plugin_env_isolation.md — they must NOT depend on
+  // ${CLAUDE_PLUGIN_ROOT} (different plugins overwrite each other's value).
+  const homeDir = mkHome(t);
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+
+  execFileSync(process.execPath, [lifecyclePath, 'install'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+  const after = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  const serialized = JSON.stringify(after.hooks || {});
+  assert.ok(!serialized.includes('${CLAUDE_PLUGIN_ROOT}'),
+    'settings.json hook commands must not reference ${CLAUDE_PLUGIN_ROOT}: ' + serialized);
+});
+
+// ════════════════════════════════════════════════════════════════════
+// v0.32.2 — update() upgrade-path integration tests (reviewer Rec #2)
+// ════════════════════════════════════════════════════════════════════
+// Covers the actual v0.31.x → v0.32.x migration path that runs in
+// production via session-init.js syncLifecycleConfig detecting a manifest
+// version mismatch and calling update(). Previously only install() was
+// tested end-to-end; the upgrade path shared the registerHooksToSettings
+// code internally but had no integration test exercising the wiring.
+
+test('update() from v0.31.x manifest registers fresh hooks in empty settings.json', (t) => {
+  const homeDir = mkHome(t);
+  const manifestPath = path.join(homeDir, '.cache', 'code-graph', 'install-manifest.json');
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+
+  // Seed v0.31.2 manifest state. updatedAt is the v0.31.2 release date.
+  writeJson(manifestPath, {
+    version: '0.31.2',
+    installedAt: '2026-03-16T18:56:17.656Z',
+    updatedAt: '2026-05-23T16:46:39.353Z',
+    config: { statusLine: false },
+  });
+  // settings.json empty (mirrors real v0.31.x state — pre-v0.32.0 strategy
+  // was "strip from settings.json, rely on plugin-cache hooks.json").
+  writeJson(settingsPath, {});
+
+  const out = execFileSync(process.execPath, [lifecyclePath, 'update'], {
+    env: { ...process.env, HOME: homeDir },
+  }).toString();
+  assert.match(out, /Updated 0\.31\.2 → /, 'CLI output must show version transition');
+
+  // Manifest version was bumped to current
+  const manifestAfter = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  assert.notEqual(manifestAfter.version, '0.31.2', 'manifest version must advance');
+  assert.ok(/^\d+\.\d+\.\d+$/.test(manifestAfter.version),
+    `manifest version must be semver, got ${manifestAfter.version}`);
+
+  // settings.json got the v0.32+ hook entries
+  const settingsAfter = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  assert.ok(settingsAfter.hooks, 'update() must populate hooks block');
+  assert.ok(settingsAfter.hooks.PreToolUse, 'PreToolUse must be registered');
+  assert.ok(settingsAfter.hooks.PostToolUse, 'PostToolUse must be registered');
+  assert.ok(settingsAfter.hooks.UserPromptSubmit, 'UserPromptSubmit must be registered');
+
+  // Every entry must carry the v0.32+ marker
+  for (const entries of Object.values(settingsAfter.hooks)) {
+    for (const e of entries) {
+      assert.ok(e.description && e.description.includes('[code-graph-mcp v0.32+'),
+        `update() entry without v0.32+ marker: ${JSON.stringify(e.description)}`);
+    }
+  }
+});
+
+test('update() from v0.31.x evicts legacy v0.7/v0.8 entries with stale paths', (t) => {
+  const homeDir = mkHome(t);
+  const manifestPath = path.join(homeDir, '.cache', 'code-graph', 'install-manifest.json');
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+
+  writeJson(manifestPath, {
+    version: '0.31.2',
+    installedAt: '2026-03-16T18:56:17.656Z',
+    config: { statusLine: false },
+  });
+  // Seed with legacy v0.8.2-era entries that should be evicted on update.
+  writeJson(settingsPath, {
+    hooks: legacyHooksFromPlugin(),
+  });
+
+  execFileSync(process.execPath, [lifecyclePath, 'update'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+
+  const settingsAfter = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  const serialized = JSON.stringify(settingsAfter.hooks || {});
+  // Stale paths must be gone
+  assert.ok(!serialized.includes('/stale/cache/'),
+    'legacy stale paths must be evicted by update(): ' + serialized);
+  // Fresh v0.32+ entries must be present
+  assert.ok(serialized.includes('[code-graph-mcp v0.32+'),
+    'fresh v0.32+ entries must be installed by update()');
+});
+
+test('update() preserves foreign plugin hooks during upgrade', (t) => {
+  const homeDir = mkHome(t);
+  const manifestPath = path.join(homeDir, '.cache', 'code-graph', 'install-manifest.json');
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+
+  writeJson(manifestPath, {
+    version: '0.31.2',
+    config: { statusLine: false },
+  });
+  // Seed with an unrelated plugin's hooks — must survive our update().
+  writeJson(settingsPath, {
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Bash',
+        description: 'foreign-plugin Bash watcher',
+        hooks: [{ type: 'command', command: 'node /opt/foreign/bash.js', timeout: 3 }],
+      }],
+    },
+  });
+
+  execFileSync(process.execPath, [lifecyclePath, 'update'], {
+    env: { ...process.env, HOME: homeDir },
+  });
+
+  const settingsAfter = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  const ptu = settingsAfter.hooks.PreToolUse;
+  assert.ok(ptu.some(e => e.description === 'foreign-plugin Bash watcher'),
+    'foreign Bash hook must survive update() — never strip non-code-graph entries');
+  // And our own entries must coexist
+  assert.ok(ptu.some(e => e.description && e.description.includes('[code-graph-mcp v0.32+')),
+    'update() must add our v0.32+ entries alongside the foreign one');
+});
+
+// ════════════════════════════════════════════════════════════════════
+// v0.32.2 — healthCheck post-repair re-verification
+// (Reviewer M3: repaired:true was set blindly after install() without
+//  re-scanning to confirm the issues actually resolved.)
+// ════════════════════════════════════════════════════════════════════
+
+function runHealthCheckInChild(homeDir) {
+  const code = `
+    const lc = require(${JSON.stringify(lifecyclePath)});
+    process.stdout.write(JSON.stringify(lc.healthCheck()));
+  `;
+  const out = execFileSync(process.execPath, ['-e', code], {
+    env: { ...process.env, HOME: homeDir },
+    encoding: 'utf8',
+  });
+  return JSON.parse(out);
+}
+
+test('healthCheck on a clean state returns healthy:true and never sets remaining', (t) => {
+  const homeDir = mkHome(t);
+  // No settings.json, no registry — clean slate.
+  const r = runHealthCheckInChild(homeDir);
+  assert.equal(r.healthy, true, 'fresh empty state must be healthy');
+  assert.deepEqual(r.issues, [], 'no issues on empty state');
+  assert.equal(r.repaired, false, 'no repair runs when nothing was broken');
+  assert.equal(r.remaining, undefined, 'no remaining field when no repair attempted');
+});
+
+test('healthCheck repaired:true ONLY after post-repair re-scan returns clean', (t) => {
+  const homeDir = mkHome(t);
+  // Seed a hook entry whose path is broken AND carries our marker. install()
+  // will overwrite our entries with fresh absolute paths derived from
+  // __dirname (which is real in the test env), so the re-scan should be clean.
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+  writeJson(settingsPath, {
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Edit',
+        description: '[code-graph-mcp v0.32+] PreToolUse re-routed via settings.json (cache hooks.json silently ignored for this event by current CC)',
+        hooks: [{ type: 'command', command: 'node "/nonexistent/code-graph-mcp/pre-edit-guide.js"' }],
+      }],
+    },
+  });
+
+  const r = runHealthCheckInChild(homeDir);
+  assert.equal(r.healthy, false, 'pre-repair scan must have flagged the broken path');
+  assert.ok(r.issues.length >= 1, 'pre-repair issues must list the broken hook');
+  assert.equal(r.repaired, true, 'install() rewrote our entry → post-scan clean → repaired:true');
+  assert.deepEqual(r.remaining, [], 'remaining must be empty when repair succeeded');
+});
+
+test('healthCheck repaired:false when install() cannot resolve a flagged path', (t) => {
+  const homeDir = mkHome(t);
+  // Seed the registry with a non-`_previous` third-party provider whose path
+  // is broken. install() only manages the 'code-graph' registry entry, so
+  // the third-party entry survives untouched and the post-repair re-scan
+  // still flags it. This is the canonical "auto-repair could not fix it"
+  // path — previously the function lied and returned repaired:true anyway.
+  const registryPath = path.join(homeDir, '.cache', 'code-graph', 'statusline-registry.json');
+  writeJson(registryPath, [
+    { id: 'third-party-statusline', command: 'node "/nonexistent/foreign/sl.js"', needsStdin: false },
+  ]);
+
+  const r = runHealthCheckInChild(homeDir);
+  assert.equal(r.healthy, false, 'broken third-party path must be flagged on entry');
+  assert.ok(r.issues.some(i => i.type === 'registry' && i.id === 'third-party-statusline'),
+    'pre-repair issue list must contain the third-party entry');
+  assert.equal(r.repaired, false,
+    'install() does not touch third-party providers → re-scan still broken → repaired must be false');
+  assert.ok(Array.isArray(r.remaining), 'remaining must be present when install() was attempted');
+  assert.ok(r.remaining.some(i => i.id === 'third-party-statusline'),
+    'remaining must still contain the un-fixable third-party entry');
+});
+
+test('scanForBrokenPaths is exported and returns the issue structure', (t) => {
+  // Direct unit test of the extracted scanner — no install() side effects.
+  // Verifies the contract M3 relies on: a pure function whose return
+  // shape is what healthCheck composes its result from.
+  const homeDir = mkHome(t);
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+  writeJson(settingsPath, {
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Edit',
+        description: '[code-graph-mcp v0.32+] PreToolUse re-routed via settings.json (cache hooks.json silently ignored for this event by current CC)',
+        hooks: [{ type: 'command', command: 'node "/nonexistent/code-graph-mcp/pre-edit-guide.js"' }],
+      }],
+    },
+  });
+
+  const code = `
+    const lc = require(${JSON.stringify(lifecyclePath)});
+    process.stdout.write(JSON.stringify(lc.scanForBrokenPaths()));
+  `;
+  const out = execFileSync(process.execPath, ['-e', code], {
+    env: { ...process.env, HOME: homeDir },
+    encoding: 'utf8',
+  });
+  const issues = JSON.parse(out);
+  assert.ok(Array.isArray(issues));
+  assert.ok(issues.some(i => i.type === 'hook' && i.event === 'PreToolUse' && i.path.includes('/nonexistent/')),
+    'scanForBrokenPaths must report the seeded broken hook entry');
 });

package/claude-plugin/scripts/mcp-launcher.js

@@ -15,6 +15,79 @@ const fs = require('fs');
 // Always derive from __dirname — CLAUDE_PLUGIN_ROOT can leak from other plugins
 process.env._FIND_BINARY_ROOT = path.resolve(__dirname, '..');
 
+// --- Tool-catalog dedup gate -----------------------------------------------
+// If the user's project has its own .mcp.json registering a code-graph server
+// (the recommended pattern for dev work on this repo — points at a local
+// `target/release/code-graph-mcp` so usage telemetry lands in the project's
+// `.code-graph/usage.jsonl`), the plugin's own MCP server adds a SECOND copy
+// of the same 7 tools to the catalog, costing context budget and splitting
+// the agent's choice between two equivalent namespaces.
+//
+// Detect that case and serve a minimal "0-tools" MCP stub so this plugin
+// stops contributing to the catalog. Hooks, skills, agents stay registered
+// (they live outside the MCP server). Env override
+// `CODE_GRAPH_FORCE_PLUGIN_MCP=1` bypasses the gate.
+function projectHasLocalCodeGraphMcp(cwd) {
+  try {
+    const p = path.join(cwd, '.mcp.json');
+    if (!fs.existsSync(p)) return false;
+    const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const servers = (cfg && cfg.mcpServers) || {};
+    return Object.keys(servers).some(n => /code[-_]?graph/i.test(n));
+  } catch { return false; }
+}
+
+function serveEmptyMcpStub() {
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let req;
+      try { req = JSON.parse(line); } catch { continue; }
+      if (!req || typeof req.method !== 'string') continue;
+      // JSON-RPC notifications (id missing) get no response.
+      if (typeof req.id === 'undefined') continue;
+      const method = req.method;
+      let result, error;
+      if (method === 'initialize') {
+        result = {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'code-graph-mcp (plugin stub, dedup)', version: '0.31.1' },
+        };
+      } else if (method === 'tools/list') {
+        result = { tools: [] };
+      } else if (method === 'resources/list') {
+        result = { resources: [] };
+      } else if (method === 'prompts/list') {
+        result = { prompts: [] };
+      } else {
+        error = { code: -32601, message: 'method not found (plugin MCP is in dedup stub mode)' };
+      }
+      const resp = error
+        ? { jsonrpc: '2.0', id: req.id, error }
+        : { jsonrpc: '2.0', id: req.id, result };
+      process.stdout.write(JSON.stringify(resp) + '\n');
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+}
+
+if (process.env.CODE_GRAPH_FORCE_PLUGIN_MCP !== '1' && projectHasLocalCodeGraphMcp(process.cwd())) {
+  process.stderr.write(
+    '[code-graph] project .mcp.json registers a code-graph server; ' +
+    'plugin MCP serving 0 tools to avoid duplicate catalog entries. ' +
+    'Set CODE_GRAPH_FORCE_PLUGIN_MCP=1 to override.\n'
+  );
+  serveEmptyMcpStub();
+  return; // top-level function scope of mcp-launcher.js
+}
+
 const { findBinary, clearCache } = require('./find-binary');
 
 let binary = findBinary();

package/claude-plugin/scripts/mcp-launcher.test.js

@@ -33,11 +33,11 @@ function hasBuiltBinary() {
  * Run the launcher, send one MCP message on stdin, collect stdout/stderr,
  * resolve once we either see a JSON-RPC response on stdout or hit timeout.
  */
-function runLauncherInitialize(timeoutMs = 15000) {
+function runLauncherInitialize(timeoutMs = 15000, extraEnv = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [LAUNCHER], {
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env },
+      env: { ...process.env, ...extraEnv },
       cwd: REPO_ROOT,
     });
 
@@ -80,7 +80,11 @@ test('mcp-launcher resolves dev binary and forwards MCP JSON-RPC stdin/stdout',
     return;
   }
 
-  const { stdout, stderr } = await runLauncherInitialize();
+  // REPO_ROOT has its own .mcp.json registering code-graph-dev (v0.31.2
+  // landed that to capture dev session metrics), which trips the launcher's
+  // dedup gate. Force the original launch path so this test still covers
+  // it. The dedup behavior gets its own test below.
+  const { stdout, stderr } = await runLauncherInitialize(15000, { CODE_GRAPH_FORCE_PLUGIN_MCP: '1' });
 
   // Find the JSON-RPC line in the bytes the launcher forwarded from the binary.
   // Stderr may contain "[code-graph] ..." breadcrumbs from the launcher; those
@@ -95,6 +99,22 @@ test('mcp-launcher resolves dev binary and forwards MCP JSON-RPC stdin/stdout',
   assert.equal(resp.result.serverInfo.name, 'code-graph-mcp');
 });
 
+test('mcp-launcher enters dedup stub when project .mcp.json registers a code-graph server', async () => {
+  // REPO_ROOT/.mcp.json registers code-graph-dev → dedup gate fires →
+  // launcher serves a 0-tools stub with a distinctive serverInfo.name.
+  // No need for the release binary; the stub is implemented in the
+  // launcher script itself.
+  const { stdout, stderr } = await runLauncherInitialize();
+  const respLine = stdout.trim().split('\n').find((l) => l.includes('"result"'));
+  assert.ok(respLine,
+    `expected stub JSON-RPC result on stdout, got: ${stdout.slice(0, 400)} | stderr: ${stderr.slice(0, 400)}`);
+  const resp = JSON.parse(respLine);
+  assert.match(resp.result.serverInfo.name, /stub|dedup/i,
+    `serverInfo.name should indicate stub mode, got ${JSON.stringify(resp.result.serverInfo)}`);
+  assert.match(stderr, /plugin MCP serving 0 tools/,
+    `stderr should explain the dedup, got: ${stderr.slice(0, 400)}`);
+});
+
 test('mcp-launcher sets _FIND_BINARY_ROOT from __dirname (does not trust CLAUDE_PLUGIN_ROOT)', () => {
   // Static check: the source must derive _FIND_BINARY_ROOT from __dirname so a
   // sibling plugin's CLAUDE_PLUGIN_ROOT can't redirect us to the wrong binary.

package/claude-plugin/scripts/pre-edit-guide.js

@@ -9,12 +9,19 @@
 const { execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
+const { findBinary } = require('./find-binary');
+const { cgTmpDir } = require('./tmp-dir');
 
 const cwd = process.cwd();
 const dbPath = path.join(cwd, '.code-graph', 'index.db');
 if (!fs.existsSync(dbPath)) process.exit(0);
 
+// Resolve binary the same way the other hooks do — bare PATH lookup misses
+// npm-global installs on systems where the global bin dir isn't on PATH for
+// non-login shells (a real failure mode reported in mem #8187).
+const binary = findBinary();
+if (!binary) process.exit(0);
+
 // --- Parse tool input ---
 let input;
 try {
@@ -63,7 +70,7 @@ if (!symbol || symbol.length < 3) {
         .sort((a, b) => b.length - a.length);
       for (const candidate of candidates.slice(0, 5)) {
         try {
-          const raw = execFileSync('code-graph-mcp', ['grep', candidate, filePath, '--json'], {
+          const raw = execFileSync(binary, ['grep', candidate, filePath, '--json'], {
             cwd, timeout: 2000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
           });
           const grepResult = JSON.parse(raw);
@@ -98,15 +105,24 @@ function isCommonKeyword(s) {
 }
 
 // --- Per-symbol cooldown: 2 minutes ---
-const cooldownFile = path.join(os.tmpdir(), `.cg-impact-${symbol}`);
+const cooldownFile = path.join(cgTmpDir(), `.cg-impact-${symbol}`);
 try {
   if (Date.now() - fs.statSync(cooldownFile).mtimeMs < 120000) process.exit(0);
 } catch { /* first time for this symbol */ }
 
 // --- Run impact analysis (JSON mode for programmatic parsing) ---
+// Disambiguate via --file: file_path from tool_input is absolute, but the
+// indexer stores files as repo-relative paths — converting here is what makes
+// short generic symbol names (open, new, create, parse, from, init) resolve
+// to a unique node instead of triggering the CLI's "Ambiguous symbol" error
+// path, which previously caused silent exits for the most common edit cases.
+const editedFile = (input.tool_input && input.tool_input.file_path) || '';
+const relFile = editedFile ? path.relative(cwd, editedFile) : '';
 let jsonResult;
 try {
-  const raw = execFileSync('code-graph-mcp', ['impact', symbol, '--json'], {
+  const args = ['impact', symbol, '--json'];
+  if (relFile && !relFile.startsWith('..')) args.push('--file', relFile);
+  const raw = execFileSync('code-graph-mcp', args, {
     cwd,
     timeout: 2500,
     encoding: 'utf8',
@@ -118,6 +134,10 @@ try {
   process.exit(0);
 }
 
+// CLI returns {"error": "..."} on ambiguous / not-found instead of throwing.
+// Treat as silent skip — direct_callers will be undefined.
+if (jsonResult && jsonResult.error) process.exit(0);
+
 // --- Inject when the symbol has any caller (1+) ---
 // Earlier gate was 2+ direct callers; reality is that editing a function with
 // even one production caller benefits from a one-line impact summary, and the