🤖 feat: implement SSH workspace forking

[ammar-agent]

Summary

Implements workspace forking for SSH runtimes. Fork operations copy the entire workspace (preserving uncommitted changes) while keeping the UI responsive by moving the slow copy operation to the init phase.

Implementation

Follows the existing createWorkspace + initWorkspace pattern:

• Fast path (forkWorkspace): Detect branch + create empty directory → instant return
• Slow path (initWorkspace): Copy files + checkout branch + run init hook → fire-and-forget with progress streaming

Changes

1. Added sourceWorkspacePath parameter to WorkspaceInitParams

export interface WorkspaceInitParams {
  // ... existing fields ...
  /** If provided, copy from this workspace instead of syncing from local (fork scenario) */
  sourceWorkspacePath?: string;
}

2. Implemented SSHRuntime.forkWorkspace

• Detects current branch in source workspace via git branch --show-current
• Creates empty directory for new workspace (mkdir -p)
• Returns immediately with source workspace path and branch info
• Result: Fork IPC returns in ~1 second

3. Updated SSHRuntime.initWorkspace to handle fork scenario

• Fork mode (when sourceWorkspacePath provided):
  • Copy from source workspace via cp -a (preserves uncommitted changes, timestamps, permissions)
  • Checkout new branch
  • Run init hook
• Normal mode (when sourceWorkspacePath undefined):
  • Sync from local via rsync
  • Checkout branch
  • Run init hook

4. Updated LocalRuntime.forkWorkspace

• Uses existing createWorkspace (git worktree) with source branch as trunk
• Instant operation (git worktrees are fast)
• Calls init hook if present

5. Updated IPC handler

• Calls runtime.initWorkspace() with sourceWorkspacePath for fork scenario
• Fire-and-forget pattern with progress streaming via initLogger
• Copies chat history (chat.jsonl) from source to forked workspace

6. Refactored tests to use describe.each matrix

• Tests run for both local and ssh runtimes
• Single SSH server shared across all tests (performance optimization)
• Proper path handling: SSH uses constructed paths, local uses metadata paths
• SSH-specific test: preserves uncommitted changes (local creates clean worktrees)

Benefits

✅ UI stays responsive: Fork IPC returns immediately (~1s) even for large workspaces
✅ Progress streaming: Init events stream via initLogger during copy operation
✅ Uncommitted changes preserved: cp -a copies everything (SSH only)
✅ Matches existing patterns: Same architecture as createWorkspace + initWorkspace
✅ Runtime parity: Both local and SSH runtimes fully tested

Test Coverage

All 14 tests passing in ~63 seconds:

Basic fork operations:

• ✅ Invalid name validation (both runtimes)
• ✅ Successful fork (both runtimes)

Init hook execution:

• ✅ Verifies init hook runs during fork (both runtimes)

Fork with API operations:

• ✅ Send messages to forked workspace (local)
• ✅ Preserve chat history (local)

Fork preserves filesystem state:

• ✅ Preserve uncommitted changes (SSH only - local worktrees are clean checkouts)
• ✅ Preserve git state/branch (both runtimes)

Test structure:

describe.each<{ type: "local" | "ssh" }>([{ type: "local" }, { type: "ssh" }])(
  "Runtime: $type",
  ({ type }) => {
    // Tests run for both runtimes with proper path handling
  }
);

Files Modified

• src/runtime/Runtime.ts (+2 lines): Added sourceWorkspacePath? parameter
• src/runtime/SSHRuntime.ts (+110 lines): Implemented forkWorkspace + updated initWorkspace
• src/runtime/LocalRuntime.ts (+35 lines): Implemented forkWorkspace + updated initWorkspace
• src/services/ipcMain.ts (+170 lines): Implemented WORKSPACE_FORK IPC handler
• tests/ipcMain/forkWorkspace.test.ts (+641 lines): Matrix testing for both runtimes
• tests/ipcMain/setup.ts (+60 lines): Shared SSH test helpers
• tests/README.md (+80 lines): Documentation for test infrastructure

Net change: 910 insertions, 332 deletions

Generated with cmux

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".