agent-relay-orchestrator 0.11.1 → 0.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -19,7 +19,9 @@
     "agent-relay-sdk": "0.2.2"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "6.0.0"
   },
   "peerDependencies": {
     "typescript": "^5"

package/src/api.ts

@@ -1,12 +1,10 @@
 import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, statSync } from "node:fs";
-import { createHash } from "node:crypto";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import type { ServerWebSocket } from "bun";
 import { proxyArtifactRequest } from "./artifact-proxy";
 import type { OrchestratorConfig } from "./config";
 import type { ProviderProbeCache } from "./provider-probe";
 import { captureSession, captureTerminal, createTerminalGuest, listSessions, sendTerminalInput, resizeTerminal, stopTerminalGuest } from "./spawn";
-import type { TerminalSnapshot } from "./spawn";
 import { acquireTerminalStream, type TerminalStreamHandle, type TerminalStreamSubscriber } from "./terminal-stream";
 import { VERSION, runtimeMetadata } from "./version";
 import { previewWorkspaceMerge, probeWorkspace, workspaceDiff, workspaceGitState } from "./workspace-probe";
@@ -76,26 +74,6 @@ interface TerminalSocketData {
 
 type TerminalSocket = ServerWebSocket<TerminalSocketData>;
 
-export function terminalSnapshotSignature(snapshot: TerminalSnapshot): string {
-  const hash = createHash("sha1");
-  hash.update(snapshot.session);
-  hash.update("\0");
-  hash.update(snapshot.running ? "1" : "0");
-  hash.update("\0");
-  hash.update(snapshot.agentAlive ? "1" : "0");
-  hash.update("\0");
-  hash.update(String(snapshot.cols ?? ""));
-  hash.update("\0");
-  hash.update(String(snapshot.rows ?? ""));
-  hash.update("\0");
-  hash.update(String(snapshot.cursorX ?? ""));
-  hash.update("\0");
-  hash.update(String(snapshot.cursorY ?? ""));
-  hash.update("\0");
-  hash.update(snapshot.content);
-  return hash.digest("hex");
-}
-
 function listDirectories(requestedPath: string | undefined, baseDir: string): DirectoryListing {
   const base = resolve(baseDir);
   const target = resolve(requestedPath || base);
@@ -599,23 +577,12 @@ function startTerminalSocket(ws: TerminalSocket): void {
   }
 }
 
-// How long to wait between stabilization captures, and how many to try. The viewer's
-// resize fires SIGWINCH at the TUI, whose repaint is *asynchronous* — capturing before
-// it lands snapshots a mid-repaint screen with a transient cursor, and the post-capture
-// relative deltas then land offset and stack a ghost frame. We poll until the capture
-// stops changing (or the budget runs out) so we only ever backfill a quiescent screen.
-const BACKFILL_STABILIZE_STEP_MS = Math.max(20, Number(process.env.AGENT_RELAY_TERMINAL_STABILIZE_STEP_MS) || 60);
-const BACKFILL_STABILIZE_MAX_STEPS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_STABILIZE_MAX_STEPS ?? 8));
-
-// Resize the pane to the viewer's dimensions and capture the matching backfill.
-//
-// Claude's TUI streams pure *relative* cursor deltas (no absolute positioning), so the
-// backfill snapshot must reflect a *settled* screen: the cursor we park has to match
-// where the next delta continues from. We stabilize the capture first (see sendBackfill),
-// so by the time we flush, every byte up to the capture is baked into the snapshot. The
-// capture is synchronous (spawnSync), so the queued bytes are all PRE-capture and already
-// in the snapshot — replaying them would double-apply deltas and stack a garbled ghost
-// frame, so we discard the queue here and only forward bytes that arrive after capture.
+// Backfill comes straight from tmux's own grid (see terminal-stream.ts): the snapshot's
+// `content` is a `capture-pane -e` repaint of the current screen (styled, cursor parked).
+// tmux is the real emulator and never drifts, so the repaint is byte-faithful and live
+// relative deltas then apply identically on the client. Live bytes that arrive before the
+// snapshot are already on tmux's grid (and thus in the capture), so we discard the queue
+// and only forward bytes that arrive after.
 async function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
   if (ws.data.syncTimer) {
     clearTimeout(ws.data.syncTimer);
@@ -628,46 +595,13 @@ async function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number)
   ws.data.ready = true;
 }
 
