Move saved sessions between cmux installs: restore-session --from / --export

CLI/CMUXCLI+TaskHelp.swift

@@ -188,7 +188,7 @@ extension CMUXCLI {
         return """
         \(restoreCommandUsageLine)
         \(forkCommandUsageLine)
-        restore-session
+        restore-session [--from <channel|path> | --export <path> [--force]]
         \(String(localized: "cli.sessions.command", defaultValue: "sessions [list] [options]"))
         open <path-or-url>... [--workspace <id|ref|index>] [--surface <id|ref|index>] [--pane <id|ref|index>] [--window <id|ref|index>] [--focus <true|false>] [--no-focus]
         new-workspace [--name <title>] [--description <text>] [--cwd <path>] [--command <text>] [--layout <json>] [--window <id|ref|index>] [--focus <true|false>] [--group <id|ref>] [--group-placement afterCurrent|top|end] [--group-reference <workspace>]

CLI/cmux.swift

@@ -8694,10 +8694,56 @@ struct CMUXCLI {
         explicitPassword: String?,
         jsonOutput: Bool
     ) throws {
-        let remaining = commandArgs.filter { $0 != "--" }
+        let (fromValue, afterFrom) = parseOption(commandArgs, name: "--from")
+        let (exportValue, afterExport) = parseOption(afterFrom, name: "--export")
+        // `--export --force` must not write a file named `--force`, and
+        // `--from --export x` must not treat `--export` as a channel.
+        for (flag, value) in [("--from", fromValue), ("--export", exportValue)] {
+            if let value, value.hasPrefix("--") {
+                throw CLIError(message: "restore-session: \(flag) requires a value")
+            }
+        }
+        let beforeTerminator = afterExport.prefix { $0 != "--" }
+        let force = beforeTerminator.contains("--force")
+        let remaining = afterExport.filter { $0 != "--" && $0 != "--force" }
         if let unknown = remaining.first {
+            if unknown == "--from" || unknown == "--export" {
+                throw CLIError(message: "restore-session: \(unknown) requires a value")
+            }
             throw CLIError(message: "restore-session: unknown flag '\(unknown)'")
         }
+        if fromValue != nil && exportValue != nil {
+            throw CLIError(message: "restore-session: use either --from or --export, not both")
+        }
+        if force && exportValue == nil {
+            throw CLIError(message: "restore-session: --force only applies to --export")
+        }
+        if let fromValue {
+            try runRestoreSessionTransfer(
+                method: "session.import",
+                params: try restoreSessionImportParams(fromValue),
+                socketPath: socketPath,
+                explicitPassword: explicitPassword,
+                jsonOutput: jsonOutput,
+                resultPathKey: "source_path"
+            )
+            return
+        }
+        if let exportValue {
+            let trimmed = exportValue.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else {
+                throw CLIError(message: "restore-session: --export requires a file path")
+            }
+            try runRestoreSessionTransfer(
+                method: "session.export",
+                params: ["path": resolvePath(trimmed), "force": force],
+                socketPath: socketPath,
+                explicitPassword: explicitPassword,
+                jsonOutput: jsonOutput,
+                resultPathKey: "path"
+            )
+            return
+        }
 
         let initialClient = SocketClient(path: socketPath)
         let client: SocketClient
@@ -8729,6 +8775,112 @@ struct CMUXCLI {
         }
     }
 
+    /// `session.import` params for `restore-session --from <value>`: a value
+    /// that looks like a file path (contains `/`, starts with `~` or `.`, or
+    /// ends in `.json`) is sent as an absolute `path`. A channel name or
+    /// bundle id (`source`) wins over a same-named file in the current
+    /// directory, so `--from nightly` never silently becomes an untrusted
+    /// file import; `./nightly` names the file. Any other bare name is a file
+    /// when it exists, otherwise a source the app resolves.
+    func restoreSessionImportParams(_ rawValue: String) throws -> [String: Any] {
+        let value = rawValue.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !value.isEmpty else {
+            throw CLIError(message: "restore-session: --from requires a channel or a file path")
+        }
+        let resolvedPath = resolvePath(value)
+        let explicitPath = value.contains("/")
+            || value.hasPrefix("~")
+            || value.hasPrefix(".")
+            || value.lowercased().hasSuffix(".json")
+        if explicitPath {
+            return ["path": resolvedPath]
+        }
+        if Self.restoreSessionLooksLikeChannel(value) {
+            return ["source": value]
+        }
+        if FileManager.default.fileExists(atPath: resolvedPath) {
+            return ["path": resolvedPath]
+        }
+        return ["source": value]
+    }
+
+    /// Whether `value` names an install channel (`stable`, `release`,
+    /// `nightly`, `rc`, `staging`, `debug`, `debug:<tag>`, `dev:<tag>`) or a
+    /// cmux bundle identifier. Mirrors `SessionSnapshotFileLocation`.
+    static func restoreSessionLooksLikeChannel(_ value: String) -> Bool {
+        let lowered = value.lowercased()
+        if ["stable", "release", "nightly", "rc", "staging", "debug"].contains(lowered) {
+            return true
+        }
+        if lowered.hasPrefix("debug:") || lowered.hasPrefix("dev:") {
+            return true
+        }
+        return value == "com.cmuxterm.app" || value.hasPrefix("com.cmuxterm.app.")
+    }
+
+    /// Sends a session transfer request (`session.import` / `session.export`)
+    /// to the running app. Unlike plain `restore-session`, these never launch
+    /// cmux: importing into an app that is still starting would race its own
+    /// startup restore.
+    private func runRestoreSessionTransfer(
+        method: String,
+        params: [String: Any],
+        socketPath: String,
+        explicitPassword: String?,
+        jsonOutput: Bool,
+        resultPathKey: String
+    ) throws {
+        let client = SocketClient(path: socketPath)
+        do {
+            try client.connect()
+        } catch {
+            client.close()
+            throw CLIError(message: "restore-session: cmux is not running. Open cmux, then run this command again.")
+        }
+        defer { client.close() }
+        try authenticateClientIfNeeded(
+            client,
+            explicitPassword: explicitPassword,
+            socketPath: socketPath
+        )
+        let response = try client.sendV2(method: method, params: params)
+        if jsonOutput {
+            print(jsonString(response))
+            return
+        }
+        if let path = response[resultPathKey] as? String {
+            print("OK \(path)")
+        } else {
+            print("OK")
+        }
+        for line in restoreSessionImportNotes(response) {
+            print(line)
+        }
+    }
+
+    /// Follow-up lines for a file import that held back automatic resume or
+    /// dropped remote connections.
+    func restoreSessionImportNotes(_ response: [String: Any]) -> [String] {
+        var lines: [String] = []
+        let heldBack = (response["held_back_resume_count"] as? NSNumber)?.intValue ?? 0
+        if heldBack > 0 {
+            lines.append(
+                "Held back automatic resume in \(heldBack) terminal\(heldBack == 1 ? "" : "s") from this file. "
+                    + "In each one, run `cmux surface resume show` to inspect the command "
+                    + "and `cmux restore --surface` to run it. "
+                    + "Use --from <channel> to import another install's session with automatic resume."
+            )
+        }
+        let droppedRemote = (response["dropped_remote_workspace_count"] as? NSNumber)?.intValue ?? 0
+        if droppedRemote > 0 {
+            lines.append(
+                "Opened \(droppedRemote) workspace\(droppedRemote == 1 ? "" : "s") without the file's "
+                    + "SSH/cloud connection and environment variables."
+            )
+        }
+        return lines
+    }
+
     func connectClient(
         socketPath: String,
         explicitPassword: String?,
@@ -18638,14 +18790,26 @@ struct CMUXCLI {
             Configure idle and live-terminal limits from Settings or cmux settings JSON.
             """
         case "restore-session":
-            return """
+            return String(localized: "cli.restoreSession.help", defaultValue: """
             Usage: cmux restore-session
+                   cmux restore-session --from <stable|nightly|rc|staging|debug:<tag>|path>
+                   cmux restore-session --export <path> [--force]
 
             Reopen the previous saved cmux session.
 
             If the app is already running, this restores the last saved session into the current app.
             If the app is not running, this launches cmux and lets startup restore reopen the saved session.
-            """
+
+            Each cmux install (stable, nightly, rc, staging, tagged debug builds) saves its own session.
+            --from <channel>  Reopen another install's saved session in this running cmux, for example
+                              after trying nightly and switching back to stable. The session opens as
+                              additional windows; the other install's saved file is only read.
+            --from <path>     Reopen a session file written by --export.
+            --export <path>   Write this cmux's saved session to a file. Pass --force to replace an
+                              existing file.
+
+            --from and --export require cmux to be running.
+            """)
         case "restore":
             return String(localized: "cli.restore.help", defaultValue: """
             Usage: cmux restore [--surface <id|ref>] <kind> <checkpoint-id>

Packages/macOS/CmuxControlSocket/Package.swift

@@ -4,6 +4,7 @@ import PackageDescription
 
 let package = Package(
     name: "CmuxControlSocket",
+    defaultLocalization: "en",
     platforms: [
         .macOS(.v14),
     ],
@@ -29,6 +30,9 @@ let package = Package(
                 .product(name: "CmuxSettings", package: "CmuxSettings"),
                 "CmuxControlSocketAtomicsC",
             ],
+            resources: [
+                .process("Resources/Localizable.xcstrings"),
+            ],
             swiftSettings: [
                 .swiftLanguageMode(.v6),
                 .enableUpcomingFeature("ExistentialAny"),

Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/System/ControlCommandCoordinator+System.swift

@@ -1,7 +1,8 @@
 internal import Foundation
 
 /// The system/misc domain (`system.identify`, `system.tree`, `auth.login`,
-/// `session.restore_previous`, `settings.open`, `feedback.open`,
+/// `session.restore_previous`, `session.import`, `session.export`,
+/// `settings.open`, `feedback.open`,
 /// `extension.sidebar.snapshot`, `workspace.action`, `surface.action` /
 /// `tab.action`, `surface.drag_to_split` / `surface.split_off`, and the
 /// DEBUG-only `mobile.dev_stack_auth.configure`), lifted byte-faithfully from
@@ -30,6 +31,10 @@ extension ControlCommandCoordinator {
             return authLogin()
         case "session.restore_previous":
             return sessionRestorePrevious()
+        case "session.import":
+            return sessionImport(request.params)
+        case "session.export":
+            return sessionExport(request.params)
         case "settings.open":
             return settingsOpen(request.params)
         case "feedback.open":

Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/System/ControlCommandCoordinator+SystemMisc.swift

@@ -1,6 +1,7 @@
 internal import Foundation
 
 /// The small system-domain bodies: `auth.login`, `session.restore_previous`,
+/// `session.import`, `session.export`,
 /// `settings.open`, `feedback.open`, `extension.sidebar.snapshot`, the
 /// `surface.split_off` / `surface.drag_to_split` bridge, and the DEBUG-only
 /// `mobile.dev_stack_auth.configure`.
@@ -26,6 +27,120 @@ extension ControlCommandCoordinator {
         }
     }
 
+    /// `session.import` — reopen another install's saved session (`source`:
+    /// a channel name or bundle identifier) or a snapshot file (`path`, an
+    /// absolute path) as additional windows.
+    func sessionImport(_ params: [String: JSONValue]) -> ControlCallResult {
+        let path = string(params, "path")
+        let channel = string(params, "source")
+        let source: ControlSessionImportSource
+        switch (path, channel) {
+        case (let path?, nil):
+            guard path.hasPrefix("/") else {
+                return .err(
+                    code: "invalid_params",
+                    message: String(
+                        format: String(
+                            localized: "socket.sessionTransfer.absolutePathRequired",
+                            defaultValue: "%@ must be an absolute path.",
+                            bundle: .module
+                        ),
+                        "session.import params.path"
+                    ),
+                    data: .object(["path": .string(path)])
+                )
+            }
+            source = .file(path: path)
+        case (nil, let channel?):
+            source = .channel(channel)
+        default:
+            return .err(
+                code: "invalid_params",
+                message: String(
+                    localized: "socket.sessionTransfer.importSelectorRequired",
+                    defaultValue: "session.import requires exactly one of params.source or params.path.",
+                    bundle: .module
+                ),
+                data: nil
+            )
+        }
+        guard let systemContext else {
+            return .err(
+                code: "unavailable",
+                message: String(
+                    localized: "socket.sessionTransfer.contextUnavailable",
+                    defaultValue: "Session context is unavailable.",
+                    bundle: .module
+                ),
+                data: nil
+            )
+        }
+        switch systemContext.controlSessionImport(source: source) {
+        case let .restored(sourcePath, windowCount, heldBackResumeCount, droppedRemoteWorkspaceCount):
+            return .ok(.object([
+                "restored": .bool(true),
+                "source_path": .string(sourcePath),
+                "window_count": .int(Int64(windowCount)),
+                "trusted": .bool(source.isTrusted),
+                "held_back_resume_count": .int(Int64(heldBackResumeCount)),
+                "dropped_remote_workspace_count": .int(Int64(droppedRemoteWorkspaceCount)),
+            ]))
+        case let .failed(code, message, path):
+            return .err(code: code, message: message, data: .object(["path": orNull(path)]))
+        }
+    }
+
+    /// `session.export` — write this install's saved session snapshot to an
+    /// absolute `path`; `force` allows replacing an existing file.
+    func sessionExport(_ params: [String: JSONValue]) -> ControlCallResult {
+        guard let path = string(params, "path") else {
+            return .err(
+                code: "invalid_params",
+                message: String(
+                    localized: "socket.sessionTransfer.exportPathRequired",
+                    defaultValue: "session.export requires params.path.",
+                    bundle: .module
+                ),
+                data: nil
+            )
+        }
+        guard path.hasPrefix("/") else {
+            return .err(
+                code: "invalid_params",
+                message: String(
+                    format: String(
+                        localized: "socket.sessionTransfer.absolutePathRequired",
+                        defaultValue: "%@ must be an absolute path.",
+                        bundle: .module
+                    ),
+                    "session.export params.path"
+                ),
+                data: .object(["path": .string(path)])
+            )
+        }
+        guard let systemContext else {
+            return .err(
+                code: "unavailable",
+                message: String(
+                    localized: "socket.sessionTransfer.contextUnavailable",
+                    defaultValue: "Session context is unavailable.",
+                    bundle: .module
+                ),
+                data: nil
+            )
+        }
+        switch systemContext.controlSessionExport(path: path, overwrite: bool(params, "force") ?? false) {
+        case let .exported(exportedPath, sourcePath):
+            return .ok(.object([
+                "exported": .bool(true),
+                "path": .string(exportedPath),
+                "source_path": .string(sourcePath),
+            ]))
+        case let .failed(code, message, path):
+            return .err(code: code, message: message, data: .object(["path": orNull(path)]))
+        }
+    }
+
     /// `settings.open` — open the settings window, optionally at a target pane.
     func settingsOpen(_ params: [String: JSONValue]) -> ControlCallResult {
         let targetRaw = string(params, "target")