agent-relay-orchestrator 0.10.25 → 0.10.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.10.25",
+  "version": "0.10.27",
   "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) }));

package/src/spawn.ts

@@ -962,20 +962,14 @@ export function captureTerminal(name: string, config: OrchestratorConfig): Termi
   }
 
   const size = tmuxPaneSize(name, socketName);
-  const cursor = tmuxCursorPos(name, socketName);
-  const result = Bun.spawnSync(tmuxCommand(socketName, "capture-pane", "-p", "-e", "-S", "-1000", "-t", name), {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  if (result.exitCode !== 0) {
-    const stderr = result.stderr.toString().trim();
-    throw new Error(stderr || `tmux capture-pane failed with exit code ${result.exitCode}`);
-  }
+  const { content, cursor } = captureConsistent(
+    () => captureContent(name, socketName),
+    () => tmuxCursorPos(name, socketName),
+  );
 
   return {
     session: name,
-    content: result.stdout.toString(),
+    content,
     running: true,
     agentAlive,
     ...size,
@@ -984,6 +978,42 @@ export function captureTerminal(name: string, config: OrchestratorConfig): Termi
   };
 }
 
+// Capture cursor and content *consistently*. They come from separate tmux invocations,
+// so if the pane scrolls between them (e.g. tool output streaming while the agent
+// "thinks"), cursorY ends up off-by-one against the captured grid — the parked cursor
+// then lands a row off and the TUI's next relative redraw stacks a stale statusline row
+// (bottom-box ghost). Read content, then cursor, then content again; accept only when the
+// two content reads bracket the cursor read unchanged, which proves the cursor reflects
+// that exact grid. Fall through with the latest capture if the pane never holds still.
+export function captureConsistent(
+  readContent: () => string,
+  readCursor: () => { cursorX?: number; cursorY?: number },
+  maxAttempts = 4,
+): { content: string; cursor: { cursorX?: number; cursorY?: number } } {
+  let content = readContent();
+  let cursor = readCursor();
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const recheck = readContent();
+    if (recheck === content) break;
+    content = recheck;
+    cursor = readCursor();
+  }
+  return { content, cursor };
+}
+
+function captureContent(name: string, socketName?: string): string {
+  const result = Bun.spawnSync(tmuxCommand(socketName, "capture-pane", "-p", "-e", "-S", "-1000", "-t", name), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(stderr || `tmux capture-pane failed with exit code ${result.exitCode}`);
+  }
+  return result.stdout.toString();
+}
+
 export function terminalInputTokens(data: string): TerminalInputToken[] {
   const tokens: TerminalInputToken[] = [];
   let literal = "";