tracking: terminal flicker / repaint on VSCode / Cursor / xterm.js hosts

[esengine]

Umbrella issue for collecting reports of screen flicker, frame tearing,
or stale-output artifacts when running reasonix chat / reasonix code
inside terminals built on xterm.js — primarily the VSCode and Cursor
integrated terminals, also Hyper and other Electron-based terminals.

If you've hit this, please file a fresh report using the new
Display / rendering issue
template and link it back here. The terminal-environment fields in that
template are what we actually need to repro and fix.

What we know

• The shell does not matter. PowerShell 5.1, PowerShell 7.x, bash,
  zsh, fish all render identically inside a given terminal host.
• The terminal host is the variable. Standalone Windows Terminal,
  iTerm2, Alacritty, kitty, WezTerm, conhost (cmd.exe) all use native
  renderers and handle our incremental frames cleanly.
• VSCode / Cursor / Hyper embed xterm.js.
  xterm.js only added DEC mode 2026 (synchronized output / BSU+ESU)
  support in 5.4.0 (Apr 2024). VSCode bundles ship xterm.js with a
  lag — older VSCode/Cursor builds drop our \x1b[?2026h…\x1b[?2026l
  envelopes and repaint the per-line diff sequence frame-by-frame, which
  reads as visible flicker.
• Same root cause as Claude Code's #18084.

What our renderer already does

Our forked Ink (ink@7.0.2) on main:

• Line-level incremental diff — only changed lines re-emit
  (node_modules/ink/build/log-update.js)
• Synchronized output bracketing — bsu/esu per frame when stdout is
  a TTY (node_modules/ink/build/write-synchronized.js)
• 30 fps throttle by default

In a host that honors mode 2026 this is enough. In a host that doesn't,
each per-line cursorTo + content + eraseEndLine is painted
individually.

What we want from reports

Quantity over essay. The display_issue template asks for:

1. Which exact terminal host + version
2. TERM_PROGRAM, TERM_PROGRAM_VERSION, COLORTERM, WT_SESSION,
   VSCODE_INJECTION — these split hosts apart deterministically
3. VSCode terminal.integrated.gpuAcceleration value
4. A short screen recording — pictures of flicker are pictures of flicker
5. Whether the same build flickers in a non-VSCode terminal on the
   same machine (the cleanest diagnostic — proves it is the host)

Workarounds while we sort this

• Run reasonix in standalone Windows Terminal / iTerm2 / kitty
  rather than the IDE-embedded terminal.
• On VSCode: try toggling terminal.integrated.gpuAcceleration between
  auto / canvas / off (note: per upstream reports this often does
  not help, but it is cheap to try).
• Update VSCode / Cursor to the latest build — newer xterm.js
  versions honor synchronized output.

Possible mitigations on our side (not yet decided)

• Detect TERM_PROGRAM === 'vscode' and degrade to a lower frame rate +
  no per-token streaming animation
• --reduced-motion / REASONIX_NO_ANIM=1 opt-out flag
• Cell-level diff (only emit changed cells, not whole lines) — bigger
  surgery on the Ink fork; weighing whether the win justifies it given
  that the synchronized-output path already handles the real cases

Reports first; pick a mitigation once we know the actual host
distribution of affected users.

[esengine]

PR #529 lands a partial mitigation: chat now renders with incrementalRendering: false, so each frame is one full-screen redraw inside the BSU/ESU envelope instead of a per-line diff sequence.

For xterm.js hosts that don't honor mode 2026, this collapses the N per-line cursorTo + content + eraseEndLine writes per frame into one frame body — the most visible flicker source goes away even when the synchronized-output bracket itself is dropped. Doesn't replace the cell-level-diff option discussed above and won't help on builds so old the cursor-home redraw still tears, but it's the cheapest win that doesn't fork Ink further.

Leaving this umbrella open — mode 2026 support inside the host is still the long tail driving the remaining reports.