Fix Cloud VM creation, snapshot refresh, and desktop restore

Sources/Surfaces/CloudProviderRefreshCoordinator.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+/// Serializes graph publication for one provider. A forced reader waits for a
+/// pass started after its request; ordinary readers share the active pass.
+@MainActor
+final class CloudProviderRefreshCoordinator {
+    private struct Entry {
+        let request: UInt64
+        let forced: Bool
+        let task: Task<Bool, Never>
+    }
+
+    private var inFlight: Entry?
+    private var latestRequest: UInt64 = 0
+    private var invalidation: UInt64 = 0
+    private var lifetime: UInt64 = 0
+
+    func refresh(force: Bool, operation: @escaping @MainActor (Bool) async -> Bool) async -> Bool {
+        latestRequest &+= 1
+        let request = latestRequest
+        let epoch = lifetime
+        while !Task.isCancelled, epoch == lifetime {
+            if let entry = inFlight {
+                let result = await entry.task.value
+                if inFlight?.task == entry.task { inFlight = nil }
+                guard !Task.isCancelled, epoch == lifetime else { return false }
+                if !force || (entry.forced && entry.request >= request) { return result }
+                continue
+            }
+            let task = Task { @MainActor [weak self] in
+                while let self, !Task.isCancelled, epoch == self.lifetime {
+                    let revision = self.invalidation
+                    let result = await operation(force)
+                    guard !Task.isCancelled, epoch == self.lifetime else { return false }
+                    // Metadata superseded this pass. Readers stay attached to
+                    // the owner until a pass over the current metadata finishes.
+                    if revision == self.invalidation { return result }
+                }
+                return false
+            }
+            // Covers all forced readers already waiting, so a burst shares
+            // one trailing pass instead of issuing one snapshot per waiter.
+            inFlight = Entry(request: latestRequest, forced: force, task: task)
+        }
+        return false
+    }
+
+    func invalidate() { invalidation &+= 1 }
+
+    func cancel() {
+        lifetime &+= 1
+        inFlight?.task.cancel()
+        inFlight = nil
+    }
+}

Sources/Surfaces/CloudVMState+SnapshotComparison.swift

@@ -0,0 +1,62 @@
+import Foundation
+
+extension CloudVMState {
+    static func == (lhs: CloudVMState, rhs: CloudVMState) -> Bool {
+        lhs.hasSameModeledContent(as: rhs) && lhs.document == rhs.document
+    }
+
+    /// Clients and live terminal titles and dimensions are observations, not
+    /// revisioned resources (client.list and public_terminal_snapshot). Keep
+    /// them in exports without treating inspection or resize as a conflict.
+    func hasSameRevisionedContent(as other: CloudVMState) -> Bool {
+        hasSameModeledContent(as: other, includingLiveTerminalMetadata: false)
+            && document.values.filter { $0.key != "clients" } == other.document.values.filter { $0.key != "clients" }
+            && document.collections.filter { $0.key != "clients" && $0.key != "terminals" }
+                == other.document.collections.filter { $0.key != "clients" && $0.key != "terminals" }
+            && hasSameTerminalDocument(as: other)
+    }
+
+    private var revisionedTerminals: [CloudVMTerminalState] {
+        terminals.map {
+            var terminal = $0
+            terminal.title = ""
+            terminal.cols = nil
+            terminal.rows = nil
+            return terminal
+        }
+    }
+
+    private func hasSameModeledContent(as other: CloudVMState, includingLiveTerminalMetadata: Bool = true) -> Bool {
+        let left = includingLiveTerminalMetadata ? terminals : revisionedTerminals
+        let right = includingLiveTerminalMetadata ? other.terminals : other.revisionedTerminals
+        return machine == other.machine
+            && cursor == other.cursor
+            && workspaces == other.workspaces
+            && screens == other.screens
+            && panes == other.panes
+            && tabs == other.tabs
+            && left == right
+            && browsers == other.browsers
+            && agents == other.agents
+    }
+
+    /// Identity, launch fields, and unknown fields remain strict. Only the PTY
+    /// title and dimensions are live; unchanged rows use their byte cache.
+    private func hasSameTerminalDocument(as other: CloudVMState) -> Bool {
+        guard let left = document.collections["terminals"] else {
+            return other.document.collections["terminals"] == nil
+        }
+        guard let right = other.document.collections["terminals"], left.order == right.order else { return false }
+        for id in left.order {
+            guard let a = left.rows[id], let b = right.rows[id] else { return false }
+            if a == b { continue }
+            guard var lhs = try? JSONSerialization.jsonObject(with: a) as? [String: Any],
+                  var rhs = try? JSONSerialization.jsonObject(with: b) as? [String: Any] else { return false }
+            for key in ["title", "cols", "rows"] { lhs[key] = nil; rhs[key] = nil }
+            guard let lhsData = try? JSONSerialization.data(withJSONObject: lhs, options: [.sortedKeys]),
+                  let rhsData = try? JSONSerialization.data(withJSONObject: rhs, options: [.sortedKeys]),
+                  lhsData == rhsData else { return false }
+        }
+        return true
+    }
+}

Sources/Surfaces/CmuxTuiSurfaceProvider+PortForward.swift

