vscode: terminal renders corrupted and cursor lands at top after window reactivation

[amrmelsayed]

Symptom

When the VSCode window loses focus (alt-tab to another app, lock screen, second monitor switch, etc.) and the user returns to the Codev terminal pane, one of two things happens:

1. Cursor renders at the wrong location — typed input lands near the top of the terminal pane instead of in the prompt area at the bottom where the cursor should be.
2. Rendering corruption — the status bar / INSERT line stack up and partially overlay each other; old TUI frames bleed into new ones; the visual state of the terminal looks distorted until something forces a redraw (resize, focus toggle, manual refresh).

The two symptoms appear together or one without the other. Screenshots below show both in the same affected pane.

Reproduction

1. Open a builder or architect terminal in VSCode (any Codev terminal pane backed by the shellper PTY relayed through Tower).
2. Let the TUI (Claude Code's UI, or any full-screen alt-screen TUI) render normally.
3. Switch focus away from the VSCode window — alt-tab to another app, lock the screen, or move to a different desktop / monitor. Wait at least a few seconds.
4. Return focus to the VSCode window and click into the terminal pane.
5. Type any character.

Expected: the character renders in the prompt area at the bottom of the terminal where the cursor was.
Actual: the character renders near the top of the terminal pane and / or the visible TUI state shows stacking overlapping render lines from prior frames.

Workarounds (none satisfying)

• Resizing the VSCode window forces a full TUI redraw and clears the corruption — slow and disruptive.
• Manually triggering the editor's terminal "clear" command — destroys the visible history.
• Closing and reopening the terminal tab — destroys the connection.

Screenshots

Screenshot 1 — distorted TUI: stacked INSERT lines (─INSERTe──m▶▶tautotmodeoon, INSERT─C▶▶ auto mode on), the Musing… line garbled, cursor visible near the top by check #861's scope instead of in the empty prompt area below.

Screenshot 2 — typed input rendering at the top of the terminal in what should be chat history (multi-line description text appearing as overlay), pasted file path drawing across older content, empty prompt unchanged at the bottom.

Suspected area

This is a VSCode-side terminal rendering / state-sync issue, not (apparently) a Tower / shellper PTY bug. Several plausible mechanisms, none verified:

1. xterm.js cursor-position desync. VSCode's terminal uses xterm.js. When the WebView loses and regains focus, xterm.js's internal cursor-position state may drift from where the PTY thinks the cursor is. Subsequent keystrokes land at xterm.js's tracked position, not the PTY's actual cursor location.
2. WebSocket reconnect / replay race during window inactivity. When the VSCode window is hidden or inactive, the OS may throttle the WebView's network or timers. The Tower → VSCode WebSocket may briefly disconnect or pause draining. On reactivation, the accumulated output replays in a way that confuses xterm.js. This is adjacent to but distinct from the PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 / tower + vscode: terminal freeze from oversized-replay reconnect storm (unbounded no-newline buffers + client backpressure loop) #1047 terminal-freeze fix — that issue was sustained CPU saturation, this one is a transient render-state corruption on focus change.
3. Connect-time replay path interacting with window-visibility events. PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 added a post-connect repaint nudge to address the blank-pane-on-open case (same-size resize as no-op). The same nudge may need to fire on window reactivation (onDidChangeWindowState) even when no reconnect happened — to force a known-clean redraw after long periods of background output accumulation in an unfocused WebView.
4. TUI escape sequence interleaving during overload. Drop-not-reconnect (also from PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050) keeps the WebSocket alive but drops live output frames under overload. If a partial escape sequence is dropped mid-frame, xterm.js may end up in an inconsistent ANSI parser state. Returning to the window then displays the broken state until a manual redraw.

Reproduction context for the investigator

Per the screenshots, the affected pane is the architect terminal (Claude Code TUI). Reproducible reliably on the architect's daily-driver setup. Worth checking whether builder terminals exhibit the same symptom (same code path) or only the architect's pane (some architect-specific routing).

VSCode version, OS, multi-monitor configuration, and external-display refresh-rate variance probably matter for narrowing this down.

Suggested protocol

PIR. Root cause is ambiguous (four plausible mechanisms above, none verified). Investigation phase needed before a fix shape is obvious. Dev-approval gate is load-bearing because the fix is visual and reproducible-only-in-real-VSCode — PR diff alone cannot verify it works.

Related

• PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 / tower + vscode: terminal freeze from oversized-replay reconnect storm (unbounded no-newline buffers + client backpressure loop) #1047 — terminal freeze fix. Same broader area (terminal-adapter, ring-buffer, reconnect path) but different symptom (sustained CPU pegging vs transient post-focus render corruption). The post-connect repaint nudge from tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 is a related mechanism worth examining for whether it could be extended to handle window-reactivation.
• PR [Bugfix #905] Replay EXIT frame to clients that connect after PTY exit #953 / Investigate flaky session-manager integration tests (formerly skipIf-CI) #905 — late-connect EXIT race fix. Same WS-relayed terminal subsystem but a different timing concern.
• PR terminal: stale tab on a pre-restart terminal id can't self-recover without a manual state re-fetch #991 / Terminals survive a Tower restart: preserve terminal id + stop afx tower stop killing port clients (#991) #999 — terminal id preservation across Tower restart. The WS reconnect logic these added is part of the suspected area.
• vscode: builder terminal unopenable after move-between-groups + close (silent failure, requires VS Code restart) #803 — builder terminal unopenable after move-between-groups + close. Different scenario (group-move state corruption) but same surface (xterm.js + terminal-manager state coordination).

Out of scope

• Tower-side PTY behavior — PTY content reaching Tower is correct; the issue is between Tower's WS relay and VSCode's xterm.js renderer.
• The terminal-freeze / oversized-replay class of bug (already fixed in tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050).
• TUIs running in other terminal applications (iTerm2, Terminal.app) — those use a real PTY path, not the Tower-relayed WS path, and are not in scope here.

[amrmelsayed]

Architect follow-up: ranked hypothesis + suggested verification path

After filing this triage I worked through the four mechanisms above and converged on a strong primary candidate. Posting it as a comment rather than baking it into the spec so the PIR builder can evaluate it on its own merits.

Primary candidate: PR #1050's drop-not-reconnect interacting with background-window throttling

The mechanism:

1. PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 changed the VSCode terminal-adapter from "reconnect on overload" to "drop live output frames under overload." Right fix for the original freeze, but the overload trigger isn't "the terminal emits a lot" — it's "the consumer's receive budget fills." Two distinct triggers reach the same drop path:
   • the terminal genuinely streams a lot (the case the fix targets)
   • the consumer is throttled. When a VSCode window goes to the background, Electron / Chromium throttles the WebView: requestAnimationFrame slows to 1 Hz, network reads can pause, the JS event loop is partially suspended. Tower keeps streaming. The buffer fills. The drop path fires.
2. Drops are indifferent to which ANSI bytes they're dropping. With high probability the dropped bytes include cursor-positioning sequences (ESC[<row>;<col>H, ESC[H), screen-clear sequences (ESC[2J, ESC[K), and alt-screen-state updates that the TUI emits as it incrementally redraws.
3. When the window regains focus, the WebView unfreezes and xterm.js drains the buffer. The buffer is missing the dropped bytes. xterm.js ends up with: cursor at wherever the last received position-set put it (alt-screen-enter starts the cursor at row 0, hence the "cursor at top"), and rendered content layered as TUI incremental redraws stack without their interleaved screen-clear/cursor-move commands (hence "stacked INSERT lines, garbled status bar").

Evidence chain mapping to the screenshots

• "Cursor renders at the top" — maps directly to "alt-screen-enter is the last received cursor-position event because everything after got dropped." Alt-screen-enter starts the cursor at row 0; if nothing later moved it, that's where xterm.js renders subsequent keystrokes.
• "Stacked status / INSERT lines" — maps directly to "screen-clear sequences between TUI frames got dropped." Each new redraw of the status bar would normally be preceded by an ESC[K or equivalent clear; without that, the new draw layers over the previous one.
• "Resize fixes it" — SIGWINCH triggers a full TUI redraw from scratch. The TUI re-emits the entire screen-setup including all cursor-positioning. With the window now focused there's no overload, no drops, and xterm.js gets a complete consistent state.

Why this ranks highest among the four mechanisms

• Timing correlation: the symptom started becoming noticeable now, immediately after PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 landed (yesterday). Pre-tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 behavior was "reconnect on overload" — which would have triggered the post-connect repaint nudge and recovered the dropped state.
• "Cursor at top" is specific: random rendering errors could land cursor anywhere; "top" specifically points at alt-screen-enter being the last consistent cursor-position event.
• Resize-fixes-it is specific: a network-reconnect bug would need a reconnect to fix, not just a redraw. Resize works because it forces a full redraw, recovering from incomplete state.

Why the other three hypotheses are less likely (not impossible)

• xterm.js render-state desync from rAF throttling — could compound but probably isn't independent. Resize-fixes-it argues against rAF throttling as primary: rAF throttling affects rendering not buffer state, and browsers fire pending rAF callbacks rapidly on visibility-change, which would usually be enough without needing a manual resize.
• WS reconnect race during window inactivity — nothing suggests the WS actually disconnects during background inactivity. The reconnect path from PR terminal: stale tab on a pre-restart terminal id can't self-recover without a manual state re-fetch #991 would trigger the existing repaint nudge if it fired.
• Pre-existing xterm.js cursor-position bug under alt-screen mode — possible but xterm.js is widely deployed; this would be a known issue if common. The timing correlation with PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 is too tight to ignore.

Suggested fix shape (for the plan to validate)

Extend the existing repaint-nudge mechanism PR #1050 already put in place. PR #1050 fires the nudge after a reconnect to recover state. We need to also fire it when the window regains focus even without a reconnect, because the drop path can fire during inactivity without the WS ever disconnecting.

// In the terminal-adapter activation path
vscode.window.onDidChangeWindowState((state) => {
 if (state.focused) {
 requestPostConnectRepaint(); // existing helper from PR #1050
 }
});

A more defensive companion fix is to never drop cursor-positioning or alt-screen-state ANSI sequences under overload — the drop logic would parse enough of the bytestream to recognize critical sequences and pass them through. Materially harder than the focus-change nudge; probably not worth it if the nudge handles the common case. Worth keeping as a fallback option if the nudge alone proves insufficient at dev-approval.

Suggested first move for the PIR builder

1. Verify the timing correlation: was this symptom reported before PR tower + vscode: fix terminal freeze (oversized-replay storm) and blank-on-open #1050 merged? git log v3.1.9..HEAD shows the change landed yesterday; if the user can't reproduce it on a v3.1.9 install, the correlation tightens significantly.
2. Reproduce with logging in the drop path: instrument terminal-adapter.ts's drop branch to log a count of bytes dropped per inactivity period. If background-window inactivity produces consistent drops (and foreground use doesn't), the mechanism is confirmed.
3. Prototype the focus-change nudge: simplest change that could possibly work. If it eliminates the symptom, ship that; if it doesn't, escalate to the defensive companion (don't-drop-critical-sequences).

Cross-link to PR #1050 (the source of the drop-not-reconnect logic this hypothesis builds on) for context.

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).