Decouple iOS primary terminal scroll

Packages/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalScrollbackBudget.swift

@@ -0,0 +1,15 @@
+public enum MobileTerminalScrollbackBudget {
+    /// Small fallback used when an older client asks for replay without an
+    /// explicit scrollback window.
+    public static let defaultReplayRows = 240
+
+    /// Bounded repair window for host-coupled scroll responses. The decoupled
+    /// primary-screen path should not depend on this during normal iPhone
+    /// scrolling.
+    public static let scrollPrefetchRows = 600
+}
+
+public enum MobileTerminalScrollbackReplayRequest {
+    public static let scopeParameter = "scrollback_scope"
+    public static let fullScope = "full"
+}

Packages/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Debug/ControlCommandCoordinator+Debug.swift

@@ -74,6 +74,8 @@ extension ControlCommandCoordinator {
             return debugSimulateTerminalFileDrop(request.params)
         case "debug.terminal.read_text":
             return debugReadTerminalText(request.params)
+        case "debug.terminal.scroll_to_row_offset":
+            return debugTerminalScrollToRowOffset(request.params)
         case "debug.terminal.render_stats":
             return debugRenderStats(request.params)
         case "debug.layout":

Packages/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Debug/ControlCommandCoordinator+Debug2.swift

@@ -232,6 +232,28 @@ extension ControlCommandCoordinator {
         return .ok(.object(["base64": .string(b64)]))
     }
 
+    /// `debug.terminal.scroll_to_row_offset` — drive Ghostty's fractional
+    /// row-offset scroll API for renderer verification.
+    func debugTerminalScrollToRowOffset(_ params: [String: JSONValue]) -> ControlCallResult {
+        let surfaceArg = string(params, "surface_id") ?? ""
+        guard let rowOffset = double(params, "row_offset"), rowOffset.isFinite else {
+            return .err(code: "invalid_params", message: "Missing or invalid row_offset", data: nil)
+        }
+        let didScroll = debugContext?.controlDebugTerminalScrollToRowOffset(
+            surfaceArgument: surfaceArg,
+            rowOffset: rowOffset
+        ) ?? false
+        guard didScroll else {
+            return .err(code: "not_found", message: "Terminal surface not found", data: .object([
+                "surface_id": .string(surfaceArg)
+            ]))
+        }
+        return .ok(.object([
+            "surface_id": .string(surfaceArg),
+            "row_offset": .double(rowOffset)
+        ]))
+    }
+
     /// `debug.terminal.render_stats` — renderer stats (shared v1 body's JSON,
     /// decoded exactly as the legacy wrapper did).
     func debugRenderStats(_ params: [String: JSONValue]) -> ControlCallResult {

Packages/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Debug/ControlDebugContext.swift

@@ -71,6 +71,16 @@ public protocol ControlDebugContext: AnyObject {
     /// - Returns: The raw v1 response (`"OK <base64>"` or an `ERROR:` line).
     func controlDebugReadTerminalText(surfaceArgument: String) -> String
 
+    /// Drives a terminal's Ghostty scrollback to a fractional row offset for
+    /// renderer verification.
+    ///
+    /// - Parameters:
+    ///   - surfaceArgument: The surface id/index argument (may be empty for the
+    ///     focused surface).
+    ///   - rowOffset: Fractional row offset from the top of primary scrollback.
+    /// - Returns: `true` when the target terminal exists and has a live surface.
+    func controlDebugTerminalScrollToRowOffset(surfaceArgument: String, rowOffset: Double) -> Bool
+
     /// Runs the shared v1 `render_stats` body for `debug.terminal.render_stats`.
     ///
     /// - Parameter surfaceArgument: The surface id/index argument.

Packages/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandContextTestStubs+Debug.swift

@@ -16,6 +16,7 @@ extension ControlDebugContext {
     func controlDebugActivateApp() -> String { "ERROR: not implemented" }
     func controlDebugIsTerminalFocused(surfaceArgument: String) -> String { "ERROR: not implemented" }
     func controlDebugReadTerminalText(surfaceArgument: String) -> String { "ERROR: not implemented" }
+    func controlDebugTerminalScrollToRowOffset(surfaceArgument: String, rowOffset: Double) -> Bool { false }
     func controlDebugRenderStats(surfaceArgument: String) -> String { "ERROR: not implemented" }
     func controlDebugLayout() -> String { "ERROR: not implemented" }
     func controlDebugBonsplitUnderflowCount() -> String { "ERROR: not implemented" }

Packages/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift

@@ -29,7 +29,11 @@ extension MobileShellComposite {
         terminalOutputQueuesBySurfaceID[surfaceID] = queue
         if let immediate {
             continuation.yield(
-                MobileTerminalOutputChunk(data: immediate.bytes, streamToken: streamToken)
+                MobileTerminalOutputChunk(
+                    data: immediate.bytes,
+                    streamToken: streamToken,
+                    activeScreen: immediate.activeScreen
+                )
             )
         }
     }
@@ -45,6 +49,10 @@ extension MobileShellComposite {
               terminalOutputStreamTokensBySurfaceID[surfaceID] == streamToken else {
             return
         }
-        continuation.yield(MobileTerminalOutputChunk(data: next.bytes, streamToken: streamToken))
+        continuation.yield(MobileTerminalOutputChunk(
+            data: next.bytes,
+            streamToken: streamToken,
+            activeScreen: next.activeScreen
+        ))
     }
 }

Packages/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift

@@ -534,6 +534,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
     private var deliveredTerminalByteEndSeqBySurfaceID: [String: UInt64]
     private var pendingTerminalByteEndSeqBySurfaceID: [String: UInt64]
     private var terminalReplaySurfaceIDsInFlight: Set<String>
+    private var terminalReplaySurfaceIDsPendingWorkspaceMapping: Set<String>
     private var terminalOutputTransport: TerminalOutputTransport
     var terminalByteContinuationsBySurfaceID: [String: AsyncStream<MobileTerminalOutputChunk>.Continuation]
     var terminalOutputStreamTokensBySurfaceID: [String: UUID]
@@ -661,6 +662,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         self.deliveredTerminalByteEndSeqBySurfaceID = [:]
         self.pendingTerminalByteEndSeqBySurfaceID = [:]
         self.terminalReplaySurfaceIDsInFlight = []
+        self.terminalReplaySurfaceIDsPendingWorkspaceMapping = []
         self.terminalOutputTransport = .rawBytes
         self.terminalByteContinuationsBySurfaceID = [:]
         self.terminalOutputStreamTokensBySurfaceID = [:]
@@ -3076,6 +3078,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         deliveredTerminalByteEndSeqBySurfaceID = [:]
         pendingTerminalByteEndSeqBySurfaceID = [:]
         terminalReplaySurfaceIDsInFlight = []
+        terminalReplaySurfaceIDsPendingWorkspaceMapping = []
         terminalOutputQueuesBySurfaceID = [:]
         terminalOutputStreamTokensBySurfaceID = terminalOutputStreamTokensBySurfaceID.mapValues { _ in UUID() }
         terminalScrollQueueTokensBySurfaceID = [:]
@@ -4258,6 +4261,19 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         }
     }
 
+    private func retryTerminalReplaysPendingWorkspaceMapping(reason: String) {
+        guard remoteClient != nil, connectionState == .connected else { return }
+        let surfaceIDs = terminalReplaySurfaceIDsPendingWorkspaceMapping
+            .filter { hasTerminalOutputSink(surfaceID: $0) && workspaceID(forTerminalID: $0) != nil }
+        guard !surfaceIDs.isEmpty else { return }
+        MobileDebugLog.anchormux(
+            "sync.replay_mapping_ready reason=\(reason) surfaces=\(surfaceIDs.count)"
+        )
+        for surfaceID in surfaceIDs {
+            requestTerminalReplay(surfaceID: surfaceID)
+        }
+    }
+
     private func handleTerminalInputResponse(_ data: Data, surfaceID: String) {
         guard hasTerminalOutputSink(surfaceID: surfaceID),
               let payload = try? MobileTerminalInputResponse.decode(data),
@@ -4371,6 +4387,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         terminalScrollbackPrefetchStatesBySurfaceID.removeValue(forKey: surfaceID)
         deliveredTerminalByteEndSeqBySurfaceID.removeValue(forKey: surfaceID)
         pendingTerminalByteEndSeqBySurfaceID.removeValue(forKey: surfaceID)
+        terminalReplaySurfaceIDsPendingWorkspaceMapping.remove(surfaceID)
         // Tell the Mac this device is no longer viewing the surface so it stops
         // pinning the shared grid to our viewport and clears the macOS border.
         clearTerminalViewport(surfaceID: surfaceID)
@@ -4469,11 +4486,13 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
             return
         }
         guard let workspaceID = workspaceID(forTerminalID: surfaceID) else {
+            terminalReplaySurfaceIDsPendingWorkspaceMapping.insert(surfaceID)
             #if DEBUG
             mobileShellLog.error("CMUX_REPLAY skip surface=\(surfaceID, privacy: .public) reason=workspace_not_found")
             #endif
             return
         }
+        terminalReplaySurfaceIDsPendingWorkspaceMapping.remove(surfaceID)
         guard !terminalReplaySurfaceIDsInFlight.contains(surfaceID) else {
             #if DEBUG
             mobileShellLog.info("CMUX_REPLAY skip surface=\(surfaceID, privacy: .public) reason=in_flight")
@@ -4490,6 +4509,8 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
                     params: [
                         "workspace_id": workspaceID.rawValue,
                         "surface_id": surfaceID,
+                        MobileTerminalScrollbackReplayRequest.scopeParameter:
+                            MobileTerminalScrollbackReplayRequest.fullScope,
                     ]
                 )
                 let data = try await client.sendRequest(request)
@@ -4743,11 +4764,13 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
             workspaceGroups = response.groups.map { MobileWorkspaceGroupPreview(remote: $0) }
         }
         if preferActiveTicketTarget, selectActiveTicketTargetIfAvailable() {
+            retryTerminalReplaysPendingWorkspaceMapping(reason: "workspace_list")
             return
         }
         if let selectedWorkspaceID,
            workspaces.contains(where: { $0.id == selectedWorkspaceID }) {
             syncSelectedTerminalForWorkspace()
+            retryTerminalReplaysPendingWorkspaceMapping(reason: "workspace_list")
             return
         }
         setSelectedWorkspaceID(
@@ -4756,6 +4779,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
                 ?? workspaces.first?.id
         )
         syncSelectedTerminalForWorkspace()
