fix(terminal): make the 10 000-line scrollback promise true

libghostty's `Options::max_scrollback` is documented as a line count and is a
byte budget for the history page list. Passing 10 000 for "10 000 lines" bought
one page: 745 rows at 80 columns, 456 at 200, 3 310 at 20, and doubling the
number changed nothing because both values are smaller than a page. A session
that promised a 10 000-line replay window delivered 7% of it, and
`scrollback_capacity()` reported a number that described nothing.

The line count is now converted to a byte budget that scales with the width
(256 + 16 bytes per column per line, against a measured ~838 at 80 columns and
~1 804 at 200), capped at 64 MiB. `scrollback()` reports what is retainable,
`scrollback_request()` what was asked for, and `scrollback_bytes()` the budget
libghostty holds it in — so the reported numbers describe the terminal rather
than the request.

Two consequences are recorded rather than hidden: capacity is a guaranteed
minimum instead of Node's ceiling, because libghostty never holds less than one
page; and widening a terminal lowers the line count it can retain, because
libghostty takes the budget in `Options` and exposes no setter.

docs/decisions/0013-scrollback-is-a-line-promise.md has the measurements, the
memory cost, and the remaining gap.

Refs #3

agent-identity: dev3.direct.omp.2gz9tcpa
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.1.2
agent-runtime: OMP 18.1.2
tooling-profile: dotfiles@7534055

Author: schickling-assistant

crates/pty-terminal/src/actor.rs

@@ -24,9 +24,50 @@ use crate::serialize::{self, SerializeOpts};
 use crate::snapshot::{self, CellGrid};
 use crate::strip::{OutputScanner, Osc, Token};
 
-/// Node's scrollback (`src/server.ts:333-338`).
+/// Node's scrollback (`src/server.ts:333-338`), in lines.
 pub const DEFAULT_SCROLLBACK: usize = 10_000;
 
