homegraph 1.1.2 → 1.1.3

package/scripts/agent-eval/probe-trace.mjs

@@ -1,20 +1,20 @@
-#!/usr/bin/env node
-// Probe homegraph_trace against an index using the built dist.
-// Usage: node probe-trace.mjs <repo-with-.homegraph> <from> <to>
-import { pathToFileURL } from 'node:url';
-import { resolve } from 'node:path';
-
-const [, , repo, from, to] = process.argv;
-if (!repo || !from || !to) { console.error('usage: probe-trace.mjs <repo> <from> <to>'); process.exit(1); }
-
-const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
-const idx = await load('dist/index.js');
-const tools = await load('dist/mcp/tools.js');
-const HomeGraph = idx.default?.default ?? idx.default ?? idx.HomeGraph;
-const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
-
-const cg = HomeGraph.openSync(repo);
-const h = new ToolHandler(cg);
-const res = await h.execute('homegraph_trace', { from, to });
-console.log(res.content?.[0]?.text ?? '(no text)');
-try { cg.close?.(); } catch {}
+#!/usr/bin/env node
+// Probe homegraph_trace against an index using the built dist.
+// Usage: node probe-trace.mjs <repo-with-.homegraph> <from> <to>
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, from, to] = process.argv;
+if (!repo || !from || !to) { console.error('usage: probe-trace.mjs <repo> <from> <to>'); process.exit(1); }
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const HomeGraph = idx.default?.default ?? idx.default ?? idx.HomeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+const cg = HomeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('homegraph_trace', { from, to });
+console.log(res.content?.[0]?.text ?? '(no text)');
+try { cg.close?.(); } catch {}

package/scripts/agent-eval/redirect-read-hook.sh

@@ -1,38 +1,38 @@
-#!/usr/bin/env bash
-# PreToolUse(Read) REDIRECT hook — prototype for A/B (P1: get agents off Read and
-# onto homegraph_node during implementation, not just for Q&A).
-#
-# When the agent Reads a SOURCE file, deny it and steer to homegraph_node's
-# file-view, which (as of the Lever-1 change) returns the WHOLE file verbatim
-# WITH line numbers — imports, top-level code, comments and all — PLUS the file's
-# blast radius, in one call. That output is a strict superset of Read, so the
-# redirect is lossless: the agent loses nothing by taking it, and gains who-
-# depends-on-this for the edit it's about to make.
-#
-# Differs from block-read-hook.sh (which steers to explore/node-by-symbol): this
-# names the FILE-VIEW path explicitly (file:"<base>" + includeCode:true), the
-# 1:1 Read replacement we're trying to get picked during implementation.
-#
-# Non-source files (configs, docs, lockfiles, .env) pass through to a real Read.
-# A redirect to a file homegraph hasn't indexed SELF-CORRECTS: the file-view
-# replies "No indexed file matches … Read it directly", so a just-created file
-# never dead-ends — the agent Reads it on the next turn.
-#
-# Wire via:  claude ... --settings <settings-with-this-as-PreToolUse(Read)>
-# Eval artifact only. The production version is an indexed-aware `homegraph`
-# subcommand (cross-platform — no bash/jq — and queries the index so it never
-# bounces a new/un-indexed file), wired opt-in by the installer.
-set -uo pipefail
-input="$(cat)"
-fp="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
-[ -n "$fp" ] || exit 0
-base="$(basename "$fp")"
-
-case "$fp" in
-  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.py|*.go|*.rs|*.java|*.rb|*.php|*.swift|*.kt|*.kts|*.scala|*.c|*.cc|*.cpp|*.h|*.hpp|*.cs|*.lua|*.vue|*.svelte|*.m|*.mm)
-    msg="homegraph has this file indexed (kept in sync on every edit). Call homegraph_node with file:\"$base\" and includeCode:true instead of Read — it returns the WHOLE file verbatim WITH line numbers (imports, top-level code and all — safe to base an Edit on) PLUS which files depend on it, in one call. Treat its output as already-Read; do not Read this file. (If it answers that the file isn't indexed — e.g. you just created it — then Read it directly.)"
-    jq -n --arg m "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$m}}'
-    exit 0
-    ;;
-esac
-exit 0
+#!/usr/bin/env bash
+# PreToolUse(Read) REDIRECT hook — prototype for A/B (P1: get agents off Read and
+# onto homegraph_node during implementation, not just for Q&A).
+#
+# When the agent Reads a SOURCE file, deny it and steer to homegraph_node's
+# file-view, which (as of the Lever-1 change) returns the WHOLE file verbatim
+# WITH line numbers — imports, top-level code, comments and all — PLUS the file's
+# blast radius, in one call. That output is a strict superset of Read, so the
+# redirect is lossless: the agent loses nothing by taking it, and gains who-
+# depends-on-this for the edit it's about to make.
+#
+# Differs from block-read-hook.sh (which steers to explore/node-by-symbol): this
+# names the FILE-VIEW path explicitly (file:"<base>" + includeCode:true), the
+# 1:1 Read replacement we're trying to get picked during implementation.
+#
+# Non-source files (configs, docs, lockfiles, .env) pass through to a real Read.
+# A redirect to a file homegraph hasn't indexed SELF-CORRECTS: the file-view
+# replies "No indexed file matches … Read it directly", so a just-created file
+# never dead-ends — the agent Reads it on the next turn.
+#
+# Wire via:  claude ... --settings <settings-with-this-as-PreToolUse(Read)>
+# Eval artifact only. The production version is an indexed-aware `homegraph`
+# subcommand (cross-platform — no bash/jq — and queries the index so it never
+# bounces a new/un-indexed file), wired opt-in by the installer.
+set -uo pipefail
+input="$(cat)"
+fp="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+[ -n "$fp" ] || exit 0
+base="$(basename "$fp")"
+
+case "$fp" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.py|*.go|*.rs|*.java|*.rb|*.php|*.swift|*.kt|*.kts|*.scala|*.c|*.cc|*.cpp|*.h|*.hpp|*.cs|*.lua|*.vue|*.svelte|*.m|*.mm)
+    msg="homegraph has this file indexed (kept in sync on every edit). Call homegraph_node with file:\"$base\" and includeCode:true instead of Read — it returns the WHOLE file verbatim WITH line numbers (imports, top-level code and all — safe to base an Edit on) PLUS which files depend on it, in one call. Treat its output as already-Read; do not Read this file. (If it answers that the file isn't indexed — e.g. you just created it — then Read it directly.)"
+    jq -n --arg m "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$m}}'
+    exit 0
+    ;;
+esac
+exit 0

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

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

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

