perf(server): make terminal history updates incremental

[burnmandont]

What Changed

• Replace repeated full-string terminal history rebuilding with an incremental bounded line buffer.
• Materialize retained history only for snapshots and coalesced persistence writes.
• Preserve partial lines, empty lines, trailing newlines, clearing, and the configured line cap.
• Document the server-owned terminal output and persistence path.

Why

Every PTY output chunk currently concatenates, splits, caps, and rejoins the entire retained history. Once the default 5,000-line buffer is full, sustained output repeatedly copies the whole buffer and makes callback cost proportional to retained history size.

The bounded buffer processes only newly received text during the hot path while keeping the existing wire format, persistence format, and terminal behavior unchanged.

A local Node 26.2 benchmark appended 50,000 representative one-line chunks while retaining 5,000 lines. The existing implementation took 7,342.5 ms; the incremental buffer took 5.5 ms (approximately 1,325x faster). Both produced byte-for-byte identical 230,000-byte output. These are machine-specific measurements rather than a product budget.

Verification

• vp test run apps/server/src/terminal/Manager.test.ts — 55 tests passed
• vp run --filter t3 typecheck — passed (pre-existing Effect suggestions only)
• vp fmt --check apps/server/src/terminal/Manager.ts apps/server/src/terminal/Manager.test.ts docs/internals/terminal-runtime.md — passed

Checklist

• This PR is small and focused
• I explained what changed and why
• UI screenshots are not applicable
• Interaction video is not applicable

Created with GPT-5.6 in the Codex harness.

---

Note

Medium Risk
Touches core terminal output and persistence on every PTY chunk; behavior is heavily tested but regressions in line boundaries or capping would affect all integrated terminals.

Overview
Replaces per-chunk full-string history rebuild (concatenate, split, cap, rejoin) with an incremental BoundedTerminalHistory line buffer on the PTY output hot path. Sessions now append sanitized chunks and only value() materialize the full transcript for client snapshots and debounced disk writes.

Clear, restart, and cwd/context resets use history.clear() instead of assigning an empty string; the coalescing persist worker still receives the live buffer object and writes history.value() after debounce. Wire format and line-cap semantics stay the same, with a new test covering chunked partial lines, empty lines, and trailing newlines.

Adds docs/internals/terminal-runtime.md documenting the output path and the performance invariant that retained history must not be copied on every PTY callback.

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

Note

Make terminal history updates incremental in TerminalManager

• Replaces full-string concatenation on every PTY output event with an incremental line buffer (BoundedTerminalHistory) that caps retained lines and materializes the full string only on demand
• Persistence worker now holds the bounded buffer reference and calls value() at write time, so debounced writes reflect the latest state instead of a snapshot string enqueued earlier
• Session open, reset, clear, and restart paths all operate on the bounded buffer API; initial history is capped during construction and existing buffers are cleared before re-persistence on context change or error
• Adds a regression test for empty lines, partial-line continuation, and line-limit preservation, plus internal runtime documentation
• Risk: BoundedTerminalHistory handles trailing-newline and partial-line state internally; any out-of-tree code reading the history field via snapshot will still get a string, but the value is now materialized through BoundedTerminalHistory.value() rather than maintained eagerly

📊 Macroscope summarized ed17b7d. 2 files reviewed, 1 issue evaluated, 1 issue filtered, 0 comments posted

🗂️ Filtered Issues

apps/server/src/terminal/Manager.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 823: append drops a newline-only chunk when the existing history already ends in a newline. For example, appending "\n" to retained "a\n" takes the this.trailingNewline branch with an empty appendedLines array, leaving the value "a\n" rather than "a\n\n". PTY chunk boundaries can split consecutive blank lines this way, so terminal history and persisted/snapshotted output silently lose empty lines. [ Out of scope (triage) ]

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the production terminal output hot path and persistence lifecycle through a new stateful buffering abstraction. Although the scope is focused and the external formats remain stable, the runtime impact is broad enough to merit human review.

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

[juliusmarminge]

Superseded by #9703 (perf(server): stop rebuilding terminal history per chunk), which continues this work and has merged to main.

Closing this PR in favor of that continuation.