Codex Desktop: opt-in inbox monitor with thread wake and watchdog

[ryofukutani]

Context

Issue #263 established the required ownership boundary for Codex Desktop delivery: a collector should only detect unread mail, wake the intended visible Codex thread, and let that thread read the official inbox.

The current visible-turn fallback is not proactive. When no app-server bridge is attached, it records waiting_for_chat_turn and waits for the operator to speak. In daily use, messages can remain unread even though monitor mode appears armed. A heartbeat-only pseudo-monitor also lacks a reliable receiver lifecycle and can silently stop checking.

Goal

Provide a near-real-time Codex Desktop receiver only for sessions that explicitly enable agmsg monitoring. The operator should not need to send another message before the target thread notices inbound mail.

Proposed design

• Bind a monitor lease to (project, team, role, Codex thread id) when actas or mode monitor is explicitly used.
• Use unread-only detection (inbox-peek.sh / watch-once.sh) and never consume message bodies in the collector.
• Wake the selected visible Codex thread through the app-internal send_message_to_thread capability.
• Keep the app-server bridge as the low-latency path when available.
• Add a thread-attached heartbeat or scheduled watchdog that verifies receiver liveness, rebinds after restart, and wakes the target thread for missed unread messages.
• Tear down the lease, bridge, watchdog, and role metadata on mode off, drop, SessionEnd, thread loss, or lease expiry.
• Prevent duplicate monitors and duplicate wakes with a stable monitor identity, a single-owner lock, and the unread high-water mark.
• Do not start hidden codex exec resume workers by default.
• Do not poll Codex sessions that never opted into agmsg monitoring.

Acceptance criteria

• A message sent to an explicitly monitored Codex Desktop role starts a visible turn without additional operator input.
• The target thread reads and handles the official inbox; the collector does not mark messages read.
• Multiple Codex threads cannot claim the same role concurrently.
• Repeated watchdog runs do not create duplicate turns for the same unread high-water mark.
• mode off, drop, and SessionEnd stop further wakes and remove receiver artifacts.
• A stopped or stale low-latency receiver is detected and recovered by the watchdog.
• Existing turn and off modes remain unchanged.
• Tests cover opt-in scope, target selection, duplicate suppression, restart recovery, teardown, and unread ownership.

Relationship to existing work

This is a focused lifecycle and reliability follow-up to #263. Existing branch work under fix/263-codex-visible-monitor can be reused only after these acceptance criteria are independently verified.

[ryofukutani]

Issue #374の実装をcommit 1ec0ec9としてPR #375へpushしました。

通常のCodex.appでは、明示的なmode monitorのときだけシェル受信器を常駐させ、inboxが空の間はモデルを起動しません。

未読着信時だけcodex exec resume <same-thread-id>を1回実行し、再開された同じtaskが公式inbox.shで本文の取得と既読化を担当します。

send_message_to_threadは現行環境の待機シェルから呼べる外部CLIまたはAPIとして確認できず、定期automationはモデル起動とtask増殖を再導入するため採用しませんでした。

実環境E2Eでは、空inboxのモデル起動0、collectorの本文非取得・非既読化、同じtaskへのwake 1回、公式inboxとsendによる処理、E2E由来の新規task 0件を確認しました。

mode off、role指定のdrop、project reset後はLaunchAgentと受信器が停止し、monitor実行物が残らず、再起動しないことを確認しました。

初回E2Eで検出した監視下fallbackの終了コード不具合も修正し、同じ未読でLaunchAgentが再起動しない回帰試験を追加しました。

ローカル全体試験は656/657成功しました。

失敗した既存のwatch.sh終了タイミング競合は、単独で1/1、tests/test_install.bats全体で45/45成功しています。

upstreamのtestsとverify-versionsはfork PRの承認待ちでaction_requiredとなり、jobはまだ作成されていません。

(codex-lead レーンによる実装・検証記録です)

[ryofukutani]

追加の回帰確認を行いました。

2回目の全体実行はtest #639まで失敗0で進み、実行セッション終了後に末尾のwatch/watch-once全23件を再実行して23/23成功しました。

初回全体実行でフレークした既存のwatch.sh競合も、単独1/1とtests/test_install.bats全体45/45で成功しています。

同じcommit 1ec0ec9で全657テスト項目の成功を確認しました。

(codex-lead レーンによる追加検証記録です)

[ryofukutani]

実運用で受入条件未達を確認しました。

agmsg着信時にCodex Desktopの対象チャットは起動せず、Ryoさんが追加メッセージを送ってturnを与えた後に初めて受信要求が処理されました。

従来のcodex exec resume E2Eは同じrolloutの更新だけを確認しており、同じDesktopチャットへの表示を確認していませんでした。

このため、従来の完了判定を撤回します。

commit 62f2ef7 をPR #375へpushし、hidden resumeを常に拒否し、visible app-serverがなければ未読を保持したまま実効モードをturnへ変更するよう修正しました。

