@sdsrs/code-graph 0.102.0 → 0.104.0

package/bin/cli.js

@@ -45,16 +45,21 @@ if (sub === "uninstall") {
   if (process.argv.slice(3).some((a) => a === "--help" || a === "-h")) {
     process.stdout.write(
       "code-graph-mcp uninstall — remove code-graph config + cache from this machine\n\n" +
-      "USAGE:\n    code-graph-mcp uninstall\n\n" +
+      "USAGE:\n    code-graph-mcp uninstall [--unadopt-all] [--purge-global]\n\n" +
       "Restores your prior statusline, strips code-graph hooks from settings.json,\n" +
       "deletes ~/.cache/code-graph, and removes this project's CLAUDE.md adoption\n" +
-      "block. Also run `/plugin uninstall code-graph-mcp` in Claude Code to sync its\n" +
-      "UI, and `code-graph-mcp unadopt` in any OTHER adopted project.\n");
+      "block. --unadopt-all also removes the managed block + detail file from every\n" +
+      "registered adopted project; --purge-global removes the globally-installed\n" +
+      "@sdsrs npm packages even without the plugin-install marker. Also run\n" +
+      "`/plugin uninstall code-graph-mcp` in Claude Code to sync its UI.\n");
     process.exit(0);
   }
   const lifecycle = require("../claude-plugin/scripts/lifecycle");
   const { unadopt } = require("../claude-plugin/scripts/adopt");
-  const r = lifecycle.uninstall({ purgeGlobal: process.argv.slice(3).includes("--purge-global") });
+  const r = lifecycle.uninstall({
+    purgeGlobal: process.argv.slice(3).includes("--purge-global"),
+    unadoptAll: process.argv.slice(3).includes("--unadopt-all"),
+  });
   let ua = { ok: false };
   try { ua = unadopt(); } catch { /* best-effort — settings/cache already cleaned */ }
   const projectUnadopted = !!(ua && (ua.blockPruned || ua.fileRemoved || ua.claudeMdRemoved));
@@ -69,9 +74,14 @@ if (sub === "uninstall") {
       `    Remove with: npm uninstall -g ${r.globalPkgsRemaining.join(" ")}` +
       (r.pluginInstalledGlobals ? "\n" : "   (or re-run with --purge-global)\n");
   }
+  if (r.unadopted.length) {
+    const cleaned = r.unadopted.filter((u) => u.cleaned).length;
+    out += `  Unadopted ${cleaned}/${r.unadopted.length} registered project(s) (--unadopt-all).\n`;
+  }
   const otherAdopted = r.adoptedProjects.filter((p) => p !== process.cwd());
   if (otherAdopted.length) {
-    out += "  Other adopted project(s) — run `code-graph-mcp unadopt` + `rm -rf .code-graph` in each:\n" +
+    out += "  Other adopted project(s) — re-run with --unadopt-all, or in each:" +
+      " `code-graph-mcp unadopt` + `rm -rf .code-graph`\n" +
       otherAdopted.map((p) => `    ${p}\n`).join("");
   }
   out += "  Also run `/plugin uninstall code-graph-mcp` in Claude Code to sync its UI state.\n";

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

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

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

@@ -9,8 +9,8 @@ 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, globalNodeModulesCandidates, PLATFORM_PKG, detectLibc } = require('./find-binary');
-const { readBinaryVersion, isDevMode } = require('./version-utils');
+const { clearCache: clearBinaryCache, globalNodeModulesCandidates, nvmNodeModulesDirs, PLATFORM_PKG, detectLibc } = require('./find-binary');
+const { readBinaryVersion, compareVersions, isDevMode } = require('./version-utils');
 const { cgTmpDir } = require('./tmp-dir');
 const { npmSpawnOpts } = require('./npm-exec');
 const { acquireLock } = require('./install-lock');
@@ -112,21 +112,9 @@ function shouldCheck(state, { force = false } = {}) {
   return elapsed >= interval;
 }
 
-// ── Version Comparison (semver) ────────────────────────────
-
-// Assumes plain numeric "M.m.p" releases (the project's tag scheme). A pre-release
-// tag (e.g. "1.2.4-rc1") is NOT semver-ordered: `Number("4-rc1")` is NaN → coerced
-// to 0, dropping that segment's number (so "1.2.4-rc1" wrongly sorts below "1.2.3").
-// Revisit with a real semver compare only if the release process adopts pre-releases.
-function compareVersions(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
-    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
-  }
-  return 0;
-}
+// ── Version Comparison ─────────────────────────────────────
+// compareVersions is imported from version-utils.js (single canonical,
+// pre-release-aware implementation) and re-exported below.
 
 // ── GitHub API ─────────────────────────────────────────────
 
@@ -609,6 +597,31 @@ function staleGlobalPkgs(latestVersion, roots = null) {
   return out;
 }
 
