perf(terminal): tab switch to a pane with no scrollback loads only its screen

After a session's first load per page, a tab switch fetched a 1 MiB tail of
the server's byte stream. For a fullscreen claude pane (alternate screen,
tmux `history_size` 0) that tail is old repaints of one frame, and an idle
tab parsed it twice (the cached copy, then the fresh one).

Every terminal response now records `paneHistoryLines` per session, and
`selectSession` takes `full=1` whenever the last report was 0. For such a
pane that capture is the visible frame, a few KB, which is also what a page
load already shows. A response without the field forgets the entry, so
unknown never counts as empty; a pane that starts keeping history goes back
to the tail on the next switch. Shells and the refresh path are unchanged.

Measured with real prod payloads through the real client in chromium:
median switch 1.26-1.66 s -> 0.10-0.19 s, parse ~1.1-1.5 s -> 2-3 ms.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

.changeset/fullscreen-tab-switch.md

@@ -0,0 +1,5 @@
+---
+'aicodeman': patch
+---
+
+Switching to a fullscreen Claude tab is about ten times faster. Claude keeps that conversation itself and tmux holds no scrollback for it, so instead of downloading and replaying a 1 MB tail of old screen redraws on every switch, the browser loads just the current screen (a few KB), the same as a page load already did. Tabs whose pane does keep scrollback are unchanged.

config/test-suites.ts

