@sdsrs/code-graph 0.112.1 → 0.114.0

package/README.md

@@ -353,7 +353,7 @@ Skip the full local index for team members and CI runners by publishing a
 ~3-5MB graph snapshot with each GitHub release.
 
 **Setup (one-time):**
-1. Copy `node_modules/code-graph-mcp/templates/code-graph-snapshot.yml`
+1. Copy `node_modules/@sdsrs/code-graph/claude-plugin/templates/code-graph-snapshot.yml`
    into your repo's `.github/workflows/`.
 2. Push a release tag. The workflow uploads
    `code-graph-snapshot-<sha>.db.zst` as a release asset.
@@ -361,7 +361,7 @@ Skip the full local index for team members and CI runners by publishing a
 **Verify:**
 
 ```bash
-npx code-graph-mcp snapshot inspect ./code-graph-snapshot-<sha>.db.zst
+npx -y -p @sdsrs/code-graph code-graph-mcp snapshot inspect ./code-graph-snapshot-<sha>.db.zst
 ```
 
 After setup, the auto-fetch is **opt-in per consumer**: an untrusted repo could

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

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

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

@@ -130,26 +130,56 @@ function saveState(state) {
 
 // ── Throttle ───────────────────────────────────────────────
 
+// The updater has given up on the current target release (MAX_UPDATE_ATTEMPTS
+// consecutive failed installs of the SAME version, retried once a day).
+// `suspendedAt` is stamped only on entry to that state and cleared on success
+// and on a new target, so it alone identifies it; `updateAttempts` is required
+// too so a hand-edited or half-written state file cannot park the updater.
+function isUpdateSuspended(state) {
+  return Boolean(state && state.suspendedAt) && (state.updateAttempts || 0) >= MAX_UPDATE_ATTEMPTS;
+}
+
 // Whether to hit GitHub now. Keyed to the previous check's outcome, with a force
-// override for high-intent triggers (session start / explicit reload). Ordering:
+// override for high-intent triggers (session start / explicit reload) and two
+// binary-health overrides. EVERY bypass is decided here — the caller used to
+// short-circuit `binaryMissing`/`binaryStale` outside this function, which put
+// them above the rate-limit arm and made the "wins over everything" below false:
+// a stale binary plus `rateLimited: true` hit the API on every session start
+// (measured: 1 request per check, vs 0 for the same state with a current
+// binary). Ordering:
 //   1. rate-limit backoff (RATE_LIMIT_INTERVAL_MS, 1h = GitHub's own reset
-//      window) wins over everything, force included — never push more requests
-//      into a GitHub 403. Safe to outrank force only because it is an hour; the
-//      24h it said before made one 403 a silent day-long no-op for `--force`.
-//   2. force → only the short SESSION_START_MIN_GAP_MS floor applies, so opening
+//      window) wins over everything — force and both binary overrides included.
+//      Never push more requests into a GitHub 403; a 403 cannot hand us a
+//      download URL either, so the bypasses have nothing to gain by outranking
+//      it. Safe to outrank force only because it is an hour; the 24h it said
+//      before made one 403 a silent day-long no-op for `--force`.
+//   2. binaryMissing → check now. This is the one repair still reachable while
+//      the download chain is otherwise parked (the suspension branch in
+//      checkForUpdate keeps that heal alive), so it outranks suspension.
+//   3. suspension → neither `binaryStale` nor `force` applies. A stale binary
+//      cannot be healed while the chain is parked, and since suspension makes
+//      `cachedBinaryStaleVsState` permanently true, that bypass otherwise
+//      fired on every single session forever and did nothing with the answer.
+//      Both fall through to the ordinary interval, which still notices a newer
+//      release (that un-suspends) and still lets the daily retry come due.
+//   4. force → only the short SESSION_START_MIN_GAP_MS floor applies, so opening
 //      a new session re-checks immediately while a crash/reopen loop still can't
 //      hammer the API.
-//   3. otherwise → an "up to date" result is re-verified on a short cadence
+//   5. otherwise → an "up to date" result is re-verified on a short cadence
 //      (UP_TO_DATE_RECHECK_MS). This is the release-publish race guard: a version
 //      can go live seconds AFTER a check that said "up to date", and the plain 6h
 //      interval left it invisible for the full 6h (observed live — v0.85.7
 //      published 8s after a check pinned v0.85.6). A pending-but-unfinished update
 //      keeps the 6h steady-state interval.
-function shouldCheck(state, { force = false } = {}) {
+function shouldCheck(state, { force = false, binaryMissing = false, binaryStale = false } = {}) {
   if (!state.lastCheck) return true;
   const elapsed = Date.now() - new Date(state.lastCheck).getTime();
   if (state.rateLimited) return elapsed >= RATE_LIMIT_INTERVAL_MS;
-  if (force) return elapsed >= SESSION_START_MIN_GAP_MS;
+  if (binaryMissing) return true;
+  if (!isUpdateSuspended(state)) {
+    if (binaryStale) return true;
+    if (force) return elapsed >= SESSION_START_MIN_GAP_MS;
+  }
   const interval = state.updateAvailable === false ? UP_TO_DATE_RECHECK_MS : CHECK_INTERVAL_MS;
   return elapsed >= interval;
 }
@@ -373,8 +403,12 @@ async function downloadBinary(latest) {
 
   try {
     fs.mkdirSync(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
+    // gates later — by the silent size check, which reported nothing about why.
     execFileSync('curl', [
-      '-sL', '-o', binaryTmp,
+      '-sfL', '-o', binaryTmp,
       latest.binaryUrl,
     ], hidden({ timeout: 60000, stdio: 'pipe' }));
 
@@ -427,8 +461,20 @@ function sha256File(filePath) {
 
 function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSha256) {
   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
+    // a word — and it sits ABOVE the two gates that DO explain themselves, so
+    // the most common download failures were also the only silent ones, each
+    // burning one of MAX_UPDATE_ATTEMPTS with nothing on stderr to explain it.
     const stat = fs.statSync(binaryTmp);
-    if (stat.size <= 1_000_000) return false;
+    if (stat.size <= 1_000_000) {
+      console.error(
+        `[code-graph] Refusing to install: downloaded binary is ${stat.size} bytes — far below the ~1 MB floor, ` +
+        'so the transfer was truncated or the server returned an error page. ' +
+        'The current binary is unchanged; the next update check retries.'
+      );
+      return false;
+    }
 
     // Integrity gate BEFORE the file is made executable or run, so a corrupted
     // or tampered download is never exec'd. The published <asset>.sha256 sidecar
@@ -462,13 +508,26 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSh
 
     const actualVersion = readBinaryVersion(binaryTmp);
     if (!actualVersion || (expectedVersion && actualVersion !== expectedVersion)) {
+      // Sibling of the size floor above: silent for the same reason and with the
+      // same cost. `--version` failing to run at all (wrong arch, missing libc)
+      // reads identically to a version mismatch without this.
+      console.error(
+        `[code-graph] Refusing to install: downloaded binary reports ${actualVersion ? `v${actualVersion}` : 'no runnable --version'}` +
+        `${expectedVersion ? `, expected v${expectedVersion}` : ''} — not installing it.`
+      );
       return false;
     }
 
     fs.renameSync(binaryTmp, binaryDst);
     clearBinaryCache();
     return true;
-  } catch {
+  } catch (e) {
+    // `e.code` is the whole diagnosis for this arm: ENOSPC (full disk), EACCES /
+    // EPERM (locked cache dir, or Windows refusing to replace the .exe the MCP
+    // server is running), EBUSY, EXDEV. A bare `catch { return false }` made all
+    // of them one indistinguishable failure that the caller counted as an
+    // attempt and printed nothing about.
+    console.error(`[code-graph] Binary promote failed${e && e.code ? ` (${e.code})` : ''}: ${e && e.message}`);
     return false;
   } finally {
     try {
@@ -834,10 +893,13 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
     // (launcher cannot start) and a present-but-stale binary (otherwise it stays
     // pinned to the old version for up to a full check interval — the binary
     // self-heal would never run inside the throttle window). Both bypass to the
-    // fetch + self-heal path below.
+    // fetch + self-heal path below — but they are ARGUMENTS to shouldCheck, not
+    // `||`-ed around it: as short-circuits out here they sat above the
+    // rate-limit backoff and the suspension state, the two conditions under
+    // which a fetch cannot accomplish anything at all.
     const binaryMissing = !fs.existsSync(cachedBinaryPath());
     const binaryStale = cachedBinaryStaleVsState(state);
-    if (!binaryMissing && !binaryStale && !shouldCheck(state, { force })) {
+    if (!shouldCheck(state, { force, binaryMissing, binaryStale })) {
       if (state.installedVersion !== installedVersion) {
         saveState({ ...state, installedVersion });
       }
@@ -1031,6 +1093,7 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
 
 module.exports = {
   checkForUpdate, commandExists, isDevMode, readState, compareVersions, shouldCheck,
+  isUpdateSuspended,
   getExtractedPluginVersion, readBinaryVersion, promoteVerifiedBinary,
   isSilentMode, isInstallMissingMode, isForceMode, isAutoUpdateDisabled,
   MAX_UPDATE_ATTEMPTS,

package/claude-plugin/scripts/doctor.js

@@ -55,6 +55,191 @@ function classifyEmbeddings(hc) {
   return { name: 'Embeddings', status: 'ok', detail: `hybrid — embeddings complete (${done}/${total})` };
 }
 
+/**
+ * Classify the `integrity` block that `health-check --json` has carried since
+ * v0.113.0 (audit DB-1). Pure, same as `classifyEmbeddings`.
+ *
+ * Severity is deliberately NOT uniform across the three probes:
+ *  - `quick_check` complaining means pages do not read back — the index is
+ *    corrupt, and only a rebuild fixes it. Error + fixId.
+ *  - `fts_drift != 0` means the FTS5 index and `nodes` disagree, so search
+ *    silently misses (or invents) symbols. Wrong answers, no crash. Warn + fixId.
+ *  - `orphan_vectors != 0` is dead weight that skews coverage math; answers stay
+ *    correct. It is DISCLOSED in the detail but does not raise an issue on its
+ *    own: the only repair is a full rebuild, and a permanent warn with a
+ *    disproportionate fix is how `doctor` ends up exiting 1 forever on installs
+ *    that are fine (the MCP server already reaps these at startup; a CLI-only
+ *    install is exactly who would be stuck with it).
+ * `null` on any probe means "could not be measured", never a fault.
+ * @returns {{name:string, status:'ok'|'warn'|'error'|'skip', detail:string, fixId?:string}}
+ */
+function classifyIntegrity(hc) {
+  const it = hc && hc.integrity;
+  if (!it || typeof it !== 'object') {
+    // Binary predates the probes. Say so rather than inventing a verdict — an
+    // absent measurement is not a passing one.
+    return { name: 'Integrity', status: 'skip', detail: 'not reported by this binary version' };
+  }
+  const orphanNote = it.orphan_vectors ? `; ${it.orphan_vectors} orphan vector(s)` : '';
+  const qc = it.quick_check;
+  if (typeof qc === 'string' && qc !== 'ok' && qc !== 'skipped_large') {
+    return {
+      name: 'Integrity', status: 'error', fixId: 'index-corrupt',
+      detail: `database is CORRUPT — quick_check: ${qc}${orphanNote}`,
+    };
+  }
+  if (typeof it.fts_drift === 'number' && it.fts_drift !== 0) {
+    return {
+      name: 'Integrity', status: 'warn', fixId: 'index-corrupt',
+      detail: `FTS index drifted from nodes by ${it.fts_drift} row(s) — search silently misses symbols${orphanNote}`,
+    };
+  }
+  if (qc === 'skipped_large') {
+    // The size gate skipped the page scan on purpose. Reporting `ok` here would
+    // claim a check that never ran.
+    return { name: 'Integrity', status: 'skip',
+      detail: `page check skipped (index over the size gate) — run: code-graph-mcp health-check --deep${orphanNote}` };
+  }
+  if (qc == null) {
+    return { name: 'Integrity', status: 'skip', detail: `page check unavailable${orphanNote}` };
+  }
+  return { name: 'Integrity', status: 'ok', detail: `quick_check ok, FTS in sync${orphanNote}` };
+}
+
+/**
+ * Turn a parsed `health-check --json` payload into doctor rows.
+ *
+ * Extracted so the success path and the recovered-from-stdout path (below)
+ * cannot classify the same payload differently. Pure.
+ */
+function classifyHealthReport(hc) {
+  // No-index short-circuit — binary deliberately returns a structured JSON with
+  // reason='no_index' instead of bailing, so we can route to the index-empty fix
+  // without grepping stderr.
+  if (hc.reason === 'no_index') {
+    return [
+      { name: 'Schema', status: 'ok', detail: 'binary ok (no index yet)' },
+      { name: 'Index', status: 'warn', detail: 'missing — not indexed yet', fixId: 'index-empty' },
+      { name: 'Embeddings', status: 'skip', detail: 'no index' },
+    ];
+  }
+  // The database could not be opened at all, so schema/nodes/embeddings are not
+  // unknown-but-probably-fine, they are unmeasurable. Reporting `Schema: ok
+  // vnull` off the zeroed payload would be a fabricated pass; the Integrity row
+  // below carries the real verdict and the `index-corrupt` fix.
+  if (hc.reason === 'corrupt') {
+    return [
+      { name: 'Schema', status: 'skip', detail: 'index unreadable' },
+      { name: 'Index', status: 'skip', detail: 'index unreadable' },
+      { name: 'Embeddings', status: 'skip', detail: 'index unreadable' },
+      classifyIntegrity(hc),
+    ];
+  }
+  const rows = [];
+  if (hc.issue && String(hc.issue).includes('schema')) {
+    rows.push({ name: 'Schema', status: 'warn', detail: hc.issue, fixId: 'schema-mismatch' });
+  } else {
+    rows.push({ name: 'Schema', status: 'ok', detail: `v${hc.schema_version}` });
+  }
+  if (hc.nodes === 0) {
+    rows.push({ name: 'Index', status: 'warn', detail: 'empty', fixId: 'index-empty' });
+  } else {
+    const age = hc.index_age ? ` (${hc.index_age})` : '';
+    rows.push({
+      name: 'Index', status: 'ok',
+      detail: `${hc.nodes} nodes, ${hc.edges} edges, ${hc.files} files${age}`,
+    });
+  }
+  // Embeddings / vector availability — pure classifier; warns on FTS5-only
+  // degradation (model missing/not loaded) instead of false-greening it.
+  rows.push(classifyEmbeddings(hc));
+  rows.push(classifyIntegrity(hc));
+  return rows;
+}
+
+/**
+ * Recover a health-check payload from a buffer, or null if it isn't one.
+ *
+ * `health-check --json` prints the FULL report to stdout and THEN exits 1 when
+ * the index is unhealthy, so `execFileSync` throwing does not mean there is no
+ * report — it means there is a report saying something is wrong. Requiring a
+ * key only this command emits keeps unrelated stdout (a panic, a wrapper's
+ * noise) from being read as a clean bill of health.
+ */
+function parseHealthPayload(buf) {
+  if (!buf) return null;
+  try {
+    const obj = JSON.parse(buf.toString().trim());
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null;
+    // `reason` covers payloads the binary emits BEFORE it can read a schema
+    // version (no_index, corrupt). Keying only on `schema_version` meant the
+    // corrupt payload — the one case where recovering the report matters most —
+    // was rejected and fell through to `binary-broken`. Caught by an end-to-end
+    // run against a real clobbered index; neither side's unit tests could see
+    // it, because each was asserted against its own fixture.
+    const looksLikeReport = 'schema_version' in obj || typeof obj.reason === 'string';
+    return looksLikeReport ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Spawn `health-check --json`. Separate + injectable: see `rebuildIndexInPlace`. */
+function runHealthCheckCli(binary) {
+  // Deliberately NOT `--deep`. That flag forces the integrity pragmas the
+  // default path skips above INTEGRITY_PRAGMA_MAX_BYTES, and quick_check reads
+  // every page at ~2.4 ms/MB — a multi-GB index would blow the 5 s budget below
+  // and report a phantom "health-check failed" instead of the integrity answer
+  // it went looking for. Raising the timeout to fit trades that for a doctor run
+  // that appears hung. `--deep` stays a user-invoked escape hatch until this
+  // call can size its own budget from the index.
+  return execFileSync(binary, ['health-check', '--json'], hidden({
+    cwd: process.cwd(),
+    timeout: 5000,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })).trim();
+}
+
+/**
+ * Schema / Index / Embeddings / Integrity rows from the binary's health-check.
+ *
+ * The failure branches are the point of this function existing separately.
+ * `health-check --json` prints the FULL report to stdout and THEN exits 1 when
+ * the index is unhealthy, so `execFileSync` throwing does not mean the probe
+ * failed. The old code read the throw as "the binary is broken" and emitted
+ * `Schema: error … fixId:'binary-broken'` — a fixId `runRepairs` has no case
+ * for. Net effect: the integrity probes added in v0.113.0 never reached the
+ * consumer they were built for, and a genuinely corrupt index was reported as a
+ * binary problem with no repair offered.
+ */
+function healthRows(binary, { runHealthCheck = runHealthCheckCli } = {}) {
+  try {
+    return classifyHealthReport(JSON.parse(runHealthCheck(binary)));
+  } catch (e) {
+    const recovered = parseHealthPayload(e.stdout);
+    if (recovered) return classifyHealthReport(recovered);
+
+    const rawStderr = e.stderr ? e.stderr.toString() : '';
+    const msg = rawStderr ? rawStderr.trim().slice(0, 100) : e.message.slice(0, 100);
+    // "No index found" is a missing-index situation, not a broken binary — the
+    // index-empty fix path knows how to create one. Without this branch the
+    // fixId routes to nothing and the report shows "0/1 addressed".
+    if (rawStderr.includes('No index found')) {
+      return [
+        { name: 'Schema', status: 'ok', detail: 'binary ok (no index yet)' },
+        { name: 'Index', status: 'warn', detail: 'missing — not indexed yet', fixId: 'index-empty' },
+        { name: 'Embeddings', status: 'skip', detail: 'no index' },
+      ];
+    }
+    return [
+      { name: 'Schema', status: 'error', detail: `health-check failed: ${msg}`, fixId: 'binary-broken' },
+      { name: 'Index', status: 'skip', detail: 'health-check failed' },
+      { name: 'Embeddings', status: 'skip', detail: 'health-check failed' },
+    ];
+  }
+}
+
 /**
  * Run all diagnostic checks. Returns an array of:
  *   { name: string, status: 'ok'|'warn'|'error'|'skip', detail: string, fixId?: string }
@@ -134,66 +319,9 @@ function runDiagnostics({ checkOnly = false } = {}) {
       results.push({ name: 'Source fresh', status: 'skip', detail: 'not dev mode' });
     }
 
-    // 4. health-check (schema, index, embeddings) via binary --json
+    // 4. health-check (schema, index, embeddings, integrity) via binary --json
     if (execOk) {
-      try {
-        const cwd = process.cwd();
-        const hcOutput = execFileSync(binary, ['health-check', '--json'], hidden({
-          cwd,
-          timeout: 5000,
-          encoding: 'utf8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-        })).trim();
-        const hc = JSON.parse(hcOutput);
-
-        // No-index short-circuit — binary deliberately returns a structured
-        // JSON with reason='no_index' instead of bailing, so we can route to
-        // the index-empty fix without grepping stderr. Falls through to the
-        // rest of runDiagnostics so Auto-update / Hooks still report.
-        if (hc.reason === 'no_index') {
-          results.push({ name: 'Schema', status: 'ok', detail: 'binary ok (no index yet)' });
-          results.push({ name: 'Index', status: 'warn', detail: 'missing — not indexed yet', fixId: 'index-empty' });
-          results.push({ name: 'Embeddings', status: 'skip', detail: 'no index' });
-        } else {
-          // Schema
-          if (hc.issue && hc.issue.includes('schema')) {
-            results.push({ name: 'Schema', status: 'warn', detail: hc.issue, fixId: 'schema-mismatch' });
-          } else {
-            results.push({ name: 'Schema', status: 'ok', detail: `v${hc.schema_version}` });
-          }
-
-          // Index
-          if (hc.nodes === 0) {
-            results.push({ name: 'Index', status: 'warn', detail: 'empty', fixId: 'index-empty' });
-          } else {
-            const age = hc.index_age ? ` (${hc.index_age})` : '';
-            results.push({
-              name: 'Index',
-              status: 'ok',
-              detail: `${hc.nodes} nodes, ${hc.edges} edges, ${hc.files} files${age}`,
-            });
-          }
-
-          // Embeddings / vector availability — pure classifier; warns on FTS5-only
-          // degradation (model missing/not loaded) instead of false-greening it.
-          results.push(classifyEmbeddings(hc));
-        }
-      } catch (e) {
-        const rawStderr = e.stderr ? e.stderr.toString() : '';
-        const msg = rawStderr ? rawStderr.trim().slice(0, 100) : e.message.slice(0, 100);
-        // "No index found" is a missing-index situation, not a broken binary —
-        // the index-empty fix path knows how to create one. Without this branch
-        // the fixId routes to nothing and the report shows "0/1 addressed".
-        if (rawStderr.includes('No index found')) {
-          results.push({ name: 'Schema', status: 'ok', detail: 'binary ok (no index yet)' });
-          results.push({ name: 'Index', status: 'warn', detail: 'missing — not indexed yet', fixId: 'index-empty' });
-          results.push({ name: 'Embeddings', status: 'skip', detail: 'no index' });
-        } else {
-          results.push({ name: 'Schema', status: 'error', detail: `health-check failed: ${msg}`, fixId: 'binary-broken' });
-          results.push({ name: 'Index', status: 'skip', detail: 'health-check failed' });
-          results.push({ name: 'Embeddings', status: 'skip', detail: 'health-check failed' });
-        }
-      }
+      results.push(...healthRows(binary));
     } else {
       results.push({ name: 'Schema', status: 'skip', detail: 'binary not executable' });
       results.push({ name: 'Index', status: 'skip', detail: 'binary not executable' });
@@ -495,7 +623,135 @@ function devBuildCommand(embed) {
     : 'cargo build --release --no-default-features';
 }
 
-function runRepairs(results) {
+// ── Post-repair re-scan for the auto-update-driven arms ────────────────────
+//
+// `auto-update.js check` has NO non-zero exit path: dev mode, the opt-out,
+// suspension, the rate-limit backoff and plain offline all print a line and exit
+// 0. So "execFileSync did not throw" carries no information about whether
+// anything was repaired, and the two arms below counted every one of those
+// no-ops as a fix — including the one the suspension notice sends the user here
+// to run, producing "✅ Update check complete" for a check that is suspended.
+// Re-read the same predicate the DIAGNOSIS used and let that decide, exactly as
+// the `hooks-invalid` arm does with its post-install re-scan.
+
+function triggerAutoUpdateCheck() {
+  execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], hidden({
+    timeout: 60000,
+    stdio: 'inherit',
+  }));
+}
+
+/**
+ * Mirror of the `version-mismatch` diagnosis (runDiagnostics step 2): the binary
+ * on disk reports the version the plugin expects. find-binary memoizes, and the
+ * promote happened in a CHILD process, so the cache has to be dropped first or
+ * this re-reads the pre-repair answer.
+ */
+function binaryVersionResolved({
+  find = findBinary, readVersion = readBinaryVersion, pluginVersion = getPluginVersion,
+} = {}) {
+  clearBinaryCache();
+  const binary = find();
+  if (!binary) return false;
+  const actual = readVersion(binary);
+  return Boolean(actual) && actual === pluginVersion();
+}
+
+/** Mirror of the `update-incomplete` diagnosis (runDiagnostics step 5). */
+function updateIncompleteResolved({ readStateFile = readUpdateState } = {}) {
+  const state = readStateFile();
+  return !(state && state.updateAvailable && state.binaryUpdated === false);
+}
+
+/**
+ * Mirror of the `index-corrupt` diagnosis: re-run the probes against the
+ * database the rebuild just produced and re-classify with the SAME function the
+ * diagnosis used, so "resolved" cannot mean something different from "not
+ * raised". A rebuild that exits 0 over failing hardware still fails this.
+ */
+function integrityResolved({ probe = probeHealth, classify = classifyIntegrity } = {}) {
+  const hc = probe();
+  if (!hc) return false;
+  const row = classify(hc);
+  return row.status !== 'error' && row.status !== 'warn';
+}
+
+/**
+ * Run `rebuild-index --confirm`. Returns false when there is no binary to run
+ * it with; throws whatever the child failed with (including the deliberate bail
+ * when another process holds the index lock, added in v0.113.0).
+ *
+ * Separate + injectable because `execFileSync` is destructured at load here, so
+ * a test that patches `child_process.execFileSync` after the fact stubs nothing
+ * and silently exercises the real spawn.
+ */
+function rebuildIndexInPlace({ find = findBinary } = {}) {
+  const binary = find();
+  if (!binary) return false;
+  execFileSync(binary, ['rebuild-index', '--confirm'], hidden({
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    timeout: 600000,  // full reindex, not a diff — same budget as a build
+  }));
+  return true;
+}
+
+/**
+ * Read a `health-check --json` payload, tolerating the exit-1-on-unhealthy
+ * contract (the report is on stdout either way). null when there is no payload.
+ */
+function probeHealth({ find = findBinary } = {}) {
+  const binary = find();
+  if (!binary) return null;
+  const opts = hidden({ cwd: process.cwd(), timeout: 5000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+  try {
+    return parseHealthPayload(execFileSync(binary, ['health-check', '--json'], opts));
+  } catch (e) {
+    return parseHealthPayload(e.stdout);
+  }
+}
+
+function readUpdateState() {
+  try { return readJson(path.join(CACHE_DIR, 'update-state.json')); } catch { return null; }
+}
+
+/**
+ * Why a just-run `auto-update.js check` can have done nothing, in the updater's
+ * own terms. Without this the user is told to update manually with no idea that
+ * the updater is deliberately parked — which is the state the doctor prompt
+ * itself came from.
+ * @returns {string|null} one clause, or null when nothing is known to block it
+ */
+function autoUpdateNoOpReason(state = readUpdateState(), env = process.env) {
+  if (env.CODE_GRAPH_NO_AUTO_UPDATE === '1') {
+    return 'auto-update is switched off by CODE_GRAPH_NO_AUTO_UPDATE=1';
+  }
+  if (!state) return null;
+  if (state.suspendedAt && (state.updateAttempts || 0) >= MAX_UPDATE_ATTEMPTS) {
+    return `auto-update is SUSPENDED after ${state.updateAttempts} failed attempts on v${state.latestVersion} `
+      + '(it retries once a day, and immediately when a newer release is published)';
+  }
+  if (state.rateLimited) {
+    return 'the updater is in its GitHub rate-limit backoff (up to 1h)';
+  }
+  return null;
+}
+
+function reportAutoUpdateNoOp(what) {
+  console.log(`  ❌ ${what}`);
+  const why = autoUpdateNoOpReason();
+  if (why) console.log(`     Why: ${why}.`);
+  console.log('     Update manually: `npm install -g @sdsrs/code-graph` (or `/plugin update code-graph-mcp`)');
+}
+
+function runRepairs(results, {
+  devMode = isDevMode,
+  runAutoUpdate = triggerAutoUpdateCheck,
+  binaryResolved = binaryVersionResolved,
+  updateResolved = updateIncompleteResolved,
+  integrityOk = integrityResolved,
+  rebuildIndex = rebuildIndexInPlace,
+} = {}) {
   const fixable = results.filter(r => r.fixId);
   if (fixable.length === 0) return 0;
 
@@ -504,17 +760,21 @@ function runRepairs(results) {
     switch (issue.fixId) {
       case 'binary-stale':
       case 'version-mismatch': {
-        if (!isDevMode()) {
+        if (!devMode()) {
           console.log('\n  Triggering binary update...');
           try {
-            execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], hidden({
-              timeout: 60000,
-              stdio: 'inherit',
-            }));
-            console.log('  \u2705 Update check complete');
-            fixed++;
+            runAutoUpdate();
           } catch {
             console.log('  \u274c Update check failed — install manually');
+            break;
+          }
+          // Exited 0 — which says nothing about whether the binary moved (see
+          // the re-scan note above). Ask the disk, not the exit code.
+          if (binaryResolved()) {
+            console.log('  \u2705 Binary now matches the version the plugin expects');
+            fixed++;
+          } else {
+            reportAutoUpdateNoOp('Update check ran, but the binary version still does not match the plugin');
           }
           break;
         }
@@ -547,7 +807,7 @@ function runRepairs(results) {
 
       case 'binary-missing': {
         console.log('\n  Installing binary...');
-        if (isDevMode()) {
+        if (devMode()) {
           // No binary to probe \u2014 build the fast FTS5 binary, but point at the
           // hybrid option so FTS5 isn't silently presented as the only choice.
           console.log('    \u2192 cargo build --release --no-default-features');
@@ -612,14 +872,18 @@ function runRepairs(results) {
       case 'update-incomplete': {
         console.log('\n  Completing auto-update...');
         try {
-          execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], hidden({
-            timeout: 60000,
-            stdio: 'inherit',
-          }));
-          console.log('  \u2705 Update check complete');
-          fixed++;
+          runAutoUpdate();
         } catch {
           console.log('  \u274c Update check failed');
+          break;
+        }
+        // Same as the version-mismatch arm: exit 0 is not evidence. Re-read
+        // the state file the diagnosis read.
+        if (updateResolved()) {
+          console.log('  \u2705 Auto-update completed — the binary download is no longer pending');
+          fixed++;
+        } else {
+          reportAutoUpdateNoOp('Update check ran, but the binary download is still recorded as incomplete');
         }
         break;
       }
@@ -692,6 +956,32 @@ function runRepairs(results) {
         break;
       }
 
+      case 'index-corrupt': {
+        // `incremental-index` (the index-empty arm) cannot help here: it opens
+        // the same damaged file and diffs against it. The index is a rebuildable
+        // cache, and this is the command health-check itself prints.
+        console.log('\n  Rebuilding corrupt index from scratch...');
+        console.log('    → code-graph-mcp rebuild-index --confirm');
+        try {
+          if (!rebuildIndex()) break;   // no binary to run it with
+        } catch {
+          // Includes the deliberate bail when another process holds the index
+          // lock (v0.113.0), which is a refusal, not a failure to repair.
+          console.log('  ❌ Index rebuild failed — see the error above');
+          break;
+        }
+        // Exit 0 says the command ran, not that the corruption cleared. Ask the
+        // database again, the same way the hooks arm re-scans after install().
+        if (integrityOk()) {
+          console.log('  ✅ Index rebuilt — integrity checks now pass');
+          fixed++;
+        } else {
+          console.log('  ❌ Rebuild completed but the integrity check still fails');
+          console.log('     The problem may be the filesystem or disk, not the index.');
+        }
+        break;
+      }
+
       case 'schema-mismatch': {
         console.log('\n  Schema migration happens automatically when the binary runs.');
         console.log('  If binary is older than DB, update the binary first.');
@@ -739,7 +1029,7 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length, unresolved };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, detectEmbedModel, devBuildCommand };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, classifyIntegrity, classifyHealthReport, parseHealthPayload, integrityResolved, healthRows, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, autoUpdateNoOpReason };
 
 // Shared by BOTH doctor entry points: `node doctor.js …` and `node lifecycle.js
 // doctor …`. It exists as one function because the first version of this guard

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

@@ -3,7 +3,13 @@
 # small (~3-5MB) zstd-compressed SQLite database that lets first-time
 # clones of your repo skip the initial full code-graph index.
 #
-# Requires: code-graph-mcp >= 0.23.0 published to npm.
+# Requires: @sdsrs/code-graph >= 0.23.0 published to npm.
+#
+# The package name is `@sdsrs/code-graph` (the `code-graph-mcp` binary lives
+# inside it). Do NOT shorten this to `npx -y code-graph-mcp` — that unscoped
+# name belongs to an unrelated publisher on npm, and `npx -y` would install and
+# execute their package in your CI with whatever permissions this job holds.
+# Bump the pinned version below when you want a newer snapshot format.
 
 name: Code Graph Snapshot
 on:
@@ -24,7 +30,7 @@ jobs:
           node-version: '20'
       - name: Build snapshot
         run: |
-          npx -y code-graph-mcp@latest snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.114.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.112.1",
+  "version": "0.114.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.112.1",
-    "@sdsrs/code-graph-linux-arm64": "0.112.1",
-    "@sdsrs/code-graph-darwin-x64": "0.112.1",
-    "@sdsrs/code-graph-darwin-arm64": "0.112.1",
-    "@sdsrs/code-graph-win32-x64": "0.112.1"
+    "@sdsrs/code-graph-linux-x64": "0.114.0",
+    "@sdsrs/code-graph-linux-arm64": "0.114.0",
+    "@sdsrs/code-graph-darwin-x64": "0.114.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.114.0",
+    "@sdsrs/code-graph-win32-x64": "0.114.0"
   }
 }