Propagate phone transport state to iOS surface errors

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileStateSyncRecords.swift

@@ -35,6 +35,43 @@ public struct MobileSyncCollectionID: RawRepresentable, Codable, Hashable, Senda
 /// `mobile.workspace.list` payload (same snake_case wire names) plus an
 /// explicit `sort_index` so list order syncs without positional inference.
 public struct WorkspaceSyncRecord: MobileSyncRecord {
+    /// One surface row within a workspace.
+    public struct Surface: Codable, Equatable, Sendable {
+        /// Stable surface identifier.
+        public let surfaceID: String
+        /// Open surface-kind wire string.
+        public let kind: String
+        /// User-facing surface title.
+        public let title: String
+        /// Backing file path for file-based surfaces, when reported.
+        public let filePath: String?
+        /// Bounded checklist/status payload for todo surfaces.
+        public let todo: MobileTodoSnapshot?
+
+        /// Creates a surface row from its wire fields.
+        public init(
+            surfaceID: String,
+            kind: String,
+            title: String,
+            filePath: String?,
+            todo: MobileTodoSnapshot? = nil
+        ) {
+            self.surfaceID = surfaceID
+            self.kind = kind
+            self.title = title
+            self.filePath = filePath
+            self.todo = todo
+        }
+
+        private enum CodingKeys: String, CodingKey {
+            case surfaceID = "surface_id"
+            case kind
+            case title
+            case filePath = "file_path"
+            case todo
+        }
+    }
+
     /// One terminal row within a workspace.
     public struct Terminal: Codable, Equatable, Sendable {
         /// Stable terminal identifier.
@@ -104,6 +141,9 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
     public let sortIndex: Int
     /// Terminal rows belonging to this workspace, in spatial order.
     public let terminals: [Terminal]
+    /// All surface rows belonging to this workspace, in spatial order.
+    /// `nil` when decoded from a Mac that predates surface inventory support.
+    public let surfaces: [Surface]?
 
     /// ``MobileSyncRecord`` identity: the workspace id.
     public var syncID: String { id }
@@ -127,7 +167,8 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
         lastActivityAt: Double,
         hasUnread: Bool,
         sortIndex: Int,
-        terminals: [Terminal]
+        terminals: [Terminal],
+        surfaces: [Surface]? = nil
     ) {
         self.id = id
         self.windowID = windowID
@@ -145,6 +186,7 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
         self.hasUnread = hasUnread
         self.sortIndex = sortIndex
         self.terminals = terminals
+        self.surfaces = surfaces
     }
 
     public init(from decoder: any Decoder) throws {
@@ -168,6 +210,7 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
         hasUnread = try container.decode(Bool.self, forKey: .hasUnread)
         sortIndex = try container.decode(Int.self, forKey: .sortIndex)
         terminals = try container.decode([Terminal].self, forKey: .terminals)
+        surfaces = try container.decodeIfPresent([Surface].self, forKey: .surfaces)
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -187,6 +230,7 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
         case hasUnread = "has_unread"
         case sortIndex = "sort_index"
         case terminals
+        case surfaces
     }
 }
 

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileSurfaceKind.swift

@@ -0,0 +1,48 @@
+/// A mobile surface kind identified by its open wire string.
+///
+/// Known kinds have static constants, while unknown raw values remain valid so
+/// older clients can preserve and route surface kinds introduced by newer Macs.
+public struct MobileSurfaceKind: RawRepresentable, Codable, Hashable, Sendable {
+    /// The surface kind's wire identifier.
+    public let rawValue: String
+
+    /// Creates a surface kind from its wire identifier.
+    /// - Parameter rawValue: The open surface-kind string.
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+
+    /// Decodes the kind directly from its open wire string.
+    public init(from decoder: any Decoder) throws {
+        rawValue = try decoder.singleValueContainer().decode(String.self)
+    }
+
+    /// Encodes the kind directly as its open wire string.
+    public func encode(to encoder: any Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(rawValue)
+    }
+
+    /// A Ghostty terminal surface.
+    public static let terminal = MobileSurfaceKind(rawValue: "terminal")
+    /// A browser surface.
+    public static let browser = MobileSurfaceKind(rawValue: "browser")
+    /// A markdown preview surface.
+    public static let markdown = MobileSurfaceKind(rawValue: "markdown")
+    /// A file preview surface.
+    public static let filePreview = MobileSurfaceKind(rawValue: "filePreview")
+    /// A right-sidebar tool hosted as a surface.
+    public static let rightSidebarTool = MobileSurfaceKind(rawValue: "rightSidebarTool")
+    /// A custom sidebar hosted as a surface.
+    public static let customSidebar = MobileSurfaceKind(rawValue: "customSidebar")
+    /// An agent-session surface.
+    public static let agentSession = MobileSurfaceKind(rawValue: "agentSession")
+    /// A project surface.
+    public static let project = MobileSurfaceKind(rawValue: "project")
+    /// A browser surface owned by an extension.
+    public static let extensionBrowser = MobileSurfaceKind(rawValue: "extensionBrowser")
+    /// A workspace todo surface.
+    public static let todo = MobileSurfaceKind(rawValue: "todo")
+    /// A transient Cloud VM loading surface.
+    public static let cloudVMLoading = MobileSurfaceKind(rawValue: "cloudVMLoading")
+}

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTodoItem.swift

