perf(terminal): stream output and history

[StiensWout]

Large terminal sessions repeatedly rebuilt retained output in server and client memory, rewrote growing log files, and could leave slow remote subscribers with unbounded queued deltas. The small attach snapshot limited scrollback, reopening a shell could redraw its prompt through an unchanged PTY resize, and full-screen apps such as btop visibly tore because synchronized updates were painted between PTY chunks.

This makes terminal output a bounded stream end to end:

• coalesces PTY output for up to 8 ms or 64 KB, caps the server pre-drain backlog at 4 MB, and pauses/resumes node-pty around a 2 MB low-water mark
• appends durable history with an 8 MB target / 12 MB ceiling
• starts web attaches with 64 KB, then requests and progressively renders up to 4 MB when the user reaches the top
• restores the top-of-scrollback viewport after deep replay and resets renderer cursors when attach identity or replay budget changes
• bounds each live subscriber to 32 events and resynchronizes a stalled client from the latest recent snapshot
• retains byte-counted chunks with replay/live provenance in shared client state and sends ordered append/reset/replay-append commands to native mobile renderers, even when replay completion and live output reduce in one render
• buffers typed native writes until surfaces mount, suppresses PTY replies for every streamed replay chunk, and clears stale empty frames
• unmounts hidden web terminal renderers and ignores unchanged PTY resize requests
• drains queued large writes through a 64 KB per-frame budget, immediately full-drains at a 1 MB visible backlog, and uses a 100 ms fallback when browsers suspend animation frames
• separates the 64 KB initial replay request from a 512 KB live client-retention floor, while extended attaches retain their full requested history
• honors DEC synchronized-output mode 2026 in the web/desktop Ghostty renderer, with a 500 ms safety flush for interrupted sequences
• routes resize and device-pixel-ratio repaints through the same synchronized-output gate and defers backing-store changes until that paint, keeping the last complete frame visible instead of flashing a cleared canvas
• tracks the installed device-pixel ratio independently of backing dimensions, so DPR-only transitions still schedule the same atomic resize and repaint
• uses one integer logical-pixel cell grid for canvas rendering, libghostty resize, and mouse encoding; solid Unicode block elements are drawn to exact cell edges so TUI art stays seamless and click targets stay aligned
• highlights URLs, paths, and unambiguous source-position file names on Ctrl/Command hover without misclassifying host:port endpoints
• makes paste shortcut delivery first-wins across the async Clipboard API and native paste event, so a single gesture reaches the PTY once
• keeps the normal shell on the host light/dark theme while applying theme-derived dark defaults only during the standard alternate screen used by btop, vim, htop, less, tmux, and similar TUIs; source-to-target remapping preserves reverse video and leaves the primary screen plus explicit ANSI/OSC colors untouched
• preserves legacy Ctrl+C as ETX before Kitty keyboard mode and verifies Ctrl+Right word navigation through the real shell

Measured on this checkout:

• 1 MB client replay, 1 KB events: 729.01 ms to 15.41 ms, 47.3x faster
• 1 MB client replay, 16 KB events: 48.80 ms to 0.843 ms, 57.9x faster
• 1 MB server retention loop: 479.69 ms to 0.265 ms, 1,812x faster
• 128 KB PTY burst: 65 callbacks to 2 output events while preserving exact bytes, 32.5x fewer events
• persistence model: 5.50 MB to 1.00 MB written across ten equal flushes
• btop -u 100 at 150x37: largest synchronized update was 32,507 bytes across roughly six raw PTY callbacks; the fixed renderer painted at a 99.4 ms median interval, matching the requested 100 ms application cadence
• authenticated 5 MB output flood: reducing the bounded immediate-drain threshold from 4 MB to 1 MB lowered the worst observed animation-frame gap from 216.6 ms to 66.7 ms; p95 remained about 33.3 ms
• warm document fetch after five warmups: 20.68 ms local median and 37.54 ms public-route median across 25 requests; these are route checks, not terminal-input RTT measurements

Verification:

