@sdsrs/code-graph 0.129.0 → 0.130.0

package/README.md

@@ -520,6 +520,41 @@ defaults are what you get by doing nothing.
 | `CODE_GRAPH_PROJECT_TYPE=<type>` | Override project-type detection for the steering block. |
 | `CODE_GRAPH_FAIL_ON_RISK=1` | Make the PR impact comment fail the check on HIGH risk (CI). |
 
+### Sharing the statusline with another plugin
+
+code-graph claims Claude Code's single `statusLine` slot and runs a **composite**
+that calls each registered provider in turn, so other plugins keep their segment
+instead of losing the slot. Whatever occupied it at install time is captured
+automatically as the `_previous` provider and restored on uninstall.
+
+A third-party plugin registers itself through the shipped CLI:
+
+```bash
+# Resolve the script through the installed package. NOT $CLAUDE_PLUGIN_ROOT:
+# Claude Code sets that per-plugin, so inside YOUR hook it points at YOUR
+# plugin's root, and in a plain shell it is unset.
+CG="$(npm root -g)/@sdsrs/code-graph/claude-plugin/scripts/statusline-chain.js"
+
+# <id> is a stable name (your plugin's, not a version); <command> is a shell
+# command that prints ONE line. Add --stdin if it expects Claude Code's status
+# JSON on stdin.
+node "$CG" register gsd "node /path/to/gsd-status.js" --stdin
+node "$CG" list
+node "$CG" unregister gsd
+```
+
+| Detail | Value |
+|---|---|
+| Registry (working copy) | `~/.cache/code-graph/statusline-registry.json` |
+| Durable mirror | `~/.claude/statusline-providers.json` — survives a cache wipe |
+| Reserved ids | `code-graph`, `_previous` |
+| Exit codes | `0` registered / unregistered / listed / already in that state · `1` usage · `2` reserved id, or a registry file that exists and cannot be read |
+
+Exit 2 on an unreadable registry is deliberate: the mutation refuses rather than
+rebuilding, because that file holds the user's previous statusline and other
+plugins' entries. An installer that reads exit codes must not treat it as
+"registered".
+
 <details>
 <summary><b>Internal and test-only</b> — set by the plugin's own processes, or by the test suite. Setting them by hand is not supported.</summary>
 

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

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

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

