@saluzi/codegraph 0.1.0 → 0.2.1

package/scripts/agent-eval/itrun.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Drive an INTERACTIVE Claude Code session in tmux, send a prompt, wait for the
+# agent to finish, then print the tool-call breakdown from the session logs.
+#
+# Why interactive (not `claude -p`): headless print-mode picks the
+# general-purpose subagent, while real interactive sessions delegate to the
+# Explore subagent (or drive codegraph from the main thread). Only the
+# interactive TUI reproduces the behavior users actually see. (Idle-detection
+# technique borrowed from devpit's WaitForIdle.)
+#
+# Usage: itrun.sh <repo-path> <label> "<prompt>"
+# Output dir: $AGENT_EVAL_OUT (default /tmp/agent-eval)
+# Requires: tmux 3.0+, a logged-in `claude` CLI, codegraph MCP configured.
+set -uo pipefail
+REPO="$1"; LABEL="$2"; PROMPT="$3"
+SESSION="cgt_${LABEL}"
+OUT_DIR="${AGENT_EVAL_OUT:-/tmp/agent-eval}"; mkdir -p "$OUT_DIR"
+OUT="$OUT_DIR/itrun-${LABEL}.txt"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+cap() { tmux capture-pane -p -t "$SESSION" -S -40; }
+
+tmux kill-session -t "$SESSION" 2>/dev/null
+
+# Wide pane so the TUI doesn't hard-wrap tool lines.
+tmux new-session -d -s "$SESSION" -x 230 -y 60
+tmux send-keys -t "$SESSION" "cd $REPO && claude --dangerously-skip-permissions ${CLAUDE_EXTRA_ARGS:-}" Enter
+
+# Wait for the ❯ prompt (claude drew its UI), up to 60s. NOTE: ❯ appears on the
+# welcome screen seconds before the input actually accepts keystrokes, so this is
+# necessary but NOT sufficient — the type-and-verify loop below is what proves
+# the input is live.
+ready=0
+for _ in $(seq 1 120); do
+  cap | grep -q "❯" && { ready=1; break; }
+  sleep 0.5
+done
+[ "$ready" = 1 ] || { echo "claude never drew its UI"; cap; tmux kill-session -t "$SESSION" 2>/dev/null; exit 1; }
+
+# Accept the per-folder "Is this a project you trust?" dialog if it shows (first
+# time claude opens a given repo). Option 1 ("Yes, I trust this folder") is
+# pre-selected, so Enter accepts. This dialog also contains ❯, so it must be
+# cleared before the type-and-verify loop or keystrokes land on the menu.
+for _ in $(seq 1 20); do
+  cap | grep -q "trust this folder" || break
+  tmux send-keys -t "$SESSION" Enter
+  sleep 1
+done
+
+# Type-and-verify: send the prompt, confirm a distinctive chunk of it actually
+# landed in the input box, retry if it didn't (handles the early-❯ race where
+# the welcome screen shows the prompt glyph but MCP init is still eating keys).
+needle="${PROMPT:0:24}"
+typed=0
+for _ in $(seq 1 30); do
+  tmux send-keys -l -t "$SESSION" "$PROMPT"
+  sleep 1
+  if cap | grep -Fq "$needle"; then typed=1; break; fi
+  # Clear whatever partial text may have landed, then retry.
+  tmux send-keys -t "$SESSION" C-u
+  sleep 1
+done
+[ "$typed" = 1 ] || { echo "prompt never landed in the input box"; cap; tmux kill-session -t "$SESSION" 2>/dev/null; exit 1; }
+sleep 0.5
+tmux send-keys -t "$SESSION" Enter
+
+# Busy signals. The robust one is the spinner's elapsed-time-in-parens, which
+# EVERY working state shows — both the pre-stream thinking phase
+# "(8s · thinking with max effort)" and the streaming phase
+# "(24s · ↑ 2.5k tokens · …)", and it survives the 32s→"1m 3s" rollover. We OR
+# in the token arrows, "esc to interrupt", and "Initializing" as belt-and-braces
+# (some TUI versions/states show one but not the others).
+BUSY_RE='esc to interrupt|↓ [0-9]|↑ [0-9]|Initializing|\(([0-9]+m )?[0-9]+s ·'
+
+# Wait for work to START (busy indicator appears), up to 60s. If it never starts,
+# fail loudly rather than silently reporting an empty run.
+started=0
+for _ in $(seq 1 120); do
+  cap | grep -qE "$BUSY_RE" && { started=1; break; }
+  sleep 0.5
+done
+[ "$started" = 1 ] || { echo "agent never started working"; cap; tmux kill-session -t "$SESSION" 2>/dev/null; exit 1; }
+
+# Poll for idle. CRITICAL: Opus 4.8 (extended thinking) renders NO spinner /
+# "esc to interrupt" / timer while it STREAMS its final answer — those appear
+# only during the thinking + tool-use phases ("✻ Marinating… (32s · ↓ 1.3k
+# tokens · thinking with max effort)"). So BUSY_RE reads "not busy" for the whole
+# 10-30s answer stream, and any short not-busy threshold kills the run mid-answer
+# (the truncation bug). We therefore detect "done" by CONTENT STABILITY, not by a
+# spinner string: while the agent streams, the captured pane changes every poll,
+# so stability never accrues; it accrues only once the agent has finished and the
+# static "✻ Brewed for 1m 9s" summary is all that is left. BUSY_RE still hard-
+# resets stability (covers thinking/tool-use/live-timer, where text can briefly
+# sit still). Need STABLE_NEEDED polls (~8s) of zero pane change + ❯ present.
+# Content-stability is model-agnostic — it survives future spinner re-wordings.
+STABLE_NEEDED=16
+prev=""; stable=0
+for _ in $(seq 1 2400); do            # up to ~20 min
+  pane="$(cap)"
+  sig="$(printf '%s' "$pane" | tr -s '[:space:]' ' ')"
+  if printf '%s' "$pane" | grep -qE "$BUSY_RE"; then
+    stable=0                          # thinking / tool use / live timer → busy
+  elif [ -n "$sig" ] && [ "$sig" = "$prev" ] && printf '%s' "$pane" | grep -q "❯"; then
+    stable=$((stable+1)); [ "$stable" -ge "$STABLE_NEEDED" ] && break
+  else
+    stable=0                          # answer still streaming → pane changing
+  fi
+  prev="$sig"
+  sleep 0.5
+done
+sleep 1
+
+tmux capture-pane -p -t "$SESSION" -S - > "$OUT"
+echo "captured $(wc -l < "$OUT") lines -> $OUT"
+grep -oE "Done \([^)]*\)|[A-Z][a-z]+ for ([0-9]+m )?[0-9]+s" "$OUT" | tail -1
+grep -oE "[0-9.]+k?/[0-9.]+M" "$OUT" | tail -1 | sed 's/^/Context /'
+tmux kill-session -t "$SESSION" 2>/dev/null
+
+# Clean tool breakdown from the session logs (main + subagents).
+node "$HERE/parse-session.mjs" "$REPO" 2>/dev/null || true

