🤖 fix: spawn local PTY terminals on Windows (#1622)

This fixes embedded terminal creation on Windows failing with:

- `Failed to spawn Local terminal: File not found:`

Root cause was `PTYService` using `process.env.SHELL ?? "/bin/bash"` for
*local* PTY sessions. On Windows this can be unset, invalid, or even
present-but-empty (`SHELL=""`), which results in node-pty attempting to
spawn an empty executable.

### What changed
- Added `resolveLocalPtyShell()` to pick a sane default shell per
platform.
- Windows: prefer Git Bash (if available), else `pwsh` → `powershell` →
`COMSPEC`/`cmd.exe`
- Non-Windows: prefer non-empty `SHELL`, else `/bin/zsh` (macOS) or
`/bin/bash`
- `PTYService` local sessions now use the resolver and include args
(e.g. `--login -i` for Git Bash).
- Improved PTY spawn failures to include the attempted
command/args/cwd/platform (and preserve the original error as `cause`).

### Validation
- `bun test src/node/utils/main/resolveLocalPtyShell.test.ts`
- `make static-check`

---
_Generated with `mux` • Model: `openai:gpt-5.2` • Thinking: `xhigh` •
Cost: `$2.00`_

Author: ibetitsmike

src/node/services/ptyService.ts

@@ -21,6 +21,7 @@ import { DockerRuntime } from "@/node/runtime/DockerRuntime";
 import { access } from "fs/promises";
 import { constants } from "fs";
 import { getControlPath, sshConnectionPool } from "@/node/runtime/sshConnectionPool";
+import { resolveLocalPtyShell } from "@/node/utils/main/resolveLocalPtyShell";
 import { expandTildeForSSH } from "@/node/runtime/tildeExpansion";
 
 interface SessionData {
@@ -180,12 +181,19 @@ export class PTYService {
       } catch {
         throw new Error(`Workspace path does not exist: ${workspacePath}`);
       }
-      const shell = process.env.SHELL ?? "/bin/bash";
-      spawnConfig = { command: shell, args: [], cwd: workspacePath };
+      const shell = resolveLocalPtyShell();
+      spawnConfig = { command: shell.command, args: shell.args, cwd: workspacePath };
+
+      if (!spawnConfig.command.trim()) {
+        throw new Error("Cannot spawn Local terminal: empty shell command");
+      }
+
+      const printableArgs = spawnConfig.args.length > 0 ? ` ${spawnConfig.args.join(" ")}` : "";
       log.info(
-        `Spawning PTY with shell: ${shell}, cwd: ${workspacePath}, size: ${params.cols}x${params.rows}`
+        `Spawning PTY: ${spawnConfig.command}${printableArgs}, cwd: ${workspacePath}, size: ${params.cols}x${params.rows}`
       );
-      log.debug(`PATH env: ${process.env.PATH ?? "undefined"}`);
+      log.debug(`process.env.SHELL: ${process.env.SHELL ?? "undefined"}`);
+      log.debug(`process.env.PATH: ${process.env.PATH ?? process.env.Path ?? "undefined"}`);
     } else if (runtime instanceof SSHRuntime) {
       const sshConfig = runtime.getConfig();
       // Ensure connection is healthy before spawning terminal
@@ -217,6 +225,11 @@ export class PTYService {
     // Load node-pty and spawn process
     // Local prefers node-pty (Electron rebuild), SSH/Docker prefer @lydell/node-pty (prebuilds)
     const isLocal = runtime instanceof LocalBaseRuntime;
+
+    const pathEnv =
+      process.env.PATH ??
+      process.env.Path ??
+      (process.platform === "win32" ? undefined : "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin");
     const pty = loadNodePty(runtimeType, isLocal);
     let ptyProcess: IPty;
     try {
@@ -228,19 +241,30 @@ export class PTYService {
         env: {
           ...process.env,
           TERM: "xterm-256color",
-          PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+          ...(pathEnv ? { PATH: pathEnv } : {}),
         },
       });
     } catch (err) {
       log.error(`[PTY] Failed to spawn ${runtimeType} terminal ${sessionId}:`, err);
+
+      const printableArgs = spawnConfig.args.length > 0 ? ` ${spawnConfig.args.join(" ")}` : "";
+      const cmd = `${spawnConfig.command}${printableArgs}`;
+      const details = `cmd="${cmd}", cwd="${spawnConfig.cwd}", platform="${process.platform}"`;
+      const errMessage = err instanceof Error ? err.message : String(err);
+
       if (isLocal) {
-        log.error(`Shell: ${spawnConfig.command}, CWD: ${spawnConfig.cwd}`);
+        log.error(`Local PTY spawn config: ${cmd} (cwd: ${spawnConfig.cwd})`);
         log.error(`process.env.SHELL: ${process.env.SHELL ?? "undefined"}`);
-        log.error(`process.env.PATH: ${process.env.PATH ?? "undefined"}`);
+        log.error(`process.env.PATH: ${process.env.PATH ?? process.env.Path ?? "undefined"}`);
       }
-      throw new Error(
-        `Failed to spawn ${runtimeType} terminal: ${err instanceof Error ? err.message : String(err)}`
-      );
+
+      if (err instanceof Error) {
+        throw new Error(`Failed to spawn ${runtimeType} terminal (${details}): ${errMessage}`, {
+          cause: err,
+        });
+      }
+
+      throw new Error(`Failed to spawn ${runtimeType} terminal (${details}): ${errMessage}`);
     }
 
     // Wire up handlers

src/node/utils/main/resolveLocalPtyShell.test.ts

@@ -0,0 +1,80 @@
+import { resolveLocalPtyShell } from "./resolveLocalPtyShell";
+
+describe("resolveLocalPtyShell", () => {
+  it("uses SHELL when it is set and non-empty", () => {
+    const result = resolveLocalPtyShell({
+      platform: "linux",
+      env: { SHELL: "  /usr/bin/fish  " },
+      isCommandAvailable: () => {
+        throw new Error("isCommandAvailable should not be called");
+      },
+      getBashPath: () => {
+        throw new Error("getBashPath should not be called");
+      },
+    });
+
+    expect(result).toEqual({ command: "/usr/bin/fish", args: [] });
+  });
+
+  it("on Windows, treats empty SHELL as unset and prefers Git Bash", () => {
+    const result = resolveLocalPtyShell({
+      platform: "win32",
+      env: { SHELL: "" },
+      isCommandAvailable: () => false,
+      getBashPath: () => "C:\\Program Files\\Git\\bin\\bash.exe",
+    });
+
+    expect(result).toEqual({
+      command: "C:\\Program Files\\Git\\bin\\bash.exe",
+      args: ["--login", "-i"],
+    });
+  });
+
+  it("on Windows, falls back to pwsh when Git Bash is unavailable", () => {
+    const result = resolveLocalPtyShell({
+      platform: "win32",
+      env: { SHELL: "" },
+      isCommandAvailable: (command) => command === "pwsh",
+      getBashPath: () => {
+        throw new Error("Git Bash not installed");
+      },
+    });
+
+    expect(result).toEqual({ command: "pwsh", args: [] });
+  });
+
+  it("on Windows, falls back to COMSPEC/cmd.exe when no other shells are available", () => {
+    const result = resolveLocalPtyShell({
+      platform: "win32",
+      env: { SHELL: "   ", COMSPEC: "C:\\Windows\\System32\\cmd.exe" },
+      isCommandAvailable: () => false,
+      getBashPath: () => {
+        throw new Error("Git Bash not installed");
+      },
+    });
+
+    expect(result).toEqual({ command: "C:\\Windows\\System32\\cmd.exe", args: [] });
+  });
+
+  it("on Linux, falls back to /bin/bash when SHELL is unset", () => {
+    const result = resolveLocalPtyShell({
+      platform: "linux",
+      env: {},
+      isCommandAvailable: () => false,
+      getBashPath: () => "bash",
+    });
+
+    expect(result).toEqual({ command: "/bin/bash", args: [] });
+  });
+
+  it("on macOS, falls back to /bin/zsh when SHELL is unset", () => {
+    const result = resolveLocalPtyShell({
+      platform: "darwin",
+      env: {},
+      isCommandAvailable: () => false,
+      getBashPath: () => "bash",
+    });
+
+    expect(result).toEqual({ command: "/bin/zsh", args: [] });
+  });
+});

src/node/utils/main/resolveLocalPtyShell.ts

@@ -0,0 +1,81 @@
+import { spawnSync } from "child_process";
+
+import { getBashPath } from "@/node/utils/main/bashPath";
+
+export interface ResolvedPtyShell {
+  command: string;
+  args: string[];
+}
+
+export interface ResolveLocalPtyShellParams {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  isCommandAvailable: (command: string) => boolean;
+  getBashPath: () => string;
+}
+
+function defaultIsCommandAvailable(platform: NodeJS.Platform): (command: string) => boolean {
+  return (command: string) => {
+    if (!command) return false;
+
+    try {
+      const result = spawnSync(platform === "win32" ? "where" : "which", [command], {
+        stdio: "ignore",
+      });
+      return result.status === 0;
+    } catch {
+      return false;
+    }
+  };
+}
+
+/**
+ * Resolve the best shell to use for a *local* PTY session.
+ *
+ * We keep this as a small, mostly-pure helper so it can be unit-tested without
+ * mutating `process.platform` / `process.env`.
+ */
+export function resolveLocalPtyShell(
+  params: Partial<ResolveLocalPtyShellParams> = {}
+): ResolvedPtyShell {
+  const platform = params.platform ?? process.platform;
+  const env = params.env ?? process.env;
+  const isCommandAvailable = params.isCommandAvailable ?? defaultIsCommandAvailable(platform);
+  const getBashPathFn = params.getBashPath ?? getBashPath;
+
+  // `process.env.SHELL` can be present-but-empty (""), especially in packaged apps.
+  // Treat empty/whitespace as "unset".
+  const envShell = env.SHELL?.trim();
+  if (envShell) {
+    return { command: envShell, args: [] };
+  }
+
+  if (platform === "win32") {
+    // Prefer Git Bash when available (works well with repo tooling).
+    try {
+      const bashPath = getBashPathFn().trim();
+      if (bashPath) {
+        return { command: bashPath, args: ["--login", "-i"] };
+      }
+    } catch {
+      // Git Bash not available; fall back to PowerShell / cmd.
+    }
+
+    if (isCommandAvailable("pwsh")) {
+      return { command: "pwsh", args: [] };
+    }
+
+    if (isCommandAvailable("powershell")) {
+      return { command: "powershell", args: [] };
+    }
+
+    const comspec = env.COMSPEC?.trim();
+    return { command: comspec && comspec.length > 0 ? comspec : "cmd.exe", args: [] };
+  }
+
+  if (platform === "darwin") {
+    return { command: "/bin/zsh", args: [] };
+  }
+
+  return { command: "/bin/bash", args: [] };
+}