Scroll-back broken and screen flickers during multi-agent runs in non-VP mode

[chiga0]

Summary

In non-VP mode (default), when conversation output plus the footer exceeds the terminal height while background agents are running, the view cannot be scrolled up — any scroll-up immediately snaps back to the bottom and the screen flickers. The issue resolves on its own once the agent run finishes.

Steps to Reproduce

1. Use default settings (non-VP mode, ui.useTerminalBuffer unset)
2. Run a flow that launches several background agents (e.g., a parallel review with multiple subagents)
3. Wait for conversation/tool output to fill the terminal height
4. Try to scroll up while agents are still running

Expected Behavior

The view should scroll up normally, showing earlier output.

Actual Behavior

• Scroll-up immediately snaps back to the bottom
• Screen flickers during each repaint cycle (~1s intervals)
• Issue resolves once all agents finish

Root Cause

controlsHeight (footer height) is measured in a useLayoutEffect whose dependencies don't include the agent roster state. When LiveAgentPanel grows (agents launching/changing status), the measurement effect doesn't re-run, leaving controlsHeight stale (too small). This causes the content area to overflow the terminal viewport, and the per-second elapsed-time ticks force repaints that snap the view to the bottom.

Environment

• OS: macOS
• Qwen Code version: latest main
• ui.useTerminalBuffer: not set (default false)

[qwen-code-ci-bot]

This issue involves the availableTerminalHeight calculation in AppContainer.tsx, specifically the controlsHeight measurement effect not re-firing when LiveAgentPanel grows. A related issue in the same layout subsystem was previously reported and closed:

• bug(cli): When active "Virtualized History" in /settings, viewport height is taller than expected #4921 — Viewport height too tall in VP mode due to staticExtraHeight underestimating the header. Root cause was different (header not subtracted), but both issues share the same AppContainer height-reservation math and the controlsHeight / availableTerminalHeight pipeline.

The fix proposed here (roster-derived layout key in the useLayoutEffect dependency array) is analogous to the stickyTodosLayoutKey pattern already in use and targets the measurement stale-ness without adding render churn.

[qwen-code-ci-bot]

Triage

• Type: bug — TUI rendering regression in non-VP mode
• Labels: type/bug, category/ui, scope/rendering, scope/components, priority/P2, welcome-pr
• Root cause confirmed: controlsHeight useLayoutEffect in AppContainer.tsx (line ~2537) depends on [buffer, terminalWidth, terminalHeight, btwItem, dialogsVisible, stickyTodosLayoutKey] — none reflect LiveAgentPanel roster growth. When agents launch, controlsHeight stays stale (too small), availableTerminalHeight overshoots, and the dynamic region overflows the terminal → scroll-up snaps back + flicker.
• Fix direction: add a roster-derived layout key (agent count + terminal-status changes that affect panel row count) to the dependency array, following the existing stickyTodosLayoutKey pattern. Requires destructuring entries from useBackgroundTaskViewState() in AppContainer (currently only bgTasksDialogOpen is consumed there).
• CHANGELOG context: #3909 introduced LiveAgentPanel, #3721 fixed a similar height-based flicker for the old SubAgent display. This is the same class of bug — footer measurement not tracking a dynamic child's growth.
• Similar issues: none found
• Next: community PR welcome — well-scoped fix (~10 lines).

Source Verification

• Reproduced in tmux: no — requires multi-agent launch on a short terminal (hard to automate). Root cause confirmed by source inspection.
• Affected files:
  • packages/cli/src/ui/AppContainer.tsx:2537–2559 — useLayoutEffect missing a LiveAgentPanel-derived dep
  • packages/cli/src/ui/layouts/DefaultAppLayout.tsx:106–115 — LiveAgentPanel rendered inside mainControlsRef (intentional, so measureElement counts its rows — but the effect never re-runs when the panel grows)
  • packages/cli/src/ui/components/background-view/LiveAgentPanel.tsx:199–215 — per-second setNow tick drives repaints; panel height = roster rows + overflow line + focus hint
• Confidence: high — the mechanism is clear from code. entries from useBackgroundTaskViewState() (already available in AppContainer at line 1587) only updates on status transitions, not per-second ticks, so adding a derived layout key won't cause extra render churn.
• Implementation note: the layout key should capture agent count + statuses that affect visible row count (e.g. entries.filter(isAgentEntry).map(e => [e.agentId, e.status])), stable across the per-second tick but reactive to add/remove/status-change events.

中文说明

• 类型: bug — 非 VP 模式下 TUI 渲染回归
• 根因已确认: AppContainer.tsx 中 controlsHeight 的 useLayoutEffect 依赖数组不包含任何反映 LiveAgentPanel 行高变化的变量。当后台 agent 启动时，面板增高但 controlsHeight 仍为旧值（偏小），导致 availableTerminalHeight 过大，动态区域溢出终端。
• 修复方向: 参照 stickyTodosLayoutKey 模式，从 entries 派生一个 layout key 加入依赖数组。需要在 AppContainer 中额外解构 entries（当前只用了 bgTasksDialogOpen）。
• 相关历史: #3909 引入 LiveAgentPanel，#3721 修过类似的旧 SubAgent 高度闪烁问题。
• tmux 复现: 未复现——需要多 agent 启动 + 矮终端环境，难以自动化。根因已通过源码分析确认。
• 实现要点: layout key 应捕获影响面板行数的信息（agent 数量 + 状态），对每秒 tick 保持稳定，仅在 add/remove/status-change 时变化。
• 下一步: 欢迎社区 PR，修复范围明确（约 10 行代码）。

— Qwen Code · qwen3.7-max