🤖 feat: allow workspaces on git branches with slashes (e.g. feature/foo)

Enable creating and opening workspaces on existing git branches that contain
forward slashes, a common naming convention like `feature/foo` or
`bugfix/issue-123`.

- Add `encodeWorkspaceNameForDir()` helper that uses `encodeURIComponent()`
- `feature/foo` → directory `feature%2Ffoo` (not nested directories)
- Simple names like `main` remain unchanged
- Applied in WorktreeRuntime, SSHRuntime, and Config.addWorkspace()

- Add `validateGitBranchName()` for worktree/SSH runtimes
- Allows forward slashes (plus existing charset: a-z, 0-9, _, -)
- Rejects: leading/trailing slashes, consecutive slashes, 64+ chars
- Original `validateWorkspaceName()` still used for local runtime

- workspaceService.create/rename/fork now choose validator based on runtime type
- Git runtimes (worktree/SSH) use slash-permitting validation
- Local runtime uses strict validation

- Command palette now uses `metadata.name` for display (not path derivation)
- Correctly displays `feature/foo` instead of `foo` or `feature%2Ffoo`

- Existing workspaces continue to work (no migration needed)
- Old workspace paths without encoding are handled correctly
- Legacy fallback paths in config.ts unchanged

Signed-off-by: Thomas Kosiewski <tk@coder.com>

---
_Generated with `mux` • Model: `anthropic:claude-opus-4-5` • Thinking: `high`_

Change-Id: I650cebc612b2111cff8ae75a94a6a50fe7217165

Author: ThomasK33

src/browser/utils/commands/sources.ts