@@ -45,6 +45,7 @@ export const BROWSER_TEST_GLOBS = [
   'test/spreadsheet-preview.browser.test.ts',
   'test/mobile-ime-preview.browser.test.ts',
   'test/run-mode-menu-scroll.browser.test.ts',
+  'test/fullscreen-tab-switch-capture.browser.test.ts',
 ];
 
 /**

docs/architecture-invariants.md

@@ -213,6 +213,8 @@ Further detail: the `<prefix>: <title>` form (`w3-myapp: fix the login redirect`
 
 **The partial-history notice is lazy and pane-gated** (`computeHistoryTruncationNotice()` in constants.js, `_renderHistoryTruncationBanner()` / `_setHistoryNoticeRevealed()` in app.js). `truncated` on a terminal response measures the server's BYTE stream, which is not what `full=1` can return: for a pane with no tmux scrollback (fullscreen claude starts in the alternate screen and never writes to the main grid, so `#{history_size}` is 0) the bytes a tail cut drops are old repaint frames. Measured on prod 2026-10-10, every claude pane: the tab-switch tail cut a 1.2 to 6.2 MB stream to 1 MiB, the local scrollback that tail replays into is repeats of the same frames (one pane: 450 non-blank rows, 44 unique, one row 33 times), and `full=1` returned 1 to 5 KB, so **Load full history** could only end in the downgrade refusal while the banner promised "4.8 MB more". The capture therefore reads `#{history_size}` in the SAME `display-message` as the cursor (no extra tmux call), the route returns it as `paneHistoryLines` (absent when the body is not a capture), and a reported 0 hides the notice in every state; a positive count replaces the byte gap in the message. ⚠️ Key the decision on `history_size`, never on `alternate_on`: a shell running `less` is in the alternate screen with its whole history still retained (measured, 99,972 rows) and `full=1` returns all of it. The notice is also LAZY: it appears only after a wheel/touch gesture reaches the top of the browser buffer and the pull that gesture started has settled (`_maybeLoadMoreHistoryOnScroll`), goes away when a downward gesture is back at live output or the tab switches (`selectSession` nulls `_historyNoticeRevealedFor` before repainting), and its × is sticky per session until reload (`_historyNoticeDismissed`). Tests: `test/history-truncation-notice.test.ts`, `test/history-notice-reveal.test.ts`.
 
+**A tab switch to a pane with no tmux scrollback takes `full=1`, not the 1 MiB tail** (`_paneHistoryLines` + `_notePaneHistory()` in app.js). Every terminal response (select, refresh, re-pull) records `paneHistoryLines` per session, and `selectSession` serves a non-shell switch from `full=1` whenever the last report was 0. For such a pane that capture IS the visible frame (0.9 to 5.6 KB on prod) and matches what a page load shows, while the tail was 1 MiB of old repaints. Measured 2026-10-10 with real prod payloads through the real client in chromium: median switch 1.26 to 1.66 s down to 0.10 to 0.19 s, parse ~1.1 to 1.5 s down to 2 to 3 ms; server time 136 to 1070 ms (tail) vs 89 to 330 ms (full). An empty local buffer is also what lets `_maybePageCliTranscript` send a gesture to the CLI's own transcript. ⚠️ Only a reported 0 counts: a response without the field FORGETS the entry (unknown is never empty), so an older server or a byte-history fallback keeps the tail; a pane that starts keeping history (claude switched to its inline view) is learned from the next response and goes back to the tail. ⚠️ Shells never take this path. ⚠️ The refresh path (`_onSessionNeedsRefresh`) keeps its downgrade guard unchanged: a server-triggered refresh must not wipe local rows the user may be reading. Tests: `test/pane-history-memory.test.ts`, `test/fullscreen-tab-switch-capture.browser.test.ts` (browser suite).
+
 **A capture reports the geometry it was taken at** (#435): a visible frame repaints each row at an absolute position, counting up to the pane's height and out to the pane's width, so a terminal smaller than that pane damages it two ways at once. Too short and every address past the browser's own height clamps onto the last line, overwriting the rows underneath (measured: against a 50-row pane, a 30-row terminal rendered 28 of a 45-line command and drew the survivors twice). Too narrow and each row is painted out to the pane's width, so the browser wraps every painted row and the wrap on the last one scrolls the whole frame up by one. Nothing in the response used to say what geometry the frame was built for, so the client could not see either case. `PaneCaptureOptions.capturedGeometry` carries it out, and the terminal response publishes it as `captureCols`/`captureRows`. ⚠️ **Both fields are ABSENT unless a frame was really positioned**, and every consumer must test `Number.isFinite` rather than truthiness: `mux-visible` is necessary but not sufficient, because when the `display-message` cursor query fails `capturePaneBuffer` skips the snapshot repaint and returns the raw capture, and the route still labels that non-empty body `mux-visible`. A body that positioned nothing has no geometry to describe and nothing to repair, so a comparison that fires there buys a second capture, a reset plus chunked rewrite, a dropped and reopened WebSocket and a discarded xterm snapshot for no gain. ⚠️ **The comparison runs on `mux-visible` ONLY.** A full-history body is linear scrollback closed by a RELATIVE cursor move, which is relative precisely so the browser's row count need not match the pane's, and a byte-history body carries no row alignment at all, so a size mismatch damages neither and a replay repairs neither. That gate matters because the first select of every non-shell session per page takes the full-history path, where an ungated comparison would fire most often on the one response it cannot help, at the price of a second whole-scrollback capture. ⚠️ **The replay is capped at one attempt and latches per session when it cannot converge.** `resizeRetry` stops two competing fits trading replays forever; a pane already drawing at the size just requested is left alone, because a retry would capture the identical frame; and a pass that still does not converge joins `_geometryRetryUseless`, so the case `Session.resize` declines outright (a small viewport while a desktop viewport's size claim is live, where the retry re-sends the same declined resize and captures the same pane) costs one attempt per session per page load instead of one per select. ⚠️ **The clamp used to manufacture that equality, and no longer can** (#464). This paragraph previously explained it as the signature of a clamp: `getTerminalDimensions()` floors at 40x10 while `fitAddon.fit()` did not, so a terminal under 40 columns or 10 rows reported a pane permanently bigger than itself and would replay on every tab switch. That divergence is fixed at the source — `syncTerminalGeometry()` (terminal-ui.js) fits, floors and APPLIES in one step, so the browser terminal IS the size it reports. The only remaining reason the two can differ is a resize the server declined, which the server now reports back (`Session.ptyGeometry`, the `{"t":"zc"}` frame and the resize response) for the client to adopt by COLUMNS. The equality guard stays, for the plain case of a pane already at the requested size. ⚠️ **A retry pass must not re-arm `_fullHistoryLoaded`**: it did not consume the full-history pull, and re-arming it would spend a whole-scrollback capture on the next select. That branch is currently unreachable by construction, since reaching it needs `source === 'mux-visible'` while a `full=1` pass is answered `mux-full-history` or `history`; a static test over the source is the habit this repo uses for an invariant nothing can execute. Tests: `test/capture-geometry-retry.browser.test.ts` (eight cases, five of which fail against the merge base), `test/tmux-capture-full-history.test.ts`, `test/routes/session-routes.test.ts`.
 
 ⚠️ **A frame dropped at the 128 KiB render cap MUST be recovered, and the recovery must verify itself** (`_scheduleDroppedOutputRecovery`, app.js): a hole in a TUI byte stream is a desynced cursor, which is muffled text (#464). It was a fire-and-forget 2s timer that nulled its own handle and then called `_onSessionNeedsRefresh()` — whose early returns (a buffer load in flight, a refresh already owning the session) are MOST likely to be true during exactly the burst that caused the drop, so the recovery was lost silently and the bytes were never replayed. `_onSessionNeedsRefresh` now returns whether it actually repainted, and the scheduler re-arms while it has not, bounded by `DROP_RECOVERY_MAX_ATTEMPTS` because the early returns it retries past are transient contention. A refresh that died at the capture fetch DEADLINE (it returns `'deadline'`) is a stalled link, not contention, and is NOT retried: each retry would be another `?full=1` capture waiting out a deadline of up to two minutes. The same debounce still collapses a burst into one attempt, and the `TERMINAL DROP` crash-trail line sits behind it, since one line per dropped frame evicted the whole 50-entry trail in under a second. Tests: `test/dropped-output-recovery.test.ts`, whose retry case and no-retry case only pin the fix as a pair.

docs/wiki/The-Dashboard.md

@@ -210,6 +210,8 @@ TUIs render correctly.
 Worth knowing:
 
 - **Scrollback.** Agent/TUI sessions pull their entire tmux scrollback on first open.
+  A fullscreen Claude tab keeps its history inside Claude, so switching back to it
+  reloads only the current screen, which keeps tab switches fast.
   Shell sessions open from a bounded recent tail so a large transcript cannot stall tab
   switching. Scrolling to the top of a Shell pane pulls the most recent 1 MiB of its tmux
   history; press **Load full history** to pull the rest explicitly. That notice only

src/web/public/app.js

@@ -767,6 +767,12 @@ class CodemanApp {
     // their scrollback can be very large; full history stays available on demand.
     // Tracked PER SESSION rather than as a single "first load" flag (issue #205).
     this._fullHistoryLoaded = new Set();
+    // Rows of scrollback tmux reported above the visible frame on this session's
+    // last capture (`paneHistoryLines`). 0 marks a pane with no history to load
+    // (a fullscreen CLI in the alternate screen), which a tab switch serves from
+    // the small `full=1` capture instead of the 1 MiB byte tail: see
+    // _notePaneHistory and selectSession.
+    this._paneHistoryLines = new Map(); // Map<sessionId, number>
     // Cooldown per session for the scroll-to-top "load more history" re-pull.
     this._fullHistoryRepullAt = new Map(); // Map<sessionId, timestamp>
     this._fullHistoryRepullInFlight = false;
@@ -3193,6 +3199,7 @@ class CodemanApp {
         headersReceivedAt = capture.headersAt;
         data = capture.json?.data ?? {};
       }
+      this._notePaneHistory?.(sessionId, data);
       // Bail on a tab switch mid-fetch: writing here would paint this session's
       // history into the terminal the user is now looking at. The window is two
       // fetches wide in the fallback case, so this guard is not optional.
@@ -8552,6 +8559,7 @@ class CodemanApp {
       const headersReceivedAt = capture.headersAt;
       const payload = capture.json?.data ?? {};
       const bodyParsedAt = performance.now();
+      this._notePaneHistory?.(sessionId, payload);
       const buffer = payload.terminalBuffer;
       const timing = {
         trigger: force ? 'full-history-button' : 'full-history-scroll',
@@ -8700,9 +8708,27 @@ class CodemanApp {
   _clearHistoryTruncation(sessionId) {
     this._historyTruncation?.delete(sessionId);
     this._historyNoticeDismissed?.delete(sessionId);
+    this._paneHistoryLines?.delete(sessionId);
     if (sessionId === this.activeSessionId) this._renderHistoryTruncationBanner();
   }
 
+  /**
+   * Remember how much scrollback tmux holds for a session's pane, from any
+   * terminal response. Called whether or not the response was written, since
+   * it describes the PANE, not the payload. A response without the field (a
+   * byte-history fallback, an older server) forgets it, so the next tab switch
+   * goes back to the bounded tail: unknown never counts as empty.
+   */
+  _notePaneHistory(sessionId, payload) {
+    if (!sessionId) return;
+    const lines = payload?.paneHistoryLines;
+    if (typeof lines === 'number' && Number.isFinite(lines) && lines >= 0) {
+      (this._paneHistoryLines ||= new Map()).set(sessionId, lines);
+    } else {
+      this._paneHistoryLines?.delete(sessionId);
+    }
+  }
+
   /**
    * Bring the partial-history notice up for `sessionId`, or retire it (null).
    *
@@ -9166,7 +9192,23 @@ class CodemanApp {
       // automatically replaying all of them makes tab selection scale with the
       // entire session. Load its bounded 1MB tail first; the existing truncation
       // banner action fetches ?full=1 when the user explicitly asks for it.
-      const useFullHistory = session?.mode !== 'shell' && !this._fullHistoryLoaded.has(sessionId);
+      //
+      // A TUI pane whose last capture reported NO tmux scrollback (fullscreen
+      // claude: it lives in the alternate screen and keeps its transcript itself)
+      // takes `full=1` on every switch, not only the first. For such a pane that
+      // capture IS the visible frame, a few KB, while the tail is 1 MiB of the
+      // byte stream's old repaints. Measured on 11 live fullscreen claude panes:
+      // the tail took 250-1070 ms on the server and 70-510 ms to parse, and
+      // rendered one frame repeated (450 rows, 44 distinct); `full=1` took
+      // 150-330 ms and returned 0.9-5.6 KB. It also matches what a page load
+      // already shows, and an empty local buffer is what lets
+      // _maybePageCliTranscript send a wheel to the CLI's own transcript. The
+      // response re-reports the count, so a pane that starts keeping history
+      // (claude switched to its inline view) goes back to the tail on the next
+      // switch.
+      const paneKeepsNoHistory = this._paneHistoryLines?.get(sessionId) === 0;
+      const useFullHistory =
+        session?.mode !== 'shell' && (paneKeepsNoHistory || !this._fullHistoryLoaded.has(sessionId));
       if (useFullHistory) this._fullHistoryLoaded.add(sessionId);
       const fetchStartedAt = performance.now();
       const tailUrl = `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`;
@@ -9196,6 +9238,7 @@ class CodemanApp {
       }
       const data = capture.json?.data ?? {};
       const bodyParsedAt = performance.now();
+      this._notePaneHistory?.(sessionId, data);
       // How this load must end, decided here because `chunkedTerminalWrite` is
       // what actually ends it for a non-empty buffer. A tmux pane capture is a
       // point-in-time frame, so nothing that reached the browser after the

test/fullscreen-tab-switch-capture.browser.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview A tab switch to a pane with no tmux scrollback takes the small capture.
+ *
+ * After the first select of a page, a tab switch to a non-shell session used to
+ * fetch a 1 MiB tail of the server's byte stream. For a fullscreen claude pane
+ * (alternate screen, `#{history_size}` 0) that tail is old repaints of one frame:
+ * measured on live panes it cost 250-1070 ms on the server and 70-510 ms to
+ * parse, and an idle tab parsed it twice (the cached copy, then the fresh one,
+ * which never matched). The `full=1` capture of such a pane is the visible
+ * frame, a few KB, so `selectSession` now takes it whenever the session's last
+ * capture reported `paneHistoryLines: 0`, and goes back to the tail as soon as a
+ * capture reports scrollback again.
+ *
+ * Drives the real client in chromium against a testMode server, with the
+ * terminal route stubbed (the real one needs live tmux to report a hollow pane).
+ *
+ * Port: ephemeral (`new WebServer(0, …)`, read back through `boundPort`)
+ *
+ * Run: npm run test:browser -- test/fullscreen-tab-switch-capture.browser.test.ts
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { chromium, type Browser, type Page } from 'playwright';
+import { WebServer } from '../src/web/server.js';
+
+let server: WebServer;
+let browser: Browser;
+
+beforeAll(async () => {
+  server = new WebServer(0, false, true); // testMode
+  await server.start();
+  browser = await chromium.launch({ headless: true });
+}, 60_000);
+
+afterAll(async () => {
+  await browser?.close();
+  await server?.stop();
+}, 30_000);
+
+/** What each session's pane reports, set by the test as the "pane" changes. */
+type PaneHistory = Record<string, number | undefined>;
+
+/**
+ * Serve every terminal fetch from a stub and log which shape was asked for.
+ * `source` follows the real route: `full=1` answers `mux-full-history`, anything
+ * else `mux-visible`. No capture geometry, so the geometry retry stays out of it.
+ */
+async function stubTerminal(page: Page, history: PaneHistory, log: string[]) {
+  await page.route('**/api/sessions/*/terminal*', async (route) => {
+    const url = new URL(route.request().url());
+    const id = url.pathname.split('/')[3];
+    const full = url.searchParams.get('full') === '1';
+    log.push(`${id}:${full ? 'full' : 'tail'}`);
+    const frame = `frame of ${id}\r\n`;
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        success: true,
+        data: {
+          terminalBuffer: full ? frame : `${'old repaint\r\n'.repeat(50)}${frame}`,
+          status: 'idle',
+          fullSize: full ? frame.length : 5 * 1024 * 1024,
+          retainedBytes: full ? frame.length : 1024 * 1024,
+          truncated: !full,
+          truncationReason: full ? null : 'tail',
+          source: full ? 'mux-full-history' : 'mux-visible',
+          paneHistoryLines: history[id],
+        },
+      }),
+    });
+  });
+}
+
+async function openApp(page: Page): Promise<void> {
+  await page.goto(`http://localhost:${server.boundPort}`, { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => document.body.classList.contains('app-loaded'), { timeout: 10_000 });
+  await page.waitForFunction(() => (window as unknown as { app?: { terminal?: unknown } }).app?.terminal, null, {
+    timeout: 30_000,
+  });
+}
+
+async function createSession(page: Page, name: string): Promise<string> {
+  return page.evaluate(async (n) => {
+    const res = await fetch('/api/sessions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workingDir: '/tmp', name: n }),
+    });
+    const body = await res.json();
+    return body.data?.session?.id ?? body.data?.id ?? body.id;
+  }, name);
+}
+
+async function select(page: Page, sessionId: string): Promise<void> {
+  await page.evaluate(async (sid) => {
+    const app = (window as unknown as { app: { selectSession: (id: string) => Promise<void> } }).app;
+    await app.selectSession(sid);
+  }, sessionId);
+}
+
+async function deleteSession(page: Page, sessionId: string): Promise<void> {
+  await page.evaluate(
+    (sid: string) => fetch(`/api/sessions/${sid}`, { method: 'DELETE' }).then(() => undefined),
+    sessionId
+  );
+}
+
+describe('tab switch to a pane that keeps no scrollback', () => {
+  it('takes the small full capture on every switch, and the tail again once the pane keeps history', async () => {
+    const context = await browser.newContext({ viewport: { width: 1280, height: 800 }, deviceScaleFactor: 1 });
+    const page = await context.newPage();
+    await openApp(page);
+    const hollow = await createSession(page, 'fullscreen-claude');
+    const inline = await createSession(page, 'inline-claude');
+    const history: PaneHistory = { [hollow]: 0, [inline]: 40_000 };
+    const log: string[] = [];
+    await stubTerminal(page, history, log);
+
+    // First select of each on this page: the canonical full replay, as before.
+    await select(page, hollow);
+    await select(page, inline);
+    expect(log).toEqual([`${hollow}:full`, `${inline}:full`]);
+
+    // Switching back: the hollow pane takes the frame, the inline one the tail.
+    log.length = 0;
+    await select(page, hollow);
+    await select(page, inline);
+    await select(page, hollow);
+    expect(log).toEqual([`${hollow}:full`, `${inline}:tail`, `${hollow}:full`]);
+
+    // The pane starts keeping history (claude switched to its inline view). The
+    // switch that learns it is still a full capture, which is the canonical
+    // load anyway; the one after goes back to the bounded tail.
+    history[hollow] = 1200;
+    log.length = 0;
+    await select(page, inline);
+    await select(page, hollow);
+    await select(page, inline);
+    await select(page, hollow);
+    expect(log).toEqual([`${inline}:tail`, `${hollow}:full`, `${inline}:tail`, `${hollow}:tail`]);
+
+    // Unknown is never treated as empty: a response without the field (an
+    // older server, a byte-history fallback) keeps the tail.
+    history[hollow] = 0;
+    log.length = 0;
+    await select(page, inline);
+    await select(page, hollow); // learns 0 from this tail response
+    history[hollow] = undefined;
+    await select(page, inline);
+    await select(page, hollow); // last report was 0: frame, which reports nothing
+    await select(page, inline);
+    await select(page, hollow); // forgot it: tail
+    expect(log).toEqual([
+      `${inline}:tail`,
+      `${hollow}:tail`,
+      `${inline}:tail`,
+      `${hollow}:full`,
+      `${inline}:tail`,
+      `${hollow}:tail`,
+    ]);
+
+    // What the hollow switch actually paints: the frame, without the repaints.
+    history[hollow] = 0;
+    await select(page, inline);
+    await select(page, hollow); // learns 0
+    await select(page, inline);
+    await select(page, hollow);
+    const screen = await page.evaluate(() => {
+      const t = (window as unknown as { app: { terminal: any } }).app.terminal;
+      const lines: string[] = [];
+      for (let i = 0; i < t.buffer.active.length; i++) lines.push(t.buffer.active.getLine(i)?.translateToString(true));
+      return lines.join('\n');
+    });
+    expect(screen).toContain(`frame of ${hollow}`);
+    expect(screen).not.toContain('old repaint');
+
+    await deleteSession(page, hollow);
+    await deleteSession(page, inline);
+    await context.close();
+  }, 90_000);
+});

