Add first-install iCloud pairing prompt with main-device auto-surface

When a fresh install finds another device's identity in the iCloud-synced
keychain backup, prompt "Pair <device>?" and run the standard joiner
pairing handshake against it - the found inbox id becomes this device's
identity. The invite is minted locally, signed by the backed-up key, so
the joiner's slug and identity-share verification hold unchanged and no
QR is scanned.

The main device now auto-surfaces incoming requests: StreamProcessor
verifies the join request's slug against its own identity key (only a
device sharing the iCloud keychain can mint one) and presents the
initiator PIN sheet directly when foregrounded, or posts a local
"<device> is requesting to pair" notification otherwise.

Includes QA test 42 (two-simulator clone seeding via the
CONVOS_QA_WIPE_PRIMARY_IDENTITY launch hook), accessibility ids and QA
events for automation, and unit tests for invite signing, backup
filtering, and the coordinator's respond entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: yewreeka

Convos/Config/QALaunchHooks.swift

@@ -0,0 +1,37 @@
+import ConvosCore
+import Foundation
+import Security
+
+/// Launch-time hooks for QA automation. Every hook is double-gated: it
+/// only runs in non-production environments and only when its environment
+/// variable is set (pass to a simulator app by exporting the
+/// SIMCTL_CHILD_-prefixed name before `xcrun simctl launch`).
+enum QALaunchHooks {
+    static func run(environment: AppEnvironment) {
+        guard !environment.isProduction else { return }
+        wipePrimaryIdentityIfRequested(environment: environment)
+    }
+
+    /// CONVOS_QA_WIPE_PRIMARY_IDENTITY=1 deletes the device-local identity
+    /// slot while leaving the iCloud-synced backup slot intact. iCloud
+    /// Keychain doesn't sync between simulators, so two-simulator QA seeds
+    /// the "brand-new device on the same iCloud account" state by cloning
+    /// the onboarded simulator (clones copy the whole keychain) and wiping
+    /// the cloned primary slot with this hook on first launch. The app then
+    /// registers a fresh placeholder identity and finds the original
+    /// device's synced backup, which drives the first-install
+    /// "Pair <device>?" prompt. See qa/tests/43-icloud-pairing-prompt.md.
+    private static func wipePrimaryIdentityIfRequested(environment: AppEnvironment) {
+        guard ProcessInfo.processInfo.environment["CONVOS_QA_WIPE_PRIMARY_IDENTITY"] == "1" else { return }
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: KeychainIdentityStore.defaultService,
+            kSecAttrAccount as String: KeychainIdentityStore.identityAccount,
+            kSecAttrAccessGroup as String: environment.keychainAccessGroup,
+            kSecAttrSynchronizable as String: false
+        ]
+        let status = SecItemDelete(query as CFDictionary)
+        Log.info("QALaunchHooks: wiped primary identity slot (status=\(status))")
+        QAEvent.emit(.app, "qa_wiped_primary_identity", ["status": "\(status)"])
+    }
+}

Convos/Conversations List/ConversationsView.swift

@@ -406,6 +406,20 @@ private struct ConversationsSheetModifier: ViewModifier {
                         .padding(.top, DesignConstants.Spacing.step5x)
                 }
             )
+            .selfSizingSheet(
+                item: $viewModel.foundDevicePairingPrompt,
+                onDismiss: {
+                    viewModel.onFoundDevicePromptDismissed()
+                },
+                content: { prompt in
+                    PairFoundDeviceInfoSheet(
+                        deviceName: prompt.deviceName,
+                        onPair: { viewModel.pairWithFoundDevice() },
+                        onSkip: { viewModel.skipFoundDevicePairing() }
+                    )
+                    .padding(.top, DesignConstants.Spacing.step5x)
+                }
+            )
             .selfSizingSheet(isPresented: $viewModel.presentingExplodeInfo) {
                 ExplodeInfoView()
             }

Convos/Conversations List/ConversationsViewModel.swift