@@ -0,0 +1,32 @@
+/// One bounded checklist item synced with a workspace todo surface.
+public struct MobileTodoItem: Codable, Equatable, Identifiable, Sendable {
+    /// The maximum number of characters accepted for one item's normalized text.
+    public static let maxTextLength = 500
+
+    /// The Mac-owned stable item identifier.
+    public let id: String
+    /// The normalized item text.
+    public let text: String
+    /// The item's progress state.
+    public let state: MobileTodoItemState
+    /// Who created the item.
+    public let origin: MobileTodoItemOrigin
+
+    /// Creates a mobile checklist item.
+    /// - Parameters:
+    ///   - id: The Mac-owned stable item identifier.
+    ///   - text: The normalized item text.
+    ///   - state: The item's progress state.
+    ///   - origin: Who created the item.
+    public init(
+        id: String,
+        text: String,
+        state: MobileTodoItemState,
+        origin: MobileTodoItemOrigin
+    ) {
+        self.id = id
+        self.text = text
+        self.state = state
+        self.origin = origin
+    }
+}

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTodoItemOrigin.swift

@@ -0,0 +1,7 @@
+/// The creator of a mobile checklist item.
+public enum MobileTodoItemOrigin: String, Codable, CaseIterable, Sendable {
+    /// A person created the item.
+    case user
+    /// An agent created the item.
+    case agent
+}

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTodoItemState.swift

@@ -0,0 +1,18 @@
+/// A mobile checklist item's progress state.
+public enum MobileTodoItemState: String, Codable, CaseIterable, Sendable {
+    /// Work has not started.
+    case pending
+    /// Work is actively progressing.
+    case inProgress = "in_progress"
+    /// Work is complete.
+    case completed
+
+    /// The next state in the mobile tap cycle.
+    public var next: MobileTodoItemState {
+        switch self {
+        case .pending: .inProgress
+        case .inProgress: .completed
+        case .completed: .pending
+        }
+    }
+}

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTodoSnapshot.swift

@@ -0,0 +1,29 @@
+/// The bounded todo payload attached to a synced todo surface.
+public struct MobileTodoSnapshot: Codable, Equatable, Sendable {
+    /// The maximum number of checklist items carried by one mobile snapshot.
+    public static let maxItems = 50
+
+    /// The effective status after applying any valid manual override.
+    public let status: MobileTodoStatus
+    /// Whether the workspace opted out of showing its status lane.
+    public let statusHidden: Bool
+    /// Checklist items in the Mac's storage order.
+    public let items: [MobileTodoItem]
+
+    /// Creates a todo snapshot.
+    /// - Parameters:
+    ///   - status: The effective workspace status.
+    ///   - statusHidden: Whether status presentation is hidden.
+    ///   - items: Checklist items in storage order.
+    public init(status: MobileTodoStatus, statusHidden: Bool, items: [MobileTodoItem]) {
+        self.status = status
+        self.statusHidden = statusHidden
+        self.items = items
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case status
+        case statusHidden = "status_hidden"
+        case items
+    }
+}

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTodoStatus.swift

@@ -0,0 +1,20 @@
+/// A workspace's effective todo status on the mobile wire.
+public enum MobileTodoStatus: String, Codable, CaseIterable, Sendable {
+    /// Work has not started.
+    case todo
+    /// Work is actively progressing.
+    case working
+    /// Work is waiting for attention or input.
+    case needsAttention = "needs-attention"
+    /// Work is ready for review.
+    case review
+    /// Work is complete.
+    case done
+
+    /// The next status in the same cycle used by the Mac todo controls.
+    public var next: MobileTodoStatus {
+        let statuses = Self.allCases
+        guard let index = statuses.firstIndex(of: self) else { return .todo }
+        return statuses[(index + 1) % statuses.count]
+    }
+}

