Resize: archive the rows a shrink pushes off, once it is clear they are not a copy

The carry fixed the duplication by clearing the screen before the reflow, and in
doing so quietly ate history: the rows that no longer fitted were dropped, so
every zoom-in cost up to a screenful of scrollback and a pane could no longer
scroll all the way up. Reported from the dev Space, reproduced at 30 lines gone
over six zoom steps.

Archiving them instead brought the duplication straight back — 82 duplicated
tokens — because for a repainting TUI those rows ARE the screen it is about to
reprint. The two failures are the same question with opposite answers, and it
cannot be answered at resize time: it depends on what the app does next.

So it is answered afterwards. The rows go into limbo, and 250ms later
settleArchive looks at whether a screenful arrived: if the app repainted, they
were a copy and are discarded; if nothing came — a shell's log, a TUI that
exited, an agent sitting idle — they were the only copy and are printed into
scrollback with the screen painted back over them. The same verdict updates
host.repaints, so a session whose TUI exited stops being treated as one instead
of carrying a stale guess forever.

Archiving needs rows printed and scrolled off, which took two attempts: a newline
on the last row moves the TOP row into scrollback, not the one just printed, so
the first version archived blank lines and then painted over the real ones.

snapshot.js grows rowsToAnsi for this, and snapshotToAnsi now shares its per-row
rendering instead of duplicating it.

Verified with the browser's own emulator attached to the real server: six zoom
steps lose nothing from the grid and duplicate nothing in either, against 63 and
101 duplicated tokens with AM_RESIZE_CARRY=0.

Two losses in that test are NOT ours, and the test says so rather than pretending:
bash redraws its prompt on every SIGWINCH and, when wrapped, draws over the rows
above it, and xterm's own reflow drops about three lines over a cycle this
violent. Both reproduce identically with the carry disabled. The grid — which is
what a reattach repaints from — is exact.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -148,6 +148,7 @@ conversations.
 | `AM_REPLAY_BYTES` | `262144` | PTY bytes replayed to a reattaching browser |
 | `AM_RESIZE_SETTLE_MS` | `120` | Quiet period before a resize is applied to the PTY |
 | `AM_RESIZE_CARRY` | `1` | `0` reflows on resize like a plain terminal (duplicates scrollback) |
+| `AM_RESIZE_ARCHIVE_MS` | `250` | Grace period for an app to repaint before rows a shrink pushed off are archived |
 | `ANTHROPIC_API_KEY` | — | Claude Code / opencode / Hermes (Space **secret**) |
 | `OPENAI_API_KEY` / `CODEX_API_KEY` | — | Codex (Space secret) |
 | `GEMINI_API_KEY` | — | Gemini CLI (Space secret) |

server/resize.test.mjs