+/// The most memory one terminal's history may be given, whatever scrollback
+/// it was asked for: 64 MiB, which is 10 000 lines of a 400-column terminal.
+///
+/// A session that asks for more history than this gets what fits and says so
+/// ([`TerminalActor::scrollback`] reports what is actually retainable, not
+/// what was requested), because a silently unmet promise is what this whole
+/// conversion exists to remove.
+pub const MAX_SCROLLBACK_BYTES: usize = 64 * 1024 * 1024;
+
+/// libghostty's `max_scrollback` is a **byte** budget for the history page
+/// list, not a line count — its own doc comment says "lines", but the
+/// behaviour is bytes and the page list evicts whole pages. Passing 10 000
+/// for "10 000 lines" buys one page: 745 rows at 80 columns, 456 at 200,
+/// 3 310 at 20. A line promise therefore has to be converted, and the cost
+/// of a row depends on how wide it is.
+///
+/// These two numbers are the conversion, measured against libghostty-vt
+/// 0.2.1: a plain row costs ~838 bytes at 80 columns and ~1 804 at 200, so
+/// ~9-10 bytes per column plus per-row overhead. They are deliberately
+/// generous — roughly 1.8x the measured cost — because the page list rounds
+/// up to whole pages and because a row of styled or multi-codepoint cells
+/// costs more than a plain one. Under-budgeting loses history; over-budgeting
+/// costs address space that is only touched when the history actually fills.
+const SCROLLBACK_BYTES_PER_COL: usize = 16;
+/// Fixed per-row cost, independent of width. See
+/// [`SCROLLBACK_BYTES_PER_COL`].
+const SCROLLBACK_ROW_OVERHEAD: usize = 256;
+
+/// What one row of a `cols`-wide terminal costs in the history.
+fn scrollback_row_bytes(cols: u16) -> usize {
+    SCROLLBACK_ROW_OVERHEAD + SCROLLBACK_BYTES_PER_COL * cols.max(1) as usize
+}
+
+/// The byte budget that retains `lines` lines of a `cols`-wide terminal,
+/// capped at [`MAX_SCROLLBACK_BYTES`].
+fn scrollback_budget(lines: usize, cols: u16) -> usize {
+    lines
+        .saturating_mul(scrollback_row_bytes(cols))
+        .min(MAX_SCROLLBACK_BYTES)
+}
+
 /// A desktop notification the child asked for (OSC 9, 99, or 777).
 /// Shapes follow Node (`src/server.ts:421-454`).
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -156,7 +197,12 @@ pub struct TerminalActor {
     modes: Modes,
     events: Vec<TerminalEvent>,
     last_title: Option<String>,
-    scrollback: usize,
+    /// Lines of history the owner asked for.
+    scrollback_request: usize,
+    /// The byte budget libghostty was given for the history. Fixed at
+    /// construction: libghostty takes it in `Options` and exposes no setter,
+    /// so a resize changes how many lines it holds, not how much memory.
+    scrollback_bytes: usize,
     /// How big a cell is on the surface that draws this terminal, zero when
     /// undeclared. It comes from the client (a font on its host), travels on
     /// ATTACH and RESIZE, and decides the cell extent of any placement that
@@ -176,12 +222,17 @@ pub struct TerminalActor {
 
 impl TerminalActor {
     /// A terminal of `rows` x `cols` with `scrollback` lines of history.
+    ///
+    /// The line count is converted to the byte budget libghostty actually
+    /// takes (see [`MAX_SCROLLBACK_BYTES`]); [`TerminalActor::scrollback`]
+    /// reports how many lines that buys at the current width.
     pub fn new(rows: u16, cols: u16, scrollback: usize) -> TerminalActor {
         let shared: Rc<RefCell<Shared>> = Rc::new(RefCell::new(Shared::default()));
+        let scrollback_bytes = scrollback_budget(scrollback, cols);
         let mut term = Terminal::new(Options {
             cols: cols.max(1),
             rows: rows.max(1),
-            max_scrollback: scrollback,
+            max_scrollback: scrollback_bytes,
         })
         .expect("libghostty terminal");
         {
@@ -210,7 +261,8 @@ impl TerminalActor {
             modes: Modes::default(),
             events: Vec::new(),
             last_title: None,
-            scrollback,
+            scrollback_request: scrollback,
+            scrollback_bytes,
             cell: CellSize::default(),
             graphics: None,
             normal_replay: None,
@@ -653,13 +705,38 @@ impl TerminalActor {
     }
 
     /// Node's `scrollbackCapacity`: `rows + scrollback`.
+    ///
+    /// A guaranteed minimum, not a ceiling. libghostty's history is a list of
+    /// pages and it never holds less than one, so a terminal asked for a
+    /// small scrollback retains more than it promised (a 100-line request at
+    /// 80 columns keeps ~1 000 rows). Node's number is a ceiling because
+    /// xterm counts lines; this one is a floor because libghostty counts
+    /// bytes and rounds to pages
+    /// (docs/decisions/0013-scrollback-is-a-line-promise.md).
     pub fn scrollback_capacity(&self) -> usize {
-        self.rows() as usize + self.scrollback
+        self.rows() as usize + self.scrollback()
     }
 
-    /// Configured scrollback lines.
+    /// How many lines of history this terminal retains at its current width.
+    ///
+    /// Normally the line count the owner asked for. It is less when the byte
+    /// budget cannot buy that many — either because the request exceeded
+    /// [`MAX_SCROLLBACK_BYTES`], or because the terminal has since been
+    /// widened and libghostty's budget is fixed at construction. Reporting
+    /// the request in that case is what made the promise a lie.
     pub fn scrollback(&self) -> usize {
-        self.scrollback
+        let fits = self.scrollback_bytes / scrollback_row_bytes(self.cols());
+        self.scrollback_request.min(fits)
+    }
+
+    /// Lines of history the owner asked for, whether or not they fit.
+    pub fn scrollback_request(&self) -> usize {
+        self.scrollback_request
+    }
+
+    /// The byte budget libghostty holds the history in.
+    pub fn scrollback_bytes(&self) -> usize {
+        self.scrollback_bytes
     }
 
     /// Node's `baseY`: the buffer row where the active area starts.

crates/pty-terminal/tests/scrollback.rs

@@ -0,0 +1,147 @@
+//! The scrollback promise: a terminal asked for N lines of history retains N
+//! lines, and says so.
+//!
+//! libghostty's `max_scrollback` is a byte budget for the history page list,
+//! not a line count — its own doc comment says "lines" — and the page list
+//! evicts whole pages. Passing 10 000 for "10 000 lines" buys one page: 745
+//! rows at 80 columns, 456 at 200, 3 310 at 20. Every case here is about the
+//! conversion that makes the declared line count true, and about the reported
+//! numbers being the truth rather than the request.
+
+use pty_terminal::actor::{DEFAULT_SCROLLBACK, MAX_SCROLLBACK_BYTES};
+use pty_terminal::{Range, TerminalActor};
+
+/// Feed `n` numbered lines, each short enough that it cannot wrap, so a row
+/// written is a row of history and nothing here depends on reflow.
+fn fill(a: &mut TerminalActor, n: usize) {
+    for i in 0..n {
+        a.write(format!("L{i}\r\n").as_bytes());
+    }
+}
+
+/// The oldest of 10 000 lines is still reachable, at the geometry the
+/// terminal was built with. This is the substrate's promised replay window;
+/// before the byte conversion it retained 745 of them.
+#[test]
+fn ten_thousand_lines_of_history_are_all_retained() {
+    let mut a = TerminalActor::new(24, 80, DEFAULT_SCROLLBACK);
+    fill(&mut a, 10_008);
+
+    // 10 008 written lines plus the row the cursor sits on, all within the
+    // 10 024-row capacity of a 24-row terminal with 10 000 lines of history.
+    assert!(
+        a.buffer_length() >= 10_008,
+        "expected every line retained, got {} rows",
+        a.buffer_length()
+    );
+    let text = a.plain(Range::Full);
+    let first = text.lines().next().unwrap_or("");
+    assert_eq!(first, "L0", "the oldest line is still the oldest line");
+    assert!(text.contains("\nL9999\n"), "and the newest are there too");
+}
+
+/// The same promise at widths where the byte cost of a row differs by 5x. A
+/// budget derived from the line count has to scale with the width, or a wide
+/// terminal keeps a fraction of the history a narrow one does.
+#[test]
+fn the_promise_holds_at_every_width() {
+    for cols in [20u16, 80, 200, 400] {
+        let mut a = TerminalActor::new(24, cols, 10_000);
+        fill(&mut a, 10_008);
+        assert!(
+            a.buffer_length() >= 10_008,
+            "{cols} columns: expected 10 008 rows, got {}",
+            a.buffer_length()
+        );
+        assert_eq!(
+            a.plain(Range::Full).lines().next().unwrap_or(""),
+            "L0",
+            "{cols} columns: the oldest line was evicted"
+        );
+    }
+}
+
+/// A small scrollback is a line promise too, and the promise is a floor: the
+/// history is a list of pages and libghostty never holds less than one, so a
+/// terminal asked for 100 lines keeps at least 100 and in practice more.
+/// Bounded, though — a terminal asked for 100 lines does not keep 5 000.
+#[test]
+fn a_small_scrollback_keeps_at_least_what_it_promised() {
+    let mut a = TerminalActor::new(24, 80, 100);
+    fill(&mut a, 5_000);
+    let text = a.plain(Range::Full);
+    for i in 4_900..4_999 {
+        assert!(
+            text.contains(&format!("L{i}\n")),
+            "the promised window must be there: L{i} is missing"
+        );
+    }
+    assert!(text.contains("L4999"), "including the newest line");
+    assert!(!text.contains("L0\n"), "and the far past is evicted");
+    assert!(
+        a.buffer_length() < 5_000,
+        "a 100-line request must not keep 5 000 rows, got {}",
+        a.buffer_length()
+    );
+}
+
+/// `scrollback_used` and `scrollback_capacity` are the numbers a consumer
+/// budgets against, so they have to describe the terminal rather than the
+/// request.
+#[test]
+fn used_and_capacity_are_honest() {
+    let mut a = TerminalActor::new(24, 80, DEFAULT_SCROLLBACK);
+    assert_eq!(a.scrollback(), DEFAULT_SCROLLBACK);
+    assert_eq!(a.scrollback_capacity(), 24 + DEFAULT_SCROLLBACK);
+    assert_eq!(a.scrollback_used(), 24, "an empty terminal is its viewport");
+
+    fill(&mut a, 10_008);
+    assert_eq!(a.scrollback_used(), a.buffer_length());
+    // Capacity is a floor, not a ceiling (see its doc comment): what it
+    // promises has to actually be there.
+    assert!(
+        a.scrollback_used() >= 10_008,
+        "capacity is not honest if the rows are not there: {}",
+        a.scrollback_used()
+    );
+}
+
+/// A request beyond the memory bound is reported as what it is. libghostty
+/// takes the budget at construction and exposes no setter, so this cannot be
+/// fixed by asking for more later — it can only be told truthfully.
+#[test]
+fn a_request_beyond_the_memory_bound_reports_what_fits() {
+    let a = TerminalActor::new(24, 80, 10_000_000);
+    assert_eq!(a.scrollback_request(), 10_000_000);
+    assert_eq!(a.scrollback_bytes(), MAX_SCROLLBACK_BYTES);
+    assert!(
+        a.scrollback() < 10_000_000,
+        "the request cannot be met and must not be reported as met"
+    );
+    assert!(
+        a.scrollback() > DEFAULT_SCROLLBACK,
+        "but the bound still buys more than the default: {}",
+        a.scrollback()
+    );
+    assert_eq!(a.scrollback_capacity(), 24 + a.scrollback());
+}
+
+/// Widening the terminal makes each row cost more out of a budget fixed at
+/// construction, so the retainable line count drops. The reported number
+/// follows it instead of repeating the original promise.
+#[test]
+fn a_widened_terminal_reports_the_history_it_can_still_hold() {
+    let mut a = TerminalActor::new(24, 80, DEFAULT_SCROLLBACK);
+    assert_eq!(a.scrollback(), DEFAULT_SCROLLBACK);
+    let budget = a.scrollback_bytes();
+
+    a.resize(400, 24);
+    assert_eq!(a.scrollback_bytes(), budget, "the budget does not move");
+    assert!(
+        a.scrollback() < DEFAULT_SCROLLBACK,
+        "a five-times wider row cannot hold the same line count: {}",
+        a.scrollback()
+    );
+    assert_eq!(a.scrollback_capacity(), 24 + a.scrollback());
+    assert_eq!(a.scrollback_request(), DEFAULT_SCROLLBACK);
+}

docs/decisions/0013-scrollback-is-a-line-promise.md

@@ -0,0 +1,110 @@
+# 0013 — scrollback is a line promise, and libghostty counts bytes
+
+**Status:** accepted
+
+**Node behavior.** Node's daemon passes `scrollback: 10000` to
+`xterm-headless` (`src/server.ts:333-338`), where it is a line count: the
+buffer holds 10 000 lines of history and evicts the 10 001st line. `pty stats`
+reports `scrollbackUsed` (`buffer.active.length`, `src/server.ts:1128`) against
+`scrollbackCapacity` (`rows + scrollback`), and that capacity is a ceiling the
+buffer never exceeds.
+
+**Rust behavior.** `TerminalActor::new(rows, cols, scrollback)` still takes a
+line count, and now converts it to the byte budget libghostty actually wants.
+
+libghostty's `Options::max_scrollback` is documented as "maximum number of
+lines to keep in scrollback history" and is not: it is a byte budget for the
+history page list, and the list evicts whole pages. Measured against
+libghostty-vt 0.2.1, a terminal given `max_scrollback: 10_000` and fed 10 008
+short lines keeps:
+
+| columns | rows retained | oldest line surviving |
+| --- | --- | --- |
+| 20 | 3 310 | `L6698` |
+| 80 | 745 | `L9263` |
+| 200 | 456 | `L9552` |
+| 400 | 149 | `L9859` |
+
+The retained count scales inversely with the width, which a line count cannot
+do, and doubling the number to 20 000 changes nothing at 80 columns — both are
+smaller than one page, and one page is the floor. Passing a line count straight
+through therefore delivered 7% of the promised history at 80 columns, and the
+number `scrollback_capacity()` reported (`24 + 10_000`) described nothing that
+existed.
+
+The conversion is `SCROLLBACK_ROW_OVERHEAD + SCROLLBACK_BYTES_PER_COL * cols`
+per line (256 + 16), against a measured cost of ~838 bytes per row at 80
+columns and ~1 804 at 200 — roughly 1.8x headroom, because the page list rounds
+up to whole pages and because a row of styled or multi-codepoint cells costs
+more than a plain one. The total is capped at `MAX_SCROLLBACK_BYTES` (64 MiB,
+which is 10 000 lines of a 400-column terminal).
+
+Three reads describe the result instead of the request:
+
+- `scrollback()` — lines actually retainable at the current width.
+- `scrollback_request()` — what the owner asked for, met or not.
+- `scrollback_bytes()` — the budget libghostty holds the history in.
+
+**Why.** The alternative was to leave the number as libghostty takes it and
+weaken the promise to "up to N lines", which is what the first Fractal test did
+when it asserted `used <= capacity` — an assertion that passes when 6 398 of
+10 008 lines have been thrown away. A replay window is a product promise: a
+consumer that shows history decides what to keep on the basis of that number,
+and the honest options were to meet it or to publish a smaller one. Meeting it
+costs memory that is bounded, documented, and only touched when the history
+actually fills; publishing a smaller one would have meant every consumer
+carrying its own conversion from lines to whatever libghostty's number means
+this release.
+
+libghostty exposes the budget only in `Options`, with no setter, so it is fixed
+at construction. That is the source of the one remaining gap below.
+
+**Client effect.** A session asked for 10 000 lines retains 10 000 lines at the
+width it was created with, and `stats` reports numbers that are true. Memory
+per session with the default 10 000 lines: 14.6 MiB of budget at 80 columns
+(33 MiB at 200, 63.5 MiB at 400), against ~1 MiB before — the budget is address
+space the page list fills only as history accumulates, so an idle session pays
+nothing.
+
+Residual differences a consumer can observe:
+
+1. `scrollback_capacity()` is a guaranteed minimum, where Node's is a ceiling.
+   libghostty never holds less than one page, so a terminal asked for a small
+   scrollback keeps more than it promised: a 100-line request at 80 columns
+   retains about 1 000 rows. The promise is met and then some; code that
+   treated the number as an upper bound on `scrollback_used` has to stop.
+2. Widening a terminal reduces the line count it can retain, because the byte
+   budget is fixed at construction and a wider row costs more. `scrollback()`
+   and `scrollback_capacity()` follow the width down; `scrollback_request()`
+   keeps saying what was asked for. A terminal created at 80 columns and
+   widened to 400 holds about a fifth of the lines. Fixing this needs either a
+   libghostty setter for the budget (upstream) or budgeting for the widest
+   plausible width at construction (10 000 lines at 1 000 columns is 154 MiB
+   per session, which is not worth it).
+3. A request whose budget exceeds `MAX_SCROLLBACK_BYTES` is clamped, and
+   `scrollback()` reports the clamped line count rather than the request.
+
+**Test.** `crates/pty-terminal/tests/scrollback.rs` — six cases, all of which
+fail on the pass-through:
+`ten_thousand_lines_of_history_are_all_retained` (the oldest of 10 008 lines is
+still `L0`, at 24x80 with the default scrollback),
+`the_promise_holds_at_every_width` (the same at 20, 80, 200 and 400 columns,
+where the per-row cost differs by 5x),
+`a_small_scrollback_keeps_at_least_what_it_promised` (the promised window is
+present and the far past is gone),
+`used_and_capacity_are_honest`,
+`a_request_beyond_the_memory_bound_reports_what_fits`, and
+`a_widened_terminal_reports_the_history_it_can_still_hold`.
+
+Every line written by these tests is short enough that it cannot wrap, so no
+result here depends on reflow: a row written is a row of history.
+
+No gated `_node` / `_rust` conformance pair exists for the byte conversion
+itself — it is an implementation detail of reaching Node's behaviour, not a
+deviation from it. The observable deviations are the three above.
+
+**Migration / negotiation.** None. `TerminalActor::new` and
+`SpawnOptions`/`AttachOptions` still take a line count and now honour it; a
+consumer reading `scrollback_capacity()` as a ceiling should read it as a floor
+(residual 1), and one that resizes should re-read `scrollback()` rather than
+assume the original number (residual 2).