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
• wraps replay in explicit replay-start/replay-complete markers, retains byte-counted chunks with replay/live provenance in shared client state, and sends ordered append/reset/replay-append commands to native mobile renderers
• honors DEC synchronized-output mode 2026 in the web/desktop Ghostty renderer, routes resize and device-pixel-ratio repaints through the same gate, and draws Unicode block elements to exact cell edges
• keeps the normal shell on the host light/dark theme while applying dark defaults only during the standard alternate screen used by btop, vim, htop, and similar TUIs

This supersedes #8564, keeping its feature work and hardening the replay protocol against the delivery failures a full review pass found:

• replay markers are only sent to clients that requested replayBytes, so released web and mobile clients whose bundled contracts predate the markers keep decoding the attach stream instead of failing on the first event
• a replay-complete marker now latches the client out of every open replay instead of incrementing a counter, and the slow-consumer resync re-emits one after clearing the transport queue; a marker lost to backpressure or a transport hand-off can no longer leave the renderer permanently in replay mode with Ghostty's PTY writer detached (which silently ate DSR/DA query replies and hung full-screen apps)
• the attach event buffer is byte-bounded at 4 MB instead of 32 events, so an extended 4 MB replay over a slow link no longer self-destructs into a 64 KB resync snapshot the moment the terminal produces a quarter second of live output
• retained client chunks compact in place when the chunk budget fills, so ~1,000 small interactive writes no longer force a full renderer reset that snapped the viewport to the bottom and cleared the selection every few minutes of typing
• each attach scan run seeds a distinct reset epoch, so a stream rebuilt by a connection hand-off can never alias a stale renderer cursor and silently freeze the web or mobile terminal
• mobile defers the empty replay reset until the first history chunk arrives, so reconnects on flaky links no longer blank the native terminal while up to 4 MB re-feeds
• the UTF-8 chunk splitter now lives once in packages/shared and is used by both the server batcher and the client chunk store, with a fast path that skips the decode round-trip for single-chunk writes

Verification for the hardening pass, on top of the original PR's browser and benchmark evidence:

• 127 focused server, client-runtime, contracts, and mobile tests plus 91 focused web Ghostty/drawer tests, including new coverage for marker gating without replayBytes, completion latching after a lost marker, appending across chunk compaction, and resetting a cursor that falls inside a compacted chunk
• typechecks for contracts, shared, client-runtime, server, web, and mobile
• targeted lint and formatting for every touched file

