@vizalice/codegraph 1.5.0

package/scripts/agent-eval/ab-new-vs-baseline.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# A/B a codegraph retrieval/steering change: the NEW build (current HEAD) vs a
+# BASELINE build (a git ref) — BOTH with codegraph attached — on the same
+# implementation task. ISOLATES the change (unlike run-all.sh's
+# with-vs-without). The agent works on a throwaway copy of the target, so your
+# repos are never touched.
+#
+# Each run reports the tool mix AND the three feedback metrics; compare-arms.mjs
+# then puts both arms side by side:
+#   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
+# This is the harness those metrics were built for: both arms are codegraph-on,
+# so every one of them is measuring the retrieval change rather than adoption.
+# docs/benchmarks/agent-eval-feedback-metrics.md is the entry point; the three
+# per-metric docs it links carry the caveats — in particular that allocation
+# efficiency is RELATIVE (attribution is by citation), which is exactly why
+# same-question new-vs-baseline is the comparison it is valid for.
+#
+# Both arms also run with the codegraph CLI blocked (no-cli-shim.sh). Here that
+# is not a with/without leak but an ATTRIBUTION one: an explore issued through
+# Bash is charged to Bash in the occupancy table and never reaches the
+# sufficiency or allocation parse at all, so a run that shells out silently
+# drops calls from all three metrics.
+#
+# Reliable attach (works even when this is itself run nested inside a Claude
+# session): each arm PRE-WARMS a persistent codegraph daemon for its target so
+# claude connects to an already-bound, index-loaded daemon instantly — before
+# the agent's first turn — and SKIPS codegraph's startup re-exec via
+# CODEGRAPH_WASM_RELAUNCHED=1. Without this, on a multi-step task the agent
+# dives into Read/grep before codegraph finishes its ~2-3s startup (worse under
+# the CPU contention of a nested run) and runs with NO codegraph.
+#
+# Gotcha: claude's `system/init` snapshot can read status:"pending" / 0 tools
+# even when the server then connects fine — judge by ACTUAL codegraph usage in
+# parse-run.mjs's "by type", not the init line.
+#
+# Usage: ab-new-vs-baseline.sh <indexed-repo> "<task>" [baseline-ref]
+#   <indexed-repo>  a repo with a .codegraph index (copied per arm)
+#   "<task>"        an implementation task, e.g. "Add X to Y and wire it through"
+#   [baseline-ref]  git ref for the BEFORE build (default: HEAD~1)
+# Env:
+#   AGENT_EVAL_OUT  output dir (default: /tmp/ab-new-vs-baseline)
+#   RUNS            runs per arm (default 1). Run-to-run variance is large —
+#                   use >=2 and report the range, never a single run. Both arms
+#                   build/index ONCE and then run RUNS times, so raising this is
+#                   far cheaper than re-invoking the script.
+#   MODEL / EFFORT  default sonnet / high. Never raise without a reason: sonnet
+#                   is the deliberate floor model (see CLAUDE.md).
+#
+# Both arms run with CODEGRAPH_NO_PROMPT_HOOK=1: the machine's ambient
+# UserPromptSubmit front-load hook resolves to whichever build is currently in
+# dist/, so leaving it on injects context through a second, uncontrolled channel
+# and confounds the tool-call counts this script exists to compare.
+set -uo pipefail
+
+TARGET="${1:?usage: ab-new-vs-baseline.sh <indexed-repo> \"<task>\" [baseline-ref]}"
+TASK="${2:?task required}"
+BASE_REF="${3:-HEAD~1}"
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+ENGINE="$(cd "$HARNESS/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-new-vs-baseline}"
+PARSE="$HARNESS/parse-run.mjs"
+
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$TARGET/.codegraph" ] || { echo "target not indexed: run 'codegraph init $TARGET' first"; exit 1; }
+if ! git -C "$ENGINE" diff --quiet || ! git -C "$ENGINE" diff --cached --quiet; then
+  echo "engine repo has uncommitted changes — commit or stash first (this script checks files out)"; exit 1
+fi
+CHANGED=$(git -C "$ENGINE" diff --name-only "$BASE_REF" HEAD -- src 2>/dev/null)
+[ -n "$CHANGED" ] || { echo "no src/ changes between $BASE_REF and HEAD — nothing to A/B"; exit 1; }
+
+# On exit: kill any eval daemons + restore the engine to HEAD.
+cleanup() {
+  pkill -9 -f "serve --mcp --path $OUT/" 2>/dev/null
+  git -C "$ENGINE" checkout HEAD -- $CHANGED 2>/dev/null
+  ( cd "$ENGINE" && npm run build >/dev/null 2>&1 )
+}
+# INT/TERM too: killing the script mid-baseline-arm otherwise leaves the engine
+# checked out at the baseline ref, which silently poisons every later build.
+trap cleanup EXIT INT TERM
+
+mkdir -p "$OUT"
+
+# Sanitized PATH + the absolute-path block, shared with run-all.sh. Sets
+# $ARM_PATH and $ARM_SETTINGS; aborts if either layer fails its own probe.
+. "$HARNESS/no-cli-shim.sh"
+cg_no_cli_setup "$OUT" || exit 1
+
+echo "###### engine=$ENGINE  baseline=$BASE_REF"
+echo "###### changed: $(echo "$CHANGED" | tr '\n' ' ')"
+echo "###### target=$TARGET"
+echo "###### task=$TASK"
+echo
+
+# Two pristine copies so each arm starts clean (the agent edits its own copy).
+rm -rf "$OUT/t-new" "$OUT/t-base"
+rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$TARGET/" "$OUT/t-new/"
+cp -R "$OUT/t-new" "$OUT/t-base"
+
+prewarm() { # target — spawn a persistent daemon (current $BIN) and wait for its socket
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null
+  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: $1" || echo "  WARN: daemon never bound for $1 (arm may run without codegraph)"
+}
+
+run_arm() { # label, target-copy — runs the task $RUNS times against one build
+  local label="$1" tgt="$2" c="$OUT/mcp-$1.json"
+  # Connect to the pre-warmed daemon; skip the startup re-exec for a fast attach.
+  # CODEGRAPH_EXPLORE_DEBUG points explore's per-file allocation diagnostic at a
+  # sidecar (no-op on builds predating it; never perturbs the response).
+  printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","CODEGRAPH_EXPLORE_DEBUG=%s","node","%s","serve","--mcp","--path","%s"]}}}' \
+    "$OUT/explore-$label.jsonl" "$BIN" "$tgt" > "$c"
+  rm -f "$OUT/explore-$label.jsonl"
+  echo "############## ARM [$label] ##############"
+  for i in $(seq 1 "${RUNS:-1}"); do
+    # Re-warm per run: the previous run's daemon is killed below, and a cold
+    # attach is exactly the failure this pre-warm exists to prevent.
+    prewarm "$tgt"
+    ( cd "$tgt" && PATH="$ARM_PATH" CODEGRAPH_NO_PROMPT_HOOK=1 claude -p "$TASK" \
+        --output-format stream-json --verbose --permission-mode bypassPermissions \
+        --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 --strict-mcp-config --mcp-config "$c" \
+        --settings "$ARM_SETTINGS" \
+        </dev/null > "$OUT/run-$label-$i.jsonl" 2>"$OUT/run-$label-$i.err" )
+    echo "-- run $i --"
+    # --brief: tool counts, result, and the three metric blocks, minus the
+    # numbered call transcript (RUNS>=2 is otherwise mostly call listings; the
+    # full sequence is one `parse-run.mjs $OUT/run-$label-$i.jsonl` away).
+    node "$PARSE" --brief "$OUT/run-$label-$i.jsonl" 2>&1 || echo "  (parse failed — see $OUT/run-$label-$i.jsonl)"
+    pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
+  done
+  echo
+}
+
+echo "== NEW build (HEAD) =="
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "  built"
+node "$BIN" init "$OUT/t-new" >/dev/null 2>&1 && echo "  indexed t-new"
+run_arm new "$OUT/t-new"
+
+echo "== BASELINE build ($BASE_REF) =="
+# Per-file: a file ADDED since baseline has no pathspec on the ref — and a
+# single multi-file checkout with one bad pathspec checks out NOTHING, which
+# silently ran the NEW build in the baseline arm. Absent-on-baseline → remove.
+for f in $CHANGED; do
+  git -C "$ENGINE" checkout "$BASE_REF" -- "$f" 2>/dev/null || rm -f "$ENGINE/$f"
+done
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "  built"
+node "$BIN" init "$OUT/t-base" >/dev/null 2>&1 && echo "  indexed t-base"
+run_arm baseline "$OUT/t-base"
+
+# Both arms, all three metrics, one table. The per-run blocks above say WHY a
+# number moved (which query fell short, which file nothing cited); this says
+# whether it moved at all, with the range across RUNS — never read the median
+# of one run.
+node "$HARNESS/compare-arms.mjs" "$OUT" new baseline 2>&1 || true
+
+echo "###### DONE. Read the ARM COMPARISON above first, then the per-run blocks"
+echo "###### for the queries and files behind any number that moved."
+echo "###### Full logs in: $OUT"

