@sdsrs/code-graph 0.123.0 → 0.125.0

package/README.md

@@ -54,19 +54,27 @@ Every design decision — from token-aware compression to node_id-based snippet
 
 ## Performance
 
-| Metric | Value |
-|--------|-------|
-| Indexing speed | **300+ files/second** (single-threaded, release build) |
-| Incremental re-index | **<250ms** no-change detection via BLAKE3 Merkle tree |
-| FTS search P50 / P99 | **<300us / <1ms** |
-| Database overhead | **~3.5MB** per 800 nodes |
-| Token savings | **5-20x fewer tokens** per code understanding task vs grep+read |
+Every row below is a line `code-graph-mcp benchmark` prints, measured on this
+repository (278 files, 5,065 nodes, 10,731 edges) with a release build. Run the
+same command on your own project — the numbers that matter are yours, and these
+scale with tree size and machine.
 
-Run `code-graph-mcp benchmark` on your own project to measure.
+| `benchmark` line | This repo, v0.123.0 |
+|--------|-------|
+| Full index | **~1.9s** (≈145 files/second, single-threaded) |
+| Incremental (noop) | **~30ms** no-change detection via BLAKE3 Merkle tree |
+| Query latency P50 / P99 | **~575us / ~1.9ms** |
+| DB size | **~21.8MB** (≈4.4MB per 1,000 nodes) |
+| Avg tokens/node | **~239** |
 
 ## Efficiency: code-graph vs Traditional Tools
 
-Real-world benchmarks comparing code-graph-mcp tools against traditional approaches (Grep + Read + Glob) on a 33-file Rust project (~537 AST nodes).
+How many TOOL CALLS each question takes, comparing code-graph-mcp against Grep
++ Read + Glob. These are call counts, not token measurements: the left column is
+the round trips the traditional approach needs before it can answer, the right
+column is the single call that answers it. Token cost follows call count only
+loosely — how much source lands in the context window depends on the files, so
+this table does not claim a token ratio.
 
 ### Tool Call Reduction
 
@@ -80,14 +88,25 @@ Real-world benchmarks comparing code-graph-mcp tools against traditional approac
 | File dependency mapping | 3-5 calls | 1 call (`module_overview` + `include_deps`) | **~75%** |
 | Similar code detection | N/A | 1 call (`get_ast_node` + `include_similar`) | **unique** |
 
-### Overall Session Efficiency
+### Session token savings
 
-| Metric | Without code-graph | With code-graph | Improvement |
-|--------|:------------------:|:---------------:|:-----------:|
-| Tool calls per navigation task | ~6 | ~1.2 | **~80% fewer** |
-| Source lines read into context | ~8,000 lines | ~400 lines (structured) | **~95% less** |
-| Navigation token cost | ~36K tokens | ~7K tokens | **~80% saved** |
-| Full session token savings | — | — | **40-60%** |
+`tests/effectiveness_bench.rs` is the only reproducible number here, and it is
+worth being precise about what it measures. For each of five navigation tasks it
+runs the real CLI on a fixture project and compares the response size in bytes
+against a **hand-set** `baseline_bytes` for the Grep+Read approach. Bytes stand
+in for tokens; the baselines are estimates committed once and held fixed, so its
+value is regression tracking over releases, not a measurement of your project.
+
+```bash
+cargo build --no-default-features
+cargo test --test effectiveness_bench --no-default-features -- --ignored --nocapture
+```
+
+On the fixture at v0.123.0 that prints `942 / 23000 = 0.04x`, and the test fails
+if the overall ratio ever exceeds 0.60. Earlier revisions of this README carried
+an "Overall Session Efficiency" table (~80% fewer calls, ~95% fewer lines read,
+40-60% session savings) whose first rows had no source at all; they are gone
+rather than dressed up.
 
 ### What code-graph Uniquely Enables
 
@@ -454,6 +473,59 @@ Uses SQLite with:
 
 Data is stored in `.code-graph/index.db` under the project root (auto-created, gitignored).
 
