🤖 refactor: add Local/Worktree runtime distinction

- Add explicit 'worktree' RuntimeMode alongside 'local' and 'ssh'
- Local runtime uses project directory directly (no isolation)
- Worktree runtime creates isolated git worktrees (existing behavior)
- Extract LocalBaseRuntime for shared exec/file operations
- Update UI to show Local/Worktree/SSH options in creation controls
- Maintain backward compatibility: legacy local+srcBaseDir treated as worktree

_Generated with mux_

Author: ibetitsmike

src/browser/components/ChatInput/CreationControls.tsx

@@ -15,14 +15,18 @@ interface CreationControlsProps {
 
 /**
  * Additional controls shown only during workspace creation
- * - Trunk branch selector (which branch to fork from)
- * - Runtime mode (local vs SSH)
+ * - Trunk branch selector (which branch to fork from) - hidden for Local runtime
+ * - Runtime mode (Local, Worktree, SSH)
  */
 export function CreationControls(props: CreationControlsProps) {
+  // Local runtime doesn't need a trunk branch selector (uses project dir as-is)
+  const showTrunkBranchSelector =
+    props.branches.length > 0 && props.runtimeMode !== RUNTIME_MODE.LOCAL;
+
   return (
     <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
-      {/* Trunk Branch Selector */}
-      {props.branches.length > 0 && (
+      {/* Trunk Branch Selector - hidden for Local runtime */}
+      {showTrunkBranchSelector && (
         <div
           className="flex items-center gap-1"
           data-component="TrunkBranchGroup"
@@ -53,11 +57,13 @@ export function CreationControls(props: CreationControlsProps) {
           value={props.runtimeMode}
           options={[
             { value: RUNTIME_MODE.LOCAL, label: "Local" },
+            { value: RUNTIME_MODE.WORKTREE, label: "Worktree" },
             { value: RUNTIME_MODE.SSH, label: "SSH" },
           ]}
           onChange={(newMode) => {
             const mode = newMode as RuntimeMode;
-            props.onRuntimeChange(mode, mode === RUNTIME_MODE.LOCAL ? "" : props.sshHost);
+            // Clear SSH host when switching away from SSH
+            props.onRuntimeChange(mode, mode === RUNTIME_MODE.SSH ? props.sshHost : "");
           }}
           disabled={props.disabled}
           aria-label="Runtime mode"
@@ -77,8 +83,10 @@ export function CreationControls(props: CreationControlsProps) {
           <Tooltip className="tooltip" align="center" width="wide">
             <strong>Runtime:</strong>
             <br />
-            • Local: git worktree in ~/.mux/src
-            <br />• SSH: remote clone in ~/mux on SSH host
+            • Local: work directly in project directory (no isolation)
+            <br />
+            • Worktree: git worktree in ~/.mux/src (recommended)
+            <br />• SSH: remote clone on SSH host
           </Tooltip>
         </TooltipWrapper>
       </div>

src/browser/components/RuntimeBadge.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import { cn } from "@/common/lib/utils";
 import type { RuntimeConfig } from "@/common/types/runtime";
-import { isSSHRuntime } from "@/common/types/runtime";
+import { isSSHRuntime, isWorktreeRuntime, isLocalProjectRuntime } from "@/common/types/runtime";
 import { extractSshHostname } from "@/browser/utils/ui/runtimeBadge";
 import { TooltipWrapper, Tooltip } from "./Tooltip";
 
@@ -10,47 +10,122 @@ interface RuntimeBadgeProps {
   className?: string;
 }
 
+/** Server rack icon for SSH runtime */
+function SSHIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-label="SSH Runtime"
+    >
+      <rect x="2" y="2" width="12" height="4" rx="1" />
+      <rect x="2" y="10" width="12" height="4" rx="1" />
+      <line x1="5" y1="4" x2="5" y2="4" />
+      <line x1="5" y1="12" x2="5" y2="12" />
+    </svg>
+  );
+}
+
+/** Git branch icon for worktree runtime */
+function WorktreeIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-label="Worktree Runtime"
+    >
+      {/* Git branch icon */}
+      <circle cx="5" cy="4" r="2" />
+      <circle cx="11" cy="4" r="2" />
+      <circle cx="5" cy="12" r="2" />
+      <line x1="5" y1="6" x2="5" y2="10" />
+      <path d="M5 8 C 5 4 11 8 11 6" />
+    </svg>
+  );
+}
+
+/** Folder icon for local project-dir runtime (reserved for future use) */
+function _LocalIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-label="Local Runtime"
+    >
+      {/* Folder icon */}
+      <path d="M2 4 L2 13 L14 13 L14 5 L8 5 L7 3 L2 3 L2 4" />
+    </svg>
+  );
+}
+
 /**
- * Badge to display SSH runtime information.
- * Shows icon-only badge for SSH runtimes with hostname in tooltip.
+ * Badge to display runtime type information.
+ * Shows icon-only badge with tooltip describing the runtime type.
+ * - SSH: server icon with hostname
+ * - Worktree: git branch icon (isolated worktree)
+ * - Local: folder icon (project directory, no badge shown by default)
  */
 export function RuntimeBadge({ runtimeConfig, className }: RuntimeBadgeProps) {
-  const hostname = extractSshHostname(runtimeConfig);
-
-  if (!hostname) {
-    return null;
+  // SSH runtime: show server icon with hostname
+  if (isSSHRuntime(runtimeConfig)) {
+    const hostname = extractSshHostname(runtimeConfig);
+    return (
+      <TooltipWrapper inline>
+        <span
+          className={cn(
+            "inline-flex items-center rounded px-1 py-0.5",
+            "bg-accent/10 text-accent border border-accent/30",
+            className
+          )}
+        >
+          <SSHIcon />
+        </span>
+        <Tooltip align="right">SSH: {hostname ?? runtimeConfig.host}</Tooltip>
+      </TooltipWrapper>
+    );
   }
 
-  return (
-    <TooltipWrapper inline>
-      <span
-        className={cn(
-          "inline-flex items-center rounded px-1 py-0.5",
-          "bg-accent/10 text-accent border border-accent/30",
-          className
-        )}
-      >
-        <svg
-          width="12"
-          height="12"
-          viewBox="0 0 16 16"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="1.5"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-          aria-label="SSH Runtime"
+  // Worktree runtime: show git branch icon
+  if (isWorktreeRuntime(runtimeConfig)) {
+    return (
+      <TooltipWrapper inline>
+        <span
+          className={cn(
+            "inline-flex items-center rounded px-1 py-0.5",
+            "bg-muted/50 text-muted-foreground border border-muted",
+            className
+          )}
         >
-          {/* Server rack icon */}
-          <rect x="2" y="2" width="12" height="4" rx="1" />
-          <rect x="2" y="10" width="12" height="4" rx="1" />
-          <line x1="5" y1="4" x2="5" y2="4" />
-          <line x1="5" y1="12" x2="5" y2="12" />
-        </svg>
-      </span>
-      <Tooltip align="right">
-        SSH: {isSSHRuntime(runtimeConfig) ? runtimeConfig.host : hostname}
-      </Tooltip>
-    </TooltipWrapper>
-  );
+          <WorktreeIcon />
+        </span>
+        <Tooltip align="right">Worktree: isolated git worktree</Tooltip>
+      </TooltipWrapper>
+    );
+  }
+
+  // Local project-dir runtime: don't show badge (it's the simplest/default)
+  // Could optionally show LocalIcon if we want visibility
+  if (isLocalProjectRuntime(runtimeConfig)) {
+    return null; // No badge for simple local runtimes
+  }
+
+  return null;
 }

src/browser/utils/chatCommands.test.ts

@@ -13,14 +13,21 @@ beforeEach(() => {
 describe("parseRuntimeString", () => {
   const workspaceName = "test-workspace";
 
-  test("returns undefined for undefined runtime (default to local)", () => {
+  test("returns undefined for undefined runtime (default to worktree)", () => {
     expect(parseRuntimeString(undefined, workspaceName)).toBeUndefined();
   });
 
-  test("returns undefined for explicit 'local' runtime", () => {
-    expect(parseRuntimeString("local", workspaceName)).toBeUndefined();
-    expect(parseRuntimeString("LOCAL", workspaceName)).toBeUndefined();
-    expect(parseRuntimeString(" local ", workspaceName)).toBeUndefined();
+  test("returns undefined for explicit 'worktree' runtime", () => {
+    expect(parseRuntimeString("worktree", workspaceName)).toBeUndefined();
+    expect(parseRuntimeString("WORKTREE", workspaceName)).toBeUndefined();
+    expect(parseRuntimeString(" worktree ", workspaceName)).toBeUndefined();
+  });
+
+  test("returns local config for explicit 'local' runtime", () => {
+    // "local" now returns project-dir runtime config (no srcBaseDir)
+    expect(parseRuntimeString("local", workspaceName)).toEqual({ type: "local" });
+    expect(parseRuntimeString("LOCAL", workspaceName)).toEqual({ type: "local" });
+    expect(parseRuntimeString(" local ", workspaceName)).toEqual({ type: "local" });
   });
 
   test("parses valid SSH runtime", () => {
@@ -87,10 +94,10 @@ describe("parseRuntimeString", () => {
 
   test("throws error for unknown runtime type", () => {
     expect(() => parseRuntimeString("docker", workspaceName)).toThrow(
-      "Unknown runtime type: 'docker'"
+      "Unknown runtime type: 'docker'. Use 'ssh <host>', 'worktree', or 'local'"
     );
     expect(() => parseRuntimeString("remote", workspaceName)).toThrow(
-      "Unknown runtime type: 'remote'"
+      "Unknown runtime type: 'remote'. Use 'ssh <host>', 'worktree', or 'local'"
     );
   });
 });

src/browser/utils/chatCommands.ts

@@ -404,22 +404,30 @@ async function handleForkCommand(
  * Parse runtime string from -r flag into RuntimeConfig for backend
  * Supports formats:
  * - "ssh <host>" or "ssh <user@host>" -> SSH runtime
- * - "local" -> Local runtime (explicit)
- * - undefined -> Local runtime (default)
+ * - "worktree" -> Worktree runtime (git worktrees)
+ * - "local" -> Local runtime (project-dir, no isolation)
+ * - undefined -> Worktree runtime (default)
  */
 export function parseRuntimeString(
   runtime: string | undefined,
   _workspaceName: string
 ): RuntimeConfig | undefined {
   if (!runtime) {
-    return undefined; // Default to local (backend decides)
+    return undefined; // Default to worktree (backend decides)
   }
 
   const trimmed = runtime.trim();
   const lowerTrimmed = trimmed.toLowerCase();
 
+  // Worktree runtime (explicit or default)
+  if (lowerTrimmed === RUNTIME_MODE.WORKTREE) {
+    return undefined; // Explicit worktree - let backend use default
+  }
+
+  // Local runtime (project-dir, no isolation)
   if (lowerTrimmed === RUNTIME_MODE.LOCAL) {
-    return undefined; // Explicit local - let backend use default
+    // Return "local" type without srcBaseDir to indicate project-dir runtime
+    return { type: RUNTIME_MODE.LOCAL };
   }
 
   // Parse "ssh <host>" or "ssh <user@host>" format
@@ -439,7 +447,7 @@ export function parseRuntimeString(
     };
   }
 
-  throw new Error(`Unknown runtime type: '${runtime}'. Use 'ssh <host>' or 'local'`);
+  throw new Error(`Unknown runtime type: '${runtime}'. Use 'ssh <host>', 'worktree', or 'local'`);
 }
 
 export interface CreateWorkspaceOptions {

src/common/constants/workspace.ts

@@ -1,10 +1,11 @@
 import type { RuntimeConfig } from "@/common/types/runtime";
 
 /**
- * Default runtime configuration for local workspaces
- * Used when no runtime config is specified
+ * Default runtime configuration for worktree workspaces.
+ * Uses git worktrees for workspace isolation.
+ * Used when no runtime config is specified.
  */
 export const DEFAULT_RUNTIME_CONFIG: RuntimeConfig = {
-  type: "local",
+  type: "worktree",
   srcBaseDir: "~/.mux/src",
 } as const;

src/common/types/runtime.test.ts

@@ -23,16 +23,16 @@ describe("parseRuntimeModeAndHost", () => {
     });
   });
 
-  it("defaults to local for undefined", () => {
+  it("defaults to worktree for undefined", () => {
     expect(parseRuntimeModeAndHost(undefined)).toEqual({
-      mode: "local",
+      mode: "worktree",
       host: "",
     });
   });
 
-  it("defaults to local for null", () => {
+  it("defaults to worktree for null", () => {
     expect(parseRuntimeModeAndHost(null)).toEqual({
-      mode: "local",
+      mode: "worktree",
       host: "",
     });
   });
@@ -47,8 +47,12 @@ describe("buildRuntimeString", () => {
     expect(buildRuntimeString("ssh", "")).toBe("ssh");
   });
 
-  it("returns undefined for local mode", () => {
-    expect(buildRuntimeString("local", "")).toBeUndefined();
+  it("returns 'local' for local mode", () => {
+    expect(buildRuntimeString("local", "")).toBe("local");
+  });
+
+  it("returns undefined for worktree mode (default)", () => {
+    expect(buildRuntimeString("worktree", "")).toBeUndefined();
   });
 
   it("trims whitespace from host", () => {