@sdsrs/code-graph 0.7.16 → 0.7.18

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

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

package/claude-plugin/hooks/hooks.json

@@ -1,16 +1,5 @@
 {
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|clear|compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-init.js\"",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
+  "description": "code-graph-mcp hooks",
+  "_note": "Hooks are registered to ~/.claude/settings.json by scripts/lifecycle.js. This file is intentionally empty to prevent double-firing — Claude Code would otherwise load hooks from both the plugin cache copy AND settings.json, causing each hook to run twice per event.",
+  "hooks": {}
 }

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

@@ -7,6 +7,7 @@ const path = require('path');
 const os = require('os');
 const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, writeJsonAtomic } = require('./lifecycle');
 const { clearCache: clearBinaryCache } = require('./find-binary');
+const { readBinaryVersion, isDevMode } = require('./version-utils');
 
 // ── Environment Checks ────────────────────────────────────
 
@@ -32,7 +33,6 @@ const BINARY_CACHE_DIR = path.join(CACHE_DIR, 'bin');
 const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;        // 6h
 const RATE_LIMIT_INTERVAL_MS = 24 * 60 * 60 * 1000;  // 24h if rate-limited
 const FETCH_TIMEOUT_MS = 3000;
-const VERSION_OUTPUT_RE = /^code-graph-mcp\s+(\d+\.\d+\.\d+)$/;
 
 function isSilentMode(argv = process.argv.slice(2), env = process.env) {
   return argv.includes('--silent') || env.CODE_GRAPH_AUTO_UPDATE_SILENT === '1';
@@ -65,18 +65,6 @@ function saveState(state) {
   } catch { /* ok */ }
 }
 
