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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(session-host): document the 10k emulator history cap
reviewb9922cd0c8ec
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 whentmux 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.mdindex 4794b1458..aa6e8f0bd 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -506,6 +506,11 @@ anything else. Board-level fields survive every transform — `pullLinks` is onesees the pane app's own bytes — see CLAUDE.md's "We have our own VT emulator" for the one placethat 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 along-lived host routinely outlives the app that started it — so a frame the connection did notdiff --git a/docs/windows-session-host.md b/docs/windows-session-host.mdindex 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-countdiff --git a/src/renderer/components/settings/sections/TmuxSection.tsx b/src/renderer/components/settings/sections/TmuxSection.tsxindex 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}><FieldRowlabel="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={<NumberFieldvalue={settings.tmuxScrollback}