v0.8.66: Terminal visual regression matrix for contrast, borders, truncation, and overlays

[Hmbown]

Parent: #3480

Problem

CodeWhale has multiple open reports that are really the same class of failure: terminal UI states render, but the information is hard or impossible to read because of contrast, border, wrapping, clipping, overlay, or width behavior.

Examples to fold into the same QA lens:

• [Bug] /model /sessions command TUI selector has extremely low text contrast on macOS terminal (v0.8.64) #3474 low text contrast in /model / /sessions selector on macOS terminal
• The border lines in the settings interface are rendering incorrectly. This bug has not been fixed yet. #1165 settings interface border lines rendering incorrectly
• 文案展示不全 #998 copy/text displayed incompletely
• 笔记本安装win包后，运行任务结果展示不全 #805 Windows/laptop task result display incomplete
• recent v0.8.65 screenshots where sub-agent overlays, task sidebar, statusline, and transcript compete for space

Scope

Build a visual regression matrix for terminal states that should remain legible across representative terminals and widths.

Cover at least:

• normal transcript with running tools
• /model and /sessions selectors
• settings/config surfaces
• approval modal
• sub-agent/Fleet progress overlay
• task sidebar with long task names
• long CJK/Unicode text
• narrow, medium, and wide terminal widths
• light/high-contrast-ish and dark terminal palettes where feasible

Suggested Implementation

• Add deterministic fixture states that do not require provider access.
• Render snapshots or golden text/cell assertions through the existing TUI test surface.
• Include checks for clipping, overlap, unreadable empty rows, impossible contrast pairs, and broken borders.
• Keep this separate from subjective theme redesign; this issue is about preventing obviously broken terminal rendering.

Acceptance Criteria

• Representative UI states can be rendered in tests without network/provider access.
• The matrix includes at least one narrow-width and one medium-width terminal case.
• Tests catch low-contrast selector rows, broken borders, clipped key labels, and long-row truncation regressions.
• [Bug] /model /sessions command TUI selector has extremely low text contrast on macOS terminal (v0.8.64) #3474 has a concrete fixture or reproduction path tied to the matrix.
• Findings feed back into v0.8.66 EPIC: TUI information architecture and visual UX overhaul #3480's information architecture work rather than becoming one-off cosmetic patches.

[Hmbown]

Dogfood screenshot notes from 2026-06-23 13:03-13:04 local run. These should become concrete fixture cases for the visual matrix, not just subjective polish.

Observed states:

1. Sub-agents modal / Fleet progress overlay

   • Header row fits poorly at the right edge; the Cancel affordance is visually cramped/cut off.
   • Agent rows expose raw IDs, branch names, objectives, and millisecond durations, but the user-facing status is hard to scan.
   • Very long objectives and branch names are truncated mid-thought, e.g. provider-route and README tasks lose the action/result portion.
   • The bottom help chrome (Esc to close, R to refresh) consumes a full line and competes with content inside a short modal.

2. Nested detail popover over transcript/sidebar

   • The agent detail popover appears near the bottom of the terminal and collides with the statusline/bottom bar.
   • Text beneath the popover remains visible around/behind it, making the state look overdrawn rather than deliberately layered.
   • The detail row mixes internal state (agent_e0b2dcf1, depth, status: model wait, elapsed time, objective) in one dense block with no visual priority.
   • Right-side task/sidebar content and the popup fight for the same visual plane; the popup does not clearly own focus.

3. Regression cases to add

   • Medium-width terminal with transcript + right task sidebar + sub-agent overlay open.
   • Bottom-edge detail popover with statusline visible.
   • Three running agents with long branch names, long objectives, and raw durations.
   • One row with mixed English/CJK display name.
   • Modal where a top-right action label must remain fully visible or collapse to a fixed-width icon/short command.

Acceptance additions for this issue:

• Overlays should erase/occlude underlying cells cleanly; no transcript/status text should bleed through.
• Popup placement should flip upward or shrink/scroll when near the bottom edge instead of colliding with the statusline.
• Long objective/branch text should preserve useful prefixes/suffixes and degrade predictably.
• Durations should render human-scale values in UI surfaces instead of large millisecond counts.
• Action/help chrome should have a stable reserved area and should not crowd the primary content rows.