• 221 focused tests across contracts, server, client runtime, web Ghostty/drawer behavior, and mobile terminal behavior before the final rebase
• 159 focused server/contracts/client-runtime/web tests after rebasing onto current main
• typechecks for contracts, client runtime, server, web, and mobile; server and web rerun after rebase
• targeted formatting, lint, and mobile native static checks
• authenticated web passes for 64 KB initial replay, 4 MB on-demand history, hidden-drawer reattach, one prompt after switching away and back, the double-prompt regression, and synchronized btop rendering
• 112 focused web tests, lint, and typecheck after the final rebase
• final review hardening: 68 server tests, 83 focused web tests, 5 mobile terminal tests, all package typechecks, native static checks, and targeted lint
• latest mobile review pass: 15 client-runtime tests, 5 focused mobile tests, client-runtime/web/mobile typechecks, and targeted lint; revision 1 uses standard snapshot plus reset/write streaming while revision 2 gates extended replay
• server backpressure test verified PTY pause/resume and exact ordered delivery at a tiny test high-water mark
• browser verification that an async-first plus native paste race writes one marker, and a later context-menu paste remains independent
• browser verification that a clipboard read completing after shortcut key-up does not suppress the next independent paste
• browser verification that light-mode shell → btop -u 100 → light-mode shell and light-mode shell → vim → light-mode shell switch without breakup or residual dark rows
• browser verification that an empty reset while btop owns the alternate screen immediately restores the canvas and mount to rgb(252,252,252)
• browser verification that vim visual selection retains a true inverse region and terminal text selection remains visible (rgb(70,70,70) selected versus rgb(13,13,13) unselected), then exits to a fully light canvas and mount
• browser stress verification across 60 consecutive live-btop resize frames (817↔857 px): zero blank frames, stable visible-content density, and a fully light canvas after exit
• browser verification that OpenCode's Unicode block logo renders without cell seams and that an SGR mouse click 350 px into the surface reports column 50, exactly matching the visible 7 px cell grid plus 4 px padding
• focused verification that URL, repository-path, and bare file:line:column highlighting remains modifier-gated while hostname and IPv4 host:port endpoints stay unlinked

Visual verification:

Before: quitting a full-screen app left dark rows	After: btop stays coherent at 10 Hz	After exit: the light shell is fully restored

Before: font side bearings split block art	After: exact cell geometry joins blocks cleanly

The repository already uses the latest stable node-pty 1.1.0. The 1.2.0-beta.15 line remains prerelease and has a reported Windows regression where persistent PTYs can exit before their first write, so this PR does not take that native dependency risk. The newer Ghostty source needs regenerated WASM, iOS, and Android artifacts plus cross-platform ABI/performance testing, so that vendor refresh remains separate. iOS, Android, and Windows native runtime profiling still require their platform toolchains. Mobile benefits from the 64 KB event ceiling and existing display-frame coalescing, but its native Ghostty APIs do not yet expose mode 2026 for protocol-level gating of updates larger than 64 KB.

Authored by GPT-5.6 Sol with the Codex harness through T3 Code.

Note

Stream terminal output and history with byte-based batching and backpressure

• Replaces line-based terminal history with byte-based budgets (historyTargetBytes, historyMaxBytes, replay variants) and adds output coalescing, chunked persistence, and PTY pause/resume backpressure in TerminalManager.
• Introduces explicit replay-start / replay-complete stream events and chunked replay delivery (≤64 KB chunks), with a new readSnapshot method for subscriber resync on backpressure overflow in ws.ts.
• Reworks client session state to store output as UTF-8-safe TerminalOutputChunk segments with retention budgets, incremental readTerminalOutputUpdate cursors, and replay/live delivery tags in terminalSession.ts.
• Updates web TerminalViewport and mobile NativeTerminalSurface to consume structured output via streaming commands (write, writeReplay, reset), with on-demand extended replay (4 MiB) when scrolling to top.
• Adds Ghostty renderer support for block-element geometry, alternate-screen theme remapping, synchronized output mode (2026), and replay-safe writes that suppress PTY replies.
• Risk: TerminalManagerOptions removes historyLineLimit; any caller passing that option will fail. The attach listener signature gains a required delivery parameter, and TerminalAttachInput now validates replayBytes within [64 KiB, 8 MiB].

^{Macroscope summarized f459a54.}

---

Note

High Risk
Changes span PTY lifecycle, attach streaming protocol, durable history I/O, and native/mobile rendering paths—any ordering or backpressure bug can lose output, duplicate history, or break interactive shells.

Overview
Terminal sessions stop passing one giant buffer string through attach, persistence, and native renderers. Output is retained and delivered as byte-bounded chunks with replay vs live provenance, and the server coalesces PTY output, appends durable history, and pauses the PTY when subscribers fall behind.

