Fix btw overlay delivery and presentation

LEON-gittech · LEON-gittech · commit 2e7991debb45 · 2026-05-11T23:36:20.000+08:00
Treat /btw text and completion notifications as lossless app-server events so a saturated event bridge cannot leave the modal stuck in Answering state. Replace the generic pager chrome with a compact BTW modal and request redraws when side-answer state changes.

Tests:
- RUSTC_WRAPPER=sccache CC=clang cargo test -p codex-app-server --lib guaranteed_delivery_helpers_cover_terminal_server_notifications
- RUSTC_WRAPPER=sccache CC=clang cargo test -p codex-app-server-client --lib event_requires_delivery_marks_transcript_and_terminal_events
- RUSTC_WRAPPER=sccache CC=clang cargo test -p codex-tui --lib btw_notifications_collect_answer_and_emit_completion
- RUSTC_WRAPPER=sccache CC=clang cargo test -p codex-tui --lib btw_overlay_snapshot_uses_compact_modal_chrome
- RUSTC_WRAPPER=sccache CC=clang just fix -p codex-tui
- RUSTC_WRAPPER=sccache CC=clang just fix -p codex-app-server-client
- RUSTC_WRAPPER=sccache CC=clang just fix -p codex-app-server
diff --git a/codex-rs/app-server-client/src/lib.rs b/codex-rs/app-server-client/src/lib.rs
@@ -162,10 +162,10 @@ fn event_requires_delivery(event: &InProcessServerEvent) -> bool {
 
 /// Returns `true` for notifications that must survive backpressure.
 ///
-/// Transcript events (`AgentMessageDelta`, `PlanDelta`, reasoning deltas) and
-/// the authoritative `ItemCompleted` / `TurnCompleted` form the lossless tier
-/// of the event stream. Dropping any of these corrupts the visible assistant
-/// output or leaves surfaces waiting for a completion signal that already
+/// Transcript events (`AgentMessageDelta`, `PlanDelta`, reasoning deltas), `/btw`
+/// lifecycle events, and the authoritative `ItemCompleted` / `TurnCompleted` form
+/// the lossless tier of the event stream. Dropping any of these corrupts the visible
+/// assistant output or leaves surfaces waiting for a completion signal that already
 /// fired. Everything else (`CommandExecutionOutputDelta`, progress, etc.) is
 /// best-effort and may be dropped with only cosmetic impact.
 ///
@@ -180,6 +180,8 @@ pub(crate) fn server_notification_requires_delivery(notification: &ServerNotific
             | ServerNotification::PlanDelta(_)
             | ServerNotification::ReasoningSummaryTextDelta(_)
             | ServerNotification::ReasoningTextDelta(_)
+            | ServerNotification::BtwTextDelta(_)
+            | ServerNotification::BtwCompleted(_)
     )
 }
 
@@ -2072,6 +2074,27 @@ mod tests {
                 )
             )
         ));
+        assert!(event_requires_delivery(
+            &InProcessServerEvent::ServerNotification(
+                codex_app_server_protocol::ServerNotification::BtwTextDelta(
+                    codex_app_server_protocol::BtwTextDeltaNotification {
+                        btw_id: "btw".to_string(),
+                        delta: "hello".to_string(),
+                    }
+                )
+            )
+        ));
+        assert!(event_requires_delivery(
+            &InProcessServerEvent::ServerNotification(
+                codex_app_server_protocol::ServerNotification::BtwCompleted(
+                    codex_app_server_protocol::BtwCompletedNotification {
+                        btw_id: "btw".to_string(),
+                        answer: Some("done".to_string()),
+                        error: None,
+                    }
+                )
+            )
+        ));
         assert!(!event_requires_delivery(&InProcessServerEvent::Lagged {
             skipped: 1
         }));
diff --git a/codex-rs/app-server/src/in_process.rs b/codex-rs/app-server/src/in_process.rs
@@ -102,7 +102,12 @@ pub const DEFAULT_IN_PROCESS_CHANNEL_CAPACITY: usize = CHANNEL_CAPACITY;
 type PendingClientRequestResponse = std::result::Result<Result, JSONRPCErrorError>;
 
 fn server_notification_requires_delivery(notification: &ServerNotification) -> bool {
-    matches!(notification, ServerNotification::TurnCompleted(_))
+    matches!(
+        notification,
+        ServerNotification::TurnCompleted(_)
+            | ServerNotification::BtwTextDelta(_)
+            | ServerNotification::BtwCompleted(_)
+    )
 }
 
 /// Input needed to start an in-process app-server runtime.
@@ -721,6 +726,8 @@ async fn start_uninitialized(args: InProcessStartArgs) -> IoResult<InProcessClie
 #[cfg(test)]
 mod tests {
     use super::*;
+    use codex_app_server_protocol::BtwCompletedNotification;
+    use codex_app_server_protocol::BtwTextDeltaNotification;
     use codex_app_server_protocol::ClientInfo;
     use codex_app_server_protocol::ConfigRequirementsReadResponse;
     use codex_app_server_protocol::SessionSource as ApiSessionSource;
@@ -886,5 +893,18 @@ mod tests {
                 },
             })
         ));
