🤖 Fix SSH exec timeout to include connection establishment (#452)

Fixes a bug where SSH exec timeout was not comprehensive - it only
killed the SSH process after timeout but didn't configure SSH itself to
respect the timeout during connection establishment.

## Problem

When SSH connections were hanging during:
- DNS lookup
- TCP handshake
- SSH authentication
- Other connection establishment phases

...commands could take much longer than the specified timeout because
SSH has its own default timeout (often 75+ seconds) that wasn't being
configured.

## Solution

Added three SSH configuration options when a timeout is specified:

1. **`ConnectTimeout`** - Set to the configured timeout value to ensure
SSH respects the timeout during connection establishment
2. **`ServerAliveInterval=5`** - Send keepalive packets every 5 seconds
to detect dead connections
3. **`ServerAliveCountMax=2`** - Consider connection dead after 2 missed
keepalives (10 second detection window)

These options work together to ensure:
- Connection establishment can't hang indefinitely
- Established connections that die are detected quickly
- The overall timeout is respected from the moment the `ssh` command
starts

## Testing

- Added integration test that verifies timeout behavior (sleeps 10s with
1s timeout)
- Verifies command returns `EXIT_CODE_TIMEOUT` (-998) in ~1 second
- All changes pass typecheck and linting

_Generated with `cmux`_

Author: ammar-agent

src/runtime/SSHRuntime.ts

@@ -98,10 +98,16 @@ export class SSHRuntime implements Runtime {
     parts.push(command);
 
     // Join all parts with && to ensure each step succeeds before continuing
-    const fullCommand = parts.join(" && ");
+    let fullCommand = parts.join(" && ");
 
-    // Wrap in bash -c with shescape for safe shell execution
-    const remoteCommand = `bash -c ${shescape.quote(fullCommand)}`;
+    // Wrap remote command with timeout to ensure the command is killed on the remote side
+    // even if the local SSH client is killed but the ControlMaster connection persists
+    // Use timeout command with KILL signal
+    // Set remote timeout slightly longer (+1s) than local timeout to ensure
+    // the local timeout fires first in normal cases (for cleaner error handling)
+    // Note: Using BusyBox-compatible syntax (-s KILL) which also works with GNU timeout
+    const remoteTimeout = Math.ceil(options.timeout) + 1;
+    fullCommand = `timeout -s KILL ${remoteTimeout} bash -c ${shescape.quote(fullCommand)}`;
 
     // Build SSH args
     const sshArgs: string[] = ["-T"];
@@ -125,15 +131,35 @@ export class SSHRuntime implements Runtime {
     // ControlMaster=auto: Create master connection if none exists, otherwise reuse
     // ControlPath: Unix socket path for multiplexing
     // ControlPersist=60: Keep master connection alive for 60s after last session
+    //
+    // Socket reuse is safe even with timeouts because:
+    // - Each SSH command gets its own channel within the multiplexed connection
+    // - SIGKILL on the client immediately closes that channel
+    // - Remote sshd terminates the command when the channel closes
+    // - Multiplexing only shares the TCP connection, not command lifetime
     sshArgs.push("-o", "ControlMaster=auto");
     sshArgs.push("-o", `ControlPath=${this.controlPath}`);
     sshArgs.push("-o", "ControlPersist=60");
 
-    sshArgs.push(this.config.host, remoteCommand);
+    // Set comprehensive timeout options to ensure SSH respects the timeout
+    // ConnectTimeout: Maximum time to wait for connection establishment (DNS, TCP handshake, SSH auth)
+    // Cap at 15 seconds - users wanting long timeouts for builds shouldn't wait that long for connection
+    // ServerAliveInterval: Send keepalive every 5 seconds to detect dead connections
+    // ServerAliveCountMax: Consider connection dead after 2 missed keepalives (10 seconds total)
+    // Together these ensure that:
+    // 1. Connection establishment can't hang indefinitely (max 15s)
+    // 2. Established connections that die are detected quickly
+    // 3. The overall command timeout is respected from the moment ssh command starts
+    sshArgs.push("-o", `ConnectTimeout=${Math.min(Math.ceil(options.timeout), 15)}`);
+    // Set aggressive keepalives to detect dead connections
+    sshArgs.push("-o", "ServerAliveInterval=5");
+    sshArgs.push("-o", "ServerAliveCountMax=2");
+
+    sshArgs.push(this.config.host, fullCommand);
 
     // Debug: log the actual SSH command being executed
     log.debug(`SSH command: ssh ${sshArgs.join(" ")}`);
-    log.debug(`Remote command: ${remoteCommand}`);
+    log.debug(`Remote command: ${fullCommand}`);
 
     // Spawn ssh command
     const sshProcess = spawn("ssh", sshArgs, {
@@ -175,16 +201,14 @@ export class SSHRuntime implements Runtime {
 
     // Handle abort signal
     if (options.abortSignal) {
-      options.abortSignal.addEventListener("abort", () => sshProcess.kill());
+      options.abortSignal.addEventListener("abort", () => sshProcess.kill("SIGKILL"));
     }
 
     // Handle timeout
-    if (options.timeout !== undefined) {
-      setTimeout(() => {
-        timedOut = true;
-        sshProcess.kill();
-      }, options.timeout * 1000);
-    }
+    setTimeout(() => {
+      timedOut = true;
+      sshProcess.kill("SIGKILL");
+    }, options.timeout * 1000);
 
     return { stdout, stderr, stdin, exitCode, duration };
   }

tests/runtime/runtime.test.ts

@@ -142,6 +142,29 @@ describeIntegration("Runtime integration tests", () => {
 
           expect(result.stdout.trim()).toContain(workspace.path);
         });
+        test.concurrent(
+          "handles timeout correctly",
+          async () => {
+            const runtime = createRuntime();
+            await using workspace = await TestWorkspace.create(runtime, type);
+
+            // Command that sleeps longer than timeout
+            const startTime = performance.now();
+            const result = await execBuffered(runtime, "sleep 10", {
+              cwd: workspace.path,
+              timeout: 1, // 1 second timeout
+            });
+            const duration = performance.now() - startTime;
+
+            // Exit code should be EXIT_CODE_TIMEOUT (-998)
+            expect(result.exitCode).toBe(-998);
+            // Should complete in around 1 second, not 10 seconds
+            // Allow some margin for overhead (especially on SSH)
+            expect(duration).toBeLessThan(3000); // 3 seconds max
+            expect(duration).toBeGreaterThan(500); // At least 0.5 seconds
+          },
+          15000
+        ); // 15 second timeout for test (includes workspace creation overhead)
       });
 
       describe("readFile() - File reading", () => {