@sdsrs/code-graph 0.64.0 → 0.67.0

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

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

package/claude-plugin/scripts/doctor.js

@@ -260,6 +260,24 @@ function runDiagnostics() {
     }
   } catch { /* probe failed — skip */ }
 
+  // 8. Hook firing (v0.67.0) — coverage (#7) proves the hook is WIRED into
+  //    settings.json; this proves the script actually RUNS. Spawns each
+  //    registered hook with a synthetic CC payload in a throwaway fixture and
+  //    checks it exits 0. Catches the registered-but-inert class (broken
+  //    require-chain / incompatible node / corrupt install) that a string/path
+  //    check cannot see. (It does NOT prove CC dispatches to it — that needs a
+  //    live session; the dispatch canary in session-init.js covers that.)
+  try {
+    const { verifyHooksFire } = require('./lifecycle');
+    const fire = verifyHooksFire();
+    if (fire.ok) {
+      results.push({ name: 'Hook firing', status: 'ok', detail: `${fire.results.length} hooks fire cleanly` });
+    } else {
+      const failed = fire.results.filter(r => !r.ok).map(r => r.label).join(', ') || fire.error || 'unknown';
+      results.push({ name: 'Hook firing', status: 'warn', detail: `did not fire: ${failed}` });
+    }
+  } catch { /* probe failed — skip */ }
+
   return results;
 }
 

package/claude-plugin/scripts/hook-fire.test.js

