Performance bug: UI refresh lag in long-running tmux sessions (agent still healthy)

[ARCJ137442]

Summary

When running Codex CLI inside tmux for a long session, the UI refresh becomes noticeably laggy/stuttery, while the agent execution itself continues to run normally.

Environment

• Runtime context: Termux + tmux
• Client: Codex CLI (TUI)
• Time pattern: usually after a long-running session (multiple turns / long streaming usage)

Reproduction (observed)

1. Launch Codex CLI inside a tmux session.
2. Keep a long interactive session running (many turns / long streaming output).
3. Continue interacting and scrolling.
4. Observe increasing UI repaint lag (delayed refresh / stutter), while agent task execution remains normal.

Actual Behavior

• TUI refresh becomes slow and less responsive over time in tmux.
• Agent still processes requests and tools normally (logic path is alive).

Expected Behavior

• TUI refresh performance should remain stable over long sessions in tmux.

Impact

• Degraded usability in long-running workflows on Termux/tmux.
• Operator may think the CLI is stuck, even though backend execution is still healthy.

Notes

• This appears to be primarily a rendering/perf issue rather than an agent execution issue.
• Please triage for potential repaint/back-buffer growth or terminal update path inefficiency in long sessions.

[ARCJ137442]

开始处理，分支：fix/issue-19-tmux-redraw-lag

首轮研究结论：

1. 当前 TUI redraw scheduler 使用 FrameRequester -> unbounded_channel -> FrameScheduler。
2. 调度器每次只消费一条 redraw 请求，长流式输出下可能积压大量历史 redraw 请求。
3. 当前 redraw 频率上限是 120 FPS；历史上该 limiter 原本是 60 FPS，后续在 aec58ac29（catch-up stream chunking/hysteresis）被提高到 120 FPS。
4. 对 tmux / Termux 这类终端复用环境，120 FPS 很可能过高，会放大终端刷新开销与积压尾巴，表现为“Agent 正常但界面越来越卡”。

首轮修复方向：

• 优先尝试让 scheduler 合并/丢弃过期 redraw 请求，避免 backlog 长尾；
• 同时评估将 redraw cap 回退到更保守的 60 FPS；
• 为 scheduler 补一个“高频请求不产生 backlog 尾巴”的测试。

后续会在本 issue 回写实现结果与验证结论。

[ARCJ137442]

首轮修复已提交到 PR #27：
#27

对应提交：f28dfff64

本轮实现：

• 在 codex-rs/tui/src/tui/frame_requester.rs 中，scheduler 收到一条 redraw 请求后，会继续 drain 当前已积压的 redraw 请求；
• 对这批请求仅保留最早的有效 deadline，避免 bursty streaming 在后面留下长尾 stale redraw backlog；
• 新增回归测试：test_drains_bursty_requests_without_backlog_tail。

已验证：

• CARGO_TARGET_DIR=G:/cargo-target cargo test -p codex-tui frame_requester -- --nocapture
• just fmt
• CARGO_TARGET_DIR=G:/cargo-target cargo test -p codex-tui

说明：

• 这是一轮“最小结构修复”，先处理 redraw backlog 尾巴问题；
• 当前还没有引入 tmux 专项 60 FPS/30 FPS 限流策略；若 PR 合并后实机仍有卡顿，再继续评估 redraw cap 与 tmux/Termux 环境探针。

[ARCJ137442]

补充上游关联（openai/codex）供跟踪：

核心关联（与“tmux 长时运行后 UI 变卡/输出抖动”最接近）：

• Terminal animations use excessive terminal output openai/codex#11877 Terminal animations use excessive terminal output（OPEN）
• High invisible output churn when idle (request for regression test or to fix the suppressed bug) openai/codex#11857 High invisible output churn when idle（CLOSED，后续转到 Terminal animations use excessive terminal output openai/codex#11877）

高相关 tmux/TUI 问题（可能共享渲染/终端更新路径）：

• Enter key stops responding after task completion in tmux (TUI input stuck) openai/codex#12645 Enter key stops responding after task completion in tmux（OPEN）
• LLM output is not displayed properly when running codex cli in alacritty + tmux openai/codex#12223 alacritty + tmux 输出显示异常（OPEN）
• Codex in tmux, zoom will show previous discussion instead of latest openai/codex#8352 tmux zoom 后显示旧会话内容（OPEN）
• Input lag during high disk usage openai/codex#8976 高磁盘 IO 时输入延迟（OPEN）
• Crashed (segmentation fault, exited 139) inside tmux on Linux, introduced after v0.110.0 openai/codex#13842 tmux 内间歇性崩溃（OPEN）

