🤖 Add resolvePath() to Runtime interface for tilde expansion

- Add resolvePath() method to Runtime interface
- LocalRuntime: Expands tildes using expandTilde() and verifies path exists
- SSHRuntime: Uses remote 'realpath' command to expand and verify paths
- WORKSPACE_CREATE: Resolves srcBaseDir before creating runtime and storing in config
- Remove tilde validation from SSHRuntime constructor (now handled by resolvePath)
- Both tilde (~) and non-tilde paths now work for workspace creation
- Add comprehensive unit tests for both runtimes

This enables storing resolved paths in config, ensuring consistency across
local and SSH runtimes regardless of how the path was originally specified.

Generated with `cmux`

Author: ammar-agent

src/runtime/LocalRuntime.test.ts

@@ -29,3 +29,41 @@ describe("LocalRuntime constructor", () => {
     expect(workspacePath).toBe(expected);
   });
 });
+
+describe("LocalRuntime.resolvePath", () => {
+  it("should expand tilde to home directory", async () => {
+    const runtime = new LocalRuntime("/tmp");
+    const resolved = await runtime.resolvePath("~");
+    expect(resolved).toBe(os.homedir());
+  });
+
+  it("should expand tilde with path", async () => {
+    const runtime = new LocalRuntime("/tmp");
+    // Use a path that likely exists (or use /tmp if ~ doesn't have subdirs)
+    const resolved = await runtime.resolvePath("~/..");
+    const expected = path.dirname(os.homedir());
+    expect(resolved).toBe(expected);
+  });
+
+  it("should resolve absolute paths", async () => {
+    const runtime = new LocalRuntime("/tmp");
+    const resolved = await runtime.resolvePath("/tmp");
+    expect(resolved).toBe("/tmp");
+  });
+
+  it("should reject non-existent paths", async () => {
+    const runtime = new LocalRuntime("/tmp");
+    // eslint-disable-next-line @typescript-eslint/await-thenable
+    await expect(runtime.resolvePath("/this/path/does/not/exist/12345")).rejects.toThrow(
+      /Cannot resolve path/
+    );
+  });
+
+  it("should resolve relative paths from cwd", async () => {
+    const runtime = new LocalRuntime("/tmp");
+    const resolved = await runtime.resolvePath(".");
+    // Should resolve to absolute path
+    expect(path.isAbsolute(resolved)).toBe(true);
+  });
+});
+

src/runtime/LocalRuntime.ts

@@ -301,6 +301,26 @@ export class LocalRuntime implements Runtime {
     }
   }
 
