Guard SSH PTY resize dimensions

Author: tolluset

docs/solutions/runtime-errors/ssh-pty-zero-size-window-change.md

@@ -0,0 +1,35 @@
+---
+module: SSH Gateway
+date: 2026-03-09
+problem_type: runtime_error
+component: tooling
+symptoms:
+  - "The terminal client crashed only when connected through `ssh pxpx.sh`."
+  - "Resizing the SSH terminal could terminate the session with a renderer resize error."
+root_cause: async_timing
+resolution_type: code_fix
+severity: high
+tags: [ssh-gateway, pty, window-change, terminal-resize, opentui]
+---
+
+# SSH PTY Zero-Size Window Change
+
+## Context
+The terminal client stayed stable locally, but users could crash the session when resizing an SSH-backed `pxpx.sh` terminal.
+
+## Problem
+During SSH `window-change`, some terminals can briefly report invalid PTY dimensions such as `0x0`. The gateway forwarded those values to the child PTY runner, which then propagated them to the OpenTUI client. OpenTUI rejects framebuffer resizes at `0` width or height and aborts.
+
+## Working Solution
+- Added `sanitizePtyWindow` and `sanitizePtyInfo` in `src/ssh-gateway/pty.ts`
+- Sanitized initial PTY dimensions before launching the interactive child
+- Sanitized every SSH `window-change` event before forwarding it
+- Preserved the last valid PTY size when a resize event reported invalid dimensions
+- Added regression tests in `tests/ssh-gateway/pty.test.ts`
+
+## Key Insight
+This was not a generic client-side resize bug. The failure path was specific to the SSH PTY bridge, where transient invalid sizes can appear during interactive terminal resizes.
+
+## Verification
+- Ran `bun test tests/ssh-gateway/*.test.ts`
+- Ran `pnpm typecheck`

src/ssh-gateway/child-process.ts

@@ -4,6 +4,7 @@ import { resolveCommandPlan } from "./command-plan";
 import type { GatewayConfig } from "./config";
 import { formatGatewayError } from "./errors";
 import { acquireControlChannel } from "./control-channel";
+import { sanitizePtyWindow } from "./pty";
 import { buildRunnerEnvironment, buildSpawnOptions } from "./runner-env";
 import type { AuthIdentity, CommandPlan, ExecutionHandle, PtyState, UserAccount } from "./types";
 import type { PseudoTtyInfo, ServerChannel } from "ssh2";
