From ef23a80eedb9daa43428037067eabb56f154e133 Mon Sep 17 00:00:00 2001
From: Felipe Coury <felipe.coury@openai.com>
Date: Sat, 30 May 2026 17:31:57 -0300
Subject: [PATCH] docs(tui): explain token activity insertion ordering

---
 codex-rs/tui/src/app/event_dispatch.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/codex-rs/tui/src/app/event_dispatch.rs b/codex-rs/tui/src/app/event_dispatch.rs
index 53b9231b2b..ca32e0a061 100644
--- a/codex-rs/tui/src/app/event_dispatch.rs
+++ b/codex-rs/tui/src/app/event_dispatch.rs
@@ -732,6 +732,9 @@ impl App {
                     .chat_widget
                     .finish_token_activity_refresh(request_id, result)
                 {
+                    // Commit synchronously so an already queued /clear cannot overtake this card.
+                    // Do not route through ChatWidget::add_to_history: /tokens may complete during
+                    // active work, and flushing an in-progress tool cell would corrupt its lifecycle.
                     self.insert_history_cell(tui, Box::new(cell));
                 }
             }