agent-relay-orchestrator 0.10.25 → 0.10.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.10.25",
+  "version": "0.10.26",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {

package/src/api.ts

@@ -590,38 +590,84 @@ function startTerminalSocket(ws: TerminalSocket): void {
     ws.data.stream = acquireTerminalStream(ws.data.session, ws.data.config, subscriber);
     // Wait for the client's resize to size the pane before backfilling. Fall back to
     // the pane's current size if no resize arrives (e.g. a non-fitting client).
-    ws.data.syncTimer = setTimeout(() => syncAndBackfill(ws), 700);
+    ws.data.syncTimer = setTimeout(() => {
+      if (!ws.data.synced) void syncAndBackfill(ws);
+    }, 700);
   } catch (e) {
     ws.send(JSON.stringify({ type: "error", error: e instanceof Error ? e.message : String(e) }));
     ws.close();
   }
 }
 
+// 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 already reflects every byte emitted up to the capture moment.
-// The capture is synchronous (spawnSync), so no live byte is processed during it —
-// which means the queued bytes are all PRE-capture and already baked into the snapshot.
-// Replaying them would double-apply every delta and stack a garbled ghost frame, so we
-// discard the queue here and only forward bytes that arrive after the capture.
-function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number): void {
+// 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.
+async function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
   if (ws.data.syncTimer) {
     clearTimeout(ws.data.syncTimer);
     ws.data.syncTimer = undefined;
   }
+  if (ws.data.synced) return;
   ws.data.synced = true;
-  sendBackfill(ws, cols, rows);
+  await sendBackfill(ws, cols, rows);
   ws.data.queue = [];
   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.
-function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number): void {
+async function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
   const stream = ws.data.stream;
   if (!stream) return;
-  const snapshot = stream.backfill(cols, rows);
+  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
   ws.send(JSON.stringify({
     type: "reset",
     session: snapshot.session,
@@ -670,16 +716,16 @@ function handleTerminalSocketMessage(ws: TerminalSocket, data: string | Buffer):
       // First resize sizes the pane and triggers the (size-matched) backfill;
       // later ones just reflow the live stream.
       if (!ws.data.synced) {
-        syncAndBackfill(ws, cols, rows);
+        void syncAndBackfill(ws, cols, rows);
       } else {
         ws.data.stream?.resize(cols, rows);
       }
     } else if (frame.type === "pause") {
       ws.data.paused = frame.paused === true;
       // We drop (not buffer) bytes while paused, so resync with a fresh backfill.
-      if (!ws.data.paused && ws.data.synced) sendBackfill(ws);
+      if (!ws.data.paused && ws.data.synced) void sendBackfill(ws);
     } else if (frame.type === "refresh") {
-      if (ws.data.synced) sendBackfill(ws);
+      if (ws.data.synced) void sendBackfill(ws);
     }
   } catch (e) {
     ws.send(JSON.stringify({ type: "error", error: e instanceof Error ? e.message : String(e) }));