fix(cli): improve message queue atomicity and add --wait-idle to tmux harness

Defensive improvements to message queue handling:
- chat.tsx: Use useLayoutEffect for synchronous store updates
- use-message-queue.ts: Make queue operations atomic with functional setState

Test harness fix for rapid message testing:
- tmux-send.sh: Add --wait-idle SECS option that polls until terminal output
  stabilizes before returning. This allows rapid message tests to wait for
  streaming to complete between sends.

Note: The 'rapid message scrolling' issue was primarily a test harness limitation
where tmux sends input faster than the CLI can process during heavy rendering.
The --wait-idle flag is the proper fix for this test scenario.

Co-authored-by: Codex CLI <codex@openai.com>
Co-authored-by: Claude Code CLI <claude@anthropic.com>
Co-authored-by: Gemini CLI <gemini@google.com>

Author: 4 people

cli/src/chat.tsx

@@ -5,6 +5,7 @@ import { useQueryClient } from '@tanstack/react-query'
 import {
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -1372,8 +1373,9 @@ export const Chat = ({
     (state) => state.setCallbacks,
   )
 
-  // Update context when values change
-  useEffect(() => {
+  // Update context when values change - useLayoutEffect ensures synchronous updates
+  // to prevent message loss during rapid streaming (race condition fix)
+  useLayoutEffect(() => {
     setMessageBlockContext({
       theme,
       markdownPalette,

cli/src/hooks/use-message-queue.ts

@@ -28,9 +28,8 @@ export const useMessageQueue = (
   const isQueuePausedRef = useRef<boolean>(false)
   const isProcessingQueueRef = useRef<boolean>(false)
 
-  useEffect(() => {
-    queuedMessagesRef.current = queuedMessages
-  }, [queuedMessages])
+  // Note: queuedMessagesRef is now updated atomically inside functional setState calls
+  // (in addToQueue and the queue processing effect), so no sync effect is needed here.
 
   useEffect(() => {
     isQueuePausedRef.current = queuePaused
@@ -114,24 +113,45 @@ export const useMessageQueue = (
 
     isProcessingQueueRef.current = true
 
-    const nextMessage = queuedList[0]
-    const remainingMessages = queuedList.slice(1)
-    queuedMessagesRef.current = remainingMessages
-    setQueuedMessages(remainingMessages)
-    // Add .catch() to prevent unhandled promise rejections.
-    // Safety net: release lock here in case sendMessage failed before its own error handling.
-    // Lock is also released in finalizeQueueState and sendMessage's finally block (idempotent).
-    sendMessage(nextMessage).catch((err: unknown) => {
-      logger.warn(
-        { error: err },
-        '[message-queue] sendMessage promise rejected - releasing lock',
-      )
-      isProcessingQueueRef.current = false
+    // IMPORTANT: We must read the message to process INSIDE the functional setState
+    // to ensure we send the same message we remove. Reading from the ref separately
+    // can cause a race condition where we send message X but remove message Y.
+    let messageToProcess: QueuedMessage | undefined
+
+    setQueuedMessages((prev) => {
+      if (prev.length === 0) {
+        return prev
+      }
+      messageToProcess = prev[0]
+      const remainingMessages = prev.slice(1)
+      queuedMessagesRef.current = remainingMessages
+      return remainingMessages
     })
+
+    if (!messageToProcess) {
+      isProcessingQueueRef.current = false
+      return
+    }
+
+    // Use .finally() to ensure lock is always released after sendMessage completes
+    sendMessage(messageToProcess)
+      .catch((err: unknown) => {
+        logger.warn(
+          { error: err },
+          '[message-queue] sendMessage promise rejected',
+        )
+      })
+      .finally(() => {
+        // Release the processing lock so the next message can be processed
+        // The effect will re-run when streamStatus changes or other deps update
+        isProcessingQueueRef.current = false
+        logger.debug('[message-queue] Processing lock released')
+      })
   }, [
     canProcessQueue,
     queuePaused,
     streamStatus,
+    queuedMessages, // Re-run when queue changes to process next message
     sendMessage,
     isChainInProgressRef,
     activeAgentStreamsRef,
@@ -140,13 +160,19 @@ export const useMessageQueue = (
   const addToQueue = useCallback(
     (message: string, attachments: PendingAttachment[] = []) => {
       const queuedMessage = { content: message, attachments }
-      const newQueue = [...queuedMessagesRef.current, queuedMessage]
-      queuedMessagesRef.current = newQueue
-      setQueuedMessages(newQueue)
-      logger.info(
-        { newQueueLength: newQueue.length, messageLength: message.length },
-        '[message-queue] Message added to queue',
-      )
+      // Use functional setState to ensure atomic updates during rapid calls.
+      // We update queuedMessagesRef inside the callback to keep ref and state
+      // in sync atomically - this prevents race conditions when multiple
+      // messages are added before React can process state updates.
+      setQueuedMessages((prev) => {
+        const newQueue = [...prev, queuedMessage]
+        queuedMessagesRef.current = newQueue
+        logger.info(
+          { newQueueLength: newQueue.length, messageLength: message.length },
+          '[message-queue] Message added to queue',
+        )
+        return newQueue
+      })
     },
     [],
   )

scripts/tmux/README.md

@@ -144,6 +144,9 @@ Send input to a running session.
 ./scripts/tmux/tmux-send.sh SESSION --key C-c
 ./scripts/tmux/tmux-send.sh SESSION --key Enter
 
+# Send and wait for CLI to finish streaming (for rapid message tests)
+./scripts/tmux/tmux-send.sh SESSION "hello" --wait-idle 2
+
 # Paste clipboard content and submit immediately
 ./scripts/tmux/tmux-send.sh SESSION --paste
 

scripts/tmux/tmux-send.sh

@@ -34,6 +34,11 @@
 #                       testing attachment UI before sending).
 #   --no-enter          Don't automatically press Enter after text
 #   --retry N           Retry session detection N times (default: 3)
+#   --delay MS          Wait time in ms after Enter (default: 500, use 200 for faster tests)
+#   --wait-idle SECS    Wait until terminal output is stable for SECS seconds (for streaming)
+#                       This polls every 250ms until output hasn't changed for SECS seconds.
+#                       Useful for rapid message testing where you need to wait for streaming.
+#                       Max wait time is 120 seconds to prevent infinite loops.
 #   --force             Bypass duplicate detection (send even if same text was just sent)
 #   --help              Show this help message
 #
@@ -50,6 +55,9 @@
 #   # Send Ctrl+C to interrupt
 #   ./scripts/tmux/tmux-send.sh tui-test-123 --key C-c
 #
+#   # Send a message and wait for CLI to finish streaming before returning
+#   ./scripts/tmux/tmux-send.sh tui-test-123 "hello" --wait-idle 2
+#
 #   # Paste clipboard content and submit immediately
 #   ./scripts/tmux/tmux-send.sh tui-test-123 --paste
 #
@@ -80,7 +88,11 @@ SPECIAL_KEY=""
 PASTE_CLIPBOARD=false
 RETRY_COUNT=3
 RETRY_DELAY=0.3
+POST_ENTER_DELAY=0.5
 FORCE_SEND=false
+WAIT_IDLE_SECONDS=0
+WAIT_IDLE_MAX=120
+WAIT_IDLE_POLL_INTERVAL=0.25
 
 # Check minimum arguments
 if [[ $# -lt 1 ]]; then
@@ -120,6 +132,15 @@ while [[ $# -gt 0 ]]; do
             RETRY_COUNT="$2"
             shift 2
             ;;
+        --delay)
+            # Convert ms to seconds for sleep command
+            POST_ENTER_DELAY=$(echo "scale=3; $2 / 1000" | bc)
+            shift 2
+            ;;
+        --wait-idle)
+            WAIT_IDLE_SECONDS="$2"
+            shift 2
+            ;;
         --force)
             FORCE_SEND=true
             shift
@@ -249,8 +270,52 @@ if [[ "$AUTO_ENTER" == true ]]; then
     tmux send-keys -t "$SESSION_NAME" Enter
     # Wait for CLI to process Enter and clear input buffer before returning
     # This prevents the next send from concatenating with the previous input
-    # 200ms is needed for slower CLIs like Codex to fully process the command
-    sleep 0.2
+    # Default 500ms is needed for TUI CLIs to fully process the command and reset input state
+    # Use --delay to customize (e.g., --delay 200 for faster tests if not testing rapid input)
+    sleep $POST_ENTER_DELAY
+fi
+
+# If --wait-idle is specified, poll until terminal output stabilizes
+# This is essential for rapid message testing where we need to wait for streaming to complete
+# Works with both --auto-enter and --no-enter modes
+if [[ "$WAIT_IDLE_SECONDS" != "0" && -n "$WAIT_IDLE_SECONDS" ]]; then
+    LAST_OUTPUT=""
+    STABLE_START=0
+    POLL_COUNT=0
+    # Calculate max polls: WAIT_IDLE_MAX / WAIT_IDLE_POLL_INTERVAL (120 / 0.25 = 480)
+    MAX_POLLS=480
+    
+    while true; do
+        # Capture current terminal output
+        CURRENT_OUTPUT=$(tmux capture-pane -t "$SESSION_NAME" -p 2>/dev/null || echo "")
+        CURRENT_TIME=$(date +%s)
+        
+        if [[ "$CURRENT_OUTPUT" == "$LAST_OUTPUT" ]]; then
+            # Output unchanged - check if stable long enough
+            if [[ "$STABLE_START" == "0" ]]; then
+                STABLE_START=$CURRENT_TIME
+            fi
+            
+            STABLE_DURATION=$((CURRENT_TIME - STABLE_START))
+            if [[ "$STABLE_DURATION" -ge "$WAIT_IDLE_SECONDS" ]]; then
+                # Output has been stable for the required duration
+                break
+            fi
+        else
+            # Output changed - reset stability timer
+            LAST_OUTPUT="$CURRENT_OUTPUT"
+            STABLE_START=0
+        fi
+        
+        # Check max wait timeout using simple integer counter
+        POLL_COUNT=$((POLL_COUNT + 1))
+        if [[ "$POLL_COUNT" -ge "$MAX_POLLS" ]]; then
+            echo "⚠️  --wait-idle timed out after ${WAIT_IDLE_MAX}s" >&2
+            break
+        fi
+        
+        sleep $WAIT_IDLE_POLL_INTERVAL
+    done
 fi
 
 # Log the text send as YAML and update last-sent tracker