建议把本 issue 作为 fork 侧聚合入口：

• 上游跟踪渲染/终端路径演进；
• 下游记录我们在 Termux/tmux 的复现实测和补丁验证结果（尤其是 redraw backlog 与帧率上限策略）。

[ARCJ137442]

补充对比（供后续调优参考，不代表结论）：

1. 目前没有发现“完全没有 tmux 类问题”的同类 Agent TUI。OpenCode 公开 issue 里已有 tmux 相关问题：

• TUI broken inside Linux tmux anomalyco/opencode#16967
• TUI not rendering LLM response in tmux (opentui rendering bug, v1.2.21) anomalyco/opencode#16566
• Terminal escape sequences printed on startup in tmux anomalyco/opencode#16547
• 搜索汇总：https://github.com/anomalyco/opencode/issues?q=tmux

2. OpenCode 的 TUI 使用 OpenTUI，渲染策略偏事件驱动：

• OpenTUI renderer 文档明确说明默认仅在 tree 变更时 render，动画需显式 requestLive/dropLive；targetFps 默认 30、maxFps 60：
  https://github.com/anomalyco/opentui/blob/main/packages/opentui/src/renderer/README.md
• OpenCode TUI 入口设置 targetFps: 60：
  https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx#L87

3. Codex 当前实现（本仓库）作为对照：

• codex-rs/tui/src/tui/frame_rate_limiter.rs 仍为 120 FPS cap
• codex-rs/tui/src/status_indicator_widget.rs 仍以 32ms 节奏触发下一帧

4. 上游 openai/codex 也有直接关联的 tmux/终端输出抖动 issue：

• Terminal animations use excessive terminal output openai/codex#11877
• High invisible output churn when idle (request for regression test or to fix the suppressed bug) openai/codex#11857

初步关联假设（仅假设）：OpenTUI 的“tree 变更驱动 + 动画显式 live + 较低 targetFps”可能降低 tmux 输出压力；Codex 目前更接近“常态化刷新 + 动画节奏驱动”，因此 tmux lag 更像渲染/动画策略差异，而不仅仅是队列 backlog。

[ARCJ137442]

综合解决方案草案（tmux-only 10 FPS）：

目标

• 仅在 tmux 下把 TUI 动画/重绘预算降到 10 FPS（100ms），非 tmux 不变。
• 不新增 config 开关；保持 TUI 之外逻辑不动，fix(tui): drain redraw bursts in frame scheduler #27 backlog drain 继续保留。

方案核心

• tmux 检测：复用 codex_core::terminal::terminal_info().multiplexer。
• 在 TUI 初始化处选择 min_frame_interval：tmux=100ms，非 tmux=现有 8.33ms。
• 将该 interval 传入 FrameScheduler 的 limiter，统一 clamp 所有 redraw 请求（包括动画）。

验证建议

• tmux history_bytes 观测：tmux list-panes -F 'hist_bytes=#{history_bytes} hist_lines=#{history_size}'
• Raw PTY 输出：script -q -f /tmp/raw.log -c 'codex ...' + stat -c%s /tmp/raw.log

相关证据与背景

• 上游 openai/codex 输出抖动问题：
  • Terminal animations use excessive terminal output openai/codex#11877
  • High invisible output churn when idle (request for regression test or to fix the suppressed bug) openai/codex#11857
• 其它同类 TUI 在 tmux 下也有渲染问题：
  • OpenCode: TUI broken inside Linux tmux anomalyco/opencode#16967
  • OpenCode: TUI not rendering LLM response in tmux (opentui rendering bug, v1.2.21) anomalyco/opencode#16566
  • OpenCode: Terminal escape sequences printed on startup in tmux anomalyco/opencode#16547
  • Claude Code: [BUG] Terminal rendering corruption in tmux - text overlaps and overwrites previous output anthropics/claude-code#29937
  • Claude Code: [BUG] Terminal blinks/flickers when pasting long messages in tmux anthropics/claude-code#28282
  • Claude Code: [Bug] Screen not rendered after external editor (Ctrl+G) exits in tmux anthropics/claude-code#32744

设计文档与实施计划（分支 docs/tmux-10fps-solution）：

• 设计：https://github.com/exomind-team/codex/blob/docs/tmux-10fps-solution/docs/plans/2026-03-13-tmux-10fps-design.md
• 实施计划：https://github.com/exomind-team/codex/blob/docs/tmux-10fps-solution/docs/plans/2026-03-13-tmux-10fps-implementation-plan.md