package/scripts/agent-eval/ab-sufficiency.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Sufficiency A/B: on a real understanding/flow question, WHEN the agent uses
+# codegraph (explore/node), does it still Read? Premise under test: explore/node
+# return source WITH line numbers, so a Read should not be needed.
+#
+# WITH codegraph (pre-warmed daemon, reliable nested attach) vs WITHOUT (empty
+# MCP, Read/Grep only), N runs each, on a throwaway copy of the repo. Reports
+# explore/node vs Read/Grep, and LISTS the files Read in the WITH arm so a true
+# sufficiency gap (an indexed source file) is distinguishable from out-of-scope
+# (configs, docs, a file codegraph didn't index).
+#
+# Usage: ab-sufficiency.sh <indexed-repo> "<question>" [runs-per-arm]
+# Env: AGENT_EVAL_OUT (default: /tmp/ab-sufficiency)
+set -uo pipefail
+REPO="${1:?usage: ab-sufficiency.sh <indexed-repo> \"<question>\" [runs]}"
+Q="${2:?question required}"
+RUNS="${3:-2}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-sufficiency}"
+TGT="$OUT/target"
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$REPO/.codegraph" ] || { echo "no .codegraph index at $REPO"; exit 1; }
+cleanup(){ pkill -9 -f "serve --mcp --path $TGT" 2>/dev/null; }
+trap cleanup EXIT
+mkdir -p "$OUT"
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built"
+
+# Throwaway copy + fresh index (the agent works here; a read-only question won't
+# edit, but isolate anyway). Excludes the source repo's index/build/vcs.
+rm -rf "$TGT"
+rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$REPO/" "$TGT/"
+node "$BIN" init "$TGT" >/dev/null 2>&1 && echo "indexed copy ($(node "$BIN" status --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).fileCount+" files")}catch{console.log("?")}})' 2>/dev/null || echo '?'))"
+
+echo "###### repo=$REPO  runs/arm=$RUNS"
+echo "###### Q=$Q"; echo
+echo '{"mcpServers":{}}' > "$OUT/mcp-empty.json"
+printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$TGT" > "$OUT/mcp-cg.json"
+
+prewarm(){
+  pkill -9 -f "serve --mcp --path $TGT" 2>/dev/null
+  CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$TGT" </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)' "$TGT" >/dev/null 2>&1
+}
+
+analyze(){
+  node -e '
+    const fs=require("fs");
+    const L=fs.readFileSync(process.argv[1],"utf8").split("\n").filter(Boolean);
+    let ex=0,nf=0,ns=0,oc=0,gr=0,exposed="?";const reads=[];
+    for(const l of L){try{const o=JSON.parse(l);
+      if(o.type==="system"&&o.subtype==="init")exposed=(o.tools||[]).filter(t=>/codegraph/.test(t)).length;
+      for(const b of (o.message?.content||[])){if(b.type!=="tool_use")continue;
+        if(b.name==="mcp__codegraph__codegraph_explore")ex++;
+        else if(b.name==="mcp__codegraph__codegraph_node"){if(b.input&&b.input.symbol)ns++;else nf++;}
+        else if(/mcp__codegraph__/.test(b.name))oc++;
+        else if(b.name==="Read")reads.push((b.input?.file_path||"").split("/").pop());
+        else if(b.name==="Grep")gr++;
+      }}catch{}}
+    console.log(`    explore=${ex} node[sym]=${ns} node[file]=${nf} other_cg=${oc} | Read=${reads.length}${reads.length?" ("+reads.join(", ")+")":""} Grep=${gr}  [cg exposed=${exposed}]`);
+  ' "$1"
+}
+
+run(){ # label, cfg, prewarm(0/1)
+  local label="$1" cfg="$2" pw="$3"
+  for i in $(seq 1 "$RUNS"); do
+    [ "$pw" = "1" ] && prewarm
+    ( cd "$TGT" && 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" </dev/null > "$OUT/$label-$i.jsonl" 2>"$OUT/$label-$i.err" )
+    echo "[$label] run $i:"; analyze "$OUT/$label-$i.jsonl"
+  done
+  echo
+}
+
+echo "== WITH codegraph (premise: explore/node used -> Read ~0) =="; run with "$OUT/mcp-cg.json" 1
+echo "== WITHOUT (Read/Grep only — the contrast) =="; run without "$OUT/mcp-empty.json" 0
+echo "###### DONE. In the WITH arm: are explore/node>0 and Read~0? Any Read of an INDEXED source file = sufficiency gap. Logs: $OUT"

package/scripts/agent-eval/allocation-fixtures.json

@@ -0,0 +1,344 @@
+{
+  "$comment": [
+    "Regression fixtures for GitHub issue #1500 / epic CG-1 — relevance-proportional",
+    "explore budget allocation. Run them with `node scripts/agent-eval/probe-allocation.mjs`",
+    "against a built dist/.",
+    "",
+    "STATUS: BOTH FIXTURES PASS again as of CG-31. self-query's delivered-share gates",
+    "failed on the CG-30-only build (`afterCG30`) and CG-31 restored them (`afterCG31`):",
+    "the incidental file was not over-RESERVED at all — it was over-SPENDING, drawing on",
+    "the reservations of files the render loop had not reached yet. Bounding that put the",
+    "response back inside the envelope, so nothing truncates and every admitted file",
+    "delivers. Read the two blocks together; the CG-30 verdict's diagnosis was wrong.",
+    "",
+    "CG-10 (relevance scoring) closed the RANKING half —",
+    "nothing incidental reaches the envelope any more — and CG-12 (score-proportional",
+    "allocation with a relative cliff) closed the BYTE SPLIT: each file's share is reserved",
+    "before anything renders, and a file under 15% of the top weight gets no source at all,",
+    "freeing both its bytes and its maxFiles slot. Each fixture records the pre-CG-10",
+    "`baseline`, the interim `afterCG10`, and the current `afterCG12`.",
+    "",
+    "`groups` partitions the files explore rendered into `answer` (what the query is",
+    "actually about) and `incidental` (what wins the envelope today on name collisions).",
+    "Assertions are on the DELIVERED envelope unless suffixed `Allocated`; delivered is",
+    "what the agent got, allocated is what the render loop chose before the hard ceiling.",
+    "Shares are fractions of the whole response, meta-text included, so they never sum to 1.",
+    "",
+    "CG-36 adds two more fixtures and a per-file `spendShareAtLeast` gate. The share gates",
+    "above ask which files WON the envelope; that one asks whether a file that won its share",
+    "then spent it. `starved-cluster` and `dense-header` are the two halves of the same",
+    "tradeoff and must be read together — one fails if a trivial cluster starves the",
+    "answer-bearing one, the other fails if the fix for that buries a query's own methods",
+    "under a dense declaration block."
+  ],
+  "fixtures": [
+    {
+      "id": "payroll-go",
+      "title": "#1500 — generated Go CRUD beside a hand-written payroll workflow",
+      "kind": "fixture",
+      "path": "__tests__/fixtures/payroll-go",
+      "query": "how does payroll cycle create and calculate payslips?",
+      "rationale": [
+        "The reporter's repo shape: a Go service whose generated FKIT CRUD layer sits",
+        "beside the hand-written use-case that does the real work. The query deliberately",
+        "does NOT name runPayrollCycleAll / BuildPayslip / Upsert — an architecture",
+        "question phrased the way a newcomer would phrase it. The generated layer",
+        "name-collides on every query term (CreatePayslip, PayrollCycleCreateRequest,",
+        "CalculatePayrollCycleTotals, a second BuildPayslip, a second Upsert), so a",
+        "scorer that rewards incidental name matches surfaces the CRUD path.",
+        "Half the generated files carry ORDINARY names and are only detectable by their",
+        "`// Code generated ... DO NOT EDIT.` header (CG-5), which is what makes this",
+        "the #1500 case rather than a .pb.go case."
+      ],
+      "groups": {
+        "answer": [
+          "internal/usecase/**",
+          "internal/store/**",
+          "internal/transport/**",
+          "internal/domain/**",
+          "cmd/**"
+        ],
+        "incidental": [
+          "internal/gen/**"
+        ]
+      },
+      "assert": {
+        "answerShareAtLeast": 0.55,
+        "incidentalShareAtMost": 0.25,
+        "topFileGroup": "answer",
+        "mustDeliverBytes": [
+          "internal/usecase/payroll/cycle.go",
+          "internal/usecase/payroll/payslip_builder.go"
+        ],
+        "$mustContainComment": "Needles are chosen to match the HAND-WRITTEN chain only — a bare `BuildPayslip`/`Upsert` also matches the generated collisions, which is the whole point of the fixture.",
+        "mustContain": [
+          "runPayrollCycleAll",
+          "func (s *Service) BuildPayslip",
+          "s.store.Upsert(ctx, slip)"
+        ]
+      },
+      "baseline": {
+        "measuredOn": "2026-08-03",
+        "note": "19 files → very-tiny tier (13,000 budget); 23,020 chars allocated against it, cut to 16,011 by the 19,500 hard ceiling.",
+        "delivered": {
+          "internal/gen/fkit/payroll/payslip.go": 0.307,
+          "internal/gen/fkit/payroll/payroll_cycle.go": 0.266,
+          "internal/domain/payroll/payslip.go": 0.256,
+          "internal/usecase/payroll/cycle.go": 0.0
+        },
+        "verdict": "The workflow file is allocated the single largest slice (30.6%) and delivers ZERO — the hard ceiling drops its whole section. Generated CRUD takes 57.4% of what the agent actually receives; runPayrollCycleAll, BuildPayslip and the real Upsert never reach the response."
+      },
+      "afterCG10": {
+        "measuredOn": "2026-08-04",
+        "delivered": {
+          "internal/usecase/payroll/cycle.go": 0.389,
+          "internal/gen/fkit/payroll/payroll_cycle.go": 0.235,
+          "internal/domain/payroll/payslip.go": 0.226,
+          "internal/gen/fkit/payroll/payslip.go": 0.0
+        },
+        "verdict": "PASSES answerShareAtLeast (61.5%), incidentalShareAtMost (23.5%), topFileGroup, and the cycle.go + runPayrollCycleAll + real-Upsert needles. The generated files now rank #3/#4 instead of #1/#2 — kind weighting plus a 0.3x generated penalty on BOTH the score and the graph mass, which is the key the comparator sorts on. STILL FAILING for CG-12: payslip_builder.go ranks #6 against the tier's maxFiles of 4, so `func (s *Service) BuildPayslip` never renders."
+      },
+      "afterCG12": {
+        "measuredOn": "2026-08-04",
+        "note": "19,337 delivered, nothing truncated. Both generated files cliffed to pointers (weight 3.9 and 3.5 against a cliff of 5.4), which frees the two maxFiles slots the hand-written store and builder then take.",
+        "delivered": {
+          "internal/usecase/payroll/cycle.go": 0.306,
+          "internal/domain/payroll/payslip.go": 0.212,
+          "internal/usecase/payroll/payslip_builder.go": 0.151,
+          "internal/store/payslipstore/store.go": 0.118,
+          "internal/gen/fkit/payroll/payroll_cycle.go": 0.0,
+          "internal/gen/fkit/payroll/payslip.go": 0.0
+        },
+        "verdict": "ALL GATES PASS. Answer group 78.7% (from 25.6% at baseline), generated layer 0.0% (from 57.4%). All four hand-written files deliver source, including payslip_builder.go — `func (s *Service) BuildPayslip`, the 'calculate' half of the question, finally reaches the agent. The generated files are still NAMED with their symbols and line numbers under 'Not shown above', so withholding their bytes costs ~100 chars each instead of ~4,500 and stays one follow-up explore away."
+      }
+    },
+    {
+      "id": "starved-cluster",
+      "title": "CG-36 — a trivial top-ranked cluster starving the answer-bearing one",
+      "kind": "fixture",
+      "path": "__tests__/fixtures/starved-cluster-ts",
+      "query": "how does a request travel from sendRequest to the socket",
+      "rationale": [
+        "django's `db/models/sql/query.py` and okhttp's `RealInterceptorChain.kt`, reduced",
+        "to a fixture. `chain.ts` holds a one-line `describeChain` helper at the top —",
+        "trivial, but a direct callee of the query's entry point, so its cluster carries",
+        "the file's highest per-symbol importance — and, past the cluster gap, the",
+        "`RequestChain` class that actually answers the question. The helper's cluster wins",
+        "the one guaranteed-and-shrinkable slot; the class then does not fit the remainder.",
+        "",
+        "Before CG-36 the class was dropped WHOLE and the file delivered 1,985 of a 6,904",
+        "reservation. That is not merely unspent budget: the slack carries forward to",
+        "lower-ranked files, so the response stays full and every envelope-share gate",
+        "passes while the answer is missing. Hence `spendShareAtLeast`."
+      ],
+      "groups": {
+        "answer": [
+          "src/pipeline/chain.ts",
+          "src/transport/**",
+          "src/app/client.ts"
+        ],
+        "incidental": [
+          "src/app/config.ts",
+          "src/pipeline/framing.ts"
+        ]
+      },
+      "assert": {
+        "topFileGroup": "answer",
+        "spendShareAtLeast": {
+          "src/pipeline/chain.ts": 0.6
+        },
+        "mustDeliverBytes": [
+          "src/pipeline/chain.ts"
+        ],
+        "$mustContainComment": "The two ends of the in-file flow: the chain hop and the transport hop it terminates in. Both live in the cluster that used to be dropped whole.",
+        "mustContain": [
+          "async proceed(request: PipelineRequest)",
+          "private async writeAndRead(request: PipelineRequest)"
+        ]
+      },
+      "baseline": {
+        "measuredOn": "2026-08-06",
+        "note": "The CG-24 epic tip (76ab1fe), before CG-36. 3,725 chars of source delivered in total.",
+        "delivered": {
+          "src/pipeline/chain.ts": 1985,
+          "src/app/client.ts": 997,
+          "src/pipeline/types.ts": 743
+        },
+        "verdict": "FAILS spendShareAtLeast and both needles. chain.ts spends 1,985 of its 6,904 reservation (28.8%) — it keeps the `describeChain` cluster and drops the `RequestChain` cluster whole, so neither `proceed` nor `writeAndRead` reaches the agent. Nothing else in the response is wrong: the file still ranks #1 by score and is still reserved the largest slice."
+      },
+      "afterCG36": {
+        "measuredOn": "2026-08-06",
+        "note": "10,802 chars of source delivered in total, nothing truncated.",
+        "delivered": {
+          "src/pipeline/chain.ts": 9062,
+          "src/app/client.ts": 997,
+          "src/pipeline/types.ts": 743
+        },
+        "verdict": "ALL GATES PASS. The `RequestChain` cluster is now SHRUNK into the remainder by the same whole-member rule the first cluster already used, instead of being dropped whole, so chain.ts delivers 9,062 chars including `proceed`, `advance` and `writeAndRead` — the whole in-file flow the question asks for."
+      }
+    },
+    {
+      "id": "dense-header",
+      "title": "CG-36 — the Session.swift shape density-first ranking exists for",
+      "kind": "fixture",
+      "path": "__tests__/fixtures/dense-header-ts",
+      "query": "how does perform create a URLRequest and start the task",
+      "rationale": [
+        "The counterweight to `starved-cluster`, and the reason CG-36 did NOT touch cluster",
+        "ranking. `session.ts` opens with a 60-line property list and a run of trivial",
+        "accessors — many adjacent, individually worthless declarations, i.e. the densest",
+        "block in the file — while `perform`, `didCreateURLRequest` and `task`, which the",
+        "query names, sit ~200 lines below it.",
+        "",
+        "Ranked on density alone the header block takes the file's whole budget and the",
+        "methods are buried; that is Alamofire's Session.swift, the case the",
+        "importance-then-density order was built for. Any future change to selection or",
+        "shrinking has to keep this passing as well as `starved-cluster` — they pull in",
+        "opposite directions, which is exactly why both are here."
+      ],
+      "groups": {
+        "answer": [
+          "src/net/**",
+          "src/core/request-builder.ts",
+          "src/core/task-factory.ts"
+        ],
+        "incidental": [
+          "src/core/queue.ts"
+        ]
+      },
+      "assert": {
+        "topFileGroup": "answer",
+        "answerShareOfSourceAtLeast": 0.8,
+        "spendShareAtLeast": {
+          "src/net/session.ts": 0.6
+        },
+        "$mustContainComment": "All three named symbols are deep in the file, past the dense header block. If density ever outranks importance again, these are the first thing to go.",
+        "mustContain": [
+          "async perform(url: string, method: string",
+          "didCreateURLRequest(request: URLRequest)",
+          "task(request: URLRequest, identifier: number)"
+        ]
+      },
+      "afterCG36": {
+        "measuredOn": "2026-08-06",
+        "note": "11,695 chars of source delivered, BYTE-IDENTICAL to the CG-24 epic tip (76ab1fe) — this fixture pins behaviour CG-36 deliberately left alone.",
+        "delivered": {
+          "src/net/session.ts": 9007,
+          "src/core/types.ts": 1957,
+          "src/core/task-factory.ts": 731
+        },
+        "verdict": "ALL GATES PASS, on the epic tip and on CG-36 alike. session.ts spends 9,007 of its 9,009 reservation and the response carries all three named methods from the bottom of the file. The dense header block is not what won the budget."
+      }
+    },
+    {
+      "id": "self-query",
+      "title": "This repo — incidental `explore`/`BUDGET` matches in the agent-eval scripts",
+      "kind": "self",
+      "path": ".",
+      "query": "how does explore allocate its output budget across files",
+      "rationale": [
+        "The same failure mode with no generated code in sight. `scripts/agent-eval/*.mjs`",
+        "mention `explore` and `BUDGET` incidentally — they are eval harnesses, not the",
+        "allocator — and they are small enough to ship WHOLE, while src/mcp/tools.ts (which",
+        "carries getExploreOutputBudget and the render loop, and scores 4x higher on every",
+        "signal) is large enough to be clipped at maxCharsPerFile. Allocation follows file",
+        "size, not relevance.",
+        "",
+        "Unlike payroll-go this fixture reads THIS repo's live index, so its exact numbers",
+        "move as the repo changes (indexed file count crossing 500 flips the budget tier).",
+        "The assertions are therefore relative — answer-vs-incidental, not fixed percentages."
+      ],
+      "groups": {
+        "answer": [
+          "src/mcp/**"
+        ],
+        "incidental": [
+          "scripts/**"
+        ]
+      },
+      "assert": {
+        "$answerShareComment": [
+          "Denominated in DELIVERED SOURCE, not in the whole envelope (CG-26). The",
+          "envelope-denominated form of this gate moved for reasons that have nothing",
+          "to do with allocation: it fell when the epilogue stopped being discarded,",
+          "and it fell again when a fifth ADMITTED file finally got paid its",
+          "reservation instead of being dropped by the ceiling. Both are the",
+          "improvements this epic exists to make, and a gate that reads them as",
+          "regressions is measuring the denominator. The fixture's own rationale",
+          "already says the assertions are relative, answer-vs-incidental, not fixed",
+          "percentages. 0.5 is unchanged; only what it is a share OF."
+        ],
+        "answerShareOfSourceAtLeast": 0.5,
+        "incidentalShareAtMost": 0.25,
+        "topFileGroup": "answer",
+        "mustDeliverBytes": [
+          "src/mcp/tools.ts"
+        ]
+      },
+      "baseline": {
+        "measuredOn": "2026-08-03",
+        "note": "493 files → small tier (18,000 budget); 27,518 chars allocated against it, cut to 19,749 by the 25,000 hard ceiling.",
+        "delivered": {
+          "scripts/agent-eval/offload-eval-hook.mjs": 0.25,
+          "scripts/agent-eval/offload-eval-metrics.mjs": 0.236,
+          "scripts/agent-eval/parse-session.mjs": 0.232,
+          "src/mcp/tools.ts": 0.185,
+          "scripts/agent-eval/offload-eval-cost.mjs": 0.0
+        },
+        "verdict": "The script corpus takes 71.8% of the delivered envelope (79.4% of what was allocated) against tools.ts's 18.5%, despite tools.ts scoring 46 vs 10, carrying 2.3x the graph mass and 3x the distinct term hits."
+      },
+      "afterCG10": {
+        "measuredOn": "2026-08-04",
+        "delivered": {
+          "src/resolution/memory-budget.ts": 0.512,
+          "src/mcp/tools.ts": 0.329
+        },
+        "verdict": "PASSES incidentalShareAtMost: every scripts/agent-eval/*.mjs file is gone (0.0%), which is CG-10's acceptance bar — their sole match was an unused file-scope `explore`/`BUDGET` constant, worth 0.08x weight, and the relative floor (8.2) then cut them. tools.ts ranks #1. STILL FAILING for CG-12: memory-budget.ts scores 18 to tools.ts's 41 yet takes 51.2% of the envelope to tools.ts's 32.9%, purely because it is small enough to ship whole while tools.ts is clipped at maxCharsPerFile. Allocation still follows file size, not relevance."
+      },
+      "afterCG12": {
+        "measuredOn": "2026-08-04",
+        "note": "18,134 delivered, nothing truncated. tools.ts scores 58 here (it grew by the allocator this task added), memory-budget.ts 18.",
+        "delivered": {
+          "src/mcp/tools.ts": 0.606,
+          "src/resolution/memory-budget.ts": 0.172,
+          "src/resolution/lru-cache.ts": 0.111
+        },
+        "verdict": "ALL GATES PASS. tools.ts takes 60.6% of the envelope, up from 18.5% at baseline and 32.9% after CG-10 — past the epic's >50% acceptance bar. The reversal is the whole point: memory-budget.ts no longer wins by being small enough to ship whole (it now clusters within its 3.1K reservation), and tools.ts is no longer clipped at maxCharsPerFile (11K reservation, ~3x the old flat cap). Exception to 'no previously-unclipped file becomes clipped': memory-budget.ts was unclipped-whole at 5,672 and is now clipped to its proportional share. That is the epic's own diagnosis of the bug, not a regression — it scored 18 against tools.ts's 58 and was taking the larger slice."
+      },
+      "afterCG30": {
+        "measuredOn": "2026-08-06",
+        "note": "23,688 delivered of 26,430 allocated, truncated at the 25,000 ceiling. Baseline (main) on the SAME index: 14,851 delivered of 25,221 allocated. tools.ts delivers 8,282 chars in BOTH arms — identical bytes; only the denominator moved.",
+        "delivered": {
+          "scripts/agent-eval/parse-run.mjs": 0.361,
+          "src/mcp/tools.ts": 0.35,
+          "src/mcp/explore-session-state.ts": 0.147,
+          "src/resolution/memory-budget.ts": 0.0
+        },
+        "verdict": "THREE GATES FAIL — and the cause is not the CG-30 bound. Allocation is unchanged between arms (parse-run.mjs 32.3% here vs 33.9% on main); what changed is that it now DELIVERS. On main its whole 8,548-char section was cut by the hard-ceiling truncation, so the incidental group scored 0.0% by luck, not by design, and the fixture passed on that. Bounding the oversize-member overshoot freed enough headroom that the response no longer truncates the same section away. Every file obeys the new bound on this repo (max ratio 1.40x of spendable, against the 1.5x ceiling). What the failure exposes is real and pre-existing: parse-run.mjs scores 18 against tools.ts's 58 yet is reserved a comparable slice — a low-scoring file taking a top-file share, which is epic CG-24's subject. Fix it there; do not tune the CG-30 bound to restore a pass that depended on truncation. SUPERSEDED by afterCG31 — the diagnosis above is wrong on one load-bearing point, see there."
+      },
+      "afterCG31": {
+        "measuredOn": "2026-08-06",
+        "note": "23,083 delivered of 23,080 allocated — inside the envelope, nothing truncated. Both arms measured on the SAME clean FULL REBUILD of this repo's index (CG-33: an incrementally-synced index diverges and shifts ranking). CG-30-only arm on that index: 23,692 delivered of 26,410 allocated, TRUNCATED.",
+        "delivered": {
+          "src/mcp/tools.ts": 0.359,
+          "scripts/agent-eval/parse-run.mjs": 0.187,
+          "src/mcp/explore-session-state.ts": 0.151,
+          "src/resolution/lru-cache.ts": 0.087
+        },
+        "verdict": "ALL FOUR GATES PASS. The afterCG30 verdict called parse-run.mjs over-RESERVED; it was not — its reservation is 4,314 in both arms. It was over-SPENDING: 8,548 chars, drawing on reservations belonging to files the render loop had not reached yet, which is the CG-31 defect. With the displacement guard it renders 4,314, tools.ts's identical 8,282 chars go from 35.0% to 35.9% of a response that no longer overruns, and lru-cache.ts (dropped as memory-budget.ts was on the CG-30 arm) delivers. Note what did NOT change: allocation. This fixture moved because the render loop stopped spending other files' bytes, not because anything was re-ranked."
+      },
+      "afterCG26": {
+        "measuredOn": "2026-08-06",
+        "note": "24,952 delivered of 24,949 allocated, nothing truncated — against the CG-31 tip's 23,083 on the SAME clean full rebuild of this repo's index. tools.ts delivers 8,282 chars in BOTH arms: identical bytes, unchanged reservation, unchanged rank. Total delivered SOURCE 21,228 against 18,105.",
+        "delivered": {
+          "src/mcp/tools.ts": 0.334,
+          "scripts/agent-eval/parse-run.mjs": 0.174,
+          "src/mcp/explore-session-state.ts": 0.141,
+          "src/resolution/memory-budget.ts": 0.126,
+          "src/resolution/lru-cache.ts": 0.081
+        },
+        "verdict": "ALL GATES PASS. The one that changed shape is answerShareAtLeast → answerShareOfSourceAtLeast: on the envelope denominator the answer group reads 47.5% here against 51.0% at the CG-31 tip, and neither number is about allocation. tools.ts's bytes are byte-identical between the arms; what moved is that the response now delivers a FIFTH admitted file (memory-budget.ts, rank 4, paid its full 3,123-char reservation — the CG-31 tip rendered it and then let the hard ceiling drop the whole section) and keeps epilogue prose it used to discard. Answer/incidental separation is unchanged and strong: tools.ts 33.4% against parse-run.mjs's 17.4%, incidental 17.4% (down from 18.7%), top delivered file still tools.ts. Measured in delivered source the answer group is 55.5%."
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Arm F (body-inlining trace + trace-first steering) across the same 6 repos as
+# arms-matrix.sh, so F vs B isolates the trace-enrichment effect (same surface,
+# old thin trace in B vs body-inlining trace here).
+set -uo pipefail
+H="$(cd "$(dirname "$0")" && pwd)"; RUNS="${RUNS:-2}"; C="${CORPUS:-/tmp/codegraph-corpus}"
+ROWS=(
+"$C/flutter-samples/add_to_app/books/flutter_module_books|How does the books UI build and what child widgets does it show?"
+"$C/aspnet-realworld|How is creating an article handled? Trace the controller to the service."
+"$C/spring-mall|How is a product-list request handled? Trace the controller to the service."
+"$C/vapor-spi|How is a package-show request handled? Name the route and controller."
+"$C/excalidraw|How does updating an element re-render the canvas on screen? Trace the flow."
+"$C/spring-halo|How is publishing a post handled? Trace the controller to the service."
+)
+ARM="${ARM:-F}"
+echo "### ARM $ARM START $(date) RUNS=$RUNS"
+for row in "${ROWS[@]}"; do
+  repo="${row%%|*}"; q="${row#*|}"
+  for r in $(seq 1 "$RUNS"); do bash "$H/run-arms.sh" "$repo" "$q" "$ARM" "$r"; done
+done
+echo "### ARM $ARM COMPLETE $(date)"

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

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Drive the tool-surface ablation across the chosen repos × arms (A–E).
+# Arms A–D ask the canonical FLOW question; arm E asks a NON-flow survey
+# question (the control probe — should degrade without explore+context).
+# Output: /tmp/arms/<repo>/<arm>-r<n>.jsonl  (parse with parse-arms.mjs).
+set -uo pipefail
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+RUNS="${RUNS:-2}"
+C="${CORPUS:-/tmp/codegraph-corpus}"
+NFQ='What are the main modules/components of this codebase and what does each one do? Give an overview of how it is organized.'
+
+# repo-path|flow-question  (2 small, 2 medium, 2 large — spans the size range)
+ROWS=(
+"$C/flutter-samples/add_to_app/books/flutter_module_books|How does the books UI build and what child widgets does it show?"
+"$C/aspnet-realworld|How is creating an article handled? Trace the controller to the service."
+"$C/spring-mall|How is a product-list request handled? Trace the controller to the service."
+"$C/vapor-spi|How is a package-show request handled? Name the route and controller."
+"$C/excalidraw|How does updating an element re-render the canvas on screen? Trace the flow."
+"$C/spring-halo|How is publishing a post handled? Trace the controller to the service."
+)
+
+echo "### ARMS MATRIX START $(date) RUNS=$RUNS"
+for row in "${ROWS[@]}"; do
+  repo="${row%%|*}"; q="${row#*|}"
+  for arm in A B C D; do
+    for r in $(seq 1 "$RUNS"); do
+      bash "$HARNESS/run-arms.sh" "$repo" "$q" "$arm" "$r"
+    done
+  done
+done
+# E: non-flow control probe on two repos (must degrade without explore+context)
+for repo in "$C/excalidraw" "$C/spring-mall"; do
+  for r in $(seq 1 "$RUNS"); do
+    bash "$HARNESS/run-arms.sh" "$repo" "$NFQ" E "$r"
+  done
+done
+echo "### ARMS MATRIX COMPLETE $(date)"