forge-orkes 0.50.1 → 0.55.0

package/template/.claude/hooks/forge-slice-runner.sh

@@ -0,0 +1,593 @@
+#!/usr/bin/env sh
+# forge-slice-runner — run a slice's phases headless, in fresh heads, files-only.
+#
+# Brief-R2 step 1. The runner is a LOOP, not a daemon (NFR-028): each invocation
+# reads the slice's phase list and, per phase, assembles a prompt FROM FILES ONLY
+# (the phase plan + every prior phase's phase-report.yml + a repo-state snippet —
+# NEVER a transcript or a --continue/session-resume of the prior phase), launches
+# a bounded fresh-context run in the slice worktree via FORGE_SLICE_LAUNCHER
+# (default `claude -p`), requires the phase to write a phase-report.yml, reads its
+# `verdict`, and advances. It is a DUMB DISPATCHER (Fork 3): it holds no
+# authoritative state — everything it knows is recomputable from files on disk, so
+# killing it mid-slice loses nothing. If it ever needs resident state or a
+# scheduler to work, that is a STOP-and-route-out signal, not a feature here.
+#
+#   forge-slice-runner.sh --slice <worktree> [--work-dir <dir>]
+#       [--config <config.yml>] [--schema <schema.json>]
+#       [--report-template <phase-report.yml>]
+#
+# Runner env prerequisite (real launcher only): the machine must export
+#   CLAUDE_CODE_OAUTH_TOKEN  (from `claude setup-token`)  — or ANTHROPIC_API_KEY.
+# Headless `claude -p` has no other credential in this app-brokered setup.
+#
+# stdout: a machine-readable summary line, last:
+#   SLICE_RESULT phases=<completed> touches=<operator-touches> last_ping=<name>
+# All human/progress logging goes to stderr.
+#
+# Pure POSIX sh — no arrays, no bashisms, dependency-free (NFR-026).
+set -eu
+
+# --- defaults ----------------------------------------------------------------
+WORKTREE=""
+WORK_DIR=""
+CONFIG=""
+SCHEMA=""
+REPORT_TEMPLATE=""
+LAUNCHER="${FORGE_SLICE_LAUNCHER:-claude}"   # the swappable launch seam
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null || echo "")"
+
+# --- parse args --------------------------------------------------------------
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --slice)           WORKTREE="${2:-}"; shift 2 ;;
+    --work-dir)        WORK_DIR="${2:-}"; shift 2 ;;
+    --config)          CONFIG="${2:-}"; shift 2 ;;
+    --schema)          SCHEMA="${2:-}"; shift 2 ;;
+    --report-template) REPORT_TEMPLATE="${2:-}"; shift 2 ;;
+    *) printf 'forge-slice-runner: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$WORKTREE" ] || { printf 'forge-slice-runner: --slice <worktree> is required\n' >&2; exit 2; }
+[ -d "$WORKTREE" ] || { printf 'forge-slice-runner: slice worktree not found: %s\n' "$WORKTREE" >&2; exit 2; }
+WORKTREE="$(cd "$WORKTREE" && pwd)"                       # absolutize (we cd into it to launch)
+
+# Sensible defaults resolved against the slice / repo.
+[ -n "$WORK_DIR" ]        || WORK_DIR="$WORKTREE/.forge/runner-work"
+[ -n "$CONFIG" ]          || CONFIG="${REPO_ROOT:+$REPO_ROOT/}.forge/templates/slice-runner/config.yml"
+[ -n "$SCHEMA" ]          || SCHEMA="${REPO_ROOT:+$REPO_ROOT/}.forge/templates/slice-runner/phase-report.schema.json"
+[ -n "$REPORT_TEMPLATE" ] || REPORT_TEMPLATE="${REPO_ROOT:+$REPO_ROOT/}.forge/templates/slice-runner/phase-report.yml"
+mkdir -p "$WORK_DIR"
+WORK_DIR="$(cd "$WORK_DIR" && pwd)"
+PING_DIR="$WORK_DIR/pings"                                # append-once ping markers (dedup across re-runs)
+
+# --- config (flat key: value — grep/sed, no YAML lib) ------------------------
+cfg_get() {
+  # cfg_get <key> <default>
+  _v=""
+  [ -f "$CONFIG" ] && _v="$(grep -E "^$1:" "$CONFIG" 2>/dev/null | head -1 | sed -E "s/^$1:[[:space:]]*//; s/[[:space:]]*(#.*)?$//")"
+  [ -n "$_v" ] && printf '%s' "$_v" || printf '%s' "$2"
+}
+MAX_TURNS="$(cfg_get max_turns_per_phase 60)"
+# per-phase budget cap: bounded by the per-slice cap for now. A per-phase
+# --max-budget-usd <= the slice cap.
+MAX_BUDGET="$(cfg_get per_slice_budget_usd 25)"
+# per-SLICE budget cap (plan-47 task 2): the runner accumulates usage.cost_usd
+# across phase reports and parks with a §8.4 `budget` ping when the running total
+# breaches this. Same config key as the per-phase bound (the cap IS the slice cap);
+# the accumulation is what makes it a slice-level guard, not a phase-level one.
+SLICE_BUDGET="$(cfg_get per_slice_budget_usd 25)"
+# phase-boundary refresh + divergence budget (plan-03).
+INT_BRANCH="$(cfg_get integration_branch main)"
+DIV_BUDGET_COMMITS="$(cfg_get divergence_budget_commits 40)"
+DIV_BUDGET_LINES="$(cfg_get divergence_budget_lines 4000)"
+# FORGE_SLICE_REFRESH=off disables the whole phase-boundary refresh — the neg
+# control the refresh fixtures assert against, and a kill switch if a slice must
+# run without integrating main.
+REFRESH_MAIN="${FORGE_SLICE_REFRESH:-on}"
+
+# --- read the phase list (POSIX awk over `phases:` block) --------------------
+slice_manifest="$WORKTREE/slice.yml"
+[ -f "$slice_manifest" ] || { printf 'forge-slice-runner: no slice.yml in %s\n' "$WORKTREE" >&2; exit 2; }
+PHASES="$(awk '
+  /^phases:/ {f=1; next}
+  f && /^[[:space:]]*-[[:space:]]/ {sub(/^[[:space:]]*-[[:space:]]*/,""); print; next}
+  f && /^[^[:space:]-]/ {f=0}
+' "$slice_manifest")"
+[ -n "$PHASES" ] || { printf 'forge-slice-runner: slice.yml lists no phases\n' >&2; exit 2; }
+
+# --- report readers (grep/sed, dependency-free) ------------------------------
+report_field() {  # report_field <file> <key> — a TOP-LEVEL `key:` (col 0)
+  grep -E "^$2:" "$1" 2>/dev/null | head -1 | sed -E "s/^$2:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^\"//; s/\"$//"
+}
+report_nested() {  # report_nested <file> <key> — an INDENTED `key:` (checks.*/usage.*)
+  # The report nests checks.failed and usage.model under their parent block;
+  # report_field's `^key:` anchor can't see them. Each nested key we read
+  # (checks.failed; usage.model as a fallback in model_for_phase) is unique in the
+  # file, so a plain indented grep is enough. NOTE: usage.cost_usd/tokens are NO
+  # longer read from the report — the authoritative numbers come from the launcher's
+  # result.json (see result_num), because a phase can't know its own usage.
+  grep -E "^[[:space:]]+$2:" "$1" 2>/dev/null | head -1 | sed -E "s/^[[:space:]]+$2:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^\"//; s/\"$//"
+}
+extract_session() {  # extract_session <result.json> — the launcher's session id
+  # Fresh-context proof: a real `claude -p` mints a new session_id per call; the
+  # mock varies it per attempt. Dependency-free extraction (no jq, NFR-026).
+  [ -f "$1" ] || return 0
+  sed -n 's/.*"session_id":"\([^"]*\)".*/\1/p' "$1" 2>/dev/null | head -1
+}
+result_num() {  # result_num <result.json> <json-key> — LAST numeric value of "key":N
+  # The launcher's result envelope carries the AUTHORITATIVE usage (input/output
+  # tokens, total_cost_usd) — unlike the phase-report's usage block, which the phase
+  # self-reports and cannot actually know (it wrote 0 tokens in the live walk). We
+  # read the real numbers here. The `"key":` anchor (leading quote) means a key like
+  # cache_creation_input_tokens never matches `input_tokens` (no quote before it).
+  # `tail -1`: the real scalar is appended AFTER the model-controlled `result` string,
+  # so if a phase tries to spoof e.g. total_cost_usd in its answer text, the real one
+  # still wins. (A JSON-escaped injection `\"key\":N` wouldn't match this grep anyway.)
+  [ -f "$1" ] || { printf '0'; return 0; }
+  _rn="$(grep -o "\"$2\":[0-9][0-9.]*" "$1" 2>/dev/null | tail -1 | sed 's/.*://')"
+  [ -n "$_rn" ] && printf '%s' "$_rn" || printf '0'
+}
+usage_num() {  # usage_num <result.json> <input_tokens|output_tokens> — the AGGREGATE
+  # A real envelope carries MORE than one "input_tokens" (a nested per-tool/per-model
+  # breakdown), so a bare first/last match is unreliable. Anchor to the top-level
+  # `usage` object: greedy `.*"usage":{` lands on the LAST `usage:{` (the launcher's,
+  # after the model's answer — "modelUsage" uses camelCase, never matches), and the
+  # aggregate input/output tokens sit at its head, so the FIRST match within is the
+  # aggregate. Also drops any value the model injected before `usage` in its text.
+  [ -f "$1" ] || { printf '0'; return 0; }
+  _um="$(sed 's/.*"usage":{//' "$1" 2>/dev/null | grep -o "\"$2\":[0-9]*" | head -1 | sed 's/.*://')"
+  [ -n "$_um" ] && printf '%s' "$_um" || printf '0'
+}
+
+# --- model-by-phase-type map (STEP-5 SEAM — read, NOT routed) ----------------
+# The runner reads config.model_by_phase_type to RECORD each phase's intended model
+# into usage.tsv (spend attribution + step 5's switch surface). It deliberately
+# does NOT turn that value into a routing flag on the headless run — routing on this
+# map is step 5's job (FR-160 / handoff B5). Recording without routing is the seam.
+cfg_map_get() {  # cfg_map_get <map-key> <sub-key> <default> — an indented sub-key
+  _mv=""
+  if [ -f "$CONFIG" ]; then
+    _mv="$(awk -v mk="$1" -v sk="$2" '
+      $0 ~ ("^" mk ":[[:space:]]*$") { inb=1; next }
+      inb && /^[^[:space:]#]/          { inb=0 }
+      inb && $0 ~ ("^[[:space:]]+" sk ":") {
+        line=$0
+        sub("^[[:space:]]+" sk ":[[:space:]]*", "", line)
+        sub(/[[:space:]]*(#.*)?$/, "", line)
+        print line; exit
+      }
+    ' "$CONFIG" 2>/dev/null)"
+  fi
+  [ -n "$_mv" ] && printf '%s' "$_mv" || printf '%s' "$3"
+}
+phase_type_of() {  # phase_type_of <phase> — optional `phase_type:` in the phase plan
+  _pt=""
+  _pl="$WORKTREE/phases/$1/plan.md"
+  [ -f "$_pl" ] && _pt="$(grep -E '^phase_type:' "$_pl" 2>/dev/null | head -1 \
+    | sed -E 's/^phase_type:[[:space:]]*//; s/[[:space:]]*(#.*)?$//')"
+  printf '%s' "$_pt"
+}
+model_for_phase() {  # model_for_phase <phase> <report-file> — intended model, recorded not routed
+  _mp_type="$(phase_type_of "$1")"
+  _mp=""
+  [ -n "$_mp_type" ] && _mp="$(cfg_map_get model_by_phase_type "$_mp_type" "")"
+  # Fall back to what the phase itself recorded, then a placeholder.
+  [ -z "$_mp" ] && _mp="$(report_nested "$2" model)"
+  [ -z "$_mp" ] && _mp="-"
+  printf '%s' "$_mp"
+}
+
+# --- named seams (filled by later plans; explicit stubs, not silent) ---------
+
+# notify: the swappable ping channel. Delivery is DELEGATED to an external command
+# (FORGE_SLICE_NOTIFY, default forge-slice-notify.sh — a thin `claude -p` →
+# PushNotification micro-call); tests point it at notify-stub.sh. The dedup stays
+# HERE (the runner owns "should this ping fire at all"): APPEND-ONCE by <key>+<kind>,
+# a marker records a ping fired so a crash-resume re-run never re-pings. The marker
+# lives under WORK_DIR (inside the slice worktree by default), so it persists across
+# runs and never touches primary.
+#
+# The §8 ping surface is CLOSED to five operator-facing types:
+#   ambiguity|irreversible|fork|budget|done
+# plus `halt` as the failure slice-end (the counterpart of `done`). The park branch
+# below rejects any `interrupt` value outside that set loudly, never forwarding it.
+NOTIFY_CMD="${FORGE_SLICE_NOTIFY:-$SELF_DIR/forge-slice-notify.sh}"
+slice_notify() {  # slice_notify <kind> <key> <payload>
+  _kind="$1"; _key="$2"; _msg="$3"
+  _marker="$PING_DIR/$_key-$_kind.marker"
+  if [ -f "$_marker" ]; then
+    printf '[ping] (suppressed dup) %s: %s\n' "$_kind" "$_msg" >&2
+    return 0
+  fi
+  mkdir -p "$PING_DIR"
+  printf '%s\n' "$_msg" > "$_marker"
+  # Tally this actual fire by §8 type (deduped fires only) — feeds slice-summary.txt.
+  case "$_kind" in
+    ambiguity)    PING_AMBIGUITY=$((PING_AMBIGUITY + 1)) ;;
+    irreversible) PING_IRREVERSIBLE=$((PING_IRREVERSIBLE + 1)) ;;
+    fork)         PING_FORK=$((PING_FORK + 1)) ;;
+    budget)       PING_BUDGET=$((PING_BUDGET + 1)) ;;
+    done)         PING_DONE=$((PING_DONE + 1)) ;;
+    halt)         PING_HALT=$((PING_HALT + 1)) ;;
+  esac
+  printf '[ping] %s: %s\n' "$_kind" "$_msg" >&2
+  # Dispatch to the swappable delivery channel — BEST-EFFORT: a channel that is
+  # missing, unauthed, or errors must never crash the slice (phone delivery is a
+  # deferred open item). The local `[ping]` line + marker above are the durable log.
+  "$NOTIFY_CMD" "$_kind" "$_msg" >&2 2>&1 \
+    || printf '[ping] (notify channel best-effort: %s exited non-zero for %s)\n' "$NOTIFY_CMD" "$_kind" >&2
+  LAST_PING="$_kind"
+}
+
+# refresh: at each phase boundary, integrate main into the slice worktree, then
+# check how far the slice has diverged. This is where a slice incorporates other
+# slices' landed work — conflicts stay small + early (J§5.1). Returns 0 to proceed
+# SILENTLY; returns 1 to PARK (a §8 fork ping has already fired) so the caller
+# STOPs BEFORE launching the next phase. FORGE_SLICE_REFRESH=off makes it a no-op.
+# The merge-boundary half of the divergence budget lives in step 2, not here.
+slice_refresh_from_main() {  # slice_refresh_from_main <phase-name>
+  _rf_phase="${1:-?}"
+  [ "$REFRESH_MAIN" = "off" ] && return 0
+
+  # Resolve the integration ref: origin/<branch> when a remote has it (fetch
+  # first, best-effort), else the local branch. Missing entirely (e.g. the first
+  # slice, before main exists) → nothing to integrate → proceed silently.
+  _int_ref=""
+  if git -C "$WORKTREE" remote | grep -q .; then
+    git -C "$WORKTREE" fetch --quiet origin "$INT_BRANCH" 2>/dev/null || true
+    if git -C "$WORKTREE" rev-parse --verify --quiet "origin/$INT_BRANCH" >/dev/null 2>&1; then
+      _int_ref="origin/$INT_BRANCH"
+    fi
+  fi
+  if [ -z "$_int_ref" ] && git -C "$WORKTREE" rev-parse --verify --quiet "$INT_BRANCH" >/dev/null 2>&1; then
+    _int_ref="$INT_BRANCH"
+  fi
+  [ -n "$_int_ref" ] || { printf '[runner] refresh: no %s ref to integrate — skipping\n' "$INT_BRANCH" >&2; return 0; }
+
+  # Attempt the merge. A clean fast-forward or clean auto-merge is MECHANICAL →
+  # silent, proceed. A real merge conflict is beyond mechanical → NEVER
+  # auto-resolve (FORGE.md); abort and PARK with a fork ping.
+  if git -C "$WORKTREE" merge --no-edit "$_int_ref" >/dev/null 2>&1; then
+    printf '[runner] refresh: integrated %s cleanly\n' "$_int_ref" >&2
+  else
+    git -C "$WORKTREE" merge --abort >/dev/null 2>&1 || true
+    slice_notify fork "refresh-$_rf_phase" \
+      "refresh from $INT_BRANCH conflicts at phase boundary ($_rf_phase) — resolve, split, or land the slice; the runner will not auto-resolve"
+    return 1
+  fi
+
+  # Divergence budget: how far has the slice drifted from main since their shared
+  # base (commits and changed lines)? Over EITHER threshold → park with a fork
+  # ping ("split, land, or explicitly extend"). Within → proceed silently.
+  _base="$(git -C "$WORKTREE" merge-base "$_int_ref" HEAD 2>/dev/null || echo '')"
+  if [ -n "$_base" ]; then
+    _commits="$(git -C "$WORKTREE" rev-list --count "$_base"..HEAD 2>/dev/null || echo 0)"
+    _lines="$(git -C "$WORKTREE" diff --numstat "$_base" HEAD 2>/dev/null | awk '{a+=$1; d+=$2} END{print a+d+0}')"
+    : "${_lines:=0}"
+    if [ "$_commits" -gt "$DIV_BUDGET_COMMITS" ] || [ "$_lines" -gt "$DIV_BUDGET_LINES" ]; then
+      slice_notify fork "divergence-$_rf_phase" \
+        "divergence budget blown at phase boundary ($_rf_phase): ${_commits} commits / ${_lines} lines vs $INT_BRANCH (budget ${DIV_BUDGET_COMMITS}c/${DIV_BUDGET_LINES}l) — split, land, or explicitly extend"
+      return 1
+    fi
+    printf '[runner] refresh: divergence within budget (%sc/%sl of %sc/%sl)\n' \
+      "$_commits" "$_lines" "$DIV_BUDGET_COMMITS" "$DIV_BUDGET_LINES" >&2
+  fi
+  return 0
+}
+
+# resume/done-detection — COMPUTE, don't store (NFR-028 / Fork 3 / Amendment 2).
+# A phase is "done" iff its work dir already holds a phase-report.yml with a
+# TERMINAL verdict (proceed/done). The resume point is derived every run by this
+# check — there is NO runner-owned cursor/state file. Kill the runner between
+# phases and re-run: it recomputes the same point from the reports on disk, redoes
+# no completed phase, and (via the append-once ping markers) re-pings nothing.
+phase_already_done() {  # phase_already_done <report-file>
+  [ -f "$1" ] || return 1
+  _v="$(report_field "$1" verdict)"
+  [ "$_v" = "proceed" ] || [ "$_v" = "done" ]
+}
+
+# --- the loop ----------------------------------------------------------------
+COMPLETED=0
+TOUCHES=0            # RESERVED, structurally always 0 — a files-only headless run has no
+                     # between-phase operator interaction to count. Reported in SLICE_RESULT
+                     # + slice-summary as a fixed 0 (a stable field for step-3's board), not a
+                     # live measurement. Wire a real source here if attended runs ever land.
+LAST_PING="none"
+ACCUM=0             # cumulative usage.cost_usd across phases — the per-slice spend
+idx=0
+total="$(printf '%s\n' "$PHASES" | grep -c .)"
+
+# Per-slice ping tallies by §8 type (+ halt failure-end). Incremented by
+# slice_notify on each real fire; written to slice-summary.txt on every exit path.
+PING_AMBIGUITY=0; PING_IRREVERSIBLE=0; PING_FORK=0; PING_BUDGET=0; PING_DONE=0; PING_HALT=0
+USAGE_FILE="$WORK_DIR/usage.tsv"           # per-phase receipts (one row per phase)
+SUMMARY_FILE="$WORK_DIR/slice-summary.txt" # per-slice ping/touch/spend roll-up
+
+# Per-slice summary is written from an EXIT trap so EVERY termination path — done,
+# halt, park, budget breach, phase-list exhaustion, even a crash exit — leaves the
+# same roll-up on disk. Uses ${..:-} defaults so it is safe under `set -u` even if
+# we die before the counters are live. Files-only, never authoritative (Fork 3).
+write_slice_summary() {
+  [ -n "${WORK_DIR:-}" ] || return 0
+  {
+    printf 'phases_completed=%s\n' "${COMPLETED:-0}"
+    printf 'touches=%s\n'          "${TOUCHES:-0}"
+    printf 'spend_usd=%s\n'        "${ACCUM:-0}"
+    printf 'ambiguity=%s\n'        "${PING_AMBIGUITY:-0}"
+    printf 'irreversible=%s\n'     "${PING_IRREVERSIBLE:-0}"
+    printf 'fork=%s\n'             "${PING_FORK:-0}"
+    printf 'budget=%s\n'           "${PING_BUDGET:-0}"
+    printf 'done=%s\n'             "${PING_DONE:-0}"
+    printf 'halt=%s\n'             "${PING_HALT:-0}"
+    printf 'last_ping=%s\n'        "${LAST_PING:-none}"
+  } > "$SUMMARY_FILE" 2>/dev/null || true
+}
+trap write_slice_summary EXIT
+
+# Iterate phases in order with a `for` (NOT a `printf | while`, which would run
+# the loop in a subshell and swallow the `done`-verdict `exit` + the counters).
+# Phase names are single tokens, so word-splitting on IFS is safe; `set -f`
+# guards against a stray glob in a phase name.
+set -f
+for phase in $PHASES; do
+  [ -n "$phase" ] || continue
+  idx=$((idx + 1))
+  wdir="$WORK_DIR/phase-$idx"
+  mkdir -p "$wdir"
+  report="$wdir/phase-report.yml"
+
+  if phase_already_done "$report"; then
+    printf '[runner] phase %s (%s/%s) already done — skipping\n' "$phase" "$idx" "$total" >&2
+    COMPLETED=$((COMPLETED + 1))
+    continue
+  fi
+
+  # (1) ASSEMBLE the prompt FROM FILES ONLY -> assembled-prompt.txt.
+  #     plan + prior phase-report.yml files + a repo-state snippet. Never a
+  #     transcript or a prior-phase resume handle.
+  prompt="$wdir/assembled-prompt.txt"
+  {
+    printf '# Headless phase: %s (%s of %s)\n\n' "$phase" "$idx" "$total"
+    printf 'Files-only context. Everything you need is below or on disk in the slice\n'
+    printf 'worktree; there is no prior conversation to draw on.\n\n'
+
+    printf '## This phase plan\n\n'
+    if [ -f "$WORKTREE/phases/$phase/plan.md" ]; then
+      cat "$WORKTREE/phases/$phase/plan.md"
+    else
+      printf '(no plan.md for %s)\n' "$phase"
+    fi
+    printf '\n'
+
+    if [ "$idx" -gt 1 ]; then
+      printf '## Prior phase reports (files-only hand-off)\n\n'
+      j=1
+      while [ "$j" -lt "$idx" ]; do
+        prj="$WORK_DIR/phase-$j/phase-report.yml"
+        printf -- '- phase-%s/phase-report.yml:\n' "$j"
+        if [ -f "$prj" ]; then
+          sed 's/^/    /' "$prj"
+        else
+          printf '    (missing)\n'
+        fi
+        printf '\n'
+        j=$((j + 1))
+      done
+    fi
+
+    printf '## Repo state (slice worktree)\n\n'
+    printf '```\n'
+    git -C "$WORKTREE" log --oneline -5 2>/dev/null || true
+    printf -- '---\n'
+    git -C "$WORKTREE" status --short 2>/dev/null || true
+    printf '```\n'
+  } > "$prompt"
+
+  # (2) per-phase SYSTEM PROMPT: tell the phase to write phase-report.yml to its
+  #     work dir as its LAST action. Carries the concrete report path so a real
+  #     `claude -p` phase knows exactly where to put it (the mock reads the env).
+  sysprompt="$wdir/system-prompt.txt"
+  {
+    printf 'You are executing ONE phase of a Forge slice, headless and unattended.\n'
+    printf 'Do the work described in the user prompt. Rely only on the files given\n'
+    printf 'and the slice worktree — there is no chat history behind this run.\n\n'
+    printf 'As your FINAL action, write a phase report FILE to this exact path\n'
+    printf '(the runner reads it from disk — it is NOT parsed from your reply):\n'
+    printf '  %s\n' "$report"
+    printf 'It MUST match the annotated example here:\n'
+    printf '  %s\n' "$REPORT_TEMPLATE"
+    printf 'and the JSON schema here:\n'
+    printf '  %s\n' "$SCHEMA"
+    printf 'Set verdict to one of proceed|park|halt|done. If you hit a Rule-4 stop,\n'
+    printf 'an ambiguity, an irreversible step, a design fork, or a budget breach,\n'
+    printf 'set verdict=park and fill interrupt + interrupt_payload — do not guess.\n'
+  } > "$sysprompt"
+
+  # (3) LAUNCH + FAILURE POLICY. A phase that HALTS ITSELF (verdict=halt) or whose
+  #     own checks failed (checks.failed>0) gets exactly ONE fresh-context retry (a
+  #     brand-new launcher call — new session id), absorbing a flake. A SECOND
+  #     failure halts the slice early with evidence attached. This is a bounded
+  #     count (attempt <= 2), NOT a loop-until-success (handoff B3: that is the
+  #     token furnace). A launch that writes no report at all is a CRASH, not a
+  #     check failure — it halts immediately so crash-resume re-runs it next boot.
+  _pstart="$(date +%s 2>/dev/null || echo 0)"   # phase wall-clock start (runner-measured)
+  attempt=1
+  max_attempt=2
+  verdict=""
+  while : ; do
+    printf '[runner] phase %s (%s/%s): launching %s (attempt %s)\n' \
+      "$phase" "$idx" "$total" "$LAUNCHER" "$attempt" >&2
+    (
+      cd "$WORKTREE"
+      # A headless, zero-touch phase has no TTY to approve tool use, so the per-tool
+      # permission gate is bypassed — otherwise the very first Write (the work, or
+      # the mandatory phase-report.yml) blocks forever waiting for an approval that
+      # can never arrive. This is SAFE by the runner's design, not in spite of it:
+      # the slice runs in an ISOLATED worktree (main stays clean, locked decision),
+      # and the runner substitutes its OWN §8 `irreversible` interrupt for Claude
+      # Code's permission prompt — a dangerous action is DECLARED as a park, caught
+      # before it runs, not gated per-tool. Budget caps bound the blast radius.
+      FORGE_SLICE_REPORT_PATH="$report" \
+      FORGE_SLICE_PHASE="$phase" \
+      FORGE_SLICE_PHASE_INDEX="$idx" \
+      FORGE_SLICE_ATTEMPT="$attempt" \
+      "$LAUNCHER" -p \
+        --output-format json \
+        --max-turns "$MAX_TURNS" \
+        --max-budget-usd "$MAX_BUDGET" \
+        --dangerously-skip-permissions \
+        --append-system-prompt-file "$sysprompt" \
+        < "$prompt" \
+        > "$wdir/result.json" 2> "$wdir/launch.err"
+    ) || {
+      printf '[runner] phase %s: launcher exited non-zero (attempt %s)\n' "$phase" "$attempt" >&2
+    }
+
+    # Record this attempt's session id — the fresh-context proof the retry asserts.
+    extract_session "$wdir/result.json" > "$wdir/attempt-$attempt.session"
+
+    # (4) REQUIRE the on-disk phase-report.yml. Absent = crash → halt now (do NOT
+    #     spend the retry on a crash; the resume path re-runs it from files).
+    if [ ! -f "$report" ]; then
+      printf '[runner] phase %s: no phase-report.yml written at %s — halting\n' "$phase" "$report" >&2
+      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      exit 1
+    fi
+
+    verdict="$(report_field "$report" verdict)"
+    cfailed="$(report_nested "$report" failed)"
+    case "$cfailed" in ''|*[!0-9]*) cfailed=0 ;; esac
+
+    # FAIL = the phase halted itself OR its own checks failed (a proceed with
+    # checks.failed>0 is the contradiction the schema calls halt-worthy).
+    if [ "$verdict" = "halt" ] || [ "$cfailed" -gt 0 ]; then
+      if [ "$attempt" -lt "$max_attempt" ]; then
+        printf '[runner] phase %s: FAILED (verdict=%s checks.failed=%s) — one fresh-context retry\n' \
+          "$phase" "$verdict" "$cfailed" >&2
+        attempt=$((attempt + 1))
+        continue
+      fi
+      # Retry exhausted → HALT the slice early, failure evidence attached.
+      _ev="$(report_field "$report" evidence)"
+      slice_notify halt slice \
+        "slice HALTED at phase $phase ($idx/$total) after 1 retry — verdict=$verdict checks.failed=$cfailed; evidence: $report${_ev:+ ; $_ev}"
+      printf '[runner] phase %s: HALTED after retry — failure evidence at %s\n' "$phase" "$report" >&2
+      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      exit 1
+    fi
+    break   # phase passed its own checks — proceed to the verdict branch below
+  done
+
+  # A phase that produced a valid (non-halt) report RAN — its usage is recorded
+  # below regardless — but "completed" is reserved for proceed/done. A `park` ran
+  # WITHOUT completing (it stopped for the operator), so COMPLETED is incremented in
+  # the proceed/done branches only, NOT here — a parked phase must not inflate the
+  # count (live walk: an irreversible park was showing phases_completed=2).
+
+  # Accumulate the per-slice spend from the launcher's AUTHORITATIVE receipt
+  # (result.json total_cost_usd), not the phase's self-reported cost (feeds the
+  # budget cap below + B5 instrumentation). Float math via awk — POSIX sh has no
+  # floats; LC_NUMERIC=C forces a `.` decimal so the stored value never picks up a
+  # locale comma (the live walk showed `0,000000`).
+  _cost="$(result_num "$wdir/result.json" total_cost_usd)"
+  case "$_cost" in ''|*[!0-9.]*) _cost=0 ;; esac
+  ACCUM="$(LC_NUMERIC=C awk -v a="$ACCUM" -v b="$_cost" 'BEGIN{printf "%.6f", (a+0)+(b+0)}')"
+  printf '[runner] phase %s: verdict=%s spend=$%s/$%s\n' "$phase" "$verdict" "$ACCUM" "$SLICE_BUDGET" >&2
+
+  # (4a) INSTRUMENTATION — append this phase's receipts to usage.tsv (B5 / step-5
+  #      spend seam), one row per phase. Sourced for FIDELITY (live walk found the
+  #      phase-report's self-reported usage was all zeros — a phase can't know its
+  #      own token count):
+  #        tokens       = result.json input_tokens + output_tokens (launcher truth)
+  #        wall_clock_s = runner-measured elapsed for the phase (incl. any retry)
+  #        retry_count  = runner-observed (attempt-1), not the phase's self-report
+  #        model        = intended model for the phase-type, READ from config but
+  #                       NOT routed (model_for_phase → the step-5 seam)
+  _tok_in="$(usage_num "$wdir/result.json" input_tokens)"
+  _tok_out="$(usage_num "$wdir/result.json" output_tokens)"
+  _u_tokens="$(awk -v a="$_tok_in" -v b="$_tok_out" 'BEGIN{printf "%d", (a+0)+(b+0)}')"
+  _now="$(date +%s 2>/dev/null || echo 0)"
+  if [ "$_now" -ge "$_pstart" ] 2>/dev/null; then _u_wall=$(( _now - _pstart )); else _u_wall=0; fi
+  _u_retry=$(( attempt - 1 ))
+  _u_model="$(model_for_phase "$phase" "$report")"
+  [ -f "$USAGE_FILE" ] || printf 'phase_name\ttokens\twall_clock_s\tmodel\tretry_count\n' > "$USAGE_FILE"
+  printf '%s\t%s\t%s\t%s\t%s\n' "$phase" "$_u_tokens" "$_u_wall" "$_u_model" "$_u_retry" >> "$USAGE_FILE"
+
+  # (5) BRANCH on verdict. proceed advances; done ends with the done ping.
+  #     park is STUBBED here (plan-48 wires the real §8 interrupt ping) — explicit,
+  #     not silent. halt never reaches here (handled by the retry/halt path above).
+  case "$verdict" in
+    proceed)
+      COMPLETED=$((COMPLETED + 1))   # this phase finished its work and advances
+      # Per-slice budget cap (§8.4). A breach of the running spend total parks the
+      # slice with a `budget` ping BEFORE launching the next phase. Checked before
+      # the refresh — it is cheaper (no git) and a distinct §8 interrupt type.
+      if LC_NUMERIC=C awk -v a="$ACCUM" -v c="$SLICE_BUDGET" 'BEGIN{exit !((a+0) > (c+0))}'; then
+        slice_notify budget slice \
+          "per-slice budget breached after phase $phase ($idx/$total): spent \$$ACCUM > cap \$$SLICE_BUDGET — split the slice or raise per_slice_budget_usd"
+        printf '[runner] phase %s: BUDGET CAP breached ($%s > $%s) — parking slice\n' "$phase" "$ACCUM" "$SLICE_BUDGET" >&2
+        printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+        exit 3
+      fi
+      # Phase-boundary refresh + divergence budget. A non-zero return means the
+      # slice PARKED (fork ping already fired) — STOP before the next phase.
+      if ! slice_refresh_from_main "$phase"; then
+        printf '[runner] phase %s: slice PARKED at phase boundary (fork ping) — stopping before next phase\n' "$phase" >&2
+        printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+        exit 3
+      fi
+      ;;
+    done)
+      COMPLETED=$((COMPLETED + 1))   # the final phase completed the slice
+      slice_notify done slice "slice complete: $total phases, $COMPLETED run, 0 operator touches"
+      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      exit 0
+      ;;
+    park)
+      # A phase parks itself with a §8 interrupt. Map it to exactly ONE of the
+      # closed five-type set; anything else is rejected loudly (never forwarded).
+      # The park happens BEFORE the next phase launches, so an irreversible action
+      # (declared in the report, deferred by the phase) is caught pre-execution.
+      interrupt="$(report_field "$report" interrupt)"
+      ipayload="$(report_field "$report" interrupt_payload)"
+
+      # A design fork must arrive as something to LOOK AT — the payload is a
+      # sketch/mockup PATH that exists, never prose describing a visual (§8).
+      if [ "$interrupt" = "fork" ] && { [ -z "$ipayload" ] || [ ! -e "$ipayload" ]; }; then
+        printf '[runner] phase %s: fork interrupt payload %s is not an existing path — a design fork must be a sketch/mockup to look at, not prose; rejecting\n' "$phase" "${ipayload:-<empty>}" >&2
+        printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+        exit 1
+      fi
+
+      case "$interrupt" in
+        ambiguity|irreversible|fork|budget)
+          slice_notify "$interrupt" "$phase" "$ipayload"
+          printf '[runner] phase %s: PARKED — §8 %s interrupt (stopping before next phase)\n' "$phase" "$interrupt" >&2
+          printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+          exit 3
+          ;;
+        *)
+          printf '[runner] phase %s: park with interrupt %s — not one of the five §8 types (ambiguity|irreversible|fork|budget) — rejecting loudly\n' "$phase" "${interrupt:-<none>}" >&2
+          printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+          exit 1
+          ;;
+      esac
+      ;;
+    *)
+      printf '[runner] phase %s: unrecognized verdict "%s" — halting\n' "$phase" "$verdict" >&2
+      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      exit 1
+      ;;
+  esac
+done
+set +f
+
+# The loop runs in the main shell, so a `done` verdict already `exit 0`'d above.
+# Reaching here means the phase list was exhausted WITHOUT a `done` verdict — the
+# slice ran every phase but the last one never marked itself done.
+printf '[runner] phase list exhausted with no `done` verdict\n' >&2
+printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+exit 0