dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-brainstorm/references/visual-probes.md

@@ -0,0 +1,164 @@
+# Visual Probes
+
+Use visual probes when a brainstorm decision is faster to judge by seeing a rough artifact than by reading prose. A visual probe is a disposable decision sketch, not a prototype, implementation plan, UI spec, or design deliverable.
+
+## Trigger
+
+Use this reference only when the next question has a specific visual decision:
+
+- behavior shape: "Which annotation or drawing behavior feels right?"
+- layout shape: "Which navigation structure matches the workflow?"
+- flow shape: "Where should this decision point sit?"
+- state shape: "Which empty/loading/error state communicates the right thing?"
+- diagram shape: "Which relationship or system boundary is clearer?"
+
+Do not use a visual probe for product goals, scope boundaries, success criteria, evidence probes, tradeoff prose, or technical decisions that are easier to discuss in chat. A decision that meets Interaction Rule 7 in `references/interaction-rules.md` — which states that test — belongs to `ce-prototype`, not to a visual probe.
+
+**Classifying a wide decision.** Per-avenue classification applies only once the avenues have been named. An undecomposed decision is classified once, on its dominant dimension. When any named avenue meets Rule 7, the whole decision goes to `ce-prototype` — the sketchable avenues ride along there as thin variants rather than splitting one decision across two tiers.
+
+## The gate (when the offer must fire)
+
+When Phase 0.3 flagged an inherently-visual topic, the offer must be made before the **first** decision about shape, behavior, state, layout, flow, or a diagram is raised in *any* form — plain chat or a blocking question. A decision that meets Interaction Rule 7 routes to `ce-prototype` instead; this rule does not apply to it.
+
+**Timing is state-based, not memory-based.** Anchor the check to the decision you are about to raise, not to a "pending offer" remembered since Phase 0.3: offer unless this specific decision has already been through the offer (the user already chose text or visual for it). This rule takes precedence over the default blocking-question path — do not raise the shape decision as a blocking-question menu, or as a plain-chat shape question, until the user has declined visual (or visual feedback has returned to chat).
+
+**Having been through the offer closes only this offer, never Rule 7.** Two paths reopen the prototype route for a decision already offered here: the user chose text and the decision then turns on finish or motion, or a rough sketch was built and did not settle it. Route those to `ce-prototype` rather than treating the decision as closed.
+
+**An ASCII preview or text mockup embedded inside the question's choices does NOT satisfy the offer** — that shortcut is exactly what this rule exists to stop. The offer is its own prior question with two options (sketch vs describe); only after the user chooses does the shape decision proceed.
+
+## Offer
+
+Ask once at the decision point. Do not enable a session-wide mode.
+
+Use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Use a plain chat question only when no such tool is in the list or a real question call errors. The opt-in should have two clear options:
+
+- Visual sketch — create rough options in a local browser
+- Text description — keep the decision in chat
+
+Use this wording:
+
+> This decision may be easier to judge visually. I can either sketch rough options in a local browser so you can react to the shape, or keep it in chat and describe the options textually, which is faster but lower-fidelity. Which do you prefer?
+
+The text path must be credible. If you cannot explain the decision clearly in text, you do not understand it well enough to sketch it.
+
+If the user chooses text, continue in chat and do not re-offer for the same decision. If they choose visual, proceed below.
+
+## Visual Path
+
+Create the cheapest artifact that answers the current question. Optimize for fast feedback, not polish.
+
+Allowed:
+
+- rough behavior sketches
+- low-fidelity wireframes
+- state comparisons
+- flow diagrams
+- simple A/B/C visual contrasts
+- a disposable one-decision interaction demo only when a single behavior shape is the decision — not a wide diverge, layered slices, or an in-app overlay
+
+Avoid:
+
+- polished branding
+- final colors or typography
+- component-library precision
+- pixel-perfect layout
+- production-like implementation
+- unnecessary animation
+- details that imply exact UI commitments
+
+Label the artifact as directional. State what the user should judge and what they should ignore.
+
+## Display Helper
+
+Use the bundled display-only helper when the current platform can run a bundled skill script. Invoke it via the `SKILL_DIR` anchor: set `SKILL_DIR` to the absolute path of the directory containing the `ce-brainstorm` `SKILL.md` you loaded (the Bash tool's cwd is the user's project, not the skill dir), and re-set it in the same command on each call since shell vars don't persist between Bash invocations. Do not resolve the helper from the user's project CWD.
+
+Start (detached):
+
+```bash
+SKILL_DIR="<absolute path of the ce-brainstorm skill directory>";
+SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)";
+[ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") 2>/dev/null && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && [ -w "$SCRATCH_ROOT" ] || SCRATCH_ROOT="${TMPDIR:-/tmp}/compound-engineering-$(id -u)";
+if [ -L "$SCRATCH_ROOT" ]; then echo "unsafe scratch root symlink: $SCRATCH_ROOT" >&2; exit 1; fi;
+(umask 077; mkdir -p "$SCRATCH_ROOT") || exit 1;
+if [ -L "$SCRATCH_ROOT" ] || [ ! -O "$SCRATCH_ROOT" ]; then echo "scratch root is not owned by the current user: $SCRATCH_ROOT" >&2; exit 1; fi;
+chmod 700 "$SCRATCH_ROOT" || exit 1;
+PROBE_DIR="$SCRATCH_ROOT/ce-brainstorm-visual/<run-id>"; (umask 077; mkdir -p "$PROBE_DIR") || exit 1; chmod 700 "$PROBE_DIR" || exit 1;
+node "$SKILL_DIR/scripts/light-webserver.js" start --root "$PROBE_DIR"
+```
+
+Append `--foreground` to that `start` command for foreground mode. Status and stop take the same anchor — and because `SKILL_DIR` does not persist between Bash invocations, each must re-set it in its own call rather than reuse the `start` block's value:
+
+```bash
+SKILL_DIR="<absolute path of the ce-brainstorm skill directory>";
+SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)";
+[ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") 2>/dev/null && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && [ -w "$SCRATCH_ROOT" ] || SCRATCH_ROOT="${TMPDIR:-/tmp}/compound-engineering-$(id -u)";
+if [ -L "$SCRATCH_ROOT" ]; then echo "unsafe scratch root symlink: $SCRATCH_ROOT" >&2; exit 1; fi;
+(umask 077; mkdir -p "$SCRATCH_ROOT") || exit 1;
+if [ -L "$SCRATCH_ROOT" ] || [ ! -O "$SCRATCH_ROOT" ]; then echo "scratch root is not owned by the current user: $SCRATCH_ROOT" >&2; exit 1; fi;
+chmod 700 "$SCRATCH_ROOT" || exit 1;
+PROBE_DIR="$SCRATCH_ROOT/ce-brainstorm-visual/<run-id>"; (umask 077; mkdir -p "$PROBE_DIR") || exit 1; chmod 700 "$PROBE_DIR" || exit 1;
+node "$SKILL_DIR/scripts/light-webserver.js" status --root "$PROBE_DIR"
+# stop: the same command with `stop` in place of `status` (re-set SKILL_DIR again)
+```
+
+If `SKILL_DIR` cannot be resolved to a concrete skill directory, do not guess from the project CWD — use the text path.
+
+The helper creates `screens/` and `state/`, serves the newest `.html` file in `screens/`, writes `state/display-info.json`, and exposes `/version` so the browser can poll for screen changes. The browser reloads only when the newest screen changes; it must not continually reload on a timer. `/version` polling does not count as activity, so an abandoned browser tab cannot keep the server alive forever. Detached servers monitor the owning harness process when it can be resolved, and all servers exit after an idle timeout. The helper has no click tracking or browser-to-agent event path.
+
+If the helper path is unavailable or the platform cannot display a local URL cleanly, say so briefly and use the text path. Do not build a custom event system or long-lived server to compensate during the brainstorm.
+
+## Launch Mode by Platform
+
+The server is the same everywhere; only the launch mode changes.
+
+- **Claude Code / Claude desktop app:** detached `start` is the default path. If the app opens localhost URLs, show the returned URL and continue. If the browser surface is unavailable, use the text path.
+- **Codex CLI / Codex app:** if detached processes are reaped or the URL dies after the tool call, use `start --foreground` through the platform's long-running/background terminal mechanism. If there is no stable browser surface, use the text path.
+- **Plain terminal UI:** print the returned URL for the user to open manually. If opening a browser would interrupt the flow, keep the decision in chat.
+- **Remote or containerized sessions:** if `localhost` is not reachable from the user's browser, start with `--host 0.0.0.0` and tell the user which host/port to open. That serves the run directory to anything that can reach the port, with no auth — do it only on a network the user trusts, and say so when you hand over the URL. If that cannot be made clear, use the text path.
+
+Never force the visual path because a local server exists. The user chose visual to understand the decision faster; if the platform plumbing gets in the way, switch back to text.
+
+## Post-Artifact Feedback
+
+After showing the visual artifact, use the host's blocking question tool already in the current tool list for bounded artifact feedback. This is still chat-based feedback, not browser event capture.
+
+Use a bounded interactive question when the expected response is a small choice set:
+
+- A/B/C/D option selection
+- visual direction vs mix
+- choose one layout/state/behavior
+- accept one option with requested tweaks
+
+Include a free-text fallback option when the tool supports it. Use plain chat only when feedback is genuinely open critique, no interactive question tool exists, or the tool errors.
+
+Good post-artifact prompt:
+
+> Which direction best matches what you want? Pick A, B, C, D, or mix, and use the free-text fallback for anything that feels off. Judge the behavior shape, not the exact styling.
+
+Do not ask the user to click inside the browser artifact. The question tool is for the chat/session response after the artifact is visible.
+
+## Interaction Contract
+
+The browser/artifact is display-only. Feedback happens in chat.
+
+Do not add click tracking, selected states, event ingestion, forms, analytics, or "submit" affordances in v1. Do not ask the user to click an option. Ask them to look at the artifact and reply in chat with the choice, mix, or correction.
+
+If no interactive question tool is available, use this plain-chat fallback after showing the artifact:
+
+> I’m showing three rough options. Reply here with A, B, C, or "mix", plus anything that feels off. Judge the behavior shape, not the exact styling.
+
+The user's chat response is authoritative. The visual artifact is supporting context only.
+
+## File Placement
+
+Use OS temp by default because visual probes are disposable scratch:
+
+```text
+<scratch-root>/ce-brainstorm-visual/<run-id>/
+  screens/
+    001-<decision>.html
+  state/
+    display-info.json
+```
+
+Use `.context/compound-engineering/ce-brainstorm-visual/<run-id>/` only when the user explicitly wants to inspect, preserve, or curate the sketches after the session. The probe is disposable scratch; the durable artifact is the Phase 3 requirements-only unified plan under `<root>/plans/`.