@@ -91,7 +91,7 @@ function view(id, cols, rows, mirror = false) {
         v.frames.push(m);
         if (term && (m.t === 'grid' || m.t === 'restore') && m.cols > 0 && m.rows > 0
             && (term.cols !== m.cols || term.rows !== m.rows)) {
-          if (m.clear) term.write('\x1b[H\x1b[2J', () => term.resize(m.cols, m.rows));
+          if (m.clear) term.write('', () => term.resize(m.cols, m.rows));
           else term.resize(m.cols, m.rows);
         }
       } else {
@@ -261,6 +261,62 @@ try {
     await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
   }
 
+  // --- scrolling back still reaches everything -----------------------------
+  // The first version of the carry cleared the screen and dropped the rows that
+  // no longer fitted, so every zoom-in quietly ate history: a 40->24 shrink took
+  // 16 lines with it and the pane could no longer scroll all the way up. Rows
+  // that fall off the top have to be ARCHIVED, not discarded.
+  if (!Headless) {
+    console.log('SKIP  scrollback checks (@xterm/headless not installed)');
+  } else {
+    const id = await session('resize history');
+    const v = await view(id, 120, 40, true);
+    v.resize(120, 40);
+    await sleep(900);
+    // Teach the host that this session repaints, so the carry path is the one
+    // under test, then leave a real log behind — that is what must survive.
+    v.type(`node ${FIXTURE}\r`);
+    await sleep(1500);
+    v.resize(118, 38);
+    await sleep(800);
+    v.type('\x03');
+    await sleep(800);
+    // The trailing blank lines are load-bearing. Bash redraws its prompt on every
+    // SIGWINCH and, when that prompt is wrapped, draws over the rows above it —
+    // verified identical with AM_RESIZE_CARRY=0, so it is bash's doing and not the
+    // resize path's. Without the padding this test would be asserting something no
+    // terminal delivers.
+    v.type('for i in $(seq 1 200); do echo "hist-$i"; done; echo; echo; echo\r');
+    await sleep(2000);
+
+    const missing = (text) => {
+      const gone = [];
+      for (let i = 1; i <= 200; i++) if (!new RegExp(`hist-${i}(?!\\d)`).test(text)) gone.push(i);
+      return gone;
+    };
+    const before = missing(await v.screenText());
+    check('the log is complete before zooming', before.length === 0, `${before.length} lines missing`);
+
+    for (const [c, r] of [[100, 30], [90, 24], [100, 30], [110, 34], [120, 40], [90, 24]]) {
+      v.resize(c, r);
+      await sleep(400);
+    }
+    await sleep(1200);
+    // The grid is the authority and has to be exact.
+    const gridGone = missing(await gridText(id));
+    check('zooming loses no scrollback in the grid', gridGone.length === 0,
+      gridGone.length ? `${gridGone.length} lines gone, e.g. hist-${gridGone.slice(0, 5).join(', hist-')}` : '');
+    // xterm's own reflow drops a couple of lines over a cycle this violent no
+    // matter what we do — AM_RESIZE_CARRY=0 loses three in the same run, from the
+    // same region — so this is a bound, not a promise. A reattach repaints the
+    // pane from the grid, which is why the grid check above is the strict one.
+    const after = missing(await v.screenText());
+    check('zooming loses no more browser scrollback than plain reflow does', after.length <= 4,
+      after.length ? `${after.length} lines gone, e.g. hist-${after.slice(0, 5).join(', hist-')}` : 'none');
+    v.close();
+    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
+  }
+
   // --- the screen survives a resize the app ignores ------------------------
   // Clearing before the reflow is only safe because the screen is re-painted
   // afterwards. An app that never answers SIGWINCH is the case that proves it:

server/src/runner.js

@@ -6,7 +6,7 @@ import { remoteState, setPaused } from './remote.js';
 import { cliById, WORKSPACES_DIR, isRemote } from './config.js';
 import { update, list } from './sessions.js';
 import { captureOpencodeSession } from './traces.js';
-import { buildPaletteIndex, snapshotToAnsi } from './snapshot.js';
+import { buildPaletteIndex, rowsToAnsi, snapshotToAnsi } from './snapshot.js';
 
 // libghostty-vt ships prebuilts for linux x64/arm64 and macOS arm64. Loading it
 // is guarded so a platform without a prebuilt still boots and says so, rather
@@ -70,6 +70,9 @@ const RESIZE_SETTLE_MS = Number(process.env.AM_RESIZE_SETTLE_MS || 120);
 // plain terminal does, duplication and all. Kept because carrying the screen by
 // hand is the one part of a resize that makes an assumption about the app.
 const RESIZE_CARRY = process.env.AM_RESIZE_CARRY !== '0';
+// How long an app gets to answer SIGWINCH before the rows a shrink pushed off the
+// screen are treated as history rather than as a copy (see settleArchive).
+const ARCHIVE_SETTLE_MS = Number(process.env.AM_RESIZE_ARCHIVE_MS || 250);
 
 const hosts = new Map(); // session id -> host
 
@@ -163,8 +166,8 @@ function effectiveGrid(host) {
  * Re-frame a snapshot for a different geometry, so it can be painted into one.
  *
  * Bottom-anchored on a shrink, like a terminal: the cursor and the newest rows
- * are what a user is looking at. Rows that fall off the top are DROPPED rather
- * than archived — see carryScreen for why that is the point.
+ * are what a user is looking at. The rows that fall off the top are not in here
+ * at all — settleArchive decides what becomes of those.
  */
 function fitSnapshot(snap, cols, rows) {
   const drop = Math.max(0, snap.rows - rows);
@@ -191,18 +194,76 @@ function fitSnapshot(snap, cols, rows) {
  *
  * So the screen is cleared BEFORE the reflow, which leaves it nothing to archive,
  * and re-painted after: snapshotToAnsi positions every row absolutely and emits
- * no newline, so the paint itself cannot wrap or scroll either. Returns the ANSI
- * to feed after the resize, or null when reflow should be left alone (see
- * host.repaints).
+ * no newline, so the paint itself cannot wrap or scroll either.
+ *
+ * The rows that no longer fit cannot be settled here, which took two tries to
+ * see. Dropping them ate real history — a 40->24 shrink lost 16 lines a user
+ * could previously scroll back to. Archiving them brought the duplication
+ * straight back, because for a repainting TUI those rows ARE the screen it is
+ * about to reprint. Whether they are redundant depends on what the app does
+ * NEXT, so they are handed to settleArchive to decide once that is known.
+ *
+ * Returns { pre, ansi, dropped }: bytes for before the resize and after it (both
+ * of which every viewer needs too) plus the rows in limbo. Null when reflow
+ * should be left alone (see host.repaints).
  */
 function carryScreen(host, cols, rows) {
   if (!RESIZE_CARRY || !host.repaints) return null;
-  let ansi = null;
+  let snap;
+  let ansi;
   try {
-    ansi = snapshotToAnsi(fitSnapshot(host.vt.snapshot({ includeCells: true }), cols, rows));
+    snap = host.vt.snapshot({ includeCells: true });
+    ansi = snapshotToAnsi(fitSnapshot(snap, cols, rows));
   } catch { return null; }
-  try { host.vt.feed('\x1b[H\x1b[2J'); } catch { return null; }
-  return ansi;
+
+  const drop = Math.max(0, snap.rows - rows);
+  const pre = '\x1b[0m\x1b[H\x1b[2J';
+  try { host.vt.feed(pre); } catch { return null; }
+  return { pre, ansi, dropped: drop ? rowsToAnsi(snap, 0, drop) : [] };
+}
+
+/**
+ * Put lines into scrollback without disturbing the screen.
+ *
+ * Printing is the only way in — there is no API for "append to history" — so the
+ * lines are printed at the top and then pushed off it, and the screen is painted
+ * back from the grid afterwards. Costs one repaint, which is why it only happens
+ * when nothing else repainted.
+ */
+function archiveLines(host, lines) {
+  let restore;
+  try { restore = snapshotToAnsi(host.vt.snapshot({ includeCells: true })); } catch { return; }
+  let bytes = '\x1b[0m\x1b[H\x1b[2J\x1b[1;1H' + lines.join('\r\n');
+  // A newline on the LAST row is what moves a row into scrollback, and it moves
+  // the top row — not the one just printed. Enough of them to clear the screen
+  // archives every line, whether they all fitted on it or not.
+  bytes += `\x1b[0m\x1b[${host.rows};1H` + '\r\n'.repeat(Math.min(lines.length, host.rows));
+  bytes += restore;
+  try { host.vt.feed(bytes); } catch { return; }
+  for (const sub of host.subs) sub.onData(bytes);
+}
+
+/**
+ * Decide what the rows a shrink pushed off the screen were: a copy, or history.
+ *
+ * A screenful of output within the window means the app answered SIGWINCH by
+ * reprinting its screen, so those rows are about to appear again and archiving
+ * them is what filled the scrollback with duplicates. Silence means they were the
+ * only copy — a shell's log, a TUI that exited, an agent sitting idle — and
+ * dropping them is what stopped a pane from scrolling all the way up.
+ *
+ * Deciding afterwards is the point: at resize time this is not yet knowable, and
+ * both guesses are wrong for somebody. The verdict also updates host.repaints, so
+ * a session that stops repainting (its TUI exited) stops being treated as one.
+ */
+function settleArchive(host) {
+  host.archiveTimer = null;
+  const pending = host.pendingArchive;
+  host.pendingArchive = null;
+  if (!pending) return;
+  const repainted = host.resizeBytes > (host.cols * host.rows) / 4;
+  host.repaints = repainted;
+  if (!repainted && pending.length) archiveLines(host, pending);
 }
 
 /**
@@ -225,16 +286,28 @@ function applyGrid(host) {
   host.cols = cols;
   host.rows = rows;
   const carried = carryScreen(host, cols, rows);
+  // Viewers get the erase BEFORE they resize, in the same order the grid saw it,
+  // so their emulators skip the same reflow ours did.
+  if (carried) for (const sub of host.subs) sub.onData(carried.pre);
   try { host.vt.resize(cols, rows); } catch {}
   try { host.pty.resize(cols, rows); } catch {}
   host.resizedAt = Date.now();
   host.resizeBytes = 0;
-  let ansi = carried;
-  if (carried) { try { host.vt.feed(carried); } catch {} }
+  if (carried) {
+    // Oldest first: a second resize before the verdict lands adds to the same
+    // batch rather than replacing it.
+    host.pendingArchive = [...(host.pendingArchive || []), ...carried.dropped];
+    if (host.archiveTimer) clearTimeout(host.archiveTimer);
+    host.archiveTimer = setTimeout(() => settleArchive(host), ARCHIVE_SETTLE_MS);
+    if (host.archiveTimer.unref) host.archiveTimer.unref();
+  }
+  let ansi = carried ? carried.ansi : null;
+  if (carried) { try { host.vt.feed(carried.ansi); } catch {} }
   else { try { ansi = snapshotToAnsi(host.vt.snapshot({ includeCells: true })); } catch {} }
   for (const sub of host.subs) {
     // `carried` doubles as the flag: the viewer's own emulator has to skip its
-    // reflow exactly when we skipped ours, or it archives what we did not.
+    // reflow exactly when we skipped ours, or it archives what we did not — and it
+    // must not resize until the bytes above have been parsed at the OLD size.
     sub.onGrid(cols, rows, host.subs.size > 1, host.subs.size, !!carried);
     if (ansi) sub.onData(ansi);
   }
@@ -767,6 +840,8 @@ export function ensureRunning(session, cols = 120, rows = 34) {
     repaints: !isShell,
     resizedAt: 0,
     resizeBytes: 0,
+    pendingArchive: null,
+    archiveTimer: null,
     subs: new Set(),
     sizes: new Map(), // sub -> the grid that viewer can display
     pendingSizes: new Set(), // subs whose request hasn't been answered yet
@@ -786,13 +861,15 @@ export function ensureRunning(session, cols = 120, rows = 34) {
     // rewrapped copy reflow just archived was redundant. Latch that: the next
     // resize carries the screen across by hand instead (see carryScreen). This is
     // what catches `vim` or a hand-typed `claude` inside a shell session.
-    if (!host.repaints && host.resizedAt) {
-      if (Date.now() - host.resizedAt > 250) host.resizedAt = 0;
+    if (host.resizedAt) {
+      if (Date.now() - host.resizedAt > ARCHIVE_SETTLE_MS + 150) host.resizedAt = 0;
       else {
         host.resizeBytes += chunk.length;
         // A quarter screen of bytes is far more than a shell prompt redrawing
-        // itself and far less than a TUI frame.
-        if (host.resizeBytes > (host.cols * host.rows) / 4) { host.repaints = true; host.resizedAt = 0; }
+        // itself and far less than a TUI frame. For a session that reflowed
+        // plainly there is no verdict pending, so latch it here instead — this is
+        // what catches `vim` or a hand-typed `claude` in a shell pane.
+        if (!host.repaints && host.resizeBytes > (host.cols * host.rows) / 4) host.repaints = true;
       }
     }
 
@@ -816,6 +893,7 @@ export function ensureRunning(session, cols = 120, rows = 34) {
   term.onExit(() => {
     hosts.delete(session.id);
     if (host.gridTimer) { clearTimeout(host.gridTimer); host.gridTimer = null; }
+    if (host.archiveTimer) { clearTimeout(host.archiveTimer); host.archiveTimer = null; }
     try { vt.dispose(); } catch {}
     for (const sub of host.subs) sub.onExit();
     host.subs.clear();

server/src/snapshot.js

@@ -70,13 +70,69 @@ function sgrFor(cell) {
   return out;
 }
 
-export function snapshotToAnsi(snap) {
+/** Cells indexed by row, since snapshot() returns them as a flat sparse list. */
+function cellGrid(snap) {
   const grid = Array.from({ length: snap.rows }, () => new Array(snap.cols).fill(null));
   for (const cell of snap.cells || []) {
     if (cell.row >= 0 && cell.row < snap.rows && cell.col >= 0 && cell.col < snap.cols) {
       grid[cell.row][cell.col] = cell;
     }
   }
+  return grid;
+}
+
+/**
+ * One row as styled text, with no cursor positioning. Everything after the last
+ * drawn cell is dropped: trailing spaces are the bulk of a mostly-empty agent
+ * screen, and the caller has either just erased the line or is about to end it.
+ */
+function renderRow(cells, cols) {
+  let last = -1;
+  for (let col = cols - 1; col >= 0; col--) {
+    if (cells[col] && (cells[col].text !== ' ' || cells[col].background)) { last = col; break; }
+  }
+  if (last < 0) return '';
+
+  let out = '';
+  let style = '';
+  let col = 0;
+  while (col <= last) {
+    const cell = cells[col];
+    if (!cell) {
+      if (style) { out += '\x1b[0m'; style = ''; }
+      out += ' ';
+      col += 1;
+      continue;
+    }
+    const next = sgrFor(cell);
+    if (next !== style) {
+      out += '\x1b[0m' + next;
+      style = next;
+    }
+    out += cell.text;
+    col += Math.max(1, cell.width || 1);
+  }
+  if (style) out += '\x1b[0m';
+  return out;
+}
+
+/**
+ * Rows `from`..`to` as styled lines, ready to be PRINTED rather than placed —
+ * for putting rows into scrollback, where a line has to be written and scrolled
+ * off rather than positioned. Blank rows are kept as empty strings so the
+ * archived block keeps its shape.
+ */
+export function rowsToAnsi(snap, from, to) {
+  const grid = cellGrid(snap);
+  const out = [];
+  for (let row = Math.max(0, from); row < Math.min(snap.rows, to); row++) {
+    out.push(renderRow(grid[row], snap.cols));
+  }
+  return out;
+}
+
+export function snapshotToAnsi(snap) {
+  const grid = cellGrid(snap);
 
   // Normalise the buffer first: a byte replay can leave the receiver on the
   // alternate screen (or off it), and the repaint alone would then land on the
@@ -86,35 +142,8 @@ export function snapshotToAnsi(snap) {
   out += '\x1b[?25l\x1b[0m\x1b[H\x1b[2J';
 
   for (let row = 0; row < snap.rows; row++) {
-    const cells = grid[row];
-    // Everything after the last drawn cell is already blank from the erase, and
-    // trailing spaces are the bulk of a mostly-empty agent screen.
-    let last = -1;
-    for (let col = snap.cols - 1; col >= 0; col--) {
-      if (cells[col] && (cells[col].text !== ' ' || cells[col].background)) { last = col; break; }
-    }
-    if (last < 0) continue;
-
-    out += `\x1b[${row + 1};1H`;
-    let style = '';
-    let col = 0;
-    while (col <= last) {
-      const cell = cells[col];
-      if (!cell) {
-        if (style) { out += '\x1b[0m'; style = ''; }
-        out += ' ';
-        col += 1;
-        continue;
-      }
-      const next = sgrFor(cell);
-      if (next !== style) {
-        out += '\x1b[0m' + next;
-        style = next;
-      }
-      out += cell.text;
-      col += Math.max(1, cell.width || 1);
-    }
-    if (style) out += '\x1b[0m';
+    const line = renderRow(grid[row], snap.cols);
+    if (line) out += `\x1b[${row + 1};1H` + line;
   }
 
   out += `\x1b[0m\x1b[${snap.cursorRow + 1};${snap.cursorCol + 1}H`;

web/src/components/TerminalPane.tsx

@@ -415,13 +415,14 @@ export default function TerminalPane({
             // own geometry instead would garble the screen.
             else if (m.t === 'grid' || m.t === 'restore') {
               if (m.cols > 0 && m.rows > 0 && (term.cols !== m.cols || term.rows !== m.rows)) {
-                // m.clear: the backend cleared its screen before reflowing and a
-                // repaint is already on the wire, so clear ours too — xterm rewraps
-                // the outgoing screen into scrollback on resize (harder than the
-                // grid does: 119 lines against 80 over one drag), and that copy is
-                // the duplication. Resizing inside the write callback is what keeps
-                // it ordered against the repaint that follows.
-                if (m.clear) term.write('\x1b[H\x1b[2J', () => { try { term.resize(m.cols, m.rows); } catch { /* ignore */ } });
+                // m.clear: the backend already sent us the bytes that erase this
+                // screen and archive the rows about to fall off it, so skip our own
+                // reflow — xterm rewraps the outgoing screen into scrollback harder
+                // than the grid does (119 lines against 80 over one drag), and that
+                // copy is the duplication. The empty write is a barrier: writes are
+                // asynchronous, so resizing outside its callback would apply the new
+                // size to bytes that were written for the old one.
+                if (m.clear) term.write('', () => { try { term.resize(m.cols, m.rows); } catch { /* ignore */ } });
                 else try { term.resize(m.cols, m.rows); } catch { /* ignore */ }
               }
               setViewers(m.viewers > 1 ? m.viewers : 0);