+## Environment variables
+
+Every `CODE_GRAPH_*` variable the code reads, in one place — the alternative was
+reading the source to find out a switch existed. All of them are optional; the
+defaults are what you get by doing nothing.
+
+**Switches you may actually want**
+
+| Variable | Effect |
+|---|---|
+| `CODE_GRAPH_NO_AUTO_UPDATE=1` | Never check GitHub for a new release. |
+| `CODE_GRAPH_NO_AUTO_ADOPT=1` | Do not write the steering block into a project's `CLAUDE.md` on SessionStart. |
+| `CODE_GRAPH_NO_TEMPLATE_REFRESH=1` | Keep hand edits to the generated steering block — it is otherwise refreshed to the current template. |
+| `CODE_GRAPH_QUIET_HOOKS=1` | Hooks inject a one-line pointer instead of the full decision table. |
+| `CODE_GRAPH_VERBOSE_HOOKS=1` | The opposite: opt into the noisy form. |
+| `CODE_GRAPH_NO_BLOCK_GREP=1` | Never turn a `grep` hint into a block — prefix a single command with it to get past one. |
+| `CODE_GRAPH_NO_INJECT=1` | No post-tool AST context injection. |
+| `CODE_GRAPH_NO_RECENT_IMPACT=1` | Skip the recent-impact section of the SessionStart briefing. |
+| `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_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. |
+| `CODE_GRAPH_RESYNC_BUDGET=<n>` | Files a read command may re-index before answering (default 8). `CODE_GRAPH_GREP_SYNC_BUDGET` is the older name, still honoured by `grep`. |
+| `CODE_GRAPH_RG_ARGV_BUDGET=<bytes>` | Cap on the argv `grep` builds for ripgrep. |
+| `CODE_GRAPH_INTEGRITY_MAX_BYTES=<bytes>` | Index size above which `health-check` skips `PRAGMA quick_check`. |
+| `CODE_GRAPH_SNAPSHOT_TRUST_URL=1` | Install a snapshot from an arbitrary URL. **A snapshot is a database — treat it like running a script.** |
+| `CODE_GRAPH_SNAPSHOT_TRUST_ORIGIN=1` | Install a snapshot whose origin does not match this repository. |
+| `CODE_GRAPH_SNAPSHOT_PIN=<digest>` | Accept exactly this snapshot digest (an alternative to the two switches above). |
+| `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). |
+
+<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>
+
+| Variable | Set by | Purpose |
+|---|---|---|
+| `CODE_GRAPH_STATUSLINE_CWD` | statusline-composite | Forwards Claude Code's authoritative cwd to each statusline provider. |
+| `CODE_GRAPH_INSTALL_LOCK_HELD` | launcher | Tells a child that the parent already holds the install lock, so it does not deadlock. |
+| `CODE_GRAPH_AUTO_UPDATE_SILENT` | session-init | Runs the update check without console output. |
+| `CODE_GRAPH_NO_ANSWER_IN_DENY` | lifecycle | Keeps `cg-answer` out of the deny path. |
+| `CODE_GRAPH_FORCE_PLUGIN_MCP` | launcher | Serve MCP even from a context that would otherwise decline. |
+| `CODE_GRAPH_FORCE_STATUSLINE` | `lifecycle install` | Reclaim the statusline slot from another provider. |
+| `CODE_GRAPH_INTERNAL` | this repo's own hooks | Marks a tool call as self-generated so it is excluded from adoption metrics. |
+| `CODE_GRAPH_DOGFOOD` | dev sessions | Tags MCP usage as dev self-test traffic. |
+| `CODE_GRAPH_DEV` | dev checkouts | Dev mode: changes binary resolution and disables auto-update. |
+| `CODE_GRAPH_EMIT_CONFIDENCE` | debugging | Emit per-result confidence from semantic search. |
+| `CODE_GRAPH_BIN` | `scripts/e2e-validate.js` | Binary under test. |
+| `CODE_GRAPH_AUTO_UPDATE_E2E=1` | release smoke test | Opts into the live auto-update E2E, skipped by default. |
+
+</details>
+
 ## Build from Source
 
 ### Prerequisites

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

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

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

@@ -7,7 +7,7 @@ const http = require('http');
 const crypto = require('crypto');
 const path = require('path');
 const os = require('os');
-const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, readJsonResult, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
+const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, readJsonResult, backupCorruptFile, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
 const { claudeHome } = require('./claude-config');
 const { clearCache: clearBinaryCache, globalNodeModulesCandidates, nvmNodeModulesDirs, PLATFORM_PKG, detectLibc } = require('./find-binary');
 const { readBinaryVersion, compareVersions, isDevMode } = require('./version-utils');
@@ -254,8 +254,71 @@ function resolveProxy(targetUrl, env = process.env) {
   return proxy && proxy.trim() ? proxy.trim() : null;
 }
 
