@sdsrs/code-graph 0.134.0 → 0.136.0

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

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

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

@@ -167,6 +167,43 @@ function saveState(state) {
   }
 }
 
+// ── Failure diagnostics ────────────────────────────────────
+//
+// The updater's main trigger is `launchBackgroundAutoUpdate` in session-init.js:
+// `spawn(..., { detached: true, stdio: 'ignore' })`. On that path EVERY
+// `console.error` in this file goes to /dev/null — the sha-sidecar refusal, the
+// size floor, the checksum mismatch, the promote EACCES, the repoint block. All
+// the user gets is the statusline's "⚠ update stuck" and a `doctor` that re-runs
+// its checks instead of reporting what already failed (audit 2026-09-05 JS-02).
+//
+// Recorded in memory and persisted by the ONE site that already writes state,
+// rather than a `saveState` at each rejection point: `CACHE_DIR` is
+// `~/.cache/code-graph` with no env seam, so a leaf function that persisted on
+// its own would have in-process unit tests writing into the developer's real
+// cache directory.
+let lastFailure = null;
+
+/** Record why the updater refused/failed. Returns `message` so call sites can
+ *  print the same string they store, instead of maintaining two copies. */
+function noteUpdateFailure(stage, message) {
+  lastFailure = {
+    at: new Date().toISOString(),
+    stage,
+    // Bounded: `e.message` can carry a whole curl transcript, and this lands in
+    // a JSON file read on every session start.
+    message: String(message == null ? '' : message).slice(0, 300),
+  };
+  return message;
+}
+
+/** Read-and-clear. The caller is about to persist it (or to record a success,
+ *  which must not leave the previous attempt's reason behind). */
+function takeUpdateFailure() {
+  const f = lastFailure;
+  lastFailure = null;
+  return f;
+}
+
 // ── Throttle ───────────────────────────────────────────────
 
 // The updater has given up on the current target release (MAX_UPDATE_ATTEMPTS
@@ -525,7 +562,8 @@ async function downloadBinary(latest, { needsUpdate = cachedBinaryNeedsUpdate }
   if (!latest || !latest.binaryUrl) return false;
   if (!needsUpdate(latest)) return false; // already at latest.version — no fetch
   if (!commandExists('curl')) {
-    console.error('[code-graph] Binary download skipped: curl not on PATH.');
+    console.error(`[code-graph] ${noteUpdateFailure('curl-missing',
+      'Binary download skipped: curl not on PATH.')}`);
     return false;
   }
 
@@ -569,14 +607,16 @@ async function downloadBinary(latest, { needsUpdate = cachedBinaryNeedsUpdate }
       }
     }
     if (!expectedSha) {
-      console.error(`[code-graph] Refusing to install: no sha256 sidecar for ${latest.binaryUrl} (fetched twice). The current binary is unchanged; the next update check will retry.`);
+      console.error(`[code-graph] ${noteUpdateFailure('binary-sha-sidecar-missing',
+        `Refusing to install: no sha256 sidecar for ${latest.binaryUrl} (fetched twice). The current binary is unchanged; the next update check will retry.`)}`);
       try { fs.unlinkSync(binaryTmp); } catch { /* ok */ }
       return false;
     }
 
     return promoteVerifiedBinary(binaryTmp, binaryDst, latest.version, expectedSha);
   } catch (e) {
-    console.error(`[code-graph] Binary download failed: ${e.message}`);
+    console.error(`[code-graph] ${noteUpdateFailure('binary-download-failed',
+      `Binary download failed: ${e.message}`)}`);
     return false;
   }
 }
@@ -599,11 +639,10 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSh
     // burning one of MAX_UPDATE_ATTEMPTS with nothing on stderr to explain it.
     const stat = fs.statSync(binaryTmp);
     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, ` +
+      console.error(`[code-graph] ${noteUpdateFailure('binary-too-small',
+        `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.'
-      );
+        'The current binary is unchanged; the next update check retries.')}`);
       return false;
     }
 
