🤖 feat: optimize workspace fork init and tests

Author: ammar-agent

docs/AGENTS.md

@@ -67,3 +67,8 @@ export const IPC_CHANNELS = {
 // Helper functions for dynamic channels
 export const getChatChannel = (workspaceId: string): string =>
   `${IPC_CHANNELS.WORKSPACE_CHAT_PREFIX}${workspaceId}`;
+
+// Event type constants for workspace init events
+export const EVENT_TYPE_PREFIX_INIT = "init-";
+export const EVENT_TYPE_INIT_OUTPUT = "init-output" as const;
+export const EVENT_TYPE_INIT_END = "init-end" as const;

src/constants/ipc-constants.ts

@@ -18,15 +18,9 @@ import type {
 } from "./Runtime";
 import { RuntimeError as RuntimeErrorClass } from "./Runtime";
 import { NON_INTERACTIVE_ENV_VARS } from "../constants/env";
-import { getBashPath } from "../utils/main/bashPath";
 import { EXIT_CODE_ABORTED, EXIT_CODE_TIMEOUT } from "../constants/exitCodes";
 import { listLocalBranches } from "../git";
-import {
-  checkInitHookExists,
-  getInitHookPath,
-  createLineBufferedLoggers,
-  getInitHookEnv,
-} from "./initHook";
+import { checkInitHookExists, getInitHookPath, createLineBufferedLoggers } from "./initHook";
 import { execAsync, DisposableProcess } from "../utils/disposableExec";
 import { getProjectName } from "../utils/runtime/helpers";
 import { getErrorMessage } from "../utils/errors";
@@ -62,13 +56,11 @@ export class LocalRuntime implements Runtime {
       );
     }
 
-    // If niceness is specified on Unix/Linux, spawn nice directly to avoid escaping issues
-    // Windows doesn't have nice command, so just spawn bash directly
-    const isWindows = process.platform === "win32";
-    const bashPath = getBashPath();
-    const spawnCommand = options.niceness !== undefined && !isWindows ? "nice" : bashPath;
+    // If niceness is specified, spawn nice directly to avoid escaping issues
+    const spawnCommand = options.niceness !== undefined ? "nice" : "bash";
+    const bashPath = "bash";
     const spawnArgs =
-      options.niceness !== undefined && !isWindows
+      options.niceness !== undefined
         ? ["-n", options.niceness.toString(), bashPath, "-c", command]
         : ["-c", command];
 
