@sdsrs/code-graph 0.101.0 → 0.103.0

package/claude-plugin/scripts/lifecycle.js

@@ -18,6 +18,13 @@ const CACHE_DIR = path.join(os.homedir(), '.cache', 'code-graph');
 const PLUGIN_ROOT = path.resolve(__dirname, '..');
 const MANIFEST_FILE = path.join(CACHE_DIR, 'install-manifest.json');
 const REGISTRY_FILE = path.join(CACHE_DIR, 'statusline-registry.json');
+// Written by the launcher's background install when ITS `npm install -g` step
+// introduced the global shell + platform packages. Uninstall only removes
+// global packages it can prove the plugin installed (marker present) or when
+// the user passes --purge-global — a deliberate user install is never yanked.
+const GLOBAL_INSTALL_MARKER = path.join(CACHE_DIR, 'global-install-marker.json');
+const INSTALL_LOCK_FILE = path.join(CACHE_DIR, 'install.lock');
+const SHELL_PKG = '@sdsrs/code-graph';
 
 // Lazy resolvers — Claude Code's config dir can be overridden by CLAUDE_CONFIG_DIR
 // (multi-account isolation). Re-read every call so test subprocesses with a
@@ -190,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;
 }
 
@@ -218,13 +241,25 @@ function cleanupDisabledStatusline() {
     return { cleaned: false, settingsChanged: false };
   }
 
-  let settingsChanged = detachStatuslineIntegration(settings);
+  // Decide BEFORE mutating: isPluginUninstalled reads the same composite/
+  // registry markers detachStatuslineIntegration is about to remove.
+  const uninstalled = isPluginUninstalled(settings);
+
+  let settingsChanged = detachStatuslineIntegration(settings, { compositeDoomed: uninstalled });
   if (removeHooksFromSettings(settings)) settingsChanged = true;
   if (settingsChanged) {
     writeJsonAtomic(settingsPath(), settings);
   }
 
-  return { cleaned: true, settingsChanged };
+  // Genuine uninstall (not a temporary disable): reclaim ~/.cache/code-graph
+  // too. This statusline-render path is the ONLY plugin code guaranteed to
+  // still run after `/plugin uninstall` — Claude Code stops loading the
+  // plugin's hooks.json, so the SessionStart teardown in session-init.js never
+  // fires post-uninstall. Without this, the ~40MB cached binary leaked forever.
+  let cacheRemoved = false;
+  if (uninstalled) cacheRemoved = removeCacheResidue();
+
+  return { cleaned: true, settingsChanged, cacheRemoved };
 }
 
 // --- Scope Conflict Detection ---
@@ -374,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: [
@@ -585,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()) || {};
@@ -601,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();
@@ -616,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
@@ -648,7 +721,30 @@ function install() {
 
 // --- Uninstall (clean all config) ---
 
-function uninstall() {
+/** Which of our npm packages exist at a global top level right now. */
+function installedGlobalPkgs() {
+  const { globalNodeModulesCandidates, PLATFORM_PKG } = require('./find-binary');
+  const found = [];
+  for (const name of [SHELL_PKG, PLATFORM_PKG]) {
+    for (const root of globalNodeModulesCandidates()) {
+      if (fs.existsSync(path.join(root, name, 'package.json'))) { found.push(name); break; }
+    }
+  }
+  return found;
+}
+
+function defaultRunNpm(args) {
+  const { spawnSync } = require('child_process');
+  const { npmSpawnOpts } = require('./npm-exec');
+  try {
+    const r = spawnSync('npm', args, npmSpawnOpts({
+      timeout: 120000, stdio: 'pipe', encoding: 'utf8',
+    }));
+    return !r.error && r.status === 0;
+  } catch { return false; }
+}
+
+function uninstall({ purgeGlobal = false, unadoptAll = false, runNpm = defaultRunNpm, scanGlobalPkgs = installedGlobalPkgs } = {}) {
   const settings = readJson(settingsPath());
   let settingsChanged = false;
 
@@ -692,6 +788,44 @@ function uninstall() {
     if (ipChanged) writeJsonAtomic(installedPluginsPath(), installedPlugins);
   }
 
+  // 5.5. Global npm packages + adoption inventory — read BEFORE step 6 wipes
+  // CACHE_DIR (both the install marker and the adopted-projects registry live
+  // there). The launcher's background install runs `npm install -g` on the
+  // user's behalf; nothing on the Claude Code uninstall path ever removes those
+  // packages (~40MB platform binary + CLI shim left on PATH forever).
+  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)) {
+    if (runNpm(['uninstall', '-g', ...globalPkgsRemaining])) {
+      globalPkgsRemoved = globalPkgsRemaining;
+      globalPkgsRemaining = scanGlobalPkgs(); // re-scan: report only what actually survived
+    }
+  }
+
   // 6. Remove cache directory
   try { fs.rmSync(CACHE_DIR, { recursive: true, force: true }); } catch { /* ok */ }
 
@@ -706,7 +840,7 @@ function uninstall() {
     try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ok */ }
   }
 
