🤖 refactor: broaden workspace runtime cleanup

Continue the workspace runtime cleanup by centralizing the shared init-hook
flow, threading persisted workspace identity through runtime recreation, and
using directoryName consistently for workspace/container paths.

---

_Generated with `mux` • Model: `openai:gpt-5.4` • Thinking: `xhigh` • Cost: `$153.79`_

<!-- mux-attribution: model=openai:gpt-5.4 thinking=xhigh costs=153.79 -->

Author: ammar-agent

src/node/runtime/DevcontainerRuntime.ts

@@ -30,12 +30,7 @@ import {
   type BindMount,
 } from "./credentialForwarding";
 import { devcontainerUp, devcontainerDown } from "./devcontainerCli";
-import {
-  checkInitHookExists,
-  getMuxEnv,
-  runInitHookOnRuntime,
-  shouldSkipInitHook,
-} from "./initHook";
+import { runInitHookOnRuntime, runWorkspaceInitHook } from "./initHook";
 import { DisposableProcess, forceCloseStdio, killProcessTree } from "@/node/utils/disposableExec";
 import { EXIT_CODE_ABORTED, EXIT_CODE_TIMEOUT } from "@/common/constants/exitCodes";
 import { NON_INTERACTIVE_ENV_VARS } from "@/common/constants/env";