-// ── Dev Mode Detection ─────────────────────────────────────
-
-function isDevMode() {
-  // Always derive from __dirname — CLAUDE_PLUGIN_ROOT can leak from other plugins
-  const pluginRoot = path.resolve(__dirname, '..');
-  // Dev mode: running from source repo (has Cargo.toml nearby)
-  if (fs.existsSync(path.join(pluginRoot, '..', 'Cargo.toml'))) return true;
-  // Dev mode: plugin root is a symlink
-  try { if (fs.lstatSync(pluginRoot).isSymbolicLink()) return true; } catch { /* ok */ }
-  return false;
-}
-
 // ── Throttle ───────────────────────────────────────────────
 
 function shouldCheck(state) {
@@ -184,19 +172,6 @@ function getExtractedPluginVersion(pluginSrc) {
   return manifest && typeof manifest.version === 'string' ? manifest.version : null;
 }
 
-function readBinaryVersion(binaryPath) {
-  try {
-    const out = execFileSync(binaryPath, ['--version'], {
-      timeout: 2000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).toString().trim();
-    const match = out.match(VERSION_OUTPUT_RE);
-    return match ? match[1] : null;
-  } catch {
-    return null;
-  }
-}
-
 function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion) {
   try {
     const stat = fs.statSync(binaryTmp);

package/claude-plugin/scripts/doctor.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+'use strict';
+const { execFileSync, execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
+const {
+  getPluginVersion, readJson, healthCheck, CACHE_DIR,
+  findStalePluginHooksJson, clearStalePluginCacheHooks,
+} = require('./lifecycle');
+const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
+
+// ── Diagnostics ───────────────────────────────────────────
+
+/**
+ * Run all diagnostic checks. Returns an array of:
+ *   { name: string, status: 'ok'|'warn'|'error'|'skip', detail: string, fixId?: string }
+ */
+function runDiagnostics() {
+  const results = [];
+  const binary = findBinary();
+
+  // 1. Binary executable
+  if (!binary) {
+    results.push({ name: 'Binary', status: 'error', detail: 'not found', fixId: 'binary-missing' });
+    results.push({ name: 'Binary version', status: 'skip', detail: 'binary not found' });
+    results.push({ name: 'Source fresh', status: 'skip', detail: 'binary not found' });
+    results.push({ name: 'Schema', status: 'skip', detail: 'binary not found' });
+    results.push({ name: 'Index', status: 'skip', detail: 'binary not found' });
+    results.push({ name: 'Embeddings', status: 'skip', detail: 'binary not found' });
+  } else {
+    let execOk = true;
+    try {
+      fs.accessSync(binary, fs.constants.X_OK);
+      results.push({ name: 'Binary exec', status: 'ok', detail: binary });
+    } catch {
+      results.push({ name: 'Binary exec', status: 'error', detail: `not executable: ${binary}`, fixId: 'binary-not-exec' });
+      execOk = false;
+    }
+
+    // 2. Binary version vs plugin version
+    const pluginVersion = getPluginVersion();
+    const binaryVersion = execOk ? readBinaryVersion(binary) : null;
+    if (!binaryVersion) {
+      results.push({ name: 'Binary version', status: 'error', detail: 'failed to read version', fixId: 'binary-broken' });
+    } else if (binaryVersion !== pluginVersion) {
+      results.push({
+        name: 'Binary version',
+        status: 'warn',
+        detail: `v${binaryVersion} (plugin expects v${pluginVersion})`,
+        fixId: 'version-mismatch',
+      });
+    } else {
+      results.push({ name: 'Binary version', status: 'ok', detail: `v${binaryVersion}` });
+    }
+
+    // 3. Source freshness (dev mode only)
+    if (isDevMode()) {
+      const srcDir = path.resolve(__dirname, '..', '..', 'src');
+      try {
+        const binaryMtime = fs.statSync(binary).mtimeMs;
+        const latestSrcMtime = getNewestMtime(srcDir, '.rs');
+        if (latestSrcMtime > binaryMtime) {
+          const deltaMin = Math.round((latestSrcMtime - binaryMtime) / 60000);
+          results.push({
+            name: 'Source fresh',
+            status: 'warn',
+            detail: `src/ modified ${deltaMin}min after binary`,
+            fixId: 'binary-stale',
+          });
+        } else {
+          results.push({ name: 'Source fresh', status: 'ok', detail: 'binary up-to-date' });
+        }
+      } catch {
+        results.push({ name: 'Source fresh', status: 'skip', detail: 'could not stat files' });
+      }
+    } else {
+      results.push({ name: 'Source fresh', status: 'skip', detail: 'not dev mode' });
+    }
+
+    // 4. health-check (schema, index, embeddings) via binary --json
+    if (execOk) {
+      try {
+        const cwd = process.cwd();
+        const hcOutput = execFileSync(binary, ['health-check', '--json'], {
+          cwd,
+          timeout: 5000,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        const hc = JSON.parse(hcOutput);
+
+        // Schema
+        if (hc.issue && hc.issue.includes('schema')) {
+          results.push({ name: 'Schema', status: 'warn', detail: hc.issue, fixId: 'schema-mismatch' });
+        } else {
+          results.push({ name: 'Schema', status: 'ok', detail: `v${hc.schema_version}` });
+        }
+
+        // Index
+        if (hc.nodes === 0) {
+          results.push({ name: 'Index', status: 'warn', detail: 'empty', fixId: 'index-empty' });
+        } else {
+          const age = hc.index_age ? ` (${hc.index_age})` : '';
+          results.push({
+            name: 'Index',
+            status: 'ok',
+            detail: `${hc.nodes} nodes, ${hc.edges} edges, ${hc.files} files${age}`,
+          });
+        }
+
+        // Embeddings
+        const ep = hc.embedding_progress || '0/0';
+        const [done, total] = ep.split('/').map(Number);
+        if (total > 0 && done < total) {
+          const pct = Math.round((done / total) * 100);
+          results.push({ name: 'Embeddings', status: 'ok', detail: `${pct}% (${done}/${total})` });
+        } else if (total === 0) {
+          results.push({ name: 'Embeddings', status: 'ok', detail: 'no embeddable nodes' });
+        } else {
+          results.push({ name: 'Embeddings', status: 'ok', detail: `100% (${done}/${total})` });
+        }
+      } catch (e) {
+        const msg = e.stderr ? e.stderr.toString().trim().slice(0, 100) : e.message.slice(0, 100);
+        results.push({ name: 'Schema', status: 'error', detail: `health-check failed: ${msg}`, fixId: 'binary-broken' });
+        results.push({ name: 'Index', status: 'skip', detail: 'health-check failed' });
+        results.push({ name: 'Embeddings', status: 'skip', detail: 'health-check failed' });
+      }
+    } else {
+      results.push({ name: 'Schema', status: 'skip', detail: 'binary not executable' });
+      results.push({ name: 'Index', status: 'skip', detail: 'binary not executable' });
+      results.push({ name: 'Embeddings', status: 'skip', detail: 'binary not executable' });
+    }
+  }
+
+  // 5. Auto-update state
+  try {
+    const state = readJson(path.join(CACHE_DIR, 'update-state.json'));
+    if (state && state.updateAvailable && state.binaryUpdated === false) {
+      results.push({
+        name: 'Auto-update',
+        status: 'warn',
+        detail: `plugin v${state.latestVersion}, binary download incomplete`,
+        fixId: 'update-incomplete',
+      });
+    } else {
+      results.push({ name: 'Auto-update', status: 'ok', detail: 'up-to-date' });
+    }
+  } catch {
+    results.push({ name: 'Auto-update', status: 'ok', detail: 'no update state' });
+  }
+
+  // 6. Hook paths validity
+  const hookResult = healthCheck();
+  if (hookResult.healthy) {
+    results.push({ name: 'Hooks', status: 'ok', detail: 'all paths valid' });
+  } else {
+    results.push({
+      name: 'Hooks',
+      status: hookResult.repaired ? 'ok' : 'warn',
+      detail: hookResult.repaired
+        ? `${hookResult.issues.length} issue(s) auto-repaired`
+        : `${hookResult.issues.length} invalid path(s)`,
+      fixId: hookResult.repaired ? undefined : 'hooks-invalid',
+    });
+  }
+
+  // 7. Plugin cache hooks.json sanity — non-empty copies cause every hook to fire twice
+  try {
+    const stale = findStalePluginHooksJson();
+    if (stale.length === 0) {
+      results.push({ name: 'Plugin cache', status: 'ok', detail: 'no stale hooks.json' });
+    } else {
+      results.push({
+        name: 'Plugin cache',
+        status: 'warn',
+        detail: `${stale.length} stale hooks.json (hooks fire twice per event)`,
+        fixId: 'hooks-cache-stale',
+      });
+    }
+  } catch { /* lifecycle probe failed — skip */ }
+
+  return results;
+}
+
+// ── Report Formatting ─────────────────────────────────────
+
+const STATUS_ICONS = { ok: '\u2705', warn: '\u26a0\ufe0f', error: '\u274c', skip: '\u2796' };
+
+function formatReport(results) {
+  const pluginVersion = getPluginVersion();
+  const lines = [`\ud83d\udd0d code-graph doctor v${pluginVersion}`, ''];
+
+  const maxName = Math.max(...results.map(r => r.name.length));
+  for (const r of results) {
+    const icon = STATUS_ICONS[r.status] || '?';
+    const pad = ' '.repeat(maxName - r.name.length + 2);
+    lines.push(`  ${r.name}${pad}${icon}  ${r.detail}`);
+  }
+
+  const issues = results.filter(r => r.status === 'warn' || r.status === 'error');
+  lines.push('');
+  if (issues.length === 0) {
+    lines.push('  All checks passed.');
+  } else {
+    const fixable = issues.filter(r => r.fixId);
+    lines.push(`  ${issues.length} issue(s) found.${fixable.length > 0 ? ' Fixing...' : ''}`);
+  }
+
+  return lines.join('\n');
+}
+
+// ── Repair Actions ────────────────────────────────────────
+
+function runRepairs(results) {
+  const fixable = results.filter(r => r.fixId);
+  if (fixable.length === 0) return 0;
+
+  let fixed = 0;
+  for (const issue of fixable) {
+    switch (issue.fixId) {
+      case 'binary-stale':
+      case 'version-mismatch': {
+        if (!isDevMode()) {
+          console.log('\n  Triggering binary update...');
+          try {
+            execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], {
+              timeout: 60000,
+              stdio: 'inherit',
+            });
+            console.log('  \u2705 Update check complete');
+            fixed++;
+          } catch {
+            console.log('  \u274c Update check failed — install manually');
+          }
+          break;
+        }
+        console.log('\n  Building binary...');
+        console.log('    \u2192 cargo build --release --no-default-features');
+        try {
+          const projectRoot = path.resolve(__dirname, '..', '..');
+          execSync('cargo build --release --no-default-features', {
+            cwd: projectRoot,
+            stdio: 'inherit',
+            timeout: 300000,
+          });
+          clearBinaryCache();
+          console.log('  \u2705 Build complete');
+          fixed++;
+        } catch {
+          console.log('  \u274c Build failed');
+        }
+        break;
+      }
+
+      case 'binary-missing': {
+        console.log('\n  Installing binary...');
+        if (isDevMode()) {
+          console.log('    \u2192 cargo build --release --no-default-features');
+          try {
+            const projectRoot = path.resolve(__dirname, '..', '..');
+            execSync('cargo build --release --no-default-features', {
+              cwd: projectRoot,
+              stdio: 'inherit',
+              timeout: 300000,
+            });
+            clearBinaryCache();
+            console.log('  \u2705 Build complete');
+            fixed++;
+          } catch {
+            console.log('  \u274c Build failed');
+          }
+        } else {
+          console.log('    Install: npm install -g @sdsrs/code-graph');
+          console.log('    Or download from: https://github.com/sdsrss/code-graph-mcp/releases');
+        }
+        break;
+      }
+
+      case 'binary-not-exec': {
+        const binary = findBinary();
+        if (binary) {
+          try {
+            fs.chmodSync(binary, 0o755);
+            console.log(`\n  \u2705 Fixed permissions: chmod +x ${binary}`);
+            fixed++;
+          } catch {
+            console.log(`\n  \u274c Could not fix permissions: ${binary}`);
+          }
+          if (os.platform() === 'darwin') {
+            console.log(`  Also try: xattr -d com.apple.quarantine "${binary}"`);
+          }
+        }
+        break;
+      }
+
+      case 'index-empty': {
+        const binary = findBinary();
+        if (binary) {
+          console.log('\n  Rebuilding index...');
+          console.log('    \u2192 code-graph-mcp incremental-index');
+          try {
+            execFileSync(binary, ['incremental-index'], {
+              cwd: process.cwd(),
+              stdio: 'inherit',
+              timeout: 120000,
+            });
+            console.log('  \u2705 Index rebuilt');
+            fixed++;
+          } catch {
+            console.log('  \u274c Index rebuild failed');
+          }
+        }
+        break;
+      }
+
+      case 'update-incomplete': {
+        console.log('\n  Completing auto-update...');
+        try {
+          execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], {
+            timeout: 60000,
+            stdio: 'inherit',
+          });
+          console.log('  \u2705 Update check complete');
+          fixed++;
+        } catch {
+          console.log('  \u274c Update check failed');
+        }
+        break;
+      }
+
+      case 'hooks-invalid': {
+        console.log('\n  Repairing hooks...');
+        const { install } = require('./lifecycle');
+        install();
+        console.log('  \u2705 Hooks repaired');
+        fixed++;
+        break;
+      }
+
+      case 'hooks-cache-stale': {
+        console.log('\n  Clearing stale plugin cache hooks.json...');
+        const cleared = clearStalePluginCacheHooks();
+        console.log(`  \u2705 Cleared ${cleared.length} file(s) — restart Claude Code to apply`);
+        for (const p of cleared) console.log(`     - ${p}`);
+        fixed++;
+        break;
+      }
+
+      case 'schema-mismatch': {
+        console.log('\n  Schema migration happens automatically when the binary runs.');
+        console.log('  If binary is older than DB, update the binary first.');
+        break;
+      }
+
+      default:
+        break;
+    }
+  }
+  return fixed;
+}
+
+// ── Main ──────────────────────────────────────────────────
+
+function runDoctor(opts = {}) {
+  const results = runDiagnostics();
+  console.log(formatReport(results));
+
+  const issues = results.filter(r => r.status === 'warn' || r.status === 'error');
+
+  if (issues.length > 0 && !opts.checkOnly) {
+    const fixed = runRepairs(results);
+    console.log(`\n  ${fixed}/${issues.length} issue(s) addressed.`);
+  }
+
+  return { results, issueCount: issues.length };
+}
+
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const checkOnly = args.includes('--check-only');
+  const { issueCount } = runDoctor({ checkOnly });
+  process.exit(issueCount > 0 ? 1 : 0);
+}

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

@@ -0,0 +1,47 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { runDiagnostics, formatReport } = require('./doctor');
+
+test('runDiagnostics returns an array of check results', () => {
+  const results = runDiagnostics();
+  assert.ok(Array.isArray(results));
+  assert.ok(results.length > 0, 'should have at least one check result');
+  for (const r of results) {
+    assert.equal(typeof r.name, 'string');
+    assert.ok(['ok', 'warn', 'error', 'skip'].includes(r.status));
+    assert.equal(typeof r.detail, 'string');
+  }
+});
+
+test('formatReport produces readable output', () => {
+  const results = [
+    { name: 'Binary version', status: 'ok', detail: 'v0.7.16' },
+    { name: 'Source fresh', status: 'warn', detail: 'src/ modified 3min after binary', fixId: 'binary-stale' },
+    { name: 'Schema', status: 'ok', detail: 'v6' },
+  ];
+  const output = formatReport(results);
+  assert.ok(output.includes('Binary version'));
+  assert.ok(output.includes('v0.7.16'));
+  assert.ok(output.includes('Source fresh'));
+  assert.ok(output.includes('3min'));
+});
+
+test('formatReport shows issue count when problems exist', () => {
+  const results = [
+    { name: 'Test', status: 'warn', detail: 'problem', fixId: 'test-fix' },
+  ];
+  const output = formatReport(results);
+  assert.ok(output.includes('1'));
+  assert.ok(output.includes('issue'));
+});
+
+test('formatReport shows all-clear when no problems', () => {
+  const results = [
+    { name: 'Binary version', status: 'ok', detail: 'v0.7.16' },
+    { name: 'Schema', status: 'ok', detail: 'v6' },
+  ];
+  const output = formatReport(results);
+  assert.ok(output.includes('All checks passed') || output.includes('0 issues'));
+});

package/claude-plugin/scripts/lifecycle.js

@@ -220,6 +220,88 @@ function migrateOldPluginIds(settings) {
   return changed;
 }
 
+// --- Plugin-cache hooks.json guard ---
+// Claude Code loads hooks from TWO places: settings.json AND the plugin cache
+// at ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/hooks/hooks.json. If both have
+// our hooks, every event fires twice. We register to settings.json (reliable),
+// so cache copies must stay empty. Auto-updates can re-populate cache hooks.json
+// from the marketplace source — this scan+clear runs on every install/update and
+// every SessionStart (via session-init.js) as a second layer of defense.
+
+const EMPTY_HOOKS_STUB = Object.freeze({
+  description: 'code-graph-mcp hooks',
+  _note: 'Hooks are registered to ~/.claude/settings.json by lifecycle.js. Cleared automatically to prevent double-firing.',
+  hooks: {},
+});
+
+function isOurPluginMarketplace(mpDir) {
+  try {
+    const meta = readJson(path.join(mpDir, '.claude-plugin', 'marketplace.json'));
+    if (meta && meta.name === MARKETPLACE_NAME) return true;
+  } catch { /* fallthrough */ }
+  return path.basename(mpDir) === MARKETPLACE_NAME;
+}
+
+function scanPluginHooksJsonCopies() {
+  const HOME = os.homedir();
+  const paths = [];
+
+  // Marketplace source (git-cloned by Claude Code on install)
+  const mpRoot = path.join(HOME, '.claude', 'plugins', 'marketplaces');
+  try {
+    for (const name of fs.readdirSync(mpRoot)) {
+      const mpDir = path.join(mpRoot, name);
+      try { if (!fs.statSync(mpDir).isDirectory()) continue; } catch { continue; }
+      if (!isOurPluginMarketplace(mpDir)) continue;
+      const p = path.join(mpDir, 'claude-plugin', 'hooks', 'hooks.json');
+      if (fs.existsSync(p)) paths.push(p);
+    }
+  } catch { /* no marketplaces dir */ }
+
+  // Cache (what Claude Code actually loads at runtime), per plugin + per version
+  const cacheRoot = path.join(HOME, '.claude', 'plugins', 'cache', MARKETPLACE_NAME);
+  try {
+    for (const pluginName of fs.readdirSync(cacheRoot)) {
+      const pluginDir = path.join(cacheRoot, pluginName);
+      try { if (!fs.statSync(pluginDir).isDirectory()) continue; } catch { continue; }
+      for (const ver of fs.readdirSync(pluginDir)) {
+        const verDir = path.join(pluginDir, ver);
+        try { if (!fs.statSync(verDir).isDirectory()) continue; } catch { continue; }
+        const p = path.join(verDir, 'hooks', 'hooks.json');
+        if (fs.existsSync(p)) paths.push(p);
+      }
+    }
+  } catch { /* no cache dir */ }
+
+  return paths;
+}
+
+function findStalePluginHooksJson() {
+  const stale = [];
+  for (const p of scanPluginHooksJsonCopies()) {
+    try {
+      const cur = readJson(p);
+      if (cur && cur.hooks && typeof cur.hooks === 'object' && Object.keys(cur.hooks).length > 0) {
+        stale.push(p);
+      }
+    } catch { /* unreadable — skip */ }
+  }
+  return stale;
+}
+
+function clearStalePluginCacheHooks() {
+  const cleared = [];
+  const stamp = new Date().toISOString();
+  for (const p of findStalePluginHooksJson()) {
+    try {
+      const stub = { ...EMPTY_HOOKS_STUB, _note: `${EMPTY_HOOKS_STUB._note} (cleared ${stamp})` };
+      writeJsonAtomic(p, stub);
+      cleared.push(p);
+    } catch { /* write failure — skip */ }
+  }
+  return cleared;
+}
+
 // --- Hook Registration ---
 // Plugin system's hooks.json auto-loading is unreliable (observed across GSD,
 // superpowers, code-graph-mcp). Write hooks directly to settings.json instead.
@@ -366,13 +448,17 @@ function install() {
     writeJsonAtomic(SETTINGS_PATH, settings);
   }
 
+  // 3b. Clear cache/marketplace hooks.json copies after settings.json is authoritative,
+  //     so next session only fires hooks from settings.json (no double-firing).
+  const clearedHookCopies = clearStalePluginCacheHooks();
+
   // 4. Write manifest with version
   manifest.version = version;
   manifest.installedAt = manifest.installedAt || new Date().toISOString();
   manifest.updatedAt = new Date().toISOString();
   writeManifest(manifest);
 
-  return { version, settingsChanged, statusLineClaimed: manifest.config.statusLine };
+  return { version, settingsChanged, statusLineClaimed: manifest.config.statusLine, clearedHookCopies };
 }
 
 // --- Uninstall (clean all config) ---
