homegraph 1.1.2 → 1.1.3

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

@@ -1,50 +1,50 @@
-#!/usr/bin/env bash
-# ONE offload run on ONE indexed repo at a given offload STYLE (plain|refs), so we can
-# watch a single agent transcript at a time (the user's one-run-at-a-time methodology).
-# The OFFLOAD reasoning runs in the prewarmed DAEMON process, so the style env must be
-# set on BOTH the daemon and the client MCP config. Writes one metrics line to RESULTS
-# and leaves the raw stream-json at $RUNS/<repo>-<style>-<n>.jsonl for inspection.
-#
-# Usage: offload-eval-refs1.sh <indexed-repo> <style> <n> "<question>"
-set -uo pipefail
-HERE="$(cd "$(dirname "$0")" && pwd)"; ENGINE="$(cd "$HERE/../.." && pwd)"; BIN="$ENGINE/dist/bin/homegraph.js"
-OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"; RUNS="$OUT/runs"; EXTRACT="$HERE/offload-eval-metrics.mjs"
-TARGET="${1:?repo}"; STYLE="${2:?style}"; N="${3:?run-tag}"; Q="${4:?question}"
-RESULTS="${RESULTS:-$OUT/results-refs.jsonl}"; REPO=$(basename "$TARGET"); TARGET=$(cd "$TARGET" && pwd -P)
-mkdir -p "$RUNS"; command -v claude >/dev/null || { echo "no claude"; exit 1; }
-USAGE="$RUNS/$REPO-$STYLE-usage.jsonl"; : > "$USAGE"
-CFG="$RUNS/mcp-$REPO-$STYLE.json"
-# `raw` is a pseudo-style: homegraph attached but the offload DISABLED (the ceiling —
-# verbatim source, no reasoning model). Any other value is an offload style (plain|refs).
-if [ "$STYLE" = "raw" ]; then
-  DAEMON_ENV="HOMEGRAPH_OFFLOAD_DISABLE=1"
-  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1","HOMEGRAPH_OFFLOAD_DISABLE=1","node","%s","serve","--mcp","--path","%s"]}}}' \
-    "$BIN" "$TARGET" > "$CFG"
-  USAGE="-"
-else
-  DAEMON_ENV="HOMEGRAPH_OFFLOAD_STYLE=$STYLE HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE"
-  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1","HOMEGRAPH_OFFLOAD_STYLE=%s","HOMEGRAPH_OFFLOAD_USAGE_LOG=%s","node","%s","serve","--mcp","--path","%s"]}}}' \
-    "$STYLE" "$USAGE" "$BIN" "$TARGET" > "$CFG"
-fi
-
-# Prewarm a persistent daemon carrying the SAME offload config (it does the reasoning).
-pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.homegraph/daemon.sock" 2>/dev/null; sleep 0.6
-env $DAEMON_ENV HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 \
-  node "$BIN" serve --mcp --path "$TARGET" </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)' "$TARGET" \
-  && echo "daemon warm ($STYLE)" || echo "WARN daemon never bound"
-
-tag="$REPO-$STYLE-$N"
-echo "== run $tag =="
-# DISALLOW (optional): block tools that confound the offload-sufficiency signal —
-# chiefly "Agent" (sub-agent delegation: the spawned Explore subagent has low MCP
-# salience, ignores homegraph, and thrashes via Bash+Read, making the A/B noise).
-( 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 "offload-$STYLE" --rep "$N" \
-    --repo "$REPO" --tier "complex" --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"
-pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.homegraph/daemon.sock" 2>/dev/null
-echo "raw transcript: $RUNS/$tag.jsonl"
+#!/usr/bin/env bash
+# ONE offload run on ONE indexed repo at a given offload STYLE (plain|refs), so we can
+# watch a single agent transcript at a time (the user's one-run-at-a-time methodology).
+# The OFFLOAD reasoning runs in the prewarmed DAEMON process, so the style env must be
+# set on BOTH the daemon and the client MCP config. Writes one metrics line to RESULTS
+# and leaves the raw stream-json at $RUNS/<repo>-<style>-<n>.jsonl for inspection.
+#
+# Usage: offload-eval-refs1.sh <indexed-repo> <style> <n> "<question>"
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"; ENGINE="$(cd "$HERE/../.." && pwd)"; BIN="$ENGINE/dist/bin/homegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"; RUNS="$OUT/runs"; EXTRACT="$HERE/offload-eval-metrics.mjs"
+TARGET="${1:?repo}"; STYLE="${2:?style}"; N="${3:?run-tag}"; Q="${4:?question}"
+RESULTS="${RESULTS:-$OUT/results-refs.jsonl}"; REPO=$(basename "$TARGET"); TARGET=$(cd "$TARGET" && pwd -P)
+mkdir -p "$RUNS"; command -v claude >/dev/null || { echo "no claude"; exit 1; }
+USAGE="$RUNS/$REPO-$STYLE-usage.jsonl"; : > "$USAGE"
+CFG="$RUNS/mcp-$REPO-$STYLE.json"
+# `raw` is a pseudo-style: homegraph attached but the offload DISABLED (the ceiling —
+# verbatim source, no reasoning model). Any other value is an offload style (plain|refs).
+if [ "$STYLE" = "raw" ]; then
+  DAEMON_ENV="HOMEGRAPH_OFFLOAD_DISABLE=1"
+  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1","HOMEGRAPH_OFFLOAD_DISABLE=1","node","%s","serve","--mcp","--path","%s"]}}}' \
+    "$BIN" "$TARGET" > "$CFG"
+  USAGE="-"
+else
+  DAEMON_ENV="HOMEGRAPH_OFFLOAD_STYLE=$STYLE HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE"
+  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1","HOMEGRAPH_OFFLOAD_STYLE=%s","HOMEGRAPH_OFFLOAD_USAGE_LOG=%s","node","%s","serve","--mcp","--path","%s"]}}}' \
+    "$STYLE" "$USAGE" "$BIN" "$TARGET" > "$CFG"
+fi
+
+# Prewarm a persistent daemon carrying the SAME offload config (it does the reasoning).
+pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.homegraph/daemon.sock" 2>/dev/null; sleep 0.6
+env $DAEMON_ENV HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 \
+  node "$BIN" serve --mcp --path "$TARGET" </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)' "$TARGET" \
+  && echo "daemon warm ($STYLE)" || echo "WARN daemon never bound"
+
+tag="$REPO-$STYLE-$N"
+echo "== run $tag =="
+# DISALLOW (optional): block tools that confound the offload-sufficiency signal —
+# chiefly "Agent" (sub-agent delegation: the spawned Explore subagent has low MCP
+# salience, ignores homegraph, and thrashes via Bash+Read, making the A/B noise).
+( 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 "offload-$STYLE" --rep "$N" \
+    --repo "$REPO" --tier "complex" --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"
+pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.homegraph/daemon.sock" 2>/dev/null
+echo "raw transcript: $RUNS/$tag.jsonl"

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

@@ -1,24 +1,24 @@
-#!/usr/bin/env bash
-# Clone + index the 4 "not-trained-on" eval repos into $AGENT_EVAL_OUT/repos. These were
-# selected via a no-tools memory-probe gate (Sonnet cannot answer their flow questions from
-# memory — so the no-homegraph baseline is honest). Env: AGENT_EVAL_OUT=<scratch dir>
-set -uo pipefail
-HERE="$(cd "$(dirname "$0")" && pwd)"
-ENGINE="$(cd "$HERE/../.." && pwd)"
-BIN="$ENGINE/dist/bin/homegraph.js"
-OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"
-ROOT="$OUT/repos"; mkdir -p "$ROOT"
-export HOMEGRAPH_TELEMETRY=0 DO_NOT_TRACK=1
-[ -f "$BIN" ] || { echo "engine not built: run 'npm run build' in $ENGINE first"; exit 1; }
-
-clone_index() { # url name
-  echo "=== $2: clone ==="; rm -rf "$ROOT/$2"
-  git clone --quiet --depth 1 "$1" "$ROOT/$2" || { echo "  clone FAILED"; return 1; }
-  echo "=== $2: index ==="
-  node "$BIN" init "$ROOT/$2" 2>&1 | grep -iE 'indexed|nodes|edges|error' | tail -2
-}
-clone_index https://github.com/MTKruto/MTKruto.git mtkruto          # small  (~322 TS)
-clone_index https://github.com/mvdicarlo/postybirb-plus.git postybirb  # medium (~608 TS)
-clone_index https://github.com/shapeshift/web.git shapeshift        # complex (~3.2k TS, 35-pkg monorepo)
-clone_index https://github.com/trezor/trezor-suite.git trezor       # large  (~8k TS monorepo)
-echo "###### SETUP DONE -> $ROOT"
+#!/usr/bin/env bash
+# Clone + index the 4 "not-trained-on" eval repos into $AGENT_EVAL_OUT/repos. These were
+# selected via a no-tools memory-probe gate (Sonnet cannot answer their flow questions from
+# memory — so the no-homegraph baseline is honest). Env: AGENT_EVAL_OUT=<scratch dir>
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ENGINE="$(cd "$HERE/../.." && pwd)"
+BIN="$ENGINE/dist/bin/homegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"
+ROOT="$OUT/repos"; mkdir -p "$ROOT"
+export HOMEGRAPH_TELEMETRY=0 DO_NOT_TRACK=1
+[ -f "$BIN" ] || { echo "engine not built: run 'npm run build' in $ENGINE first"; exit 1; }
+
+clone_index() { # url name
+  echo "=== $2: clone ==="; rm -rf "$ROOT/$2"
+  git clone --quiet --depth 1 "$1" "$ROOT/$2" || { echo "  clone FAILED"; return 1; }
+  echo "=== $2: index ==="
+  node "$BIN" init "$ROOT/$2" 2>&1 | grep -iE 'indexed|nodes|edges|error' | tail -2
+}
+clone_index https://github.com/MTKruto/MTKruto.git mtkruto          # small  (~322 TS)
+clone_index https://github.com/mvdicarlo/postybirb-plus.git postybirb  # medium (~608 TS)
+clone_index https://github.com/shapeshift/web.git shapeshift        # complex (~3.2k TS, 35-pkg monorepo)
+clone_index https://github.com/trezor/trezor-suite.git trezor       # large  (~8k TS monorepo)
+echo "###### SETUP DONE -> $ROOT"

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

@@ -1,72 +1,72 @@
-#!/usr/bin/env bash
-# Offload reasoning-OUTPUT-STYLE A/B — all homegraph-on, isolating the Worker's
-# output shape's effect on main-session tokens / latency / accuracy:
-#   raw  : HOMEGRAPH_OFFLOAD_DISABLE=1            (verbatim explore source, the floor)
-#   refs : managed offload, default              (Cerebras map re-expanded to verbatim, ~24K)
-#   map  : managed offload, STYLE=map            (compact reasoned map + file:line anchors, ~1-3K)
-#   src  : managed offload, STYLE=src            (map + cited line ranges only, ~1-5K)
-# Delegation BLOCKED by default (DISALLOW=Agent) so we measure the offload payload's
-# effect on the main Sonnet agent, not whether it spawns a Haiku Explore subagent.
-#
-# Usage: offload-eval-styles.sh <indexed-repo> <reps> "<question>"
-# Env:   RESULTS=<file>  AGENT_EVAL_OUT=<dir>  REP_START=1  DISALLOW=Agent  MODEL/EFFORT
-set -uo pipefail
-HERE="$(cd "$(dirname "$0")" && pwd)"
-ENGINE="$(cd "$HERE/../.." && pwd)"
-BIN="$ENGINE/dist/bin/homegraph.js"
-OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"
-TARGET="${1:?usage: offload-eval-styles.sh <indexed-repo> <reps> \"<question>\"}"
-REPS="${2:?reps}"; Q="${3:?question}"
-RUNS="$OUT/runs"; EXTRACT="$HERE/offload-eval-metrics.mjs"
-RESULTS="${RESULTS:-$OUT/results-styles.jsonl}"
-REPO=$(basename "$TARGET")
-DISALLOW="${DISALLOW-Agent}"   # default: block delegation. `DISALLOW= ` to allow.
-START="${REP_START:-1}"; END=$((START + REPS - 1))
-mkdir -p "$RUNS"
-command -v claude >/dev/null || { echo "no claude on PATH"; exit 1; }
-[ -d "$TARGET/.homegraph" ] || { echo "not indexed: $TARGET"; exit 1; }
-TARGET=$(cd "$TARGET" && pwd -P)
-
-prewarm() { # path  extra-env
-  pkill -9 -f "serve --mcp --path $1" 2>/dev/null; rm -f "$1/.homegraph/daemon.sock" 2>/dev/null; sleep 0.6
-  env ${2:-} 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" || echo "  WARN daemon never bound"
-}
-kill_daemon() { pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.homegraph/daemon.sock" 2>/dev/null; sleep 1; }
-
-run() { # arm rep mcp-config usage-log-or-dash
-  local arm="$1" rep="$2" cfg="$3" usage="$4" tag="$REPO-$1-$2"
-  [ "$usage" != "-" ] && : > "$usage"
-  ( 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 styles --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 | ${o.tokBillable} billable tok | read=${o.read} grep=${o.grep} explore=${o.explore} offload=${o.offloadFired} | AI ${o.ai.calls}c/${o.ai.totalTokens}t | ok=${o.ok}`)' "$RESULTS"
-}
-
-# MCP configs: env baked into the daemon-spawn command claude uses.
-USAGE="$RUNS/$REPO-usage.jsonl"
-mkcfg() { # file extra-env-pairs(JSON array entries, comma-led or empty)
-  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1"%s,"node","%s","serve","--mcp","--path","%s"]}}}' "$1" "$BIN" "$TARGET"
-}
-CFG_RAW="$RUNS/mcp-sty-raw-$REPO.json";   mkcfg ',"HOMEGRAPH_OFFLOAD_DISABLE=1"' > "$CFG_RAW"
-CFG_REFS="$RUNS/mcp-sty-refs-$REPO.json"; mkcfg ",\"HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE\"" > "$CFG_REFS"
-CFG_MAP="$RUNS/mcp-sty-map-$REPO.json";   mkcfg ",\"HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE\",\"HOMEGRAPH_OFFLOAD_STYLE=map\"" > "$CFG_MAP"
-CFG_SRC="$RUNS/mcp-sty-src-$REPO.json";   mkcfg ",\"HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE\",\"HOMEGRAPH_OFFLOAD_STYLE=src\"" > "$CFG_SRC"
-
-echo "###### repo=$REPO reps=$START..$END model=${MODEL:-sonnet}/${EFFORT:-high} disallow=${DISALLOW:-<none>}"
-echo "###### Q=$Q"
-echo "== ARM raw ==";  prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_DISABLE=1"
-for r in $(seq "$START" "$END"); do run raw  "$r" "$CFG_RAW"  "-"; done; kill_daemon
-echo "== ARM refs =="; prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE"
-for r in $(seq "$START" "$END"); do run refs "$r" "$CFG_REFS" "$USAGE"; done; kill_daemon
-echo "== ARM map ==";  prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE HOMEGRAPH_OFFLOAD_STYLE=map"
-for r in $(seq "$START" "$END"); do run map  "$r" "$CFG_MAP"  "$USAGE"; done; kill_daemon
-echo "== ARM src ==";  prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE HOMEGRAPH_OFFLOAD_STYLE=src"
-for r in $(seq "$START" "$END"); do run src  "$r" "$CFG_SRC"  "$USAGE"; done; kill_daemon
+#!/usr/bin/env bash
+# Offload reasoning-OUTPUT-STYLE A/B — all homegraph-on, isolating the Worker's
+# output shape's effect on main-session tokens / latency / accuracy:
+#   raw  : HOMEGRAPH_OFFLOAD_DISABLE=1            (verbatim explore source, the floor)
+#   refs : managed offload, default              (Cerebras map re-expanded to verbatim, ~24K)
+#   map  : managed offload, STYLE=map            (compact reasoned map + file:line anchors, ~1-3K)
+#   src  : managed offload, STYLE=src            (map + cited line ranges only, ~1-5K)
+# Delegation BLOCKED by default (DISALLOW=Agent) so we measure the offload payload's
+# effect on the main Sonnet agent, not whether it spawns a Haiku Explore subagent.
+#
+# Usage: offload-eval-styles.sh <indexed-repo> <reps> "<question>"
+# Env:   RESULTS=<file>  AGENT_EVAL_OUT=<dir>  REP_START=1  DISALLOW=Agent  MODEL/EFFORT
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ENGINE="$(cd "$HERE/../.." && pwd)"
+BIN="$ENGINE/dist/bin/homegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/cg-offload-eval}"
+TARGET="${1:?usage: offload-eval-styles.sh <indexed-repo> <reps> \"<question>\"}"
+REPS="${2:?reps}"; Q="${3:?question}"
+RUNS="$OUT/runs"; EXTRACT="$HERE/offload-eval-metrics.mjs"
+RESULTS="${RESULTS:-$OUT/results-styles.jsonl}"
+REPO=$(basename "$TARGET")
+DISALLOW="${DISALLOW-Agent}"   # default: block delegation. `DISALLOW= ` to allow.
+START="${REP_START:-1}"; END=$((START + REPS - 1))
+mkdir -p "$RUNS"
+command -v claude >/dev/null || { echo "no claude on PATH"; exit 1; }
+[ -d "$TARGET/.homegraph" ] || { echo "not indexed: $TARGET"; exit 1; }
+TARGET=$(cd "$TARGET" && pwd -P)
+
+prewarm() { # path  extra-env
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null; rm -f "$1/.homegraph/daemon.sock" 2>/dev/null; sleep 0.6
+  env ${2:-} 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" || echo "  WARN daemon never bound"
+}
+kill_daemon() { pkill -9 -f "serve --mcp --path $TARGET" 2>/dev/null; rm -f "$TARGET/.homegraph/daemon.sock" 2>/dev/null; sleep 1; }
+
+run() { # arm rep mcp-config usage-log-or-dash
+  local arm="$1" rep="$2" cfg="$3" usage="$4" tag="$REPO-$1-$2"
+  [ "$usage" != "-" ] && : > "$usage"
+  ( 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 styles --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 | ${o.tokBillable} billable tok | read=${o.read} grep=${o.grep} explore=${o.explore} offload=${o.offloadFired} | AI ${o.ai.calls}c/${o.ai.totalTokens}t | ok=${o.ok}`)' "$RESULTS"
+}
+
+# MCP configs: env baked into the daemon-spawn command claude uses.
+USAGE="$RUNS/$REPO-usage.jsonl"
+mkcfg() { # file extra-env-pairs(JSON array entries, comma-led or empty)
+  printf '{"mcpServers":{"homegraph":{"command":"env","args":["HOMEGRAPH_WASM_RELAUNCHED=1"%s,"node","%s","serve","--mcp","--path","%s"]}}}' "$1" "$BIN" "$TARGET"
+}
+CFG_RAW="$RUNS/mcp-sty-raw-$REPO.json";   mkcfg ',"HOMEGRAPH_OFFLOAD_DISABLE=1"' > "$CFG_RAW"
+CFG_REFS="$RUNS/mcp-sty-refs-$REPO.json"; mkcfg ",\"HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE\"" > "$CFG_REFS"
+CFG_MAP="$RUNS/mcp-sty-map-$REPO.json";   mkcfg ",\"HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE\",\"HOMEGRAPH_OFFLOAD_STYLE=map\"" > "$CFG_MAP"
+CFG_SRC="$RUNS/mcp-sty-src-$REPO.json";   mkcfg ",\"HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE\",\"HOMEGRAPH_OFFLOAD_STYLE=src\"" > "$CFG_SRC"
+
+echo "###### repo=$REPO reps=$START..$END model=${MODEL:-sonnet}/${EFFORT:-high} disallow=${DISALLOW:-<none>}"
+echo "###### Q=$Q"
+echo "== ARM raw ==";  prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_DISABLE=1"
+for r in $(seq "$START" "$END"); do run raw  "$r" "$CFG_RAW"  "-"; done; kill_daemon
+echo "== ARM refs =="; prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE"
+for r in $(seq "$START" "$END"); do run refs "$r" "$CFG_REFS" "$USAGE"; done; kill_daemon
+echo "== ARM map ==";  prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE HOMEGRAPH_OFFLOAD_STYLE=map"
+for r in $(seq "$START" "$END"); do run map  "$r" "$CFG_MAP"  "$USAGE"; done; kill_daemon
+echo "== ARM src ==";  prewarm "$TARGET" "HOMEGRAPH_OFFLOAD_USAGE_LOG=$USAGE HOMEGRAPH_OFFLOAD_STYLE=src"
+for r in $(seq "$START" "$END"); do run src  "$r" "$CFG_SRC"  "$USAGE"; done; kill_daemon
 echo "###### DONE $REPO — judge: node $HERE/offload-eval-judge.mjs --results $RESULTS --truth $HERE/offload-eval-ground-truth.json --out $OUT/judged-styles.jsonl"

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

@@ -1,68 +1,68 @@
-#!/usr/bin/env node
-// Aggregate judged.jsonl (or results.jsonl) into a per-repo, per-arm report:
-// time, main tokens/cost, AI tokens/cost, total cost, tool mix, accuracy.
-// Usage: summarize.mjs <judged-or-results.jsonl>
-import { readFileSync } from 'fs';
-const rows = readFileSync(process.argv[2], 'utf8').split('\n').filter(Boolean).map(l => JSON.parse(l));
-
-const med = (xs) => { const a = xs.filter(x => x != null).sort((p, q) => p - q); if (!a.length) return null; const m = Math.floor(a.length / 2); return a.length % 2 ? a[m] : (a[m - 1] + a[m]) / 2; };
-const rng = (xs) => { const a = xs.filter(x => x != null); return a.length ? `${Math.min(...a)}–${Math.max(...a)}` : '—'; };
-const d2 = (x) => x == null ? '—' : (+x).toFixed(2);
-const d3 = (x) => x == null ? '—' : (+x).toFixed(3);
-const d4 = (x) => x == null ? '—' : (+x).toFixed(4);
-
-const ARM_ORDER = ['frontload', 'offload', 'raw', 'nocg'];
-const byRepo = {};
-for (const r of rows) (byRepo[r.repo] ??= {});
-for (const r of rows) ((byRepo[r.repo][r.arm] ??= []).push(r));
-
-const verdictTally = (rs, field) => {
-  const t = { pass: 0, partial: 0, fail: 0, error: 0 };
-  for (const r of rs) { const v = r[field]?.verdict; if (v in t) t[v]++; }
-  return t;
-};
-
-for (const repo of Object.keys(byRepo)) {
-  const tier = byRepo[repo][Object.keys(byRepo[repo])[0]][0].tier;
-  console.log(`\n${'='.repeat(78)}\n${repo}  [${tier}]\n${'='.repeat(78)}`);
-  console.log(`${'arm'.padEnd(9)} n  ${'time(s)'.padStart(9)} ${'mainCost'.padStart(9)} ${'aiCost'.padStart(8)} ${'totCost'.padStart(8)} ${'mainTok'.padStart(8)} ${'aiTok'.padStart(7)} ${'rd'.padStart(3)} ${'gr'.padStart(3)} ${'exp'.padStart(3)} ${'off'.padStart(3)}  e2e(P/p/F)  fidScore`);
-  for (const arm of ARM_ORDER) {
-    const rs = byRepo[repo][arm]; if (!rs) continue;
-    const n = rs.length;
-    const mainCost = med(rs.map(r => r.costUsdMain));
-    const aiCost = med(rs.map(r => r.ai?.costUsd ?? 0));
-    const totCost = (mainCost ?? 0) + (aiCost ?? 0);
-    const e2e = verdictTally(rs, 'e2e');
-    const fidScores = arm === 'offload' ? rs.flatMap(r => r.fidelity?.scores ?? []) : [];
-    const fid = fidScores.length ? med(fidScores) : null;
-    const fab = arm === 'offload' && rs.some(r => r.fidelity?.anyFabrication);
-    const e2eScore = med(rs.map(r => r.e2e?.score).filter(x => x != null));
-    console.log(
-      `${arm.padEnd(9)} ${String(n).padStart(1)}  ${String(med(rs.map(r => r.durationSec))).padStart(9)} ` +
-      `${('$' + d3(mainCost)).padStart(9)} ${('$' + d3(aiCost)).padStart(8)} ${('$' + d3(totCost)).padStart(8)} ` +
-      `${String(Math.round(med(rs.map(r => r.tokBillable)) / 1000) + 'k').padStart(8)} ${String(Math.round(med(rs.map(r => r.ai?.totalTokens ?? 0)) / 1000) + 'k').padStart(7)} ` +
-      `${String(med(rs.map(r => r.read))).padStart(3)} ${String(med(rs.map(r => r.grep))).padStart(3)} ${String(med(rs.map(r => r.explore))).padStart(3)} ${String(med(rs.map(r => r.offloadFired))).padStart(3)}  ` +
-      `${(e2e.pass + '/' + e2e.partial + '/' + e2e.fail).padStart(9)}  ${e2eScore != null ? 'e2e=' + e2eScore : ''} ${fid != null ? 'fid=' + fid + (fab ? ' FAB!' : '') : ''}`
-    );
-  }
-  // ranges line for the two key metrics (variance matters)
-  for (const arm of ARM_ORDER) {
-    const rs = byRepo[repo][arm]; if (!rs) continue;
-    console.log(`   ${arm} ranges: time ${rng(rs.map(r => r.durationSec))}s · mainCost $${rng(rs.map(r => r.costUsdMain))} · read ${rng(rs.map(r => r.read))} · explore ${rng(rs.map(r => r.explore))} · offloadFired ${rng(rs.map(r => r.offloadFired))}`);
-  }
-}
-
-// Cross-repo roll-up: offload vs raw vs nocg deltas
-console.log(`\n${'='.repeat(78)}\nCROSS-REPO SUMMARY (medians per repo, then averaged)\n${'='.repeat(78)}`);
-console.log(`${'repo'.padEnd(12)} ${'arm'.padEnd(8)} ${'time'.padStart(7)} ${'totCost'.padStart(8)} ${'read'.padStart(5)} ${'e2e pass%'.padStart(9)} ${'fid'.padStart(5)}`);
-for (const repo of Object.keys(byRepo)) {
-  for (const arm of ARM_ORDER) {
-    const rs = byRepo[repo][arm]; if (!rs) continue;
-    const e2e = verdictTally(rs, 'e2e');
-    const passPct = Math.round(100 * e2e.pass / rs.length);
-    const totCost = (med(rs.map(r => r.costUsdMain)) ?? 0) + (med(rs.map(r => r.ai?.costUsd ?? 0)) ?? 0);
-    const fid = arm === 'offload' ? med(rs.flatMap(r => r.fidelity?.scores ?? [])) : null;
-    console.log(`${repo.padEnd(12)} ${arm.padEnd(8)} ${(med(rs.map(r => r.durationSec)) + 's').padStart(7)} ${('$' + d3(totCost)).padStart(8)} ${String(med(rs.map(r => r.read))).padStart(5)} ${(passPct + '%').padStart(9)} ${String(fid ?? '—').padStart(5)}`);
-  }
-}
-console.log('');
+#!/usr/bin/env node
+// Aggregate judged.jsonl (or results.jsonl) into a per-repo, per-arm report:
+// time, main tokens/cost, AI tokens/cost, total cost, tool mix, accuracy.
+// Usage: summarize.mjs <judged-or-results.jsonl>
+import { readFileSync } from 'fs';
+const rows = readFileSync(process.argv[2], 'utf8').split('\n').filter(Boolean).map(l => JSON.parse(l));
+
+const med = (xs) => { const a = xs.filter(x => x != null).sort((p, q) => p - q); if (!a.length) return null; const m = Math.floor(a.length / 2); return a.length % 2 ? a[m] : (a[m - 1] + a[m]) / 2; };
+const rng = (xs) => { const a = xs.filter(x => x != null); return a.length ? `${Math.min(...a)}–${Math.max(...a)}` : '—'; };
+const d2 = (x) => x == null ? '—' : (+x).toFixed(2);
+const d3 = (x) => x == null ? '—' : (+x).toFixed(3);
+const d4 = (x) => x == null ? '—' : (+x).toFixed(4);
+
+const ARM_ORDER = ['frontload', 'offload', 'raw', 'nocg'];
+const byRepo = {};
+for (const r of rows) (byRepo[r.repo] ??= {});
+for (const r of rows) ((byRepo[r.repo][r.arm] ??= []).push(r));
+
+const verdictTally = (rs, field) => {
+  const t = { pass: 0, partial: 0, fail: 0, error: 0 };
+  for (const r of rs) { const v = r[field]?.verdict; if (v in t) t[v]++; }
+  return t;
+};
+
+for (const repo of Object.keys(byRepo)) {
+  const tier = byRepo[repo][Object.keys(byRepo[repo])[0]][0].tier;
+  console.log(`\n${'='.repeat(78)}\n${repo}  [${tier}]\n${'='.repeat(78)}`);
+  console.log(`${'arm'.padEnd(9)} n  ${'time(s)'.padStart(9)} ${'mainCost'.padStart(9)} ${'aiCost'.padStart(8)} ${'totCost'.padStart(8)} ${'mainTok'.padStart(8)} ${'aiTok'.padStart(7)} ${'rd'.padStart(3)} ${'gr'.padStart(3)} ${'exp'.padStart(3)} ${'off'.padStart(3)}  e2e(P/p/F)  fidScore`);
+  for (const arm of ARM_ORDER) {
+    const rs = byRepo[repo][arm]; if (!rs) continue;
+    const n = rs.length;
+    const mainCost = med(rs.map(r => r.costUsdMain));
+    const aiCost = med(rs.map(r => r.ai?.costUsd ?? 0));
+    const totCost = (mainCost ?? 0) + (aiCost ?? 0);
+    const e2e = verdictTally(rs, 'e2e');
+    const fidScores = arm === 'offload' ? rs.flatMap(r => r.fidelity?.scores ?? []) : [];
+    const fid = fidScores.length ? med(fidScores) : null;
+    const fab = arm === 'offload' && rs.some(r => r.fidelity?.anyFabrication);
+    const e2eScore = med(rs.map(r => r.e2e?.score).filter(x => x != null));
+    console.log(
+      `${arm.padEnd(9)} ${String(n).padStart(1)}  ${String(med(rs.map(r => r.durationSec))).padStart(9)} ` +
+      `${('$' + d3(mainCost)).padStart(9)} ${('$' + d3(aiCost)).padStart(8)} ${('$' + d3(totCost)).padStart(8)} ` +
+      `${String(Math.round(med(rs.map(r => r.tokBillable)) / 1000) + 'k').padStart(8)} ${String(Math.round(med(rs.map(r => r.ai?.totalTokens ?? 0)) / 1000) + 'k').padStart(7)} ` +
+      `${String(med(rs.map(r => r.read))).padStart(3)} ${String(med(rs.map(r => r.grep))).padStart(3)} ${String(med(rs.map(r => r.explore))).padStart(3)} ${String(med(rs.map(r => r.offloadFired))).padStart(3)}  ` +
+      `${(e2e.pass + '/' + e2e.partial + '/' + e2e.fail).padStart(9)}  ${e2eScore != null ? 'e2e=' + e2eScore : ''} ${fid != null ? 'fid=' + fid + (fab ? ' FAB!' : '') : ''}`
+    );
+  }
+  // ranges line for the two key metrics (variance matters)
+  for (const arm of ARM_ORDER) {
+    const rs = byRepo[repo][arm]; if (!rs) continue;
+    console.log(`   ${arm} ranges: time ${rng(rs.map(r => r.durationSec))}s · mainCost $${rng(rs.map(r => r.costUsdMain))} · read ${rng(rs.map(r => r.read))} · explore ${rng(rs.map(r => r.explore))} · offloadFired ${rng(rs.map(r => r.offloadFired))}`);
+  }
+}
+
+// Cross-repo roll-up: offload vs raw vs nocg deltas
+console.log(`\n${'='.repeat(78)}\nCROSS-REPO SUMMARY (medians per repo, then averaged)\n${'='.repeat(78)}`);
+console.log(`${'repo'.padEnd(12)} ${'arm'.padEnd(8)} ${'time'.padStart(7)} ${'totCost'.padStart(8)} ${'read'.padStart(5)} ${'e2e pass%'.padStart(9)} ${'fid'.padStart(5)}`);
+for (const repo of Object.keys(byRepo)) {
+  for (const arm of ARM_ORDER) {
+    const rs = byRepo[repo][arm]; if (!rs) continue;
+    const e2e = verdictTally(rs, 'e2e');
+    const passPct = Math.round(100 * e2e.pass / rs.length);
+    const totCost = (med(rs.map(r => r.costUsdMain)) ?? 0) + (med(rs.map(r => r.ai?.costUsd ?? 0)) ?? 0);
+    const fid = arm === 'offload' ? med(rs.flatMap(r => r.fidelity?.scores ?? [])) : null;
+    console.log(`${repo.padEnd(12)} ${arm.padEnd(8)} ${(med(rs.map(r => r.durationSec)) + 's').padStart(7)} ${('$' + d3(totCost)).padStart(8)} ${String(med(rs.map(r => r.read))).padStart(5)} ${(passPct + '%').padStart(9)} ${String(fid ?? '—').padStart(5)}`);
+  }
+}
+console.log('');

package/scripts/agent-eval/offload-eval.md

@@ -1,76 +1,76 @@
-# HomeGraph AI offload — accuracy & adoption eval harness
-
-Measures the managed **offload** (`homegraph_explore` → reasoning model synthesis) and the
-**front-load hook** (approach 1) against plain homegraph and no-homegraph, across repo sizes,
-on **time · main-session tokens/cost · HomeGraph-AI tokens/cost · accuracy**.
-
-All agent arms run `claude -p --model sonnet --effort high` (the deliberate floor model — an
-affordance that lands on Sonnet generalizes up). Everything writes to a scratch dir
-(`AGENT_EVAL_OUT`, default `/tmp/cg-offload-eval`); nothing here is shipped to users.
-
-## Repos (selected via a memory-probe gate — NOT trained on)
-
-Famous repos (express, excalidraw, n8n, …) are useless for *accuracy* evals: Sonnet answers their
-flow questions from memory, so the no-homegraph baseline is dishonest. These four passed a no-tools
-probe (Sonnet could not name their real flow internals) and are cloned fresh by `offload-eval-setup.sh`:
-
-| tier | repo | ~src files | canonical flow |
-|---|---|---|---|
-| small | MTKruto/MTKruto | 322 TS | `sendMessage` → invoke → TL serialize → transport |
-| medium | mvdicarlo/postybirb-plus | 608 TS | submission → queue → per-website `.post()` |
-| complex | shapeshift/web | 3.2k TS (35-pkg monorepo) | swap → swapper registry → concrete swapper |
-| large | trezor/trezor-suite | 8k TS monorepo | send-form → sign thunk → `@trezor/connect` |
-
-Verified ground-truth flows (the judge's reference) live in `offload-eval-ground-truth.json`.
-
-## Arms
-
-- **offload** — homegraph + managed offload ON (requires `homegraph login`); records AI tokens/credits via `HOMEGRAPH_OFFLOAD_USAGE_LOG`.
-- **raw** — homegraph, `HOMEGRAPH_OFFLOAD_DISABLE=1` (returns raw source).
-- **nocg** — empty MCP config; Read/Grep baseline.
-- **frontload** — homegraph (offload-disabled) + a `UserPromptSubmit` hook (`offload-eval-hook.mjs`) that runs raw explore on the prompt and injects the result into context (approach 1).
-
-## Run it
-
-```bash
-npm run build                       # the harness shells out to dist/
-homegraph login                     # only needed for the offload arm
-export AGENT_EVAL_OUT=/tmp/cg-offload-eval
-
-bash scripts/agent-eval/offload-eval-setup.sh            # clone + index the 4 repos
-bash scripts/agent-eval/offload-eval-matrix.sh           # 3 arms × 4 tiers × REPS (default 3)
-node scripts/agent-eval/offload-eval-judge.mjs \
-     --results $AGENT_EVAL_OUT/results.jsonl \
-     --truth  scripts/agent-eval/offload-eval-ground-truth.json \
-     --out    $AGENT_EVAL_OUT/judged.jsonl
-node scripts/agent-eval/offload-eval-summarize.mjs $AGENT_EVAL_OUT/judged.jsonl
-
-bash scripts/agent-eval/offload-eval-frontload-matrix.sh # frontload arm + judge + merged summary
-```
-
-Single repo: `offload-eval-3arm.sh <indexed-repo> <tier> <reps> "<question>"` (or `-frontload.sh`).
-
-## Files
-
-- `offload-eval-setup.sh` — clone + index the 4 repos.
-- `offload-eval-3arm.sh` / `-frontload.sh` — one repo, the arms.
-- `offload-eval-matrix.sh` / `-frontload-matrix.sh` — drive all 4 tiers.
-- `offload-eval-hook.mjs` — the front-load `UserPromptSubmit` hook (resolves its own engine; `CG_FRONTLOAD_DEBUG=<path>` to log injections; `CG_FRONTLOAD_BUDGET` to cap injected chars).
-- `offload-eval-metrics.mjs` — one run's stream-json + usage log → one JSON metrics line.
-- `offload-eval-judge.mjs` — Sonnet judge: end-to-end (agent final vs ground truth) + per-answer offload fidelity.
-- `offload-eval-summarize.mjs` — per-tier, per-arm table + cross-repo roll-up.
-- `offload-eval-ground-truth.json` — source-verified canonical flows.
-
-## Findings (2026-06, n=3 — direction consistent, magnitudes noisy)
-
-- **Raw homegraph is the efficiency win** — ~nocg accuracy, fewer reads, faster, no AI cost.
-- **The offload is the least-accurate arm in all 4 tiers** — synthesized fidelity 12–27/100 with
-  fabrication in 3/4 (e.g. invented website services; traced `ClientPlain`/`SessionPlain` instead of
-  the real encrypted path). Its speed/cost win is narrow (medium-only) and inversely correlated with
-  accuracy. **Use raw until offload fidelity is fixed.**
-- **The front-load hook SOLVES adoption** — reads → 0–1 in every tier (incl. large, where the agent
-  otherwise read 12–24 files); fired 12/12, 0 errors. Wins on medium/complex (100% pass). But it
-  **regresses small/large to partial** — it suppresses the reads that compensate for explore's gaps at
-  **dynamic boundaries** (async queues, redux thunks, facade/factory indirection).
-- **Master lever for BOTH:** explore's dynamic-dispatch coverage. Fix it → front-load is complete
-  everywhere and the offload has the full flow to synthesize.
+# HomeGraph AI offload — accuracy & adoption eval harness
+
+Measures the managed **offload** (`homegraph_explore` → reasoning model synthesis) and the
+**front-load hook** (approach 1) against plain homegraph and no-homegraph, across repo sizes,
+on **time · main-session tokens/cost · HomeGraph-AI tokens/cost · accuracy**.
+
+All agent arms run `claude -p --model sonnet --effort high` (the deliberate floor model — an
+affordance that lands on Sonnet generalizes up). Everything writes to a scratch dir
+(`AGENT_EVAL_OUT`, default `/tmp/cg-offload-eval`); nothing here is shipped to users.
+
+## Repos (selected via a memory-probe gate — NOT trained on)
+
+Famous repos (express, excalidraw, n8n, …) are useless for *accuracy* evals: Sonnet answers their
+flow questions from memory, so the no-homegraph baseline is dishonest. These four passed a no-tools
+probe (Sonnet could not name their real flow internals) and are cloned fresh by `offload-eval-setup.sh`:
+
+| tier | repo | ~src files | canonical flow |
+|---|---|---|---|
+| small | MTKruto/MTKruto | 322 TS | `sendMessage` → invoke → TL serialize → transport |
+| medium | mvdicarlo/postybirb-plus | 608 TS | submission → queue → per-website `.post()` |
+| complex | shapeshift/web | 3.2k TS (35-pkg monorepo) | swap → swapper registry → concrete swapper |
+| large | trezor/trezor-suite | 8k TS monorepo | send-form → sign thunk → `@trezor/connect` |
+
+Verified ground-truth flows (the judge's reference) live in `offload-eval-ground-truth.json`.
+
+## Arms
+
+- **offload** — homegraph + managed offload ON (requires `homegraph login`); records AI tokens/credits via `HOMEGRAPH_OFFLOAD_USAGE_LOG`.
+- **raw** — homegraph, `HOMEGRAPH_OFFLOAD_DISABLE=1` (returns raw source).
+- **nocg** — empty MCP config; Read/Grep baseline.
+- **frontload** — homegraph (offload-disabled) + a `UserPromptSubmit` hook (`offload-eval-hook.mjs`) that runs raw explore on the prompt and injects the result into context (approach 1).
+
+## Run it
+
+```bash
+npm run build                       # the harness shells out to dist/
+homegraph login                     # only needed for the offload arm
+export AGENT_EVAL_OUT=/tmp/cg-offload-eval
+
+bash scripts/agent-eval/offload-eval-setup.sh            # clone + index the 4 repos
+bash scripts/agent-eval/offload-eval-matrix.sh           # 3 arms × 4 tiers × REPS (default 3)
+node scripts/agent-eval/offload-eval-judge.mjs \
+     --results $AGENT_EVAL_OUT/results.jsonl \
+     --truth  scripts/agent-eval/offload-eval-ground-truth.json \
+     --out    $AGENT_EVAL_OUT/judged.jsonl
+node scripts/agent-eval/offload-eval-summarize.mjs $AGENT_EVAL_OUT/judged.jsonl
+
+bash scripts/agent-eval/offload-eval-frontload-matrix.sh # frontload arm + judge + merged summary
+```
+
+Single repo: `offload-eval-3arm.sh <indexed-repo> <tier> <reps> "<question>"` (or `-frontload.sh`).
+
+## Files
+
+- `offload-eval-setup.sh` — clone + index the 4 repos.
+- `offload-eval-3arm.sh` / `-frontload.sh` — one repo, the arms.
+- `offload-eval-matrix.sh` / `-frontload-matrix.sh` — drive all 4 tiers.
+- `offload-eval-hook.mjs` — the front-load `UserPromptSubmit` hook (resolves its own engine; `CG_FRONTLOAD_DEBUG=<path>` to log injections; `CG_FRONTLOAD_BUDGET` to cap injected chars).
+- `offload-eval-metrics.mjs` — one run's stream-json + usage log → one JSON metrics line.
+- `offload-eval-judge.mjs` — Sonnet judge: end-to-end (agent final vs ground truth) + per-answer offload fidelity.
+- `offload-eval-summarize.mjs` — per-tier, per-arm table + cross-repo roll-up.
+- `offload-eval-ground-truth.json` — source-verified canonical flows.
+
+## Findings (2026-06, n=3 — direction consistent, magnitudes noisy)
+
+- **Raw homegraph is the efficiency win** — ~nocg accuracy, fewer reads, faster, no AI cost.
+- **The offload is the least-accurate arm in all 4 tiers** — synthesized fidelity 12–27/100 with
+  fabrication in 3/4 (e.g. invented website services; traced `ClientPlain`/`SessionPlain` instead of
+  the real encrypted path). Its speed/cost win is narrow (medium-only) and inversely correlated with
+  accuracy. **Use raw until offload fidelity is fixed.**
+- **The front-load hook SOLVES adoption** — reads → 0–1 in every tier (incl. large, where the agent
+  otherwise read 12–24 files); fired 12/12, 0 errors. Wins on medium/complex (100% pass). But it
+  **regresses small/large to partial** — it suppresses the reads that compensate for explore's gaps at
+  **dynamic boundaries** (async queues, redux thunks, facade/factory indirection).
+- **Master lever for BOTH:** explore's dynamic-dispatch coverage. Fix it → front-load is complete
+  everywhere and the offload has the full flow to synthesize.