fix(cli): eliminate banner duplication and drag flicker on resize/wake

packages/cli/src/ui/AppContainer.test.tsx

@@ -4,8 +4,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-const { writeTerminalTitleSpy } = vi.hoisted(() => ({
+const { writeTerminalTitleSpy, useWakeRepaintMock } = vi.hoisted(() => ({
   writeTerminalTitleSpy: vi.fn(),
+  useWakeRepaintMock: vi.fn(),
+}));
+
+vi.mock('./hooks/use-wake-repaint.js', () => ({
+  useWakeRepaint: useWakeRepaintMock,
 }));
 
 vi.mock('../utils/windowTitle.js', async (importOriginal) => {
@@ -954,7 +959,7 @@ describe('AppContainer State Management', () => {
       expect(mockStdout.write).toHaveBeenCalledWith(ansiEscapes.clearTerminal);
     });
 
-    it('refreshStatic skips the physical clear in VP mode (#4891)', () => {
+    it('refreshStatic stays write-free in VP mode for ordinary callers (#8557)', () => {
       const vpSettings = {
         merged: {
           hideTips: false,
@@ -980,13 +985,61 @@ describe('AppContainer State Management', () => {
 
       capturedUIActions.refreshStatic();
 
-      // VP mode owns the viewport via the React tree, so refreshStatic must not
-      // emit a physical clear — the resize-settle path (#4891) strands nothing.
+      // Ordinary callers (/clear, model change, Ctrl+O, ...) must not
+      // trigger a physical clear-and-replay in VP: replaying the pre-change
+      // frame would flash stale content. Their refresh comes from the state
+      // change that triggered them; only the wake path repaints physically.
+      expect(mockStdout.write).not.toHaveBeenCalledWith(
+        ansiEscapes.clearViewport,
+      );
       expect(mockStdout.write).not.toHaveBeenCalledWith(
         ansiEscapes.clearTerminal,
       );
     });
 
+    // The wake/SIGCONT trigger itself is covered by use-wake-repaint.test.ts
+    // (SIGCONT/heartbeat-gap -> repaint callback); the VP/static selection is
+    // unit-covered by buildWakeRepaint tests. This test locks the AppContainer
+    // call site: the callback handed to the hook must be the wake repaint
+    // (repaintViewport + remount), not refreshStatic or a mis-wired memo.
+    it('wires the wake repaint (not refreshStatic) into useWakeRepaint', async () => {
+      useWakeRepaintMock.mockClear();
+      const repaintSpy = vi.fn();
+      const vpSettings = {
+        merged: {
+          hideTips: false,
+          theme: 'default',
+          ui: {
+            showStatusInTitle: false,
+            hideWindowTitle: false,
+            useTerminalBuffer: true,
+          },
+        },
+        setValue: vi.fn(),
+      } as unknown as LoadedSettings;
+
+      render(
+        <AppContainer
+          config={mockConfig}
+          settings={vpSettings}
+          version="1.0.0"
+          initializationResult={mockInitResult}
+          repaintViewport={repaintSpy}
+        />,
+      );
+
+      // Let ink-testing-library's scheduled initial render flush.
+      await Promise.resolve();
+      const wakeCallback = useWakeRepaintMock.mock.calls.at(-1)?.[0];
+      expect(typeof wakeCallback).toBe('function');
+      act(() => {
+        wakeCallback();
+      });
+      // A revert to useWakeRepaint(refreshStatic) would leave the spy
+      // uncalled (VP refreshStatic is write-free) and fail here.
+      expect(repaintSpy).toHaveBeenCalledTimes(1);
+    });
+
     it('defaults to VP mode when useTerminalBuffer is unset', () => {
       const defaultSettings = {
         merged: {

packages/cli/src/ui/AppContainer.tsx

@@ -78,6 +78,7 @@ import {
   buildResumedHistoryItems,
   expandCollapsedHistory,
 } from './utils/resumeHistoryUtils.js';
+import { buildWakeRepaint } from './utils/terminal-resize-reflow.js';
 import { loadLowlight } from './utils/lowlightLoader.js';
 import {
   getStickyTodos,
@@ -624,6 +625,12 @@ interface AppContainerProps {
   initializationResult: InitializationResult;
   initialUseVirtualViewport?: boolean;
   extensionRefreshState?: ExtensionRefreshState;
+  /**
+   * VP wake/SIGCONT repaint: clear the viewport and replay the last frame
+   * (Ink skips unchanged-output redraws, so a bare clear would blank the
+   * screen). Falls back to a viewport clear when absent.
+   */
+  repaintViewport?: () => void;
 }
 
 /**
@@ -639,8 +646,13 @@ const SHELL_WIDTH_FRACTION = 0.89;
 const SHELL_HEIGHT_PADDING = 10;
 
 export const AppContainer = (props: AppContainerProps) => {
-  const { settings, config, initializationResult, initialUseVirtualViewport } =
-    props;
+  const {
+    settings,
+    config,
+    initializationResult,
+    initialUseVirtualViewport,
+    repaintViewport,
+  } = props;
   const extensionRefreshState = useMemo(
     () => props.extensionRefreshState ?? new ExtensionRefreshState(),
     [props.extensionRefreshState],
@@ -1287,15 +1299,16 @@ export const AppContainer = (props: AppContainerProps) => {
   }, []);
 
   // In VP mode (ui.useTerminalBuffer) the React tree fully owns the visible
-  // region via ink 7 native overflow clipping. Writing clearTerminal /
-  // cursorTo+eraseDown would be a wasted flash and would also corrupt the
-  // in-app scroll position. The remount-key bump is also a near-no-op for
-  // VP: nothing in the VP render path is keyed by historyRemountKey, so
-  // keeping the bump is harmless because the startup-scoped VP decision
-  // is intentionally restart-only to match Ink's alternateScreen lifetime.
-  // The visible refresh in VP mode comes for free from the React tree
-  // re-reading `mergedHistory` / `allVirtualItems` on whatever state
-  // change triggered refreshStatic (Ctrl+O, model change, etc.).
+  // region via ink 7 native overflow clipping. The remount-key bump is
+  // write-free but not inert: one-shot <Static> output keyed by it (agent
+  // tab history in AgentChatContent) is only re-emitted on a bump.
+  // refreshStatic must stay write-free in VP: ordinary callers (Ctrl+O,
+  // model change, /clear, ...) get their visible refresh from the state
+  // change that triggered them, and replaying the pre-change frame would
+  // flash stale content. Only the wake/SIGCONT path (wakeRepaint below) does
+  // a physical clear-and-replay, because there the terminal buffer may be
+  // stale or rearranged while Ink both erases with a stale relative count
+  // and skips redraws whose output is unchanged.
   const [useTerminalBuffer] = useState(
     () =>
       initialUseVirtualViewport ??
@@ -1310,9 +1323,32 @@ export const AppContainer = (props: AppContainerProps) => {
     if (!useTerminalBuffer) {
       stdout.write(ansiEscapes.clearTerminal);
     }
+    // VP stays write-free for ordinary callers (/clear, model change, Ctrl+O,
+    // ...): replaying the pre-change frame would flash stale content. Their
+    // visible refresh comes from the state change that triggered them. The
+    // wake/SIGCONT path repaints separately via useWakeRepaint below.
     remountStaticHistory();
   }, [useTerminalBuffer, remountStaticHistory, stdout]);
 
+  // Wake/SIGCONT: the terminal buffer may be stale or rearranged, and Ink
+  // both erases with a stale relative count and skips redraws whose output
+  // is unchanged — so VP repaints by replaying the last frame over a clean
+  // viewport (viewport-only: clearTerminal's 3J would destroy scrollback /
+  // Warp history) and bumps the static remount key so one-shot <Static>
+  // history (agent tabs) is re-emitted over the clear. Static mode uses the
+  // ordinary refreshStatic. Selection extracted (buildWakeRepaint) for unit
+  // coverage.
+  const wakeRepaint = useMemo(
+    () =>
+      buildWakeRepaint({
+        isVP: useTerminalBuffer,
+        repaintViewport,
+        refreshStatic,
+        remountStaticHistory,
+      }),
+    [useTerminalBuffer, repaintViewport, refreshStatic, remountStaticHistory],
+  );
+
   // Keep the static header in sync with model changes without polling.
   // Ink's <Static> output is append-only, so model changes must explicitly
   // clear and remount the static region to redraw the banner at the top.
@@ -3402,7 +3438,7 @@ export const AppContainer = (props: AppContainerProps) => {
   // display sleep, Ctrl+Z → fg).  The terminal's screen buffer is stale but
   // Ink's frame-diff state still reflects the pre-sleep output, so the next
   // render strands border characters on screen.
-  useWakeRepaint(refreshStatic);
+  useWakeRepaint(wakeRepaint);
 
   useEffect(() => {
     if (ideNeedsRestart) {

packages/cli/src/ui/startInteractiveUI.tsx

@@ -35,6 +35,7 @@ import {
   pushKittyProtocolFlags,
 } from './utils/kittyProtocolDetector.js';
 import { installTerminalRedrawOptimizer } from './utils/terminalRedrawOptimizer.js';
+import { installTerminalResizeReflow } from './utils/terminal-resize-reflow.js';
 import { installSynchronizedOutput } from './utils/synchronizedOutput.js';
 import {
   isInteractiveTerminal,
@@ -164,6 +165,15 @@ export async function startInteractiveUI(
     isInteractiveTerminal(),
   );
 
+  // On width shrink the terminal reflows the printed frame into more physical
+  // rows than Ink's stale erase count (issue #8557); amplify the clear to the
+  // reflowed height. Installed before render() so the resize listener runs
+  // ahead of Ink's resized().
+  const resizeReflow =
+    process.stdout.isTTY && !config.getScreenReader()
+      ? installTerminalResizeReflow(process.stdout, { virtualViewport: useVP })
+      : { restore: () => {}, repaint: () => {} };
+
   // Create wrapper component to use hooks inside render
   const AppWrapper = () => {
     const kittyProtocolStatus = useKittyKeyboardProtocol();
@@ -195,6 +205,7 @@ export async function startInteractiveUI(
                         initializationResult={initializationResult}
                         initialUseVirtualViewport={useVP}
                         extensionRefreshState={options.extensionRefreshState}
+                        repaintViewport={resizeReflow.repaint}
                       />
                     </BackgroundTaskViewProvider>
                   </AgentViewProvider>
@@ -313,6 +324,10 @@ export async function startInteractiveUI(
     if (useVP) {
       process.stdout.setMaxListeners(stdoutMaxListeners);
     }
+    // Unwind the stdout.write wrapper stack in LIFO order (resizeReflow is
+    // installed last / outermost); the identity-guarded restores silently
+    // no-op and leak wrappers otherwise.
+    resizeReflow.restore();
     restoreSynchronizedOutput();
     restoreTerminalRedrawOptimizer();
     // If the ErrorBoundary caught a rendering error, echo it to stderr

packages/cli/src/ui/utils/synchronizedOutput.test.ts

@@ -31,6 +31,8 @@ function createStdout(write: NodeJS.WriteStream['write']): NodeJS.WriteStream {
 describe('terminalSupportsSynchronizedOutput', () => {
   it.each([
     [{ TERM_PROGRAM: 'WezTerm' }, true],
+    [{ TERM_PROGRAM: 'WarpTerminal' }, true],
+    [{ TERM_PROGRAM: 'ghostty' }, true],
     [{ TERM_PROGRAM: 'iTerm.app' }, true],
     [{ TERM: 'xterm-kitty' }, true],
     [{ KITTY_WINDOW_ID: '1' }, true],

packages/cli/src/ui/utils/synchronizedOutput.ts

@@ -53,7 +53,16 @@ export function terminalSupportsSynchronizedOutput(
   }
 
   const termProgram = env['TERM_PROGRAM'];
-  if (termProgram === 'WezTerm' || termProgram === 'iTerm.app') {
+  // Warp's DECRQM 2026 probe answers status 2 (recognized, reset), so
+  // synchronized updates are available there; without them Warp renders the
+  // erase-then-rewrite pattern as flicker (issue #8557). Ghostty implements
+  // synchronized output natively.
+  if (
+    termProgram === 'WezTerm' ||
+    termProgram === 'iTerm.app' ||
+    termProgram === 'WarpTerminal' ||
+    termProgram === 'ghostty'
+  ) {
     return true;
   }