@@ -475,6 +561,10 @@ function update() {
     writeJsonAtomic(SETTINGS_PATH, settings);
   }
 
+  // 4b. Clear cache/marketplace hooks.json copies after settings.json is updated.
+  //     Auto-update can re-populate cache from marketplace source; stamp it out.
+  const clearedHookCopies = clearStalePluginCacheHooks();
+
   // 5. Clear update-check cache (force re-check after update)
   const updateCache = path.join(CACHE_DIR, 'update-check');
   try { fs.unlinkSync(updateCache); } catch { /* ok */ }
@@ -487,7 +577,7 @@ function update() {
   // 7. Clean up old cached versions (keep latest 3)
   cleanupOldCacheVersions(3);
 
-  return { oldVersion, version, settingsChanged };
+  return { oldVersion, version, settingsChanged, clearedHookCopies };
 }
 
 /**
@@ -584,6 +674,7 @@ module.exports = {
   readRegistry, writeRegistry,
   getPluginVersion, cleanupOldCacheVersions,
   registerHooksToSettings, removeHooksFromSettings, getHookDefinitions,
+  scanPluginHooksJsonCopies, findStalePluginHooksJson, clearStalePluginCacheHooks,
   PLUGIN_ID, OLD_PLUGIN_IDS, MARKETPLACE_NAME, CACHE_DIR, REGISTRY_FILE,
 };
 
@@ -609,8 +700,13 @@ if (require.main === module) {
         console.log(`  ${issue.type}: ${issue.path || issue.id}`);
       }
     }
+  } else if (cmd === 'doctor') {
+    const { runDoctor } = require('./doctor');
+    const checkOnly = process.argv.includes('--check-only');
+    const { issueCount } = runDoctor({ checkOnly });
+    process.exit(issueCount > 0 ? 1 : 0);
   } else {
-    console.error('Usage: lifecycle.js <install|uninstall|update|health>');
+    console.error('Usage: lifecycle.js <install|uninstall|update|health|doctor>');
     process.exit(1);
   }
 }

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

@@ -94,4 +94,82 @@ test('cleanupDisabledStatusline also heals orphaned statusline after uninstall',
   const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
   assert.equal(settings.statusLine.command, 'echo previous-status');
   assert.equal(fs.existsSync(registryPath), false);
+});
+
+function nonEmptyHooksJson() {
+  return {
+    hooks: {
+      SessionStart: [{
+        matcher: 'startup',
+        hooks: [{ type: 'command', command: 'node "/plugin/session-init.js"' }],
+      }],
+    },
+  };
+}
+
+test('findStalePluginHooksJson detects non-empty cache and marketplace copies', () => {
+  const homeDir = mkHome();
+  const mpHooks = path.join(homeDir, '.claude', 'plugins', 'marketplaces', 'code-graph-mcp', 'claude-plugin', 'hooks', 'hooks.json');
+  const mpManifest = path.join(homeDir, '.claude', 'plugins', 'marketplaces', 'code-graph-mcp', '.claude-plugin', 'marketplace.json');
+  const cacheHooks = path.join(homeDir, '.claude', 'plugins', 'cache', 'code-graph-mcp', 'code-graph-mcp', '0.7.17', 'hooks', 'hooks.json');
+
+  writeJson(mpManifest, { name: 'code-graph-mcp' });
+  writeJson(mpHooks, nonEmptyHooksJson());
+  writeJson(cacheHooks, nonEmptyHooksJson());
+
+  const out = execFileSync(process.execPath, ['-e', `
+    const { findStalePluginHooksJson } = require(${JSON.stringify(lifecyclePath)});
+    process.stdout.write(JSON.stringify(findStalePluginHooksJson()));
+  `], { env: { ...process.env, HOME: homeDir } }).toString();
+
+  const stale = JSON.parse(out).sort();
+  assert.equal(stale.length, 2);
+  assert.ok(stale.some(p => p === mpHooks));
+  assert.ok(stale.some(p => p === cacheHooks));
+});
+
+test('clearStalePluginCacheHooks empties non-empty hooks.json copies', () => {
+  const homeDir = mkHome();
+  const cacheHooks = path.join(homeDir, '.claude', 'plugins', 'cache', 'code-graph-mcp', 'code-graph-mcp', '0.7.17', 'hooks', 'hooks.json');
+  writeJson(cacheHooks, nonEmptyHooksJson());
+
+  const out = execFileSync(process.execPath, ['-e', `
+    const { clearStalePluginCacheHooks } = require(${JSON.stringify(lifecyclePath)});
+    process.stdout.write(JSON.stringify(clearStalePluginCacheHooks()));
+  `], { env: { ...process.env, HOME: homeDir } }).toString();
+
+  const cleared = JSON.parse(out);
+  assert.deepEqual(cleared, [cacheHooks]);
+
+  const payload = JSON.parse(fs.readFileSync(cacheHooks, 'utf8'));
+  assert.deepEqual(payload.hooks, {});
+  assert.ok(payload._note && payload._note.includes('cleared'));
+});
+
+test('clearStalePluginCacheHooks is idempotent and skips already-empty copies', () => {
+  const homeDir = mkHome();
+  const cacheHooks = path.join(homeDir, '.claude', 'plugins', 'cache', 'code-graph-mcp', 'code-graph-mcp', '0.7.17', 'hooks', 'hooks.json');
+  writeJson(cacheHooks, { hooks: {} });
+
+  const out = execFileSync(process.execPath, ['-e', `
+    const { clearStalePluginCacheHooks } = require(${JSON.stringify(lifecyclePath)});
+    process.stdout.write(JSON.stringify(clearStalePluginCacheHooks()));
+  `], { env: { ...process.env, HOME: homeDir } }).toString();
+
+  assert.deepEqual(JSON.parse(out), []);
+});
+
+test('scanPluginHooksJsonCopies ignores unrelated marketplaces', () => {
+  const homeDir = mkHome();
+  const otherMp = path.join(homeDir, '.claude', 'plugins', 'marketplaces', 'some-other-plugin', 'claude-plugin', 'hooks', 'hooks.json');
+  const otherManifest = path.join(homeDir, '.claude', 'plugins', 'marketplaces', 'some-other-plugin', '.claude-plugin', 'marketplace.json');
+  writeJson(otherManifest, { name: 'some-other-plugin' });
+  writeJson(otherMp, nonEmptyHooksJson());
+
+  const out = execFileSync(process.execPath, ['-e', `
+    const { scanPluginHooksJsonCopies } = require(${JSON.stringify(lifecyclePath)});
+    process.stdout.write(JSON.stringify(scanPluginHooksJsonCopies()));
+  `], { env: { ...process.env, HOME: homeDir } }).toString();
+
+  assert.deepEqual(JSON.parse(out), []);
 });

package/claude-plugin/scripts/session-init.js

@@ -6,8 +6,10 @@ const os = require('os');
 const fs = require('fs');
 const {
   install, update, readManifest, getPluginVersion, checkScopeConflict,
-  cleanupDisabledStatusline, isPluginInactive, readJson,
+  cleanupDisabledStatusline, isPluginInactive, readJson, CACHE_DIR,
+  clearStalePluginCacheHooks, findStalePluginHooksJson,
 } = require('./lifecycle');
+const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 
 function launchBackgroundAutoUpdate(spawnFn = spawn, env = process.env) {
   try {
@@ -161,6 +163,94 @@ function verifyBinary() {
   return { available: true, binary };
 }
 
+/**
+ * Lightweight consistency checks — called from runSessionInit().
+ * Returns an array of issue objects: { id, msg, fix }.
+ * Empty array = all consistent (silent).
+ */
+function consistencyCheck(binary) {
+  const issues = [];
+
+  // Check 1: Binary version vs plugin version
+  try {
+    const pluginVersion = getPluginVersion();
+    const binaryVersion = readBinaryVersion(binary);
+    if (binaryVersion && binaryVersion !== pluginVersion) {
+      issues.push({
+        id: 'version-mismatch',
+        msg: `Binary v${binaryVersion}, plugin expects v${pluginVersion}`,
+        fix: isDevMode() ? 'cargo build --release' : 'code-graph-mcp doctor',
+      });
+    }
+  } catch { /* skip check on error */ }
+
+  // Check 2: Source freshness (dev mode only)
+  try {
+    if (isDevMode()) {
+      const srcDir = path.resolve(__dirname, '..', '..', 'src');
+      const binaryMtime = fs.statSync(binary).mtimeMs;
+      const latestSrcMtime = getNewestMtime(srcDir, '.rs');
+      if (latestSrcMtime > binaryMtime) {
+        const deltaMin = Math.round((latestSrcMtime - binaryMtime) / 60000);
+        issues.push({
+          id: 'binary-stale',
+          msg: `src/ modified ${deltaMin}min after last build`,
+          fix: 'cargo build --release',
+        });
+      }
+    }
+  } catch { /* skip check on error */ }
+
+  // Check 3: Auto-update incomplete
+  try {
+    const statePath = path.join(CACHE_DIR, 'update-state.json');
+    const state = readJson(statePath);
+    if (state && state.updateAvailable && state.binaryUpdated === false) {
+      issues.push({
+        id: 'update-incomplete',
+        msg: `Plugin updated to v${state.latestVersion}, binary not updated`,
+        fix: 'code-graph-mcp doctor',
+      });
+    }
+  } catch { /* skip check on error */ }
+
+  // Output warnings to stderr
+  if (issues.length > 0) {
+    const lines = [`[code-graph] ${issues.length} consistency issue(s):`];
+    issues.forEach((issue, i) => {
+      lines.push(`  ${i + 1}. ${issue.msg}`);
+      lines.push(`     → ${issue.fix}`);
+    });
+    process.stderr.write(lines.join('\n') + '\n');
+  }
+
+  return issues;
+}
+
+/**
+ * Self-heal: Claude Code auto-update can re-populate cache hooks.json from the
+ * marketplace source, which would double-fire every hook we registered to
+ * settings.json. If our hooks are already in settings.json (install has run),
+ * any non-empty cache/marketplace hooks.json is stale — clear it.
+ * Gated on settings.json registration so pure plugin-only users (no install
+ * script run; cache hooks.json is their only registration) are not broken.
+ */
+function healStaleCacheHooks() {
+  try {
+    const settings = readJson(path.join(os.homedir(), '.claude', 'settings.json')) || {};
+    const manifest = readManifest();
+    if (!manifest || !manifest.version) return { checked: false, cleared: 0 };
+    const serialized = JSON.stringify(settings.hooks || {});
+    if (!serialized.includes('code-graph')) return { checked: false, cleared: 0 };
+    const stale = findStalePluginHooksJson();
+    if (stale.length === 0) return { checked: true, cleared: 0 };
+    const cleared = clearStalePluginCacheHooks();
+    return { checked: true, cleared: cleared.length };
+  } catch {
+    return { checked: false, cleared: 0 };
+  }
+}
+
 function runSessionInit() {
   if (isPluginInactive()) {
     cleanupDisabledStatusline();
@@ -177,13 +267,24 @@ function runSessionInit() {
 
   const lifecycle = syncLifecycleConfig();
 
+  // Self-heal stale plugin cache hooks.json (prevents double-firing after auto-update).
+  // syncLifecycleConfig's install/update path already clears; this catches the
+  // 'noop' case where version matches but cache was re-populated externally.
+  const cacheHookHeal = healStaleCacheHooks();
+
   // Verify binary availability — catch issues early with actionable diagnostics
   const binaryCheck = verifyBinary();
 
   const autoUpdateLaunched = launchBackgroundAutoUpdate();
   const indexFreshness = binaryCheck.available ? ensureIndexFresh() : 'skipped';
   const mapInjected = binaryCheck.available ? injectProjectMap() : false;
-  return { inactive: false, lifecycle, autoUpdateLaunched, indexFreshness, mapInjected, binaryCheck };
+  const consistencyIssues = binaryCheck.available
+    ? consistencyCheck(binaryCheck.binary)
+    : [];
+  return {
+    inactive: false, lifecycle, cacheHookHeal,
+    autoUpdateLaunched, indexFreshness, mapInjected, binaryCheck, consistencyIssues,
+  };
 }
 
 /**
@@ -221,6 +322,8 @@ module.exports = {
   ensureIndexFresh,
   injectProjectMap,
   verifyBinary,
+  consistencyCheck,
+  healStaleCacheHooks,
   runSessionInit,
 };
 

package/claude-plugin/scripts/session-init.test.js

@@ -1,6 +1,8 @@
 'use strict';
 const test = require('node:test');
 const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
 
 const { launchBackgroundAutoUpdate, syncLifecycleConfig, ensureIndexFresh, verifyBinary } = require('./session-init');
 
@@ -70,3 +72,34 @@ test('launchBackgroundAutoUpdate spawns detached silent updater', () => {
   assert.equal(calls[0].unrefCalled, true);
 });
 
+const { consistencyCheck } = require('./session-init');
+
+test('consistencyCheck is exported as a function', () => {
+  assert.equal(typeof consistencyCheck, 'function');
+});
+
+test('consistencyCheck returns empty array when binary version matches plugin', () => {
+  const result = consistencyCheck('/tmp/nonexistent-binary');
+  assert.ok(Array.isArray(result));
+});
+
+test('consistencyCheck returns version-mismatch when versions differ', () => {
+  const os = require('os');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-'));
+  const bin = path.join(dir, 'code-graph-mcp');
+  fs.writeFileSync(bin, [
+    '#!/usr/bin/env bash',
+    'if [ "$1" = "--version" ]; then',
+    '  echo "code-graph-mcp 0.0.1"',
+    '  exit 0',
+    'fi',
+    'exit 0',
+  ].join('\n'));
+  fs.chmodSync(bin, 0o755);
+
+  const issues = consistencyCheck(bin);
+  const versionIssue = issues.find(i => i.id === 'version-mismatch');
+  assert.ok(versionIssue, 'should detect version mismatch');
+  assert.ok(versionIssue.msg.includes('0.0.1'));
+});
+

package/claude-plugin/scripts/version-utils.js

@@ -0,0 +1,49 @@
+'use strict';
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const VERSION_OUTPUT_RE = /^code-graph-mcp\s+(\d+\.\d+\.\d+)$/;
+
+function readBinaryVersion(binaryPath) {
+  try {
+    const out = execFileSync(binaryPath, ['--version'], {
+      timeout: 2000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).toString().trim();
+    const match = out.match(VERSION_OUTPUT_RE);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function isDevMode() {
+  // Always derive from __dirname — CLAUDE_PLUGIN_ROOT can leak from other plugins
+  const pluginRoot = path.resolve(__dirname, '..');
+  // Dev mode: running from source repo (has Cargo.toml nearby)
+  if (fs.existsSync(path.join(pluginRoot, '..', 'Cargo.toml'))) return true;
+  // Dev mode: plugin root is a symlink
+  try { if (fs.lstatSync(pluginRoot).isSymbolicLink()) return true; } catch { /* ok */ }
+  return false;
+}
+
+function getNewestMtime(dir, ext = '.rs') {
+  let newest = 0;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const sub = getNewestMtime(full, ext);
+        if (sub > newest) newest = sub;
+      } else if (entry.name.endsWith(ext)) {
+        const mt = fs.statSync(full).mtimeMs;
+        if (mt > newest) newest = mt;
+      }
+    }
+  } catch { /* dir doesn't exist or not readable */ }
+  return newest;
+}
+
+module.exports = { readBinaryVersion, isDevMode, getNewestMtime, VERSION_OUTPUT_RE };