package/scripts/agent-eval/offload-eval-3arm.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# 3-arm offload eval for ONE indexed repo + ONE question, n reps each.
+#   ARM offload : codegraph attached, managed offload ON  (per-run AI usage log)
+#   ARM raw     : codegraph attached, CODEGRAPH_OFFLOAD_DISABLE=1 (raw source)
+#   ARM nocg    : no codegraph (empty MCP config) -> Read/Grep baseline
+# All arms: claude -p sonnet --effort high. One JSON metrics line/run -> $RESULTS.
+#
+# Usage: offload-eval-3arm.sh <indexed-repo> <tier> <reps> "<question>"
+# Env:   MODEL=sonnet EFFORT=high  RESULTS=<file>  AGENT_EVAL_OUT=<scratch dir>
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ENGINE="$(cd "$HERE/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"
+TARGET="${1:?usage: offload-eval-3arm.sh <indexed-repo> <tier> <reps> \"<question>\"}"
+TIER="${2:?tier}"; REPS="${3:?reps}"; Q="${4:?question}"
+RUNS="$OUT/runs"
+EXTRACT="$HERE/offload-eval-metrics.mjs"
+RESULTS="${RESULTS:-$OUT/results.jsonl}"
+REPO=$(basename "$TARGET")
+mkdir -p "$RUNS"
+command -v claude >/dev/null || { echo "no claude on PATH"; exit 1; }
+[ -d "$TARGET/.codegraph" ] || { echo "not indexed: $TARGET (run offload-eval-setup.sh first)"; exit 1; }
+# Physical path so pkill matches the daemon's real cmdline (macOS /tmp->/private/tmp symlink
+# otherwise makes the kill miss the daemon, and the next arm connects to the SURVIVING daemon
+# — contaminating the raw arm with offload).
+TARGET=$(cd "$TARGET" && pwd -P)
+
+prewarm() { # path  extra-env (e.g. "FOO=bar")
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null; rm -f "$1/.codegraph/daemon.sock" 2>/dev/null; sleep 0.6
+  env ${2:-} CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$1" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$1" \
+    && echo "  daemon warm" || echo "  WARN daemon never bound"
+}
+
+run() { # arm rep mcp-config usage-log-or-dash
+  local arm="$1" rep="$2" cfg="$3" usage="$4" tag="$REPO-$1-$2"
+  [ "$usage" != "-" ] && : > "$usage"
+  # DISALLOW (optional): block sub-agent delegation across all arms so the A/B
+  # measures the retrieval mode, not whether Sonnet decides to spawn a codegraph-blind
+  # Explore subagent (which thrashes regardless and adds huge variance).
+  ( cd "$TARGET" && claude -p "$Q" \
+      --output-format stream-json --verbose --permission-mode bypassPermissions \
+      --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 \
+      ${DISALLOW:+--disallowedTools "$DISALLOW"} \
+      --strict-mcp-config --mcp-config "$cfg" \
+      </dev/null > "$RUNS/$tag.jsonl" 2>"$RUNS/$tag.err" )
+  node "$EXTRACT" --run "$RUNS/$tag.jsonl" --usage "$usage" --arm "$arm" --rep "$rep" \
+      --repo "$REPO" --tier "$TIER" --q "$Q" >> "$RESULTS"
+  node -e 'const o=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8").trim().split("\n").pop());console.log(`  [${o.arm} #${o.rep}] ${o.durationSec}s | main $${o.costUsdMain} ${o.tokBillable} tok | read=${o.read} grep=${o.grep} explore=${o.explore} offload=${o.offloadFired} | AI ${o.ai.calls}call/${o.ai.totalTokens}tok/$${o.ai.costUsd.toFixed(4)} | ok=${o.ok}`)' "$RESULTS"
+}
+
+CFG_OFF="$RUNS/mcp-offload-$REPO.json"; CFG_RAW="$RUNS/mcp-raw-$REPO.json"; CFG_NOCG="$RUNS/mcp-nocg.json"
+USAGE="$RUNS/$REPO-usage.jsonl"
+printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","CODEGRAPH_OFFLOAD_USAGE_LOG=%s","node","%s","serve","--mcp","--path","%s"]}}}' "$USAGE" "$BIN" "$TARGET" > "$CFG_OFF"
+printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","CODEGRAPH_OFFLOAD_DISABLE=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$TARGET" > "$CFG_RAW"
+printf '{"mcpServers":{}}' > "$CFG_NOCG"
+
+# REP_START lets a later batch ADD reps without clobbering earlier jsonls
+# (e.g. REP_START=4 REPS=3 -> reps 4,5,6; default starts at 1).
+START="${REP_START:-1}"; END=$((START + REPS - 1))
+echo "###### repo=$REPO tier=$TIER reps=$START..$END model=${MODEL:-sonnet}/${EFFORT:-high}"
+echo "###### Q=$Q"
+echo "== ARM offload =="; prewarm "$TARGET" "CODEGRAPH_OFFLOAD_USAGE_LOG=$USAGE"
+for r in $(seq "$START" "$END"); do run offload "$r" "$CFG_OFF" "$USAGE"; done
+pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.codegraph/daemon.sock" 2>/dev/null; sleep 1
+echo "== ARM raw =="; prewarm "$TARGET" "CODEGRAPH_OFFLOAD_DISABLE=1"
+for r in $(seq "$START" "$END"); do run raw "$r" "$CFG_RAW" "-"; done
+pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.codegraph/daemon.sock" 2>/dev/null; sleep 1
+echo "== ARM nocg =="
+for r in $(seq "$START" "$END"); do run nocg "$r" "$CFG_NOCG" "-"; done
+echo "###### DONE $REPO"

