@sdsrs/code-graph 0.56.2 → 0.57.0

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

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

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

@@ -3,6 +3,7 @@
 const { execFileSync } = require('child_process');
 const fs = require('fs');
 const https = require('https');
+const crypto = require('crypto');
 const path = require('path');
 const os = require('os');
 const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
@@ -240,18 +241,59 @@ async function downloadBinary(latest) {
       latest.binaryUrl,
     ], { timeout: 60000, stdio: 'pipe' });
 
-    return promoteVerifiedBinary(binaryTmp, binaryDst, latest.version);
+    // Best-effort fetch of the integrity sidecar (<asset>.sha256). curl -f makes
+    // a 404 (an older release with no sidecar) fail → expectedSha stays null →
+    // promoteVerifiedBinary takes the TOFU path. Same-origin, so this guards
+    // corruption in transit, not a release-asset swap (version-exec is the
+    // backstop there).
+    let expectedSha = null;
+    const shaTmp = binaryTmp + '.sha256';
+    try {
+      execFileSync('curl', ['-sfL', '-o', shaTmp, latest.binaryUrl + '.sha256'],
+        { timeout: 30000, stdio: 'pipe' });
+      expectedSha = (fs.readFileSync(shaTmp, 'utf8').trim().split(/\s+/)[0]) || null;
+    } catch { /* no sidecar → TOFU */ } finally {
+      try { if (fs.existsSync(shaTmp)) fs.unlinkSync(shaTmp); } catch { /* ok */ }
+    }
+
+    return promoteVerifiedBinary(binaryTmp, binaryDst, latest.version, expectedSha);
   } catch (e) {
     console.error(`[code-graph] Binary download failed: ${e.message}`);
     return false;
   }
 }
 
