🤖 fix: eliminate terminal resize race condition (#1538)

The previous approach resized the frontend terminal immediately but
debounced the PTY resize by 300ms. During that window, shell output
formatted for the old dimensions would display incorrectly in the
already-resized frontend terminal, causing text clobbering.

**Symptoms:** Output from commands like `git status --stat` would have
columns bleeding into each other - e.g., diff stats appearing mid-line,
"modified" becoming "commodified" as text from different areas
overlapped.

**Root cause:** Frontend `fitAddon.fit()` ran immediately on resize, but
`router.resize()` was debounced by 300ms. During that 300ms window, the
shell formatted output for the old PTY dimensions while the frontend
displayed it at the new dimensions.

**Fix:** Use `requestAnimationFrame` to batch resize events, then resize
both frontend and PTY in the same tick. This eliminates the window where
sizes can diverge.

- Simpler code (no setTimeout, no pendingResize state)
- Natural batching via RAF (coalesces rapid resize events)
- No race between frontend and PTY dimensions

---
_Generated with `mux` • Model: `anthropic:claude-opus-4-5` • Thinking:
`high` • Cost: $3.75_

Author: ammar-agent

src/browser/components/TerminalView.tsx

@@ -118,7 +118,7 @@ export function TerminalView({
 
     // Send initial resize to sync PTY dimensions
     const { cols, rows } = term;
-    router.resize(sessionId, cols, rows);
+    void router.resize(sessionId, cols, rows);
 
     return unsubscribe;
   }, [visible, terminalReady, sessionId, router]);
@@ -322,54 +322,84 @@ export function TerminalView({
 
     let lastCols = 0;
     let lastRows = 0;
-    let resizeTimeoutId: ReturnType<typeof setTimeout> | null = null;
-    let pendingResize: { cols: number; rows: number } | null = null;
+    let resizeInFlight = false;
+    let pendingResize = false;
+    let rafId: number | null = null;
+    let disposed = false;
+
+    // PTY-first resize: calculate desired dimensions, resize the PTY, then resize the
+    // frontend terminal to match.
+    //
+    // This eliminates the race that causes output clobbering when the frontend resizes
+    // before the PTY (shell output is formatted for old dimensions but displayed in the
+    // already-resized frontend terminal).
+    const doResize = async () => {
+      if (!fitAddonRef.current) return;
+
+      // Calculate what size we want without applying it yet.
+      // (fit() would resize the frontend immediately, reintroducing the race.)
+      const proposed = fitAddonRef.current.proposeDimensions();
+      if (!proposed) return;
+
+      const { cols, rows } = proposed;
+      if (cols === lastCols && rows === lastRows) return;
+
+      // Record the requested dimensions up front so we don't re-request the same resize
+      // if more resize events arrive while awaiting the backend.
+      lastCols = cols;
+      lastRows = rows;
 
-    // Use both ResizeObserver (for container changes) and window resize (as backup)
-    const handleResize = () => {
-      if (fitAddonRef.current && termRef.current) {
-        try {
-          // Resize terminal UI to fit container immediately for responsive UX
-          fitAddonRef.current.fit();
+      try {
+        // Resize PTY first - wait for backend to confirm.
+        await router.resize(sessionId, cols, rows);
 
-          // Get new dimensions
-          const { cols, rows } = termRef.current;
+        if (disposed) {
+          return;
+        }
 
-          // Only process if dimensions actually changed
-          if (cols === lastCols && rows === lastRows) {
-            return;
-          }
+        // Now resize frontend to match the PTY *exactly*.
+        // We intentionally do NOT call fit() here because it can recompute dimensions
+        // (if the container changed while awaiting) and would resize the frontend without
+        // resizing the PTY, reintroducing the mismatch.
+        termRef.current?.resize(cols, rows);
+      } catch (err) {
+        // Allow future retries if the resize call failed.
+        lastCols = 0;
+        lastRows = 0;
+        console.error("[TerminalView] Error resizing terminal:", err);
+      }
+    };
 
-          lastCols = cols;
-          lastRows = rows;
+    const handleResize = () => {
+      if (disposed) {
+        return;
+      }
 
-          // Store pending resize
-          pendingResize = { cols, rows };
+      // If a resize is already in flight, mark that we need another one
+      if (resizeInFlight) {
+        pendingResize = true;
+        return;
+      }
 
-          // Always debounce PTY resize to prevent vim corruption
-          // Clear any pending timeout and set a new one
-          if (resizeTimeoutId !== null) {
-            clearTimeout(resizeTimeoutId);
-          }
+      resizeInFlight = true;
+      pendingResize = false;
 
-          resizeTimeoutId = setTimeout(() => {
-            if (pendingResize) {
-              // Double requestAnimationFrame to ensure vim is ready
-              requestAnimationFrame(() => {
-                requestAnimationFrame(() => {
-                  if (pendingResize) {
-                    router.resize(sessionId, pendingResize.cols, pendingResize.rows);
-                    pendingResize = null;
-                  }
-                });
-              });
-            }
-            resizeTimeoutId = null;
-          }, 300); // 300ms debounce - enough time for vim to stabilize
-        } catch (err) {
-          console.error("[TerminalView] Error fitting terminal:", err);
-        }
+      // Use RAF to batch rapid resize events (e.g., window drag)
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId);
       }
+
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+
+        void doResize().finally(() => {
+          resizeInFlight = false;
+          // If another resize was requested while we were busy, handle it
+          if (pendingResize) {
+            handleResize();
+          }
+        });
+      });
     };
 
     const resizeObserver = new ResizeObserver(handleResize);
@@ -379,8 +409,9 @@ export function TerminalView({
     window.addEventListener("resize", handleResize);
 
     return () => {
-      if (resizeTimeoutId !== null) {
-        clearTimeout(resizeTimeoutId);
+      disposed = true;
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId);
       }
       resizeObserver.disconnect();
       window.removeEventListener("resize", handleResize);

src/browser/terminal/TerminalSessionRouter.ts

@@ -149,9 +149,12 @@ export class TerminalSessionRouter {
 
   /**
    * Resize a terminal session.
+   *
+   * Returns a promise that resolves when the backend handler has completed.
+   * (This is used by TerminalView to keep frontend and PTY dimensions in sync.)
    */
-  resize(sessionId: string, cols: number, rows: number): void {
-    void this.api.terminal.resize({ sessionId, cols, rows });
+  resize(sessionId: string, cols: number, rows: number): Promise<void> {
+    return this.api.terminal.resize({ sessionId, cols, rows });
   }
 
   /**