pantheon-opencode 1.4.2 → 1.5.0-beta.1

package/scripts/test-opencode-v1-v2-sandbox.sh

@@ -0,0 +1,591 @@
+#!/usr/bin/env bash
+# test-opencode-v1-v2-sandbox.sh — Pantheon global-install sandbox validator
+# for OpenCode V1 (`opencode`) and V2 (`opencode2`) side-by-side.
+#
+# Validates the installed pantheon-opencode package AS A REAL USER inside an
+# isolated sandbox (own HOME, npm prefix and venv), never the dev environment.
+#
+# Modes (combinable):
+#   --prepare        Build tarball, install pantheon-opencode + OpenCode V1/V2
+#                    binaries in the sandbox prefix, headless init, and generate
+#                    the per-version project configs and sandbox run-test.sh.
+#   --run v1|v2      Base validation for one version: opencode mcp list + doctor
+#                    (config is regenerated for that version first).
+#   --prompts        Prompt battery via `opencode run --format json` for every
+#                    requested version (with --run vX) or both versions alone.
+#   --reset          Wipe the sandbox root.
+#   --help           Usage.
+#
+# Env overrides:
+#   PANTHEON_SANDBOX_ROOT    Sandbox root (default: ~/pantheon-sandbox)
+#   OPENCODE_V1_SPEC         npm spec providing the `opencode` binary
+#                            (default: opencode-ai@1.18.18)
+#   OPENCODE_V2_SPEC         npm spec providing the `opencode2` binary
+#                            (default: @opencode-ai/cli@beta)
+#   PANTHEON_SANDBOX_MODEL   Model used by init/prompts
+#                            (default: opencode-go/mimo-v2.5)
+#   PANTHEON_PROMPT_TIMEOUT  Per-prompt timeout in seconds (default: 300)
+#   PANTHEON_RETRY_COOLDOWN  Cooldown seconds before the single FAIL retry
+#                            (default: 60; retry only for real FAIL, never AMBIENTAL)
+#
+# Exit codes: 0 = no real failures (AMBIENTAL issues do not fail the run),
+#             1 = real FAIL (see prompts-report.md in the sandbox root),
+#             2 = usage error, 3 = sandbox not prepared.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+SANDBOX_ROOT="${PANTHEON_SANDBOX_ROOT:-$HOME/pantheon-sandbox}"
+SANDBOX_HOME="$SANDBOX_ROOT/home"
+NPM_PREFIX="$SANDBOX_HOME/.npm-global"
+
+OPENCODE_V1_SPEC="${OPENCODE_V1_SPEC:-opencode-ai@1.18.18}"
+OPENCODE_V2_SPEC="${OPENCODE_V2_SPEC:-@opencode-ai/cli@beta}"
+PANTHEON_SANDBOX_MODEL="${PANTHEON_SANDBOX_MODEL:-opencode-go/mimo-v2.5}"
+PANTHEON_PROMPT_TIMEOUT="${PANTHEON_PROMPT_TIMEOUT:-300}"
+
+V1_BIN="${OPENCODE_V1_BIN:-opencode}"
+V2_BIN="${OPENCODE_V2_BIN:-opencode2}"
+
+REPORT_FILE="$SANDBOX_ROOT/prompts-report.md"
+EXTRACT_PY="$SANDBOX_ROOT/.prompt-extract-json.py"
+
+MODE_PREPARE=0
+MODE_RESET=0
+MODE_PROMPTS=0
+RUN_VERSION=""
+
+usage() {
+  sed -n '2,40p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+  exit 2
+}
+
+log() { printf '%s\n' "$*"; }
+warn() { printf 'WARN: %s\n' "$*" >&2; }
+die() { printf 'ERROR: %s\n' "$*" >&2; exit 1; }
+
+bin_for() {
+  case "$1" in
+    v1) printf '%s' "$V1_BIN" ;;
+    v2) printf '%s' "$V2_BIN" ;;
+    *) return 1 ;;
+  esac
+}
+
+project_for() { printf '%s/project-%s' "$SANDBOX_ROOT" "$1"; }
+
+# Resolve a binary STRICTLY inside the sandbox npm prefix — never fall back to
+# the dev PATH, otherwise a non-prepared sandbox would silently test the host
+# installation.
+sandbox_bin_for() { # name → prints path; rc 1 if not inside sandbox prefix
+  local p
+  p="$(command -v "$1" 2>/dev/null || true)"
+  case "$p" in
+    "$NPM_PREFIX"/*) printf '%s' "$p" ;;
+    *) return 1 ;;
+  esac
+}
+
+sandbox_bin_v() { # v → echoes path; rc 1 if missing
+  sandbox_bin_for "$(bin_for "$1")"
+}
+
+# ── Sandbox environment isolation ─────────────────────────────────────────────
+
+sandbox_env() {
+  export HOME="$SANDBOX_HOME"
+  export PATH="$NPM_PREFIX/bin:$HOME/.config/opencode/.venv/bin:$PATH"
+  export npm_config_prefix="$NPM_PREFIX"
+}
+
+# ── Gate (b): sandbox run-test.sh with pantheon://agents content validation ──
+
+write_run_test_sh() {
+  cat > "$SANDBOX_ROOT/run-test.sh" <<'RUNTEST'
+#!/usr/bin/env bash
+# Generated by pantheon-opencode scripts/test-opencode-v1-v2-sandbox.sh --prepare
+# Validates the global install: binaries, 5/5 MCP connectivity, doctor 0 errors,
+# AND the CONTENT of the pantheon://agents resource (zeus/hermes present).
+set -euo pipefail
+
+SANDBOX_DIR="$(cd "$(dirname "$0")" && pwd)"
+SANDBOX_HOME="$SANDBOX_DIR/home"
+NPM_PREFIX="$SANDBOX_HOME/.npm-global"
+PANTHEON_GLOBAL="$SANDBOX_HOME/.config/opencode"
+SANDBOX_VENV="$PANTHEON_GLOBAL/.venv"
+REPO_DIR="${PANTHEON_REPO:-$(cd "$SANDBOX_DIR/../pantheon" && pwd)}"
+
+echo "=== Pantheon Sandbox Test ==="
+echo "Sandbox: $SANDBOX_DIR"
+echo "Repo:    $REPO_DIR"
+
+export HOME="$SANDBOX_HOME"
+export PATH="$NPM_PREFIX/bin:$SANDBOX_VENV/bin:$PATH"
+export npm_config_prefix="$NPM_PREFIX"
+
+echo "--- Binaries ---"
+opencode --version
+opencode2 --version
+
+echo "--- Building tarball ---"
+cd "$REPO_DIR"
+npm pack 2>/dev/null || { echo "ERROR: npm pack failed"; exit 1; }
+TGZ=$(ls -t pantheon-opencode-*.tgz | head -1)
+npm rm -g pantheon-opencode 2>/dev/null || true
+npm install -g "$TGZ"
+
+echo "--- Init (headless) ---"
+pantheon-opencode init --headless -y
+
+echo "--- MCP List (V1) ---"
+opencode mcp list
+
+echo "--- MCP List (V2) ---"
+opencode2 mcp list
+
+echo "--- Doctor ---"
+pantheon-opencode doctor --target "$SANDBOX_DIR"
+
+echo "--- Gate (b): pantheon://agents CONTENT check ---"
+RESOURCES_SRV="$PANTHEON_GLOBAL/scripts/mcp_resources_server.py"
+if [ ! -f "$RESOURCES_SRV" ]; then
+  echo "ERROR: resources server not found at $RESOURCES_SRV"; exit 1
+fi
+AGENTS_CONTENT="$("$SANDBOX_VENV/bin/python" - "$RESOURCES_SRV" <<'PYEOF'
+import asyncio, importlib.util, sys
+spec = importlib.util.spec_from_file_location("mrs", sys.argv[1])
+mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+print(asyncio.run(mod.list_agents()))
+PYEOF
+)"
+printf '%s\n' "$AGENTS_CONTENT" | head -8
+if printf '%s\n' "$AGENTS_CONTENT" | grep -qi 'zeus' \
+  && printf '%s\n' "$AGENTS_CONTENT" | grep -qi 'hermes'; then
+  echo "OK: pantheon://agents content includes zeus and hermes"
+else
+  echo "ERROR: pantheon://agents content missing zeus/hermes (connectivity alone is not enough)"; exit 1
+fi
+
+echo ""
+echo "=== VALIDATION COMPLETE ==="
+echo "Next: open the isolated TUI with: $SANDBOX_DIR/start-pantheon.sh"
+RUNTEST
+  chmod +x "$SANDBOX_ROOT/run-test.sh"
+}
+
+# ── Reset / Prepare ───────────────────────────────────────────────────────────
+
+cmd_reset() {
+  case "$SANDBOX_ROOT" in
+    "/" | "$HOME" | "$REPO_DIR" | "$REPO_DIR"/*)
+      die "refusing to reset unsafe sandbox root: $SANDBOX_ROOT" ;;
+  esac
+  log "Resetting sandbox: $SANDBOX_ROOT"
+  rm -rf "$SANDBOX_ROOT"
+  log "Sandbox removed."
+}
+
+install_binaries() {
+  log "--- Installing pantheon-opencode (from repo tarball) ---"
+  cd "$REPO_DIR"
+  npm pack 2>/dev/null || die "npm pack failed"
+  local tgz
+  tgz=$(ls -t pantheon-opencode-*.tgz | head -1)
+  npm rm -g pantheon-opencode 2>/dev/null || true
+  npm install -g "$REPO_DIR/$tgz" || die "install of $tgz failed"
+  log "--- Installing OpenCode V1 ($OPENCODE_V1_SPEC) ---"
+  npm install -g "$OPENCODE_V1_SPEC" \
+    || warn "V1 binary install failed ($OPENCODE_V1_SPEC) — v1 prompts will be AMBIENTAL"
+  log "--- Installing OpenCode V2 ($OPENCODE_V2_SPEC) ---"
+  npm install -g "$OPENCODE_V2_SPEC" \
+    || warn "V2 binary install failed ($OPENCODE_V2_SPEC) — v2 prompts will be AMBIENTAL"
+}
+
+prepare_project() {
+  local v="$1" dir pan
+  dir="$(project_for "$v")"
+  mkdir -p "$dir"
+  pan="$(sandbox_bin_for "pantheon-opencode")" \
+    || die "pantheon-opencode not installed in sandbox prefix — run $0 --prepare first"
+  log "--- Regenerating config for $v in $dir ---"
+  (cd "$dir" && "$pan" init --project --version "$v" --model "$PANTHEON_SANDBOX_MODEL" -y) \
+    || die "init --project --version $v failed in $dir"
+}
+
+cmd_prepare() {
+  mkdir -p "$SANDBOX_HOME" "$NPM_PREFIX"
+  write_run_test_sh
+  sandbox_env
+  install_binaries
+  local pan
+  pan="$(sandbox_bin_for "pantheon-opencode")" \
+    || die "pantheon-opencode not found in sandbox prefix after install"
+  log "--- Headless init (global venv + runtime) ---"
+  "$pan" init --headless -y --model "$PANTHEON_SANDBOX_MODEL" \
+    || die "pantheon-opencode init --headless failed"
+  prepare_project v1
+  prepare_project v2
+  write_extract_py
+  log "Prepare complete. Sandbox: $SANDBOX_ROOT"
+  log "Next: $0 --run v1 --prompts  |  $0 --run v2 --prompts"
+}
+
+# ── JSON text extraction (schema-agnostic) ────────────────────────────────────
+
+write_extract_py() {
+  cat > "$EXTRACT_PY" <<'PYEOF'
+"""Collect every string value from opencode run --format json output."""
+import json
+import sys
+
+
+def walk(obj, out):
+    if isinstance(obj, str):
+        out.append(obj)
+    elif isinstance(obj, dict):
+        for value in obj.values():
+            walk(value, out)
+    elif isinstance(obj, list):
+        for value in obj:
+            walk(value, out)
+
+
+raw = sys.stdin.read()
+chunks = []
+try:
+    walk(json.loads(raw), chunks)
+except Exception:
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            walk(json.loads(line), chunks)
+        except Exception:
+            chunks.append(line)
+print("\n".join(chunks))
+PYEOF
+}
+
+# ── Prompt battery ────────────────────────────────────────────────────────────
+
+# Known environmental failure signatures (never fail the run).
+AMBIENTAL_RE='bifrost|unauthorized|authentication failure|api key|credentials|401|docker|econnrefused|enotfound|etimedout|econnreset|connection refused|rate.?limit|429|quota|overloaded|edgesout|npm err'
+
+PROMPT_IDS=()
+PROMPT_TEXTS=()
+PROMPT_MARKERS=()
+PROMPT_AMB_MARKERS=()
+PROMPT_VERIFY=()
+
+add_prompt() { # id marker ambiental_marker verify text
+  PROMPT_IDS+=("$1")
+  PROMPT_MARKERS+=("$2")
+  PROMPT_AMB_MARKERS+=("$3")
+  PROMPT_VERIFY+=("$4")
+  PROMPT_TEXTS+=("$5")
+}
+
+build_battery() {
+  local v="$1"
+  PROMPT_IDS=()
+  PROMPT_TEXTS=()
+  PROMPT_MARKERS=()
+  PROMPT_AMB_MARKERS=()
+  PROMPT_VERIFY=()
+  add_prompt "agents-resource" "AGENTS-OK" "AGENTS-MISSING" "" \
+    "List your MCP resources and read the resource pantheon://agents. If the returned agent list includes an agent named 'zeus' and one named 'hermes', reply with exactly: AGENTS-OK. Otherwise reply with exactly: AGENTS-MISSING."
+  add_prompt "memory-store" "MEMORY-STORE-OK" "" "" \
+    "Use the pantheon-memory memory_store tool to store this exact entry: namespace 'default', key 'pantheon-sandbox-probe-$v', value 'alive'. Then reply with exactly: MEMORY-STORE-OK"
+  add_prompt "memory-recall" "MEMORY-RECALL-OK" "" "" \
+    "Use the pantheon-memory memory_recall tool (or memory_search) to look up key 'pantheon-sandbox-probe-$v' in namespace 'default'. If the stored value is 'alive', reply with exactly: MEMORY-RECALL-OK"
+  add_prompt "tmp-write-read" "TMP-OK" "" \
+    "${TMPDIR:-/tmp}/pantheon-sandbox-probe-$v.txt::TMP-OK" \
+    "Using the bash tool, run a python3 -c command that writes the text TMP-OK to the file ${TMPDIR:-/tmp}/pantheon-sandbox-probe-$v.txt (overwrite it), then run another python3 -c command to read that file back. Do not use any other tool or command to write or read the file — only python3 -c. If what you read back is exactly TMP-OK, reply with exactly: TMP-OK"
+  add_prompt "delegation" "DELEGATION-OK" "DELEGATION-UNAVAILABLE" "" \
+    "Delegate a tiny task to the @talos agent via the task tool: ask it to reply with the single word PONG. If the delegated response contains PONG, reply with exactly: DELEGATION-OK. If you cannot delegate to agents in this context, reply with exactly: DELEGATION-UNAVAILABLE"
+}
+
+declare -A RESULTS
+declare -A DETAILS
+
+record() { # v id result detail
+  RESULTS["$1:$2"]="$3"
+  DETAILS["$1:$2"]="$4"
+}
+
+extract_text() { "$HOME/.config/opencode/.venv/bin/python" "$EXTRACT_PY" < "$1"; }
+
+ATTEMPT_RESULT=""
+ATTEMPT_DETAIL=""
+
+run_prompt_attempt() { # v idx current_bin — sets ATTEMPT_RESULT / ATTEMPT_DETAIL
+  local v="$1" idx="$2" bin="$3" id marker amb_marker verify text
+  id="${PROMPT_IDS[$idx]}"
+  marker="${PROMPT_MARKERS[$idx]}"
+  amb_marker="${PROMPT_AMB_MARKERS[$idx]}"
+  verify="${PROMPT_VERIFY[$idx]}"
+  text="${PROMPT_TEXTS[$idx]}"
+
+  # Remove the probe file first so post-run verification reflects THIS run.
+  if [ -n "$verify" ]; then
+    rm -f "${verify%%::*}"
+  fi
+
+  local out_file err_file rc=0
+  out_file="$(mktemp)"
+  err_file="$(mktemp)"
+
+  set +e
+  (cd "$(project_for "$v")" \
+    && timeout "$PANTHEON_PROMPT_TIMEOUT" "$bin" run --auto --format json "$text") \
+    > "$out_file" 2> "$err_file"
+  rc=$?
+  set -e
+
+  local extracted
+  extracted="$(extract_text "$out_file" || true)"
+  local raw
+  raw="$( { tr '\n' ' ' < "$out_file"; tr '\n' ' ' < "$err_file"; } | cut -c1-400)"
+  rm -f "$out_file" "$err_file"
+
+  if [ "$rc" -eq 124 ]; then
+    ATTEMPT_RESULT="AMBIENTAL"
+    ATTEMPT_DETAIL="timeout after ${PANTHEON_PROMPT_TIMEOUT}s (provider latency)"
+  elif printf '%s' "$extracted" | grep -q "$marker"; then
+    ATTEMPT_RESULT="PASS"
+    ATTEMPT_DETAIL="marker $marker found"
+  elif [ -n "$amb_marker" ] && printf '%s' "$extracted" | grep -q "$amb_marker"; then
+    ATTEMPT_RESULT="AMBIENTAL"
+    ATTEMPT_DETAIL="explicit $amb_marker"
+  elif [ -n "$verify" ] \
+    && [ "$(cat "${verify%%::*}" 2>/dev/null)" = "${verify##*::}" ]; then
+    ATTEMPT_RESULT="PASS"
+    ATTEMPT_DETAIL="probe file verified: ${verify%%::*} contains ${verify##*::}"
+  elif printf '%s' "$raw" | grep -Eiq "$AMBIENTAL_RE"; then
+    local sig
+    sig="$(printf '%s' "$raw" | grep -Eio "$AMBIENTAL_RE" | head -1)"
+    ATTEMPT_RESULT="AMBIENTAL"
+    ATTEMPT_DETAIL="environmental signature: $sig"
+  else
+    ATTEMPT_RESULT="FAIL"
+    ATTEMPT_DETAIL="marker $marker absent; rc=$rc; snippet: $(printf '%s' "$raw" | cut -c1-160)"
+  fi
+}
+
+RETRY_COOLDOWN="${PANTHEON_RETRY_COOLDOWN:-60}"
+RETRIES_USED=0
+
+run_prompt() { # v idx current_bin — ONE retry after cooldown for real FAIL only
+  local v="$1" idx="$2" bin="$3" id first_detail
+  id="${PROMPT_IDS[$idx]}"
+  run_prompt_attempt "$v" "$idx" "$bin"
+  if [ "$ATTEMPT_RESULT" = "FAIL" ]; then
+    first_detail="$ATTEMPT_DETAIL"
+    log "[$v] prompt $id FAIL on first attempt — retrying once after ${RETRY_COOLDOWN}s cooldown"
+    sleep "$RETRY_COOLDOWN"
+    run_prompt_attempt "$v" "$idx" "$bin"
+    RETRIES_USED=$((RETRIES_USED + 1))
+    if [ "$ATTEMPT_RESULT" != "FAIL" ]; then
+      ATTEMPT_DETAIL="$ATTEMPT_DETAIL [retry used — first attempt: $first_detail]"
+    else
+      ATTEMPT_DETAIL="$ATTEMPT_DETAIL [FAIL persisted after retry — first attempt: $first_detail]"
+    fi
+  fi
+  record "$v" "$id" "$ATTEMPT_RESULT" "$ATTEMPT_DETAIL"
+}
+
+check_mcp_list() { # v
+  local v="$1" bin out rc=0
+  if ! bin="$(sandbox_bin_v "$v")"; then
+    record "$v" "mcp-list" "AMBIENTAL" "binary not installed in sandbox prefix"
+    return 0
+  fi
+  set +e
+  out="$(cd "$(project_for "$v")" && "$bin" mcp list 2>&1)"
+  rc=$?
+  set -e
+  if [ "$rc" -ne 0 ]; then
+    record "$v" "mcp-list" "FAIL" "opencode mcp list exited $rc"
+  elif printf '%s' "$out" | grep -qi "connected" \
+    && ! printf '%s' "$out" | grep -Eiq "failed|✘"; then
+    record "$v" "mcp-list" "PASS" "$(printf '%s' "$out" | grep -ci 'connected') connected"
+  else
+    record "$v" "mcp-list" "FAIL" "no connected MCPs or failures reported"
+  fi
+}
+
+check_doctor() { # v
+  local v="$1" pan rc=0
+  if ! pan="$(sandbox_bin_for "pantheon-opencode")"; then
+    record "$v" "doctor" "AMBIENTAL" "pantheon-opencode not installed in sandbox prefix"
+    return 0
+  fi
+  set +e
+  (cd "$(project_for "$v")" && "$pan" doctor --target "$(project_for "$v")") > /dev/null 2>&1
+  rc=$?
+  set -e
+  if [ "$rc" -eq 0 ]; then
+    record "$v" "doctor" "PASS" "exit 0"
+  else
+    record "$v" "doctor" "FAIL" "doctor exited $rc (blocking errors)"
+  fi
+}
+
+run_version_prompts() { # v
+  local v="$1" bin
+  if ! bin="$(sandbox_bin_v "$v")"; then
+    log "Binary '$(bin_for "$v")' not in sandbox prefix — marking all $v prompts AMBIENTAL."
+    build_battery "$v"
+    local i
+    for i in "${!PROMPT_IDS[@]}"; do
+      record "$v" "${PROMPT_IDS[$i]}" "AMBIENTAL" "binary $(bin_for "$v") not installed in sandbox"
+    done
+    record "$v" "mcp-list" "AMBIENTAL" "binary $(bin_for "$v") not installed in sandbox"
+    record "$v" "doctor" "AMBIENTAL" "binary $(bin_for "$v") not installed in sandbox"
+    return 0
+  fi
+  prepare_project "$v"
+  build_battery "$v"
+  local i
+  for i in "${!PROMPT_IDS[@]}"; do
+    log "[$v] prompt ${PROMPT_IDS[$i]} ..."
+    run_prompt "$v" "$i" "$bin"
+    log "[$v] prompt ${PROMPT_IDS[$i]} → ${RESULTS["$v:${PROMPT_IDS[$i]}"]}"
+  done
+  check_mcp_list "$v"
+  check_doctor "$v"
+}
+
+write_report() { # versions...
+  local versions=("$@") total_fail=0 total_pass=0 total_amb=0
+  {
+    printf '# Pantheon Sandbox Prompts Report\n\n'
+    printf -- '- **Date:** %s\n' "$(date -u '+%Y-%m-%d %H:%M UTC')"
+    printf -- '- **Model:** %s\n' "$PANTHEON_SANDBOX_MODEL"
+    printf -- '- **Sandbox:** %s\n' "$SANDBOX_ROOT"
+    printf -- '- **V1 binary:** %s (%s) | **V2 binary:** %s (%s)\n\n' \
+      "$V1_BIN" "$OPENCODE_V1_SPEC" "$V2_BIN" "$OPENCODE_V2_SPEC"
+    local v id res
+    for v in "${versions[@]}"; do
+      printf '## Version %s (`%s`)\n\n' "$v" "$(bin_for "$v")"
+      printf '| Prompt | Result | Detail |\n|---|---|---|\n'
+      for id in "${PROMPT_IDS[@]}" mcp-list doctor; do
+        res="${RESULTS["$v:$id"]:-SKIP}"
+        case "$res" in
+          PASS) total_pass=$((total_pass + 1)) ;;
+          AMBIENTAL) total_amb=$((total_amb + 1)) ;;
+          FAIL) total_fail=$((total_fail + 1)) ;;
+        esac
+        printf '| %s | %s | %s |\n' "$id" "$res" "${DETAILS["$v:$id"]:-—}"
+      done
+      printf '\n'
+    done
+    printf '## Summary\n\n'
+    printf -- '- PASS: %d\n- FAIL (real): %d\n- AMBIENTAL: %d\n- Retries used: %d\n\n' \
+      "$total_pass" "$total_fail" "$total_amb" "$RETRIES_USED"
+    if [ "$total_fail" -eq 0 ]; then
+      printf '**Verdict: PASS** — no real failures (AMBIENTAL issues do not block).\n'
+    else
+      printf '**Verdict: FAIL** — real failures detected (see table above).\n'
+    fi
+  } > "$REPORT_FILE"
+  log "Report written to $REPORT_FILE"
+}
+
+run_battery() { # versions...
+  local versions=("$@")
+  mkdir -p "$SANDBOX_ROOT"
+  write_extract_py
+  local v
+  for v in "${versions[@]}"; do
+    run_version_prompts "$v"
+  done
+  write_report "${versions[@]}"
+  local v fail=0 id
+  for v in "${versions[@]}"; do
+    for id in "${PROMPT_IDS[@]}" mcp-list doctor; do
+      [ "${RESULTS["$v:$id"]:-}" = "FAIL" ] && fail=$((fail + 1)) || true
+    done
+  done
+  if [ "$fail" -gt 0 ]; then
+    log "Prompts battery: $fail real FAIL(s)."
+    exit 1
+  fi
+  log "Prompts battery: no real failures."
+}
+
+# ── Base validation (no prompts) ──────────────────────────────────────────────
+
+run_base() { # v
+  local v="$1" bin
+  if ! bin="$(sandbox_bin_v "$v")"; then
+    printf 'ERROR: sandbox not prepared for %s (binary '\''%s'\'' missing from sandbox prefix) — run %s --prepare first\n' \
+      "$v" "$(bin_for "$v")" "$0" >&2
+    exit 3
+  fi
+  prepare_project "$v"
+  build_battery "$v"
+  log "[$v] opencode mcp list"
+  check_mcp_list "$v"
+  log "[$v] mcp-list → ${RESULTS["$v:mcp-list"]}"
+  log "[$v] doctor"
+  check_doctor "$v"
+  log "[$v] doctor → ${RESULTS["$v:doctor"]}"
+  local fail=0
+  [ "${RESULTS["$v:mcp-list"]}" = "FAIL" ] && fail=$((fail + 1)) || true
+  [ "${RESULTS["$v:doctor"]}" = "FAIL" ] && fail=$((fail + 1)) || true
+  if [ "$fail" -gt 0 ]; then
+    log "Base validation $v: $fail real FAIL(s)."
+    exit 1
+  fi
+  log "Base validation $v: OK."
+}
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --prepare) MODE_PREPARE=1 ;;
+    --reset) MODE_RESET=1 ;;
+    --prompts) MODE_PROMPTS=1 ;;
+    --run)
+      shift
+      case "${1:-}" in
+        v1 | v2) RUN_VERSION="$1" ;;
+        *) usage ;;
+      esac
+      ;;
+    --help | -h) usage ;;
+    *) usage ;;
+  esac
+  shift
+done
+
+if [ "$MODE_RESET" -eq 1 ]; then
+  cmd_reset
+  exit 0
+fi
+
+if [ "$MODE_PREPARE" -eq 0 ] && [ -z "$RUN_VERSION" ] && [ "$MODE_PROMPTS" -eq 0 ]; then
+  usage
+fi
+
+if [ "$MODE_PREPARE" -eq 1 ]; then
+  cmd_prepare
+fi
+
+if [ -n "$RUN_VERSION" ]; then
+  if [ "$MODE_PROMPTS" -eq 1 ]; then
+    sandbox_env
+    run_battery "$RUN_VERSION"
+  else
+    sandbox_env
+    run_base "$RUN_VERSION"
+  fi
+elif [ "$MODE_PROMPTS" -eq 1 ]; then
+  sandbox_env
+  run_battery v1 v2
+fi