oh-my-codex-pennix 0.18.13

package/crates/omx-explore/src/main.rs

@@ -0,0 +1,2972 @@
+use std::env;
+use std::ffi::OsString;
+use std::fs::{
+    canonicalize, create_dir_all, read_to_string, remove_dir_all, remove_file, write, File,
+};
+use std::io::{self, BufRead, BufReader, Read};
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, Output, Stdio};
+use std::sync::mpsc::{self, Receiver, RecvTimeoutError, TryRecvError};
+use std::thread;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+const CODEX_BIN_ENV: &str = "OMX_EXPLORE_CODEX_BIN";
+const HARNESS_ROOT_ENV: &str = "OMX_EXPLORE_ROOT";
+const CODEX_TIMEOUT_MS_ENV: &str = "OMX_EXPLORE_CODEX_TIMEOUT_MS";
+const PROCESS_LIMIT_ENV: &str = "OMX_EXPLORE_PROCESS_LIMIT";
+const CODEX_OUTPUT_LIMIT_BYTES_ENV: &str = "OMX_EXPLORE_CODEX_OUTPUT_LIMIT_BYTES";
+const INTERNAL_DIRECT_WRAPPER_FLAG: &str = "--internal-allowlist-direct";
+const INTERNAL_SHELL_WRAPPER_FLAG: &str = "--internal-allowlist-shell";
+const TEMP_ALLOWLIST_DIR_PREFIX: &str = "omx-explore-allowlist-";
+const DEFAULT_CODEX_TIMEOUT_MS: u64 = 180_000;
+const DEFAULT_PROCESS_LIMIT: usize = 96;
+const DEFAULT_CODEX_OUTPUT_LIMIT_BYTES: usize = 8 * 1024 * 1024;
+const PROCESS_LIMIT_POLL_MS: u64 = 100;
+const PROCESS_TERMINATION_GRACE_MS: u64 = 500;
+const PIPE_READER_READY_GRACE_MS: u64 = 25;
+const PIPE_READER_JOIN_GRACE_MS: u64 = 500;
+const EXPLORE_SUBPROCESS_ENV_VARS_TO_SCRUB: &[&str] = &[
+    "BASH_ENV",
+    "ENV",
+    "PROMPT_COMMAND",
+    "NODE_OPTIONS",
+    "SHELLOPTS",
+    "BASHOPTS",
+    "GREP_OPTIONS",
+    "GREP_COLORS",
+];
+const WINDOWS_UNSUPPORTED_ALLOWLIST_MESSAGE: &str =
+    "omx explore built-in harness is not ready on Windows because its allowlist runtime relies on POSIX sh/bash wrappers. Set OMX_EXPLORE_BIN to a compatible custom harness, prefer `omx sparkshell` for shell-native read-only lookups, or run `omx doctor` for readiness details.";
+
+const ALLOWED_DIRECT_COMMANDS: &[&str] = &[
+    "rg", "grep", "ls", "find", "wc", "cat", "head", "tail", "pwd", "printf",
+];
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Args {
+    cwd: PathBuf,
+    prompt: String,
+    prompt_file: PathBuf,
+    instructions_file: PathBuf,
+    spark_model: String,
+    fallback_model: String,
+}
+
+#[derive(Debug)]
+struct AttemptResult {
+    status_code: i32,
+    stderr: String,
+    output_markdown: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct FallbackEvent {
+    from_model: String,
+    to_model: String,
+    exit_code: i32,
+    stderr: String,
+}
+
+#[derive(Debug)]
+struct AllowlistEnvironment {
+    bin_dir: PathBuf,
+    shell_path: PathBuf,
+    sandbox_bin_dir: Option<PathBuf>,
+    _root: TempDirGuard,
+}
+
+#[derive(Debug)]
+struct TempDirGuard {
+    path: PathBuf,
+}
+
+impl Drop for TempDirGuard {
+    fn drop(&mut self) {
+        let _ = remove_dir_all(&self.path);
+    }
+}
+
+fn main() {
+    if let Err(error) = dispatch_main() {
+        eprintln!("[omx explore] {}", error);
+        std::process::exit(1);
+    }
+}
+
+fn dispatch_main() -> Result<(), String> {
+    let mut args = env::args_os().skip(1);
+    match args.next() {
+        Some(flag) if flag == INTERNAL_DIRECT_WRAPPER_FLAG => {
+            run_internal_direct_wrapper(args)?;
+            Ok(())
+        }
+        Some(flag) if flag == INTERNAL_SHELL_WRAPPER_FLAG => {
+            run_internal_shell_wrapper(args)?;
+            Ok(())
+        }
+        Some(first) => run_with_leading_arg(first, args),
+        None => run(),
+    }
+}
+
+fn run_with_leading_arg<I>(first: OsString, remaining: I) -> Result<(), String>
+where
+    I: Iterator<Item = OsString>,
+{
+    let args = std::iter::once(first).chain(remaining);
+    run_with_args(args)
+}
+
+fn run() -> Result<(), String> {
+    run_with_args(env::args_os().skip(1))
+}
+
+fn run_with_args<I>(args: I) -> Result<(), String>
+where
+    I: Iterator<Item = OsString>,
+{
+    let args = parse_args(args)?;
+    let prompt_contract = read_to_string(&args.prompt_file).map_err(|err| {
+        format!(
+            "failed to read explore prompt contract {}: {err}",
+            args.prompt_file.display()
+        )
+    })?;
+
+    let spark_attempt = invoke_codex(&args, &args.spark_model, &prompt_contract)
+        .map_err(|err| format!("spark attempt failed to launch: {err}"))?;
+    if spark_attempt.status_code == 0 {
+        print_attempt_output(spark_attempt)?;
+        return Ok(());
+    }
+
+    let fallback_event = FallbackEvent {
+        from_model: args.spark_model.clone(),
+        to_model: args.fallback_model.clone(),
+        exit_code: spark_attempt.status_code,
+        stderr: spark_attempt.stderr.clone(),
+    };
+    emit_model_fallback_event(&fallback_event);
+
+    let fallback_attempt = invoke_codex(&args, &args.fallback_model, &prompt_contract)
+        .map_err(|err| format!("fallback attempt failed to launch: {err}"))?;
+    if fallback_attempt.status_code == 0 {
+        print_attempt_output_with_fallback(fallback_attempt, &fallback_event)?;
+        return Ok(());
+    }
+
+    Err(format!(
+        "both spark (`{}`) and fallback (`{}`) attempts failed (codes {} / {}). Last stderr: {}",
+        args.spark_model,
+        args.fallback_model,
+        spark_attempt.status_code,
+        fallback_attempt.status_code,
+        fallback_attempt.stderr.trim()
+    ))
+}
+
+fn print_attempt_output(attempt: AttemptResult) -> Result<(), String> {
+    print_attempt_output_with_optional_fallback(attempt, None)
+}
+
+fn print_attempt_output_with_fallback(
+    attempt: AttemptResult,
+    fallback: &FallbackEvent,
+) -> Result<(), String> {
+    print_attempt_output_with_optional_fallback(attempt, Some(fallback))
+}
+
+fn print_attempt_output_with_optional_fallback(
+    attempt: AttemptResult,
+    fallback: Option<&FallbackEvent>,
+) -> Result<(), String> {
+    if let Some(markdown) = attempt.output_markdown {
+        if let Some(event) = fallback {
+            print!("{}", fallback_output_notice(event));
+            if !markdown.starts_with('\n') {
+                println!();
+            }
+        }
+        print!("{}", markdown);
+        return Ok(());
+    }
+    Err(
+        "codex completed successfully but did not produce the expected markdown output artifact"
+            .to_string(),
+    )
+}
+
+fn emit_model_fallback_event(event: &FallbackEvent) {
+    eprintln!("{}", fallback_attempt_event_message(event));
+    eprintln!(
+        "[omx explore] spark model `{}` unavailable or failed (exit {}). Falling back to `{}`.",
+        event.from_model, event.exit_code, event.to_model
+    );
+    if !event.stderr.trim().is_empty() {
+        eprintln!("[omx explore] spark stderr: {}", event.stderr.trim());
+    }
+}
+
+fn fallback_attempt_event_message(event: &FallbackEvent) -> String {
+    format!(
+        "[omx explore] fallback-attempt=model from=`{}` to=`{}` reason=spark_attempt_failed exit={}. Cost/behavior boundary changed if fallback succeeds; stdout fallback notice is emitted only after successful fallback output.",
+        event.from_model, event.to_model, event.exit_code
+    )
+}
+
+fn fallback_output_notice(event: &FallbackEvent) -> String {
+    format!(
+        "## OMX Explore fallback\n- fallback: model\n- from: `{}`\n- to: `{}`\n- reason: spark attempt failed with exit {}\n- boundary: cost/behavior may differ from the low-cost spark path\n",
+        event.from_model, event.to_model, event.exit_code
+    )
+}
+
+fn parse_args<I>(mut args: I) -> Result<Args, String>
+where
+    I: Iterator<Item = OsString>,
+{
+    let mut cwd: Option<PathBuf> = None;
+    let mut prompt: Option<String> = None;
+    let mut prompt_file: Option<PathBuf> = None;
+    let mut instructions_file: Option<PathBuf> = None;
+    let mut spark_model: Option<String> = None;
+    let mut fallback_model: Option<String> = None;
+
+    while let Some(token) = args.next() {
+        let token_str = token.to_string_lossy();
+        match token_str.as_ref() {
+            "--cwd" => cwd = Some(PathBuf::from(next_required(&mut args, "--cwd")?)),
+            "--prompt" => prompt = Some(next_required(&mut args, "--prompt")?),
+            "--prompt-file" => {
+                prompt_file = Some(PathBuf::from(next_required(&mut args, "--prompt-file")?))
+            }
+            "--instructions-file" => {
+                instructions_file = Some(PathBuf::from(next_required(
+                    &mut args,
+                    "--instructions-file",
+                )?))
+            }
+            "--model-spark" => spark_model = Some(next_required(&mut args, "--model-spark")?),
+            "--model-fallback" => {
+                fallback_model = Some(next_required(&mut args, "--model-fallback")?)
+            }
+            "--help" | "-h" => return Err(usage().to_string()),
+            other => return Err(format!("unknown argument: {other}\n{}", usage())),
+        }
+    }
+
+    let args = Args {
+        cwd: cwd.ok_or_else(|| format!("missing --cwd\n{}", usage()))?,
+        prompt: prompt.ok_or_else(|| format!("missing --prompt\n{}", usage()))?,
+        prompt_file: prompt_file.ok_or_else(|| format!("missing --prompt-file\n{}", usage()))?,
+        instructions_file: instructions_file
+            .ok_or_else(|| format!("missing --instructions-file\n{}", usage()))?,
+        spark_model: spark_model.ok_or_else(|| format!("missing --model-spark\n{}", usage()))?,
+        fallback_model: fallback_model
+            .ok_or_else(|| format!("missing --model-fallback\n{}", usage()))?,
+    };
+
+    Ok(args)
+}
+
+fn next_required<I>(args: &mut I, flag: &str) -> Result<String, String>
+where
+    I: Iterator<Item = OsString>,
+{
+    args.next()
+        .map(|value| value.to_string_lossy().trim().to_string())
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| format!("missing value after {flag}\n{}", usage()))
+}
+
+fn usage() -> &'static str {
+    "Usage: omx-explore --cwd <dir> --prompt <text> --prompt-file <explore-prompt.md> --instructions-file <AGENTS.md> --model-spark <model> --model-fallback <model>"
+}
+
+#[allow(unknown_lints, clippy::io_other_error)]
+fn invoke_codex(args: &Args, model: &str, prompt_contract: &str) -> io::Result<AttemptResult> {
+    let codex_launch = resolve_codex_launch();
+    let allowlist =
+        prepare_allowlist_environment().map_err(|err| io::Error::new(io::ErrorKind::Other, err))?;
+    let output_path = temp_output_path();
+    let final_prompt = compose_exec_prompt(&args.prompt, prompt_contract);
+    let mut command = Command::new(&codex_launch.program);
+    command.args(&codex_launch.leading_args);
+    command
+        .arg("exec")
+        .arg("-C")
+        .arg(&args.cwd)
+        .args(codex_support_dir_args())
+        .arg("-m")
+        .arg(model)
+        .arg("-s")
+        .arg("read-only")
+        .arg("-c")
+        .arg("model_reasoning_effort=\"low\"")
+        .arg("-c")
+        .arg(format!(
+            "model_instructions_file=\"{}\"",
+            escape_toml_string(&args.instructions_file.display().to_string())
+        ))
+        .arg("-c")
+        .arg("shell_environment_policy.inherit=all")
+        .arg("--skip-git-repo-check")
+        .arg("-o")
+        .arg(&output_path)
+        .arg(&final_prompt)
+        .env(HARNESS_ROOT_ENV, &args.cwd)
+        .env(
+            "PATH",
+            build_codex_path(&allowlist.bin_dir, allowlist.sandbox_bin_dir.as_deref())
+                .map_err(|err| io::Error::new(io::ErrorKind::Other, err))?,
+        )
+        .env("SHELL", &allowlist.shell_path);
+    sanitize_explore_subprocess_env(&mut command);
+    let timeout = codex_timeout();
+    let output = run_command_with_timeout(command, timeout)?;
+
+    let markdown = read_to_string(&output_path).ok();
+    let _ = remove_file(&output_path);
+    match output {
+        TimedCommandOutput::Completed(output) => Ok(AttemptResult {
+            status_code: output.status.code().unwrap_or(1),
+            stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+            output_markdown: markdown,
+        }),
+        TimedCommandOutput::TimedOut { stderr } => Ok(AttemptResult {
+            status_code: 124,
+            stderr: format!(
+                "[omx explore] codex exec timed out after {}ms; terminated process tree{}{}",
+                timeout.as_millis(),
+                if stderr.trim().is_empty() {
+                    ""
+                } else {
+                    ". stderr before timeout: "
+                },
+                stderr.trim()
+            ),
+            output_markdown: None,
+        }),
+        TimedCommandOutput::ProcessLimitExceeded {
+            stderr,
+            process_count,
+            process_limit,
+        } => Ok(AttemptResult {
+            status_code: 125,
+            stderr: format!(
+                "[omx explore] codex exec exceeded per-run process limit ({process_count}>{process_limit}); terminated process tree to avoid runaway shell storms{}{}",
+                if stderr.trim().is_empty() {
+                    ""
+                } else {
+                    ". stderr before termination: "
+                },
+                stderr.trim()
+            ),
+            output_markdown: None,
+        }),
+        TimedCommandOutput::OutputLimitExceeded {
+            stderr,
+            output_limit,
+            stream,
+        } => Ok(AttemptResult {
+            status_code: 126,
+            stderr: format!(
+                "[omx explore] codex exec exceeded subprocess {stream} output limit ({output_limit} bytes); terminated process tree to avoid unbounded memory growth{}{}",
+                if stderr.trim().is_empty() {
+                    ""
+                } else {
+                    ". stderr before termination: "
+                },
+                stderr.trim()
+            ),
+            output_markdown: None,
+        }),
+    }
+}
+
+#[derive(Debug)]
+enum TimedCommandOutput {
+    Completed(Output),
+    TimedOut {
+        stderr: String,
+    },
+    ProcessLimitExceeded {
+        stderr: String,
+        process_count: usize,
+        process_limit: usize,
+    },
+    OutputLimitExceeded {
+        stderr: String,
+        output_limit: usize,
+        stream: &'static str,
+    },
+}
+
+fn codex_timeout() -> Duration {
+    let timeout_ms = env::var(CODEX_TIMEOUT_MS_ENV)
+        .ok()
+        .and_then(|value| value.trim().parse::<u64>().ok())
+        .filter(|value| *value > 0)
+        .unwrap_or(DEFAULT_CODEX_TIMEOUT_MS);
+    Duration::from_millis(timeout_ms)
+}
+
+fn codex_output_limit_bytes() -> usize {
+    env::var(CODEX_OUTPUT_LIMIT_BYTES_ENV)
+        .ok()
+        .and_then(|value| value.trim().parse::<usize>().ok())
+        .filter(|value| *value > 0)
+        .unwrap_or(DEFAULT_CODEX_OUTPUT_LIMIT_BYTES)
+}
+
+fn process_limit() -> usize {
+    env::var(PROCESS_LIMIT_ENV)
+        .ok()
+        .and_then(|value| value.trim().parse::<usize>().ok())
+        .filter(|value| *value > 0)
+        .unwrap_or(DEFAULT_PROCESS_LIMIT)
+}
+
+fn run_command_with_timeout(
+    mut command: Command,
+    timeout: Duration,
+) -> io::Result<TimedCommandOutput> {
+    command.stdout(Stdio::piped()).stderr(Stdio::piped());
+    configure_process_group(&mut command);
+    let mut child = command.spawn()?;
+
+    let output_limit = codex_output_limit_bytes();
+    let mut stdout_reader = spawn_pipe_reader("stdout", child.stdout.take(), output_limit);
+    let mut stderr_reader = spawn_pipe_reader("stderr", child.stderr.take(), output_limit);
+
+    let deadline = Instant::now() + timeout;
+    let process_limit = process_limit();
+    let mut next_process_limit_poll = Instant::now() + Duration::from_millis(PROCESS_LIMIT_POLL_MS);
+    loop {
+        if let Some(status) = child.try_wait()? {
+            // The wrapper may exit while grandchildren keep the process group
+            // alive. Sweep it before collecting pipes so completed harness
+            // runs cannot leave detached shells behind.
+            terminate_child_process_tree(&mut child);
+            let output = collect_completed_output(
+                &mut child,
+                &mut stdout_reader,
+                &mut stderr_reader,
+                Duration::from_millis(PIPE_READER_READY_GRACE_MS),
+                Duration::from_millis(PIPE_READER_JOIN_GRACE_MS),
+            );
+            let (stdout, stderr) = match output {
+                Ok(output) => output,
+                Err(err) if is_output_limit_error(&err) => {
+                    return Ok(TimedCommandOutput::OutputLimitExceeded {
+                        stderr: String::new(),
+                        output_limit,
+                        stream: output_limit_stream(&err),
+                    });
+                }
+                Err(err) => return Err(err),
+            };
+            return Ok(TimedCommandOutput::Completed(Output {
+                status,
+                stdout,
+                stderr,
+            }));
+        }
+
+        if Instant::now() >= deadline {
+            terminate_child_process_tree(&mut child);
+            let _ = child.wait();
+            let reader_timeout = Duration::from_millis(PIPE_READER_JOIN_GRACE_MS);
+            let _ = receive_pipe_reader(&mut stdout_reader, reader_timeout);
+            let stderr =
+                receive_pipe_reader(&mut stderr_reader, reader_timeout).unwrap_or_default();
+            return Ok(TimedCommandOutput::TimedOut {
+                stderr: String::from_utf8_lossy(&stderr).into_owned(),
+            });
+        }
+
+        if Instant::now() >= next_process_limit_poll {
+            next_process_limit_poll = Instant::now() + Duration::from_millis(PROCESS_LIMIT_POLL_MS);
+            if let Some(process_count) = count_process_tree(child.id()) {
+                if process_count > process_limit {
+                    terminate_child_process_tree(&mut child);
+                    let _ = child.wait();
+                    let reader_timeout = Duration::from_millis(PIPE_READER_JOIN_GRACE_MS);
+                    let _ = receive_pipe_reader(&mut stdout_reader, reader_timeout);
+                    let stderr =
+                        receive_pipe_reader(&mut stderr_reader, reader_timeout).unwrap_or_default();
+                    return Ok(TimedCommandOutput::ProcessLimitExceeded {
+                        stderr: String::from_utf8_lossy(&stderr).into_owned(),
+                        process_count,
+                        process_limit,
+                    });
+                }
+            }
+        }
+
+        if let Some(stream) = poll_output_limit(&mut stdout_reader, &mut stderr_reader)? {
+            terminate_child_process_tree(&mut child);
+            let _ = child.wait();
+            let reader_timeout = Duration::from_millis(PIPE_READER_JOIN_GRACE_MS);
+            let stderr = if stream == "stderr" {
+                Vec::new()
+            } else {
+                receive_pipe_reader(&mut stderr_reader, reader_timeout).unwrap_or_default()
+            };
+            return Ok(TimedCommandOutput::OutputLimitExceeded {
+                stderr: String::from_utf8_lossy(&stderr).into_owned(),
+                output_limit,
+                stream,
+            });
+        }
+
+        thread::sleep(Duration::from_millis(25));
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn count_process_tree(root_pid: u32) -> Option<usize> {
+    use std::collections::HashMap;
+    let entries = std::fs::read_dir("/proc").ok()?;
+    let mut children: HashMap<u32, Vec<u32>> = HashMap::new();
+    for entry in entries.flatten() {
+        let name = entry.file_name();
+        let Some(name) = name.to_str() else {
+            continue;
+        };
+        let Ok(pid) = name.parse::<u32>() else {
+            continue;
+        };
+        let Ok(stat) = std::fs::read_to_string(format!("/proc/{pid}/stat")) else {
+            continue;
+        };
+        let Some(close_paren) = stat.rfind(')') else {
+            continue;
+        };
+        let fields: Vec<&str> = stat[close_paren + 2..].split(' ').collect();
+        let Some(ppid) = fields.get(1).and_then(|field| field.parse::<u32>().ok()) else {
+            continue;
+        };
+        children.entry(ppid).or_default().push(pid);
+    }
+    let mut count = 1;
+    let mut stack = children.remove(&root_pid).unwrap_or_default();
+    while let Some(pid) = stack.pop() {
+        count += 1;
+        if let Some(mut nested) = children.remove(&pid) {
+            stack.append(&mut nested);
+        }
+    }
+    Some(count)
+}
+
+#[cfg(not(target_os = "linux"))]
+fn count_process_tree(_root_pid: u32) -> Option<usize> {
+    None
+}
+
+struct PipeReader {
+    receiver: Receiver<io::Result<Vec<u8>>>,
+    cached: Option<io::Result<Vec<u8>>>,
+}
+
+fn spawn_pipe_reader<R: Read + Send + 'static>(
+    stream: &'static str,
+    pipe: Option<R>,
+    output_limit: usize,
+) -> PipeReader {
+    let (sender, receiver) = mpsc::channel();
+    thread::spawn(move || {
+        let _ = sender.send(read_pipe_bounded(pipe, stream, output_limit));
+    });
+    PipeReader {
+        receiver,
+        cached: None,
+    }
+}
+
+fn read_pipe_bounded<R: Read + Send + 'static>(
+    pipe: Option<R>,
+    stream: &'static str,
+    output_limit: usize,
+) -> io::Result<Vec<u8>> {
+    let mut bytes = Vec::new();
+    let Some(pipe) = pipe else {
+        return Ok(bytes);
+    };
+    let mut reader = BufReader::new(pipe);
+    let mut chunk = [0_u8; 8192];
+    loop {
+        let read = reader.read(&mut chunk)?;
+        if read == 0 {
+            return Ok(bytes);
+        }
+        if bytes.len().saturating_add(read) > output_limit {
+            return Err(output_limit_error(stream, output_limit));
+        }
+        bytes.extend_from_slice(&chunk[..read]);
+    }
+}
+
+fn output_limit_error(stream: &'static str, output_limit: usize) -> io::Error {
+    io::Error::new(
+        io::ErrorKind::Other,
+        format!("subprocess {stream} exceeded output limit of {output_limit} bytes"),
+    )
+}
+
+fn is_output_limit_error(err: &io::Error) -> bool {
+    err.to_string().contains("exceeded output limit")
+}
+
+fn output_limit_stream(err: &io::Error) -> &'static str {
+    if err.to_string().contains("stderr") {
+        "stderr"
+    } else {
+        "stdout"
+    }
+}
+
+fn poll_output_limit(
+    stdout_reader: &mut PipeReader,
+    stderr_reader: &mut PipeReader,
+) -> io::Result<Option<&'static str>> {
+    if let Some(stream) = poll_one_output_limit("stdout", stdout_reader)? {
+        return Ok(Some(stream));
+    }
+    poll_one_output_limit("stderr", stderr_reader)
+}
+
+fn poll_one_output_limit(
+    stream: &'static str,
+    reader: &mut PipeReader,
+) -> io::Result<Option<&'static str>> {
+    if reader.cached.is_some() {
+        return Ok(None);
+    }
+    match reader.receiver.try_recv() {
+        Ok(Ok(bytes)) => {
+            reader.cached = Some(Ok(bytes));
+            Ok(None)
+        }
+        Ok(Err(err)) if is_output_limit_error(&err) => Ok(Some(stream)),
+        Ok(Err(err)) => Err(err),
+        Err(TryRecvError::Empty) => Ok(None),
+        Err(TryRecvError::Disconnected) => Err(io::Error::new(
+            io::ErrorKind::Other,
+            "subprocess output reader disconnected",
+        )),
+    }
+}
+
+fn collect_completed_output(
+    child: &mut Child,
+    stdout_reader: &mut PipeReader,
+    stderr_reader: &mut PipeReader,
+    ready_timeout: Duration,
+    cleanup_timeout: Duration,
+) -> io::Result<(Vec<u8>, Vec<u8>)> {
+    let stdout = receive_pipe_reader_if_ready(stdout_reader, ready_timeout)?;
+    let stderr = receive_pipe_reader_if_ready(stderr_reader, ready_timeout)?;
+
+    if stdout.is_none() || stderr.is_none() {
+        terminate_child_process_tree(child);
+    }
+
+    let stdout = match stdout {
+        Some(stdout) => stdout,
+        None => receive_pipe_reader(stdout_reader, cleanup_timeout)?,
+    };
+    let stderr = match stderr {
+        Some(stderr) => stderr,
+        None => receive_pipe_reader(stderr_reader, cleanup_timeout)?,
+    };
+
+    Ok((stdout, stderr))
+}
+
+fn receive_pipe_reader_if_ready(
+    reader: &mut PipeReader,
+    timeout: Duration,
+) -> io::Result<Option<Vec<u8>>> {
+    match receive_pipe_reader(reader, timeout) {
+        Ok(bytes) => Ok(Some(bytes)),
+        Err(err) if err.kind() == io::ErrorKind::TimedOut => Ok(None),
+        Err(err) => Err(err),
+    }
+}
+
+fn receive_pipe_reader(reader: &mut PipeReader, timeout: Duration) -> io::Result<Vec<u8>> {
+    if let Some(result) = reader.cached.take() {
+        return result;
+    }
+    match reader.receiver.recv_timeout(timeout) {
+        Ok(result) => result,
+        Err(RecvTimeoutError::Timeout) => Err(io::Error::new(
+            io::ErrorKind::TimedOut,
+            "timed out waiting for subprocess output pipe to close",
+        )),
+        Err(RecvTimeoutError::Disconnected) => Err(io::Error::new(
+            io::ErrorKind::Other,
+            "subprocess output reader disconnected",
+        )),
+    }
+}
+
+#[cfg(unix)]
+fn configure_process_group(command: &mut Command) {
+    use std::os::unix::process::CommandExt;
+    command.process_group(0);
+}
+
+#[cfg(not(unix))]
+fn configure_process_group(_command: &mut Command) {}
+
+#[cfg(unix)]
+fn terminate_child_process_tree(child: &mut Child) {
+    let pgid = child.id() as libc::pid_t;
+    unsafe {
+        let _ = libc::kill(-pgid, libc::SIGTERM);
+    }
+    thread::sleep(Duration::from_millis(PROCESS_TERMINATION_GRACE_MS));
+    unsafe {
+        let _ = libc::kill(-pgid, libc::SIGKILL);
+    }
+    let _ = child.kill();
+}
+
+#[cfg(not(unix))]
+fn terminate_child_process_tree(child: &mut Child) {
+    let _ = child.kill();
+}
+
+fn escape_toml_string(value: &str) -> String {
+    value.replace('\\', "\\\\").replace('"', "\\\"")
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct CodexLaunch {
+    program: String,
+    leading_args: Vec<String>,
+}
+
+fn resolve_codex_launch() -> CodexLaunch {
+    let codex_binary = resolve_codex_binary();
+    codex_launch_for_binary(&codex_binary).unwrap_or_else(|| CodexLaunch {
+        program: codex_binary,
+        leading_args: Vec::new(),
+    })
+}
+
+fn resolve_codex_binary() -> String {
+    if let Some(value) = env::var(CODEX_BIN_ENV)
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+    {
+        if value.contains(std::path::MAIN_SEPARATOR) {
+            return value;
+        }
+        if let Some(path) = resolve_host_command(&value) {
+            return path.display().to_string();
+        }
+        return value;
+    }
+
+    resolve_host_command("codex")
+        .map(|path| path.display().to_string())
+        .unwrap_or_else(|| "codex".to_string())
+}
+
+fn codex_launch_for_binary(codex_binary: &str) -> Option<CodexLaunch> {
+    let codex_path = Path::new(codex_binary);
+    if let Some(launch) = codex_launch_for_posix_node_shim(codex_path) {
+        return Some(launch);
+    }
+
+    let interpreter = read_shebang_interpreter(codex_path)?;
+    let (program, mut leading_args) = resolve_shebang_launch(&interpreter)?;
+    leading_args.push(codex_binary.to_string());
+    Some(CodexLaunch {
+        program,
+        leading_args,
+    })
+}
+
+fn codex_launch_for_posix_node_shim(codex_path: &Path) -> Option<CodexLaunch> {
+    let shebang = read_shebang_interpreter(codex_path)?;
+    if !is_posix_shell_shebang(&shebang) {
+        return None;
+    }
+
+    let script = read_to_string(codex_path).ok()?;
+    let entrypoint = resolve_posix_node_shim_entrypoint(codex_path, &script)?;
+    let program = resolve_posix_node_shim_program(codex_path, &script)?;
+    Some(CodexLaunch {
+        program: program.display().to_string(),
+        leading_args: vec![entrypoint.display().to_string()],
+    })
+}
+
+fn read_shebang_interpreter(path: &Path) -> Option<String> {
+    let file = File::open(path).ok()?;
+    let mut reader = BufReader::new(file);
+    let mut first_line = String::new();
+    if reader.read_line(&mut first_line).ok()? == 0 {
+        return None;
+    }
+    first_line
+        .strip_prefix("#!")
+        .map(str::trim)
+        .filter(|line| !line.is_empty())
+        .map(ToOwned::to_owned)
+}
+
+fn is_posix_shell_shebang(shebang: &str) -> bool {
+    let parts: Vec<&str> = shebang.split_whitespace().collect();
+    let interpreter = *parts.first().unwrap_or(&"");
+    if interpreter.ends_with("/env") {
+        return parts
+            .get(1)
+            .is_some_and(|target| is_posix_shell_name(target));
+    }
+    is_posix_shell_name(interpreter)
+}
+
+fn is_posix_shell_name(value: &str) -> bool {
+    matches!(
+        Path::new(value).file_name().and_then(|name| name.to_str()),
+        Some("sh" | "bash" | "dash" | "ash" | "ksh" | "zsh")
+    )
+}
+
+fn resolve_posix_node_shim_entrypoint(codex_path: &Path, script: &str) -> Option<PathBuf> {
+    let basedir = codex_path.parent()?;
+    quoted_shell_segments(script)
+        .into_iter()
+        .filter_map(|segment| strip_basedir_prefix(&segment).map(ToOwned::to_owned))
+        .map(|relative| normalize_path(basedir.join(relative)))
+        .find(|candidate| is_node_entrypoint(candidate))
+}
+
+fn resolve_posix_node_shim_program(codex_path: &Path, script: &str) -> Option<PathBuf> {
+    let basedir = codex_path.parent()?;
+    if quoted_shell_segments(script)
+        .into_iter()
+        .any(|segment| matches!(strip_basedir_prefix(&segment), Some("node")))
+    {
+        let sibling_node = basedir.join("node");
+        if is_usable_host_command(&sibling_node) {
+            return Some(sibling_node);
+        }
+    }
+    resolve_host_command("node")
+}
+
+fn quoted_shell_segments(script: &str) -> Vec<String> {
+    let mut segments = Vec::new();
+    let mut active_quote: Option<char> = None;
+    let mut current = String::new();
+
+    for ch in script.chars() {
+        if let Some(quote) = active_quote {
+            if ch == quote {
+                segments.push(std::mem::take(&mut current));
+                active_quote = None;
+            } else {
+                current.push(ch);
+            }
+            continue;
+        }
+
+        if ch == '\'' || ch == '"' {
+            active_quote = Some(ch);
+        }
+    }
+
+    segments
+}
+
+fn strip_basedir_prefix(segment: &str) -> Option<&str> {
+    segment
+        .strip_prefix("$basedir/")
+        .or_else(|| segment.strip_prefix("${basedir}/"))
+}
+
+fn is_node_entrypoint(path: &Path) -> bool {
+    path.is_file()
+        && matches!(
+            path.extension().and_then(|value| value.to_str()),
+            Some("js" | "cjs" | "mjs")
+        )
+}
+
+fn resolve_shebang_launch(shebang: &str) -> Option<(String, Vec<String>)> {
+    let parts: Vec<&str> = shebang.split_whitespace().collect();
+    let interpreter = *parts.first()?;
+    if interpreter.ends_with("/env") {
+        let target = parts.get(1).copied()?;
+        let resolved = resolve_host_command(target)?;
+        return Some((
+            resolved.display().to_string(),
+            parts
+                .iter()
+                .skip(2)
+                .map(|part| (*part).to_string())
+                .collect(),
+        ));
+    }
+
+    Some((
+        interpreter.to_string(),
+        parts
+            .iter()
+            .skip(1)
+            .map(|part| (*part).to_string())
+            .collect(),
+    ))
+}
+
+fn codex_support_dir_args() -> Vec<String> {
+    discover_codex_support_dirs()
+        .into_iter()
+        .flat_map(|dir| ["--add-dir".to_string(), dir.display().to_string()])
+        .collect()
+}
+
+fn discover_codex_support_dirs() -> Vec<PathBuf> {
+    let mut dirs = Vec::new();
+    if let Some(home) = env::var_os("HOME").filter(|value| !value.is_empty()) {
+        let home = PathBuf::from(home);
+        for relative in [".omx", ".codex"] {
+            let dir = home.join(relative);
+            if dir.is_dir() {
+                dirs.push(dir);
+            }
+        }
+    }
+    dirs
+}
+
+fn temp_output_path() -> PathBuf {
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_nanos();
+    env::temp_dir().join(format!("omx-explore-{}-{}.md", std::process::id(), nanos))
+}
+
+fn compose_exec_prompt(user_prompt: &str, prompt_contract: &str) -> String {
+    format!(
+        concat!(
+            "You are OMX Explore, a low-cost read-only repository exploration harness.\\n",
+            "Operate strictly in read-only mode. You may use repository-inspection shell commands only.\\n",
+            "Preferred commands: rg, grep, and tightly bounded read-only bash wrappers over rg/grep/ls/find/wc/cat/head/tail.\\n",
+            "Do not write, delete, rename, or modify files. Do not run git commands that alter working state.\\n",
+            "Always return markdown only.\\n\\n",
+            "Reference behavior contract:\\n",
+            "---------------- BEGIN EXPLORE PROMPT ----------------\\n{}\\n---------------- END EXPLORE PROMPT ----------------\\n\\n",
+            "User request:\\n{}\\n"
+        ),
+        prompt_contract,
+        user_prompt
+    )
+}
+
+fn prepare_allowlist_environment() -> Result<AllowlistEnvironment, String> {
+    if let Some(message) = allowlist_platform_diagnostic(env::consts::OS) {
+        return Err(message.to_string());
+    }
+    let root = temp_allowlist_dir()?;
+    let bin_dir = root.path.join("bin");
+    create_dir_all(&bin_dir).map_err(|err| {
+        format!(
+            "failed to create allowlist bin dir {}: {err}",
+            bin_dir.display()
+        )
+    })?;
+
+    let self_exe = env::current_exe().map_err(|err| {
+        format!("failed to resolve current executable for allowlist wrappers: {err}")
+    })?;
+    let bash_path = resolve_host_command("bash")
+        .ok_or_else(|| "failed to locate host bash for allowlist wrapper".to_string())?;
+    let sh_path = resolve_host_command("sh")
+        .ok_or_else(|| "failed to locate host sh for allowlist wrapper".to_string())?;
+
+    for command in ALLOWED_DIRECT_COMMANDS {
+        let wrapper_path = bin_dir.join(command);
+        let wrapper = build_direct_wrapper(&self_exe, command)?;
+        write_executable(&wrapper_path, &wrapper)?;
+    }
+
+    let bash_wrapper = format!(
+        "#!/bin/sh\nexec {} {} {} \"$@\"\n",
+        shell_quote(&self_exe.display().to_string()),
+        shell_quote(INTERNAL_SHELL_WRAPPER_FLAG),
+        shell_quote(&bash_path.display().to_string()),
+    );
+    let sh_wrapper = format!(
+        "#!/bin/sh\nexec {} {} {} \"$@\"\n",
+        shell_quote(&self_exe.display().to_string()),
+        shell_quote(INTERNAL_SHELL_WRAPPER_FLAG),
+        shell_quote(&sh_path.display().to_string()),
+    );
+    let shell_path = bin_dir.join("bash");
+    write_executable(&shell_path, &bash_wrapper)?;
+    write_executable(&bin_dir.join("sh"), &sh_wrapper)?;
+
+    let sandbox_bin_dir = prepare_sandbox_dependency_bin(&root.path)?;
+
+    Ok(AllowlistEnvironment {
+        bin_dir,
+        shell_path,
+        sandbox_bin_dir,
+        _root: root,
+    })
+}
+
+fn build_codex_path(
+    allowlist_bin_dir: &Path,
+    sandbox_bin_dir: Option<&Path>,
+) -> Result<OsString, String> {
+    let mut entries = vec![allowlist_bin_dir.to_path_buf()];
+    if let Some(sandbox_bin_dir) = sandbox_bin_dir {
+        entries.push(sandbox_bin_dir.to_path_buf());
+    }
+    env::join_paths(entries).map_err(|err| format!("failed to construct restricted PATH: {err}"))
+}
+
+fn prepare_sandbox_dependency_bin(root: &Path) -> Result<Option<PathBuf>, String> {
+    let Some(bwrap_path) = resolve_host_command("bwrap") else {
+        return Ok(None);
+    };
+
+    let sandbox_bin_dir = root.join("sandbox-bin");
+    create_dir_all(&sandbox_bin_dir).map_err(|err| {
+        format!(
+            "failed to create sandbox dependency bin dir {}: {err}",
+            sandbox_bin_dir.display()
+        )
+    })?;
+    write_executable(
+        &sandbox_bin_dir.join("bwrap"),
+        &format!(
+            "#!/bin/sh\nexec {} \"$@\"\n",
+            shell_quote(&bwrap_path.display().to_string())
+        ),
+    )?;
+    Ok(Some(sandbox_bin_dir))
+}
+
+fn allowlist_platform_diagnostic(os: &str) -> Option<&'static str> {
+    if os.eq_ignore_ascii_case("windows") {
+        return Some(WINDOWS_UNSUPPORTED_ALLOWLIST_MESSAGE);
+    }
+    None
+}
+
+fn temp_allowlist_dir() -> Result<TempDirGuard, String> {
+    let dir = env::temp_dir().join(format!(
+        "omx-explore-allowlist-{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_nanos()
+    ));
+    create_dir_all(&dir)
+        .map_err(|err| format!("failed to create allowlist dir {}: {err}", dir.display()))?;
+    Ok(TempDirGuard { path: dir })
+}
+
+fn write_executable(path: &Path, content: &str) -> Result<(), String> {
+    write(path, content)
+        .map_err(|err| format!("failed to write wrapper {}: {err}", path.display()))?;
+    #[cfg(unix)]
+    {
+        use std::fs;
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = fs::metadata(path)
+            .map_err(|err| format!("failed to stat wrapper {}: {err}", path.display()))?
+            .permissions();
+        perms.set_mode(0o755);
+        fs::set_permissions(path, perms)
+            .map_err(|err| format!("failed to chmod wrapper {}: {err}", path.display()))?;
+    }
+    Ok(())
+}
+
+fn build_direct_wrapper(self_exe: &Path, command: &str) -> Result<String, String> {
+    if let Some(real) = resolve_host_command(command) {
+        return Ok(format!(
+            "#!/bin/sh\nexec {} {} {} \"$@\"\n",
+            shell_quote(&self_exe.display().to_string()),
+            shell_quote(INTERNAL_DIRECT_WRAPPER_FLAG),
+            shell_quote(&format!("{command}:{}", real.display())),
+        ));
+    }
+
+    if command != "rg" {
+        return Err(format!(
+            "failed to locate host command `{command}` for allowlist wrapper"
+        ));
+    }
+
+    Ok(format!(
+        "#!/bin/sh\nprintf '%s\\n' {} >&2\nexit 127\n",
+        shell_quote(&format!(
+            "omx explore allowlisted host command `{command}` is unavailable on this host"
+        )),
+    ))
+}
+
+fn resolve_host_command(command: &str) -> Option<PathBuf> {
+    let candidate = Path::new(command);
+    if candidate.is_absolute()
+        && is_usable_host_command(candidate)
+        && !is_omx_explore_allowlist_path(candidate)
+    {
+        return Some(candidate.to_path_buf());
+    }
+
+    let path = env::var_os("PATH")?;
+    for entry in env::split_paths(&path) {
+        let resolved = entry.join(command);
+        if is_usable_host_command(&resolved) && !is_omx_explore_allowlist_path(&resolved) {
+            return Some(resolved);
+        }
+    }
+    None
+}
+
+fn is_omx_explore_allowlist_path(path: &Path) -> bool {
+    fn is_under_allowlist_bin(path: &Path) -> bool {
+        path.ancestors().any(|ancestor| {
+            let is_allowlist_root = ancestor
+                .file_name()
+                .and_then(|name| name.to_str())
+                .is_some_and(|name| name.starts_with(TEMP_ALLOWLIST_DIR_PREFIX));
+            if !is_allowlist_root {
+                return false;
+            }
+            path.strip_prefix(ancestor)
+                .ok()
+                .and_then(|relative| relative.components().next())
+                .is_some_and(|component| component.as_os_str() == "bin")
+        })
+    }
+
+    is_under_allowlist_bin(path)
+        || canonicalize_existing_prefix(path)
+            .as_deref()
+            .is_some_and(is_under_allowlist_bin)
+}
+
+fn is_usable_host_command(path: &Path) -> bool {
+    let metadata = match path.metadata() {
+        Ok(metadata) => metadata,
+        Err(_) => return false,
+    };
+    if !metadata.is_file() {
+        return false;
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        metadata.permissions().mode() & 0o111 != 0
+    }
+    #[cfg(not(unix))]
+    {
+        true
+    }
+}
+
+fn shell_quote(value: &str) -> String {
+    format!("'{}'", value.replace('\'', "'\"'\"'"))
+}
+
+fn sanitize_explore_subprocess_env(command: &mut Command) {
+    for key in EXPLORE_SUBPROCESS_ENV_VARS_TO_SCRUB {
+        command.env_remove(key);
+    }
+}
+
+fn shell_supports_bash_startup_suppression(shell_path: &str) -> bool {
+    Path::new(shell_path)
+        .file_name()
+        .and_then(|name| name.to_str())
+        .is_some_and(|name| name == "bash")
+}
+
+fn run_internal_direct_wrapper<I>(mut args: I) -> Result<(), String>
+where
+    I: Iterator<Item = OsString>,
+{
+    let spec = args
+        .next()
+        .ok_or_else(|| "missing direct wrapper spec".to_string())?;
+    let spec = spec.to_string_lossy();
+    let (command_name, real_path) = spec
+        .split_once(':')
+        .ok_or_else(|| format!("invalid direct wrapper spec: {spec}"))?;
+    let forwarded: Vec<String> = args.map(|arg| arg.to_string_lossy().into_owned()).collect();
+    validate_direct_command(command_name, &forwarded)?;
+
+    let status = Command::new(real_path)
+        .args(&forwarded)
+        .status()
+        .map_err(|err| format!("failed to execute allowlisted `{command_name}`: {err}"))?;
+    std::process::exit(status.code().unwrap_or(1));
+}
+
+fn run_internal_shell_wrapper<I>(mut args: I) -> Result<(), String>
+where
+    I: Iterator<Item = OsString>,
+{
+    let real_shell = args
+        .next()
+        .ok_or_else(|| "missing real shell path for internal wrapper".to_string())?;
+    let real_shell = real_shell.to_string_lossy().into_owned();
+    let forwarded: Vec<String> = args.map(|arg| arg.to_string_lossy().into_owned()).collect();
+    let command = validate_shell_invocation(&forwarded)?;
+
+    let status_code = execute_validated_shell(&real_shell, &command)?;
+    std::process::exit(status_code);
+}
+
+fn execute_validated_shell(real_shell: &str, command: &str) -> Result<i32, String> {
+    let mut child = Command::new(real_shell);
+    if shell_supports_bash_startup_suppression(real_shell) {
+        child.arg("--noprofile").arg("--norc");
+    }
+    sanitize_explore_subprocess_env(&mut child);
+    let status = child
+        .arg("-c")
+        .arg(command)
+        .status()
+        .map_err(|err| format!("failed to execute validated shell command: {err}"))?;
+    Ok(status.code().unwrap_or(1))
+}
+
+fn validate_shell_invocation(args: &[String]) -> Result<String, String> {
+    if args.len() != 2 {
+        return Err(format!(
+            "shell wrapper only accepts a single `-c` or `-lc` command, received {:?}",
+            args
+        ));
+    }
+    if args[0] != "-c" && args[0] != "-lc" {
+        return Err(format!(
+            "shell wrapper only accepts `-c` or `-lc`, received `{}`",
+            args[0]
+        ));
+    }
+
+    let command = args[1].trim();
+    if command.is_empty() {
+        return Err("shell wrapper received an empty command".to_string());
+    }
+
+    for fragment in ["\n", "\r", "&&", "||", ";", "|", ">", "<", "`", "$(", "${"] {
+        if command.contains(fragment) {
+            return Err(format!(
+                "shell wrapper rejected disallowed fragment `{fragment}` in `{command}`"
+            ));
+        }
+    }
+
+    let tokens: Vec<String> = command
+        .split_whitespace()
+        .map(|token| token.trim_matches(|ch| ch == '"' || ch == '\'').to_string())
+        .filter(|token| !token.is_empty())
+        .collect();
+    let first = tokens
+        .first()
+        .ok_or_else(|| "shell wrapper could not determine the command name".to_string())?;
+    if first.contains('/') {
+        return Err(format!(
+            "shell wrapper rejected path-qualified command `{first}`; use allowlisted bare commands only"
+        ));
+    }
+
+    validate_direct_command(first, &tokens[1..])?;
+    Ok(command.to_string())
+}
+
+fn validate_direct_command(command_name: &str, args: &[String]) -> Result<(), String> {
+    if !ALLOWED_DIRECT_COMMANDS.contains(&command_name) {
+        return Err(format!(
+            "command `{command_name}` is not on the omx explore allowlist"
+        ));
+    }
+
+    match command_name {
+        "rg" => {
+            if args
+                .iter()
+                .any(|arg| arg == "--pre" || arg.starts_with("--pre="))
+            {
+                return Err("ripgrep `--pre` is not allowed in omx explore".to_string());
+            }
+            if args.iter().any(|arg| arg == "-") {
+                return Err("ripgrep stdin (`-`) is not allowed in omx explore".to_string());
+            }
+        }
+        "grep" => {
+            if args.iter().any(|arg| arg == "-") {
+                return Err("grep stdin (`-`) is not allowed in omx explore".to_string());
+            }
+            if non_option_operands(args).len() < 2 {
+                return Err(
+                    "grep requires a pattern and at least one file/path in omx explore".to_string(),
+                );
+            }
+        }
+        "find"
+            if args.iter().any(|arg| {
+                matches!(
+                    arg.as_str(),
+                    "-exec"
+                        | "-execdir"
+                        | "-ok"
+                        | "-okdir"
+                        | "-delete"
+                        | "-fprint"
+                        | "-fprint0"
+                        | "-fprintf"
+                        | "-fls"
+                )
+            }) =>
+        {
+            return Err(
+                "find actions that execute, delete, or write files are not allowed in omx explore"
+                    .to_string(),
+            );
+        }
+        "find" => {}
+        "cat" => {
+            let operands = non_option_operands(args);
+            if operands.is_empty() {
+                return Err("cat requires at least one file/path in omx explore".to_string());
+            }
+            if operands.contains(&"-") {
+                return Err("cat stdin (`-`) is not allowed in omx explore".to_string());
+            }
+        }
+        "head" | "wc" => {
+            let operands = non_option_operands(args);
+            if operands.is_empty() {
+                return Err(format!(
+                    "{command_name} requires at least one file/path in omx explore"
+                ));
+            }
+            if operands.contains(&"-") {
+                return Err(format!(
+                    "{command_name} stdin (`-`) is not allowed in omx explore"
+                ));
+            }
+        }
+        "tail" => {
+            let operands = non_option_operands(args);
+            if operands.is_empty() {
+                return Err("tail requires at least one file/path in omx explore".to_string());
+            }
+            if operands.contains(&"-") {
+                return Err("tail stdin (`-`) is not allowed in omx explore".to_string());
+            }
+            if args.iter().any(|arg| {
+                matches!(arg.as_str(), "-f" | "-F" | "--retry") || arg.starts_with("--follow")
+            }) {
+                return Err("tail follow/retry modes are not allowed in omx explore".to_string());
+            }
+        }
+        _ => {}
+    }
+
+    validate_repo_paths(command_name, args)?;
+    Ok(())
+}
+
+fn non_option_operands(args: &[String]) -> Vec<&str> {
+    let mut operands = Vec::new();
+    let mut after_double_dash = false;
+    for arg in args {
+        if after_double_dash {
+            operands.push(arg.as_str());
+            continue;
+        }
+        if arg == "--" {
+            after_double_dash = true;
+            continue;
+        }
+        if arg.starts_with('-') && arg != "-" {
+            continue;
+        }
+        operands.push(arg.as_str());
+    }
+    operands
+}
+
+fn validate_repo_paths(command_name: &str, args: &[String]) -> Result<(), String> {
+    let Some(repo_root) = env::var_os(HARNESS_ROOT_ENV).filter(|value| !value.is_empty()) else {
+        return Ok(());
+    };
+    let repo_root = normalize_path(PathBuf::from(repo_root));
+    let canonical_repo_root = canonicalize_existing_prefix(&repo_root);
+    let candidate_paths = command_path_operands(command_name, args);
+    for operand in candidate_paths {
+        let normalized = normalize_candidate_path(&repo_root, operand);
+        let canonical_candidate = canonicalize_existing_prefix(&normalized);
+        let is_textually_inside = normalized.starts_with(&repo_root);
+        let is_canonically_inside = match (&canonical_candidate, &canonical_repo_root) {
+            (Some(candidate), Some(root)) => candidate.starts_with(root),
+            _ => false,
+        };
+
+        if !is_textually_inside && !is_canonically_inside {
+            return Err(format!(
+                "path `{operand}` escapes the omx explore repository root {}",
+                repo_root.display()
+            ));
+        }
+        if is_textually_inside {
+            if let Some(canonical_candidate) = canonical_candidate {
+                if let Some(canonical_repo_root) = &canonical_repo_root {
+                    if !canonical_candidate.starts_with(canonical_repo_root) {
+                        return Err(format!(
+                            "path `{operand}` resolves outside the omx explore repository root {}",
+                            canonical_repo_root.display()
+                        ));
+                    }
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+fn command_path_operands<'a>(command_name: &str, args: &'a [String]) -> Vec<&'a str> {
+    let operands = non_option_operands(args);
+    match command_name {
+        "rg" => operands.into_iter().skip(1).collect(),
+        "grep" => operands.into_iter().skip(1).collect(),
+        "find" => {
+            let mut paths = Vec::new();
+            for arg in args {
+                let value = arg.as_str();
+                if matches!(value, "!" | "(" | ")") || value.starts_with('-') {
+                    break;
+                }
+                paths.push(value);
+            }
+            paths
+        }
+        "ls" | "cat" | "head" | "tail" | "wc" => operands,
+        _ => Vec::new(),
+    }
+}
+
+fn normalize_candidate_path(repo_root: &Path, operand: &str) -> PathBuf {
+    let candidate = Path::new(operand);
+    if candidate.is_absolute() {
+        normalize_path(candidate.to_path_buf())
+    } else {
+        normalize_path(repo_root.join(candidate))
+    }
+}
+
+fn normalize_path(path: PathBuf) -> PathBuf {
+    use std::path::Component;
+
+    let mut normalized = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::CurDir => {}
+            Component::ParentDir => {
+                normalized.pop();
+            }
+            Component::RootDir | Component::Prefix(_) | Component::Normal(_) => {
+                normalized.push(component.as_os_str());
+            }
+        }
+    }
+    normalized
+}
+
+fn canonicalize_existing_prefix(path: &Path) -> Option<PathBuf> {
+    let mut probe = path;
+    let mut suffix: Vec<&std::ffi::OsStr> = Vec::new();
+
+    loop {
+        if probe.exists() {
+            let mut canonical = canonicalize(probe).ok()?;
+            for segment in suffix.iter().rev() {
+                canonical.push(segment);
+            }
+            return Some(normalize_path(canonical));
+        }
+        let name = probe.file_name()?;
+        suffix.push(name);
+        probe = probe.parent()?;
+    }
+}
+
+#[cfg(test)]
+#[allow(unused_unsafe)]
+mod tests {
+    use super::*;
+    use std::sync::{Mutex, OnceLock};
+
+    #[cfg(unix)]
+    use std::os::unix::fs::symlink;
+
+    fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(()))
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
+    fn process_tree_lock() -> std::sync::MutexGuard<'static, ()> {
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(()))
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
+    #[test]
+    fn parse_args_requires_all_fields() {
+        let result = parse_args(vec![OsString::from("--cwd")].into_iter());
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn parse_args_accepts_full_contract() {
+        let args = parse_args(
+            vec![
+                "--cwd",
+                "/tmp/repo",
+                "--prompt",
+                "find auth",
+                "--prompt-file",
+                "/tmp/explore.md",
+                "--instructions-file",
+                "/tmp/explore-agents.md",
+                "--model-spark",
+                "gpt-5.3-codex-spark",
+                "--model-fallback",
+                "gpt-5.5",
+            ]
+            .into_iter()
+            .map(OsString::from),
+        )
+        .expect("args");
+
+        assert_eq!(args.cwd, Path::new("/tmp/repo"));
+        assert_eq!(args.prompt, "find auth");
+        assert_eq!(args.prompt_file, Path::new("/tmp/explore.md"));
+        assert_eq!(args.instructions_file, Path::new("/tmp/explore-agents.md"));
+        assert_eq!(args.spark_model, "gpt-5.3-codex-spark");
+        assert_eq!(args.fallback_model, "gpt-5.5");
+    }
+
+    #[test]
+    fn compose_exec_prompt_mentions_read_only_constraints() {
+        let prompt = compose_exec_prompt("find auth", "contract body");
+        assert!(prompt.contains("read-only repository exploration harness"));
+        assert!(prompt.contains("Preferred commands: rg, grep"));
+        assert!(prompt.contains("Always return markdown only"));
+        assert!(prompt.contains("contract body"));
+        assert!(prompt.contains("find auth"));
+    }
+
+    #[test]
+    fn resolve_codex_binary_prefers_env_override() {
+        let _guard = env_lock();
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, "/tmp/codex-stub");
+        }
+        assert_eq!(resolve_codex_binary(), "/tmp/codex-stub");
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+        }
+    }
+
+    #[test]
+    fn resolve_codex_binary_resolves_bare_env_override_from_path() {
+        let _guard = env_lock();
+        let root = TempDirGuard {
+            path: env::temp_dir().join(format!(
+                "omx-explore-resolve-codex-binary-{}-{}",
+                std::process::id(),
+                SystemTime::now()
+                    .duration_since(UNIX_EPOCH)
+                    .unwrap_or_default()
+                    .as_nanos()
+            )),
+        };
+        create_dir_all(&root.path).expect("create temp root");
+        let bin_dir = root.path.join("bin");
+        create_dir_all(&bin_dir).expect("create bin");
+        let fake_codex = bin_dir.join("codex-custom");
+        write(&fake_codex, b"#!/bin/sh\nexit 0\n").expect("write fake codex");
+        write_executable(&fake_codex, "#!/bin/sh\nexit 0\n").expect("chmod fake codex");
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, "codex-custom");
+            env::set_var("PATH", &bin_dir);
+        }
+
+        let resolved = resolve_codex_binary();
+
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+        }
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(resolved, fake_codex.display().to_string());
+    }
+
+    #[test]
+    fn codex_launch_for_env_node_shebang_uses_host_node_absolute_path() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let script_path = root.path.join("codex-script");
+        write(&script_path, b"#!/usr/bin/env node\nconsole.log(\"ok\");\n").expect("write script");
+
+        let launch = codex_launch_for_binary(script_path.to_str().expect("script path"))
+            .expect("launch config");
+        let expected_node = resolve_host_command("node").expect("host node path");
+        assert_eq!(launch.program, expected_node.display().to_string());
+        assert_eq!(launch.leading_args, vec![script_path.display().to_string()]);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn codex_launch_for_posix_package_manager_shim_uses_host_node_and_entrypoint() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let host_bin = root.path.join("host-bin");
+        let shim_dir = root.path.join("node_modules").join(".bin");
+        let entrypoint = root
+            .path
+            .join("node_modules")
+            .join("@openai")
+            .join("codex")
+            .join("bin")
+            .join("codex.js");
+        create_dir_all(&host_bin).expect("create host bin");
+        create_dir_all(&shim_dir).expect("create shim dir");
+        create_dir_all(entrypoint.parent().expect("entrypoint parent"))
+            .expect("create entrypoint dir");
+
+        let fake_node = host_bin.join("node");
+        write_executable(&fake_node, "#!/bin/sh\nexit 0\n").expect("write fake node");
+        write(&entrypoint, "console.log('ok');\n").expect("write entrypoint");
+
+        let shim_path = shim_dir.join("codex");
+        write_executable(
+            &shim_path,
+            r#"#!/bin/sh
+basedir=$(dirname "$0")
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node" "$basedir/../@openai/codex/bin/codex.js" "$@"
+fi
+exec node "$basedir/../@openai/codex/bin/codex.js" "$@"
+"#,
+        )
+        .expect("write shim");
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var("PATH", &host_bin);
+        }
+
+        let launch =
+            codex_launch_for_binary(shim_path.to_str().expect("shim path")).expect("launch config");
+
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(launch.program, fake_node.display().to_string());
+        assert_eq!(launch.leading_args, vec![entrypoint.display().to_string()]);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn resolve_host_command_skips_directory_and_non_executable_path_entries() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let bad_bin = root.path.join("bad-bin");
+        let blocked_file_bin = root.path.join("blocked-file-bin");
+        let good_bin = root.path.join("good-bin");
+        create_dir_all(&bad_bin).expect("create bad bin");
+        create_dir_all(&blocked_file_bin).expect("create blocked file bin");
+        create_dir_all(&good_bin).expect("create good bin");
+
+        let blocked_directory = bad_bin.join("node");
+        create_dir_all(blocked_directory).expect("create blocked directory");
+
+        let blocked_node = blocked_file_bin.join("node");
+        write(&blocked_node, "#!/bin/sh\nexit 0\n").expect("write blocked file node");
+        let executable_node = good_bin.join("node");
+        write_executable(&executable_node, "#!/bin/sh\nexit 0\n").expect("write executable node");
+
+        #[cfg(unix)]
+        {
+            use std::fs;
+            use std::os::unix::fs::PermissionsExt;
+            let mut perms = fs::metadata(&blocked_node)
+                .expect("stat blocked node")
+                .permissions();
+            perms.set_mode(0o644);
+            fs::set_permissions(&blocked_node, perms).expect("chmod blocked node");
+        }
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var(
+                "PATH",
+                env::join_paths([
+                    bad_bin.as_path(),
+                    blocked_file_bin.as_path(),
+                    good_bin.as_path(),
+                ])
+                .expect("join path"),
+            );
+        }
+
+        let resolved = resolve_host_command("node");
+
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(resolved, Some(executable_node));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn codex_launch_for_env_node_shebang_skips_non_executable_earlier_node_entry() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let bad_bin = root.path.join("bad-bin");
+        let good_bin = root.path.join("good-bin");
+        create_dir_all(&bad_bin).expect("create bad bin");
+        create_dir_all(&good_bin).expect("create good bin");
+
+        let blocked_node = bad_bin.join("node");
+        write(&blocked_node, "#!/bin/sh\nexit 0\n").expect("write blocked node");
+        let executable_node = good_bin.join("node");
+        write_executable(&executable_node, "#!/bin/sh\nexit 0\n").expect("write executable node");
+
+        #[cfg(unix)]
+        {
+            use std::fs;
+            use std::os::unix::fs::PermissionsExt;
+            let mut perms = fs::metadata(&blocked_node)
+                .expect("stat blocked node")
+                .permissions();
+            perms.set_mode(0o644);
+            fs::set_permissions(&blocked_node, perms).expect("chmod blocked node");
+        }
+
+        let script_path = root.path.join("codex-script");
+        write(&script_path, b"#!/usr/bin/env node\nconsole.log(\"ok\");\n").expect("write script");
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var(
+                "PATH",
+                env::join_paths([bad_bin.as_path(), good_bin.as_path()]).expect("join path"),
+            );
+        }
+
+        let launch = codex_launch_for_binary(script_path.to_str().expect("script path"))
+            .expect("launch config");
+
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(launch.program, executable_node.display().to_string());
+        assert_eq!(launch.leading_args, vec![script_path.display().to_string()]);
+    }
+
+    #[cfg(unix)]
+    fn create_host_bin_with_commands(commands: &[&str]) -> (TempDirGuard, PathBuf) {
+        let root = temp_allowlist_dir().expect("temp root");
+        let host_bin = root.path.join("host-bin");
+        create_dir_all(&host_bin).expect("create host bin");
+        for command in commands {
+            let resolved =
+                resolve_host_command(command).unwrap_or_else(|| panic!("host {command} path"));
+            symlink(&resolved, host_bin.join(command))
+                .unwrap_or_else(|err| panic!("symlink {command}: {err}"));
+        }
+        (root, host_bin)
+    }
+
+    #[cfg(unix)]
+    fn with_path<T>(path: &Path, f: impl FnOnce() -> T) -> T {
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var("PATH", path);
+        }
+        let result = f();
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+        result
+    }
+
+    #[test]
+    fn build_codex_path_keeps_allowlist_first_and_only_adds_sandbox_bin() {
+        let allowlist_bin = Path::new("/tmp/omx-explore-allowlist/bin");
+        let sandbox_bin = Path::new("/tmp/omx-explore-sandbox-bin");
+
+        let path = build_codex_path(allowlist_bin, Some(sandbox_bin)).expect("restricted path");
+        let entries: Vec<PathBuf> = env::split_paths(&path).collect();
+
+        assert_eq!(
+            entries,
+            vec![allowlist_bin.to_path_buf(), sandbox_bin.to_path_buf()]
+        );
+    }
+
+    #[test]
+    fn build_codex_path_omits_sandbox_bin_when_bwrap_is_absent() {
+        let allowlist_bin = Path::new("/tmp/omx-explore-allowlist/bin");
+
+        let path = build_codex_path(allowlist_bin, None).expect("restricted path");
+        let entries: Vec<PathBuf> = env::split_paths(&path).collect();
+
+        assert_eq!(entries, vec![allowlist_bin.to_path_buf()]);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn prepare_allowlist_environment_adds_controlled_bwrap_without_host_path() {
+        let _guard = env_lock();
+        let mut commands = vec!["bash", "sh"];
+        commands.extend(
+            ALLOWED_DIRECT_COMMANDS
+                .iter()
+                .copied()
+                .filter(|command| *command != "rg"),
+        );
+        let (_root, host_bin) = create_host_bin_with_commands(&commands);
+        let fake_bwrap = host_bin.join("bwrap");
+        write_executable(&fake_bwrap, "#!/bin/sh\nexit 0\n").expect("write fake bwrap");
+
+        let allowlist =
+            with_path(&host_bin, prepare_allowlist_environment).expect("allowlist environment");
+        let sandbox_bin = allowlist
+            .sandbox_bin_dir
+            .as_ref()
+            .expect("sandbox bin when bwrap exists");
+        let path = build_codex_path(&allowlist.bin_dir, allowlist.sandbox_bin_dir.as_deref())
+            .expect("codex path");
+        let entries: Vec<PathBuf> = env::split_paths(&path).collect();
+
+        assert_eq!(
+            entries,
+            vec![allowlist.bin_dir.clone(), sandbox_bin.clone()]
+        );
+        assert!(!entries.contains(&host_bin));
+        let controlled_bwrap =
+            read_to_string(sandbox_bin.join("bwrap")).expect("read controlled bwrap");
+        assert!(controlled_bwrap.contains(&fake_bwrap.display().to_string()));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn prepare_allowlist_environment_leaves_path_allowlist_only_without_bwrap() {
+        let _guard = env_lock();
+        let mut commands = vec!["bash", "sh"];
+        commands.extend(
+            ALLOWED_DIRECT_COMMANDS
+                .iter()
+                .copied()
+                .filter(|command| *command != "rg"),
+        );
+        let (_root, host_bin) = create_host_bin_with_commands(&commands);
+
+        let allowlist =
+            with_path(&host_bin, prepare_allowlist_environment).expect("allowlist environment");
+        let path = build_codex_path(&allowlist.bin_dir, allowlist.sandbox_bin_dir.as_deref())
+            .expect("codex path");
+        let entries: Vec<PathBuf> = env::split_paths(&path).collect();
+
+        assert!(allowlist.sandbox_bin_dir.is_none());
+        assert_eq!(entries, vec![allowlist.bin_dir]);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn prepare_allowlist_environment_tolerates_missing_rg_by_stubbing_wrapper() {
+        let _guard = env_lock();
+        let mut commands = vec!["bash", "sh"];
+        commands.extend(
+            ALLOWED_DIRECT_COMMANDS
+                .iter()
+                .copied()
+                .filter(|command| *command != "rg"),
+        );
+        let (_root, host_bin) = create_host_bin_with_commands(&commands);
+
+        let allowlist =
+            with_path(&host_bin, prepare_allowlist_environment).expect("allowlist environment");
+        let rg_output = Command::new(allowlist.bin_dir.join("rg"))
+            .arg("needle")
+            .arg("src")
+            .output()
+            .expect("run rg stub");
+
+        assert_eq!(rg_output.status.code(), Some(127));
+        assert!(String::from_utf8_lossy(&rg_output.stderr).contains("`rg` is unavailable"));
+        assert!(allowlist.bin_dir.join("grep").exists());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn prepare_allowlist_environment_still_fails_fast_when_non_rg_command_is_missing() {
+        let _guard = env_lock();
+        let mut commands = vec!["bash", "sh"];
+        commands.extend(
+            ALLOWED_DIRECT_COMMANDS
+                .iter()
+                .copied()
+                .filter(|command| *command != "grep" && *command != "rg"),
+        );
+        let (_root, host_bin) = create_host_bin_with_commands(&commands);
+
+        let error = with_path(&host_bin, prepare_allowlist_environment)
+            .expect_err("missing non-rg command should fail");
+
+        assert!(error.contains("failed to locate host command `grep`"));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn prepare_allowlist_environment_preserves_present_command_wrapper_execution() {
+        let _guard = env_lock();
+        let self_exe = env::current_exe().expect("current exe");
+        let pwd = resolve_host_command("pwd").expect("host pwd path");
+
+        let wrapper = build_direct_wrapper(&self_exe, "pwd").expect("pwd wrapper");
+
+        assert!(wrapper.contains(INTERNAL_DIRECT_WRAPPER_FLAG));
+        assert!(wrapper.contains(&self_exe.display().to_string()));
+        assert!(wrapper.contains(&format!("pwd:{}", pwd.display())));
+        assert!(!wrapper.contains("exit 127"));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn resolve_host_command_skips_omx_explore_allowlist_wrappers() {
+        let _guard = env_lock();
+        let allowlist_root = temp_allowlist_dir().expect("allowlist root");
+        let real_root = TempDirGuard {
+            path: env::temp_dir().join(format!(
+                "omx-explore-host-resolution-{}-{}",
+                std::process::id(),
+                SystemTime::now()
+                    .duration_since(UNIX_EPOCH)
+                    .unwrap_or_default()
+                    .as_nanos()
+            )),
+        };
+        create_dir_all(&real_root.path).expect("create real root");
+        let real_bin = real_root.path.join("real-bin");
+        let allowlist_bin = allowlist_root
+            .path
+            .join(format!("{TEMP_ALLOWLIST_DIR_PREFIX}fixture"))
+            .join("bin");
+        create_dir_all(&real_bin).expect("create real bin");
+        create_dir_all(&allowlist_bin).expect("create allowlist bin");
+
+        let real_grep = real_bin.join("grep");
+        write_executable(&real_grep, "#!/bin/sh\nexit 0\n").expect("write real grep");
+        let wrapper_grep = allowlist_bin.join("grep");
+        write_executable(&wrapper_grep, "#!/bin/sh\nexit 0\n").expect("write wrapper grep");
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var(
+                "PATH",
+                env::join_paths([allowlist_bin.as_path(), real_bin.as_path()]).expect("join path"),
+            );
+        }
+
+        let resolved = resolve_host_command("grep");
+
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(resolved, Some(real_grep));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn resolve_host_command_rejects_absolute_allowlist_wrapper_paths() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let wrapper_dir = root
+            .path
+            .join(format!("{TEMP_ALLOWLIST_DIR_PREFIX}fixture"))
+            .join("bin");
+        create_dir_all(&wrapper_dir).expect("create wrapper dir");
+        let wrapper = wrapper_dir.join("grep");
+        write_executable(&wrapper, "#!/bin/sh\nexit 0\n").expect("write wrapper");
+
+        assert_eq!(
+            resolve_host_command(wrapper.to_str().expect("wrapper path")),
+            None
+        );
+    }
+
+    #[test]
+    fn discover_codex_support_dirs_includes_home_omx_and_codex_when_present() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let home_dir = root.path.join("home");
+        create_dir_all(home_dir.join(".omx")).expect("create .omx");
+        create_dir_all(home_dir.join(".codex")).expect("create .codex");
+        let original_home = env::var_os("HOME");
+        unsafe {
+            env::set_var("HOME", &home_dir);
+        }
+
+        let dirs = discover_codex_support_dirs();
+
+        match original_home {
+            Some(value) => unsafe { env::set_var("HOME", value) },
+            None => unsafe { env::remove_var("HOME") },
+        }
+        assert_eq!(dirs, vec![home_dir.join(".omx"), home_dir.join(".codex")]);
+    }
+
+    #[test]
+    fn validate_shell_invocation_rejects_control_operators_and_paths() {
+        assert!(validate_shell_invocation(&["-lc".into(), "rg auth src".into()]).is_ok());
+        assert!(validate_shell_invocation(&["-lc".into(), "rg auth src | head".into()]).is_err());
+        assert!(validate_shell_invocation(&["-lc".into(), "/usr/bin/rg auth src".into()]).is_err());
+        assert!(validate_shell_invocation(&["-lc".into(), "find . -exec rm {} +".into()]).is_err());
+        assert!(validate_shell_invocation(&["-lc".into(), "tail -f README.md".into()]).is_err());
+        assert!(
+            validate_shell_invocation(&["-lc".into(), "sed -n 1,5p README.md".into()]).is_err()
+        );
+    }
+
+    #[test]
+    fn validate_direct_command_blocks_risky_flags() {
+        assert!(validate_direct_command("rg", &["needle".into(), "src".into()]).is_ok());
+        assert!(validate_direct_command("rg", &["--pre=python".into(), "needle".into()]).is_err());
+        assert!(validate_direct_command("rg", &["needle".into(), "-".into()]).is_err());
+        assert!(validate_direct_command("grep", &["needle".into(), "src/file.ts".into()]).is_ok());
+        assert!(validate_direct_command("grep", &["needle".into()]).is_err());
+        assert!(validate_direct_command("grep", &["needle".into(), "-".into()]).is_err());
+        assert!(validate_direct_command("find", &[".".into(), "-type".into(), "f".into()]).is_ok());
+        assert!(validate_direct_command("find", &[".".into(), "-delete".into()]).is_err());
+        assert!(validate_direct_command(
+            "find",
+            &[".".into(), "-fprint".into(), "/tmp/out".into()]
+        )
+        .is_err());
+        assert!(validate_direct_command("cat", &["README.md".into()]).is_ok());
+        assert!(validate_direct_command("cat", &[]).is_err());
+        assert!(validate_direct_command("cat", &["-".into()]).is_err());
+        assert!(validate_direct_command("head", &["README.md".into()]).is_ok());
+        assert!(validate_direct_command("head", &[]).is_err());
+        assert!(validate_direct_command("wc", &["README.md".into()]).is_ok());
+        assert!(validate_direct_command("wc", &["-".into()]).is_err());
+        assert!(validate_direct_command("tail", &["README.md".into()]).is_ok());
+        assert!(validate_direct_command("tail", &[]).is_err());
+        assert!(validate_direct_command("tail", &["-f".into(), "README.md".into()]).is_err());
+        assert!(
+            validate_direct_command("sed", &["-n".into(), "1,20p".into(), "README.md".into()])
+                .is_err()
+        );
+    }
+
+    #[test]
+    fn allowlist_platform_diagnostic_blocks_windows_with_actionable_guidance() {
+        let diagnostic = allowlist_platform_diagnostic("windows").expect("windows diagnostic");
+
+        assert!(diagnostic.contains("not ready on Windows"));
+        assert!(diagnostic.contains("OMX_EXPLORE_BIN"));
+        assert!(allowlist_platform_diagnostic("linux").is_none());
+    }
+
+    #[test]
+    fn validate_direct_command_covers_additional_head_wc_and_tail_rejections() {
+        assert!(validate_direct_command("head", &["-".into()]).is_err());
+        assert!(validate_direct_command("wc", &[]).is_err());
+        assert!(validate_direct_command("tail", &["--retry".into(), "README.md".into()]).is_err());
+    }
+
+    #[test]
+    fn validate_direct_command_blocks_repo_escape_paths() {
+        let _guard = env_lock();
+        unsafe {
+            env::set_var(HARNESS_ROOT_ENV, "/repo");
+        }
+        assert!(validate_direct_command("cat", &["README.md".into()]).is_ok());
+        assert!(validate_direct_command("ls", &["src".into()]).is_ok());
+        assert!(validate_direct_command("rg", &["needle".into(), "src".into()]).is_ok());
+        assert!(
+            validate_direct_command("grep", &["needle".into(), "../secret.txt".into()]).is_err()
+        );
+        assert!(validate_direct_command("cat", &["../secret.txt".into()]).is_err());
+        assert!(
+            validate_direct_command("find", &["../".into(), "-type".into(), "f".into()]).is_err()
+        );
+        assert!(validate_direct_command("ls", &["/tmp".into()]).is_err());
+        unsafe {
+            env::remove_var(HARNESS_ROOT_ENV);
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn validate_direct_command_blocks_symlink_escape_paths() {
+        let _guard = env_lock();
+        use std::os::unix::fs::symlink;
+
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        let outside = root.path.join("outside");
+        create_dir_all(&repo).expect("create repo");
+        create_dir_all(&outside).expect("create outside");
+        write(outside.join("secret.txt"), "secret").expect("write secret");
+        symlink(&outside, repo.join("linked-outside")).expect("create symlink");
+
+        unsafe {
+            env::set_var(HARNESS_ROOT_ENV, &repo);
+        }
+        let result = validate_direct_command("cat", &["linked-outside/secret.txt".into()]);
+        unsafe {
+            env::remove_var(HARNESS_ROOT_ENV);
+        }
+
+        assert!(result.is_err());
+        assert!(result
+            .expect_err("symlink escape should fail")
+            .contains("resolves outside"));
+    }
+
+    #[test]
+    fn resolve_shebang_launch_preserves_env_arguments() {
+        let _guard = env_lock();
+        let (python_name, python) = resolve_host_command("python3")
+            .map(|path| ("python3", path))
+            .or_else(|| resolve_host_command("python").map(|path| ("python", path)))
+            .expect("host python path");
+        let shebang = format!("/usr/bin/env {} -I", python_name);
+        let launch = resolve_shebang_launch(&shebang).expect("launch");
+        assert_eq!(launch.0, python.display().to_string());
+        assert_eq!(launch.1, vec!["-I"]);
+    }
+
+    #[test]
+    fn validate_shell_invocation_rejects_empty_and_wrong_flag_forms() {
+        assert!(validate_shell_invocation(&["-lc".into(), "   ".into()]).is_err());
+        assert!(validate_shell_invocation(&["--command".into(), "rg auth src".into()]).is_err());
+        assert!(validate_shell_invocation(&["-c".into()]).is_err());
+    }
+
+    #[test]
+    fn validate_direct_command_accepts_repo_internal_absolute_paths() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(repo.join("nested")).expect("create repo");
+        write(repo.join("nested").join("file.txt"), "ok").expect("write file");
+
+        unsafe {
+            env::set_var(HARNESS_ROOT_ENV, &repo);
+        }
+        let result = validate_direct_command(
+            "cat",
+            &[repo.join("nested").join("file.txt").display().to_string()],
+        );
+        unsafe {
+            env::remove_var(HARNESS_ROOT_ENV);
+        }
+
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn command_path_operands_handle_double_dash_and_find_roots() {
+        let rg_args = vec![
+            "needle".to_string(),
+            "--".to_string(),
+            "src/lib.rs".to_string(),
+        ];
+        assert_eq!(command_path_operands("rg", &rg_args), vec!["src/lib.rs"]);
+
+        let find_args = vec![
+            "src".to_string(),
+            "tests".to_string(),
+            "-type".to_string(),
+            "f".to_string(),
+        ];
+        assert_eq!(
+            command_path_operands("find", &find_args),
+            vec!["src", "tests"]
+        );
+    }
+
+    #[test]
+    fn run_with_args_reports_both_failed_attempts_with_codes_and_stderr() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(&repo).expect("create repo");
+        let prompt_file = root.path.join("prompt.md");
+        write(&prompt_file, "contract").expect("write prompt");
+        let fake_codex = root.path.join("codex-stub");
+        write_executable(
+            &fake_codex,
+            r#"#!/bin/sh
+model=""
+while [ $# -gt 0 ]; do
+  if [ "$1" = "-m" ]; then
+    shift
+    model="$1"
+  fi
+  shift
+done
+printf 'simulated stderr for %s
+' "$model" >&2
+if [ "$model" = "spark-model" ]; then
+  exit 9
+fi
+exit 17
+"#,
+        )
+        .expect("write fake codex");
+
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, &fake_codex);
+        }
+        let result = run_with_args(
+            vec![
+                "--cwd",
+                repo.to_str().expect("repo path"),
+                "--prompt",
+                "find tests",
+                "--prompt-file",
+                prompt_file.to_str().expect("prompt path"),
+                "--instructions-file",
+                prompt_file.to_str().expect("instructions path"),
+                "--model-spark",
+                "spark-model",
+                "--model-fallback",
+                "fallback-model",
+            ]
+            .into_iter()
+            .map(OsString::from),
+        );
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+        }
+
+        let _error = result.expect_err("both attempts should fail");
+    }
+
+    #[test]
+    fn invoke_codex_clears_shell_startup_env_before_launching_codex() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(&repo).expect("create repo");
+        let prompt_file = root.path.join("prompt.md");
+        write(&prompt_file, "contract").expect("write prompt");
+        let capture_path = root.path.join("capture.txt");
+        let fake_codex = root.path.join("codex-stub");
+        write_executable(
+            &fake_codex,
+            &format!(
+                r#"#!/bin/sh
+set -eu
+output_path=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "-o" ]; then
+    shift
+    output_path="$1"
+  fi
+  shift
+done
+printf 'BASH_ENV=%s\nENV=%s\nPROMPT_COMMAND=%s\n' "${{BASH_ENV:-}}" "${{ENV:-}}" "${{PROMPT_COMMAND:-}}" > {}
+printf '# Answer\nok\n' > "$output_path"
+"#,
+                shell_quote(&capture_path.display().to_string())
+            ),
+        )
+        .expect("write fake codex");
+
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, &fake_codex);
+            env::set_var("BASH_ENV", "/tmp/bash-env-should-not-leak");
+            env::set_var("ENV", "/tmp/env-should-not-leak");
+            env::set_var("PROMPT_COMMAND", "printf should-not-run");
+        }
+        let attempt = invoke_codex(
+            &Args {
+                cwd: repo.clone(),
+                prompt: "find tests".to_string(),
+                prompt_file,
+                instructions_file: repo.join("AGENTS.md"),
+                spark_model: "spark-model".to_string(),
+                fallback_model: "fallback-model".to_string(),
+            },
+            "spark-model",
+            "contract",
+        )
+        .expect("invoke codex");
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+            env::remove_var("BASH_ENV");
+            env::remove_var("ENV");
+            env::remove_var("PROMPT_COMMAND");
+        }
+
+        assert_eq!(attempt.status_code, 0);
+        assert_eq!(
+            read_to_string(&capture_path).expect("read capture"),
+            "BASH_ENV=\nENV=\nPROMPT_COMMAND=\n"
+        );
+    }
+
+    #[test]
+    fn invoke_codex_scrubs_node_options_before_node_shebang_launch() {
+        let _guard = env_lock();
+        if resolve_host_command("node").is_none() {
+            return;
+        }
+
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(&repo).expect("create repo");
+        let prompt_file = root.path.join("prompt.md");
+        write(&prompt_file, "contract").expect("write prompt");
+        let capture_path = root.path.join("node-options.txt");
+        let fake_codex = root.path.join("codex-node-stub");
+        write(
+            &fake_codex,
+            format!(
+                r#"#!/usr/bin/env node
+const fs = require('fs');
+let outputPath = '';
+for (let index = 2; index < process.argv.length; index += 1) {{
+  if (process.argv[index] === '-o') {{
+    outputPath = process.argv[index + 1];
+    index += 1;
+  }}
+}}
+fs.writeFileSync({}, `NODE_OPTIONS=${{process.env.NODE_OPTIONS || ''}}\n`);
+fs.writeFileSync(outputPath, '# Answer\nok\n');
+"#,
+                shell_quote(&capture_path.display().to_string())
+            ),
+        )
+        .expect("write fake codex");
+
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, &fake_codex);
+            env::set_var("NODE_OPTIONS", "--disable-warning=");
+        }
+        let attempt = invoke_codex(
+            &Args {
+                cwd: repo.clone(),
+                prompt: "find tests".to_string(),
+                prompt_file,
+                instructions_file: repo.join("AGENTS.md"),
+                spark_model: "spark-model".to_string(),
+                fallback_model: "fallback-model".to_string(),
+            },
+            "spark-model",
+            "contract",
+        )
+        .expect("invoke codex");
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+            env::remove_var("NODE_OPTIONS");
+        }
+
+        assert_eq!(attempt.status_code, 0);
+        assert_eq!(
+            read_to_string(&capture_path).expect("read capture"),
+            "NODE_OPTIONS=\n"
+        );
+    }
+
+    #[test]
+    fn invoke_codex_injects_model_instructions_file_override() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(&repo).expect("create repo");
+        let prompt_file = root.path.join("prompt.md");
+        write(&prompt_file, "contract").expect("write prompt");
+        let capture_path = root.path.join("argv.txt");
+        let fake_codex = root.path.join("codex-stub");
+        write_executable(
+            &fake_codex,
+            &format!(
+                r#"#!/bin/sh
+set -eu
+output_path=""
+capture={}
+printf '' > "$capture"
+while [ "$#" -gt 0 ]; do
+  printf '%s\n' "$1" >> "$capture"
+  if [ "$1" = "-o" ]; then
+    shift
+    output_path="$1"
+  fi
+  shift
+done
+printf '# Answer\nok\n' > "$output_path"
+"#,
+                shell_quote(&capture_path.display().to_string())
+            ),
+        )
+        .expect("write fake codex");
+
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, &fake_codex);
+        }
+        let instructions_path = repo.join("custom instructions.md");
+        let attempt = invoke_codex(
+            &Args {
+                cwd: repo.clone(),
+                prompt: "find tests".to_string(),
+                prompt_file,
+                instructions_file: instructions_path.clone(),
+                spark_model: "spark-model".to_string(),
+                fallback_model: "fallback-model".to_string(),
+            },
+            "spark-model",
+            "contract",
+        )
+        .expect("invoke codex");
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+        }
+
+        assert_eq!(attempt.status_code, 0);
+        let captured = read_to_string(&capture_path).expect("read capture");
+        let expected = format!(
+            "model_instructions_file=\"{}\"",
+            escape_toml_string(&instructions_path.display().to_string())
+        );
+        assert!(
+            captured.contains(&expected),
+            "expected {:?} in {:?}",
+            expected,
+            captured
+        );
+    }
+
+    #[test]
+    fn sanitize_explore_subprocess_env_blocks_bash_env_startup_hooks() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let bash_env_log = root.path.join("bash-env.log");
+        let bash_env = root.path.join("bash-env.sh");
+        write(
+            &bash_env,
+            format!(
+                "printf 'startup:%s\\n' \"$BASH_ENV\" >> {}\n",
+                shell_quote(&bash_env_log.display().to_string())
+            ),
+        )
+        .expect("write bash env");
+        let bash_path = resolve_host_command("bash").expect("host bash path");
+
+        unsafe {
+            env::set_var("BASH_ENV", &bash_env);
+        }
+        let mut child = Command::new(bash_path);
+        child
+            .arg("--noprofile")
+            .arg("--norc")
+            .arg("-lc")
+            .arg("true");
+        sanitize_explore_subprocess_env(&mut child);
+        let status = child.status().expect("run bash");
+        unsafe {
+            env::remove_var("BASH_ENV");
+        }
+
+        assert!(status.success());
+        assert_eq!(read_to_string(&bash_env_log).unwrap_or_default(), "");
+    }
+
+    #[test]
+    fn execute_validated_shell_drops_login_flag_and_startup_env() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let fake_shell = root.path.join("fake-sh");
+        let argv_log = root.path.join("argv.log");
+        let startup_log = root.path.join("startup.log");
+        let bash_env = root.path.join("bash-env.sh");
+        write(
+            &bash_env,
+            format!(
+                "grep -qsi '^COLOR.*none' /etc/GREP_COLORS || true\nprintf startup >> {}\n",
+                shell_quote(&startup_log.display().to_string())
+            ),
+        )
+        .expect("write fake startup hook");
+        write_executable(
+            &fake_shell,
+            &format!(
+                r#"#!/bin/sh
+printf '%s
+' "$@" > {}
+if [ "${{BASH_ENV:-}}" ]; then
+  . "$BASH_ENV"
+fi
+if [ "$1" = "-lc" ]; then
+  grep -qsi '^COLOR.*none' /etc/GREP_COLORS
+fi
+if [ "$1" = "-c" ]; then
+  shift
+  exec /bin/sh -c "$1"
+fi
+exit 64
+"#,
+                shell_quote(&argv_log.display().to_string())
+            ),
+        )
+        .expect("write fake shell");
+
+        unsafe {
+            env::set_var("BASH_ENV", &bash_env);
+            env::set_var("ENV", &bash_env);
+            env::set_var(
+                "PROMPT_COMMAND",
+                "grep -qsi '^COLOR.*none' /etc/GREP_COLORS",
+            );
+        }
+        let status = execute_validated_shell(
+            &fake_shell.display().to_string(),
+            "printf shell-ok >/dev/null",
+        )
+        .expect("execute fake shell");
+        unsafe {
+            env::remove_var("BASH_ENV");
+            env::remove_var("ENV");
+            env::remove_var("PROMPT_COMMAND");
+        }
+
+        assert_eq!(status, 0);
+        assert_eq!(
+            read_to_string(&argv_log).expect("read argv"),
+            "-c\nprintf shell-ok >/dev/null\n"
+        );
+        assert_eq!(read_to_string(&startup_log).unwrap_or_default(), "");
+    }
+
+    #[test]
+    fn sanitize_explore_subprocess_env_blocks_fedora_grep_colors_startup_hook() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(&repo).expect("create repo");
+        let startup_log = root.path.join("startup.log");
+        let bash_env = root.path.join("bash-env.sh");
+        write(
+            &bash_env,
+            format!(
+                "grep -qsi '^COLOR.*none' /etc/GREP_COLORS || true\nprintf 'fedora-startup-ran\n' >> {}\n",
+                shell_quote(&startup_log.display().to_string())
+            ),
+        )
+        .expect("write bash env");
+        let allowlist = prepare_allowlist_environment().expect("allowlist environment");
+        let bash_path = resolve_host_command("bash").expect("host bash path");
+
+        unsafe {
+            env::set_var("BASH_ENV", &bash_env);
+            env::set_var("ENV", &bash_env);
+            env::set_var(
+                "PROMPT_COMMAND",
+                "grep -qsi '^COLOR.*none' /etc/GREP_COLORS",
+            );
+        }
+        let mut child = Command::new(bash_path);
+        child
+            .arg("--noprofile")
+            .arg("--norc")
+            .arg("-c")
+            .arg("true")
+            .env(HARNESS_ROOT_ENV, &repo)
+            .env(
+                "PATH",
+                build_codex_path(&allowlist.bin_dir, allowlist.sandbox_bin_dir.as_deref())
+                    .expect("restricted path"),
+            );
+        sanitize_explore_subprocess_env(&mut child);
+        let output = child.output().expect("run bash");
+        unsafe {
+            env::remove_var("BASH_ENV");
+            env::remove_var("ENV");
+            env::remove_var("PROMPT_COMMAND");
+        }
+
+        assert!(output.status.success());
+        assert_eq!(read_to_string(&startup_log).unwrap_or_default(), "");
+        assert!(
+            !String::from_utf8_lossy(&output.stderr).contains("/etc/GREP_COLORS"),
+            "stderr should not contain Fedora GREP_COLORS repo escape: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    #[test]
+    fn invoke_codex_times_out_and_returns_bounded_failure() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(&repo).expect("create repo");
+        let prompt_file = root.path.join("prompt.md");
+        write(&prompt_file, "contract").expect("write prompt");
+        let fake_codex = root.path.join("codex-sleep");
+        write_executable(
+            &fake_codex,
+            r#"#!/bin/sh
+printf 'fake codex started
+' >&2
+/bin/sleep 5
+"#,
+        )
+        .expect("write fake codex");
+
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, &fake_codex);
+            env::set_var(CODEX_TIMEOUT_MS_ENV, "100");
+        }
+        let started = Instant::now();
+        let attempt = invoke_codex(
+            &Args {
+                cwd: repo.clone(),
+                prompt: "find tests".to_string(),
+                prompt_file,
+                instructions_file: repo.join("AGENTS.md"),
+                spark_model: "spark-model".to_string(),
+                fallback_model: "fallback-model".to_string(),
+            },
+            "spark-model",
+            "contract",
+        )
+        .expect("invoke codex");
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+            env::remove_var(CODEX_TIMEOUT_MS_ENV);
+        }
+
+        assert_eq!(attempt.status_code, 124);
+        assert!(attempt.stderr.contains("timed out after 100ms"));
+        assert!(attempt.stderr.contains("terminated process tree"));
+        assert!(started.elapsed() < Duration::from_secs(3));
+        assert!(attempt.output_markdown.is_none());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn run_command_with_timeout_kills_process_group_children() {
+        let _env_guard = env_lock();
+        let _process_guard = process_tree_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let term_file = root.path.join("grandchild.term");
+        let ready_file = root.path.join("grandchild.ready");
+        let script = root.path.join("spawn-grandchild.sh");
+        write_executable(
+            &script,
+            &format!(
+                r#"#!/bin/sh
+(trap 'printf term > {}; exit 0' TERM; printf ready > {}; sleep 30) &
+while [ ! -f {} ]; do
+  sleep 0.01
+done
+sleep 30
+"#,
+                shell_quote(&term_file.display().to_string()),
+                shell_quote(&ready_file.display().to_string()),
+                shell_quote(&ready_file.display().to_string()),
+            ),
+        )
+        .expect("write script");
+
+        let result = run_command_with_timeout(Command::new(&script), Duration::from_millis(500))
+            .expect("run with timeout");
+        let TimedCommandOutput::TimedOut { .. } = result else {
+            panic!("expected timeout");
+        };
+        let deadline = Instant::now() + Duration::from_secs(2);
+        while !term_file.exists() && Instant::now() < deadline {
+            std::thread::sleep(Duration::from_millis(10));
+        }
+        assert_eq!(read_to_string(&term_file).unwrap_or_default(), "term");
+    }
+
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn run_command_with_timeout_aborts_suspicious_process_storm() {
+        let _env_guard = env_lock();
+        let _process_guard = process_tree_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let script = root.path.join("storm.sh");
+        write_executable(
+            &script,
+            r#"#!/bin/sh
+while :; do
+  sleep 30 &
+  sleep 0.01
+done
+"#,
+        )
+        .expect("write script");
+
+        unsafe {
+            env::set_var(PROCESS_LIMIT_ENV, "12");
+        }
+        let started = Instant::now();
+        let result = run_command_with_timeout(Command::new(&script), Duration::from_secs(10))
+            .expect("run with process storm");
+        unsafe {
+            env::remove_var(PROCESS_LIMIT_ENV);
+        }
+
+        let TimedCommandOutput::ProcessLimitExceeded {
+            process_count,
+            process_limit,
+            ..
+        } = result
+        else {
+            panic!("expected process limit failure");
+        };
+        assert!(process_count > process_limit);
+        assert!(started.elapsed() < Duration::from_secs(5));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn run_command_with_timeout_fails_closed_on_large_stdout() {
+        let _env_guard = env_lock();
+        let _process_guard = process_tree_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let script = root.path.join("large-stdout.sh");
+        write_executable(
+            &script,
+            r#"#!/bin/sh
+while :; do
+  printf 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+done
+"#,
+        )
+        .expect("write script");
+
+        unsafe {
+            env::set_var(CODEX_OUTPUT_LIMIT_BYTES_ENV, "4096");
+        }
+        let started = Instant::now();
+        let result = run_command_with_timeout(Command::new(&script), Duration::from_secs(10))
+            .expect("run with large stdout");
+        unsafe {
+            env::remove_var(CODEX_OUTPUT_LIMIT_BYTES_ENV);
+        }
+
+        let TimedCommandOutput::OutputLimitExceeded {
+            stream,
+            output_limit,
+            ..
+        } = result
+        else {
+            panic!("expected stdout output limit failure");
+        };
+        assert_eq!(stream, "stdout");
+        assert_eq!(output_limit, 4096);
+        assert!(started.elapsed() < Duration::from_secs(3));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn run_command_with_timeout_fails_closed_on_large_stderr() {
+        let _env_guard = env_lock();
+        let _process_guard = process_tree_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let script = root.path.join("large-stderr.sh");
+        write_executable(
+            &script,
+            r#"#!/bin/sh
+while :; do
+  printf 'eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee' >&2
+done
+"#,
+        )
+        .expect("write script");
+
+        unsafe {
+            env::set_var(CODEX_OUTPUT_LIMIT_BYTES_ENV, "4096");
+        }
+        let started = Instant::now();
+        let result = run_command_with_timeout(Command::new(&script), Duration::from_secs(10))
+            .expect("run with large stderr");
+        unsafe {
+            env::remove_var(CODEX_OUTPUT_LIMIT_BYTES_ENV);
+        }
+
+        let TimedCommandOutput::OutputLimitExceeded {
+            stream,
+            output_limit,
+            ..
+        } = result
+        else {
+            panic!("expected stderr output limit failure");
+        };
+        assert_eq!(stream, "stderr");
+        assert_eq!(output_limit, 4096);
+        assert!(started.elapsed() < Duration::from_secs(3));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn run_command_with_timeout_closes_inherited_stdio_after_parent_exit() {
+        let _env_guard = env_lock();
+        let _process_guard = process_tree_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let script = root.path.join("inherited-stdio.sh");
+        write_executable(
+            &script,
+            r#"#!/bin/sh
+(sleep 30) &
+printf 'parent stdout\n'
+printf 'parent stderr\n' >&2
+exit 0
+"#,
+        )
+        .expect("write script");
+
+        let started = Instant::now();
+        let result = run_command_with_timeout(Command::new(&script), Duration::from_secs(10))
+            .expect("run with inherited stdio descendant");
+
+        let TimedCommandOutput::Completed(output) = result else {
+            panic!("expected parent completion");
+        };
+        assert!(
+            started.elapsed() < Duration::from_secs(3),
+            "reader cleanup should not wait for the descendant sleep"
+        );
+        assert!(output.status.success());
+        assert_eq!(String::from_utf8_lossy(&output.stdout), "parent stdout\n");
+        assert_eq!(String::from_utf8_lossy(&output.stderr), "parent stderr\n");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn run_command_with_timeout_sweeps_detached_grandchildren_after_parent_exit() {
+        let _env_guard = env_lock();
+        let _process_guard = process_tree_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let term_file = root.path.join("orphan.term");
+        let ready_file = root.path.join("orphan.ready");
+        let script = root.path.join("spawn-detached-grandchild.sh");
+        write_executable(
+            &script,
+            &format!(
+                r#"#!/bin/sh
+(trap 'printf term > {}; exit 0' TERM; printf ready > {}; sleep 30) >/dev/null 2>&1 &
+while [ ! -f {} ]; do
+  sleep 0.01
+done
+printf 'parent done\n'
+exit 0
+"#,
+                shell_quote(&term_file.display().to_string()),
+                shell_quote(&ready_file.display().to_string()),
+                shell_quote(&ready_file.display().to_string()),
+            ),
+        )
+        .expect("write script");
+
+        let result = run_command_with_timeout(Command::new(&script), Duration::from_secs(10))
+            .expect("run with detached grandchild");
+
+        let TimedCommandOutput::Completed(output) = result else {
+            panic!("expected parent completion");
+        };
+        assert!(output.status.success());
+        assert_eq!(String::from_utf8_lossy(&output.stdout), "parent done\n");
+        assert_eq!(read_to_string(&term_file).unwrap_or_default(), "term");
+    }
+
+    fn fallback_test_event() -> FallbackEvent {
+        FallbackEvent {
+            from_model: "spark-model".to_string(),
+            to_model: "fallback-model".to_string(),
+            exit_code: 17,
+            stderr: "spark timed out".to_string(),
+        }
+    }
+
+    #[test]
+    fn fallback_attempt_event_distinguishes_attempt_from_output_notice() {
+        let event = fallback_test_event();
+
+        let message = fallback_attempt_event_message(&event);
+        assert!(message.contains("fallback-attempt=model"));
+        assert!(message.contains("from=`spark-model`"));
+        assert!(message.contains("to=`fallback-model`"));
+        assert!(message.contains("spark_attempt_failed exit=17"));
+        assert!(message
+            .contains("stdout fallback notice is emitted only after successful fallback output"));
+        assert!(!message.contains("output includes a fallback notice"));
+        assert!(!message.contains("## OMX Explore fallback"));
+    }
+
+    #[test]
+    fn fallback_output_notice_records_model_boundary() {
+        let event = fallback_test_event();
+
+        let notice = fallback_output_notice(&event);
+        assert!(notice.contains("## OMX Explore fallback"));
+        assert!(notice.contains("fallback: model"));
+        assert!(notice.contains("from: `spark-model`"));
+        assert!(notice.contains("to: `fallback-model`"));
+        assert!(notice.contains("spark attempt failed with exit 17"));
+        assert!(notice.contains("cost/behavior may differ from the low-cost spark path"));
+    }
+
+    #[test]
+    fn print_attempt_output_requires_markdown_artifact() {
+        let result = print_attempt_output(AttemptResult {
+            status_code: 0,
+            stderr: String::new(),
+            output_markdown: None,
+        });
+        assert!(result.is_err());
+        assert!(result
+            .expect_err("missing markdown should fail")
+            .contains("expected markdown output artifact"));
+    }
+}