Fix pending invite stuck after navigation (#514)

## Problem

When a joiner scans an invite and navigates away before the inviter approves, the conversation permanently stays as a "pending invite" and never transitions to an active conversation. This was reported by Andy Yang — stuck for 45+ minutes on "Balloon Animals".

## Root Cause

Three gaps in the sync/stream lifecycle:

1. **No post-sync group discovery** — after syncing, the app never checked for XMTP groups that were added while streams were stopped
2. **Resume didn't re-sync** — `handleResume()` only restarted streams without re-syncing, missing groups added during pause
3. **ValueObservation cancelled on navigation** — the DB observation watching for the draft→active transition was tied to the conversation view's lifecycle

## Fix

### 1. Post-sync group discovery (`SyncingManager`)
New `discoverNewConversations()` method lists all XMTP groups after every sync and processes any missing from the local DB. Acts as a safety net for missed stream events.

### 2. Re-sync on resume (`SyncingManager`)
`handleResume()` now calls `syncAllConversations` + `discoverNewConversations` + `processJoinRequestsAfterSync` instead of only restarting streams.

### 3. Restart observation on navigation (`ConversationStateMachine`)
`handleUseExisting()` checks if the conversation is still a draft with an inviteTag and restarts `waitForJoinedConversation` observation in the background.

### 4. Accessibility fix
Added `accessibilityIdentifier("close-new-conversation")` to the close button on `NewConversationView`.

## Testing

- 59 unit tests pass
- QA test 24 (pending invite recovery) passed end-to-end:
  - Joiner scans invite → navigates away → inviter approves via CLI → conversation automatically transitions to active → messaging works

## Files Changed

- `ConvosCore/Sources/ConvosCore/Syncing/SyncingManager.swift` — post-sync discovery + resume re-sync
- `ConvosCore/Sources/ConvosCore/Inboxes/ConversationStateMachine.swift` — restart pending invite observation
- `Convos/Conversation Creation/NewConversationView.swift` — close button accessibility ID
- `docs/plans/fix-pending-invite-stuck.md` — plan doc
- `qa/tests/24-pending-invite-recovery.md` — QA test

<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible markers, and the markers themselves will not be visible in the GitHub rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's description, Macroscope will append its summary at the bottom of the description. -->
> [!NOTE]
> ### Recover pending invites after navigation by observing draft `inviteTag` in `ConversationStateMachine.handleUseExisting` and backfilling missed conversations in `SyncingManager`
> Add background observation for draft invites in `ConversationStateMachine` to transition to the joined conversation, and backfill missed conversations on sync and resume in `SyncingManager`; also add a close button accessibility identifier in the new conversation view. Key entry points: [`ConvosCore/Sources/ConvosCore/Inboxes/ConversationStateMachine.swift`](https://github.com/xmtplabs/convos-ios/pull/514/files#diff-a1762ce564035d6cdd7e3b2d3200cfe0db6c3ec5fac03636392780086ba58344), [`ConvosCore/Sources/ConvosCore/Syncing/SyncingManager.swift`](https://github.com/xmtplabs/convos-ios/pull/514/files#diff-ba2362cf646b78283a1af17654ea8d2c18f6b1cb686a78e7761e10f1b0328101), [`Convos/Conversation Creation/NewConversationView.swift`](https://github.com/xmtplabs/convos-ios/pull/514/files#diff-be8eeec29bfb3f245f16cd6258d1ef28ced1aa75bad52187e34243f915b084f6).
>
> #### 📍Where to Start
> Start with `ConversationStateMachine.handleUseExisting` and the new helpers in [ConversationStateMachine.swift](https://github.com/xmtplabs/convos-ios/pull/514/files#diff-a1762ce564035d6cdd7e3b2d3200cfe0db6c3ec5fac03636392780086ba58344), then review `SyncingManager.handleSyncComplete` and `handleResume` plus `discoverNewConversations` in [SyncingManager.swift](https://github.com/xmtplabs/convos-ios/pull/514/files#diff-ba2362cf646b78283a1af17654ea8d2c18f6b1cb686a78e7761e10f1b0328101).
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized e6abb51.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- macroscope-ui-refresh -->
<!-- Macroscope's pull request summary ends here -->

Author: yewreeka

Convos/Conversation Creation/NewConversationView.swift

@@ -53,6 +53,7 @@ struct NewConversationView: View {
                             Button(role: .close) {
                                 dismiss()
                             }
+                            .accessibilityIdentifier("close-new-conversation")
                         }
                     }
                 }

ConvosCore/Sources/ConvosCore/Inboxes/ConversationStateMachine.swift

@@ -447,6 +447,62 @@ public actor ConversationStateMachine {
             conversationId: conversationId,
             origin: .existing
         )))
