@sdsrs/code-graph 0.163.0 → 0.164.0

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

@@ -88,13 +88,48 @@ const VERB_STRIP = new RegExp(`^\\s*(?:env\\s+)?(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\
 // invisible to the hook so it could never scope the answer to the real target.
 const SRC_PREFIXES =
   'src|tests|lib|libs|scripts|skills|claude-plugin|tools|pkg|cmd|internal|app|apps|components?|server|client|crates|packages|backend|frontend|services|models|domain|controllers|views|handlers|middleware|routes|repositories|entities|migrations|tasks|jobs|workers|features|modules|api|web';
-const SRC_PATH = new RegExp(`(?:^|\\s|["'])(${SRC_PREFIXES})/`);
+// The three source-path tests below are built from SRC_PREFIXES plus the
+// project's own source roots (useSourceRoots), so they are `let`.
+let SRC_PATH;
 // Anchored variant for whole-token matching in extractSearchPath.
-const SRC_PATH_TOKEN = new RegExp(`^(?:\\./)?(${SRC_PREFIXES})/`);
+let SRC_PATH_TOKEN;
 // A path operand the rewrite grammar proved: a bare prefix word (`src`), or a
 // `./`-rooted one with any subpath (`./src`, `./src/x/`), which SRC_PATH's
 // lookbehind never matched.
-const SRC_BARE_TOKEN = new RegExp(`^(?:(?:${SRC_PREFIXES})|\\./(?:${SRC_PREFIXES})(?:/.*)?)$`);
+let SRC_BARE_TOKEN;
+
+// F1 (tasks/specs/grep-hook-source-roots.md) — the prefix list names
+// conventional source dirs, but a Python package lives in a dir named after it
+// (`networkx/`, `django/`): in the 2026-09-28 coding eval not one grep of 15
+// runs reached this hook. The indexer writes the top-level dirs that hold
+// indexed code to `.code-graph/source-roots.json`, and those names join the
+// list. A name must be one plain shell word (no quote, space, slash, leading
+// dot); past MAX_SOURCE_ROOTS the list alone applies, as it does when the file
+// is missing or unreadable.
+const SOURCE_ROOTS_FILE = 'source-roots.json';
+const MAX_SOURCE_ROOTS = 64;
+const SOURCE_ROOT_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.+@-]{0,63}$/;
+const PREFIX_WORDS = new Set(SRC_PREFIXES.replace('components?', 'components|component').split('|'));
+
+function readSourceRoots(root) {
+  if (!root) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(path.join(root, '.code-graph', SOURCE_ROOTS_FILE), 'utf8'));
+  } catch { return []; }
+  const roots = parsed && Array.isArray(parsed.roots) ? parsed.roots : null;
+  if (!roots || roots.length > MAX_SOURCE_ROOTS) return [];
+  return roots.filter((r) => typeof r === 'string' && SOURCE_ROOT_NAME.test(r) && !PREFIX_WORDS.has(r));
+}
+
+function useSourceRoots(roots) {
+  const escaped = (roots || []).map((r) => r.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const alt = [SRC_PREFIXES, ...escaped].join('|');
+  SRC_PATH = new RegExp(`(?:^|\\s|["'])(${alt})/`);
+  SRC_PATH_TOKEN = new RegExp(`^(?:\\./)?(${alt})/`);
+  SRC_BARE_TOKEN = new RegExp(`^(?:(?:${alt})|\\./(?:${alt})(?:/.*)?)$`);
+}
+useSourceRoots([]);
 
 // D#73 — a source dir written as a bare word (`grep -rn X src`, `rg X tests`,
 // `./src`): the shape models write when a prompt says "under src/", and it
@@ -826,6 +861,135 @@ function extractSedReadTargets(cmd) {
   return out;
 }
 
+// Q1 — `sed -i` and `perl -pi` edit files the edit hooks never see. Their
+// targets are logged for the Stop hook's signature check (never answered).
+// Shapes: tasks/specs/edit-log-coverage.md. A word only counts as a target
+// when it names an existing regular file, so a misread costs a few baseline
+// records the Stop check then finds unchanged; a command the tokenizer cannot
+// read exactly (`$x`, globs) is skipped, which is the state before Q1.
+const MAX_IN_PLACE_TARGETS = 8;
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/**
+ * Absolute paths of the files an in-place `sed`/`perl` in `cmd` edits, at
+ * most MAX_IN_PLACE_TARGETS, in command order.
+ * @param {string} cmd
+ * @param {string} shellCwd  where the command starts
+ * @param {{isFile?: (abs:string)=>boolean, isDir?: (abs:string)=>boolean}} [opts]
+ * @returns {string[]}
+ */
+function extractInPlaceEditTargets(cmd, shellCwd, { isFile = isRegularFile, isDir = isDirectory } = {}) {
+  if (!cmd || typeof cmd !== 'string' || cmd.length > 4000 || !/\b(?:sed|perl)\b/.test(cmd)) return [];
+  const segments = splitTopLevelSegments(cmd);
+  const seps = segmentSeparators(cmd);
+  const out = [];
+  for (let i = 0; i < segments.length && out.length < MAX_IN_PLACE_TARGETS; i++) {
+    const words = shellWords(segments[i]);
+    if (!words) continue;
+    let k = 0;
+    while (k < words.length && !words[k].op && !words[k].anyQuoted && ENV_ASSIGNMENT.test(words[k].text)) k++;
+    const head = words[k];
+    if (!head || head.op || head.anyQuoted || (head.text !== 'sed' && head.text !== 'perl')) continue;
+    const args = [];
+    for (let j = k + 1; j < words.length && !words[j].op; j++) args.push(words[j]);
+    const operands = head.text === 'sed' ? sedInPlaceFiles(args) : perlInPlaceFiles(args);
+    if (operands.length === 0) continue;
+    const cwd = segmentCwd(segments, i, shellCwd, { isDir, seps });
+    if (cwd === null) continue;
+    for (const w of operands) {
+      const abs = path.resolve(cwd, w);
+      if (!out.includes(abs) && out.length < MAX_IN_PLACE_TARGETS && isFile(abs)) out.push(abs);
+    }
+  }
+  return out;
+}
+
+// Quoting does not decide what is an option: the shell removes the quotes
+// before sed or perl sees `--expression='s/a/b/'` or `'-i'`.
+//
+// Plain operand words, a redirect and its target dropped. A word with a bare
+// glob or redirect character is not a file name the shell passes unchanged.
+function operandWords(words) {
+  const out = [];
+  for (let j = 0; j < words.length; j++) {
+    const w = words[j];
+    if (w.bareOp) {
+      if (/[<>]$/.test(w.text)) j++;  // `> out`: the next word is the redirect's target
+      continue;
+    }
+    if (!w.bareSpecial) out.push(w.text);
+  }
+  return out;
+}
+
+// GNU sed: `-i[SUFFIX]` / `--in-place[=SUFFIX]` (a suffix is attached, so in a
+// cluster the rest of the word is it: `-ie` = suffix `e`); `-e`/`-f`/`-l` and
+// their long forms take a value. The first operand is the script unless `-e`
+// or `-f` gave one. BSD `-i ''` reads as GNU `-i` with script `''`, and its
+// real script then fails the existing-file test.
+function sedInPlaceFiles(words) {
+  let inPlace = false;
+  let haveScript = false;
+  let endOfOpts = false;
+  const operands = [];
+  for (let j = 0; j < words.length; j++) {
+    const w = words[j];
+    const t = w.text;
+    if (endOfOpts || !t.startsWith('-') || t === '-') { operands.push(w); continue; }
+    if (t === '--') { endOfOpts = true; continue; }
+    if (t.startsWith('--')) {
+      const [name, value] = [t.slice(2).split('=')[0], t.includes('=')];
+      if (name === 'in-place') inPlace = true;
+      else if (name === 'expression' || name === 'file') { haveScript = true; if (!value) j++; }
+      else if (name === 'line-length' && !value) j++;
+      continue;
+    }
+    for (let c = 1; c < t.length; c++) {
+      const ch = t[c];
+      if (ch === 'i') { inPlace = true; break; }
+      if (ch === 'e' || ch === 'f' || ch === 'l') {
+        if (ch !== 'l') haveScript = true;
+        if (c === t.length - 1) j++;
+        break;
+      }
+    }
+  }
+  if (!inPlace) return [];
+  return operandWords(haveScript ? operands : operands.slice(1));
+}
+
+// perl: `-i[EXT]` (the rest of the word is the extension: `-pie` = `-p -i`
+// with extension `e`); `-e`/`-E` take the code (rest of the word, else the
+// next word), `-M`/`-I`/`-F` a value the same way. With no `-e`, the first
+// operand is the script file.
+function perlInPlaceFiles(words) {
+  let inPlace = false;
+  let haveCode = false;
+  let endOfOpts = false;
+  const operands = [];
+  for (let j = 0; j < words.length; j++) {
+    const w = words[j];
+    const t = w.text;
+    if (endOfOpts || !t.startsWith('-') || t === '-') { operands.push(w); continue; }
+    if (t === '--') { endOfOpts = true; continue; }
+    for (let c = 1; c < t.length; c++) {
+      const ch = t[c];
+      if (ch === 'i') { inPlace = true; break; }
+      if ('eEMIF'.includes(ch)) {
+        if (ch === 'e' || ch === 'E') haveCode = true;
+        if (c === t.length - 1) j++;
+        break;
+      }
+    }
+  }
+  if (!inPlace) return [];
+  return operandWords(haveCode ? operands : operands.slice(1));
+}
+
+function isRegularFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
 // v0.50 — a compound command (`grep …; sed -n 1,60p f` / `grep … && wc`) is
 // denied WHOLE, but the answer covers only the grep. The 2026-06-13 mem-project
 // deny swallowed a `; sed` read while the copy said "use these results directly
@@ -1120,7 +1284,7 @@ function buildHint() {
     '  • code-graph-mcp ast-search "<pat>" --type fn # filter by type/returns/params',
     '  • code-graph-mcp callgraph SYMBOL             # callers + callees, repo-wide',
     '  • code-graph-mcp show SYMBOL                  # one symbol: signature + source',
-    'Repo-wide index (LSP only sees open files). Skip this hint if you specifically need raw-text regex.',
+    'Repo-wide index. Skip this hint if you specifically need raw-text regex.',
   ].join('\n');
 }
 
