Summary

This is PR4 in the TUI flicker/stability series and is intentionally stacked on #3587 (codex/pr3-narrow-shell-viewport). It should stay last in the stack because it touches terminal protocol behavior and stdout monkeypatch ordering.

It adds a conservative DECSET 2026 synchronized-output wrapper for supported terminals so a burst of Ink frame writes can be bracketed by BSU/ESU. Unknown terminals, tmux, SSH, JetBrains, non-TTY output, and screen reader mode stay on the existing path by default.

Changes

• Add synchronizedOutput utility with DECSET 2026 BSU/ESU frame bracketing.
• Enable only for known supported terminals by default: WezTerm, iTerm2, and kitty.
• Keep tmux / SSH / JetBrains / unknown terminals disabled unless explicitly forced.
• Add env rollback controls:
  • QWEN_CODE_DISABLE_SYNCHRONIZED_OUTPUT=1
  • QWEN_CODE_SYNCHRONIZED_OUTPUT=0
• Add explicit force controls for manual validation:
  • QWEN_CODE_FORCE_SYNCHRONIZED_OUTPUT=1
  • QWEN_CODE_SYNCHRONIZED_OUTPUT=1
• Preserve stdout.write return value, callback, Buffer, and encoding behavior.
• Install after terminalRedrawOptimizer and restore before it so the monkeypatch stack unwinds cleanly.
• Expose BSU/ESU balance counters for verification.

Issue Class

Targets the PR4 issue class from the TUI plan:

• Residual frame tearing / intermediate frames after PR1-PR3 application-level fixes.
• Terminal-family-specific flicker where synchronized output is supported.
• Safe fallback and rollback for unsupported terminals.

Verification

After rebasing on the updated PR2/PR3 stack:

• git diff --check
• cd packages/cli && npx vitest run src/ui/hooks/useGeminiStream.test.tsx src/ui/components/messages/ToolMessage.test.tsx src/ui/utils/terminalRedrawOptimizer.test.ts src/ui/utils/synchronizedOutput.test.ts
• cd packages/core && npx vitest run src/utils/terminalSerializer.test.ts src/services/shellExecutionService.test.ts
• npm run typecheck --workspace=packages/cli
• npm run typecheck --workspace=packages/core
• npm run lint --workspace=packages/cli
• npm run lint --workspace=packages/core

Manual Matrix

Before merge, please manually verify:

• WezTerm
• kitty
• iTerm2
• JetBrains terminal: should not regress by default
• tmux / SSH: should not enable by default
• screen reader mode: should not install protocol wrapper

Effect Comparison

Before screenshot/video:

TODO: attach supported-terminal frame tearing before this PR.

After screenshot/video:

TODO: attach the same scenario after this PR.