Add Codex remote-control backend

README.md

@@ -178,6 +178,24 @@ preamble        = "set -a; . ./.env; set +a"   # shell run before launch (e.g. l
 active_re = "esc interrupt|thinking|running tool|preparing patch"
 limit_re  = "usage limit|limit reached"
 
+[backend.codex]                 # Codex TUI, exposed through Codex Remote Control
+bin             = "codex"
+preamble        = "{bin} remote-control start --json >/dev/null"
+flags           = "--dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust --no-alt-screen"
+supports_resume = false         # thread-ID persistence is not implemented by this harness
+prompt_delivery = "arg"
+process_name    = "codex"
+footer_ui       = true
+log_grace       = 180
+submit_key      = "Enter"
+startup_prompt_re       = "Trusting the directory|Do you trust"
+startup_prompt_response = "1" # explicitly trust the agent's configured working directory
+startup_prompt_delay    = 2
+stall_idle      = 300
+active_re = "esc to interrupt|working|thinking|running|searching|exploring|implementing"
+limit_re  = "usage limit|limit reached|reached your .*limit|out of (credits|tokens)"
+fatal_re  = "connection is errored|not logged in|authentication required"
+
 [backend.demo]                  # a dependency-free backend for testing the harness mechanics
 bin             = "echo '[demo] {session} up'; exec sleep 1000000"
 prompt_delivery = "exec"        # {kickoff}=prompt file, {session}=session name, {model}=model
@@ -187,6 +205,13 @@ For an `"arg"` backend the flag *templates* are configurable (so you can point a
 CLI): `resume_flag` (default `--resume '{id}'`), `model_flag` (default `--model '{model}'`),
 `remote_control_flag` (default `--remote-control '{session}'`). A backend that sets `process_name`
 participates in backend-mismatch healing; one that doesn't (e.g. `demo`) never does.
+An optional `preamble` runs first and must succeed before the TUI starts; it supports `{bin}`,
+`{session}`, `{model}`, and `{dir}` templates. The Codex backend uses it to idempotently start the
+shared Remote Control daemon before launching each tmux-hosted Codex TUI.
+For an unattended TUI with a deterministic first-run gate, `startup_prompt_re` opts into one
+screen check after `startup_prompt_delay` seconds; on a match, the harness types the explicitly
+configured `startup_prompt_response` and `submit_key`. Codex uses this to trust the agent's
+configured project directory so its argv kickoff can proceed.
 
 ### `[[agent]]` — one block per agent
 
@@ -438,7 +463,7 @@ nix develop -c python3 agents.py selftest      # or run one command in it
 nix flake check                                # evaluate + build the devShell
 ```
 
-The agent CLIs themselves (`claude`, `opencode`) are **external, non-Nix tools** — install them
+The agent CLIs themselves (`claude`, `codex`, `opencode`) are **external, non-Nix tools** — install them
 per their own docs and make sure they are on `PATH` before launching live agents. The devShell
 documents this in its banner.
 
@@ -461,13 +486,15 @@ What it runs:
   parsing, `WAITING-UNTIL` / stall parsing, and the per-backend activity detectors (claude +
   opencode footers). Always run; a failure fails the suite. Run them alone with
   `python3 -m unittest discover -s tests` (or `python3 tests/test_unit.py`).
-- **Live backend smokes** (`tests/smoke_claude.sh`, `tests/smoke_opencode.sh`) — each brings a
+- **Live backend smokes** (`tests/smoke_claude.sh`, `tests/smoke_codex.sh`,
+  `tests/smoke_opencode.sh`) — each brings a
   throwaway scratch project up **through `agents.py`** on a real backend, in a fully isolated
   sandbox (its own unique `session_prefix`, a temp `log_dir`, and — for opencode — a dedicated
   server on a non-default port `AOTEST_OC_PORT`, default `4097`), confirms the session attaches and
   `status` reports it RUNNING, then `down`s it and cleans up (no leftover sessions, port freed).
   Each **SKIPs gracefully** (exit 0) when its backend's binary or creds are unavailable. Useful env:
-  `CLAUDE_BIN` / `OPENCODE_BIN`, `AOTEST_MODEL`, `AOTEST_OC_PORT`, `AOTEST_OC_CREDS`.
+  `CLAUDE_BIN` / `CODEX_BIN` / `OPENCODE_BIN`, `AOTEST_MODEL`, `AOTEST_OC_PORT`,
+  `AOTEST_OC_CREDS`.
 - **Isolation sanity** — after the live runs, the runner asserts no `aotest-*` tmux sessions leaked
   and reports that any live sessions are untouched.