package/scripts/agent-eval/offload-eval-cost.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Cost/token analysis for the 3-arm offload eval, with a MAIN-vs-SUBAGENT split.
+//
+// The explore-subagent question. With delegation ALLOWED, the nocg arm spawns a
+// Claude Code Explore subagent; the codegraph arms do all work in the main agent.
+// Two facts make naive accounting wrong:
+//   1. The Explore subagent runs on HAIKU 4.5; the main agent on SONNET 4.6.
+//      So per-token cost differs ~3x between them — you cannot price both the same.
+//   2. The subagent's consumption is ~95% cache-reads. At Haiku's $0.10/MTok
+//      cache-read rate, a huge TOKEN volume is a small DOLLAR cost.
+//
+// Rather than re-derive cost from raw token counts (and guess the cache TTL —
+// Claude Code uses 1-hour ephemeral cache here, 2x write, not 5-min), we read
+// Claude Code's OWN authoritative accounting from the `result` event:
+//   result.modelUsage[model].costUSD  — per-model cost CC itself billed
+//   result.total_cost_usd             — their sum (INCLUDES the Haiku subagent;
+//                                       the handoff's "excludes subagent" was wrong)
+// The model split IS the agent split here: sonnet => main, haiku => Explore subagent
+// (only nocg spawns one, and only nocg shows haiku usage). Token volume is still
+// summed per-model from modelUsage for the separate "tokens" story.
+//
+// Usage: offload-eval-cost.mjs <runs-dir> <repo> [reps]
+//   e.g. offload-eval-cost.mjs /tmp/cg-offload-eval/runs trezor 3
+import { readFileSync, existsSync } from 'fs';
+
+const MAIN_TIER = /sonnet/;   // main agent
+const SUB_TIER  = /haiku/;    // Claude Code Explore subagent
+
+const [,, runsDir, repo, repsArg] = process.argv;
+if (!runsDir || !repo) { console.error('usage: offload-eval-cost.mjs <runs-dir> <repo> [reps]   (env ARMS=nocg,raw,offload)'); process.exit(1); }
+const REPS = Number(repsArg || 3);
+// Arms to analyze (file stems `<repo>-<arm>-<rep>.jsonl`). Override for the style A/B:
+// ARMS=raw,refs,map,src. nocg's Haiku subagent is the only sub-tier; the rest are main-only.
+const ARMS = (process.env.ARMS || 'nocg,raw,offload').split(',').map((s) => s.trim()).filter(Boolean);
+
+const toks = (u) => (u.inputTokens||0)+(u.outputTokens||0)+(u.cacheReadInputTokens||0)+(u.cacheCreationInputTokens||0);
+
+function analyzeRun(file) {
+  let result = null, agentCalls = 0;
+  const tools = {}, subPids = new Set();
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (!line) continue;
+    let e; try { e = JSON.parse(line); } catch { continue; }
+    if (e.parent_tool_use_id && e.message?.usage) subPids.add(e.parent_tool_use_id);
+    if (e.type === 'assistant' && Array.isArray(e.message?.content))
+      for (const b of e.message.content)
+        if (b.type === 'tool_use') { tools[b.name] = (tools[b.name]||0)+1; if (b.name === 'Agent') agentCalls++; }
+    if (e.type === 'result') result = e;
+  }
+  // Authoritative cost + tokens from Claude Code's per-model accounting.
+  const mu = result?.modelUsage || {};
+  const main = { cost: 0, tok: 0 }, sub = { cost: 0, tok: 0 };
+  for (const [model, u] of Object.entries(mu)) {
+    const bucket = SUB_TIER.test(model) ? sub : main; // sonnet/anything-else => main
+    bucket.cost += u.costUSD || 0;
+    bucket.tok  += toks(u);
+  }
+  return {
+    main, sub, subagents: subPids.size, agentCalls,
+    ccTotal: result?.total_cost_usd ?? null,
+    ok: result?.subtype === 'success',
+    durationSec: result?.duration_ms ? +(result.duration_ms/1000).toFixed(1) : null,
+    models: Object.keys(mu), tools,
+  };
+}
+
+const k = (n) => (n/1000).toFixed(0).padStart(5) + 'K';
+const d = (n) => '$' + n.toFixed(3);
+const cost = (b) => b.cost;
+const tot  = (b) => b.tok;
+
+const byArm = {};
+for (const arm of ARMS) {
+  const runs = [];
+  for (let r = 1; r <= REPS; r++) {
+    const f = `${runsDir}/${repo}-${arm}-${r}.jsonl`;
+    if (existsSync(f)) runs.push({ rep: r, ...analyzeRun(f) });
+  }
+  byArm[arm] = runs;
+}
+
+// Per-run detail. Cost is Claude Code's own modelUsage.costUSD (authoritative,
+// per-model pricing + correct cache TTL). MAIN=Sonnet, SUB=Haiku Explore subagent.
+// cc-check: main$+sub$ must equal result.total_cost_usd (delta should be ~0).
+console.log(`\n=== ${repo}: per-run main(Sonnet)/sub(Haiku) split — Claude Code's own cost accounting ===`);
+console.log('arm      rep | subAg | MAIN(sonnet) tok / $ | SUB(haiku) tok / $   | TOTAL tok / $   | cc_total Δ | dur  reads');
+for (const arm of ARMS) for (const r of byArm[arm]) {
+  const mC = cost(r.main), sC = cost(r.sub), mT = tot(r.main), sT = tot(r.sub);
+  const reads = r.tools['Read'] || 0, grep = (r.tools['Grep']||0)+(r.tools['Bash']||0)+(r.tools['Glob']||0);
+  const explore = r.tools['mcp__codegraph__codegraph_explore'] || 0;
+  const delta = (mC + sC) - (r.ccTotal || 0); // should be ~0
+  console.log(
+    `${arm.padEnd(8)} #${r.rep} | ${String(r.subagents).padStart(2)}    | ${k(mT)} ${d(mC).padStart(7)}     | ${k(sT)} ${d(sC).padStart(7)}     | ${k(mT+sT)} ${d(mC+sC).padStart(7)} | ${d(r.ccTotal||0).padStart(7)} ${(delta>=0?'+':'')+delta.toFixed(4)} | ${String(r.durationSec).padStart(5)} r=${reads} g=${grep} x=${explore}`
+  );
+}
+
+// Per-arm means
+const mean = (arr, f) => arr.length ? arr.reduce((s,x)=>s+f(x),0)/arr.length : 0;
+console.log(`\n=== ${repo}: per-arm MEANS (n per arm) ===`);
+console.log('arm      n | main $   sub $    TOTAL $  | main tok   sub tok    TOTAL tok | %$ in sub | %tok in sub');
+for (const arm of ARMS) {
+  const runs = byArm[arm]; if (!runs.length) continue;
+  const mC = mean(runs, r=>cost(r.main)), sC = mean(runs, r=>cost(r.sub));
+  const mT = mean(runs, r=>tot(r.main)),  sT = mean(runs, r=>tot(r.sub));
+  const pctSubC = (mC+sC) ? (100*sC/(mC+sC)) : 0;
+  const pctSubT = (mT+sT) ? (100*sT/(mT+sT)) : 0;
+  console.log(
+    `${arm.padEnd(8)} ${runs.length} | ${d(mC).padStart(7)} ${d(sC).padStart(7)} ${d(mC+sC).padStart(7)} | ${k(mT)} ${k(sT)} ${k(mT+sT)} | ${pctSubC.toFixed(0).padStart(3)}%      | ${pctSubT.toFixed(0).padStart(3)}%`
+  );
+}
+
+// Headline ladders — cost, tokens, duration, all vs a baseline (nocg if present, else first arm).
+console.log(`\n=== Ladders (mean, incl. subagent) ===`);
+const totals = ARMS.map(a => ({ a, c: mean(byArm[a], r=>cost(r.main)+cost(r.sub)), t: mean(byArm[a], r=>tot(r.main)+tot(r.sub)) })).filter(x=>byArm[x.a].length);
+const base = totals.find(x=>x.a==='nocg') ?? totals[0];
+const bn = base?.a ?? '?';
+console.log(`  COST (vs ${bn}):`);
+for (const x of totals) {
+  const vs = base && base.c ? ` (${((x.c/base.c-1)*100>=0?'+':'')}${((x.c/base.c-1)*100).toFixed(0)}%)` : '';
+  console.log(`    ${x.a.padEnd(8)} ${d(x.c)}${vs}`);
+}
+console.log(`  TOKENS (vs ${bn}):`);
+for (const x of totals) {
+  const vs = base && base.t ? ` (${((x.t/base.t-1)*100>=0?'+':'')}${((x.t/base.t-1)*100).toFixed(0)}%)` : '';
+  console.log(`    ${x.a.padEnd(8)} ${k(x.t)}${vs}`);
+}
+console.log(`  DURATION (wall-clock, vs ${bn}):`);
+const durs = ARMS.map(a => ({ a, s: mean(byArm[a].filter(r=>r.durationSec!=null), r=>r.durationSec) })).filter(x=>byArm[x.a].length);
+const dbase = durs.find(x=>x.a==='nocg') ?? durs[0];
+for (const x of durs) {
+  const vs = dbase && dbase.s ? ` (${((x.s/dbase.s-1)*100>=0?'+':'')}${((x.s/dbase.s-1)*100).toFixed(0)}%)` : '';
+  console.log(`    ${x.a.padEnd(8)} ${x.s.toFixed(0)}s${vs}`);
+}