+
+        if DBConversation.isDraft(id: conversationId) {
+            startPendingInviteObservationIfNeeded(draftConversationId: conversationId)
+        }
+    }
+
+    /// For draft conversations with an inviteTag, starts a background observation
+    /// that watches for the matching non-draft conversation to appear in the DB.
+    /// When it appears (written by SyncingManager's discoverNewConversations or
+    /// the conversation stream), this transitions the state to the real conversation.
+    private func startPendingInviteObservationIfNeeded(draftConversationId: String) {
+        let inviteTag: String? = try? databaseReader.read { db in
+            try DBConversation
+                .filter(DBConversation.Columns.id == draftConversationId)
+                .select(DBConversation.Columns.inviteTag)
+                .fetchOne(db)
+        }
+
+        guard let inviteTag, !inviteTag.isEmpty else { return }
+
+        Log.info("Starting pending invite observation for draft \(draftConversationId) with inviteTag")
+
+        observationTask?.cancel()
+        let task = waitForJoinedConversation(inviteTag: inviteTag)
+        observationTask = task
+
+        Task { [weak self] in
+            guard let self else { return }
+            do {
+                let conversationId = try await task.value
+                await self.handlePendingInviteResolved(
+                    conversationId: conversationId,
+                    draftConversationId: draftConversationId
+                )
+            } catch is CancellationError {
+                // expected when navigating away or stopping
+            } catch {
+                Log.error("Pending invite observation failed: \(error)")
+            }
+        }
+    }
+
+    private func handlePendingInviteResolved(conversationId: String, draftConversationId: String) {
+        observationTask = nil
+        guard case .ready(let result) = _state,
+              result.conversationId == draftConversationId else {
+            Log.debug("State no longer matches draft \(draftConversationId), skipping")
+            return
+        }
+        Log.info("Pending invite resolved to conversation: \(conversationId)")
+        cachedMessageWriter = nil
+        QAEvent.emit(.conversation, "joined", ["id": conversationId])
+        emitStateChange(.ready(ConversationReadyResult(
+            conversationId: conversationId,
+            origin: .joined
+        )))
     }
 
     private func handleValidate(inviteCode: String, previousResult: ConversationReadyResult?) async throws {
@@ -680,10 +736,12 @@ public actor ConversationStateMachine {
             throw ConversationStateMachineError.timedOut
         }
     }
+}
 
