@sdsrs/code-graph 0.101.0 → 0.102.0

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

@@ -5,6 +5,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 const { readBinaryVersion } = require('./version-utils');
+const { npmSpawnOpts } = require('./npm-exec');
 
 const PLATFORM = os.platform();
 const ARCH = os.arch();
@@ -51,9 +52,17 @@ function unsupportedPlatformHint(platform = PLATFORM, arch = ARCH, libc = null)
   return null;
 }
 
-/** Read the npm pkg version from this script's package.json (claude-plugin/../package.json). */
+/**
+ * Version that arms the gates below. Two shipped layouts resolve differently:
+ * npm install has `<pkg>/package.json` two levels up; the marketplace/plugin-cache
+ * copy ships ONLY the claude-plugin subtree, so `../.claude-plugin/plugin.json`
+ * is the sole version source there. Without the fallback, every marketplace
+ * install ran with a null version and each gate degraded to
+ * first-candidate-wins (the pre-d578d99 relic-shadowing behavior).
+ */
 function getPackageVersion() {
-  try { return require('../../package.json').version; }
+  try { return require('../../package.json').version; } catch { /* not npm layout */ }
+  try { return require('../.claude-plugin/plugin.json').version; }
   catch { return null; }
 }
 
@@ -87,7 +96,19 @@ function globalNodeModulesCandidates() {
   const out = [];
   const nodeBinDir = path.dirname(process.execPath);
 
-  // 1. Derive from process.execPath. Works for nvm + standard Unix prefixes
+  // 1. NPM_CONFIG_PREFIX env override (users with `~/.npm-global` etc.) FIRST:
+  //    when set, `npm install -g` actually installs THERE, so it is the most
+  //    authoritative location — matching npm's own prefix-resolution order.
+  //    (It also used to rank below the execPath derivation, which let a stale
+  //    relic in the nvm prefix shadow the user's real prefix.)
+  const envPrefix = process.env.NPM_CONFIG_PREFIX || process.env.npm_config_prefix;
+  if (envPrefix) {
+    out.push(PLATFORM === 'win32'
+      ? path.join(envPrefix, 'node_modules')
+      : path.join(envPrefix, 'lib', 'node_modules'));
+  }
+
+  // 2. Derive from process.execPath. Works for nvm + standard Unix prefixes
   //    (`<prefix>/bin/node` → globals at `<prefix>/lib/node_modules`); on
   //    Windows globals sit next to `node.exe`.
   if (PLATFORM === 'win32') {
@@ -96,25 +117,17 @@ function globalNodeModulesCandidates() {
     out.push(path.resolve(nodeBinDir, '..', 'lib', 'node_modules'));
   }
 
-  // 2. NPM_CONFIG_PREFIX env override (set by users using `~/.npm-global` etc.)
-  const envPrefix = process.env.NPM_CONFIG_PREFIX || process.env.npm_config_prefix;
-  if (envPrefix) {
-    out.push(PLATFORM === 'win32'
-      ? path.join(envPrefix, 'node_modules')
-      : path.join(envPrefix, 'lib', 'node_modules'));
-  }
-
   // 3. Common no-sudo user prefix
   out.push(path.join(os.homedir(), '.npm-global', 'lib', 'node_modules'));
 
   // 4. Last resort: ask npm directly. Slow (~50-200ms) but most accurate when
   //    user has a non-standard prefix. Cached at the disk-cache layer above.
   try {
-    const root = execFileSync('npm', ['root', '-g'], {
+    const root = execFileSync('npm', ['root', '-g'], npmSpawnOpts({
       timeout: 2000,
       stdio: ['pipe', 'pipe', 'pipe'],
       encoding: 'utf8',
-    }).trim();
+    })).trim();
     if (root) out.push(root);
   } catch { /* npm not on PATH or timed out */ }
 
@@ -160,6 +173,10 @@ function isCachedBinaryFresh(cachedPath, pkgVersion) {
  *   auto-update cache → platform npm pkg → bundled (bin/) →
  *   cargo install → PATH → npx cache
  *
+ * Every tier after dev-mode is version-gated (createVersionGate): the first
+ * candidate at/above the pkg version wins; when NONE is current, the newest
+ * stale candidate is returned rather than null.
+ *
  * Returns the absolute path or null if not found.
  */
 function findBinary() {
@@ -200,21 +217,57 @@ function isDevRepo(rootDir) {
  * nvm/standard setups), so a working `npm install -g @sdsrs/code-graph` can
  * still be invisible without the fallback.
  */
-function findPlatformBinary() {
+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)) return bin;
+    if (isNativeBinary(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)) return bin;
+    if (isNativeBinary(bin)) out.push(bin);
   }
 
-  return null;
+  return out;
+}
+
+function findPlatformBinary() {
+  return platformBinaryCandidates()[0] || null;
+}
+
+/**
+ * Version gate for discovery candidates. `consider(bin)` accepts a candidate
+ * outright when it is current (version >= pkgVersion) or unverifiable (no pkg
+ * version / binary won't report one — don't refuse the only path we may have);
+ * a candidate OLDER than the package is recorded as a stale fallback instead of
+ * being returned, and `best()` yields the NEWEST of those.
+ *
+ * Why: candidates below the auto-update cache had no version check at all, so
+ * a years-old relic (a 0.16.6 `npm install -g` leftover in the nvm global
+ * node_modules) was returned VERBATIM during every post-release window in
+ * which the cache binary was one version behind — an ancient server on a
+ * modern schema, presenting as the MCP 30s connect-timeout. Newest-stale
+ * beats null because every consumer (statusline, hooks, CLI) degrades more
+ * gracefully on a slightly-old binary than on "offline", and the stale-binary
+ * self-heal in auto-update.js re-downloads shortly anyway.
+ */
+function createVersionGate(pkgVersion, { readVersion = readBinaryVersion } = {}) {
+  let bestStale = null;
+  return {
+    consider(bin) {
+      if (!isNativeBinary(bin)) return null;
+      if (!pkgVersion) return bin;
+      const ver = readVersion(bin);
+      if (!ver || compareVersions(ver, pkgVersion) >= 0) return bin;
+      if (!bestStale || compareVersions(ver, bestStale.ver) > 0) bestStale = { bin, ver };
+      return null;
+    },
+    best() { return bestStale ? bestStale.bin : null; },
+  };
 }
 
 function findBinaryUncached() {
@@ -240,24 +293,31 @@ function findBinaryUncached() {
     }
   }
 
+  // Every tier below runs through the version gate: a candidate at or above
+  // the npm pkg version is returned on the spot (tier order = priority, same
+  // as before); an OLDER candidate is only remembered as a fallback. Without
+  // the gate, tiers below the auto-update cache accepted any binary verbatim —
+  // so when the cache was one release behind (every post-release window), an
+  // ancient global-npm relic could shadow it (the 0.16.6-serves-a-modern-DB
+  // incident behind the MCP 30s connect-timeout).
+  const gate = createVersionGate(getPackageVersion());
+
   // --- Auto-update cache (binary downloaded directly from GitHub release) ---
   // Cache wins when its version >= the npm pkg version. After `npm update`
   // refreshes the platform-pkg, an older auto-update cache binary must NOT
   // shadow the freshly-installed one; this version check prevents the
   // upgrade-race where users keep running stale binary until auto-update fires.
   const autoUpdateBin = path.join(os.homedir(), '.cache', 'code-graph', 'bin', BINARY_NAME);
-  if (isNativeBinary(autoUpdateBin)) {
-    const cacheVer = readBinaryVersion(autoUpdateBin);
-    const pkgVer = getPackageVersion();
-    if (!pkgVer || !cacheVer || compareVersions(cacheVer, pkgVer) >= 0) {
-      return autoUpdateBin;
-    }
-    // Cache is older than npm pkg — fall through to platform-pkg.
+  {
+    const hit = gate.consider(autoUpdateBin);
+    if (hit) return hit;
   }
 
   // --- Platform-specific npm package (@sdsrs/code-graph-{os}-{arch}) ---
-  const platformBin = findPlatformBinary();
-  if (platformBin) return platformBin;
+  for (const platformBin of platformBinaryCandidates()) {
+    const hit = gate.consider(platformBin);
+    if (hit) return hit;
+  }
 
   // --- Bundled binary (in same directory as cli.js or plugin scripts) ---
   // Check bin/ directory of the npm package
@@ -267,20 +327,23 @@ function findBinaryUncached() {
   }
   binDirs.add(path.resolve(__dirname, '..', '..', 'bin'));
   for (const dir of binDirs) {
-    const bundled = path.join(dir, BINARY_NAME);
-    if (isNativeBinary(bundled)) return bundled;
+    const hit = gate.consider(path.join(dir, BINARY_NAME));
+    if (hit) return hit;
   }
 
   // --- Cargo install (~/.cargo/bin) ---
-  const cargoBin = path.join(os.homedir(), '.cargo', 'bin', BINARY_NAME);
-  if (isNativeBinary(cargoBin)) return cargoBin;
+  {
+    const hit = gate.consider(path.join(os.homedir(), '.cargo', 'bin', BINARY_NAME));
+    if (hit) return hit;
+  }
 
   // --- PATH lookup (last resort for intentionally installed binaries) ---
   try {
     const which = PLATFORM === 'win32' ? 'where' : 'which';
     const found = execFileSync(which, [BINARY_NAME], { stdio: ['pipe', 'pipe', 'pipe'] })
       .toString().trim().split('\n')[0];
-    if (isNativeBinary(found)) return found;
+    const hit = gate.consider(found);
+    if (hit) return hit;
   } catch { /* not in PATH */ }
 
   // --- npx cache (very last resort — may be outdated) ---
@@ -288,12 +351,15 @@ function findBinaryUncached() {
   try {
     for (const entry of fs.readdirSync(npxDir)) {
       const platDir = path.join(npxDir, entry, 'node_modules', '@sdsrs', `code-graph-${PLATFORM}-${ARCH}`);
-      const platBin = path.join(platDir, BINARY_NAME);
-      if (isNativeBinary(platBin)) return platBin;
+      const hit = gate.consider(path.join(platDir, BINARY_NAME));
+      if (hit) return hit;
     }
   } catch { /* no npx cache */ }
 
-  return null;
+  // Nothing current anywhere: the newest stale candidate (if any) beats null —
+  // consumers degrade better on a slightly-old binary than on "offline", and
+  // auto-update's stale-binary self-heal replaces it shortly.
+  return gate.best();
 }
 
 /**
@@ -306,7 +372,7 @@ function clearCache() {
 
 module.exports = {
   findBinary, findBinaryUncached, clearCache,
-  globalNodeModulesCandidates, findPlatformBinary,
+  globalNodeModulesCandidates, findPlatformBinary, createVersionGate,
   getPackageVersion, compareVersions, isCachedBinaryFresh,
   detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,

package/claude-plugin/scripts/install-lock.js

@@ -0,0 +1,48 @@
+'use strict';
+// Inter-process install lock. N concurrently-opened sessions each spawn a
+// launcher / auto-update process; without a lock they ran parallel
+// `npm install -g` against one global prefix (npm's staging dir is not
+// concurrency-safe → EEXIST/ENOTEMPTY tree corruption) and clobbered each
+// other's update-state counters. O_EXCL create is the atomic primitive; a lock
+// whose owner pid is dead or whose file is older than staleMs is reclaimed
+// (crashed installer must not wedge every future session).
+const fs = require('fs');
+const path = require('path');
+
+const STALE_MS = 10 * 60 * 1000; // > the longest install step (npm 180s heal timeout)
+
+function lockIsStale(lockPath, staleMs) {
+  try {
+    const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+    if (age > staleMs) return true;
+    const info = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    if (!info || !Number.isInteger(info.pid)) return false; // unreadable → trust age only
+    try { process.kill(info.pid, 0); return false; }        // owner alive
+    catch (e) { return e.code !== 'EPERM'; }                // EPERM = alive, not ours
+  } catch {
+    return false; // raced away / unreadable — treat as held; age check re-runs next attempt
+  }
+}
+
+/**
+ * Try to take the lock. Returns `{ release() }` on success, null when another
+ * live process holds it. Never throws, never blocks.
+ */
+function acquireLock(lockPath, { staleMs = STALE_MS } = {}) {
+  try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch { return null; }
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+      fs.closeSync(fd);
+      return { release: () => { try { fs.unlinkSync(lockPath); } catch { /* ok */ } } };
+    } catch (e) {
+      if (!e || e.code !== 'EEXIST') return null;
+      if (!lockIsStale(lockPath, staleMs)) return null;
+      try { fs.unlinkSync(lockPath); } catch { /* another reclaimer won — retry loop */ }
+    }
+  }
+  return null;
+}
+
+module.exports = { acquireLock, STALE_MS };

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

