@sdsrs/code-graph 0.102.0 → 0.103.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.103.0",
   "keywords": [
     "code-graph",
     "ast",

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

@@ -10,7 +10,7 @@ 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 { 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 ─────────────────────────────────────────────
 

package/claude-plugin/scripts/doctor.js

@@ -292,12 +292,20 @@ function runDiagnostics() {
       .filter((p) => p.version);
     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`.
@@ -217,19 +202,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 +367,7 @@ function clearCache() {
 
 module.exports = {
   findBinary, findBinaryUncached, clearCache,
-  globalNodeModulesCandidates, findPlatformBinary, createVersionGate,
+  globalNodeModulesCandidates, 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);
@@ -393,11 +409,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: [
@@ -604,7 +629,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 +645,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 +686,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 +744,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 +796,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 +840,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 +1095,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 +1125,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.103.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.103.0",
+    "@sdsrs/code-graph-linux-arm64": "0.103.0",
+    "@sdsrs/code-graph-darwin-x64": "0.103.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.103.0",
+    "@sdsrs/code-graph-win32-x64": "0.103.0"
   }
 }