package/claude-plugin/scripts/version-utils.test.js

@@ -0,0 +1,83 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function mkDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+// ── readBinaryVersion ──
+
+test('readBinaryVersion returns version from valid binary', () => {
+  const { readBinaryVersion } = require('./version-utils');
+  const dir = mkDir('vu-');
+  const bin = path.join(dir, 'code-graph-mcp');
+  fs.writeFileSync(bin, [
+    '#!/usr/bin/env bash',
+    'if [ "$1" = "--version" ]; then',
+    '  echo "code-graph-mcp 1.2.3"',
+    '  exit 0',
+    'fi',
+    'exit 0',
+  ].join('\n'));
+  fs.chmodSync(bin, 0o755);
+  assert.equal(readBinaryVersion(bin), '1.2.3');
+});
+
+test('readBinaryVersion returns null for non-existent binary', () => {
+  const { readBinaryVersion } = require('./version-utils');
+  assert.equal(readBinaryVersion('/tmp/does-not-exist-binary'), null);
+});
+
+test('readBinaryVersion returns null for binary with unexpected output', () => {
+  const { readBinaryVersion } = require('./version-utils');
+  const dir = mkDir('vu-');
+  const bin = path.join(dir, 'code-graph-mcp');
+  fs.writeFileSync(bin, '#!/usr/bin/env bash\necho "something else"');
+  fs.chmodSync(bin, 0o755);
+  assert.equal(readBinaryVersion(bin), null);
+});
+
+// ── isDevMode ──
+
+test('isDevMode returns true in source repo (Cargo.toml nearby)', () => {
+  const { isDevMode } = require('./version-utils');
+  // Running from source repo: __dirname/../.. has Cargo.toml → true
+  assert.equal(isDevMode(), true);
+});
+
+// ── getNewestMtime ──
+
+test('getNewestMtime returns 0 for non-existent directory', () => {
+  const { getNewestMtime } = require('./version-utils');
+  assert.equal(getNewestMtime('/tmp/no-such-dir-xyz'), 0);
+});
+
+test('getNewestMtime finds newest .rs file mtime', () => {
+  const { getNewestMtime } = require('./version-utils');
+  const dir = mkDir('vu-mtime-');
+  const sub = path.join(dir, 'sub');
+  fs.mkdirSync(sub);
+
+  const older = path.join(dir, 'old.rs');
+  const newer = path.join(sub, 'new.rs');
+  fs.writeFileSync(older, 'fn old() {}');
+
+  fs.writeFileSync(newer, 'fn new() {}');
+  const futureMs = Date.now() + 1000;
+  fs.utimesSync(newer, futureMs / 1000, futureMs / 1000);
+
+  const newerMtime = fs.statSync(newer).mtimeMs;
+  const result = getNewestMtime(dir, '.rs');
+  assert.equal(result, newerMtime, 'should return exactly the newest file mtime');
+});
+
+test('getNewestMtime ignores non-matching extensions', () => {
+  const { getNewestMtime } = require('./version-utils');
+  const dir = mkDir('vu-ext-');
+  fs.writeFileSync(path.join(dir, 'file.js'), 'hello');
+  assert.equal(getNewestMtime(dir, '.rs'), 0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.7.16",
+  "version": "0.7.18",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -34,10 +34,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.7.16",
-    "@sdsrs/code-graph-linux-arm64": "0.7.16",
-    "@sdsrs/code-graph-darwin-x64": "0.7.16",
-    "@sdsrs/code-graph-darwin-arm64": "0.7.16",
-    "@sdsrs/code-graph-win32-x64": "0.7.16"
+    "@sdsrs/code-graph-linux-x64": "0.7.18",
+    "@sdsrs/code-graph-linux-arm64": "0.7.18",
+    "@sdsrs/code-graph-darwin-x64": "0.7.18",
+    "@sdsrs/code-graph-darwin-arm64": "0.7.18",
+    "@sdsrs/code-graph-win32-x64": "0.7.18"
   }
 }