@vizalice/codegraph 1.5.0

package/scripts/agent-eval/probe-named-symbol.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * "Did the symbol the agent NAMED actually render?" (CG-38).
+ *
+ * This is the measurement the whole CG-24 epic was missing. Every other probe
+ * here scores the response in AGGREGATE — `probe-suite-envelope.mjs` measures how
+ * much source came back, `probe-file-spend.mjs` measures whether the bytes went
+ * to the files that earned them, `probe-allocation.mjs` measures group shares.
+ * All three are green on a response that returns 25K of source from the right
+ * file and still omits the one function the agent asked for by name. That is
+ * exactly what CG-38 was: `queueMessage` at L1087 of a 1,414-line file, whose
+ * file won rank #1 with 67% of the envelope, never rendered — the agent got a
+ * same-stem `QueuedMessage` INTERFACE at L70 instead and had to Read the file.
+ *
+ * So the assertion here is per-SYMBOL and binary: for each named symbol, does its
+ * definition line appear in the rendered source? Nothing else can substitute —
+ * not the file being present, not its share, not its byte count.
+ *
+ * Usage (needs a current `npm run build`):
+ *   node scripts/agent-eval/probe-named-symbol.mjs
+ *   node scripts/agent-eval/probe-named-symbol.mjs --verbose
+ *   # any indexed repo, ad hoc:
+ *   node scripts/agent-eval/probe-named-symbol.mjs <repo> "<query>" sym1 sym2
+ *
+ * Exit code is 1 when any expected symbol is missing, so this can gate.
+ */
+import { cpSync, mkdtempSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, '..', '..');
+
+const load = async (rel) => import(pathToFileURL(resolve(REPO, rel)).href);
+const idxMod = await load('dist/index.js');
+const toolsMod = await load('dist/mcp/tools.js');
+const CodeGraph = idxMod.default?.default ?? idxMod.default ?? idxMod.CodeGraph;
+const { ToolHandler } = toolsMod;
+
+/**
+ * The fixture cases. `symbols` are what the agent names; each must come back with
+ * its DEFINITION rendered. The queries deliberately cover both shapes the bug was
+ * reported on — a bare symbol bag and a prose question — because the failure had
+ * a different cause on each and a fix for one does not imply the other.
+ */
+const FIXTURE = '__tests__/fixtures/tail-render-ts';
+const CASES = [
+  {
+    id: 'tail-symbol-bag',
+    why: 'two sibling closures past L1000, named directly; neither calls the other',
+    query: 'queueMessage flushQueuedMessages',
+    symbols: ['queueMessage', 'flushQueuedMessages'],
+  },
+  {
+    id: 'tail-prose',
+    why: 'same two symbols named inside a prose question',
+    query: 'how does queueMessage hand its entries to flushQueuedMessages',
+    symbols: ['queueMessage', 'flushQueuedMessages'],
+  },
+  {
+    id: 'tail-with-decoy',
+    why: 'the same-stem QueuedMessage interface at L70 must not stand in for the functions',
+    query: 'explain queueMessage, removeQueuedMessage and flushQueuedMessages',
+    symbols: ['queueMessage', 'removeQueuedMessage', 'flushQueuedMessages'],
+  },
+];
+
+/** Every `<n>\t<text>` line number present in the response's source blocks. */
+function renderedLines(response) {
+  const out = new Set();
+  for (const m of response.matchAll(/^(\d+)\t/gm)) out.add(Number(m[1]));
+  return out;
+}
+
+/**
+ * A symbol counts as rendered only when its DECLARATION line is among the lines
+ * the response actually sent — not when its name merely appears somewhere (it
+ * shows up in the section header symbol list and in call sites regardless, which
+ * is precisely how this defect hid for a whole epic).
+ */
+function check(cg, response, names) {
+  const lines = renderedLines(response);
+  return names.map((name) => {
+    const node = (cg.getNodesByName?.(name) ?? []).find((n) => n.startLine > 0);
+    return {
+      name,
+      file: node?.filePath ?? '(not indexed)',
+      line: node?.startLine ?? 0,
+      rendered: !!node && lines.has(node.startLine),
+    };
+  });
+}
+
+async function runCase(root, { query, symbols }) {
+  const cg = CodeGraph.openSync(root);
+  try {
+    const res = await new ToolHandler(cg).execute('codegraph_explore', { query });
+    const response = res.content?.[0]?.text ?? '';
+    return { response, results: check(cg, response, symbols) };
+  } finally {
+    try { cg.close?.(); } catch { /* already closed */ }
+  }
+}
+
+const argv = process.argv.slice(2);
+const verbose = argv.includes('--verbose');
+const positional = argv.filter((a) => !a.startsWith('--'));
+
+let failures = 0;
+let checked = 0;
+
+if (positional.length >= 3) {
+  // Ad-hoc mode: <repo> "<query>" sym...
+  const [repo, query, ...symbols] = positional;
+  const { response, results } = await runCase(resolve(repo), { query, symbols });
+  console.log(`\n${repo}\n  query "${query}"  ·  ${response.length} chars\n`);
+  for (const r of results) {
+    checked += 1;
+    if (!r.rendered) failures += 1;
+    console.log(`   ${r.rendered ? 'PASS' : 'FAIL'}  ${r.name}  ${r.file}:${r.line}`);
+  }
+} else {
+  const src = join(REPO, FIXTURE);
+  if (!existsSync(src)) {
+    console.error(`fixture missing: ${src}`);
+    process.exit(2);
+  }
+  const dir = mkdtempSync(join(tmpdir(), 'cg-named-'));
+  try {
+    cpSync(src, dir, { recursive: true });
+    rmSync(join(dir, '.codegraph'), { recursive: true, force: true });
+    const cg = CodeGraph.initSync(dir);
+    await cg.indexAll();
+    cg.close?.();
+
+    console.log(`\ntail-render-ts  ·  agent-named symbols must render\n`);
+    for (const c of CASES) {
+      const { response, results } = await runCase(dir, c);
+      console.log(`── ${c.id} — ${c.why}`);
+      console.log(`   query   "${c.query}"`);
+      console.log(`   response ${response.length.toLocaleString()} chars`);
+      for (const r of results) {
+        checked += 1;
+        if (!r.rendered) failures += 1;
+        console.log(`   ${r.rendered ? 'PASS' : 'FAIL'}  ${r.name} defined at ${r.file}:${r.line}`
+          + (r.rendered ? '' : '  — DEFINITION NOT IN RESPONSE'));
+      }
+      if (verbose && failures) {
+        const spans = [...renderedLines(response)].sort((a, b) => a - b);
+        console.log(`   rendered lines: ${spans[0]}..${spans[spans.length - 1]} (${spans.length} lines)`);
+      }
+      console.log();
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+console.log(failures === 0
+  ? `Every agent-named symbol rendered (${checked} checked).`
+  : `${failures} of ${checked} agent-named symbols did NOT render.`);
+process.exit(failures === 0 ? 0 : 1);

package/scripts/agent-eval/probe-node.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Probe codegraph_node (with trail) against an index using the built dist.
+// Usage: node probe-node.mjs <repo-with-.codegraph> <symbol> [code]
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, symbol, code] = process.argv;
+if (!repo || !symbol) { console.error('usage: probe-node.mjs <repo> <symbol> [code]'); process.exit(1); }
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+const cg = CodeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('codegraph_node', { symbol, includeCode: code === 'code' });
+console.log(res.content?.[0]?.text ?? '(no text)');
+try { cg.close?.(); } catch {}

package/scripts/agent-eval/probe-suite-envelope.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * Deterministic 6-repo envelope sweep for `codegraph_explore` (CG-26).
+ *
+ * The allocation issues (CG-30 / CG-31 / CG-26) are all decided by how the
+ * render loop divides a fixed byte ceiling, and the agent A/B is far too noisy
+ * to see a 2K byte shift. This runs the SAME six queries the CG-30 and CG-31
+ * benchmark tables use, against the same clean-rebuilt corpus indexes, and
+ * prints the numbers those tables are made of: source chars delivered, files in
+ * the final output, whether the hard ceiling cut anything, and whether the
+ * epilogue survived.
+ *
+ * Numbers come from the CG-4 diagnostic (`CODEGRAPH_EXPLORE_DEBUG`), so this
+ * measures the shipping allocator rather than re-deriving shares from markdown.
+ *
+ * Usage (needs a current `npm run build`, and full-REBUILT indexes — CG-33):
+ *   node scripts/agent-eval/probe-suite-envelope.mjs
+ *   node scripts/agent-eval/probe-suite-envelope.mjs --json > /tmp/new.json
+ *   node scripts/agent-eval/probe-suite-envelope.mjs --baseline /tmp/base.json
+ *   CORPUS=/tmp/codegraph-corpus node scripts/agent-eval/probe-suite-envelope.mjs
+ */
+import { mkdtempSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const CORPUS = process.env.CORPUS ?? '/tmp/codegraph-corpus';
+
+/** The six suite repos + the exact queries the CG-30/CG-31 tables were measured on. */
+const SUITE = [
+  { id: 'django', q: 'How does a QuerySet turn into SQL and fetch rows from the database?' },
+  { id: 'excalidraw', q: 'How does updating an element re-render the canvas on screen?' },
+  { id: 'okhttp', q: 'How does a call go through the interceptor chain to the network?' },
+  { id: 'tokio', q: 'How does a spawned task get scheduled and run by a worker?' },
+  { id: 'gin', q: 'How does a registered route handler get invoked for an incoming HTTP request?' },
+  { id: 'alamofire', q: 'How does a request get built and sent through the session?' },
+];
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const baselineAt = argv.includes('--baseline') ? argv[argv.indexOf('--baseline') + 1] : null;
+const only = argv.filter((a) => !a.startsWith('--') && a !== baselineAt);
+
+const say = (s = '') => { if (!asJson) console.log(s); };
+const num = (n) => Math.round(n).toLocaleString('en-US');
+
+const load = (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const toolsMod = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = toolsMod.ToolHandler ?? toolsMod.default?.ToolHandler;
+if (typeof CodeGraph?.openSync !== 'function' || typeof ToolHandler !== 'function') {
+  console.error('could not resolve CodeGraph/ToolHandler from dist/ — run `npm run build`');
+  process.exit(2);
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'cg-suite-'));
+const results = [];
+try {
+  for (const { id, q } of SUITE) {
+    if (only.length > 0 && !only.includes(id)) continue;
+    const repo = join(CORPUS, id);
+    if (!existsSync(join(repo, '.codegraph', 'codegraph.db'))) {
+      say(`${id}: no index at ${repo} — skipped`);
+      continue;
+    }
+    const sidecar = join(tmp, `${id}.jsonl`);
+    process.env.CODEGRAPH_EXPLORE_DEBUG = sidecar;
+    const cg = CodeGraph.openSync(repo);
+    const h = new ToolHandler(cg);
+    const res = await h.execute('codegraph_explore', { query: q });
+    const text = res.content?.[0]?.text ?? '';
+    try { cg.close?.(); } catch { /* best effort */ }
+    const report = JSON.parse(readFileSync(sidecar, 'utf8').trim().split('\n').pop());
+    results.push({
+      repo: id,
+      sourceChars: report.envelope.sourceChars,
+      envelopeChars: report.envelope.chars,
+      allocatedChars: report.envelope.allocatedChars,
+      hardCeiling: report.budget.hardCeiling,
+      truncated: report.envelope.truncated,
+      files: report.selection.filesInFinalOutput,
+      // Did the response keep its trailing pointer list / notes, or did the
+      // hard ceiling spend them? This is CG-26's residual 1.
+      epilogueCut: text.includes('omitted for size'),
+      sectionCut: text.includes('output truncated to budget'),
+      notShown: text.includes('Not shown above'),
+      budgetNote: text.includes('**Explore budget:'),
+    });
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+if (asJson) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  const base = baselineAt ? JSON.parse(readFileSync(baselineAt, 'utf8')) : null;
+  const byRepo = new Map((base ?? []).map((r) => [r.repo, r]));
+  say('repo         source     Δ        env      files  cut          epilogue');
+  say('-'.repeat(74));
+  for (const r of results) {
+    const b = byRepo.get(r.repo);
+    const delta = b ? (r.sourceChars - b.sourceChars) : null;
+    const dStr = delta === null ? '' : (delta > 0 ? `+${num(delta)}` : num(delta));
+    const cut = r.sectionCut ? 'section' : r.epilogueCut ? 'epilogue' : '—';
+    const epi = [r.notShown ? 'not-shown' : null, r.budgetNote ? 'budget-note' : null]
+      .filter(Boolean).join('+') || 'none';
+    say(
+      `${r.repo.padEnd(12)} ${num(r.sourceChars).padStart(7)} ${dStr.padStart(8)} `
+      + `${num(r.envelopeChars).padStart(7)} ${String(r.files).padStart(5)}  ${cut.padEnd(12)} ${epi}`,
+    );
+  }
+  if (base) {
+    const lost = results.filter((r) => {
+      const b = byRepo.get(r.repo);
+      return b && (r.sourceChars < b.sourceChars || r.files < b.files);
+    });
+    say('');
+    say(lost.length === 0
+      ? 'No repo delivers less source or fewer files than the baseline.'
+      : `REGRESSION: ${lost.map((r) => r.repo).join(', ')} deliver less than baseline.`);
+  }
+}

package/scripts/agent-eval/probe-sweep.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// probe-sweep — direct MCP test across N repos × N tools, no claude needed.
+//
+// Measures response characteristics (size, sections present, signals fired)
+// for each (repo, query) pair against the built dist/. Sub-second per probe;
+// the full sweep below runs in ~10-30s vs hours for a real claude audit.
+//
+// Use this to iterate on backend changes rapidly: change tools.ts /
+// context-builder, npm run build, re-run probe-sweep, compare. Once a
+// change looks good on probe metrics, run a focused claude audit for the
+// few repos that matter to confirm end-to-end cost behavior.
+//
+// Usage: node scripts/agent-eval/probe-sweep.mjs [--tool=context|explore|trace] [--repos=a,b,c]
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const args = Object.fromEntries(
+  process.argv.slice(2).map(a => a.startsWith('--') ? a.slice(2).split('=') : [a, true])
+);
+const TOOL = args.tool ?? 'context';
+
+const load = (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+// Each entry: repo, query, optional 2nd arg for trace (from, to).
+// The query is the same prompt used in the real claude audits, so probe
+// output is directly comparable to the agent's would-be input.
+const SWEEP = [
+  // Small realworld template repos (the loss cases from the cross-language sweep)
+  { id: 'gin-rw',        repo: '/tmp/codegraph-corpus/gin-realworld',         q: 'How does this Gin app route a request through its middleware chain to a handler?' },
+  { id: 'go-mux',        repo: '/tmp/codegraph-corpus/go-mux',                q: 'How does this gorilla/mux app route a request to its handler?' },
+  { id: 'fastapi-rw',    repo: '/tmp/codegraph-corpus/fastapi-realworld',     q: 'How does FastAPI route a request through its dependencies to a handler?' },
+  { id: 'spring-pc',     repo: '/tmp/codegraph-corpus/spring-petclinic',      q: 'How does Spring route an HTTP request to a controller method?' },
+  { id: 'axum-rw',       repo: '/tmp/codegraph-corpus/rust-axum-realworld',   q: 'How does Axum route a request to its handler in this app?' },
+  { id: 'express-rw',    repo: '/tmp/codegraph-corpus/express-realworld',     q: 'How does this Express app route a request through middleware to a handler?' },
+  { id: 'kotlin-pc',     repo: '/tmp/codegraph-corpus/kotlin-petclinic',      q: 'How does the Kotlin Spring app route an HTTP request to its handler?' },
+  { id: 'flask-mb',      repo: '/tmp/codegraph-corpus/flask-microblog',       q: 'How does this Flask app route a request to a view function?' },
+  { id: 'vapor-tpl',     repo: '/tmp/codegraph-corpus/vapor-template',        q: 'How does Vapor route an HTTP request to its handler?' },
+  { id: 'cpp-leveldb',   repo: '/tmp/codegraph-corpus/cpp-leveldb',           q: 'How does LevelDB handle a Put operation through to disk?' },
+  { id: 'lualine',       repo: '/tmp/codegraph-corpus/lualine.nvim',          q: 'How does lualine assemble and render the statusline?' },
+  { id: 'drupal-admin',  repo: '/tmp/codegraph-corpus/drupal-admintoolbar',   q: 'How does the Drupal admin toolbar module render its toolbar?' },
+  { id: 'svelte-rw',     repo: '/tmp/codegraph-corpus/svelte-realworld',      q: 'How does this SvelteKit app route a request to a handler?' },
+  { id: 'react-rw',      repo: '/tmp/codegraph-corpus/react-realworld',       q: 'How does this React app fetch and display articles?' },
+  { id: 'rails-rw',      repo: '/tmp/codegraph-corpus/rails-realworld',       q: 'How does Rails route a request to a controller action?' },
+  { id: 'flask-rest',    repo: '/tmp/codegraph-corpus/flask-restful-realworld', q: 'How does Flask-RESTful route a request to a resource method?' },
+  { id: 'laravel-rw',    repo: '/tmp/codegraph-corpus/laravel-realworld',     q: 'How does Laravel route a request to the controller method?' },
+  { id: 'aspnet-rw',     repo: '/tmp/codegraph-corpus/aspnet-realworld',      q: 'How does ASP.NET route a request to the controller action?' },
+  // The iter7 wins/ties (to make sure we don't regress)
+  { id: 'cobra',         repo: '/tmp/codegraph-corpus/cobra',                 q: 'How does cobra parse commands and flags?' },
+  { id: 'sinatra',       repo: '/tmp/codegraph-corpus/sinatra',               q: 'How does sinatra route a request to its handler?' },
+  { id: 'slim',          repo: '/tmp/codegraph-corpus/slim',                  q: 'How does slim route a request and apply middleware?' },
+];
+
+// Detect signals in response text — these are the levers we've added that
+// otherwise only show up via "agent ran X more tool calls" downstream.
+const detect = (text) => ({
+  hasEntryPoints: /^### Entry Points/m.test(text),
+  hasRelatedSymbols: /^### Related Symbols/m.test(text),
+  hasFlowTrace: /^## Inline flow trace/m.test(text),
+  hasRouteManifest: /^## Routing manifest/m.test(text),
+  hasTopHandler: /^### Top handler file/m.test(text),
+  hasSmallRepoTail: /This project is small/.test(text),
+});
+
+const filterRepos = args.repos ? new Set(String(args.repos).split(',')) : null;
+const subjects = SWEEP.filter(s => !filterRepos || filterRepos.has(s.id));
+
+const t0 = Date.now();
+const rows = [];
+for (const s of subjects) {
+  try {
+    const cg = CodeGraph.openSync(s.repo);
+    const handler = new ToolHandler(cg);
+    const t1 = Date.now();
+    const res = await handler.execute('codegraph_' + TOOL,
+      TOOL === 'context' ? { task: s.q } :
+      TOOL === 'explore' ? { query: s.q } : { from: 'main', to: 'main' });
+    const text = res.content?.[0]?.text ?? '';
+    const signals = detect(text);
+    rows.push({
+      id: s.id,
+      ms: Date.now() - t1,
+      chars: text.length,
+      lines: text.split('\n').length,
+      ...signals,
+    });
+    try { cg.close?.(); } catch {}
+  } catch (e) {
+    rows.push({ id: s.id, error: String(e).slice(0, 80) });
+  }
+}
+
+// Pretty-print as a compact table.
+const fmt = (r) =>
+  r.error
+    ? `  ${r.id.padEnd(13)} ERROR: ${r.error}`
+    : `  ${r.id.padEnd(13)} ${String(r.chars).padStart(6)}c ${String(r.lines).padStart(4)}L ${String(r.ms).padStart(4)}ms` +
+      ` ${r.hasEntryPoints ? 'EP ' : '   '}` +
+      `${r.hasFlowTrace ? 'TRC ' : '    '}` +
+      `${r.hasRouteManifest ? 'MAN ' : '    '}` +
+      `${r.hasTopHandler ? 'HND ' : '    '}` +
+      `${r.hasSmallRepoTail ? 'TAIL' : '    '}`;
+console.log(`=== probe-sweep tool=${TOOL} n=${subjects.length} (${Date.now() - t0}ms total) ===`);
+console.log('  id            chars  lines    ms signals');
+console.log('  ' + '-'.repeat(56));
+for (const r of rows) console.log(fmt(r));
+
+// Sum + medians for the size pillar
+const sizes = rows.filter(r => !r.error).map(r => r.chars);
+sizes.sort((a, b) => a - b);
+const median = sizes[Math.floor(sizes.length / 2)];
+const sum = sizes.reduce((a, b) => a + b, 0);
+console.log(`  ${'-'.repeat(64)}`);
+console.log(`  median=${median}c  total=${sum}c  ` +
+  `manifest=${rows.filter(r => r.hasRouteManifest).length}/${rows.filter(r => !r.error).length}  ` +
+  `top-handler=${rows.filter(r => r.hasTopHandler).length}/${rows.filter(r => !r.error).length}`);

package/scripts/agent-eval/probe-trace.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Probe codegraph_trace against an index using the built dist.
+// Usage: node probe-trace.mjs <repo-with-.codegraph> <from> <to>
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, from, to] = process.argv;
+if (!repo || !from || !to) { console.error('usage: probe-trace.mjs <repo> <from> <to>'); process.exit(1); }
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+const cg = CodeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('codegraph_trace', { from, to });
+console.log(res.content?.[0]?.text ?? '(no text)');
+try { cg.close?.(); } catch {}

package/scripts/agent-eval/redirect-read-hook.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# PreToolUse(Read) REDIRECT hook — prototype for A/B (P1: get agents off Read and
+# onto codegraph_node during implementation, not just for Q&A).
+#
+# When the agent Reads a SOURCE file, deny it and steer to codegraph_node's
+# file-view, which (as of the Lever-1 change) returns the WHOLE file verbatim
+# WITH line numbers — imports, top-level code, comments and all — PLUS the file's
+# blast radius, in one call. That output is a strict superset of Read, so the
+# redirect is lossless: the agent loses nothing by taking it, and gains who-
+# depends-on-this for the edit it's about to make.
+#
+# Differs from block-read-hook.sh (which steers to explore/node-by-symbol): this
+# names the FILE-VIEW path explicitly (file:"<base>" + includeCode:true), the
+# 1:1 Read replacement we're trying to get picked during implementation.
+#
+# Non-source files (configs, docs, lockfiles, .env) pass through to a real Read.
+# A redirect to a file codegraph hasn't indexed SELF-CORRECTS: the file-view
+# replies "No indexed file matches … Read it directly", so a just-created file
+# never dead-ends — the agent Reads it on the next turn.
+#
+# Wire via:  claude ... --settings <settings-with-this-as-PreToolUse(Read)>
+# Eval artifact only. The production version is an indexed-aware `codegraph`
+# subcommand (cross-platform — no bash/jq — and queries the index so it never
+# bounces a new/un-indexed file), wired opt-in by the installer.
+set -uo pipefail
+input="$(cat)"
+fp="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+[ -n "$fp" ] || exit 0
+base="$(basename "$fp")"
+
+case "$fp" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.py|*.go|*.rs|*.java|*.rb|*.php|*.swift|*.kt|*.kts|*.scala|*.c|*.cc|*.cpp|*.h|*.hpp|*.cs|*.lua|*.vue|*.svelte|*.m|*.mm)
+    msg="codegraph has this file indexed (kept in sync on every edit). Call codegraph_node with file:\"$base\" and includeCode:true instead of Read — it returns the WHOLE file verbatim WITH line numbers (imports, top-level code and all — safe to base an Edit on) PLUS which files depend on it, in one call. Treat its output as already-Read; do not Read this file. (If it answers that the file isn't indexed — e.g. you just created it — then Read it directly.)"
+    jq -n --arg m "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$m}}'
+    exit 0
+    ;;
+esac
+exit 0

package/scripts/agent-eval/repro-concurrent-explore.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Reproduction harness A — does the shared daemon serialize concurrent explore?
+//
+// Mirrors the daemon's reality: ONE CodeGraph + ONE ToolHandler (as MCPEngine
+// shares across all sessions), then fires N concurrent codegraph_explore calls
+// and measures:
+//   - each call's wall-clock latency + completion order
+//   - an event-loop HEARTBEAT (setInterval 50ms): the max gap between ticks is a
+//     direct measure of how long synchronous compute blocked the loop. In the
+//     real daemon a blocked loop can't flush a finished response or read the
+//     next request, so this gap is what starves the MCP transport.
+//
+// Usage: node repro-concurrent-explore.mjs <repo-with-.codegraph> <N> [timeoutMs]
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+const [, , repo, nRaw, timeoutRaw] = process.argv;
+if (!repo) {
+  console.error('usage: repro-concurrent-explore.mjs <repo> <N=10> [timeoutMs=60000]');
+  process.exit(1);
+}
+const N = Number(nRaw) || 10;
+const TIMEOUT_MS = Number(timeoutRaw) || 60000; // ~ MCP SDK default request timeout
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+// Distinct queries so no two calls are trivially identical. Mix of NL questions
+// (exercise FTS + RWR over the whole graph) — the expensive explore path.
+const QUERIES = [
+  'how does the text model handle edits and undo',
+  'how does the file service watch for changes on disk',
+  'how does the keybinding service resolve a chord to a command',
+  'how does the extension host activate an extension',
+  'how does the editor render decorations in the viewport',
+  'how does the search service stream results to the UI',
+  'how does the terminal process manager spawn a shell',
+  'how does the configuration service merge user and workspace settings',
+  'how does the debug adapter forward breakpoints to the runtime',
+  'how does the quick input widget filter its items',
+  'how does the notification service queue and show toasts',
+  'how does the git extension compute the diff for a file',
+  'how does the language features registry dispatch a hover request',
+  'how does the workbench layout restore editor groups on reload',
+  'how does the storage service persist state between sessions',
+  'how does the menu service build a context menu from contributions',
+];
+
+const cg = CodeGraph.openSync(repo);
+let fileCount = 0;
+try { fileCount = cg.getStats().fileCount; } catch {}
+const handler = new ToolHandler(cg);
+
+// --- event-loop heartbeat ---
+let lastTick = performance.now();
+let maxGap = 0;
+const gaps = [];
+const hb = setInterval(() => {
+  const now = performance.now();
+  const gap = now - lastTick;
+  lastTick = now;
+  if (gap > 60) gaps.push(Math.round(gap)); // expected ~50ms; record stalls
+  if (gap > maxGap) maxGap = gap;
+}, 50);
+
+function runOne(i) {
+  const q = QUERIES[i % QUERIES.length];
+  const startedAt = performance.now();
+  let timer;
+  const timeout = new Promise((res) => {
+    timer = setTimeout(() => res({ timedOut: true }), TIMEOUT_MS);
+  });
+  const work = handler
+    .execute('codegraph_explore', { query: q })
+    .then((r) => ({ ok: !r.isError, chars: r.content?.[0]?.text?.length ?? 0 }))
+    .catch((e) => ({ ok: false, err: String(e?.message ?? e) }));
+  return Promise.race([work, timeout]).then((r) => {
+    clearTimeout(timer);
+    return { i, q, ms: Math.round(performance.now() - startedAt), ...r };
+  });
+}
+
+// Baseline: one warm single call (so the first-call cold paths don't skew N).
+const warmStart = performance.now();
+await runOne(0);
+const warmMs = Math.round(performance.now() - warmStart);
+
+// Reset heartbeat stats for the concurrent run.
+gaps.length = 0; maxGap = 0; lastTick = performance.now();
+
+const batchStart = performance.now();
+const results = await Promise.all(Array.from({ length: N }, (_, i) => runOne(i)));
+const batchMs = Math.round(performance.now() - batchStart);
+clearInterval(hb);
+
+const lat = results.map((r) => r.ms).sort((a, b) => a - b);
+const timeouts = results.filter((r) => r.timedOut).length;
+const p = (q) => lat[Math.min(lat.length - 1, Math.floor(q * lat.length))];
+
+console.log('='.repeat(64));
+console.log(`repo=${repo}`);
+console.log(`fileCount=${fileCount}  N=${N}  perCallTimeout=${TIMEOUT_MS}ms`);
+console.log(`single warm explore: ${warmMs}ms`);
+console.log('-'.repeat(64));
+console.log(`concurrent batch wall-clock: ${batchMs}ms`);
+console.log(`per-call latency  min=${lat[0]}  p50=${p(0.5)}  p90=${p(0.9)}  max=${lat[lat.length - 1]}  (ms)`);
+console.log(`TIMEOUTS (>${TIMEOUT_MS}ms): ${timeouts} / ${N}`);
+console.log(`event-loop max stall: ${Math.round(maxGap)}ms   stalls>60ms: ${gaps.length}`);
+console.log(`  sum of stalls: ${gaps.reduce((a, b) => a + b, 0)}ms   biggest 5: ${gaps.sort((a,b)=>b-a).slice(0,5).join(', ')}`);
+console.log('-'.repeat(64));
+console.log('SERIALIZATION CHECK:');
+console.log(`  if serialized, batch ≈ N×single = ~${N * warmMs}ms;  actual=${batchMs}ms  (ratio ${(batchMs / (N * warmMs)).toFixed(2)})`);
+console.log(`  max latency / single = ${(lat[lat.length - 1] / warmMs).toFixed(1)}× (≈N means last call waited for all others)`);
+console.log('='.repeat(64));
+try { cg.close?.(); } catch {}