fix!: provider wrappers — read prompt from RALPHTERM_PROMPT_FILE, write to RALPHTERM_OUTPUT_FILE (real reviewer-hang fix) (v0.4.11)

ACTUAL root cause of the multi-hour review-stage hang the user
reported (v0.4.10's paste-size fix was orthogonal):

The default reviewer is scripts/wrappers/codex.sh. The wrapper did:

    prompt=\$(cat)
    ...
    "\$PROVIDER_CMD" exec ... "\$prompt" ...

\`cat\` reads stdin until EOF. drive_agent's PTY writer never closes
(it stays alive so we can send /exit at teardown). Result: cat
deadlocks on the very first line of the wrapper. codex never spawns.
Zero PTY bytes. Spinner climbs idle indefinitely.

This is a regression vector that was created when v0.3 introduced
drive_agent — drive_agent's keep-writer-open contract is incompatible
with stdin-reading wrappers. Implementer fixtures (fake-agent.sh
etc.) were updated to dual-mode (RALPHTERM_PROMPT_FILE env var) but
the production wrappers were missed.

Rewrote all four wrappers (codex.sh, copilot.sh, gemini.sh,
opencode.sh) to be drive_agent-aware:

  1. Prompt: read from \$RALPHTERM_PROMPT_FILE if set (no stdin
     touch → no deadlock). Fall back to stdin for the legacy
     non-drive_agent call path.
  2. Output: capture the provider's stdout/stderr to a tempfile.
     Mirror it to stdout (live transcript stays useful). If
     \$RALPHTERM_OUTPUT_FILE is set, write the captured output
     between <<<BEGIN>>>/<<<END>>> markers with a trailing
     REVIEW_PASS or REVIEW_FAIL rc=N — exactly what
     review_phases.rs::external_review_decision looks for.

Implementer path (claude direct) unaffected — those go through
drive_agent's bracketed-paste, not a wrapper script.

Tests stay green (16/17 fake-agent, all wrappers_compat, all
mode_compat, etc.).

Author: hetoku

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "ralphterm"
-version = "0.4.10"
+version = "0.4.11"
 edition = "2021"
 rust-version = "1.85"
 description = "Programmable PTY for the official Claude Code and Codex CLIs. Runs long multi-task plans unattended — iterates, validates, commits per task, and gates merge behind a parallel review pipeline."

Cargo.toml

@@ -5,21 +5,31 @@
 # Auth env:
 #   OPENAI_API_KEY - required for codex to authenticate against OpenAI APIs
 # Optional env:
-#   CLAUDE_MODEL      - forwarded as `--model <value>` so plans authored for
-#                       ralphex's model selection knob keep working.
+#   CLAUDE_MODEL      - forwarded as `--model <value>`.
 #   PROVIDER_OVERRIDE - override the binary name (mostly for tests).
 #
-# Behaviour: reads the prompt from stdin and invokes `codex exec
-# "<prompt>"` (codex's non-interactive subcommand). Bare `codex` requires
-# a TTY and refuses to read piped stdin, so the wrapper must use `exec`.
-# Emits COMPLETED on success or FAILED on a non-zero exit.
+# IO contract: this wrapper supports both ralphterm's v0.3+ file-handoff
+# (env vars RALPHTERM_PROMPT_FILE + RALPHTERM_OUTPUT_FILE) AND the
+# legacy stdin/stdout streaming path. Drive_agent (v0.4+) sets the env
+# vars; older callers pipe the prompt on stdin and watch for COMPLETED
+# on stdout.
+#
+# The legacy `prompt=$(cat)` path used to deadlock against drive_agent
+# because drive_agent's PTY writer never closes (it keeps the writer
+# alive to send /exit on teardown). With RALPHTERM_PROMPT_FILE set we
+# read the prompt from disk and never touch the PTY stdin.
 set -eu
 
 PROVIDER_CMD="${PROVIDER_OVERRIDE:-codex}"
 
-prompt=$(cat)
+if [ -n "${RALPHTERM_PROMPT_FILE:-}" ]; then
+  prompt=$(cat "$RALPHTERM_PROMPT_FILE")
+else
+  prompt=$(cat)
+fi
+
 if [ -z "${prompt}" ]; then
-  printf 'FAILED: no prompt on stdin\n' >&2
+  printf 'FAILED: no prompt provided\n' >&2
   exit 1
 fi
 
@@ -30,24 +40,47 @@ if [ -n "${CLAUDE_MODEL:-}" ]; then
   model_arg="--model ${CLAUDE_MODEL}"
 fi
 
-# If PROVIDER_OVERRIDE is set, the test shim expects the prompt on stdin —
-# stream it through instead of passing as argv so the shim's
-# `prompt=$(cat)` pattern keeps working. Otherwise drive the real codex
-# via its non-interactive `exec` subcommand with the prompt as the final
-# argv, and close stdin so codex doesn't block waiting for input that
-# never comes (the PTY stdin stays open otherwise).
+# Capture codex's output to a tempfile so we can both stream it to the
+# PTY (for live transcripts) and write it into the file-handoff target.
+codex_out=$(mktemp)
+cleanup() { rm -f "$codex_out"; }
+trap 'kill "${child:-0}" 2>/dev/null || true; cleanup; exit 130' INT TERM
+
 if [ -n "${PROVIDER_OVERRIDE:-}" ]; then
   # shellcheck disable=SC2086
-  printf '%s\n' "$prompt" | "$PROVIDER_CMD" $model_arg &
+  printf '%s\n' "$prompt" | "$PROVIDER_CMD" $model_arg > "$codex_out" 2>&1 &
 else
   # shellcheck disable=SC2086
-  "$PROVIDER_CMD" exec $model_arg "$prompt" </dev/null &
+  "$PROVIDER_CMD" exec $model_arg "$prompt" </dev/null > "$codex_out" 2>&1 &
 fi
 child=$!
 set +e
 wait "$child"
 rc=$?
 set -e
+
+# Mirror codex's output to the PTY so the live transcript file (and
+# any --serve dashboard watching the PTY) sees what codex said.
+cat "$codex_out"
+
+if [ -n "${RALPHTERM_OUTPUT_FILE:-}" ]; then
+  # Write the file-handoff response. drive_agent's review decision
+  # logic recognises REVIEW_PASS / NO ISSUES FOUND on success and
+  # REVIEW_FAIL on failure (src/review_phases.rs::external_review_decision).
+  {
+    printf '<<<BEGIN>>>\n'
+    cat "$codex_out"
+    printf '\n'
+    if [ "$rc" -eq 0 ]; then
+      printf 'REVIEW_PASS\n'
+    else
+      printf 'REVIEW_FAIL rc=%s\n' "$rc"
+    fi
+    printf '<<<END>>>\n'
+  } > "$RALPHTERM_OUTPUT_FILE"
+fi
+
+cleanup
 if [ "$rc" -eq 0 ]; then
   printf '\nCOMPLETED\n'
 else

scripts/wrappers/codex.sh

@@ -17,14 +17,20 @@ set -eu
 
 PROVIDER_CMD="${PROVIDER_OVERRIDE:-gh}"
 
-prompt=$(cat)
+if [ -n "${RALPHTERM_PROMPT_FILE:-}" ]; then
+  prompt=$(cat "$RALPHTERM_PROMPT_FILE")
+else
+  prompt=$(cat)
+fi
+
 if [ -z "${prompt}" ]; then
-  printf 'FAILED: no prompt on stdin\n' >&2
+  printf 'FAILED: no prompt provided\n' >&2
   exit 1
 fi
 
 tmpfile=$(mktemp)
-trap 'rm -f "$tmpfile"' EXIT
+provider_out=$(mktemp)
+trap 'rm -f "$tmpfile" "$provider_out"' EXIT
 trap 'kill "${child:-0}" 2>/dev/null || true; exit 130' INT TERM
 
 printf '%s\n' "$prompt" > "$tmpfile"
@@ -36,16 +42,33 @@ fi
 
 if [ "$PROVIDER_CMD" = "gh" ]; then
   # shellcheck disable=SC2086
-  "$PROVIDER_CMD" copilot suggest $model_arg < "$tmpfile" &
+  "$PROVIDER_CMD" copilot suggest $model_arg < "$tmpfile" > "$provider_out" 2>&1 &
 else
   # shellcheck disable=SC2086
-  "$PROVIDER_CMD" $model_arg < "$tmpfile" &
+  "$PROVIDER_CMD" $model_arg < "$tmpfile" > "$provider_out" 2>&1 &
 fi
 child=$!
 set +e
 wait "$child"
 rc=$?
 set -e
+
+cat "$provider_out"
+
+if [ -n "${RALPHTERM_OUTPUT_FILE:-}" ]; then
+  {
+    printf '<<<BEGIN>>>\n'
+    cat "$provider_out"
+    printf '\n'
+    if [ "$rc" -eq 0 ]; then
+      printf 'REVIEW_PASS\n'
+    else
+      printf 'REVIEW_FAIL rc=%s\n' "$rc"
+    fi
+    printf '<<<END>>>\n'
+  } > "$RALPHTERM_OUTPUT_FILE"
+fi
+
 if [ "$rc" -eq 0 ]; then
   printf '\nCOMPLETED\n'
 else

scripts/wrappers/copilot.sh

@@ -17,14 +17,20 @@ set -eu
 
 PROVIDER_CMD="${PROVIDER_OVERRIDE:-gemini}"
 
-prompt=$(cat)
+if [ -n "${RALPHTERM_PROMPT_FILE:-}" ]; then
+  prompt=$(cat "$RALPHTERM_PROMPT_FILE")
+else
+  prompt=$(cat)
+fi
+
 if [ -z "${prompt}" ]; then
-  printf 'FAILED: no prompt on stdin\n' >&2
+  printf 'FAILED: no prompt provided\n' >&2
   exit 1
 fi
 
 tmpfile=$(mktemp)
-trap 'rm -f "$tmpfile"' EXIT
+provider_out=$(mktemp)
+trap 'rm -f "$tmpfile" "$provider_out"' EXIT
 trap 'kill "${child:-0}" 2>/dev/null || true; exit 130' INT TERM
 
 printf '%s\n' "$prompt" > "$tmpfile"
@@ -35,12 +41,29 @@ if [ -n "${CLAUDE_MODEL:-}" ]; then
 fi
 
 # shellcheck disable=SC2086
-"$PROVIDER_CMD" $model_arg < "$tmpfile" &
+"$PROVIDER_CMD" $model_arg < "$tmpfile" > "$provider_out" 2>&1 &
 child=$!
 set +e
 wait "$child"
 rc=$?
 set -e
+
+cat "$provider_out"
+
+if [ -n "${RALPHTERM_OUTPUT_FILE:-}" ]; then
+  {
+    printf '<<<BEGIN>>>\n'
+    cat "$provider_out"
+    printf '\n'
+    if [ "$rc" -eq 0 ]; then
+      printf 'REVIEW_PASS\n'
+    else
+      printf 'REVIEW_FAIL rc=%s\n' "$rc"
+    fi
+    printf '<<<END>>>\n'
+  } > "$RALPHTERM_OUTPUT_FILE"
+fi
+
 if [ "$rc" -eq 0 ]; then
   printf '\nCOMPLETED\n'
 else

scripts/wrappers/gemini.sh

@@ -18,14 +18,20 @@ set -eu
 
 PROVIDER_CMD="${PROVIDER_OVERRIDE:-opencode}"
 
-prompt=$(cat)
+if [ -n "${RALPHTERM_PROMPT_FILE:-}" ]; then
+  prompt=$(cat "$RALPHTERM_PROMPT_FILE")
+else
+  prompt=$(cat)
+fi
+
 if [ -z "${prompt}" ]; then
-  printf 'FAILED: no prompt on stdin\n' >&2
+  printf 'FAILED: no prompt provided\n' >&2
   exit 1
 fi
 
 tmpfile=$(mktemp)
-trap 'rm -f "$tmpfile"' EXIT
+provider_out=$(mktemp)
+trap 'rm -f "$tmpfile" "$provider_out"' EXIT
 trap 'kill "${child:-0}" 2>/dev/null || true; exit 130' INT TERM
 
 printf '%s\n' "$prompt" > "$tmpfile"
@@ -36,12 +42,29 @@ if [ -n "${CLAUDE_MODEL:-}" ]; then
 fi
 
 # shellcheck disable=SC2086
-"$PROVIDER_CMD" $model_arg < "$tmpfile" &
+"$PROVIDER_CMD" $model_arg < "$tmpfile" > "$provider_out" 2>&1 &
 child=$!
 set +e
 wait "$child"
 rc=$?
 set -e
+
+cat "$provider_out"
+
+if [ -n "${RALPHTERM_OUTPUT_FILE:-}" ]; then
+  {
+    printf '<<<BEGIN>>>\n'
+    cat "$provider_out"
+    printf '\n'
+    if [ "$rc" -eq 0 ]; then
+      printf 'REVIEW_PASS\n'
+    else
+      printf 'REVIEW_FAIL rc=%s\n' "$rc"
+    fi
+    printf '<<<END>>>\n'
+  } > "$RALPHTERM_OUTPUT_FILE"
+fi
+
 if [ "$rc" -eq 0 ]; then
   printf '\nCOMPLETED\n'
 else