Packages/Shared/CMUXMobileCore/Tests/CMUXMobileCoreTests/MobileStateSyncFrameCodingTests.swift

@@ -29,6 +29,32 @@ struct MobileStateSyncFrameCodingTests {
                     isReady: true,
                     isFocused: false
                 )
+            ],
+            surfaces: [
+                WorkspaceSyncRecord.Surface(
+                    surfaceID: "surface-future",
+                    kind: "simulator",
+                    title: "iPhone 17 Pro",
+                    filePath: nil
+                ),
+                WorkspaceSyncRecord.Surface(
+                    surfaceID: "surface-todo",
+                    kind: MobileSurfaceKind.todo.rawValue,
+                    title: "Todo",
+                    filePath: nil,
+                    todo: MobileTodoSnapshot(
+                        status: .needsAttention,
+                        statusHidden: false,
+                        items: [
+                            MobileTodoItem(
+                                id: "item-1",
+                                text: "Review the renderer",
+                                state: .inProgress,
+                                origin: .agent
+                            ),
+                        ]
+                    )
+                )
             ]
         )
     }
@@ -51,6 +77,46 @@ struct MobileStateSyncFrameCodingTests {
         let terminals = object["terminals"] as? [[String: Any]]
         #expect(terminals?.first?["is_ready"] as? Bool == true)
         #expect(terminals?.first?["is_focused"] as? Bool == false)
+        let surfaces = object["surfaces"] as? [[String: Any]]
+        #expect(surfaces?.first?["surface_id"] as? String == "surface-future")
+        #expect(surfaces?.first?["kind"] as? String == "simulator")
+        #expect(surfaces?.first?["file_path"] == nil)
+        let todo = surfaces?[1]["todo"] as? [String: Any]
+        #expect(todo?["status"] as? String == "needs-attention")
+        #expect(todo?["status_hidden"] as? Bool == false)
+        let items = todo?["items"] as? [[String: Any]]
+        #expect(items?.first?["id"] as? String == "item-1")
+        #expect(items?.first?["state"] as? String == "in_progress")
+        #expect(items?.first?["origin"] as? String == "agent")
+    }
+
+    @Test func mobileSurfaceKindPreservesUnknownRawValues() throws {
+        let kind = MobileSurfaceKind(rawValue: "simulator")
+        let data = try JSONEncoder().encode(kind)
+        #expect(String(decoding: data, as: UTF8.self) == #""simulator""#)
+        #expect(try JSONDecoder().decode(MobileSurfaceKind.self, from: data) == kind)
+    }
+
+    @Test func workspaceRecordWithoutSurfacesDecodesAndReencodesWithoutTheField() throws {
+        let json = #"{"id":"ws-old","title":"old","is_selected":false,"is_pinned":false,"last_activity_at":1,"has_unread":false,"sort_index":0,"terminals":[]}"#
+        let decoded = try MobileSyncFrameCoder().decode(
+            WorkspaceSyncRecord.self,
+            fromJSONString: json
+        )
+        #expect(decoded.surfaces == nil)
+        let object = try MobileSyncFrameCoder().jsonObject(from: decoded)
+        #expect(object["surfaces"] == nil)
+    }
+
+    @Test func workspaceRecordRoundTripsSurfaceInventory() throws {
+        let decoded = try JSONDecoder().decode(
+            WorkspaceSyncRecord.self,
+            from: JSONEncoder().encode(workspace)
+        )
+        #expect(decoded == workspace)
+        #expect(decoded.surfaces?.first?.kind == "simulator")
+        #expect(decoded.surfaces?[1].todo?.status == .needsAttention)
+        #expect(decoded.surfaces?[1].todo?.items.first?.state == .inProgress)
     }
 
     @Test func workspaceRecordDefaultsMissingDescriptionTruncatedFlagToFalse() throws {

Packages/Shared/CmuxAgentChat/Sources/CmuxAgentChat/Artifacts/ChatArtifactError.swift

@@ -18,4 +18,9 @@ public enum ChatArtifactError: Error, Sendable, Equatable {
     case macUnreachable
     /// The file exceeds the inline preview size limit.
     case tooLarge(limitBytes: Int64)
+    /// The Mac answered with an error this client does not recognize.
+    ///
+    /// Distinct from ``macUnreachable``: the connection worked and the Mac
+    /// replied, so messaging must not blame connectivity.
+    case unknown(code: String?)
 }