-function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion) {
+/**
+ * Hex sha256 of a file's contents (lowercase).
+ * @param {string} filePath
+ * @returns {string}
+ */
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSha256) {
   try {
     const stat = fs.statSync(binaryTmp);
     if (stat.size <= 1_000_000) return false;
 
+    // Integrity gate BEFORE the file is made executable or run, so a corrupted
+    // or tampered download is never exec'd. The published <asset>.sha256 sidecar
+    // is same-origin, so this defends transit/CDN corruption + truncation, not a
+    // full release compromise (an attacker swapping the binary swaps the sidecar
+    // too — the version-exec check below is the backstop there). No sidecar
+    // (older release) → warn + proceed (TOFU), preserving the size + version
+    // gates. Mirrors the snapshot checksum convention (src/snapshot/install.rs).
+    if (expectedSha256) {
+      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.`);
+        return false;
+      }
+    } else {
+      console.error('[code-graph] No binary checksum sidecar found — content not verified (size + version checks still apply).');
+    }
+
     // chmod BEFORE reading the version. readBinaryVersion executes the binary
     // (`--version`), which requires the exec bit; `curl -o` writes the tmp file
     // as 0644 (no exec bit), so reading the version first fails with EACCES →

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

@@ -4,6 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 
 const {
   commandExists,
@@ -92,6 +93,41 @@ test('promoteVerifiedBinary promotes a non-executable (0644) download — curl -
   assert.equal(readBinaryVersion(dst), '1.2.3');
 });
 
+test('promoteVerifiedBinary accepts a binary matching the expected sha256', (t) => {
+  const dir = mkDir(t, 'code-graph-bin-');
+  const tmp = path.join(dir, 'code-graph-mcp.tmp');
+  const dst = path.join(dir, 'code-graph-mcp');
+  writeFakeBinary(tmp, '1.2.3');
+  const sha = crypto.createHash('sha256').update(fs.readFileSync(tmp)).digest('hex');
+  assert.equal(promoteVerifiedBinary(tmp, dst, '1.2.3', sha), true);
+  assert.equal(fs.existsSync(dst), true);
+});
+
+test('promoteVerifiedBinary rejects a binary whose sha256 mismatches the sidecar', (t) => {
+  // Tampered/corrupted download: the checksum gate runs BEFORE chmod+exec, so a
+  // mismatched binary is refused and never made executable. Platform-independent
+  // (no exec needed to reject).
+  const dir = mkDir(t, 'code-graph-bin-');
+  const tmp = path.join(dir, 'code-graph-mcp.tmp');
+  const dst = path.join(dir, 'code-graph-mcp');
+  writeFakeBinary(tmp, '1.2.3');
+  const wrongSha = 'deadbeef'.repeat(8); // 64 hex chars, deliberately wrong
+  assert.equal(promoteVerifiedBinary(tmp, dst, '1.2.3', wrongSha), false);
+  assert.equal(fs.existsSync(dst), false, 'tampered binary must not be promoted');
+  assert.equal(fs.existsSync(tmp), false, 'tmp cleaned up on rejection');
+});
+
+test('promoteVerifiedBinary proceeds without a sidecar (TOFU back-compat)', (t) => {
+  // Older releases ship no <asset>.sha256; a null expected hash must not block
+  // install (the size + version-exec gates still apply).
+  const dir = mkDir(t, 'code-graph-bin-');
+  const tmp = path.join(dir, 'code-graph-mcp.tmp');
+  const dst = path.join(dir, 'code-graph-mcp');
+  writeFakeBinary(tmp, '1.2.3');
+  assert.equal(promoteVerifiedBinary(tmp, dst, '1.2.3', null), true);
+  assert.equal(fs.existsSync(dst), true);
+});
+
 test('cachedBinaryNeedsUpdate is version-aware, not existence-only', (t) => {
   const dir = mkDir(t, 'code-graph-heal-');
   const binaryPath = path.join(dir, 'code-graph-mcp');

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

@@ -79,7 +79,12 @@ function sanitizeSearchPath(searchPath) {
  * @param {number} [opts.maxBytes]
  * @returns {{status: 'hits', text: string, truncated: boolean}
  *         | {status: 'no-hits'}
+ *         | {status: 'no-binary'}
  *         | {status: 'unavailable'}}
+ *   `no-binary` (binary not installed / not locatable) is kept distinct from
+ *   `unavailable` (runtime failure) so the deny funnel can tell "flagship
+ *   answer-in-deny is dark because the binary is missing" apart from "binary
+ *   ran, query just had no hits". Both still fall back to the static deny.
  */
 function runGrepAnswer(opts = {}) {
   const {
@@ -97,7 +102,7 @@ function runGrepAnswer(opts = {}) {
     if (binary === undefined) {
       binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
     }
-    if (!binary) return { status: 'unavailable' };
+    if (!binary) return { status: 'no-binary' };
 
     // Defensive re-sanitize: callers should pass a clean path, but a glob
     // reaching argv is a guaranteed nonzero exit (see sanitizeSearchPath).
@@ -143,6 +148,12 @@ function runGrepAnswer(opts = {}) {
  * context-flag greps: the model wants to READ the functions, so hand it the
  * functions). Same bounded/best-effort posture as runGrepAnswer; symbols that
  * fail to resolve are skipped, all-fail → no-hits (caller falls back to grep).
+ * @returns {{status: 'hits', text: string, truncated: boolean}
+ *         | {status: 'no-hits'}
+ *         | {status: 'no-binary'}
+ *         | {status: 'unavailable'}}
+ *   `no-binary` distinguishes a missing/unlocatable binary from a runtime
+ *   `unavailable`, so the deny funnel can see a dark flagship answer-in-deny.
  */
 function runShowAnswer(opts = {}) {
   const {
@@ -159,7 +170,7 @@ function runShowAnswer(opts = {}) {
     if (binary === undefined) {
       binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
     }
-    if (!binary) return { status: 'unavailable' };
+    if (!binary) return { status: 'no-binary' };
 
     const parts = [];
     for (const sym of symbols.slice(0, 3)) {
@@ -189,6 +200,12 @@ function runShowAnswer(opts = {}) {
  * v0.49 — Run `code-graph-mcp overview <dir>` for the read-fanout hint, so the
  * hint DELIVERS the module map instead of advising a tool call (hints measured
  * 0/40 transfer on 2026-06-12; delivered answers satisfied 5/5 in place).
+ * @returns {{status: 'hits', text: string, truncated: boolean}
+ *         | {status: 'no-hits'}
+ *         | {status: 'no-binary'}
+ *         | {status: 'unavailable'}}
+ *   `no-binary` distinguishes a missing/unlocatable binary from a runtime
+ *   `unavailable`, so the read-fanout funnel can see a dark delivered hint.
  */
 function runOverviewAnswer(opts = {}) {
   const {
@@ -205,7 +222,7 @@ function runOverviewAnswer(opts = {}) {
     if (binary === undefined) {
       binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
     }
-    if (!binary) return { status: 'unavailable' };
+    if (!binary) return { status: 'no-binary' };
     const res = spawnSync(binary, ['overview', dir], {
       cwd,
       timeout: timeoutMs,

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

@@ -4,7 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { runGrepAnswer, runShowAnswer, truncateAtLine } = require('./cg-answer');
+const { runGrepAnswer, runShowAnswer, runOverviewAnswer, truncateAtLine } = require('./cg-answer');
 
 // Stub "binary": a node script that reacts to its first real arg so one stub
 // covers hits / no-hits / error / timeout cases.
@@ -95,12 +95,15 @@ test('runGrepAnswer: exit >1 → unavailable', () => {
   assert.equal(r.status, 'unavailable');
 });
 
-test('runGrepAnswer: missing binary → unavailable', () => {
+test('runGrepAnswer: missing binary → no-binary (distinct from runtime unavailable)', () => {
   const r = runGrepAnswer({ cwd: stubDir, pattern: 'fts5_search', binary: null });
-  assert.equal(r.status, 'unavailable');
+  assert.equal(r.status, 'no-binary',
+    'a null binary is the flagship-dark case and must be distinguishable from a runtime failure');
 });
 
-test('runGrepAnswer: nonexistent binary path → unavailable', () => {
+test('runGrepAnswer: nonexistent binary path → unavailable (spawn failure, not no-binary)', () => {
+  // A non-null path that fails to spawn is a runtime failure, NOT a missing
+  // binary — `no-binary` is reserved for findBinary() returning falsy.
   const r = runGrepAnswer({
     cwd: stubDir, pattern: 'fts5_search', binary: path.join(stubDir, 'nope-bin'),
   });
@@ -213,3 +216,38 @@ test('runShowAnswer: failing binary → no-hits (caller falls back to grep answe
   const r = runShowAnswer({ cwd: stubDir, symbols: ['ExplodePlease'], binary: stubBinary() });
   assert.equal(r.status, 'no-hits');
 });
+
+test('runShowAnswer: missing binary → no-binary (distinct from runtime no-hits/unavailable)', () => {
+  const r = runShowAnswer({ cwd: stubDir, symbols: ['alpha_one'], binary: null });
+  assert.equal(r.status, 'no-binary');
+});
+
+// ── runOverviewAnswer (v0.49) — read-fanout delivered module map ──────
+
+test('runOverviewAnswer: hits → status hits with stdout text', () => {
+  const r = runOverviewAnswer({ cwd: stubDir, dir: 'src/storage', binary: stubBinary() });
+  assert.equal(r.status, 'hits');
+  assert.match(r.text, /args=\["overview","src\/storage"\]/);
+});
+
+test('runOverviewAnswer: CLI "No matches" → no-hits', () => {
+  const r = runOverviewAnswer({ cwd: stubDir, dir: 'NothingHere', binary: stubBinary() });
+  assert.equal(r.status, 'no-hits');
+});
+
+test('runOverviewAnswer: failing binary → unavailable', () => {
+  const r = runOverviewAnswer({ cwd: stubDir, dir: 'ExplodePlease', binary: stubBinary() });
+  assert.equal(r.status, 'unavailable');
+});
+
+test('runOverviewAnswer: missing binary → no-binary (distinct from runtime unavailable)', () => {
+  const r = runOverviewAnswer({ cwd: stubDir, dir: 'src/storage', binary: null });
+  assert.equal(r.status, 'no-binary');
+});
+
+test('runOverviewAnswer: empty/oversized dir → unavailable (never spawns)', () => {
+  assert.equal(runOverviewAnswer({ cwd: stubDir, dir: '', binary: stubBinary() }).status, 'unavailable');
+  assert.equal(
+    runOverviewAnswer({ cwd: stubDir, dir: 'a'.repeat(301), binary: stubBinary() }).status,
+    'unavailable');
+});

package/claude-plugin/scripts/doctor.js

@@ -61,6 +61,11 @@ function runDiagnostics() {
     results.push({ name: 'Schema', status: 'skip', detail: 'binary not found' });
     results.push({ name: 'Index', status: 'skip', detail: 'binary not found' });
     results.push({ name: 'Embeddings', status: 'skip', detail: 'binary not found' });
+    // The deny hooks run `code-graph-mcp grep/show/overview` inside the hook to
+    // answer in-place (the flagship conversion lever). A missing binary silently
+    // disables that — denies fall back to bare advice — so call it out here.
+    results.push({ name: 'Answer-in-deny', status: 'skip',
+      detail: 'disabled — binary not found, deny hooks fall back to static advice' });
   } else {
     let execOk = true;
     try {

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

@@ -483,7 +483,13 @@ function runMain() {
     return;
   }
 
-  if (isOnCooldown(rawCmd)) return;
+  if (isOnCooldown(rawCmd)) {
+    // Outcome proxy: a source grep re-issued within the cooldown window runs
+    // silently (no deny/hint). Record it so `stats` sees the model's grep
+    // fan-out — especially a re-grep right after cg answered the same query.
+    recordRecommendation(root, { hook: 'grep', action: 'observe' });
+    return;
+  }
 
   markCooldown(rawCmd);
 
@@ -532,6 +538,11 @@ function runMain() {
       hook: 'grep', action: 'deny', answered,
       // mode segments which answer type converts (show=bodies, grep=hits).
       ...(answered ? { mode: answeredMode } : {}),
+      // reason segments WHY an unanswered deny fell back to the static copy:
+      // 'no-binary' (flagship answer-in-deny dark — binary missing) vs
+      // 'unavailable' (binary ran but failed/timed out). Without this the two
+      // are indistinguishable in the funnel ("broken" looks like "no hits").
+      ...(answered ? {} : { reason: answer.status }),
       // tail segments compound-command denies — lets the funnel compare
       // re-issue behavior for denies that carried a tail note.
       ...(unansweredTail ? { tail: true } : {}),

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

@@ -885,6 +885,9 @@ test('e2e: denied grep with stub hits → deny JSON embeds the answer + records
     const rec = JSON.parse(recs.trim().split('\n').pop());
     assert.equal(rec.action, 'deny');
     assert.equal(rec.answered, true);
+    // An answered deny carries no failure reason — the field is reserved for
+    // the not-answered fallback so 'no-binary' vs 'unavailable' stays legible.
+    assert.equal(rec.reason, undefined);
   } finally {
     cleanupFixture(fixture, cmd);
   }
@@ -926,6 +929,9 @@ test('e2e: stub fails → static deny (v0.46 fallback) + records answered:false'
       pathE2e.join(fixture.dir, '.code-graph', 'recommendations.jsonl'), 'utf8').trim());
     assert.equal(rec.action, 'deny');
     assert.equal(rec.answered, false);
+    // A binary that ran but failed (exit 3) is a runtime 'unavailable' — the
+    // funnel must NOT confuse this with a missing-binary ('no-binary') deny.
+    assert.equal(rec.reason, 'unavailable');
   } finally {
     cleanupFixture(fixture, cmd);
   }
@@ -1045,6 +1051,59 @@ test('e2e: simple (non-compound) denied grep → no tail field in the deny recor
   }
 });
 
+test('e2e: missing binary → static deny records reason:no-binary (flagship-dark, distinct from no-hits & unavailable)', () => {
+  // The whole point of the `reason` field: a deny that fell back because the
+  // binary could not be found ('no-binary') must be distinguishable in the log
+  // from one where the binary ran but had nothing useful. We can't make
+  // findBinary() return null in-repo (dev target/release is always there), so
+  // run the child with a `--require` shim that forces it null — and DON'T set
+  // _CG_ANSWER_BINARY (it would short-circuit before findBinary()).
+  const uniq = `StubGone${Date.now()}`;
+  const fixture = e2eFixture(`process.stdout.write('unused\\n');`);
+  const shim = pathE2e.join(fixture.dir, 'no-binary-shim.js');
+  fsE2e.writeFileSync(shim, `
+const Module = require('module');
+const orig = Module.prototype.require;
+Module.prototype.require = function (id) {
+  const m = orig.apply(this, arguments);
+  if (id === './find-binary') {
+    return new Proxy(m, { get(t, p) { return p === 'findBinary' ? () => null : t[p]; } });
+  }
+  return m;
+};
+`);
+  const cmd = `grep -rn "${uniq}" src/`;
+  try {
+    const res = spawnHook(process.execPath, [pathE2e.join(__dirname, 'pre-grep-guide.js')], {
+      cwd: fixture.dir,
+      input: JSON.stringify({ tool_input: { command: cmd } }),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        // _CG_ANSWER_BINARY intentionally UNSET so the shimmed findBinary() runs.
+        _CG_ANSWER_BINARY: '',
+        NODE_OPTIONS: `--require ${shim}`,
+        CODE_GRAPH_QUIET_HOOKS: '0',
+        CODE_GRAPH_NO_BLOCK_GREP: '0',
+        CODE_GRAPH_NO_ANSWER_IN_DENY: '0',
+      },
+    });
+    assert.equal(res.status, 0);
+    const out = JSON.parse(res.stdout);
+    // Still a deny, still the static fallback copy (no embedded answer).
+    assert.equal(out.hookSpecificOutput.permissionDecision, 'deny');
+    assert.match(out.hookSpecificOutput.permissionDecisionReason, /denied by code-graph hook/);
+    const rec = JSON.parse(fsE2e.readFileSync(
+      pathE2e.join(fixture.dir, '.code-graph', 'recommendations.jsonl'), 'utf8').trim());
+    assert.equal(rec.action, 'deny');
+    assert.equal(rec.answered, false);
+    assert.equal(rec.reason, 'no-binary',
+      'a missing-binary deny must be distinguishable from an unavailable (runtime-fail) deny');
+  } finally {
+    cleanupFixture(fixture, cmd);
+  }
+});
+
 // ── v0.48 subdir-cwd dark fix: resolveProjectRoot / rebaseRelativePaths ──
 // daagu 2026-06-11: the persistent shell `cd backend/` darkened 38/40
 // head-greps for the rest of the night — gate 5 checked process.cwd() only.

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

@@ -164,14 +164,27 @@ function trackReadAndMaybeHint(root, rel, now = Date.now()) {
     fired = true;
   }
   saveState(root, state);
-  if (!fired) return false;
+  if (!fired) {
+    // Outcome proxy: a source read that didn't trip the fanout hint still ran.
+    // Record it (best-effort) so `stats` can measure the model's read fan-out —
+    // e.g. a read right after cg answered a grep in-place (search-decay).
+    recordRecommendation(root, { hook: 'read', action: 'observe' });
+    return false;
+  }
 
   let answer = { status: 'unavailable' };
   if (!isAnswerDisabled()) {
     answer = runOverviewAnswer({ cwd: root, dir });
   }
   const answered = answer.status === 'hits';
-  recordRecommendation(root, { hook: 'read', action: 'hint', answered });
+  recordRecommendation(root, {
+    hook: 'read', action: 'hint', answered,
+    // reason segments WHY an unanswered hint fell back to the bare advice:
+    // '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.
+    ...(answered ? {} : { reason: answer.status }),
+  });
   process.stdout.write((answered ? buildHintWithAnswer(dir, answer) : buildHint(dir)) + '\n');
   return true;
 }

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

@@ -291,6 +291,58 @@ test('trackReadAndMaybeHint: fires on 5th read with stubbed overview answer', ()
   }
 });
 
+test('trackReadAndMaybeHint: missing binary → hint records reason:no-binary (delivered-overview dark, sibling of pre-grep)', () => {
+  // Sibling-hook parity: when the binary can't be found the read-fanout hint
+  // falls back to bare advice. That must be distinguishable in the funnel from a
+  // runtime failure, exactly like pre-grep's deny. Force findBinary() null
+  // in-process and unset _CG_ANSWER_BINARY so the resolution actually runs.
+  const findBinaryMod = require('./find-binary');
+  const realFindBinary = findBinaryMod.findBinary;
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'readfan-nobin-'));
+  fs.mkdirSync(path.join(root, '.code-graph'), { recursive: true });
+  const oldEnv = process.env._CG_ANSWER_BINARY;
+  delete process.env._CG_ANSWER_BINARY;
+  findBinaryMod.findBinary = () => null;
+  const origWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = () => true;
+  try {
+    let fired = false;
+    for (let i = 0; i < 5; i++) {
+      fired = trackReadAndMaybeHint(root, 'src/storage/file' + i + '.rs');
+    }
+    assert.equal(fired, true, '5th same-dir read must still fire the hint');
+    const recs = fs.readFileSync(path.join(root, '.code-graph', 'recommendations.jsonl'), 'utf8');
+    const last = JSON.parse(recs.trim().split('\n').pop());
+    assert.equal(last.action, 'hint');
+    assert.equal(last.answered, false);
+    assert.equal(last.reason, 'no-binary',
+      'a dark delivered-overview hint must be distinguishable from a runtime failure');
+  } finally {
+    process.stdout.write = origWrite;
+    findBinaryMod.findBinary = realFindBinary;
+    if (oldEnv === undefined) delete process.env._CG_ANSWER_BINARY;
+    else process.env._CG_ANSWER_BINARY = oldEnv;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('trackReadAndMaybeHint: non-fanout source read records an observe event', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'readfan-observe-'));
+  fs.mkdirSync(path.join(root, '.code-graph'), { recursive: true });
+  try {
+    // A single subdir source read is below the fanout threshold → no hint, but
+    // it must still record an `observe` event for the search-decay metric.
+    const fired = trackReadAndMaybeHint(root, 'src/storage/db.rs');
+    assert.equal(fired, false, 'single read must not fire the fanout hint');
+    const recs = fs.readFileSync(path.join(root, '.code-graph', 'recommendations.jsonl'), 'utf8');
+    const last = JSON.parse(recs.trim().split('\n').pop());
+    assert.equal(last.hook, 'read');
+    assert.equal(last.action, 'observe');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('trackReadAndMaybeHint: top-level and outside-root paths never fire', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'readfan-skip-'));
   try {

package/claude-plugin/scripts/recommendation-log.js

@@ -18,6 +18,33 @@ const path = require('path');
 
 const REC_FILE = 'recommendations.jsonl';
 
+// Bounded growth: recommendations.jsonl is append-only and written per-event
+// from BOTH here and the Rust CLI (cli::record_cli_use). Keep these constants in
+// sync with the Rust side (mcp::metrics::JSONL_ROTATE_MAX_BYTES / KEEP_BYTES).
+const ROTATE_MAX_BYTES = 1048576; // 1 MB
+const ROTATE_KEEP_BYTES = 524288; // 512 KB
+
+/**
+ * Best-effort size-based rotation: if `file` exceeds ROTATE_MAX_BYTES, rewrite
+ * it keeping ~the last ROTATE_KEEP_BYTES, trimmed *forward* to the next line
+ * boundary so no partial line survives. Swallows every error — telemetry
+ * rotation must never break or delay a tool call. Mirror of the Rust
+ * `mcp::metrics::rotate_jsonl_if_over`.
+ * @param {string} file  absolute path to the JSONL file
+ */
+function rotateIfNeeded(file) {
+  try {
+    if (fs.statSync(file).size <= ROTATE_MAX_BYTES) return;
+    const buf = fs.readFileSync(file);
+    const start = Math.max(0, buf.length - ROTATE_KEEP_BYTES);
+    const nl = buf.indexOf(0x0a, start); // first newline at/after start
+    const trimStart = nl >= 0 ? nl + 1 : start;
+    fs.writeFileSync(file, buf.subarray(trimStart));
+  } catch {
+    /* missing file or IO error → skip; the append below still runs */
+  }
+}
+
 /**
  * Append one recommendation event to <cwd>/.code-graph/recommendations.jsonl.
  * @param {string} cwd        project root (the hook's process.cwd())
@@ -30,8 +57,10 @@ function recordRecommendation(cwd, event = {}) {
     // Append-only: do NOT create .code-graph. Its absence means "not an indexed
     // project" — recording there would pollute non-project cwds.
     if (!fs.existsSync(dir)) return false;
+    const file = path.join(dir, REC_FILE);
+    rotateIfNeeded(file); // rotate-before-append so the file never exceeds ~max + one line
     const line = JSON.stringify({ ts: new Date().toISOString(), ...event }) + '\n';
-    fs.appendFileSync(path.join(dir, REC_FILE), line);
+    fs.appendFileSync(file, line);
     return true;
   } catch {
     return false;

package/claude-plugin/scripts/recommendation-log.test.js

@@ -42,3 +42,25 @@ test('recordRecommendation appends across calls (one line each)', (t) => {
   const hooks = lines.map((l) => JSON.parse(l).hook);
   assert.deepEqual(hooks, ['grep', 'read', 'grep']);
 });
+
+test('recordRecommendation rotates the file when it exceeds the size cap', (t) => {
+  const cwd = tmpProject(t, true);
+  const file = path.join(cwd, '.code-graph', REC_FILE);
+  // Pre-fill > 1MB of prior events.
+  const filler = 'y'.repeat(1024);
+  let blob = '';
+  for (let i = 0; i < 1200; i++) blob += `{"old":${i},"pad":"${filler}"}\n`;
+  fs.writeFileSync(file, blob);
+  assert.ok(fs.statSync(file).size > 1048576, 'precondition: file over 1MB');
+
+  // One more recorded event must trigger rotation (rotate-before-append).
+  assert.equal(recordRecommendation(cwd, { hook: 'grep', action: 'deny' }), true);
+
+  const size = fs.statSync(file).size;
+  assert.ok(size < 600000, `rotated file should be well under 1MB, got ${size}`);
+  const lines = fs.readFileSync(file, 'utf8').trim().split('\n');
+  // The just-recorded line is last and intact; the first surviving line is whole JSON.
+  const last = JSON.parse(lines[lines.length - 1]);
+  assert.equal(last.action, 'deny');
+  assert.doesNotThrow(() => JSON.parse(lines[0]), 'first surviving line must be a whole JSON line');
+});

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

@@ -379,6 +379,13 @@ function determineQueryType(intents, symbols, filePaths, isCoolingDownFn, messag
 // db presence) live INSIDE this guard so `require()` from tests doesn't
 // terminate the test process on module load.
 function runMain() {
+  // Escape hatch first: CODE_GRAPH_QUIET_HOOKS=1 must silence EVERYTHING,
+  // including the mid-session install notice below. On a fresh install (no
+  // manifest) that notice otherwise leaks to stdout even under quiet — and any
+  // stdout/stderr leak lands in Claude's display. (The dev box has a manifest,
+  // so this only surfaced once user-prompt-context.test.js ran in CI.)
+  if (computeQuietHooks()) return;
+
   // Mid-session install: lifecycle.js install() hasn't run yet (no manifest).
   // MCP server only starts at session startup — tell the user to restart.
   if (!fs.existsSync(MANIFEST_PATH)) {
@@ -398,8 +405,6 @@ function runMain() {
     return;
   }
 
-  if (computeQuietHooks()) return;
-
   // --- Read user message ---
   let message;
   try {

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

@@ -558,6 +558,33 @@ test('CODE_GRAPH_QUIET_HOOKS=1 short-circuits silently on stdout, stderr, exit 0
   assert.equal(proc.status, 0, 'quiet must exit 0');
 });
 
+test('CODE_GRAPH_QUIET_HOOKS=1 silences even the fresh-install (no-manifest) notice', () => {
+  // Regression: the mid-session install notice printed BEFORE the quiet check,
+  // so on a fresh checkout (no ~/.cache/code-graph manifest) it leaked to stdout
+  // despite the escape hatch. CI hit this; the dev box has a manifest and masked
+  // it. Force the no-manifest path with a throwaway HOME so it reproduces locally.
+  const { spawnSync } = require('node:child_process');
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-upc-nohome-'));
+  try {
+    const script = path.join(__dirname, 'user-prompt-context.js');
+    const proc = spawnSync(process.execPath, [script], {
+      input: JSON.stringify({ message: 'impact of refactoring parse_code function' }),
+      // HOME (POSIX) + USERPROFILE (Windows) → os.homedir() points at an empty
+      // dir, so MANIFEST_PATH is absent and runMain() enters the install branch.
+      env: { ...process.env, HOME: home, USERPROFILE: home, CODE_GRAPH_QUIET_HOOKS: '1' },
+      encoding: 'utf8',
+      timeout: 2000,
+    });
+    assert.equal(proc.stdout, '', 'quiet must silence the no-manifest install notice on stdout');
+    assert.equal(proc.stderr, '', 'quiet must be silent on stderr');
+    assert.equal(proc.status, 0, 'quiet must exit 0');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
 // ── Phase E: hasSymptom + symptom-hint fallback ──────────────
 
 const { hasSymptom, SYMPTOM_PATTERNS } = require('./user-prompt-context');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.56.2",
+  "version": "0.57.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.56.2",
-    "@sdsrs/code-graph-linux-arm64": "0.56.2",
-    "@sdsrs/code-graph-darwin-x64": "0.56.2",
-    "@sdsrs/code-graph-darwin-arm64": "0.56.2",
-    "@sdsrs/code-graph-win32-x64": "0.56.2"
+    "@sdsrs/code-graph-linux-x64": "0.57.0",
+    "@sdsrs/code-graph-linux-arm64": "0.57.0",
+    "@sdsrs/code-graph-darwin-x64": "0.57.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.57.0",
+    "@sdsrs/code-graph-win32-x64": "0.57.0"
   }
 }