@@ -618,13 +657,15 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSh
     // a fail-closed `src/snapshot/install.rs` — and a warning printed to stderr
     // during a background auto-update is seen by nobody.
     if (!expectedSha256) {
-      console.error('[code-graph] No expected sha256 supplied — refusing to install an unverified binary.');
+      console.error(`[code-graph] ${noteUpdateFailure('binary-sha-missing',
+        'No expected sha256 supplied — refusing to install an unverified binary.')}`);
       try { fs.unlinkSync(binaryTmp); } catch { /* ok */ }
       return false;
     }
     const actualSha = sha256File(binaryTmp);
     if (actualSha.toLowerCase() !== String(expectedSha256).toLowerCase()) {
-      console.error(`[code-graph] Binary checksum mismatch (sha256): expected ${expectedSha256}, got ${actualSha} — refusing to install.`);
+      console.error(`[code-graph] ${noteUpdateFailure('binary-checksum-mismatch',
+        `Binary checksum mismatch (sha256): expected ${expectedSha256}, got ${actualSha} — refusing to install.`)}`);
       return false;
     }
 
@@ -642,10 +683,9 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSh
       // 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.`
-      );
+      console.error(`[code-graph] ${noteUpdateFailure('binary-version-unrunnable',
+        `Refusing to install: downloaded binary reports ${actualVersion ? `v${actualVersion}` : 'no runnable --version'}` +
+        `${expectedVersion ? `, expected v${expectedVersion}` : ''} — not installing it.`)}`);
       return false;
     }
 
@@ -658,7 +698,8 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSh
     // 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}`);