test/history-truncation-notice.test.ts

@@ -188,7 +188,13 @@ describe('the in-terminal truncation line is gone (static guard)', () => {
 
   it('loads a bounded shell tail first and keeps unbounded full history user-triggered', () => {
     const app = readFileSync(resolve(PUBLIC, 'app.js'), 'utf8');
-    expect(app).toContain("session?.mode !== 'shell' && !this._fullHistoryLoaded.has(sessionId)");
+    // A shell never takes the full capture on a tab switch. A TUI takes it on its
+    // first select per page, and on every select while its pane keeps no tmux
+    // scrollback (behaviour pinned in fullscreen-tab-switch-capture.browser.test.ts).
+    expect(app).toContain(
+      "session?.mode !== 'shell' && (paneKeepsNoHistory || !this._fullHistoryLoaded.has(sessionId))"
+    );
+    expect(app).toContain('const paneKeepsNoHistory = this._paneHistoryLines?.get(sessionId) === 0;');
     expect(app).toContain("!restoredSnapshot && session?.mode !== 'shell'");
     expect(app).toContain('`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`');
     // Every terminal capture now goes through _fetchTerminalCapture, which adds

test/pane-history-memory.test.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview What the client remembers about a pane's tmux scrollback.
+ *
+ * `selectSession` serves a tab switch from the small `full=1` capture when the
+ * session's last terminal response reported `paneHistoryLines: 0` (a fullscreen
+ * CLI in the alternate screen), instead of the 1 MiB byte tail. The memory that
+ * decides it must treat ONLY a reported 0 as empty: a missing field (an older
+ * server, a byte-history fallback) has to forget, so the tab switch goes back to
+ * the bounded tail rather than trusting a stale answer.
+ *
+ * Runs the real `_notePaneHistory` / `_clearHistoryTruncation` from app.js in a
+ * `vm`. The switch itself is driven end to end in
+ * fullscreen-tab-switch-capture.browser.test.ts (browser suite).
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it } from 'vitest';
+
+const APP = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+
+function methodSource(source: string, method: string): string {
+  const start = source.search(new RegExp(`^ {2}(?:async )?${method}\\(`, 'm'));
+  expect(start, `${method} not found`).toBeGreaterThan(-1);
+  const next = /^ {2}(?:async )?[A-Za-z_$][\w$]*\(/m.exec(source.slice(start + 1));
+  return next ? source.slice(start, start + 1 + next.index) : source.slice(start);
+}
+
+function makeApp() {
+  const methods = vm.runInContext(
+    `({ ${methodSource(APP, '_notePaneHistory')}, ${methodSource(APP, '_clearHistoryTruncation')} })`,
+    vm.createContext({})
+  ) as Record<string, (...args: unknown[]) => void>;
+  return {
+    activeSessionId: null,
+    _paneHistoryLines: new Map<string, number>(),
+    _renderHistoryTruncationBanner() {},
+    ...methods,
+  } as Record<string, any>;
+}
+
+describe('_notePaneHistory', () => {
+  it('records the count a capture reported, 0 included', () => {
+    const app = makeApp();
+    app._notePaneHistory('s1', { paneHistoryLines: 0 });
+    app._notePaneHistory('s2', { paneHistoryLines: 40000 });
+    expect(app._paneHistoryLines.get('s1')).toBe(0);
+    expect(app._paneHistoryLines.get('s2')).toBe(40000);
+  });
+
+  it('forgets on a response without a usable count, so unknown never reads as empty', () => {
+    const app = makeApp();
+    for (const payload of [{}, { paneHistoryLines: null }, { paneHistoryLines: NaN }, { paneHistoryLines: -1 }, null]) {
+      app._notePaneHistory('s1', { paneHistoryLines: 0 });
+      app._notePaneHistory('s1', payload);
+      expect(app._paneHistoryLines.has('s1')).toBe(false);
+    }
+  });
+
+  it('ignores a call without a session', () => {
+    const app = makeApp();
+    app._notePaneHistory(null, { paneHistoryLines: 0 });
+    expect(app._paneHistoryLines.size).toBe(0);
+  });
+
+  it('is dropped with the session', () => {
+    const app = makeApp();
+    app._notePaneHistory('s1', { paneHistoryLines: 0 });
+    app._clearHistoryTruncation('s1');
+    expect(app._paneHistoryLines.has('s1')).toBe(false);
+  });
+});
+
+describe('every terminal response feeds it (static guard)', () => {
+  it('the tab switch, the refresh and the history re-pull all record the pane', () => {
+    expect(methodSource(APP, 'selectSession')).toContain('this._notePaneHistory?.(sessionId, data);');
+    expect(methodSource(APP, '_onSessionNeedsRefresh')).toContain('this._notePaneHistory?.(sessionId, data);');
+    expect(methodSource(APP, '_maybeRefetchFullHistory')).toContain('this._notePaneHistory?.(sessionId, payload);');
+  });
+});