@@ -378,7 +370,10 @@ export class LocalRuntime implements Runtime {
     const { projectPath, workspacePath, initLogger } = params;
 
     try {
-      // Run .mux/init hook if it exists
+      // Note: sourceWorkspacePath is only used by SSH runtime (to copy workspace)
+      // Local runtime creates git worktrees which are instant, so we don't need it here
+
+      // Run .cmux/init hook if it exists
       // Note: runInitHook calls logComplete() internally if hook exists
       const hookExists = await checkInitHookExists(projectPath);
       if (hookExists) {
@@ -400,7 +395,7 @@ export class LocalRuntime implements Runtime {
   }
 
   /**
-   * Run .mux/init hook if it exists and is executable
+   * Run .cmux/init hook if it exists and is executable
    */
   private async runInitHook(
     projectPath: string,
@@ -420,14 +415,9 @@ export class LocalRuntime implements Runtime {
     const loggers = createLineBufferedLoggers(initLogger);
 
     return new Promise<void>((resolve) => {
-      const bashPath = getBashPath();
-      const proc = spawn(bashPath, ["-c", `"${hookPath}"`], {
+      const proc = spawn("bash", ["-c", `"${hookPath}"`], {
         cwd: workspacePath,
         stdio: ["ignore", "pipe", "pipe"],
-        env: {
-          ...process.env,
-          ...getInitHookEnv(projectPath, "local"),
-        },
       });
 
       proc.stdout.on("data", (data: Buffer) => {
@@ -601,7 +591,10 @@ export class LocalRuntime implements Runtime {
         };
       }
 
+      initLogger.logStep(`Detected source branch: ${sourceBranch}`);
+
       // Use createWorkspace with sourceBranch as trunk to fork from source branch
+      // For local workspaces (worktrees), this is instant - no init needed
       const createResult = await this.createWorkspace({
         projectPath,
         branchName: newWorkspaceName,
@@ -617,9 +610,12 @@ export class LocalRuntime implements Runtime {
         };
       }
 
+      initLogger.logStep("Workspace forked successfully");
+
       return {
         success: true,
         workspacePath: createResult.workspacePath,
+        sourceWorkspacePath,
         sourceBranch,
       };
     } catch (error) {

src/runtime/LocalRuntime.ts

@@ -151,6 +151,8 @@ export interface WorkspaceInitParams {
   initLogger: InitLogger;
   /** Optional abort signal for cancellation */
   abortSignal?: AbortSignal;
+  /** If provided, copy from this workspace instead of syncing from local (fork scenario) */
+  sourceWorkspacePath?: string;
 }
 
 /**
@@ -189,6 +191,8 @@ export interface WorkspaceForkResult {
   success: boolean;
   /** Path to the new workspace (if successful) */
   workspacePath?: string;
+  /** Path to the source workspace (needed for init phase) */
+  sourceWorkspacePath?: string;
   /** Branch that was forked from */
   sourceBranch?: string;
   /** Error message (if failed) */
@@ -304,7 +308,7 @@ export interface Runtime {
   /**
    * Initialize workspace asynchronously (may be slow, streams progress)
    * - LocalRuntime: Runs init hook if present
-   * - SSHRuntime: Syncs files, checks out branch, runs init hook
+   * - SSHRuntime: Syncs files (or copies from source), checks out branch, runs init hook
    * Streams progress via initLogger.
    * @param params Workspace initialization parameters
    * @returns Result indicating success or error

src/runtime/Runtime.ts

@@ -17,7 +17,7 @@ import type {
 import { RuntimeError as RuntimeErrorClass } from "./Runtime";
 import { EXIT_CODE_ABORTED, EXIT_CODE_TIMEOUT } from "../constants/exitCodes";
 import { log } from "../services/log";
-import { checkInitHookExists, createLineBufferedLoggers, getInitHookEnv } from "./initHook";
+import { checkInitHookExists, createLineBufferedLoggers } from "./initHook";
 import { streamProcessToLogger } from "./streamProcess";
 import { expandTildeForSSH, cdCommandForSSH } from "./tildeExpansion";
 import { getProjectName } from "../utils/runtime/helpers";
@@ -751,7 +751,6 @@ export class SSHRuntime implements Runtime {
       cwd: workspacePath, // Run in the workspace directory
       timeout: 3600, // 1 hour - generous timeout for init hooks
       abortSignal,
-      env: getInitHookEnv(projectPath, "ssh"),
     });
 
     // Create line-buffered loggers
@@ -856,32 +855,72 @@ export class SSHRuntime implements Runtime {
   }
 
   async initWorkspace(params: WorkspaceInitParams): Promise<WorkspaceInitResult> {
-    const { projectPath, branchName, trunkBranch, workspacePath, initLogger, abortSignal } = params;
+    const {
+      projectPath,
+      branchName,
+      trunkBranch,
+      workspacePath,
+      initLogger,
+      abortSignal,
+      sourceWorkspacePath,
+    } = params;
 
     try {
-      // 1. Sync project to remote (opportunistic rsync with scp fallback)
-      initLogger.logStep("Syncing project files to remote...");
-      try {
-        await this.syncProjectToRemote(projectPath, workspacePath, initLogger, abortSignal);
-      } catch (error) {
-        const errorMsg = getErrorMessage(error);
-        initLogger.logStderr(`Failed to sync project: ${errorMsg}`);
-        initLogger.logComplete(-1);
-        return {
-          success: false,
-          error: `Failed to sync project: ${errorMsg}`,
-        };
+      // Fork scenario: Copy from source workspace instead of syncing from local
+      if (sourceWorkspacePath) {
+        // 1. Copy workspace directory on remote host
+        // cp -a preserves all attributes (permissions, timestamps, symlinks, uncommitted changes)
+        initLogger.logStep("Copying workspace from source...");
+        // Expand tilde paths before using in remote command
+        const expandedSourcePath = expandTildeForSSH(sourceWorkspacePath);
+        const expandedWorkspacePath = expandTildeForSSH(workspacePath);
+        const copyStream = await this.exec(
+          `cp -a ${expandedSourcePath}/. ${expandedWorkspacePath}/`,
+          { cwd: "~", timeout: 300, abortSignal } // 5 minute timeout for large workspaces
+        );
+
+        const [stdout, stderr, exitCode] = await Promise.all([
+          streamToString(copyStream.stdout),
+          streamToString(copyStream.stderr),
+          copyStream.exitCode,
+        ]);
+
+        if (exitCode !== 0) {
+          const errorMsg = `Failed to copy workspace: ${stderr || stdout}`;
+          initLogger.logStderr(errorMsg);
+          initLogger.logComplete(-1);
+          return {
+            success: false,
+            error: errorMsg,
+          };
+        }
+        initLogger.logStep("Workspace copied successfully");
+      } else {
+        // Normal scenario: Sync from local project
+        // 1. Sync project to remote (opportunistic rsync with scp fallback)
+        initLogger.logStep("Syncing project files to remote...");
+        try {
+          await this.syncProjectToRemote(projectPath, workspacePath, initLogger, abortSignal);
+        } catch (error) {
+          const errorMsg = getErrorMessage(error);
+          initLogger.logStderr(`Failed to sync project: ${errorMsg}`);
+          initLogger.logComplete(-1);
+          return {
+            success: false,
+            error: `Failed to sync project: ${errorMsg}`,
+          };
+        }
+        initLogger.logStep("Files synced successfully");
       }
-      initLogger.logStep("Files synced successfully");
 
       // 2. Checkout branch remotely
-      // If branch exists locally, check it out; otherwise create it from the specified trunk branch
-      // Note: We've already created local branches for all remote refs in syncProjectToRemote
       initLogger.logStep(`Checking out branch: ${branchName}`);
 
-      // Try to checkout existing branch, or create new branch from trunk
-      // Since we've created local branches for all remote refs, we can use branch names directly
-      const checkoutCmd = `git checkout ${shescape.quote(branchName)} 2>/dev/null || git checkout -b ${shescape.quote(branchName)} ${shescape.quote(trunkBranch)}`;
+      // For forked workspaces (copied with cp -a), HEAD is already on the source branch
+      // For synced workspaces, we need to specify the trunk branch to create from
+      const checkoutCmd = sourceWorkspacePath
+        ? `git checkout ${shescape.quote(branchName)} 2>/dev/null || git checkout -b ${shescape.quote(branchName)}`
+        : `git checkout ${shescape.quote(branchName)} 2>/dev/null || git checkout -b ${shescape.quote(branchName)} ${shescape.quote(trunkBranch)}`;
 
       const checkoutStream = await this.exec(checkoutCmd, {
         cwd: workspacePath, // Use the full workspace path for git operations
@@ -1159,16 +1198,46 @@ export class SSHRuntime implements Runtime {
     }
   }
 
-  forkWorkspace(_params: WorkspaceForkParams): Promise<WorkspaceForkResult> {
-    // SSH forking is not yet implemented due to unresolved complexities:
-    // - Users expect the new workspace's filesystem state to match the remote workspace,
-    //   not the local project (which may be out of sync or on a different commit)
-    // - This requires: detecting the branch, copying remote state, handling uncommitted changes
-    // - For now, users should create a new workspace from the desired branch instead
-    return Promise.resolve({
-      success: false,
-      error: "Forking SSH workspaces is not yet implemented. Create a new workspace instead.",
-    });
+  async forkWorkspace(params: WorkspaceForkParams): Promise<WorkspaceForkResult> {
+    const { projectPath, sourceWorkspaceName, newWorkspaceName, initLogger } = params;
+
+    // Get source and destination workspace paths
+    const sourceWorkspacePath = this.getWorkspacePath(projectPath, sourceWorkspaceName);
+    const newWorkspacePath = this.getWorkspacePath(projectPath, newWorkspaceName);
+
+    // Expand tilde path for the new workspace directory
+    const expandedNewPath = expandTildeForSSH(newWorkspacePath);
+
+    try {
+      // Step 1: Create empty directory for new workspace (instant)
+      // The actual copy happens in initWorkspace (fire-and-forget)
+      initLogger.logStep("Creating workspace directory...");
+      const mkdirStream = await this.exec(`mkdir -p ${expandedNewPath}`, { cwd: "~", timeout: 10 });
+
+      await mkdirStream.stdin.abort();
+      const mkdirExitCode = await mkdirStream.exitCode;
+      if (mkdirExitCode !== 0) {
+        const stderr = await streamToString(mkdirStream.stderr);
+        return {
+          success: false,
+          error: `Failed to create workspace directory: ${stderr}`,
+        };
+      }
+
+      initLogger.logStep("Workspace directory created");
+
+      // Return immediately - copy and init happen in initWorkspace (fire-and-forget)
+      return {
+        success: true,
+        workspacePath: newWorkspacePath,
+        sourceWorkspacePath,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: getErrorMessage(error),
+      };
+    }
   }
 }
 

src/runtime/SSHRuntime.ts

@@ -4,12 +4,18 @@ import * as path from "path";
 import type { InitLogger } from "./Runtime";
 
 /**
- * Check if .mux/init hook exists and is executable
+ * Constants for init hook functionality
+ */
+export const CMUX_DIR = ".mux";
+export const INIT_HOOK_FILENAME = "init";
+
+/**
+ * Check if .cmux/init hook exists and is executable
  * @param projectPath - Path to the project root
  * @returns true if hook exists and is executable, false otherwise
  */
 export async function checkInitHookExists(projectPath: string): Promise<boolean> {
-  const hookPath = path.join(projectPath, ".mux", "init");
+  const hookPath = path.join(projectPath, CMUX_DIR, INIT_HOOK_FILENAME);
 
   try {
     await fsPromises.access(hookPath, fs.constants.X_OK);
@@ -23,23 +29,7 @@ export async function checkInitHookExists(projectPath: string): Promise<boolean>
  * Get the init hook path for a project
  */
 export function getInitHookPath(projectPath: string): string {
-  return path.join(projectPath, ".mux", "init");
-}
-
-/**
- * Get environment variables for init hook execution
- * Centralizes env var injection to avoid duplication across runtimes
- * @param projectPath - Path to project root (local path for LocalRuntime, remote path for SSHRuntime)
- * @param runtime - Runtime type: "local" or "ssh"
- */
-export function getInitHookEnv(
-  projectPath: string,
-  runtime: "local" | "ssh"
-): Record<string, string> {
-  return {
-    MUX_PROJECT_PATH: projectPath,
-    MUX_RUNTIME: runtime,
-  };
+  return path.join(projectPath, CMUX_DIR, INIT_HOOK_FILENAME);
 }
 
 /**