package/scripts/agent-eval/offload-eval-effort.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Effort A/B — does CODEGRAPH_OFFLOAD_EFFORT=high improve offload SYNTHESIS FIDELITY vs low?
+// Probe-based (no agent): for each repo × effort × rep, run codegraph_explore with the offload
+// ON on the canonical question, capture the synthesized answer + AI tokens/cost/latency, then
+// Sonnet-judge that answer's fidelity vs source-verified ground truth. Isolates the synthesis
+// from agent/adoption noise. Requires `codegraph login` (managed offload) + indexed repos.
+//
+// Env: REPS (default 3) · CG_ENGINE (engine repo) · AGENT_EVAL_OUT (repos under /repos) · CONC (judge concurrency)
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { resolve, dirname, join } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ENGINE = process.env.CG_ENGINE || resolve(HERE, '..', '..');
+const OUT = process.env.AGENT_EVAL_OUT || '/tmp/cg-offload-eval';
+const REPOS = join(OUT, 'repos');
+const GT = JSON.parse(readFileSync(resolve(HERE, 'offload-eval-ground-truth.json'), 'utf8'));
+const REPS = Number(process.env.REPS || 3);
+const CONC = Number(process.env.CONC || 4);
+const EFFORTS = (process.env.EFFORTS_FILTER || 'low,high').split(',');
+const ONLY = process.env.REPOS_FILTER ? new Set(process.env.REPOS_FILTER.split(',')) : null;
+const TIER = { mtkruto: 'small', postybirb: 'medium', shapeshift: 'complex', trezor: 'large' };
+
+const load = async (rel) => import(pathToFileURL(resolve(ENGINE, 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 load engine from', ENGINE); process.exit(2);
+}
+
+const fidPrompt = (gt, ans) => `You are scoring the FIDELITY of a machine-synthesized code-exploration answer against verified ground truth. Do NOT use any tools.
+
+QUESTION: ${gt.question}
+
+VERIFIED GROUND TRUTH (the actual call path + files):
+${gt.truth}
+
+SYNTHESIZED ANSWER (to score):
+${ans || '(empty)'}
+
+Judge: (1) is the traced call path correct vs ground truth? (2) are the cited files/symbols correct (not fabricated)? (3) if it gave a "Coverage:" verdict, was it honest? A confident WRONG trace is the worst outcome — penalize it harder than an honest partial.
+Output ONLY minified JSON: {"verdict":"pass|partial|fail","score":<0-100>,"fabrication":<true|false>,"coverageHonest":<true|false>,"note":"<=20 words"}`;
+
+const askJudge = (prompt) => new Promise((res) => {
+  execFile('claude', ['-p', prompt, '--model', 'sonnet', '--effort', 'high', '--max-budget-usd', '0.5',
+    '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}'],
+    { cwd: OUT, maxBuffer: 1 << 24, timeout: 120000 }, (err, stdout) => {
+      const m = (stdout || '').match(/\{[\s\S]*\}/);
+      if (!m) return res({ verdict: 'error', score: null, note: (err ? err.message : 'no json').slice(0, 60) });
+      try { res(JSON.parse(m[0])); } catch { res({ verdict: 'error', score: null }); }
+    });
+});
+
+// ---- 1. Probe: collect synthesized answers at each effort -------------------
+const records = [];
+for (const repo of Object.keys(GT)) {
+  if (ONLY && !ONLY.has(repo)) continue;
+  const dir = join(REPOS, repo);
+  if (!existsSync(join(dir, '.codegraph'))) { console.error('skip (not indexed):', repo); continue; }
+  const cg = CodeGraph.openSync(dir);
+  const h = new ToolHandler(cg);
+  for (const effort of EFFORTS) {
+    for (let rep = 1; rep <= REPS; rep++) {
+      process.env.CODEGRAPH_OFFLOAD_EFFORT = effort;
+      const usageLog = join(tmpdir(), `effort-${repo}-${effort}-${rep}.jsonl`);
+      try { rmSync(usageLog); } catch { /* none */ }
+      process.env.CODEGRAPH_OFFLOAD_USAGE_LOG = usageLog;
+      let answer = '';
+      try { answer = (await h.execute('codegraph_explore', { query: GT[repo].question }))?.content?.[0]?.text ?? ''; }
+      catch (e) { console.error(`  ${repo}/${effort}#${rep} explore failed: ${e?.message}`); }
+      const fired = /Synthesized by CodeGraph/.test(answer);
+      const ai = { tokens: 0, cost: 0, ms: 0 };
+      if (existsSync(usageLog)) for (const e of readFileSync(usageLog, 'utf8').split('\n').filter(Boolean).map(JSON.parse)) {
+        ai.tokens += e.totalTokens || 0; ai.cost += e.costUsd || 0; ai.ms += e.ms || 0;
+      }
+      records.push({ repo, tier: TIER[repo], effort, rep, fired, ai, answer });
+      console.error(`  ${repo}/${effort}#${rep}: fired=${fired} ${ai.tokens}tok $${ai.cost.toFixed(4)} ${ai.ms}ms`);
+    }
+  }
+  try { cg.close?.(); } catch { /* none */ }
+}
+
+// ---- 2. Judge fidelity (concurrency) ---------------------------------------
+console.error(`\njudging ${records.length} answers (concurrency ${CONC})...`);
+let done = 0;
+const q = [...records];
+async function worker() { while (q.length) { const r = q.shift(); r.fid = await askJudge(fidPrompt(GT[r.repo], r.answer)); console.error(`  [${++done}/${records.length}] ${r.repo}/${r.effort}#${r.rep}: ${r.fid.verdict} ${r.fid.score ?? ''}`); } }
+await Promise.all(Array.from({ length: CONC }, worker));
+writeFileSync(join(OUT, 'effort-results.jsonl'), records.map((r) => JSON.stringify(r)).join('\n') + '\n');
+
+// ---- 3. Aggregate: low vs high per repo ------------------------------------
+const med = (a) => { a = a.filter((x) => x != null).sort((x, y) => x - y); return a.length ? (a.length % 2 ? a[(a.length - 1) / 2] : (a[a.length / 2 - 1] + a[a.length / 2]) / 2) : null; };
+console.log(`\n${'='.repeat(80)}\nEFFORT A/B — offload synthesis fidelity (probe, n=${REPS}/cell)\n${'='.repeat(80)}`);
+console.log(`${'repo'.padEnd(11)} ${'tier'.padEnd(8)} ${'effort'.padEnd(6)} fired  ${'fid(med)'.padStart(8)} ${'fab%'.padStart(5)} ${'AItok'.padStart(7)} ${'AIcost'.padStart(8)} ${'ms(med)'.padStart(8)}`);
+for (const repo of Object.keys(GT)) {
+  for (const effort of EFFORTS) {
+    const rs = records.filter((r) => r.repo === repo && r.effort === effort);
+    if (!rs.length) continue;
+    const fids = rs.map((r) => r.fid?.score).filter((x) => x != null);
+    const fab = rs.filter((r) => r.fid?.fabrication === true).length;
+    console.log(`${repo.padEnd(11)} ${TIER[repo].padEnd(8)} ${effort.padEnd(6)} ${rs.filter((r) => r.fired).length}/${rs.length}   ${String(med(fids) ?? '—').padStart(8)} ${String(Math.round(100 * fab / rs.length) + '%').padStart(5)} ${String(Math.round(med(rs.map((r) => r.ai.tokens)) / 1000) + 'k').padStart(7)} ${('$' + (med(rs.map((r) => r.ai.cost)) ?? 0).toFixed(4)).padStart(8)} ${String(med(rs.map((r) => r.ai.ms)) ?? '—').padStart(8)}`);
+  }
+}
+console.log('');

package/scripts/agent-eval/offload-eval-frontload-matrix.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Run the FRONTLOAD arm across all 4 tiers (n reps), then judge + merge with the existing
+# matrix (offload/raw/nocg in $OUT/judged.jsonl, if present) + emit a combined summary.
+# Env: REPS (default 3)  AGENT_EVAL_OUT=<scratch dir>
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"
+GT="$HERE/offload-eval-ground-truth.json"
+REPS="${REPS:-3}"
+export RESULTS="$OUT/results-fl.jsonl"
+: > "$RESULTS"; rm -f "$OUT/runs/hook-debug.log"
+for repo in mtkruto postybirb shapeshift trezor; do
+  case "$repo" in mtkruto) tier=small;; postybirb) tier=medium;; shapeshift) tier=complex;; trezor) tier=large;; esac
+  Q=$(node -e "console.log(JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]].question)" "$GT" "$repo")
+  echo ""; echo "### $repo ($tier)  $(date +%H:%M:%S)"
+  bash "$HERE/offload-eval-frontload.sh" "$OUT/repos/$repo" "$tier" "$REPS" "$Q"
+done
+echo ""
+echo "frontload: $(wc -l < "$RESULTS") runs | hook injections: $(grep -c INJECTED "$OUT/runs/hook-debug.log" 2>/dev/null) | errors: $(grep -c ERROR "$OUT/runs/hook-debug.log" 2>/dev/null)"
+echo "=== JUDGE frontload ==="
+node "$HERE/offload-eval-judge.mjs" --results "$RESULTS" --truth "$GT" --out "$OUT/judged-fl.jsonl" --concurrency 4 2>&1 | tail -4
+if [ -f "$OUT/judged.jsonl" ]; then cat "$OUT/judged.jsonl" "$OUT/judged-fl.jsonl" > "$OUT/judged-all.jsonl"; else cp "$OUT/judged-fl.jsonl" "$OUT/judged-all.jsonl"; fi
+echo "=== COMBINED SUMMARY ==="
+node "$HERE/offload-eval-summarize.mjs" "$OUT/judged-all.jsonl"
+echo "###### FRONTLOAD MATRIX DONE"

