Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs(session-host): document the 10k emulator history cap

reviewb9922cd0c8ec
diff --git a/CLAUDE.md b/CLAUDE.md
index c06ca6534..478192fdc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1489,7 +1489,11 @@ seed** — the cases are:
xterm's own `scrollback` (`xtermScrollback(settings.tmuxScrollback)`, floored at 1000, capped at
`XTERM_SCROLLBACK_MAX` = 10000) is kept for the sessions tmux does *not* back (a plain shell when
tmux is unavailable) and for the cold-snapshot replay — it is not what the user scrolls in a tmux
-session.
+session. **The Windows session host's headless emulator (and `NativeWindowsPane`) uses the SAME
+clamp** (`src/shared/scrollback.ts`, re-clamped inside the host for older clients), never the raw
+`tmuxScrollback`: xterm holds every line at full width (cols × 12 B, ~72 MB for 50k × 120 cols per
+session) where tmux stores only used cells, and nothing above the renderer's cap is ever shown.
+tmux's `history-limit` keeps the raw value.
## Terminal node lifecycle (gotchas)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4794b1458..aa6e8f0bd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -506,6 +506,11 @@ anything else. Board-level fields survive every transform — `pullLinks` is one
sees the pane app's own bytes — see CLAUDE.md's "We have our own VT emulator" for the one place
that reasoning is inverted.
+- **An xterm-shaped buffer never takes the raw `tmuxScrollback`.** tmux's `history-limit` stores
+ only used cells; an xterm buffer (the renderer, the Windows session host's headless emulator,
+ `NativeWindowsPane`) allocates every line at full width. Size them with `xtermScrollback` from
+ `src/shared/scrollback.ts` (≤ 10k), so the host never keeps history the renderer cannot show.
+
- **A new session-host push frame must be negotiated at `hello`, never just sent.** An older
`SessionHostClient` treats EVERY push frame whose `type` is not `data` as an exit, and a
long-lived host routinely outlives the app that started it — so a frame the connection did not
diff --git a/docs/windows-session-host.md b/docs/windows-session-host.md
index 9d48f81a7..b8bd62fa2 100644
--- a/docs/windows-session-host.md
+++ b/docs/windows-session-host.md
@@ -676,16 +676,33 @@ app already keeps at rest (accounts, hook tokens) relies on.
## Memory bound
-Each `HostSession` holds one `@xterm/headless` `Terminal` with `scrollback` capped at
-`settings.tmuxScrollback` (default 50,000 lines) — the exact same setting that already bounds real
-tmux's `history-limit`, so a machine that already accepted the cost of N tmux panes accepts the
-same order of cost for N session-host sessions. The per-session cost is a cell buffer sized
-`cols × (rows + scrollback)`, plus `SerializeAddon`'s own transient string-building cost only at
-the moment `serialize()` is actually called (attach, join, periodic snapshot, capture request) —
-never held continuously. This is a genuinely new per-session cost the tmux backend does not pay
-(tmux's server keeps its own C-side pane buffer regardless, but that cost is outside this app's
-process); it was a deliberate choice per the task brief ("bound the memory... document the cost
-you chose and why") rather than an oversight.
+Each `HostSession` holds one `@xterm/headless` `Terminal` whose `scrollback` is
+`xtermScrollback(settings.tmuxScrollback)` — floored at 1,000 and **capped at 10,000 lines**
+(`src/shared/scrollback.ts`), the same clamp as the renderer's own xterm. Core sends the clamped
+value, and the host clamps again at the `attach` request boundary (`clampEmulatorScrollback`) so an
+older client still sending the raw 50,000 is bounded too; the clamp runs before both the
+replacement-replay fingerprint and construction, so a replay of the same request still matches.
+The main-process `NativeWindowsPane` mirror (non-persisted win32 panes) uses the same clamp.
+
+Why not reuse tmux's `history-limit` (default 50,000): the costs are not the same order. tmux
+stores only the cells a line actually uses, in C. xterm's `BufferLine` is a `Uint32Array(cols × 3)`
+— **12 B per cell for every buffered line, whatever it holds** — so a 120-column session that fills
+50,000 lines holds ~72 MB of ArrayBuffer (measured ~91 MB with heap overhead; ~139 MB at 200 cols)
+inside the one shared host process, against ~14–18 MB at 10,000. And lines past the renderer's
+10,000 were never reachable: on this backend the renderer's xterm is the only surface a user
+scrolls, yet every warm attach serialized the full history, shipped it over the pipe and IPC, and
+the receiving xterm discarded 80% of it (measured: 50k lines → 5.4 MB string built synchronously in
+~0.7 s, stalling every session's output; 10k → 1.1 MB in ~0.13 s). Capping the emulator bounds that
+attach seed, the co-attach resync and `capture`'s `full: true` by construction — no protocol field
+was needed.
+
+Not reclaimed in place: a session that an OLDER host created at 50,000 keeps that buffer until it
+ends — installing a new app does not upgrade a running host (see below), and an old host cannot be
+told to shrink. Lowering the setting likewise applies to new sessions only. Beyond the emulator,
+the remaining per-session cost is `SerializeAddon`'s transient string at the moment `serialize()`
+runs (attach, join, periodic snapshot, capture request) — never held continuously.
+
+Device check owed (not blocking): host RSS with 10–20 busy normal-screen sessions, before and after.
A DETACHED session's cost is bounded by the same session budget tmux sessions are
(`core/session-budget.ts`): past the grace window, under memory pressure or past the detached-count
diff --git a/src/renderer/components/settings/sections/TmuxSection.tsx b/src/renderer/components/settings/sections/TmuxSection.tsx
index 5e361e538..5b88b836f 100644
--- a/src/renderer/components/settings/sections/TmuxSection.tsx
+++ b/src/renderer/components/settings/sections/TmuxSection.tsx
@@ -11,6 +11,7 @@ import { Switch } from '@renderer/ui/Switch'
import { NumberField } from '@renderer/ui/NumberField'
import { Select } from '@renderer/ui/Select'
import { normalizeSessionBackend, ZELLIJ_BACKEND_GAPS } from '@shared/session-backend'
+import { XTERM_SCROLLBACK_MAX } from '@shared/scrollback'
import {
LEAD_PANE_WIDTH_DEFAULT,
LEAD_PANE_WIDTH_MAX,
@@ -103,6 +104,10 @@ export function TmuxSection({ isActive }: { isActive: boolean }): React.JSX.Elem
<SearchableRow {...ROWS.scrollback}>
<FieldRow
label="Scrollback lines"
+ description={
+ 'tmux’s history-limit for each terminal. ' +
+ `Without tmux (Windows), history is capped at ${XTERM_SCROLLBACK_MAX.toLocaleString('en-US')} lines: the app holds it at full width in memory.`
+ }
control={
<NumberField
value={settings.tmuxScrollback}