Codex Desktop message delivery: wake-on-unread mechanism

[fujibee]

Context

agmsg's existing Codex monitor targets the Codex CLI: it intercepts the codex
command (shell function / opt-in PATH shim) and routes inbound messages as turns via
the bridge + app-server. We'd like the same delivery for Codex Desktop (the GUI
app): inject into the Desktop session when unread mail arrives. The CLI approach
(intercept the launch command) doesn't transfer directly — the Desktop app launches
itself, so there is no command to intercept.

Prior art — PoC in #260

#260 demonstrates a working delivery path (reported working on Windows): it owns a
codex app-server and drives it over WebSocket JSON-RPC — initialize, load a thread,
then start a turn with the message body as the prompt. So messages do reach a Codex
thread. It also adds a supervisor scaffold (project-scoped singleton, heartbeat
liveness, mailbox cursor, single-writer). The committed tests use a mock adapter, so the
in-repo evidence is feasibility-level; the live end-to-end is reported by the contributor.

What's open for a production path

1. Stable/supported transport. The PoC drives codex app-server --listen ws://....
   Recent Codex (0.142+) reworked the app-server surface (managed daemon + control
   socket in place of --listen ws://), so this route needs to move onto the current
   supported control surface — the same migration the CLI monitor faces.
2. Thread/target selection. --thread loaded assumes a single thread; we need a
   rule for choosing the right Desktop conversation when several exist.
3. Cross-platform. The PoC has Windows-specific pieces (powershell, taskkill,
   AppData paths) to generalize.
4. Productionization. Promote the mock-adapter path to a verified live-Desktop
   end-to-end; decide the collector's body-handling boundary (it currently reads the
   body to build the turn).

Question

For anyone running Codex Desktop: what is the most robust way to drive/inject into a
running Desktop session on current Codex versions? Input very welcome.

Out of scope

The one-line codex-bridge.js Windows fix (prepend the bash binary when arming the
watch) is a CLI-monitor improvement, tracked separately.

[orangewk]

Current working mechanism from my Windows Codex Desktop dogfood:

The path that worked was not direct external app-server injection into the Desktop GUI.

It was:

watch-once.sh reports unread
  -> collector uses Codex app-internal send_message_to_thread
  -> target Codex Desktop thread wakes
  -> target thread runs official agmsg inbox script
  -> target thread reads and replies

Important boundaries:

• watch-once.sh was used only as an unread oracle (count / max_id).
• The collector did not read the message body.
• The collector did not mark messages read.
• Message ownership stayed with the target thread.
• The wake route was available inside Codex Desktop as send_message_to_thread; I have not proven a standalone shell-only process can wake an existing Desktop GUI thread without that app-internal route.

Dogfood targets where this worked:

• Eiji
• JunoMaCoder
• Deneb

So the production question I would separate is:

1. Keep watch-once.sh / unread-only detection as the receiver-side signal.
2. Define a supported Desktop thread wake route equivalent to the app-internal send_message_to_thread behavior.
3. Let the target thread read the official inbox itself.

[ryofukutani]

We run Codex.app (macOS Desktop) in daily multi-lane production alongside Claude Code sessions, and ended up building a local variant of exactly this. Sharing the design boundaries that survived a few weeks of dogfooding, since they rhyme with @orangewk's list — happy to upstream any of it as separate PRs if wanted.

1. Chat-visible delivery by default; headless is opt-in.
Our first version woke a Desktop role via a headless codex exec resume worker. It worked, but was operationally confusing: messages were consumed and answered outside the visible chat, so the operator saw a silent conversation while the role was actually active. We inverted the default: ordinary Codex.app sessions fall back to chat-visible turn delivery (Stop-hook / next-turn pull via check-inbox.sh), and the visible bridge is used when an app-server is available. The legacy headless worker only starts when AGMSG_CODEX_ALLOW_HEADLESS_APP_MONITOR=1 is explicitly set. For a GUI app, "the human can see every delivered message in the thread" turned out to be the property worth protecting — same conclusion as "let the target thread read the official inbox itself".

2. The collector must never consume.
We split peek from mark (inbox-peek.sh / mark-read.sh): the wake path only reads an unread oracle and never marks; the target session displays and then marks. (Related: #361 fixes the blanket mark-as-read in inbox.sh/check-inbox.sh so nothing gets marked read unseen.)

3. Turn delivery must follow actas.
check-inbox.sh polls whatever whoami.sh picks first (the README caveat), so an actas'd Desktop role never received its own mail on the turn path. We persist the last actas per project (run/codex-last-actas.<project-hash>.tsv, written by an actas-monitor.sh rebind step) and have check-inbox.sh prefer it. This also gave delivery.sh set off a well-defined teardown for the per-role receiver artifacts.

If any of these fit the production path you have in mind (especially the visible-turn default and the actas-follow for turn delivery), I can cut them into focused PRs.