@@ -1459,7 +1623,48 @@ function rgIgnoreAbove(dir) {
 function isSymlink(p, { missing = true } = {}) {
   try { return fs.lstatSync(p).isSymbolicLink(); } catch { return missing; }
 }
-function searchesSameFiles({ root, target, verb, show = false } = {}) {
+// F1b — `grep -r` reads git-ignored files and the rewrite does not, so an
+// ignored entry under the path declines. The one nearly every Python tree has
+// once its tests ran is a `__pycache__/` of `.pyc` files (the coding-eval
+// fixtures carry 286), and a binary file yields no matched line: grep notes
+// "binary file matches" instead (stderr in GNU grep 3.5+, stdout in BSD grep
+// and ugrep), a notice, not a hit. So a bytecode cache may differ between the
+// two — for a grep that does not list files (see grepListsBinaryMatches).
+const BYTECODE_FILE = /\.py[co]$/;
+function isBytecodeCache(root, rel) {
+  const r = rel.replace(/\/+$/, '');
+  if (BYTECODE_FILE.test(r)) return true;
+  if (path.posix.basename(r) !== '__pycache__') return false;
+  let entries;
+  try { entries = fs.readdirSync(path.join(root, r), { withFileTypes: true }); } catch { return false; }
+  return entries.length <= WALK_LIMIT && entries.every((e) => e.isFile() && BYTECODE_FILE.test(e.name));
+}
+
+/// True when the grep would PRINT a matching binary file: it lists files
+/// (`-l`, `--files-with-matches`) and does not skip binaries (`-I`). The
+/// rewrite grammar admits no other output mode that prints one for grep
+/// (`-c`, `-L`, `-a`, `-o` are refused). Only the grep's own clause counts.
+function grepListsBinaryMatches(cmd) {
+  const words = clauseWords(firstShellClause(cmd || '').replace(VERB_STRIP, ''));
+  if (!words) return true;
+  let lists = false;
+  let skipsBinary = false;
+  // Quoted words count too: the shell strips the quotes and grep still reads
+  // `"-l"` as an option. A quoted PATTERN that merely contains ` -l ` has a
+  // space in it and never matches the one-cluster shape below.
+  for (const w of words) {
+    const t = w.text;
+    if (t === '--files-with-matches') lists = true;
+    else if (t === '--binary-files=without-match') skipsBinary = true;
+    else if (/^-[A-Za-z0-9]+$/.test(t)) {
+      if (t.includes('l')) lists = true;
+      if (t.includes('I')) skipsBinary = true;
+    }
+  }
+  return lists && !skipsBinary;
+}
+
+function searchesSameFiles({ root, target, verb, show = false, binaryCacheOk = false } = {}) {
   if (!root || !['grep', 'git', 'rg', 'ag'].includes(verb)) return false;
   const rel = target === undefined ? '' : String(target).replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
   if (rel.split('/').includes('..') || path.isAbsolute(rel)) return false;
@@ -1503,7 +1708,8 @@ function searchesSameFiles({ root, target, verb, show = false } = {}) {
     const anyHidden = (l) => l.some((f) => HIDDEN_SEGMENT.test(f));
     let reads;
     if (verb === 'grep') {
-      if (anyHidden(others) || ignoredOthers.length || ignoredTracked.length) return false;
+      const ignored = binaryCacheOk ? ignoredOthers.filter((f) => !isBytecodeCache(root, f)) : ignoredOthers;
+      if (anyHidden(others) || ignored.length || ignoredTracked.length) return false;
       reads = [...tracked, ...others];
     } else if (verb === 'git') {
       if (others.length) return false;
@@ -1998,15 +2204,17 @@ function isAnswerDisabled(env = process.env) {
 // Smallest per-dir share of the context cap worth spending on an overview answer.
 const MIN_FANOUT_ANSWER_BYTES = 400;
 
-/// Byte budget for each overview answer when several dirs fire in one command
-/// (undefined for one dir: the answer keeps its own default). Every hint first
+/// Byte budget for each overview answer of the dirs that fire in one command.
+/// A single dir is budgeted too: left at the answer's own 4,000-byte default,
+/// its header pushed the hint past the envelope cap and the overview was
+/// replaced by a bare "5+ Reads also into …" line (hook audit P2-5). Every hint first
 /// pays for its own lines — an answer's header, footer and separator are about
 /// 175 bytes plus the dir name twice, the one-line advice about 165 plus the
 /// name three times — reserved as 200 plus the name three times, and the
 /// answers share what is left of the cap. A share under MIN_FANOUT_ANSWER_BYTES
 /// returns 0: every dir then gets the one-line advice instead.
 function fanoutAnswerBudget(dirs) {
-  if (dirs.length < 2) return undefined;
+  if (dirs.length < 1) return undefined;
   const reserved = dirs.reduce((sum, d) => sum + 200 + 3 * Buffer.byteLength(d, 'utf8'), 0);
   const share = Math.floor((MAX_INJECTED_BYTES - reserved) / dirs.length);
   return share >= MIN_FANOUT_ANSWER_BYTES ? share : 0;
@@ -2039,6 +2247,7 @@ function runMain() {
   const shellCwd = process.cwd();
   const root = resolveProjectRoot(shellCwd);
   if (root === null) return;  // no index anywhere up to $HOME — no hint
+  useSourceRoots(readSourceRoots(root));
 
   let input;
   try {
@@ -2050,6 +2259,18 @@ function runMain() {
 
   const rawCmd = (input.tool_input && input.tool_input.command) || '';
 
+  // Q1 — an in-place `sed`/`perl` is logged for the Stop check, then the
+  // command goes on as it would have (nothing here answers or rewrites it).
+  const inPlace = extractInPlaceEditTargets(rawCmd, shellCwd);
+  if (inPlace.length > 0) {
+    const sessionEdits = require('./session-edits');
+    for (const abs of inPlace) {
+      const rel = path.relative(root, abs);
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+      sessionEdits.recordFileEdit(root, input.session_id, rel.split(path.sep).join('/'));
+    }
+  }
+
   // v0.49 — sed-range reads count toward the read-fanout state (the Read hook
   // never sees Bash-side file reads). A fired fanout hint already delivered an
   // overview — skip grep hinting for this command to avoid double output.
@@ -2077,8 +2298,15 @@ function runMain() {
     }
     if (firedDirs.length > 0) {
       const maxBytes = fanoutAnswerBudget(firedDirs);
-      const hints = firedDirs.map((dir) => readGuide.buildFanoutHint(root, dir, { maxBytes }));
-      process.stdout.write(emitPreToolContext(joinFanoutHints(firedDirs, hints)) + '\n');
+      // A dir with no overview contributes nothing (buildFanoutHint → null);
+      // it stays marked, so it does not fire again.
+      const answered = firedDirs
+        .map((dir) => ({ dir, hint: readGuide.buildFanoutHint(root, dir, { maxBytes }) }))
+        .filter((h) => h.hint !== null);
+      if (answered.length > 0) {
+        process.stdout.write(emitPreToolContext(
+          joinFanoutHints(answered.map((h) => h.dir), answered.map((h) => h.hint))) + '\n');
+      }
       return;
     }
   }
@@ -2232,6 +2460,7 @@ function runMain() {
     // D#133, H-2).
     if (plan && !searchesSameFiles({
       root, target: extractSearchPath(cmd), verb: plan.verb, show: answeredMode === 'show',
+      binaryCacheOk: !grepListsBinaryMatches(cmd),
     })) return;
 
     const answered = answer.status === 'hits';
@@ -2311,6 +2540,8 @@ if (require.main === module) {
 }
 
 module.exports = {
+  grepListsBinaryMatches,
+  useSourceRoots, readSourceRoots, MAX_SOURCE_ROOTS,
   shouldHint,
   shouldBlock,
   classifyBlock,         // v0.49 — intent-aware block tiers
@@ -2330,6 +2561,7 @@ module.exports = {
   segmentCwd,            // D#76 — the directory a compound command's segment runs in
   segmentSeparators,     // D#76 — the separator before each top-level segment
   extractSedReadTargets, // v0.49 — sed-range reads feed the read-fanout state
+  extractInPlaceEditTargets, // Q1 — `sed -i` / `perl -pi` targets feed the Stop check's edit log
   extractUnansweredTail, // v0.50 — compound-tail honesty in answered denies
   extractPatterns,    // v0.32.1 — exposed for tests
   countNamedPaths,    // v0.70 — multi-path deny→hint downgrade

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

@@ -19,8 +19,9 @@ if (require.main === module) require('./hook-fail-open').installHookFailOpen('Pr
 //   2. file_path is under CWD (no escape to absolute paths outside the project)
 //   3. file_path is not at CWD root (top-level files = config / one-off scripts)
 //   4. .code-graph/index.db exists in CWD (project is indexed)
-//   5. ≥5 prior Reads to the SAME parent dir tracked in /tmp state
-//   6. Same-dir cooldown not active (5 min)
+//   5. ≥5 DISTINCT files read in the SAME parent dir, tracked in /tmp state
+//   6. The dir has not fired before while its state entry lives
+//   7. The CLI delivers an overview for the dir (no advice-only line)
 //
 // State scoping: per-cwd (NOT per-session). Cost: two concurrent sessions in
 // the same project might share counters and over-trigger by ~1 hint each.
@@ -35,22 +36,17 @@ const path = require('path');
 const crypto = require('crypto');
 const { cgTmpDir } = require('./tmp-dir');
 const { recordRecommendation } = require('./recommendation-log');
-const { resolveProjectRoot } = require('./project-root');
+const { resolveProjectRoot, indexBuildInProgress } = require('./project-root');
 const { runOverviewAnswer } = require('./cg-answer');
 const { emitPreToolAllowContext } = require('./hook-emit');
 
 // --- Configuration ---
 
-// Hint fires on the (FANOUT_THRESHOLD + 1)-th Read into the same dir.
+// Hint fires on the (FANOUT_THRESHOLD + 1)-th DISTINCT file read in the same dir.
 // Set so that 4 reads stay quiet (legitimate "read a couple files to
-// understand X" pattern); 5+ reads is the fanout we want to catch.
+// understand X" pattern); 5+ files is the fanout we want to catch.
 const FANOUT_THRESHOLD = 4;
 
-// Per-dir cooldown after firing a hint. Prevents spam if Claude keeps
-// reading the same dir after seeing the hint (e.g., still has 3 more
-// files queued from a prior plan).
-const COOLDOWN_MS = 5 * 60 * 1000;
-
 // Entries older than this are pruned on load. Long enough to survive
 // normal multi-step tasks (15-20 min typical), short enough that stale
 // per-cwd state doesn't accumulate across days.
@@ -104,11 +100,23 @@ function saveState(cwd, state) {
   } catch { /* ok */ }
 }
 
-function recordRead(state, dir, now = Date.now()) {
+// Distinct files remembered per dir. Past this the count is already far over
+// the threshold, so the list stops growing and so does the state file.
+const MAX_FILES_PER_DIR = 32;
+
+/// Count a read of `file` (when given) in `dir`. Re-reading one file does not
+/// count again: five chunked reads of one big file are not a fanout, and they
+/// fired an overview of its whole parent dir (hook audit 2026-09-28).
+function recordRead(state, dir, now = Date.now(), file) {
   if (!state.by_dir[dir]) state.by_dir[dir] = { reads: 0, last_read_at: 0, last_hint_at: 0 };
   const e = state.by_dir[dir];
-  e.reads += 1;
   e.last_read_at = now;
+  if (file) {
+    if (!Array.isArray(e.files)) e.files = [];
+    if (e.files.includes(file)) return;
+    if (e.files.length < MAX_FILES_PER_DIR) e.files.push(file);
+  }
+  e.reads += 1;
 }
 
 function shouldHint(state, dir, now = Date.now()) {
@@ -116,7 +124,10 @@ function shouldHint(state, dir, now = Date.now()) {
   const e = state.by_dir[dir];
   if (!e) return false;
   if (e.reads < FANOUT_THRESHOLD + 1) return false;  // need >=5
-  if (e.last_hint_at && (now - e.last_hint_at < COOLDOWN_MS)) return false;
+  // Once per dir while its entry lives (pruned STATE_TTL_MS after the last
+  // read). The old 5-minute re-fire re-sent the same overview: 31.7% of fanout
+  // hints in 2026-09 sessions repeated a text the session already had.
+  if (e.last_hint_at) return false;
   return true;
 }
 
@@ -125,18 +136,13 @@ function markHint(state, dir, now = Date.now()) {
   state.by_dir[dir].last_hint_at = now;
 }
 
-function buildHint(dir) {
-  // Single-line, ~190-byte budget. Skip-clause matches pre-grep-guide voice.
-  return `[code-graph] 5+ Reads into ${dir}/ — \`code-graph-mcp overview ${dir}/\` gives symbols+callers in one call (MCP: \`module_overview path=${dir}\`). Skip if you need raw file contents.`;
-}
-
 // v0.49 — the hint DELIVERS the overview instead of advising a tool call
 // (advice measured 0/40 transfer on 2026-06-12; delivered answers satisfied
 // 5/5 in place). Falls back to the advice-only line when the CLI is
 // unavailable or the dir has no overview.
 function buildHintWithAnswer(dir, answer) {
   const lines = [
-    `[code-graph] 5+ Reads into ${dir}/ — module overview from the AST index (saves the remaining file-by-file reads):`,
+    `[code-graph] 5+ Reads into ${dir}/ — module overview from the AST index:`,
     answer.text,
   ];
   if (answer.truncated) {
@@ -167,9 +173,11 @@ function trackRead(root, rel, now = Date.now()) {
   if (!dir || dir === '.' || dir === '') return null;  // top-level file: not fanout
 
   const state = loadState(root, now);
-  recordRead(state, dir, now);
+  recordRead(state, dir, now, rel);
   let fired = false;
-  if (shouldHint(state, dir, now)) {
+  // During the startup build the overview would list part of the dir as the
+  // whole module (D5); leave the hint unspent for the first read after it.
+  if (!indexBuildInProgress(root, now) && shouldHint(state, dir, now)) {
     markHint(state, dir, now);
     fired = true;
   }
@@ -184,9 +192,15 @@ function trackRead(root, rel, now = Date.now()) {
   return dir;
 }
 
-/// The fanout hint text for `dir`, with the overview answer embedded when the
-/// CLI delivers one. `maxBytes` bounds that answer — the pre-grep sed path
-/// splits one envelope's budget between several dirs.
+/// The fanout hint text for `dir` with the overview answer embedded, or null
+/// when the CLI delivers none. `maxBytes` bounds that answer — the pre-grep sed
+/// path splits one envelope's budget between several dirs.
+///
+/// No overview, no hint. The advice-only line measured no effect twice: 0/40
+/// transfer on 2026-06-12, and 18/672 follow-through against a 2.76% baseline in
+/// 2026-09 sessions, where 572 of the 672 advised `overview tests/` — which
+/// answers "No symbols found", since overview leaves test symbols out. The
+/// unanswered hint is still recorded, so the funnel keeps its reasons.
 function buildFanoutHint(root, dir, { maxBytes } = {}) {
   let answer = { status: 'unavailable' };
   if (maxBytes === 0) {
@@ -212,11 +226,11 @@ function buildFanoutHint(root, dir, { maxBytes } = {}) {
     ...(answered ? {} : { reason: answer.status }),
     ...(answered || !answer.reason ? {} : { fallthrough_reason: answer.reason }),
   });
-  return answered ? buildHintWithAnswer(dir, answer) : buildHint(dir);
+  return answered ? buildHintWithAnswer(dir, answer) : null;
 }
 
 /// trackRead + buildFanoutHint for one read. Returns the hint text when the
-/// hint fired, else null. The caller emits it.
+/// hint fired with an overview, else null. The caller emits it.
 function trackReadAndMaybeHint(root, rel, now = Date.now()) {
   const dir = trackRead(root, rel, now);
   return dir === null ? null : buildFanoutHint(root, dir);
@@ -263,8 +277,8 @@ if (require.main === module) {
 module.exports = {
   isSourceFile, dirOf, cwdHash, statePath,
   loadState, saveState, recordRead, shouldHint, markHint,
-  buildHint, buildHintWithAnswer, isSilenced, isAnswerDisabled,
+  buildHintWithAnswer, isSilenced, isAnswerDisabled,
   trackReadAndMaybeHint,   // v0.49 — shared with pre-grep-guide's sed-range path
   trackRead, buildFanoutHint,  // the sed path's two halves: one envelope for every dir that fired
-  FANOUT_THRESHOLD, COOLDOWN_MS, STATE_TTL_MS, SRC_EXT,
+  FANOUT_THRESHOLD, STATE_TTL_MS, SRC_EXT,
 };

package/claude-plugin/scripts/project-root.js

@@ -124,4 +124,26 @@ function resolveProjectRoot(startDir, opts = {}) {
   return null;
 }
 
-module.exports = { resolveProjectRoot };
+// True while the MCP server's startup index is still being written for `root`.
+// The server writes `.code-graph/indexing-status.json` ({s, d, t}) and heartbeats
+// it per batch and per finalize phase, then removes it. Until then the index is
+// partial, and a structural answer from it is wrong, not just short: 0.3 s into
+// a cold networkx build `impact edge_betweenness_centrality` said "0 callers,
+// Risk UNKNOWN"; the finished index has 4 callers, MEDIUM (2026-09-29, D5).
+// Same test as statusline.js, whose INDEXING_STALE_MS mirrors the Rust
+// INDEXING_STATUS_STALE_SECS: an older file was left by a killed server.
+const INDEXING_STALE_MS = 120000;
+
+function indexBuildInProgress(root, now = Date.now()) {
+  if (!root) return false;
+  const file = path.join(root, '.code-graph', 'indexing-status.json');
+  try {
+    if (now - fs.statSync(file).mtimeMs >= INDEXING_STALE_MS) return false;
+    const p = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return (p.s === 'indexing' || p.s === 'finalizing') && p.t > 0;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { resolveProjectRoot, indexBuildInProgress, INDEXING_STALE_MS };

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 'use strict';
-// Per-session edit log shared by the PreToolUse(Edit) hook (writer) and the
-// Stop hook (reader) — P1 #3.
+// Per-session edit log shared by the PreToolUse hooks (writers: pre-edit-guide
+// for Edit/Write, pre-grep-guide for `sed -i`/`perl -pi`) and the
+// Stop hook (reader) — P1 #3, Q1.
 //
 // Two files per (project, session), both in the shared cgTmpDir() so the
 // SessionStart prune (24 h, mtime) and `uninstall`'s wholesale removal of that
@@ -84,6 +85,59 @@ function recordEdit(root, sessionId, { file, symbol = null }, now = Date.now())
   } catch { return false; }
 }
 
+// Q1: an edit that names no definition (Write over an existing file, `sed -i`,
+// `perl -pi`) baselines the file's definitions at once. Bounded so the hook
+// stays inside its budget: a larger file is logged as a file only, and at
+// most this many definitions — the first in the file — get a record.
+const MAX_FILE_SCAN_BYTES = 256 * 1024;
+const MAX_FILE_DEFINITIONS = 64;
+
+/**
+ * Log an edit that names no definition: one file record, then one baselined
+ * record per definition of the file as it is now (before the edit). With
+ * `newText` (a Write's content) only definitions whose header the new text
+ * changes are recorded — the Stop hook would find the rest unchanged. Without
+ * it (`sed -i`: the result is unknown until the command runs) every
+ * definition is, and the Stop hook sorts them out. One append, best-effort.
+ * @param {string} root project root
+ * @param {string} sessionId
+ * @param {string} file root-relative
+ * @param {{newText?: string|null}} [opts]
+ * @returns {number} records written
+ */
+function recordFileEdit(root, sessionId, file, { newText = null } = {}, now = Date.now()) {
+  const p = editsPath(root, sessionId);
+  if (!p || !file) return 0;
+  const recs = [{ ts: now, file, symbol: null }];
+  for (const [symbol, sigs] of fileBaselines(root, file, newText)) recs.push({ ts: now, file, symbol, sigs });
+  try {
+    fs.appendFileSync(p, recs.map((r) => JSON.stringify(r) + '\n').join(''));
+    return recs.length;
+  } catch { return 0; }
+}
+
+function fileBaselines(root, file, newText) {
+  try {
+    const abs = path.join(root, file);
+    if (fs.statSync(abs).size > MAX_FILE_SCAN_BYTES) return [];
+    const { allSignatures, extractSignatures, signatureChanged } = require('./stop-impact');
+    const ext = path.extname(file).toLowerCase();
+    const all = allSignatures(fs.readFileSync(abs, 'utf8'), ext);
+    if (!all) return [];
+    const out = [];
+    for (const [symbol, sigs] of all) {
+      if (out.length === MAX_FILE_DEFINITIONS) break;
+      if (sigs.length > MAX_BASELINE_SIGS) continue;
+      if (typeof newText === 'string') {
+        const after = extractSignatures(newText, symbol, ext);
+        if (!after || after.length === 0 || !signatureChanged(sigs, after, symbol)) continue;
+      }
+      out.push([symbol, sigs]);
+    }
+    return out;
+  } catch { return []; }
+}
+
 /** Every well-formed record in the session log; a torn or foreign line is skipped. */
 function readEdits(root, sessionId) {
   const p = editsPath(root, sessionId);
@@ -137,5 +191,6 @@ function writeStopState(root, sessionId, state) {
 }
 
 module.exports = {
-  sessionKey, editsPath, stopStatePath, recordEdit, readEdits, readStopState, writeStopState,
+  sessionKey, editsPath, stopStatePath, recordEdit, recordFileEdit, readEdits, readStopState, writeStopState,
+  MAX_FILE_DEFINITIONS,
 };