@@ -12,7 +12,8 @@ extension CmuxTuiSurfaceProvider {
     func materializeBrowserPane(
         _ resource: SurfaceResource,
         at destination: SurfaceDestination,
-        focus: Bool
+        focus: Bool,
+        reusing existingPane: (workspaceID: UUID, panelID: UUID)? = nil
     ) async throws -> (workspaceID: UUID, panelID: UUID) {
         let generation = currentLifecycleGeneration
         try Task.checkCancellation()
@@ -33,7 +34,7 @@ extension CmuxTuiSurfaceProvider {
             try Task.checkCancellation()
             guard isCurrentLifecycleGeneration(generation), isRegisteredInCatalog() else { throw CancellationError() }
             let label = Self.paneLabel(machineID: machineID, port: target.port, desktop: desktop)
-            let pane = try Self.makeConnectingPane(label: label, at: destination, focus: focus)
+            let pane = try Self.makeConnectingPane(label: label, at: destination, focus: focus, reusing: existingPane)
             let machineWasAwake = isAwake
             // A provider that is stopped or replaced while this runs must not
             // touch the pane its successor now owns.
@@ -66,7 +67,7 @@ extension CmuxTuiSurfaceProvider {
         case .controlPlanePreview(let port):
             guard isRegisteredInCatalog() else { throw CancellationError() }
             let label = Self.paneLabel(machineID: machineID, port: port, desktop: desktop)
-            let pane = try Self.makeConnectingPane(label: label, at: destination, focus: focus)
+            let pane = try Self.makeConnectingPane(label: label, at: destination, focus: focus, reusing: existingPane)
             browserPaneTasks[pane.panelID] = Task { @MainActor [weak self] in
                 guard let self else { return }
                 defer { self.browserPaneTasks[pane.panelID] = nil }
@@ -86,6 +87,44 @@ extension CmuxTuiSurfaceProvider {
         }
     }
 
+    /// Restored browser tabs retain their identity, but their saved loopback
+    /// ports belong to the previous process. Reuse the normal route preparation
+    /// path to create a new forward and navigate the existing tab in place.
+    func reprojectRestoredBrowserPanes(generation: UInt64) {
+        for resource in catalog.snapshot.resources(on: machine) where resource.kind != .terminal {
+            for projection in catalog.projections(of: resource.id)
+            where !materializedPanels.contains(projection.panelID) {
+                guard SurfacePaneFactory.browserPanel(panelID: projection.panelID, in: projection.workspaceID) != nil,
+                      let paneID = SurfacePaneFactory.paneID(ofPanel: projection.panelID, in: projection.workspaceID) else { continue }
+                materializedPanels.insert(projection.panelID)
+                let pane = (workspaceID: projection.workspaceID, panelID: projection.panelID)
+                // The old process no longer owns this URL. Retire it before
+                // any route setup can suspend, then reuse the normal preparer.
+                SurfacePaneFactory.navigate(panelID: pane.panelID, in: pane.workspaceID, to: SurfacePaneFactory.blankURL)
+                SurfacePaneFactory.showPlaceholder(SurfaceBrowserPlaceholder.connecting(resource.title), panelID: pane.panelID, in: pane.workspaceID)
+                // This task owns forward creation; materializeBrowserPane hands
+                // the same slot to its navigation task after the forward binds.
+                browserPaneTasks[pane.panelID] = Task { @MainActor [weak self] in
+                    guard let self else { return }
+                    do {
+                        try Task.checkCancellation()
+                        guard self.isCurrentLifecycleGeneration(generation), self.isRegisteredInCatalog() else { return }
+                        _ = try await self.materializeBrowserPane(
+                            resource,
+                            at: .tab(workspaceID: pane.workspaceID, paneID: paneID, index: nil),
+                            focus: false,
+                            reusing: pane
+                        )
+                    } catch {
+                        self.browserPaneTasks[pane.panelID] = nil
+                        guard !Task.isCancelled, self.isCurrentLifecycleGeneration(generation) else { return }
+                        Self.showFailure(label: resource.title, error: error, pane: pane)
+                    }
+                }
+            }
+        }
+    }
+
     /// The link `port` opens as, shared by the pane, Copy Link, and
     /// `vm.port_open`: the loopback forward when the machine has a private
     /// address, else the control plane's tokened preview URL. Throws when the
@@ -138,9 +177,10 @@ extension CmuxTuiSurfaceProvider {
     private static func makeConnectingPane(
         label: String,
         at destination: SurfaceDestination,
-        focus: Bool
+        focus: Bool,
+        reusing existingPane: (workspaceID: UUID, panelID: UUID)? = nil
     ) throws -> (workspaceID: UUID, panelID: UUID) {
-        let pane = try SurfacePaneFactory.makeBrowserPane(url: SurfacePaneFactory.blankURL, at: destination, focus: focus)
+        let pane = try existingPane ?? SurfacePaneFactory.makeBrowserPane(url: SurfacePaneFactory.blankURL, at: destination, focus: focus)
         SurfacePaneFactory.showPlaceholder(SurfaceBrowserPlaceholder.connecting(label), panelID: pane.panelID, in: pane.workspaceID)
         return pane
     }

Sources/Surfaces/CmuxTuiSurfaceProvider+Refresh.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+extension CmuxTuiSurfaceProvider {
+    func refresh() async {
+        await refreshCurrentGraph(force: false)
+    }
+
+    // Matches the protocol's Void return type so existential catalog reads
+    // preserve force instead of falling through to its legacy default.
+    func refresh(force: Bool) async {
+        await refreshCurrentGraph(force: force)
+    }
+
+    /// Re-syncs the graph and reports whether the result is authoritative enough
+    /// for mutations. Concurrent reads share the provider's refresh owner.
+    @discardableResult
+    func refreshCurrentGraph(force: Bool) async -> Bool {
+        await refreshCoordinator.refresh(force: force) { [weak self] force in
+            guard let self else { return false }
+            return await self.performRefresh(force: force)
+        }
+    }
+}