+// Overall deadline for one metadata GET, as a multiple of the per-socket
+// inactivity budget. Deliberately looser than `timeoutMs`: that one is an
+// inactivity timer and must stay tight, while this one only has to stop a
+// request that can never finish, so a slow-but-progressing response must not
+// trip it.
+const FETCH_TOTAL_TIMEOUT_FACTOR = 4;
+
 function requestJson(url, timeoutMs = FETCH_TIMEOUT_MS) {
   return new Promise((resolve, reject) => {
+    // Every path below settles through these. `req.setTimeout` is an
+    // INACTIVITY timer that lives on the socket, so a connection dropped
+    // mid-body emitted no `end`, no request `error` and no timeout — with only
+    // `data`/`end` wired on the response the promise stayed pending forever.
+    // The per-session detached `check` then accumulated zombie node processes,
+    // and a foreground run hung the terminal (audit 2026-08-22 P1-2). The
+    // response listeners close that shape directly; the watchdog is the
+    // backstop for any other never-settles shape. Both must be single-shot —
+    // `error` after a partial body would otherwise re-settle a settled
+    // promise — and both must clear the timer so it cannot hold the event
+    // loop open past a normal response.
+    let settled = false;
+    let watchdog = null;
+    // Settling the promise is only half of it. An undestroyed request is an
+    // ACTIVE HANDLE: the caller's `await` returns while the socket stays open,
+    // the event loop has a reason to live, and the detached per-session `check`
+    // remains resident — the same zombie process, reached by the other half of
+    // the problem. Every handle that can outlive the promise registers here.
+    const handles = [];
+    const teardown = () => {
+      while (handles.length > 0) {
+        const h = handles.pop();
+        try { h.destroy(); } catch { /* already gone */ }
+      }
+    };
+    const clearWatchdog = () => {
+      if (watchdog !== null) {
+        clearTimeout(watchdog);
+        watchdog = null;
+      }
+    };
+    const settleOk = (value) => {
+      if (settled) return;
+      settled = true;
+      clearWatchdog();
+      resolve(value);
+    };
+    const settleErr = (err) => {
+      if (settled) return;
+      settled = true;
+      clearWatchdog();
+      teardown();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    };
+    watchdog = setTimeout(
+      () => settleErr(new Error('request watchdog timeout')),
+      timeoutMs * FETCH_TOTAL_TIMEOUT_FACTOR,
+    );
+    // The timer is a handle too. If `https.request` throws synchronously (a
+    // malformed URL), the executor's throw rejects the promise without ever
+    // reaching `clearWatchdog`, and the timer alone holds the process open for
+    // the whole `timeoutMs * FETCH_TOTAL_TIMEOUT_FACTOR` — 12s at the production
+    // budget. Unref'd it still fires while a request is in flight (the socket
+    // keeps the loop alive), but it can no longer be the ONLY reason to stay up.
+    watchdog.unref();
+
     const headers = {
       'Accept': 'application/vnd.github+json',
       'User-Agent': 'code-graph-auto-update/1.0',
@@ -264,12 +327,17 @@ function requestJson(url, timeoutMs = FETCH_TIMEOUT_MS) {
       let body = '';
       res.setEncoding('utf8');
       res.on('data', (chunk) => { body += chunk; });
+      // A truncated body is not a usable answer — reject rather than hand
+      // back half a JSON document. 'aborted' covers the Node versions that
+      // do not surface the drop as a response 'error'.
+      res.on('aborted', () => settleErr(new Error('response aborted before end')));
+      res.on('error', settleErr);
       res.on('end', () => {
         if (!res.statusCode) {
-          reject(new Error('missing status code'));
+          settleErr(new Error('missing status code'));
           return;
         }
-        resolve({ statusCode: res.statusCode, body });
+        settleOk({ statusCode: res.statusCode, body });
       });
     };
 
@@ -280,7 +348,7 @@ function requestJson(url, timeoutMs = FETCH_TIMEOUT_MS) {
       // CONNECT to reach parity for users behind a corporate proxy.
       let pu, target;
       try { pu = new URL(proxy); target = new URL(url); }
-      catch { reject(new Error('invalid proxy or target URL')); return; }
+      catch { settleErr(new Error('invalid proxy or target URL')); return; }
       const connectHeaders = {};
       if (pu.username) {
         const cred = `${decodeURIComponent(pu.username)}:${decodeURIComponent(pu.password)}`;
@@ -296,25 +364,31 @@ function requestJson(url, timeoutMs = FETCH_TIMEOUT_MS) {
       connectReq.on('connect', (res, socket) => {
         if (res.statusCode !== 200) {
           socket.destroy();
-          reject(new Error(`proxy CONNECT failed: ${res.statusCode}`));
+          settleErr(new Error(`proxy CONNECT failed: ${res.statusCode}`));
           return;
         }
+        // The tunnelled socket outlives connectReq, so it needs its own entry:
+        // destroying the CONNECT request does not close the tunnel under it.
+        handles.push(socket);
         const req = https.request(url, {
           method: 'GET', headers, socket, agent: false, servername: target.hostname,
         }, onResponse);
+        handles.push(req);
         req.setTimeout(timeoutMs, () => req.destroy(new Error('request timeout')));
-        req.on('error', reject);
+        req.on('error', settleErr);
         req.end();
       });
+      handles.push(connectReq);
       connectReq.setTimeout(timeoutMs, () => connectReq.destroy(new Error('proxy connect timeout')));
-      connectReq.on('error', reject);
+      connectReq.on('error', settleErr);
       connectReq.end();
       return;
     }
 
     const req = https.request(url, { method: 'GET', headers }, onResponse);
+    handles.push(req);
     req.setTimeout(timeoutMs, () => req.destroy(new Error('request timeout')));
-    req.on('error', reject);
+    req.on('error', settleErr);
     req.end();
   });
 }
@@ -711,25 +785,96 @@ async function downloadAndInstall(latest, {
     // fragile), pluginDst was never created. Advancing installPath/manifest to it anyway
     // pointed Claude Code at a nonexistent install dir while state read "up to date".
     if (pluginUpdated) {
-      // Update installed_plugins.json to point to new version
+      // Update installed_plugins.json to point to new version.
+      //
+      // Through the same three-way read the lifecycle.js site uses. The lenient
+      // `readJson` returns null for ENOENT, EACCES and unparseable alike, and
+      // the `if (installed && …)` guard below then skipped the repoint in
+      // SILENCE — while the plugin copy had landed and the manifest below is
+      // about to be advanced. Claude Code keeps launching the old install dir
+      // with state reading "up to date": the split-brain shape the binary-pin
+      // incident was made of, and one this file cannot fix by guessing at bytes
+      // it could not read. So it says so instead, which keeps `/plugin update`
+      // reachable as the manual way out.
       const installedPath = installedPluginsPath();
-      try {
-        const installed = readJson(installedPath);
+      const installedRead = readJsonResult(installedPath);
+      // Whether the registry entry is STILL pointing at the old version when this
+      // block ends. It gates the manifest advance below, and that gate is the
+      // whole difference between a report and a fix: `checkForUpdate` reads
+      // `readManifest().version` as the authoritative installed version, so
+      // advancing it past a repoint that did not happen makes the next session
+      // compute "up to date" — the message below prints ONCE, into a SessionStart
+      // hook's stderr, and the split-brain then has nothing behind it. Left
+      // behind, the ordinary check interval retries the whole install and
+      // re-reports, and the repoint lands by itself the moment the file is
+      // repaired. `missing` is not blocked: no registry means nothing to repoint.
+      let repointBlocked = false;
+      if (installedRead.corrupt) {
+        // Value unusable — the bytes are not ours to guess at.
+        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} ` +
+          `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.'
+        );
+        repointBlocked = true;
+      } else {
+        let installed = installedRead.value;
+        // `lossy` is NOT `corrupt`: the value parsed and is usable, it is the
+        // BYTES that will not survive our rewrite (a cp1252 byte inside a path,
+        // see readJsonResult). lifecycle.js's readSettingsForWrite route applies
+        // here for the same reason — preserve the true bytes, then proceed, since
+        // refusing outright strands the install over a byte we can work around.
+        // Collapsing this into the corrupt arm also misreported it: a lossy result
+        // carries no `error`, so the message called a parseable file unparseable.
+        if (installed && installedRead.lossy) {
+          const backup = backupCorruptFile(installedPath, installedRead.raw);
+          if (backup) {
+            console.error(
+              `[code-graph] ${installedPath} contains bytes that are not valid UTF-8; ` +
+              `repointing it at ${latest.version} will replace them. Saved the original ` +
+              `to ${backup} first.`
+            );
+          } else {
+            console.error(
+              `[code-graph] 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.'
+            );
+            installed = null;
+            repointBlocked = true;
+          }
+        }
         if (installed && installed.plugins && installed.plugins[PLUGIN_ID]) {
           installed.plugins[PLUGIN_ID][0].installPath = pluginDst;
           installed.plugins[PLUGIN_ID][0].version = latest.version;
           installed.plugins[PLUGIN_ID][0].lastUpdated = new Date().toISOString();
-          writeJsonAtomic(installedPath, installed);
+          try {
+            writeJsonAtomic(installedPath, installed);
+          } catch (err) {
+            console.error(
+              `[code-graph] 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`.'
+            );
+            repointBlocked = true;
+          }
         }
-      } catch { /* not fatal */ }
+      }
 
-      // Update install manifest
-      try {
-        const manifest = readManifest();
-        manifest.version = latest.version;
-        manifest.updatedAt = new Date().toISOString();
-        writeJsonAtomic(path.join(CACHE_DIR, 'install-manifest.json'), manifest);
-      } catch { /* not fatal */ }
+      // Update install manifest — only when nothing is left pointing at the old
+      // version. See `repointBlocked` above: this value IS the update gate.
+      if (!repointBlocked) {
+        try {
+          const manifest = readManifest();
+          manifest.version = latest.version;
+          manifest.updatedAt = new Date().toISOString();
+          writeJsonAtomic(path.join(CACHE_DIR, 'install-manifest.json'), manifest);
+        } catch { /* not fatal */ }
+      }
 
       // Run the NEW lifecycle.js to update settings.json hooks with new paths.
       // Without this, settings.json hooks still point to the old version directory

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

@@ -61,7 +61,14 @@ function truncateAtLine(text, maxBytes) {
   if (lastNl > 0) {
     return { text: head.slice(0, lastNl), truncated: true };
   }
-  return { text: buf.subarray(0, maxBytes).toString('latin1'), truncated: true };
+  // Hard cut, when even the first line does not fit. Back the cut off to a
+  // UTF-8 character boundary instead of re-decoding the bytes: `latin1` maps
+  // each byte to its own character, so a CJK line came back as mojibake rather
+  // than as a shortened line, and `utf8` alone would leave a U+FFFD where the
+  // cut landed mid-character. A continuation byte is `10xxxxxx`.
+  let end = maxBytes;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return { text: buf.subarray(0, end).toString('utf8'), truncated: true };
 }
 
 /**

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

@@ -159,14 +159,82 @@ function isNativeBinary(candidate) {
  * Permissive on unknown values: missing pkg version or unreadable binary
  * version → trust cache (don't refuse the only path we know about).
  */
-function isCachedBinaryFresh(cachedPath, pkgVersion) {
+function isCachedBinaryFresh(cachedPath, pkgVersion, knownVersion) {
   if (!isNativeBinary(cachedPath)) return false;
   if (!pkgVersion) return true;
-  const cacheVer = readBinaryVersion(cachedPath);
+  // `knownVersion` lets the caller skip the `--version` spawn when the cache
+  // entry already recorded it AND the file has not changed since — see
+  // `readCacheEntry`. Absent, behaviour is exactly as before.
+  const cacheVer = knownVersion || readBinaryVersion(cachedPath);
   if (!cacheVer) return true;
   return compareVersions(cacheVer, pkgVersion) >= 0;
 }
 
+/// Identity stamp for a binary file: if this is unchanged, the version we
+/// recorded for it is still its version. mtime alone would be fooled by a
+/// same-second replacement, so size rides along.
+function binaryStamp(binPath) {
+  try {
+    const st = fs.statSync(binPath);
+    return `${st.mtimeMs}:${st.size}`;
+  } catch {
+    return null;
+  }
+}
+
+/// Read the on-disk cache entry.
+///
+/// The file used to hold a bare path, so every cache HIT still spawned
+/// `code-graph-mcp --version` to check freshness — four `findBinary()` calls in
+/// one SessionStart process meant four spawns, plus one more from the
+/// consistency check. Cheap warm (2-4ms), but a cold spawn behind Windows AV
+/// has been measured above 2s in this codebase's own notes, and they run
+/// serially inside a hook's time budget (audit 2026-08-22 P2-17).
+///
+/// The entry now carries the version and a file stamp. A pre-existing bare-path
+/// file still reads (no version → verified once, then rewritten in the new
+/// shape), and an older plugin reading the new file sees a non-path string,
+/// fails `isNativeBinary`, and re-discovers — one extra walk, never a wrong
+/// answer.
+function readCacheEntry() {
+  let raw;
+  try {
+    raw = fs.readFileSync(CACHE_FILE, 'utf8').trim();
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  if (raw[0] === '{') {
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed.path === 'string' ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  return { path: raw };
+}
+
+function writeCacheEntry(binPath) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+    fs.writeFileSync(
+      CACHE_FILE,
+      JSON.stringify({
+        path: binPath,
+        version: readBinaryVersion(binPath) || null,
+        stamp: binaryStamp(binPath),
+      })
+    );
+  } catch { /* ok */ }
+}
+
+/// Per-process memo. `findBinary()` is called four times in a single
+/// session-init run; only the first should touch the disk. Only a FOUND path is
+/// memoized — a miss must stay retryable, because `launcher-install` installs
+/// the binary and looks again in the same process.
+let memoizedBinary = null;
+
 /**
  * Locate the code-graph-mcp binary using multiple strategies.
  * Results are cached to disk so repeated calls (e.g. per-hook) are fast.
@@ -183,21 +251,29 @@ function isCachedBinaryFresh(cachedPath, pkgVersion) {
  * Returns the absolute path or null if not found.
  */
 function findBinary() {
+  if (memoizedBinary) return memoizedBinary;
+
   // Try disk cache first (avoids spawning `which` on hot paths)
-  try {
-    const cached = fs.readFileSync(CACHE_FILE, 'utf8').trim();
-    if (isCachedBinaryFresh(cached, getPackageVersion())) return cached;
-    if (cached) clearCache();
-  } catch { /* no cache or stale */ }
+  const entry = readCacheEntry();
+  if (entry) {
+    // Trust the recorded version only while the FILE is the one it was recorded
+    // for; a replaced binary re-reads it.
+    const stamped = entry.stamp && entry.stamp === binaryStamp(entry.path);
+    const known = stamped ? entry.version : null;
+    if (isCachedBinaryFresh(entry.path, getPackageVersion(), known)) {
+      if (!known) writeCacheEntry(entry.path); // upgrade a bare-path / stale-stamp record
+      memoizedBinary = entry.path;
+      return memoizedBinary;
+    }
+    clearCache();
+  }
 
   const result = findBinaryUncached();
 
   // Write cache for subsequent calls
   if (isNativeBinary(result)) {
-    try {
-      fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
-      fs.writeFileSync(CACHE_FILE, result);
-    } catch { /* ok */ }
+    writeCacheEntry(result);
+    memoizedBinary = result;
   }
 
   return result;
@@ -414,6 +490,7 @@ function findBinaryUncached() {
  * findBinary() picks up the new location.
  */
 function clearCache() {
+  memoizedBinary = null; // the memo is a cache too — an update must invalidate both
   try { fs.unlinkSync(CACHE_FILE); } catch { /* ok */ }
 }
 

package/claude-plugin/scripts/lifecycle.js

@@ -702,12 +702,44 @@ function migrateOldPluginIds(settings) {
       delete settings.enabledPlugins[oldId];
       changed = true;
     }
+  }
 
-    // Clean old ID from installed_plugins.json
-    const installed = readJson(installedPluginsPath());
-    if (installed && installed.plugins && oldId in installed.plugins) {
-      delete installed.plugins[oldId];
-      writeJsonAtomic(installedPluginsPath(), installed);
+  // Clean old IDs from installed_plugins.json — Claude Code's OWN file.
+  //
+  // Read once and write once, through the same three-way read the other
+  // read-modify-write sites in this file use. The lenient `readJson` was the
+  // last caller left here, and it cannot tell "no such file" (nothing to do)
+  // from "unreadable" (say so): both came back null and were skipped in
+  // silence. The write was also the only unguarded one in install()/update() —
+  // with `~/.claude` unwritable (EACCES) and a legacy ID still present, it threw
+  // a bare stack out of both of doctor's repair arms, which is a repair tool
+  // crashing on the state it exists to repair (audit 2026-08-22 P2-10).
+  const installedRead = readJsonResult(installedPluginsPath());
+  if (installedRead.corrupt || installedRead.lossy) {
+    console.error(
+      `[code-graph] cannot read ${installedPluginsPath()} — leaving legacy plugin ` +
+      'IDs in place. Claude Code may still list an old code-graph entry.'
+    );
+  } else {
+    const installed = installedRead.value;
+    let ipChanged = false;
+    if (installed && installed.plugins) {
+      for (const oldId of OLD_PLUGIN_IDS) {
+        if (oldId in installed.plugins) {
+          delete installed.plugins[oldId];
+          ipChanged = true;
+        }
+      }
+    }
+    if (ipChanged) {
+      try {
+        writeJsonAtomic(installedPluginsPath(), installed);
+      } catch (err) {
+        console.error(
+          `[code-graph] cannot write ${installedPluginsPath()} (${err.code || err.name}) — ` +
+          'a legacy code-graph entry remains. Remove it with `/plugin uninstall`.'
+        );
+      }
     }
   }
 
@@ -1785,6 +1817,8 @@ module.exports = {
   isPluginExplicitlyDisabled, isPluginInactive, isPluginUninstalled, removeCacheResidue,
   cleanupDisabledStatusline, unadoptRegisteredProjects,
   readManifest, readJson, readJsonResult, readSettingsForWrite, writeJsonAtomic,
+  backupCorruptFile,                                                   // 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,
   removeHooksFromSettings, isOurHookEntry,

package/claude-plugin/scripts/pr-impact-comment.js

@@ -219,6 +219,60 @@ function renderMarkdown(review) {
   return lines.join('\n');
 }
 
+/// Split a stream of back-to-back JSON documents into their source texts.
+///
+/// `gh api --paginate` writes ONE document per page, concatenated with no
+/// separator (`[...][...]`), which `JSON.parse` rejects outright. The caller's
+/// catch then fell through to "no existing comment", so every CI run on a PR
+/// past 100 comments POSTed a fresh sticky comment instead of patching the one
+/// already there (audit 2026-08-22 P2-12).
+///
+/// Splits on TOP-LEVEL boundaries only, tracking string and escape state. The
+/// obvious `][` → `],[` rewrite is wrong: `][` occurs inside ordinary comment
+/// bodies (markdown reference links are literally `[text][ref]`), so that
+/// repair would corrupt the very payload it is trying to read.
+function splitJsonDocuments(text) {
+  const out = [];
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  let start = -1;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === '\\') esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') { inStr = true; continue; }
+    if (c === '[' || c === '{') {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (c === ']' || c === '}') {
+      depth--;
+      if (depth === 0 && start >= 0) {
+        out.push(text.slice(start, i + 1));
+        start = -1;
+      }
+    }
+  }
+  return out;
+}
+
+/// Flatten a paginated `gh api` array response into one array of items.
+/// A single page parses as itself; multiple pages concatenate.
+function parseGhPagedArray(stdout) {
+  const items = [];
+  for (const doc of splitJsonDocuments(String(stdout || ''))) {
+    let value;
+    try { value = JSON.parse(doc); } catch { continue; }
+    if (Array.isArray(value)) items.push(...value);
+    else items.push(value);
+  }
+  return items;
+}
+
 /// Upsert a sticky comment: find an existing comment containing MARKER and PATCH
 /// it, else POST a new one. Uses `gh api` (preinstalled on GitHub runners).
 function upsertComment(repo, prNumber, body) {
@@ -230,11 +284,9 @@ function upsertComment(repo, prNumber, body) {
   const list = gh(['api', '--paginate', `repos/${repo}/issues/${prNumber}/comments`]);
   let existingId = null;
   if (list.status === 0) {
-    try {
-      const comments = JSON.parse(list.stdout || '[]');
-      const hit = comments.find((c) => (c.body || '').includes(MARKER));
-      if (hit) existingId = hit.id;
-    } catch { /* fall through to create */ }
+    const comments = parseGhPagedArray(list.stdout);
+    const hit = comments.find((c) => c && (c.body || '').includes(MARKER));
+    if (hit) existingId = hit.id;
   }
 
   if (existingId) {
@@ -308,4 +360,7 @@ if (require.main === module) {
   main(process.argv.slice(2));
 }
 
-module.exports = { isTestPath, renderMarkdown, computeReview, upsertComment, MARKER };
+module.exports = {
+  isTestPath, renderMarkdown, computeReview, upsertComment, MARKER,
+  parseGhPagedArray, splitJsonDocuments,
+};

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

@@ -42,7 +42,7 @@ function run(stdin) {
   const registry = readRegistry();
   if (registry.length === 0) {
     // Fallback: no registry, run code-graph only
-    const cg = runProvider(codeGraphCommand(), false, stdin);
+    const cg = runProvider(codeGraphCommand(), false, stdin, 'code-graph');
     if (cg) process.stdout.write(cg);
     return;
   }
@@ -57,7 +57,7 @@ function run(stdin) {
 
   const outputs = [];
   for (const provider of sorted) {
-    const out = runProvider(provider.command, provider.needsStdin, stdin);
+    const out = runProvider(provider.command, provider.needsStdin, stdin, provider.id);
     if (out) outputs.push(out);
   }
   if (outputs.length > 0) {
@@ -65,11 +65,41 @@ function run(stdin) {
   }
 }
 
-function runProvider(command, needsStdin, stdin) {
+/// True when the command needs a shell to mean what it says.
+///
+/// Gated on the entry being `_previous`, and that gate is the whole point.
+/// `_previous` IS the user's `statusLine.command`, which Claude Code runs
+/// through a shell — so a captured pipeline is legitimate there, and a pipeline
+/// cannot run through `execFileSync` under any splitting: it produces ENOENT and
+/// a silently missing segment.
+///
+/// The other two registry classes were never shell strings. `codeGraphCommand()`
+/// composes `node "<__dirname>/statusline.js"`, and third-party entries arrive
+/// through `statusline-chain.js register`, whose only executor has ever been
+/// `execFileSync`. Handing those to a shell imposes semantics they never had,
+/// and OUR segment is the one that dies: measured, a plugin installed under a
+/// directory named `dev$work` produced `node "…/dev$work/statusline.js"`, which
+/// a shell reads as `…/dev/statusline.js` — segment gone, `catch` swallows it.
+/// Inside double quotes only `$` and a backtick break, which is why this stayed
+/// invisible until someone had one in an install path.
+///
+/// Trade-off, stated because it is a real one: through `sh -c`, the timeout's
+/// SIGKILL reaches the SHELL, not necessarily a grandchild that traps signals
+/// (the hazard the direct-exec path was hardened against). Confining the shell
+/// to `_previous` also confines that loss to the entry that cannot work without
+/// it. Windows keeps everything on the direct path — note that Claude Code
+/// itself runs statusline commands through Git Bash there, so a `_previous`
+/// pipeline works in Claude Code and still dies here; the fix is half-applied by
+/// platform, which is a gap rather than a regression (it never worked here).
+function needsShell(command, id) {
+  return id === '_previous' && process.platform !== 'win32' && SHELL_METACHARS.test(command);
+}
+
+function runProvider(command, needsStdin, stdin, id) {
   if (!command) return null;
   try {
     // Parse command into executable + args
-    const parts = parseCommand(command);
+    const parts = needsShell(command, id) ? ['/bin/sh', '-c', command] : parseCommand(command);
     if (!parts) return null;
 
     // Claude Code runs statusLine.command through a shell, so a leading `~`
@@ -77,7 +107,9 @@ function runProvider(command, needsStdin, stdin) {
     // does NOT use a shell, so we must expand `~/` ourselves on every word —
     // otherwise a `_previous` command captured verbatim throws ENOENT and gets
     // swallowed below, silently dropping the user's original statusline.
-    const argv = parts.map(expandTilde);
+    // `sh -c` does its own tilde expansion; expanding our own would corrupt the
+    // script text (`~` inside a quoted string is not a home directory).
+    const argv = needsShell(command, id) ? parts : parts.map(expandTilde);
 
     // Forward Claude Code's authoritative current dir (from the stdin payload) as
     // a plugin-scoped env var. The code-graph provider gates on it instead of its
@@ -117,17 +149,69 @@ function cwdFromStdin(stdin) {
   } catch { return null; }
 }
 
-function parseCommand(cmd) {
-  // Handle: node "/path/to/script.js"
-  const match = cmd.match(/^(\S+)\s+"([^"]+)"(.*)$/);
-  if (match) {
-    const args = [match[2]];
-    if (match[3].trim()) args.push(...match[3].trim().split(/\s+/));
-    return [match[1], ...args];
+/// Shell constructs a direct `execFileSync` cannot honour at all: pipelines,
+/// redirection, sequencing, command substitution, backgrounding.
+///
+/// Deliberately NOT here: `\\` (every Windows path has them), `~` (expandTilde
+/// handles it), and glob characters (far likelier to be a literal in a path
+/// than an intended glob in a statusline command).
+const SHELL_METACHARS = /[|&;<>()`$]/;
+
+/// Split a command line into argv the way a shell would: double quotes, single
+/// quotes, and backslash escapes of space / quote / backslash.
+///
+/// The old parser was a single regex that only understood ONE double-quoted
+/// word immediately after the executable; everything else went through
+/// `split(/\s+/)`. So a `_previous` command whose path contains a space —
+/// `"C:\Program Files\tools\line.exe"`, `node "~/My Configs/line.js"` — was
+/// torn into fragments, `execFileSync` threw ENOENT, and the catch swallowed
+/// it. The user's original statusline vanished without a word, which is exactly
+/// the case the `_previous` slot exists to protect (audit 2026-08-22 P2-9).
+///
+/// A backslash escapes only space, quote and backslash. Treating it as a
+/// general escape would eat `C:\Users\me\bin` on Windows, turning a working
+/// path into a broken one — a repair that breaks the platform it did not test.
+///
+/// Returns null for an unterminated quote: the caller then leaves the provider
+/// alone rather than exec'ing a guess.
+function tokenize(cmd) {
+  const argv = [];
+  let cur = '';
+  let has = false;
+  let quote = null; // '"' | "'" | null
+  for (let i = 0; i < cmd.length; i++) {
+    const c = cmd[i];
+    if (quote === "'") {
+      // Single quotes are literal, backslash included — POSIX rules.
+      if (c === "'") quote = null;
+      else { cur += c; has = true; }
+      continue;
+    }
+    if (c === '\\' && (cmd[i + 1] === ' ' || cmd[i + 1] === '"' || cmd[i + 1] === '\\')) {
+      cur += cmd[++i];
+      has = true;
+      continue;
+    }
+    if (quote === '"') {
+      if (c === '"') quote = null;
+      else { cur += c; has = true; }
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; has = true; continue; }
+    if (/\s/.test(c)) {
+      if (has) { argv.push(cur); cur = ''; has = false; }
+      continue;
+    }
+    cur += c;
+    has = true;
   }
-  // Handle: node /path/to/script.js
-  const parts = cmd.split(/\s+/);
-  return parts.length > 0 ? parts : null;
+  if (quote) return null; // unterminated quote — do not guess
+  if (has) argv.push(cur);
+  return argv.length > 0 ? argv : null;
+}
+
+function parseCommand(cmd) {
+  return tokenize(cmd);
 }
 
 // Expand a leading `~` / `~/` to the home directory, mirroring shell tilde
@@ -145,4 +229,4 @@ function codeGraphCommand() {
   return `node "${path.join(__dirname, 'statusline.js')}"`;
 }
 
-module.exports = { run, runProvider, parseCommand, expandTilde, cwdFromStdin };
+module.exports = { run, runProvider, parseCommand, tokenize, needsShell, expandTilde, cwdFromStdin };

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