fix!: file-reference prompt for oversized pastes (1-hour hang fix) (v0.4.10)

User repro'd a 1-hour silent hang on the phase 1 review stage:
\`(1484s, idle 1478s) phase 1 first review: reviewer running …\` —
6 seconds of activity at spawn, then ZERO PTY bytes for 24+ minutes
until they Ctrl+C'd.

Root cause: the composite multi-dimension review prompt is ~5× a
normal iteration prompt (5 dimensions × full review_template ×
substituted agent_template body) — easily 30–50 KB. drive_agent
pasted it through bracketed-paste in a single write. claude's REPL
input handler either silently truncates / rejects / freezes on a
30 KB+ paste; the PTY then goes completely silent because claude
isn't processing any input.

Fix: drive_agent's protocol preamble now switches to file-reference
mode when the task prompt is >8 KiB (INLINE_PASTE_SOFT_CAP). The
agent gets a tiny (<1 KB) instruction pasted into the PTY:

  RALPHTERM PROTOCOL …
  1. Read your task instructions from this file:
       /workspace/.ralphterm/iteration-output/<nonce>.prompt.txt
  2. Perform the task it describes.
  3. Write your response to /workspace/.ralphterm/iteration-output/<nonce>.md
     between <<<BEGIN>>> and <<<END>>> markers.

The agent reads the prompt via its own Read tool — one short request
that fits any PTY buffer. We already wrote the full inline-form
prompt to .ralphterm/iteration-output/<nonce>.prompt.txt for the
fixtures' RALPHTERM_PROMPT_FILE env-var path, so the file is
guaranteed to be there.

Small prompts (implementer iterations, ~5–8 KB) keep the old
inline-paste path: no extra tool call, no behaviour change.

Tests:
  - build_prompt_includes_path_and_task_text retained, updated for
    the new 4-arg signature.
  - NEW build_prompt_uses_file_reference_for_large_prompts asserts:
      * pasted form < 1 KB
      * contains the prompt_path
      * does NOT contain the huge task body
      * contains the output_path

build_inline_prompt_with_protocol extracted as a sibling helper
because both the always-written-to-disk path and the small-prompt
inline path use the same body.

Author: hetoku

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "ralphterm"
-version = "0.4.9"
+version = "0.4.10"
 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

@@ -121,9 +121,14 @@ pub async fn drive_agent(spec: AgentSpec<'_>) -> Result<AgentRun> {
     let prompt_path = output_dir.join(format!("{nonce}.prompt.txt"));
     let transcript_path = output_dir.join(format!("{nonce}.transcript.txt"));
 
-    let prompt = build_prompt_with_protocol(spec.task_prompt, &nonce, &output_path);
-    std::fs::write(&prompt_path, &prompt)
+    // ALWAYS write the full inline-form wrapped prompt to disk so the
+    // agent (or a curious operator) can read it. The pasted prompt may
+    // either be this full text (small prompts) or a short pointer to
+    // this file (large prompts) — see build_prompt_with_protocol.
+    let inline_prompt = build_inline_prompt_with_protocol(spec.task_prompt, &nonce, &output_path);
+    std::fs::write(&prompt_path, &inline_prompt)
         .with_context(|| format!("write {}", prompt_path.display()))?;
+    let prompt = build_prompt_with_protocol(spec.task_prompt, &nonce, &output_path, &prompt_path);
     // Touch the transcript so `tail -f` works the moment the run starts.
     let _ = std::fs::File::create(&transcript_path);
 
@@ -453,7 +458,15 @@ enum DriverShutdown {
     Cancelled,
 }
 
-fn build_prompt_with_protocol(task_prompt: &str, nonce: &str, output_path: &Path) -> String {
+/// Soft cap on inline-pasted prompts (bytes). Above this, we paste a
+/// short instruction that points at the prompt file on disk instead.
+/// 8 KiB is well under typical PTY buffer limits and observed to be a
+/// safe paste size for claude's REPL.
+const INLINE_PASTE_SOFT_CAP: usize = 8 * 1024;
+
+/// The full inline form of the wrapped prompt. Always written to
+/// `prompt_path` so the file-reference path has something to read.
+fn build_inline_prompt_with_protocol(task_prompt: &str, nonce: &str, output_path: &Path) -> String {
     format!(
         "RALPHTERM PROTOCOL — you MUST follow this exactly:\n\
          When you have a final response for this iteration, write the response to this file:\n\
@@ -470,6 +483,40 @@ fn build_prompt_with_protocol(task_prompt: &str, nonce: &str, output_path: &Path
     )
 }
 
+fn build_prompt_with_protocol(
+    task_prompt: &str,
+    nonce: &str,
+    output_path: &Path,
+    prompt_path: &Path,
+) -> String {
+    // For large prompts (composite multi-dimension reviews especially),
+    // pasting tens of kilobytes through bracketed-paste is unreliable —
+    // user reproed a 1-hour silent hang on a ~30 KB composite prompt
+    // (claude's REPL stopped responding after the paste; zero PTY
+    // bytes for 24+ minutes idle). Above 8 KiB we paste a tiny
+    // instruction that tells the agent to read the prompt from disk
+    // instead. The agent then reads the file via its own tool, which
+    // is a single short request that doesn't blow any input buffer.
+    if task_prompt.len() > INLINE_PASTE_SOFT_CAP {
+        return format!(
+            "RALPHTERM PROTOCOL — you MUST follow this exactly:\n\n\
+             1. Read your task instructions from this file (it's too large to paste inline):\n\
+                    {prompt}\n\
+             2. Perform the task it describes.\n\
+             3. When you have a final response, write it to this file:\n\
+                    {out}\n\
+                The file MUST start with the literal line `<<<BEGIN>>>` on its own line, \
+                followed by your response (a concise account of what was done), and end with \
+                the literal line `<<<END>>>` on its own line. After writing the file you do \
+                not need to print anything special — the orchestrator polls the file. \
+                (Reference nonce: {nonce})\n",
+            prompt = prompt_path.display(),
+            out = output_path.display(),
+        );
+    }
+    build_inline_prompt_with_protocol(task_prompt, nonce, output_path)
+}
+
 fn make_nonce() -> String {
     let nanos = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -604,7 +651,12 @@ mod tests {
 
     #[test]
     fn build_prompt_includes_path_and_task_text() {
-        let p = build_prompt_with_protocol("DO THE THING", "abc123", Path::new("/tmp/x/abc123.md"));
+        let p = build_prompt_with_protocol(
+            "DO THE THING",
+            "abc123",
+            Path::new("/tmp/x/abc123.md"),
+            Path::new("/tmp/x/abc123.prompt.txt"),
+        );
         assert!(p.contains("/tmp/x/abc123.md"));
         assert!(p.contains("<<<BEGIN>>>"));
         assert!(p.contains("<<<END>>>"));
@@ -613,6 +665,30 @@ mod tests {
         assert!(p.contains("abc123"));
     }
 
+    #[test]
+    fn build_prompt_uses_file_reference_for_large_prompts() {
+        // Reproduces the user's 24-minute-silent-hang scenario: a
+        // composite multi-dimension review prompt that's tens of KB.
+        // Above INLINE_PASTE_SOFT_CAP we paste a short pointer to the
+        // prompt file instead of the prompt body.
+        let huge = "X".repeat(INLINE_PASTE_SOFT_CAP + 1);
+        let p = build_prompt_with_protocol(
+            &huge,
+            "abc123",
+            Path::new("/tmp/x/abc123.md"),
+            Path::new("/tmp/x/abc123.prompt.txt"),
+        );
+        // Pasted form should be tiny (instruction only, no body).
+        assert!(
+            p.len() < 1024,
+            "large-prompt form should be a short pointer, got {} bytes",
+            p.len()
+        );
+        assert!(p.contains("/tmp/x/abc123.prompt.txt"));
+        assert!(p.contains("/tmp/x/abc123.md"));
+        assert!(!p.contains(&huge));
+    }
+
     #[test]
     fn nonce_is_unique_across_calls_within_a_process() {
         let a = make_nonce();