+        retryTerminalReplaysPendingWorkspaceMapping(reason: "workspace_list")
     }
 
     private func remoteWorkspacesPreservingSnapshots(

Packages/CmuxMobileShell/Sources/CmuxMobileShell/TerminalOutputDelivery.swift

@@ -29,6 +29,15 @@ struct TerminalOutputDelivery: Equatable, Sendable {
             frame.vtPatchBytes()
         }
     }
+
+    var activeScreen: MobileTerminalRenderGridFrame.Screen? {
+        switch payload {
+        case .bytes:
+            nil
+        case .renderGrid(let frame):
+            frame.activeScreen
+        }
+    }
 }
 
 /// Backpressure queue for one mounted mobile terminal output stream.

Packages/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalOutputDeliveryQueueTests.swift

@@ -90,6 +90,22 @@ import Testing
     #expect(!vt.contains("old"))
 }
 
+@Test func terminalOutputDeliveryCarriesRenderGridActiveScreen() throws {
+    let frame = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal",
+        stateSeq: 1,
+        columns: 12,
+        rows: 2,
+        rowSpans: [],
+        activeScreen: .alternate
+    )
+    let delivery = TerminalOutputDelivery(renderGrid: frame, replaceable: false)
+    let rawDelivery = TerminalOutputDelivery(bytes: Data("raw".utf8), replaceable: false)
+
+    #expect(delivery.activeScreen == .alternate)
+    #expect(rawDelivery.activeScreen == nil)
+}
+
 @Test func terminalOutputQueuePreservesNonreplaceableBarriers() {
     var queue = TerminalOutputDeliveryQueue()
     let inFlight = TerminalOutputDelivery(bytes: Data("in-flight".utf8), replaceable: false)

Packages/CmuxMobileShellModel/Sources/CmuxMobileShellModel/MobileTerminalOutputSinking.swift

@@ -1,3 +1,4 @@
+public import CMUXMobileCore
 public import Foundation
 
 /// A seam exposing per-surface terminal output as an `AsyncStream`.
@@ -14,10 +15,18 @@ public import Foundation
 /// propagation is a structured, cancellable `AsyncSequence` instead of a stored
 /// callback.
 public struct MobileTerminalOutputChunk: Sendable {
+    /// The active terminal screen captured by the render-grid frame that
+    /// produced ``data``. Raw byte fallback chunks carry `nil`.
+    public let activeScreen: MobileTerminalRenderGridFrame.Screen?
     public let data: Data
     public let streamToken: UUID
 
-    public init(data: Data, streamToken: UUID) {
+    public init(
+        data: Data,
+        streamToken: UUID,
+        activeScreen: MobileTerminalRenderGridFrame.Screen? = nil
+    ) {
+        self.activeScreen = activeScreen
         self.data = data
         self.streamToken = streamToken
     }

Packages/CmuxMobileShellUI/Sources/CmuxMobileShellUI/CMUXMobileRootView.swift

@@ -75,7 +75,10 @@ struct CMUXMobileRootView: View {
         .animation(.snappy(duration: 0.18), value: isAuthenticated)
         .animation(.snappy(duration: 0.18), value: store.phase)
         .onAppear {
-            syncShellAuthentication(isAuthenticated)
+            let startedLaunchAttachURL = connectLaunchAttachURLIfNeeded()
+            if !startedLaunchAttachURL {
+                syncShellAuthentication(isAuthenticated)
+            }
             store.resumeForegroundRefresh()
             #if os(iOS)
             pushCoordinator.bind(store: store)
@@ -85,7 +88,9 @@ struct CMUXMobileRootView: View {
             // so kick off the stored-Mac reconnect here too. Without this the
             // restoring gate could stay on RestoringSessionView forever because
             // nothing ever resolves `didFinishStoredMacReconnectAttempt`.
-            reconnectStoredMacIfNeeded()
+            if !startedLaunchAttachURL {
+                reconnectStoredMacIfNeeded()
+            }
         }
         #if os(iOS)
         // A notification tap can arrive before the workspace (or terminal) it
@@ -125,6 +130,7 @@ struct CMUXMobileRootView: View {
         .onChange(of: isAuthenticated) { _, isAuthenticated in
             syncShellAuthentication(isAuthenticated)
             guard isAuthenticated else {
+                _ = connectLaunchAttachURLIfNeeded()
                 return
             }
             if let rawURL = pendingAttachURL {
@@ -308,10 +314,9 @@ struct CMUXMobileRootView: View {
     /// sign-in that completes after mount) so the restoring gate always resolves
     /// even when the auth state never transitions while this view is mounted.
     private func reconnectStoredMacIfNeeded() {
+        if connectLaunchAttachURLIfNeeded() { return }
         guard isAuthenticated else { return }
-        let startedUITestAttachURL = connectUITestAttachURLIfNeeded()
-        guard !startedUITestAttachURL,
-              MobileRootAuthGate.shouldReconnectStoredMac(
+        guard MobileRootAuthGate.shouldReconnectStoredMac(
                 stackAuthenticated: authManager.isAuthenticated,
                 attachTicketAuthenticated: hasActiveAttachTicketAuthentication,
                 connectionState: store.connectionState
@@ -379,7 +384,7 @@ struct CMUXMobileRootView: View {
     }
 
     @discardableResult
-    private func connectUITestAttachURLIfNeeded() -> Bool {
+    private func connectLaunchAttachURLIfNeeded() -> Bool {
         #if DEBUG
         // Auto-pair when an attach URL is supplied at launch. Two sources:
         //   - CMUX_DOGFOOD_ATTACH_URL (UITestConfig.dogfoodAttachURL): NOT gated on
@@ -394,14 +399,11 @@ struct CMUXMobileRootView: View {
         // No-op unless one of those env vars is set, so normal launches are
         // unaffected.
         guard !didConsumeUITestAttachURL,
-              isAuthenticated,
               let attachURL = UITestConfig.dogfoodAttachURL ?? UITestConfig.attachURL else {
             return false
         }
         didConsumeUITestAttachURL = true
-        Task {
-            await store.connectPairingURL(attachURL)
-        }
+        connectAttachURL(attachURL)
         return true
         #else
         return false

Packages/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift

@@ -36,6 +36,10 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
     /// band and pins first responder so the keyboard hands over in place; when it
     /// flips off, the field is unmounted and the band collapses to zero height.
     var isComposerActive: Bool = false
+    /// Whether normal-screen scrollback should move on the phone without a Mac
+    /// round trip. Turning this off restores host-coupled scroll for dogfood
+    /// comparison.
+    var decouplePrimaryScreenScroll: Bool = true
 
     func makeCoordinator() -> Coordinator {
         Coordinator(surfaceID: surfaceID, store: store)
@@ -59,6 +63,7 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
             fontSize: fontSize
         )
         view.autoFocusOnWindowAttach = autoFocusOnWindowAttach
+        view.decouplePrimaryScreenScroll = decouplePrimaryScreenScroll
         #if DEBUG
         // Hand the surface the structured diagnostic log so the composer-dock
         // probes land in the blob the "Send to agent" feedback pane exports.
@@ -88,6 +93,7 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
         // state write, so it is safe in `updateUIView`.
         guard let surfaceView = uiView as? GhosttySurfaceView else { return }
         surfaceView.autoFocusOnWindowAttach = autoFocusOnWindowAttach
+        surfaceView.decouplePrimaryScreenScroll = decouplePrimaryScreenScroll
         surfaceView.setComposerActive(isComposerActive)
         context.coordinator.setComposerMounted(isComposerActive)
         // A width change (rotation) is not a text change, so the field-content trigger
@@ -137,6 +143,7 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
                 for await chunk in store.terminalOutputStream(surfaceID: surfaceID) {
                     guard !Task.isCancelled else { return }
                     guard let surfaceView else { return }
+                    surfaceView.applyTerminalOutputMetadata(activeScreen: chunk.activeScreen)
                     await surfaceView.processOutputAndWait(chunk.data)
                     store.terminalOutputDidProcess(
                         surfaceID: surfaceID,