+    console.error(`[code-graph] ${noteUpdateFailure('binary-promote-failed',
+      `Binary promote failed${e && e.code ? ` (${e.code})` : ''}: ${e && e.message}`)}`);
     return false;
   } finally {
     try {
@@ -706,7 +747,8 @@ async function downloadAndInstall(latest, {
   // Pre-flight: check required CLI tools before attempting any download
   const missingTools = ['curl', 'tar'].filter(cmd => !cmdExists(cmd));
   if (missingTools.length > 0) {
-    console.error(`[code-graph] Auto-update skipped: missing required tools: ${missingTools.join(', ')}. Install them to enable auto-updates.`);
+    console.error(`[code-graph] ${noteUpdateFailure('missing-tools',
+      `Auto-update skipped: missing required tools: ${missingTools.join(', ')}. Install them to enable auto-updates.`)}`);
     return { pluginUpdated: false, binaryUpdated: false };
   }
 
@@ -743,7 +785,8 @@ async function downloadAndInstall(latest, {
     // the user on their current, working plugin version; the binary update below
     // still runs.
     if (!latest.pluginTarballUrl) {
-      console.error(`[code-graph] Plugin update skipped: release ${latest.version} publishes no ${PLUGIN_ASSET_NAME} — refusing to install plugin code from an unverifiable source archive.`);
+      console.error(`[code-graph] ${noteUpdateFailure('plugin-tarball-absent',
+        `Plugin update skipped: release ${latest.version} publishes no ${PLUGIN_ASSET_NAME} — refusing to install plugin code from an unverifiable source archive.`)}`);
       return { pluginUpdated: false, binaryUpdated: await downloadBin(latest), marketplaceRefreshed: false };
     }
     const tarballPath = path.join(tmpDir, PLUGIN_ASSET_NAME);
@@ -773,7 +816,8 @@ async function downloadAndInstall(latest, {
     }
     const actualSha = fs.existsSync(tarballPath) ? sha256File(tarballPath) : null;
     if (!expectedSha || !actualSha || expectedSha.toLowerCase() !== actualSha.toLowerCase()) {
-      console.error(`[code-graph] Plugin tarball integrity check failed (expected ${expectedSha || '<no sidecar>'}, got ${actualSha || '<no download>'}) — refusing to extract.`);
+      console.error(`[code-graph] ${noteUpdateFailure('plugin-tarball-integrity',
+        `Plugin tarball integrity check failed (expected ${expectedSha || '<no sidecar>'}, got ${actualSha || '<no download>'}) — refusing to extract.`)}`);
       return { pluginUpdated: false, binaryUpdated: await downloadBin(latest), marketplaceRefreshed: false };
     }
 
@@ -837,11 +881,10 @@ async function downloadAndInstall(latest, {
         const why = installedRead.error
           ? (installedRead.error.code || installedRead.error.message)
           : 'it does not contain a JSON object';
-        console.error(
-          `[code-graph] plugin ${latest.version} is installed, but ${installedPath} ` +
+        console.error(`[code-graph] ${noteUpdateFailure('repoint-registry-unreadable',
+          `plugin ${latest.version} is installed, but ${installedPath} ` +
           `could not be read (${why}) — its entry for this plugin still points at the ` +
-          'previous version. Run `/plugin update` or repair that file by hand.'
-        );
+          'previous version. Run `/plugin update` or repair that file by hand.')}`);
         repointBlocked = true;
       } else {
         let installed = installedRead.value;
@@ -861,12 +904,11 @@ async function downloadAndInstall(latest, {
               `to ${backup} first.`
             );
           } else {
-            console.error(
-              `[code-graph] plugin ${latest.version} is installed, but ${installedPath} ` +
+            console.error(`[code-graph] ${noteUpdateFailure('repoint-lossy-no-backup',
+              `plugin ${latest.version} is installed, but ${installedPath} ` +
               'contains bytes that are not valid UTF-8 and no backup copy could be made — ' +
               'its entry for this plugin still points at the previous version. Rewriting it ' +
-              'would replace those bytes permanently. Run `/plugin update` after repairing it.'
-            );
+              'would replace those bytes permanently. Run `/plugin update` after repairing it.')}`);
             installed = null;
             repointBlocked = true;
           }
@@ -885,11 +927,10 @@ async function downloadAndInstall(latest, {
           // Present but not the shape we can write into (`[]`, or a truthy
           // non-array). Blocked, NOT skipped: a silent skip here would feed the
           // JS-02 treadmill through a new door.
-          console.error(
-            `[code-graph] plugin ${latest.version} is installed, but this plugin's entry in ` +
+          console.error(`[code-graph] ${noteUpdateFailure('repoint-entry-malformed',
+            `plugin ${latest.version} is installed, but this plugin's entry in ` +
             `${installedPath} is malformed (expected a non-empty array) — it still points at ` +
-            'the previous version. Run `/plugin update` or repair that file by hand.'
-          );
+            'the previous version. Run `/plugin update` or repair that file by hand.')}`);
           repointBlocked = true;
         }
         if (repointable) {
@@ -899,11 +940,10 @@ async function downloadAndInstall(latest, {
           try {
             writeJsonAtomic(installedPath, installed);
           } catch (err) {
-            console.error(
-              `[code-graph] plugin ${latest.version} is installed, but ${installedPath} ` +
+            console.error(`[code-graph] ${noteUpdateFailure('repoint-write-failed',
+              `plugin ${latest.version} is installed, but ${installedPath} ` +
               `could not be written (${err.code || err.name}) — its entry for this plugin ` +
-              'still points at the previous version. Run `/plugin update`.'
-            );
+              'still points at the previous version. Run `/plugin update`.')}`);
             repointBlocked = true;
           }
         }
@@ -946,7 +986,8 @@ async function downloadAndInstall(latest, {
 
     return { pluginUpdated, binaryUpdated, marketplaceRefreshed, repointBlocked };
   } catch (e) {
-    console.error(`[code-graph] Plugin download/extract failed: ${e.message}`);
+    console.error(`[code-graph] ${noteUpdateFailure('plugin-extract-failed',
+      `Plugin download/extract failed: ${e.message}`)}`);
     return { pluginUpdated: false, binaryUpdated: false, marketplaceRefreshed };
   } finally {
     try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ok */ }
@@ -1311,6 +1352,11 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
           latestVersion: latest.version,
           updateAvailable: true,
           updateAttempts: attempts,
+          // The suspension notice below says "N failed attempts" without ever
+          // saying what failed. Carry the last recorded reason forward so
+          // `doctor` can answer that; `healedMissing` above may have recorded a
+          // fresh one on the way in.
+          lastError: takeUpdateFailure() || state.lastError || null,
           // Stamp on ENTRY to suspension, then leave it alone: the retry clock
           // must measure time since we gave up, not time since the last check
           // (which every session would reset, making the retry unreachable).
@@ -1366,6 +1412,13 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
         suspendedAt: nextSuspendedAt,
         lastUpdate: success ? new Date().toISOString() : state.lastUpdate,
         rateLimited: false,
+        // The reason this attempt failed, or null once one succeeds. Every
+        // refusal above printed to a stderr nobody reads (detached, stdio
+        // 'ignore'); this is the only channel that survives to `doctor`.
+        // `takeUpdateFailure()` runs on BOTH arms so a stale reason from an
+        // earlier attempt in the same process can never be attributed to this
+        // one (JS-02).
+        lastError: (() => { const f = takeUpdateFailure(); return success ? null : (f || state.lastError || null); })(),
         binaryUpdated: result.binaryUpdated,
         marketplaceRefreshed: result.marketplaceRefreshed,
       };
@@ -1413,6 +1466,11 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
       updateAttempts: 0,
       suspendedAt: null,
       rateLimited: false,
+      // Same reasoning one field up: the shell is current, so a stored reason
+      // describes an update that is no longer pending. Cleared unless the
+      // binary self-heal ON THIS PASS recorded a fresh one — that chain keeps
+      // its own budget and can still be failing while the shell is fine.
+      lastError: takeUpdateFailure() || null,
       binaryUpdated: selfHealedBinary || state.binaryUpdated,
       // The shell-update counters above reset because the shell IS current.
       // The BINARY heal keeps its own, un-reset budget — clearing it here is
@@ -1445,6 +1503,7 @@ module.exports = {
   selfHealGlobalPkgs, staleGlobalPkgs, globalPkgVersion, npmInstallGlobal,
   shouldHealGlobalsOnThrottle, inactiveNodeGlobalRelics,
   downloadAndInstall, refreshMarketplaceClone, marketplaceCloneDir,
+  noteUpdateFailure, takeUpdateFailure,
 };
 
 // CLI: node auto-update.js [check|status] [--silent] [--install-missing]

package/claude-plugin/scripts/cg-answer.js

@@ -33,9 +33,17 @@ const { hidden } = require('./proc-opts');
 // roughly one run in seven, while 12/12 isolated runs passed. An intermittently
 // red suite teaches people to re-run instead of read, which is the one habit
 // this whole audit is about.
+//
+// FLOORED AT THE SOURCE. `Number('1500.5')` is finite and positive, and
+// `child_process` rejects a fractional `timeout` with ERR_OUT_OF_RANGE — which
+// each runner's own try/catch turns into a silent `unavailable`, so the hook
+// exits 0 having answered nothing. That regression is what `remainingMs` was
+// hardened for; this value happens to pass through it today, which means the
+// property is currently held one file away by a function that has no obligation
+// to keep holding it (audit 2026-09-05 NEW-02).
 const DEFAULT_TIMEOUT_MS = (() => {
   const override = Number(process.env._CG_ANSWER_TIMEOUT_MS);
-  return Number.isFinite(override) && override > 0 ? override : 2000;
+  return Number.isFinite(override) && override >= 1 ? Math.floor(override) : 2000;
 })();
 // ~1000 tokens. A deny reason carrying more than this stops being an answer
 // and starts being a context tax.
@@ -105,11 +113,41 @@ function resolveAnswerBinary(opts) {
   return binary || null;
 }
 
-/** One spawn, one options block, one `CODE_GRAPH_INTERNAL` stamp. */
+/**
+ * One spawn, one options block, one `CODE_GRAPH_INTERNAL` stamp.
+ *
+ * The timeout is the SMALLER of this call's own budget and whatever is left of
+ * the hook process's registered budget, because the callers run these in
+ * series: post-grep-inject loops callgraph over every symbol in the pattern
+ * before falling back to show and then grep, so three 2 s answers overran a 5 s
+ * hook and Claude Code killed it — which the user sees as a hook error on their
+ * own tool call, not as a missing hint (audit 2026-09-05 JS-03). Out of budget
+ * returns a synthetic timeout the exit-code table already reads as
+ * `unavailable`, so the caller degrades to the static path exactly as it does
+ * for a real timeout.
+ *
+ * `killSignal: 'SIGKILL'`: the child we are giving up on is most often one
+ * wedged waiting on `index.lock`, and node's `timeout` sends SIGTERM and then
+ * WAITS. It reads no stdin and holds no lock file worth unwinding — the same
+ * reasoning statusline.js and doctor.js already apply (see proc-opts.js).
+ */
 function runCg(binary, args, { cwd, timeoutMs }) {
+  const budget = require('./hook-fail-open').remainingMs(timeoutMs);
+  if (budget === null) {
+    // `error` is what classifyRun reads (→ `unavailable`); `budgetExhausted` is
+    // for the one caller that loops and must not mistake this for "that symbol
+    // did not resolve" — see runShowAnswer.
+    return {
+      error: new Error('hook budget exhausted'),
+      budgetExhausted: true,
+      status: null,
+      stdout: '',
+    };
+  }
   return spawnSync(binary, args, hidden({
     cwd,
-    timeout: timeoutMs,
+    timeout: budget,
+    killSignal: 'SIGKILL',
     encoding: 'utf8',
     maxBuffer: 4 * 1024 * 1024,
     stdio: ['ignore', 'pipe', 'ignore'],
@@ -187,7 +225,13 @@ function runGrepAnswer(opts = {}) {
     // Older binaries exit 0 on no-match with NO_MATCH_PREFIX on stdout — that
     // shape resolves to 'no-hits' through isEmptyAnswer below.
     const verdict = classifyRun(res, { exitOneIsNoHits: true });
-    if (verdict !== 'ok') return { status: verdict };
+    // `reason` separates the two things `unavailable` covers. The binary failing
+    // and the binary never being given time are different facts, and the caller
+    // renders one of them to the user — "ran but failed" is simply untrue of a
+    // run that never started (audit 2026-09-05 NEW-08).
+    if (verdict !== 'ok') {
+      return { status: verdict, ...(res.budgetExhausted ? { reason: 'budget' } : {}) };
+    }
     const out = (res.stdout || '').trim();
     if (isEmptyAnswer(out)) {
       return { status: 'no-hits' };
@@ -230,6 +274,15 @@ function runShowAnswer(opts = {}) {
     for (const sym of symbols.slice(0, 3)) {
       if (typeof sym !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sym)) continue;
       const res = runCg(binary, ['show', sym], { cwd, timeoutMs });
+      // Out of hook budget is not "this symbol did not resolve". This loop
+      // `continue`s past every failure and reports `no-hits` when none of the
+      // three produced output, so without this arm an exhausted budget reached
+      // recordRecommendation as a genuine empty result — and the whole reason
+      // `no-binary` is kept distinct from `unavailable` (see this function's
+      // docs) is that the deny funnel has to tell those causes apart. Nothing
+      // later in the loop can succeed either: the budget is gone for all three
+      // (pre-ship review 2026-09-05).
+      if (res.budgetExhausted) return { status: 'unavailable', reason: 'budget' };
       // A symbol that did not resolve is SKIPPED, not fatal — exit 1 included,
       // which is why this asks for `exitOneIsNoHits: false` and then treats
       // every non-`ok` verdict the same way.
@@ -329,7 +382,13 @@ function runCallgraphAnswer(opts = {}) {
     const res = runCg(binary, ['callgraph', symbol], { cwd, timeoutMs });
     // grep-parity exit codes: 1 = symbol not found (no graph node).
     const verdict = classifyRun(res, { exitOneIsNoHits: true });
-    if (verdict !== 'ok') return { status: verdict };
+    // `reason` separates the two things `unavailable` covers. The binary failing
+    // and the binary never being given time are different facts, and the caller
+    // renders one of them to the user — "ran but failed" is simply untrue of a
+    // run that never started (audit 2026-09-05 NEW-08).
+    if (verdict !== 'ok') {
+      return { status: verdict, ...(res.budgetExhausted ? { reason: 'budget' } : {}) };
+    }
     const out = (res.stdout || '').trim();
     // Only an edge-bearing tree is marginal over the grep the model already ran.
     if (isEmptyAnswer(out) ||
@@ -346,4 +405,8 @@ function runCallgraphAnswer(opts = {}) {
 module.exports = {
   runGrepAnswer, runShowAnswer, runOverviewAnswer, runCallgraphAnswer,
   truncateAtLine, sanitizeSearchPath,
+  // Exported so the integer property can be asserted where it is ESTABLISHED.
+  // Asserting it end-to-end instead passes either way: `remainingMs` floors
+  // again downstream, so such a test cannot fail and proves nothing (NEW-02).
+  DEFAULT_TIMEOUT_MS,
 };

package/claude-plugin/scripts/doctor.js

@@ -384,17 +384,25 @@ function runDiagnostics({ checkOnly = false } = {}) {
       // suspended, so offering it as a repair would print "✅ Update check
       // complete" and count a fix that cannot happen. Say what is true and hand
       // the user the manual route.
+      const last = autoUpdateLastError(state);
       results.push({
         name: 'Auto-update',
         status: 'warn',
+        // "failed to install 5×" was the whole diagnosis until JS-02: the count
+        // without the cause, for a chain whose every explanation had already
+        // been written to a discarded stderr. A user cannot tell a missing
+        // `curl` from a full disk from a blocked CDN out of a number.
         detail: `v${state.latestVersion} failed to install ${attempts}× — auto-retry throttled to once a day. `
+          + (last ? `${last}. ` : '')
           + 'Update manually: `npm install -g @sdsrs/code-graph` (or `/plugin update code-graph-mcp`)',
       });
     } else if (state && state.updateAvailable && state.binaryUpdated === false) {
+      const last = autoUpdateLastError(state);
       results.push({
         name: 'Auto-update',
         status: 'warn',
-        detail: `plugin v${state.latestVersion}, binary download incomplete`,
+        detail: `plugin v${state.latestVersion}, binary download incomplete`
+          + (last ? ` — ${last}` : ''),
         fixId: 'update-incomplete',
       });
     } else {
@@ -530,7 +538,17 @@ function runDiagnostics({ checkOnly = false } = {}) {
       const failed = fire.results.filter(r => !r.ok).map(r => r.label).join(', ') || fire.error || 'unknown';
       results.push({ name: 'Hook firing', status: 'warn', detail: `did not fire: ${failed}` });
     }
-  } catch { /* probe failed — skip */ }
+  } catch (err) {
+    // Same stance as step 7 above, which learned it the hard way: dropping the
+    // row makes the table look complete while a check never ran, and doctor
+    // then exits 0 on a shorter all-green report. A probe that cannot run is
+    // itself a finding (audit 2026-09-05 JS-04).
+    results.push({
+      name: 'Hook firing',
+      status: 'warn',
+      detail: `probe could not run (${(err && err.message) || err}) — the registered hooks were NOT verified`,
+    });
+  }
 
   // 9. Global npm residue — the launcher's background install (or the user)
   //    may have `npm install -g`'d the shell + platform packages. Surface what
@@ -584,7 +602,16 @@ function runDiagnostics({ checkOnly = false } = {}) {
             : ` — no plugin-install marker; uninstall leaves them (remove: npm uninstall -g ${found.map((p) => p.name).join(' ')})`)),
       });
     }
-  } catch { /* probe failed — skip */ }
+  } catch (err) {
+    // Sibling of the step-8 arm above (JS-04). Here the row is conditional on
+    // `found.length`, so absence is ALREADY the normal "nothing installed"
+    // answer — which is exactly why a throw must not produce the same silence.
+    results.push({
+      name: 'Global npm packages',
+      status: 'warn',
+      detail: `probe could not run (${(err && err.message) || err}) — global npm residue was NOT checked`,
+    });
+  }
 
   return results;
 }
@@ -742,6 +769,30 @@ function buildBinaryFromSource(cmd) {
   return true;
 }
 
+/**
+ * The part of a failed child that its own output does NOT already show.
+ *
+ * The build / update / rebuild helpers all run `stdio: 'inherit'`, so a cargo
+ * error or an npm error is already on the user's terminal and repeating it here
+ * would be noise. What that stream cannot show is a child that never ran
+ * (`ENOENT` — cargo or node not on PATH) or one this process killed
+ * (`ETIMEDOUT`, `SIGTERM` — the 10-minute build budget): the inherited stream is
+ * empty and "Build failed" is then the whole explanation the user gets
+ * (audit 2026-09-05 JS-04). Returns '' when the child spoke for itself.
+ */
+function silentFailureReason(e) {
+  if (!e) return '';
+  if (e.code === 'ETIMEDOUT' || e.signal === 'SIGTERM' || e.signal === 'SIGKILL') {
+    return ' — timed out; it was still running when the budget ran out';
+  }
+  if (e.code === 'ENOENT') {
+    return ' — the command is not on PATH';
+  }
+  // A non-zero exit means the child ran and printed its own diagnosis above.
+  if (typeof e.status === 'number') return '';
+  return e.code ? ` (${e.code})` : '';
+}
+
 /** Manual recovery for a binary we could not repair — the end of every failed arm. */
 function printBinaryRecovery() {
   console.log('     Reinstall: npm install -g @sdsrs/code-graph');
@@ -846,10 +897,35 @@ function autoUpdateNoOpReason(state = readUpdateState(), env = process.env) {
   return null;
 }
 
+/**
+ * What the updater's last failed attempt actually said, if it recorded one.
+ *
+ * Every refusal in auto-update.js prints to stderr, and the main trigger path
+ * spawns it `detached` with `stdio: 'ignore'` — so on the path that matters the
+ * explanation went to /dev/null and doctor could only re-run its own checks
+ * (audit 2026-09-05 JS-02). `lastError` is that explanation, persisted.
+ *
+ * Separate from `autoUpdateNoOpReason` on purpose: that answers "why is nothing
+ * happening" (suspended / throttled / switched off) and can be null while this
+ * is set — a single failed attempt records a reason without parking anything.
+ */
+function autoUpdateLastError(state = readUpdateState()) {
+  const e = state && state.lastError;
+  if (!e || !e.message) return null;
+  const when = e.at ? new Date(e.at) : null;
+  const stamp = when && !Number.isNaN(when.getTime()) ? ` on ${when.toISOString().slice(0, 16).replace('T', ' ')} UTC` : '';
+  return `last failure${stamp}${e.stage ? ` [${e.stage}]` : ''}: ${e.message}`;
+}
+
 function reportAutoUpdateNoOp(what) {
   console.log(`  ❌ ${what}`);
   const why = autoUpdateNoOpReason();
   if (why) console.log(`     Why: ${why}.`);
+  // Printed even when `why` is null: "nothing is parked" and "the last attempt
+  // failed for reason X" are different facts, and X is the one the user can act
+  // on (a missing curl, a full disk, a blocked CDN).
+  const last = autoUpdateLastError();
+  if (last) console.log(`     ${last}`);
   console.log('     Update manually: `npm install -g @sdsrs/code-graph` (or `/plugin update code-graph-mcp`)');
 }
 
@@ -875,8 +951,8 @@ function runRepairs(results, {
           console.log('\n  Triggering binary update...');
           try {
             runAutoUpdate();
-          } catch {
-            console.log('  \u274c Update check failed — install manually');
+          } catch (e) {
+            console.log(`  \u274c Update check failed${silentFailureReason(e)} — install manually`);
             break;
           }
           // Exited 0 — which says nothing about whether the binary moved (see
@@ -908,8 +984,8 @@ function runRepairs(results, {
           buildBinary(buildCmd);
           console.log('  \u2705 Build complete');
           fixed++;
-        } catch {
-          console.log('  \u274c Build failed');
+        } catch (e) {
+          console.log(`  \u274c Build failed${silentFailureReason(e)}`);
         }
         break;
       }
@@ -926,8 +1002,8 @@ function runRepairs(results, {
             buildBinary('cargo build --release --no-default-features');
             console.log('  \u2705 Build complete');
             fixed++;
-          } catch {
-            console.log('  \u274c Build failed');
+          } catch (e) {
+            console.log(`  \u274c Build failed${silentFailureReason(e)}`);
           }
         } else {
           console.log('    Install: npm install -g @sdsrs/code-graph');
@@ -959,8 +1035,8 @@ function runRepairs(results, {
               console.log('  ❌ Build failed');
               break;
             }
-          } catch {
-            console.log('  ❌ Build failed');
+          } catch (e) {
+            console.log(`  ❌ Build failed${silentFailureReason(e)}`);
             break;
           }
         } else {
@@ -1000,8 +1076,12 @@ function runRepairs(results, {
             fs.chmodSync(binary, 0o755);
             console.log(`\n  \u2705 Fixed permissions: chmod +x ${binary}`);
             fixed++;
-          } catch {
-            console.log(`\n  \u274c Could not fix permissions: ${binary}`);
+          } catch (e) {
+            // Nothing else here speaks: `chmodSync` inherits no stream, so the
+            // errno IS the diagnosis — EPERM (not the owner), EROFS (read-only
+            // mount) and ENOENT are three different next steps for the user.
+            console.log(`\n  \u274c Could not fix permissions: ${binary}` +
+              `${e && e.code ? ` (${e.code})` : ''}`);
           }
           if (os.platform() === 'darwin') {
             console.log(`  Also try: xattr -d com.apple.quarantine "${binary}"`);
@@ -1023,8 +1103,8 @@ function runRepairs(results, {
             }));
             console.log('  \u2705 Index rebuilt');
             fixed++;
-          } catch {
-            console.log('  \u274c Index rebuild failed');
+          } catch (e) {
+            console.log(`  \u274c Index rebuild failed${silentFailureReason(e)}`);
           }
         }
         break;
@@ -1034,8 +1114,8 @@ function runRepairs(results, {
         console.log('\n  Completing auto-update...');
         try {
           runAutoUpdate();
-        } catch {
-          console.log('  \u274c Update check failed');
+        } catch (e) {
+          console.log(`  \u274c Update check failed${silentFailureReason(e)}`);
           break;
         }
         // Same as the version-mismatch arm: exit 0 is not evidence. Re-read
@@ -1208,7 +1288,7 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length, unresolved };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, classifyIntegrity, classifyHealthReport, parseHealthPayload, integrityResolved, healthRows, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, binaryBrokenResolved, autoUpdateNoOpReason };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, classifyIntegrity, classifyHealthReport, parseHealthPayload, integrityResolved, healthRows, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, binaryBrokenResolved, autoUpdateNoOpReason, autoUpdateLastError, silentFailureReason };
 
 // 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