package/skills/ce-brainstorm/scripts/elevation-dispatch.sh

@@ -0,0 +1,288 @@
+#!/usr/bin/env bash
+# elevation-dispatch.sh — off-host model-elevation worker for ce-plan / ce-brainstorm.
+#
+# Runs one reasoning-heavy step on a user-chosen model via the Claude CLI, as a
+# detached job supervised by peer-job-runner.py. Streams NDJSON so the idle
+# window observes genuine progress, not just liveness — a buffered format would
+# make a healthy long run byte-identical to a wedged one. See
+# docs/solutions/skill-design/cli-output-buffering-for-progress-detection.md.
+#
+# Read-only posture (R7): the CLI is allowlisted to Read/Glob/Grep plus
+# WebSearch/WebFetch, so writes, shell, skills, and MCP are unavailable; the
+# model reads the repo and web to verify its brief and returns prose.
+#
+# Usage:
+#   elevation-dispatch.sh <model> <prompt-file> <result-path>
+#   elevation-dispatch.sh --emit-adapter <model>   # print argv, no model call (test hook)
+#
+# NOTE ON THE FUNCTION NAMED run_codex_cmd: it is NOT codex-specific here. It is
+# the $PEERLOG byte-growth idle loop that implements R11's primary supervision
+# signal (run_timeout_cmd, hard-cap-only, would leave a stalled run undetected).
+# It keeps that name because the shared heartbeat-parity regex in
+# tests/peer-job-runner-parity.test.ts uses `run_codex_cmd()` as the terminator
+# that forces BOTH heartbeat functions into the byte-compared kernel; renaming it
+# would weaken that cross-skill guard.
+
+set -uo pipefail
+trap '' HUP
+
+ACTIVE_PEER_PID=""
+RUN_SUCCEEDED=false
+
+log() { printf '[elevation] %s\n' "$*" >&2; }
+
+EFFORT="high"   # settled: elevation runs at high effort
+
+# Read-only tool posture (R7): the available built-in set, not a denylist. The
+# elevated step reads the repo (Read/Glob/Grep) and may check current facts on
+# the web (WebSearch/WebFetch) while authoring; it never needs Write/Bash/Task or
+# any mutating tool. Its output is returned prose, not a file write.
+ALLOWED=(Read Glob Grep WebSearch WebFetch)
+
+build_cmd() {   # <model> <handoff-dir> -> sets CMD array (claude CLI, streaming, read-only)
+  # --safe-mode suppresses the user environment's hooks, plugins, and MCP
+  # servers; --disable-slash-commands blocks skills. --tools RESTRICTS the
+  # available built-in set to this list — Write/Edit/Bash are not present at all.
+  # This is the real read-only boundary: --allowedTools ALONE only pre-approves
+  # (verified — it leaves every other tool available), so --allowedTools here
+  # just lets --permission-mode dontAsk run these five without a prompt instead
+  # of denying them.
+  local csv; csv="$(IFS=,; printf '%s' "${ALLOWED[*]}")"
+  # Grant read access to ONLY the single per-run handoff dir ($2, where the
+  # orchestrator co-located the prompt and evidence), which sits outside the
+  # launch dir. Claude's file access defaults to the launch dir and is extended
+  # via --add-dir. Adding the whole OS temp root ($TMPDIR / /tmp) instead would
+  # expose every other same-user scratch file and credential to the elevated
+  # model; the scoped dir does not. Read-only (only Read/Glob/Grep available).
+  local add_dirs=()
+  [ -n "${2:-}" ] && add_dirs=(--add-dir "$2")
+  # --no-session-persistence: this is a one-shot background model call, so the
+  # prompt and scratch-file references must not be saved as a resumable session
+  # on disk (matches the other scripted Claude peer routes in this repo).
+  CMD=(claude -p --model "$1" --effort "$EFFORT"
+       --output-format stream-json --verbose
+       --safe-mode --no-session-persistence --disable-slash-commands --strict-mcp-config
+       --permission-mode dontAsk
+       "${add_dirs[@]}"
+       --tools "$csv" --allowedTools "${ALLOWED[@]}"
+       --max-turns "${ELEVATION_MAX_TURNS:-30}")
+}
+
+# Test hook: print the argv the worker would exec, without calling a model.
+# Accepts an optional handoff dir ($3) so the emitted argv shows the scoped
+# --add-dir; without it the flag is omitted (no dir to grant).
+if [ "${1:-}" = "--emit-adapter" ]; then
+  [ -n "${2:-}" ] || { log "--emit-adapter requires <model>"; exit 2; }
+  build_cmd "$2" "${3:-}"
+  printf '%s\0' "${CMD[@]}"
+  exit 0
+fi
+
+MODEL="${1:?model required}"
+PROMPT_FILE="${2:?prompt-file required}"
+RESULT_PATH="${3:?result-path required}"
+[ -f "$PROMPT_FILE" ] || { log "prompt file not found: $PROMPT_FILE"; exit 2; }
+
+# The orchestrator co-locates the prompt and every evidence file in one private
+# per-run dir; grant the elevated model read access to just that dir (resolved
+# to an absolute path), never the whole OS temp root. Pure-bash dirname (no
+# external `dirname`): strip the last /component, defaulting to cwd if none.
+HANDOFF_DIR="${PROMPT_FILE%/*}"
+[ "$HANDOFF_DIR" = "$PROMPT_FILE" ] && HANDOFF_DIR="."
+HANDOFF_DIR="$(cd "$HANDOFF_DIR" 2>/dev/null && pwd || printf '%s' "$HANDOFF_DIR")"
+
+# jq builds every result envelope; it is only an optional capability (ce-setup),
+# so preflight it here rather than spending the CLI call and failing to parse.
+# Exit 0 with a failure envelope, NOT nonzero: the runner classifies a nonzero
+# exit as `failed`, and its `result` command then refuses to emit the artifact,
+# so the recovery flow could never read this envelope. Exit 0 makes the job
+# `done`, the envelope's status:failed is read, and it degrades to inline.
+if ! command -v jq >/dev/null 2>&1; then
+  log "jq not found on PATH; cannot parse the elevated result — degrading to inline"
+  printf '{"status":"failed","requested_model":"%s","evidence":"jq unavailable on PATH"}' "$MODEL" > "$RESULT_PATH" 2>/dev/null || true
+  exit 0
+fi
+
+PEERLOG="$(mktemp "${TMPDIR:-/tmp}/elevation-peer-XXXXXX")"
+
+# Idle window is the primary stall signal; the hard cap is a raised backstop (R11).
+# Keep this inner cap >= the runner's CE_PEER_HARD_SECS so it never reaps a
+# healthy run before the outer supervisor's own raised backstop.
+IDLE_SECS="${CE_ELEVATION_IDLE_SECS:-180}"
+HARD_SECS="${CE_ELEVATION_HARD_SECS:-5400}"
+POLL_SECS="${CE_ELEVATION_POLL_SECS:-5}"   # $PEERLOG growth poll interval
+
+reap() {
+  local pid="$1" grp
+  if kill -TERM -- -"$pid" 2>/dev/null; then grp=1; else kill -TERM "$pid" 2>/dev/null; grp=0; fi
+  for _ in 1 2 3 4 5; do
+    if [ "$grp" = 1 ]; then kill -0 -- -"$pid" 2>/dev/null || return 0
+    else kill -0 "$pid" 2>/dev/null || return 0; fi
+    sleep 1
+  done
+  if [ "$grp" = 1 ]; then kill -KILL -- -"$pid" 2>/dev/null; else kill -KILL "$pid" 2>/dev/null; fi
+}
+
+on_term() {
+  if [ -n "${_HEARTBEAT_PID:-}" ]; then
+    stop_heartbeat
+  fi
+  if [ -n "${ACTIVE_PEER_PID:-}" ]; then
+    log "received TERM/INT; reaping peer process group $ACTIVE_PEER_PID"
+    reap "$ACTIVE_PEER_PID" 2>/dev/null || true
+    ACTIVE_PEER_PID=""
+  fi
+  exit 0
+}
+trap 'on_term' TERM INT
+
+write_result() {   # <json-string> -> atomic publish to RESULT_PATH
+  local tmp="${RESULT_PATH}.tmp.$$"
+  printf '%s' "$1" > "$tmp" && mv -f "$tmp" "$RESULT_PATH"
+}
+
+# Bounded stderr/stdout tail for a failed run. tail -c avoids the macOS bash
+# negative-slice bug that erased sub-300-char evidence in the review worker.
+bounded_failure_evidence() { tail -c 800 "$PEERLOG" 2>/dev/null || true; }
+
+# Expected served-id prefix for a requested model alias, or empty if unknown.
+model_prefix() {   # <requested> -> prefix | ""
+  case "$1" in
+    fable)    printf 'claude-fable-' ;;
+    opus)     printf 'claude-opus-' ;;
+    sonnet)   printf 'claude-sonnet-' ;;
+    haiku)    printf 'claude-haiku-' ;;
+    claude-*) printf '%s' "$1" ;;
+  esac
+}
+
+# Requested family vs served id (R6/R16). matched | mismatch | unverified.
+classify_receipt() {   # <requested> <served>
+  local served="$2" prefix
+  { [ -z "$served" ] || [ "$served" = "unverified" ]; } && { printf 'unverified'; return; }
+  prefix="$(model_prefix "$1")"
+  [ -z "$prefix" ] && { printf 'unverified'; return; }
+  case "$served" in
+    "$prefix"*) printf 'matched' ;;
+    *)          printf 'mismatch' ;;
+  esac
+}
+
+# --- liveness heartbeat -----------------------------------------------------
+# Emits one stderr line every CROSS_MODEL_HEARTBEAT_SECS so the OUTER
+# peer-job-runner idle window (out.log byte-growth) sees the supervising script
+# as alive during a long model call. It writes to stderr, NOT $PEERLOG, so it
+# never masks this worker's OWN $PEERLOG idle detection (run_codex_cmd below) —
+# a stalled model still stops growing $PEERLOG and is reaped. This block is
+# byte-identical across all peer workers (kernel parity, tests/peer-job-runner-parity.test.ts).
+_HEARTBEAT_PID=""
+start_heartbeat() {
+  local every="${CROSS_MODEL_HEARTBEAT_SECS:-60}" parent_pid="$$"
+  # Floor to 1s: a non-numeric or 0 value would make `sleep` return instantly and
+  # spin the loop, flooding out.log into the runner's byte cap.
+  case "$every" in ''|*[!0-9]*) every=60 ;; esac; [ "$every" -lt 1 ] && every=1
+  _HEARTBEAT_READY=0
+  trap '_HEARTBEAT_READY=1' USR1
+  # Callers restore set +m after launching the peer, so without this the
+  # heartbeat inherits the worker pgid and kill -- -PID cannot reach the sleep.
+  local prev_m; case "$-" in *m*) prev_m=1;; *) prev_m=0;; esac
+  set -m
+  ( local t0 n sleeper=""
+    trap 'kill "${sleeper:-}" 2>/dev/null || true; exit 0' TERM INT
+    kill -USR1 "$parent_pid"
+    t0="$(date +%s)"
+    while kill -0 "$parent_pid" 2>/dev/null; do
+      sleep "$every" & sleeper=$!
+      wait "$sleeper" 2>/dev/null || exit 0
+      sleeper=""
+      kill -0 "$parent_pid" 2>/dev/null || break
+      n="$(date +%s)"; log "peer alive ($(( n - t0 ))s elapsed)"
+    done ) &
+  _HEARTBEAT_PID=$!
+  [ "$prev_m" = 0 ] && set +m
+  while [ "$_HEARTBEAT_READY" != 1 ] && kill -0 "$_HEARTBEAT_PID" 2>/dev/null; do sleep 0.01 || true; done
+  trap - USR1
+}
+stop_heartbeat() {
+  if [ -n "$_HEARTBEAT_PID" ]; then
+    # Leader-only TERM is deferred until the inner `wait $sleeper` returns, so
+    # the default 60s interval would block this wait. Signal the process group.
+    kill -- -"$_HEARTBEAT_PID" 2>/dev/null || kill "$_HEARTBEAT_PID" 2>/dev/null || true
+    wait "$_HEARTBEAT_PID" 2>/dev/null || true
+  fi
+  _HEARTBEAT_PID=""
+}
+
+run_codex_cmd() {
+  RUN_SUCCEEDED=false
+  local prev; case "$-" in *m*) prev=1;; *) prev=0;; esac
+  set -m
+  command "${CMD[@]}" < "$PROMPT_FILE" > "$PEERLOG" 2>&1 &
+  local pid=$!
+  ACTIVE_PEER_PID="$pid"
+  [ "$prev" = 0 ] && set +m
+  start_heartbeat
+  local start last=-1 lastchg now size
+  start="$(date +%s)"; lastchg="$start"
+  while kill -0 "$pid" 2>/dev/null; do
+    sleep "$POLL_SECS"; now="$(date +%s)"; size="$(wc -c <"$PEERLOG" 2>/dev/null || echo 0)"
+    [ "$size" != "$last" ] && { last="$size"; lastchg="$now"; }
+    if [ $(( now - lastchg )) -ge "$IDLE_SECS" ]; then
+      log "elevated call idle ${IDLE_SECS}s; reaping"; reap "$pid"; break
+    fi
+    if [ $(( now - start )) -ge "$HARD_SECS" ]; then
+      log "elevated call exceeded hard cap ${HARD_SECS}s; reaping"; reap "$pid"; break
+    fi
+  done
+  if wait "$pid" 2>/dev/null; then RUN_SUCCEEDED=true
+  else log "elevated call exited non-zero or was reaped"; fi
+  reap "$pid" 2>/dev/null || true
+  stop_heartbeat
+  ACTIVE_PEER_PID=""
+}
+
+# --- main -------------------------------------------------------------------
+build_cmd "$MODEL" "$HANDOFF_DIR"
+run_codex_cmd
+
+# The stream-json terminal event is the LAST line whose type is "result". Match
+# on it rather than `tail -1`, so a diagnostic written to stderr after the result
+# (an update notice, wrapper output) does not become the "result" we parse.
+EVENT="$(grep -a '"type":"result"' "$PEERLOG" 2>/dev/null | tail -1 || true)"
+PREFIX="$(model_prefix "$MODEL")"
+# jq `keys` is sorted, so keys[0] is not necessarily the served model when
+# modelUsage carries an auxiliary model too; prefer the requested family's key.
+SERVED="$(printf '%s' "$EVENT" | jq -r --arg p "$PREFIX" \
+  '(.modelUsage // {} | keys) as $k
+   | (if $p != "" then first($k[] | select(startswith($p))) else empty end) // $k[0] // "unverified"' \
+  2>/dev/null || printf 'unverified')"
+# Ship "ok" only on a clean success — a terminal event carries .result even when
+# truncated/errored (subtype error_*, is_error true). HAS_OUTPUT is a tiny jq
+# flag, so the plan text is never loaded into a shell variable or an argv.
+SUBTYPE="$(printf '%s' "$EVENT" | jq -r '.subtype // empty' 2>/dev/null || true)"
+IS_ERROR="$(printf '%s' "$EVENT" | jq -r '.is_error // false' 2>/dev/null || printf 'true')"
+HAS_OUTPUT="$(printf '%s' "$EVENT" | jq -r 'if (.result // "") == "" then "no" else "yes" end' 2>/dev/null || printf 'no')"
+
+if [ "$RUN_SUCCEEDED" = true ] && [ "$HAS_OUTPUT" = "yes" ] \
+   && [ "$SUBTYPE" = "success" ] && [ "$IS_ERROR" != "true" ]; then
+  RECEIPT="$(classify_receipt "$MODEL" "$SERVED")"
+  # Build the envelope by piping the event THROUGH jq, which reads .result
+  # internally — never pass the plan text as an argv --arg, which would exceed
+  # ARG_MAX for a large Deep plan.
+  tmp="${RESULT_PATH}.tmp.$$"
+  if printf '%s' "$EVENT" | jq --arg m "$MODEL" --arg s "$SERVED" --arg r "$RECEIPT" \
+       '{status:"ok", requested_model:$m, served_model:$s, receipt:$r, output:.result}' \
+       > "$tmp" 2>/dev/null; then
+    mv -f "$tmp" "$RESULT_PATH"
+    log "elevated step complete: requested=$MODEL served=$SERVED receipt=$RECEIPT"
+  else
+    rm -f "$tmp"
+    write_result "$(jq -n --arg m "$MODEL" '{status:"failed", requested_model:$m, evidence:"result envelope build failed"}')"
+    log "elevated step: result envelope build failed"
+  fi
+else
+  write_result "$(jq -n --arg m "$MODEL" --arg e "$(bounded_failure_evidence)" \
+    '{status:"failed", requested_model:$m, evidence:$e}')"
+  log "elevated step failed; wrote failure envelope"
+fi
+rm -f "$PEERLOG"