feat: support '/' character in Git branch names used as workspace names

Allow forward slashes in workspace names (e.g. 'feature/my-branch') to
match common Git branch naming conventions.

Changes:
- Update validation regex to accept '/' (reject leading, trailing, and
  consecutive slashes)
- Add sanitizeWorkspaceNameForPath() that replaces '/' with '-' for
  filesystem paths
- Apply sanitization in getWorkspacePath() for WorktreeManager and
  SSHRuntime, with an absolute-path guard for in-place workspaces
- Add path collision detection in create(), rename(), and fork() scoped
  to path-based runtimes (worktree, SSH, devcontainer) using
  usesPathBasedDirs() helper
- Auto-fork collision retry loop scales with existing workspace count
  and uses normalized parent for legacy name compatibility
- Handle slashes in CoderSSHRuntime.toCoderCompatibleName()
- Ensure movePlanFile() creates destination directories via mkdir -p
- Same-path rename short-circuit runs best-effort git branch -m
- Update mobile validation, UI hints, and add comprehensive tests

Closes #407

Author: Coder

mobile/src/components/RenameWorkspaceModal.tsx

@@ -253,7 +253,8 @@ export function RenameWorkspaceModal({
                   variant="caption"
                   style={{ marginTop: spacing.sm, color: theme.colors.foregroundMuted }}
                 >
-                  Only lowercase letters, digits, underscore, and hyphen (1-64 characters)
+                  Only lowercase letters, digits, underscore, hyphen, and forward slash (1-64
+                  characters, no leading/trailing/consecutive slashes)
                 </ThemedText>
               )}
             </View>