Server: TerminalManager replaces line caps with separate durable (≈8–12 MB) and client-replay budgets, batches output (~8 ms / 64 KB), bounds the pre-drain queue (4 MB) with optional pauseOutput/resumeOutput, and wraps attach in replay-start → snapshot → chunked history → replay-complete before live events. Extended attach can request larger replay via replayBytes; attachStream listeners get a delivery flag (replay | live), and slow WS clients get a fresh snapshot instead of an unbounded delta queue. Adds readSnapshot and ignores duplicate resizes.

Clients: Shared state moves from terminal.buffer to TerminalOutputState with readTerminalOutputUpdate driving incremental write / writeReplay / reset on mobile (revision-gated streamingRevision) and ordered replay-then-live rendering on web (writeTerminalOutputSegments, extended replay when scrolling to top). Native Ghostty scrollback limits switch from row counts to 64 MB byte budgets; replay feeds suppress PTY query replies from echoing to the shell.

UI polish: Hidden web terminal drawers unmount instead of staying mounted; buffer replay during font changes becomes an explicit replayPaused flag; terminal link detection gains unambiguous file:line:column patterns without treating host:port as paths; alternate-screen theme CSS variables support full-screen TUIs.

^{Reviewed by Cursor Bugbot for commit f459a54. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0903eaab-cf67-4722-a5d5-83fe8cc9cc2e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

One finding on the new web scrollback-top replay upgrade. Everything else in the in-scope web files (Ghostty core/surface chunked writes, Home/End viewport handling, drawer output-cursor wiring, ChatView drawer unmount) looked consistent with the existing primitives and Tailwind ownership rules.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a broad terminal architecture change spanning PTY backpressure, history persistence, transport protocol events, shared state, and web/native rendering, with substantial new runtime behavior. It also changes default history, buffering, scrollback, and presentation settings, so the impact warrants human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

One finding on the new Ghostty write queue in apps/web/src/terminal/ghostty/surface.ts. The extended-replay viewport restore raised in the previous run now looks addressed by pendingScrollbackReplayIdentityRef + scrollToTopAfterWrites, so that is not re-reported.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding: requesting the extended scrollback replay clears the rendered terminal before the replacement history arrives. Details inline.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding in apps/web/src/terminal/ghostty/surface.ts: the write queue can hold a replay chunk behind a live write, and core.writeReplay throws once the replay has been closed at that boundary, which permanently stalls the rAF drain. Details inline.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding in the web terminal renderer: an extended-replay attach that restarts (e.g. after a WebSocket session change) is no longer treated as a streamed replay, which blanks the viewport and replays retained history through the live write path.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding on the new Ghostty write scheduling: the rAF-gated write queue has no size bound and cannot drain while the window is hidden.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding on the web terminal renderer: the default attach path now retains only one server output batch of client-side output, so a busy terminal falls back to a full ghostty_terminal_reset replay. Details inline.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding in the web renderer: the new per-frame write budget is paired with an unbounded write queue, so sustained PTY output above ~4 MB/s makes the visible terminal fall behind the session instead of janking while staying current. Everything else previously flagged on this PR (blank-screen resets at replay boundaries, replay chunks queued behind live writes, rAF-only draining in hidden windows, retention vs. attach-replay budgets) reads as addressed in the current head.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding on terminal theming ownership; the rest of the changed web surface (streamed replay wiring in ThreadTerminalDrawer, write queue bounds, ChatView unmount) looks consistent with the existing contracts.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

Two theme-ownership issues in the new alternate-screen terminal palette. Everything else in the web scope (streamed replay ordering, bounded write drain, scrollback-top request, renderer default remapping) looks consistent with the existing surface contracts.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding: the resize repaint is now deferred to an animation frame, which lets a frame composite the stale canvas backing store scaled into the new element box.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

Two findings in the web terminal renderer geometry and link detection introduced by fix(web): align terminal interaction geometry. Details inline.

^{Posted via Macroscope — UI Consistency}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a08dae3. Configure here.}

[macroscopeapp]

Reviewed the web terminal changes (ThreadTerminalDrawer.tsx, ghostty/{core,surface,renderer}.ts, terminal-links.ts, index.css). One finding: the drawer's streamed-replay path discards the replay/live classification that readTerminalOutputUpdate returns, so live output batched with a replay is fed into Ghostty with the PTY writer detached.

^{Posted via Macroscope — UI Consistency}

[StiensWout]

Superseded by #9027, which carries this branch's feature work rebased onto current main plus a hardening pass on the replay delivery protocol (marker version-skew gating, completion latching, byte-bounded attach buffering, chunk compaction, and stream-restart epochs). Closing to restart review on the consolidated diff.