@ltm-alpha/alpha-cs 1.6.0

package/scripts/agent-eval/repro-daemon-clients.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Reproduction harness B — the FAITHFUL opencode scenario.
+//
+// Spawns N real `codegraph serve --mcp --path <repo>` processes (each becomes a
+// proxy that attaches to ONE shared daemon — exactly what opencode does with N
+// subagents), drives clean MCP JSON-RPC over each child's stdio, then fires ONE
+// concurrent wave of codegraph_explore tools/call across all N and measures
+// end-to-end latency + timeouts. This captures transport-flush starvation: a
+// daemon event-loop blocked in synchronous explore compute can neither read the
+// next request nor flush a finished response.
+//
+// Usage: node repro-daemon-clients.mjs <repo> <N=10> [perCallTimeoutMs=60000] [warm=1]
+import { spawn } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
+import { resolve } from 'node:path';
+
+const [, , repoRaw, nRaw, timeoutRaw, warmRaw] = process.argv;
+const repo = resolve(repoRaw || '.');
+const N = Number(nRaw) || 10;
+const TIMEOUT_MS = Number(timeoutRaw) || 60000;
+const WARM = warmRaw === undefined ? true : warmRaw !== '0';
+const CLI = resolve('dist/bin/codegraph.js');
+
+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',
+];
+
+function makeClient(id) {
+  const child = spawn('node', [CLI, 'serve', '--mcp', '--path', repo], {
+    env: { ...process.env, CODEGRAPH_TELEMETRY: '0', DO_NOT_TRACK: '1', CODEGRAPH_MCP_LOG_ATTACH: '0' },
+    stdio: ['pipe', 'pipe', 'inherit'],
+  });
+  let buf = '';
+  const waiters = new Map(); // id -> resolve
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => {
+    buf += chunk;
+    let idx;
+    while ((idx = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+      let msg; try { msg = JSON.parse(line); } catch { continue; }
+      if (msg.id !== undefined && waiters.has(msg.id)) {
+        waiters.get(msg.id)(msg);
+        waiters.delete(msg.id);
+      }
+    }
+  });
+  const send = (obj) => child.stdin.write(JSON.stringify(obj) + '\n');
+  const request = (method, params, rpcId, timeoutMs) =>
+    new Promise((res) => {
+      let timer;
+      if (timeoutMs) timer = setTimeout(() => { waiters.delete(rpcId); res({ __timeout: true }); }, timeoutMs);
+      waiters.set(rpcId, (m) => { if (timer) clearTimeout(timer); res(m); });
+      send({ jsonrpc: '2.0', id: rpcId, method, params });
+    });
+  return { id, child, send, request };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const clients = Array.from({ length: N }, (_, i) => makeClient(i));
+
+// Initialize every client (handshake is answered locally by each proxy, instant).
+await Promise.all(clients.map((c) =>
+  c.request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'repro', version: '1' } }, `init-${c.id}`, 10000)
+    .then(() => c.send({ jsonrpc: '2.0', method: 'initialized' }))
+));
+
+// Warm the daemon: one explore through client 0 forces daemon spawn + project
+// open + catch-up gate to complete, so the concurrent wave measures the STEADY
+// state (the user's real scenario after the first call), not cold start.
+if (WARM) {
+  process.stderr.write('[repro] warming daemon (first explore triggers spawn+open+catchup)...\n');
+  const t0 = performance.now();
+  const r = await clients[0].request('tools/call', { name: 'codegraph_explore', arguments: { query: QUERIES[0] } }, 'warm-0', 120000);
+  process.stderr.write(`[repro] warm explore took ${Math.round(performance.now() - t0)}ms (timeout=${!!r.__timeout})\n`);
+  await sleep(500);
+}
+
+// THE WAVE: fire one explore on every client as simultaneously as possible.
+process.stderr.write(`[repro] firing ${N} concurrent explores...\n`);
+const waveStart = performance.now();
+const results = await Promise.all(clients.map((c, i) => {
+  const started = performance.now();
+  return c.request('tools/call', { name: 'codegraph_explore', arguments: { query: QUERIES[i % QUERIES.length] } }, `call-${c.id}`, TIMEOUT_MS)
+    .then((m) => ({
+      id: c.id,
+      ms: Math.round(performance.now() - started),
+      timedOut: !!m.__timeout,
+      ok: !!m.result && !m.result.isError,
+      chars: m.result?.content?.[0]?.text?.length ?? 0,
+    }));
+}));
+const waveMs = Math.round(performance.now() - waveStart);
+
+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(`HARNESS B (real daemon + ${N} proxies)   repo=${repo}`);
+console.log(`warm=${WARM}  perCallTimeout=${TIMEOUT_MS}ms`);
+console.log('-'.repeat(64));
+console.log(`wave wall-clock: ${waveMs}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(`completion order (id:ms): ${results.slice().sort((a,b)=>a.ms-b.ms).map(r=>`${r.id}:${r.ms}`).join('  ')}`);
+console.log('='.repeat(64));
+
+for (const c of clients) { try { c.child.stdin.end(); c.child.kill('SIGTERM'); } catch {} }
+await sleep(300);
+process.exit(0);

package/scripts/agent-eval/run-agent.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Headless Claude Code run against a repo with codegraph MCP, capturing the
+# full stream-json so we can see tool calls + token usage. Complements the
+# interactive itrun.sh: headless gives a clean per-tool breakdown + exact
+# tokens/cost, but defaults to the general-purpose subagent (not Explore).
+# To force the Explore path, ask for it in the prompt.
+#
+# Usage: run-agent.sh <repo-path> <label> "<prompt>"
+# Env: AGENT_EVAL_OUT (default /tmp/agent-eval), CG_BIN (codegraph dist binary)
+set -uo pipefail
+
+REPO="$1"; LABEL="$2"; PROMPT="$3"
+CG_BIN="${CG_BIN:-$(command -v codegraph || echo /usr/local/bin/codegraph)}"
+OUT_DIR="${AGENT_EVAL_OUT:-/tmp/agent-eval}"; mkdir -p "$OUT_DIR"
+OUT="$OUT_DIR/run-${LABEL}.jsonl"
+
+MCP_CONFIG=$(cat <<JSON
+{"mcpServers":{"codegraph":{"command":"${CG_BIN}","args":["serve","--mcp","--path","${REPO}"]}}}
+JSON
+)
+
+echo "→ running [$LABEL] in $REPO"
+cd "$REPO" || exit 1
+
+claude -p "$PROMPT" \
+  --output-format stream-json --verbose \
+  --permission-mode bypassPermissions \
+  --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" \
+  --max-budget-usd 2 \
+  --strict-mcp-config --mcp-config "$MCP_CONFIG" \
+  > "$OUT" 2>"$OUT_DIR/run-${LABEL}.err"
+
+echo "exit: $? | wrote $OUT ($(wc -l < "$OUT") lines)"
+node "$(cd "$(dirname "$0")" && pwd)/parse-run.mjs" "$OUT" 2>/dev/null || true

package/scripts/agent-eval/run-all.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# With/without A/B (and optional interactive) eval for a codegraph version on a
+# repo. Codegraph is the ONLY variable: both arms launch claude with
+# --strict-mcp-config — with = codegraph-only MCP (pointed at $CG_BIN),
+# without = empty MCP. Built-in Read/Grep/Bash stay available in both arms.
+#
+# Usage: run-all.sh <repo-path> "<question>" [headless|tmux|all]
+#
+# Each headless arm reports the three feedback metrics (parse-run.mjs prints all
+# three under every run, and compare-arms.mjs puts the arms side by side at the
+# end when both ran):
+#   residual context occupancy (CG-7)  window still held by the arm's retrieval
+#   explore sufficiency        (CG-8)  was the response ENOUGH — the agent's next act
+#   allocation efficiency      (CG-9)  share of returned bytes the answer cited
+# docs/benchmarks/agent-eval-feedback-metrics.md is the entry point; the three
+# per-metric docs it links carry the caveats.
+#
+# MULTI-TURN: separate questions with "||" to run them as ONE session —
+#   run-all.sh <repo> "How does X work?||Where is Y handled in that path?"
+# Turn 1 runs normally; every later turn `--resume`s the same session, so the
+# earlier turns' tool output is still in the window (that is the whole point:
+# residual context occupancy, the cost a single-question run cannot see).
+# Segments land in run-<label>.jsonl, run-<label>.t2.jsonl, … and parse-run.mjs
+# stitches them back into one session.
+#
+# Env:   CG_BIN          codegraph binary (default: command -v codegraph)
+#        AGENT_EVAL_OUT  output dir (default: /tmp/agent-eval)
+#        MODEL / EFFORT  claude model/effort (default: sonnet / high — the
+#                        standing A/B policy; see CLAUDE.md, don't raise)
+set -uo pipefail
+
+REPO="${1:?usage: run-all.sh <repo-path> \"<question>\" [headless|tmux|all]}"
+Q="${2:?question required}"
+MODE="${3:-headless}"
+
+# Split "Q1||Q2||Q3" into turns (kept bash-3.2-safe: macOS ships 3.2).
+TURNS=()
+rest="$Q"
+while [ "$rest" != "${rest#*||}" ]; do
+  TURNS+=("${rest%%||*}")
+  rest="${rest#*||}"
+done
+TURNS+=("$rest")
+CG_BIN="${CG_BIN:-$(command -v codegraph)}"
+OUT="${AGENT_EVAL_OUT:-/tmp/agent-eval}"
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+mkdir -p "$OUT"
+
+# Neutralize any ambient CodeGraph prompt-hook (~/.claude) in BOTH arms:
+# the hook injects codegraph context into every prompt, which contaminates
+# the without-arm (free structural context) and double-counts the with-arm.
+# The A/B's only variable must be the MCP server wired below.
+export CODEGRAPH_NO_PROMPT_HOOK=1
+
+# Hide the codegraph CLI from BOTH arms, so the only way to reach codegraph is
+# the MCP server wired below — which is what makes it the A/B's single variable.
+# Two layers (sanitized PATH + a PreToolUse hook that blocks absolute-path
+# invocations), both in no-cli-shim.sh, which ab-new-vs-baseline.sh shares; the
+# reasoning and the incident that forced each layer are documented there.
+# Sets $ARM_PATH and $ARM_SETTINGS, and aborts if either layer fails its probe.
+. "$HARNESS/no-cli-shim.sh"
+cg_no_cli_setup "$OUT" || exit 1
+
+[ -n "$CG_BIN" ] || { echo "no codegraph binary on PATH (set CG_BIN)"; exit 1; }
+[ -d "$REPO/.codegraph" ] || { echo "no .codegraph index at $REPO — index it first"; exit 1; }
+case "$MODE" in headless|tmux|all) ;; *) echo "mode must be headless|tmux|all (got '$MODE')"; exit 1;; esac
+
+# MCP config files (path form avoids inline-JSON quoting through tmux).
+cat > "$OUT/mcp-codegraph.json" <<JSON
+{"mcpServers":{"codegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"]}}}
+JSON
+echo '{"mcpServers":{}}' > "$OUT/mcp-empty.json"
+
+echo "###### codegraph: $CG_BIN"
+echo "###### repo:      $REPO"
+echo "###### turns:     ${#TURNS[@]}"
+for t in "${TURNS[@]}"; do echo "######   - $t"; done
+echo
+
+# Pull the session id out of a segment's result event so the next turn can
+# --resume it (rather than minting a --session-id, which needs a valid uuid).
+session_id_of() {
+  node -e '
+    const fs=require("fs");
+    for (const l of fs.readFileSync(process.argv[1],"utf8").split("\n").reverse()) {
+      if (!l) continue; let e; try { e=JSON.parse(l) } catch { continue }
+      if (e.session_id) { console.log(e.session_id); break }
+    }' "$1" 2>/dev/null
+}
+
+# Headless arm: claude -p with stream-json -> exact tool sequence + tokens/cost
+# + residual context occupancy. One session, one segment file per turn.
+headless() {
+  local label="$1" cfg="$2"
+  echo "############################## HEADLESS [$label] ##############################"
+  local sid="" seg=0 out="" files=()
+  : > "$OUT/run-$label.err"
+  for q in "${TURNS[@]}"; do
+    seg=$((seg + 1))
+    out="$OUT/run-$label.jsonl"
+    [ "$seg" -gt 1 ] && out="$OUT/run-$label.t$seg.jsonl"
+    local resume=()
+    [ -n "$sid" ] && resume=(--resume "$sid")
+    ( cd "$REPO" && PATH="$ARM_PATH" claude -p "$q" \
+        --output-format stream-json --verbose \
+        --permission-mode bypassPermissions \
+        --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" \
+        --max-budget-usd 4 \
+        --strict-mcp-config --mcp-config "$cfg" \
+        --settings "$ARM_SETTINGS" \
+        ${resume[@]+"${resume[@]}"} \
+        </dev/null > "$out" 2>>"$OUT/run-$label.err" )
+    echo "exit $? -> $out ($(wc -l < "$out" | tr -d ' ') lines) [turn $seg/${#TURNS[@]}]"
+    files+=("$out")
+    sid="$(session_id_of "$out")"
+    if [ -z "$sid" ] && [ "$seg" -lt "${#TURNS[@]}" ]; then
+      echo "  WARN: no session_id in $out — later turns would start a FRESH context; stopping this arm"
+      break
+    fi
+  done
+  tail -2 "$OUT/run-$label.err" 2>/dev/null
+  node "$HARNESS/parse-run.mjs" "${files[@]}" 2>&1 || true
+  echo
+}
+
+# CG_ARMS=with|without|both — re-run one arm without redoing the other.
+ARMS="${CG_ARMS:-both}"
+if [ "$MODE" = headless ] || [ "$MODE" = all ]; then
+  case "$ARMS" in both|with)    headless "headless-with"    "$OUT/mcp-codegraph.json";; esac
+  case "$ARMS" in both|without) headless "headless-without" "$OUT/mcp-empty.json";; esac
+  # Both arms' three metrics on one screen. The per-arm blocks above say WHY a
+  # number moved (which query fell short, which file was never cited); this says
+  # whether it moved at all. CG_ARMS=with|without leaves one arm's logs from an
+  # earlier invocation in $OUT, and comparing against those is the point of the
+  # split — so this runs whichever arms have logs, not only a fresh pair.
+  node "$HARNESS/compare-arms.mjs" "$OUT" headless-with headless-without 2>&1 || true
+fi
+
+if [ "$MODE" = tmux ] || [ "$MODE" = all ]; then
+  echo "############################## INTERACTIVE [with] ##############################"
+  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-codegraph.json" \
+    bash "$HARNESS/itrun.sh" "$REPO" "int-with" "${TURNS[0]}" 2>&1 || echo "[itrun WITH failed]"
+  echo
+  echo "############################## INTERACTIVE [without] ##############################"
+  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-empty.json" \
+    bash "$HARNESS/itrun.sh" "$REPO" "int-without" "${TURNS[0]}" 2>&1 || echo "[itrun WITHOUT failed]"
+  echo
+fi
+echo "############################## RUN-ALL COMPLETE ##############################"

package/scripts/agent-eval/run-arms.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Tool-surface ablation — run ONE repo+question under ONE arm.
+#
+# Arms vary (exposed codegraph tools, trace-first steering). Tools are trimmed
+# SERVER-SIDE via CODEGRAPH_MCP_TOOLS in the MCP config's `env` block, so an
+# ablated tool is genuinely absent from ListTools — no deferred-ToolSearch or
+# denied-call confound (which --disallowedTools would introduce). Steering is
+# injected with --append-system-prompt, so no rebuild of the shipped
+# server-instructions is needed to A/B it.
+#
+#   A control       all tools            no steering
+#   B steer         all tools            trace-first
+#   C no-explore    hide explore         trace-first
+#   D trace-centric hide explore+context trace-first
+#   E control-probe hide explore+context trace-first  (caller passes a NON-flow Q)
+#
+# Usage: run-arms.sh <repo-path> "<question>" <A|B|C|D|E> [run-id]
+set -uo pipefail
+REPO="${1:?repo path}"; Q="${2:?question}"; ARM="${3:?arm A-E}"; RID="${4:-1}"
+CG_BIN="${CG_BIN:-$(command -v codegraph)}"
+OUT="${ARMS_OUT:-/tmp/arms}/$(basename "$REPO")"
+mkdir -p "$OUT"
+[ -n "$CG_BIN" ] || { echo "no codegraph binary (set CG_BIN)"; exit 1; }
+[ -d "$REPO/.codegraph" ] || { echo "no .codegraph index at $REPO"; exit 1; }
+
+STEER='Flow questions ("how does X reach/become Y", "trace the flow", request to handler, state to render): call codegraph_trace(from,to) FIRST — one call returns the whole path. Use codegraph_context/search only to locate the two endpoint symbols if you do not know them. Do NOT reconstruct the path with repeated search/callers/explore.'
+KEEP_NO_EXPLORE="trace,search,node,context,callers,callees,impact,files,status"
+KEEP_TRACE_CENTRIC="trace,search,node,callers,callees,impact,files,status"
+
+case "$ARM" in
+  A|G|H|I) TOOLS="";            STEERING="" ;;  # no steering; H = body-trace, I = body-trace + destination callees (sufficiency)
+  B|F) TOOLS="";                STEERING="$STEER" ;;  # F = B's surface, run on the body-inlining trace build
+  C) TOOLS="$KEEP_NO_EXPLORE";  STEERING="$STEER" ;;
+  D|E) TOOLS="$KEEP_TRACE_CENTRIC"; STEERING="$STEER" ;;
+  *) echo "bad arm '$ARM' (want A|B|C|D|E)"; exit 1 ;;
+esac
+
+CFG="$OUT/mcp-$ARM.json"
+if [ -n "$TOOLS" ]; then
+  cat > "$CFG" <<JSON
+{"mcpServers":{"codegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"],"env":{"CODEGRAPH_MCP_TOOLS":"$TOOLS"}}}}
+JSON
+else
+  cat > "$CFG" <<JSON
+{"mcpServers":{"codegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"]}}}
+JSON
+fi
+
+LOG="$OUT/$ARM-r$RID.jsonl"; ERR="$OUT/$ARM-r$RID.err"
+ARGS=( -p "$Q" --output-format stream-json --verbose
+       --permission-mode bypassPermissions --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4
+       --strict-mcp-config --mcp-config "$CFG" )
+[ -n "$STEERING" ] && ARGS+=( --append-system-prompt "$STEERING" )
+
+( cd "$REPO" && claude "${ARGS[@]}" > "$LOG" 2>"$ERR" )
+echo "[$(basename "$REPO") $ARM r$RID] exit $? -> $LOG ($(wc -l < "$LOG" | tr -d ' ') lines)"

package/scripts/agent-eval/seq-matrix.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Mine the surviving A/B stream-json logs (/tmp/ab-matrix/<Cell>/run-headless-*.jsonl)
+// for what the aggregate matrix can't see: the call SEQUENCE and per-call output SIZE.
+//
+// Answers three questions:
+//   1. Trace adoption — on a flow question, does the with-arm actually call codegraph_trace?
+//   2. Payload size vs repo size — is trace path-scoped (tiny, size-independent) while
+//      explore is breadth-scoped (grows with the repo / over-returns on small repos)?
+//   3. Round-trips — num_turns with vs without (the real wall-clock driver).
+//
+// Usage: node scripts/agent-eval/seq-matrix.mjs [/tmp/ab-matrix]
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const AB = process.argv[2] || '/tmp/ab-matrix';
+const MD = new URL('../../docs/benchmarks/codegraph-ab-matrix.md', import.meta.url).pathname;
+
+// repo -> {lang,size,files} from the published matrix table
+const repoMeta = {};
+if (existsSync(MD)) for (const line of readFileSync(MD, 'utf8').split('\n')) {
+  const m = line.match(/^\|\s*([^|]+?)\s*\|\s*(S|M|L)\s*\|\s*`([^`]+)`\s*\|\s*(\d+)\s*\|/);
+  if (m) repoMeta[m[3]] = { lang: m[1].trim(), size: m[2], files: +m[4] };
+}
+
+const cgShort = (n) => n.replace('mcp__codegraph__codegraph_', '').replace('mcp__codegraph__', '');
+const tag = (n) => n === 'Read' ? 'R' : n === 'Grep' ? 'G' : n === 'Glob' ? 'Gl'
+  : n === 'Bash' ? 'B' : n === 'Task' ? 'Ag' : n === 'ToolSearch' ? 'TS'
+  : n.includes('codegraph') ? cgShort(n) : n;
+
+function parse(file) {
+  if (!existsSync(file)) return null;
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const calls = []; let result = null, initCg = 0;
+  for (const l of lines) {
+    let ev; try { ev = JSON.parse(l); } catch { continue; }
+    if (ev.type === 'system' && ev.subtype === 'init') initCg = (ev.tools || []).filter(t => /codegraph/.test(t)).length;
+    if (ev.type === 'assistant') for (const b of (ev.message?.content || [])) if (b.type === 'tool_use') {
+      const i = b.input || {};
+      const q = i.query ?? i.symbol ?? i.task ?? (i.from && i.to ? `${i.from}->${i.to}` : (i.file_path || i.command || ''));
+      calls.push({ id: b.id, name: b.name, q: String(q ?? '').slice(0, 38), out: 0 });
+    }
+    if (ev.type === 'user') for (const b of (ev.message?.content || [])) if (b.type === 'tool_result') {
+      const c = b.content;
+      const txt = typeof c === 'string' ? c : Array.isArray(c) ? c.map(x => x?.text || '').join('') : '';
+      const call = calls.find(k => k.id === b.tool_use_id); if (call) call.out = txt.length;
+    }
+    if (ev.type === 'result') result = ev;
+  }
+  const cg = calls.filter(c => c.name.includes('codegraph'));
+  const perTool = {};
+  for (const c of cg) { const k = cgShort(c.name); (perTool[k] ??= { n: 0, out: 0 }); perTool[k].n++; perTool[k].out += c.out; }
+  const traceIdx = cg.findIndex(c => c.name.includes('trace'));
+  const u = result?.usage || {};
+  return {
+    initCg, cg, perTool,
+    cgSeq: cg.map(c => cgShort(c.name)),
+    seq: calls.map(c => tag(c.name)),
+    reads: calls.filter(c => c.name === 'Read').length,
+    greps: calls.filter(c => c.name === 'Grep').length,
+    cgOut: cg.reduce((s, c) => s + c.out, 0),
+    traceUsed: traceIdx >= 0,
+    afterTrace: traceIdx >= 0 ? cg.slice(traceIdx + 1).map(c => cgShort(c.name)) : null,
+    turns: result?.num_turns ?? null,
+    dur: result?.duration_ms ? Math.round(result.duration_ms / 1000) : null,
+    cost: result?.total_cost_usd || 0,
+  };
+}
+
+const cells = [];
+for (const d of readdirSync(AB)) {
+  const dir = join(AB, d);
+  if (!existsSync(join(dir, 'run-headless-with.jsonl'))) continue;
+  const log = existsSync(join(AB, d + '.log')) ? readFileSync(join(AB, d + '.log'), 'utf8') : '';
+  const repo = (log.match(/repo:\s*\S*\/([^\s/]+)/) || [])[1] || d;
+  const question = (log.match(/question:\s*(.+)/) || [])[1] || '';
+  cells.push({ cell: d, repo, question, ...(repoMeta[repo] || {}),
+    with: parse(join(dir, 'run-headless-with.jsonl')),
+    without: parse(join(dir, 'run-headless-without.jsonl')) });
+}
+cells.sort((a, b) => (a.files || 0) - (b.files || 0));
+
+const k = (n) => (n / 1000).toFixed(1);
+const pad = (s, n) => String(s).padEnd(n);
+
+// ---- per-cell sequence table ----
+console.log('\n=== PER-CELL: with-arm codegraph sequence + payload (sorted by repo size) ===');
+console.log(pad('repo', 22), pad('files', 6), 'trace', pad('cg-call sequence', 40), pad('cgOutK', 7), 'turns(w/wo)');
+for (const c of cells) {
+  const w = c.with;
+  console.log(
+    pad(c.repo, 22), pad(c.files ?? '?', 6),
+    pad(w.traceUsed ? 'YES' : 'no', 5),
+    pad(w.cgSeq.join(',') || '(none)', 40),
+    pad(k(w.cgOut), 7),
+    `${w.turns}/${c.without?.turns}`,
+  );
+}
+
+// ---- trace adoption ----
+const flow = cells; // every matrix question is a canonical flow question by design
+const used = flow.filter(c => c.with.traceUsed);
+console.log(`\n=== TRACE ADOPTION (all ${flow.length} cells are flow questions) ===`);
+console.log(`trace called in ${used.length}/${flow.length} cells`);
+console.log('used trace:', used.map(c => c.repo).join(', ') || '(none)');
+if (used.length) console.log('after-trace follow-ups:', used.map(c => `${c.repo}[${c.with.afterTrace.join(',') || 'none'}]`).join('  '));
+
+// ---- payload size by repo-size tier ----
+const tier = (f) => f < 200 ? 'S(<200)' : f < 2000 ? 'M(<2000)' : 'L(>=2000)';
+const byTier = {};
+for (const c of cells) { (byTier[tier(c.files || 0)] ??= []).push(c.with.cgOut); }
+console.log('\n=== with-arm TOTAL codegraph payload by repo-size tier ===');
+for (const t of ['S(<200)', 'M(<2000)', 'L(>=2000)']) {
+  const a = byTier[t] || []; if (!a.length) continue;
+  const avg = a.reduce((s, x) => s + x, 0) / a.length;
+  console.log(`  ${pad(t, 10)} n=${a.length}  avg cgOut=${k(avg)}K  range ${k(Math.min(...a))}-${k(Math.max(...a))}K`);
+}
+
+// ---- per-tool usage + avg payload (breadth vs path evidence) ----
+const tot = {};
+for (const c of cells) for (const [name, v] of Object.entries(c.with.perTool)) {
+  (tot[name] ??= { n: 0, out: 0 }); tot[name].n += v.n; tot[name].out += v.out;
+}
+console.log('\n=== codegraph tool usage across all cells (n calls, avg payload/call) ===');
+for (const [name, v] of Object.entries(tot).sort((a, b) => b[1].n - a[1].n)) {
+  console.log(`  ${pad(name, 10)} calls=${pad(v.n, 4)} avg=${k(v.out / v.n)}K/call  total=${k(v.out)}K`);
+}
+
+// ---- round-trips ----
+const sum = (arr, f) => arr.reduce((s, x) => s + (f(x) || 0), 0);
+const wTurns = sum(cells, c => c.with.turns), woTurns = sum(cells, c => c.without?.turns);
+const wCalls = sum(cells, c => c.with.cg.length);
+const tsAll = cells.every(c => c.with.seq[0] === 'TS');
+console.log('\n=== ROUND-TRIPS ===');
+console.log(`turns: with=${wTurns}  without=${woTurns}  (${((1 - wTurns / woTurns) * 100).toFixed(0)}% fewer with)`);
+console.log(`avg turns/cell: with=${(wTurns / cells.length).toFixed(1)}  without=${(woTurns / cells.length).toFixed(1)}`);
+console.log(`total codegraph calls=${wCalls} (avg ${(wCalls / cells.length).toFixed(1)}/cell)`);
+console.log(`every with-arm opens with a ToolSearch round-trip (deferred tools): ${tsAll ? 'YES — 1 fixed tax/run' : 'no'}`);

package/scripts/benchmarks/measure-index.cjs

@@ -0,0 +1,128 @@
+// Standalone benchmark harness; see docs/benchmarks/regression-audit-2026-09.md.
+// Arguments: built engine directory, fixture root, existing output directory, native|wasm.
+const fs = require('node:fs');
+const path = require('node:path');
+const { performance, monitorEventLoopDelay } = require('node:perf_hooks');
+const { DatabaseSync } = require('node:sqlite');
+const [engine, root, out, backend] = process.argv.slice(2);
+if (!engine || !root || !out || !['native', 'wasm'].includes(backend)) {
+  throw new Error('Usage: node measure-index.cjs BUILT_ENGINE FRESH_FIXTURE EXISTING_OUTPUT native|wasm');
+}
+if (fs.existsSync(path.join(root, '.codegraph'))) {
+  throw new Error('Refusing an existing fixture index; preserve it and use a fresh fixture.');
+}
+const begin = performance.now();
+const tracePath = path.join(out, 'progress.ndjson');
+// Exclusive creation prevents accidental reuse of a previous run's evidence.
+const traceFd = fs.openSync(tracePath, 'wx');
+let phase = 'opening';
+function progress(event, details = {}) {
+  fs.writeSync(traceFd, JSON.stringify({ event, phase, epochMs: Date.now(),
+    wallMs: performance.now() - begin, cpu: process.cpuUsage(), rss: process.memoryUsage().rss,
+    ...details }) + '\n');
+}
+const loopDelay = monitorEventLoopDelay({ resolution: 20 });
+loopDelay.enable();
+let previousLoop = performance.eventLoopUtilization();
+const heartbeat = setInterval(() => {
+  const current = performance.eventLoopUtilization();
+  progress('heartbeat', { eventLoop: performance.eventLoopUtilization(current, previousLoop),
+    delayMaxMs: loopDelay.max / 1e6 });
+  previousLoop = current;
+  loopDelay.reset();
+}, 5000);
+heartbeat.unref();
+progress('start');
+const { CodeGraph } = require(path.join(engine, 'dist/index.js'));
+const { DatabaseConnection } = require(path.join(engine, 'dist/db/index.js'));
+const loader = require(path.join(engine, 'dist/extraction/kernel/loader.js'));
+const result = { engine, root, backend, node: process.version, stages: [] };
+let cg;
+const orig = CodeGraph.prototype.resolveReferencesBatched;
+CodeGraph.prototype.resolveReferencesBatched = async function (...args) {
+  const stage = { name: 'resolution-and-synthesis', startEpochMs: Date.now(), memoryBefore: process.memoryUsage(), refsBefore: this.db.getDb().prepare('SELECT count(*) AS n FROM unresolved_refs').get().n };
+  const start = performance.now(), cpu = process.cpuUsage();
+  progress('stage-start', { name: stage.name });
+  try { const value = await orig.apply(this, args); stage.stats = value.stats; return value; }
+  finally {
+    Object.assign(stage, { endEpochMs: Date.now(), wallMs: performance.now() - start, cpu: process.cpuUsage(cpu), memoryAfter: process.memoryUsage() });
+    result.stages.push(stage);
+    progress('stage-complete', { stage });
+    phase = 'finalizing';
+  }
+};
+const origMaintenance = DatabaseConnection.prototype.runMaintenance;
+DatabaseConnection.prototype.runMaintenance = async function (...args) {
+  phase = 'maintenance';
+  const start = performance.now(), cpu = process.cpuUsage();
+  progress('stage-start', { name: 'database-maintenance' });
+  try { return await origMaintenance.apply(this, args); }
+  finally {
+    const stage = { name: 'database-maintenance', wallMs: performance.now() - start,
+      cpu: process.cpuUsage(cpu) };
+    result.stages.push(stage);
+    progress('stage-complete', { stage });
+    phase = 'finalizing';
+  }
+};
+(async () => {
+  try {
+    // getKernel() deliberately ignores CODEGRAPH_KERNEL=0; kernelSupports()
+    // is the actual per-call routing predicate used by extraction.
+    result.nativeLoaded = loader.kernelSupports('typescript');
+    if (result.nativeLoaded !== (backend === 'native')) throw new Error('Wrong extraction backend');
+    cg = CodeGraph.initSync(root);
+    result.openMs = performance.now() - begin;
+    const start = performance.now(), cpu = process.cpuUsage();
+    result.indexStartEpochMs = Date.now();
+    let lastProgress = 0;
+    phase = 'indexing';
+    progress('index-start');
+    result.index = await cg.indexAll({ onProgress: p => {
+      const now = performance.now();
+      // Preserve every resolution/synthesis batch, but avoid one disk write per
+      // scanned/parsed file. Heartbeats continue while asynchronous work waits.
+      if (phase !== p.phase || p.phase === 'resolving' || p.phase === 'linking' ||
+          now - lastProgress >= 1000 || (p.total > 0 && p.current === p.total)) {
+        phase = p.phase;
+        progress('progress', { progress: p });
+        lastProgress = now;
+      }
+    } });
+    result.indexEndEpochMs = Date.now();
+    result.indexMs = performance.now() - start;
+    result.indexCpu = process.cpuUsage(cpu);
+    progress('index-complete', { indexMs: result.indexMs, indexCpu: result.indexCpu, index: result.index });
+    // Save the completed index measurement BEFORE potentially expensive full DB
+    // checks. A stopped validation must not look like an indexing timeout.
+    fs.writeFileSync(path.join(out, 'index-result.json'), JSON.stringify(result, null, 2));
+    phase = 'verification';
+    progress('verification-start');
+    if (!result.index.success || result.index.filesErrored) throw new Error('Index did not finish cleanly');
+    const db = new DatabaseSync(path.join(root, '.codegraph/codegraph.db'), { readOnly: true });
+    result.counts = Object.fromEntries(['files','nodes','edges','unresolved_refs'].map(table => [table, db.prepare(`SELECT count(*) AS n FROM ${table}`).get().n]));
+    result.languages = db.prepare('SELECT language,count(*) AS n FROM files GROUP BY language').all();
+    result.integrity = db.prepare('PRAGMA integrity_check').all();
+    result.foreignKeys = db.prepare('PRAGMA foreign_key_check').all();
+    result.orphans = db.prepare('SELECT count(*) AS n FROM edges e LEFT JOIN nodes s ON s.id=e.source LEFT JOIN nodes t ON t.id=e.target WHERE s.id IS NULL OR t.id IS NULL').get().n;
+    db.close();
+    if (result.integrity.length !== 1 || result.integrity[0].integrity_check !== 'ok' ||
+        result.foreignKeys.length || result.orphans) throw new Error('Database verification failed');
+    progress('verification-complete');
+  } catch (e) { result.error = e.stack; process.exitCode = 1; }
+  finally {
+    phase = 'closing';
+    progress('closing');
+    try { cg?.close(); }
+    catch (e) { result.closeError = e.stack; process.exitCode = 1; }
+    result.totalInsideProcessMs = performance.now() - begin;
+    result.maxRSSKiB = process.resourceUsage().maxRSS;
+    result.finalMemory = process.memoryUsage();
+    fs.writeFileSync(path.join(out, 'result.json'), JSON.stringify(result, null, 2));
+    progress('complete', { error: result.error, closeError: result.closeError });
+    clearInterval(heartbeat);
+    loopDelay.disable();
+    fs.closeSync(traceFd);
+    console.log(JSON.stringify({ indexMs: result.indexMs, stages: result.stages.map(x => ({ wallMs: x.wallMs, stats: x.stats })), error: result.error }));
+  }
+})();