@@ -0,0 +1,117 @@
+'use strict';
+// Layer-A "does the hook really fire" smoke test (v0.67.0). Distinct from
+// hooks.test.js (which inspects registration STRINGS) and the per-hook unit
+// tests (which import predicates): this spawns each REGISTERED hook script the
+// way Claude Code would — node + a synthetic CC stdin payload — and asserts it
+// runs end-to-end without erroring. Catches the "registered but inert on this
+// machine" class (broken require-chain, node-version, corrupt install) that
+// string/predicate tests can't see. See feedback_pretooluse_dark_under_green_health.md.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { verifyHooksFire } = require('./lifecycle');
+const { hookFireWarning, analyzeHookDark } = require('./session-init');
+
+test('verifyHooksFire: all real registered hooks run cleanly (exit 0)', () => {
+  const { ok, results } = verifyHooksFire();
+  // 3 PreToolUse + 1 PostToolUse + 1 UserPromptSubmit = 5 settings.json hooks
+  assert.ok(results.length >= 5, `expected >=5 hook probes, got ${results.length}`);
+  for (const r of results) {
+    assert.ok(r.ok, `hook ${r.label} (${r.script}) did not fire cleanly: code=${r.code} err=${r.error}`);
+  }
+  assert.equal(ok, true);
+});
+
+test('verifyHooksFire: the grep hook actually engages (emits a decision)', () => {
+  const { results } = verifyHooksFire();
+  const grep = results.find(r => /pre-grep-guide/.test(r.script));
+  assert.ok(grep, 'no grep hook probe found');
+  assert.ok(grep.emitted,
+    'pre-grep-guide produced no output on an engaging grep payload — the firing path did not engage');
+});
+
+test('verifyHooksFire: reports a broken hook script (teeth)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-hookfire-teeth-'));
+  const broken = path.join(dir, 'broken-hook.js');
+  fs.writeFileSync(broken, 'throw new Error("boom at runtime");\n');
+  try {
+    const { ok, results } = verifyHooksFire({ hooks: [{ label: 'broken', script: broken, payload: {} }] });
+    assert.equal(ok, false, 'a hook that throws must make ok=false');
+    assert.equal(results[0].ok, false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('verifyHooksFire: missing hook script is reported, not thrown (teeth)', () => {
+  const { ok, results } = verifyHooksFire({
+    hooks: [{ label: 'gone', script: path.join(os.tmpdir(), 'definitely-not-here-xyz.js'), payload: {} }],
+  });
+  assert.equal(ok, false);
+  assert.equal(results[0].ok, false);
+});
+
+// ── Layer A surface: hookFireWarning (pure interpreter of cached state) ──
+
+test('hookFireWarning: ok / absent state → no warning', () => {
+  assert.equal(hookFireWarning({ ok: true, failures: [] }), null);
+  assert.equal(hookFireWarning(null), null);
+  assert.equal(hookFireWarning({ ok: false, failures: [] }), null); // no names → nothing to say
+});
+
+test('hookFireWarning: failed state names the failed hook + points to doctor', () => {
+  const w = hookFireWarning({ ok: false, failures: ['PreToolUse:Bash'] });
+  assert.match(w, /PreToolUse:Bash/);
+  assert.match(w, /doctor/);
+});
+
+// ── Layer B dispatch canary: analyzeHookDark (pure) ──
+
+test('analyzeHookDark: edit fires repeatedly but grep/read never → warns', () => {
+  const lines = ['{"hook":"edit"}', '{"hook":"edit"}', '{"hook":"edit"}'].join('\n');
+  assert.match(analyzeHookDark(lines), /grep\/read/);
+});
+
+test('analyzeHookDark: any grep/read event present → no warning', () => {
+  const lines = ['{"hook":"edit"}', '{"hook":"edit"}', '{"hook":"edit"}', '{"hook":"read","action":"observe"}'].join('\n');
+  assert.equal(analyzeHookDark(lines), null);
+});
+
+test('analyzeHookDark: below the edit threshold / empty → no warning (low false-positive)', () => {
+  assert.equal(analyzeHookDark('{"hook":"edit"}\n{"hook":"edit"}'), null);
+  assert.equal(analyzeHookDark(''), null);
+  assert.equal(analyzeHookDark('garbage\n{not json}'), null);
+});
+
+// ── CLI wiring: `lifecycle.js verify-hooks-fire` writes the state file ──
+
+test('CLI verify-hooks-fire runs and writes hook-fire-state.json (HOME-redirected)', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-hf-home-'));
+  try {
+    const r = spawnSync(process.execPath, [path.join(__dirname, 'lifecycle.js'), 'verify-hooks-fire'], {
+      env: { ...process.env, HOME: home }, encoding: 'utf8', timeout: 30000,
+    });
+    assert.equal(r.status, 0, `CLI exit ${r.status}: ${r.stderr}`);
+    assert.match(r.stdout, /Hook firing: (OK|FAIL)/);
+    const statePath = path.join(home, '.cache', 'code-graph', 'hook-fire-state.json');
+    assert.ok(fs.existsSync(statePath), 'hook-fire-state.json was not written');
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    assert.equal(typeof state.ok, 'boolean');
+    assert.ok(state.ts, 'state missing timestamp');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+// ── doctor wiring: runDiagnostics surfaces a "Hook firing" check ──
+
+test('doctor runDiagnostics includes a Hook firing check', () => {
+  const { runDiagnostics } = require('./doctor');
+  const results = runDiagnostics();
+  const hf = results.find(r => r.name === 'Hook firing');
+  assert.ok(hf, 'doctor did not report a "Hook firing" check');
+  assert.ok(['ok', 'warn'].includes(hf.status), `unexpected status ${hf.status}`);
+});

package/claude-plugin/scripts/hooks.test.js

@@ -3,6 +3,7 @@ const test = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 
 // Regression gate for v0.31.1: hooks.json matchers must be Claude Code's
 // literal/regex form, NOT the expression DSL `tool == "X"`. The earlier
@@ -149,3 +150,81 @@ test('lifecycle.buildSettingsHookEntries: hook commands use absolute paths (no e
     }
   }
 });
+
+// v0.67.0 hook-reliability Layer 1 (static firing invariants):
+// The tests above inspect matcher STRINGS but never the target script file. A
+// renamed/typo'd/moved hook script makes Claude Code unable to run it → the hook
+// is SILENTLY inert (the "dark hook" class — feedback_pretooluse_dark_under_green_health.md).
+// This collects every script CC will actually load — both registration channels —
+// and asserts each exists and parses. Cheapest possible guard against silent dark.
+const PLUGIN_ROOT = path.resolve(__dirname, '..'); // claude-plugin/
+
+function resolveHookScript(cmd) {
+  // command form: node "<path>"  (<path> may contain ${CLAUDE_PLUGIN_ROOT})
+  const m = (cmd || '').match(/"([^"]+\.js)"/);
+  return m ? m[1].replace('${CLAUDE_PLUGIN_ROOT}', PLUGIN_ROOT) : null;
+}
+
+function allRegisteredHookCommands() {
+  const commands = [];
+  // (1) settings.json side — lifecycle.buildSettingsHookEntries (PreToolUse/PostToolUse/UserPromptSubmit)
+  const { buildSettingsHookEntries } = require('./lifecycle');
+  for (const entries of Object.values(buildSettingsHookEntries())) {
+    for (const e of entries) for (const h of e.hooks || []) commands.push(h.command);
+  }
+  // (2) plugin-cache hooks.json side — SessionStart (the only event CC loads from here)
+  for (const entries of Object.values(loadHooks().hooks || {})) {
+    if (!Array.isArray(entries)) continue;
+    for (const e of entries) for (const h of e.hooks || []) commands.push(h.command);
+  }
+  return commands;
+}
+
+test('every registered hook script exists on disk', () => {
+  const commands = allRegisteredHookCommands();
+  // 3 PreToolUse + 1 PostToolUse + 1 UserPromptSubmit + 1 SessionStart = 6
+  assert.ok(commands.length >= 6, `expected >=6 registered hook commands, got ${commands.length}`);
+  for (const cmd of commands) {
+    const p = resolveHookScript(cmd);
+    assert.ok(p, `could not extract a .js path from hook command: ${JSON.stringify(cmd)}`);
+    assert.ok(fs.existsSync(p),
+      `hook script missing on disk: ${p}\n  (from command ${JSON.stringify(cmd)})\n` +
+      `  A renamed/typo'd/moved script makes the hook silently inert — Claude Code cannot run a missing file.`);
+  }
+});
+
+test('every registered hook script parses (node --check)', () => {
+  for (const cmd of allRegisteredHookCommands()) {
+    const p = resolveHookScript(cmd);
+    assert.doesNotThrow(
+      () => execFileSync(process.execPath, ['--check', p], { stdio: 'pipe' }),
+      `hook script has a syntax error (node --check failed): ${p}`);
+  }
+});
+
+// Pin the EXACT matcher surface, not just "covers". The earlier tests assert the
+// set INCLUDES Edit/Bash/Read etc.; this asserts it EQUALS the intended set, so
+// adding/dropping a matcher must update this test — a deliberate decision, never a
+// silent coverage drift. A PreToolUse hook fires only on the literal tool name.
+// Deliberate exclusions (verified 2026-06-23; revisit if either premise changes):
+//   - MultiEdit: NOT a tool in current Claude Code (absent from the tool surface;
+//     the plugin targets recent CC per the v0.32.0 settings.json architecture), so
+//     a matcher for it would be dead config. Re-add only if CC (re)introduces it.
+//   - NotebookEdit: a real tool, but code-graph does NOT parse .ipynb (no jupyter
+//     support in the parser / supported-language set), so both pre-edit-guide
+//     (needs graph symbols) and incremental-index (needs to re-index the file)
+//     would no-op on a notebook. Prerequisite is .ipynb PARSING support (a parser
+//     feature); add the matcher as PART of that work, never before it.
+test('buildSettingsHookEntries: matcher surface is exactly the intended set', () => {
+  const { buildSettingsHookEntries } = require('./lifecycle');
+  const desired = buildSettingsHookEntries();
+  const setOf = (event) => (desired[event] || []).map(e => e.matcher).sort();
+  assert.deepEqual(setOf('PreToolUse'), ['Bash', 'Edit', 'Read'],
+    'PreToolUse matcher set changed — update this gate intentionally (does the new tool need a guide hook?)');
+  assert.deepEqual(setOf('PostToolUse'), ['Write|Edit'],
+    'PostToolUse matcher set changed — incremental-index re-index trigger surface must be deliberate');
+  assert.deepEqual(setOf('UserPromptSubmit'), [''],
+    'UserPromptSubmit matcher set changed unexpectedly');
+  assert.deepEqual(Object.keys(desired).sort(), ['PostToolUse', 'PreToolUse', 'UserPromptSubmit'],
+    'a new top-level hook event is registered into settings.json — confirm it is intended (SessionStart belongs in hooks.json)');
+});