@@ -1,69 +1,69 @@
-#!/usr/bin/env bash
-# With/without A/B (and optional interactive) eval for a homegraph version on a
-# repo. Codegraph is the ONLY variable: both arms launch claude with
-# --strict-mcp-config — with = homegraph-only MCP (pointed at $CG_BIN),
-# without = empty MCP. Built-in Read/Grep/Bash stay available in both arms.
-#
-# Usage: run-all.sh <repo-path> "<question>" [headless|tmux|all]
-# Env:   CG_BIN          homegraph binary (default: command -v homegraph)
-#        AGENT_EVAL_OUT  output dir (default: /tmp/agent-eval)
-#        MODEL / EFFORT  claude model/effort (default: sonnet / high — the
-#                        standing A/B policy; see CLAUDE.md, don't raise)
-set -uo pipefail
-
-REPO="${1:?usage: run-all.sh <repo-path> \"<question>\" [headless|tmux|all]}"
-Q="${2:?question required}"
-MODE="${3:-headless}"
-CG_BIN="${CG_BIN:-$(command -v homegraph)}"
-OUT="${AGENT_EVAL_OUT:-/tmp/agent-eval}"
-HARNESS="$(cd "$(dirname "$0")" && pwd)"
-mkdir -p "$OUT"
-
-[ -n "$CG_BIN" ] || { echo "no homegraph binary on PATH (set CG_BIN)"; exit 1; }
-[ -d "$REPO/.homegraph" ] || { echo "no .homegraph index at $REPO — index it first"; exit 1; }
-case "$MODE" in headless|tmux|all) ;; *) echo "mode must be headless|tmux|all (got '$MODE')"; exit 1;; esac
-
-# MCP config files (path form avoids inline-JSON quoting through tmux).
-cat > "$OUT/mcp-homegraph.json" <<JSON
-{"mcpServers":{"homegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"]}}}
-JSON
-echo '{"mcpServers":{}}' > "$OUT/mcp-empty.json"
-
-echo "###### homegraph: $CG_BIN"
-echo "###### repo:      $REPO"
-echo "###### question:  $Q"
-echo
-
-# Headless arm: claude -p with stream-json -> exact tool sequence + tokens/cost.
-headless() {
-  local label="$1" cfg="$2"
-  echo "############################## HEADLESS [$label] ##############################"
-  ( cd "$REPO" && 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" \
-      > "$OUT/run-$label.jsonl" 2>"$OUT/run-$label.err" )
-  echo "exit $? -> $OUT/run-$label.jsonl ($(wc -l < "$OUT/run-$label.jsonl" | tr -d ' ') lines)"
-  tail -2 "$OUT/run-$label.err" 2>/dev/null
-  node "$HARNESS/parse-run.mjs" "$OUT/run-$label.jsonl" 2>&1 || true
-  echo
-}
-
-if [ "$MODE" = headless ] || [ "$MODE" = all ]; then
-  headless "headless-with"    "$OUT/mcp-homegraph.json"
-  headless "headless-without" "$OUT/mcp-empty.json"
-fi
-
-if [ "$MODE" = tmux ] || [ "$MODE" = all ]; then
-  echo "############################## INTERACTIVE [with] ##############################"
-  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-homegraph.json" \
-    bash "$HARNESS/itrun.sh" "$REPO" "int-with" "$Q" 2>&1 || echo "[itrun WITH failed]"
-  echo
-  echo "############################## INTERACTIVE [without] ##############################"
-  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-empty.json" \
-    bash "$HARNESS/itrun.sh" "$REPO" "int-without" "$Q" 2>&1 || echo "[itrun WITHOUT failed]"
-  echo
-fi
-echo "############################## RUN-ALL COMPLETE ##############################"
+#!/usr/bin/env bash
+# With/without A/B (and optional interactive) eval for a homegraph version on a
+# repo. Codegraph is the ONLY variable: both arms launch claude with
+# --strict-mcp-config — with = homegraph-only MCP (pointed at $CG_BIN),
+# without = empty MCP. Built-in Read/Grep/Bash stay available in both arms.
+#
+# Usage: run-all.sh <repo-path> "<question>" [headless|tmux|all]
+# Env:   CG_BIN          homegraph binary (default: command -v homegraph)
+#        AGENT_EVAL_OUT  output dir (default: /tmp/agent-eval)
+#        MODEL / EFFORT  claude model/effort (default: sonnet / high — the
+#                        standing A/B policy; see CLAUDE.md, don't raise)
+set -uo pipefail
+
+REPO="${1:?usage: run-all.sh <repo-path> \"<question>\" [headless|tmux|all]}"
+Q="${2:?question required}"
+MODE="${3:-headless}"
+CG_BIN="${CG_BIN:-$(command -v homegraph)}"
+OUT="${AGENT_EVAL_OUT:-/tmp/agent-eval}"
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+mkdir -p "$OUT"
+
+[ -n "$CG_BIN" ] || { echo "no homegraph binary on PATH (set CG_BIN)"; exit 1; }
+[ -d "$REPO/.homegraph" ] || { echo "no .homegraph index at $REPO — index it first"; exit 1; }
+case "$MODE" in headless|tmux|all) ;; *) echo "mode must be headless|tmux|all (got '$MODE')"; exit 1;; esac
+
+# MCP config files (path form avoids inline-JSON quoting through tmux).
+cat > "$OUT/mcp-homegraph.json" <<JSON
+{"mcpServers":{"homegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"]}}}
+JSON
+echo '{"mcpServers":{}}' > "$OUT/mcp-empty.json"
+
+echo "###### homegraph: $CG_BIN"
+echo "###### repo:      $REPO"
+echo "###### question:  $Q"
+echo
+
+# Headless arm: claude -p with stream-json -> exact tool sequence + tokens/cost.
+headless() {
+  local label="$1" cfg="$2"
+  echo "############################## HEADLESS [$label] ##############################"
+  ( cd "$REPO" && 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" \
+      > "$OUT/run-$label.jsonl" 2>"$OUT/run-$label.err" )
+  echo "exit $? -> $OUT/run-$label.jsonl ($(wc -l < "$OUT/run-$label.jsonl" | tr -d ' ') lines)"
+  tail -2 "$OUT/run-$label.err" 2>/dev/null
+  node "$HARNESS/parse-run.mjs" "$OUT/run-$label.jsonl" 2>&1 || true
+  echo
+}
+
+if [ "$MODE" = headless ] || [ "$MODE" = all ]; then
+  headless "headless-with"    "$OUT/mcp-homegraph.json"
+  headless "headless-without" "$OUT/mcp-empty.json"
+fi
+
+if [ "$MODE" = tmux ] || [ "$MODE" = all ]; then
+  echo "############################## INTERACTIVE [with] ##############################"
+  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-homegraph.json" \
+    bash "$HARNESS/itrun.sh" "$REPO" "int-with" "$Q" 2>&1 || echo "[itrun WITH failed]"
+  echo
+  echo "############################## INTERACTIVE [without] ##############################"
+  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-empty.json" \
+    bash "$HARNESS/itrun.sh" "$REPO" "int-without" "$Q" 2>&1 || echo "[itrun WITHOUT failed]"
+  echo
+fi
+echo "############################## RUN-ALL COMPLETE ##############################"

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

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