🤖 fix: delete workspace by ID not path, fix title bar for local runtime

ammar-agent · ammar-agent · commit 95df44f046af · 2025-12-01T14:47:29.000-06:00
Bug fixes:
- Delete workspace filters by ID instead of path. For local project-dir
  runtimes, all workspaces share the same path (project dir), so filtering
  by path was deleting ALL local workspaces when one was deleted.
- WorkspaceHeader now uses metadata.name for display, fixing 'project/project'
  title issue for local runtimes where namedWorkspacePath is the project path.

Docs:
- Split runtime docs into docs/runtime/{local,worktree,ssh}.md
- Add docs/runtime/index.md overview with comparison table
- Update cross-references in workspaces.md and vscode-extension.md

Tests:
- Add integration tests for local project-dir workspace deletion
- Verify only specified workspace is deleted, not all with same path
- Verify project directory is not deleted
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -9,8 +9,10 @@
 # Features
 
 - [Workspaces](./workspaces.md)
-  - [Local](./local.md)
-  - [SSH](./ssh.md)
+  - [Runtimes](./runtime/index.md)
+    - [Local](./runtime/local.md)
+    - [Worktree](./runtime/worktree.md)
+    - [SSH](./runtime/ssh.md)
   - [Forking](./fork.md)
   - [Init Hooks](./init-hooks.md)
 - [VS Code Extension](./vscode-extension.md)
