🤖 Clarify workspace ID vs name vs path architecture (#420)

Fixes terminology inconsistencies that could mislead contributors about
workspace identity vs directory naming.

## Changes

**Parameter renaming:**
- `config.getWorkspacePath(workspaceId)` →
`getWorkspacePath(directoryName)`
- `CreateWorktreeOptions.workspaceId` → `directoryName`

**Documentation:**
- Clarified "Workspace Path Architecture" in config.ts to separate
workspace ID (stable identifier) from directory name (branch name)
- Removed outdated symlink references (directories use workspace names
directly now)

**Test fixtures:**
- Updated App.stories.tsx to use hex-like IDs (e.g., `1a2b3c4d5e`)
matching production format

All changes are non-functional: comments, docs, parameter names, and
test fixtures only.

_Generated with `cmux`_

Author: ammar-agent

src/App.stories.tsx

@@ -182,15 +182,16 @@ export const SingleProject: Story = {
 
 export const MultipleProjects: Story = {
   render: () => {
+    // Note: Workspace IDs are fixtures using hex-like format (production uses random 10-hex chars)
     const projects = new Map<string, ProjectConfig>([
       [
         "/home/user/projects/frontend",
         {
           workspaces: [
-            { path: "/home/user/.cmux/src/frontend/main", id: "frontend-main", name: "main" },
+            { path: "/home/user/.cmux/src/frontend/main", id: "1a2b3c4d5e", name: "main" },
             {
               path: "/home/user/.cmux/src/frontend/redesign",
-              id: "frontend-redesign",
+              id: "2b3c4d5e6f",
               name: "redesign",
             },
           ],
@@ -200,11 +201,11 @@ export const MultipleProjects: Story = {
         "/home/user/projects/backend",
         {
           workspaces: [
-            { path: "/home/user/.cmux/src/backend/main", id: "backend-main", name: "main" },
-            { path: "/home/user/.cmux/src/backend/api-v2", id: "backend-api-v2", name: "api-v2" },
+            { path: "/home/user/.cmux/src/backend/main", id: "3c4d5e6f7a", name: "main" },
+            { path: "/home/user/.cmux/src/backend/api-v2", id: "4d5e6f7a8b", name: "api-v2" },
             {
               path: "/home/user/.cmux/src/backend/db-migration",
-              id: "backend-db-migration",
+              id: "5e6f7a8b9c",
               name: "db-migration",
             },
           ],
@@ -214,50 +215,50 @@ export const MultipleProjects: Story = {
         "/home/user/projects/mobile",
         {
           workspaces: [
-            { path: "/home/user/.cmux/src/mobile/main", id: "mobile-main", name: "main" },
+            { path: "/home/user/.cmux/src/mobile/main", id: "6f7a8b9c0d", name: "main" },
           ],
         },
       ],
     ]);
 
     const workspaces: FrontendWorkspaceMetadata[] = [
       {
-        id: "frontend-main",
+        id: "1a2b3c4d5e",
         name: "main",
         projectPath: "/home/user/projects/frontend",
         projectName: "frontend",
         namedWorkspacePath: "/home/user/.cmux/src/frontend/main",
       },
       {
-        id: "frontend-redesign",
+        id: "2b3c4d5e6f",
         name: "redesign",
         projectPath: "/home/user/projects/frontend",
         projectName: "frontend",
         namedWorkspacePath: "/home/user/.cmux/src/frontend/redesign",
       },
       {
-        id: "backend-main",
+        id: "3c4d5e6f7a",
         name: "main",
         projectPath: "/home/user/projects/backend",
         projectName: "backend",
         namedWorkspacePath: "/home/user/.cmux/src/backend/main",
       },
       {
-        id: "backend-api-v2",
+        id: "4d5e6f7a8b",
         name: "api-v2",
         projectPath: "/home/user/projects/backend",
         projectName: "backend",
         namedWorkspacePath: "/home/user/.cmux/src/backend/api-v2",
       },
       {
-        id: "backend-db-migration",
+        id: "5e6f7a8b9c",
         name: "db-migration",
         projectPath: "/home/user/projects/backend",
         projectName: "backend",
         namedWorkspacePath: "/home/user/.cmux/src/backend/db-migration",
       },
       {
-        id: "mobile-main",
+        id: "6f7a8b9c0d",
         name: "main",
         projectPath: "/home/user/projects/mobile",
         projectName: "mobile",

src/App.tsx

@@ -219,7 +219,7 @@ function AppInner() {
 
   const openWorkspaceInTerminal = useCallback(
     (workspaceId: string) => {
-      // Look up workspace metadata to get the named path (user-friendly symlink)
+      // Look up workspace metadata to get the worktree path (directory uses workspace name)
       const metadata = workspaceMetadata.get(workspaceId);
       if (metadata) {
         void window.api.workspace.openTerminal(metadata.namedWorkspacePath);

src/components/WorkspaceListItem.tsx

@@ -13,7 +13,7 @@ import { cn } from "@/lib/utils";
 export interface WorkspaceSelection {
   projectPath: string;
   projectName: string;
-  namedWorkspacePath: string; // User-friendly path (symlink for new workspaces)
+  namedWorkspacePath: string; // Worktree path (directory uses workspace name)
   workspaceId: string;
 }
 export interface WorkspaceListItemProps {

src/config.ts

@@ -126,12 +126,12 @@ export class Config {
   }
 
   /**
-   * Get the workspace worktree path for a given workspace ID.
-   * New workspaces use stable IDs, legacy workspaces use the old format.
+   * Get the workspace worktree path for a given directory name.
+   * The directory name is the workspace name (branch name).
    */
-  getWorkspacePath(projectPath: string, workspaceId: string): string {
+  getWorkspacePath(projectPath: string, directoryName: string): string {
     const projectName = this.getProjectName(projectPath);
-    return path.join(this.srcDir, projectName, workspaceId);
+    return path.join(this.srcDir, projectName, directoryName);
   }
 
   /**
@@ -212,10 +212,13 @@ export class Config {
   /**
    * Workspace Path Architecture:
    *
-   * Workspace paths are computed on-demand from projectPath + workspaceId using
-   * config.getWorkspacePath(). This ensures single source of truth for path format.
+   * Workspace paths are computed on-demand from projectPath + workspace name using
+   * config.getWorkspacePath(projectPath, directoryName). This ensures a single source of truth.
    *
-   * Backend: Uses getWorkspacePath(metadata.projectPath, metadata.name) for directory paths (worktree directories use name)
+   * - Worktree directory name: uses workspace.name (the branch name)
+   * - Workspace ID: stable random identifier for identity and sessions (not used for directories)
+   *
+   * Backend: Uses getWorkspacePath(metadata.projectPath, metadata.name) for worktree directory paths
    * Frontend: Gets enriched metadata with paths via IPC (FrontendWorkspaceMetadata)
    *
    * WorkspaceMetadata.workspacePath is deprecated and will be removed. Use computed

src/git.ts

@@ -12,7 +12,7 @@ export interface WorktreeResult {
 export interface CreateWorktreeOptions {
   trunkBranch: string;
   /** Directory name to use for the worktree (if not provided, uses branchName) */
-  workspaceId?: string;
+  directoryName?: string;
 }
 
 export async function listLocalBranches(projectPath: string): Promise<string[]> {
@@ -76,9 +76,9 @@ export async function createWorktree(
   options: CreateWorktreeOptions
 ): Promise<WorktreeResult> {
   try {
-    // Use workspaceId for directory name if provided, otherwise fall back to branchName (legacy)
-    const directoryName = options.workspaceId ?? branchName;
-    const workspacePath = config.getWorkspacePath(projectPath, directoryName);
+    // Use directoryName if provided, otherwise fall back to branchName (legacy)
+    const dirName = options.directoryName ?? branchName;
+    const workspacePath = config.getWorkspacePath(projectPath, dirName);
     const { trunkBranch } = options;
     const normalizedTrunkBranch = typeof trunkBranch === "string" ? trunkBranch.trim() : "";
 

src/services/ipcMain.ts

@@ -275,7 +275,7 @@ export class IpcMain {
         // Create the git worktree with the workspace name as directory name
         const result = await createWorktree(this.config, projectPath, branchName, {
           trunkBranch: normalizedTrunkBranch,
-          workspaceId: branchName, // Use name for directory (workspaceId param is misnamed, it's directoryName)
+          directoryName: branchName,
         });
 
         if (result.success && result.path) {
@@ -504,7 +504,7 @@ export class IpcMain {
           // Create new git worktree branching from source workspace's branch
           const result = await createWorktree(this.config, foundProjectPath, newName, {
             trunkBranch: sourceBranch,
-            workspaceId: newName, // Use name for directory (workspaceId param is misnamed, it's directoryName)
+            directoryName: newName,
           });
 
           if (!result.success || !result.path) {

src/types/workspace.ts

@@ -30,9 +30,9 @@ export const WorkspaceMetadataSchema = z.object({
  * - name is the branch/workspace name (e.g., "feature-branch")
  *
  * Path handling:
- * - Worktree paths are computed on-demand via config.getWorkspacePath(projectPath, id)
+ * - Worktree paths are computed on-demand via config.getWorkspacePath(projectPath, name)
+ * - Directory name uses workspace.name (the branch name)
  * - This avoids storing redundant derived data
- * - Frontend can show symlink paths, backend uses real paths
  */
 export interface WorkspaceMetadata {
   /** Stable unique identifier (10 hex chars for new workspaces, legacy format for old) */

src/utils/ui/workspaceFiltering.test.ts

@@ -11,7 +11,7 @@ describe("partitionWorkspacesByAge", () => {
     name: `workspace-${id}`,
     projectName: "test-project",
     projectPath: "/test/project",
-    namedWorkspacePath: `/test/project/.worktrees/${id}`,
+    namedWorkspacePath: `/test/project/workspace-${id}`, // Path is arbitrary for this test
   });
 
   it("should partition workspaces into recent and old based on 24-hour threshold", () => {

tests/ipcMain/removeWorkspace.test.ts

@@ -40,14 +40,14 @@ describeIntegration("IpcMain remove workspace integration tests", () => {
           .catch(() => false);
         expect(worktreeExistsBefore).toBe(true);
 
-        // Get the symlink path before removing
+        // Get the worktree directory path before removing
         const projectName = tempGitRepo.split("/").pop() || "unknown";
-        const symlinkPath = `${env.config.srcDir}/${projectName}/${metadata.name}`;
-        const symlinkExistsBefore = await fs
-          .lstat(symlinkPath)
+        const worktreeDirPath = `${env.config.srcDir}/${projectName}/${metadata.name}`;
+        const worktreeDirExistsBefore = await fs
+          .lstat(worktreeDirPath)
           .then(() => true)
           .catch(() => false);
-        expect(symlinkExistsBefore).toBe(true);
+        expect(worktreeDirExistsBefore).toBe(true);
 
         // Remove the workspace
         const removeResult = await env.mockIpcRenderer.invoke(
@@ -60,12 +60,12 @@ describeIntegration("IpcMain remove workspace integration tests", () => {
         const worktreeRemoved = await waitForFileNotExists(workspacePath, 5000);
         expect(worktreeRemoved).toBe(true);
 
-        // Verify symlink is removed
-        const symlinkExistsAfter = await fs
-          .lstat(symlinkPath)
+        // Verify worktree directory is removed
+        const worktreeDirExistsAfter = await fs
+          .lstat(worktreeDirPath)
           .then(() => true)
           .catch(() => false);
-        expect(symlinkExistsAfter).toBe(false);
+        expect(worktreeDirExistsAfter).toBe(false);
 
         // Verify workspace is no longer in config
         const config = env.config.loadConfigOrDefault();