fix(mobile): Local Network permission sheet leaves pairing stuck

[imMxts]

Fixes #5061

What Changed

waitForEstablishmentInterrupt now returns true for any isApplicationActiveWakeup (application-active, application-active-probe, or application-active-reconnect), so a short resume during connection setup resets the retry ladder the same way a long resume already did. mobileSuspensionStartedAtMs starts that clock on AppState inactive as well as background (??= keeps the earlier stamp; active clears it). The Wakeups paragraph in docs/internals/connection-runtime.md no longer says establishment ignores probe.

Why

First-time iOS LAN pairing: user taps Allow on the Local Network sheet, the environment stays on Failed to connect. Reconnecting… until force-quit. The sheet is active → inactive → active; that resume is an application-active-probe. Establishment consumed the probe and left the doomed attempt on the retry ladder. The mobile adapter never started the suspension clock on inactive, so a permission sheet could not be classified as a real resume.

waitForEstablishmentInterrupt already returned resetRetry for application-active-reconnect. Extending that predicate is the existing seam — same interface, more behaviour. mobileApplicationActiveWakeup still classifies short inactive as probe; web/desktop inherit the supervisor change via isApplicationActiveWakeup. Connected-phase monitorConnectedLease still probes on probe and only replaces the lease on reconnect.

Test

• restarts the retry ladder when a short resume interrupts connection setup timed out at 60000ms on upstream/main (waitForEstablishmentInterrupt swallowed application-active-probe; hanging prepare on attempt 2 never reset). After the fix the same assertion reached phase === "connected" && generation === 2 && attempt === 1.
• starts the clock on inactive so a short permission sheet stays a probe covers the AppState inactive stamp that the supervisor test cannot see.
• vp test run packages/client-runtime/src/connection/supervisor.test.ts apps/mobile/src/connection/app-state-wakeups.test.ts — 36 + 5 passed.
• vp lint on the touched source and test files: 0 errors.
• Did not pair on a device or simulator. Did not run web, desktop, or server suites.

UI Changes

No UI change.

Deliberately not included

• Connected-phase probe stays a probe (supervisor.ts:421-427). monitorConnectedLease still calls lease.session.probe for application-active / application-active-probe and only replaces the lease on application-active-reconnect.
• No new ConnectionWakeup reason (wakeups.ts:5-9). A new reason would widen the interface and collide with fix(mobile): probe on network path changes, restore server leases on reconnect #5154.
• mobileApplicationActiveWakeup duration rule unchanged. Short inactive remains probe; only the stamp helper now treats inactive like background.
• Web visibility adapter (apps/web/src/connection/platform.ts:93-99) still emits plain application-active.
• connectivityLayer AppState network re-read (apps/mobile/src/connection/platform.ts:63-70) — fix(client-runtime): re-read network status when the app resumes #4528 / fix(connection): refresh network status after app activation #5597 resume network refresh.
• fix(mobile): probe on network path changes, restore server leases on reconnect #5154 network-path-changed — not in this tree; hunks kept off that path.
• fix(client-runtime): tolerate transient foreground probe timeouts #5198 / fix(client): a busy backend no longer looks like a disconnect #7233 connected probe timeout tolerance (supervisor.ts:34-35, supervisor.ts:425-427; tests at supervisor.test.ts:1021 and :1044).
• feat(mobile): keep Android connections alive in the background #5179 Android background connection (background-activity.ts:30-34).
• fix(mobile): Catch up the thread feed after a long background #6642 thread-feed resubscribe (threads.ts:548-557). shouldResubscribeAfterWakeup is unchanged.
• Distinguishing Control Center from the Local Network sheet: both are AppState inactive; there is no API to tell them apart.
• contracts.
• UI copy (presentation.ts:68-81).
• Pairing UI (ConnectionsNewRouteScreen.tsx:150-155, onboarding.ts:13-20).

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

Implemented with grok-4.6 in T3 Code.

---

Note

Medium Risk
Changes shared EnvironmentSupervisor establishment interrupts for all platforms; scope is narrow and connected-phase probing is unchanged, but any platform can now restart setup on short foreground wakeups.

Overview
Fixes iOS first-time LAN pairing getting stuck on Reconnecting… after the Local Network permission sheet (active → inactive → active).

Shared supervisor: During connection establishment, waitForEstablishmentInterrupt now interrupts and resets the retry ladder for any application-active wakeup (application-active, application-active-probe, or application-active-reconnect), not only long-background application-active-reconnect. Short resumes during setup therefore abandon a doomed in-flight attempt instead of waiting through backoff. Connected-phase behavior is unchanged (probe vs full reconnect).

Mobile wakeups: New mobileSuspensionStartedAtMs starts the background suspension clock on AppState inactive as well as background (first timestamp is kept through inactive; active clears it). The mobile wakeup layer uses this so a brief permission sheet still classifies as a short application-active-probe with correct timing.

Docs and tests cover the new establishment and AppState behavior.

^{Reviewed by Cursor Bugbot for commit cf7995e. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Fix mobile pairing getting stuck when Local Network permission sheet appears

• Introduces mobileSuspensionStartedAtMs to track suspension start across both inactive and background app states, preserving the earliest timestamp and clearing it on active.
• Updates EnvironmentSupervisor so that any application-active wakeup (application-active, application-active-probe, or application-active-reconnect) interrupts an in-flight connection attempt and resets the retry ladder — previously only application-active-reconnect did this.
• The Local Network permission sheet briefly moves the app to inactive before returning to active; without this fix, that transition was not recognized as a suspension, leaving the pairing flow stuck waiting for a retry.
• Behavioral Change: short inactive blips now emit application-active-probe wakeups and reset the retry ladder, which may cause more reconnect attempts after transient interruptions.

^{Macroscope summarized cf7995e.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b86d2927-accc-4d66-b2d4-04b6fc68430b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Approved cf7995e

This is a straightforward bug fix for mobile pairing getting stuck when iOS permission sheets appear. The changes track 'inactive' app state and reset the connection retry ladder more aggressively during reconnection—a safer fallback behavior. Well-tested with documentation updates.

^{You can customize Macroscope's approvability policy. Learn more.}