-  return { settingsChanged };
+  return { settingsChanged, pluginInstalledGlobals, globalPkgsRemoved, globalPkgsRemaining, adoptedProjects, unadopted };
 }
 
 // --- Update (refresh config points) ---
@@ -952,6 +1086,7 @@ module.exports = {
   SETTINGS_HOOK_DESC, OUR_HOOK_SCRIPTS, OUR_DESCRIPTIONS,              // v0.32.0 — for tests
   PLUGIN_ROOT,                                                         // v0.32.1 — for tests / consumers
   registerStatuslineProvider, unregisterStatuslineProvider,
+  installedGlobalPkgs, GLOBAL_INSTALL_MARKER, INSTALL_LOCK_FILE, SHELL_PKG,   // uninstall residue
   PLUGIN_ID, OLD_PLUGIN_IDS, MARKETPLACE_NAME, CACHE_DIR, REGISTRY_FILE,
   settingsPath, installedPluginsPath, providersBackupFile, pluginsCacheDir,
 };
@@ -960,13 +1095,39 @@ 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();
+    const r = uninstall({
+      purgeGlobal: process.argv.includes('--purge-global'),
+      unadoptAll: process.argv.includes('--unadopt-all'),
+    });
     console.log(`Uninstalled | settings cleaned=${r.settingsChanged}`);