@@ -481,6 +476,7 @@ export class DevcontainerRuntime extends LocalBaseRuntime {
     return this.worktreeManager.createWorkspace({
       projectPath: params.projectPath,
       branchName: params.branchName,
+      directoryName: params.directoryName,
       trunkBranch: params.trunkBranch,
       initLogger: params.initLogger,
       abortSignal: params.abortSignal,
@@ -530,36 +526,23 @@ export class DevcontainerRuntime extends LocalBaseRuntime {
    * Run .mux/init hook inside the devcontainer.
    */
   async initWorkspace(params: WorkspaceInitParams): Promise<WorkspaceInitResult> {
-    const { projectPath, branchName, workspacePath, initLogger, env } = params;
-
-    try {
-      if (shouldSkipInitHook(params, initLogger)) {
-        initLogger.logComplete(0);
-        return { success: true };
-      }
-
-      // Check if init hook exists (on host - worktree is bind-mounted)
-      const hookExists = await checkInitHookExists(workspacePath);
-      if (hookExists) {
-        initLogger.enterHookPhase?.();
-        const muxEnv = { ...env, ...getMuxEnv(projectPath, "devcontainer", branchName) };
-        const containerWorkspacePath = this.remoteWorkspaceFolder ?? workspacePath;
+    return runWorkspaceInitHook({
+      params,
+      runtimeType: "devcontainer",
+      hookCheckPath: params.workspacePath,
+      runHook: async ({ muxEnv, initLogger, abortSignal }) => {
+        const containerWorkspacePath = this.remoteWorkspaceFolder ?? params.workspacePath;
         const hookPath = `${containerWorkspacePath}/.mux/init`;
-        await runInitHookOnRuntime(this, hookPath, containerWorkspacePath, muxEnv, initLogger);
-      } else {
-        // No hook - signal completion immediately
-        initLogger.logComplete(0);
-      }
-      return { success: true };
-    } catch (error) {
-      const errorMsg = getErrorMessage(error);
-      initLogger.logStderr(`Initialization failed: ${errorMsg}`);
-      initLogger.logComplete(-1);
-      return {
-        success: false,
-        error: errorMsg,
-      };
-    }
+        await runInitHookOnRuntime(
+          this,
+          hookPath,
+          containerWorkspacePath,
+          muxEnv,
+          initLogger,
+          abortSignal
+        );
+      },
+    });
   }
 
   /**

src/node/runtime/DockerRuntime.ts

@@ -29,12 +29,7 @@ import type {
 } from "./Runtime";
 import { RuntimeError } from "./Runtime";
 import { RemoteRuntime, type SpawnResult } from "./RemoteRuntime";
-import {
-  checkInitHookExists,
-  getMuxEnv,
-  runInitHookOnRuntime,
-  shouldSkipInitHook,
-} from "./initHook";
+import { runInitHookOnRuntime, runWorkspaceInitHook } from "./initHook";
 import { getProjectName } from "@/node/utils/runtime/helpers";
 import { getErrorMessage } from "@/common/utils/errors";
 import { syncProjectViaGitBundle } from "./gitBundleSync";
@@ -423,10 +418,11 @@ export class DockerRuntime extends RemoteRuntime {
   }
 
   async createWorkspace(params: WorkspaceCreationParams): Promise<WorkspaceCreationResult> {
-    const { projectPath, branchName } = params;
+    const { projectPath, directoryName } = params;
 
-    // Generate container name and check for collisions before persisting metadata
-    const containerName = getContainerName(projectPath, branchName);
+    // Container identity should follow the workspace entry name rather than the git branch.
+    // The two are usually equal today, but the runtime contract keeps them distinct.
+    const containerName = getContainerName(projectPath, directoryName);
 
     // Check if container already exists (collision detection)
     const checkResult = await runDockerCommand(`docker inspect ${containerName}`, 10000);
@@ -528,43 +524,30 @@ export class DockerRuntime extends RemoteRuntime {
    * is handled by postCreateSetup().
    */
   async initWorkspace(params: WorkspaceInitParams): Promise<WorkspaceInitResult> {
-    const { projectPath, branchName, workspacePath, initLogger, abortSignal, env } = params;
-
-    try {
-      if (!this.containerName) {
-        return {
-          success: false,
-          error: "Container not initialized. Call createWorkspace first.",
-        };
-      }
-
-      if (shouldSkipInitHook(params, initLogger)) {
-        initLogger.logComplete(0);
-        return { success: true };
-      }
-
-      // Run .mux/init hook if it exists
-      const hookExists = await checkInitHookExists(projectPath);
-      if (hookExists) {
-        initLogger.enterHookPhase?.();
-        const muxEnv = { ...env, ...getMuxEnv(projectPath, "docker", branchName) };
-        const hookPath = `${workspacePath}/.mux/init`;
-        await runInitHookOnRuntime(this, hookPath, workspacePath, muxEnv, initLogger, abortSignal);
-      } else {
-        initLogger.logComplete(0);
-      }
-
-      return { success: true };
-    } catch (error) {
-      const errorMsg = getErrorMessage(error);
-      initLogger.logStderr(`Initialization failed: ${errorMsg}`);
-      initLogger.logComplete(-1);
-      // Do NOT delete container on hook failure - user can debug
+    if (!this.containerName) {
       return {
         success: false,
-        error: errorMsg,
+        error: "Container not initialized. Call createWorkspace first.",
       };
     }
+
+    // Do NOT delete container on hook failure - user can debug.
+    return runWorkspaceInitHook({
+      params,
+      runtimeType: "docker",
+      hookCheckPath: params.projectPath,
+      runHook: async ({ muxEnv, initLogger, abortSignal }) => {
+        const hookPath = `${params.workspacePath}/.mux/init`;
+        await runInitHookOnRuntime(
+          this,
+          hookPath,
+          params.workspacePath,
+          muxEnv,
+          initLogger,
+          abortSignal
+        );
+      },
+    });
   }
 
   /**

src/node/runtime/LocalRuntime.ts

@@ -8,7 +8,7 @@ import type {
   WorkspaceForkParams,
   WorkspaceForkResult,
 } from "./Runtime";
-import { checkInitHookExists, getMuxEnv, shouldSkipInitHook } from "./initHook";
+import { runWorkspaceInitHook } from "./initHook";
 import { getErrorMessage } from "@/common/utils/errors";
 import { LocalBaseRuntime } from "./LocalBaseRuntime";
 
@@ -86,34 +86,14 @@ export class LocalRuntime extends LocalBaseRuntime {
   }
 
   async initWorkspace(params: WorkspaceInitParams): Promise<WorkspaceInitResult> {
-    const { projectPath, branchName, workspacePath, initLogger, abortSignal, env } = params;
-
-    try {
-      if (shouldSkipInitHook(params, initLogger)) {
-        initLogger.logComplete(0);
-        return { success: true };
-      }
-
-      // Run .mux/init hook if it exists
-      const hookExists = await checkInitHookExists(projectPath);
-      if (hookExists) {
-        initLogger.enterHookPhase?.();
-        const muxEnv = { ...env, ...getMuxEnv(projectPath, "local", branchName) };
-        await this.runInitHook(workspacePath, muxEnv, initLogger, abortSignal);
-      } else {
-        // No hook - signal completion immediately
-        initLogger.logComplete(0);
-      }
-      return { success: true };
-    } catch (error) {
-      const errorMsg = getErrorMessage(error);
-      initLogger.logStderr(`Initialization failed: ${errorMsg}`);
-      initLogger.logComplete(-1);
-      return {
-        success: false,
-        error: errorMsg,
-      };
-    }
+    return runWorkspaceInitHook({
+      params,
+      runtimeType: "local",
+      hookCheckPath: params.projectPath,
+      runHook: async ({ muxEnv, initLogger, abortSignal }) => {
+        await this.runInitHook(params.workspacePath, muxEnv, initLogger, abortSignal);
+      },
+    });
   }
 
   /**

src/node/runtime/SSHRuntime.test.ts

@@ -35,6 +35,47 @@ describe("SSHRuntime constructor", () => {
   });
 });
 
+describe("SSHRuntime.createWorkspace", () => {
+  it("uses directoryName for the workspace path while preparing the remote parent directory", async () => {
+    const config = { host: "example.com", srcBaseDir: "/home/user/src" };
+    const runtime = new SSHRuntime(config, createSSHTransport(config, false));
+    const execSpy = spyOn(runtime, "exec").mockResolvedValue({
+      stdout: new ReadableStream<Uint8Array>(),
+      stderr: new ReadableStream<Uint8Array>(),
+      stdin: new WritableStream<Uint8Array>(),
+      exitCode: Promise.resolve(0),
+      duration: Promise.resolve(0),
+    });
+
+    try {
+      const result = await runtime.createWorkspace({
+        projectPath: "/projects/demo",
+        branchName: "feature-branch",
+        directoryName: "review-slot",
+        trunkBranch: "main",
+        initLogger: {
+          logStep: () => undefined,
+          logStdout: () => undefined,
+          logStderr: () => undefined,
+          logComplete: () => undefined,
+        },
+      });
+
+      expect(result).toEqual({
+        success: true,
+        workspacePath: "/home/user/src/demo/review-slot",
+      });
+      expect(execSpy).toHaveBeenCalledWith('mkdir -p "/home/user/src/demo"', {
+        cwd: "/tmp",
+        timeout: 10,
+        abortSignal: undefined,
+      });
+    } finally {
+      execSpy.mockRestore();
+    }
+  });
+});
+
 describe("SSHRuntime.ensureReady repository checks", () => {
   let execBufferedSpy: ReturnType<typeof spyOn<typeof runtimeHelpers, "execBuffered">> | null =
     null;

src/node/runtime/SSHRuntime.ts

@@ -32,12 +32,7 @@ import type {
 import { WORKSPACE_REPO_MISSING_ERROR } from "./Runtime";
 import { RemoteRuntime, type SpawnResult } from "./RemoteRuntime";
 import { log } from "@/node/services/log";
-import {
-  checkInitHookExists,
-  getMuxEnv,
-  runInitHookOnRuntime,
-  shouldSkipInitHook,
-} from "./initHook";
+import { runInitHookOnRuntime, runWorkspaceInitHook } from "./initHook";
 import { expandTildeForSSH as expandHookPath } from "./tildeExpansion";
 
 import { expandTildeForSSH, cdCommandForSSH } from "./tildeExpansion";
@@ -752,9 +747,9 @@ export class SSHRuntime extends RemoteRuntime {
 
   async createWorkspace(params: WorkspaceCreationParams): Promise<WorkspaceCreationResult> {
     try {
-      const { projectPath, branchName, initLogger, abortSignal } = params;
-      // Compute workspace path using canonical method
-      const workspacePath = this.getWorkspacePath(projectPath, branchName);
+      const { projectPath, directoryName, initLogger, abortSignal } = params;
+      // Workspace directories follow the persisted workspace name; branch checkout happens later.
+      const workspacePath = this.getWorkspacePath(projectPath, directoryName);
 
       // Prepare parent directory for git clone (fast - returns immediately)
       // Note: git clone will create the workspace directory itself during initWorkspace,
@@ -805,49 +800,29 @@ export class SSHRuntime extends RemoteRuntime {
   }
 
   async initWorkspace(params: WorkspaceInitParams): Promise<WorkspaceInitResult> {
-    const { projectPath, branchName, workspacePath, initLogger, abortSignal, env } = params;
-
     // Disable git hooks for untrusted projects (prevents post-checkout execution)
     const nhp = gitNoHooksPrefix(params.trusted);
 
-    try {
-      await this.prepareWorkspaceCheckout(params, nhp);
-
-      // 3. Run .mux/init hook if it exists
-      // Note: runInitHookOnRuntime calls logComplete() internally
-      if (shouldSkipInitHook(params, initLogger)) {
-        initLogger.logComplete(0);
-      } else {
-        const hookExists = await checkInitHookExists(projectPath);
-        if (hookExists) {
-          initLogger.enterHookPhase?.();
-          const muxEnv = { ...env, ...getMuxEnv(projectPath, "ssh", branchName) };
-          // Expand tilde in hook path (quoted paths don't auto-expand on remote)
-          const hookPath = expandHookPath(`${workspacePath}/.mux/init`);
-          await runInitHookOnRuntime(
-            this,
-            hookPath,
-            workspacePath,
-            muxEnv,
-            initLogger,
-            abortSignal
-          );
-        } else {
-          // No hook - signal completion immediately
-          initLogger.logComplete(0);
-        }
-      }
-
-      return { success: true };
-    } catch (error) {
-      const errorMsg = getErrorMessage(error);
-      initLogger.logStderr(`Initialization failed: ${errorMsg}`);
-      initLogger.logComplete(-1);
-      return {
-        success: false,
-        error: errorMsg,
-      };
-    }
+    return runWorkspaceInitHook({
+      params,
+      runtimeType: "ssh",
+      hookCheckPath: params.projectPath,
+      beforeHook: async () => {
+        await this.prepareWorkspaceCheckout(params, nhp);
+      },
+      runHook: async ({ muxEnv, initLogger, abortSignal }) => {
+        // Expand tilde in hook path (quoted paths don't auto-expand on remote).
+        const hookPath = expandHookPath(`${params.workspacePath}/.mux/init`);
+        await runInitHookOnRuntime(
+          this,
+          hookPath,
+          params.workspacePath,
+          muxEnv,
+          initLogger,
+          abortSignal
+        );
+      },
+    });
   }
 
   private async prepareWorkspaceCheckout(params: WorkspaceInitParams, nhp: string): Promise<void> {