tmux 分屏下联动滚动导致分隔线消失（inline 重绘）

[ARCJ137442]

Summary

在 tmux 左右分栏时，Codex 在一侧刷新消息会把另一侧内容和纵向分隔线一起“下拉”，导致分隔线消失、另一侧行距被拉大。单 pane 或非 tmux 环境不明显。

Repro Steps

1. 启动 tmux，创建左右分栏。
2. 在左右两侧各运行 Codex（建议使用 inline 模式，例如 codex --no-alt-screen 或 tui.alternate_screen=never）。
3. 右侧输入一条会产生多行输出的消息（如“你是谁”），等待渲染完成。

Expected

仅右侧 pane 更新，tmux 纵向分隔线保持稳定，左侧内容不移动。

Actual

右侧更新时，左侧内容被整体向下拉，纵向分隔线消失，视觉上像整屏滚动了一段。

Environment

• Termux/Android + tmux（用户实际环境）
• Codex 0.114.0-exomind

Analysis / Hypothesis

Codex TUI 在 inline 模式下会使用 ratatui 的 scrolling-regions 优化，依赖 “滚动区域 + CSI S(Scroll Up)” 来给历史行腾位置。具体路径：

• tui::draw 在 viewport 超出屏幕时调用 scroll_region_up 来把上方内容滚动出空间：
  • codex-rs/tui/src/tui.rs L470-L500（scroll_region_up(0..area.top(), area.bottom() - size.height)）