+// MARK: - Cleanup
+
+extension ConversationStateMachine {
     private func handleDelete() async throws {
-        // For invites, we need the external conversation ID if available,
-        // capture before changing state
         let conversationId: String? = switch _state {
         case .ready(let result):
             result.conversationId
@@ -693,18 +751,14 @@ public actor ConversationStateMachine {
 
         emitStateChange(.deleting)
 
-        // Unregister error handler if we were in joining state
         await clearInviteJoinErrorHandler()
 
-        // Cancel observation tasks and stop accepting new messages
-        // Note: currentTask is already cancelled by delete() - don't cancel ourselves!
         messageStreamContinuation?.finish()
         messageProcessingTask?.cancel()
         observationTask?.cancel()
         observationTask = nil
 
         if let conversationId {
-            // Get the inbox state to access the API client for unsubscribing
             let inboxReady = try await inboxStateManager.waitForInboxReadyResult()
 
             try await cleanUp(
@@ -747,9 +801,6 @@ public actor ConversationStateMachine {
         client: any XMTPClientProvider,
         apiClient: any ConvosAPIClientProtocol
     ) async throws {
-        // nonisolated(unsafe) is used because XMTP types are not Sendable. This is safe
-        // here because findConversation() is a one-shot operation, not a long-running
-        // stream that could overlap with other XMTP operations.
         nonisolated(unsafe) let conversationsProvider = client.conversationsProvider
         let externalConversation = try await conversationsProvider.findConversation(conversationId: conversationId)
         try await externalConversation?.updateConsentState(state: .denied)

ConvosCore/Sources/ConvosCore/Syncing/SyncingManager.swift

@@ -129,12 +129,15 @@ actor SyncingManager: SyncingManagerProtocol {
 
     // MARK: - Initialization
 
+    private let databaseReader: any DatabaseReader
+
     init(identityStore: any KeychainIdentityStoreProtocol,
          databaseWriter: any DatabaseWriter,
          databaseReader: any DatabaseReader,
          deviceRegistrationManager: (any DeviceRegistrationManagerProtocol)? = nil,
          notificationCenter: any UserNotificationCenterProtocol) {
         self.identityStore = identityStore
+        self.databaseReader = databaseReader
         self.streamProcessor = StreamProcessor(
             identityStore: identityStore,
             databaseWriter: databaseWriter,
@@ -389,6 +392,11 @@ actor SyncingManager: SyncingManagerProtocol {
             Log.info("syncAllConversations completed, sync ready")
             QAEvent.emit(.sync, "completed")
 
+            // Discover any XMTP groups that the conversation stream missed.
+            // This handles cases where the joiner was added to a group while
+            // the inbox was paused, stopped, or the stream had a timeout.
+            await discoverNewConversations(params: params)
+
             // Process any join requests that may have been missed during stream startup.
             // This handles the race condition where a joiner sends a DM before the message
             // stream has fully subscribed to the XMTP network.
@@ -403,6 +411,50 @@ actor SyncingManager: SyncingManagerProtocol {
         }
     }
 
+    /// Lists all XMTP groups and processes any that are missing from the local database.
+    ///
+    /// After syncAllConversations syncs the XMTP data layer, the local DB may still be
+    /// missing groups that the conversation stream failed to deliver (e.g., stream timeout,
+    /// inbox paused during approval, app backgrounded). This method provides a fallback
+    /// by listing all groups and storing any that aren't already in the DB.
+    private func discoverNewConversations(params: SyncClientParams) async {
+        do {
+            let groups = try params.client.conversationsProvider.listGroups(
+                createdAfterNs: nil,
+                createdBeforeNs: nil,
+                lastActivityAfterNs: nil,
+                lastActivityBeforeNs: nil,
+                limit: nil,
+                consentStates: params.consentStates,
+                orderBy: .lastActivity
+            )
+
+            let existingIds: Set<String> = try await databaseReader.read { db in
+                let ids = try String.fetchAll(
+                    db,
+                    DBConversation.select(DBConversation.Columns.id)
+                )
+                return Set(ids)
+            }
+
+            var discoveredCount: Int = 0
+            for group in groups where !existingIds.contains(group.id) {
+                do {
+                    try await streamProcessor.processConversation(group, params: params)
+                    discoveredCount += 1
+                } catch {
+                    Log.error("Failed to process discovered conversation \(group.id): \(error)")
+                }
+            }
+
+            if discoveredCount > 0 {
+                Log.info("Discovered \(discoveredCount) new conversations after sync")
+            }
+        } catch {
+            Log.error("Failed to discover new conversations: \(error)")
+        }
+    }
+
     /// Waits for both message and conversation streams to signal they're ready.
     /// Sets up stream readiness tracking by creating continuations that stream tasks will signal.
     /// Must be called BEFORE creating stream tasks to avoid race conditions.
@@ -539,8 +591,23 @@ actor SyncingManager: SyncingManagerProtocol {
         Log.debug("Waiting for streams to subscribe after resume...")
         await waitForStreamsToBeReady(messageStream: streams.messageStream, conversationStream: streams.conversationStream)
 
+        // Re-sync to pick up any changes that occurred while paused/backgrounded.
+        // The conversation stream only delivers new groups created after subscription,
+        // so groups added while paused would be missed without this.
+        do {
+            let syncStart = CFAbsoluteTimeGetCurrent()
+            _ = try await params.client.conversationsProvider.syncAllConversations(consentStates: params.consentStates)
+            let syncElapsed = String(format: "%.0f", (CFAbsoluteTimeGetCurrent() - syncStart) * 1000)
+            Log.info("[PERF] sync.resume_conversations: \(syncElapsed)ms")
+        } catch {
+            Log.error("syncAllConversations on resume failed: \(error)")
+        }
+
         emitStateChange(.ready(params))
         Log.info("Sync resumed")
+
+        await discoverNewConversations(params: params)
+        await processJoinRequestsAfterSync(params: params)
     }
 
     private func handleStop() async throws {

docs/plans/fix-pending-invite-stuck.md

@@ -0,0 +1,90 @@
+# Fix: Pending Invite Stuck After Navigation
+
+## Problem
+
+When a joiner scans an invite QR code and the inviter approves (adds them to the XMTP group), the joiner's device can get permanently stuck showing the conversation as "pending invite."
+
+**User report:** Andy scanned an invite for "Balloon Animals." The inviter confirmed Andy was added. Andy's device showed the conversation stuck as pending for 45+ minutes.
+
+## Root Cause
+
+The joiner's device discovers new XMTP groups through exactly **two** mechanisms:
+1. **Conversation stream** — real-time stream from XMTP SDK
+2. **Message stream** — when a message arrives for a group conversation
+
+`syncAllConversations()` only syncs the XMTP data layer (LibXMTP/Rust). It does **not** list groups and process new ones into the local GRDB database.
+
+There are three gaps that caused the bug:
+
+### Gap 1: No post-sync group discovery
+After `syncAllConversations` syncs from the network, there's no step that lists all XMTP groups and writes missing ones to the local DB. The app relies entirely on the conversation stream for discovery.
+
+### Gap 2: Resume doesn't re-sync
+`SyncingManager.handleResume()` only restarts streams — it doesn't call `syncAllConversations`. If the joiner was added to a group while the inbox was paused/backgrounded, the conversation stream won't emit it (it only streams *newly created* groups, not pre-existing ones).
+
+### Gap 3: ValueObservation cancelled on navigation
+`ConversationStateMachine.waitForJoinedConversation()` sets up a GRDB ValueObservation watching for a non-draft conversation with matching `inviteTag`. When the user navigates away, `handleStop()` cancels this observation. When the user returns to the conversation, it calls `useExisting()` which just sets state to `.ready` — it never restarts the observation.
+
+**In Andy's case:** The inbox was stopped at 19:34:38 (after initial sync completed but before the inviter processed the join request). When it resumed at 19:42:25, only streams were restarted. The group had already been created on the network, so the conversation stream didn't emit it. No fallback mechanism existed to discover it.
+
+## Fixes
+
+### Fix 1: Post-sync group discovery in SyncingManager
+
+After `syncAllConversations` completes, list all XMTP groups and process any that don't exist in the local DB.
+
+**File:** `ConvosCore/Sources/ConvosCore/Syncing/SyncingManager.swift`
+
+In `handleSyncComplete`, after calling `processJoinRequestsAfterSync`:
+
+```
+1. List all XMTP groups via client.conversationsProvider.listGroups(consentStates: params.consentStates)
+2. For each group, check if a DBConversation exists with that group ID
+3. If not, call streamProcessor.processConversation(group, params:) to store it
+```
+
+This is the primary fix — it provides a robust fallback regardless of how the stream missed the event.
+
+### Fix 2: Re-sync on resume
+
+When `handleResume()` is called (foreground, network reconnect), call `syncAllConversations` followed by the group discovery step from Fix 1.
+
+**File:** `ConvosCore/Sources/ConvosCore/Syncing/SyncingManager.swift`
+
+Modify `handleResume()` to:
+1. Restart streams (existing behavior)
+2. Call `syncAllConversations`
+3. Run post-sync group discovery (Fix 1)
+4. Run `processJoinRequestsAfterSync` (existing behavior)
+
+### Fix 3: Restart join observation for pending drafts
+
+When `ConversationStateMachine` receives `useExisting` for a draft conversation that has a pending invite (draft ID + inviteTag), restart the `waitForJoinedConversation` observation instead of immediately transitioning to `.ready`.
+
+**File:** `ConvosCore/Sources/ConvosCore/Inboxes/ConversationStateMachine.swift`
+
+Modify `handleUseExisting(conversationId:)`:
+1. If the conversationId starts with `draft-`, look up the DBConversation
+2. If it has an inviteTag and hasn't joined yet, start `waitForJoinedConversation(inviteTag:)` observation
+3. Emit `.ready` with the draft ID so the UI still renders, but keep the observation running
+4. When the observation fires (non-draft conversation appears), update the state with the real conversation ID
+
+This ensures reopening a pending conversation re-arms the detection mechanism.
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `SyncingManager.swift` | Add `discoverNewConversations(params:)` after sync; call on resume |
+| `ConversationStateMachine.swift` | Restart join observation for draft conversations in `handleUseExisting` |
+| `StreamProcessor.swift` | Possibly extract `shouldProcessConversation` check for reuse |
+
+## Testing
+
+### Unit Tests
+- `SyncingManager`: After sync completes, new groups are processed into DB
+- `ConversationStateMachine`: `useExisting` with a draft ID + inviteTag starts observation
+- `ConversationStateMachine`: Observation fires when matching non-draft conversation appears
+
+### QA Test
+See `qa/tests/XX-pending-invite-recovery.md` — covers the scenario where the joiner navigates away during the pending state and the invite is approved while they're in another conversation.

qa/tests/24-pending-invite-recovery.md

@@ -0,0 +1,58 @@
+# Test: Pending Invite Recovery After Navigation
+
+Verify that when a joiner navigates away from a pending invite conversation, the invite is still detected and the conversation transitions to active after the inviter approves.
+
+## Prerequisites
+
+- The app is running and past onboarding on the simulator (this is the joiner's device).
+- The `convos` CLI is available for creating the inviter identity and processing join requests.
+- Two separate identities are needed: the inviter (CLI) and the joiner (simulator).
+
+## Setup
+
+1. Using the CLI, create a new conversation as the inviter and generate an invite link.
+2. Note the invite URL for the joiner to scan.
+
+## Steps
+
+### Join via invite and navigate away
+
+1. Open the invite URL in the simulator as a deep link.
+2. The app should show the new conversation view with a "Verifying" state or QR code.
+3. Wait a few seconds for the join request DM to be sent (check logs for `join_request_sent` event).
+4. Navigate back to the conversations list (tap back or swipe).
+5. Open a different conversation (or create a new one) so the pending invite's inbox is no longer the active view.
+
+### Approve the invite while joiner is away
+
+6. Using the CLI on the inviter's identity, process pending join requests to approve the joiner.
+7. Verify via CLI that the joiner was added to the conversation (member count should be 2).
+
+### Verify recovery
+
+8. Navigate back to the conversations list.
+9. The previously pending conversation should now appear as a normal (non-pending) conversation with the correct name.
+10. Tap on the conversation to open it.
+11. The conversation should be fully functional — the bottom bar should be enabled, messages should be sendable.
+
+### Verify via background/foreground cycle (additional recovery path)
+
+12. If step 9 still shows pending, background the app and bring it back to foreground.
+13. After foregrounding, the conversation should transition to active within a few seconds.
+
+## Teardown
+
+Explode both conversations (the test conversation and any helper conversation) using the CLI or app UI.
+
+## Pass/Fail Criteria
+
+- [ ] Join request is sent successfully (log event `invite.join_request_sent`)
+- [ ] Navigating away from the pending conversation does not cause errors
+- [ ] After the inviter approves, the joiner's conversation transitions from pending to active
+- [ ] The conversation is fully functional after recovery (messages can be sent)
+- [ ] The transition happens without requiring the user to re-scan the invite code
+- [ ] The recovery works even if the app was backgrounded during approval
+
+## Accessibility Improvements Needed
+
+- None identified yet — this test primarily validates backend sync behavior rather than UI elements.