@sdsrs/code-graph 0.148.0 → 0.149.0

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.148.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/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
@@ -2018,7 +2041,39 @@ const POST_TEARDOWN_UI_NOTE = [
   '`/plugin uninstall code-graph-mcp` there to sync its UI.',
 ];
 
-function removeCacheResidue() {
+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.
@@ -2046,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 {
@@ -2089,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

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.148.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.148.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.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"
+    "@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"
   }
 }