Add shell-free cmux restore verb

CLI/CMUXCLI+CommandSuggestions.swift

@@ -166,6 +166,7 @@ extension CMUXCLI {
         "resize-pane",
         "respawn-pane",
         "restore-session",
+        "restore",
         "right-sidebar",
         "rpc",
         "select-workspace",

CLI/CMUXCLI+Restore.swift

@@ -0,0 +1,296 @@
+import CMUXAgentLaunch
+import Foundation
+
+extension CMUXCLI {
+    func controlAgentLaunchCommandPayload(
+        _ command: AgentLaunchCommand
+    ) -> [String: Any] {
+        var payload: [String: Any] = ["arguments": command.arguments]
+        if let launcher = command.launcher {
+            payload["launcher"] = launcher
+        }
+        if let executablePath = command.executablePath {
+            payload["executable_path"] = executablePath
+        }
+        if let workingDirectory = command.workingDirectory {
+            payload["working_directory"] = workingDirectory
+        }
+        if let environment = command.environment {
+            payload["environment"] = environment
+        }
+        if let capturedAt = command.capturedAt {
+            payload["captured_at"] = capturedAt
+        }
+        if let source = command.source {
+            payload["source"] = source
+        }
+        return payload
+    }
+
+    func runRestoreCommand(
+        commandArgs: [String],
+        client: SocketClient,
+        processEnvironment: [String: String]
+    ) throws {
+        let selector = try restoreSelector(commandArgs)
+        var params: [String: Any] = [:]
+        if let surface = selector.surface {
+            let surfaceID = try normalizeSurfaceHandle(
+                surface,
+                client: client,
+                workspaceHandle: nil,
+                windowHandle: nil
+            )
+            guard let surfaceID else {
+                throw loggedRestoreError(
+                    stage: "surface.lookup",
+                    detail: surface,
+                    message: String(
+                        localized: "cli.restore.error.surfaceNotFound",
+                        defaultValue: "restore: the requested surface was not found. Check the surface reference, then retry."
+                    )
+                )
+            }
+            params["surface_id"] = surfaceID
+        } else if selector.usesCurrentSurface,
+                  let surfaceID = processEnvironment["CMUX_SURFACE_ID"],
+                  !surfaceID.isEmpty {
+            params["surface_id"] = surfaceID
+        } else if selector.usesCurrentSurface,
+                  let ttyName = resolveCallerTTYName(),
+                  let caller = resolveTerminalBinding(
+                      ttyName: ttyName,
+                      client: client
+                  ) {
+            params["surface_id"] = caller.surfaceId
+        } else {
+            throw CLIError(
+                message: String(
+                    localized: "cli.restore.error.currentSurfaceUnknown",
+                    defaultValue: "restore: the current cmux surface could not be identified. Retry from this terminal or pass --surface <id|ref>."
+                )
+            )
+        }
+
+        let payload = try client.sendV2(method: "surface.resume.get", params: params)
+        guard let rawRecord = payload["restore_record"] as? [String: Any] else {
+            throw loggedRestoreError(
+                stage: "record.missing",
+                message: String(
+                    localized: "cli.restore.error.noRecord",
+                    defaultValue: "restore: this session has nothing to restore. Start the agent again in this terminal."
+                )
+            )
+        }
+        let record = try restoreRecord(from: rawRecord)
+        if let expectedKind = selector.kind, expectedKind != record.kind {
+            throw loggedRestoreError(
+                stage: "record.kind-mismatch",
+                detail: "expected=\(expectedKind) actual=\(record.kind)",
+                message: String(
+                    localized: "cli.restore.error.kindMismatch",
+                    defaultValue: "restore: this command no longer matches the session. Run 'cmux restore --surface' to use the current record."
+                )
+            )
+        }
+        if let expectedCheckpointID = selector.checkpointID,
+           expectedCheckpointID != record.checkpointID {
+            throw loggedRestoreError(
+                stage: "record.checkpoint-mismatch",
+                detail: "expected=\(expectedCheckpointID) actual=\(record.checkpointID ?? "none")",
+                message: String(
+                    localized: "cli.restore.error.checkpointMismatch",
+                    defaultValue: "restore: this command no longer matches the session. Run 'cmux restore --surface' to use the current record."
+                )
+            )
+        }
+
+        let environment = processEnvironment.merging(record.environment) { _, restored in
+            restored
+        }
+        if record.launchCommand == nil,
+           record.preparedArguments == nil,
+           let legacyCommand = record.legacyCommand {
+            try execLegacyRestoreRecord(
+                legacyCommand,
+                record: record,
+                environment: environment,
+                client: client
+            )
+        }
+
+        guard let mode = AgentRestoreRequestMode(rawValue: record.mode) else {
+            throw loggedRestoreError(
+                stage: "record.mode",
+                detail: record.mode,
+                message: String(
+                    localized: "cli.restore.error.unsupportedMode",
+                    defaultValue: "restore: this session's saved restore data is not compatible. Start the agent again in this terminal."
+                )
+            )
+        }
+        let requestedWorkingDirectory = requestedRestoreWorkingDirectory(for: record)
+        let appliedWorkingDirectory = try applyRestoreWorkingDirectory(
+            requestedWorkingDirectory
+        )
+        let effectiveWorkingDirectory: String? =
+            if requestedWorkingDirectory?.isEmpty == false {
+                appliedWorkingDirectory ?? FileManager.default.currentDirectoryPath
+            } else {
+                nil
+            }
+        let request = AgentRestoreRequest(
+            mode: mode,
+            kind: record.kind,
+            checkpointID: record.checkpointID,
+            source: record.source,
+            workingDirectory: effectiveWorkingDirectory,
+            environment: record.environment,
+            launchCommand: record.launchCommand,
+            preparedArguments: record.preparedArguments,
+            preparedArgumentsWorkingDirectory: normalizedRestoreWorkingDirectory(
+                record.preparedArgumentsWorkingDirectory
+            ),
+            observedPermissionMode: record.permissionMode
+        )
+        guard let invocation = AgentRestorePlanner(
+            executableFileResolver: AgentRestoreExecutableFileResolver()
+        ).invocation(
+            for: request,
+            ambientEnvironment: processEnvironment
+        ) else {
+            if let legacyCommand = record.legacyCommand {
+                try execLegacyRestoreRecord(
+                    legacyCommand,
+                    record: record,
+                    environment: environment,
+                    client: client
+                )
+            }
+            throw loggedRestoreError(
+                stage: "record.incomplete",
+                detail: "mode=\(record.mode) kind=\(record.kind)",
+                message: String(
+                    localized: "cli.restore.error.incompleteData",
+                    defaultValue: "restore: this session's saved restore data is not compatible. Start the agent again in this terminal."
+                )
+            )
+        }
+
+        for preflight in invocation.preflightInvocations {
+            try runRestorePreflight(
+                preflight,
+                appliedWorkingDirectory: effectiveWorkingDirectory
+            )
+        }
+        client.close()
+        try execRestoreInvocation(
+            invocation,
+            appliedWorkingDirectory: effectiveWorkingDirectory
+        )
+    }
+
+    private func restoreSelector(_ arguments: [String]) throws -> RestoreSelector {
+        if arguments.first == "--surface" {
+            if arguments.count == 1 {
+                return RestoreSelector(
+                    surface: nil,
+                    usesCurrentSurface: true,
+                    kind: nil,
+                    checkpointID: nil
+                )
+            }
+            guard arguments.count == 2, !arguments[1].isEmpty else {
+                throw CLIError(message: String(
+                    localized: "cli.restore.usage.surface",
+                    defaultValue: "Usage: cmux restore --surface [id|ref]"
+                ))
+            }
+            return RestoreSelector(
+                surface: arguments[1],
+                usesCurrentSurface: false,
+                kind: nil,
+                checkpointID: nil
+            )
+        }
+        guard arguments.count == 2,
+              !arguments[0].trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+              !arguments[1].trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            throw CLIError(message: String(
+                localized: "cli.restore.usage.positional",
+                defaultValue: "Usage: cmux restore <kind> <checkpoint-id>"
+            ))
+        }
+        return RestoreSelector(
+            surface: nil,
+            usesCurrentSurface: true,
+            kind: arguments[0],
+            checkpointID: arguments[1]
+        )
+    }
+
+    private func restoreRecord(from object: [String: Any]) throws -> RestoreRecord {
+        guard let mode = object["mode"] as? String,
+              let kind = object["kind"] as? String else {
+            throw loggedRestoreError(
+                stage: "record.decode",
+                detail: "keys=\(object.keys.sorted().joined(separator: ","))",
+                message: String(
+                    localized: "cli.restore.error.malformedRecord",
+                    defaultValue: "restore: this session's saved restore data is not compatible. Start the agent again in this terminal."
+                )
+            )
+        }
+        let legacyCommand = object["legacy_command"] as? String
+        let launchCommand: AgentLaunchCommand?
+        do {
+            launchCommand = try restoreLaunchCommand(from: object["launch_command"])
+        } catch {
+            guard legacyCommand != nil else {
+                throw loggedRestoreError(
+                    stage: "record.launch-command",
+                    detail: String(reflecting: type(of: error)),
+                    message: String(
+                        localized: "cli.restore.error.malformedArguments",
+                        defaultValue: "restore: this session's saved restore data is not compatible. Start the agent again in this terminal."
+                    )
+                )
+            }
+            launchCommand = nil
+        }
+        return RestoreRecord(
+            mode: mode,
+            kind: kind,
+            checkpointID: object["checkpoint_id"] as? String,
+            source: object["source"] as? String,
+            workingDirectory: object["working_directory"] as? String,
+            environment: object["environment"] as? [String: String] ?? [:],
+            launchCommand: launchCommand,
+            preparedArguments: object["prepared_arguments"] as? [String],
+            preparedArgumentsWorkingDirectory:
+                object["prepared_arguments_working_directory"] as? String,
+            permissionMode: object["permission_mode"] as? String,
+            legacyCommand: legacyCommand
+        )
+    }
+
+    private func restoreLaunchCommand(from value: Any?) throws -> AgentLaunchCommand? {
+        guard let object = value as? [String: Any] else { return nil }
+        guard let arguments = object["arguments"] as? [String], !arguments.isEmpty else {
+            throw CLIError(message: String(
+                localized: "cli.restore.error.malformedArguments",
+                defaultValue: "restore: this session's saved restore data is not compatible. Start the agent again in this terminal."
+            ))
+        }
+        return AgentLaunchCommand(
+            launcher: object["launcher"] as? String,
+            executablePath: object["executable_path"] as? String,
+            arguments: arguments,
+            workingDirectory: object["working_directory"] as? String,
+            environment: object["environment"] as? [String: String],
+            capturedAt: (object["captured_at"] as? NSNumber)?.doubleValue,
+            source: object["source"] as? String
+        )
+    }
+
+}