@sdsrs/code-graph 0.135.0 → 0.137.0

package/README.md

@@ -536,6 +536,7 @@ defaults are what you get by doing nothing.
 | `CODE_GRAPH_HOOK_INDEX=on\|off` | Force the incremental-index hook on or off instead of letting it decide. |
 | `CODE_GRAPH_MODEL_DIR=<dir>` | Load the embedding model from here (air-gapped installs). |
 | `CODE_GRAPH_DISABLE_MODEL_DOWNLOAD=1` | Never fetch the model; fail instead. |
+| `CODE_GRAPH_REQUIRE_MODEL=1` | Test-only: make the embedding tests FAIL when no model can be loaded instead of self-skipping. Set by the release gate and the cache-warm cron, which supply pinned weights — without it those tests pass by doing nothing on any runner with no cached model. |
 | `CODE_GRAPH_MAX_FILE_SIZE=<bytes>` | Skip files larger than this (default 1 MiB). |
 | `CODE_GRAPH_MAX_CODE_LEN=<bytes>` | Truncate stored per-node source at this length. |
 | `CODE_GRAPH_PARSE_TIMEOUT_MS=<ms>` | Per-file parse timeout. |

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.135.0",
+  "version": "0.137.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.
@@ -217,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' };
@@ -268,7 +282,7 @@ function runShowAnswer(opts = {}) {
       // 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' };
+      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.
@@ -322,7 +336,13 @@ function runOverviewAnswer(opts = {}) {
     // green against it.
     const verdict = classifyRun(res, { exitOneIsNoHits: false });
     if (verdict !== 'ok') {
-      return { status: verdict };
+      // Same arm as the three sibling runners: an exhausted hook budget reaches
+      // `classifyRun` as a synthetic timeout, so without this it is reported as
+      // a bare `unavailable` — indistinguishable from a wedged or broken binary.
+      // This runner is the read-fanout hint's only answer path, and its budget is
+      // the one most often already spent (pre-read runs after a SessionStart that
+      // already burned six children), so it is the worst place to lose the cause.
+      return { status: verdict, ...(res.budgetExhausted ? { reason: 'budget' } : {}) };
     }
     const out = (res.stdout || '').trim();
     if (isEmptyAnswer(out)) return { status: 'no-hits' };
@@ -368,7 +388,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) ||
@@ -385,4 +411,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

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

@@ -12,6 +12,27 @@ const PLATFORM = os.platform();
 const ARCH = os.arch();
 const CACHE_FILE = path.join(os.homedir(), '.cache', 'code-graph', 'binary-path');
 const BINARY_NAME = PLATFORM === 'win32' ? 'code-graph-mcp.exe' : 'code-graph-mcp';
+// PATH lookup bound (NEW-07). 2 s matches the sibling `npm root -g` probe; the
+// floor is what a budget-exhausted hook still gives it, because a `which` that
+// cannot answer in 250 ms was not going to rescue this hook anyway.
+const PATH_PROBE_TIMEOUT_MS = 2000;
+const PATH_PROBE_MIN_MS = 250;
+
+/**
+ * How long the PATH probe may run: the hook budget when one is armed, the
+ * default otherwise, never 0 and never fractional.
+ *
+ * Both edges matter. `timeout: 0` is read by node as NO TIMEOUT AT ALL — it
+ * would restore the exact unbounded call this replaced — and a fractional value
+ * makes `child_process` throw ERR_OUT_OF_RANGE, which the `catch` below would
+ * silently turn into "not on PATH" (bugfix #7's shape, in a function that runs
+ * before any hook has spent a millisecond).
+ */
+function pathProbeTimeoutMs(remaining = require('./hook-fail-open').remainingMs) {
+  const left = remaining(PATH_PROBE_TIMEOUT_MS);
+  const ms = left === null ? PATH_PROBE_MIN_MS : Math.floor(left);
+  return Math.max(ms, PATH_PROBE_MIN_MS);
+}
 const PLATFORM_PKG = `@sdsrs/code-graph-${PLATFORM}-${ARCH}`;
 
 /**
@@ -471,9 +492,28 @@ function findBinaryUncached() {
   }
 
   // --- PATH lookup (last resort for intentionally installed binaries) ---
+  //
+  // BOUNDED. This had no timeout at all, and it runs BEFORE any hook has called
+  // `remainingMs` even once — `findBinary()` is the first thing every hook does
+  // (audit 2026-09-05 NEW-07). It was called "the only unbounded child on the
+  // hook path" when it was fixed; the pre-ship review then found `ps` in
+  // `lifecycle.js`, so that was never true. Do not restore the superlative
+  // without re-deriving it. A `which` against a wedged PATH entry (a dead NFS mount, an
+  // automounter) hangs until Claude Code kills the hook, which surfaces to the
+  // user as an error on THEIR tool call.
+  //
+  // Spends the hook budget when one is armed, floored at 250 ms so the probe is
+  // always actually attempted: skipping it outright would make `findBinary`
+  // answer "no binary" for one that is on PATH, and a fabricated absence is
+  // worse than a probe that ran out of time. Outside a hook `remainingMs`
+  // returns the default, so nothing changes for doctor / statusline / the
+  // launcher.
   try {
     const which = PLATFORM === 'win32' ? 'where' : 'which';
-    const found = execFileSync(which, [BINARY_NAME], hidden({ stdio: ['pipe', 'pipe', 'pipe'] }))
+    const found = execFileSync(which, [BINARY_NAME], hidden({
+      timeout: pathProbeTimeoutMs(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }))
       .toString().trim().split('\n')[0];
     const hit = gate.consider(found);
     if (hit) return hit;
@@ -513,6 +553,7 @@ module.exports = {
   getPackageVersion, compareVersions, isCachedBinaryFresh,
   detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,
+  pathProbeTimeoutMs, PATH_PROBE_TIMEOUT_MS, PATH_PROBE_MIN_MS,
 };
 
 // Allow direct invocation for testing

package/claude-plugin/scripts/hook-fail-open.js

@@ -25,15 +25,14 @@
 // pins both registration sites to this table so a bump in one cannot drift from
 // the other.
 //
-// `session-init.js` is here for its REGISTRATION only. It is registered from
-// `claude-plugin/hooks/hooks.json` (SessionStart is the one event Claude Code
-// loads from plugin-cache), it predates `installHookFailOpen` and wraps its own
-// main in a try/catch, so nothing arms a deadline for it and none of its six
-// child spawns clamp — 15.5 s of serial timeouts against the 5 s below. That is
-// the largest overrun of the seven and it is NOT fixed here; pre-ship review
-// 2026-09-05 finding 1, carried in the audit report as NEW-05. Wiring it means
-// deciding, per child, whether an out-of-budget SessionStart should skip a
-// binary health check or a quarantine probe, which is not a mechanical change.
+// `session-init.js` is registered from `claude-plugin/hooks/hooks.json` rather
+// than by `lifecycle.js` (SessionStart is the one event Claude Code loads from
+// plugin-cache), so `hooks.test.js` pins that file to this table too. It was
+// the last unclamped hook — 21.5 s of serial children against the 5 s below,
+// the largest overrun of the seven — until audit 2026-09-05 NEW-05 wired it.
+// Its skips are not uniform: see the budget block at the top of
+// `session-init.js` for which children may be dropped silently and which two
+// report a distinct result instead of a fabricated all-clear.
 const HOOK_TIMEOUT_SECONDS = {
   'pre-edit-guide.js': 4,
   'pre-grep-guide.js': 3,
@@ -93,9 +92,17 @@ function remainingMs(defaultMs) {
   return Math.floor(Math.min(defaultMs, left));
 }
 
-/** Test seam: drop any armed deadline so one test file can't leak into another. */
-function resetHookDeadline() {
-  deadlineAt = null;
+/**
+ * Test seam: drop any armed deadline so one test file can't leak into another.
+ *
+ * `at` (an absolute epoch ms) arms one directly instead. `armHookDeadline`
+ * derives its instant from `process.uptime()`, so a test that wants the
+ * budget-EXHAUSTED branch would otherwise have to wait out a real budget — a
+ * clock race dressed up as a test. Pass `Date.now() - 1` to make every
+ * `remainingMs` return null deterministically.
+ */
+function resetHookDeadline(at = null) {
+  deadlineAt = at === null ? null : Math.floor(at);
 }
 
 function installHookFailOpen(label) {

package/claude-plugin/scripts/lifecycle.js

@@ -13,6 +13,11 @@ const OLD_PLUGIN_IDS = [
 ];
 const MARKETPLACE_NAME = 'code-graph-mcp';
 const CACHE_DIR = path.join(os.homedir(), '.cache', 'code-graph');
+// 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.
+const PS_PROBE_TIMEOUT_MS = 2000;
+const PS_PROBE_MIN_MS = 250;
 // Always derive from __dirname — CLAUDE_PLUGIN_ROOT env var can leak from other
 // plugins when hooks run in shared process context (e.g. claude-mem-lite sets it
 // to its own marketplace path, polluting all subsequent settings.json hook processes).
@@ -1647,10 +1652,19 @@ function update() {
     settingsChanged = true;
   }
 
-  // 1. Update composite command path if version changed
+  // 1. Update composite command path if version changed.
+  //
+  // Same predicate as install()'s heal arm, not a bare string comparison: an
+  // exact mismatch is NOT staleness. Two copies of this plugin (plugin cache +
+  // global npm, or a dev checkout) derive different absolute paths for the SAME
+  // current composite, so rewriting on mismatch makes each surface take the slot
+  // back from the other. install() has carried the guard since that ping-pong
+  // was diagnosed; update() kept the string test, which reopened the pair for
+  // one round on every version bump and walked straight past the
+  // `statuslineDisplaced` stand-down (audit 2026-09-05 JS-08).
   if (isOurComposite(settings)) {
     const cmd = compositeCommand();
-    if (settings.statusLine.command !== cmd) {
+    if (settings.statusLine.command !== cmd && compositeSlotIsStale(settings.statusLine.command)) {
       settings.statusLine.command = cmd;
       settingsChanged = true;
     }
@@ -1775,10 +1789,33 @@ function readActiveProcessCmdlines() {
   } catch { /* fall through to ps */ }
   try {
     const { execFileSync } = require('child_process');
+    // BOUNDED. Reached in-process from the SessionStart hook —
+    // runSessionInit -> syncLifecycleConfig -> update() ->
+    // cleanupOldCacheVersions -> here, unconditionally, on the first session
+    // after every plugin update, which is precisely the session the hook budget
+    // work targets. It carried no timeout, so a wedged `ps` (a stuck process
+    // table, a paused container) hung the hook until Claude Code killed it —
+    // which the user sees as an error on their own tool call. Found by pre-ship
+    // review 2026-09-06 after find-binary's `which` was fixed and the release
+    // notes called it "the only unbounded child a hook could reach".
+    //
+    // Spends the hook budget when one is armed, floored so the probe is always
+    // attempted.
+    //
+    // Be honest about the cost: an empty answer drops pruning back to
+    // recency-only, which is exactly the state this guard exists to escape —
+    // see cleanupOldCacheVersions, where pruning a version a live process is
+    // bound to breaks `/mcp` reconnect with MODULE_NOT_FOUND. So a timeout is a
+    // NEW route to the guard being off, not a free fallback. It is still the
+    // right trade: a `ps` slow enough to hit this is rare, and hanging the hook
+    // past its budget is a certain failure rather than a possible one.
+    const { remainingMs } = require('./hook-fail-open');
+    const budget = remainingMs(PS_PROBE_TIMEOUT_MS);
     return execFileSync('ps', ['-axww', '-o', 'command='], hidden({
+      timeout: budget === null ? PS_PROBE_MIN_MS : Math.max(budget, PS_PROBE_MIN_MS),
       encoding: 'utf8', maxBuffer: 8 * 1024 * 1024,
     })).split('\n').filter(Boolean);
-  } catch { /* unsupported platform — caller falls back to recency-only */ }
+  } catch { /* unsupported platform, or out of time — caller falls back to recency-only */ }
   return [];
 }
 

package/claude-plugin/scripts/post-grep-inject.js

@@ -316,6 +316,13 @@ function runMain() {
       ...(pattern ? { pattern } : {}),
       fallthrough: answer.status,
       reason: answer.status,
+      // Sub-divides `unavailable` without touching it: a starved hook and a
+      // wedged binary arrive under the same word and only one of them means
+      // something is broken. It cannot ride in `reason` — src/cli/usage.rs:448
+      // scores `reason:"unavailable"` as an inconclusive follow-up, so a new
+      // value there would silently re-file every budget skip as "the inline
+      // answer was insufficient". Same field pre-grep-guide.js:790 uses.
+      ...(answer.reason ? { fallthrough_reason: answer.reason } : {}),
       // Attribute the skip to the mode that burned the attempt — the LAST mode
       // tried, so a callgraph miss that fell through to grep is charged to grep,
       // matching the fallback order above. Without this the aggregator files

package/claude-plugin/scripts/pre-grep-guide.js

@@ -642,8 +642,14 @@ function buildNoHitsFyi(pattern) {
 // only (PreToolUse exit-0 stdout → debug log, never the model); the operative
 // effect at the call site is the ALLOW (no deny emitted) so the raw grep runs
 // intact instead of a static deny that would hand the model nothing.
-function buildUnavailableFyi(pattern, status) {
-  const why = status === 'no-binary' ? 'binary not found' : 'ran but failed';
+function buildUnavailableFyi(pattern, status, reason) {
+  // Three causes, not two. A hook whose budget was already spent at startup
+  // (cold node on a loaded machine — see the reserve note in cg-answer.js)
+  // deliberately runs no children at all; calling that "ran but failed" blames
+  // the binary for something it was never asked to do (audit 2026-09-05 NEW-08).
+  const why = status === 'no-binary' ? 'binary not found'
+    : reason === 'budget' ? 'no time left in the hook budget'
+      : 'ran but failed';
   return `[code-graph] FYI: \`code-graph-mcp grep "${pattern}"\` unavailable (${why}) — raw grep proceeding.`;
 }
 
@@ -777,11 +783,16 @@ function runMain() {
     // static deny (the answer never ran → status stays the default 'unavailable')
     // — that path falls through to the v0.46 static deny below.
     if (answer.status !== 'hits' && !isAnswerDisabled()) {
-      recordRecommendation(root, { hook: 'grep', action: 'hint', fallthrough: answer.status });
+      recordRecommendation(root, {
+        hook: 'grep', action: 'hint', fallthrough: answer.status,
+        // So the funnel can tell a starved hook from a broken binary; both
+        // arrive as `unavailable` and only one of them means anything is wrong.
+        ...(answer.reason ? { fallthrough_reason: answer.reason } : {}),
+      });
       process.stdout.write(
         (answer.status === 'no-hits'
           ? buildNoHitsFyi(pattern)
-          : buildUnavailableFyi(pattern, answer.status)) + '\n');
+          : buildUnavailableFyi(pattern, answer.status, answer.reason)) + '\n');
       return;
     }
 

package/claude-plugin/scripts/pre-read-guide.js

@@ -192,7 +192,15 @@ function trackReadAndMaybeHint(root, rel, now = Date.now()) {
     // 'no-binary' (delivered overview dark — binary missing) vs 'unavailable'
     // (binary ran but failed/timed out) vs 'no-hits'. Mirrors pre-grep-guide
     // so the read-fanout funnel can tell a dark flagship apart from no result.
+    //
+    // `fallthrough_reason` sub-divides 'unavailable' rather than replacing it:
+    // a spent hook budget and a wedged binary are the same word here, and only
+    // the former is the healthy-hook-answers-nothing case NEW-08 traded a kill
+    // for. It cannot go in `reason` — src/cli/usage.rs:448 scores
+    // `reason:"unavailable"` as an inconclusive follow-up, so a new value there
+    // would re-file every budget skip as "the answer was insufficient".
     ...(answered ? {} : { reason: answer.status }),
+    ...(answered || !answer.reason ? {} : { fallthrough_reason: answer.reason }),
   });
   // Compound-grep sibling sweep: emit via the PreToolUse allow+additionalContext
   // envelope (shared hook-emit.js). Bare stdout on a PreToolUse exit-0 lands in

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

@@ -12,11 +12,47 @@ const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-util
 const { maybeAutoAdopt, isAdopted, unadopt } = require('./adopt');
 const { isNonProjectCwd } = require('./project-detect');
 const { hidden } = require('./proc-opts');
+const { installHookFailOpen, remainingMs } = require('./hook-fail-open');
 // Module scope on purpose: `detectHookDark` reads it inside a try/catch that
 // treats any throw as "nothing to conclude", so a lazy require in there would
 // turn a resolution failure into a silent disable (pre-tag review, JS-08).
 const { resolveProjectRoot } = require('./project-root');
 
+// ── SessionStart budget (audit 2026-09-05 NEW-05) ─────────────────────────
+//
+// Claude Code kills this hook at 5 s (`HOOK_TIMEOUT_SECONDS['session-init.js']`,
+// mirrored by hooks.json). Its blocking children were each sized alone and run
+// in SERIES: the darwin quarantine probe 3 s, `git log` 2 s, `health-check` 3 s,
+// `map --compact` 5 s, `git status` 1 s, `git diff` 1 s, `affected` 1.5 s and
+// `readBinaryVersion` 5 s — 21.5 s worst case. Nothing enforced the sum, so a
+// binary wedged on `index.lock` got the hook killed and took the SessionStart
+// output the user had already earned with it. JS-03 fixed the other six hooks;
+// this one was left because clamping it is a per-child decision, not a
+// mechanical edit.
+//
+// Every blocking child now spends `budgetFor(...)`, which returns null when the
+// budget is gone — meaning SKIP, never "run unbounded" (node reads `timeout: 0`
+// as no timeout at all).
+//
+// Two skips would otherwise fabricate a POSITIVE result, so they get their own
+// answer rather than folding into an existing bucket — the mistake NEW-09 fixed
+// in cg-answer, where "budget exhausted" arrived as `no-hits`:
+//   * a skipped freshness probe reports 'unknown', NOT 'fresh';
+//   * a skipped Gatekeeper probe reports `quarantine-probe-skipped`, NOT a
+//     silent "the binary runs".
+// The rest degrade to "nothing injected", which is a state they already reach
+// for ordinary reasons (no index, clean tree) and which claims nothing untrue.
+// `budgetSkipped` in the return value names whichever ones actually skipped, so
+// a starved SessionStart is legible to `doctor` and to tests instead of just
+// being quieter than usual.
+let budgetSkips = [];
+
+function budgetFor(label, defaultMs) {
+  const ms = remainingMs(defaultMs);
+  if (ms === null) budgetSkips.push(label);
+  return ms;
+}
+
 // v0.17.0 — quietHooks: unconditional quiet 默认。
 // 项目地图与 MEMORY.md plugin contract + on-demand `project_map` 工具高度重叠，
 // 默认每次 SessionStart 都注入 ≈2.3 KB 是不必要的常驻上下文成本。
@@ -344,13 +380,19 @@ function syncLifecycleConfig() {
  * project where the MCP server isn't running, nothing else nudges a rebuild.
  * health-check carries the verdict in `index_version_stale`. Best-effort: any
  * failure → false (never force work off a bad probe).
+ *
+ * Returns true | false | null, where null means the SessionStart budget ran out
+ * before the probe could run. `false` says "asked, not stale"; conflating the
+ * two would let the caller report a freshness it never established.
  */
 function indexNeedsRevalidation(bin, cwd) {
+  const budget = budgetFor('health-check', 3000);
+  if (budget === null) return null;
   try {
     let out;
     try {
       out = execFileSync(bin, ['health-check', '--format', 'json'],
-        hidden({ cwd, timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] })).toString();
+        hidden({ cwd, timeout: budget, stdio: ['pipe', 'pipe', 'pipe'] })).toString();
     } catch (e) {
       // health-check exits non-zero on an unhealthy index but still writes JSON.
       out = ((e && e.stdout) || '').toString();
@@ -370,7 +412,10 @@ function indexNeedsRevalidation(bin, cwd) {
  *   1. git HEAD newer than index.db mtime — content drifted since last index.
  *   2. INDEX_VERSION mismatch (post-upgrade) — see indexNeedsRevalidation.
  *
- * Returns 'fresh' | 'refreshing' | 'skipped'.
+ * Returns 'fresh' | 'refreshing' | 'skipped' | 'unknown', where 'unknown' means
+ * the SessionStart budget ran out before either trigger could be evaluated —
+ * distinct from 'fresh' (both triggers asked and neither fired) and from
+ * 'skipped' (no binary / no index, so there was nothing to ask).
  */
 function ensureIndexFresh() {
   const { findBinary } = require('./find-binary');
@@ -387,19 +432,33 @@ function ensureIndexFresh() {
   if (!fs.existsSync(dbPath)) return 'skipped';
 
   let needsRefresh = false;
+  let unprobed = false;
   // Trigger 1: git HEAD newer than index mtime.
-  try {
-    const dbMtime = fs.statSync(dbPath).mtimeMs;
-    const gitTs = parseInt(
-      execSync('git log -1 --format=%ct', hidden({ cwd, timeout: 2000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })).trim()
-    ) * 1000;
-    if (gitTs > dbMtime) needsRefresh = true;
-  } catch { /* no git / not a repo — fall through to the version probe */ }
+  const gitBudget = budgetFor('git-log', 2000);
+  if (gitBudget === null) {
+    unprobed = true;
+  } else {
+    try {
+      const dbMtime = fs.statSync(dbPath).mtimeMs;
+      const gitTs = parseInt(
+        execSync('git log -1 --format=%ct', hidden({ cwd, timeout: gitBudget, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })).trim()
+      ) * 1000;
+      if (gitTs > dbMtime) needsRefresh = true;
+    } catch { /* no git / not a repo — fall through to the version probe */ }
+  }
 
   // Trigger 2: INDEX_VERSION mismatch (only probe when mtime looked fresh).
-  if (!needsRefresh && indexNeedsRevalidation(bin, cwd)) needsRefresh = true;
+  if (!needsRefresh) {
+    const stale = indexNeedsRevalidation(bin, cwd);
+    if (stale === true) needsRefresh = true;
+    else if (stale === null) unprobed = true;
+  }
 
-  if (!needsRefresh) return 'fresh';
+  // No trigger fired. Whether that means "fresh" depends on whether anything
+  // was actually asked: with a spent budget this is a claim about an index
+  // nothing looked at, and 'fresh' is the one answer that would stop a caller
+  // from looking again.
+  if (!needsRefresh) return unprobed ? 'unknown' : 'fresh';
 
   const child = spawn(bin, ['incremental-index', '--quiet'], hidden({
     cwd,
@@ -463,8 +522,17 @@ function verifyBinary() {
 
   // On macOS, verify the binary can actually run (Gatekeeper may block it)
   if (process.platform === 'darwin') {
+    const budget = budgetFor('quarantine-probe', 3000);
+    if (budget === null) {
+      // Out of budget before the probe. The binary exists and is executable, so
+      // `available: false` here would be a false alarm that sends the user to
+      // `xattr -d` for nothing. But "it actually runs" is precisely what the
+      // probe establishes and we did not establish it — so say which half is
+      // unverified instead of returning the clean shape.
+      return { available: true, binary, issue: 'quarantine-probe-skipped' };
+    }
     try {
-      execFileSync(binary, ['--version'], hidden({ timeout: 3000, stdio: 'pipe' }));
+      execFileSync(binary, ['--version'], hidden({ timeout: budget, stdio: 'pipe' }));
     } catch (err) {
       const msg = (err.message || '') + (err.stderr ? err.stderr.toString() : '');
       if (msg.includes('quarantine') || msg.includes('not permitted') ||
@@ -499,7 +567,15 @@ function consistencyCheck(binary) {
   // Check 1: Binary version vs plugin version
   try {
     const pluginVersion = getPluginVersion();
-    const binaryVersion = readBinaryVersion(binary);
+    // The last child of the hook and the most expensive one (5s of its own
+    // against a 5s total). Skipping folds into `binaryVersion === null`, which
+    // this check already treats as "no comparison to make" — it only ever
+    // reports a MISMATCH, so a skip suppresses a warning rather than inventing
+    // an all-clear.
+    const versionBudget = budgetFor('binary-version', 5000);
+    const binaryVersion = versionBudget === null
+      ? null
+      : readBinaryVersion(binary, { timeoutMs: versionBudget });
     if (binaryVersion && binaryVersion !== pluginVersion) {
       issues.push({
         id: 'version-mismatch',
@@ -565,6 +641,10 @@ function samePath(a, b) {
 }
 
 function runSessionInit({ source } = {}) {
+  // Fresh per run: this is module state, and the test suite calls this function
+  // many times in one process. A carried-over array would report last run's
+  // skips as this one's.
+  budgetSkips = [];
   // GC the shared tmp dir before anything else, so it happens even on the
   // inactive / non-project early returns below — those sessions still wrote
   // cooldown flags on the way in. Cheap (one readdir + a stat per entry) and
@@ -775,6 +855,10 @@ function runSessionInit({ source } = {}) {
     autoUpdateLaunched, indexFreshness, mapInjected, recentImpactInjected, binaryCheck, consistencyIssues,
     quietHooks, adopted, autoAdopted: autoAdopt.attempted,
     hookFireWarn: !!hookFireWarn, hookDarkWarn: !!hookDarkWarn,
+    // Which children the 5s budget cut, in the order they were reached. Empty
+    // on every healthy run; non-empty is the only signal that this SessionStart
+    // did less than it looks like it did.
+    budgetSkipped: budgetSkips.slice(),
   };
 }
 
@@ -797,9 +881,15 @@ function injectProjectMap() {
     const bin = findBinary();
     if (!bin) return false;
 
+    // Skipping here degrades to "nothing injected", the same state a project
+    // with no index reaches — no false claim, just less context. Safe to fold
+    // (unlike the freshness/quarantine probes) because this dump is opt-in,
+    // off by default, and duplicates MEMORY.md plus the on-demand tool.
+    const mapBudget = budgetFor('map', 5000);
+    if (mapBudget === null) return false;
     const output = execFileSync(bin, ['map', '--compact'], hidden({
       cwd,
-      timeout: 5000,
+      timeout: mapBudget,
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
       // Hook-internal delivery, not a model conversion — keep record_cli_use from
@@ -846,16 +936,28 @@ function injectRecentImpact({ source } = {}) {
     // last commit. Timeouts tightened (finding #1): worst-case cap sum is now
     // status(1s) + HEAD~1(1s) + affected(1.5s) = 3.5s, comfortably under the 5s
     // SessionStart hook budget; the old 2+2+3=7s could get the whole hook killed.
-    const gitOpts = hidden({ cwd: sessionDir, timeout: 1000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    // Each git call re-reads the budget and builds its own opts rather than
+    // sharing one object: the fallback `git diff` runs AFTER `git status` has
+    // already spent wall clock, so a timeout computed once would let the pair
+    // overshoot by up to its own value. `hidden(...)` stays inline at both call
+    // sites — windows-hide.test.js follows a `const x = hidden(...)` binding but
+    // not one returned from a helper, and that guard is right to be that strict.
     let changed = [];
     let isWip = false;
     try {
+      const statusMs = budgetFor('git-status', 1000);
+      if (statusMs === null) return false;
       changed = filterSourceFiles(parseGitStatusPaths(
-        execSync('git status --porcelain --untracked-files=all', gitOpts)));
+        execSync('git status --porcelain --untracked-files=all',
+          hidden({ cwd: sessionDir, timeout: statusMs, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }))));
       isWip = changed.length > 0;
       // Clean tree → fall back to what the last commit touched.
       if (!isWip) {
-        changed = filterSourceFiles(execSync('git diff --name-only HEAD~1 HEAD', gitOpts));
+        const diffMs = budgetFor('git-diff', 1000);
+        if (diffMs === null) return false;
+        changed = filterSourceFiles(
+          execSync('git diff --name-only HEAD~1 HEAD',
+            hidden({ cwd: sessionDir, timeout: diffMs, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })));
       }
     } catch {
       return false; // not a git repo / no commits — nothing to diff
@@ -870,10 +972,13 @@ function injectRecentImpact({ source } = {}) {
     const bin = findBinary();
     if (!bin) return false;
 
+    const affectedBudget = budgetFor('affected', 1500);
+    if (affectedBudget === null) return false;
+
     let affected;
     try {
       const raw = execFileSync(bin, ['affected', ...changed, '--json'], hidden({
-        cwd, timeout: 1500, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+        cwd, timeout: affectedBudget, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
         env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
       }));
       affected = JSON.parse(raw);
@@ -998,6 +1103,12 @@ module.exports = {
 };
 
 if (require.main === module) {
+  // Arms the 5s deadline every `budgetFor` above spends against, and adds the
+  // async-throw coverage the try/catch below cannot reach (a rejected promise
+  // from a spawn or a read). Only here, never on `require`: the test suite
+  // calls `runSessionInit` in-process, where an armed deadline from a foreign
+  // argv[1] would clamp children against a budget nobody granted.
+  installHookFailOpen('SessionStart');
   // SessionStart passes {source:"startup"|"clear"|"compact"|"resume"} on stdin.
   // Best-effort + TTY-guarded: a hook gets piped JSON (EOF closes it), but a
   // manual `node session-init.js` in a terminal must not block on fd 0.

package/claude-plugin/scripts/version-utils.js

@@ -12,12 +12,17 @@ const { hidden } = require('./proc-opts');
 // rejected by the same parse: a self-sustaining loop.
 const VERSION_OUTPUT_RE = /^code-graph-mcp\s+v?(\d+\.\d+\.\d+)/m;
 
-function readBinaryVersion(binaryPath) {
+function readBinaryVersion(binaryPath, { timeoutMs = 5000 } = {}) {
   try {
     const out = execFileSync(binaryPath, ['--version'], hidden({
-      // 5s: a cold exec of a freshly-written ~40MB binary (page-in, Windows AV
-      // scan) regularly exceeded the old 2s, misclassifying a good binary.
-      timeout: 5000,
+      // 5s default: a cold exec of a freshly-written ~40MB binary (page-in,
+      // Windows AV scan) regularly exceeded the old 2s, misclassifying a good
+      // binary. `timeoutMs` exists for callers running inside a hook budget —
+      // session-init spends what is LEFT of its 5s SessionStart allowance here,
+      // which is otherwise the single largest unclamped child in that hook
+      // (audit 2026-09-05 NEW-05). Must be an integer: `child_process`
+      // validates it and throws ERR_OUT_OF_RANGE on a fraction.
+      timeout: timeoutMs,
       stdio: ['pipe', 'pipe', 'pipe'],
     })).toString().trim();
     const match = out.match(VERSION_OUTPUT_RE);

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