@@ -1057,6 +1057,10 @@ function isBinaryHealExhausted(state) {
 // release target, silent failure (an unhealable npm env must not block or spam).
 
 const SHELL_PKG = '@sdsrs/code-graph';
+// Exported because doctor.js renders "gave up" from the same threshold. It
+// used to hardcode a literal 3 next to a comment naming this constant, so
+// raising the cap here would have left the diagnosis reporting the old one
+// (audit 2026-08-29 JS-07).
 const GLOBAL_PKG_HEAL_MAX_ATTEMPTS = 3;
 const GLOBAL_PKG_HEAL_TIMEOUT_MS = 180000; // npm resolves + downloads the platform optionalDependency (~40MB)
 
@@ -1432,7 +1436,7 @@ module.exports = {
   isUpdateSuspended,
   getExtractedPluginVersion, readBinaryVersion, promoteVerifiedBinary,
   isSilentMode, isInstallMissingMode, isForceMode, isAutoUpdateDisabled,
-  MAX_UPDATE_ATTEMPTS,
+  MAX_UPDATE_ATTEMPTS, GLOBAL_PKG_HEAL_MAX_ATTEMPTS,
   requestJson, resolveProxy, parseLatestRelease, fetchLatestRelease,
   PLUGIN_ASSET_NAME,
   downloadBinary, cachedBinaryPath, cachedBinaryNeedsUpdate, cachedBinaryStaleVsState,

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

@@ -89,6 +89,60 @@ function sanitizeSearchPath(searchPath) {
   return kept || undefined;
 }
 
+/**
+ * The four runners below each spawned the binary and mapped the result by hand
+ * — the same fifteen lines, four times (audit 2026-08-29 ARC-07). Hoisted into
+ * three pieces, with the one genuine difference between them made a PARAMETER
+ * rather than a divergence you have to notice.
+ */
+
+/** Explicit `opts.binary` → `_CG_ANSWER_BINARY` → `findBinary()`; null if none. */
+function resolveAnswerBinary(opts) {
+  let binary = opts.binary;
+  if (binary === undefined) {
+    binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
+  }
+  return binary || null;
+}
+
+/** One spawn, one options block, one `CODE_GRAPH_INTERNAL` stamp. */
+function runCg(binary, args, { cwd, timeoutMs }) {
+  return spawnSync(binary, args, hidden({
+    cwd,
+    timeout: timeoutMs,
+    encoding: 'utf8',
+    maxBuffer: 4 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    // Hook-internal run: a delivered answer, not a model-initiated conversion.
+    // The CLI skips its recommendations.jsonl `use` record when this is set.
+    env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
+  }));
+}
+
+/**
+ * The exit-code table: 0 = answered, 1 = the query found nothing, anything else
+ * (plus a spawn error or a signal) = the tool did not run.
+ *
+ * `exitOneIsNoHits` is the whole reason this is a parameter and not a constant.
+ * `grep` and `callgraph` treat exit 1 as an empty result — the v0.50
+ * grep-parity contract. `overview` does NOT: its exit 1 means "no indexed files
+ * under that path", which the read-fanout hint reports as unavailable rather
+ * than as an answered-but-empty query. That difference predates this hoist and
+ * lived in four separate copies; folding it away silently would have changed
+ * one of them.
+ */
+function classifyRun(res, { exitOneIsNoHits }) {
+  if (res.error || res.signal) return 'unavailable';
+  if (res.status === 1) return exitOneIsNoHits ? 'no-hits' : 'unavailable';
+  if (res.status !== 0) return 'unavailable';
+  return 'ok';
+}
+
+/** stdout carrying no answer: empty, or the CLI's own no-match line. */
+function isEmptyAnswer(out) {
+  return !out || out.startsWith(NO_MATCH_PREFIX);
+}
+
 /**
  * Run `code-graph-mcp grep <pattern> [searchPath]` synchronously.
  *
@@ -121,10 +175,7 @@ function runGrepAnswer(opts = {}) {
     if (!pattern || typeof pattern !== 'string' || pattern.length > MAX_PATTERN_LEN) {
       return { status: 'unavailable' };
     }
-    let binary = opts.binary;
-    if (binary === undefined) {
-      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
-    }
+    const binary = resolveAnswerBinary(opts);
     if (!binary) return { status: 'no-binary' };
 
     // Defensive re-sanitize: callers should pass a clean path, but a glob
@@ -132,30 +183,13 @@ function runGrepAnswer(opts = {}) {
     const scope = sanitizeSearchPath(searchPath);
     const args = ['grep', pattern];
     if (scope) args.push(scope);
-    const res = spawnSync(binary, args, hidden({
-      cwd,
-      timeout: timeoutMs,
-      encoding: 'utf8',
-      maxBuffer: 4 * 1024 * 1024,
-      stdio: ['ignore', 'pipe', 'ignore'],
-      // Hook-internal run: a delivered answer, not a model-initiated conversion.
-      // The CLI skips its recommendations.jsonl `use` record when this is set.
-      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
-    }));
-    if (res.error || res.signal) {
-      return { status: 'unavailable' };
-    }
-    // v0.50 grep-parity exit codes: 0 = matched, 1 = no match, 2 = error.
-    // Older binaries exit 0 on no-match with the NO_MATCH_PREFIX on stderr
-    // (stdout empty) — both shapes resolve to 'no-hits' below.
-    if (res.status === 1) {
-      return { status: 'no-hits' };
-    }
-    if (res.status !== 0) {
-      return { status: 'unavailable' };
-    }
+    const res = runCg(binary, args, { cwd, timeoutMs });
+    // 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 };
     const out = (res.stdout || '').trim();
-    if (!out || out.startsWith(NO_MATCH_PREFIX)) {
+    if (isEmptyAnswer(out)) {
       return { status: 'no-hits' };
     }
     const { text, truncated } = truncateAtLine(out, maxBytes);
@@ -189,26 +223,19 @@ function runShowAnswer(opts = {}) {
     if (!Array.isArray(symbols) || symbols.length === 0) {
       return { status: 'unavailable' };
     }
-    let binary = opts.binary;
-    if (binary === undefined) {
-      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
-    }
+    const binary = resolveAnswerBinary(opts);
     if (!binary) return { status: 'no-binary' };
 
     const parts = [];
     for (const sym of symbols.slice(0, 3)) {
       if (typeof sym !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sym)) continue;
-      const res = spawnSync(binary, ['show', sym], hidden({
-        cwd,
-        timeout: timeoutMs,
-        encoding: 'utf8',
-        maxBuffer: 4 * 1024 * 1024,
-        stdio: ['ignore', 'pipe', 'ignore'],
-        env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
-      }));
-      if (res.error || res.signal || res.status !== 0) continue;
+      const res = runCg(binary, ['show', sym], { cwd, timeoutMs });
+      // 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.
+      if (classifyRun(res, { exitOneIsNoHits: false }) !== 'ok') continue;
       const out = (res.stdout || '').trim();
-      if (!out || out.startsWith(NO_MATCH_PREFIX)) continue;
+      if (isEmptyAnswer(out)) continue;
       parts.push(`$ code-graph-mcp show ${sym}\n${out}`);
     }
     if (parts.length === 0) return { status: 'no-hits' };
@@ -241,24 +268,25 @@ function runOverviewAnswer(opts = {}) {
     if (!dir || typeof dir !== 'string' || dir.length > 300) {
       return { status: 'unavailable' };
     }
-    let binary = opts.binary;
-    if (binary === undefined) {
-      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
-    }
+    const binary = resolveAnswerBinary(opts);
     if (!binary) return { status: 'no-binary' };
-    const res = spawnSync(binary, ['overview', dir], hidden({
-      cwd,
-      timeout: timeoutMs,
-      encoding: 'utf8',
-      maxBuffer: 4 * 1024 * 1024,
-      stdio: ['ignore', 'pipe', 'ignore'],
-      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
-    }));
-    if (res.error || res.signal || res.status !== 0) {
-      return { status: 'unavailable' };
+    const res = runCg(binary, ['overview', dir], { cwd, timeoutMs });
+    // Deliberately NOT exitOneIsNoHits: `overview` exits 1 for "no indexed
+    // files under that path", and this hint reports that as unavailable. It is
+    // the one arm that differs, preserved from the pre-hoist code.
+    //
+    // The verdict is RETURNED rather than collapsed to a literal
+    // `'unavailable'`. Collapsing it reads the same on this exit path and is
+    // not: it makes the flag above decorative, so flipping it changes nothing
+    // and no test can see the difference. Measured — the first version of this
+    // hoist had exactly that shape, and the mutation that flips the flag stayed
+    // green against it.
+    const verdict = classifyRun(res, { exitOneIsNoHits: false });
+    if (verdict !== 'ok') {
+      return { status: verdict };
     }
     const out = (res.stdout || '').trim();
-    if (!out || out.startsWith(NO_MATCH_PREFIX)) return { status: 'no-hits' };
+    if (isEmptyAnswer(out)) return { status: 'no-hits' };
     const { text, truncated } = truncateAtLine(out, maxBytes);
     return { status: 'hits', text, truncated };
   } catch {
@@ -295,27 +323,16 @@ function runCallgraphAnswer(opts = {}) {
     if (typeof symbol !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(symbol)) {
       return { status: 'unavailable' };
     }
-    let binary = opts.binary;
-    if (binary === undefined) {
-      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
-    }
+    const binary = resolveAnswerBinary(opts);
     if (!binary) return { status: 'no-binary' };
 
-    const res = spawnSync(binary, ['callgraph', symbol], hidden({
-      cwd,
-      timeout: timeoutMs,
-      encoding: 'utf8',
-      maxBuffer: 4 * 1024 * 1024,
-      stdio: ['ignore', 'pipe', 'ignore'],
-      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
-    }));
-    if (res.error || res.signal) return { status: 'unavailable' };
+    const res = runCg(binary, ['callgraph', symbol], { cwd, timeoutMs });
     // grep-parity exit codes: 1 = symbol not found (no graph node).
-    if (res.status === 1) return { status: 'no-hits' };
-    if (res.status !== 0) return { status: 'unavailable' };
+    const verdict = classifyRun(res, { exitOneIsNoHits: true });
+    if (verdict !== 'ok') return { status: verdict };
     const out = (res.stdout || '').trim();
     // Only an edge-bearing tree is marginal over the grep the model already ran.
-    if (!out || out.startsWith(NO_MATCH_PREFIX) ||
+    if (isEmptyAnswer(out) ||
         !(out.includes('← called by') || out.includes('→ calls'))) {
       return { status: 'no-hits' };
     }

package/claude-plugin/scripts/doctor.js

@@ -12,7 +12,7 @@ const {
 } = require('./lifecycle');
 const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 const { hidden } = require('./proc-opts');
-const { MAX_UPDATE_ATTEMPTS, isBinaryHealExhausted } = require('./auto-update');
+const { MAX_UPDATE_ATTEMPTS, GLOBAL_PKG_HEAL_MAX_ATTEMPTS, isBinaryHealExhausted, readState } = require('./auto-update');
 
 // ── Diagnostics ───────────────────────────────────────────
 
@@ -356,9 +356,28 @@ function runDiagnostics({ checkOnly = false } = {}) {
   }
 
   // 5. Auto-update state
-  try {
-    const state = readJson(path.join(CACHE_DIR, 'update-state.json'));
+  //
+  // Read through auto-update's own `readState`, which distinguishes three
+  // outcomes: a missing file (`{}`), a readable one, and an unreadable one
+  // (`{ stateUnreadable: <code> }`). doctor used lifecycle's `readJson`, which
+  // collapses all three to `null` — so a corrupt state file, and a machine that
+  // had never checked at all, both rendered as "Auto-update ✅ up-to-date", a
+  // claim with nothing behind it (audit 2026-08-29 JS-11). The `catch` arm that
+  // was supposed to cover this could not fire: `readJson` never throws.
+  {
+    const state = readState();
     const attempts = (state && state.updateAttempts) || 0;
+    if (state && state.stateUnreadable) {
+      results.push({
+        name: 'Auto-update',
+        status: 'warn',
+        detail: `update-state.json is unreadable (${state.stateUnreadable}) — the next check `
+          + 'rewrites it, so this clears itself; until then the throttle and the '
+          + 'failed-install counter are both starting from zero.',
+      });
+    } else if (!state || Object.keys(state).length === 0) {
+      results.push({ name: 'Auto-update', status: 'ok', detail: 'no update state yet (no check has run)' });
+    } else
     if (state && state.updateAvailable && attempts >= MAX_UPDATE_ATTEMPTS) {
       // The updater has given up on this release (issue #40). Deliberately NO
       // fixId: re-running `auto-update.js check` is precisely the thing that was
@@ -381,8 +400,6 @@ function runDiagnostics({ checkOnly = false } = {}) {
     } else {
       results.push({ name: 'Auto-update', status: 'ok', detail: 'up-to-date' });
     }
-  } catch {
-    results.push({ name: 'Auto-update', status: 'ok', detail: 'no update state' });
   }
 
   // 6. Hook paths validity
@@ -548,10 +565,14 @@ function runDiagnostics({ checkOnly = false } = {}) {
     if (found.length) {
       const marker = !!readJson(GLOBAL_INSTALL_MARKER);
       // Heal-exhausted is otherwise invisible: selfHealGlobalPkgs stops after
-      // 3 failed npm runs per target version and stays silent until the next
-      // release re-arms the counter — a drifted CLI shim just sits there.
+      // GLOBAL_PKG_HEAL_MAX_ATTEMPTS failed npm runs per target version and
+      // stays silent until the next release re-arms the counter — a drifted CLI
+      // shim just sits there. The threshold is imported rather than repeated:
+      // this line used to hardcode 3 while the comment named the constant, so
+      // raising the cap in auto-update.js would have left this diagnosis
+      // reporting the old one (audit 2026-08-29 JS-07).
       const state = readJson(path.join(CACHE_DIR, 'update-state.json')) || {};
-      const healGaveUp = (state.globalPkgHealAttempts || 0) >= 3;
+      const healGaveUp = (state.globalPkgHealAttempts || 0) >= GLOBAL_PKG_HEAL_MAX_ATTEMPTS;
       results.push({
         name: 'Global npm packages',
         status: healGaveUp ? 'warn' : 'ok',
@@ -879,14 +900,12 @@ function runRepairs(results, {
           console.log('     for semantic search rebuild with `cargo build --release --features embed-model`)');
         }
         console.log(`    \u2192 ${buildCmd}`);
+        // Through the injectable helper, like the binary-broken arm below
+        // (audit 2026-08-29 ARC-02). An inline `execSync` here is not merely
+        // duplication: `execSync` is destructured at load, so a test injecting
+        // `buildBinary` leaves this arm running a REAL ten-minute cargo build.
         try {
-          const projectRoot = path.resolve(__dirname, '..', '..');
-          execSync(buildCmd, hidden({
-            cwd: projectRoot,
-            stdio: 'inherit',
-            timeout: 600000,  // embed-model (Candle) builds exceed the old 5min
-          }));
-          clearBinaryCache();
+          buildBinary(buildCmd);
           console.log('  \u2705 Build complete');
           fixed++;
         } catch {
@@ -903,13 +922,8 @@ function runRepairs(results, {
           console.log('    \u2192 cargo build --release --no-default-features');
           console.log('      (for semantic search: cargo build --release --features embed-model)');
           try {
-            const projectRoot = path.resolve(__dirname, '..', '..');
-            execSync('cargo build --release --no-default-features', hidden({
-              cwd: projectRoot,
-              stdio: 'inherit',
-              timeout: 600000,
-            }));
-            clearBinaryCache();
+            // Same injectable helper as the other two build arms (ARC-02).
+            buildBinary('cargo build --release --no-default-features');
             console.log('  \u2705 Build complete');
             fixed++;
           } catch {

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

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+// Fail-open wrapper for hook entry points (audit 2026-08-29 JS-12).
+//
+// A hook is optional housekeeping running inside somebody else's tool call. Its
+// internal operations each carry their own guards, so this is defence in depth
+// rather than a known crash — but the cost asymmetry is total: an unhandled
+// throw prints a node stack trace into the user's session and exits non-zero,
+// for work whose entire value is being unobtrusive. `session-init.js` learned
+// this in audit 2026-08-16 P1-16 and grew a try/catch; the other eight entry
+// points did not.
+//
+// A `process.on` handler rather than a try/catch around each `main()`, for two
+// reasons. Two of the entry points (`pre-edit-guide.js`, `statusline.js`) are
+// straight-line scripts with no main function to wrap, so a try/catch means
+// re-indenting the whole file — a large diff through the exact hooks that gate
+// Edit and the statusline. And a handler also covers the async escape, which is
+// the one that actually happens: a rejected promise from a spawn or a read.
+//
+// EPIPE is silent by design. It means the consumer closed the pipe — Claude
+// Code moved on, or a `| head` upstream exited. There is nobody left to tell.
+function installHookFailOpen(label) {
+  const bail = (err) => {
+    const code = (err && err.code) || (err && err.name) || 'Error';
+    if (code !== 'EPIPE') {
+      try {
+        process.stderr.write(
+          `[code-graph] ${label} hook error (${code}): ${(err && err.message) || String(err)}\n` +
+          '            The tool call continues; run `code-graph-mcp doctor` if this repeats.\n'
+        );
+      } catch { /* stderr is gone too — there is nothing further to do */ }
+    }
+    // Exit 0, not the throw's non-zero: for a PreToolUse hook a non-zero exit is
+    // a DECISION (2 = deny), so crashing must not read as a verdict.
+    //
+    // Known limit: `process.exit` does not flush a pending stdout write, so an
+    // async throw AFTER a partial decision write could truncate it mid-JSON.
+    // Every entry point here writes its decision in one final call, so the
+    // window is "threw between that write and process exit". Draining instead
+    // (setting `process.exitCode` and returning) trades that for a hang risk
+    // against the hook's own 3-10s timeout, which is the worse failure — a
+    // timeout blocks the user's tool call, a truncated write does not.
+    process.exit(0);
+  };
+  process.on('uncaughtException', bail);
+  process.on('unhandledRejection', bail);
+}
+
+module.exports = { installHookFailOpen };