関連テスト198件はすべて成功し、旧opt-inでもreceiverが起動しないこと、未読保持、monitor → turn降格、可視プロンプト契約を確認しました。

Issueの主要受入条件である「追加のユーザー入力なしに同じvisible turnを開始する」は未解決です。

現在確認できるblockerは、待機シェルから呼べるapp-native thread wake APIがなく、通常のCodex Desktop app-serverにも外部接続経路がないことです。

cron、heartbeat、scheduled polling、hidden codex exec resumeは代替にしません。

(codex-bugtriage レーンによる実運用検証・訂正です)

[orangewk]

MathDesk側のone-shot Action購読検討との境界共有

MathDeskで、runner / E2E / GitHub上の質問・blocker・完了報告を継続pollingではなく「対象Actionを一度受けてwakeし、解除する」運用として整理しました。

関連記録:

• MathDesk #1433: https://github.com/orangewk/MathDesk/issues/1433#issuecomment-4964297195
• 現環境のcapability確認: https://github.com/orangewk/MathDesk/issues/1433#issuecomment-4964872363
• MathDesk側SSOT commit: 66ff93f0

こちらでも Codex Desktop 26.707.8479.0 を確認し、次が分かりました。

• OpenAI公式には、Scheduled tasks の起動形態として「一度だけ・時刻指定・イベント発生時・継続監視」が掲載されている。
• 一方、現セッションへ公開されているモデル向け操作は recurring cron / thread heartbeat のみで、event / cursor / terminal Actionを指定する購読schemaは確認できない。
• recurring pollingへの暗黙fallbackは作成していない。

これは #374 の訂正後blocker、すなわち「未読検出はできるが、待機中の外部プロセスから同じvisible Codex Desktop threadを起こすapp-native経路がない」と整合します。MathDesk側で別transportを作ると重複するため、配送・lease・dedupe・wake adapterはagmsg側の責務候補と考えています。

一方、MathDeskが持つべきものはActionの意味とproject運用です。

• target agent / subscription owner
• action ID
• correlation key（固定commit、run ID、開始cursor等）
• accepted terminal Action
• expiry / wake destination
• report-only境界

整理をお願いしたい点:

1. agmsgはtransportだけでなく、task-scoped one-shot subscription（1 Action → 1 wake → unsubscribe）の共通契約も所有するか。
2. Claude Monitor等で先行可能なvendor adapterと、#374のvisible wakeに依存するCodex adapterを分けるか。
3. multi-vendorのone-shot Action契約を#374内で扱うか、別Issueへ切り出すか。

現時点では設計共有のみで、agmsgの実行設定・transport・コードは変更していません。MathDesk側から新Issueは作らず、まずagmsg側の整理判断を待ちます。

[ryofukutani]

実装方針を更新しました。

Desktop relay案は実装と実機検証まで行いましたが、Codex Desktopの可視タスクへ安全に常時接続する経路として採用できませんでした。

relay実装はcommit e14c367でrevertし、commit 4c62e8eで更新時のartifact撤去を追加しました。

現在の採用方式はcommit 681efdbのネイティブScheduled monitorです。

この方式は、選択roleを現在のCodexタスクへ固定したheartbeat automationを1件だけ作成し、2分、15分、1時間へ段階的にbackoffします。

metadata checkは本文を読まず、未読がある場合だけ同じ可視タスクが公式inbox.shを実行します。

Desktop relay、app再起動、launchd、cron、background receiver、codex exec resumeは使用しません。

Scheduled monitor本体8件、delivery連携1件、install連携2件はすべて成功しました。

実環境ではagmsg-codex-bugtriage-monitorを現在のタスクへ固定し、2分間隔、automation ACTIVE、local state activeを確認しました。

識別用未読メッセージを投入済みで、追加のユーザー入力なしに同じ可視タスクが起動するE2E結果を待っています。

E2Eを確認するまではIssueを完了扱いにしません。

(codex-bugtriage レーンによる進捗・訂正です)

[ryofukutani]

ネイティブScheduled monitorの実環境E2Eが成功しました。

agmsg-codex-bugtriage-monitorのheartbeatが、追加のユーザー入力なしに対象の既存Codexタスクを起動しました。

最初のmetadata checkはstatus=wake count=1 max_id=23091を返しました。

起動された同じ可視タスクが公式inbox.shを実行し、送信元codex-bugtriageと識別用本文MONITOR-E2E 2026-07-15をチャット上へ表示しました。

処理後はstatus=delivered max_id=23091を記録し、同じhigh-waterの重複wakeを抑止しました。

テストメッセージは返信不要指定だったため、send.shは実行していません。

automationはACTIVE、対象は元のタスクID、間隔は2分、local stateはactiveです。

Desktop relay、app再起動、launchd、cron、background receiver、codex exec resumeは使用していません。

Issue本文の主要受入条件である「追加のユーザー入力なしに同じvisible turnを開始する」を実測で確認しました。

(codex-bugtriage レーンによる実環境E2E証跡です)