• ratatui 在 scrolling-regions feature 下会发出 ESC[{top};{bottom}r + ESC[{n}S（设置滚动区域 + Scroll Up）
• codex-rs/tui/Cargo.toml L66-L71 启用了 scrolling-regions

猜测 tmux 未完整处理/隔离这些滚动区域指令，导致它们被传递到外层终端，从而触发“整屏滚动”，把别的 pane 和分隔线一起拖动。这与观察到的分隔线消失、另一侧整体下移现象吻合。

Suggested Investigation

• 记录 Codex 渲染期间发出的 ANSI 序列（例如 tmux pipe-pane 或 script），确认是否包含 DECSTBM + CSI S。
• 在 tmux 下禁用 scrolling-regions（或运行时绕过 scroll_region_up）验证现象是否消失。

Possible Mitigations (Hypothesis)

• 当 Multiplexer::Tmux 时避免 scroll_region_up，退回到全量重绘路径。
• 或在 tmux 下强制走 alt-screen（但会改变 scrollback 体验，需要权衡）。

[ARCJ137442]

初步关联分析（基于 GitHub 搜索，不涉及代码）：

1. opencode-ai/opencode：未发现与“tmux 分屏滚动联动/分隔线消失”相同的问题。现有相关条目主要是 tmux 快捷键冲突 tmux <leader>+<key> bindings stop working inside opencode opencode-ai/opencode#331，以及滚动体验相关 Scroll position should not reset when new message begins opencode-ai/opencode#276、Im not able to scroll inside the terminal window opencode-ai/opencode#166，但描述不涉及分屏联动滚动。
2. marhsjbdn/opencode：未检索到 tmux 或 scroll 相关 issue。
   结论：从 issue 侧暂无证据表明 OpenCode 存在同类 tmux 渲染问题，可能是渲染策略不同或未暴露。后续需要从其渲染实现对比（例如是否使用滚动区域/inline viewport）。

[ARCJ137442]

定位追踪结论（已精确到代码与依赖链实现）：

1. Codex 触发点：inline 重绘在视口扩展时调用滚动区域上滚 scroll_region_up(0..area.top(), area.bottom() - size.height)，见 codex-rs/tui/src/tui.rs L490-L495（本地行号）。
2. 依赖链实现：ratatui/crossterm 在 ScrollUpInRegion 发出 ANSI 序列 CSI r(设置滚动区域) + CSI S(滚动上移) + CSI r(重置滚动区域)，见 ratatui backend/crossterm.rs L538-L548（本地依赖源码行号）。
3. 依赖特性来源：codex-rs/tui/Cargo.toml 启用 ratatui 的 scrolling-regions feature（L66-L71）。
4. 上游关联：Support for TMUX is limited. crossterm-rs/crossterm#401 明确说明 tmux 支持有限；crossterm PR fix: remember to set lastIndex = 0 on shared RegExp openai/codex#918/fix: test_dev_null_write() was not using echo as intended openai/codex#923 为滚动区域命令；ratatui PR fix: skip git repository warning in quiet mode openai/codex#1341 引入 scrolling-regions 来优化 inline insert_before；ratatui Codex hangs openai/codex#584 报告 inline 视口高频插入闪烁。
   结论：问题由 Codex 的 inline 优化路径触发，滚动区域序列由依赖链生成，tmux 对该序列的隔离/兼容性不足导致分屏联动滚动与分隔线消失。

[ARCJ137442]

排查剖析补强（含已验证与未验证部分）：

一、完整逻辑链条（已验证 + 可信推断）

1. Codex 触发点（已验证）：inline 视口扩展时在 tui::draw 调用 scroll_region_up 以腾空间，见 codex-rs/tui/src/tui.rs L490-L495。
2. 依赖链发出 ANSI 序列（已验证）：ratatui/crossterm 的 ScrollUpInRegion 写入 CSI r（设置区域）+ CSI S（上滚）+ CSI r（重置），见 ratatui backend/crossterm.rs L538-L548。
3. tmux 对滚动区域的兼容性（部分推断）：Support for TMUX is limited. crossterm-rs/crossterm#401 明确说明 tmux 支持有限，但未直接描述分屏联动滚动问题。
4. 最可能路径（推断，与现象吻合）：inline 视口扩展 + 滚动区域序列 + tmux 对区域/滚动指令在 pane 级别隔离不足或上下文处理异常 → 触发分屏联动滚动与分隔线消失。

二、已做验证

• 在 tmux 3.6a 下，直接向右侧 pane 发出 CSI r/CSI S/CSI r，左侧 pane 未发生变化。
  结论：单条滚动区域序列不足以触发问题，说明触发条件更复杂（与视口状态、刷新时机、滚动区域范围、连续输出等相关）。

三、仍需补齐的证据

1. 捕获 Codex 实际重绘时的完整 ANSI 序列上下文（不仅是 CSI r/CSI S）。
2. 用 ratatui inline 示例或最小程序复现“视口扩展 + 高频输出”时的 tmux 分屏联动滚动。
3. 如需最终确认，定位 tmux 对 DECSTBM/CSI S 的 pane 隔离处理路径。

当前结论：链条已完备到“Codex触发路径 → 依赖链 ANSI 序列 → tmux 可能隔离问题”，且已排除“单条序列即可触发”的简单解释，剩余工作是补足真实重绘上下文的证据。

[ARCJ137442]

调研补充：结合 OpenCode 等开源 TUI 的实现差异（与 Codex 对比）

1. opencode-ai/opencode（Go + Bubble Tea v1）

• 入口创建 TUI 时固定启用 Alt Screen：cmd/root.go 使用 tea.WithAltScreen()。
• 渲染模式为 Bubble Tea 的“全屏重绘 + diff”，未发现终端级滚动区域的使用。
• 结论：其滚动主要发生在应用层/渲染层，而不是通过终端滚动区域指令。

2. marhsjbdn/opencode（Go + Bubble Tea v2 beta）

• packages/tui/cmd/opencode/main.go 同样启用 tea.WithAltScreen()。
• packages/tui/internal/viewport 维护 YOffset/lines 等逻辑视口，滚动为应用层逻辑移动；未见终端级滚动区域指令。
• 结论：同样避开终端级滚动区域序列。

3. 与 Codex 的关键差异

• Codex inline 模式会在视口扩展时调用 scroll_region_up（终端级滚动区域），由 ratatui/crossterm 发出 CSI r + CSI S + CSI r 序列。
• OpenCode 两个实现都采用 Alt Screen + 应用层视口/重绘，未使用滚动区域。

推断与洞察：

• tmux 分屏“联动滚动/分隔线消失”更可能由“终端级滚动区域 + tmux pane 隔离边界”触发。
• OpenCode 这类实现避免终端级滚动区域，因此不容易暴露同类问题。
• 若需规避 tmux 问题，Codex 在 tmux 下可考虑降级为：禁用滚动区域或强制 Alt Screen（代价是 scrollback 体验变化）。

（注：此结论与 #43 的定位链条一致，属于“实现策略差异导致问题触发概率不同”的对比补强。）