+        assert!(server_notification_requires_delivery(
+            &ServerNotification::BtwTextDelta(BtwTextDeltaNotification {
+                btw_id: "btw-1".to_string(),
+                delta: "hello".to_string(),
+            })
+        ));
+        assert!(server_notification_requires_delivery(
+            &ServerNotification::BtwCompleted(BtwCompletedNotification {
+                btw_id: "btw-1".to_string(),
+                answer: Some("done".to_string()),
+                error: None,
+            })
+        ));
     }
 }
diff --git a/codex-rs/tui/src/app/btw.rs b/codex-rs/tui/src/app/btw.rs
@@ -64,15 +64,10 @@ impl App {
         self.pending_btw_questions
             .insert(btw_id.clone(), Arc::clone(&state));
         let _ = tui.enter_alt_screen();
-        let overlay_cell: Box<dyn history_cell::HistoryCell> = Box::new(
+        let overlay_cell: Arc<dyn history_cell::HistoryCell> = Arc::new(
             history_cell::new_btw_question_cell(Arc::clone(&state), cwd.as_path()),
         );
-        let overlay_renderable: Box<dyn Renderable> = Box::new(overlay_cell);
-        self.overlay = Some(Overlay::new_static_with_renderables(
-            vec![overlay_renderable],
-            "B T W".to_string(),
-            self.keymap.pager.clone(),
-        ));
+        self.overlay = Some(Overlay::new_btw(overlay_cell, self.keymap.pager.clone()));
         tui.frame_requester().schedule_frame();
 
         let response = app_server
@@ -104,6 +99,7 @@ impl App {
                 if let Ok(mut state) = state.lock() {
                     state.push_delta(&notification.delta);
                 }
+                self.app_event_tx.send(AppEvent::RequestRedraw);
                 true
             }
             ServerNotification::BtwCompleted(notification) => {
@@ -113,6 +109,7 @@ impl App {
                 if let Ok(mut state) = state.lock() {
                     state.complete(notification.answer.clone(), notification.error.clone());
                 }
+                self.app_event_tx.send(AppEvent::RequestRedraw);
                 true
             }
             _ => false,
diff --git a/codex-rs/tui/src/app/event_dispatch.rs b/codex-rs/tui/src/app/event_dispatch.rs
@@ -16,6 +16,9 @@ impl App {
         event: AppEvent,
     ) -> Result<AppRunControl> {
         match event {
+            AppEvent::RequestRedraw => {
+                tui.frame_requester().schedule_frame();
+            }
             AppEvent::NewSession => {
                 self.start_fresh_session_with_summary_hint(
                     tui, app_server, /*session_start_source*/ None,
diff --git a/codex-rs/tui/src/app_event.rs b/codex-rs/tui/src/app_event.rs
@@ -126,6 +126,9 @@ pub(crate) enum KeymapEditIntent {
 #[allow(clippy::large_enum_variant)]
 #[derive(Debug)]
 pub(crate) enum AppEvent {
+    /// Schedule a frame because state changed outside the direct TUI event path.
+    RequestRedraw,
+
     /// Open the agent picker for switching active threads.
     OpenAgentPicker,
     /// Stop a spawned subagent from the background task panel.
diff --git a/codex-rs/tui/src/history_cell.rs b/codex-rs/tui/src/history_cell.rs
@@ -691,14 +691,16 @@ impl HistoryCell for BtwQuestionCell {
         let Ok(state) = self.state.lock() else {
             return vec!["/btw state unavailable".red().into()];
         };
-        let mut lines = vec![vec!["/btw ".magenta().bold(), state.question.clone().dim()].into()];
+        let mut lines = vec![
+            vec!["Question ".magenta().bold(), state.question.clone().into()].into(),
+            Line::from(""),
+        ];
 
         if let Some(error) = &state.error {
             lines.push(vec!["  ".into(), format!("■ {error}").red()].into());
         } else if state.answer.trim().is_empty() && !state.completed {
             lines.push(
                 vec![
-                    "  ".into(),
                     activity_indicator(
                         Some(state.start_time),
                         MotionMode::from_animations_enabled(state.animations_enabled),
@@ -721,17 +723,7 @@ impl HistoryCell for BtwQuestionCell {
                 Some(self.cwd.as_path()),
                 &mut answer_lines,
             );
-            lines.extend(prefix_lines(answer_lines, "  ".into(), "  ".into()));
-        }
-
-        if state.completed {
-            lines.push(
-                vec![
-                    "  ".into(),
-                    "Space, Enter, or Escape to dismiss".dark_gray(),
-                ]
-                .into(),
-            );
+            lines.extend(answer_lines);
         }
         lines
     }
diff --git a/codex-rs/tui/src/pager_overlay.rs b/codex-rs/tui/src/pager_overlay.rs
diff --git a/codex-rs/tui/src/snapshots/codex_tui__pager_overlay__tests__btw_overlay_snapshot_uses_compact_modal_chrome.snap b/codex-rs/tui/src/snapshots/codex_tui__pager_overlay__tests__btw_overlay_snapshot_uses_compact_modal_chrome.snap
