@sdsrs/code-graph 0.48.0 → 0.50.0

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.48.0",
+  "version": "0.50.0",
   "keywords": [
     "code-graph",
     "ast",

package/claude-plugin/scripts/adopt.js

@@ -45,8 +45,8 @@ const INDEX_LINE =
   '- [code-graph-mcp](plugin_code_graph_mcp.md) ' +
   '[impact-analysis, callgraph, find-references, module-overview, semantic-search, ast-search, dead-code, find-similar-code, dependency-graph, trace-http-chain] — ' +
   '改 X 影响面/谁调用 X/X 被谁用/看 X 源码/Y 模块长啥样/概念查询 优先于 Grep；字面匹配走 Grep。' +
-  '核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map）' +
-  '+ 进阶 5（impact_analysis/trace_http_chain/dependency_graph/find_similar_code/find_dead_code），决策表见全文';
+  'Bash 直呼 CLI 最快（零加载）：`code-graph-mcp callgraph X / show X / overview <dir> / grep "pat" / impact X`；' +
+  'MCP 核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map），决策表见全文';
 
 // memdir L1 升格 (per sdscc 重构方案 §5.0): the INDEX_LINE that lands in
 // MEMORY.md is what Claude sees first on every keyword match. Tailoring it
@@ -234,9 +234,12 @@ function detectProjectType(cwd = process.cwd(), env = process.env) {
 // most for THIS project.
 function buildIndexLine(projectType = 'generic') {
   const prefix = '- [code-graph-mcp](plugin_code_graph_mcp.md) ';
+  // v0.49 — CLI form leads: in Claude Code the MCP tools are deferred (need a
+  // ToolSearch load before first call) while Bash is always live; the only
+  // conversions observed in real coding nights were CLI invocations.
   const coreSuffix =
-    '核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map）' +
-    '+ 进阶 5（impact_analysis/trace_http_chain/dependency_graph/find_similar_code/find_dead_code），决策表见全文';
+    'Bash 直呼 CLI 最快（零加载）：`code-graph-mcp callgraph X / show X / overview <dir> / grep "pat" / impact X`；' +
+    'MCP 核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map），决策表见全文';
   switch (projectType) {
     case 'web-rs':
     case 'web-node':

package/claude-plugin/scripts/auto-update.js

@@ -6,6 +6,7 @@ const https = require('https');
 const path = require('path');
 const os = require('os');
 const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
+const { claudeHome } = require('./claude-config');
 const { clearCache: clearBinaryCache } = require('./find-binary');
 const { readBinaryVersion, isDevMode } = require('./version-utils');
 const { cgTmpDir } = require('./tmp-dir');
@@ -277,9 +278,41 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion) {
   }
 }
 
+// ── Marketplace clone refresh ──────────────────────────────
+
+function marketplaceCloneDir() {
+  return path.join(claudeHome(), 'plugins', 'marketplaces', MARKETPLACE_NAME);
+}
+
+/**
+ * Fast-forward the Claude Code marketplace clone after a plugin update.
+ *
+ * Auto-update writes the plugin cache + installed_plugins.json directly and
+ * never touched the marketplace clone, so its marketplace.json stayed pinned
+ * at the version present when the user last ran a /plugin command (observed
+ * live: clone at 0.48.0 four days after 0.49.0 shipped). A stale clone makes
+ * the /plugin UI report the old version and lets Claude Code re-install the
+ * old plugin files from it. --ff-only + silent failure: a dirty or diverged
+ * clone is Claude Code's property — never force anything there.
+ */
+function refreshMarketplaceClone({ dir = marketplaceCloneDir(), exec = execFileSync, timeoutMs = 15000 } = {}) {
+  try {
+    if (!fs.existsSync(path.join(dir, '.git'))) return false;
+    if (!commandExists('git')) return false;
+    exec('git', ['-C', dir, 'pull', '--ff-only', '--quiet'], { timeout: timeoutMs, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ── Download & Install ─────────────────────────────────────
 
-async function downloadAndInstall(latest) {
+async function downloadAndInstall(latest, {
+  exec = execFileSync,
+  downloadBin = downloadBinary,
+  refreshMarketplace = refreshMarketplaceClone,
+} = {}) {
   // Pre-flight: check required CLI tools before attempting any download
   const missingTools = ['curl', 'tar'].filter(cmd => !commandExists(cmd));
   if (missingTools.length > 0) {
@@ -290,19 +323,20 @@ async function downloadAndInstall(latest) {
   const tmpDir = path.join(cgTmpDir(), `update-${Date.now()}`);
   let pluginUpdated = false;
   let binaryUpdated = false;
+  let marketplaceRefreshed = false;
 
   try {
     fs.mkdirSync(tmpDir, { recursive: true });
 
     // ── Step 1: Download and install plugin files from tarball ──
     const tarballPath = path.join(tmpDir, 'release.tar.gz');
-    execFileSync('curl', [
+    exec('curl', [
       '-sL', '-o', tarballPath,
       '-H', 'Accept: application/vnd.github+json',
       latest.tarballUrl,
     ], { timeout: 30000, stdio: 'pipe' });
 
-    execFileSync('tar', [
+    exec('tar', [
       'xzf', tarballPath, '-C', tmpDir, '--strip-components=1',
     ], { timeout: 15000, stdio: 'pipe' });
 
@@ -344,22 +378,28 @@ async function downloadAndInstall(latest) {
       try {
         const newLifecycle = path.join(pluginDst, 'scripts', 'lifecycle.js');
         if (fs.existsSync(newLifecycle)) {
-          execFileSync(process.execPath, [newLifecycle, 'update'], {
+          exec(process.execPath, [newLifecycle, 'update'], {
             timeout: 5000, stdio: 'pipe',
           });
         }
       } catch { /* not fatal — syncLifecycleConfig will self-heal on next session */ }
     }
 
+    // ── Step 1.5: Fast-forward the marketplace clone so /plugin UI and any
+    //    Claude-Code-side reinstall see the version we just installed.
+    if (pluginUpdated) {
+      marketplaceRefreshed = refreshMarketplace();
+    }
+
     // ── Step 2: Download platform binary directly from GitHub release ──
-    if (await downloadBinary(latest)) {
+    if (await downloadBin(latest)) {
       binaryUpdated = true;
     }
 
-    return { pluginUpdated, binaryUpdated };
+    return { pluginUpdated, binaryUpdated, marketplaceRefreshed };
   } catch (e) {
     console.error(`[code-graph] Plugin download/extract failed: ${e.message}`);
-    return { pluginUpdated: false, binaryUpdated: false };
+    return { pluginUpdated: false, binaryUpdated: false, marketplaceRefreshed };
   } finally {
     try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ok */ }
   }
@@ -431,6 +471,7 @@ async function checkForUpdate({ installMissing = false } = {}) {
         lastUpdate: success ? new Date().toISOString() : state.lastUpdate,
         rateLimited: false,
         binaryUpdated: result.binaryUpdated,
+        marketplaceRefreshed: result.marketplaceRefreshed,
       };
       saveState(newState);
 
@@ -474,6 +515,7 @@ module.exports = {
   requestJson, parseLatestRelease, fetchLatestRelease,
   downloadBinary, cachedBinaryPath, cachedBinaryNeedsUpdate, cachedBinaryStaleVsState,
   selfHealStaleBinary,
+  downloadAndInstall, refreshMarketplaceClone, marketplaceCloneDir,
 };
 
 // CLI: node auto-update.js [check|status] [--silent] [--install-missing]

package/claude-plugin/scripts/auto-update.test.js

@@ -247,4 +247,96 @@ test('fetchLatestRelease parses JSON without relying on global fetch', async ()
 
   assert.equal(latest.version, '2.0.0');
   assert.equal(latest.tarballUrl, 'https://example.com/release.tgz');
-});
+});
+// ── refreshMarketplaceClone (v0.49.1 marketplace-staleness fix) ────────────
+
+const { execFileSync: execGit } = require('child_process');
+const { refreshMarketplaceClone, downloadAndInstall } = require('./auto-update');
+
+function git(cwd, ...args) {
+  return execGit('git', ['-C', cwd, '-c', 'user.email=t@t', '-c', 'user.name=t', ...args],
+    { stdio: 'pipe', encoding: 'utf8' });
+}
+
+test('refreshMarketplaceClone fast-forwards a stale clone', (t) => {
+  const root = mkDir(t, 'code-graph-mp-');
+  const remote = path.join(root, 'remote');
+  const clone = path.join(root, 'clone');
+
+  fs.mkdirSync(remote);
+  git(remote, 'init', '-q', '-b', 'main');
+  fs.writeFileSync(path.join(remote, 'marketplace.json'), '{"version":"0.48.0"}');
+  git(remote, 'add', '.');
+  git(remote, 'commit', '-q', '-m', 'v0.48.0');
+  execGit('git', ['clone', '-q', remote, clone], { stdio: 'pipe' });
+
+  // Remote advances (a release bumped marketplace.json) — clone is now stale.
+  fs.writeFileSync(path.join(remote, 'marketplace.json'), '{"version":"0.49.0"}');
+  git(remote, 'commit', '-q', '-am', 'v0.49.0');
+
+  assert.equal(refreshMarketplaceClone({ dir: clone }), true);
+  assert.match(fs.readFileSync(path.join(clone, 'marketplace.json'), 'utf8'), /0\.49\.0/);
+});
+
+test('refreshMarketplaceClone is a safe no-op on non-git dirs and pull failures', (t) => {
+  const root = mkDir(t, 'code-graph-mp-');
+  // Not a git repo → false, no throw.
+  assert.equal(refreshMarketplaceClone({ dir: root }), false);
+  // Missing dir → false, no throw.
+  assert.equal(refreshMarketplaceClone({ dir: path.join(root, 'nope') }), false);
+  // exec throws (diverged / dirty clone) → false, no throw.
+  const fakeGitDir = path.join(root, 'repo');
+  fs.mkdirSync(path.join(fakeGitDir, '.git'), { recursive: true });
+  assert.equal(refreshMarketplaceClone({
+    dir: fakeGitDir,
+    exec: () => { throw new Error('not a fast-forward'); },
+  }), false);
+});
+
+test('downloadAndInstall wires the marketplace refresh + binary download (orchestration glue)', async (t) => {
+  // In-process with all side-effectful deps injected would still write the
+  // manifest into the REAL ~/.cache (CACHE_DIR is bound at module load), so
+  // run in a subprocess with a sandboxed HOME — same pattern as install-e2e.
+  const sandboxHome = mkDir(t, 'code-graph-dai-');
+  const script = `
+    const fs = require('fs');
+    const path = require('path');
+    const { downloadAndInstall } = require(${JSON.stringify(path.join(__dirname, 'auto-update.js'))});
+    const latest = { version: '9.9.9', tarballUrl: 'https://example/tar', binaryUrl: null };
+    const calls = [];
+    const exec = (cmd, args) => {
+      calls.push(cmd);
+      if (cmd === 'tar') {
+        // Simulate extraction: produce claude-plugin/ with a matching version.
+        const tmpDir = args[args.indexOf('-C') + 1];
+        const mDir = path.join(tmpDir, 'claude-plugin', '.claude-plugin');
+        fs.mkdirSync(mDir, { recursive: true });
+        fs.writeFileSync(path.join(mDir, 'plugin.json'), JSON.stringify({ version: '9.9.9' }));
+      }
+    };
+    (async () => {
+      let refreshed = 0;
+      let binDownloads = 0;
+      const result = await downloadAndInstall(latest, {
+        exec,
+        refreshMarketplace: () => { refreshed++; return true; },
+        downloadBin: async () => { binDownloads++; return true; },
+      });
+      console.log(JSON.stringify({ result, refreshed, binDownloads, calls }));
+    })();
+  `;
+  const out = execGit(process.execPath, ['-e', script], {
+    env: { ...process.env, HOME: sandboxHome },
+    encoding: 'utf8',
+  });
+  const { result, refreshed, binDownloads } = JSON.parse(out.trim().split('\n').pop());
+  assert.equal(result.pluginUpdated, true, 'plugin files must install from the extracted tarball');
+  assert.equal(refreshed, 1, 'marketplace refresh must run exactly once after a plugin update');
+  assert.equal(result.marketplaceRefreshed, true);
+  assert.equal(binDownloads, 1, 'binary download must run');
+  assert.equal(result.binaryUpdated, true);
+  // Plugin landed in the sandboxed cache, not the real one.
+  const dst = path.join(sandboxHome, '.claude', 'plugins', 'cache',
+    'code-graph-mcp', 'code-graph-mcp', '9.9.9', '.claude-plugin', 'plugin.json');
+  assert.equal(fs.existsSync(dst), true, 'plugin copied into sandbox plugins cache');
+});

package/claude-plugin/scripts/cg-answer.js

@@ -110,8 +110,20 @@ function runGrepAnswer(opts = {}) {
       encoding: 'utf8',
       maxBuffer: 4 * 1024 * 1024,
       stdio: ['ignore', 'pipe', 'ignore'],
+      // Hook-internal run: a delivered answer, not a model-initiated conversion.
+      // The CLI skips its recommendations.jsonl `use` record when this is set.
+      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
     });
-    if (res.error || res.signal || res.status !== 0) {
+    if (res.error || res.signal) {
+      return { status: 'unavailable' };
+    }
+    // v0.50 grep-parity exit codes: 0 = matched, 1 = no match, 2 = error.
+    // Older binaries exit 0 on no-match with the NO_MATCH_PREFIX on stderr
+    // (stdout empty) — both shapes resolve to 'no-hits' below.
+    if (res.status === 1) {
+      return { status: 'no-hits' };
+    }
+    if (res.status !== 0) {
       return { status: 'unavailable' };
     }
     const out = (res.stdout || '').trim();
@@ -125,4 +137,95 @@ function runGrepAnswer(opts = {}) {
   }
 }
 
-module.exports = { runGrepAnswer, truncateAtLine, sanitizeSearchPath };
+/**
+ * v0.49 — Run `code-graph-mcp show <symbol>` for up to 3 declaration symbols
+ * and concatenate the bodies. Powers the show-mode deny (declaration-anchor +
+ * context-flag greps: the model wants to READ the functions, so hand it the
+ * functions). Same bounded/best-effort posture as runGrepAnswer; symbols that
+ * fail to resolve are skipped, all-fail → no-hits (caller falls back to grep).
+ */
+function runShowAnswer(opts = {}) {
+  const {
+    cwd,
+    symbols,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxBytes = DEFAULT_MAX_BYTES,
+  } = opts;
+  try {
+    if (!Array.isArray(symbols) || symbols.length === 0) {
+      return { status: 'unavailable' };
+    }
+    let binary = opts.binary;
+    if (binary === undefined) {
+      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
+    }
+    if (!binary) return { status: 'unavailable' };
+
+    const parts = [];
+    for (const sym of symbols.slice(0, 3)) {
+      if (typeof sym !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sym)) continue;
+      const res = spawnSync(binary, ['show', sym], {
+        cwd,
+        timeout: timeoutMs,
+        encoding: 'utf8',
+        maxBuffer: 4 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
+      });
+      if (res.error || res.signal || res.status !== 0) continue;
+      const out = (res.stdout || '').trim();
+      if (!out || out.startsWith(NO_MATCH_PREFIX)) continue;
+      parts.push(`$ code-graph-mcp show ${sym}\n${out}`);
+    }
+    if (parts.length === 0) return { status: 'no-hits' };
+    const { text, truncated } = truncateAtLine(parts.join('\n\n'), maxBytes);
+    return { status: 'hits', text, truncated };
+  } catch {
+    return { status: 'unavailable' };
+  }
+}
+
+/**
+ * v0.49 — Run `code-graph-mcp overview <dir>` for the read-fanout hint, so the
+ * hint DELIVERS the module map instead of advising a tool call (hints measured
+ * 0/40 transfer on 2026-06-12; delivered answers satisfied 5/5 in place).
+ */
+function runOverviewAnswer(opts = {}) {
+  const {
+    cwd,
+    dir,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxBytes = DEFAULT_MAX_BYTES,
+  } = opts;
+  try {
+    if (!dir || typeof dir !== 'string' || dir.length > 300) {
+      return { status: 'unavailable' };
+    }
+    let binary = opts.binary;
+    if (binary === undefined) {
+      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
+    }
+    if (!binary) return { status: 'unavailable' };
+    const res = spawnSync(binary, ['overview', dir], {
+      cwd,
+      timeout: timeoutMs,
+      encoding: 'utf8',
+      maxBuffer: 4 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
+    });
+    if (res.error || res.signal || res.status !== 0) {
+      return { status: 'unavailable' };
+    }
+    const out = (res.stdout || '').trim();
+    if (!out || out.startsWith(NO_MATCH_PREFIX)) return { status: 'no-hits' };
+    const { text, truncated } = truncateAtLine(out, maxBytes);
+    return { status: 'hits', text, truncated };
+  } catch {
+    return { status: 'unavailable' };
+  }
+}
+
+module.exports = {
+  runGrepAnswer, runShowAnswer, runOverviewAnswer, truncateAtLine, sanitizeSearchPath,
+};

package/claude-plugin/scripts/cg-answer.test.js

@@ -4,7 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { runGrepAnswer, truncateAtLine } = require('./cg-answer');
+const { runGrepAnswer, runShowAnswer, truncateAtLine } = require('./cg-answer');
 
 // Stub "binary": a node script that reacts to its first real arg so one stub
 // covers hits / no-hits / error / timeout cases.
@@ -21,6 +21,9 @@ if (pattern === 'HangForever') { setTimeout(() => {}, 60000); }
 else if (pattern === 'ExplodePlease') { process.exit(3); }
 else if (pattern === 'NothingHere') {
   process.stdout.write('[code-graph] No matches for: NothingHere\\n');
+} else if (pattern === 'NothingHereExit1') {
+  // v0.50 grep-parity binary: no match → empty stdout + exit 1
+  process.exit(1);
 } else {
   process.stdout.write(
     'src/storage/db.rs:42  fn ' + pattern + '() {\\n' +
@@ -58,6 +61,19 @@ test('runGrepAnswer: passes grep subcommand, pattern and path as argv', () => {
   assert.match(r.text, /args=\["grep","fts5_search","src\/storage\/"\]/);
 });
 
+test('runGrepAnswer: child env carries CODE_GRAPH_INTERNAL=1 (not a funnel conversion)', () => {
+  // Stub variant that echoes the marker back in its output.
+  const envStub = path.join(stubDir, 'cg-env-stub.js');
+  fs.writeFileSync(envStub, `#!/usr/bin/env node
+process.stdout.write('internal=' + (process.env.CODE_GRAPH_INTERNAL || '') + '\\n');
+`);
+  fs.chmodSync(envStub, 0o755);
+  const r = runGrepAnswer({ cwd: stubDir, pattern: 'whatever', binary: envStub });
+  assert.equal(r.status, 'hits');
+  assert.match(r.text, /internal=1/,
+    'hook-internal CLI runs must be marked so record_cli_use skips them');
+});
+
 test('runGrepAnswer: omits path argv when no searchPath', () => {
   const r = runGrepAnswer({ cwd: stubDir, pattern: 'fts5_search', binary: stubBinary() });
   assert.match(r.text, /args=\["grep","fts5_search"\]/);
@@ -68,7 +84,13 @@ test('runGrepAnswer: CLI "[code-graph] No matches" → status no-hits', () => {
   assert.equal(r.status, 'no-hits');
 });
 
-test('runGrepAnswer: nonzero exit → unavailable', () => {
+test('runGrepAnswer: exit 1 (v0.50 grep-parity no-match) → status no-hits', () => {
+  const r = runGrepAnswer({ cwd: stubDir, pattern: 'NothingHereExit1', binary: stubBinary() });
+  assert.equal(r.status, 'no-hits',
+    'grep-parity exit 1 means no match, not a failed binary');
+});
+
+test('runGrepAnswer: exit >1 → unavailable', () => {
   const r = runGrepAnswer({ cwd: stubDir, pattern: 'ExplodePlease', binary: stubBinary() });
   assert.equal(r.status, 'unavailable');
 });
@@ -160,3 +182,34 @@ test('runGrepAnswer: glob searchPath is truncated before spawn (defensive layer)
   assert.equal(r.status, 'hits');
   assert.match(r.text, /args=\["grep","fts5_search","src\/storage"\]/);
 });
+
+// ── runShowAnswer (v0.49) — show-mode deny bodies ────────────────────
+
+test('runShowAnswer: concatenates per-symbol show output with $ headers', () => {
+  const r = runShowAnswer({ cwd: stubDir, symbols: ['alpha_one', 'beta_two'], binary: stubBinary() });
+  assert.equal(r.status, 'hits');
+  assert.match(r.text, /\$ code-graph-mcp show alpha_one/);
+  assert.match(r.text, /\$ code-graph-mcp show beta_two/);
+});
+
+test('runShowAnswer: skips non-identifier symbols, all-skipped → unavailable-safe no-hits', () => {
+  const r = runShowAnswer({ cwd: stubDir, symbols: ['$(rm -rf)', 'a|b'], binary: stubBinary() });
+  assert.equal(r.status, 'no-hits');
+});
+
+test('runShowAnswer: caps at 3 symbols', () => {
+  const r = runShowAnswer({
+    cwd: stubDir, symbols: ['s_one', 's_two', 's_three', 's_four'], binary: stubBinary(),
+  });
+  assert.equal(r.status, 'hits');
+  assert.doesNotMatch(r.text, /show s_four/);
+});
+
+test('runShowAnswer: empty symbol list → unavailable', () => {
+  assert.equal(runShowAnswer({ cwd: stubDir, symbols: [], binary: stubBinary() }).status, 'unavailable');
+});
+
+test('runShowAnswer: failing binary → no-hits (caller falls back to grep answer)', () => {
+  const r = runShowAnswer({ cwd: stubDir, symbols: ['ExplodePlease'], binary: stubBinary() });
+  assert.equal(r.status, 'no-hits');
+});

package/claude-plugin/scripts/doctor.js

@@ -7,7 +7,7 @@ const os = require('os');
 const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 const {
   getPluginVersion, readJson, healthCheck, CACHE_DIR,
-  isOurHookEntry, settingsPath, buildSettingsHookEntries,
+  settingsPath, surveyHookCoverage,
 } = require('./lifecycle');
 const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 
@@ -234,49 +234,6 @@ function runDiagnostics() {
   return results;
 }
 
-// Inventory of (event, matcher) tuples we expect to find in settings.json after
-// install. Used by doctor to detect missing entries.
-function surveyHookCoverage(settings) {
-  const desired = buildSettingsHookEntries();
-  const expected = [];
-  const desiredCmd = {}; // key -> command string we would write now
-  for (const [event, entries] of Object.entries(desired)) {
-    for (const e of entries) {
-      const key = `${event}:${e.matcher || '*'}`;
-      expected.push(key);
-      desiredCmd[key] = e.hooks && e.hooks[0] && e.hooks[0].command;
-    }
-  }
-
-  const present = new Set();
-  const presentCmd = {}; // key -> command currently registered
-  if (settings && settings.hooks) {
-    for (const [event, entries] of Object.entries(settings.hooks)) {
-      if (!Array.isArray(entries)) continue;
-      for (const entry of entries) {
-        if (isOurHookEntry(entry)) {
-          const key = `${event}:${entry.matcher || '*'}`;
-          present.add(key);
-          if (entry.hooks && entry.hooks[0] && entry.hooks[0].command) {
-            presentCmd[key] = entry.hooks[0].command;
-          }
-        }
-      }
-    }
-  }
-
-  const missing = expected.filter(k => !present.has(k));
-  // Stale = present but the registered command no longer matches what we'd write
-  // now (points at an old plugin-cache version dir / moved path). A stale path can
-  // run pre-recordRecommendation hook code, so the hook fires but the conversion
-  // metric stays dark — invisible to a present/absent check. This is the
-  // 0.45.1-registered-while-0.45.4-active case the RCA surfaced.
-  const stale = expected.filter(k =>
-    present.has(k) && desiredCmd[k] && presentCmd[k] && presentCmd[k] !== desiredCmd[k]
-  );
-  return { expected, present: [...present], missing, stale };
-}
-
 // ── Report Formatting ─────────────────────────────────────
 
 const STATUS_ICONS = { ok: '\u2705', warn: '\u26a0\ufe0f', error: '\u274c', skip: '\u2796' };
@@ -306,6 +263,26 @@ function formatReport(results) {
 
 // ── Repair Actions ────────────────────────────────────────
 
+/**
+ * v0.50.0: settings-writing repairs get the same stale-relic guard as
+ * session-init. A doctor launched from an old plugin-cache version dir would
+ * otherwise install() and re-anchor manifest + settings.json hook paths to the
+ * relic — the exact downgrade war the guard exists for, just user-triggered.
+ * Returns true (and prints redirection) when this copy must NOT write config.
+ * `relic` is injectable for tests.
+ */
+function relicRepairGuard({ log = console.log, relic = undefined } = {}) {
+  const { isStaleRelicContext, activeInstallPath } = require('./lifecycle');
+  const isRelic = relic !== undefined ? relic : isStaleRelicContext();
+  if (!isRelic) return false;
+  const active = activeInstallPath();
+  log('  ⚠ This doctor copy is not the active install (installed_plugins.json points elsewhere) — skipping settings repair.');
+  if (active) {
+    log(`  Run the active copy instead: node "${path.join(active, 'scripts', 'doctor.js')}"`);
+  }
+  return true;
+}
+
 function runRepairs(results) {
   const fixable = results.filter(r => r.fixId);
   if (fixable.length === 0) return 0;
@@ -425,6 +402,7 @@ function runRepairs(results) {
 
       case 'hooks-invalid': {
         console.log('\n  Repairing hooks...');
+        if (relicRepairGuard()) break;
         const { install } = require('./lifecycle');
         install();
         console.log('  \u2705 Hooks repaired \u2014 restart Claude Code to apply');
@@ -434,6 +412,7 @@ function runRepairs(results) {
 
       case 'missing-hooks-in-settings': {
         console.log('\n  Registering code-graph hooks in settings.json...');
+        if (relicRepairGuard()) break;
         const { install } = require('./lifecycle');
         const r = install();
         if (r.hooksRegistered) {
@@ -474,7 +453,7 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, surveyHookCoverage };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, surveyHookCoverage, relicRepairGuard };
 
 if (require.main === module) {
   const args = process.argv.slice(2);

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

@@ -80,3 +80,16 @@ test('surveyHookCoverage flags missing entries when settings empty', () => {
   assert.ok(cov.missing.length === cov.expected.length, 'all expected entries missing');
   assert.equal(cov.stale.length, 0, 'nothing present to be stale');
 });
+
+// ── relicRepairGuard (v0.50.0 — doctor twin of the session-init relic guard) ──
+
+test('relicRepairGuard blocks settings repair from a relic copy and redirects', () => {
+  const { relicRepairGuard } = require('./doctor');
+  const lines = [];
+  // Relic context → guard fires, prints the redirect, returns true (skip install).
+  assert.equal(relicRepairGuard({ relic: true, log: (s) => lines.push(s) }), true);
+  assert.ok(lines.some(l => l.includes('not the active install')),
+    `guard must explain why repair is skipped, got: ${lines.join(' | ')}`);
+  // Active (or dev/npm) context → repair proceeds.
+  assert.equal(relicRepairGuard({ relic: false, log: () => {} }), false);
+});