fix(ios): deadline-bounded Tailscale readiness so the first QR scan succeeds

Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift

@@ -4394,6 +4394,9 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         acceptedVersionWarning: Bool,
         userEnteredPairingCode: Bool = false
     ) async -> MobilePairingURLConnectionResult {
+        MobileDebugLog.shared.append(
+            "pairing.qr_connect.begin user_entered=\(userEnteredPairingCode) accepted_version_warning=\(acceptedVersionWarning)"
+        )
         let rawURL = Self.normalizedPairingURL(rawValue ?? pairingCode)
         _ = beginPairingValidationAttempt()
         connectionAttemptGeneration = UUID()
@@ -4407,6 +4410,9 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         let ticket: CmxAttachTicket
         do {
             ticket = try CmxAttachTicketInput.decode(rawURL)
+            MobileDebugLog.shared.append(
+                "pairing.qr_decode.success route_count=\(ticket.routes.count) route_kinds=\(ticket.routes.map(\.kind.rawValue).sorted().joined(separator: ","))"
+            )
             // The v2 grammar rejects loopback inside the decoder; the legacy
             // grammars must keep decoding loopback for the simulator dev flow
             // (where 127.0.0.1 IS the host Mac). On a physical phone no
@@ -4422,6 +4428,10 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
                 throw MobileSyncPairingPayloadError.loopbackRouteRejected
             }
         } catch {
+            MobileDebugLog.shared.append(
+                // Type-only: a decode error can embed the scanned payload.
+                "pairing.qr_decode.failed error_type=\(type(of: error))"
+            )
             if case MobileSyncPairingPayloadError.loopbackRouteRejected = error {
                 // A scanned/pasted code that only points back at the Mac
                 // itself (127.0.0.1) would make the phone dial itself. Name
@@ -4451,6 +4461,9 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
             isDevelopmentAuthEnvironment: identityProvider?.isDevelopmentAuthEnvironment ?? false
         )
         if let emailFailure = accountPreflight.failure(for: ticket) {
+            MobileDebugLog.shared.append(
+                "pairing.account_preflight.failed category=\(emailFailure)"
+            )
             applyPairingValidationFailure(emailFailure)
             if connectionState != .connected {
                 connectionState = .disconnected
@@ -4499,6 +4512,9 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
             supportedKinds: runtime?.supportedRouteKinds ?? [],
             userTailscalePairingAuthorizations: userTailscalePairingAuthorizations
         )
+        MobileDebugLog.shared.append(
+            "pairing.attempt.started route_count=\(candidateRoutes.count) supported_route_kinds=\(candidateRoutes.map(\.kind.rawValue).sorted().joined(separator: ","))"
+        )
         if !candidateRoutes.isEmpty {
             switch await failPairingIfOffline(attemptID: attemptID, phase: "preflight", routes: candidateRoutes) {
             case .failedOffline: return .failed
@@ -4522,11 +4538,15 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
                 await loadPairedMacs()
                 guard isCurrentPairingAttempt(attemptID) else { return .superseded }
                 recordPairingSucceeded()
+                MobileDebugLog.shared.append("pairing.attempt.succeeded")
                 return .connected
             }
             // `connect()` returned without connecting and already set a
             // specific error; record without overwriting that message.
             recordFailureForCurrentConnectionError(phase: "connect", category: noThrowFailure)
+            MobileDebugLog.shared.append(
+                "pairing.attempt.failed_without_throw category=\(noThrowFailure.map(String.init(describing:)) ?? "nil")"
+            )
             return .failed
         } catch is CancellationError {
             guard isCurrentPairingAttempt(attemptID) else { return .superseded }
@@ -4537,6 +4557,9 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         } catch {
             guard isCurrentPairingAttempt(attemptID) else { return .superseded }
             mobileShellLog.error("pairing failed: \(String(describing: error), privacy: .private)")
+            MobileDebugLog.shared.append(
+                "pairing.attempt.failed error=\(String(describing: error))"
+            )
             // Definitive auth failures drive the re-auth prompt rather than a
             // generic connection error (matches the manual-host path); the
             // helper records the analytics failure + guidance.

Packages/iOS/CmuxMobileTransport/Package.swift

@@ -16,11 +16,12 @@ let package = Package(
     ],
     dependencies: [
         .package(path: "../../Shared/CMUXMobileCore"),
+        .package(path: "../CmuxMobileDiagnostics"),
     ],
     targets: [
         .target(
             name: "CmuxMobileTransport",
-            dependencies: ["CMUXMobileCore"],
+            dependencies: ["CMUXMobileCore", "CmuxMobileDiagnostics"],
             swiftSettings: [
                 .swiftLanguageMode(.v6),
                 .enableUpcomingFeature("ExistentialAny"),

Packages/iOS/CmuxMobileTransport/Sources/CmuxMobileTransport/CmxNetworkByteTransport.swift

@@ -1,4 +1,5 @@
 public import CMUXMobileCore
+import CmuxMobileDiagnostics
 public import Foundation
 import Dispatch
 @preconcurrency public import Network
@@ -330,9 +331,17 @@ public actor CmxNetworkByteTransport: CmxByteTransport {
             guard !isTerminal else {
                 return
             }
+            if tailscaleBinding != nil {
+                MobileDebugLog.shared.append(
+                    "tailscale.connection.ready path=\(Self.pathSummary(connection.currentPath)) revision=\(tailscalePathRevision)"
+                )
+            }
             do {
                 try await validateTailscaleAuthorizationForCurrentPath()
             } catch {
+                MobileDebugLog.shared.append(
+                    "tailscale.connection.ready_validation_failed error=\(String(describing: error)) path=\(Self.pathSummary(connection.currentPath)) revision=\(tailscalePathRevision)"
+                )
                 failTransport(.tailscaleAuthorizationUnavailable)
                 return
             }
@@ -679,9 +688,18 @@ public actor CmxNetworkByteTransport: CmxByteTransport {
     private func handleTailscalePathUpdate(_ path: NWPath) async {
         guard tailscaleBinding != nil, !isTerminal else { return }
         tailscalePathRevision = tailscalePathRevision == .max ? 1 : tailscalePathRevision + 1
+        MobileDebugLog.shared.append(
+            "tailscale.connection.path_update revision=\(tailscalePathRevision) path=\(Self.pathSummary(path))"
+        )
         do {
-            try await validateTailscaleAuthorization(path: path)
+            // This callback can fire before the connection binds its local
+            // endpoint, so only route-level facts exist here; the endpoint
+            // facts are asserted at ready and at every write boundary.
+            try await validateTailscaleAuthorization(path: path, phase: .pathUpdate)
         } catch {
+            MobileDebugLog.shared.append(
+                "tailscale.connection.path_validation_failed error=\(String(describing: error)) revision=\(tailscalePathRevision) path=\(Self.pathSummary(path))"
+            )
             tailscaleAuthorizationInvalidated = true
             failTransport(.tailscaleAuthorizationUnavailable)
         }
@@ -693,31 +711,54 @@ public actor CmxNetworkByteTransport: CmxByteTransport {
             throw CmxNetworkByteTransportError.tailscaleAuthorizationUnavailable
         }
         let revision = tailscalePathRevision
-        try await validateTailscaleAuthorization(path: path)
+        try await validateTailscaleAuthorization(path: path, phase: .established)
         // The authority call yields this actor. Reject any connection-path
         // update that interleaved before the synchronous send boundary.
         guard revision == tailscalePathRevision else {
             throw CmxNetworkByteTransportError.tailscaleAuthorizationUnavailable
         }
     }
 
-    private func validateTailscaleAuthorization(path: NWPath) async throws {
+    private func validateTailscaleAuthorization(
+        path: NWPath,
+        phase: CmxTailscaleRouteValidationPhase
+    ) async throws {
         guard let binding = tailscaleBinding else { return }
+        MobileDebugLog.shared.append(
+            "tailscale.authorization.validate_begin phase=\(phase) path=\(Self.pathSummary(path)) revision=\(tailscalePathRevision)"
+        )
         guard !tailscaleAuthorizationInvalidated,
               binding.request == binding.preparedRoute.proof.request,
               connection.parameters.requiredInterface == binding.preparedRoute.requiredInterface else {
+            MobileDebugLog.shared.append(
+                "tailscale.authorization.validate_precondition_failed invalidated=\(tailscaleAuthorizationInvalidated) request_matches=\(binding.request == binding.preparedRoute.proof.request) interface_matches=\(connection.parameters.requiredInterface == binding.preparedRoute.requiredInterface)"
+            )
             throw CmxNetworkByteTransportError.tailscaleAuthorizationUnavailable
         }
         do {
             try await binding.authority.validate(
                 proof: binding.preparedRoute.proof,
-                connectionPath: path
+                connectionPath: path,
+                phase: phase
             )
+            MobileDebugLog.shared.append("tailscale.authorization.validate_success phase=\(phase)")
         } catch {
+            MobileDebugLog.shared.append(
+                "tailscale.authorization.validate_failed underlying=\(String(describing: error)) phase=\(phase) path=\(Self.pathSummary(path))"
+            )
             throw CmxNetworkByteTransportError.tailscaleAuthorizationUnavailable
         }
     }
 
+    private static func pathSummary(_ path: NWPath?) -> String {
+        guard let path else { return "nil" }
+        let interfaces = path.availableInterfaces
+            .map { "\($0.name):\($0.index)" }
+            .sorted()
+            .joined(separator: ",")
+        return "status=\(path.status) interfaces=\(interfaces) local=\(path.localEndpoint != nil) remote=\(path.remoteEndpoint != nil)"
+    }
+
     /// The single legacy bearer-write boundary. Authorization completes before
     /// Network.framework receives the send request.
     func performAuthorizedWrite(

Packages/iOS/CmuxMobileTransport/Sources/CmuxMobileTransport/CmxPreparingTailscaleByteTransport.swift

@@ -1,9 +1,21 @@
 internal import CMUXMobileCore
 import Foundation
+import os
+import CmuxMobileDiagnostics
+
+nonisolated private let tailscalePreparationLog = Logger(
+    subsystem: "com.manaflow.cmux",
+    category: "TailscalePreparation"
+)
 
 /// Defers the actor-isolated route proof until `connect()` while preserving the
 /// synchronous transport-factory contract. The proven interface is set on
 /// `NWParameters` before Network.framework starts the connection.
+///
+/// Waiting for tunnel readiness (including the retry-on-path-update loop and
+/// its deadline) is owned entirely by the route authority; this transport
+/// makes exactly one `prepare` call and maps its failure to the transport
+/// error the pairing classifier turns into actionable Tailscale guidance.
 actor CmxPreparingTailscaleByteTransport: CmxByteTransport {
     private let request: CmxByteTransportRequest
     private let tailscaleRouteAuthority: any CmxTailscaleRouteAuthorizing
@@ -26,8 +38,17 @@ actor CmxPreparingTailscaleByteTransport: CmxByteTransport {
     }
 
     func connect() async throws {
+        MobileDebugLog.shared.append("tailscale.transport.connect.begin")
         let transport = try await preparedTransport()
-        try await transport.connect()
+        do {
+            try await transport.connect()
+            MobileDebugLog.shared.append("tailscale.transport.connect.success")
+        } catch {
+            MobileDebugLog.shared.append(
+                "tailscale.transport.connect.failed error=\(String(describing: error))"
+            )
+            throw error
+        }
     }
 
     func receive() async throws -> Data? {
@@ -87,6 +108,12 @@ actor CmxPreparingTailscaleByteTransport: CmxByteTransport {
                 } catch is CancellationError {
                     throw CancellationError()
                 } catch {
+                    MobileDebugLog.shared.append(
+                        "tailscale.prepare.failed error=\(String(describing: error))"
+                    )
+                    tailscalePreparationLog.error(
+                        "Tailscale preparation failed: \(String(describing: error), privacy: .public)"
+                    )
                     throw CmxNetworkByteTransportError.tailscaleAuthorizationUnavailable
                 }
             }