No mechanism to reduce live terminal scrollback buffers under memory pressure

[gregpriday]

Summary

When system memory is constrained, one of the most effective per-terminal mitigations is to reduce the in-memory scrollback buffer. Each terminal holds thousands of lines in memory via xterm.js — at approximately 2 KB per line, a terminal with 5000 lines of scrollback holds ~10 MB. With 10–20 concurrent terminals, that is 100–200 MB that could be partially reclaimed by trimming the scrollback of background terminals. There is currently no mechanism for the main process to request this of live terminals.

Problem Statement

The existing TERMINAL_CONFIG_SET_SCROLLBACK IPC channel updates the user's persistent scrollback setting in the store:

• electron/ipc/channels.ts#L215
• electron/ipc/handlers/terminalConfig.ts#L38

This is a settings update — it writes to store.terminalConfig.scrollbackLines and affects new terminals created afterwards. It does not touch any live running xterm.js Terminal instance.

Live scrollback buffers are owned entirely by the renderer process. The TerminalInstanceService manages xterm.js instances in the renderer, but there is no IPC path for the main process to push a "reduce your scrollback" request to specific live terminals:

• src/services/terminal/TerminalInstanceService.ts

Without this channel, the memory mitigation described in issue #3286 cannot include scrollback reduction as a tier-2 action, even though it would be one of the most impactful recoverable steps (xterm.js 6.0 trims the buffer immediately when terminal.options.scrollback is lowered, and the memory is reclaimed on the next GC cycle).

Desired Behavior

The main process can push a request to the renderer to reduce the scrollback buffer size on specific terminals, or on all background (non-visible, non-focused) terminals. The renderer respects this request by lowering terminal.options.scrollback on the affected live xterm.js instances.

The reduction should be selective — it targets background terminals first, and only applies to terminals that are not currently focused or being actively read by the user. The original scrollback limit should be restorable when pressure subsides (by simply raising the option back to the user-configured default).

A user-visible indicator should be written to the terminal (e.g., a brief system message) when its scrollback is reduced, so the user understands why older history is no longer visible.

Context

xterm.js 6.0 (the version used in this project) supports runtime scrollback modification:

terminal.options.scrollback = newLimit; // Trims oldest lines synchronously

The current renderer terminal instance service manages all live xterm.js instances and is the correct place to handle this:

• src/services/terminal/TerminalInstanceService.ts

The window.electron IPC bridge pattern for push events from main → renderer is established throughout the codebase via the preload and events namespace:

• electron/preload.cts
• src/types/electron.d.ts

Acceptance Criteria

• The main process can send a message to the renderer requesting scrollback reduction on one or more terminal IDs (or "all background terminals")
• The renderer reduces terminal.options.scrollback on the targeted live xterm.js instances to the specified limit
• Terminals that are currently focused or visible in the active panel are not targeted
• A brief system message is written to each affected terminal indicating the scrollback was reduced and why
• The scrollback limit can be restored to the user's configured default when the main process sends a restore message
• This channel is distinct from and does not affect the existing persistent TERMINAL_CONFIG_SET_SCROLLBACK user preference

Edge Cases & Risks

• xterm.js trims the oldest lines when scrollback is reduced — if the user is scrolled up reading old output, that content could disappear mid-read. The implementation should check whether a terminal is scrolled away from the bottom (viewport not at base) and skip those terminals
• The user-visible message written to the terminal should not corrupt the current prompt line — it must use \r\n before and after to avoid cursor alignment issues
• If a terminal has fewer lines in its buffer than the new reduced limit, no trimming occurs and no notification is needed
• Restoring scrollback to the original limit does not restore trimmed lines — this is expected behavior and should be documented in the system message

Dependencies

Depends on #3285 and #3286 — this channel enables the mitigation cascade but requires memory pressure detection to know when to trigger it.