homegraph 1.5.0 → 1.5.1

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

@@ -1,102 +1,102 @@
-#!/usr/bin/env bash
-# A/B a homegraph retrieval/steering change: the NEW build (current HEAD) vs a
-# BASELINE build (a git ref) — BOTH with homegraph attached — on the same
-# implementation task, measuring how many Read vs homegraph calls the agent
-# makes. 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.
-#
-# Reliable attach (works even when this is itself run nested inside a Claude
-# session): each arm PRE-WARMS a persistent homegraph daemon for its target so
-# claude connects to an already-bound, index-loaded daemon instantly — before
-# the agent's first turn — and SKIPS homegraph's startup re-exec via
-# HOMEGRAPH_WASM_RELAUNCHED=1. Without this, on a multi-step task the agent
-# dives into Read/grep before homegraph finishes its ~2-3s startup (worse under
-# the CPU contention of a nested run) and runs with NO homegraph.
-#
-# Gotcha: claude's `system/init` snapshot can read status:"pending" / 0 tools
-# even when the server then connects fine — judge by ACTUAL homegraph 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 .homegraph 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 (default: /tmp/ab-new-vs-baseline)
-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}"
-ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
-BIN="$ENGINE/dist/bin/homegraph.js"
-OUT="${AGENT_EVAL_OUT:-/tmp/ab-new-vs-baseline}"
-PARSE="$ENGINE/scripts/agent-eval/parse-run.mjs"
-
-command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
-[ -d "$TARGET/.homegraph" ] || { echo "target not indexed: run 'homegraph 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 )
-}
-trap cleanup EXIT
-
-mkdir -p "$OUT"
-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 .homegraph "$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
-  HOMEGRAPH_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]+"/.homegraph/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 homegraph)"
-}
-
-run_arm() { # label, target-copy
-  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.
-  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$tgt" > "$c"
-  prewarm "$tgt"
-  echo "############## ARM [$label] ##############"
-  ( cd "$tgt" && 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" \
-      </dev/null > "$OUT/run-$label.jsonl" 2>"$OUT/run-$label.err" )
-  node "$PARSE" "$OUT/run-$label.jsonl" 2>&1 | grep -E "by type|Result" || echo "  (parse failed — see $OUT/run-$label.jsonl)"
-  pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
-  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"
-
-echo "###### DONE. Compare the [new] vs [baseline] 'by type' counts above"
-echo "###### (especially Read vs mcp__homegraph__*). Full logs in: $OUT"
+#!/usr/bin/env bash
+# A/B a homegraph retrieval/steering change: the NEW build (current HEAD) vs a
+# BASELINE build (a git ref) — BOTH with homegraph attached — on the same
+# implementation task, measuring how many Read vs homegraph calls the agent
+# makes. 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.
+#
+# Reliable attach (works even when this is itself run nested inside a Claude
+# session): each arm PRE-WARMS a persistent homegraph daemon for its target so
+# claude connects to an already-bound, index-loaded daemon instantly — before
+# the agent's first turn — and SKIPS homegraph's startup re-exec via
+# HOMEGRAPH_WASM_RELAUNCHED=1. Without this, on a multi-step task the agent
+# dives into Read/grep before homegraph finishes its ~2-3s startup (worse under
+# the CPU contention of a nested run) and runs with NO homegraph.
+#
+# Gotcha: claude's `system/init` snapshot can read status:"pending" / 0 tools
+# even when the server then connects fine — judge by ACTUAL homegraph 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 .homegraph 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 (default: /tmp/ab-new-vs-baseline)
+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}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/homegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-new-vs-baseline}"
+PARSE="$ENGINE/scripts/agent-eval/parse-run.mjs"
+
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$TARGET/.homegraph" ] || { echo "target not indexed: run 'homegraph 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 )
+}
+trap cleanup EXIT
+
+mkdir -p "$OUT"
+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 .homegraph "$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
+  HOMEGRAPH_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]+"/.homegraph/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 homegraph)"
+}
+
+run_arm() { # label, target-copy
+  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.
+  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$tgt" > "$c"
+  prewarm "$tgt"
+  echo "############## ARM [$label] ##############"
+  ( cd "$tgt" && 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" \
+      </dev/null > "$OUT/run-$label.jsonl" 2>"$OUT/run-$label.err" )
+  node "$PARSE" "$OUT/run-$label.jsonl" 2>&1 | grep -E "by type|Result" || echo "  (parse failed — see $OUT/run-$label.jsonl)"
+  pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
+  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"
+
+echo "###### DONE. Compare the [new] vs [baseline] 'by type' counts above"
+echo "###### (especially Read vs mcp__homegraph__*). Full logs in: $OUT"

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

@@ -1,78 +1,78 @@
-#!/usr/bin/env bash
-# Sufficiency A/B: on a real understanding/flow question, WHEN the agent uses
-# homegraph (explore/node), does it still Read? Premise under test: explore/node
-# return source WITH line numbers, so a Read should not be needed.
-#
-# WITH homegraph (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 homegraph 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/homegraph.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/.homegraph" ] || { echo "no .homegraph 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 .homegraph "$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":{"homegraph":{"command":"env","args":["HOMEGRAPH_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
-  HOMEGRAPH_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]+"/.homegraph/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=>/homegraph/.test(t)).length;
-      for(const b of (o.message?.content||[])){if(b.type!=="tool_use")continue;
-        if(b.name==="mcp__homegraph__homegraph_explore")ex++;
-        else if(b.name==="mcp__homegraph__homegraph_node"){if(b.input&&b.input.symbol)ns++;else nf++;}
-        else if(/mcp__homegraph__/.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 homegraph (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"
+#!/usr/bin/env bash
+# Sufficiency A/B: on a real understanding/flow question, WHEN the agent uses
+# homegraph (explore/node), does it still Read? Premise under test: explore/node
+# return source WITH line numbers, so a Read should not be needed.
+#
+# WITH homegraph (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 homegraph 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/homegraph.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/.homegraph" ] || { echo "no .homegraph 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 .homegraph "$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":{"homegraph":{"command":"env","args":["HOMEGRAPH_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
+  HOMEGRAPH_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]+"/.homegraph/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=>/homegraph/.test(t)).length;
+      for(const b of (o.message?.content||[])){if(b.type!=="tool_use")continue;
+        if(b.name==="mcp__homegraph__homegraph_explore")ex++;
+        else if(b.name==="mcp__homegraph__homegraph_node"){if(b.input&&b.input.symbol)ns++;else nf++;}
+        else if(/mcp__homegraph__/.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 homegraph (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/arms-F.sh

@@ -1,21 +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/homegraph-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)"
+#!/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/homegraph-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

@@ -1,37 +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/homegraph-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)"
+#!/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/homegraph-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)"

package/scripts/agent-eval/audit.sh

@@ -1,68 +1,68 @@
-#!/usr/bin/env bash
-# One-shot HomeGraph quality audit:
-#   set version -> ensure corpus repo -> wipe+reindex with that version ->
-#   run with/without A/B -> restore the local dev link.
-#
-# Usage: audit.sh <version> <repo-name> <repo-url> "<question>" [headless|all]
-#   <version>    "local" (build + npm link this repo) | "latest" | a version (e.g. 0.7.10)
-#   <repo-name>  dir name under the corpus dir
-#   <repo-url>   git URL (cloned --depth 1 when the repo dir is missing)
-#   [mode]       headless (default) | all (also the interactive tmux arms)
-# Env: CORPUS  corpus dir (default: /tmp/homegraph-corpus)
-set -uo pipefail
-
-VERSION="${1:?usage: audit.sh <version> <repo-name> <repo-url> \"<question>\" [mode]}"
-NAME="${2:?repo-name required}"
-URL="${3:?repo-url required}"
-Q="${4:?question required}"
-MODE="${5:-headless}"
-
-HARNESS="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$HARNESS/../.." && pwd)"     # homegraph repo root
-CORPUS="${CORPUS:-/tmp/homegraph-corpus}"
-REPO="$CORPUS/$NAME"
-PKG="homegraph"
-
-echo "==================== HomeGraph audit ===================="
-echo "version=$VERSION  repo=$NAME  mode=$MODE  corpus=$CORPUS"
-echo
-
-# 1. Set the homegraph version under test (mutates the global install).
-if [ "$VERSION" = local ]; then
-  echo "→ [1/4] building + linking local dev build (local-install.sh)"
-  ( cd "$REPO_ROOT" && ./scripts/local-install.sh ) || { echo "local-install.sh failed"; exit 1; }
-else
-  echo "→ [1/4] installing $PKG@$VERSION globally"
-  npm install -g "$PKG@$VERSION" || { echo "npm install -g $PKG@$VERSION failed"; exit 1; }
-fi
-ACTUAL="$(homegraph --version 2>/dev/null || echo '?')"
-echo "  homegraph on PATH: $(command -v homegraph) -> $ACTUAL"
-
-# 2. Ensure the corpus repo exists (clone shallow if missing, reuse if present).
-mkdir -p "$CORPUS"
-if [ -d "$REPO/.git" ]; then
-  echo "→ [2/4] reusing existing checkout: $REPO"
-else
-  echo "→ [2/4] cloning $URL"
-  git clone --depth 1 "$URL" "$REPO" || { echo "git clone failed"; exit 1; }
-fi
-
-# 3. Wipe + re-index with THIS version (the index must be built by the same
-#    binary that serves it — different versions extract differently).
-echo "→ [3/4] wiping .homegraph and re-indexing with $ACTUAL"
-rm -rf "$REPO/.homegraph"
-( cd "$REPO" && homegraph init -i ) || { echo "indexing failed"; exit 1; }
-
-# 4. Run the with/without A/B.
-echo "→ [4/4] running A/B harness (mode=$MODE)"
-bash "$HARNESS/run-all.sh" "$REPO" "$Q" "$MODE"
-
-# Restore the dev link (the normal working state in this repo).
-echo
-echo "→ restoring local dev link (local-install.sh)"
-if ( cd "$REPO_ROOT" && ./scripts/local-install.sh >/dev/null 2>&1 ); then
-  echo "  global homegraph restored to dev build"
-else
-  echo "  WARN: restore failed — run ./scripts/local-install.sh manually"
-fi
-echo "==================== audit complete ===================="
+#!/usr/bin/env bash
+# One-shot HomeGraph quality audit:
+#   set version -> ensure corpus repo -> wipe+reindex with that version ->
+#   run with/without A/B -> restore the local dev link.
+#
+# Usage: audit.sh <version> <repo-name> <repo-url> "<question>" [headless|all]
+#   <version>    "local" (build + npm link this repo) | "latest" | a version (e.g. 0.7.10)
+#   <repo-name>  dir name under the corpus dir
+#   <repo-url>   git URL (cloned --depth 1 when the repo dir is missing)
+#   [mode]       headless (default) | all (also the interactive tmux arms)
+# Env: CORPUS  corpus dir (default: /tmp/homegraph-corpus)
+set -uo pipefail
+
+VERSION="${1:?usage: audit.sh <version> <repo-name> <repo-url> \"<question>\" [mode]}"
+NAME="${2:?repo-name required}"
+URL="${3:?repo-url required}"
+Q="${4:?question required}"
+MODE="${5:-headless}"
+
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HARNESS/../.." && pwd)"     # homegraph repo root
+CORPUS="${CORPUS:-/tmp/homegraph-corpus}"
+REPO="$CORPUS/$NAME"
+PKG="homegraph"
+
+echo "==================== HomeGraph audit ===================="
+echo "version=$VERSION  repo=$NAME  mode=$MODE  corpus=$CORPUS"
+echo
+
+# 1. Set the homegraph version under test (mutates the global install).
+if [ "$VERSION" = local ]; then
+  echo "→ [1/4] building + linking local dev build (local-install.sh)"
+  ( cd "$REPO_ROOT" && ./scripts/local-install.sh ) || { echo "local-install.sh failed"; exit 1; }
+else
+  echo "→ [1/4] installing $PKG@$VERSION globally"
+  npm install -g "$PKG@$VERSION" || { echo "npm install -g $PKG@$VERSION failed"; exit 1; }
+fi
+ACTUAL="$(homegraph --version 2>/dev/null || echo '?')"
+echo "  homegraph on PATH: $(command -v homegraph) -> $ACTUAL"
+
+# 2. Ensure the corpus repo exists (clone shallow if missing, reuse if present).
+mkdir -p "$CORPUS"
+if [ -d "$REPO/.git" ]; then
+  echo "→ [2/4] reusing existing checkout: $REPO"
+else
+  echo "→ [2/4] cloning $URL"
+  git clone --depth 1 "$URL" "$REPO" || { echo "git clone failed"; exit 1; }
+fi
+
+# 3. Wipe + re-index with THIS version (the index must be built by the same
+#    binary that serves it — different versions extract differently).
+echo "→ [3/4] wiping .homegraph and re-indexing with $ACTUAL"
+rm -rf "$REPO/.homegraph"
+( cd "$REPO" && homegraph init -i ) || { echo "indexing failed"; exit 1; }
+
+# 4. Run the with/without A/B.
+echo "→ [4/4] running A/B harness (mode=$MODE)"
+bash "$HARNESS/run-all.sh" "$REPO" "$Q" "$MODE"
+
+# Restore the dev link (the normal working state in this repo).
+echo
+echo "→ restoring local dev link (local-install.sh)"
+if ( cd "$REPO_ROOT" && ./scripts/local-install.sh >/dev/null 2>&1 ); then
+  echo "  global homegraph restored to dev build"
+else
+  echo "  WARN: restore failed — run ./scripts/local-install.sh manually"
+fi
+echo "==================== audit complete ===================="