@giamme/forge 0.0.0-stage → 0.9.0

package/scripts/forge-dispatch.sh

@@ -0,0 +1,671 @@
+#!/usr/bin/env bash
+# forge-dispatch.sh — resolve a forge spec (alias[:effort[:harness]]) into a real
+# CLI invocation and run it. Harness-agnostic: needs only bash + coreutils, so it
+# behaves identically whether the orchestrator is codex, claude, openclaude or
+# opencode.
+#
+# Usage:
+#   forge-dispatch.sh doctor          (harnesses: codex claude openclaude opencode antigravity grok)
+#   forge-dispatch.sh dwarf <spec> --prompt-file <f> [--repo <dir>] [--run-dir <d>] [--yolo] [--dry-run]
+#   forge-dispatch.sh qa    <spec> --prompt-file <f> [--repo <dir>] [--run-dir <d>] [--yolo] [--dry-run]
+#                                  [--native-review [--review-base <ref>]]
+#   any role: [--no-ripwire] [--ripwire-query-file <requirements>]
+#   any role: [--timeout <seconds>]   0 disables the watchdog
+#
+# Timeout precedence: --timeout, then FORGE_TIMEOUT (both used as given, 0 included),
+#   then the registry row's optional 5th `timeout` column, then the built-in 2700 (45m).
+#   A registry or built-in value is scaled by the resolved effort: <= high x1,
+#   xhigh x4/3, max/ultra/ultracode x2. The limit and its source are recorded as
+#   `timeout=` / `timeout_source=` in $ROLE.resolved.
+#
+# Environment: FORGE_REGISTRY      alternate registry file (default: <skill>/registry.tsv)
+#              FORGE_ORPHAN_GUARD  off = do not run the harness in its own process group
+#                                  (default on; also skipped under FORGE_FRACTAL_RUN)
+#
+# Exit codes: 0 ok | 2 usage/resolution error | 3 harness missing or unusable
+#             4 backend ran but failed | 7 backend exceeded --timeout and was killed
+#             8 infrastructure failure (auth, quota, rate limit, network, or an empty
+#               answer): the model never got to do its work. $ROLE.infra says which.
+#               A DWARF that exits 0 with an empty final message also writes $ROLE.infra
+#               (class=empty) but still exits 0; consult the file only if the diff is empty.
+# A process still alive in the harness's group after it exited is killed and listed in
+# $ROLE.orphans (only written when there is something to list).
+set -uo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REGISTRY="${FORGE_REGISTRY:-$SKILL_DIR/registry.tsv}"
+RUNTIME="$SKILL_DIR/scripts/forge-runtime.py"
+GUARD="$SKILL_DIR/scripts/forge-guard.py"
+
+die()  { printf 'forge: %s\n' "$1" >&2; exit "${2:-2}"; }
+note() { printf 'forge: %s\n' "$*" >&2; }
+
+# --- effort ladders -----------------------------------------------------------
+# codex does NOT validate model_reasoning_effort: a typo runs at some silent
+# default instead of erroring. So forge validates before dispatch — a run at the
+# wrong effort is expensive and invisible, which is exactly the failure worth
+# spending ten lines to prevent.
+ladder_for() {
+  case "$1" in
+    codex)       echo "low medium high xhigh max ultra" ;;
+    claude)      echo "low medium high xhigh max" ;;
+    openclaude)  echo "low medium high xhigh max ultracode" ;;
+    antigravity) echo "low medium high" ;;
+    grok)        echo "low medium high xhigh max" ;;   # each model offers a subset (registry)
+    opencode)    echo "" ;;   # --variant is provider-specific; forwarded verbatim
+    *)           echo "" ;;
+  esac
+}
+
+# The harness name is not always the binary name.
+binary_for() {
+  case "$1" in antigravity) echo agy ;; *) echo "$1" ;; esac
+}
+
+# Every effort word forge recognizes, weakest first. Used only to tell "you asked
+# for more thinking than this pairing offers" (clamp, keep going) apart from "that
+# is not an effort level" (stop). ultra and ultracode are each their harness's top
+# tier under different names, so they rank together.
+CANON="low medium high xhigh max ultra ultracode"
+rank_of() {
+  case "$1" in
+    low) echo 0 ;; medium) echo 1 ;; high) echo 2 ;; xhigh) echo 3 ;;
+    max) echo 4 ;; ultra|ultracode) echo 5 ;; *) echo -1 ;;
+  esac
+}
+
+idx_in() { # idx_in <needle> <space-separated haystack> -> index or -1
+  local n="$1" i=0 w
+  for w in $2; do [ "$w" = "$n" ] && { echo "$i"; return; }; i=$((i+1)); done
+  echo -1
+}
+
+# --- registry lookup ----------------------------------------------------------
+# The fourth and fifth fields print "-" when empty, because `IFS=$'\t' read` treats tab as
+# whitespace and would collapse an empty field into its neighbour.
+lookup() { # lookup <alias> [harness] -> "harness<TAB>model<TAB>ceiling<TAB>timeout"
+  local alias="$1" want="${2:-}"
+  awk -F'\t' -v a="$alias" -v h="$want" '
+    /^#/ || NF < 3 { next }
+    $1 == a && (h == "" || $2 == h) {
+      t = $5; gsub(/[ \t\r]+$/, "", t)
+      print $2 "\t" $3 "\t" ($4 == "" ? "-" : $4) "\t" (t == "" ? "-" : t); exit
+    }
+  ' "$REGISTRY"
+}
+
+known_harness() {
+  case "$1" in codex|claude|openclaude|opencode|antigravity|grok) return 0 ;; *) return 1 ;; esac
+}
+
+# --- doctor -------------------------------------------------------------------
+doctor() {
+  local rc=0 h bin
+  printf '%-12s %-10s %s\n' HARNESS STATUS DETAIL
+  for h in codex claude openclaude opencode antigravity grok; do
+    bin="$(command -v "$(binary_for "$h")" 2>/dev/null)"
+    if [ -z "$bin" ]; then
+      printf '%-12s %-10s %s\n' "$h" MISSING "$(binary_for "$h") not on PATH"; rc=1; continue
+    fi
+    printf '%-12s %-10s %s\n' "$h" "found" "$bin"
+  done
+  python3 "$SKILL_DIR/scripts/forge-ripwire.py" --doctor
+  cat <<'EOT'
+
+Binary presence is not reachability. A harness can be installed and still fail on
+auth or billing (opencode in particular fails this way), and that failure only
+shows up mid-dispatch. To prove a pairing end to end before spending a real run:
+
+  forge-dispatch.sh dwarf <spec> --prompt-file /dev/stdin --repo <scratch dir> \
+      <<< 'Reply with exactly: FORGE_OK'
+EOT
+  return $rc
+}
+
+[ $# -ge 1 ] || die "usage: forge-dispatch.sh <doctor|dwarf|qa|planner> [spec] [options]"
+ROLE="$1"; shift
+if [ "$ROLE" = report ]; then python3 "$RUNTIME" report "${1:?report needs a run directory}"; exit $?; fi
+PREFLIGHT=0
+if [ "$ROLE" = doctor ]; then
+  if [ $# = 0 ]; then doctor; exit $?; fi
+  [ "${1:-}" = --spec ] || die "doctor accepts --spec <spec> [--role dwarf|qa|planner]"
+  SPEC_CHECK="${2:?--spec needs a spec}"; shift 2
+  ROLE=dwarf
+  if [ "${1:-}" = --role ]; then ROLE="${2:?}"; shift 2; fi
+  PREFLIGHT=1
+  CHECK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/forge-doctor.XXXXXX")" || exit 3
+  trap 'rm -rf "$CHECK_DIR"' EXIT
+  echo 'Offline capability check' > "$CHECK_DIR/input"
+  set -- "$SPEC_CHECK" --run-dir "$CHECK_DIR" --prompt-file "$CHECK_DIR/input" "$@"
+fi
+case "$ROLE" in dwarf|qa|planner) ;; *) die "unknown role '$ROLE' (expected dwarf, qa, planner or doctor)" ;; esac
+
+# qa and planner both read the repo and write nothing to it: a reviewer that can
+# edit the diff is no longer an independent check of it, and a planner that edits
+# has quietly become the dwarf. They share one permission profile.
+read_only_role() { case "$ROLE" in qa|planner) return 0 ;; *) return 1 ;; esac; }
+[ $# -ge 1 ] || die "role '$ROLE' needs a spec, e.g. sol:xhigh:openclaude"
+SPEC="$1"; shift
+
+RIPWIRE_QUERY=""
+OUTPUT=full
+REPO="$PWD"; RUN_DIR=""; PROMPT_FILE=""; YOLO=0; DRY=0; REVIEW_BASE=""; PROMPT_VIA_STDIN=0; NATIVE_REVIEW=0; AGY_TIMEOUT="30m"; TIMEOUT_FLAG=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --no-ripwire) export FORGE_RIPWIRE=off; shift ;;
+    --ripwire-query-file) RIPWIRE_QUERY="${2:?}"; shift 2 ;;
+    --output) OUTPUT="${2:?}"; shift 2 ;;
+    --repo)         REPO="${2:?--repo needs a value}"; shift 2 ;;
+    --run-dir)      RUN_DIR="${2:?--run-dir needs a value}"; shift 2 ;;
+    --prompt-file)  PROMPT_FILE="${2:?--prompt-file needs a value}"; shift 2 ;;
+    --review-base)  REVIEW_BASE="${2:?--review-base needs a value}"; shift 2 ;;
+    --native-review) NATIVE_REVIEW=1; shift ;;
+    --agy-timeout)  AGY_TIMEOUT="${2:?--agy-timeout needs a value}"; shift 2 ;;
+    --timeout)      TIMEOUT_FLAG="${2:?--timeout needs a value in seconds, 0 to disable}"; shift 2 ;;
+    --yolo)         YOLO=1; shift ;;
+    --dry-run)      DRY=1; shift ;;
+    *)              die "unknown option '$1'" ;;
+  esac
+done
+
+case "$OUTPUT" in summary|full) ;; *) die "--output must be summary or full" ;; esac
+# Where the limit comes from is part of the record, so --timeout and FORGE_TIMEOUT are kept
+# apart from the registry and built-in values instead of being folded into one variable.
+case "$TIMEOUT_FLAG" in *[!0-9]*) die "--timeout must be a nonnegative integer" ;; esac
+case "${FORGE_TIMEOUT:-}" in *[!0-9]*) die "FORGE_TIMEOUT must be a nonnegative integer" ;; esac
+[ -z "${FORGE_REGISTRY:-}" ] || [ -f "$REGISTRY" ] || die "FORGE_REGISTRY '$REGISTRY' is not a file"
+
+# --- resolve spec -------------------------------------------------------------
+ALIAS="${SPEC%%:*}"; REST="${SPEC#*:}"
+if [ "$REST" = "$SPEC" ]; then EFFORT=""; HARNESS=""
+else
+  EFFORT="${REST%%:*}"; H="${REST#*:}"
+  if [ "$H" = "$REST" ]; then HARNESS=""; else HARNESS="$H"; fi
+fi
+[ -n "$ALIAS" ] || die "empty alias in spec '$SPEC'"
+[ -z "$HARNESS" ] || known_harness "$HARNESS" \
+  || die "unknown harness '$HARNESS' (expected codex, claude, openclaude, opencode, antigravity or grok)"
+
+ROW="$(lookup "$ALIAS" "$HARNESS")"
+REG_TIMEOUT="-"
+if [ -n "$ROW" ]; then
+  IFS=$'\t' read -r HARNESS MODEL CEILING REG_TIMEOUT <<< "$ROW"
+  PASSTHRU=0
+else
+  # Not in the registry. Treat the alias as a literal model id — but only with an
+  # explicit harness, because there is no sane default for a model forge has
+  # never seen, and guessing wrong burns a real dispatch.
+  [ -n "$HARNESS" ] || die "'$ALIAS' is not a known alias. Either add it to $REGISTRY or name the harness explicitly, e.g. --dwarf $ALIAS:high:opencode"
+  if [ -n "$(awk -F'\t' -v a="$ALIAS" '!/^#/ && $1 == a {print; exit}' "$REGISTRY")" ]; then
+    note "alias '$ALIAS' has no row for harness '$HARNESS' — using it as a literal model id"
+  else
+    note "'$ALIAS' is not in the registry — using it as a literal model id on $HARNESS"
+  fi
+  MODEL="$ALIAS"; CEILING="-"; PASSTHRU=1
+fi
+
+if [ "$NATIVE_REVIEW" = 1 ] && { [ "$ROLE" != qa ] || [ "$HARNESS" != codex ]; }; then
+  die "--native-review requires QA on codex"
+fi
+
+# --- resolve effort -----------------------------------------------------------
+LADDER="$(ladder_for "$HARNESS")"
+CLAMPED=""; NO_EFFORT=0
+
+# Expand the registry's effort column into the concrete set this pairing accepts.
+# The four forms exist because real backends differ in more than a ceiling: some
+# models offer low and high but no medium, and some take no effort flag at all.
+ALLOWED=""
+case "$CEILING" in
+  "-")    ALLOWED="" ;;                       # forwarded verbatim, no validation
+  none)   NO_EFFORT=1 ;;
+  "<="*)  top="${CEILING#<=}"
+          for w in $LADDER; do ALLOWED="$ALLOWED $w"; [ "$w" = "$top" ] && break; done ;;
+  *)      ALLOWED="$(printf '%s' "$CEILING" | tr ',' ' ')" ;;
+esac
+
+if [ "$NO_EFFORT" = 1 ]; then
+  # Not a clamp to report: this model has no effort dial, so an effort the user
+  # typed is simply inapplicable. Say so once rather than failing the dispatch.
+  [ -n "$EFFORT" ] && note "$MODEL on $HARNESS takes no effort setting — ignoring ':$EFFORT'"
+  EFFORT=""
+else
+  if [ -z "$EFFORT" ]; then
+    # Build at medium, review high: a reviewer that thinks less than the
+    # implementer tends to rubber-stamp, which defeats the point of a second model.
+    # Planning is the stage where thinking pays for itself most cheaply — a bad
+    # plan is executed at full cost by every dwarf downstream of it.
+    case "$ROLE" in dwarf) EFFORT="medium" ;; qa|planner) EFFORT="xhigh" ;; esac
+    DEFAULTED=1
+    [ -n "$LADDER" ] || EFFORT=""   # opencode: no ladder, let the provider choose
+  else
+    DEFAULTED=0
+  fi
+
+  if [ -n "$EFFORT" ] && [ -n "$ALLOWED" ]; then
+    if [ "$(idx_in "$EFFORT" "$ALLOWED")" -lt 0 ]; then
+      want="$(rank_of "$EFFORT")"
+      [ "$want" -ge 0 ] || die "'$EFFORT' is not a recognized effort (known: $CANON)"
+      # Step down to the strongest accepted effort at or below what was asked;
+      # if even the weakest is stronger, take that. Asking for more thinking than
+      # a model offers should cost you thinking, not the whole run.
+      pick=""
+      for w in $ALLOWED; do
+        r="$(rank_of "$w")"
+        [ "$r" -le "$want" ] && pick="$w"
+      done
+      if [ -z "$pick" ]; then for w in $ALLOWED; do pick="$w"; break; done; fi
+      [ "$DEFAULTED" = 1 ] || CLAMPED="$EFFORT -> $pick"
+      EFFORT="$pick"
+    fi
+  fi
+fi
+
+if [ -n "$EFFORT" ] && [ -n "$LADDER" ] && [ "$(idx_in "$EFFORT" "$LADDER")" -lt 0 ]; then
+  die "invalid effort '$EFFORT' for $HARNESS"
+fi
+
+# --- resolve timeout ----------------------------------------------------------
+# Explicit (--timeout, FORGE_TIMEOUT) wins as given, including 0. Otherwise the registry
+# row's `timeout` column, then 2700. Only those two defaults scale with the resolved
+# effort, because an xhigh/max run is expected to think for longer; a number the caller
+# typed is never second-guessed.
+if [ -n "$TIMEOUT_FLAG" ]; then LIMIT="$TIMEOUT_FLAG"; LIMIT_SOURCE=explicit
+elif [ -n "${FORGE_TIMEOUT:-}" ]; then LIMIT="$FORGE_TIMEOUT"; LIMIT_SOURCE=env
+elif [ "$REG_TIMEOUT" != "-" ]; then
+  case "$REG_TIMEOUT" in ''|*[!0-9]*) die "registry timeout '$REG_TIMEOUT' for $ALIAS on $HARNESS is not a nonnegative integer ($REGISTRY)" ;; esac
+  LIMIT="$REG_TIMEOUT"; LIMIT_SOURCE=registry
+else LIMIT=2700; LIMIT_SOURCE=default
+fi
+# Normalize ("007" -> 7) so arithmetic is not read as octal and "00" really means off.
+[ "${#LIMIT}" -gt 9 ] || LIMIT=$((10#$LIMIT))
+if [ "$LIMIT_SOURCE" = registry ] || [ "$LIMIT_SOURCE" = default ]; then
+  if [ "$LIMIT" != 0 ] && [ "${#LIMIT}" -le 9 ]; then
+    effort_rank=-1; [ -z "$EFFORT" ] || effort_rank="$(rank_of "$EFFORT")"
+    if [ "$effort_rank" -ge 4 ]; then LIMIT=$((LIMIT * 2)); LIMIT_SOURCE="$LIMIT_SOURCE+effort-scaled"
+    elif [ "$effort_rank" -eq 3 ]; then LIMIT=$((LIMIT * 4 / 3)); LIMIT_SOURCE="$LIMIT_SOURCE+effort-scaled"
+    fi
+  fi
+fi
+
+# --- run dir & prompt ---------------------------------------------------------
+[ -d "$REPO" ] || die "--repo '$REPO' is not a directory"
+REPO="$(cd "$REPO" && pwd)"
+if [ -z "$RUN_DIR" ]; then
+  RUN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/forge-XXXXXX")" || die "could not create run dir"
+fi
+mkdir -p "$RUN_DIR" || die "could not create run dir '$RUN_DIR'"
+RUN_DIR="$(cd "$RUN_DIR" && pwd)"   # normalize, so the containment check below is real
+# The run dir deliberately lives outside the repo: anything forge writes inside
+# the working tree would show up in the dwarf's own diff and pollute QA's input.
+case "$RUN_DIR" in "$REPO"|"$REPO"/*) die "--run-dir must be outside --repo, or it lands in the diff under review" ;; esac
+
+# Start an immutable attempt record before preparation, including failures.
+ATTEMPT=""
+if [ "$PREFLIGHT" != 1 ] && [ "$DRY" != 1 ]; then
+  ATTEMPT="$(python3 "$RUNTIME" begin "$RUN_DIR" "$ROLE")" || exit 3
+  rm -f "$RUN_DIR/$ROLE.last" "$RUN_DIR/$ROLE.log" "$RUN_DIR/$ROLE.resolved" "$RUN_DIR/$ROLE.cmd" "$RUN_DIR/$ROLE.timedout" "$RUN_DIR/$ROLE.infra" "$RUN_DIR/$ROLE.orphans"
+  trap 'exit 143' TERM
+  trap 'exit 130' INT
+  # GUARD_ON is 1 only when the harness was started in its own process group (see the
+  # launch below), in which case $hpid is also the group id and the whole group is
+  # signalled. Every wait here is bounded: this runs on the way out of an interrupted
+  # dispatch and must not be the thing that hangs it.
+  exit_cleanup() {
+    if [ -n "${hpid:-}" ] && kill -0 "$hpid" 2>/dev/null; then
+      [ "${GUARD_ON:-0}" != 1 ] || kill -s TERM -- "-$hpid" 2>/dev/null
+      pkill -TERM -P "$hpid" 2>/dev/null; kill -TERM "$hpid" 2>/dev/null
+      if [ "${GUARD_ON:-0}" = 1 ]; then sleep 1; kill -s KILL -- "-$hpid" 2>/dev/null; fi
+    elif [ "${GUARD_ON:-0}" = 1 ] && [ "${reaped:-0}" != 1 ] && [ -n "${hpid:-}" ]; then
+      # Interrupted after the harness exited but before the normal reap.
+      python3 "$GUARD" reap "$hpid" "$RUN_DIR/$ROLE.orphans" >/dev/null 2>&1
+    fi
+    if [ -n "${wpid:-}" ]; then pkill -P "$wpid" 2>/dev/null; kill "$wpid" 2>/dev/null; fi
+  }
+  trap 'result=$?; exit_cleanup; python3 "$RUNTIME" finish "$ATTEMPT" "$RUN_DIR" "$ROLE" "$HARNESS" "$result"; exit "$result"' EXIT
+fi
+[ -n "$PROMPT_FILE" ] || die "role '$ROLE' needs --prompt-file"
+case "$PROMPT_FILE" in -|/dev/stdin) cat > "$RUN_DIR/$ROLE.prompt" ;;
+  *) [ -r "$PROMPT_FILE" ] || die "cannot read --prompt-file '$PROMPT_FILE'"
+     if [ "$PROMPT_FILE" != "$RUN_DIR/$ROLE.prompt" ]; then
+       prompt_copy="$(mktemp "$RUN_DIR/.prompt.XXXXXX")" || die "cannot create prompt copy"
+       cat "$PROMPT_FILE" > "$prompt_copy" || { rm -f "$prompt_copy"; die "cannot materialize prompt"; }
+       mv "$prompt_copy" "$RUN_DIR/$ROLE.prompt" || die "cannot install prompt copy"
+     fi ;;
+esac
+# Reusing the delivered prompt must not accumulate advisory sections or constraints.
+if [ -f "$RUN_DIR/$ROLE.delivered" ] && cmp -s "$RUN_DIR/$ROLE.prompt" "$RUN_DIR/$ROLE.delivered"; then
+  cp "$RUN_DIR/$ROLE.original" "$RUN_DIR/$ROLE.prompt"
+fi
+cp "$RUN_DIR/$ROLE.prompt" "$RUN_DIR/$ROLE.original"
+[ -n "$RIPWIRE_QUERY" ] || RIPWIRE_QUERY="$RUN_DIR/$ROLE.original"
+PROMPT_FILE="$RUN_DIR/$ROLE.prompt"
+[ -z "$ATTEMPT" ] || touch "$ATTEMPT/prompt.ready"
+# Streaming POSIX character class, using the caller's locale as Bash did.
+grep -q '[^[:space:]]' "$PROMPT_FILE" || die "prompt file '$PROMPT_FILE' is empty"
+PROMPT=""
+
+LAST="$RUN_DIR/$ROLE.last"
+LOG="$RUN_DIR/$ROLE.log"
+
+# Some harnesses cannot do things the standard role prompt asks for. Telling the
+# model up front beats letting it discover the wall mid-run: on antigravity a
+# denied command does not degrade gracefully, it aborts the whole dispatch, so a
+# dwarf that dutifully tries to run the test suite ends with an error and an
+# empty diff after burning the full quota.
+CONSTRAINT=""
+if [ "$HARNESS" = "antigravity" ] && [ "$YOLO" != 1 ]; then
+  CONSTRAINT="This environment cannot run terminal commands: permission is denied for every
+shell command, and a single attempt aborts this run entirely. Do not try to run tests,
+linters, git, or any other command. Verify your work by reading the code instead, and say
+plainly in your final message that it is unverified by execution."
+fi
+if [ -n "$CONSTRAINT" ]; then
+  printf '\n%s\n' "$CONSTRAINT" >> "$RUN_DIR/$ROLE.prompt"
+  PROMPT="$(cat "$RUN_DIR/$ROLE.prompt")"
+  PROMPT_FILE="$RUN_DIR/$ROLE.prompt"
+  note "antigravity without --yolo cannot run commands; told the $ROLE not to try"
+fi
+
+if [ -n "$ATTEMPT" ]; then
+  python3 "$SKILL_DIR/scripts/forge-ripwire.py" --repo "$REPO" --role "$ROLE" \
+    --prompt "$PROMPT_FILE" --query "$RIPWIRE_QUERY" --baseline "$REVIEW_BASE" \
+    --artifacts "$ATTEMPT" --native "$NATIVE_REVIEW" || note "Ripwire preparation failed; continuing"
+fi
+cp "$PROMPT_FILE" "$RUN_DIR/$ROLE.delivered"
+case "$HARNESS" in opencode|antigravity) PROMPT="$(cat "$PROMPT_FILE")" ;; esac
+
+# --- build argv ---------------------------------------------------------------
+CMD=()
+case "$HARNESS" in
+  codex)
+    if [ "$ROLE" = "qa" ] && [ "$NATIVE_REVIEW" = 1 ]; then
+      # codex's built-in reviewer. Its scope flags are mutually exclusive with a
+      # custom PROMPT, so this mode trades away the goal context: it can judge
+      # whether the diff is correct, but not whether it is the change that was
+      # actually asked for. `codex exec review` also has no --cd, hence the
+      # subshell cd below.
+      CMD=(codex exec review --json -m "$MODEL" --skip-git-repo-check -o "$LAST")
+      [ -n "$EFFORT" ] && CMD+=(-c "model_reasoning_effort=$EFFORT")
+      if [ -n "$REVIEW_BASE" ]; then CMD+=(--base "$REVIEW_BASE"); else CMD+=(--uncommitted); fi
+      if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-bypass-approvals-and-sandbox); fi
+    else
+      CMD=(codex exec --json -m "$MODEL" -C "$REPO" --skip-git-repo-check -o "$LAST")
+      [ -n "$EFFORT" ] && CMD+=(-c "model_reasoning_effort=$EFFORT")
+      # --approve-for-me and --dangerously-bypass-... are mutually exclusive.
+      if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-bypass-approvals-and-sandbox)
+      elif [ "$ROLE" = "dwarf" ]; then CMD+=(--approve-for-me)
+      else CMD+=(-s read-only); fi
+      CMD+=(-)
+      PROMPT_VIA_STDIN=1
+    fi
+    ;;
+  claude|openclaude)
+    # The run dir sits outside the repo (so it stays out of the diff), which also
+    # puts it outside the harness's default reach — without this the agent
+    # refuses to open the very artifacts forge just wrote for it.
+    CMD=("$HARNESS" -p --model "$MODEL" --add-dir "$RUN_DIR")
+    # One JSON message per line: what the agent said and every tool call, so the run keeps
+    # its conversation (forge-ui reads it), ending in the `result` line forge-runtime.py
+    # takes the final message and the tokens from. stream-json needs --verbose with -p.
+    CMD+=(--output-format stream-json --verbose)
+    [ -n "$EFFORT" ] && CMD+=(--effort "$EFFORT")
+    if [ "$YOLO" = 1 ]; then
+      CMD+=(--dangerously-skip-permissions)
+    else
+      # `acceptEdits`, not `auto`. Re-measured against this machine's CLIs:
+      # acceptEdits allows both Edit and Bash, whereas `auto` allows Bash but
+      # still prompts for Edit — and a headless dwarf has nobody to answer that
+      # prompt, so it ends with "I need your permission to edit f.py" and an
+      # empty diff. The failure is silent: the harness exits 0 and forge sees a
+      # successful run that changed nothing.
+      CMD+=(--permission-mode acceptEdits)
+      # Neither mode alone is enough, and the gap is silent in both directions:
+      # `auto` allows shell but prompts for Edit, so a dwarf ends with "I need
+      # your permission to edit" and an empty diff; `acceptEdits` allows Edit but
+      # still prompts for any non-trivial shell command, so a dwarf writes code
+      # and then stalls on "awaiting approval to run pytest" without ever
+      # verifying it. acceptEdits plus an explicit Bash allowance gives both, and
+      # QA's --disallowed-tools below still overrides the edit permission.
+      CMD+=(--allowedTools "Bash")
+      # Disable editing tools as defense in depth. Bash can still write files;
+      # runners use disposable snapshots and fingerprint checks for acceptance.
+      read_only_role && CMD+=(--disallowed-tools "Edit,Write,NotebookEdit")
+    fi
+    # The prompt goes on stdin, not argv. --disallowed-tools and friends are
+    # variadic, so any positional after them is silently eaten as another tool
+    # name — the run then dies on "Input must be provided" if you are lucky, or
+    # reviews nothing at all if you are not. stdin also lifts the argv length
+    # limit, which a long goal plus an inlined diff will otherwise hit.
+    PROMPT_VIA_STDIN=1
+    ;;
+  opencode)
+    CMD=(opencode run -m "$MODEL" --dir "$REPO")
+    [ -n "$EFFORT" ] && CMD+=(--variant "$EFFORT")
+    # opencode run exposes no sandbox tier — without --auto it blocks on a
+    # permission prompt that nothing can answer headlessly, so it is always set.
+    CMD+=(--auto)
+    read_only_role && [ "$YOLO" != 1 ] && CMD+=(--agent plan)
+    # One JSON event per line (text, tool_use, step_finish, error): the conversation, the
+    # final message and the tokens, read by forge-runtime.py and forge-ui.
+    CMD+=(--format json)
+    CMD+=("$PROMPT")
+    ;;
+  antigravity)
+    # `agy --print` is a Go flag with an OPTIONAL value: written detached it eats
+    # whatever token follows as its prompt ("--print took --print-timeout as its
+    # prompt"). The attached --print=... form is the only safe spelling, and it
+    # goes last so nothing can be captured after it.
+    CMD=(agy --model "$MODEL" --print-timeout "$AGY_TIMEOUT")
+    [ -n "$EFFORT" ] && CMD+=(--effort "$EFFORT")
+    # --add-dir on the repo is not optional. Antigravity is workspace-scoped
+    # rather than cwd-scoped, so without it the agent searches the wrong tree and
+    # the run dies on "Find command timed out: context deadline exceeded".
+    CMD+=(--add-dir "$REPO" --add-dir "$RUN_DIR")
+    if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-skip-permissions)
+    elif read_only_role; then CMD+=(--mode plan)
+    else CMD+=(--mode accept-edits); fi
+    CMD+=(--print="$PROMPT")
+    ;;
+  grok)
+    # Headless grok refuses any tool call that needs approval and still exits 0
+    # ("permission required: Edit calc.py was not run"): the same silent empty diff
+    # claude gives without acceptEdits, so the dwarf gets edits and the whole shell.
+    # The Messages-format stream ends in a claude-shaped `result` line, which
+    # forge-runtime.py reads for the final message and the tokens.
+    CMD=(grok --model "$MODEL" --prompt-file "$PROMPT_FILE" --output-format streaming-messages-json)
+    [ -n "$EFFORT" ] && CMD+=(--reasoning-effort "$EFFORT")
+    if [ "$YOLO" = 1 ]; then
+      CMD+=(--always-approve)
+    else
+      CMD+=(--permission-mode acceptEdits --allow Bash)
+      # A deny rule beats the mode and every allow, so a reviewer keeps its shell for
+      # running tests but cannot edit. Bash can still write files, as with claude.
+      read_only_role && CMD+=(--deny Edit --deny Write)
+    fi
+    ;;
+  *) die "no dispatch recipe for harness '$HARNESS'" ;;
+esac
+
+# Offline validation uses the exact command recipe, never a model request.
+preflight_command() {
+  local bin help arg flag
+  local help_args=(--help)
+  bin="$(command -v "$(binary_for "$HARNESS")")" || die "harness '$HARNESS' is not installed" 3
+  case "$HARNESS" in
+    codex) help_args=(exec --help); [ "$NATIVE_REVIEW" = 1 ] && help_args=(exec review --help) ;;
+    opencode) help_args=(run --help) ;;
+  esac
+  help="$(python3 "$RUNTIME" help "${FORGE_CAPABILITY_CACHE:-$RUN_DIR/capabilities}" "$REGISTRY" "${BASH_SOURCE[0]}" "$bin" "${help_args[@]}")" || die "cannot read $HARNESS help" 3
+  for arg in "${CMD[@]:1}"; do
+    [ "$arg" = "$PROMPT" ] && continue
+    [ "$arg" = - ] && continue
+    case "$arg" in
+      -*) flag="${arg%%=*}"
+          printf '%s\n' "$help" | grep -E -- "(^|[[:space:],|])$flag([=[:space:],|]|$)" >/dev/null || die "$HARNESS does not advertise required flag $flag" 3 ;;
+    esac
+  done
+}
+[ -z "$ATTEMPT" ] || python3 "$RUNTIME" phase "$ATTEMPT" preflight
+if [ "$DRY" != 1 ] || [ "$PREFLIGHT" = 1 ]; then preflight_command; fi
+
+# --- report the resolution ----------------------------------------------------
+{
+  echo "role=$ROLE"
+  echo "alias=$ALIAS"
+  echo "harness=$HARNESS"
+  echo "model=$MODEL"
+  echo "effort=${EFFORT:-<harness default>}"
+  echo "yolo=$([ "$YOLO" = 1 ] && echo ON || echo off)"
+  echo "passthrough=$([ "$PASSTHRU" = 1 ] && echo yes || echo no)"
+  [ -n "$CLAMPED" ] && echo "clamped=$CLAMPED"
+  echo "timeout=$LIMIT"
+  echo "timeout_source=$LIMIT_SOURCE"
+  # Native review ignores the assembled prompt, so whether it reached the model is a fact
+  # worth recording rather than inferring from the role and harness later.
+  echo "delivery=$([ "$NATIVE_REVIEW" = 1 ] && echo native_review || echo custom)"
+  echo "repo=$REPO"
+  echo "run_dir=$RUN_DIR"
+} | tee "$RUN_DIR/$ROLE.resolved"
+
+if [ "$PREFLIGHT" = 1 ]; then
+  echo "offline preflight passed; authentication, quota and live model availability unverified"
+  exit 0
+fi
+printf '%q ' "${CMD[@]}" > "$RUN_DIR/$ROLE.cmd"; echo >> "$RUN_DIR/$ROLE.cmd"
+if [ "$DRY" = 1 ]; then
+  echo "--- dry run, command not executed ---"
+  cat "$RUN_DIR/$ROLE.cmd"
+  [ "$PROMPT_VIA_STDIN" = 1 ] && echo "  (prompt delivered on stdin from $PROMPT_FILE)"
+  exit 0
+fi
+
+if [ "$YOLO" = 1 ]; then
+  note "YOLO: $HARNESS runs with sandbox and approvals disabled in $REPO"
+fi
+[ -n "$(command -v "$(binary_for "$HARNESS")")" ] || die "harness '$HARNESS' is not installed ($(binary_for "$HARNESS") not on PATH)" 3
+
+# Harnesses that take the prompt on argv get stdin redirected from /dev/null:
+# codex exec otherwise blocks waiting to append piped input to the prompt, which
+# headless reads as a silent hang rather than an error.
+#
+# The harness runs in the background rather than through `| tee` so that its pid is
+# knowable and therefore killable. `exec` matters: it replaces the subshell with the
+# harness itself, so $hpid IS the backend process and not a shell that merely owns
+# it — otherwise a timeout would kill the wrapper and leave the real process running.
+# The cost is that the log is no longer echoed incrementally; it is printed whole at
+# the end, so anything reading this script's stdout sees the same bytes as before.
+# Clear the previous dispatch's artifacts. Only codex writes $LAST itself (-o);
+# every other harness relies on the copy-from-log fallback below, which is a no-op
+# when a stale $LAST is already there. That is harmless when each run gets a fresh
+# run-dir, and silently wrong for `forge-parallel.sh retry`, which reuses the task
+# directory — it would read the first attempt's result and never notice.
+rm -f "$LAST" "$LOG" "$RUN_DIR/$ROLE.timedout" "$RUN_DIR/$ROLE.infra" "$RUN_DIR/$ROLE.orphans"
+python3 "$RUNTIME" phase "$ATTEMPT" model
+t0="$(date +%s)"
+# Process-group guard. A dwarf that starts `npm test &` and ends its turn leaves that
+# process running after dispatch returns, mutating the tree under whoever reads it next.
+# forge-guard.py does setsid() and then exec()s the harness, so $! is still the harness
+# pid and is now also its group id; after the harness exits, anything left in the group is
+# reaped and listed. Off by kill switch, and under Fractal (which manages its own process
+# groups and would otherwise lose the ability to signal this one). If the helper cannot
+# even start, fall back to the plain exec: a guard failure must never cost the run.
+GUARD_ON=0; reaped=0
+case "${FORGE_ORPHAN_GUARD:-on}" in off|OFF|Off|0|no|false) ;; *)
+  if [ -z "${FORGE_FRACTAL_RUN:-}" ] && [ -r "$GUARD" ] && [ "$(python3 "$GUARD" ping 2>/dev/null)" = ok ]; then GUARD_ON=1; fi ;;
+esac
+RUNCMD=("${CMD[@]}")
+[ "$GUARD_ON" != 1 ] || RUNCMD=(python3 "$GUARD" session -- "${CMD[@]}")
+if [ "$PROMPT_VIA_STDIN" = 1 ]; then
+  ( cd "$REPO" && exec "${RUNCMD[@]}" < "$PROMPT_FILE" ) > "$LOG" 2>&1 &
+else
+  ( cd "$REPO" && exec "${RUNCMD[@]}" </dev/null ) > "$LOG" 2>&1 &
+fi
+hpid=$!
+
+# Watchdog. Only antigravity has a time bound of its own, and `timeout` is not
+# present on stock macOS, so without this a hung backend blocks forever — and under
+# forge-parallel's `xargs -P` one hung task silently stalls its whole wave. The
+# default is deliberately generous: killing a slow-but-working dwarf is its own
+# failure, so this is a backstop, not a scheduler.
+wpid=""
+if [ "${LIMIT:-0}" != "0" ]; then
+  (
+    sleep "$LIMIT"
+    kill -0 "$hpid" 2>/dev/null || exit 0
+    : > "$RUN_DIR/$ROLE.timedout"
+    # The whole process group first when the harness has its own (GUARD_ON), then
+    # children, then the process itself, then SIGKILL for a CLI that traps TERM and
+    # takes its time. Without the guard there is no group to signal as a unit.
+    [ "$GUARD_ON" != 1 ] || kill -s TERM -- "-$hpid" 2>/dev/null
+    pkill -TERM -P "$hpid" 2>/dev/null
+    kill -TERM "$hpid" 2>/dev/null
+    sleep 5
+    [ "$GUARD_ON" != 1 ] || kill -s KILL -- "-$hpid" 2>/dev/null
+    pkill -KILL -P "$hpid" 2>/dev/null
+    kill -KILL "$hpid" 2>/dev/null
+  ) >/dev/null 2>&1 &
+  wpid=$!
+fi
+
+wait "$hpid"; rc=$?
+if [ -n "$wpid" ]; then
+  # The watchdog is asleep in a child of its own; kill that too or it outlives the
+  # run as an orphan holding the timer.
+  pkill -P "$wpid" 2>/dev/null
+  kill "$wpid" 2>/dev/null
+  wait "$wpid" 2>/dev/null
+fi
+# Anything the harness left running in its group is an abandoned background job. Kill it
+# before reading the tree, and leave the list for the caller. Bounded (~3s) and advisory:
+# a reaper failure changes nothing about the exit code.
+if [ "$GUARD_ON" = 1 ]; then
+  orphans_found="$(python3 "$GUARD" reap "$hpid" "$RUN_DIR/$ROLE.orphans" 2>/dev/null)"
+  case "$orphans_found" in ''|*[!0-9]*|0) ;; *) note "$HARNESS left $orphans_found process(es) running after it exited; killed — see $RUN_DIR/$ROLE.orphans" ;; esac
+fi
+reaped=1
+python3 "$RUNTIME" phase "$ATTEMPT" finalization
+DURATION=$(( $(date +%s) - t0 ))
+echo "duration_s=$DURATION" >> "$RUN_DIR/$ROLE.resolved"
+[ "$OUTPUT" != full ] || cat "$LOG"
+[ "$OUTPUT" != summary ] || echo "forge: role=$ROLE backend_exit=$rc final=$LAST log=$LOG metrics=$ATTEMPT/metrics.json"
+if [ -f "$RUN_DIR/$ROLE.timedout" ]; then
+  note "$HARNESS exceeded the ${LIMIT}s timeout and was killed after ${DURATION}s — see $LOG"
+  exit 7
+fi
+# Infrastructure, not the model's work: auth, quota, rate limit, network, or an answer that
+# never arrived. Classified from the LOG because $LAST is only created later, by the EXIT
+# trap's `finish`. Any trouble running the classifier counts as "not infrastructure".
+INFRA="$(python3 "$RUNTIME" classify "$LOG" "$HARNESS" "$rc" "$LAST" "$ROLE" 2>/dev/null)" || INFRA=""
+if [ -n "$INFRA" ]; then
+  TAB=$'\t'
+  infra_class="${INFRA%%"$TAB"*}"; infra_rest="${INFRA#*"$TAB"}"
+  infra_after="${infra_rest%%"$TAB"*}"; infra_detail="${infra_rest#*"$TAB"}"
+  {
+    echo "class=$infra_class"
+    echo "retry_after=$infra_after"
+    echo "detail=$infra_detail"
+    echo "rc=$rc"
+    echo "role=$ROLE"
+    echo "harness=$HARNESS"
+    echo "model=$MODEL"
+  } > "$RUN_DIR/$ROLE.infra"
+  # A dwarf may legitimately finish with nothing to say when its work is the diff, so
+  # an empty message alone is recorded but is not a failure; the caller decides when
+  # the diff turns out to be empty too. Every other role has nothing but its message.
+  if [ "$rc" -eq 0 ] && [ "$infra_class" = empty ] && [ "$ROLE" = dwarf ]; then
+    note "$HARNESS finished with an empty final message — recorded in $RUN_DIR/$ROLE.infra"
+  elif [ "$rc" -eq 0 ] && [ "$infra_class" = cancelled ]; then
+    # The CLI stopped a working model: a dwarf's diff so far still goes to review, and a
+    # reviewer cut off before its verdict is UNKNOWN, which re-runs only the review.
+    note "$HARNESS cancelled the $ROLE before it finished: $infra_detail — recorded in $RUN_DIR/$ROLE.infra"
+  else
+    note "$HARNESS failed on infrastructure ($infra_class${infra_after:+, retry after ${infra_after}s}): $infra_detail — see $LOG"
+    exit 8
+  fi
+fi
+if [ "$rc" -ne 0 ]; then
+  note "$HARNESS exited $rc — see $LOG"
+  exit 4
+fi
+echo "forge: $ROLE done in ${DURATION}s -> $LAST" >&2