-    console.log('  Note: also run `/plugin uninstall code-graph-mcp` inside Claude Code to sync its UI state,');
-    console.log('  and `code-graph-mcp unadopt` in each adopted project to remove its CLAUDE.md block.');
+    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(', ')}`);
+    }
+    if (r.globalPkgsRemaining.length) {
+      console.log(`  Global npm package(s) still installed: ${r.globalPkgsRemaining.join(', ')}`);
+      console.log(`    Remove with: npm uninstall -g ${r.globalPkgsRemaining.join(' ')}`);
+      if (!r.pluginInstalledGlobals) {
+        console.log('    (left in place: no plugin-install marker, so they may be your own install; --purge-global forces removal)');
+      }
+    }
+    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('    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') {
     const r = update();
     console.log(`Updated ${r.oldVersion} → ${r.version} | settings=${r.settingsChanged}`);

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

@@ -7,7 +7,7 @@
  * Used by .mcp.json so the plugin controls binary discovery instead of
  * relying on the binary being in PATH.
  */
-const { spawn, spawnSync } = require('child_process');
+const { spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const { isNonProjectCwd } = require('./project-detect');
@@ -86,66 +86,15 @@ if (process.env.CODE_GRAPH_FORCE_PLUGIN_MCP !== '1' && isNonProjectCwd(process.c
 }
 
 const { findBinary, clearCache, unsupportedPlatformHint } = require('./find-binary');
+const { installBinaryInBackground } = require('./launcher-install');
 
-let binary = findBinary();
+const binary = findBinary();
 
-// Auto-install binary if not found (first-time install)
-if (!binary) {
-  let version = 'latest';
-  try {
-    const pj = path.join(__dirname, '..', '.claude-plugin', 'plugin.json');
-    version = JSON.parse(fs.readFileSync(pj, 'utf8')).version || 'latest';
-  } catch { /* use latest */ }
-
-  process.stderr.write(`[code-graph] Binary not found, installing @sdsrs/code-graph@${version}...\n`);
-  const npmResult = spawnSync('npm', ['install', '-g', `@sdsrs/code-graph@${version}`], {
-    timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
-  });
-  if (npmResult.error || npmResult.status !== 0) {
-    process.stderr.write('[code-graph] npm install failed.\n');
-    if (npmResult.stderr) {
-      process.stderr.write(npmResult.stderr.trim().split('\n').map(l => `[code-graph][npm] ${l}\n`).join(''));
-    }
-  } else {
-    clearCache();
-    binary = findBinary();
-    if (binary) {
-      process.stderr.write(`[code-graph] Installed at ${binary}\n`);
-    }
-  }
-}
-
-// Fallback: npm install may have succeeded but optionalDependencies for the
-// platform binary can fail silently (npm tolerates OS-mismatch + flaky
-// registry). Pull the platform binary directly from the GitHub release.
-//
-// --install-missing bypasses auto-update.js's isDevMode() short-circuit. The
-// marketplace ships the full repo (including Cargo.toml at the workspace root),
-// so dev-mode heuristics that look for Cargo.toml were misclassifying every
-// marketplace install as dev mode and skipping this fallback (issue #12).
-if (!binary) {
-  process.stderr.write('[code-graph] Falling back to GitHub release download...\n');
-  const result = spawnSync(
-    process.execPath,
-    [path.join(__dirname, 'auto-update.js'), '--silent', '--install-missing'],
-    { timeout: 90000, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }
-  );
-  if (result.stderr && result.stderr.trim()) {
-    process.stderr.write(result.stderr.trim().split('\n').map(l => `[code-graph][auto-update] ${l}\n`).join(''));
-  }
-  if (result.error) {
-    process.stderr.write(`[code-graph] auto-update spawn failed: ${result.error.message}\n`);
-  } else if (result.status !== 0) {
-    process.stderr.write(`[code-graph] auto-update exited with status ${result.status}\n`);
-  }
-  clearCache();
-  binary = findBinary();
-  if (binary) {
-    process.stderr.write(`[code-graph] Installed at ${binary}\n`);
-  }
-}
-
-if (!binary) {
+// Manual-install guidance, printed when the background install chain exhausts
+// both steps without producing a binary. Unlike the old sync path this does NOT
+// exit: the upgradeable stub stays connected (0 tools), so a manual
+// `npm install -g` mid-session still upgrades the live connection.
+function printManualInstallHints() {
   const installedViaMarketplace = fs.existsSync(
     path.join(__dirname, '..', '.claude-plugin', 'plugin.json')
   );
@@ -155,9 +104,9 @@ if (!binary) {
     // npm package does not exist, so the generic "npm install @sdsrs/code-graph-<plat>-<arch>"
     // suggestion below would point at a nonexistent package. Show the source/emulation hint.
     process.stderr.write('[code-graph] Binary not found.\n' + platformHint + '\n');
-    process.exit(1);
+    return;
   }
-  process.stderr.write('[code-graph] Binary not found. Install manually:\n');
+  process.stderr.write('[code-graph] Binary install failed. Install manually:\n');
   if (installedViaMarketplace) {
     process.stderr.write(
       '  # Re-install the plugin via Claude Code marketplace:\n' +
@@ -171,7 +120,71 @@ if (!binary) {
     '  npm install -g @sdsrs/code-graph\n' +
     '  npm install -g @sdsrs/code-graph-' + process.platform + '-' + process.arch + '\n'
   );
-  process.exit(1);
+}
+
+// --- Missing binary: answer the handshake NOW, install in the background ----
+// The old chain ran `npm install -g` (60s timeout) and the GitHub-release
+// fallback (90s) SYNCHRONOUSLY before answering any MCP JSON-RPC. Claude
+// Code's connect timeout is 30s, so a cold install always presented as
+// "MCP server connection timed out after 30000ms" and the tools only appeared
+// on a later reconnect. Serve the upgradeable 0-tool stub first (initialize is
+// answered instantly), run the same install chain in the background, and hand
+// the live connection to the real binary via the same upgrade mechanism the
+// non-project gate uses — no reconnect, no restart.
+//
+// --install-missing bypasses auto-update.js's isDevMode() short-circuit. The
+// marketplace ships the full repo (including Cargo.toml at the workspace root),
+// so dev-mode heuristics that look for Cargo.toml were misclassifying every
+// marketplace install as dev mode and skipping this fallback (issue #12).
+if (!binary) {
+  let version = 'latest';
+  try {
+    const pj = path.join(__dirname, '..', '.claude-plugin', 'plugin.json');
+    version = JSON.parse(fs.readFileSync(pj, 'utf8')).version || 'latest';
+  } catch { /* use latest */ }
+
+  process.stderr.write(
+    `[code-graph] Binary not found — serving 0-tool stub while installing ` +
+    `@sdsrs/code-graph@${version} in the background (tools appear when it lands)...\n`
+  );
+
+  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();
+        if (!bin) return null;
+        process.stderr.write(`[code-graph] binary ready at ${bin} — upgrading plugin MCP to real tools (restart Claude Code for full tool steering)\n`);
+        return spawn(bin, ['serve'], { stdio: ['pipe', 'pipe', 'inherit'], env: process.env });
+      },
+    },
+  });
+
+  const { GLOBAL_INSTALL_MARKER, INSTALL_LOCK_FILE } = require('./lifecycle');
+  installBinaryInBackground({
+    version,
+    findBinary,
+    clearCache,
+    // Nudge the handover immediately instead of waiting for the stub's next poll.
+    onInstalled: () => stub.attemptUpgrade(),
+    onFailed: () => printManualInstallHints(),
+    // Marker: this npm install was OURS, so lifecycle.js uninstall knows it
+    // owns removing the global packages (never yanks a user's own install).
+    recordGlobalInstall: () => {
+      fs.mkdirSync(path.dirname(GLOBAL_INSTALL_MARKER), { recursive: true });
+      fs.writeFileSync(GLOBAL_INSTALL_MARKER, JSON.stringify({
+        installedBy: 'code-graph-mcp launcher', version, at: new Date().toISOString(),
+      }, null, 2) + '\n');
+    },
+    // Serialize against other cold sessions + auto-update (parallel global npm
+    // installs corrupt the shared prefix).
+    lockPath: INSTALL_LOCK_FILE,
+  });
+  return; // top-level function scope of mcp-launcher.js
 }
 
 // Pre-spawn: verify binary is executable (catches macOS quarantine, permission issues)

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/npm-exec.js

@@ -0,0 +1,15 @@
+'use strict';
+// npm is `npm.cmd` on Windows: child_process spawn/execFileSync cannot exec a
+// .cmd without a shell (and Node >= 18.20 throws EINVAL spawning .cmd directly
+// as a CVE-2024-27980 mitigation). Every bare `spawn('npm', ...)` in the
+// install/update flow therefore silently ENOENT'd on Windows while
+// commandExists('npm') (via `where`) said npm was present. All args routed
+// through here are fixed flags / package specs — shell-quoting-safe.
+const NPM_NEEDS_SHELL = process.platform === 'win32';
+
+/** Merge shell:true into spawn/exec options when the platform needs it. */
+function npmSpawnOpts(opts = {}) {
+  return NPM_NEEDS_SHELL ? { ...opts, shell: true } : opts;
+}
+
+module.exports = { npmSpawnOpts, NPM_NEEDS_SHELL };

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

@@ -480,10 +480,13 @@ function runSessionInit({ source } = {}) {
     cleanupDisabledStatusline();
     // Genuine uninstall (not a temporary disable) leaves residue the settings-only
     // self-heal can't reach: ~/.cache/code-graph (the ~40MB binary + state) and the
-    // current project's CLAUDE.md adoption block. CC fires no uninstall hook, so this
-    // SessionStart is the only automated teardown — symmetric to install's auto-adopt.
-    // Per-project: only the cwd we're in; other adopted projects self-clean when next
-    // opened, or via `code-graph-mcp unadopt`.
+    // current project's CLAUDE.md adoption block. CC fires no uninstall hook, AND it
+    // stops loading this plugin's hooks.json the moment the install record is gone —
+    // so after a real `/plugin uninstall` this SessionStart usually never runs again.
+    // The reachable teardown is cleanupDisabledStatusline() via the composite
+    // statusline (still wired in settings.json); it removes the cache residue too.
+    // This branch remains for the disable→uninstall-while-running edge and as the
+    // only place project unadoption can happen automatically.
     let teardown = null;
     if (uninstalled) {
       const cacheRemoved = removeCacheResidue();
@@ -550,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/statusline.js

@@ -57,13 +57,31 @@ const codeGraphDir = path.join(root, '.code-graph');
 // Check for background indexing progress file first
 const progressFile = path.join(codeGraphDir, 'indexing-status.json');
 try {
-  const raw = fs.readFileSync(progressFile, 'utf8');
-  const p = JSON.parse(raw);
-  if (p.s === 'indexing' && p.t > 0) {
-    const pct = Math.round((p.d / p.t) * 100);
+  // Staleness gate: the file is normally deleted by the server's IndexGuard, but
+  // a killed process (session exit, SIGKILL, the 30s MCP connect-timeout kill)
+  // skips Drop, and the orphan would pin "indexing N/M" here forever. A LIVE
+  // indexer heartbeats the file at least once per batch and per finalize phase,
+  // so an old mtime proves no indexer is writing it: ignore the file and fall
+  // through to the health check. (Mirrors INDEXING_STATUS_STALE_SECS in
+  // src/indexer/pipeline/mod.rs, which drives server/CLI-side stale cleanup.)
+  const INDEXING_STALE_MS = 120000;
+  const fresh = (Date.now() - fs.statSync(progressFile).mtimeMs) < INDEXING_STALE_MS;
+  const p = fresh ? JSON.parse(fs.readFileSync(progressFile, 'utf8')) : null;
+  if (p && p.s === 'indexing' && p.t > 0) {
+    // floor, not round: skipped files (parse errors, oversized) keep d below t
+    // even in the terminal progress write, and rounding displayed that state as
+    // a confusing stuck "100%".
+    const pct = Math.floor((p.d / p.t) * 100);
     process.stdout.write(`code-graph: \u21BB indexing ${p.d}/${p.t} (${pct}%)`);
     process.exit(0);
   }
+  if (p && p.s === 'finalizing' && p.t > 0) {
+    // Post-batch full-graph phases (context strings, import bind/prune, ANALYZE):
+    // the file count no longer moves, so show an explicit phase label instead of
+    // a frozen-looking counter.
+    process.stdout.write(`code-graph: ↻ finalizing ${p.d}/${p.t}`);
+    process.exit(0);
+  }
 } catch { /* no progress file or parse error — continue to health check */ }
 
 // No indexing in progress — show normal health status
@@ -131,8 +149,14 @@ function statusUnavailable(errText) {
 let report = null;
 let errText = '';
 try {
+  // 1500ms, NOT 3000ms: the composite wrapper kills this whole provider at
+  // 3000ms (statusline-composite.js runProvider), so an inner budget equal to
+  // the outer one guaranteed the OUTER timeout fired first on a slow
+  // health-check (e.g. CPU saturated by the embedding backfill) and the segment
+  // silently vanished. Keeping the inner budget well under the outer one turns
+  // "slow health-check" into a rendered "offline"/"updating" instead of a blank.
   report = parseReport(execFileSync(bin, ['health-check', '--format', 'json'], {
-    timeout: 3000,
+    timeout: 1500,
     stdio: ['pipe', 'pipe', 'pipe'],
     // Run the binary FROM the resolved root so its own project-root resolution
     // lands on the same DB the gate above picked (a subdir cwd would otherwise