@@ -0,0 +1,146 @@
+'use strict';
+/**
+ * Background binary installer for mcp-launcher.js.
+ *
+ * Replaces the launcher's old SYNCHRONOUS missing-binary chain — `npm install
+ * -g` (60s timeout) then the GitHub-release fallback (90s) — which ran BEFORE
+ * any MCP JSON-RPC was answered. Claude Code's connect timeout is 30s, so a
+ * cold install always presented as "connection timed out after 30000ms" and
+ * the tools only appeared on a later reconnect. The launcher now answers the
+ * handshake from an upgradeable 0-tool stub immediately and runs this chain in
+ * the background; `onInstalled` fires as soon as a step yields a resolvable
+ * binary so the caller can hand the live connection over to it.
+ *
+ * Steps (same order + timeouts as the old sync chain):
+ *   1. npm install -g @sdsrs/code-graph@<version>   — the normal package path
+ *   2. auto-update.js --silent --install-missing    — direct GitHub release
+ *      download, for when npm succeeds but the platform optionalDependency
+ *      fails silently (OS-mismatch tolerance, flaky registry — issue #12)
+ *
+ * `spawnFn` is injectable so the chain is unit-testable without touching npm
+ * or the network (launcher-install.test.js).
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+const { NPM_NEEDS_SHELL } = require('./npm-exec');
+const { acquireLock } = require('./install-lock');
+
+const NPM_TIMEOUT_MS = 60000;
+const GITHUB_TIMEOUT_MS = 90000;
+
+/**
+ * Run one install step, capture its stderr, and invoke `cb` exactly once when
+ * the step is over — whether it exited, timed out (spawn's `timeout` option
+ * SIGTERMs and still emits 'exit'), or failed to start at all ('error' without
+ * 'exit', e.g. npm missing from PATH). Never throws: a failed step just means
+ * the chain moves on. `cb` receives the step's exit code (null when it never
+ * exited cleanly); `spawnOpts` merges extras into the spawn options (shell for
+ * npm on Windows, env for the auto-update child).
+ */
+function runStep(cmd, args, timeoutMs, prefix, spawnFn, cb, spawnOpts = {}) {
+  let settled = false;
+  let exitCode = null;
+  const done = () => {
+    if (settled) return;
+    settled = true;
+    cb(exitCode);
+  };
+
+  let child;
+  try {
+    child = spawnFn(cmd, args, {
+      timeout: timeoutMs,
+      stdio: ['ignore', 'ignore', 'pipe'],
+      ...spawnOpts,
+    });
+  } catch (e) {
+    process.stderr.write(`[code-graph] install step ${cmd} failed to start: ${e.message}\n`);
+    done();
+    return;
+  }
+
+  let stderr = '';
+  if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString(); });
+  child.on('error', (err) => {
+    process.stderr.write(`[code-graph] install step ${cmd} failed to start: ${err.message}\n`);
+    done();
+  });
+  child.on('exit', (code) => {
+    exitCode = code;
+    if (stderr.trim()) {
+      process.stderr.write(stderr.trim().split('\n').map((l) => `${prefix} ${l}\n`).join(''));
+    }
+    done();
+  });
+}
+
+/**
+ * Kick off the background install chain. Fire-and-forget: exactly one of
+ * `onInstalled` / `onFailed` is eventually called — EXCEPT when `lockPath` is
+ * given and another live session already holds the lock, in which case the
+ * chain is skipped entirely (neither callback fires; that session's install
+ * lands and our stub's poller picks the binary up).
+ *
+ * - findBinary / clearCache: injected from find-binary.js (clear the disk
+ *   cache before each re-resolve so a pre-install negative result can't mask a
+ *   freshly landed binary).
+ * - onInstalled: a step produced a resolvable binary — attempt the stub→real
+ *   handover now instead of waiting for the stub's next 4s poll.
+ * - onFailed: both steps ran and no binary resolved — surface manual hints.
+ * - recordGlobalInstall: called when the npm step itself exited 0 AND yielded a
+ *   binary — i.e. the plugin (not the user) introduced the global packages.
+ *   lifecycle.js uninstall uses that marker to know it owns their removal.
+ * - lockPath: opt-in inter-process lock — N cold sessions otherwise run
+ *   parallel `npm install -g` against one global prefix (npm staging is not
+ *   concurrency-safe).
+ */
+function installBinaryInBackground({
+  version,
+  findBinary,
+  clearCache,
+  onInstalled,
+  onFailed,
+  spawnFn = spawn,
+  autoUpdateScript = path.join(__dirname, 'auto-update.js'),
+  npmTimeoutMs = NPM_TIMEOUT_MS,
+  githubTimeoutMs = GITHUB_TIMEOUT_MS,
+  recordGlobalInstall = null,
+  lockPath = null,
+}) {
+  let lock = null;
+  if (lockPath) {
+    lock = acquireLock(lockPath);
+    if (!lock) {
+      process.stderr.write('[code-graph] another session is already installing the binary; this stub will pick it up when it lands\n');
+      return;
+    }
+  }
+  const finish = (fn) => {
+    if (lock) { lock.release(); lock = null; }
+    fn();
+  };
+  const resolved = () => {
+    clearCache();
+    return findBinary();
+  };
+
+  runStep('npm', ['install', '-g', `@sdsrs/code-graph@${version}`], npmTimeoutMs, '[code-graph][npm]', spawnFn, (npmExit) => {
+    if (resolved()) {
+      if (npmExit === 0 && recordGlobalInstall) {
+        try { recordGlobalInstall(); } catch { /* marker is best-effort */ }
+      }
+      finish(onInstalled);
+      return;
+    }
+    process.stderr.write('[code-graph] npm install did not yield a binary; falling back to GitHub release download...\n');
+    runStep(process.execPath, [autoUpdateScript, '--silent', '--install-missing'], githubTimeoutMs, '[code-graph][auto-update]', spawnFn, () => {
+      if (resolved()) { finish(onInstalled); return; }
+      finish(onFailed);
+    }, {
+      // The child would otherwise try to take the same install lock we hold.
+      env: { ...process.env, CODE_GRAPH_INSTALL_LOCK_HELD: '1' },
+    });
+  }, NPM_NEEDS_SHELL ? { shell: true } : {});
+}
+
+module.exports = { installBinaryInBackground, runStep, NPM_TIMEOUT_MS, GITHUB_TIMEOUT_MS };

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
@@ -218,13 +225,25 @@ function cleanupDisabledStatusline() {
     return { cleaned: false, settingsChanged: false };
   }
 
+  // Decide BEFORE mutating: isPluginUninstalled reads the same composite/
+  // registry markers detachStatuslineIntegration is about to remove.
+  const uninstalled = isPluginUninstalled(settings);
+
   let settingsChanged = detachStatuslineIntegration(settings);
   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 ---
@@ -648,7 +667,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, runNpm = defaultRunNpm, scanGlobalPkgs = installedGlobalPkgs } = {}) {
   const settings = readJson(settingsPath());
   let settingsChanged = false;
 
@@ -692,6 +734,23 @@ 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 */ }
+  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 +765,7 @@ function uninstall() {
     try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ok */ }
   }
 
-  return { settingsChanged };
+  return { settingsChanged, pluginInstalledGlobals, globalPkgsRemoved, globalPkgsRemaining, adoptedProjects };
 }
 
 // --- Update (refresh config points) ---
@@ -952,6 +1011,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,
 };
@@ -963,10 +1023,24 @@ if (require.main === module) {
     const r = install();
     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') });
     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.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('    In each: run `code-graph-mcp unadopt` and `rm -rf .code-graph` to clean up.');
+    }
+    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}`);