@sdsrs/code-graph 0.119.0 → 0.120.1

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

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

package/claude-plugin/scripts/adopt.js

@@ -808,7 +808,17 @@ function unadopt({ cwd, home } = {}) {
   // Also sweep any legacy memory-dir remnants (uninstall before auto-migration ran).
   const migrated = migrateLegacyMemoryDir({ cwd, home });
 
-  const registryUpdated = removeAdopted(effectiveCwd, home);
+  // Deregister ONLY what we actually cleaned. The registry is the sole record
+  // of which repos carry a managed block — `uninstall --unadopt-all` and the
+  // uninstall-time sweep are both driven by it — so dropping the entry for a
+  // project whose CLAUDE.md we could not rewrite (root-owned file, read-only
+  // mount, EPERM dir) strands that block with nothing left pointing at it.
+  // Harmless while the caller only ever passed the current cwd; load-bearing
+  // since the uninstall sweep walks the whole list, because an unconditional
+  // deregister empties the file and removeCacheResidue() only preserves a
+  // NON-EMPTY registry — so the failed project's record died with the cache.
+  const cleanupFailed = claudeMdUnwritable || claudeMdUnreadable;
+  const registryUpdated = cleanupFailed ? false : removeAdopted(effectiveCwd, home);
   return {
     ok: true, fileRemoved, blockPruned, claudeMdRemoved,
     claudeMdUnreadable, claudeMdUnwritable, registryUpdated,
@@ -889,7 +899,7 @@ if (require.main === module) {
 
 module.exports = {
   adopt, unadopt, memoryDir, formatResult, stripSentinelBlock,
-  readAdoptedProjects, recordAdopted, removeAdopted, adoptedRegistryFile,
+  readAdoptedProjects, readAdoptedResult, recordAdopted, removeAdopted, adoptedRegistryFile,
   isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh, isProjectRoot,
   detectProjectType, buildBlock, buildTriggerRows, migrateLegacyMemoryDir,
   claudeMdPath, detailDir, detailPath,

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

@@ -1063,7 +1063,12 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
       // that set it, and kept polling GitHub on the ordinary interval while
       // already rate-limited. Dead code since the backoff was written.
       saveState({ ...readState(), installedVersion, lastCheck: new Date().toISOString() });
-      return null;
+      // NOT null: null is the CLI's "nothing to do" and it prints "Up to date
+      // (vX)". A failed fetch means the opposite — the update status is
+      // UNKNOWN — and a user running this because they are stuck on an old
+      // version was being told the old version is current (offline, captive
+      // portal, proxy, GitHub 5xx all land here).
+      return { noop: true, reason: 'fetch-failed', from: installedVersion };
     }
 
     // Compare versions
@@ -1079,7 +1084,9 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
     // against our own parent.
     if (process.env.CODE_GRAPH_INSTALL_LOCK_HELD !== '1') {
       installLock = acquireLock(path.join(CACHE_DIR, 'install.lock'));
-      if (!installLock) return null;
+      // Reason, not null — same misreport as the fetch failure above: the
+      // holder is mid-update, so "Up to date (v<old>)" is exactly wrong.
+      if (!installLock) return { noop: true, reason: 'install-lock-held', from: installedVersion };
     }
 
     if (hasUpdate) {
@@ -1266,6 +1273,14 @@ if (require.main === module) {
         console.log(`Update available: v${result.to} (auto-install failed)`);
       } else if (result && result.binaryUpdated) {
         console.log(`Repaired binary cache (v${result.to})`);
+      } else if (result && result.noop && result.reason === 'fetch-failed') {
+        // Message only — the exit code stays 0 on purpose: an unreachable
+        // GitHub is not a failure of this command, and the launcher's install
+        // chain plus `doctor` both spawn it.
+        console.log(`Could not reach GitHub — update status UNKNOWN (still on v${result.from}). ` +
+          'Retried on the next session; run `code-graph-mcp doctor` if it persists.');
+      } else if (result && result.noop && result.reason === 'install-lock-held') {
+        console.log(`Another session is installing/updating right now — check skipped (on v${result.from}).`);
       } else if (!installMissing && isAutoUpdateDisabled()) {
         console.log('CODE_GRAPH_NO_AUTO_UPDATE=1 — auto-update skipped');
       } else if (!installMissing && isDevMode()) {

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

@@ -230,6 +230,36 @@ function isPlausibleReleaseBinary(candidate) {
   try { return fs.statSync(candidate).size > 1_000_000; } catch { return false; }
 }
 
+/**
+ * Both places npm may put the platform optionalDependency inside a
+ * `node_modules` root, most-likely first:
+ *
+ *   <root>/@sdsrs/code-graph-<plat>-<arch>/                        (hoisted)
+ *   <root>/@sdsrs/code-graph/node_modules/@sdsrs/code-graph-…/     (nested)
+ *
+ * Hoisting is an npm implementation detail, not a contract: npm 12 leaves the
+ * optionalDependency nested under the shell package on a plain
+ * `npm install -g @sdsrs/code-graph`, while older npm hoists it (both layouts
+ * were observed on one machine, 2026-08-17). Probing only the hoisted spelling
+ * made a SUCCESSFUL npm install read as "did not yield a binary": the launcher
+ * then re-downloaded ~41MB from GitHub, and — the part that outlives the
+ * session — never called `recordGlobalInstall()`, so `uninstall` had no marker
+ * proving the plugin owns those global packages and left them on PATH forever.
+ *
+ * Discovery only. The global-package INVENTORY scanners (staleGlobalPkgs,
+ * installedGlobalPkgs, doctor) stay top-level-on-purpose: a nested
+ * optionalDependency is the shell package's private dependency, so
+ * `npm install -g`/`npm uninstall -g` on its name would introduce or orphan a
+ * top-level global the user never asked for.
+ */
+function platformPkgBinaries(nodeModulesRoot) {
+  const pkg = `code-graph-${PLATFORM}-${ARCH}`;
+  return [
+    path.join(nodeModulesRoot, '@sdsrs', pkg, BINARY_NAME),
+    path.join(nodeModulesRoot, '@sdsrs', 'code-graph', 'node_modules', '@sdsrs', pkg, BINARY_NAME),
+  ];
+}
+
 function platformBinaryCandidates() {
   const out = [];
   // Fast path: standard module resolution.
@@ -239,10 +269,11 @@ function platformBinaryCandidates() {
     if (isNativeBinary(bin) && isPlausibleReleaseBinary(bin)) out.push(bin);
   } catch { /* not in node_modules walk-up */ }
 
-  // Slow path: explicit global node_modules probe.
+  // Slow path: explicit global node_modules probe, both npm layouts.
   for (const globalRoot of globalNodeModulesCandidates()) {
-    const bin = path.join(globalRoot, '@sdsrs', `code-graph-${PLATFORM}-${ARCH}`, BINARY_NAME);
-    if (isNativeBinary(bin) && isPlausibleReleaseBinary(bin)) out.push(bin);
+    for (const bin of platformPkgBinaries(globalRoot)) {
+      if (isNativeBinary(bin) && isPlausibleReleaseBinary(bin)) out.push(bin);
+    }
   }
 
   return out;
@@ -363,9 +394,12 @@ function findBinaryUncached() {
   const npxDir = path.join(os.homedir(), '.npm', '_npx');
   try {
     for (const entry of fs.readdirSync(npxDir)) {
-      const platDir = path.join(npxDir, entry, 'node_modules', '@sdsrs', `code-graph-${PLATFORM}-${ARCH}`);
-      const hit = gate.consider(path.join(platDir, BINARY_NAME));
-      if (hit) return hit;
+      // Same hoisted-or-nested question as the global prefix — an npx tree is
+      // just another node_modules root, and npm decides the layout there too.
+      for (const bin of platformPkgBinaries(path.join(npxDir, entry, 'node_modules'))) {
+        const hit = gate.consider(bin);
+        if (hit) return hit;
+      }
     }
   } catch { /* no npx cache */ }
 

package/claude-plugin/scripts/lifecycle.js

@@ -588,10 +588,92 @@ function cleanupDisabledStatusline() {
   // 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.
+  //
+  // Adoption comes off in the SAME breath, and BEFORE the wipe: install's
+  // auto-adopt writes a managed block into every project's CLAUDE.md, and until
+  // now nothing reachable removed it. session-init.js owned that step, on the
+  // branch its own comment concedes "usually never runs again" after a real
+  // uninstall — so the block (steering Claude at a CLI that is being deleted two
+  // lines below) survived forever in every adopted repo. The registry that names
+  // those projects lives inside CACHE_DIR, which is exactly why this must run
+  // first: same capture-before-cleanup ordering the rest of this teardown
+  // already learned. This branch fires at most once — the write above removes
+  // our composite from settings.json, so Claude Code stops invoking us.
   let cacheRemoved = false;
-  if (uninstalled) cacheRemoved = removeCacheResidue();
+  let unadopted = [];
+  let registryUnusable = false;
+  if (uninstalled) {
+    ({ unadopted, registryUnusable } = unadoptRegisteredProjects());
+    cacheRemoved = removeCacheResidue();
+  }
 
-  return { cleaned: true, settingsChanged, cacheRemoved };
+  return { cleaned: true, settingsChanged, cacheRemoved, unadopted, registryUnusable };
+}
+
+/**
+ * Strip the managed CLAUDE.md block + generated `.claude/plugin_code_graph_mcp.md`
+ * from every project in the adopted-projects registry. `unadopt` is
+ * sentinel-guarded, so user prose outside the managed block is preserved and a
+ * project that was already cleaned is a no-op.
+ *
+ * Fully swallowed per project AND overall: this runs inside a statusline render
+ * (statusline.js / statusline-composite.js call the caller at their top), where
+ * an uncaught throw blanks the user's status line — and an unreadable project
+ * must not cost the remaining ones their cleanup.
+ */
+function unadoptRegisteredProjects() {
+  const out = [];
+  let readAdoptedResult, unadopt;
+  try { ({ readAdoptedResult, unadopt } = require('./adopt')); }
+  catch { return { unadopted: out, registryUnusable: false }; } // POSIX-only helper unavailable — teardown continues
+  // readAdoptedResult, NOT the lenient readAdoptedProjects(): that wrapper
+  // collapses "unreadable / truncated / wrong shape" into `[]`, which here is
+  // indistinguishable from "no projects to clean" — so a corrupt registry would
+  // silently sweep nothing AND still be deleted by removeCacheResidue() below,
+  // taking the only record of which repos carry a managed block with it. adopt.js
+  // documents the same bit for the same reason: only a genuinely ABSENT file may
+  // be read as empty.
+  let res;
+  try { res = readAdoptedResult(); } catch { return { unadopted: out, registryUnusable: true }; }
+  if (res && res.unusable) return { unadopted: out, registryUnusable: true };
+  for (const project of (res && res.list) || []) {
+    try {
+      const r = unadopt({ cwd: project });
+      out.push({ project, cleaned: !!(r && (r.blockPruned || r.fileRemoved || r.claudeMdRemoved)) });
+    } catch (e) {
+      out.push({ project, cleaned: false, error: (e && e.message) || String(e) });
+    }
+  }
+  reportUnadoptSweep(out);
+  return { unadopted: out, registryUnusable: false };
+}
+
+/**
+ * Tell the user their repos were just edited. Everything else about this
+ * teardown is invisible by construction: it runs inside a statusline render,
+ * both callers `process.exit(0)` on `cleaned` and discard the return value, and
+ * Claude Code fires no uninstall hook — so without this line the first signal is
+ * unexplained `CLAUDE.md` diffs in `git status` across several repositories.
+ * stderr, because a statusline's stdout IS the status line.
+ */
+function reportUnadoptSweep(entries) {
+  try {
+    const cleaned = entries.filter((e) => e && e.cleaned).map((e) => e.project);
+    const failed = entries.filter((e) => e && !e.cleaned).map((e) => e.project);
+    if (!cleaned.length && !failed.length) return;
+    const lines = [];
+    if (cleaned.length) {
+      lines.push(`[code-graph] Plugin uninstalled — removed the managed CLAUDE.md block from ${cleaned.length} project(s):`);
+      for (const p of cleaned.slice(0, 10)) lines.push(`             ${p}`);
+      if (cleaned.length > 10) lines.push(`             …and ${cleaned.length - 10} more`);
+      lines.push('             Your own text outside the block was kept; .code-graph/ index dirs are untouched.');
+    }
+    if (failed.length) {
+      lines.push(`[code-graph] Could NOT clean ${failed.length} project(s) — remove the block by hand or run \`code-graph-mcp unadopt\` there:`);
+      for (const p of failed.slice(0, 10)) lines.push(`             ${p}`);
+    }
+    process.stderr.write(lines.join('\n') + '\n');
+  } catch { /* a notice must never be able to fail a teardown */ }
 }
 
 // --- Scope Conflict Detection ---
@@ -1672,9 +1754,20 @@ function removeCacheResidue() {
   try {
     registryPath = require('./adopt').adoptedRegistryFile();
     const raw = fs.existsSync(registryPath) ? fs.readFileSync(registryPath) : null;
-    const parsed = raw ? JSON.parse(raw.toString('utf8')) : null;
-    if (Array.isArray(parsed) && parsed.length) registry = raw;
-  } catch { /* POSIX-only helper, unreadable, or corrupt — nothing to preserve */ }
+    if (raw) {
+      let parsed = null;
+      let usable = true;
+      try { parsed = JSON.parse(raw.toString('utf8')); } catch { usable = false; }
+      // Preserve a NON-EMPTY list (projects still carry a block) and anything we
+      // could not READ as a list. The unusable case used to fall into the same
+      // "nothing to preserve" catch as a missing file — the strictly worse
+      // outcome, since a registry we cannot parse is the one whose contents we
+      // are least able to reconstruct, and the sweep above deliberately skips it
+      // rather than guessing. Only a genuinely EMPTY array strands nothing and
+      // is allowed to go with the cache dir.
+      if (!usable || !Array.isArray(parsed) || parsed.length) registry = raw;
+    }
+  } catch { /* POSIX-only helper or an unreadable path — nothing to preserve */ }
   try {
     fs.rmSync(CACHE_DIR, { recursive: true, force: true });
   } catch { return false; }
@@ -1690,7 +1783,7 @@ function removeCacheResidue() {
 module.exports = {
   install, uninstall, update, healthCheck, scanForBrokenPaths, checkScopeConflict,
   isPluginExplicitlyDisabled, isPluginInactive, isPluginUninstalled, removeCacheResidue,
-  cleanupDisabledStatusline,
+  cleanupDisabledStatusline, unadoptRegisteredProjects,
   readManifest, readJson, readJsonResult, readSettingsForWrite, writeJsonAtomic,
   readRegistry, readRegistryForWrite, writeRegistry,
   getPluginVersion, cleanupOldCacheVersions,

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

@@ -406,6 +406,30 @@ function ensureIndexFresh() {
   return 'refreshing';
 }
 
+/**
+ * What to tell a user whose binary is missing. A missing binary is the NORMAL
+ * state of the first session after `/plugin install` — nothing ships the ~40MB
+ * engine with the plugin — and both automatic install paths are already
+ * running by the time the user reads this: launchBackgroundAutoUpdate() below
+ * (a missing binary bypasses the check throttle) and the MCP launcher's own
+ * install chain. Telling that user "MCP server cannot start. Install: npm
+ * install -g" reads as a failed install and sends them to fix something that
+ * is already fixing itself.
+ *
+ * The manual instruction is still the right answer when the user has opted out
+ * of auto-update, because then nothing else will fetch it. Pure so both arms
+ * are testable without a binary-less machine.
+ */
+function missingBinaryMessage(env = process.env) {
+  if (env.CODE_GRAPH_NO_AUTO_UPDATE === '1') {
+    return '[code-graph] Binary not found, and auto-download is off (CODE_GRAPH_NO_AUTO_UPDATE=1).\n' +
+           '            Install it yourself:  npm install -g @sdsrs/code-graph\n';
+  }
+  return '[code-graph] Binary not found — fetching it in the background (~40MB, first run only).\n' +
+         '            Tools appear as soon as it lands; no restart needed.\n' +
+         '            Still missing next session? Run `code-graph-mcp doctor`.\n';
+}
+
 /**
  * Verify binary is available and executable.
  * On macOS, detect Gatekeeper quarantine (common after npm/GitHub download).
@@ -415,10 +439,7 @@ function verifyBinary() {
   const { findBinary } = require('./find-binary');
   const binary = findBinary();
   if (!binary) {
-    process.stderr.write(
-      '[code-graph] Binary not found — MCP server cannot start.\n' +
-      'Install: npm install -g @sdsrs/code-graph\n'
-    );
+    process.stderr.write(missingBinaryMessage());
     return { available: false, binary: null };
   }
 
@@ -527,6 +548,18 @@ function consistencyCheck(binary) {
   return issues;
 }
 
+/**
+ * Do two paths name the same project? The registry stores what `adopt` was
+ * given and `process.cwd()` is what the shell resolved, so a symlinked repo
+ * path (`/tmp` → `/private/tmp` on macOS) compares unequal as raw strings.
+ * realpath both, fall back to the resolved literal when a side no longer exists.
+ */
+function samePath(a, b) {
+  if (!a || !b) return false;
+  const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+  return real(a) === real(b);
+}
+
 function runSessionInit({ source } = {}) {
   // GC the shared tmp dir before anything else, so it happens even on the
   // inactive / non-project early returns below — those sessions still wrote
@@ -543,7 +576,8 @@ function runSessionInit({ source } = {}) {
     // Third caller of the same unguarded teardown (statusline.js and
     // statusline-composite.js are the others): a read-only ~/.claude turns this
     // into an uncaught throw that takes down the whole SessionStart hook.
-    try { cleanupDisabledStatusline(); } catch { /* best-effort teardown */ }
+    let cleanup = null;
+    try { cleanup = cleanupDisabledStatusline(); } catch { /* best-effort teardown */ }
     // 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, AND it
@@ -570,9 +604,18 @@ function runSessionInit({ source } = {}) {
       // other projects is the preservation inside removeCacheResidue(); this
       // ordering is the belt to that pair of braces, and it is what keeps the
       // single-project case from depending on the preservation at all.
-      let unadopted = false;
+      //
+      // cleanupDisabledStatusline() now sweeps the WHOLE adopted-projects
+      // registry (it is the only teardown that still runs after a real
+      // uninstall), so this cwd is usually already clean by the time we get
+      // here. Fold that in rather than re-deriving it: with the work moved
+      // earlier, the local `unadopt` returns "nothing to clean" and reporting
+      // `unadopted:false` for a project whose block IS gone would be a false
+      // negative in the one field a caller could act on.
+      let unadopted = !!(cleanup && Array.isArray(cleanup.unadopted)
+        && cleanup.unadopted.some((u) => u && u.cleaned && samePath(u.project, process.cwd())));
       try {
-        if (!isNonProjectCwd(process.cwd())) {
+        if (!unadopted && !isNonProjectCwd(process.cwd())) {
           const r = unadopt({ cwd: process.cwd() });
           unadopted = !!(r && (r.blockPruned || r.fileRemoved || r.claudeMdRemoved));
         }
@@ -924,7 +967,7 @@ module.exports = {
   indexNeedsRevalidation,
   injectProjectMap,
   injectRecentImpact,
-  verifyBinary,
+  verifyBinary, missingBinaryMessage,
   consistencyCheck,
   runSessionInit,
   computeQuietHooks,

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.119.0 code-graph-mcp snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.120.1 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.119.0",
+  "version": "0.120.1",
   "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.119.0",
-    "@sdsrs/code-graph-linux-arm64": "0.119.0",
-    "@sdsrs/code-graph-darwin-x64": "0.119.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.119.0",
-    "@sdsrs/code-graph-win32-x64": "0.119.0"
+    "@sdsrs/code-graph-linux-x64": "0.120.1",
+    "@sdsrs/code-graph-linux-arm64": "0.120.1",
+    "@sdsrs/code-graph-darwin-x64": "0.120.1",
+    "@sdsrs/code-graph-darwin-arm64": "0.120.1",
+    "@sdsrs/code-graph-win32-x64": "0.120.1"
   }
 }