🤖 fix: add downgrade compatibility for incompatible runtime configs

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.

Author: ammar-agent

src/browser/components/ChatInputToasts.test.ts

@@ -69,5 +69,18 @@ describe("ChatInputToasts", () => {
       expect(toast.title).toBe("Message Send Failed");
       expect(toast.message).toContain("unexpected error");
     });
+
+    test("should create toast for incompatible_workspace error", () => {
+      const error: SendMessageError = {
+        type: "incompatible_workspace",
+        message: "This workspace uses a runtime configuration from a newer version of mux.",
+      };
+
+      const toast = createErrorToast(error);
+
+      expect(toast.type).toBe("error");
+      expect(toast.title).toBe("Incompatible Workspace");
+      expect(toast.message).toContain("newer version");
+    });
   });
 });

src/browser/components/ChatInputToasts.tsx

@@ -195,6 +195,21 @@ export const createErrorToast = (error: SendMessageErrorType): Toast => {
       };
     }
 
+    case "incompatible_workspace": {
+      return {
+        id: Date.now().toString(),
+        type: "error",
+        title: "Incompatible Workspace",
+        message: error.message,
+        solution: (
+          <>
+            <SolutionLabel>Solution:</SolutionLabel>
+            Upgrade mux to use this workspace, or delete it and create a new one.
+          </>
+        ),
+      };
+    }
+
     case "unknown":
     default: {
       const formatted = formatSendMessageError(error);

src/browser/utils/messages/retryEligibility.test.ts

@@ -594,4 +594,12 @@ describe("isNonRetryableSendError", () => {
     };
     expect(isNonRetryableSendError(error)).toBe(false);
   });
+
+  it("returns true for incompatible_workspace error", () => {
+    const error: SendMessageError = {
+      type: "incompatible_workspace",
+      message: "This workspace uses a runtime configuration from a newer version of mux.",
+    };
+    expect(isNonRetryableSendError(error)).toBe(true);
+  });
 });

src/browser/utils/messages/retryEligibility.ts

