dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-plan/references/universal-planning.md

@@ -0,0 +1,170 @@
+# Universal Planning Workflow
+
+This file is loaded when ce-plan detects a non-software task (Phase 0.1b). It replaces the software-specific phases (0.2 through 5.1) with a domain-agnostic planning workflow.
+
+## Before starting: verify classification
+
+The detection stub in SKILL.md routes here for anything that isn't clearly software. Verify the classification is correct before proceeding:
+
+- **Is this actually a software task?** The key distinction is task-type, not topic-domain. A study guide about Rust is non-software (producing educational content). A Rust library refactor is software (modifying code). If this is actually software, return to Phase 0.2 in the main SKILL.md.
+- **Is this a trivial single-fact lookup?** Only a question answerable from one fact with no research, retrieval, or judgment skips planning — answer it directly and stop, in the user's terms. Do not narrate that it "isn't a planning task" or explain the routing; that is process exhaust (see Veil of value below). Examples: "zsh: command not found: brew", "what's the capital of France." A question that needs multiple steps, any retrieval, or synthesis to answer well does **not** qualify: it is an answer-seeking task (see Disposition below), not a quick-help exit. When unsure, do not exit.
+- **Pipeline mode?** If invoked from `lfg` or any `disable-model-invocation` context: tell the user this is a non-software task, `lfg` requires the software-only `ce-work` path, and they should invoke `ce-plan` directly for non-software planning. For this user-runnable output, default to `/ce-plan`; use `$ce-plan` only on Codex or a host explicitly documented as dollar-prefixed. Render only the invocation as inline code and output one form only, then stop.
+- **Unified artifact guard.** Universal-planning outputs are not software implementation plans. Do not label them `artifact_contract: ce-unified-plan/v1` and do not produce an implementation launch block unless the deliverable itself is a complete software implementation plan with Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done.
+
+Once past these checks, commit to the task — do not bail because it looks like a "lookup" or "research question." The user invoked the planning tool on purpose. Then choose the disposition below.
+
+---
+
+## Disposition: plan-seeking vs. answer-seeking
+
+Two kinds of task land here, with different deliverables:
+
+- **Plan-seeking** — the deliverable is a *plan*: a trip itinerary, a study curriculum, an event runbook, a project plan. The plan is the artifact, saved or shared. → Follow Steps 1-3 below.
+- **Answer-seeking** — the deliverable is an *answer*: an investigative or analytical question ("how often does X happen — is it a big deal?", "how does our approach compare to Y?", "should we Z?"). No one wants a saved plan document for this; planning is the means to a good answer, not the output. → Follow the **Answer-seeking flow** below; skip the Step 3 artifact handling.
+
+If a request blends both ("research X, then plan Y"), do the answer-seeking research first, then produce the plan artifact.
+
+Commit to one disposition before reading further, and follow only that flow: a plan-seeking task still produces its plan document (Steps 1-3) and does not stop at a chat answer; an answer-seeking task does not write a plan file.
+
+---
+
+## Answer-seeking flow
+
+The planning instinct still applies — but the plan is *working scaffold*, not an artifact. State it in chat to steer the work and show the human the approach; execute it; discard it. No plan file is written.
+
+### State a brief plan-of-attack, then proceed
+
+Say how the question will be answered, right-sized to it: a light question gets a one-line approach; a multi-part analytical question gets a short bulleted plan (a few steps). This is **non-blocking** — announce the approach and continue immediately. Do not ask the user to approve the plan; the stated approach is itself the checkpoint, and the user can interrupt if the framing is wrong. Stop to ask only on a genuine fork the agent cannot resolve (e.g., "his personal account or the org's?").
+
+### Execute the plan
+
+Carry out the approach. When the answer depends on facts the model can't reliably supply from memory — current data, recent events, specifics that drift — gather them using the **Research decomposition pattern** under Step 1 below (decompose into focused questions, dispatch in parallel via the platform's subagent/web primitive, collate). Skip research for anything the model already knows well.
+
+**Ground answers about the user's own code, repo, or named artifacts in the actual sources — not memory.** When the question references local code, a specific file, a named CLI or service, or "our X", read those sources first (and any resource the user named — see Core Principle 8 in SKILL.md). "The model already knows the topic" covers general knowledge only, never the contents of the user's codebase: a comparison or recommendation about local code that was never read is ungrounded. Inspect, then answer.
+
+**Execution here is research and analysis only — never code.** Reading code and artifacts to understand them is in-bounds research; writing or running code to change the system is not — that belongs in `ce-work`. This keeps the planning/execution boundary intact.
+
+### Deliver the answer
+
+Answer in chat. Do **not** write a plan file and do **not** run the Step 3 save/share menu by default. If the investigation produced something the user might want to keep (a comparison table, a sourced summary), offer to save it; otherwise just give the answer. In headless or non-interactive runs, skip the offer and deliver the answer.
+
+### Veil of value: what to show, what to hide
+
+The plan-of-attack and the answer are for the caller; the skill's internal machinery is not. Edit for relevance the way an expert consultant does — they tell you their thinking about your problem, not which template their back office applied.
+
+- **Show** (question-domain — reads as value): the approach to the user's actual question, in the user's terms.
+- **Hide** (skill-domain — process exhaust): which skill, mode, or phase is running; whether a plan file was or wasn't written; the routing or disposition decision itself.
+- **Never hide** (audit content — affects trust in the answer): caveats, gaps, and uncertainty. "I could only pull his last ~100 stars, so this is partial" or "this is my read, not a hard signal" is not junk — it is what a good assistant says out loud. The veil hides plumbing, never the limits of the answer.
+
+Register example, for "how often does he star things — is this a big deal?":
+
+> Wrong: "Quick note first: `ce-plan` builds implementation plans, so I ignored the template and just answered the question. Here's what the data says..."
+
+Leaks the skill's name, narrates an internal routing decision, apologizes for deviating — the caller sees the tool's machinery.
+
+> Right: "Let me size this up — I'll check how active a starrer he is overall, his recent cadence, and the kinds of repos he tends to star, then weigh where this one lands. [gathers data] Yes, this is a real signal: ..."
+
+Same underlying process; none of the machinery shows. The caller sees thinking about their question.
+
+---
+
+## Step 1: Assess Ambiguity and Research Need
+
+Evaluate two things before planning:
+
+**Would 1-3 quick questions meaningfully improve this plan?**
+
+- **Default: ask 1-3 questions** via Step 1b when the answers would change the plan's structure or content. Always include a final option like "Skip — just make the plan with reasonable assumptions" so the user can opt out instantly.
+- **Skip questions entirely** only when the request already specifies all major variables or the task is simple enough that reasonable assumptions cover it well.
+
+**Research need — does this plan depend on facts that change faster than training data?**
+
+| Research need | Signals | Action |
+|--------------|---------|--------|
+| **None** | Generic, timeless, or conceptual plan (study curriculum methodology, project management approach, personal goal breakdown) | Skip research. Model knowledge is sufficient. After structuring the plan, offer: "I based this on general knowledge. Want me to search for [specific thing research would improve]?" — e.g., sourced recipes, current product recommendations, expert frameworks. Only if the user accepts. |
+| **Recommended** | Plan references specific locations, venues, dates, prices, schedules, seasonal availability, or current events — anything where stale information would break the plan (closed restaurants, changed prices, cancelled events, wrong seasonal dates). | Research before planning. Decompose into 2-5 focused research questions and dispatch parallel web searches. In Claude Code, use the Agent tool with `model: "haiku"` for each search to reduce cost. Collate findings before structuring the plan. |
+
+If the user's or project's active instructions or the live prompt name a model for this subagent, use that model instead of the default tier above. They can name it by the subagent's tier, by its prompt-asset name, or for the subagents being dispatched. Without such an instruction, a model configured for this subagent's role takes precedence over the default tier.
+
+When research is recommended, do it — don't just offer. Stale recommendations (closed restaurants, rethemed attractions, outdated prices) are worse than no recommendations. The user invoked `ce-plan` because they want a good plan, not a disclaimer about training data.
+
+**Research decomposition pattern:**
+1. Identify 2-5 independent research questions based on the task. Good questions target facts the model is least confident about: current prices, hours, availability, recent changes, seasonal specifics.
+2. Dispatch parallel research. Prefer user-named surfaces first per Core Principle 8 in SKILL.md; fall back to web search for questions those surfaces don't cover.
+3. Collate findings into a brief research summary before proceeding to planning.
+
+Example for "plan a date night in Seattle this Saturday":
+- "Best restaurants open late Saturday in Capitol Hill Seattle 2026"
+- "Events happening in Seattle [specific date]"
+- "Seattle waterfront current status and hours"
+
+## Step 1b: Focused Q&A
+
+Ask up to 3 questions targeting the unknowns that would most change the plan. 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. Fall back to numbered options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question.
+
+**How to ask well:**
+- Offer informed options, not open-ended blanks. Instead of "When are you going?", try "Mid-week visits have 30-40% shorter lines — are you flexible on timing?" The question should give the user a frame of reference, not just extract information.
+- Use multi-select when several independent choices can be captured in one question. This is compact and respects the user's time.
+- Always include a final option like **"Skip — just make the plan with reasonable assumptions"** so the user can opt out at any point.
+
+Focus on the unknowns specific to this task that would change what the plan recommends or how it's structured. Do not ask more than 3 — after that, proceed with assumptions for anything remaining.
+
+## Step 2: Structure the Plan
+
+Create a structured plan guided by these quality principles. Do NOT use the software plan template (implementation units, test scenarios, file paths, etc.).
+
+### Format: when to prescribe vs. present options
+
+Not every plan should be a single linear path. Match the format to the task:
+
+| Task type | Best format | Why |
+|-----------|------------|-----|
+| **High personal preference** (food, entertainment, activities, gifts) | Curated options per category — present 2-3 choices and let the user compose | Preferences vary; a single pick may miss. Options respect the user's taste. |
+| **Logical sequence** (study plan, project timeline, multi-day trip logistics) | Single prescriptive path with clear ordering | Sequencing matters; options at each step create decision paralysis. |
+| **Hybrid** (event with fixed structure but variable details) | Fixed structure with choice points marked | The skeleton is set but specific vendors/venues/activities are options. |
+
+Example: A date night plan should present 2-3 restaurant options, 2-3 activity options, and a suggested flow — not pick one restaurant and build the whole evening around it. A study plan should prescribe a single weekly progression — not present 3 different curricula to choose from.
+
+### Formatting: bullets over prose
+
+- Prefer bullets and tables for actionable content (steps, options, logistics, budgets)
+- Use prose only for context, rationale, or explanations that connect the dots
+- Plans are for scanning and executing, not reading cover-to-cover
+
+### Quality principles
+
+- **Actionable steps**: Each step is specific enough to execute without further research
+- **Sequenced by dependency**: Steps are in the right order, with dependencies noted
+- **Time-aware**: When relevant, include timing, durations, deadlines, or phases
+- **Resource-identified**: Specify what's needed — tools, materials, people, budget, locations
+- **Contingency-aware**: For important decisions, note alternatives or what to do if plans change
+- **Appropriately detailed**: Match detail to task complexity. A weekend trip needs less structure than a 3-month curriculum. A dinner plan should be concise, not a 200-line document.
+- **Domain-appropriate format**: Choose a structure that fits the domain:
+  - Itinerary for travel (day-by-day, with times and locations)
+  - Syllabus or curriculum for study plans (topics, resources, milestones)
+  - Runbook for events (timeline, responsibilities, logistics)
+  - Project plan for business or operational tasks (phases, owners, deliverables)
+  - Research plan for investigations (questions, methods, sources)
+  - Options menu for preference-driven tasks (curated picks per category)
+
+## Step 3: Save or Share
+
+After structuring the plan, ask the user how they want to receive it using the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Fall back to numbered options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question.
+
+**Question:** "Plan ready. How would you like to receive it?"
+
+**Options:**
+
+1. **Save to disk** — Write the plan as a markdown file. Ask where:
+   - `<root>/plans/` (only show if this directory exists)
+   - Current working directory
+   - `/tmp`
+   - A custom path
+   - Use filename convention: `YYYY-MM-DD-HHMM-<descriptive-name>-plan.md`, taking `HHMM` from the local wall-clock time at write; reserve the path atomically and, on collision, retry with the smallest available numeric suffix before the extension rather than overwriting
+   - Start the document with a `# Title` heading, followed by `Created: YYYY-MM-DD` on the next line. No YAML frontmatter.
+
+2. **Publish to Proof — shareable link** — Publish the doc to Every's Proof editor and get a shareable link to read, comment on, or share with others. Load the `ce-proof` skill to create the shared document and return the URL. One-way: nothing syncs back to disk.
+
+3. **Save to disk AND publish to Proof** — Do both: write the markdown file to disk and publish a shareable Proof copy for review. The local file stays canonical.
+
+Do not offer `ce-work` (software-only) or issue creation (not applicable to non-software plans).

package/skills/ce-plan/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"