-// Re-capture until the screen stops changing (or the budget runs out). The first
-// capture resizes the pane to the viewer geometry, which fires SIGWINCH at the TUI
-// whose repaint is asynchronous; capturing before it lands snapshots a mid-repaint
-// screen with a transient cursor, and the post-capture relative deltas then stack a
-// ghost frame. `shouldAbort` lets the caller bail if the socket is torn down mid-poll.
-export async function captureStableSnapshot(
-  capture: (resize: boolean) => TerminalSnapshot,
-  options?: {
-    stepMs?: number;
-    maxSteps?: number;
-    sleep?: (ms: number) => Promise<void>;
-    shouldAbort?: () => boolean;
-  },
-): Promise<TerminalSnapshot | null> {
-  const stepMs = options?.stepMs ?? BACKFILL_STABILIZE_STEP_MS;
-  const maxSteps = options?.maxSteps ?? BACKFILL_STABILIZE_MAX_STEPS;
-  const sleep = options?.sleep ?? ((ms: number) => Bun.sleep(ms));
-  let snapshot = capture(true);
-  let signature = terminalSnapshotSignature(snapshot);
-  for (let i = 0; i < maxSteps; i++) {
-    await sleep(stepMs);
-    if (options?.shouldAbort?.()) return null;
-    const next = capture(false);
-    const nextSignature = terminalSnapshotSignature(next);
-    snapshot = next;
-    if (nextSignature === signature) break;
-    signature = nextSignature;
-  }
-  return snapshot;
-}
-
-// Send a full reset: a control frame with current geometry/status, then the
-// captured scrollback as a raw byte frame. Used on connect, resume, and refresh.
+// Send a full reset: a control frame with current geometry/status, then the serialized
+// emulator state as a raw byte frame. Used on connect, resume, and refresh.
 async function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
   const stream = ws.data.stream;
   if (!stream) return;
-  const snapshot = await captureStableSnapshot((resize) => (resize ? stream.backfill(cols, rows) : stream.backfill()), {
-    shouldAbort: () => ws.data.stream !== stream,
-  });
-  if (!snapshot) return; // socket torn down mid-stabilize
+  const snapshot = await stream.backfill(cols, rows);
+  if (ws.data.stream !== stream) return; // socket torn down mid-backfill
   ws.send(JSON.stringify({
     type: "reset",
     session: snapshot.session,
@@ -675,23 +609,10 @@ async function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number): P
     agentAlive: snapshot.agentAlive,
     cols: snapshot.cols,
     rows: snapshot.rows,
-    cursorX: snapshot.cursorX,
-    cursorY: snapshot.cursorY,
     capturedAt: snapshot.capturedAt,
   }));
   if (snapshot.content) {
-    // Strip the single trailing newline capture-pane appends. Left in, it scrolls xterm
-    // one extra row so the whole screen sits one row too high — and the cursor-park below
-    // then lands a row off, offsetting every relative statusline redraw (bottom-box ghost).
-    let content = snapshot.content.replace(/\n$/, "");
-    // Park the cursor where tmux actually has it (screen-relative). Without this the
-    // cursor sits at the end of the captured text, so the TUI's first relative redraw
-    // (cursor-up + rewrite of its prompt/statusline) lands at the wrong row and stacks
-    // a ghost copy into scrollback.
-    if (snapshot.cursorX != null && snapshot.cursorY != null) {
-      content += `\x1b[${snapshot.cursorY + 1};${snapshot.cursorX + 1}H`;
-    }
-    ws.send(new TextEncoder().encode(content));
+    ws.send(new TextEncoder().encode(snapshot.content));
   }
 }
 