@@ -52,6 +52,7 @@ export function isNonRetryableSendError(error: SendMessageError): boolean {
     case "api_key_not_found": // Missing API key - user must configure
     case "provider_not_supported": // Unsupported provider - user must switch
     case "invalid_model_string": // Bad model format - user must fix
+    case "incompatible_workspace": // Workspace from newer mux version - user must upgrade
       return true;
     case "unknown":
       return false; // Unknown errors might be transient

src/common/types/errors.ts

@@ -12,6 +12,7 @@ export type SendMessageError =
   | { type: "api_key_not_found"; provider: string }
   | { type: "provider_not_supported"; provider: string }
   | { type: "invalid_model_string"; message: string }
+  | { type: "incompatible_workspace"; message: string }
   | { type: "unknown"; raw: string };
 
 /**

src/common/utils/errors/formatSendError.ts

@@ -32,6 +32,11 @@ export function formatSendMessageError(error: SendMessageError): FormattedError
         message: error.message,
       };
 
+    case "incompatible_workspace":
+      return {
+        message: error.message,
+      };
+
     case "unknown":
       return {
         message: error.raw || "An unexpected error occurred",

src/node/runtime/runtimeFactory.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "bun:test";
+import {
+  isIncompatibleRuntimeConfig,
+  createRuntime,
+  IncompatibleRuntimeError,
+} from "./runtimeFactory";
+import type { RuntimeConfig } from "@/common/types/runtime";
+
+describe("isIncompatibleRuntimeConfig", () => {
+  it("returns false for undefined config", () => {
+    expect(isIncompatibleRuntimeConfig(undefined)).toBe(false);
+  });
+
+  it("returns false for valid local config with srcBaseDir", () => {
+    const config: RuntimeConfig = {
+      type: "local",
+      srcBaseDir: "~/.mux/src",
+    };
+    expect(isIncompatibleRuntimeConfig(config)).toBe(false);
+  });
+
+  it("returns false for valid SSH config", () => {
+    const config: RuntimeConfig = {
+      type: "ssh",
+      host: "example.com",
+      srcBaseDir: "/home/user/mux",
+    };
+    expect(isIncompatibleRuntimeConfig(config)).toBe(false);
+  });
+
+  it("returns true for local config without srcBaseDir (future project-dir mode)", () => {
+    // Simulate a config from a future version that has type: "local" without srcBaseDir
+    // This bypasses TypeScript checks to simulate runtime data from newer versions
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const config = { type: "local" } as RuntimeConfig;
+    expect(isIncompatibleRuntimeConfig(config)).toBe(true);
+  });
+
+  it("returns true for local config with empty srcBaseDir", () => {
+    // Simulate a malformed config - empty srcBaseDir shouldn't be valid
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const config = { type: "local", srcBaseDir: "" } as RuntimeConfig;
+    expect(isIncompatibleRuntimeConfig(config)).toBe(true);
+  });
+
+  it("returns true for unknown runtime type (future types like worktree)", () => {
+    // Simulate a config from a future version with new type
+
+    const config = { type: "worktree", srcBaseDir: "~/.mux/src" } as unknown as RuntimeConfig;
+    expect(isIncompatibleRuntimeConfig(config)).toBe(true);
+  });
+});
+
+describe("createRuntime", () => {
+  it("creates LocalRuntime for valid local config", () => {
+    const config: RuntimeConfig = {
+      type: "local",
+      srcBaseDir: "/tmp/test-src",
+    };
+    const runtime = createRuntime(config);
+    expect(runtime).toBeDefined();
+  });
+
+  it("throws IncompatibleRuntimeError for local config without srcBaseDir", () => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const config = { type: "local" } as RuntimeConfig;
+    expect(() => createRuntime(config)).toThrow(IncompatibleRuntimeError);
+    expect(() => createRuntime(config)).toThrow(/newer version of mux/);
+  });
+
+  it("throws IncompatibleRuntimeError for unknown runtime type", () => {
+    const config = { type: "worktree", srcBaseDir: "~/.mux/src" } as unknown as RuntimeConfig;
+    expect(() => createRuntime(config)).toThrow(IncompatibleRuntimeError);
+    expect(() => createRuntime(config)).toThrow(/newer version of mux/);
+  });
+});

src/node/runtime/runtimeFactory.ts

@@ -3,10 +3,52 @@ import { LocalRuntime } from "./LocalRuntime";
 import { SSHRuntime } from "./SSHRuntime";
 import type { RuntimeConfig } from "@/common/types/runtime";
 
+/**
+ * Error thrown when a workspace has an incompatible runtime configuration,
+ * typically from a newer version of mux that added new runtime types.
+ */
+export class IncompatibleRuntimeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IncompatibleRuntimeError";
+  }
+}
+
+/**
+ * Check if a runtime config is from a newer version and incompatible.
+ *
+ * This handles downgrade compatibility: if a user upgrades to a version
+ * with new runtime types (e.g., "local" without srcBaseDir for project-dir mode),
+ * then downgrades, those workspaces should show a clear error rather than crashing.
+ */
+export function isIncompatibleRuntimeConfig(config: RuntimeConfig | undefined): boolean {
+  if (!config) {
+    return false;
+  }
+  // Future versions may add "local" without srcBaseDir (project-dir mode)
+  // or new types like "worktree". Detect these as incompatible.
+  if (config.type === "local" && !("srcBaseDir" in config && config.srcBaseDir)) {
+    return true;
+  }
+  // Unknown types from future versions
+  if (config.type !== "local" && config.type !== "ssh") {
+    return true;
+  }
+  return false;
+}
+
 /**
  * Create a Runtime instance based on the configuration
  */
 export function createRuntime(config: RuntimeConfig): Runtime {
+  // Check for incompatible configs from newer versions
+  if (isIncompatibleRuntimeConfig(config)) {
+    throw new IncompatibleRuntimeError(
+      `This workspace uses a runtime configuration from a newer version of mux. ` +
+        `Please upgrade mux to use this workspace.`
+    );
+  }
+
   switch (config.type) {
     case "local":
       return new LocalRuntime(config.srcBaseDir);

src/node/services/ipcMain.ts

@@ -36,7 +36,7 @@ import type { BashToolResult } from "@/common/types/tools";
 import { secretsToRecord } from "@/common/types/secrets";
 import { DisposableTempDir } from "@/node/services/tempDir";
 import { InitStateManager } from "@/node/services/initStateManager";
-import { createRuntime } from "@/node/runtime/runtimeFactory";
+import { createRuntime, IncompatibleRuntimeError } from "@/node/runtime/runtimeFactory";
 import type { RuntimeConfig } from "@/common/types/runtime";
 import { isSSHRuntime } from "@/common/types/runtime";
 import { validateProjectPath } from "@/node/utils/pathUtils";
@@ -1157,6 +1157,16 @@ export class IpcMain {
           const errorMessage =
             error instanceof Error ? error.message : JSON.stringify(error, null, 2);
           log.error("Unexpected error in sendMessage handler:", error);
+
+          // Handle incompatible workspace errors from downgraded configs
+          if (error instanceof IncompatibleRuntimeError) {
+            const sendError: SendMessageError = {
+              type: "incompatible_workspace",
+              message: error.message,
+            };
+            return { success: false, error: sendError };
+          }
+
           const sendError: SendMessageError = {
             type: "unknown",
             raw: `Failed to send message: ${errorMessage}`,
@@ -1187,6 +1197,16 @@ export class IpcMain {
           // Convert to SendMessageError for typed error handling
           const errorMessage = error instanceof Error ? error.message : String(error);
           log.error("Unexpected error in resumeStream handler:", error);
+
+          // Handle incompatible workspace errors from downgraded configs
+          if (error instanceof IncompatibleRuntimeError) {
+            const sendError: SendMessageError = {
+              type: "incompatible_workspace",
+              message: error.message,
+            };
+            return { success: false, error: sendError };
+          }
+
           const sendError: SendMessageError = {
             type: "unknown",
             raw: `Failed to resume stream: ${errorMessage}`,