package/claude-plugin/scripts/lifecycle.js

@@ -463,6 +463,118 @@ function surveyHookCoverage(settings) {
   return { expected, present: [...present], missing, stale };
 }
 
+// --- Firing self-test (v0.67.0) ---
+//
+// surveyHookCoverage proves a hook is WIRED; it does NOT prove the script RUNS.
+// A renamed sibling module, an incompatible node, or a corrupt install leaves a
+// hook registered-but-inert — invisible to every string/path check. verifyHooksFire
+// spawns each registered hook the way Claude Code does (node + a synthetic CC
+// stdin payload) inside a throwaway fixture and asserts it exits 0. This is the
+// "does it really fire" check. What it CANNOT prove is that CC *dispatches* real
+// tool-calls to it (only a live session shows that — see the Layer-B dispatch
+// canary in session-init.js). Best-effort; never throws.
+
+// Representative CC stdin payload that drives each matcher's path. The Bash
+// payload is engaging (a source-tree search → a deny/hint IS emitted); the Edit
+// payload's short old_string short-circuits before any binary spawn; the rest
+// just exercise the require-chain + stdin parse.
+function hookFirePayload(matcher) {
+  switch (matcher) {
+    case 'Bash':
+      return { tool_name: 'Bash', tool_input: { command: 'grep -rn someUniqueSymbol src/' } };
+    case 'Read':
+      return { tool_name: 'Read', tool_input: { file_path: 'src/example.rs' } };
+    case 'Edit':
+    case 'Write|Edit':
+      return { tool_name: 'Edit', tool_input: { file_path: 'src/example.rs', old_string: 'a', new_string: 'b' } };
+    case '': // UserPromptSubmit
+      return { prompt: 'where is the parse function defined' };
+    default:
+      return { tool_name: 'Unknown', tool_input: {} };
+  }
+}
+
+// The hooks CC actually loads from settings.json (PreToolUse/PostToolUse/
+// UserPromptSubmit). SessionStart (hooks.json) runs every session → its own
+// liveness proof → excluded here.
+function defaultHookFireProbes() {
+  const probes = [];
+  for (const [event, entries] of Object.entries(buildSettingsHookEntries())) {
+    for (const e of entries) {
+      const cmd = e.hooks && e.hooks[0] && e.hooks[0].command;
+      const m = (cmd || '').match(/"([^"]+\.js)"/);
+      if (!m) continue;
+      probes.push({ label: `${event}:${e.matcher || '*'}`, script: m[1], payload: hookFirePayload(e.matcher || '') });
+    }
+  }
+  return probes;
+}
+
+function verifyHooksFire({ hooks, env, timeoutMs = 4000, tmpBase } = {}) {
+  const { spawnSync } = require('child_process');
+  const probes = hooks || defaultHookFireProbes();
+
+  // Throwaway fixture carrying the .code-graph/index.db marker so resolveProjectRoot
+  // resolves (otherwise the hooks early-return before exercising anything).
+  // Base is os.tmpdir() directly (a UNIQUE mkdtemp), NOT the shared cgTmpDir()
+  // subdir — a concurrent process clearing `<tmp>/code-graph-mcp` mid-run would
+  // otherwise yank this fixture out from under an in-flight spawn (cwd ENOENT).
+  let fixture = null;
+  try {
+    const base = tmpBase || os.tmpdir();
+    fixture = fs.mkdtempSync(path.join(base, 'cg-hookfire-'));
+    fs.mkdirSync(path.join(fixture, '.code-graph'), { recursive: true });
+    fs.writeFileSync(path.join(fixture, '.code-graph', 'index.db'), '');
+  } catch (e) {
+    return { ok: false, results: [], error: `fixture: ${e && e.message}` };
+  }
+
+  // Force a non-silenced, no-binary-spawn firing config: the smoke tests the
+  // machinery regardless of the user's silence prefs and never invokes the binary
+  // (CODE_GRAPH_NO_ANSWER_IN_DENY keeps cg-answer out of the deny path).
+  // Redirect the hooks' tmp state (per-command grep cooldown, read-fanout state)
+  // into the throwaway fixture via TMPDIR so the smoke neither collides with a
+  // real 60s cooldown (which would suppress the deny → false "didn't fire") nor
+  // pollutes the user's real cooldown/state.
+  const baseEnv = {
+    ...process.env,
+    CODE_GRAPH_QUIET_HOOKS: '0',
+    CODE_GRAPH_NO_ANSWER_IN_DENY: '1',
+    TMPDIR: fixture, TMP: fixture, TEMP: fixture,
+    ...(env || {}),
+  };
+
+  const results = [];
+  for (const h of probes) {
+    let error = null, ok = false, emitted = false, code = null, signal = null;
+    try {
+      const r = spawnSync(process.execPath, [h.script], {
+        input: JSON.stringify(h.payload || {}),
+        cwd: fixture,
+        env: baseEnv,
+        timeout: timeoutMs,
+        encoding: 'utf8',
+      });
+      code = r.status;
+      signal = r.signal;
+      ok = !r.error && r.status === 0;
+      emitted = !!(r.stdout && r.stdout.trim());
+      if (!ok) {
+        error = r.error
+          ? String(r.error.message || r.error)
+          : ((r.stderr || '').trim().slice(0, 200) || `exit ${r.status}`);
+      }
+    } catch (e) {
+      error = String((e && e.message) || e);
+    }
+    results.push({ label: h.label, script: h.script, ok, code, signal, emitted, error });
+  }
+
+  try { fs.rmSync(fixture, { recursive: true, force: true }); } catch { /* ok */ }
+
+  return { ok: results.length > 0 && results.every(r => r.ok), results };
+}
+
 // --- Install (idempotent) ---
 
 function install() {
@@ -760,6 +872,7 @@ module.exports = {
   removeHooksFromSettings, isOurHookEntry,
   registerHooksToSettings, buildSettingsHookEntries,                  // v0.32.0
   surveyHookCoverage, compositeCommand,                                // v0.49.1 — version-aware self-heal
+  verifyHooksFire, defaultHookFireProbes,                              // v0.67.0 — firing self-test
   activeInstallPath, isStaleRelicContext,                              // v0.49.1 — stale-relic downgrade guard
   SETTINGS_HOOK_DESC, OUR_HOOK_SCRIPTS, OUR_DESCRIPTIONS,              // v0.32.0 — for tests
   PLUGIN_ROOT,                                                         // v0.32.1 — for tests / consumers
@@ -796,8 +909,20 @@ if (require.main === module) {
     const checkOnly = process.argv.includes('--check-only');
     const { issueCount } = runDoctor({ checkOnly });
     process.exit(issueCount > 0 ? 1 : 0);
+  } else if (cmd === 'verify-hooks-fire') {
+    // v0.67.0 — Layer-A firing self-test. Spawned detached by session-init
+    // (off the SessionStart budget); writes a small state file the next
+    // SessionStart reads to surface failures.
+    const res = verifyHooksFire();
+    const failures = res.results.filter(r => !r.ok).map(r => r.label);
+    try {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+      writeJsonAtomic(path.join(CACHE_DIR, 'hook-fire-state.json'),
+        { ts: new Date().toISOString(), ok: res.ok, failures });
+    } catch { /* best-effort telemetry */ }
+    console.log(`Hook firing: ${res.ok ? 'OK' : 'FAIL'} (${res.results.length} probed${failures.length ? ', failed: ' + failures.join(', ') : ''})`);
   } else {
-    console.error('Usage: lifecycle.js <install|uninstall|update|health|doctor>');
+    console.error('Usage: lifecycle.js <install|uninstall|update|health|doctor|verify-hooks-fire>');
     process.exit(1);
   }
 }

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

@@ -484,6 +484,13 @@ function runMain() {
   if (relPrefix) cmd = rebaseRelativePaths(cmd, relPrefix, root);
   if (!shouldHint(cmd)) return;
 
+  // v0.64 — fingerprint the grep's pattern once, shared by the emit points below.
+  // The funnel (aggregate_recommendations_jsonl) uses it to tell a verbatim re-grep
+  // of an answered deny (inline answer ignored → fall-through) from a deeper
+  // drill-down. undefined when there's no identifier-like pattern (unquoted / prose
+  // grep) → omitted from the event, so the funnel stays back-compatible.
+  const grepPattern = translateBreToRg(cmd, pickBlockPattern(cmd));
+
   // v0.48 — deliberate escape: record it (funnel visibility) and stay silent.
   // Before GREP_HEAD accepted bare KEY=VALUE prefixes these were invisible.
   if (commandHasBypass(rawCmd)) {
@@ -495,7 +502,7 @@ function runMain() {
     // 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' });
+    recordRecommendation(root, { hook: 'grep', action: 'observe', ...(grepPattern ? { pattern: grepPattern } : {}) });
     return;
   }
 
@@ -510,7 +517,7 @@ function runMain() {
     // v0.49 — intent-aware: declaration+context greps get `show` bodies,
     // falling back to the grep answer, then the static deny.
     let answer = { status: 'unavailable' };
-    const pattern = translateBreToRg(cmd, pickBlockPattern(cmd));
+    const pattern = grepPattern; // computed once above; reused for the answer + deny fingerprint
     // v0.48 — glob-truncated once, shared by the run and the deny message
     // (a literal `dir/*.py` argv made rg exit 1 → answered:false static deny).
     const searchPath = sanitizeSearchPath(extractSearchPath(cmd));
@@ -544,6 +551,9 @@ function runMain() {
     const unansweredTail = extractUnansweredTail(rawCmd);
     recordRecommendation(root, {
       hook: 'grep', action: 'deny', answered,
+      // pattern fingerprints the denied search so the funnel can score a verbatim
+      // re-grep of it (the inline answer was ignored) as fall-through, not a win.
+      ...(pattern ? { pattern } : {}),
       // 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:

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

@@ -909,6 +909,45 @@ test('e2e: denied grep with stub hits → deny JSON embeds the answer + records
   }
 });
 
+test('e2e: denied grep records the denied pattern (fingerprint for verbatim re-grep detection)', () => {
+  // The Rust funnel (aggregate_recommendations_jsonl) scores a follow-up search
+  // carrying the SAME pattern as the armed answered deny as fall-through, not a
+  // sustained drill-down. That needs the pattern on the deny event.
+  const uniq = `StubPat${Date.now()}`;
+  const fixture = e2eFixture(`process.stdout.write('src/foo.rs:7  hit\\n');`);
+  const cmd = `grep -rn "${uniq}" src/`;
+  try {
+    const res = runHook(cmd, fixture);
+    assert.equal(res.status, 0);
+    const rec = JSON.parse(fsE2e.readFileSync(
+      pathE2e.join(fixture.dir, '.code-graph', 'recommendations.jsonl'), 'utf8').trim().split('\n').pop());
+    assert.equal(rec.action, 'deny');
+    assert.equal(rec.pattern, uniq, 'deny event carries the denied pattern as a fingerprint');
+  } finally {
+    cleanupFixture(fixture, cmd);
+  }
+});
+
+test('e2e: re-grep within cooldown → observe carries the same pattern (answer-ignored fingerprint)', () => {
+  // First grep denies + marks the cooldown; the verbatim re-grep within the
+  // window runs silently as an observe. It must carry the same pattern so the
+  // funnel can tell "ignored the inline answer" from "drilled into something new".
+  const uniq = `StubCool${Date.now()}`;
+  const fixture = e2eFixture(`process.stdout.write('src/foo.rs:7  hit\\n');`);
+  const cmd = `grep -rn "${uniq}" src/`;
+  try {
+    runHook(cmd, fixture);              // 1st → deny + markCooldown
+    const res2 = runHook(cmd, fixture); // 2nd within window → observe
+    assert.equal(res2.status, 0);
+    const last = JSON.parse(fsE2e.readFileSync(
+      pathE2e.join(fixture.dir, '.code-graph', 'recommendations.jsonl'), 'utf8').trim().split('\n').pop());
+    assert.equal(last.action, 'observe');
+    assert.equal(last.pattern, uniq, 'cooldown observe carries the re-grepped pattern');
+  } finally {
+    cleanupFixture(fixture, cmd);
+  }
+});
+
 test('e2e: stub reports no matches → grep allowed with FYI + records fallthrough', () => {
   const uniq = `StubMiss${Date.now()}`;
   const fixture = e2eFixture(

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

@@ -17,6 +17,9 @@ const fs = require('fs');
 const path = require('path');
 
 const REC_FILE = 'recommendations.jsonl';
+// Opt-in per-project metrics-silence sentinel (under .code-graph/). Mirror of the
+// Rust `domain::NO_METRICS_SENTINEL` — keep the literal in sync.
+const NO_METRICS_FILE = '.no-metrics';
 
 // 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
@@ -57,6 +60,11 @@ 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;
+    // Opt-in metrics silence for dev/dogfood checkouts: when the project marks
+    // itself with `.code-graph/.no-metrics`, the tool's own hook/CLI runs (sims,
+    // functionality testing) must not self-pollute its adoption metrics. Mirrors
+    // the Rust cli::record_cli_use guard. Reversible: delete the file to re-enable.
+    if (fs.existsSync(path.join(dir, NO_METRICS_FILE))) 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';

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

@@ -32,6 +32,19 @@ test('recordRecommendation is a no-op (no dir created) when .code-graph absent',
   assert.equal(fs.existsSync(path.join(cwd, '.code-graph')), false);
 });
 
+test('recordRecommendation is a no-op when .code-graph/.no-metrics sentinel present', (t) => {
+  const cwd = tmpProject(t, true);
+  // Without the sentinel it records normally...
+  assert.equal(recordRecommendation(cwd, { hook: 'grep', action: 'deny' }), true);
+  const before = fs.readFileSync(path.join(cwd, '.code-graph', REC_FILE), 'utf8');
+  // ...then the project marks itself metrics-silent (a dev/dogfood checkout)...
+  fs.writeFileSync(path.join(cwd, '.code-graph', '.no-metrics'), '');
+  // ...and subsequent recordings are suppressed, leaving the file byte-unchanged.
+  assert.equal(recordRecommendation(cwd, { hook: 'grep', action: 'hint' }), false);
+  const after = fs.readFileSync(path.join(cwd, '.code-graph', REC_FILE), 'utf8');
+  assert.equal(after, before, 'sentinel must suppress further recordings');
+});
+
 test('recordRecommendation appends across calls (one line each)', (t) => {
   const cwd = tmpProject(t, true);
   recordRecommendation(cwd, { hook: 'grep', action: 'hint' });

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

@@ -493,10 +493,18 @@ function runSessionInit({ source } = {}) {
   const consistencyIssues = binaryCheck.available
     ? consistencyCheck(binaryCheck.binary)
     : [];
+  // v0.67.0 — hook reliability (active-project path only): Layer A pushes a
+  // FAILED firing self-test result (and refreshes it in the background, off the
+  // 5s budget); Layer B is the runtime dispatch-dark canary. Both best-effort.
+  const hookFireWarn = checkHookFiring();
+  if (hookFireWarn) process.stderr.write(hookFireWarn);
+  const hookDarkWarn = detectHookDark();
+  if (hookDarkWarn) process.stderr.write(hookDarkWarn);
   return {
     inactive: false, lifecycle,
     autoUpdateLaunched, indexFreshness, mapInjected, recentImpactInjected, binaryCheck, consistencyIssues,
     quietHooks, adopted, autoAdopted: autoAdopt.attempted,
+    hookFireWarn: !!hookFireWarn, hookDarkWarn: !!hookDarkWarn,
   };
 }
 
@@ -611,6 +619,69 @@ function injectRecentImpact({ source } = {}) {
   }
 }
 
+// ── v0.67.0 hook-reliability surfaces ─────────────────────────────────
+//
+// Layer A (firing): surface the cached `verify-hooks-fire` result. PUSH — the
+// model/user learns of a broken hook without running doctor. Pure interpreter
+// + an I/O wrapper that background-refreshes the cache off the SessionStart budget.
+function hookFireWarning(state) {
+  if (state && state.ok === false && Array.isArray(state.failures) && state.failures.length) {
+    return `[code-graph] Hook firing self-test failed for: ${state.failures.join(', ')}.\n` +
+           `            Registered but did not run on this machine — run: code-graph-mcp doctor\n`;
+  }
+  return null;
+}
+
+function checkHookFiring({ now = Date.now() } = {}) {
+  const STALE_MS = 24 * 60 * 60 * 1000;
+  let warn = null;
+  try {
+    const state = readJson(path.join(CACHE_DIR, 'hook-fire-state.json'));
+    warn = hookFireWarning(state);
+    const fresh = state && state.ts && (now - new Date(state.ts).getTime() < STALE_MS);
+    if (!fresh) {
+      // Background refresh — detached + unref'd + stdio ignore → zero budget impact.
+      // First session after install has no cache → schedules a check; failures
+      // surface from the next start. Re-checks daily (catches post-install drift,
+      // e.g. a node upgrade that breaks a hook).
+      try {
+        const child = spawn(process.execPath, [path.join(__dirname, 'lifecycle.js'), 'verify-hooks-fire'], {
+          detached: true, stdio: 'ignore',
+        });
+        if (child && typeof child.unref === 'function') child.unref();
+      } catch { /* ok */ }
+    }
+  } catch { /* best-effort */ }
+  return warn;
+}
+
+// Layer B (dispatch): verifyHooksFire proves the script RUNS; only a live session
+// proves Claude Code DISPATCHES tool-calls to it. Pure: given recommendations.jsonl
+// text, the grep/read matchers are "dark" when the edit hook has fired repeatedly
+// (dispatch demonstrably works) but grep AND read never have. Relative sibling
+// comparison → low false-positive (full darkness leaves no file → no claim).
+function analyzeHookDark(recText) {
+  let edit = 0, grepOrRead = 0;
+  for (const line of (recText || '').split('\n')) {
+    if (!line) continue;
+    let ev; try { ev = JSON.parse(line); } catch { continue; }
+    if (ev.hook === 'grep' || ev.hook === 'read') grepOrRead++;
+    else if (ev.hook === 'edit') edit++;
+  }
+  if (edit >= 3 && grepOrRead === 0) {
+    return `[code-graph] The grep/read PreToolUse hooks have recorded nothing in this project,\n` +
+           `            though the edit hook fired ${edit}× — grep/read interception may be dark. Run: code-graph-mcp doctor\n`;
+  }
+  return null;
+}
+
+function detectHookDark() {
+  try {
+    const recPath = path.join(process.cwd(), '.code-graph', 'recommendations.jsonl');
+    return analyzeHookDark(fs.readFileSync(recPath, 'utf8'));
+  } catch { return null; } // no recommendations.jsonl → nothing to conclude
+}
+
 module.exports = {
   launchBackgroundAutoUpdate,
   syncLifecycleConfig,
@@ -627,6 +698,7 @@ module.exports = {
   filterSourceFiles,
   parseGitStatusPaths,
   formatRecentImpact,
+  hookFireWarning, checkHookFiring, analyzeHookDark, detectHookDark, // v0.67.0
 };
 
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.64.0",
+  "version": "0.67.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.64.0",
-    "@sdsrs/code-graph-linux-arm64": "0.64.0",
-    "@sdsrs/code-graph-darwin-x64": "0.64.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.64.0",
-    "@sdsrs/code-graph-win32-x64": "0.64.0"
+    "@sdsrs/code-graph-linux-x64": "0.67.0",
+    "@sdsrs/code-graph-linux-arm64": "0.67.0",
+    "@sdsrs/code-graph-darwin-x64": "0.67.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.67.0",
+    "@sdsrs/code-graph-win32-x64": "0.67.0"
   }
 }