mobile/src/utils/workspaceValidation.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "bun:test";
-import { validateWorkspaceName } from "./workspaceValidation";
+import { validateWorkspaceName, sanitizeWorkspaceNameForPath } from "./workspaceValidation";
 
 describe("validateWorkspaceName", () => {
   describe("empty names", () => {
@@ -55,6 +55,12 @@ describe("validateWorkspaceName", () => {
       expect(validateWorkspaceName("test-workspace-name")).toEqual({ valid: true });
     });
 
+    it("accepts forward slashes in branch-style names", () => {
+      expect(validateWorkspaceName("feature/my-branch")).toEqual({ valid: true });
+      expect(validateWorkspaceName("fix/issue-123")).toEqual({ valid: true });
+      expect(validateWorkspaceName("user/feature/deep")).toEqual({ valid: true });
+    });
+
     it("accepts mixed valid characters", () => {
       expect(validateWorkspaceName("feature-branch_123")).toEqual({ valid: true });
       expect(validateWorkspaceName("fix-001")).toEqual({ valid: true });
@@ -73,6 +79,18 @@ describe("validateWorkspaceName", () => {
       expect(result.error).toContain("lowercase letters");
     });
 
+    it("rejects leading slash", () => {
+      expect(validateWorkspaceName("/feature").valid).toBe(false);
+    });
+
+    it("rejects trailing slash", () => {
+      expect(validateWorkspaceName("feature/").valid).toBe(false);
+    });
+
+    it("rejects consecutive slashes", () => {
+      expect(validateWorkspaceName("feature//branch").valid).toBe(false);
+    });
+
     it("rejects special characters", () => {
       const invalidNames = [
         "test!",
@@ -92,7 +110,6 @@ describe("validateWorkspaceName", () => {
         "test}",
         "test|",
         "test\\",
-        "test/",
         "test?",
         "test<",
         "test>",
@@ -126,3 +143,25 @@ describe("validateWorkspaceName", () => {
     });
   });
 });
+
+describe("sanitizeWorkspaceNameForPath", () => {
+  it("returns name unchanged when no slashes", () => {
+    expect(sanitizeWorkspaceNameForPath("my-branch")).toBe("my-branch");
+  });
+
+  it("replaces single slash with hyphen", () => {
+    expect(sanitizeWorkspaceNameForPath("feature/my-branch")).toBe("feature-my-branch");
+  });
+
+  it("replaces multiple slashes in deep paths", () => {
+    expect(sanitizeWorkspaceNameForPath("user/feature/deep")).toBe("user-feature-deep");
+  });
+
+  it("preserves existing consecutive hyphens", () => {
+    expect(sanitizeWorkspaceNameForPath("feature--branch")).toBe("feature--branch");
+  });
+
+  it("does not collapse hyphens adjacent to replaced slash", () => {
+    expect(sanitizeWorkspaceNameForPath("feature/-branch")).toBe("feature--branch");
+  });
+});

mobile/src/utils/workspaceValidation.ts

@@ -1,8 +1,9 @@
 /**
  * Validates workspace name format
  * - Must be 1-64 characters long
- * - Can only contain: lowercase letters, digits, underscore, hyphen
- * - Pattern: [a-z0-9_-]{1,64}
+ * - Can only contain: lowercase letters, digits, underscore, hyphen, forward slash
+ * - No leading, trailing, or consecutive slashes
+ * - Pattern: [a-z0-9_-]+(?:\/[a-z0-9_-]+)* (1-64 characters)
  */
 export function validateWorkspaceName(name: string): { valid: boolean; error?: string } {
   if (!name || name.length === 0) {
@@ -13,13 +14,22 @@ export function validateWorkspaceName(name: string): { valid: boolean; error?: s
     return { valid: false, error: "Workspace name cannot exceed 64 characters" };
   }
 
-  const validPattern = /^[a-z0-9_-]+$/;
+  const validPattern = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)*$/;
   if (!validPattern.test(name)) {
     return {
       valid: false,
-      error: "Workspace name can only contain lowercase letters, digits, underscore, and hyphen",
+      error:
+        "Workspace names can only contain lowercase letters, numbers, hyphens, underscores, and forward slashes (no leading, trailing, or consecutive slashes)",
     };
   }
 
   return { valid: true };
 }
+
+/**
+ * Convert a workspace name to a filesystem-safe path component by replacing
+ * forward slashes with hyphens.
+ */
+export function sanitizeWorkspaceNameForPath(name: string): string {
+  return name.replace(/\//g, "-");
+}

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

@@ -1,4 +1,4 @@
-import { validateWorkspaceName } from "./workspaceValidation";
+import { validateWorkspaceName, sanitizeWorkspaceNameForPath } from "./workspaceValidation";
 
 describe("validateWorkspaceName", () => {
   describe("valid names", () => {
@@ -22,6 +22,12 @@ describe("validateWorkspaceName", () => {
       expect(validateWorkspaceName("feature-test-123").valid).toBe(true);
     });
 
+    test("accepts forward slashes in branch-style names", () => {
+      expect(validateWorkspaceName("feature/my-branch").valid).toBe(true);
+      expect(validateWorkspaceName("fix/issue-123").valid).toBe(true);
+      expect(validateWorkspaceName("user/feature/deep").valid).toBe(true);
+    });
+
     test("accepts combinations", () => {
       expect(validateWorkspaceName("feature-branch_123").valid).toBe(true);
       expect(validateWorkspaceName("a1-b2_c3").valid).toBe(true);
@@ -72,13 +78,45 @@ describe("validateWorkspaceName", () => {
       expect(validateWorkspaceName("branch%123").valid).toBe(false);
       expect(validateWorkspaceName("branch!123").valid).toBe(false);
       expect(validateWorkspaceName("branch.123").valid).toBe(false);
-      expect(validateWorkspaceName("branch/123").valid).toBe(false);
       expect(validateWorkspaceName("branch\\123").valid).toBe(false);
     });
 
-    test("rejects names with slashes", () => {
-      expect(validateWorkspaceName("feature/branch").valid).toBe(false);
+    test("rejects leading slash", () => {
+      expect(validateWorkspaceName("/feature").valid).toBe(false);
+    });
+
+    test("rejects trailing slash", () => {
+      expect(validateWorkspaceName("feature/").valid).toBe(false);
+    });
+
+    test("rejects consecutive slashes", () => {
+      expect(validateWorkspaceName("feature//branch").valid).toBe(false);
+    });
+
+    test("rejects backslashes", () => {
       expect(validateWorkspaceName("path\\to\\branch").valid).toBe(false);
     });
   });
 });
+
+describe("sanitizeWorkspaceNameForPath", () => {
+  test("returns name unchanged when no slashes", () => {
+    expect(sanitizeWorkspaceNameForPath("my-branch")).toBe("my-branch");
+  });
+
+  test("replaces single slash with hyphen", () => {
+    expect(sanitizeWorkspaceNameForPath("feature/my-branch")).toBe("feature-my-branch");
+  });
+
+  test("replaces multiple slashes in deep paths", () => {
+    expect(sanitizeWorkspaceNameForPath("user/feature/deep")).toBe("user-feature-deep");
+  });
+
+  test("preserves existing consecutive hyphens", () => {
+    expect(sanitizeWorkspaceNameForPath("feature--branch")).toBe("feature--branch");
+  });
+
+  test("does not collapse hyphens adjacent to replaced slash", () => {
+    expect(sanitizeWorkspaceNameForPath("feature/-branch")).toBe("feature--branch");
+  });
+});

src/common/utils/validation/workspaceValidation.ts

@@ -1,8 +1,9 @@
 /**
  * Validates workspace name format
  * - Must be 1-64 characters long
- * - Can only contain: lowercase letters, digits, underscore, hyphen
- * - Pattern: [a-z0-9_-]{1,64}
+ * - Can only contain: lowercase letters, digits, underscore, hyphen, forward slash
+ * - No leading, trailing, or consecutive slashes
+ * - Pattern: [a-z0-9_-]+(?:\/[a-z0-9_-]+)* (1-64 characters)
  */
 export function validateWorkspaceName(name: string): { valid: boolean; error?: string } {
   if (!name || name.length === 0) {
@@ -13,16 +14,25 @@ export function validateWorkspaceName(name: string): { valid: boolean; error?: s
     return { valid: false, error: "Workspace name cannot exceed 64 characters" };
   }
 
-  const validPattern = /^[a-z0-9_-]+$/;
+  const validPattern = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)*$/;
   if (!validPattern.test(name)) {
     return {
       valid: false,
-      // Workspace names become folder names, git branches, and session directories,
-      // so they need to be filesystem-safe across platforms.
       error:
-        "Workspace names can only contain lowercase letters, numbers, hyphens, and underscores",
+        "Workspace names can only contain lowercase letters, numbers, hyphens, underscores, and forward slashes (no leading, trailing, or consecutive slashes)",
     };
   }
 
   return { valid: true };
 }
+
+/**
+ * Convert a workspace name to a filesystem-safe path component by replacing
+ * forward slashes with hyphens.
+ *
+ * This allows git-style branch names like "feature/my-branch" to be used as
+ * workspace names while remaining safe for directory names and session paths.
+ */
+export function sanitizeWorkspaceNameForPath(name: string): string {
+  return name.replace(/\//g, "-");
+}

src/node/config.ts

@@ -39,6 +39,7 @@ import { isValidModelFormat, normalizeGatewayModel } from "@/common/utils/ai/mod
 import { ensurePrivateDirSync } from "@/node/utils/fs";
 import { stripTrailingSlashes } from "@/node/utils/pathUtils";
 import { getContainerName as getDockerContainerName } from "@/node/runtime/DockerRuntime";
+import { sanitizeWorkspaceNameForPath } from "@/common/utils/validation/workspaceValidation";
 
 // Re-export project/provider types from dedicated schema/types files (for preload usage)
 export type { Workspace, ProjectConfig, ProjectsConfig, ProviderConfig, CanonicalProvidersConfig };
@@ -1060,7 +1061,7 @@ export class Config {
       // otherwise fall back to worktree-style path for legacy compatibility
       const projectName = this.getProjectName(projectPath);
       const workspacePath =
-        metadata.namedWorkspacePath ?? path.join(this.srcDir, projectName, metadata.name);
+        metadata.namedWorkspacePath ?? path.join(this.srcDir, projectName, path.isAbsolute(metadata.name) ? metadata.name : sanitizeWorkspaceNameForPath(metadata.name));
       const workspaceEntry: Workspace = {
         path: workspacePath,
         id: metadata.id,

src/node/runtime/CoderSSHRuntime.ts

@@ -55,6 +55,7 @@ const CODER_NAME_REGEX = /^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$/;
  */
 function toCoderCompatibleName(name: string): string {
   return name
+    .replace(/\//g, "-") // Replace slashes with hyphens (branch-style names)
     .replace(/_/g, "-") // Replace underscores with hyphens
     .replace(/^-+|-+$/g, "") // Remove leading/trailing hyphens
     .replace(/-{2,}/g, "-"); // Collapse multiple hyphens

src/node/runtime/SSHRuntime.ts

@@ -48,6 +48,7 @@ import { getOriginUrlForBundle } from "./gitBundleSync";
 import { gitNoHooksPrefix } from "@/node/utils/gitNoHooksEnv";
 import type { PtyHandle, PtySessionParams, SSHTransport } from "./transports";
 import { streamToString, shescape } from "./streamUtils";
+import { sanitizeWorkspaceNameForPath } from "@/common/utils/validation/workspaceValidation";
 
 /** Name of the shared bare repo directory under each project on the remote. */
 const BASE_REPO_DIR = ".mux-base.git";
@@ -338,7 +339,13 @@ export class SSHRuntime extends RemoteRuntime {
 
   getWorkspacePath(projectPath: string, workspaceName: string): string {
     const projectName = getProjectName(projectPath);
-    return path.posix.join(this.config.srcBaseDir, projectName, workspaceName);
+    // In-place workspaces use absolute paths as workspace names — do not sanitize
+    // those since path.posix.join already handles them correctly and sanitizing
+    // would turn e.g. "/home/user/project" into "-home-user-project".
+    const safeName = path.posix.isAbsolute(workspaceName)
+      ? workspaceName
+      : sanitizeWorkspaceNameForPath(workspaceName);
+    return path.posix.join(this.config.srcBaseDir, projectName, safeName);
   }
 
   /**
@@ -1147,6 +1154,27 @@ export class SSHRuntime extends RemoteRuntime {
     const oldPath = this.getWorkspacePath(projectPath, oldName);
     const newPath = this.getWorkspacePath(projectPath, newName);
 
+    // Short-circuit: if the sanitized paths are identical (e.g. renaming
+    // "feature-a" <-> "feature/a"), skip the directory move — only the
+    // persisted name changes, not the physical location.
+    if (oldPath === newPath) {
+      // Still rename the git branch to maintain the workspace/branch name sync.
+      // Best-effort: branch rename can fail if the workspace is in detached HEAD
+      // state or if the branch has drifted, matching the normal rename path.
+      try {
+        const expandedOldPath = expandTildeForSSH(oldPath);
+        const branchStream = await this.exec(
+          `git -C ${shescape.quote(expandedOldPath)} branch -m ${shescape.quote(oldName)} ${shescape.quote(newName)}`,
+          { cwd: this.config.srcBaseDir, timeout: 10, abortSignal }
+        );
+        await branchStream.stdin.abort();
+        await branchStream.exitCode;
+      } catch {
+        // Best-effort: branch rename can fail (detached HEAD, branch drift, etc.)
+      }
+      return { success: true, oldPath, newPath };
+    }
+
     try {
       const expandedOldPath = expandTildeForSSH(oldPath);
       const expandedNewPath = expandTildeForSSH(newPath);