feat(codex): raise codex approval, question and trust dialogs as BLOCKED

[Ark0N]

Codeman shows a session as BLOCKED (a red tab, a desktop notification, web push, webhooks, the phone overview's NEEDS YOU row, an Approvals Inbox card and the blocked wait signal) when an agent stops to ask the user something. Until now that came only from Claude Code's hooks and the DeepSeek Harness status bridge. Codex has no hooks, yet it is launched with its approvals on by default. So a codex session waiting on "Would you like to run the following command?" looked plainly idle, and one waiting on a question looked WORKING: the question's key hints contain esc to interrupt, which is codex's working line. This PR reads codex's dialogs off its screen and raises exactly what a Claude permission_prompt hook raises, as an alert only. Codeman never answers a codex dialog. It does not touch Claude or DeepSeek behavior, the inbox's answer flow, or any other CLI. Codex's stop signal stays a 400.

How it works

• Registry data, no id branch. A new optional field capabilities.workDetect.blockedLine (a regex), plus blockedLines (window size, 1 to 24). It is validated through compileVersionRegex() in the schema refine and again when first used. Only codex declares one. Its pattern needs a › N. option row followed by the dialog's own key-hint row as the LAST row of the window (allowing for that row to wrap at narrow widths). It was measured on live codex-cli 0.162.0 at widths 200 to 36, and 31 sanitized captures are checked in as fixtures.
• Session state. isBlockedScreen() (pure, src/session-activity.ts) is tested against the capture the idle confirmation already takes. The state raises on one reading and emits blockedChanged. A blocked screen wins over the working line in the same capture. While a dialog is up a timer re-reads every 2 s, but skips the read while the pane has drawn nothing since the last reading that saw the dialog. A dialog can only leave through a repaint, and every repaint reaches the session as output. A safety-net read still runs every 30 s. The state clears after 2 readable captures in a row without the dialog, and an unreadable capture changes nothing.
• Server. src/web/screen-blocked.ts turns the edge into the hook route's outputs: notifySignal('blocked'), an answerInTerminal inbox item with the frame as context, hook:permission_prompt with source: 'screen', push and webhook (no approvalId, so no Approve/Deny), and a run-summary row. The clear resolves only the item it opened. The message every surface shows is built from the registry label, never from screen text.
• Waits. blockedSignalAvailable() (hooks OR blockedLine) lets codex accept until=blocked. Because a screen-read dialog is a level, GET .../wait and a duplicate send-and-wait answer blocked at once for a caller that asked for it. A caller that asked only for idle still gets idle.

Testing

• Unit and route tests: fixture matching (17 dialogs, 14 negatives including a transcript quoting the dialog and the composer holding its words), session state transitions, the quiet-pane skip, server raise and clear, wait routes, the approval answer route, the push body, and the registry schema.
• Full npm test gate: 569 files passed, 1 skipped; 11,328 tests passed, 12 skipped. Typecheck, lint, format, the CLI catalogue check and the plugin mirror check are clean.
• Live end-to-end on an isolated beta instance with real codex-cli 0.162.0 (approvals forced on, only a scratch repo trusted, ~/.codex/config.toml hash unchanged):
  • Command approval: wait?until=blocked resolved in 7.2 s, and the tab turned red in the browser. Answering y cleared it about 3 s later, the file was created, and nothing re-fired.
  • Two approvals back to back: each raised its own alert and cleared 2.1 s and 2.9 s after its answer. A live page showed red, clear, red, clear.
  • Question dialog (Plan mode): the session read idle, not working, while the question was up, and it cleared 2.1 s after Enter.
  • Trust prompt in an untrusted repository: blocked after 4.5 s. Deleting the session resolved the alert as session_ended.
  • Left unanswered for 80 s: 4 screen reads (2 caused by a browser resize, then one per 30 s), instead of about 40.

Reviewing the diff

About 2,900 added lines, most of them mechanical:

• Fixtures test/fixtures/codex-dialogs/*.txt: about 1,300 lines of captured screens.
• Docs: about 330 lines (docs/, docs/wiki/, both READMEs, CLAUDE.md, the skill reference and its plugin mirror, which scripts/sync-plugin.mjs generates).
• Tests: about 760 lines.
• i18n and frontend: 9 lines (one zh-CN pattern, the notification text).

About 300 lines of logic need real review. Start with isBlockedScreen() and the constants in src/session-activity.ts, then the _probePaneWorking, _noteBlockedReading, _armBlockedRecheck and _clearScreenBlocked block in src/session.ts. Then read src/web/screen-blocked.ts and its wiring in src/web/session-listener-wiring.ts, the wait changes in src/web/session-wait-registry.ts and src/web/routes/session-routes.ts, and the reordered guard in src/web/routes/approval-routes.ts. The codex regex sits in src/config/cli-registry/stock.ts, under a comment that records what was measured.

Risk

• Pane text drives an alert. The agent writes most of the screen, so the pattern must end on chrome only codex draws at the foot of the pane. A forged or accidental match costs a false alert and nothing else: the item is alert-only, and no keystroke is ever derived from it. The one known residual is the user typing the dialog's exact hint text into their own composer under a lowercase model name.
• Raise on one read, clear on two. That choice trades 2 to 4 s of alert after an answer for never double-pushing on a mid-repaint capture. The quiet-pane skip relies on every screen change reaching the session as output, with the 30 s safety-net read as a backstop.

Follow-ups

• Answering codex dialogs from the Approvals Inbox: measure codex's keystroke contract first.
• codeman tui should hide answer keys for alert-only items (same today for DeepSeek).
• Two dialogs inside the 2 to 4 s clear window share one alert and one push. A Codeman restart with a dialog up pushes again.
• Not yet measured, so likely not matched: MCP elicitation dialogs, the experimental network proxy approval, and Implement this plan?, which is excluded on purpose because its footer matches /model.
• Remote SSH and Docker codex sessions were not tested end to end.