+/**
+ * Global installs of ours stranded under a NON-active node version. nvm keeps a
+ * separate global prefix per node; switching the default node leaves the old
+ * prefix's `@sdsrs/code-graph` behind — invisible to selfHealGlobalPkgs (which
+ * only sees, and can only `npm install -g` into, the ACTIVE node's prefix) yet
+ * still able to seed stale settings.json hooks / shadow PATH shims (the
+ * v24.11.1@0.46.0 relic firing beside the active install — RCA 2026-07-24).
+ * Detection-only: returns each relic's package + version + node prefix so doctor
+ * can surface it with manual remediation. `dirs`/`activeDir` injectable for tests.
+ */
+function inactiveNodeGlobalRelics({ dirs = null, activeDir = null } = {}) {
+  const active = path.resolve(activeDir
+    || path.join(path.dirname(process.execPath), '..', 'lib', 'node_modules'));
+  const roots = dirs || nvmNodeModulesDirs();
+  const out = [];
+  for (const dir of roots) {
+    if (path.resolve(dir) === active) continue; // active prefix → not a relic
+    for (const name of [SHELL_PKG, PLATFORM_PKG]) {
+      const version = globalPkgVersion(name, [dir]);
+      if (version) out.push({ name, version, nodeModulesDir: dir });
+    }
+  }
+  return out;
+}
+
 /** One targeted `npm install -g` for the given specs. Resolves true on exit 0. */
 function npmInstallGlobal(specs) {
   return new Promise((resolve) => {
@@ -659,6 +672,21 @@ async function selfHealGlobalPkgs(latest, state, {
   };
 }
 
+// Whether a THROTTLED checkForUpdate should still attempt the global-npm
+// self-heal. The post-fetch heal below only runs on the non-throttle path, but
+// the ONLY context that can SEE a user's nvm/global prefix is a CLI run under
+// that node (globalNodeModulesCandidates is execPath-derived) — and such a run,
+// once binary+shell are current, short-circuits at the throttle early-return and
+// never reaches the heal. That gap stranded a global `code-graph-mcp` shim at
+// 0.101.0 while the binary reached 0.103.0 (RCA 2026-07-24). Cheap local
+// package.json read (readStale) gates the slow, lock-guarded npm path. Split out
+// so the decision is unit-testable without the full checkForUpdate harness.
+function shouldHealGlobalsOnThrottle(state, { readStale = staleGlobalPkgs } = {}) {
+  if (!state || !state.latestVersion) return false;
+  if (process.env.CODE_GRAPH_INSTALL_LOCK_HELD === '1') return false; // parent launcher holds it
+  return readStale(state.latestVersion).length > 0;
+}
+
 async function checkForUpdate({ installMissing = false, force = false } = {}) {
   let installLock = null;
   try {
@@ -683,6 +711,16 @@ async function checkForUpdate({ installMissing = false, force = false } = {}) {
       if (state.installedVersion !== installedVersion) {
         saveState({ ...state, installedVersion });
       }
+      // Global-npm shell/platform self-heal reaches the throttle window too (see
+      // shouldHealGlobalsOnThrottle). Cheap local check first; only the actually-
+      // stale case takes the slow, lock-guarded npm path.
+      if (shouldHealGlobalsOnThrottle(state)) {
+        installLock = acquireLock(path.join(CACHE_DIR, 'install.lock'));
+        if (installLock) {
+          const globalHeal = await selfHealGlobalPkgs({ version: state.latestVersion }, state);
+          saveState({ ...readState(), ...globalHeal });
+        }
+      }
       if (state.updateAvailable && state.latestVersion
           && compareVersions(state.latestVersion, installedVersion) > 0) {
         return { updateAvailable: true, from: installedVersion, to: state.latestVersion };
@@ -788,6 +826,7 @@ module.exports = {
   getPlatformAssetName,
   selfHealStaleBinary,
   selfHealGlobalPkgs, staleGlobalPkgs, globalPkgVersion, npmInstallGlobal,
+  shouldHealGlobalsOnThrottle, inactiveNodeGlobalRelics,
   downloadAndInstall, refreshMarketplaceClone, marketplaceCloneDir,
 };
 

package/claude-plugin/scripts/doctor.js

@@ -285,19 +285,45 @@ function runDiagnostics() {
   //    `lifecycle.js uninstall` removes them; without it they are treated as
   //    user-installed and a plugin uninstall leaves them on PATH.
   try {
-    const { globalPkgVersion } = require('./auto-update');
+    const { globalPkgVersion, inactiveNodeGlobalRelics } = require('./auto-update');
     const { PLATFORM_PKG } = require('./find-binary');
     const found = [SHELL_PKG, PLATFORM_PKG]
       .map((name) => ({ name, version: globalPkgVersion(name) }))
       .filter((p) => p.version);
+
+    // Relics stranded under a NON-active node version (nvm keeps a per-node
+    // global prefix). selfHealGlobalPkgs / the check above only see the active
+    // node, so these drift unseen for months and can seed stale settings.json
+    // hooks — the v24.11.1@0.46.0 relic behind the RCA. Report-only: `npm i -g`
+    // can't target another node's prefix, so hand the user the exact remediation.
+    const relics = inactiveNodeGlobalRelics();
+    if (relics.length) {
+      const home = require('os').homedir();
+      results.push({
+        name: 'Global npm relics',
+        status: 'warn',
+        detail: relics.map((r) => `${r.name}@${r.version} (${r.nodeModulesDir.replace(home, '~')})`).join('; ')
+          + ' — installed under a non-active node version; auto-heal cannot reach another node\'s prefix. '
+          + 'Remove each via `nvm use <that node> && npm rm -g <pkg>`, or uninstall the unused node (`nvm uninstall <ver>`).',
+      });
+    }
+
     if (found.length) {
       const marker = !!readJson(GLOBAL_INSTALL_MARKER);
+      // Heal-exhausted is otherwise invisible: selfHealGlobalPkgs stops after
+      // 3 failed npm runs per target version and stays silent until the next
+      // release re-arms the counter — a drifted CLI shim just sits there.
+      const state = readJson(path.join(CACHE_DIR, 'update-state.json')) || {};
+      const healGaveUp = (state.globalPkgHealAttempts || 0) >= 3;
       results.push({
         name: 'Global npm packages',
-        status: 'ok',
-        detail: found.map((p) => `${p.name}@${p.version}`).join(', ') + (marker
-          ? ' — plugin-installed; `node lifecycle.js uninstall` removes them'
-          : ` — no plugin-install marker; uninstall leaves them (remove: npm uninstall -g ${found.map((p) => p.name).join(' ')})`),
+        status: healGaveUp ? 'warn' : 'ok',
+        detail: found.map((p) => `${p.name}@${p.version}`).join(', ') + (healGaveUp
+          ? ` — self-heal gave up after ${state.globalPkgHealAttempts} failed npm runs targeting v${state.globalPkgHealVersion}; ` +
+            `your npm env likely can't install globally (EACCES/system node). Run manually: npm install -g ${found.map((p) => `${p.name}@${state.globalPkgHealVersion}`).join(' ')}`
+          : (marker
+            ? ' — plugin-installed; `node lifecycle.js uninstall` removes them'
+            : ` — no plugin-install marker; uninstall leaves them (remove: npm uninstall -g ${found.map((p) => p.name).join(' ')})`)),
       });
     }
   } catch { /* probe failed — skip */ }

package/claude-plugin/scripts/find-binary.js

@@ -4,7 +4,7 @@ const { execFileSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const { readBinaryVersion } = require('./version-utils');
+const { readBinaryVersion, compareVersions } = require('./version-utils');
 const { npmSpawnOpts } = require('./npm-exec');
 
 const PLATFORM = os.platform();
@@ -66,23 +66,8 @@ function getPackageVersion() {
   catch { return null; }
 }
 
-/**
- * Compare semver-ish "M.m.p" strings; returns -1, 0, or 1. Non-numeric parts → 0.
- * Assumes plain numeric releases (the project's tag scheme); a pre-release tag
- * (e.g. "1.2.3-rc1") is NOT semver-ordered — `parseInt("3-rc1", 10)` keeps the
- * leading 3 and drops the suffix, so "1.2.3-rc1" compares EQUAL to "1.2.3".
- * Revisit only if releases adopt pre-release tags.
- */
-function compareVersions(a, b) {
-  const pa = String(a).split('.').map(s => parseInt(s, 10));
-  const pb = String(b).split('.').map(s => parseInt(s, 10));
-  for (let i = 0; i < 3; i++) {
-    const x = Number.isFinite(pa[i]) ? pa[i] : 0;
-    const y = Number.isFinite(pb[i]) ? pb[i] : 0;
-    if (x !== y) return x < y ? -1 : 1;
-  }
-  return 0;
-}
+// compareVersions lives in version-utils.js (single canonical implementation,
+// pre-release-aware); re-exported below for existing consumers.
 
 /**
  * Candidate paths for npm global `node_modules`.
@@ -134,6 +119,22 @@ function globalNodeModulesCandidates() {
   return [...new Set(out)];
 }
 
+// Every nvm-managed node version's global node_modules dir (`~/.nvm/versions/
+// node/*/lib/node_modules`). nvm keeps a SEPARATE global prefix per node
+// version; switching the default node strands the previous version's globals —
+// a global `@sdsrs/code-graph` there is invisible to globalNodeModulesCandidates
+// (execPath-derived → only the ACTIVE node) yet still shadows PATH shims / seeds
+// stale settings.json hooks (the v24.11.1@0.46.0 relic — RCA 2026-07-24). Used
+// for detection/reporting only; `npm install -g` cannot target another node's
+// prefix. `base` is injectable for hermetic tests (never the real ~/.nvm).
+function nvmNodeModulesDirs(base = path.join(os.homedir(), '.nvm', 'versions', 'node')) {
+  let entries;
+  try { entries = fs.readdirSync(base); } catch { return []; }
+  return entries
+    .map((v) => path.join(base, v, 'lib', 'node_modules'))
+    .filter((d) => { try { return fs.statSync(d).isDirectory(); } catch { return false; } });
+}
+
 function isNativeBinary(candidate) {
   if (!candidate) return false;
   try {
@@ -217,19 +218,29 @@ function isDevRepo(rootDir) {
  * nvm/standard setups), so a working `npm install -g @sdsrs/code-graph` can
  * still be invisible without the fallback.
  */
+// Truncation gate for the npm platform-package tier ONLY: an interrupted npm
+// install can leave a partial binary with the right name, and unlike the
+// GitHub-download path (size + sha256 sidecar + version-exec before promote)
+// nothing else checks this tier. Real release binaries are ~40MB; 1MB matches
+// promoteVerifiedBinary's floor. Deliberately NOT inside isNativeBinary —
+// dev builds, cargo installs, and test fixtures go through other tiers.
+function isPlausibleReleaseBinary(candidate) {
+  try { return fs.statSync(candidate).size > 1_000_000; } catch { return false; }
+}
+
 function platformBinaryCandidates() {
   const out = [];
   // Fast path: standard module resolution.
   try {
     const pkgPath = require.resolve(`${PLATFORM_PKG}/package.json`);
     const bin = path.join(path.dirname(pkgPath), BINARY_NAME);
-    if (isNativeBinary(bin)) out.push(bin);
+    if (isNativeBinary(bin) && isPlausibleReleaseBinary(bin)) out.push(bin);
   } catch { /* not in node_modules walk-up */ }
 
   // Slow path: explicit global node_modules probe.
   for (const globalRoot of globalNodeModulesCandidates()) {
     const bin = path.join(globalRoot, '@sdsrs', `code-graph-${PLATFORM}-${ARCH}`, BINARY_NAME);
-    if (isNativeBinary(bin)) out.push(bin);
+    if (isNativeBinary(bin) && isPlausibleReleaseBinary(bin)) out.push(bin);
   }
 
   return out;
@@ -372,7 +383,7 @@ function clearCache() {
 
 module.exports = {
   findBinary, findBinaryUncached, clearCache,
-  globalNodeModulesCandidates, findPlatformBinary, createVersionGate,
+  globalNodeModulesCandidates, nvmNodeModulesDirs, findPlatformBinary, platformBinaryCandidates, createVersionGate,
   getPackageVersion, compareVersions, isCachedBinaryFresh,
   detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,

package/claude-plugin/scripts/lifecycle.js

@@ -197,25 +197,41 @@ function isPluginInactive(settings = readJson(settingsPath()) || {}) {
   return !hasInstalledPluginRecord();
 }
 
-function detachStatuslineIntegration(settings) {
+function detachStatuslineIntegration(settings, { compositeDoomed = true } = {}) {
   let settingsChanged = false;
 
   unregisterStatuslineProvider('code-graph');
-  const previous = readRegistry().find(p => p.id === '_previous' && p.command);
+  const registry = readRegistry();
+  const previous = registry.find(p => p.id === '_previous' && p.command);
+  // Third-party providers registered through our registry (e.g. gsd). They
+  // must not be silently orphaned: with the composite gone from settings
+  // their segments stop rendering while the registry entries dangle.
+  const thirdParty = registry.filter(p => p.id !== '_previous' && p.id !== 'code-graph' && p.command);
 
   // If our composite is still configured while the plugin is disabled/uninstalled,
-  // prefer restoring the prior statusline (or removing ours entirely) so the plugin
-  // truly stops affecting Claude Code.
+  // stop affecting Claude Code — but keep surviving third parties rendering.
   if (isOurComposite(settings)) {
-    if (previous) {
+    if (thirdParty.length > 0 && !compositeDoomed) {
+      // Temporary disable: the composite script survives on disk and keeps
+      // rendering the remaining providers — only our segment was unregistered.
+    } else if (thirdParty.length > 0) {
+      // Genuine uninstall: our composite runner dies with the plugin cache.
+      // Hand the slot to the first surviving third-party provider; the rest
+      // stay listed in the registry backup for manual re-wiring.
+      settings.statusLine = { type: 'command', command: thirdParty[0].command };
+      settingsChanged = true;
+    } else if (previous) {
       settings.statusLine = { type: 'command', command: previous.command };
+      settingsChanged = true;
     } else {
       delete settings.statusLine;
+      settingsChanged = true;
     }
-    settingsChanged = true;
   }
 
-  unregisterStatuslineProvider('_previous');
+  // _previous only becomes removable once no third party still relies on the
+  // registry file (writeRegistry unlinks primary+backup when emptied).
+  if (thirdParty.length === 0) unregisterStatuslineProvider('_previous');
   return settingsChanged;
 }
 
@@ -229,7 +245,7 @@ function cleanupDisabledStatusline() {
   // registry markers detachStatuslineIntegration is about to remove.
   const uninstalled = isPluginUninstalled(settings);
 
-  let settingsChanged = detachStatuslineIntegration(settings);
+  let settingsChanged = detachStatuslineIntegration(settings, { compositeDoomed: uninstalled });
   if (removeHooksFromSettings(settings)) settingsChanged = true;
   if (settingsChanged) {
     writeJsonAtomic(settingsPath(), settings);
@@ -359,13 +375,17 @@ function isOurHookEntry(entry) {
   if (!entry || !entry.hooks) return false;
   // Primary: match by description (immune to path pollution).
   if (entry.description && OUR_DESCRIPTIONS.includes(entry.description)) return true;
-  // Fallback: script name + MARKETPLACE_NAME in path. v0.32.1: tightened from
-  // bare 'code-graph' (which would claim a user's own ~/code-graph/foo.js) to
-  // the actual marketplace dir name 'code-graph-mcp' — Requirement 3 says
-  // foreign-entry strip is unacceptable, so be conservative.
+  // Fallback: script basename + a delivery-surface marker in the path. TWO
+  // surfaces ship these scripts: the marketplace plugin-cache (dir
+  // 'code-graph-mcp') AND the global npm package (dir '@sdsrs/code-graph' — note
+  // NO '-mcp' suffix). v0.32.1 tightened from bare 'code-graph' (which would
+  // claim a user's own ~/code-graph/foo.js) to MARKETPLACE_NAME, but that alone
+  // missed the npm-global surface, so `npm i -g`-delivered hooks were never
+  // evicted and orphan-accumulated across node/version switches (RCA 2026-07-24).
+  // Both markers are specific enough not to claim a user's unrelated file.
   return entry.hooks.some(h =>
     h.command && OUR_HOOK_SCRIPTS.some(s => h.command.includes(s)) &&
-    h.command.includes(MARKETPLACE_NAME)
+    (h.command.includes(MARKETPLACE_NAME) || h.command.includes(SHELL_PKG))
   );
 }
 
@@ -393,11 +413,20 @@ function removeHooksFromSettings(settings) {
 
 function buildSettingsHookEntries() {
   const root = PLUGIN_ROOT;
-  const scriptCmd = (name, timeout) => ({
-    type: 'command',
-    command: `node "${path.join(root, 'scripts', name)}"`,
-    timeout,
-  });
+  const scriptCmd = (name, timeout) => {
+    const script = path.join(root, 'scripts', name);
+    // POSIX: existence-guarded. After `/plugin uninstall`, CC may delete the
+    // plugin-cache dir before our statusline teardown gets to strip these
+    // entries — in that window every Edit/Bash/Read/prompt errored on a dead
+    // path. The `if` form preserves node's own exit code (PreToolUse deny =
+    // exit 2); `&& … || exit 0` would swallow it. Windows keeps the bare
+    // command — the hook shell there is not reliably cmd, so `if exist`
+    // can't be assumed.
+    const command = process.platform === 'win32'
+      ? `node "${script}"`
+      : `if [ -f "${script}" ]; then node "${script}"; fi`;
+    return { type: 'command', command, timeout };
+  };
 
   return {
     PreToolUse: [
@@ -423,6 +452,23 @@ function buildSettingsHookEntries() {
 // re-write it to settings.json.
 function registerHooksToSettings(settings) {
   settings.hooks = settings.hooks || {};
+
+  // Idempotent across delivery surfaces: if every desired (event,matcher) is
+  // already present exactly once, pointing at a current, existing script
+  // (plugin-cache OR global-npm), do nothing. Stops the settings.json ping-pong
+  // where the cache session-init and the npm-global CLI doctor each rewrote the
+  // other's valid entry every run (RCA 2026-07-24). Any missing/stale/dead entry
+  // — or a duplicate ( oursCount > expected) — still triggers evict+rewrite.
+  const survey = surveyHookCoverage(settings);
+  let oursCount = 0;
+  for (const entries of Object.values(settings.hooks)) {
+    if (Array.isArray(entries)) oursCount += entries.filter(isOurHookEntry).length;
+  }
+  if (survey.missing.length === 0 && survey.stale.length === 0
+      && oursCount === survey.expected.length) {
+    return false;
+  }
+
   const before = JSON.stringify(settings.hooks);
 
   // Pass 1: evict our entries across every event.
@@ -442,6 +488,22 @@ function registerHooksToSettings(settings) {
   return before !== JSON.stringify(settings.hooks);
 }
 
+// Extract the .js script path a hook command invokes — bare (`node "…"`) or
+// existence-guarded (`if [ -f "…" ]; then node "…"; fi`).
+function hookCmdScript(cmd) {
+  const m = (cmd || '').match(/node "([^"]+\.js)"/) || (cmd || '').match(/"([^"]+\.js)"/);
+  return m ? m[1] : null;
+}
+
+// Version encoded in a plugin-cache path (.../code-graph-mcp/code-graph-mcp/<ver>/scripts/…).
+// Null for in-place installs (global npm), whose path never carries a version
+// dir — npm overwrites the same path on upgrade, so such a path never goes
+// version-stale (only dead-path-stale, caught separately by fs.existsSync).
+function cacheDirVersion(scriptPath) {
+  const m = (scriptPath || '').match(/\/code-graph-mcp\/code-graph-mcp\/(\d+\.\d+\.\d+[^/]*)\//);
+  return m ? m[1] : null;
+}
+
 // Inventory of (event, matcher) tuples we expect to find in settings.json after
 // install. Consumed by doctor (report + fix) and session-init (self-heal):
 // `missing` = entry absent; `stale` = present but the registered command no
@@ -479,10 +541,26 @@ function surveyHookCoverage(settings) {
     }
   }
 
+  const { compareVersions } = require('./version-utils');
   const missing = expected.filter(k => !present.has(k));
-  const stale = expected.filter(k =>
-    present.has(k) && desiredCmd[k] && presentCmd[k] && presentCmd[k] !== desiredCmd[k]
-  );
+  // Version/surface-tolerant staleness. Was an exact command-string compare,
+  // which made two registration authorities (plugin-cache session-init vs
+  // global-npm CLI doctor — different absolute paths) each flag the other's
+  // VALID CURRENT entry stale and rewrite it → settings.json ping-pong on every
+  // alternating run (RCA 2026-07-24). An entry is stale only when its script is
+  // a dead path OR resolves to an OLDER plugin-cache version dir than we'd write
+  // now. A present entry on a different but valid, current surface (npm in-place
+  // install: file exists, no version in path) is NOT stale.
+  const stale = expected.filter(k => {
+    if (!present.has(k) || !presentCmd[k]) return false;
+    const pScript = hookCmdScript(presentCmd[k]);
+    if (!pScript) return false;
+    if (!fs.existsSync(pScript)) return true;             // dead path
+    const pv = cacheDirVersion(pScript);
+    const dv = cacheDirVersion(hookCmdScript(desiredCmd[k]));
+    if (pv && dv) return compareVersions(pv, dv) < 0;     // older cache version dir
+    return false;                                         // in-place/current surface
+  });
   return { expected, present: [...present], missing, stale };
 }
 
@@ -604,7 +682,7 @@ function verifyHooksFire({ hooks, env, timeoutMs = 4000, tmpBase } = {}) {
 
 // --- Install (idempotent) ---
 
-function install() {
+function install({ reclaimStatusline = false } = {}) {
   const version = getPluginVersion();
   const manifest = readManifest();
   const settings = readJson(settingsPath()) || {};
@@ -620,14 +698,40 @@ function install() {
   //    b. Register code-graph as a provider
   //    c. Set statusLine to composite script
   if (!isOurComposite(settings)) {
-    // Preserve existing statusline as first provider
-    if (settings.statusLine && settings.statusLine.command) {
-      registerStatuslineProvider('_previous', settings.statusLine.command, true);
+    // Displacement tracking: we held the slot before (manifest.config.statusLine)
+    // but a foreign command sits there now — either another slot-claiming plugin
+    // (whose own self-heal re-takes it just like ours would → statusline
+    // ping-pong every session) or the user's deliberate choice. Either way,
+    // silently re-claiming forever is wrong: after >2 observed displacements
+    // stand down — stay registered as a provider, leave the slot alone.
+    // Explicit `lifecycle.js install` (or CODE_GRAPH_FORCE_STATUSLINE=1)
+    // resets the counter and re-claims.
+    const currentCmd = settings.statusLine && settings.statusLine.command;
+    if (reclaimStatusline || process.env.CODE_GRAPH_FORCE_STATUSLINE === '1') {
+      manifest.config.statuslineDisplaced = 0;
+    } else if (manifest.config.statusLine === true && currentCmd) {
+      manifest.config.statuslineDisplaced = (manifest.config.statuslineDisplaced || 0) + 1;
+    }
+    if ((manifest.config.statuslineDisplaced || 0) > 2) {
+      if (manifest.config.statusLine === true) {
+        // Transition into stand-down exactly once: release claimed ownership
+        // (stops the counter) and leave a breadcrumb.
+        manifest.config.statusLine = false;
+        process.stderr.write(
+          '[code-graph] statusLine slot keeps being re-claimed by another provider — standing down.\n' +
+          '            Re-claim: CODE_GRAPH_FORCE_STATUSLINE=1 or `node lifecycle.js install`\n'
+        );
+      }
+    } else {
+      // Preserve existing statusline as first provider
+      if (currentCmd) {
+        registerStatuslineProvider('_previous', currentCmd, true);
+      }
+      // Set composite as the statusLine
+      settings.statusLine = { type: 'command', command: compositeCommand() };
+      settingsChanged = true;
+      manifest.config.statusLine = true;
     }
-    // Set composite as the statusLine
-    settings.statusLine = { type: 'command', command: compositeCommand() };
-    settingsChanged = true;
-    manifest.config.statusLine = true;
   } else {
     // Composite exists — ensure path is correct (may have been polluted by env leak)
     const cmd = compositeCommand();
@@ -635,6 +739,9 @@ function install() {
       settings.statusLine.command = cmd;
       settingsChanged = true;
     }
+    // We hold the slot — any displacement episode is over.
+    if (manifest.config.statuslineDisplaced) manifest.config.statuslineDisplaced = 0;
+    manifest.config.statusLine = true;
   }
 
   // Register code-graph provider
@@ -690,7 +797,7 @@ function defaultRunNpm(args) {
   } catch { return false; }
 }
 
-function uninstall({ purgeGlobal = false, runNpm = defaultRunNpm, scanGlobalPkgs = installedGlobalPkgs } = {}) {
+function uninstall({ purgeGlobal = false, unadoptAll = false, runNpm = defaultRunNpm, scanGlobalPkgs = installedGlobalPkgs } = {}) {
   const settings = readJson(settingsPath());
   let settingsChanged = false;
 
@@ -742,6 +849,27 @@ function uninstall({ purgeGlobal = false, runNpm = defaultRunNpm, scanGlobalPkgs
   const pluginInstalledGlobals = !!readJson(GLOBAL_INSTALL_MARKER);
   let adoptedProjects = [];
   try { adoptedProjects = require('./adopt').readAdoptedProjects(); } catch { /* POSIX-only helper — ok */ }
+
+  // 5.4. --unadopt-all: sweep every registered project's managed CLAUDE.md
+  // block + generated detail file (unadopt is marker-guarded, so user files
+  // are never touched; the .code-graph/ index dir is project DATA and stays —
+  // its removal is listed in the guidance instead of automated).
+  const unadopted = [];
+  if (unadoptAll && adoptedProjects.length) {
+    let unadoptFn = null;
+    try { unadoptFn = require('./adopt').unadopt; } catch { /* POSIX-only — skip */ }
+    if (unadoptFn) {
+      for (const project of adoptedProjects) {
+        try {
+          const r = unadoptFn({ cwd: project });
+          unadopted.push({ project, ok: !!(r && r.ok), cleaned: !!(r && (r.blockPruned || r.fileRemoved || r.claudeMdRemoved)) });
+        } catch (e) {
+          unadopted.push({ project, ok: false, error: (e && e.message) || String(e) });
+        }
+      }
+      try { adoptedProjects = require('./adopt').readAdoptedProjects(); } catch { /* ok */ }
+    }
+  }
   let globalPkgsRemoved = [];
   let globalPkgsRemaining = scanGlobalPkgs();
   if (globalPkgsRemaining.length && (pluginInstalledGlobals || purgeGlobal)) {
@@ -765,7 +893,7 @@ function uninstall({ purgeGlobal = false, runNpm = defaultRunNpm, scanGlobalPkgs
     try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ok */ }
   }
 
-  return { settingsChanged, pluginInstalledGlobals, globalPkgsRemoved, globalPkgsRemaining, adoptedProjects };
+  return { settingsChanged, pluginInstalledGlobals, globalPkgsRemoved, globalPkgsRemaining, adoptedProjects, unadopted };
 }
 
 // --- Update (refresh config points) ---
@@ -1020,11 +1148,23 @@ module.exports = {
 if (require.main === module) {
   const cmd = process.argv[2];
   if (cmd === 'install') {
-    const r = install();
+    // Explicit CLI install = user intent: reset any statusline stand-down and re-claim.
+    const r = install({ reclaimStatusline: true });
     console.log(`Installed v${r.version} | settings=${r.settingsChanged} | statusLine=${r.statusLineClaimed}`);
   } else if (cmd === 'uninstall') {
-    const r = uninstall({ purgeGlobal: process.argv.includes('--purge-global') });
+    const r = uninstall({
+      purgeGlobal: process.argv.includes('--purge-global'),
+      unadoptAll: process.argv.includes('--unadopt-all'),
+    });
     console.log(`Uninstalled | settings cleaned=${r.settingsChanged}`);
+    if (r.unadopted.length) {
+      const cleaned = r.unadopted.filter((u) => u.cleaned).length;
+      console.log(`  Unadopted ${cleaned}/${r.unadopted.length} registered project(s):`);
+      for (const u of r.unadopted) {
+        console.log(`    ${u.ok ? (u.cleaned ? 'cleaned' : 'nothing-to-clean') : `FAILED (${u.error || 'unknown'})`}  ${u.project}`);
+      }
+      console.log('    Their .code-graph/ index dirs are project data — remove per project with `rm -rf .code-graph` if unwanted.');
+    }
     if (r.globalPkgsRemoved.length) {
       console.log(`  Removed global npm package(s): ${r.globalPkgsRemoved.join(', ')}`);
     }
@@ -1038,7 +1178,7 @@ if (require.main === module) {
     if (r.adoptedProjects.length) {
       console.log('  Adopted project(s) still carrying a managed CLAUDE.md block + .code-graph/ index:');
       for (const p of r.adoptedProjects) console.log(`    ${p}`);
-      console.log('    In each: run `code-graph-mcp unadopt` and `rm -rf .code-graph` to clean up.');
+      console.log('    Clean all at once: re-run with --unadopt-all, or per project `code-graph-mcp unadopt` + `rm -rf .code-graph`.');
     }
     console.log('  Note: also run `/plugin uninstall code-graph-mcp` inside Claude Code to sync its UI state.');
   } else if (cmd === 'update') {

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

@@ -150,6 +150,10 @@ if (!binary) {
 
   const stub = serveEmptyMcpStub({
     upgrade: {
+      // Each probe is a full discovery walk (incl. `npm root -g`, up to 2s);
+      // offline the binary never appears, so back the poll off toward 60s.
+      // The install chain's onInstalled nudge below still upgrades instantly.
+      backoff: true,
       shouldUpgrade: () => !!findBinary(),
       spawnReal: () => {
         const bin = findBinary();

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

@@ -52,6 +52,8 @@ function serveEmptyMcpStub(opts = {}) {
   const queuedForChild = [];    // client lines seen after spawn, before child is ready
   let poller = null;
   let upgradeFailures = 0;      // consecutive failed upgrade attempts (see noteUpgradeFailure)
+  let backoffTicks = 0;         // poll ticks to skip before the next probe (upgrade.backoff)
+  let backoffNext = 1;
 
   function writeCc(obj) { output.write(JSON.stringify(obj) + '\n'); }
 
@@ -133,7 +135,20 @@ function serveEmptyMcpStub(opts = {}) {
 
   function attemptUpgrade() {
     if (child || !upgrade) return;
-    if (!upgrade.shouldUpgrade()) return;            // not a project yet — not a failure
+    if (!upgrade.shouldUpgrade()) {
+      // Not upgradable yet — not a failure. But when the probe itself is
+      // expensive (missing-binary: full discovery walk incl. `npm root -g`,
+      // up to 2s), a flat 4s cadence for a whole offline session is pure
+      // subprocess churn. With { backoff:true } skip a doubling number of
+      // ticks between probes, capped near 60s; a manual attemptUpgrade()
+      // nudge (install chain's onInstalled) still probes immediately.
+      if (upgrade.backoff) {
+        const pollMs = upgrade.pollMs || DEFAULT_POLL_MS;
+        backoffTicks = backoffNext;
+        backoffNext = Math.min(backoffNext * 2, Math.max(1, Math.floor(60000 / pollMs) - 1));
+      }
+      return;
+    }
     const spawned = upgrade.spawnReal();
     if (!spawned) { noteUpgradeFailure('binary-unresolved'); return; }
     if (poller) { clearIv(poller); poller = null; }
@@ -141,6 +156,13 @@ function serveEmptyMcpStub(opts = {}) {
     beginProxy();
   }
 
+  // Poll-timer tick: honors the backoff skip counter; the exported
+  // attemptUpgrade stays direct so external nudges are never delayed.
+  function pollTick() {
+    if (backoffTicks > 0) { backoffTicks--; return; }
+    attemptUpgrade();
+  }
+
   function fallBackToStub(reason) {
     // Child spawned but died/errored before it was ready: answer anything the
     // client queued (so it doesn't hang on those ids), resume polling, and count
@@ -153,7 +175,7 @@ function serveEmptyMcpStub(opts = {}) {
       try { const req = JSON.parse(line); if (req && typeof req.method === 'string') answerAsStub(req); }
       catch { /* ignore */ }
     }
-    if (upgrade && !poller) poller = setIv(attemptUpgrade, upgrade.pollMs || DEFAULT_POLL_MS);
+    if (upgrade && !poller) poller = setIv(pollTick, upgrade.pollMs || DEFAULT_POLL_MS);
     noteUpgradeFailure(reason);
   }
 
@@ -206,7 +228,7 @@ function serveEmptyMcpStub(opts = {}) {
     });
   }
 
-  if (upgrade) poller = setIv(attemptUpgrade, upgrade.pollMs || DEFAULT_POLL_MS);
+  if (upgrade) poller = setIv(pollTick, upgrade.pollMs || DEFAULT_POLL_MS);
 
   return { attemptUpgrade, _state: () => ({ hasChild: !!child, childReady }) };
 }

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

@@ -553,9 +553,15 @@ function runSessionInit({ source } = {}) {
   }
   if (autoAdopt.attempted && autoAdopt.result && autoAdopt.result.ok) {
     if (autoAdopt.reason === 'refreshed') {
+      // Name BOTH refreshed surfaces: the drift-refresh fully overwrites the
+      // generated detail doc, so a user who hand-edited it must learn why
+      // their edits vanished and how to lock the file.
+      const detailNote = autoAdopt.result.detailWritten
+        ? ' + .claude/plugin_code_graph_mcp.md (manual edits to that generated file are overwritten)'
+        : '';
       process.stderr.write(
-        '[code-graph] Refreshed CLAUDE.md decision block to latest shipped version.\n' +
-        '            Lock file:  CODE_GRAPH_NO_TEMPLATE_REFRESH=1 in ~/.claude/settings.json env\n'
+        `[code-graph] Refreshed CLAUDE.md decision block to latest shipped version${detailNote}.\n` +
+        '            Lock files: CODE_GRAPH_NO_TEMPLATE_REFRESH=1 in ~/.claude/settings.json env\n'
       );
     } else {
       process.stderr.write(

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

@@ -26,6 +26,37 @@ function readBinaryVersion(binaryPath) {
   }
 }
 
+/**
+ * Compare semver-ish version strings; returns -1, 0, or 1. Numeric triple
+ * compared ordinally (missing/non-numeric parts → 0); a pre-release suffix
+ * sorts BELOW its release ("1.2.3-rc1" < "1.2.3"), two pre-releases compare
+ * as plain strings. Single canonical implementation — auto-update.js and
+ * find-binary.js each carried a divergent copy whose pre-release semantics
+ * disagreed (Number("4-rc1")→NaN→0 vs parseInt("3-rc1")→3), a silent
+ * mis-ordering trap if release tags ever adopt "-rc" suffixes.
+ */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const s = String(v);
+    const dash = s.indexOf('-');
+    const core = dash === -1 ? s : s.slice(0, dash);
+    return {
+      nums: core.split('.').map((x) => parseInt(x, 10)),
+      pre: dash === -1 ? null : s.slice(dash + 1),
+    };
+  };
+  const pa = parse(a), pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const x = Number.isFinite(pa.nums[i]) ? pa.nums[i] : 0;
+    const y = Number.isFinite(pb.nums[i]) ? pb.nums[i] : 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  if (pa.pre && !pb.pre) return -1;
+  if (!pa.pre && pb.pre) return 1;
+  if (pa.pre && pb.pre && pa.pre !== pb.pre) return pa.pre < pb.pre ? -1 : 1;
+  return 0;
+}
+
 function isDevMode(pluginRoot = path.resolve(__dirname, '..')) {
   // Explicit opt-in always wins (also lets users force dev mode in any layout)
   if (process.env.CODE_GRAPH_DEV === '1') return true;
@@ -63,4 +94,4 @@ function getNewestMtime(dir, ext = '.rs') {
   return newest;
 }
 
-module.exports = { readBinaryVersion, isDevMode, getNewestMtime, VERSION_OUTPUT_RE };
+module.exports = { readBinaryVersion, compareVersions, isDevMode, getNewestMtime, VERSION_OUTPUT_RE };

package/package.json

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