Make mobile terminals load faster (#1147)

* Speed up terminal restores on mobile * Preserve terminal output bytes in the app
2026-05-23 18:41:10 +08:00
parent 84f1dfc8cb
commit 846c9b9da3
32 changed files with 1304 additions and 357 deletions
@@ -67,6 +67,7 @@ import type {
  ListTerminalsResponse,
  CreateTerminalResponse,
  SubscribeTerminalResponse,
+  SubscribeTerminalRequest,
  CloseItemsResponse,
  KillTerminalResponse,
  CaptureTerminalResponse,
@@ -3770,13 +3771,19 @@ export class DaemonClient {

  async subscribeTerminal(
    terminalId: string,
-    requestId?: string,
+    optionsOrRequestId?:
+      | { restore?: SubscribeTerminalRequest["restore"]; requestId?: string }
+      | string,
  ): Promise<SubscribeTerminalPayload> {
+    const restore = typeof optionsOrRequestId === "object" ? optionsOrRequestId.restore : undefined;
+    const requestId =
+      typeof optionsOrRequestId === "object" ? optionsOrRequestId.requestId : optionsOrRequestId;
    const resolvedRequestId = this.createRequestId(requestId);
    const message = SessionInboundMessageSchema.parse({
      type: "subscribe_terminal_request",
      terminalId,
      requestId: resolvedRequestId,
+      ...(restore ? { restore } : {}),
    });
    const payload = await this.sendCorrelatedRequest({
      requestId: resolvedRequestId,
@@ -4363,6 +4370,8 @@ export class DaemonClient {
      frameKind = "output";
    } else if (frame.opcode === TerminalStreamOpcode.Snapshot) {
      frameKind = "snapshot";
+    } else if (frame.opcode === TerminalStreamOpcode.Restore) {
+      frameKind = "output";
    }
    this.runtimeMetrics?.recordBinaryFrame(
      frameKind,
@@ -0,0 +1,28 @@
+import { describe, expect, test } from "vitest";
+
+import { TerminalStreamOpcode } from "../shared/binary-frames/index.js";
+import { TerminalStreamRouter, type TerminalStreamEvent } from "./terminal-stream-router.js";
+
+describe("terminal-stream-router", () => {
+  test("routes restore frames as restore events", () => {
+    const router = new TerminalStreamRouter();
+    const events: TerminalStreamEvent[] = [];
+    const payload = new TextEncoder().encode("restored screen");
+
+    router.setSlot("term-1", 7);
+    router.onEvent((event) => events.push(event));
+    router.handleFrame({
+      opcode: TerminalStreamOpcode.Restore,
+      slot: 7,
+      payload,
+    });
+
+    expect(events).toEqual([
+      {
+        terminalId: "term-1",
+        type: "restore",
+        data: payload,
+      },
+    ]);
+  });
+});
@@ -9,7 +9,8 @@ import type { TerminalInput, TerminalState } from "../shared/messages.js";

 export type TerminalStreamEvent =
  | { terminalId: string; type: "output"; data: Uint8Array }
-  | { terminalId: string; type: "snapshot"; state: TerminalState };
+  | { terminalId: string; type: "snapshot"; state: TerminalState }
+  | { terminalId: string; type: "restore"; data: Uint8Array };

 export class TerminalStreamRouter {
  private readonly terminalSlots = new Map<string, number>();
@@ -97,6 +98,15 @@ export class TerminalStreamRouter {
      return;
    }

+    if (frame.opcode === TerminalStreamOpcode.Restore) {
+      this.emit({
+        terminalId,
+        type: "restore",
+        data: frame.payload,
+      });
+      return;
+    }
+
    if (frame.opcode === TerminalStreamOpcode.Snapshot) {
      const state = decodeTerminalSnapshotPayload(frame.payload);
      if (!state) {
@@ -650,6 +650,7 @@ test("receives server_info on websocket connect", async () => {
  const serverInfo = client.getLastServerInfoMessage();
  expect(serverInfo).not.toBeNull();
  expect(serverInfo?.serverId.length).toBeGreaterThan(0);
+  expect(serverInfo?.features?.["terminal-restore-modes"]).toBe(true);

  await client.close();
 }, 15000);
@@ -46,13 +46,13 @@ function extractStateText(state: Pick<TerminalState, "grid" | "scrollback">): st
 }

 async function waitForCondition(
-  predicate: () => boolean,
+  predicate: () => boolean | Promise<boolean>,
  timeoutMs: number,
  intervalMs = 25,
 ): Promise<void> {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
-    if (predicate()) {
+    if (await predicate()) {
      return;
    }
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
@@ -377,6 +377,9 @@ function getFrameText(frame: TerminalStreamFrame): string {
    }
    return extractStateText(state);
  }
+  if (frame.opcode === TerminalStreamOpcode.Restore) {
+    return new TextDecoder().decode(frame.payload);
+  }
  return "";
 }

@@ -672,6 +675,11 @@ async function subscribeRawTerminal(
  ws: WebSocket,
  terminalId: string,
  requestId: string,
+  restore?: {
+    mode: "live" | "visible-snapshot" | "full-snapshot";
+    scrollbackLines?: number;
+    size?: { rows: number; cols: number };
+  },
 ): Promise<number> {
  const ready = waitForRawSessionMessage(
    ws,
@@ -688,6 +696,7 @@ async function subscribeRawTerminal(
        type: "subscribe_terminal_request",
        terminalId,
        requestId,
+        ...(restore ? { restore } : {}),
      },
    }),
  );
@@ -753,6 +762,95 @@ test("client connects and receives a snapshot of the current terminal state", as
  rmSync(cwd, { recursive: true, force: true });
 }, 30000);

+test("live terminal restore skips the initial snapshot", async () => {
+  const cwd = tmpCwd();
+  const created = await ctx.client.createTerminal(cwd);
+  const terminalId = created.terminal!.id;
+  const ws = await connectRawWebSocket(ctx.daemon.port);
+
+  try {
+    ctx.client.sendTerminalInput(terminalId, {
+      type: "input",
+      data: "printf 'before-live\\n'\r",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    const slot = await subscribeRawTerminal(ws, terminalId, "subscribe-live", { mode: "live" });
+    const outputFramesPromise = collectRawBinaryFrames(
+      ws,
+      (frames) => frames.some((frame) => getFrameText(frame).includes("after-live")),
+      10000,
+    );
+    ws.send(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Input,
+        slot,
+        payload: "printf 'after-live\\n'\r",
+      }),
+    );
+    const outputFrames = await outputFramesPromise;
+    const outputText = outputFrames.map((frame) => getFrameText(frame)).join("");
+
+    expect(outputText).toContain("after-live");
+    expect(outputText).not.toContain("before-live");
+    expect(
+      outputFrames.some(
+        (frame) =>
+          frame.opcode === TerminalStreamOpcode.Snapshot ||
+          frame.opcode === TerminalStreamOpcode.Restore,
+      ),
+    ).toBe(false);
+  } finally {
+    await closeWebSocket(ws);
+  }
+
+  rmSync(cwd, { recursive: true, force: true });
+}, 30000);
+
+test("visible terminal restore sends bounded ANSI history", async () => {
+  const cwd = tmpCwd();
+  const created = await ctx.client.createTerminal(cwd, undefined, undefined, {
+    command: "/bin/sh",
+    args: [
+      "-lc",
+      "i=1; while [ $i -le 1200 ]; do printf 'restore-line-%04d\\n' $i; i=$((i+1)); done; sleep 30",
+    ],
+  });
+  const terminalId = created.terminal!.id;
+  const ws = await connectRawWebSocket(ctx.daemon.port);
+
+  try {
+    await waitForCondition(async () => {
+      const capture = await ctx.client.captureTerminal(terminalId);
+      return capture.lines.join("\n").includes("restore-line-1200");
+    }, 10000);
+
+    const restoreFramePromise = waitForRawBinaryFrame(
+      ws,
+      (frame) => frame.opcode === TerminalStreamOpcode.Restore,
+      10000,
+    );
+    await subscribeRawTerminal(ws, terminalId, "subscribe-visible", {
+      mode: "visible-snapshot",
+      scrollbackLines: 5,
+      size: { rows: 10, cols: 80 },
+    });
+    const restoreFrame = await restoreFramePromise;
+    const restoreText = getFrameText(restoreFrame);
+    const restoredLines = restoreText.match(/restore-line-\d{4}/g) ?? [];
+
+    expect(restoredLines[0]).toBe("restore-line-1187");
+    expect(restoredLines.at(-1)).toBe("restore-line-1200");
+    expect(restoreText).not.toContain("restore-line-1186");
+    expect(restoreText).not.toContain("restore-line-0001");
+    expect(restoredLines.length).toBeLessThanOrEqual(15);
+  } finally {
+    await closeWebSocket(ws);
+  }
+
+  rmSync(cwd, { recursive: true, force: true });
+}, 30000);
+
 test("propagates debounced terminal titles through list responses and snapshots", async () => {
  const cwd = tmpCwd();
  const created = await ctx.client.createTerminal(cwd, undefined, undefined, {
@@ -1066,13 +1164,13 @@ test("fast output to a slow websocket client falls back to a snapshot", async ()
  });

  await new Promise((resolve) => setTimeout(resolve, 750));
-  rawSocket!.resume();
-
-  const catchUpFrame = await waitForRawBinaryFrame(
+  const catchUpFramePromise = waitForRawBinaryFrame(
    ws,
    (frame) => frame.opcode === TerminalStreamOpcode.Snapshot,
    15000,
  );
+  rawSocket!.resume();
+  const catchUpFrame = await catchUpFramePromise;
  expect(catchUpFrame.opcode).toBe(TerminalStreamOpcode.Snapshot);

  await closeWebSocket(ws);
@@ -1081,6 +1081,8 @@ export class VoiceAssistantWebSocketServer {
        checkoutGithubSetAutoMerge: true,
        // COMPAT(daemonStatusRpc): added in v0.1.76, remove gate after 2026-11-18.
        daemonStatusRpc: true,
+        // COMPAT(terminalRestoreModes): added in v0.1.81, remove gate after 2026-11-23.
+        "terminal-restore-modes": true,
      },
    };
  }
@@ -13,6 +13,7 @@ export const TerminalStreamOpcode = {
  Input: 0x02,
  Resize: 0x03,
  Snapshot: 0x04,
+  Restore: 0x05,
 } as const;

 export type TerminalStreamOpcode = (typeof TerminalStreamOpcode)[keyof typeof TerminalStreamOpcode];
@@ -57,7 +58,8 @@ function isTerminalStreamOpcode(value: number): value is TerminalStreamOpcode {
    value === TerminalStreamOpcode.Output ||
    value === TerminalStreamOpcode.Input ||
    value === TerminalStreamOpcode.Resize ||
-    value === TerminalStreamOpcode.Snapshot
+    value === TerminalStreamOpcode.Snapshot ||
+    value === TerminalStreamOpcode.Restore
  );
 }

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "vitest";
+
+import { ServerInfoStatusPayloadSchema, SubscribeTerminalRequestSchema } from "./messages.js";
+
+describe("terminal restore schemas", () => {
+  test("accepts legacy terminal subscribe requests without restore options", () => {
+    expect(
+      SubscribeTerminalRequestSchema.parse({
+        type: "subscribe_terminal_request",
+        terminalId: "term-1",
+        requestId: "req-1",
+      }),
+    ).toEqual({
+      type: "subscribe_terminal_request",
+      terminalId: "term-1",
+      requestId: "req-1",
+    });
+  });
+
+  test("accepts kebab-case terminal restore modes", () => {
+    for (const mode of ["live", "visible-snapshot", "full-snapshot"] as const) {
+      expect(
+        SubscribeTerminalRequestSchema.parse({
+          type: "subscribe_terminal_request",
+          terminalId: "term-1",
+          requestId: `req-${mode}`,
+          restore: {
+            mode,
+            scrollbackLines: 200,
+            size: { rows: 24, cols: 80 },
+          },
+        }).restore?.mode,
+      ).toBe(mode);
+    }
+  });
+
+  test("rejects camel-case terminal restore modes", () => {
+    expect(() =>
+      SubscribeTerminalRequestSchema.parse({
+        type: "subscribe_terminal_request",
+        terminalId: "term-1",
+        requestId: "req-1",
+        restore: {
+          mode: "visibleSnapshot",
+        },
+      }),
+    ).toThrow();
+  });
+
+  test("accepts terminal restore mode feature metadata", () => {
+    expect(
+      ServerInfoStatusPayloadSchema.parse({
+        status: "server_info",
+        serverId: "server-1",
+        features: {
+          "terminal-restore-modes": true,
+        },
+      }).features?.["terminal-restore-modes"],
+    ).toBe(true);
+  });
+});
@@ -1754,6 +1754,20 @@ export const SubscribeTerminalRequestSchema = z.object({
  type: z.literal("subscribe_terminal_request"),
  terminalId: z.string(),
  requestId: z.string(),
+  restore: z
+    .object({
+      mode: z.enum(["live", "visible-snapshot", "full-snapshot"]),
+      scrollbackLines: z.number().int().nonnegative().optional(),
+      size: z
+        .object({
+          rows: z.number().int().positive(),
+          cols: z.number().int().positive(),
+        })
+        .strict()
+        .optional(),
+    })
+    .strict()
+    .optional(),
 });

 export const UnsubscribeTerminalRequestSchema = z.object({
@@ -2079,6 +2093,8 @@ export const ServerInfoStatusPayloadSchema = z
        checkoutGithubSetAutoMerge: z.boolean().optional(),
        // COMPAT(daemonStatusRpc): added in v0.1.76, remove gate after 2026-11-18.
        daemonStatusRpc: z.boolean().optional(),
+        // COMPAT(terminalRestoreModes): added in v0.1.81, remove gate after 2026-11-23.
+        "terminal-restore-modes": z.boolean().optional(),
      })
      .optional(),
  })
@@ -0,0 +1,205 @@
+import type { TerminalCell, TerminalState } from "./messages.js";
+
+interface TerminalStyle {
+  fg: number | undefined;
+  bg: number | undefined;
+  fgMode: number | undefined;
+  bgMode: number | undefined;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  dim: boolean;
+  inverse: boolean;
+  strikethrough: boolean;
+}
+
+const DEFAULT_STYLE: TerminalStyle = {
+  fg: undefined,
+  bg: undefined,
+  fgMode: undefined,
+  bgMode: undefined,
+  bold: false,
+  italic: false,
+  underline: false,
+  dim: false,
+  inverse: false,
+  strikethrough: false,
+};
+
+export function renderTerminalSnapshotToAnsi(state: TerminalState): string {
+  const rows = [...state.scrollback, ...state.grid];
+  const lines: string[] = ["\u001b[?7l"];
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex] ?? [];
+    lines.push(renderTerminalRow(row));
+    if (rowIndex < rows.length - 1) {
+      lines.push("\r\n");
+    }
+  }
+
+  lines.push("\u001b[0m");
+  const cursorPresentationAnsi = renderCursorPresentationToAnsi(state.cursor);
+  if (cursorPresentationAnsi) {
+    lines.push(cursorPresentationAnsi);
+  }
+  lines.push(`\u001b[${state.cursor.row + 1};${state.cursor.col + 1}H`);
+  lines.push(state.cursor.hidden ? "\u001b[?25l" : "\u001b[?25h");
+  lines.push("\u001b[?7h");
+  return lines.join("");
+}
+
+function renderCursorPresentationToAnsi(cursor: TerminalState["cursor"]): string | null {
+  if (!cursor.style) {
+    return null;
+  }
+
+  const cursorStyleCode = (() => {
+    if (cursor.style === "block") {
+      return cursor.blink === false ? 2 : 1;
+    }
+    if (cursor.style === "underline") {
+      return cursor.blink === false ? 4 : 3;
+    }
+    return cursor.blink === false ? 6 : 5;
+  })();
+
+  return `\u001b[${cursorStyleCode} q`;
+}
+
+function renderTerminalRow(row: TerminalCell[]): string {
+  const output: string[] = [];
+  const length = getTerminalRowLength(row);
+  let previousStyle = DEFAULT_STYLE;
+
+  for (let index = 0; index < length; index += 1) {
+    const cell = row[index] ?? { char: " " };
+    const nextStyle = getTerminalStyle(cell);
+    if (!terminalStylesEqual(previousStyle, nextStyle)) {
+      output.push(styleToAnsi(nextStyle));
+      previousStyle = nextStyle;
+    }
+    output.push(cell.char || " ");
+  }
+
+  if (!terminalStylesEqual(previousStyle, DEFAULT_STYLE)) {
+    output.push("\u001b[0m");
+  }
+
+  return output.join("");
+}
+
+function getTerminalRowLength(row: TerminalCell[]): number {
+  for (let index = row.length - 1; index >= 0; index -= 1) {
+    const cell = row[index];
+    if (!cell) {
+      continue;
+    }
+    if (cell.char !== " ") {
+      return index + 1;
+    }
+    if (
+      cell.fg !== undefined ||
+      cell.bg !== undefined ||
+      cell.fgMode !== undefined ||
+      cell.bgMode !== undefined ||
+      cell.bold ||
+      cell.italic ||
+      cell.underline ||
+      cell.dim ||
+      cell.inverse ||
+      cell.strikethrough
+    ) {
+      return index + 1;
+    }
+  }
+  return 0;
+}
+
+function getTerminalStyle(cell: TerminalCell): TerminalStyle {
+  return {
+    fg: cell.fg,
+    bg: cell.bg,
+    fgMode: cell.fgMode,
+    bgMode: cell.bgMode,
+    bold: Boolean(cell.bold),
+    italic: Boolean(cell.italic),
+    underline: Boolean(cell.underline),
+    dim: Boolean(cell.dim),
+    inverse: Boolean(cell.inverse),
+    strikethrough: Boolean(cell.strikethrough),
+  };
+}
+
+function terminalStylesEqual(left: TerminalStyle, right: TerminalStyle): boolean {
+  return (
+    left.fg === right.fg &&
+    left.bg === right.bg &&
+    left.fgMode === right.fgMode &&
+    left.bgMode === right.bgMode &&
+    left.bold === right.bold &&
+    left.italic === right.italic &&
+    left.underline === right.underline &&
+    left.dim === right.dim &&
+    left.inverse === right.inverse &&
+    left.strikethrough === right.strikethrough
+  );
+}
+
+function styleToAnsi(style: TerminalStyle): string {
+  const codes = ["0"];
+
+  if (style.bold) {
+    codes.push("1");
+  }
+  if (style.dim) {
+    codes.push("2");
+  }
+  if (style.italic) {
+    codes.push("3");
+  }
+  if (style.underline) {
+    codes.push("4");
+  }
+  if (style.inverse) {
+    codes.push("7");
+  }
+  if (style.strikethrough) {
+    codes.push("9");
+  }
+
+  if (style.fg !== undefined && style.fgMode !== undefined) {
+    codes.push(...colorToSgr(style.fgMode, style.fg, false));
+  }
+
+  if (style.bg !== undefined && style.bgMode !== undefined) {
+    codes.push(...colorToSgr(style.bgMode, style.bg, true));
+  }
+
+  return `\u001b[${codes.join(";")}m`;
+}
+
+function colorToSgr(mode: number, value: number, background: boolean): string[] {
+  if (mode === 1) {
+    if (value >= 8) {
+      return [String((background ? 100 : 90) + (value - 8))];
+    }
+    return [String((background ? 40 : 30) + value)];
+  }
+
+  if (mode === 2) {
+    return [background ? "48" : "38", "5", String(value)];
+  }
+
+  if (mode === 3) {
+    return [
+      background ? "48" : "38",
+      "2",
+      String((value >> 16) & 0xff),
+      String((value >> 8) & 0xff),
+      String(value & 0xff),
+    ];
+  }
+
+  return [];
+}
@@ -1,4 +1,9 @@
-import { createTerminal, type TerminalSession, type TerminalStateSnapshot } from "./terminal.js";
+import {
+  createTerminal,
+  type TerminalSession,
+  type TerminalStateSnapshot,
+  type TerminalStateSnapshotOptions,
+} from "./terminal.js";
 import { captureTerminalLines, type CaptureTerminalLinesResult } from "./terminal-capture.js";
 import { resolve, sep, win32, posix } from "node:path";

@@ -29,7 +34,10 @@ export interface TerminalManager {
  }): Promise<TerminalSession>;
  registerCwdEnv(options: { cwd: string; env: Record<string, string> }): void;
  getTerminal(id: string): TerminalSession | undefined;
-  getTerminalState(id: string): Promise<TerminalStateSnapshot | null>;
+  getTerminalState(
+    id: string,
+    options?: TerminalStateSnapshotOptions,
+  ): Promise<TerminalStateSnapshot | null>;
  setTerminalTitle(id: string, title: string): boolean;
  killTerminal(id: string): void;
  killTerminalAndWait(
@@ -208,8 +216,11 @@ export function createTerminalManager(): TerminalManager {
      return terminalsById.get(id);
    },

-    async getTerminalState(id: string): Promise<TerminalStateSnapshot | null> {
-      return terminalsById.get(id)?.getStateSnapshot() ?? null;
+    async getTerminalState(
+      id: string,
+      options?: TerminalStateSnapshotOptions,
+    ): Promise<TerminalStateSnapshot | null> {
+      return terminalsById.get(id)?.getStateSnapshot(options) ?? null;
    },

    setTerminalTitle(id: string, title: string): boolean {
@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest";
+
+import { TerminalStreamOpcode, decodeTerminalStreamFrame } from "../shared/binary-frames/index.js";
+import type { TerminalCell, TerminalState } from "../shared/messages.js";
+import {
+  encodeTerminalRestoreFrame,
+  resolveRestoreAfterOutputOverflow,
+  resolveTerminalRestoreSnapshotOptions,
+  resolveTerminalSubscriptionSnapshotMode,
+} from "./terminal-restore.js";
+
+function terminalRow(text: string, cols = 80): TerminalCell[] {
+  return Array.from({ length: cols }, (_, index) => ({
+    char: text[index] ?? " ",
+  }));
+}
+
+function terminalState(text: string): TerminalState {
+  return {
+    rows: 1,
+    cols: 80,
+    grid: [terminalRow(text)],
+    scrollback: [],
+    cursor: { row: 0, col: text.length },
+  };
+}
+
+describe("terminal restore policy", () => {
+  test("uses ready snapshots only for restore-aware subscriptions", () => {
+    expect(resolveTerminalSubscriptionSnapshotMode(undefined)).toBe("state");
+    expect(resolveTerminalSubscriptionSnapshotMode({ mode: "live" })).toBe("ready");
+  });
+
+  test("resolves bounded restore snapshot options", () => {
+    expect(resolveTerminalRestoreSnapshotOptions({ mode: "live" })).toBeNull();
+    expect(resolveTerminalRestoreSnapshotOptions({ mode: "full-snapshot" })).toBeUndefined();
+    expect(resolveTerminalRestoreSnapshotOptions({ mode: "visible-snapshot" })).toEqual({
+      scrollbackLines: 200,
+    });
+    expect(
+      resolveTerminalRestoreSnapshotOptions({
+        mode: "visible-snapshot",
+        scrollbackLines: 999,
+      }),
+    ).toEqual({ scrollbackLines: 500 });
+  });
+
+  test("promotes live restore to visible restore after output overflow", () => {
+    expect(resolveRestoreAfterOutputOverflow({ mode: "live" })).toEqual({
+      mode: "visible-snapshot",
+    });
+    expect(resolveRestoreAfterOutputOverflow({ mode: "full-snapshot" })).toEqual({
+      mode: "full-snapshot",
+    });
+  });
+
+  test("encodes restore snapshots as restore frames", () => {
+    const frame = decodeTerminalStreamFrame(
+      encodeTerminalRestoreFrame({
+        slot: 4,
+        snapshot: {
+          state: terminalState("restored"),
+          revision: 1,
+        },
+      }),
+    );
+
+    expect(frame?.opcode).toBe(TerminalStreamOpcode.Restore);
+    expect(frame?.slot).toBe(4);
+    expect(new TextDecoder().decode(frame?.payload ?? new Uint8Array())).toContain("restored");
+  });
+});
@@ -0,0 +1,75 @@
+import type { SubscribeTerminalRequest } from "../server/messages.js";
+import {
+  TerminalStreamOpcode,
+  encodeTerminalSnapshotPayload,
+  encodeTerminalStreamFrame,
+} from "../shared/binary-frames/index.js";
+import { renderTerminalSnapshotToAnsi } from "../shared/terminal-snapshot.js";
+import type { TerminalStateSnapshot, TerminalStateSnapshotOptions } from "./terminal.js";
+
+export const MAX_TERMINAL_OUTPUT_FRAME_BYTES = 256 * 1024;
+
+const DEFAULT_VISIBLE_RESTORE_SCROLLBACK_LINES = 200;
+const MAX_VISIBLE_RESTORE_SCROLLBACK_LINES = 500;
+
+export type TerminalRestoreOptions = NonNullable<SubscribeTerminalRequest["restore"]>;
+
+export type TerminalSubscriptionSnapshotMode = "state" | "ready";
+
+export function resolveTerminalSubscriptionSnapshotMode(
+  restore: TerminalRestoreOptions | undefined,
+): TerminalSubscriptionSnapshotMode {
+  return restore ? "ready" : "state";
+}
+
+export function resolveRestoreAfterOutputOverflow(
+  restore: TerminalRestoreOptions | undefined,
+): TerminalRestoreOptions | undefined {
+  if (restore?.mode === "live") {
+    return { mode: "visible-snapshot" };
+  }
+  return restore;
+}
+
+export function resolveTerminalRestoreSnapshotOptions(
+  restore: TerminalRestoreOptions,
+): TerminalStateSnapshotOptions | null | undefined {
+  if (restore.mode === "live") {
+    return null;
+  }
+  if (restore.mode === "visible-snapshot") {
+    return {
+      scrollbackLines: resolveVisibleRestoreScrollbackLines(restore.scrollbackLines),
+    };
+  }
+  return undefined;
+}
+
+export function encodeLegacyTerminalSnapshotFrame(input: {
+  slot: number;
+  snapshot: TerminalStateSnapshot;
+}): Uint8Array {
+  return encodeTerminalStreamFrame({
+    opcode: TerminalStreamOpcode.Snapshot,
+    slot: input.slot,
+    payload: encodeTerminalSnapshotPayload(input.snapshot.state),
+  });
+}
+
+export function encodeTerminalRestoreFrame(input: {
+  slot: number;
+  snapshot: TerminalStateSnapshot;
+}): Uint8Array {
+  return encodeTerminalStreamFrame({
+    opcode: TerminalStreamOpcode.Restore,
+    slot: input.slot,
+    payload: renderTerminalSnapshotToAnsi(input.snapshot.state),
+  });
+}
+
+function resolveVisibleRestoreScrollbackLines(value: number | undefined): number {
+  if (typeof value !== "number") {
+    return DEFAULT_VISIBLE_RESTORE_SCROLLBACK_LINES;
+  }
+  return Math.min(Math.max(0, value), MAX_VISIBLE_RESTORE_SCROLLBACK_LINES);
+}
@@ -0,0 +1,142 @@
+import { describe, expect, test, vi } from "vitest";
+import type pino from "pino";
+
+import type { SessionOutboundMessage } from "../server/messages.js";
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  type TerminalStreamFrame,
+} from "../shared/binary-frames/index.js";
+import type { TerminalCell, TerminalState } from "../shared/messages.js";
+import type { ServerMessage, TerminalSession, TerminalStateSnapshot } from "./terminal.js";
+import { TerminalSessionController } from "./terminal-session-controller.js";
+import type { TerminalManager } from "./terminal-manager.js";
+
+function deferred<T>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: unknown) => void;
+} {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  return { promise, resolve, reject };
+}
+
+function terminalRow(text: string, cols = 80): TerminalCell[] {
+  return Array.from({ length: cols }, (_, index) => ({
+    char: text[index] ?? " ",
+  }));
+}
+
+function terminalState(text: string): TerminalState {
+  return {
+    rows: 1,
+    cols: 80,
+    grid: [terminalRow(text)],
+    scrollback: [],
+    cursor: { row: 0, col: text.length },
+  };
+}
+
+function createLogger(): pino.Logger {
+  return {
+    warn: vi.fn(),
+    error: vi.fn(),
+  } as unknown as pino.Logger;
+}
+
+describe("terminal-session-controller restore", () => {
+  test("delivers output produced while restore is in flight after the restore frame", async () => {
+    let terminalListener: ((message: ServerMessage) => void) | null = null;
+    const snapshot = deferred<TerminalStateSnapshot | null>();
+    const binaryFrames: TerminalStreamFrame[] = [];
+    const outboundMessages: SessionOutboundMessage[] = [];
+    const terminal: TerminalSession = {
+      id: "term-1",
+      name: "Terminal",
+      cwd: "/tmp",
+      send: vi.fn(),
+      subscribe: (listener) => {
+        terminalListener = listener;
+        queueMicrotask(() => listener({ type: "snapshotReady", revision: 1 }));
+        return vi.fn();
+      },
+      onExit: () => vi.fn(),
+      onCommandFinished: () => vi.fn(),
+      onTitleChange: () => vi.fn(),
+      getSize: () => ({ rows: 1, cols: 80 }),
+      getState: () => terminalState("restore-before"),
+      getStateSnapshot: () => ({ state: terminalState("restore-before"), revision: 1 }),
+      getReplayPreamble: () => "",
+      getTitle: () => undefined,
+      setTitle: vi.fn(),
+      getExitInfo: () => null,
+      kill: vi.fn(),
+      killAndWait: vi.fn(),
+    };
+    const terminalManager: TerminalManager = {
+      getTerminals: vi.fn(),
+      createTerminal: vi.fn(),
+      registerCwdEnv: vi.fn(),
+      getTerminal: vi.fn(() => terminal),
+      getTerminalState: vi.fn(() => snapshot.promise),
+      setTerminalTitle: vi.fn(),
+      killTerminal: vi.fn(),
+      killTerminalAndWait: vi.fn(),
+      captureTerminal: vi.fn(),
+      listDirectories: vi.fn(() => []),
+      killAll: vi.fn(),
+      subscribeTerminalsChanged: vi.fn(() => vi.fn()),
+    };
+    const controller = new TerminalSessionController({
+      terminalManager,
+      emit: (message) => outboundMessages.push(message),
+      emitBinary: (bytes) => {
+        const frame = decodeTerminalStreamFrame(bytes);
+        if (frame) {
+          binaryFrames.push(frame);
+        }
+      },
+      hasBinaryChannel: () => true,
+      isPathWithinRoot: () => false,
+      sessionLogger: createLogger(),
+    });
+
+    await controller.dispatch({
+      type: "subscribe_terminal_request",
+      terminalId: "term-1",
+      requestId: "req-1",
+      restore: {
+        mode: "visible-snapshot",
+        scrollbackLines: 200,
+      },
+    });
+    await Promise.resolve();
+    expect(terminalManager.getTerminalState).toHaveBeenCalledTimes(1);
+
+    terminalListener?.({ type: "output", data: "restore-after\n", revision: 2 });
+    snapshot.resolve({ state: terminalState("restore-before"), revision: 1 });
+    await snapshot.promise;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(outboundMessages).toContainEqual({
+      type: "subscribe_terminal_response",
+      payload: {
+        terminalId: "term-1",
+        slot: 0,
+        error: null,
+        requestId: "req-1",
+      },
+    });
+    expect(binaryFrames.map((frame) => frame.opcode)).toEqual([
+      TerminalStreamOpcode.Restore,
+      TerminalStreamOpcode.Output,
+    ]);
+    expect(new TextDecoder().decode(binaryFrames[0]?.payload)).toContain("restore-before");
+    expect(new TextDecoder().decode(binaryFrames[1]?.payload)).toBe("restore-after\n");
+  });
+});
@@ -17,11 +17,19 @@ import { killTerminalsUnderPath as killWorktreeTerminalsUnderPath } from "../ser
 import {
  TerminalStreamOpcode,
  decodeTerminalResizePayload,
-  encodeTerminalSnapshotPayload,
  encodeTerminalStreamFrame,
  type TerminalStreamFrame,
 } from "../shared/binary-frames/index.js";
 import { TerminalOutputCoalescer } from "./terminal-output-coalescer.js";
+import {
+  MAX_TERMINAL_OUTPUT_FRAME_BYTES,
+  encodeLegacyTerminalSnapshotFrame,
+  encodeTerminalRestoreFrame,
+  resolveRestoreAfterOutputOverflow,
+  resolveTerminalRestoreSnapshotOptions,
+  resolveTerminalSubscriptionSnapshotMode,
+  type TerminalRestoreOptions,
+} from "./terminal-restore.js";
 import type { TerminalSession } from "./terminal.js";
 import type { TerminalManager, TerminalsChangedEvent } from "./terminal-manager.js";

@@ -38,10 +46,18 @@ interface ActiveTerminalStream {
  unsubscribe: () => void;
  needsSnapshot: boolean;
  snapshotInFlight: boolean;
+  readyRevision?: number;
+  restore?: TerminalRestoreOptions;
  bufferedOutputs: BufferedTerminalOutput[];
+  outputBytesSinceSnapshot: number;
  outputCoalescer: TerminalOutputCoalescer;
 }

+interface SnapshotSendResult {
+  shouldContinue: boolean;
+  replayRevision?: number;
+}
+
 export interface TerminalSessionControllerOptions {
  terminalManager: TerminalManager | null;
  emit: (msg: SessionOutboundMessage) => void;
@@ -488,7 +504,21 @@ export class TerminalSessionController {
    }
    this.ensureExitSubscription(session);

-    const slot = this.bindActiveStream(session);
+    if (msg.restore?.size) {
+      const currentSize = session.getSize();
+      if (
+        currentSize.rows !== msg.restore.size.rows ||
+        currentSize.cols !== msg.restore.size.cols
+      ) {
+        session.send({
+          type: "resize",
+          rows: msg.restore.size.rows,
+          cols: msg.restore.size.cols,
+        });
+      }
+    }
+
+    const slot = this.bindActiveStream(session, { restore: msg.restore });
    if (slot === null) {
      this.sessionLogger.warn(
        {
@@ -628,7 +658,10 @@ export class TerminalSessionController {
    }
  }

-  private bindActiveStream(terminal: TerminalSession): number | null {
+  private bindActiveStream(
+    terminal: TerminalSession,
+    options?: { restore?: TerminalRestoreOptions },
+  ): number | null {
    if (!this.hasBinaryChannel()) {
      return null;
    }
@@ -638,6 +671,7 @@ export class TerminalSessionController {
      const existingStream = this.activeStreams.get(existingSlot);
      if (existingStream) {
        existingStream.needsSnapshot = true;
+        existingStream.restore = options?.restore;
        return existingSlot;
      }
      this.idToSlot.delete(terminal.id);
@@ -654,13 +688,23 @@ export class TerminalSessionController {
      unsubscribe: () => {},
      needsSnapshot: true,
      snapshotInFlight: false,
+      readyRevision: undefined,
+      restore: options?.restore,
      bufferedOutputs: [],
+      outputBytesSinceSnapshot: 0,
      outputCoalescer: new TerminalOutputCoalescer({
        timers: { setTimeout, clearTimeout },
        onFlush: ({ payload }) => {
          if (this.activeStreams.get(slot) !== activeStream) {
            return;
          }
+          activeStream.outputBytesSinceSnapshot += payload.byteLength;
+          if (activeStream.outputBytesSinceSnapshot > MAX_TERMINAL_OUTPUT_FRAME_BYTES) {
+            activeStream.restore = resolveRestoreAfterOutputOverflow(activeStream.restore);
+            activeStream.needsSnapshot = true;
+            void this.trySendSnapshot(activeStream);
+            return;
+          }
          this.emitBinary(
            encodeTerminalStreamFrame({
              opcode: TerminalStreamOpcode.Output,
@@ -675,31 +719,35 @@ export class TerminalSessionController {
    this.activeStreams.set(slot, activeStream);
    this.idToSlot.set(terminal.id, slot);

-    activeStream.unsubscribe = terminal.subscribe((message) => {
-      if (this.activeStreams.get(slot) !== activeStream) {
-        return;
-      }
-      if (message.type === "snapshot") {
-        activeStream.outputCoalescer.flush();
-        activeStream.needsSnapshot = true;
-        void this.trySendSnapshot(activeStream);
-        return;
-      }
-      if (message.type === "titleChange") {
-        return;
-      }
-      if (message.data.length === 0) {
-        return;
-      }
-      if (activeStream.needsSnapshot || activeStream.snapshotInFlight) {
-        activeStream.bufferedOutputs.push({
-          data: message.data,
-          revision: message.revision,
-        });
-        return;
-      }
-      activeStream.outputCoalescer.handle(message.data);
-    });
+    activeStream.unsubscribe = terminal.subscribe(
+      (message) => {
+        if (this.activeStreams.get(slot) !== activeStream) {
+          return;
+        }
+        if (message.type === "snapshot" || message.type === "snapshotReady") {
+          activeStream.readyRevision = message.revision;
+          activeStream.outputCoalescer.flush();
+          activeStream.needsSnapshot = true;
+          void this.trySendSnapshot(activeStream);
+          return;
+        }
+        if (message.type === "titleChange") {
+          return;
+        }
+        if (message.data.length === 0) {
+          return;
+        }
+        if (activeStream.needsSnapshot || activeStream.snapshotInFlight) {
+          activeStream.bufferedOutputs.push({
+            data: message.data,
+            revision: message.revision,
+          });
+          return;
+        }
+        activeStream.outputCoalescer.handle(message.data);
+      },
+      { initialSnapshot: resolveTerminalSubscriptionSnapshotMode(options?.restore) },
+    );
    return slot;
  }

@@ -722,43 +770,23 @@ export class TerminalSessionController {
      this.detachStream(activeStream.terminalId, { emitExit: true });
      return;
    }
+    if (activeStream.restore && activeStream.readyRevision === undefined) {
+      return;
+    }

    activeStream.outputCoalescer.flush();
    activeStream.snapshotInFlight = true;
    try {
-      const snapshot = await terminalManager.getTerminalState(activeStream.terminalId);
-      if (this.activeStreams.get(activeStream.slot) !== activeStream) {
+      const restore = activeStream.restore;
+      const snapshotResult = restore
+        ? await this.emitRestoreSnapshot(activeStream, terminalManager, restore)
+        : await this.emitLegacySnapshot(activeStream, terminalManager);
+      if (!snapshotResult.shouldContinue) {
        return;
      }
-      if (!snapshot) {
-        this.detachStream(activeStream.terminalId, { emitExit: true });
-        return;
-      }
-
-      this.emitBinary(
-        encodeTerminalStreamFrame({
-          opcode: TerminalStreamOpcode.Snapshot,
-          slot: activeStream.slot,
-          payload: encodeTerminalSnapshotPayload(snapshot.state),
-        }),
-      );
-
-      const replayPreamble = terminal.getReplayPreamble();
-      if (replayPreamble.length > 0) {
-        activeStream.outputCoalescer.handle(replayPreamble);
-      }
-
-      const bufferedOutputs = activeStream.bufferedOutputs.splice(
-        0,
-        activeStream.bufferedOutputs.length,
-      );
-      for (const output of bufferedOutputs) {
-        if (output.revision !== undefined && output.revision <= snapshot.revision) {
-          continue;
-        }
-        activeStream.outputCoalescer.handle(output.data);
-      }
+      this.replayTerminalOutputAfterSnapshot(activeStream, terminal, snapshotResult.replayRevision);
      activeStream.needsSnapshot = false;
+      activeStream.outputBytesSinceSnapshot = 0;
    } catch (error) {
      this.sessionLogger.warn(
        { err: error, terminalId: activeStream.terminalId },
@@ -770,6 +798,85 @@ export class TerminalSessionController {
    }
  }

+  private async emitLegacySnapshot(
+    activeStream: ActiveTerminalStream,
+    terminalManager: TerminalManager,
+  ): Promise<SnapshotSendResult> {
+    const snapshot = await terminalManager.getTerminalState(activeStream.terminalId);
+    if (this.activeStreams.get(activeStream.slot) !== activeStream) {
+      return { shouldContinue: false };
+    }
+    if (!snapshot) {
+      this.detachStream(activeStream.terminalId, { emitExit: true });
+      return { shouldContinue: false };
+    }
+
+    this.emitBinary(
+      encodeLegacyTerminalSnapshotFrame({
+        slot: activeStream.slot,
+        snapshot,
+      }),
+    );
+    return { shouldContinue: true, replayRevision: snapshot.revision };
+  }
+
+  private async emitRestoreSnapshot(
+    activeStream: ActiveTerminalStream,
+    terminalManager: TerminalManager,
+    restore: TerminalRestoreOptions,
+  ): Promise<SnapshotSendResult> {
+    const snapshotOptions = resolveTerminalRestoreSnapshotOptions(restore);
+    if (snapshotOptions === null) {
+      return { shouldContinue: true };
+    }
+
+    const snapshot = await terminalManager.getTerminalState(
+      activeStream.terminalId,
+      snapshotOptions,
+    );
+    if (this.activeStreams.get(activeStream.slot) !== activeStream) {
+      return { shouldContinue: false };
+    }
+    if (!snapshot) {
+      this.detachStream(activeStream.terminalId, { emitExit: true });
+      return { shouldContinue: false };
+    }
+
+    this.emitBinary(
+      encodeTerminalRestoreFrame({
+        slot: activeStream.slot,
+        snapshot,
+      }),
+    );
+    return { shouldContinue: true, replayRevision: snapshot.revision };
+  }
+
+  private replayTerminalOutputAfterSnapshot(
+    activeStream: ActiveTerminalStream,
+    terminal: TerminalSession,
+    replayRevision: number | undefined,
+  ): void {
+    const replayPreamble = terminal.getReplayPreamble();
+    if (replayPreamble.length > 0) {
+      activeStream.outputCoalescer.handle(replayPreamble);
+    }
+
+    const bufferedOutputs = activeStream.bufferedOutputs.splice(
+      0,
+      activeStream.bufferedOutputs.length,
+    );
+    for (const output of bufferedOutputs) {
+      if (
+        replayRevision !== undefined &&
+        output.revision !== undefined &&
+        output.revision <= replayRevision
+      ) {
+        continue;
+      }
+      activeStream.outputCoalescer.handle(output.data);
+    }
+  }
+
  private allocateSlot(): number | null {
    for (let attempt = 0; attempt < MAX_TERMINAL_STREAM_SLOTS; attempt += 1) {
      const slot = (this.nextSlot + attempt) % MAX_TERMINAL_STREAM_SLOTS;
@@ -176,7 +176,7 @@ async function handleRequest(message: TerminalWorkerRequest): Promise<void> {
        type: "response",
        requestId: message.requestId,
        ok: true,
-        result: session?.getStateSnapshot() ?? null,
+        result: session?.getStateSnapshot(message.options) ?? null,
      });
      return;
    }
@@ -3,6 +3,7 @@ import type {
  ServerMessage,
  ClientMessage,
  TerminalStateSnapshot,
+  TerminalStateSnapshotOptions,
 } from "./terminal.js";
 import type { TerminalState } from "../shared/messages.js";
 import type { CaptureTerminalLinesResult } from "./terminal-capture.js";
@@ -61,6 +62,7 @@ export type TerminalWorkerRequest =
      type: "getTerminalState";
      requestId: string;
      terminalId: string;
+      options?: TerminalStateSnapshotOptions;
    }
  | {
      type: "captureTerminal";
@@ -33,6 +33,14 @@ export interface TerminalStateSnapshot {
  revision: number;
 }

+export interface TerminalStateSnapshotOptions {
+  scrollbackLines?: number;
+}
+
+export interface TerminalSubscribeOptions {
+  initialSnapshot?: "state" | "ready";
+}
+
 export type ClientMessage =
  | { type: "input"; data: string }
  | { type: "resize"; rows: number; cols: number }
@@ -41,6 +49,7 @@ export type ClientMessage =
 export type ServerMessage =
  | { type: "output"; data: string; revision?: number }
  | { type: "snapshot"; state: TerminalState; revision?: number }
+  | { type: "snapshotReady"; revision?: number }
  | { type: "titleChange"; title?: string };

 export interface TerminalSession {
@@ -48,13 +57,13 @@ export interface TerminalSession {
  name: string;
  cwd: string;
  send(msg: ClientMessage): void;
-  subscribe(listener: (msg: ServerMessage) => void): () => void;
+  subscribe(listener: (msg: ServerMessage) => void, options?: TerminalSubscribeOptions): () => void;
  onExit(listener: (info: TerminalExitInfo) => void): () => void;
  onCommandFinished(listener: (info: TerminalCommandFinishedInfo) => void): () => void;
  onTitleChange(listener: (title?: string) => void): () => void;
  getSize(): { rows: number; cols: number };
  getState(): TerminalState;
-  getStateSnapshot(): TerminalStateSnapshot;
+  getStateSnapshot(options?: TerminalStateSnapshotOptions): TerminalStateSnapshot;
  getReplayPreamble(): string;
  getTitle(): string | undefined;
  setTitle(title: string): void;
@@ -292,14 +301,21 @@ function extractGrid(terminal: TerminalType): TerminalCell[][] {
  return grid;
 }

-function extractScrollback(terminal: TerminalType): TerminalCell[][] {
+function extractScrollback(
+  terminal: TerminalType,
+  options?: { scrollbackLines?: number },
+): TerminalCell[][] {
  const scrollback: TerminalCell[][] = [];
  const buffer = terminal.buffer.active;
  // baseY is the first row of the visible viewport (0-indexed)
  // Lines 0 to baseY-1 are in scrollback, lines baseY onwards are visible
  const scrollbackLines = buffer.baseY;
+  const startRow =
+    typeof options?.scrollbackLines === "number"
+      ? Math.max(0, scrollbackLines - options.scrollbackLines)
+      : 0;

-  for (let row = 0; row < scrollbackLines; row++) {
+  for (let row = startRow; row < scrollbackLines; row++) {
    const rowCells: TerminalCell[] = [];
    const line = buffer.getLine(row);
    for (let col = 0; col < terminal.cols; col++) {
@@ -813,20 +829,22 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
    }
  }

-  function getState(): TerminalState {
+  function getState(snapshotOptions?: TerminalStateSnapshotOptions): TerminalState {
    return {
      rows: terminal.rows,
      cols: terminal.cols,
      grid: extractGrid(terminal),
-      scrollback: extractScrollback(terminal),
+      scrollback: extractScrollback(terminal, {
+        scrollbackLines: snapshotOptions?.scrollbackLines,
+      }),
      cursor: extractCursorState(terminal),
      ...(title ? { title } : {}),
    };
  }

-  function getStateSnapshot(): TerminalStateSnapshot {
+  function getStateSnapshot(snapshotOptions?: TerminalStateSnapshotOptions): TerminalStateSnapshot {
    return {
-      state: getState(),
+      state: getState(snapshotOptions),
      revision: stateRevision,
    };
  }
@@ -891,10 +909,14 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
    }
  }

-  function subscribe(listener: (msg: ServerMessage) => void): () => void {
+  function subscribe(
+    listener: (msg: ServerMessage) => void,
+    subscribeOptions?: TerminalSubscribeOptions,
+  ): () => void {
    let active = true;
    let snapshotDelivered = false;
    const queuedMessages: ServerMessage[] = [];
+    const initialSnapshot = subscribeOptions?.initialSnapshot ?? "state";
    const subscriptionListener = (msg: ServerMessage): void => {
      if (!active) {
        return;
@@ -911,7 +933,11 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
    terminal.write("", () => {
      if (!disposed && active && listeners.has(subscriptionListener)) {
        snapshotDelivered = true;
-        listener({ type: "snapshot", ...getStateSnapshot() });
+        if (initialSnapshot === "ready") {
+          listener({ type: "snapshotReady", revision: stateRevision });
+        } else {
+          listener({ type: "snapshot", ...getStateSnapshot() });
+        }
        for (const message of queuedMessages.splice(0)) {
          listener(message);
        }
@@ -200,8 +200,18 @@ export function createWorkerTerminalManager(
        }
        sendBestEffortRequest({ type: "send", terminalId: record.info.id, message });
      },
-      subscribe(listener: (msg: ServerMessage) => void): () => void {
+      subscribe(
+        listener: (msg: ServerMessage) => void,
+        options?: { initialSnapshot?: "state" | "ready" },
+      ): () => void {
        record.messageListeners.add(listener);
+        if (options?.initialSnapshot === "ready") {
+          queueMicrotask(() => {
+            if (record.messageListeners.has(listener)) {
+              listener({ type: "snapshotReady", revision: 0 });
+            }
+          });
+        }
        return () => {
          record.messageListeners.delete(listener);
        };
@@ -244,9 +254,14 @@ export function createWorkerTerminalManager(
      getState(): TerminalState {
        return record.state;
      },
-      getStateSnapshot(): TerminalStateSnapshot {
+      getStateSnapshot(options?: { scrollbackLines?: number }): TerminalStateSnapshot {
+        const scrollbackLines = options?.scrollbackLines;
+        const scrollback =
+          typeof scrollbackLines === "number"
+            ? record.state.scrollback.slice(-scrollbackLines)
+            : record.state.scrollback;
        return {
-          state: record.state,
+          state: { ...record.state, scrollback },
          revision: 0,
        };
      },
@@ -539,10 +554,14 @@ export function createWorkerTerminalManager(
      return recordsById.get(id)?.session;
    },

-    async getTerminalState(id: string): Promise<TerminalStateSnapshot | null> {
+    async getTerminalState(
+      id: string,
+      options?: { scrollbackLines?: number },
+    ): Promise<TerminalStateSnapshot | null> {
      return (await sendRequest({
        type: "getTerminalState",
        terminalId: id,
+        ...(options ? { options } : {}),
      })) as TerminalWorkerStateResult;
    },