package/scripts/agent-eval/offload-eval-frontload.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# FRONTLOAD arm (approach 1): codegraph attached (offload-disabled) + the front-load
+# UserPromptSubmit hook (offload-eval-hook.mjs), n reps, appended to $RESULTS. Compare against
+# the matrix's raw/nocg baselines. Usage: offload-eval-frontload.sh <indexed-repo> <tier> <reps> "<Q>"
+# Env: MODEL=sonnet EFFORT=high  RESULTS=<file>  AGENT_EVAL_OUT=<scratch dir>
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ENGINE="$(cd "$HERE/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"
+TARGET="${1:?repo}"; TIER="${2:?tier}"; REPS="${3:?reps}"; Q="${4:?question}"
+RUNS="$OUT/runs"
+EXTRACT="$HERE/offload-eval-metrics.mjs"
+RESULTS="${RESULTS:-$OUT/results-fl.jsonl}"
+REPO=$(basename "$TARGET")
+mkdir -p "$RUNS"
+[ -d "$TARGET/.codegraph" ] || { echo "not indexed: $TARGET"; exit 1; }
+TARGET=$(cd "$TARGET" && pwd -P)
+
+CFG="$RUNS/mcp-fl-$REPO.json"
+printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","CODEGRAPH_OFFLOAD_DISABLE=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$TARGET" > "$CFG"
+# Generate the hook settings pointing at the persisted hook; enable its debug log so we can
+# count injections (claude passes this env down to the spawned hook process).
+HOOKCFG="$RUNS/frontload-settings.json"
+printf '{"hooks":{"UserPromptSubmit":[{"hooks":[{"type":"command","command":"node %s/offload-eval-hook.mjs"}]}]}}' "$HERE" > "$HOOKCFG"
+export CG_FRONTLOAD_DEBUG="$RUNS/hook-debug.log"
+
+prewarm() {
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null; rm -f "$1/.codegraph/daemon.sock" 2>/dev/null; sleep 0.6
+  env CODEGRAPH_OFFLOAD_DISABLE=1 CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$1" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$1" \
+    && echo "  daemon warm" || echo "  WARN no daemon"
+}
+
+echo "###### FRONTLOAD repo=$REPO tier=$TIER reps=$REPS"
+prewarm "$TARGET"
+for r in $(seq 1 "$REPS"); do
+  tag="$REPO-frontload-$r"
+  ( cd "$TARGET" && 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 "$HOOKCFG" \
+      </dev/null > "$RUNS/$tag.jsonl" 2>"$RUNS/$tag.err" )
+  node "$EXTRACT" --run "$RUNS/$tag.jsonl" --usage "-" --arm frontload --rep "$r" --repo "$REPO" --tier "$TIER" --q "$Q" >> "$RESULTS"
+  node -e 'const o=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8").trim().split("\n").pop());console.log(`  [frontload #${o.rep}] ${o.durationSec}s | main $${o.costUsdMain} ${o.tokBillable}tok | read=${o.read} grep=${o.grep} agentExplore=${o.explore} | ok=${o.ok}`)' "$RESULTS"
+done
+pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.codegraph/daemon.sock" 2>/dev/null
+echo "###### FRONTLOAD DONE $REPO (cumulative hook injections: $(grep -c INJECTED "$CG_FRONTLOAD_DEBUG" 2>/dev/null))"

