fix(codex): open the TUI on the role's recorded thread, and let the bridge attach to it

[hakohund]

Closes #959. On main (rebased over #943, which touched the same launcher hunk).

Problem

Once a Codex role has a recorded seat, a plain monitored codex in that project can never show the conversation the bridge delivers to:

codex-monitor.sh:247	a plain codex is codex --remote <url> — a fresh thread
codex-bridge-launcher.sh:667-680	the bridge is bound to the role's recorded thread, nothing else (#350)
codex-record-session.sh:75-87	an existing seat is never replaced by inference; only CODEX_THREAD_ID may, and codex 0.141+ does not export it (#579, #170)

Seat = T1, operator relaunches, TUI = T2, bridge delivers into T1, every turn marked read where no one is looking, and the seat cannot move to T2 — not on SessionStart, not on actas. #353 closed #350 assuming "a role re-runs actas on resume, which rewrites the record"; #579 made that rewrite impossible, on purpose and for good reason. The TUI half was never done.

The change

codex-monitor.sh — a plain launch makes the same choice the launcher makes. When exactly one Codex role is registered for the project, its seat is recorded for this project, and the rollout still exists, the TUI is opened on it:

codex resume --remote <url> <thread> [the operator's own args]

The gate is agmsg_role_resume_uuid from lib/boot-command.sh — the one spawn and resurrect already use (record + transcript, else fresh), so a seat whose rollout is gone cannot take the TUI down with it (codex resume <gone-uuid> refuses to start). Several roles: fresh, with a line saying a plain launch cannot choose and how to (codex resume <thread-id>). A seat in another project: fresh, saying so. An explicit codex resume … is untouched — it already carries the operator's choice.

codex-bridge.js — --wait-for-tui-thread. With an explicit --thread, poll thread/loaded/list (up to --loaded-timeout) until the TUI has the thread loaded, then attach to it without a thread/resume of our own: turn/start needs only the id, which the no-rollout fallback has relied on since #276, so a bridge-side resume is at best redundant and at worst the already has an active writer collision of #906. If the TUI never loads it, the bridge exits instead of delivering into a thread no one is watching; the launcher relaunches it once the TUI is there.

codex-bridge-launcher.sh — passes the flag. Every thread it launches on is a live TUI's (recorded seat, or the legacy request-file thread).

Docs — README / README.ja (one paragraph in the Codex section), docs/codex-monitor-beta.md (a section under Bridge Mechanics), and the mode monitor enable message, which said "the bridge starts on your first turn" and now says what happens to a seated role.

No data layout, driver interface or manifest changes; no new dependency. No ADR.

Why it is safe

• Every new branch in codex-monitor.sh falls through to exactly today's codex --remote <url> launch; only the single-role, seated-here, rollout-present case changes. The gate is the existing fail-open one.
• --wait-for-tui-thread is opt-in on the bridge; the launcher is its only caller. --thread loaded and the default (resume) path are unchanged.
• The attach state (threadIdle = true, turnActive = false, no resume) is the state the fix(codex): grace fallback for thread/resume failure on Codex 0.142+ #276 fallback already leaves the bridge in; the watchdogs that rescue an externally-active thread (Codex bridge: thread stuck in waitingOnApproval deadlocks delivery forever (bridge can't answer approval requests; launcher never replaces the hung bridge) #299) apply as before.

Tests (measured)

New, all against the fake codex / fake app-server the existing suites use:

file	new	what
test_codex_monitor.bats	6	resumes the seat (argv shape and the operator's args after it); stays fresh with no seat, a gone rollout, a foreign-project seat, several roles (with the message); explicit resume passed through as given
test_codex_bridge.bats	2	attaches after the TUI's load shows up (≥3 thread/loaded/list, then process/spawn, never thread/resume/thread/start); gives up when it never does (no resume, no spawn, exit ≠ 0)
test_codex_bridge_launcher.bats	1	--thread rec-thread-1 --wait-for-tui-thread reaches the bridge

Control, same tests against unmodified main: the monitor "resumes the seat" / "foreign project" / "several roles" cases and both bridge cases fail; the three monitor cases that document unchanged behaviour pass on both, as they should.

suite	result
test_codex_monitor	ok=16 (1 platform skip)
test_codex_bridge_launcher	ok=17 (1 platform skip)
test_codex_bridge	ok=47 (4 sandbox skips: unix-socket listen)
test_codex_shim	ok=25
test_codex_resume	ok=33
check-enforced-assertions.sh	baseline 638, unchanged — the new assertions use grep / refute, not [[ ]] / ! cmd
check-private-names.mjs	clean

test_delivery.bats has 4 failures in my sandbox (unsignalable watcher, two watch.sh subscription cases, single-quoted hook commands) — identical on unmodified main in the same sandbox, so not from this change; the sharded CI is the gate there.

Running locally since 2026-08-10 (an earlier form of this on v1.1.13): the bridge log reads TUI loaded thread …; attaching without a competing resume, then wakeup N … started turn on thread … with the turn visible in the TUI.

Out of scope, deliberately

• Approvals on bridge-started turns are still auto-declined (Codex bridge: thread stuck in waitingOnApproval deadlocks delivery forever (bridge can't answer approval requests; launcher never replaces the hung bridge) #299/fix(codex-bridge): auto-decline approval requests, arm the turn watchdog on externally-active turns #420). With the TUI on the same thread the operator can answer them; letting the TUI resolve them (serverRequest/resolved, bounded decline as fallback) is a follow-up, not folded in here.
• Teardown generations for stale bridges/launchers overlap fix(codex): add invocation-scoped monitor lifecycle #907 / fix(codex-bridge-launcher): reap a same-(project,role) orphan before spawning (#906 link 2) #943 / codex monitor mode: duplicate-bridge leak saturates the user's TasksMax (two incidents in one day) — bridge survives "active writer" failure, launcher respawns without orphan scan, re-arm loop has no backoff #906 and are left to those.