+  async resolvePath(filePath: string): Promise<string> {
+    // Expand tilde to actual home directory path
+    const expanded = expandTilde(filePath);
+
+    // Resolve to absolute path (handles relative paths like "./foo")
+    const resolved = path.resolve(expanded);
+
+    // Verify path exists
+    try {
+      await fsPromises.access(resolved);
+      return resolved;
+    } catch (err) {
+      throw new RuntimeErrorClass(
+        `Cannot resolve path '${filePath}': ${getErrorMessage(err)}`,
+        "file_io",
+        err instanceof Error ? err : undefined
+      );
+    }
+  }
+
   normalizePath(targetPath: string, basePath: string): string {
     // For local runtime, use Node.js path resolution
     // Handle special case: current directory

src/runtime/Runtime.ts

@@ -195,6 +195,24 @@ export interface Runtime {
    */
   stat(path: string): Promise<FileStat>;
 
+  /**
+   * Resolve a path to its absolute, canonical form (expanding tildes, resolving symlinks, etc.).
+   * This is used at workspace creation time to normalize srcBaseDir paths in config.
+   *
+   * @param path Path to resolve (may contain tildes or be relative)
+   * @returns Promise resolving to absolute path
+   * @throws RuntimeError if path cannot be resolved (e.g., doesn't exist, permission denied)
+   *
+   * @example
+   * // LocalRuntime
+   * await runtime.resolvePath("~/cmux")      // => "/home/user/cmux"
+   * await runtime.resolvePath("./relative")  // => "/current/dir/relative"
+   *
+   * // SSHRuntime
+   * await runtime.resolvePath("~/cmux")      // => "/home/user/cmux" (via SSH shell expansion)
+   */
+  resolvePath(path: string): Promise<string>;
+
   /**
    * Normalize a path for comparison purposes within this runtime's context.
    * Handles runtime-specific path semantics (local vs remote).

src/runtime/SSHRuntime.test.ts

@@ -2,22 +2,24 @@ import { describe, expect, it } from "bun:test";
 import { SSHRuntime } from "./SSHRuntime";
 
 describe("SSHRuntime constructor", () => {
-  it("should reject tilde in srcBaseDir", () => {
+  it("should accept tilde in srcBaseDir", () => {
+    // Tildes are now allowed - they will be resolved via resolvePath()
     expect(() => {
       new SSHRuntime({
         host: "example.com",
         srcBaseDir: "~/cmux",
       });
-    }).toThrow(/cannot start with tilde/);
+    }).not.toThrow();
   });
 
-  it("should reject bare tilde in srcBaseDir", () => {
+  it("should accept bare tilde in srcBaseDir", () => {
+    // Tildes are now allowed - they will be resolved via resolvePath()
     expect(() => {
       new SSHRuntime({
         host: "example.com",
         srcBaseDir: "~",
       });
-    }).toThrow(/cannot start with tilde/);
+    }).not.toThrow();
   });
 
   it("should accept absolute paths in srcBaseDir", () => {
@@ -29,3 +31,63 @@ describe("SSHRuntime constructor", () => {
     }).not.toThrow();
   });
 });
+
+describe("SSHRuntime.resolvePath", () => {
+  // Note: These tests require TEST_INTEGRATION=1 to run with actual SSH connection
+  const isIntegrationTest = process.env.TEST_INTEGRATION === "1";
+  const describeIfIntegration = isIntegrationTest ? describe : describe.skip;
+
+  describeIfIntegration("with SSH connection", () => {
+    it("should expand tilde to home directory", async () => {
+      const runtime = new SSHRuntime({
+        host: process.env.SSH_HOST ?? "localhost",
+        port: parseInt(process.env.SSH_PORT ?? "2222"),
+        identityFile: process.env.SSH_IDENTITY_FILE,
+        srcBaseDir: "~/test-workspace",
+      });
+
+      const resolved = await runtime.resolvePath("~");
+      // Should be an absolute path
+      expect(resolved).toMatch(/^\/home\//);
+    });
+
+    it("should expand tilde with path", async () => {
+      const runtime = new SSHRuntime({
+        host: process.env.SSH_HOST ?? "localhost",
+        port: parseInt(process.env.SSH_PORT ?? "2222"),
+        identityFile: process.env.SSH_IDENTITY_FILE,
+        srcBaseDir: "~/test-workspace",
+      });
+
+      const resolved = await runtime.resolvePath("~/..");
+      // Should be parent of home directory
+      expect(resolved).toBe("/home");
+    });
+
+    it("should resolve absolute paths", async () => {
+      const runtime = new SSHRuntime({
+        host: process.env.SSH_HOST ?? "localhost",
+        port: parseInt(process.env.SSH_PORT ?? "2222"),
+        identityFile: process.env.SSH_IDENTITY_FILE,
+        srcBaseDir: "/tmp",
+      });
+
+      const resolved = await runtime.resolvePath("/tmp");
+      expect(resolved).toBe("/tmp");
+    });
+
+    it("should reject non-existent paths", async () => {
+      const runtime = new SSHRuntime({
+        host: process.env.SSH_HOST ?? "localhost",
+        port: parseInt(process.env.SSH_PORT ?? "2222"),
+        identityFile: process.env.SSH_IDENTITY_FILE,
+        srcBaseDir: "/tmp",
+      });
+
+      // eslint-disable-next-line @typescript-eslint/await-thenable
+      await expect(
+        runtime.resolvePath("/this/path/does/not/exist/12345")
+      ).rejects.toThrow(/Failed to resolve path/);
+    });
+  });
+});

src/runtime/SSHRuntime.ts

@@ -60,15 +60,8 @@ export class SSHRuntime implements Runtime {
   private readonly controlPath: string;
 
   constructor(config: SSHRuntimeConfig) {
-    // Reject tilde paths - require explicit full paths for SSH
-    // Rationale: Simplifies logic and avoids ambiguity about which user's home directory
-    if (config.srcBaseDir.startsWith("~")) {
-      throw new Error(
-        `SSH runtime srcBaseDir cannot start with tilde. ` +
-          `Use full path (e.g., /home/username/cmux instead of ~/cmux)`
-      );
-    }
-
+    // Note: srcBaseDir may contain tildes - they will be resolved via resolvePath() before use
+    // The WORKSPACE_CREATE IPC handler resolves paths before storing in config
     this.config = config;
     // Generate unique control path for SSH connection multiplexing
     // This allows multiple SSH sessions to reuse a single TCP connection
@@ -325,6 +318,64 @@ export class SSHRuntime implements Runtime {
       isDirectory: fileType === "directory",
     };
   }
+  async resolvePath(filePath: string): Promise<string> {
+    // Use shell to expand tildes and resolve path on remote system
+    // We use `realpath` which resolves symlinks and gives canonical path
+    // Note: realpath also verifies the path exists
+    const command = `realpath ${shescape.quote(filePath)}`;
+    const sshArgs = this.buildSSHArgs();
+    sshArgs.push(this.config.host, command);
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn("ssh", sshArgs);
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout?.on("data", (data: Buffer) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr?.on("data", (data: Buffer) => {
+        stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        if (code !== 0) {
+          reject(
+            new RuntimeErrorClass(
+              `Failed to resolve path '${filePath}' on remote host: ${stderr.trim()}`,
+              "file_io"
+            )
+          );
+          return;
+        }
+
+        const resolved = stdout.trim();
+        if (!resolved?.startsWith("/")) {
+          reject(
+            new RuntimeErrorClass(
+              `Invalid resolved path '${resolved}' for '${filePath}' (expected absolute path)`,
+              "file_io"
+            )
+          );
+          return;
+        }
+
+        resolve(resolved);
+      });
+
+      proc.on("error", (err) => {
+        reject(
+          new RuntimeErrorClass(
+            `Cannot resolve path '${filePath}' on remote host: ${getErrorMessage(err)}`,
+            "network",
+            err instanceof Error ? err : undefined
+          )
+        );
+      });
+    });
+  }
+
   normalizePath(targetPath: string, basePath: string): string {
     // For SSH, handle paths in a POSIX-like manner without accessing the remote filesystem
     const target = targetPath.trim();

src/services/gitService.test.ts

@@ -91,6 +91,9 @@ describe("removeWorktreeSafe", () => {
     const result = await createWorktree(mockConfig, repoPath, "dirty-branch", {
       trunkBranch: defaultBranch,
     });
+    if (!result.success) {
+      console.error("createWorktree failed:", result.error);
+    }
     expect(result.success).toBe(true);
     const worktreePath = result.path!;
 

src/services/ipcMain.ts

@@ -284,10 +284,26 @@ export class IpcMain {
           srcBaseDir: this.config.srcDir,
         };
 
-        // Create runtime - catch validation errors (e.g., tilde paths in SSH)
+        // Create temporary runtime to resolve srcBaseDir path
+        // This allows tilde paths to work for both local and SSH runtimes
         let runtime;
+        let resolvedSrcBaseDir: string;
         try {
           runtime = createRuntime(finalRuntimeConfig);
+          
+          // Resolve srcBaseDir to absolute path (expanding tildes, etc.)
+          resolvedSrcBaseDir = await runtime.resolvePath(finalRuntimeConfig.srcBaseDir);
+          
+          // If path was resolved to something different, recreate runtime with resolved path
+          if (resolvedSrcBaseDir !== finalRuntimeConfig.srcBaseDir) {
+            const resolvedRuntimeConfig: RuntimeConfig = {
+              ...finalRuntimeConfig,
+              srcBaseDir: resolvedSrcBaseDir,
+            };
+            runtime = createRuntime(resolvedRuntimeConfig);
+            // Update finalRuntimeConfig to store resolved path in config
+            finalRuntimeConfig.srcBaseDir = resolvedSrcBaseDir;
+          }
         } catch (error) {
           const errorMsg = error instanceof Error ? error.message : String(error);
           return { success: false, error: errorMsg };