package/scripts/agent-eval/offload-eval-ground-truth.json

@@ -0,0 +1,18 @@
+{
+  "mtkruto": {
+    "question": "How does calling the high-level client.sendMessage() method get the message serialized into a TL/MTProto request and sent over the network transport to Telegram's servers? Trace the call path.",
+    "truth": "Verified call path (small TS Telegram-client lib):\n1. Client.sendMessage — client/6_client.ts:1852 → calls this.#messageManager.sendMessage(...) (1853)\n2. MessageManager.sendMessage — client/3_message_manager.ts:330 → builds the TL function {_:\"messages.sendMessage\", peer, message,...} and calls this.#c.invoke(...) (~377)\n3. c.invoke closure / Client.#invoke — client/6_client.ts:279/887 → resolves a ClientEncrypted and calls client.invoke(function_) (897)\n4. ClientEncrypted.invoke — client/2_client_encrypted.ts:324 → this.#send(function_) (325)\n5. ClientEncrypted.#send — client/2_client_encrypted.ts:261 → SERIALIZES via Api.serializeObject(function_) (290), then this.session.send(body) (296)\n   - Serialization: Api.serializeObject (tl/2_telegram.ts:38) → new TLWriter().writeObject(...) (tl/1_tl_writer.ts) writes constructor id + fields\n6. SessionEncrypted.send — session/2_session_encrypted.ts:193 → ENQUEUES a PendingMessage and wakes the send loop (#awakeSendLoop) [DYNAMIC: async queue, not a direct call]\n7. SessionEncrypted.#sendLoopBody (AbortableLoop) — session/2_session_encrypted.ts:282 → #encryptMessage (serializeMessage tl/2_message.ts + IGE-256 AES) then this.transport.transport.send(payload) (339)\n8. Transport.send — TransportAbridged.send (transport/1_transport_abridged.ts:71) or TransportIntermediate → this.#connection.write(encrypt(framed))\n9. ConnectionTCP.write (connection/1_connection_tcp.ts:96) or ConnectionWebSocket.write — bytes exit the process.\nKEY SYMBOLS a correct answer must hit: sendMessage → MessageManager.sendMessage → invoke (ClientEncrypted.invoke/#send) → Api.serializeObject/TLWriter → SessionEncrypted.send (queue) → #sendLoopBody/#encryptMessage → Transport.send → Connection.write.\nDYNAMIC BOUNDARIES: the invoke indirection (closure→#invoke→ClientEncrypted), and the send-loop QUEUE between SessionEncrypted.send and #sendLoopBody (async, no direct edge)."
+  },
+  "postybirb": {
+    "question": "How does submitting/queueing a post reach the website-specific code that actually uploads to a target website? Trace the path from the submission entry point in the NestJS server to a concrete website service's post implementation.",
+    "truth": "Verified call path (NestJS+Electron, server under electron-app/src/server/):\n1. Entry: PostController.queue (submission/post/post.controller.ts:33, POST queue/:id) OR SubmissionService.queueScheduledSubmissions (submission/submission.service.ts, @Interval(60000) scheduler) — both call PostService.queue\n2. PostService.queue — submission/post/post.service.ts:68 → this.post(submission)\n3. PostService.post (private) — post.service.ts:206 → this.createPoster(...) for each non-default SubmissionPart\n4. PostService.createPoster — post.service.ts:373 → website = this.websites.getWebsiteModule(part.website) [part.website is a STRING]\n5. WebsiteProvider.getWebsiteModule — websites/website-provider.service.ts:86 → websiteModulesMap[name.toLowerCase()] [DYNAMIC: string-keyed registry of DI-injected Website singletons]; then new Poster(..., website, ...)\n6. Poster constructor — submission/post/poster.ts:117 → setTimeout(this.post.bind(this), delay) [DYNAMIC: async timer, min ~5s]\n7. Poster.post (poster.ts:131) → performPost (171) → attemptPost (217)\n8. Poster.attemptPost — poster.ts:217 → this.website.postFileSubmission(token, data, accountData) [DYNAMIC: polymorphic dispatch on abstract Website] (or postNotificationSubmission)\n9. Website.postFileSubmission (abstract) — websites/website.base.ts:102\n10. Concrete e.g. FurAffinity.postFileSubmission — websites/fur-affinity/fur-affinity.service.ts:231 → multi-step HTTP upload (GET /submit, POST /submit/upload multipart, POST /submit/finalize)\nKEY SYMBOLS: PostService.queue → PostService.post → createPoster → WebsiteProvider.getWebsiteModule (registry) → Poster (setTimeout) → Poster.attemptPost → Website.postFileSubmission (abstract base) → a concrete website service (e.g. FurAffinity).\nDYNAMIC BOUNDARIES: NestJS DI builds the website registry; string-keyed map lookup; setTimeout defers Poster.post; polymorphic dispatch on the abstract Website base. A correct answer must reach a concrete website's post via the registry + base class, not stop at PostService."
+  },
+  "shapeshift": {
+    "question": "How does executing a swap work in ShapeShift — from the code that fetches quotes and selects a swapper down to a specific swapper's execute/trade? Name the swapper interface, the registry, and one concrete swapper, and trace the path.",
+    "truth": "Verified call path (large multi-package monorepo; swap logic in packages/swapper + execution in src/lib):\nQUOTE/REGISTRY layer:\n- Swapper interface = the `Swapper` type (execute methods) + `SwapperApi` type (getTradeQuote/getUnsignedTx) — packages/swapper/src/types.ts (~846/897)\n- Registry = `swappers: Record<SwapperName,(SwapperApi & Swapper)>` — packages/swapper/src/constants.ts:52 (merges e.g. thorchainSwapper + thorchainApi)\n- Aggregator: swapperApi RTK endpoint getTradeQuote/getTradeRates (src/state/apis/swapper/swapperApi.ts:78/156) → getTradeQuotes (packages/swapper/src/swapper.ts:18/26): swapper = swappers[swapperName]; swapper.getTradeQuote(...) [DYNAMIC interface dispatch]\n- Concrete (THORChain): thorchainApi.getTradeQuote (swappers/ThorchainSwapper/endpoints.ts → getTradeQuote/getTradeQuote.ts:15) → getL1RateOrQuote → getQuote (thorService HTTP)\nSELECTION: tradeQuoteSlice selectors rank quotes (selectSortedTradeQuotes / selectActiveSwapperName) [DYNAMIC: winner chosen by ranking/user]\nEXECUTION layer:\n- useTradeExecution (src/components/MultiHopTrade/.../hooks/useTradeExecution.tsx:200/476) → new TradeExecution(); execution.execEvmTransaction(...) (CowSwap: execEvmMessage)\n- TradeExecution.execEvmTransaction — src/lib/tradeExecution.ts:326 → _execWalletAgnostic(...) (372)\n- TradeExecution._execWalletAgnostic — tradeExecution.ts:136 → swapper = swappers[swapperName] (149) [DYNAMIC registry]; buildSignBroadcast → swapper.getUnsignedEvmTransaction(...) (355) then swapper.executeEvmTransaction(unsignedTx, {signAndBroadcastTransaction}) (367) [DYNAMIC SwapperApi/Swapper interface]\n- Concrete (THORChain): thorchainSwapper.executeEvmTransaction (swappers/ThorchainSwapper/ThorchainSwapper.ts → utils.ts:181) delegates to callbacks.signAndBroadcastTransaction (wallet). CowSwap alt: cowSwapper.executeEvmMessage → signCowOrder + cowService.post.\nKEY SYMBOLS: Swapper/SwapperApi types, swappers registry (constants.ts), getTradeQuotes (swapper.ts), TradeExecution._execWalletAgnostic, swapper.getUnsignedEvmTransaction/executeEvmTransaction, one concrete swapper (thorchainSwapper/zrxSwapper/cowSwapper).\nDYNAMIC BOUNDARIES: swappers[name] registry lookup (2 sites); all hops into a concrete swapper are via the Swapper/SwapperApi interface, never a direct function. A correct answer must name the interface + registry and reach a concrete swapper through interface dispatch."
+  },
+  "trezor": {
+    "question": "How does sending a crypto transaction flow from the send form's review/sign action through to signing it via @trezor/connect (TrezorConnect.signTransaction)? Trace the call path.",
+    "truth": "Verified call path (trezor-suite monorepo; app in packages/suite, shared logic in suite-common/wallet-core, device API in packages/connect):\n1. ReviewButton.handleButtonReviewClick — packages/suite/src/views/wallet/send/TotalSent/ReviewButton.tsx:120 → signTransaction() (= useSendForm's sign)\n2. useSendForm.sign (exported as signTransaction) — packages/suite/src/hooks/wallet/useSendForm.ts:278 → dispatch(signAndPushSendFormTransactionThunk({formState, precomposedTransaction, selectedAccount})) [DYNAMIC: redux thunk]\n3. signAndPushSendFormTransactionThunk — packages/suite/src/actions/wallet/send/sendFormThunks.ts:237 → (first enhancePrecomposedTransactionThunk) then dispatch(signTransactionThunk({...})) [cross-package: thunk from suite-common/wallet-core]\n4. signTransactionThunk (coin-routing hub) — suite-common/wallet-core/src/send/sendFormThunks.ts:532/573 → networkType branch → dispatch(signBitcoinSendFormTransactionThunk) (ethereum→signEthereumSendFormTransactionThunk, etc.) [DYNAMIC: runtime coin dispatch]\n5. signBitcoinSendFormTransactionThunk — suite-common/wallet-core/src/send/sendFormBitcoinThunks.ts:394 → await TrezorConnect.signTransaction(signPayload)\n6. TrezorConnect.signTransaction (facade) — packages/connect-common/src/factory.ts → closure calls impl.call({method:'signTransaction',...}) [DYNAMIC: facade / iframe-or-module boundary]\n7. CoreInModule.call — packages/connect/src/impl/core-in-module.ts:171 → posts CORE_CALL to core (deferred promise)\n8. Core.onCall → getMethod — packages/connect/src/core/index.ts → getMethod resolves 'signTransaction' → new SignTransaction(message) [DYNAMIC: name→class]\n9. SignTransaction.run — packages/connect/src/api/signTransaction.ts:317 → signTx via device.getCommands().typedCall (protobuf to device). After signing, signAndPushSendFormTransactionThunk → pushSendFormTransactionThunk → TrezorConnect.pushTransaction.\nKEY SYMBOLS: ReviewButton → useSendForm.sign → signAndPushSendFormTransactionThunk (suite) → signTransactionThunk (wallet-core, coin hub) → signBitcoinSendFormTransactionThunk → TrezorConnect.signTransaction → connect factory/CoreInModule.call → SignTransaction.run.\nDYNAMIC BOUNDARIES: every suite→wallet-core hop is a redux thunk dispatch; signTransactionThunk branches by networkType at runtime; TrezorConnect is a dynamically-built facade crossing an iframe/module boundary; the SignTransaction class is resolved by name. A correct answer must cross suite→wallet-core→connect and reach TrezorConnect.signTransaction / SignTransaction.run, not stop at the UI."
+  }
+}