@@ -88,15 +89,16 @@ export function launchInteractiveCommand(
   account: UserAccount,
   ptyInfo: PseudoTtyInfo,
 ): ExecutionHandle {
+  const window = sanitizePtyWindow(ptyInfo.rows, ptyInfo.cols);
   const env = buildRunnerEnvironment(config, identity, account, (ptyInfo as PtyState).term ?? "xterm-256color");
   const scope = Effect.runSync(Scope.make());
-  const control = Effect.runSync(Scope.extend(acquireControlChannel(ptyInfo.rows, ptyInfo.cols), scope));
+  const control = Effect.runSync(Scope.extend(acquireControlChannel(window.rows, window.cols), scope));
   const runnerArgs = [
     config.runner,
     "--rows",
-    String(ptyInfo.rows),
+    String(window.rows),
     "--cols",
-    String(ptyInfo.cols),
+    String(window.cols),
     "--cwd",
     config.workdir,
     "--uid",

src/ssh-gateway/control-channel.ts

@@ -3,6 +3,7 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { Effect } from "effect";
+import { sanitizePtyWindow } from "./pty";
 import type { ControlChannel } from "./types";
 
 export function createControlChannel(initialRows: number, initialCols: number): ControlChannel {
@@ -12,7 +13,8 @@ export function createControlChannel(initialRows: number, initialCols: number):
   );
   const server = net.createServer();
   let controlSocket: net.Socket | null = null;
-  let pendingWindow = `${initialRows} ${initialCols}\n`;
+  let currentWindow = sanitizePtyWindow(initialRows, initialCols);
+  let pendingWindow = `${currentWindow.rows} ${currentWindow.cols}\n`;
 
   server.on("connection", (socket) => {
     controlSocket = socket;
@@ -38,7 +40,8 @@ export function createControlChannel(initialRows: number, initialCols: number):
       rmSync(socketPath, { force: true });
     },
     updateWindow(rows, cols) {
-      const payload = `${rows} ${cols}\n`;
+      currentWindow = sanitizePtyWindow(rows, cols, currentWindow);
+      const payload = `${currentWindow.rows} ${currentWindow.cols}\n`;
 
       if (controlSocket) {
         controlSocket.write(payload);

src/ssh-gateway/pty.ts

@@ -0,0 +1,43 @@
+import type { PseudoTtyInfo } from "ssh2";
+
+const DEFAULT_PTY_ROWS = 24;
+const DEFAULT_PTY_COLS = 80;
+
+function sanitizeDimension(value: number, fallback: number) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+
+  return Math.floor(value);
+}
+
+export function sanitizePtyWindow(
+  rows: number,
+  cols: number,
+  fallback?: {
+    rows?: number;
+    cols?: number;
+  },
+) {
+  const safeFallbackRows = sanitizeDimension(fallback?.rows ?? DEFAULT_PTY_ROWS, DEFAULT_PTY_ROWS);
+  const safeFallbackCols = sanitizeDimension(fallback?.cols ?? DEFAULT_PTY_COLS, DEFAULT_PTY_COLS);
+
+  return {
+    rows: sanitizeDimension(rows, safeFallbackRows),
+    cols: sanitizeDimension(cols, safeFallbackCols),
+  };
+}
+
+export function sanitizePtyInfo(info: PseudoTtyInfo, fallback?: Partial<PseudoTtyInfo>): PseudoTtyInfo {
+  const window = sanitizePtyWindow(info.rows, info.cols, {
+    rows: fallback?.rows,
+    cols: fallback?.cols,
+  });
+
+  return {
+    ...(fallback ?? {}),
+    ...info,
+    rows: window.rows,
+    cols: window.cols,
+  };
+}

src/ssh-gateway/session.ts

@@ -1,5 +1,6 @@
 import type { Connection, ExecInfo, PseudoTtyInfo } from "ssh2";
 import { handleExecution } from "./child-process";
+import { sanitizePtyInfo } from "./pty";
 import type { AuthIdentity, ExecutionHandle, UserAccount } from "./types";
 import type { GatewayConfig } from "./config";
 
@@ -31,12 +32,13 @@ export function attachSessionHandlers(
     let execution: ExecutionHandle = NOOP_EXECUTION_HANDLE;
 
     session.on("pty", (sessionAccept, _sessionReject, info) => {
-      ptyInfo = info;
+      ptyInfo = sanitizePtyInfo(info, ptyInfo ?? undefined);
       sessionAccept?.();
     });
 
     session.on("window-change", (sessionAccept, _sessionReject, info) => {
-      ptyInfo = {
+      ptyInfo = sanitizePtyInfo(
+        {
         ...(ptyInfo ?? {
           term: "xterm-256color",
           modes: {},
@@ -49,8 +51,10 @@ export function attachSessionHandlers(
         height: info.height,
         rows: info.rows,
         cols: info.cols,
-      };
-      execution.updateWindow(info.rows, info.cols);
+        },
+        ptyInfo ?? undefined,
+      );
+      execution.updateWindow(ptyInfo.rows, ptyInfo.cols);
       sessionAccept?.();
     });
 

tests/ssh-gateway/pty.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { sanitizePtyInfo, sanitizePtyWindow } from "../../src/ssh-gateway/pty";
+
+describe("sanitizePtyWindow", () => {
+  test("falls back to default dimensions for invalid initial sizes", () => {
+    expect(sanitizePtyWindow(0, 0)).toEqual({
+      rows: 24,
+      cols: 80,
+    });
+  });
+
+  test("preserves the previous valid size when a resize update is invalid", () => {
+    expect(
+      sanitizePtyWindow(0, -4, {
+        rows: 32,
+        cols: 120,
+      }),
+    ).toEqual({
+      rows: 32,
+      cols: 120,
+    });
+  });
+
+  test("keeps valid resize updates", () => {
+    expect(
+      sanitizePtyWindow(18, 90, {
+        rows: 32,
+        cols: 120,
+      }),
+    ).toEqual({
+      rows: 18,
+      cols: 90,
+    });
+  });
+});
+
+describe("sanitizePtyInfo", () => {
+  test("keeps previous rows and cols while updating the rest of the PTY metadata", () => {
+    expect(
+      sanitizePtyInfo(
+        {
+          term: "xterm-256color",
+          width: 1024,
+          height: 640,
+          rows: 0,
+          cols: 0,
+          modes: {},
+        },
+        {
+          term: "screen-256color",
+          width: 800,
+          height: 600,
+          rows: 28,
+          cols: 100,
+          modes: {},
+        },
+      ),
+    ).toEqual({
+      term: "xterm-256color",
+      width: 1024,
+      height: 640,
+      rows: 28,
+      cols: 100,
+      modes: {},
+    });
+  });
+});