🤖 refactor: add Local/Worktree runtime distinction #824
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
2 times, most recently
from
4c481c4 to
cc384a9
Compare
ammar-agent
added a commit
that referenced
this pull request
Dec 1, 2025
When users upgrade to a version with new runtime types (like 'local' without srcBaseDir for project-dir mode, or new 'worktree' type) and then downgrade, the old version should show a clear error instead of crashing. Changes: - Add IncompatibleRuntimeError for workspaces from newer mux versions - Add isIncompatibleRuntimeConfig helper to detect future configs - Add 'incompatible_workspace' SendMessageError type - Handle error in sendMessage/resumeStream handlers - Show helpful toast with 'upgrade mux' suggestion - Mark incompatible_workspace as non-retryable This prepares for #824 (Local/Worktree runtime distinction) by ensuring users can safely downgrade without losing access to their other workspaces.
ammar-agent
added a commit
that referenced
this pull request
Dec 1, 2025
When users upgrade to a version with new runtime types (like 'local' without srcBaseDir for project-dir mode, or new 'worktree' type) and then downgrade, the old version shows a clear error instead of crashing. Changes: - Add IncompatibleRuntimeError for workspaces from newer mux versions - Add isIncompatibleRuntimeConfig helper to detect future configs - Add incompatibleRuntime field to FrontendWorkspaceMetadata - Show error in AIView when workspace is incompatible - Add 'incompatible_workspace' SendMessageError type as fallback - Mark incompatible_workspace as non-retryable This prepares for #824 (Local/Worktree runtime distinction) by ensuring users can safely downgrade without losing access to their other workspaces.
ammar-agent
added a commit
that referenced
this pull request
Dec 1, 2025
When users upgrade to a version with new runtime types (like 'local' without srcBaseDir for project-dir mode, or new 'worktree' type) and then downgrade, the old version shows a clear error instead of crashing. Changes: - Add IncompatibleRuntimeError for workspaces from newer mux versions - Add isIncompatibleRuntimeConfig helper to detect future configs - Add incompatibleRuntime field to FrontendWorkspaceMetadata - Show error in AIView when workspace is incompatible - Add 'incompatible_workspace' SendMessageError type as fallback - Mark incompatible_workspace as non-retryable This prepares for #824 (Local/Worktree runtime distinction) by ensuring users can safely downgrade without losing access to their other workspaces.
ammario
pushed a commit
that referenced
this pull request
Dec 1, 2025
…827) ## Summary Prepares for #824 by ensuring users can safely upgrade→downgrade without losing access to their other workspaces. When users upgrade to a version with new runtime types (like `type: "local"` without `srcBaseDir` for project-dir mode, or new `type: "worktree"`) and then downgrade, the old version now shows a clear error instead of crashing. ## Changes | File | Change | |------|--------| | `src/common/utils/runtimeCompatibility.ts` | New: `isIncompatibleRuntimeConfig()` helper (in common/ to avoid circular deps) | | `src/common/types/workspace.ts` | Added `incompatibleRuntime` field to `FrontendWorkspaceMetadata` | | `src/node/config.ts` | Set `incompatibleRuntime` when loading workspace metadata | | `src/browser/components/AIView.tsx` | Display error view for incompatible workspaces | | `src/browser/App.tsx` | Pass `incompatibleRuntime` to AIView | | `src/node/runtime/runtimeFactory.ts` | Re-export helper + throw `IncompatibleRuntimeError` as safety net | | `src/node/services/ipcMain.ts` | Handle `IncompatibleRuntimeError` in sendMessage (fallback) | | `src/common/types/errors.ts` | Added `incompatible_workspace` SendMessageError type | ## User Experience When clicking into an incompatible workspace, users see a centered error view: >⚠️ **Incompatible Workspace** > This workspace was created with a newer version of mux. > Please upgrade mux to use this workspace. > > You can delete this workspace and create a new one, or upgrade mux to use it. ## Testing - Added unit tests for `isIncompatibleRuntimeConfig()` - Added unit tests for `createRuntime()` throwing on incompatible configs - Added tests for error toast display (fallback path) - Added tests for non-retryable error classification _Generated with `mux`_
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
2 times, most recently
from
eaa56ed to
c9168b7
Compare
- 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_
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
from
c9168b7 to
56094dc
Compare
Add comprehensive test coverage for LocalRuntime: - Constructor and getWorkspacePath behavior (ignores args, returns project path) - createWorkspace success/failure cases - deleteWorkspace no-op behavior (doesn't delete anything) - renameWorkspace/forkWorkspace unsupported operation errors - Inherited LocalBaseRuntime methods (exec, stat, resolvePath, normalizePath) 12 new tests covering the project-dir runtime behavior.
Add ConcurrentLocalWarning component that displays a dismissible warning when: 1. Current workspace uses local project-dir runtime (no isolation) 2. Another workspace for the same project is actively streaming The warning helps users understand that agents may interfere with each other when working on the same directory without worktree isolation. Also adds projectPath prop to AIView to enable this check.
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
from
e2ee558 to
f09ce19
Compare
- Reduce icon size from 12x12 to 10x10 (~15% smaller) - Redesign worktree icon to be vertically oriented like SSH icon - Improve SSH icon with visible indicator dots - Both icons now have similar visual weight and shape
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
13 times, most recently
from
9df61c3 to
d85230d
Compare
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
from
d85230d to
1a9f8c2
Compare
ammario
approved these changes
Dec 1, 2025
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
from
1a9f8c2 to
1eb3e2a
Compare
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
ammar-agent
force-pushed
the
runtime-local-worktree-refactor
branch
from
1eb3e2a to
e3a12fe
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds explicit runtime type distinction between Local (project-directory) and Worktree (isolated git worktrees):
Local runtime: Uses project directory directly, no isolation. Creation is a no-op (just "use this directory"), delete is a no-op (won't delete user's project). Good for existing repos where user wants to work in-place.
Worktree runtime: Creates isolated git worktrees under
~/.mux/src/<project>/<branch>. Existing behavior, now made explicit.SSH runtime: Unchanged, remote execution.
Changes
RuntimeModenow includes"local" | "worktree" | "ssh"LocalBaseRuntimefor shared exec/file operations between Local and WorktreeLocalRuntimeuses project path directly (no-op create/delete)WorktreeRuntimemanages git worktrees (renamed from old LocalRuntime)Backward Compatibility
type: "local"withsrcBaseDir= legacy worktree config (still works)type: "local"withoutsrcBaseDir= new project-dir runtimetype: "worktree"= explicit worktree (new workspaces)Users can upgrade/downgrade without breaking existing workspaces.
Generated with
mux