@sdsrs/code-graph 0.147.0 → 0.149.0

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

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

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

@@ -53,7 +53,10 @@ function commandExists(cmd, { exec = execFileSync, timeoutMs = PATH_PROBE_TIMEOU
 
 // ── Configuration ──────────────────────────────────────────
 const GITHUB_REPO = 'sdsrss/code-graph-mcp';
-const { UPDATE_STATE_FILE: STATE_FILE, MANIFEST_FILE, INSTALL_LOCK_FILE } = require('./cache-paths');
+const {
+  UPDATE_STATE_FILE: STATE_FILE, MANIFEST_FILE, INSTALL_LOCK_FILE,
+  uninstallTombstoneActive,
+} = require('./cache-paths');
 const BINARY_CACHE_DIR = path.join(CACHE_DIR, 'bin');
 const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;        // 6h — steady-state re-check
 const UP_TO_DATE_RECHECK_MS = 30 * 60 * 1000;        // 30min — re-verify an "up to date" result (release-race guard)
@@ -166,14 +169,37 @@ function readState() {
 // The unlink/cleanup `catch {}`s elsewhere in this file stay silent on purpose:
 // a failed cleanup costs a stale temp file, not a broken invariant.
 let stateWriteWarned = false;
-function saveState(state) {
+function saveState(state, { tombstoneActive = uninstallTombstoneActive, write = writeJsonAtomic } = {}) {
+  // A teardown deleted CACHE_DIR; writeJsonAtomic would re-create it to hold
+  // this file. Measured: in the arm where the teardown lands after curl has
+  // written its tmp, `update-state.json` was the ONE thing that came back, and
+  // it came back through here — noteUpdateFailure records the ENOENT the
+  // teardown caused, and the recording re-creates the directory. Guarding only
+  // the two download sites leaves this path open, so the arm keeps failing.
+  //
+  // The check sits inside saveState rather than at its eight call sites: one
+  // gate cannot drift out of step with seven others.
+  //
+  // It costs more than the file, and the cost is worth stating: this is also
+  // where the updater's anti-hammer memory lives. `fetchLatestRelease` records
+  // a GitHub 403 as `saveState({ ...state, rateLimited: true })` and
+  // `shouldCheck` reads it back to hold off; `lastCheck` drives the 6h/30min
+  // throttles the same way. While a tombstone stands, neither persists —
+  // measured, a rate-limited updater comes back with `rateLimited: null`,
+  // `lastCheck` unset and `shouldCheck` true, so it re-hits api.github.com on
+  // every invocation instead of backing off. Bounded by the TTL to five
+  // minutes, on a machine whose plugin was just torn down. No call site NEEDS
+  // the write — the state file lives inside the directory being reclaimed, so
+  // persisting it would mean re-creating exactly what this guard exists to
+  // prevent — but a reader should not have to discover the throttle loss.
+  if (tombstoneActive()) return;
   try {
     // The marker is an in-memory signal, never a persisted field: several call
     // sites do `saveState({ ...readState(), ... })`, and a persisted
     // `stateUnreadable` would park the updater permanently.
     const { stateUnreadable, ...clean } = state || {};
     void stateUnreadable;
-    writeJsonAtomic(STATE_FILE, clean);
+    write(STATE_FILE, clean);
   } catch (e) {
     if (!stateWriteWarned) {
       stateWriteWarned = true;
@@ -583,7 +609,11 @@ function cachedBinaryStaleVsState(state, { binaryPath = cachedBinaryPath(), read
  * `needsUpdate` is injectable for tests only; production always uses the real
  * predicate. Returning false on a skip is accurate: nothing was updated.
  */
-async function downloadBinary(latest, { needsUpdate = cachedBinaryNeedsUpdate } = {}) {
+async function downloadBinary(latest, {
+  needsUpdate = cachedBinaryNeedsUpdate,
+  tombstoneActive = uninstallTombstoneActive,
+  mkdir = fs.mkdirSync,
+} = {}) {
   if (!latest || !latest.binaryUrl) return false;
   if (!needsUpdate(latest)) return false; // already at latest.version — no fetch
   if (!commandExists('curl')) {
@@ -595,8 +625,15 @@ async function downloadBinary(latest, { needsUpdate = cachedBinaryNeedsUpdate }
   const binaryDst = cachedBinaryPath();
   const binaryTmp = binaryDst + '.tmp.' + process.pid;
 
+  // The 41 MB arm. A teardown that lands before this mkdir gets the whole
+  // chain proceeding on a re-created tree, and it finishes by writing a fresh
+  // 42 MB binary into a directory the user just reclaimed. Checked here rather
+  // than at the top of the function so the guard sits adjacent to the write it
+  // protects.
+  if (tombstoneActive()) return false;
+
   try {
-    fs.mkdirSync(BINARY_CACHE_DIR, { recursive: true });
+    mkdir(BINARY_CACHE_DIR, { recursive: true });
     // `-f` (fail on HTTP >= 400), same as the sidecar fetch below. Without it
     // curl writes GitHub's 404/503 HTML body to binaryTmp and exits 0, so the
     // error page travelled on as a candidate binary and was only caught two
@@ -655,7 +692,8 @@ function sha256File(filePath) {
   return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
 }
 
-function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSha256) {
+function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSha256,
+  { tombstoneActive = uninstallTombstoneActive } = {}) {
   try {
     // Size floor: every published binary is tens of MB, so anything under 1 MB
     // is a truncated transfer or an error page. It used to return false without
@@ -714,6 +752,13 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSh
       return false;
     }
 
+    // The other arm: the teardown landed after curl wrote the tmp, so the
+    // download is verified and ready and the destination directory is gone.
+    // Refusing HERE rather than earlier is deliberate — the `finally` below
+    // owns binaryTmp and unlinks it, so bailing at the last step costs one
+    // wasted download and leaves nothing on disk.
+    if (tombstoneActive()) return false;
+
     fs.renameSync(binaryTmp, binaryDst);
     clearBinaryCache();
     return true;
@@ -1529,6 +1574,7 @@ module.exports = {
   shouldHealGlobalsOnThrottle, inactiveNodeGlobalRelics,
   downloadAndInstall, refreshMarketplaceClone, marketplaceCloneDir,
   noteUpdateFailure, takeUpdateFailure,
+  saveState,
 };
 
 // CLI: node auto-update.js [check|status] [--silent] [--install-missing]

package/claude-plugin/scripts/cache-paths.js

@@ -19,6 +19,7 @@
 // file — it already does `require('./lifecycle')`, so its copy of the three path
 // segments bought nothing. An earlier version of this comment claimed both
 // modules needed the split (pre-ship review 2026-09-07).
+const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
@@ -31,9 +32,97 @@ const MANIFEST_FILE = path.join(CACHE_DIR, 'install-manifest.json');
 /** Inter-process install lock (see install-lock.js). */
 const INSTALL_LOCK_FILE = path.join(CACHE_DIR, 'install.lock');
 
+/**
+ * Teardown tombstone — a SIBLING of CACHE_DIR, deliberately not a file inside
+ * it.
+ *
+ * A teardown that runs while a SessionStart-spawned `auto-update` is in flight
+ * used to get CACHE_DIR re-created under it: measured at 42,847,128 B of fresh
+ * binary plus three JSON files, 2 of 2 runs, in the arm where the teardown
+ * beats the download.
+ *
+ * INSTALL_LOCK_FILE above is the token the updater already respects, and taking
+ * it here was prototyped for exactly this job and REFUTED: it lives at
+ * CACHE_DIR/install.lock, `removeCacheResidue()` deletes CACHE_DIR, so the lock
+ * goes with the directory and the updater acquires freely seconds later. A
+ * mutual-exclusion token stored inside the resource being destroyed cannot
+ * guard that destruction — which is why this one is a sibling.
+ */
+const UNINSTALL_TOMBSTONE_FILE = path.join(os.homedir(), '.cache', 'code-graph.uninstalled');
+
+/**
+ * How long a tombstone suppresses writes. Longer than any teardown, shorter
+ * than any interval over which a stale one could matter: a reinstall inside the
+ * window merely skips one update check, and the install itself supplies the
+ * binary. The TTL is what keeps this from becoming a permanent kill switch —
+ * a tombstone that never expired would disable auto-update for the life of the
+ * machine, a worse failure than the residue it prevents.
+ */
+const UNINSTALL_TOMBSTONE_TTL_MS = 5 * 60 * 1000;
+
+/** Record that a teardown is in flight. Best-effort: a cache we cannot write
+ *  to is one the updater's own writes will fail against too. */
+function writeUninstallTombstone({ file = UNINSTALL_TOMBSTONE_FILE, now = Date.now() } = {}) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ at: new Date(now).toISOString() }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is a teardown in flight right now?
+ *
+ * Fail-OPEN on every unreadable shape — absent, unparseable, no timestamp. The
+ * alternative is a corrupt file that can never expire, and the spec rates a
+ * permanently suppressed updater worse than the 41 MB this exists to stop.
+ */
+function uninstallTombstoneActive({
+  file = UNINSTALL_TOMBSTONE_FILE,
+  now = Date.now(),
+  ttlMs = UNINSTALL_TOMBSTONE_TTL_MS,
+} = {}) {
+  let at;
+  try {
+    at = Date.parse(JSON.parse(fs.readFileSync(file, 'utf8')).at);
+  } catch {
+    return false;
+  }
+  if (!Number.isFinite(at)) return false;
+  // `age >= 0` is not redundant with the upper bound: a NEGATIVE age — a
+  // timestamp in the future — is always less than the TTL, so a bare
+  // `age < ttlMs` would treat a tombstone stamped a year ahead as active for a
+  // year, and a legitimate one plus an 8h clock rollback (NTP correction, VM
+  // restore, RTC drift) as active for 8h05m. That is the never-expiring
+  // kill switch this design's TTL exists to prevent, in bounded form, and it is
+  // reachable without any corruption because the file carries OUR OWN
+  // Date.now(). A future stamp means the clock moved, not that a teardown is in
+  // flight, so it fails open like every other shape we cannot trust.
+  const age = now - at;
+  return age >= 0 && age < ttlMs;
+}
+
+/** Drop the tombstone. The TTL is the backstop; an install clears it eagerly so
+ *  a reinstall inside the window does not skip its first update check. */
+function clearUninstallTombstone({ file = UNINSTALL_TOMBSTONE_FILE } = {}) {
+  try {
+    fs.rmSync(file, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 module.exports = {
   CACHE_DIR,
   UPDATE_STATE_FILE,
   MANIFEST_FILE,
   INSTALL_LOCK_FILE,
+  UNINSTALL_TOMBSTONE_FILE,
+  UNINSTALL_TOMBSTONE_TTL_MS,
+  writeUninstallTombstone,
+  uninstallTombstoneActive,
+  clearUninstallTombstone,
 };

package/claude-plugin/scripts/cli-entry.js

@@ -102,20 +102,40 @@ function main({ argv = process.argv, findBinaryRoot = null } = {}) {
         "deletes ~/.cache/code-graph, and removes this project's CLAUDE.md adoption\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");
+        "@sdsrs npm packages even without the plugin-install marker.\n\n" +
+        "This also removes Claude Code's own registration, so `claude plugin uninstall\n" +
+        "code-graph-mcp` afterwards answers \"not found\" — expected. Only a Claude Code\n" +
+        "session still listing the plugin needs `/plugin uninstall code-graph-mcp`.\n");
       process.exit(0);
     }
     rejectUnknownFlags(argv, "uninstall", new Set(["--help", "-h", "--unadopt-all", "--purge-global"]));
     const lifecycle = require("./lifecycle");
     const { unadopt } = require("./adopt");
+    // Unadopt THIS project BEFORE the teardown, not after.
+    //
+    // `lifecycle.removeCacheResidue` (step 6) holds two rules: PRESERVE a
+    // non-empty adopted-projects registry — those projects still carry a managed
+    // block someone has to be able to find (JS-17) — and never re-create
+    // CACHE_DIR merely to hold `[]`, which its own comment calls "just new
+    // residue". Unadopting afterwards produced exactly that `[]`, one step too
+    // late for anything to sweep it, so the file step 6 had carefully preserved
+    // for us became the residue step 6 exists to prevent. Unadopt first and the
+    // registry is already empty when step 6 reads it, so the whole cache
+    // directory goes. It is also why that comment describes "the normal
+    // SessionStart teardown order, which unadopts first" — this was the one
+    // caller that did not.
+    //
+    // Deliberate knock-on: `r.adoptedProjects` (captured at step 5.5) and the
+    // `--unadopt-all` sweep no longer see this project, so it is reported once,
+    // on the `this project unadopted=` line, instead of being counted twice.
+    // `otherAdopted` below already filtered `process.cwd()` out either way.
+    let ua = { ok: false };
+    try { ua = unadopt(); } catch { /* best-effort — the teardown below still runs */ }
+    const projectUnadopted = !!(ua && (ua.blockPruned || ua.fileRemoved || ua.claudeMdRemoved));
     const r = lifecycle.uninstall({
       purgeGlobal: argv.slice(3).includes("--purge-global"),
       unadoptAll: 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));
     let out =
       `Uninstalled code-graph-mcp | settings cleaned=${r.settingsChanged}` +
       ` | this project unadopted=${projectUnadopted}\n`;
@@ -137,7 +157,14 @@ function main({ argv = process.argv, findBinaryRoot = null } = {}) {
         " `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";
+    // Only when the registration actually went. `uninstall` reports the arm
+    // where it could not (unreadable / unwritable installed_plugins.json) via
+    // `installedPluginsUnusable`, and in that arm it has ALREADY printed the
+    // opposite instruction to stderr — so printing this too told the user both
+    // to run `/plugin uninstall` and that its failure was expected, in one run.
+    if (!r.installedPluginsUnusable) {
+      for (const line of lifecycle.POST_TEARDOWN_UI_NOTE) out += `  ${line}\n`;
+    }
     process.stdout.write(out);
     process.exit(0);
   }

package/claude-plugin/scripts/doctor.js

@@ -1134,7 +1134,7 @@ function runRepairs(results, {
         console.log('\n  Repairing hooks...');
         if (relicRepairGuard()) break;
         const { install, scanForBrokenPaths } = require('./lifecycle');
-        const installResult = install();
+        const installResult = install({ clearTombstone: true });
         // Diagnosis already ran install()+re-scan and the paths were STILL
         // broken (that `repaired:false` is what raised hooks-invalid). Verify
         // this second attempt actually cleared them before counting it fixed \u2014
@@ -1173,7 +1173,7 @@ function runRepairs(results, {
         console.log('\n  Registering code-graph hooks in settings.json...');
         if (relicRepairGuard()) break;
         const { install } = require('./lifecycle');
-        const r = install();
+        const r = install({ clearTombstone: true });
         if (r.hooksRegistered) {
           console.log('  \u2705 settings.json updated — restart Claude Code to apply');
           fixed++;

package/claude-plugin/scripts/lifecycle.js

@@ -20,7 +20,10 @@ const MARKETPLACE_NAME = 'code-graph-mcp';
 // the first version of this comment claimed `MANIFEST_FILE` was exported from
 // here: `CACHE_DIR` and `INSTALL_LOCK_FILE` are exported and still are;
 // `MANIFEST_FILE` is module-private and always was, so nothing importable moved.
-const { CACHE_DIR, MANIFEST_FILE, INSTALL_LOCK_FILE } = require('./cache-paths');
+const {
+  CACHE_DIR, MANIFEST_FILE, INSTALL_LOCK_FILE,
+  writeUninstallTombstone, clearUninstallTombstone,
+} = require('./cache-paths');
 // Bound for the `ps` fallback in getActiveCmdlines (pre-ship review 2026-09-06).
 // 2 s matches the other hook-path probes; the floor is what a budget-exhausted
 // hook still gives it, since an empty list degrades to recency-only.
@@ -1321,7 +1324,27 @@ function verifyHooksFire({ hooks, env, timeoutMs = 4000, tmpBase } = {}) {
 
 // --- Install (idempotent) ---
 
-function install({ reclaimStatusline = false } = {}) {
+function install({ reclaimStatusline = false, clearTombstone = false } = {}) {
+  // Clearing the teardown tombstone is OPT-IN, and defaults to off, because
+  // "an install is happening" does not mean "the user asked to reinstall".
+  //
+  // The first version cleared unconditionally, on the reasoning that an install
+  // ends any teardown. Pre-ship review reproduced the hole: after a genuine
+  // uninstall, a DIFFERENT still-live session's SessionStart finds no manifest
+  // (install-manifest.json went with CACHE_DIR) and no inactive-plugin markers
+  // (the composite and the statusline registry went with it too), so it falls
+  // through to `installReporting()` -> install() and cleared the tombstone 3 s
+  // after it was written — then spawned its own updater fourteen lines later.
+  // A global record that any concurrent session may erase protects nobody.
+  //
+  // So only the two genuinely user-initiated entry points pass true: the
+  // `lifecycle.js install` CLI and doctor's repair pass. Everything automatic —
+  // session-init's install reporting, healthCheck's repair — leaves it standing
+  // and lets the TTL expire it. The cost is that a reinstall inside the window
+  // may skip one update check, which the spec already accepts; the install
+  // itself supplies the binary.
+  if (clearTombstone) clearUninstallTombstone();
+
   const version = getPluginVersion();
   const manifest = readManifest();
   // Probe FIRST, and pay the backup only on the write path (audit 2026-08-29
@@ -1989,7 +2012,68 @@ function isPluginUninstalled(settings = readJson(settingsPath()) || {}) {
 // here now. So the preservation belongs here, at the wipe, rather than at each
 // caller — the same "fix it at the shared layer, not per surface" the
 // <external> query filter needed.
-function removeCacheResidue() {
+/**
+ * What to say about Claude Code's own plugin registry after a teardown that
+ * SUCCEEDED.
+ *
+ * `uninstall` step 3 drops the plugin from `enabledPlugins` and step 5 from
+ * `installed_plugins.json`, so by the time this prints there is nothing left for
+ * `claude plugin uninstall` to find: in a fresh terminal it exits non-zero with
+ * `Plugin "code-graph-mcp" not found in installed plugins`. Both printers used to
+ * say "also run `/plugin uninstall …`" with no such warning, which hands the user
+ * an error message as the last word on an uninstall that worked.
+ *
+ * Deliberately NOT the same text as the two notes in `uninstall` itself
+ * (`cannot write installed_plugins.json` / `cannot read …`): those fire exactly
+ * when the registration could NOT be removed, so there `/plugin uninstall` is
+ * both necessary and successful. That distinction is ENFORCED, not just
+ * described — both printers gate on `installedPluginsUnusable`. It was only
+ * described for one commit, and in that commit a corrupt installed_plugins.json
+ * got both messages at once (pre-ship review of 7dc7eb4). One string because these two
+ * printers are the pair that drifted before (v0.142.0 shipped a fix for two
+ * printers of the same `unadopt` string, and the release before it fixed the
+ * first of them).
+ */
+const POST_TEARDOWN_UI_NOTE = [
+  'Claude Code UI: the registration is already gone, so `claude plugin uninstall',
+  'code-graph-mcp` in a new terminal answers "not found" — that is the expected',
+  'result here, not a failure. In a session that still lists the plugin, run',
+  '`/plugin uninstall code-graph-mcp` there to sync its UI.',
+];
+
+function removeCacheResidue({ sweep = null } = {}) {
+  // Announce the teardown BEFORE the delete, outside the directory being
+  // deleted. A mid-flight `auto-update` in ANOTHER process will otherwise
+  // re-create CACHE_DIR under us — measured at 42,847,128 B of fresh binary
+  // plus three JSON files, 2 of 2 runs, when the teardown wins the race to
+  // `downloadBinary`'s mkdir.
+  //
+  // The racing updater is always a different process. An earlier version of
+  // this comment said `runSessionInit`'s teardown "runs from the same
+  // SessionStart that spawns the updater"; it does not — that branch returns at
+  // session-init.js:718 with `autoUpdateLaunched: false`, before
+  // `launchBackgroundAutoUpdate`. SessionStart is still the racing surface,
+  // just from a concurrent session rather than this one (pre-ship review).
+  //
+  // All three callers are genuine-uninstall paths — `uninstall()`,
+  // `cleanupDisabledStatusline()` under `isPluginUninstalled`, and
+  // `runSessionInit()` under `if (uninstalled)` — so the tombstone belongs here
+  // rather than in each of them: one site, three callers, and no way for a
+  // fourth to forget it. Verified against five sandbox states (explicit
+  // disable, genuine uninstall, healthy, unreadable registry, missing
+  // registry): only the genuine uninstall writes one.
+  //
+  // BEFORE, not after: written after the sweep there is a window in which an
+  // updater sees nothing and can mkdir mid-delete, and the sweep's own
+  // `catch { return false; }` would skip the write entirely on a failed delete.
+  // `sweep` exists so a test can observe the tombstone at the moment the delete
+  // is attempted — the ordering is the property, and asserting only that the
+  // file exists on return passes with the two lines swapped.
+  //
+  // Best-effort by design: if this write fails, the delete below still runs and
+  // we are no worse off than before the tombstone existed.
+  writeUninstallTombstone();
+
   // Path comes from adopt.js rather than a second spelling of the basename —
   // a literal here would silently stop matching the day adopt.js renames it,
   // and the failure mode is exactly the data loss this guard exists to stop.
@@ -2017,7 +2101,8 @@ function removeCacheResidue() {
     }
   } catch { /* POSIX-only helper or an unreadable path — nothing to preserve */ }
   try {
-    fs.rmSync(CACHE_DIR, { recursive: true, force: true });
+    if (sweep) sweep(CACHE_DIR);
+    else fs.rmSync(CACHE_DIR, { recursive: true, force: true });
   } catch { return false; }
   if (registryPath && registry) {
     try {
@@ -2051,6 +2136,7 @@ module.exports = {
   PLUGIN_ROOT,                                                         // v0.32.1 — for tests / consumers
   registerStatuslineProvider, unregisterStatuslineProvider, detachStatuslineIntegration,
   installedGlobalPkgs, GLOBAL_INSTALL_MARKER, INSTALL_LOCK_FILE, SHELL_PKG,   // uninstall residue
+  POST_TEARDOWN_UI_NOTE,                                                       // one wording, two printers
   PLUGIN_ID, OLD_PLUGIN_IDS, MARKETPLACE_NAME, CACHE_DIR, REGISTRY_FILE,
   settingsPath, installedPluginsPath, providersBackupFile, pluginsCacheDir,
 };
@@ -2059,8 +2145,11 @@ module.exports = {
 if (require.main === module) {
   const cmd = process.argv[2];
   if (cmd === 'install') {
-    // Explicit CLI install = user intent: reset any statusline stand-down and re-claim.
-    const r = install({ reclaimStatusline: true });
+    // Explicit CLI install = user intent: reset any statusline stand-down and
+    // re-claim, and drop a teardown tombstone if one is standing. This and
+    // doctor's repair pass are the only two callers that pass clearTombstone —
+    // see the comment on install() for why an automatic install must not.
+    const r = install({ reclaimStatusline: true, clearTombstone: true });
     // Refusing to touch an unusable settings.json means NOTHING was installed —
     // no hooks, no statusline, no manifest stamp. Printing "Installed" and
     // exiting 0 there would make `lifecycle.js install && …` chains read the
@@ -2100,7 +2189,12 @@ if (require.main === module) {
       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.');
+    // Suppressed in the arm where the registration could NOT be removed — the
+    // stderr note printed there says the opposite, and both at once is a
+    // contradiction. See the constant's own docstring.
+    if (!r.installedPluginsUnusable) {
+      for (const line of POST_TEARDOWN_UI_NOTE) console.log(`  ${line}`);
+    }
   } else if (cmd === 'update') {
     const r = update();
     if (r.settingsUnreadable || r.settingsUnwritable) {

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

@@ -151,6 +151,11 @@ if (!binary) {
 
   const stub = serveEmptyMcpStub({
     upgrade: {
+      // What a tool call gets told while this gate holds. Without it the stub
+      // answered with the OTHER gate's reason ("upgrades when cwd becomes a
+      // project"), which is both wrong here and unactionable — the cwd is fine,
+      // the binary is what is missing.
+      hint: `binary not installed yet — installing @sdsrs/code-graph@${version} in the background; if tools never appear, run \`code-graph-mcp doctor\``,
       // 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.
@@ -205,13 +210,18 @@ try {
   process.exit(1);
 }
 
-// Spawn binary with stdio inheritance for MCP JSON-RPC
-const child = spawn(binary, ['serve'], hidden({
-  stdio: 'inherit',
-  env: process.env,
-}));
-
-child.on('error', (err) => {
+// Both ways a spawn failure can reach us, reported through one function so
+// neither path can drift into being the one with the good message.
+//
+// node hands exactly FIVE errnos to the async 'error' event — EACCES, EAGAIN,
+// EMFILE, ENFILE, ENOENT ("Run-time errors should emit an error, not throw an
+// exception", internal/child_process.js) — and throws every other one
+// synchronously out of `spawn`. So the EACCES branch below always did reach its
+// handler; what had no path at all was the synchronous side, where an ETXTBSY
+// from a binary an auto-update replaced moments ago printed a raw stack instead
+// of any of this. Unlike the stub's, this process exits 1 either way: here the
+// catch buys the message, not the process.
+function reportSpawnFailure(err) {
   process.stderr.write(`[code-graph] Failed to start: ${err.message}\n`);
   if (process.platform === 'darwin' && (err.code === 'EACCES' || err.code === 'EPERM')) {
     process.stderr.write(
@@ -219,12 +229,34 @@ child.on('error', (err) => {
       `  xattr -d com.apple.quarantine "${binary}"\n`
     );
   }
+  // ETXTBSY: something still holds a writer fd on the binary — an auto-update
+  // that replaced it moments ago. Retryable, unlike the rest of this function.
+  if (err.code === 'ETXTBSY') {
+    process.stderr.write(
+      'The binary was still being written when we tried to run it.\n' +
+      '  Retry: restart Claude Code, or run `code-graph-mcp doctor`\n'
+    );
+  }
   // A glibc binary installed on musl (older npm ignores the `libc` field) is present
   // but execs into a loader error — surface the actionable platform hint.
   const platformHint = unsupportedPlatformHint();
   if (platformHint) process.stderr.write(platformHint + '\n');
   process.exit(1);
-});
+}
+
+// Spawn binary with stdio inheritance for MCP JSON-RPC
+let child;
+try {
+  child = spawn(binary, ['serve'], hidden({
+    stdio: 'inherit',
+    env: process.env,
+  }));
+} catch (err) {
+  reportSpawnFailure(err);   // exits; the return keeps `child` from being read as undefined
+  return;
+}
+
+child.on('error', reportSpawnFailure);
 
 child.on('exit', (code, signal) => {
   if (signal) {

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

@@ -84,10 +84,15 @@ function serveEmptyMcpStub(opts = {}) {
     else if (m === 'tools/list') result = { tools: [] };
     else if (m === 'resources/list') result = { resources: [] };
     else if (m === 'prompts/list') result = { prompts: [] };
+    // The reason a caller is talking to a 0-tool stub differs per gate, and this
+    // string is the ONLY place it reaches the model — the launcher's stderr goes
+    // to the Claude Code log, not into the tool result. One shared wording named
+    // the non-project cause for both gates, so the missing-binary gate told a
+    // caller sitting in a perfectly good git repo to make it a project.
     else error = {
       code: -32601,
       message: canUpgrade
-        ? 'method not found (plugin MCP stub; upgrades when cwd becomes a project)'
+        ? `method not found (plugin MCP stub; ${upgrade.hint || 'upgrades when cwd becomes a project'})`
         : 'method not found (plugin MCP is in dedup stub mode)',
     };
     writeCc(error ? { jsonrpc: '2.0', id: req.id, error } : { jsonrpc: '2.0', id: req.id, result });
@@ -149,7 +154,38 @@ function serveEmptyMcpStub(opts = {}) {
       }
       return;
     }
-    const spawned = upgrade.spawnReal();
+    // `spawnReal` may THROW rather than return null. node hands exactly FIVE
+    // errnos to the async 'error' event that `beginProxy` listens on — EACCES,
+    // EAGAIN, EMFILE, ENFILE, ENOENT ("Run-time errors should emit an error, not
+    // throw an exception", internal/child_process.js) — and throws every other
+    // one synchronously out of child_process.spawn. ETXTBSY is outside that set,
+    // and it is the one this path invites: the missing-binary gate nudges
+    // attemptUpgrade() from the install chain's onInstalled, so it execs a ~40MB
+    // binary at the instant the installer finished writing it, and Linux answers
+    // ETXTBSY for as long as any writer fd is still open. Uncaught, the throw
+    // escaped this function, escaped the poll-timer callback that called it, and
+    // killed the whole MCP server — at the moment the install had SUCCEEDED
+    // (QA 2026-09-13: 3/3 against a cold npm cache, 0/3 warm).
+    let spawned;
+    try {
+      spawned = upgrade.spawnReal();
+    } catch (err) {
+      const code = (err && err.code) || 'unknown';
+      process.stderr.write(`[code-graph] plugin MCP upgrade spawn failed (${code}); staying in 0-tool stub, will retry\n`);
+      // Clear the offline backoff. It models "the binary is not there yet", and
+      // `shouldUpgrade()` just returned TRUE — the binary IS there, this is a
+      // transient exec failure. Without this the throw returns into whatever
+      // `backoffTicks` a whole offline stretch ratcheted up (capped at 14 ticks
+      // = 56 s), and `pollTick` burns that down one tick at a time before it
+      // will even probe again: measured 4 s / 16 s / 36 s / 52 s of 0-tool stub
+      // after a 10 s / 30 s / 45 s / 90 s install (pre-ship review of 7dc7eb4).
+      // The retry is what makes containment a fix rather than a downgrade, so it
+      // has to be the next tick.
+      backoffTicks = 0;
+      backoffNext = 1;
+      noteUpgradeFailure(`spawn-threw-${code}`);
+      return;
+    }
     if (!spawned) { noteUpgradeFailure('binary-unresolved'); return; }
     if (poller) { clearIv(poller); poller = null; }
     child = spawned;

package/claude-plugin/templates/code-graph-snapshot.yml

@@ -35,7 +35,7 @@ jobs:
           node-version: '20'
       - name: Build snapshot
         run: |
-          npx -y -p @sdsrs/code-graph@0.147.0 code-graph-mcp snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.149.0 code-graph-mcp snapshot create --out snapshot.db
           zstd -9 snapshot.db -o snapshot.db.zst
           mv snapshot.db.zst "code-graph-snapshot-${GITHUB_SHA:0:7}.db.zst"
       - name: Upload to release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.147.0",
+  "version": "0.149.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": {
@@ -35,10 +35,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.147.0",
-    "@sdsrs/code-graph-linux-arm64": "0.147.0",
-    "@sdsrs/code-graph-darwin-x64": "0.147.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.147.0",
-    "@sdsrs/code-graph-win32-x64": "0.147.0"
+    "@sdsrs/code-graph-linux-x64": "0.149.0",
+    "@sdsrs/code-graph-linux-arm64": "0.149.0",
+    "@sdsrs/code-graph-darwin-x64": "0.149.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.149.0",
+    "@sdsrs/code-graph-win32-x64": "0.149.0"
   }
 }