@sdsrs/code-graph 0.147.0 → 0.148.0

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

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

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/lifecycle.js

@@ -1989,6 +1989,35 @@ 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.
+/**
+ * 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() {
   // 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,
@@ -2051,6 +2080,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,
 };
@@ -2100,7 +2130,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.148.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.148.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.148.0",
+    "@sdsrs/code-graph-linux-arm64": "0.148.0",
+    "@sdsrs/code-graph-darwin-x64": "0.148.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.148.0",
+    "@sdsrs/code-graph-win32-x64": "0.148.0"
   }
 }