package/scripts/agent-eval/offload-eval-hook.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook — APPROACH 1: additive context-injection.
+// Front-loads codegraph's structural answer for flow/impact/"how/where" prompts so the
+// agent's reflex grep/read has nothing left to find. Strictly additive (never blocks),
+// gated to structural prompts (no cost otherwise), and uses RAW explore (offload disabled)
+// so the injected context is accurate — never the (currently low-fidelity) synthesis.
+//
+// Reads {prompt, cwd} as JSON on stdin; prints the explore result to stdout (which Claude
+// Code injects into the agent's context). Any failure -> silent exit 0 (degradable).
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { resolve, join, dirname } from 'node:path';
+import { existsSync, readFileSync, appendFileSync } from 'node:fs';
+
+// Resolve the engine repo from this script's own location (scripts/agent-eval/ -> ../..),
+// overridable with CG_ENGINE. The hook ships inside the repo, so it finds its own dist.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ENGINE = process.env.CG_ENGINE || resolve(HERE, '..', '..');
+const BUDGET = Number(process.env.CG_FRONTLOAD_BUDGET || 16000);
+
+// Debug log only when CG_FRONTLOAD_DEBUG is set to a file path (the harness points it at a
+// log to count injections); off by default so the shipped hook writes nothing extra.
+const DBG = process.env.CG_FRONTLOAD_DEBUG;
+const dbg = (m) => { if (!DBG) return; try { appendFileSync(DBG, `[${new Date().toISOString()}] ${m}\n`); } catch { /* ignore */ } };
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch (e) { dbg('stdin parse fail: ' + e.message); }
+const prompt = String(input.prompt || '');
+const cwd = String(input.cwd || process.cwd());
+dbg(`invoked: promptLen=${prompt.length} cwd=${cwd}`);
+
+// Gate: only structural / flow / impact / where-how questions. Cheap regex; silent no-op
+// otherwise so non-structural prompts ("fix this typo") cost nothing.
+const STRUCTURAL = /\b(how|where|trace|flow|path|reach(es|ed)?|call(s|ed|er|ers|ee)?|depend|impact|affect|wire[ds]?|connect|implement|architect|structure|breaks?|what calls|why does)\b/i;
+if (!prompt || !STRUCTURAL.test(prompt)) { dbg('gate: non-structural, no-op'); process.exit(0); }
+dbg('gate: structural PASS');
+
+// Find the index: cwd, then walk up a few levels.
+let root = cwd, found = null;
+for (let i = 0; i < 6 && root; i++) {
+  if (existsSync(join(root, '.codegraph'))) { found = root; break; }
+  const parent = resolve(root, '..'); if (parent === root) break; root = parent;
+}
+if (!found) { dbg(`no .codegraph found from cwd=${cwd}`); process.exit(0); }
+dbg(`found index at ${found}`);
+
+try {
+  process.env.CODEGRAPH_OFFLOAD_DISABLE = '1'; // raw, accurate — never the unfixed offload
+  process.env.CODEGRAPH_TELEMETRY = '0'; process.env.DO_NOT_TRACK = '1';
+  const load = async (rel) => import(pathToFileURL(resolve(ENGINE, 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;
+  if (typeof CodeGraph?.openSync !== 'function' || typeof ToolHandler !== 'function') process.exit(0);
+
+  // Retry once on a transient busy/locked index (the hook's openSync can race a
+  // freshly-warming daemon on the first prompt of a session).
+  let text = '';
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      const cg = CodeGraph.openSync(found);
+      const h = new ToolHandler(cg);
+      const res = await h.execute('codegraph_explore', { query: prompt });
+      text = res?.content?.[0]?.text ?? '';
+      try { cg.close?.(); } catch { /* ignore */ }
+      dbg(`explore attempt ${attempt} returned ${text.length} chars`);
+      break;
+    } catch (e) {
+      dbg(`explore attempt ${attempt} failed: ${e?.message || e}`);
+      if (attempt === 2) throw e;
+      await new Promise((r) => setTimeout(r, 800));
+    }
+  }
+  if (!text.trim()) { dbg('empty explore result, no-op'); process.exit(0); }
+  if (text.length > BUDGET) text = text.slice(0, BUDGET) + '\n…[front-load truncated to budget]';
+
+  process.stdout.write(
+    `## CodeGraph structural context (auto-retrieved for this question)\n` +
+    `The code graph was queried for your question; the relevant symbols, source, and call flow are below. ` +
+    `Treat the quoted source as already read. If you need more, call codegraph_explore with specific symbol names rather than grepping or reading files.\n\n` +
+    text + '\n'
+  );
+  dbg(`INJECTED ${text.length} chars`);
+} catch (e) { dbg('ERROR: ' + (e?.stack || e?.message || e)); process.exit(0); } // degradable