package/src/spawn.ts

@@ -1144,6 +1144,13 @@ function tmuxHasSession(name: string, socketName?: string): boolean {
   return result.exitCode === 0;
 }
 
+// Lightweight liveness for the live terminal stream's backfill metadata — avoids a full
+// capture-pane just to learn whether the pane/agent are still up.
+export function sessionLiveness(name: string): { running: boolean; agentAlive: boolean } {
+  const socketName = tmuxSocketForSession(name);
+  return { running: tmuxHasSession(name, socketName), agentAlive: isSessionAlive(name) };
+}
+
 function tmuxPaneSize(name: string, socketName?: string): { cols?: number; rows?: number } {
   const result = Bun.spawnSync(tmuxCommand(socketName, "display-message", "-p", "-t", name, "#{pane_width} #{pane_height}"), {
     stdin: "ignore",

package/src/terminal-stream.ts

@@ -8,13 +8,24 @@
 // to raw bytes, coalesce on a short window, and broadcast. No screen-scraping, no
 // full-buffer repaint — the client just writes the byte stream to xterm.
 //
+// Backfill: tmux control mode does not replay the pre-attach screen, so on viewer
+// attach we repaint from tmux's *own* grid via `capture-pane -e` (styled, current
+// screen only — no scrollback, exactly what `tmux attach` shows) and park the cursor
+// where tmux has it. tmux is the real terminal emulator: its grid never drifts, so the
+// repaint is byte-faithful by definition, and subsequent live relative-cursor deltas
+// apply identically on the client (which now mirrors tmux exactly). We deliberately do
+// NOT keep a server-side @xterm/headless mirror: seeding such an emulator mid-stream
+// from a snapshot and then feeding it Claude's purely-relative deltas accumulates error
+// (the seed is never byte-perfect), which ghosted the screen into a staircase. tmux's
+// grid is the only authoritative source, so we read it directly.
+//
 // Input/resize: written as plain command lines to the control client's stdin
 // (`send-keys -H <hex>`, `resize-window`), so a keystroke costs no process spawn.
 // The relay's own injection path (message delivery, /compact, initial prompts) uses
 // its separate `tmux send-keys` calls and is unaffected — control mode is just
 // another observing client.
 
-import { captureTerminal, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
+import { captureConsistent, sessionLiveness, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
 import type { OrchestratorConfig } from "./config";
 
 const FLUSH_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_FLUSH_MS) || 6);
@@ -23,6 +34,23 @@ const BACKPRESSURE_MAX_BYTES = Math.max(
   1 << 20,
   Number(process.env.AGENT_RELAY_TERMINAL_BACKPRESSURE_MAX_BYTES) || 8 << 20,
 );
+// After a resize the TUI repaints asynchronously; let tmux's grid settle before we
+// capture, so the backfill is the post-resize frame, not a half-reflowed one.
+const RESIZE_SETTLE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESIZE_SETTLE_MS) || 90);
+// Live deltas are relative-cursor moves; replaying them onto a client seeded mid-stream
+// from a capture-pane snapshot can drift (lost scroll-region/SGR/wrap state → doubled
+// statusline, faded suggestion rendered solid, cursor off by a row). We can't transfer
+// full emulator state, so we periodically re-stamp tmux's authoritative grid in place to
+// snap the client back. Debounce after output settles; cap so continuous "thinking"
+// streams still correct. 0 disables the corrector.
+const RESYNC_DEBOUNCE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_DEBOUNCE_MS) || 120);
+const RESYNC_MAX_INTERVAL_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_MAX_INTERVAL_MS) || 350);
+// On attach we include this many lines of tmux scrollback ABOVE the current screen so the
+// viewer can scroll back through pre-attach history (the client lands on the live screen;
+// the history sits in its scroll buffer). This is a one-time per-attach paint, so it's
+// fine to be large; the live resync corrector only ever repaints the current screen, so it
+// never disturbs this history. 0 = current screen only.
+const BACKFILL_SCROLLBACK_LINES = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_BACKFILL_SCROLLBACK) || 1000);
 
 export interface TerminalStreamSubscriber {
   onData(bytes: Uint8Array): void;
@@ -35,12 +63,19 @@ export interface TerminalStreamSubscriber {
 }
 
 export interface TerminalStreamHandle {
-  backfill(cols?: number, rows?: number): TerminalSnapshot;
+  backfill(cols?: number, rows?: number): Promise<TerminalSnapshot>;
   write(bytes: Uint8Array): void;
   resize(cols: number, rows: number): void;
   release(): void;
 }
 
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+const TERMINAL_DEBUG = process.env.AGENT_RELAY_TERMINAL_DEBUG === "1";
+function tdbg(...args: unknown[]): void {
+  if (TERMINAL_DEBUG) console.error("[term-debug]", ...args);
+}
+
 // --- Pure protocol helpers (unit-tested) ---
 
 // Decode a tmux control-mode `%output` payload: printable ASCII is literal, every
@@ -104,6 +139,44 @@ export function encodeSendKeysHex(bytes: Uint8Array): string {
     .join(" ");
 }
 
+// Build a client repaint from tmux's current-screen grid: lay the rows out top-down
+// (explicit CRLF so it's independent of the client's convertEol), then park the cursor
+// where tmux has it so the next live relative delta continues from the right cell.
+export function buildScreenRepaint(content: string, cursorX?: number, cursorY?: number): string {
+  let out = content.replace(/\n$/, "").replace(/\n/g, "\r\n");
+  if (cursorX != null && cursorY != null && Number.isFinite(cursorX) && Number.isFinite(cursorY)) {
+    out += `\x1b[${cursorY + 1};${cursorX + 1}H`;
+  }
+  return out;
+}
+
+// Build an in-place authoritative repaint that overwrites the client grid with tmux's
+// current screen WITHOUT a full-screen clear (so it can run mid-stream as a drift
+// corrector without flicker). Each row is absolute-positioned, SGR-reset, and erased
+// (`\x1b[2K`) before its styled cells are written, so any drift — a doubled statusline, a
+// suggestion stuck solid instead of faded, leftover cells — is stamped out. The cursor is
+// re-parked at tmux's true position and visibility restored. Wrapped in cursor-hide/show
+// so the multi-row paint doesn't visibly skitter the cursor across the screen.
+export function buildInPlaceRepaint(
+  content: string,
+  rows: number,
+  cursor: { cursorX?: number; cursorY?: number; visible?: boolean } = {},
+): string {
+  const lines = content.replace(/\n$/, "").split("\n");
+  const height = Number.isFinite(rows) && rows > 0 ? Math.trunc(rows) : lines.length;
+  let out = "\x1b[?25l\x1b[m";
+  for (let i = 0; i < height; i++) {
+    out += `\x1b[${i + 1};1H\x1b[m\x1b[2K`;
+    if (lines[i]) out += lines[i];
+  }
+  out += "\x1b[m";
+  if (cursor.cursorX != null && cursor.cursorY != null && Number.isFinite(cursor.cursorX) && Number.isFinite(cursor.cursorY)) {
+    out += `\x1b[${cursor.cursorY + 1};${cursor.cursorX + 1}H`;
+  }
+  out += cursor.visible === false ? "\x1b[?25l" : "\x1b[?25h";
+  return out;
+}
+
 // --- Shared session stream ---
 
 class SessionStream {
@@ -114,6 +187,14 @@ class SessionStream {
   private flushTimer: ReturnType<typeof setTimeout> | null = null;
   private lineBuf = "";
   private closed = false;
+  // Last size we resized the pane to / reported to viewers (tmux is the source of truth;
+  // these are just for redundant-resize avoidance and debug logging).
+  private termCols = DEFAULT_COLS;
+  private termRows = DEFAULT_ROWS;
+  // Drift corrector: re-stamp tmux's authoritative grid after live deltas settle.
+  private resyncTimer: ReturnType<typeof setTimeout> | null = null;
+  private resyncCapTimer: ReturnType<typeof setTimeout> | null = null;
+  private resyncDirty = false;
 
   constructor(
     private readonly session: string,
@@ -128,15 +209,17 @@ class SessionStream {
     this.socket = socket;
     // Pin the window size before attaching so the control client can't reflow the
     // pane (default window-size would shrink it to the new client's 80x24).
-    const snapshot = this.safeBackfill();
+    const dims = this.paneDims();
+    if (dims.cols) this.termCols = dims.cols;
+    if (dims.rows) this.termRows = dims.rows;
     Bun.spawnSync(tmuxCommand(socket, "set-window-option", "-t", this.session, "window-size", "manual"), {
       stdin: "ignore",
       stdout: "ignore",
       stderr: "ignore",
     });
-    if (snapshot?.cols && snapshot?.rows) {
+    if (dims.cols && dims.rows) {
       Bun.spawnSync(
-        tmuxCommand(socket, "resize-window", "-t", this.session, "-x", String(snapshot.cols), "-y", String(snapshot.rows)),
+        tmuxCommand(socket, "resize-window", "-t", this.session, "-x", String(dims.cols), "-y", String(dims.rows)),
         { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
       );
     }
@@ -213,6 +296,12 @@ class SessionStream {
     }
     this.pending = [];
     this.pendingBytes = 0;
+    this.broadcast(merged);
+    // Live deltas just went out; schedule an authoritative resync to correct any drift.
+    this.scheduleResync();
+  }
+
+  private broadcast(bytes: Uint8Array): void {
     for (const sub of [...this.subscribers]) {
       if (sub.bufferedAmount && sub.bufferedAmount() > BACKPRESSURE_MAX_BYTES) {
         this.removeSubscriber(sub);
@@ -222,31 +311,150 @@ class SessionStream {
         continue;
       }
       try {
-        sub.onData(merged);
+        sub.onData(bytes);
       } catch {}
     }
   }
 
-  private safeBackfill(): TerminalSnapshot | null {
-    try {
-      return captureTerminal(this.session, this.config);
-    } catch {
-      return null;
+  // Schedule a drift-correcting resync: a trailing debounce fires once output settles,
+  // and a capped interval guarantees correction during continuous output.
+  private scheduleResync(): void {
+    if (RESYNC_DEBOUNCE_MS <= 0 || this.subscribers.size === 0) return;
+    this.resyncDirty = true;
+    if (this.resyncTimer) clearTimeout(this.resyncTimer);
+    this.resyncTimer = setTimeout(() => this.doResync(), RESYNC_DEBOUNCE_MS);
+    if (!this.resyncCapTimer && RESYNC_MAX_INTERVAL_MS > 0) {
+      this.resyncCapTimer = setTimeout(() => this.doResync(), RESYNC_MAX_INTERVAL_MS);
+    }
+  }
+
+  private doResync(): void {
+    if (this.resyncTimer) {
+      clearTimeout(this.resyncTimer);
+      this.resyncTimer = null;
+    }
+    if (this.resyncCapTimer) {
+      clearTimeout(this.resyncCapTimer);
+      this.resyncCapTimer = null;
     }
+    if (!this.resyncDirty || this.closed) return;
+    this.resyncDirty = false;
+    if (this.subscribers.size === 0) return;
+    const repaint = this.resyncRepaint();
+    if (!repaint) return;
+    this.broadcast(repaint);
+    tdbg(`resync ${this.session} bytes=${repaint.length} viewers=${this.subscribers.size}`);
   }
 
-  // Capture the priming snapshot. When the viewer's dimensions are given, resize the
-  // tmux window to exactly that size *first* (synchronously) so the captured content
-  // wraps identically to the client's xterm — a width mismatch desyncs every
-  // absolute-positioned redraw the TUI emits and stacks ghost frames into scrollback.
-  backfill(cols?: number, rows?: number): TerminalSnapshot {
+  // Build an in-place authoritative repaint from tmux's grid: absolute-position each row,
+  // reset SGR + clear it, then write tmux's styled cells. This overwrites any drift (a
+  // doubled statusline, a solid-instead-of-faded suggestion, stale cells) without a
+  // full-screen clear flash, and re-parks the cursor at tmux's true position/visibility.
+  private resyncRepaint(): Uint8Array | null {
+    const body = this.readScreen();
+    if (!body) return null;
+    const cursor = this.readCursorState();
+    const rows = this.paneDims().rows ?? this.termRows;
+    return new TextEncoder().encode(buildInPlaceRepaint(body, rows, cursor));
+  }
+
+  // Read tmux's authoritative current-screen grid (styled, no scrollback) plus a
+  // consistent cursor position, and turn it into a client repaint. capture-pane reads
+  // tmux's real emulator grid, so it's always internally coherent; captureConsistent
+  // guards the (content, cursor) read against a mid-render cursor move.
+  private captureScreen(): { content: string; cursorX?: number; cursorY?: number } {
+    const { content, cursor } = captureConsistent(
+      () => this.readBackfill(),
+      () => this.readCursor(),
+    );
+    return { content: buildScreenRepaint(content, cursor.cursorX, cursor.cursorY), ...cursor };
+  }
+
+  // Backfill capture: current screen plus scrollback history above it (cursor is
+  // viewport-relative, so it still parks on the live screen). Falls back to screen-only.
+  private readBackfill(): string {
+    if (BACKFILL_SCROLLBACK_LINES <= 0) return this.readScreen();
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "capture-pane", "-p", "-e", "-S", `-${BACKFILL_SCROLLBACK_LINES}`, "-t", this.session),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    return r.exitCode === 0 ? r.stdout.toString("utf8") : this.readScreen();
+  }
+
+  // Current-screen-only capture (no scrollback) — used by the live resync corrector so it
+  // overwrites just the visible grid and leaves the client's scroll-back history intact.
+  private readScreen(): string {
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "capture-pane", "-p", "-e", "-t", this.session),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    return r.exitCode === 0 ? r.stdout.toString("utf8") : "";
+  }
+
+  private readCursor(): { cursorX?: number; cursorY?: number } {
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{cursor_x} #{cursor_y}"),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    const [x, y] = r.stdout.toString().trim().split(/\s+/).map(Number);
+    return {
+      ...(Number.isFinite(x) ? { cursorX: x } : {}),
+      ...(Number.isFinite(y) ? { cursorY: y } : {}),
+    };
+  }
+
+  // Cursor position plus visibility (cursor_flag), so a resync repaint restores whether
+  // the TUI had the cursor shown or hidden rather than guessing.
+  private readCursorState(): { cursorX?: number; cursorY?: number; visible?: boolean } {
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{cursor_x} #{cursor_y} #{cursor_flag}"),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    const [x, y, flag] = r.stdout.toString().trim().split(/\s+/);
+    const cx = Number(x);
+    const cy = Number(y);
+    return {
+      ...(Number.isFinite(cx) ? { cursorX: cx } : {}),
+      ...(Number.isFinite(cy) ? { cursorY: cy } : {}),
+      ...(flag === "0" || flag === "1" ? { visible: flag === "1" } : {}),
+    };
+  }
+
+  // Repaint a freshly-attached (or resumed/refreshed) viewer from tmux's current grid.
+  // When the viewer's dimensions are given we resize the tmux pane first so the TUI
+  // re-renders at the viewer's width, let it settle, then capture the post-resize frame.
+  async backfill(cols?: number, rows?: number): Promise<TerminalSnapshot> {
+    let resized = false;
     if (Number.isFinite(cols) && Number.isFinite(rows) && (cols as number) >= 10 && (rows as number) >= 5) {
-      Bun.spawnSync(
-        tmuxCommand(this.socket, "resize-window", "-t", this.session, "-x", String(Math.trunc(cols as number)), "-y", String(Math.trunc(rows as number))),
-        { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
-      );
+      const c = Math.trunc(cols as number);
+      const r = Math.trunc(rows as number);
+      if (c !== this.termCols || r !== this.termRows) {
+        Bun.spawnSync(
+          tmuxCommand(this.socket, "resize-window", "-t", this.session, "-x", String(c), "-y", String(r)),
+          { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
+        );
+        this.termCols = c;
+        this.termRows = r;
+        resized = true;
+      }
     }
-    return captureTerminal(this.session, this.config);
+    if (resized && RESIZE_SETTLE_MS > 0) await Bun.sleep(RESIZE_SETTLE_MS);
+    const { content } = this.captureScreen();
+    // Report tmux's actual pane size (authoritative) back to the viewer.
+    const dims = this.paneDims();
+    if (dims.cols) this.termCols = dims.cols;
+    if (dims.rows) this.termRows = dims.rows;
+    const live = sessionLiveness(this.session);
+    tdbg(`backfill ${this.session} req=${cols}x${rows} term=${this.termCols}x${this.termRows} contentLen=${content.length} viewers=${this.subscribers.size}`);
+    return {
+      session: this.session,
+      content,
+      running: live.running,
+      agentAlive: live.agentAlive,
+      cols: this.termCols,
+      rows: this.termRows,
+      capturedAt: Date.now(),
+    };
   }
 
   write(bytes: Uint8Array): void {
@@ -257,7 +465,28 @@ class SessionStream {
   resize(cols: number, rows: number): void {
     if (this.closed || !this.proc) return;
     if (!Number.isFinite(cols) || !Number.isFinite(rows) || cols < 10 || rows < 5) return;
-    this.command(`resize-window -t "${this.session}" -x ${Math.trunc(cols)} -y ${Math.trunc(rows)}`);
+    const c = Math.trunc(cols);
+    const r = Math.trunc(rows);
+    this.command(`resize-window -t "${this.session}" -x ${c} -y ${r}`);
+    this.termCols = c;
+    this.termRows = r;
+    tdbg(`resize ${this.session} -> ${c}x${r} viewers=${this.subscribers.size}`);
+  }
+
+  private paneDims(): { cols?: number; rows?: number } {
+    try {
+      const out = Bun.spawnSync(
+        tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{pane_width} #{pane_height}"),
+        { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+      ).stdout.toString().trim();
+      const [w, h] = out.split(/\s+/).map(Number);
+      return {
+        ...(w !== undefined && Number.isFinite(w) && w > 0 ? { cols: w } : {}),
+        ...(h !== undefined && Number.isFinite(h) && h > 0 ? { rows: h } : {}),
+      };
+    } catch {
+      return {};
+    }
   }
 
   private command(line: string): void {
@@ -271,10 +500,12 @@ class SessionStream {
 
   addSubscriber(sub: TerminalStreamSubscriber): void {
     this.subscribers.add(sub);
+    tdbg(`attach ${this.session} viewers=${this.subscribers.size} term=${this.termCols}x${this.termRows}`);
   }
 
   removeSubscriber(sub: TerminalStreamSubscriber): void {
     if (!this.subscribers.delete(sub)) return;
+    tdbg(`detach ${this.session} viewers=${this.subscribers.size}`);
     if (this.subscribers.size === 0) this.destroy();
   }
 
@@ -297,6 +528,14 @@ class SessionStream {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
     }
+    if (this.resyncTimer !== null) {
+      clearTimeout(this.resyncTimer);
+      this.resyncTimer = null;
+    }
+    if (this.resyncCapTimer !== null) {
+      clearTimeout(this.resyncCapTimer);
+      this.resyncCapTimer = null;
+    }
     try {
       this.proc?.kill();
     } catch {}