package/claude-plugin/scripts/incremental-index.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('PostToolUse:Write|Edit');
+
 const { execFileSync } = require('child_process');
 const { findBinary } = require('./find-binary');
 const { hidden } = require('./proc-opts');

package/claude-plugin/scripts/lifecycle.js

@@ -139,6 +139,42 @@ function readJson(filePath) {
 // will usually fail for the same reason the read did, and that failure is the
 // point: it makes the caller refuse rather than overwrite. Returns the backup
 // path, or null when no copy could be made.
+/** How many `.corrupt-*` copies of one file to keep. */
+const MAX_CORRUPT_BACKUPS = 5;
+
+/**
+ * Delete all but the newest `MAX_CORRUPT_BACKUPS` copies of `filePath`.
+ *
+ * The copies are a safety net, and a safety net nobody ever empties is a leak:
+ * each one is a full settings.json, they are created on a path that can repeat,
+ * and nothing else deletes them (audit 2026-08-29 JS-09). Newest survive because
+ * the reason to keep any is "undo what just happened".
+ *
+ * Deliberately narrow: same directory, exactly `<basename>.corrupt-` prefixed,
+ * regular files only. It runs inside `~/.claude`, so the matcher is a prefix on
+ * a name this function itself produced, never a glob.
+ */
+function pruneCorruptBackups(filePath, keep = MAX_CORRUPT_BACKUPS) {
+  const dir = path.dirname(filePath);
+  const prefix = `${path.basename(filePath)}.corrupt-`;
+  let pruned = 0;
+  try {
+    const mine = fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.startsWith(prefix))
+      .map((e) => {
+        const full = path.join(dir, e.name);
+        // Sort by the timestamp we wrote into the NAME, not by mtime: a restore
+        // or a copy re-stamps mtime and would reorder the history.
+        return { full, name: e.name };
+      })
+      .sort((a, b) => b.name.localeCompare(a.name));
+    for (const stale of mine.slice(keep)) {
+      try { fs.unlinkSync(stale.full); pruned++; } catch { /* raced or read-only */ }
+    }
+  } catch { /* unreadable dir — the copy still succeeded, which is what matters */ }
+  return pruned;
+}
+
 function backupCorruptFile(filePath, raw) {
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
   const dest = `${filePath}.corrupt-${stamp}`;
@@ -147,6 +183,7 @@ function backupCorruptFile(filePath, raw) {
     if (Buffer.isBuffer(raw)) fs.writeFileSync(dest, raw);
     else if (typeof raw === 'string') fs.writeFileSync(dest, Buffer.from(raw, 'utf8'));
     else fs.copyFileSync(filePath, dest);
+    pruneCorruptBackups(filePath);
     return dest;
   } catch {
     return null;
@@ -1201,7 +1238,20 @@ function verifyHooksFire({ hooks, env, timeoutMs = 4000, tmpBase } = {}) {
 function install({ reclaimStatusline = false } = {}) {
   const version = getPluginVersion();
   const manifest = readManifest();
-  const { settings, backedUpTo } = readSettingsForWrite();
+  // Probe FIRST, and pay the backup only on the write path (audit 2026-08-29
+  // JS-09). `readSettingsForWrite()` with no argument takes its `.corrupt-*`
+  // copy eagerly, which is right for a caller that is certainly going to
+  // rewrite the file and wrong here: install() is idempotent and usually
+  // changes nothing. Combined with any condition that re-runs it every session
+  // — the documented `manifestUnwritable` loop is one — a settings.json with a
+  // single non-UTF-8 byte grew one timestamped copy in ~/.claude per session,
+  // unbounded, for a file nothing ever rewrote. Same reasoning as
+  // `cleanupDisabledStatusline`, which already probes.
+  const probe = readJsonResult(settingsPath());
+  const deferBackup = Boolean(probe.value && probe.lossy);
+  let { settings, backedUpTo } = deferBackup
+    ? { settings: probe.value, backedUpTo: null }
+    : readSettingsForWrite(probe);
   if (!settings) {
     // Unusable settings.json that we could not even copy aside. Bail without
     // touching it — and without stamping the manifest, so the next run retries
@@ -1303,6 +1353,22 @@ function install({ reclaimStatusline = false } = {}) {
 
   // 3. Write settings atomically if changed
   if (settingsChanged) {
+    if (deferBackup) {
+      // Now it IS a rewrite, so the deferred copy is owed. A failure to make it
+      // is the same refusal as the eager path: skipping the settings work beats
+      // destroying bytes we cannot restore.
+      const late = readSettingsForWrite(probe);
+      if (!late.settings) {
+        return {
+          version,
+          settingsChanged: false,
+          statusLineClaimed: manifest.config.statusLine,
+          hooksRegistered: false,
+          settingsUnreadable: true,
+        };
+      }
+      backedUpTo = late.backedUpTo;
+    }
     const writeErr = tryWriteSettings(settings);
     if (writeErr) {
       // Do NOT fall through to the manifest stamp. A manifest carrying the
@@ -1838,7 +1904,7 @@ module.exports = {
   cleanupDisabledStatusline, unadoptRegisteredProjects,
   reportUnadoptSweep,                                                  // exported so its three-way bucketing is testable (audit 2026-08-29 JS-06)
   readManifest, readJson, readJsonResult, readSettingsForWrite, writeJsonAtomic,
-  backupCorruptFile,                                                   // auto-update.js repoints installed_plugins.json and owes the same preserve-then-proceed route
+  backupCorruptFile, pruneCorruptBackups, MAX_CORRUPT_BACKUPS,                                                   // auto-update.js repoints installed_plugins.json and owes the same preserve-then-proceed route
   migrateOldPluginIds,                                                 // exported so its failure arms are testable (audit 2026-08-22 P2-10)
   readRegistry, readRegistryForWrite, writeRegistry,
   getPluginVersion, cleanupOldCacheVersions,
@@ -1930,6 +1996,16 @@ if (require.main === module) {
     // argument — `lifecycle.js doctor --check-onlyy` ran the full repair pass.
     // Exit code still reflects issues that remain UNRESOLVED after repair, not
     // issues found (see unresolvedCount in doctor.js).
+    //
+    // LAZY ON PURPOSE — do not hoist (audit 2026-08-29 JS-13). The plugin's JS
+    // has exactly one require cycle: auto-update → lifecycle → doctor →
+    // auto-update. Deferring this one edge to call time is the only thing that
+    // keeps the top-level graph a DAG. Hoisted, `require('./auto-update')`
+    // reaches `doctor` before auto-update has finished evaluating, so doctor
+    // sees a half-built module and dies on load — from a module nobody in that
+    // chain was even asking about. Pinned by
+    // `every_hook_module_loads_first_in_a_cold_process` in lifecycle.test.js,
+    // which loads each module first in its own process.
     const { runDoctorCli } = require('./doctor');
     process.exit(runDoctorCli(process.argv.slice(3)));
   } else if (cmd === 'verify-hooks-fire') {

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

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('PostToolUse:Bash');
+
 // PostToolUse(Bash) hook: deliver cg's AST-aware answer for a FOLDABLE grep that
 // rode inside a COMPOUND command and therefore flew past the PreToolUse deny gate
 // (`echo "..." && grep Sym tests/`, `git diff && grep ...`, `for s in …; do grep`).
@@ -22,8 +30,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const crypto = require('crypto');
-const { cgTmpDir, cwdHash } = require('./tmp-dir');
+const { cgTmpDir, cwdHash, makeCooldown } = require('./tmp-dir');
 const { recordRecommendation } = require('./recommendation-log');
 const { runGrepAnswer, runShowAnswer, runCallgraphAnswer, sanitizeSearchPath } = require('./cg-answer');
 const { emitPostToolContext } = require('./hook-emit');
@@ -213,25 +220,10 @@ function isInjectDisabled(env = process.env) {
 // Per-command cooldown, mirror of pre-grep-guide's flag pattern but with a
 // DISTINCT prefix so the two hooks never share a flag (a PreToolUse deny and a
 // PostToolUse inject for different commands must not suppress each other).
-function commandHash(cmd) {
-  return crypto.createHash('sha1').update(String(cmd)).digest('hex').slice(0, 12);
-}
-
-// Project-scoped for the same reason as pre-grep-guide's (see cwdHash in
-// tmp-dir.js): one shared tmp dir means an un-scoped flag is machine-global.
-function flagPath(cmd, cwd = process.cwd()) {
-  return path.join(cgTmpDir(), `.code-graph-postinject-${cwdHash(cwd)}-${commandHash(cmd)}`);
-}
-
-function isOnCooldown(cmd, now = Date.now(), windowMs = 60000, cwd = process.cwd()) {
-  try {
-    return now - fs.statSync(flagPath(cmd, cwd)).mtimeMs < windowMs;
-  } catch { return false; }
-}
-
-function markCooldown(cmd, cwd = process.cwd()) {
-  try { fs.writeFileSync(flagPath(cmd, cwd), ''); } catch { /* ok */ }
-}
+// Shared implementation (ARC-06). The DISTINCT prefix is the load-bearing part:
+// a PreToolUse deny and a PostToolUse inject for different commands must not
+// suppress each other.
+const { commandHash, isOnCooldown, markCooldown } = makeCooldown('postinject');
 
 // --- Main execution ---
 

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

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('PreToolUse:Edit');
+
 // PreToolUse(Edit) hook: auto-inject impact analysis when editing function definitions.
 // Only fires when:
 //   1. The old_string contains a function/method definition (signature being modified)

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

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('PreToolUse:Bash');
+
 // PreToolUse(Bash) hook: detect raw `grep`/`rg`/`ag` on the indexed source tree
 // and either BLOCK with suggestion (v0.32+) or HINT (legacy path). Closes the
 // "Bash comfort zone" leak — pre-training bias has Claude reach for `grep -rn`
@@ -38,8 +46,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const crypto = require('crypto');
-const { cgTmpDir, cwdHash } = require('./tmp-dir');
+const { cgTmpDir, cwdHash, makeCooldown } = require('./tmp-dir');
 const { recordRecommendation } = require('./recommendation-log');
 const { runGrepAnswer, runShowAnswer, sanitizeSearchPath } = require('./cg-answer');
 
@@ -523,25 +530,10 @@ function splitTopLevelSegments(cmd) {
   return out.map(s => s.trim()).filter(Boolean);
 }
 
-function commandHash(cmd) {
-  return crypto.createHash('sha1').update(cmd).digest('hex').slice(0, 12);
-}
-
-// Project-scoped: the same `grep -rn "foo" src/` in two repos is two different
-// questions and must not share one 60s cooldown (see cwdHash in tmp-dir.js).
-function flagPath(cmd, cwd = process.cwd()) {
-  return path.join(cgTmpDir(), `.code-graph-bash-${cwdHash(cwd)}-${commandHash(cmd)}`);
-}
-
-function isOnCooldown(cmd, now = Date.now(), windowMs = 60000, cwd = process.cwd()) {
-  try {
-    return now - fs.statSync(flagPath(cmd, cwd)).mtimeMs < windowMs;
-  } catch { return false; }
-}
-
-function markCooldown(cmd, cwd = process.cwd()) {
-  try { fs.writeFileSync(flagPath(cmd, cwd), ''); } catch { /* ok */ }
-}
+// One implementation of the cooldown quartet, in tmp-dir.js (ARC-02/ARC-06);
+// the `bash` prefix is what keeps this hook's flags distinct from
+// post-grep-inject's.
+const { commandHash, isOnCooldown, markCooldown } = makeCooldown('bash');
 
 function buildHint() {
   // Terse, no banner spam. Single message budget ~600 bytes.

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

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('PreToolUse:Read');
+
 // PreToolUse(Read) hook: detect read-fanout into the same source directory
 // and suggest module_overview / `code-graph-mcp overview` once. The 7d audit
 // (2026-05-12 → 2026-05-14, 141 sessions) found 16 sessions with 5+ Reads

package/claude-plugin/scripts/statusline-chain.js

@@ -61,6 +61,13 @@ function runUnregister(id) {
 }
 
 function runList() {
+  // Refuses like its siblings (pre-tag review, 2026-09-02). `readRegistry()`
+  // returns [] for an unreadable file as well as for an empty one, so `list`
+  // answered a corrupt registry with `(empty)` at exit 0 — telling an installer
+  // that nothing is registered while other plugins' entries and the user's
+  // previous statusline sit in a file we could not parse. Same defect class as
+  // JS-11 in this batch: a corrupt file rendered as a clean state.
+  bailIfRegistryUnusable('listed');
   const registry = readRegistry();
   if (registry.length === 0) {
     process.stdout.write('(empty)\n');

package/claude-plugin/scripts/statusline-composite.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('statusLine');
+
 /**
  * Composite StatusLine — combines multiple statusline providers.
  * Reads stdin (JSON context from Claude Code), pipes to the primary
@@ -36,7 +44,9 @@ function main() {
 }
 
 // Only run the statusline when invoked as a CLI; `require()` (tests) just imports helpers.
-if (require.main === module) main();
+if (require.main === module) {
+  main();
+}
 
 function run(stdin) {
   const registry = readRegistry();

package/claude-plugin/scripts/statusline.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('statusLine');
+
 const { execFileSync } = require('child_process');
 const fs = require('fs');
 const os = require('os');

package/claude-plugin/scripts/tmp-dir.js

@@ -41,6 +41,39 @@ function cwdHash(cwd) {
   return crypto.createHash('sha1').update(String(cwd)).digest('hex').slice(0, 12);
 }
 
+// The per-command cooldown quartet — commandHash / flagPath / isOnCooldown /
+// markCooldown — was written twice, near-byte-identically, in pre-grep-guide.js
+// and post-grep-inject.js (audit 2026-08-29 ARC-06). The only thing that
+// differed was the filename prefix, and a prefix is a parameter; the four
+// functions are not. They already disagreed in one place: one hashed `cmd`, the
+// other `String(cmd)`, so a non-string command threw in one hook and hashed in
+// the other. This takes the `String()` form for both.
+//
+// The prefix stays the caller's, and must stay DISTINCT per hook: a PreToolUse
+// deny and a PostToolUse inject for different commands must not suppress each
+// other. Flag paths are byte-identical to what each hook wrote before.
+//
+// pre-read-guide.js is deliberately NOT folded in: its `.code-graph-readfan-*`
+// file is a JSON state document keyed on the cwd alone, not a per-command
+// cooldown flag — same directory, different thing.
+function makeCooldown(prefix) {
+  const commandHash = (cmd) =>
+    crypto.createHash('sha1').update(String(cmd)).digest('hex').slice(0, 12);
+  // Project-scoped: the same `grep -rn "foo" src/` in two repos is two different
+  // questions and must not share one cooldown (see cwdHash above).
+  const flagPath = (cmd, cwd = process.cwd()) =>
+    path.join(cgTmpDir(), `.code-graph-${prefix}-${cwdHash(cwd)}-${commandHash(cmd)}`);
+  const isOnCooldown = (cmd, now = Date.now(), windowMs = 60000, cwd = process.cwd()) => {
+    try {
+      return now - fs.statSync(flagPath(cmd, cwd)).mtimeMs < windowMs;
+    } catch { return false; }
+  };
+  const markCooldown = (cmd, cwd = process.cwd()) => {
+    try { fs.writeFileSync(flagPath(cmd, cwd), ''); } catch { /* ok */ }
+  };
+  return { commandHash, flagPath, isOnCooldown, markCooldown };
+}
+
 // Nothing ever deleted what cgTmpDir() collects. Every cooldown flag, read-fanout
 // state file and interrupted `update-*` download stayed forever: measured 281
 // entries on a working dev box, 232 of them older than a day. They are 0-byte
@@ -86,4 +119,4 @@ function pruneCgTmp({ now = Date.now(), maxAgeMs = PRUNE_MAX_AGE_MS, dir = CG_TM
   return removed;
 }
 
-module.exports = { cgTmpDir, CG_TMP_DIR, cwdHash, pruneCgTmp, PRUNE_MAX_AGE_MS };
+module.exports = { cgTmpDir, CG_TMP_DIR, cwdHash, makeCooldown, pruneCgTmp, PRUNE_MAX_AGE_MS };

package/claude-plugin/scripts/user-prompt-context.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 'use strict';
+// FIRST statement, before this file's other requires (pre-tag review
+// 2026-09-02): the handler installed after them could not catch a throw
+// from `require('./lifecycle')` itself, which is exactly the broken-install
+// case JS-12 exists for. Guarded on `require.main` so importing this module
+// in a test does NOT install a process-wide handler that exits 0 — that
+// would swallow the test's own failures.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('UserPromptSubmit');
+
 // UserPromptSubmit hook: inject relevant code-graph RESULTS based on user's intent.
 // Strategy: PUSH structural context (not suggestions) that Grep/Read cannot provide.
 // This is a CODE INDEX — only inject structural code context (impact, overview, callgraph).

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