Visual verification (carried from #8564; the rendering paths are unchanged by the hardening pass):

Before

After

Review pass 2 (rebase onto main, bot findings, TUI validation)

Squash-rebased onto current main (carries lifecycleVersion from #9663 through the chunked reducer, and supersedes the line-capped BoundedTerminalHistory from #9703: durable history here is byte-bounded and append-only, so the per-chunk rebuild that PR removed no longer exists). A write queued behind a held mouse release now re-reads the session's process after acquiring the permit, so a restart during the hold can no longer send input to the stopped PTY. Browser validation on the rebased branch covered btop and htop in the light host theme, a 30k-line scrollback with the 4 MB extended replay after a reload, thread switching, a real mouse click on htop's Quit label, and re-attach while a TUI runs. That surfaced two real defects on top of the bot findings:

• Re-attach left full-screen apps partially painted. The attach "wiggle" resized the PTY to cols-1 and back immediately; ncurses only reports KEY_RESIZE when the size it reads differs from the one it has, so the pair collapsed into a no-op. The intermediate size is now held for 100 ms.
• Frames from a previous TUI leaked onto the primary screen. The replay prefix skipped any mode the retained tail mentioned. When the tail spanned an app's exit and relaunch, the older frames were replayed on the primary screen and reappeared under the shell after the new app quit. The server now tracks the DEC mode state at the first byte of each retained tail (advanced as caps drop its prefix) and prefixes exactly that state.
• DECSTR (CSI !p) is no longer treated as a mode reset. Measured against the vendored libghostty-vt wasm: it leaves every tracked mode untouched, while RIS clears them all (matches @pnupu's note from fix(server): reset terminal modes a dead shell leaves in inherited history #9221).
• Hidden thread drawers stay mounted as on main (bounded by the existing retention), and the surface skips painting while its mount has no size. Switching threads keeps the same Ghostty instance, scroll position, and extended history.
• An app-owned drag stays captured and silent after tracking ends instead of falling through to selection handling; one-eighth block edges stay at least one pixel wide in narrow cells.
• Mobile: the attach seed counts as a pending replay so reconnects keep the last frame, and a failed native command rebuilds the surface once instead of waiting for the next output.

After: htop fully repainted 3 s after a page reload, and a clean primary screen after quitting an htop that was relaunched inside the retained tail.

Not covered here: native mobile rendering was typechecked and unit-tested only, not run on a device.

Feature work authored by GPT-5.6 Sol with the Codex harness; review passes and hardening by Claude Fable 5 and Claude Fable 5.1 with Claude Code, all through T3 Code.

---

Note

High Risk
Changes span server attach/replay protocol, session state shape (buffer → chunked output), and native mobile command paths; older clients or stale native binaries can mis-decode streams or lack streaming APIs.

Overview
Mobile native terminals now accept incremental output instead of rebuilding from a single initialBuffer prop. Android and iOS expose streamingRevision 2 with async write, writeReplay, and reset, queue up to 8 MiB of pending data before the surface exists, suppress PTY query replies during replay, and coalesce redraws. Ghostty scrollback is configured as 64 MiB (byte budget) so large 4 MiB replays fit.

NativeTerminalSurface switches from a flat buffer string to TerminalOutputState, gates on native streaming support, and queues reset / write / writeReplay commands with retry, deferred empty replay resets while history streams, and one-shot surface recovery on command failure. The thread route passes replayPending, replayPaused, and requests EXTENDED_TERMINAL_REPLAY_BYTES on attach when the binary supports it; buffer replay helpers only signal pause during font-layout transitions instead of hiding the whole buffer.

Server TerminalManager tests in this diff reflect the broader streaming work: byte-capped durable history and replay tails, replay-start / replay-complete only when replayBytes is set, PTY output batching and pause/resume under backlog, DEC mode prefixing for aged replay tails, attach resize wiggle for alternate-screen apps, and stricter mouse report handling when tracking ends.

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

Note

Stream terminal output and history as bounded replay and live chunks

• Replaces the terminal string buffer with TerminalOutputState in terminalSession.ts, containing UTF-8-bounded chunks, ids, and replay/live delivery labels.
• Server Manager.ts bounds history by bytes (64 MiB scrollback), adds PTY backpressure (pauseOutput/resumeOutput), and emits replay-start/replay-complete markers around snapshots.
• Client rendering (Web and Mobile) consumes incremental output updates via a cursor and handles the replay lifecycle to display extended history (up to 4 MiB) when scrolling to the top.
• terminal.ts adds optional replayBytes (64 KiB to 8 MiB) to TerminalAttachInput and includes the new replay boundary markers in TerminalAttachStreamEvent.
• Risk: Attach stream consumers must handle the new replay-start/replay-complete event types and TerminalOutputState instead of the removed string buffer; native terminal modules must support streaming revision 2 for replay streaming.

^{Macroscope summarized 54c6751.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a cross-platform terminal streaming and replay system that changes server PTY handling, persistence, transport contracts, web rendering, and native mobile behavior. It also changes product defaults and adds lint-suppression directives, so the scope and operational impact require human review.

Not approved because:

• Per-PR cost limit exceeded (workspace setting). Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings, or comment @macroscope-app review this PR to bypass the limit and review now. You can add or adjust custom eligibility rules. Learn more.}

[pnupu]

Heads-up on overlap: #9221 adds a small neutralizeInheritedHistory in Manager.ts for the same dead-process scenario your decModeResetSuffix handles (issue #9219, and #8574). It uses the same DEC mode table as this PR so it should absorb cleanly on rebase. Two things it covers that this PR currently does not, in case you want to fold them in: the Kitty keyboard stack (CSI > flags u push/pop/set, reset with CSI = 0 ; 1 u, which is what Codex CLI leaves behind), and DECSTR is deliberately not treated as a reset, since the vendored libghostty-vt leaves all of these modes unchanged on CSI ! p (measured against the wasm).

[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 9391da2. Configure here.}

[StiensWout]

@pnupu thanks for the DECSTR measurement. I re-measured against the vendored wasm and it holds (DECSTR leaves all tracked modes untouched, RIS clears them), so this PR no longer treats CSI !p as a reset. The Kitty keyboard stack is left to #9221.

[macroscopeapp]

Macroscope skipped reviewing this pull request. Per-PR cost limit exceeded (workspace setting).

Reviews on this PR have cost $44.21 so far. This review would add an estimated $9.31, bringing the total to $53.53 — above your per-PR limit of $50.00.

Tip

To get this pull request reviewed, you can:

1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
2. Exclude large or generated files from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
3. Raise your cost limit in your workspace billing settings.

^{Turn off this reminder going forward}