diff --git a/docs/local.md b/docs/local.md
diff --git a/docs/runtime/index.md b/docs/runtime/index.md
@@ -0,0 +1,23 @@
+# Runtimes
+
+Runtimes determine where and how mux executes agent workspaces.
+
+| Runtime                                 | Isolation                                  | Best For                                 |
+| --------------------------------------- | ------------------------------------------ | ---------------------------------------- |
+| **[Worktree](./worktree.md)** (default) | Each workspace gets its own directory      | Running multiple agents in parallel      |
+| **[Local](./local.md)**                 | All workspaces share the project directory | Quick edits to your working copy         |
+| **[SSH](./ssh.md)**                     | Remote execution over SSH                  | Security, performance, heavy parallelism |
+
+## Choosing a Runtime
+
+When creating a workspace, select the runtime from the dropdown in the workspace creation UI.
+
+## Init Hooks
+
+[Init hooks](../init-hooks.md) can detect the runtime type via the `MUX_RUNTIME` environment variable:
+
+- `worktree` — Worktree runtime
+- `local` — Local runtime
+- `ssh` — SSH runtime
+
+This lets your init hook adapt behavior, e.g., skip worktree-specific setup when running in local mode.
diff --git a/docs/runtime/local.md b/docs/runtime/local.md
@@ -0,0 +1,21 @@
+# Local Runtime
+
+Local runtime runs the agent directly in your project directory—the same directory you use for development. There's no isolation between workspaces.
+
+## When to Use
+
+- **Quick one-off tasks** in your current working copy
+- **Reviewing agent work** alongside your own uncommitted changes
+- **Projects where worktrees don't work well** (e.g., some monorepos)
+
+## Caveats
+
+⚠️ **No isolation**: Multiple local workspaces for the same project see and modify the same files. Running them simultaneously can cause conflicts.
+
+⚠️ **Affects your working copy**: Agent changes happen in your actual project directory, not a separate worktree.
+
+When multiple local workspaces exist for the same project, mux shows a warning if another workspace is actively streaming.
+
+## Filesystem
+
+The workspace path is your project directory itself. No additional directories are created.
diff --git a/docs/runtime/ssh.md b/docs/runtime/ssh.md
diff --git a/docs/runtime/worktree.md b/docs/runtime/worktree.md
@@ -0,0 +1,26 @@
+# Worktree Runtime
+
+Worktree runtime (the default) uses [git worktrees](https://git-scm.com/docs/git-worktree) to isolate each workspace. Each workspace gets its own directory with independent working changes and checkout state.
+
+## How Worktrees Work
+
+A worktree is a separate directory that shares `.git` with the main repository but has independent working changes. **All committed changes from any worktree are visible to all other worktrees including the main repository.**
+
+A **worktree is not locked to a branch**. The agent can switch branches, enter detached HEAD state, etc. When you create a workspace, the agent starts at the selected branch but may switch freely. **Define your agent's branching strategy in AGENTS.md**
+
+## Filesystem Layout
+
+Worktree workspaces are stored in `~/.mux/src/<project-name>/<workspace-name>`:
+
+```
+~/.mux/src/
+  my-project/
+    feature-auth/     # workspace 1
+    fix-ci-flakes/    # workspace 2
+```
+
+## When to Use
+
+- **Running multiple agents in parallel** (recommended)
+- **Keeping your working copy clean** while agents work
+- **Most projects** — this is the default for good reason
diff --git a/docs/vscode-extension.md b/docs/vscode-extension.md
@@ -85,5 +85,5 @@ repository.
 ## Related
 
 - [Workspaces Overview](./workspaces.md)
-- [SSH Workspaces](./ssh.md)
+- [SSH Runtime](./runtime/ssh.md)
 - [VS Code Remote-SSH Documentation](https://code.visualstudio.com/docs/remote/ssh)
diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -2,20 +2,23 @@
 
 Workspaces in mux provide isolated development environments for parallel agent work. Each workspace maintains its own Git state, allowing you to explore different approaches, run multiple tasks simultaneously, or test changes without affecting your main repository.
 
-## Workspace Types
+## Runtimes
 
-mux supports two workspace backends:
+mux supports three [runtime types](./runtime/index.md):
 
-- **[Local Workspaces](./local.md)**: Use [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes.
+- **[Worktree](./runtime/worktree.md)** (default): Isolated directories using [git worktrees](https://git-scm.com/docs/git-worktree). Worktrees share `.git` with your main repository while maintaining independent working changes.
 
-- **[SSH Workspaces](./ssh.md)**: Regular git clones on a remote server accessed via SSH. These are completely independent repositories stored on the remote machine.
+- **[Local](./runtime/local.md)**: Run directly in your project directory. No isolation—best for quick edits to your working copy.
 
-## Choosing a Backend
+- **[SSH](./runtime/ssh.md)**: Remote execution over SSH. Ideal for heavy workloads, security isolation, or leveraging remote infrastructure.
 
-The workspace backend is selected when you create a workspace:
+## Choosing a Runtime
 
-- **Local**: Best for fast iteration, local testing, and when you want to leverage your local machine's resources
-- **SSH**: Ideal for heavy workloads, long-running tasks, or when you need access to remote infrastructure
+The runtime is selected when you create a workspace:
+
+- **Worktree** (default): Best for parallel agent work with isolation
+- **Local**: Quick tasks in your current working copy
+- **SSH**: Heavy workloads, security, or remote infrastructure
 
 ## Key Concepts
 
diff --git a/src/browser/App.tsx b/src/browser/App.tsx
@@ -559,27 +559,31 @@ function AppInner() {
         <div className="mobile-main-content flex min-w-0 flex-1 flex-col overflow-hidden">
           <div className="mobile-layout flex flex-1 overflow-hidden">
             {selectedWorkspace ? (
-              <ErrorBoundary
-                workspaceInfo={`${selectedWorkspace.projectName}/${selectedWorkspace.namedWorkspacePath?.split("/").pop() ?? selectedWorkspace.workspaceId}`}
-              >
-                <AIView
-                  key={selectedWorkspace.workspaceId}
-                  workspaceId={selectedWorkspace.workspaceId}
-                  projectPath={selectedWorkspace.projectPath}
-                  projectName={selectedWorkspace.projectName}
-                  branch={
-                    selectedWorkspace.namedWorkspacePath?.split("/").pop() ??
-                    selectedWorkspace.workspaceId
-                  }
-                  namedWorkspacePath={selectedWorkspace.namedWorkspacePath ?? ""}
-                  runtimeConfig={
-                    workspaceMetadata.get(selectedWorkspace.workspaceId)?.runtimeConfig
-                  }
-                  incompatibleRuntime={
-                    workspaceMetadata.get(selectedWorkspace.workspaceId)?.incompatibleRuntime
-                  }
-                />
-              </ErrorBoundary>
+              (() => {
+                const currentMetadata = workspaceMetadata.get(selectedWorkspace.workspaceId);
+                // Use metadata.name for workspace name (works for both worktree and local runtimes)
+                // Fallback to path-based derivation for legacy compatibility
+                const workspaceName =
+                  currentMetadata?.name ??
+                  selectedWorkspace.namedWorkspacePath?.split("/").pop() ??
+                  selectedWorkspace.workspaceId;
+                return (
+                  <ErrorBoundary
+                    workspaceInfo={`${selectedWorkspace.projectName}/${workspaceName}`}
+                  >
+                    <AIView
+                      key={selectedWorkspace.workspaceId}
+                      workspaceId={selectedWorkspace.workspaceId}
+                      projectPath={selectedWorkspace.projectPath}
+                      projectName={selectedWorkspace.projectName}
+                      branch={workspaceName}
+                      namedWorkspacePath={selectedWorkspace.namedWorkspacePath ?? ""}
+                      runtimeConfig={currentMetadata?.runtimeConfig}
+                      incompatibleRuntime={currentMetadata?.incompatibleRuntime}
+                    />
+                  </ErrorBoundary>
+                );
+              })()
             ) : creationProjectPath ? (
               (() => {
                 const projectPath = creationProjectPath;
diff --git a/src/node/services/ipcMain.ts b/src/node/services/ipcMain.ts
@@ -1512,7 +1512,7 @@ export class IpcMain {
         log.info(`Workspace ${workspaceId} metadata exists but not found in config`);
         return { success: true }; // Consider it already removed
       }
-      const { projectPath, workspacePath } = workspace;
+      const { projectPath, workspacePath: _workspacePath } = workspace;
 
       // Create runtime instance for this workspace
       // For local runtimes, workdir should be srcDir, not the individual workspace path
@@ -1538,12 +1538,14 @@ export class IpcMain {
       // Delete workspace metadata (fire and forget)
       void this.extensionMetadata.deleteWorkspace(workspaceId);
 
-      // Update config to remove the workspace from all projects
+      // Update config to remove the workspace by ID
+      // NOTE: Filter by ID, not path. For local project-dir runtimes, multiple workspaces
+      // share the same path (the project directory), so filtering by path would delete them all.
       const projectsConfig = this.config.loadConfigOrDefault();
       let configUpdated = false;
       for (const [_projectPath, projectConfig] of projectsConfig.projects.entries()) {
         const initialCount = projectConfig.workspaces.length;
-        projectConfig.workspaces = projectConfig.workspaces.filter((w) => w.path !== workspacePath);
+        projectConfig.workspaces = projectConfig.workspaces.filter((w) => w.id !== workspaceId);
         if (projectConfig.workspaces.length < initialCount) {
           configUpdated = true;
         }
diff --git a/tests/ipcMain/removeWorkspace.test.ts b/tests/ipcMain/removeWorkspace.test.ts
@@ -472,6 +472,132 @@ describeIntegration("Workspace deletion integration tests", () => {
     }
   );
 
+  // Local project-dir runtime specific tests
+  // These test the new LocalRuntime that uses project directory directly (no worktree isolation)
+  describe("Local project-dir runtime tests", () => {
+    const getLocalProjectDirConfig = (): RuntimeConfig => {
+      // Local project-dir: type "local" without srcBaseDir
+      return { type: "local" };
+    };
+
+    test.concurrent(
+      "should delete only the specified workspace, not all workspaces with same path",
+      async () => {
+        const env = await createTestEnvironment();
+        const tempGitRepo = await createTempGitRepo();
+
+        try {
+          const runtimeConfig = getLocalProjectDirConfig();
+
+          // Create multiple local workspaces for the same project
+          // All will have the same workspacePath (the project directory)
+          const { workspaceId: ws1Id } = await createWorkspaceWithInit(
+            env,
+            tempGitRepo,
+            "local-ws-1",
+            runtimeConfig,
+            true, // waitForInit
+            false // not SSH
+          );
+
+          const { workspaceId: ws2Id } = await createWorkspaceWithInit(
+            env,
+            tempGitRepo,
+            "local-ws-2",
+            runtimeConfig,
+            true,
+            false
+          );
+
+          const { workspaceId: ws3Id } = await createWorkspaceWithInit(
+            env,
+            tempGitRepo,
+            "local-ws-3",
+            runtimeConfig,
+            true,
+            false
+          );
+
+          // Verify all three workspaces exist in config
+          let config = env.config.loadConfigOrDefault();
+          let project = config.projects.get(tempGitRepo);
+          expect(project?.workspaces.length).toBe(3);
+          expect(project?.workspaces.some((w) => w.id === ws1Id)).toBe(true);
+          expect(project?.workspaces.some((w) => w.id === ws2Id)).toBe(true);
+          expect(project?.workspaces.some((w) => w.id === ws3Id)).toBe(true);
+
+          // Delete workspace 2
+          const deleteResult = await env.mockIpcRenderer.invoke(
+            IPC_CHANNELS.WORKSPACE_REMOVE,
+            ws2Id
+          );
+          expect(deleteResult.success).toBe(true);
+
+          // Verify ONLY workspace 2 was removed, workspaces 1 and 3 still exist
+          config = env.config.loadConfigOrDefault();
+          project = config.projects.get(tempGitRepo);
+
+          // BUG: Currently all 3 get deleted because they share the same workspacePath
+          // After fix: Only ws2 should be deleted
+          expect(project?.workspaces.length).toBe(2);
+          expect(project?.workspaces.some((w) => w.id === ws1Id)).toBe(true);
+          expect(project?.workspaces.some((w) => w.id === ws2Id)).toBe(false); // deleted
+          expect(project?.workspaces.some((w) => w.id === ws3Id)).toBe(true);
+
+          // Cleanup remaining workspaces
+          await env.mockIpcRenderer.invoke(IPC_CHANNELS.WORKSPACE_REMOVE, ws1Id);
+          await env.mockIpcRenderer.invoke(IPC_CHANNELS.WORKSPACE_REMOVE, ws3Id);
+        } finally {
+          await cleanupTestEnvironment(env);
+          await cleanupTempGitRepo(tempGitRepo);
+        }
+      },
+      TEST_TIMEOUT_LOCAL_MS
+    );
+
+    test.concurrent(
+      "should not delete project directory when deleting local workspace",
+      async () => {
+        const env = await createTestEnvironment();
+        const tempGitRepo = await createTempGitRepo();
+
+        try {
+          const runtimeConfig = getLocalProjectDirConfig();
+          const { workspaceId } = await createWorkspaceWithInit(
+            env,
+            tempGitRepo,
+            "local-ws-test",
+            runtimeConfig,
+            true,
+            false
+          );
+
+          // Verify workspace exists
+          const existsBefore = await workspaceExists(env, workspaceId);
+          expect(existsBefore).toBe(true);
+
+          // Delete workspace
+          const deleteResult = await env.mockIpcRenderer.invoke(
+            IPC_CHANNELS.WORKSPACE_REMOVE,
+            workspaceId
+          );
+          expect(deleteResult.success).toBe(true);
+
+          // Project directory should still exist (LocalRuntime.deleteWorkspace is a no-op)
+          const projectDirExists = await fs
+            .access(tempGitRepo)
+            .then(() => true)
+            .catch(() => false);
+          expect(projectDirExists).toBe(true);
+        } finally {
+          await cleanupTestEnvironment(env);
+          await cleanupTempGitRepo(tempGitRepo);
+        }
+      },
+      TEST_TIMEOUT_LOCAL_MS
+    );
+  });
+
   // SSH-specific tests (unpushed refs only matter for SSH, not local worktrees which share .git)
   describe("SSH-only tests", () => {
     const getRuntimeConfig = (branchName: string): RuntimeConfig | undefined => {