@@ -54,6 +54,7 @@ struct ConvosApp: App {
         let appBuild = Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "unknown"
         Log.info("Launch: version=\(appVersion) build=\(appBuild) commit=\(Secrets.GIT_COMMIT_SHA) environment=\(environment.name)")
         QAEvent.emit(.app, "launched", ["environment": environment.name])
+        QALaunchHooks.run(environment: environment)
 
         // Firebase must be configured before ConvosClient is created so AppCheck is ready when auth begins
         switch environment {

Convos/ConvosApp.swift

@@ -102,8 +102,10 @@ struct JoinerPairingSheetView: View {
     }
 
     private var connectingContent: some View {
-        VStack(spacing: DesignConstants.Spacing.step4x) {
-            Text("\"\(viewModel.initiatorDeviceName)\" is requesting to pair. Paired devices sync all conversations.")
+        let message: String = viewModel.connectingMessage
+            ?? "\"\(viewModel.initiatorDeviceName)\" is requesting to pair. Paired devices sync all conversations."
+        return VStack(spacing: DesignConstants.Spacing.step4x) {
+            Text(message)
                 .font(.subheadline)
                 .foregroundStyle(.colorTextPrimary)
                 .frame(maxWidth: .infinity, alignment: .leading)

Convos/Devices/JoinerPairingSheetView.swift

@@ -30,7 +30,20 @@ final class JoinerPairingSheetViewModel: Identifiable {
     private let timeoutInterval: TimeInterval
     private let pairingService: any PairingServiceProtocol
     private let initiatorName: String?
+    /// Copy shown while `.connecting`; nil falls back to the default
+    /// "<device> is requesting to pair" text. The iCloud-discovery entry
+    /// point overrides it with instructions to open the pairing screen on
+    /// the other device.
+    let connectingMessage: String?
+    /// When set, the join request is re-sent on this cadence while the
+    /// flow stays in `.connecting`. The QR flow never needs this - the
+    /// initiator is already streaming when its QR is scanned - but the
+    /// iCloud-discovery flow sends the first request before the user has
+    /// opened the pairing screen on the other device, and the initiator
+    /// only sees requests that arrive while it streams.
+    private let resendJoinRequestInterval: TimeInterval?
     private var countdownTask: Task<Void, Never>?
+    private var resendTask: Task<Void, Never>?
     @ObservationIgnored
     private let observers: PairingNotificationObservers
     private var initiatorInboxId: String?
@@ -52,6 +65,8 @@ final class JoinerPairingSheetViewModel: Identifiable {
         expiresAt: Date? = nil,
         initiatorName: String? = nil,
         timeoutInterval: TimeInterval = 60,
+        connectingMessage: String? = nil,
+        resendJoinRequestInterval: TimeInterval? = nil,
         pairingService: any PairingServiceProtocol,
         onPairingAdopted: (@MainActor () async -> Void)? = nil,
         onApplyAdoptedProfile: (@MainActor (_ displayName: String?, _ imageAssetIdentifier: String?) async -> Void)? = nil,
@@ -62,6 +77,8 @@ final class JoinerPairingSheetViewModel: Identifiable {
         self.pairingId = pairingId
         self.timeoutInterval = timeoutInterval
         self.initiatorName = initiatorName
+        self.connectingMessage = connectingMessage
+        self.resendJoinRequestInterval = resendJoinRequestInterval
         self.pairingService = pairingService
         self.onPairingAdopted = onPairingAdopted
         self.onApplyAdoptedProfile = onApplyAdoptedProfile
@@ -140,11 +157,38 @@ final class JoinerPairingSheetViewModel: Identifiable {
                 slug: pairingId,
                 deviceName: DeviceInfo.deviceName
             )
+            startResendLoopIfNeeded()
         } catch {
             flowState = .failed(error.localizedDescription)
         }
     }
 
+    /// Re-sends the join request on a fixed cadence while the flow stays
+    /// in `.connecting`. Duplicate requests are harmless on the initiator:
+    /// before its pairing screen opens nothing is listening, and once a
+    /// handshake is underway `PairingCoordinator.receivedJoinRequest`
+    /// ignores repeats. Send failures are logged and retried - the loop
+    /// only stops when the flow leaves `.connecting`.
+    private func startResendLoopIfNeeded() {
+        guard let interval = resendJoinRequestInterval else { return }
+        resendTask?.cancel()
+        resendTask = Task { [weak self] in
+            while !Task.isCancelled {
+                try? await Task.sleep(for: .seconds(interval))
+                guard !Task.isCancelled, let self else { return }
+                guard self.flowState == .connecting else { return }
+                do {
+                    try await self.pairingService.sendPairingJoinRequest(
+                        slug: self.pairingId,
+                        deviceName: DeviceInfo.deviceName
+                    )
+                } catch {
+                    Log.warning("Pairing: join request resend failed: \(error)")
+                }
+            }
+        }
+    }
+
     func confirmDeleteAndPair() async {
         guard let onDeleteExistingData else {
             flowState = .failed("This device can't be reset from here.")
@@ -209,6 +253,7 @@ final class JoinerPairingSheetViewModel: Identifiable {
     }
 
     private func onPinReceived(_ pin: String, from senderInboxId: String) {
+        resendTask?.cancel()
         initiatorInboxId = senderInboxId
         // Rebase the countdown when the PIN arrives. The initial window
         // is the slug's expiresAt — by the time the PIN lands the user
@@ -226,6 +271,7 @@ final class JoinerPairingSheetViewModel: Identifiable {
         guard !didComplete else { return }
         didComplete = true
         countdownTask?.cancel()
+        resendTask?.cancel()
         title = "Adopting identity"
         flowState = .syncing
         canDismiss = false
@@ -242,12 +288,14 @@ final class JoinerPairingSheetViewModel: Identifiable {
     }
 
     func onPairingFailed(_ message: String) {
+        resendTask?.cancel()
         flowState = .failed(message)
         canDismiss = true
     }
 
     func cancel() {
         countdownTask?.cancel()
+        resendTask?.cancel()
         Task {
             await pairingService.stop()
         }

Convos/Devices/JoinerPairingSheetViewModel.swift

@@ -0,0 +1,76 @@
+import SwiftUI
+
+// First-install pairing prompt. When a fresh install finds another
+// device's identity in the iCloud-synced keychain backup slot,
+// ConversationsViewModel surfaces this sheet offering to pair with that
+// device instead of continuing with the placeholder account. "Pair" runs
+// the standard joiner pairing flow targeting the found device as the main
+// device; "Skip" declines persistently.
+
+/// Drives presentation of `PairFoundDeviceInfoSheet`: one backed-up
+/// device identity discovered in iCloud, identified by the inboxId this
+/// install would adopt on pair.
+struct FoundDevicePairingPrompt: Identifiable, Equatable {
+    let inboxId: String
+    let deviceName: String?
+
+    var id: String { inboxId }
+}
+
+struct PairFoundDeviceInfoSheet: View {
+    let deviceName: String?
+    let onPair: () -> Void
+    let onSkip: () -> Void
+
+    private var title: String {
+        guard let deviceName else { return "Pair your other device?" }
+        return "Pair \(deviceName)?"
+    }
+
+    private var subtitle: String {
+        guard let deviceName else {
+            return "Another device was found in iCloud, if you have it nearby, you can pair it now"
+        }
+        return "Your \(deviceName) was found in iCloud, if you have it nearby, you can pair it now"
+    }
+
+    private var primaryButtonTitle: String {
+        guard let deviceName else { return "Pair device" }
+        return "Pair \(deviceName)"
+    }
+
+    var body: some View {
+        // No container-level accessibilityIdentifier: applied to the sheet
+        // as a whole it propagates to every child element and clobbers the
+        // two button identifiers below. Automation anchors on
+        // pair-found-device-button instead.
+        FeatureInfoSheet(
+            title: title,
+            subtitle: subtitle,
+            primaryButtonTitle: primaryButtonTitle,
+            primaryButtonAction: onPair,
+            primaryButtonAccessibilityIdentifier: "pair-found-device-button",
+            secondaryButtonTitle: "Skip",
+            secondaryButtonAction: onSkip,
+            secondaryButtonAccessibilityIdentifier: "skip-found-device-pairing-button"
+        )
+    }
+}
+
+#Preview("Named device") {
+    @Previewable @State var isPresented: Bool = true
+    VStack { Button { isPresented.toggle() } label: { Text("Show") } }
+        .selfSizingSheet(isPresented: $isPresented) {
+            PairFoundDeviceInfoSheet(deviceName: "Jarod's iPhone", onPair: {}, onSkip: {})
+                .padding(.top, 20)
+        }
+}
+
+#Preview("Unnamed device") {
+    @Previewable @State var isPresented: Bool = true
+    VStack { Button { isPresented.toggle() } label: { Text("Show") } }
+        .selfSizingSheet(isPresented: $isPresented) {
+            PairFoundDeviceInfoSheet(deviceName: nil, onPair: {}, onSkip: {})
+                .padding(.top, 20)
+        }
+}

Convos/Devices/PairFoundDeviceInfoSheet.swift

@@ -12,9 +12,27 @@ enum PairingFlowState: Equatable {
     case expired
 }
 
+/// How the initiator pairing sheet was entered.
+enum PairingSheetMode: Equatable {
+    /// Settings > Devices > Add new device: create an invite and show
+    /// the QR for a joiner to scan.
+    case createInvite
+    /// A verified join request already arrived via the main message
+    /// stream (iCloud-discovery joiner); respond with a PIN immediately,
+    /// no QR step.
+    case respondToJoinRequest(joinerInboxId: String, deviceName: String)
+}
+
 @Observable
 @MainActor
-final class PairingSheetViewModel {
+final class PairingSheetViewModel: Identifiable {
+    /// The initiator sheet currently mid-flow, if any. Weak so dismissal
+    /// (either host nils its reference) clears it automatically. The
+    /// auto-surface path checks this to avoid presenting a second
+    /// initiator flow - two coordinators would race PIN generation for
+    /// the same joiner and the handshake would fail on a stale PIN.
+    private(set) static weak var active: PairingSheetViewModel?
+
     var flowState: PairingFlowState = .qrCode(url: "")
     var canDismiss: Bool = true
     var title: String = "Pair new device"
@@ -23,6 +41,7 @@ final class PairingSheetViewModel {
     private let pairingService: any PairingServiceProtocol
     private let appGroupIdentifier: String?
     private let timeoutInterval: TimeInterval
+    private let mode: PairingSheetMode
     private(set) var coordinator: PairingCoordinator?
     private var joinerDeviceName: String = "New Device"
     private var joinerInboxId: String?
@@ -34,11 +53,13 @@ final class PairingSheetViewModel {
     init(
         pairingService: any PairingServiceProtocol,
         timeoutInterval: TimeInterval = 120,
+        mode: PairingSheetMode = .createInvite,
         appGroupIdentifier: String? = nil
     ) {
         self.pairingService = pairingService
         self.appGroupIdentifier = appGroupIdentifier
         self.timeoutInterval = timeoutInterval
+        self.mode = mode
         self.secondsRemaining = Int(timeoutInterval)
         self.observers = PairingNotificationObservers()
         observeNotifications()
@@ -75,6 +96,16 @@ final class PairingSheetViewModel {
     }
 
     func startPairing() async {
+        Self.active = self
+        switch mode {
+        case .createInvite:
+            await startInviteFlow()
+        case let .respondToJoinRequest(joinerInboxId, deviceName):
+            await startRespondFlow(joinerInboxId: joinerInboxId, deviceName: deviceName)
+        }
+    }
+
+    private func startInviteFlow() async {
         let coordinator = PairingCoordinator(pairingService: pairingService, timeoutInterval: timeoutInterval)
         self.coordinator = coordinator
 
@@ -99,6 +130,47 @@ final class PairingSheetViewModel {
             startCountdown()
         } catch {
             Log.error("Pairing start failed: \(error)")
+            // The service may have started before the failing call; stop
+            // it so its stream doesn't outlive the failed flow (mirrors
+            // confirmEmoji's failure handling).
+            await pairingService.stop()
+            flowState = .failed(error.localizedDescription)
+        }
+    }
+
+    /// Mirrors the back half of `onJoinRequestReceived`: the join request
+    /// already arrived (verified by the stream layer), so the coordinator
+    /// starts directly in `.showingPin` and the PIN goes straight to the
+    /// joiner.
+    private func startRespondFlow(joinerInboxId: String, deviceName: String) async {
+        let coordinator = PairingCoordinator(pairingService: pairingService, timeoutInterval: timeoutInterval)
+        self.coordinator = coordinator
+
+        do {
+            try await pairingService.start()
+            guard let initiatorInboxId = await pairingService.pairingInboxId() else {
+                await pairingService.stop()
+                flowState = .failed("Pairing service is not ready")
+                return
+            }
+            let pin = try await coordinator.startPairing(
+                respondingToJoinerInboxId: joinerInboxId,
+                deviceName: deviceName,
+                initiatorInboxId: initiatorInboxId
+            )
+            joinerDeviceName = deviceName
+            self.joinerInboxId = joinerInboxId
+            expiresAt = Date().addingTimeInterval(timeoutInterval)
+            secondsRemaining = Int(timeoutInterval)
+            try await pairingService.sendPinToJoiner(pin, joinerInboxId: joinerInboxId)
+            QAEvent.emit(.pairing, "responding_to_join_request", ["joinerInboxId": joinerInboxId])
+            flowState = .showingPin(pin: pin, deviceName: deviceName)
+            startCountdown()
+        } catch {
+            Log.error("Pairing respond flow failed: \(error)")
+            // Mirrors confirmEmoji's failure handling: the service was
+            // started above, so stop its stream before parking in .failed.
+            await pairingService.stop()
             flowState = .failed(error.localizedDescription)
         }
     }