fix(codex): startup-prompt handling that can't live-lock or block the loop (split from #566)

CHANGELOG.md

@@ -16,6 +16,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Codex startup handling could stall a launch, or press keys into the wrong
+  dialog.** `startup_prompt_handler_timeout` is now the idle gap between
+  startup prompts, with `provider_init_timeout` as the hard cap, so lowering
+  the gap for another provider no longer truncates Codex's handler; the
+  first-run sign-in menu is recognised as a settled state instead of running
+  the handler to its cap; the handler now decides once per frame which startup
+  block is actually live at the bottom of the pane and sends a key only to
+  that block, so stale trust text left in scrollback can no longer answer a
+  live update dialog or sign-in menu; a frame in which a further dialog is
+  still being drawn is held rather than keyed, whether or not a complete
+  dialog is on screen above it; the idle gap is judged on a freshly read frame
+  with no dialog on it, not on the clock alone; the idle composer takes part in
+  that same positional decision and status detection uses the same resolver, so
+  trust wording a dismissed dialog leaves above the live composer no longer
+  reports `WAITING_USER_ANSWER` and a modal arriving below a stale composer no
+  longer reads as ready; initialisation fails, instead of succeeding through
+  the login menu's `WAITING_USER_ANSWER` path, when a trust or update dialog is
+  still on screen at the handler's cap or after the readiness wait; and a
+  profile's own `provider_init_timeout` now governs every Codex initialisation
+  wait (#731)
+
 - **enabling `CAO_MEMORY_API_URL` rejected memory keys that work without it.**
   The `/internal/memory/store` and `/forget` routes validated the wire `key` as
   the strict `MemoryKey` (`^[a-z0-9-]{1,60}$`), while the MCP tools have always

docs/codex-cli.md

@@ -22,6 +22,13 @@ export OPENAI_API_KEY=your-key-here
 codex login
 ```
 
+> **Security note.** If Codex is launched under CAO without credentials, the
+> startup handler leaves the first-run sign-in menu on screen for an operator to
+> complete (it cannot be answered automatically). That live sign-in pane — OAuth
+> device code or API-key paste — is attachable through the Web UI and the PTY
+> WebSocket like any other CAO terminal, so enable control-plane authentication
+> before launching Codex workers that will need to sign in interactively.
+
 ### Using Codex Provider with CAO
 
 Create a terminal using the Codex provider:

docs/configuration.md

@@ -138,8 +138,8 @@ Timeouts and buffer sizes used by the CAO runtime. All values have safe defaults
 |---------|---------|--------------|
 | `mcp_request_timeout` | `30` | Seconds to wait for HTTP calls between the MCP server process and the CAO API. |
 | `event_bus_max_queue_size` | `1024` | Max events buffered per subscriber queue in the internal event bus. |
-| `provider_init_timeout` | `60` | Seconds to wait for a CLI agent to reach IDLE. Also the hard outer cap on total time a startup-prompt handler (Claude Code, Kimi, Antigravity) may run. Overridable per-profile via `provider_init_timeout` in the agent profile — see [Agent Profile Format](agent-profile.md#optional-fields). |
-| `startup_prompt_handler_timeout` | `20` | Idle gap, in seconds, between consecutive startup prompts (e.g. workspace trust / bypass dialogs, Kimi's upgrade dialog, Antigravity's trust/survey dialogs). The handler polls and resets this timer each time it answers a prompt; it only starts counting once the FIRST prompt has been handled, so a first dialog arriving later than this value (e.g. a cold/containerized start) is still caught — before any prompt is seen, only `provider_init_timeout` bounds the wait. Once at least one prompt has been handled, the handler exits after this many seconds pass with no further prompt. |
+| `provider_init_timeout` | `60` | Seconds to wait for a CLI agent to reach IDLE. Also the hard outer cap on total time a startup-prompt handler (Claude Code, Kimi, Antigravity, Codex) may run; Codex fails initialisation if a trust or update dialog is still on screen when the cap is reached. Overridable per-profile via `provider_init_timeout` in the agent profile — see [Agent Profile Format](agent-profile.md#optional-fields). |
+| `startup_prompt_handler_timeout` | `20` | Idle gap, in seconds, between consecutive startup prompts (e.g. workspace trust / bypass dialogs, Kimi's upgrade dialog, Antigravity's trust/survey dialogs, Codex's trust and update dialogs). The handler polls and resets this timer each time it answers a prompt; it only starts counting once the FIRST prompt has been handled, so a first dialog arriving later than this value (e.g. a cold/containerized start) is still caught — before any prompt is seen, only `provider_init_timeout` bounds the wait. Once at least one prompt has been handled, the handler exits after this many seconds pass with no further prompt. |
 | `state_buffer_max` | `32768` | Bytes of raw terminal output `StatusMonitor` keeps per terminal for raw-path status detection and `GET /terminals/{id}/output` (`mode=full`). Not unbounded scrollback — a long, chatty session is truncated to this trailing window; raise it if a still-pending prompt is getting evicted before it's read back. |
 
 ### Memory (`memory`)