@@ -209,8 +209,10 @@ export function buildCoreSources(p: BuildSourcesParams): Array<() => CommandActi
 
     // Remove current workspace (rename action intentionally omitted until we add a proper modal)
     if (selected?.namedWorkspacePath) {
-      const workspaceDisplayName = `${selected.projectName}/${selected.namedWorkspacePath.split("/").pop() ?? selected.namedWorkspacePath}`;
       const selectedMeta = p.workspaceMetadata.get(selected.workspaceId);
+      // Use metadata.name if available (handles slashes correctly), fallback to path derivation
+      const workspaceName = selectedMeta?.name ?? selected.namedWorkspacePath;
+      const workspaceDisplayName = `${selected.projectName}/${workspaceName}`;
       list.push({
         id: CommandIds.workspaceOpenTerminalCurrent(),
         title: "Open Current Workspace in Terminal",

src/common/utils/validation/workspaceValidation.test.ts

@@ -1,4 +1,4 @@
-import { validateWorkspaceName } from "./workspaceValidation";
+import { validateWorkspaceName, validateGitBranchName } from "./workspaceValidation";
 
 describe("validateWorkspaceName", () => {
   describe("valid names", () => {
@@ -82,3 +82,81 @@ describe("validateWorkspaceName", () => {
     });
   });
 });
+
+describe("validateGitBranchName", () => {
+  describe("valid names", () => {
+    test("accepts simple names (same as validateWorkspaceName)", () => {
+      expect(validateGitBranchName("main").valid).toBe(true);
+      expect(validateGitBranchName("feature").valid).toBe(true);
+      expect(validateGitBranchName("my-branch").valid).toBe(true);
+      expect(validateGitBranchName("my_branch").valid).toBe(true);
+      expect(validateGitBranchName("branch123").valid).toBe(true);
+    });
+
+    test("accepts forward slashes (unlike validateWorkspaceName)", () => {
+      expect(validateGitBranchName("feature/foo").valid).toBe(true);
+      expect(validateGitBranchName("feature/sub/deep").valid).toBe(true);
+      expect(validateGitBranchName("bugfix/issue-123").valid).toBe(true);
+      expect(validateGitBranchName("release/v1_0").valid).toBe(true); // dots not allowed, use underscore
+    });
+
+    test("accepts 64 characters", () => {
+      const name = "a".repeat(64);
+      expect(validateGitBranchName(name).valid).toBe(true);
+    });
+
+    test("accepts 64 characters with slashes", () => {
+      // 31 chars + "/" + 32 chars = 64 chars
+      const name = "a".repeat(31) + "/" + "b".repeat(32);
+      expect(validateGitBranchName(name).valid).toBe(true);
+    });
+  });
+
+  describe("invalid names", () => {
+    test("rejects empty string", () => {
+      const result = validateGitBranchName("");
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("empty");
+    });
+
+    test("rejects names over 64 characters", () => {
+      const name = "a".repeat(65);
+      const result = validateGitBranchName(name);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("64 characters");
+    });
+
+    test("rejects leading slash", () => {
+      const result = validateGitBranchName("/feature");
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("start or end with /");
+    });
+
+    test("rejects trailing slash", () => {
+      const result = validateGitBranchName("feature/");
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("start or end with /");
+    });
+
+    test("rejects consecutive slashes", () => {
+      const result = validateGitBranchName("feature//foo");
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("consecutive slashes");
+    });
+
+    test("rejects uppercase letters", () => {
+      const result = validateGitBranchName("Feature/Foo");
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("a-z");
+    });
+
+    test("rejects special characters (except slash)", () => {
+      expect(validateGitBranchName("branch@123").valid).toBe(false);
+      expect(validateGitBranchName("branch#123").valid).toBe(false);
+      expect(validateGitBranchName("branch$123").valid).toBe(false);
+      expect(validateGitBranchName("branch%123").valid).toBe(false);
+      expect(validateGitBranchName("branch.123").valid).toBe(false);
+      expect(validateGitBranchName("branch\\123").valid).toBe(false);
+    });
+  });
+});

src/common/utils/validation/workspaceValidation.ts

@@ -1,5 +1,5 @@
 /**
- * Validates workspace name format
+ * Validates workspace name format (for non-git runtimes)
  * - Must be 1-64 characters long
  * - Can only contain: lowercase letters, digits, underscore, hyphen
  * - Pattern: [a-z0-9_-]{1,64}
@@ -23,3 +23,47 @@ export function validateWorkspaceName(name: string): { valid: boolean; error?: s
 
   return { valid: true };
 }
+
+/**
+ * Validates git branch names for worktree/SSH runtimes
+ * - Must be 1-64 characters long
+ * - Can only contain: lowercase letters, digits, underscore, hyphen, forward slash
+ * - Cannot start or end with slash
+ * - Cannot have consecutive slashes
+ * - Pattern: [a-z0-9_-]+(/[a-z0-9_-]+)*
+ *
+ * This allows common branch naming conventions like:
+ * - feature/foo
+ * - bugfix/issue-123
+ * - release/v1_0 (note: dots are not supported, use underscores)
+ */
+export function validateGitBranchName(name: string): { valid: boolean; error?: string } {
+  if (!name || name.length === 0) {
+    return { valid: false, error: "Branch name cannot be empty" };
+  }
+
+  if (name.length > 64) {
+    return { valid: false, error: "Branch name cannot exceed 64 characters" };
+  }
+
+  // Check for leading/trailing slashes
+  if (name.startsWith("/") || name.endsWith("/")) {
+    return { valid: false, error: "Branch name cannot start or end with /" };
+  }
+
+  // Check for consecutive slashes
+  if (name.includes("//")) {
+    return { valid: false, error: "Branch name cannot contain consecutive slashes" };
+  }
+
+  // Pattern: one or more segments of [a-z0-9_-]+ separated by single slashes
+  const validPattern = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)*$/;
+  if (!validPattern.test(name)) {
+    return {
+      valid: false,
+      error: "Use only: a-z, 0-9, _, -, /",
+    };
+  }
+
+  return { valid: true };
+}

src/common/utils/workspaceDirName.test.ts

@@ -0,0 +1,41 @@
+import { encodeWorkspaceNameForDir, decodeWorkspaceNameFromDir } from "./workspaceDirName";
+
+describe("encodeWorkspaceNameForDir", () => {
+  test("leaves simple names unchanged", () => {
+    expect(encodeWorkspaceNameForDir("main")).toBe("main");
+    expect(encodeWorkspaceNameForDir("feature")).toBe("feature");
+    expect(encodeWorkspaceNameForDir("my-branch")).toBe("my-branch");
+    expect(encodeWorkspaceNameForDir("my_branch")).toBe("my_branch");
+    expect(encodeWorkspaceNameForDir("branch123")).toBe("branch123");
+  });
+
+  test("encodes forward slashes", () => {
+    expect(encodeWorkspaceNameForDir("feature/foo")).toBe("feature%2Ffoo");
+    expect(encodeWorkspaceNameForDir("feature/sub/deep")).toBe("feature%2Fsub%2Fdeep");
+  });
+
+  test("encodes other special characters", () => {
+    // These are less common but encodeURIComponent handles them
+    expect(encodeWorkspaceNameForDir("test@branch")).toBe("test%40branch");
+    expect(encodeWorkspaceNameForDir("test#branch")).toBe("test%23branch");
+  });
+});
+
+describe("decodeWorkspaceNameFromDir", () => {
+  test("decodes encoded names back to original", () => {
+    expect(decodeWorkspaceNameFromDir("feature%2Ffoo")).toBe("feature/foo");
+    expect(decodeWorkspaceNameFromDir("feature%2Fsub%2Fdeep")).toBe("feature/sub/deep");
+  });
+
+  test("leaves unencoded names unchanged", () => {
+    expect(decodeWorkspaceNameFromDir("main")).toBe("main");
+    expect(decodeWorkspaceNameFromDir("my-branch")).toBe("my-branch");
+  });
+
+  test("roundtrip: encode then decode returns original", () => {
+    const names = ["main", "feature/foo", "feature/sub/deep", "my-branch_123"];
+    for (const name of names) {
+      expect(decodeWorkspaceNameFromDir(encodeWorkspaceNameForDir(name))).toBe(name);
+    }
+  });
+});

src/common/utils/workspaceDirName.ts

@@ -0,0 +1,23 @@
+/**
+ * Encodes a workspace name for safe use as a filesystem directory name.
+ *
+ * Uses encodeURIComponent which:
+ * - Is deterministic and collision-free
+ * - Leaves simple names unchanged (e.g., "main", "foo-bar")
+ * - Converts slashes: "feature/foo" → "feature%2Ffoo"
+ *
+ * This ensures workspace names like "feature/foo" don't create nested directories.
+ */
+export function encodeWorkspaceNameForDir(workspaceName: string): string {
+  return encodeURIComponent(workspaceName);
+}
+
+/**
+ * Decodes a filesystem directory name back to the original workspace name.
+ *
+ * Useful for debugging and diagnostics. Not needed for normal runtime operations
+ * since we always work with the original workspace name from metadata.
+ */
+export function decodeWorkspaceNameFromDir(dirName: string): string {
+  return decodeURIComponent(dirName);
+}

src/node/config.ts

@@ -12,6 +12,7 @@ import { isIncompatibleRuntimeConfig } from "@/common/utils/runtimeCompatibility
 import { getMuxHome } from "@/common/constants/paths";
 import { PlatformPaths } from "@/common/utils/paths";
 import { stripTrailingSlashes } from "@/node/utils/pathUtils";
+import { encodeWorkspaceNameForDir } from "@/common/utils/workspaceDirName";
 
 // Re-export project types from dedicated types file (for preload usage)
 export type { Workspace, ProjectConfig, ProjectsConfig };
@@ -411,7 +412,8 @@ export class Config {
       // Compute workspace path - this is only for legacy config migration
       // New code should use Runtime.getWorkspacePath() directly
       const projectName = this.getProjectName(projectPath);
-      const workspacePath = path.join(this.srcDir, projectName, metadata.name);
+      const dirName = encodeWorkspaceNameForDir(metadata.name);
+      const workspacePath = path.join(this.srcDir, projectName, dirName);
       const workspaceEntry: Workspace = {
         path: workspacePath,
         id: metadata.id,

src/node/runtime/SSHRuntime.ts

@@ -26,6 +26,7 @@ import { getErrorMessage } from "@/common/utils/errors";
 import { execAsync, DisposableProcess } from "@/node/utils/disposableExec";
 import { getControlPath, sshConnectionPool, type SSHRuntimeConfig } from "./sshConnectionPool";
 import { getBashPath } from "@/node/utils/main/bashPath";
+import { encodeWorkspaceNameForDir } from "@/common/utils/workspaceDirName";
 
 /**
  * Shell-escape helper for remote bash.
@@ -845,7 +846,8 @@ export class SSHRuntime implements Runtime {
 
   getWorkspacePath(projectPath: string, workspaceName: string): string {
     const projectName = getProjectName(projectPath);
-    return path.posix.join(this.config.srcBaseDir, projectName, workspaceName);
+    const dirName = encodeWorkspaceNameForDir(workspaceName);
+    return path.posix.join(this.config.srcBaseDir, projectName, dirName);
   }
 
   async createWorkspace(params: WorkspaceCreationParams): Promise<WorkspaceCreationResult> {

src/node/runtime/WorktreeRuntime.test.ts

@@ -28,6 +28,23 @@ describe("WorktreeRuntime constructor", () => {
     const expected = path.join(os.homedir(), "project", "branch");
     expect(workspacePath).toBe(expected);
   });
+
+  it("should encode slashes in workspace names", () => {
+    const runtime = new WorktreeRuntime("/absolute/path");
+    const workspacePath = runtime.getWorkspacePath("/home/user/project", "feature/foo");
+
+    // Slash should be encoded as %2F, not create nested directories
+    const expected = path.join("/absolute/path", "project", "feature%2Ffoo");
+    expect(workspacePath).toBe(expected);
+  });
+
+  it("should encode multiple slashes in workspace names", () => {
+    const runtime = new WorktreeRuntime("/absolute/path");
+    const workspacePath = runtime.getWorkspacePath("/home/user/project", "feature/sub/deep");
+
+    const expected = path.join("/absolute/path", "project", "feature%2Fsub%2Fdeep");
+    expect(workspacePath).toBe(expected);
+  });
 });
 
 describe("WorktreeRuntime.resolvePath", () => {

src/node/runtime/WorktreeRuntime.ts

@@ -18,14 +18,16 @@ import { getErrorMessage } from "@/common/utils/errors";
 import { expandTilde } from "./tildeExpansion";
 import { LocalBaseRuntime } from "./LocalBaseRuntime";
 import { toPosixPath } from "@/node/utils/paths";
+import { encodeWorkspaceNameForDir } from "@/common/utils/workspaceDirName";
 
 /**
  * Worktree runtime implementation that executes commands and file operations
  * directly on the host machine using Node.js APIs.
  *
  * This runtime uses git worktrees for workspace isolation:
- * - Workspaces are created in {srcBaseDir}/{projectName}/{workspaceName}
+ * - Workspaces are created in {srcBaseDir}/{projectName}/{encodedWorkspaceName}
  * - Each workspace is a git worktree with its own branch
+ * - Workspace names containing "/" are encoded (e.g., "feature/foo" → "feature%2Ffoo")
  */
 export class WorktreeRuntime extends LocalBaseRuntime {
   private readonly srcBaseDir: string;
@@ -38,7 +40,8 @@ export class WorktreeRuntime extends LocalBaseRuntime {
 
   getWorkspacePath(projectPath: string, workspaceName: string): string {
     const projectName = getProjectName(projectPath);
-    return path.join(this.srcBaseDir, projectName, workspaceName);
+    const dirName = encodeWorkspaceNameForDir(workspaceName);
+    return path.join(this.srcBaseDir, projectName, dirName);
   }
 
   async createWorkspace(params: WorkspaceCreationParams): Promise<WorkspaceCreationResult> {