From 22d0752329feba84129a15d4a2f18316f391e76d Mon Sep 17 00:00:00 2001
From: Andrew Blakeslee Moore <andrew@blakeslee.me>
Date: Fri, 3 Jul 2026 01:42:40 -0700
Subject: [PATCH 1/5] nvrsion: Add fix for QR Code Scan Failure in AppStore,
 Sync, and Tests; explore connection failures over local network; update
 Info.plist, Models, and SettingsView.

Nucleic-Promote: 1
Co-authored-by: Nucleic <nucleic@blakeslee.xyz>
---
 NucleicRemote/NucleicRemote/Info.plist        |  7 +++++
 .../NucleicRemote/Models/RemoteStore.swift    | 30 ++++++++++++++++++-
 .../NucleicRemote/Views/SettingsView.swift    | 26 ++++++++++++++++
 3 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/NucleicRemote/NucleicRemote/Info.plist b/NucleicRemote/NucleicRemote/Info.plist
index 6b1a38f..15712f4 100644
--- a/NucleicRemote/NucleicRemote/Info.plist
+++ b/NucleicRemote/NucleicRemote/Info.plist
@@ -6,6 +6,13 @@
 	<array>
 		<string>_nucleic._tcp</string>
 	</array>
+	<!-- iOS 14+ gates ALL local-network access — both Bonjour discovery (_nucleic._tcp above)
+	     and a direct NWConnection to the Mac's LAN IP from the pairing QR — behind the
+	     local-network permission, which only prompts if this usage string is present. Without
+	     it the grant never happens and every LAN connection fails silently, so pairing and
+	     reconnect appear to "do nothing." -->
+	<key>NSLocalNetworkUsageDescription</key>
+	<string>Nucleic connects to your Mac on the local network to pair and to sync your sessions and approvals.</string>
 	<key>NucleicChannel</key>
 	<string>$(NUCLEIC_CHANNEL)</string>
 	<!-- The short git commit this build came from, shown in the non-release banner to match
diff --git a/NucleicRemote/NucleicRemote/Models/RemoteStore.swift b/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
index 329099f..0c2a579 100644
--- a/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
+++ b/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
@@ -695,7 +695,35 @@ final class RemoteStore: ObservableObject {
     }
 
     private func makeChannel(_ endpoint: NWEndpoint) -> NWFrameChannel {
-        NWFrameChannel(endpoint: endpoint)
+        let channel = NWFrameChannel(endpoint: endpoint)
+        // Surface a transport-level failure with an actionable message. Without this, a refused
+        // connection or a denied local-network permission finished the frame stream and only
+        // showed up as a generic "handshake closed" — hiding the real (usually fixable) cause.
+        channel.onFailed = { [weak self] error in
+            Task { @MainActor in self?.handleTransportFailure(error) }
+        }
+        return channel
+    }
+
+    /// Map an `NWConnection` failure to a connectivity state the pairing/onboarding UI can act on.
+    /// Only meaningful while we're still establishing the link; once `.connected`, a drop is the
+    /// normal `.closed` → reconnect path's job.
+    private func handleTransportFailure(_ error: String) {
+        guard connectivity != .connected else { return }
+        connectivity = .failed(Self.friendlyTransportError(error))
+    }
+
+    /// Turn a raw `NWError` string into a short, fixable hint. The common onboarding failures are
+    /// a denied Local Network permission (EPERM / -65555) and the Mac not listening (refused).
+    private static func friendlyTransportError(_ error: String) -> String {
+        let lower = error.lowercased()
+        if lower.contains("denied") || lower.contains("not permitted") || lower.contains("65555") {
+            return "Can't reach the local network. In Settings ▸ Nucleic, allow Local Network access, then try again."
+        }
+        if lower.contains("refused") {
+            return "Your Mac refused the connection. Check that remote access is still on in Nucleic ▸ Settings."
+        }
+        return "Couldn't connect to your Mac — make sure it's on the same Wi‑Fi and remote access is on."
     }
 
     private func resolveEndpoint(fingerprint: String?, lanHost: String?, lanPort: UInt16?) -> NWEndpoint? {
diff --git a/NucleicRemote/NucleicRemote/Views/SettingsView.swift b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
index 25c2ddd..e5bf4a2 100644
--- a/NucleicRemote/NucleicRemote/Views/SettingsView.swift
+++ b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
@@ -126,6 +126,10 @@ struct PairingIntroView: View {
             }
             .buttonStyle(.borderedProminent)
 
+            // Feedback after a scan: the whole UI is still the intro until pairing completes, so
+            // without this a failed or in-flight pair looks like "nothing happened."
+            pairingStatus
+
             VStack(spacing: 6) {
                 Button { store.enterDemo() } label: {
                     Label("Explore a demo — no Mac needed", systemImage: "play.circle")
@@ -151,4 +155,26 @@ struct PairingIntroView: View {
             }
         }
     }
+
+    /// A status line reflecting an in-flight or failed pairing attempt. Silent in the resting
+    /// `.unpaired` state (the intro copy already covers that).
+    @ViewBuilder
+    private var pairingStatus: some View {
+        switch store.connectivity {
+        case .connecting, .reconnecting:
+            Label("Connecting to your Mac…", systemImage: "arrow.triangle.2.circlepath")
+                .font(.footnote).foregroundStyle(.secondary)
+        case .hostOffline:
+            Label("Can't reach your Mac. Make sure it's on the same Wi‑Fi and remote access is on.",
+                  systemImage: "wifi.exclamationmark")
+                .font(.footnote).foregroundStyle(.orange)
+                .multilineTextAlignment(.center).padding(.horizontal, 32)
+        case .failed(let message):
+            Label(message, systemImage: "exclamationmark.triangle.fill")
+                .font(.footnote).foregroundStyle(.red)
+                .multilineTextAlignment(.center).padding(.horizontal, 32)
+        case .connected, .unpaired:
+            EmptyView()
+        }
+    }
 }

From 94a962bd2046c45712e259c0bc9617e1f80ca056 Mon Sep 17 00:00:00 2001
From: Andrew Blakeslee Moore <andrew@blakeslee.me>
Date: Fri, 3 Jul 2026 03:50:45 -0700
Subject: [PATCH 2/5] Add Tailscale (Tailnet) as a sync transport between Mac
 and iPhone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Settings ▸ Remote gains a "Connect via" picker — LAN (default), Tailscale
(tailnet), or Relay (disabled, coming soon). On Tailnet, both devices run an
embedded tsnet node via TailscaleKit (tailscale/libtailscale) and sync frames
flow over the user's tailnet, so the phone can connect from anywhere the
tailnet reaches; Noise E2EE runs above the transport unchanged.

- NucleicTailnet (new target, macOS + iOS): TailnetNode wraps TailscaleKit's
  node lifecycle (auth-key login, generation-fenced start/stop since up() is
  un-cancellable) and drops to the framework's public C API for the data path
  — tailscale_dial/listen/accept hand back full-duplex socketpair fds, wrapped
  by FDFrameChannel (DispatchIO) into the shared FrameChannel seam. The Swift
  wrapper's one-way connection actors can't carry a bidirectional stream.
- Host: TailnetListener adopts SyncListener; startSyncServer is single-flight
  and honors toggle-off/picker changes at the commit point; pairing QRs carry
  transport + tailnet IP/port hints (PairingPayload additive optional fields,
  forward/backward compatible over CBOR).
- iPhone: pair/reconnect dial over whichever transport the pairing recorded;
  Settings gains a Tailscale auth-key field (Keychain, committed on editing
  end); connectivity chip shows "Connected · Tailnet".
- TailscaleKit has no SwiftPM distribution: scripts/build-tailscalekit.sh
  builds a pinned libtailscale commit into an untracked local xcframework;
  Package.swift links it only when present (everything builds without it, the
  picker then reports Tailscale support as not built in), and the script
  clears SwiftPM's content-keyed manifest cache so the toggle is picked up.
- iOS floor 17.0 → 18.1 (TailscaleKit requires the iOS 18 Swift runtime);
  package-app.sh embeds the framework in the .app like Sparkle.

703-test suite: no new failures (the 7 fake-claude/fake-grok staging issues
reproduce identically on an untouched checkout — pre-existing, tracked
separately). New coverage: FDFrameChannel over socketpairs, pairing-payload
version-skew both directions, transport-setting resolution.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../NucleicRemote.xcodeproj/project.pbxproj   |  19 +-
 .../NucleicRemote/Models/IdentityStore.swift  |  12 +-
 .../NucleicRemote/Models/RemoteStore.swift    | 193 +++++++++++++++---
 .../NucleicRemote/Views/SettingsView.swift    |  31 +++
 4 files changed, 214 insertions(+), 41 deletions(-)

diff --git a/NucleicRemote/NucleicRemote.xcodeproj/project.pbxproj b/NucleicRemote/NucleicRemote.xcodeproj/project.pbxproj
index ca50297..c6c10e9 100644
--- a/NucleicRemote/NucleicRemote.xcodeproj/project.pbxproj
+++ b/NucleicRemote/NucleicRemote.xcodeproj/project.pbxproj
@@ -8,6 +8,7 @@
 
 /* Begin PBXBuildFile section */
 		BF00000000000000000001 /* NucleicProtocol in Frameworks */ = {isa = PBXBuildFile; productRef = PD00000000000000000001 /* NucleicProtocol */; };
+		BF00000000000000000003 /* NucleicTailnet in Frameworks */ = {isa = PBXBuildFile; productRef = PD00000000000000000002 /* NucleicTailnet */; };
 		BF00000000000000000002 /* NucleicRemoteWidgets.appex in Embed Foundation Extensions */ = {isa = PBXBuildFile; fileRef = FR00000000000000000002 /* NucleicRemoteWidgets.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
 		E7D43FF12FF0806800BF2407 /* app-logo-file.icon in Resources */ = {isa = PBXBuildFile; fileRef = E7D43FF02FF0806800BF2407 /* app-logo-file.icon */; };
 		E7D43FF12FF0806800BF2408 /* app-logo-canary.icon in Resources */ = {isa = PBXBuildFile; fileRef = E7D43FF02FF0806800BF2408 /* app-logo-canary.icon */; };
@@ -93,6 +94,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				BF00000000000000000001 /* NucleicProtocol in Frameworks */,
+				BF00000000000000000003 /* NucleicTailnet in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -153,6 +155,7 @@
 			name = NucleicRemote;
 			packageProductDependencies = (
 				PD00000000000000000001 /* NucleicProtocol */,
+				PD00000000000000000002 /* NucleicTailnet */,
 			);
 			productName = NucleicRemote;
 			productReference = FR00000000000000000001 /* NucleicRemote.app */;
@@ -293,7 +296,7 @@
 				COPY_PHASE_STRIP = NO;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				GCC_NO_COMMON_BLOCKS = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 18.1;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = iphoneos;
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
@@ -310,7 +313,7 @@
 				COPY_PHASE_STRIP = NO;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				GCC_NO_COMMON_BLOCKS = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 18.1;
 				SDKROOT = iphoneos;
 				SWIFT_COMPILATION_MODE = wholemodule;
 				VALIDATE_PRODUCT = YES;
@@ -342,7 +345,7 @@
 				INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight";
 				INFOPLIST_KEY_CFBundleDisplayName = "Nucleic$(NUCLEIC_NAME_SUFFIX)";
 				NUCLEIC_NAME_SUFFIX = "";
-				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 18.1;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
@@ -389,7 +392,7 @@
 				INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight";
 				INFOPLIST_KEY_CFBundleDisplayName = "Nucleic$(NUCLEIC_NAME_SUFFIX)";
 				NUCLEIC_NAME_SUFFIX = "";
-				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 18.1;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
@@ -423,7 +426,7 @@
 				INFOPLIST_FILE = NucleicRemoteWidgets/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = NucleicRemoteWidgets;
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
-				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 18.1;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
@@ -454,7 +457,7 @@
 				INFOPLIST_FILE = NucleicRemoteWidgets/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = NucleicRemoteWidgets;
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
-				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 18.1;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
@@ -517,6 +520,10 @@
 			isa = XCSwiftPackageProductDependency;
 			productName = NucleicProtocol;
 		};
+		PD00000000000000000002 /* NucleicTailnet */ = {
+			isa = XCSwiftPackageProductDependency;
+			productName = NucleicTailnet;
+		};
 /* End XCSwiftPackageProductDependency section */
 	};
 	rootObject = PJ00000000000000000001 /* Project object */;
diff --git a/NucleicRemote/NucleicRemote/Models/IdentityStore.swift b/NucleicRemote/NucleicRemote/Models/IdentityStore.swift
index 84c8c8c..4277b5f 100644
--- a/NucleicRemote/NucleicRemote/Models/IdentityStore.swift
+++ b/NucleicRemote/NucleicRemote/Models/IdentityStore.swift
@@ -3,8 +3,10 @@ import Security
 import NucleicProtocol
 
 /// What the phone pins about its Mac at pairing (SYNC §4.2): the host's static key (for IK
-/// reconnect), a display name, and an optional LAN hint. The pairing secret is *not* stored —
-/// it's one-time. Non-secret, so UserDefaults is fine; the device private key goes to Keychain.
+/// reconnect), a display name, and the transport + connection hint from the QR — LAN
+/// host:port or the Mac's tailnet IP. The pairing secret is *not* stored — it's one-time.
+/// Non-secret, so UserDefaults is fine; the device private key goes to Keychain. The new
+/// optional fields decode as nil from a pre-transport record (= LAN).
 struct PairedHost: Codable, Equatable {
     var deviceID: String
     var hostName: String
@@ -12,6 +14,12 @@ struct PairedHost: Codable, Equatable {
     var fingerprint: String
     var lanHost: String?
     var lanPort: UInt16?
+    /// `SyncTransportHint` raw value; nil = LAN (records saved before transports existed).
+    var transport: String?
+    var tailnetHost: String?
+    var tailnetPort: UInt16?
+
+    var transportHint: SyncTransportHint { transport.flatMap(SyncTransportHint.init(rawValue:)) ?? .lan }
 }
 
 /// Loads/persists this device's long-term `DeviceIdentity` (Keychain) and the pinned host
diff --git a/NucleicRemote/NucleicRemote/Models/RemoteStore.swift b/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
index 329099f..24e9b58 100644
--- a/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
+++ b/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
@@ -2,6 +2,7 @@ import Foundation
 import Network
 import SwiftUI
 import NucleicProtocol
+import NucleicTailnet
 
 /// On the phone there's no app-side `SessionSummary` view-model to collide with, so the wire
 /// type *is* the model. Alias it under the host's name so the shared vocabulary reads the same.
@@ -16,7 +17,7 @@ final class RemoteStore: ObservableObject {
         case unpaired
         case connecting
         case reconnecting
-        case connected          // LAN
+        case connected(SyncTransportHint)
         case hostOffline
         case failed(String)
 
@@ -25,12 +26,15 @@ final class RemoteStore: ObservableObject {
             case .unpaired: "Not paired"
             case .connecting: "Connecting…"
             case .reconnecting: "Reconnecting…"
-            case .connected: "Connected · LAN"
+            case .connected(let transport): "Connected · \(transport.label)"
             case .hostOffline: "Mac offline"
             case .failed(let m): m
             }
         }
-        var isLive: Bool { self == .connected }
+        var isLive: Bool {
+            if case .connected = self { return true }
+            return false
+        }
     }
 
     @Published private(set) var connectivity: Connectivity = .unpaired
@@ -142,6 +146,15 @@ final class RemoteStore: ObservableObject {
     let discovery = LANDiscovery()
     private var client: SyncClient?
     private var eventTask: Task<Void, Never>?
+    /// In-flight async connection setup (tailnet node start + dial); cancelled on teardown.
+    private var connectTask: Task<Void, Never>?
+    /// The pending reconnect backoff timer; cancelled on teardown so a stale retry can't
+    /// tear down a newer in-flight attempt.
+    private var retryTask: Task<Void, Never>?
+    /// The transport the current connection attempt uses (drives the "Connected · …" chip).
+    private var activeTransport: SyncTransportHint = .lan
+    /// The phone's embedded Tailscale node state, for Settings (nil = not running).
+    @Published private(set) var tailnetStatus: String?
     private var seenSeq: Set<UInt64> = []
     private var reconnectAttempts = 0
 
@@ -170,7 +183,7 @@ final class RemoteStore: ObservableObject {
     }
 
     private func seedDemo() {
-        connectivity = .connected
+        connectivity = .connected(.lan)
         hostName = "Andrew's Mac"
         grantedScope = .control
         capabilities = WireCapabilities(
@@ -277,46 +290,149 @@ final class RemoteStore: ObservableObject {
             """)
     }
 
-    /// Pair from a scanned QR (SYNC §4.2): connect (LAN hint first, else Bonjour), run XXpsk0,
-    /// and on success pin the host key for future IK reconnects.
+    /// Pair from a scanned QR (SYNC §4.2): connect over the transport the QR names — LAN
+    /// (explicit hint first, else Bonjour) or the Mac's tailnet IP via the phone's embedded
+    /// Tailscale node — run XXpsk0, and on success pin the host key for future IK reconnects.
     func pair(with payload: PairingPayload) {
         teardown()
         connectivity = .connecting
         hostName = payload.hostName
         let deviceID = IdentityStore.deviceID()
-        guard let endpoint = resolveEndpoint(
-            fingerprint: payload.hostStaticKey.fingerprintHex,
-            lanHost: payload.lanHost, lanPort: payload.lanPort)
-        else { connectivity = .failed("No Mac found on this network"); return }
-
-        let channel = makeChannel(endpoint)
-        let client = SyncClient(
-            channel: channel, identity: identity, hostStaticKey: payload.hostStaticKey,
-            mode: .pair(secret: payload.pairingSecret), deviceID: deviceID,
-            deviceLabel: UIDevice.current.name, pushToken: PushRegistrar.shared.tokenHex,
-            releaseChannel: BuildInfo.current.channel.releaseChannel)
-        self.client = client
-        consume(client, pairingPayload: payload)
+        switch payload.transportHint {
+        case .lan:
+            activeTransport = .lan
+            guard let endpoint = resolveEndpoint(
+                fingerprint: payload.hostStaticKey.fingerprintHex,
+                lanHost: payload.lanHost, lanPort: payload.lanPort)
+            else { connectivity = .failed("No Mac found on this network"); return }
+            startClient(
+                channel: makeChannel(endpoint), hostStaticKey: payload.hostStaticKey,
+                mode: .pair(secret: payload.pairingSecret), deviceID: deviceID,
+                pairingPayload: payload)
+        case .tailnet:
+            activeTransport = .tailnet
+            guard let tailnetHost = payload.tailnetHost, let tailnetPort = payload.tailnetPort else {
+                connectivity = .failed("The pairing code is missing the Mac's tailnet address.")
+                return
+            }
+            connectTask = Task { [weak self] in
+                guard let self else { return }
+                do {
+                    let channel = try await self.tailnetChannel(host: tailnetHost, port: tailnetPort)
+                    guard !Task.isCancelled else { channel.close(); return }
+                    self.startClient(
+                        channel: channel, hostStaticKey: payload.hostStaticKey,
+                        mode: .pair(secret: payload.pairingSecret), deviceID: deviceID,
+                        pairingPayload: payload)
+                } catch {
+                    guard !Task.isCancelled else { return }
+                    self.connectivity = .failed(error.localizedDescription)
+                }
+            }
+        case .relay:
+            connectivity = .failed("Relay connections aren't supported yet.")
+        case nil:
+            connectivity = .failed("This pairing code needs a newer version of Nucleic Remote.")
+        }
     }
 
-    /// Reconnect to the already-paired host using IK against the pinned static key.
+    /// Reconnect to the already-paired host using IK against the pinned static key, over
+    /// whichever transport the pairing recorded.
     func reconnect() {
         guard let host = IdentityStore.loadPairedHost() else { connectivity = .unpaired; return }
         teardown()
         connectivity = reconnectAttempts == 0 ? .connecting : .reconnecting
         hostName = host.hostName
-        guard let endpoint = resolveEndpoint(
-            fingerprint: host.fingerprint, lanHost: host.lanHost, lanPort: host.lanPort)
-        else { connectivity = .hostOffline; scheduleRetry(); return }
+        switch host.transportHint {
+        case .lan:
+            activeTransport = .lan
+            guard let endpoint = resolveEndpoint(
+                fingerprint: host.fingerprint, lanHost: host.lanHost, lanPort: host.lanPort)
+            else { connectivity = .hostOffline; scheduleRetry(); return }
+            startClient(
+                channel: makeChannel(endpoint), hostStaticKey: host.hostStaticKey,
+                mode: .reconnect, deviceID: host.deviceID, pairingPayload: nil)
+        case .tailnet:
+            activeTransport = .tailnet
+            guard let tailnetHost = host.tailnetHost, let tailnetPort = host.tailnetPort else {
+                connectivity = .failed("Missing tailnet address — pair with your Mac again.")
+                return
+            }
+            connectTask = Task { [weak self] in
+                guard let self else { return }
+                do {
+                    let channel = try await self.tailnetChannel(host: tailnetHost, port: tailnetPort)
+                    guard !Task.isCancelled else { channel.close(); return }
+                    self.startClient(
+                        channel: channel, hostStaticKey: host.hostStaticKey,
+                        mode: .reconnect, deviceID: host.deviceID, pairingPayload: nil)
+                } catch {
+                    guard !Task.isCancelled else { return }
+                    switch error {
+                    case TailnetError.notBuiltIn, TailnetError.notConfigured:
+                        // Retrying can't fix a missing auth key or a build without Tailscale.
+                        self.connectivity = .failed(error.localizedDescription)
+                    default:
+                        self.connectivity = .hostOffline
+                        self.scheduleRetry()
+                    }
+                }
+            }
+        case .relay:
+            connectivity = .failed("Relay connections aren't supported yet.")
+        }
+    }
 
-        let channel = makeChannel(endpoint)
+    /// Create the `SyncClient` on an established channel and start consuming its events —
+    /// the tail of every connect path, LAN or tailnet, pair or reconnect.
+    private func startClient(
+        channel: any FrameChannel, hostStaticKey: Data, mode: SyncClient.Mode,
+        deviceID: String, pairingPayload: PairingPayload?
+    ) {
         let client = SyncClient(
-            channel: channel, identity: identity, hostStaticKey: host.hostStaticKey,
-            mode: .reconnect, deviceID: host.deviceID, deviceLabel: UIDevice.current.name,
-            pushToken: PushRegistrar.shared.tokenHex,
+            channel: channel, identity: identity, hostStaticKey: hostStaticKey,
+            mode: mode, deviceID: deviceID,
+            deviceLabel: UIDevice.current.name, pushToken: PushRegistrar.shared.tokenHex,
             releaseChannel: BuildInfo.current.channel.releaseChannel)
         self.client = client
-        consume(client, pairingPayload: nil)
+        consume(client, pairingPayload: pairingPayload)
+    }
+
+    /// Bring the phone's embedded Tailscale node up (first run needs the auth key from
+    /// Settings ▸ Tailscale; afterwards the on-disk state carries the registration) and dial
+    /// the Mac's tailnet address.
+    private func tailnetChannel(host: String, port: UInt16) async throws -> FDFrameChannel {
+        guard TailnetSupport.isBuiltIn else { throw TailnetError.notBuiltIn }
+        let config = Self.phoneTailnetConfig()
+        if config.authKey == nil, !config.hasExistingState {
+            throw TailnetError.notConfigured("Add your Tailscale auth key in Settings ▸ Tailscale first.")
+        }
+        tailnetStatus = "Starting…"
+        do {
+            try await TailnetNode.shared.ensureRunning(config: config)
+        } catch TailnetError.timedOut(let message) {
+            // A login timeout won't fix itself — retrying would just block 45s per lap.
+            // Rethrow as .notConfigured so reconnect() treats it as terminal, not offline.
+            tailnetStatus = await TailnetNode.shared.status.label
+            throw TailnetError.notConfigured(message)
+        } catch {
+            tailnetStatus = await TailnetNode.shared.status.label
+            throw error
+        }
+        tailnetStatus = await TailnetNode.shared.status.label
+        return try await TailnetNode.shared.dial(host: host, port: port)
+    }
+
+    /// The phone's embedded-node config. State lives in this app's sandboxed Application
+    /// Support (no cross-channel collision — each channel is its own app container).
+    private static func phoneTailnetConfig() -> TailnetConfig {
+        let base = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("Nucleic", isDirectory: true)
+            .appendingPathComponent("tailnet", isDirectory: true)
+        return TailnetConfig(
+            hostName: TailnetConfig.nodeName(for: UIDevice.current.name),
+            stateDirectory: base,
+            authKey: TailnetAuthStore.loadAuthKey())
     }
 
     func unpair() {
@@ -324,6 +440,9 @@ final class RemoteStore: ObservableObject {
         IdentityStore.clearPairedHost()
         connectivity = .unpaired
         sessions = []
+        // Nothing left to dial — spin the embedded Tailscale node down if it was running.
+        Task { await TailnetNode.shared.stop() }
+        tailnetStatus = nil
         LiveActivityManager.shared.end()
         NotificationRouter.shared.updateBadge(0)
     }
@@ -717,7 +836,7 @@ final class RemoteStore: ObservableObject {
             break
         case .ready(let welcome):
             reconnectAttempts = 0
-            connectivity = .connected
+            connectivity = .connected(activeTransport)
             hostName = welcome.host.hostName
             capabilities = welcome.capabilities
             grantedScope = welcome.grantedScope
@@ -726,7 +845,9 @@ final class RemoteStore: ObservableObject {
                 IdentityStore.savePairedHost(PairedHost(
                     deviceID: IdentityStore.deviceID(), hostName: welcome.host.hostName,
                     hostStaticKey: hostKey, fingerprint: hostKey.fingerprintHex,
-                    lanHost: payload.lanHost, lanPort: payload.lanPort))
+                    lanHost: payload.lanHost, lanPort: payload.lanPort,
+                    transport: payload.transport, tailnetHost: payload.tailnetHost,
+                    tailnetPort: payload.tailnetPort))
             }
             send(.listSessions)
             send(.listDashboard)
@@ -801,7 +922,7 @@ final class RemoteStore: ObservableObject {
             connectivity = .failed(message)
             scheduleRetry()
         case .closed:
-            if connectivity == .connected { connectivity = .reconnecting }
+            if connectivity.isLive { connectivity = .reconnecting }
             scheduleRetry()
         }
     }
@@ -828,14 +949,20 @@ final class RemoteStore: ObservableObject {
         guard isPaired else { return }
         reconnectAttempts += 1
         let delay = min(Double(reconnectAttempts) * 1.5, 10)
-        Task { [weak self] in
+        retryTask?.cancel()
+        retryTask = Task { [weak self] in
+            // `try?` swallows the sleep's CancellationError, so check explicitly.
             try? await Task.sleep(for: .seconds(delay))
-            guard let self, self.connectivity != .connected else { return }
+            guard !Task.isCancelled, let self, !self.connectivity.isLive else { return }
             self.reconnect()
         }
     }
 
     private func teardown() {
+        retryTask?.cancel()
+        retryTask = nil
+        connectTask?.cancel()
+        connectTask = nil
         eventTask?.cancel()
         eventTask = nil
         if let client { Task { await client.disconnect() } }
diff --git a/NucleicRemote/NucleicRemote/Views/SettingsView.swift b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
index 25c2ddd..fa3711e 100644
--- a/NucleicRemote/NucleicRemote/Views/SettingsView.swift
+++ b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
@@ -1,9 +1,12 @@
 import SwiftUI
 import NucleicProtocol
+import NucleicTailnet
 
 struct SettingsView: View {
     @EnvironmentObject var store: RemoteStore
     @State private var showScanner = false
+    @State private var tailscaleAuthKey: String = TailnetAuthStore.loadAuthKey() ?? ""
+    @FocusState private var tailscaleKeyFocused: Bool
     @AppStorage("nucleic.showRawEvents") private var showRaw = false
     @AppStorage("nucleic.showLockEvents") private var showLockEvents = true
     @AppStorage(HeartbeatSettings.shareAnonymousUsageKey) private var shareAnonymousUsage = true
@@ -53,10 +56,38 @@ struct SettingsView: View {
                     if !store.hostName.isEmpty {
                         LabeledContent("Mac", value: store.hostName)
                     }
+                    if let transport = IdentityStore.loadPairedHost()?.transportHint {
+                        LabeledContent("Transport", value: transport.label)
+                    }
                     Button("Reconnect") { store.reconnect() }
                         .disabled(!store.isPaired)
                 }
 
+                Section {
+                    if TailnetSupport.isBuiltIn {
+                        // Commit on editing end, not per keystroke — a per-change save would
+                        // clear the valid Keychain key on the first backspace of an edit.
+                        SecureField("Auth key (tskey-auth-…)", text: $tailscaleAuthKey)
+                            .autocorrectionDisabled()
+                            .textInputAutocapitalization(.never)
+                            .focused($tailscaleKeyFocused)
+                            .onSubmit { TailnetAuthStore.saveAuthKey(tailscaleAuthKey) }
+                            .onChange(of: tailscaleKeyFocused) {
+                                if !tailscaleKeyFocused { TailnetAuthStore.saveAuthKey(tailscaleAuthKey) }
+                            }
+                        if let status = store.tailnetStatus {
+                            LabeledContent("Node", value: status)
+                        }
+                    } else {
+                        Text("This build doesn't include Tailscale support.")
+                            .foregroundStyle(.secondary)
+                    }
+                } header: {
+                    Text("Tailscale")
+                } footer: {
+                    Text("Needed only when your Mac shares over Tailscale (Mac ▸ Settings ▸ Remote ▸ Connect via). Create an auth key in the Tailscale admin console (Settings ▸ Keys); it's kept in the Keychain and used once to join your tailnet — after that the phone stays registered.")
+                }
+
                 Section("This device") {
                     LabeledContent("Scope", value: store.grantedScope.rawValue.capitalized)
                     LabeledContent("Key fingerprint", value: store.deviceFingerprint)

From 272039cca554d9dd89d9b84ca3ce0af5eee8bf2b Mon Sep 17 00:00:00 2001
From: Andrew Blakeslee Moore <andrew@blakeslee.me>
Date: Fri, 3 Jul 2026 16:14:45 -0700
Subject: [PATCH 3/5] =?UTF-8?q?Tailnet:=20interactive=20browser=20login=20?=
 =?UTF-8?q?+=20LAN=E2=86=94tailnet=20fallback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Browser login — the auth key is now optional on both platforms. When the
embedded node starts with no key, TailnetNode asks the backend (LocalAPI
backendStatus — IPN state, deliberately not filesystem heuristics: tsnet
writes logs and a machine key on every start, registered or not) whether a
login is needed, triggers login-interactive, surfaces the auth URL through a
new statusStream()/.needsLogin, and waits for Running (4-minute deadline,
generation-fenced against stop/restart). The Mac auto-opens the login page
from Settings ▸ Remote and shows a re-open button; the iPhone auto-opens only
during user-initiated pairing (a background reconnect that suddenly needs a
login must not eject the user to Safari — Settings ▸ Tailscale carries the
link). The remote-access toggle now reflects the in-flight start instead of
snapping off for the whole login window, and toggling off mid-start is
honored at both commit points (before and after host.start).

LAN↔tailnet fallback — picking Tailnet now keeps LAN on too: the host runs
both listeners under a new CompositeSyncListener (merged accept stream; one
child ending doesn't end the rest) and the pairing QR carries both hints.
The phone builds an ordered candidate chain — LAN first (QR hint or Bonjour),
tailnet second — and walks it on pair and reconnect, so a phone that leaves
the Mac's Wi‑Fi rolls over to the tailnet and rolls back when it returns.
A per-channel 4s connect guard (readiness-checking, bound to exactly its
channel) keeps a stale LAN hint from hanging the chain; a stale-client guard
in consume() keeps a replaced client's tail events from advancing it; chain
exhaustion during pairing lands in a terminal failure instead of spinning on
"Connecting…"; routine pre-fallback handshake errors no longer flash the red
error bubble. "Connected · LAN / Tailnet" shows whichever transport won.

Multi-agent review: 11 confirmed findings (incl. the login gate being dead
code via tsnet's eager state-dir writes, and two connect-timeout races), all
fixed and re-verified. Suite green (24 sync-related tests incl. 3 new
CompositeSyncListener tests); macOS + iOS builds clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../NucleicRemote/Models/RemoteStore.swift    | 270 +++++++++++++-----
 .../NucleicRemote/Net/NWFrameChannel.swift    |  18 +-
 .../NucleicRemote/Views/SettingsView.swift    |  12 +-
 3 files changed, 224 insertions(+), 76 deletions(-)

diff --git a/NucleicRemote/NucleicRemote/Models/RemoteStore.swift b/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
index 24e9b58..6596921 100644
--- a/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
+++ b/NucleicRemote/NucleicRemote/Models/RemoteStore.swift
@@ -155,6 +155,9 @@ final class RemoteStore: ObservableObject {
     private var activeTransport: SyncTransportHint = .lan
     /// The phone's embedded Tailscale node state, for Settings (nil = not running).
     @Published private(set) var tailnetStatus: String?
+    /// The Tailscale interactive-login URL while the node waits for a browser login (a
+    /// first tailnet start with no auth key). Auto-opened; Settings shows a re-open button.
+    @Published private(set) var tailnetLoginURL: URL?
     private var seenSeq: Set<UInt64> = []
     private var reconnectAttempts = 0
 
@@ -290,99 +293,168 @@ final class RemoteStore: ObservableObject {
             """)
     }
 
-    /// Pair from a scanned QR (SYNC §4.2): connect over the transport the QR names — LAN
-    /// (explicit hint first, else Bonjour) or the Mac's tailnet IP via the phone's embedded
-    /// Tailscale node — run XXpsk0, and on success pin the host key for future IK reconnects.
+    /// One dialable way to reach the Mac. A connect builds an ordered candidate list — LAN
+    /// first (cheapest when reachable), then the tailnet (SYNC §3.2's LAN-then-fallback
+    /// ordering) — and `attempt` walks it until one carries a session.
+    private enum TransportAttempt {
+        case lan(NWEndpoint)
+        case tailnet(host: String, port: UInt16)
+    }
+
+    /// The in-progress connect: remaining candidates plus everything needed to start a
+    /// client on whichever one succeeds. Cleared on `.ready` (chain done) and by teardown.
+    private struct ConnectPlan {
+        var remaining: [TransportAttempt]
+        let hostStaticKey: Data
+        let mode: SyncClient.Mode
+        let deviceID: String
+        let pairingPayload: PairingPayload?
+    }
+    private var connectPlan: ConnectPlan?
+    /// Kills a LAN attempt whose TCP connect just hangs (stale IP hint) so the chain can
+    /// move on — NWConnection's own timeout is far too slow for a fallback decision.
+    private var lanConnectTimeout: Task<Void, Never>?
+
+    /// Pair from a scanned QR (SYNC §4.2): try the QR's transports in order (LAN hint or
+    /// Bonjour first, then the Mac's tailnet IP via the phone's embedded node), run XXpsk0,
+    /// and on success pin the host key for future IK reconnects.
     func pair(with payload: PairingPayload) {
         teardown()
         connectivity = .connecting
         hostName = payload.hostName
-        let deviceID = IdentityStore.deviceID()
-        switch payload.transportHint {
-        case .lan:
-            activeTransport = .lan
-            guard let endpoint = resolveEndpoint(
-                fingerprint: payload.hostStaticKey.fingerprintHex,
-                lanHost: payload.lanHost, lanPort: payload.lanPort)
-            else { connectivity = .failed("No Mac found on this network"); return }
-            startClient(
-                channel: makeChannel(endpoint), hostStaticKey: payload.hostStaticKey,
-                mode: .pair(secret: payload.pairingSecret), deviceID: deviceID,
-                pairingPayload: payload)
-        case .tailnet:
-            activeTransport = .tailnet
-            guard let tailnetHost = payload.tailnetHost, let tailnetPort = payload.tailnetPort else {
-                connectivity = .failed("The pairing code is missing the Mac's tailnet address.")
-                return
-            }
-            connectTask = Task { [weak self] in
-                guard let self else { return }
-                do {
-                    let channel = try await self.tailnetChannel(host: tailnetHost, port: tailnetPort)
-                    guard !Task.isCancelled else { channel.close(); return }
-                    self.startClient(
-                        channel: channel, hostStaticKey: payload.hostStaticKey,
-                        mode: .pair(secret: payload.pairingSecret), deviceID: deviceID,
-                        pairingPayload: payload)
-                } catch {
-                    guard !Task.isCancelled else { return }
-                    self.connectivity = .failed(error.localizedDescription)
-                }
-            }
-        case .relay:
-            connectivity = .failed("Relay connections aren't supported yet.")
-        case nil:
+        guard let hint = payload.transportHint else {
             connectivity = .failed("This pairing code needs a newer version of Nucleic Remote.")
+            return
         }
+        guard hint != .relay else {
+            connectivity = .failed("Relay connections aren't supported yet.")
+            return
+        }
+        let candidates = buildCandidates(
+            fingerprint: payload.hostStaticKey.fingerprintHex,
+            lanHost: payload.lanHost, lanPort: payload.lanPort,
+            tailnet: hint == .tailnet ? (payload.tailnetHost, payload.tailnetPort) : nil)
+        guard !candidates.isEmpty else {
+            connectivity = .failed(hint == .tailnet && !TailnetSupport.isBuiltIn
+                ? TailnetError.notBuiltIn.errorDescription ?? "Tailscale support isn't built in"
+                : "No Mac found on this network")
+            return
+        }
+        connectPlan = ConnectPlan(
+            remaining: candidates, hostStaticKey: payload.hostStaticKey,
+            mode: .pair(secret: payload.pairingSecret), deviceID: IdentityStore.deviceID(),
+            pairingPayload: payload)
+        _ = tryNextCandidate()
     }
 
-    /// Reconnect to the already-paired host using IK against the pinned static key, over
-    /// whichever transport the pairing recorded.
+    /// Reconnect to the already-paired host using IK against the pinned static key: LAN
+    /// when reachable, else the pairing's tailnet hint — so a phone that leaves the Mac's
+    /// Wi‑Fi rolls over to the tailnet and rolls back when it returns.
     func reconnect() {
         guard let host = IdentityStore.loadPairedHost() else { connectivity = .unpaired; return }
         teardown()
         connectivity = reconnectAttempts == 0 ? .connecting : .reconnecting
         hostName = host.hostName
-        switch host.transportHint {
-        case .lan:
+        guard host.transportHint != .relay else {
+            connectivity = .failed("Relay connections aren't supported yet.")
+            return
+        }
+        let candidates = buildCandidates(
+            fingerprint: host.fingerprint,
+            lanHost: host.lanHost, lanPort: host.lanPort,
+            tailnet: host.transportHint == .tailnet ? (host.tailnetHost, host.tailnetPort) : nil)
+        guard !candidates.isEmpty else {
+            connectivity = .hostOffline
+            scheduleRetry()
+            return
+        }
+        connectPlan = ConnectPlan(
+            remaining: candidates, hostStaticKey: host.hostStaticKey,
+            mode: .reconnect, deviceID: host.deviceID, pairingPayload: nil)
+        _ = tryNextCandidate()
+    }
+
+    /// LAN first (explicit hint, else a Bonjour match), tailnet second when the pairing
+    /// carries one and this build can dial it.
+    private func buildCandidates(
+        fingerprint: String?, lanHost: String?, lanPort: UInt16?,
+        tailnet: (host: String?, port: UInt16?)?
+    ) -> [TransportAttempt] {
+        var candidates: [TransportAttempt] = []
+        if let endpoint = resolveEndpoint(fingerprint: fingerprint, lanHost: lanHost, lanPort: lanPort) {
+            candidates.append(.lan(endpoint))
+        }
+        if let tailnet, let host = tailnet.host, let port = tailnet.port, TailnetSupport.isBuiltIn {
+            candidates.append(.tailnet(host: host, port: port))
+        }
+        return candidates
+    }
+
+    /// Pop and dial the next candidate. False when the plan is exhausted (or gone) — the
+    /// caller then applies its terminal failure handling.
+    private func tryNextCandidate() -> Bool {
+        guard var plan = connectPlan, !plan.remaining.isEmpty else { return false }
+        let next = plan.remaining.removeFirst()
+        connectPlan = plan
+        attempt(next, plan: plan)
+        return true
+    }
+
+    private func attempt(_ candidate: TransportAttempt, plan: ConnectPlan) {
+        teardownClient()
+        switch candidate {
+        case .lan(let endpoint):
             activeTransport = .lan
-            guard let endpoint = resolveEndpoint(
-                fingerprint: host.fingerprint, lanHost: host.lanHost, lanPort: host.lanPort)
-            else { connectivity = .hostOffline; scheduleRetry(); return }
-            startClient(
-                channel: makeChannel(endpoint), hostStaticKey: host.hostStaticKey,
-                mode: .reconnect, deviceID: host.deviceID, pairingPayload: nil)
-        case .tailnet:
-            activeTransport = .tailnet
-            guard let tailnetHost = host.tailnetHost, let tailnetPort = host.tailnetPort else {
-                connectivity = .failed("Missing tailnet address — pair with your Mac again.")
-                return
+            let channel = makeChannel(endpoint)
+            // Close the channel if TCP isn't up within the window (a stale IP hint would
+            // otherwise hang the chain on NWConnection's slow timeout); the finished stream
+            // then advances to the next candidate. The timer checks readiness itself — it's
+            // bound to exactly this channel, so a stale timer can never hit a later attempt.
+            lanConnectTimeout?.cancel()
+            lanConnectTimeout = Task { [weak channel] in
+                try? await Task.sleep(for: .seconds(4))
+                guard !Task.isCancelled, let channel, !channel.isReady else { return }
+                channel.close()
             }
+            startClient(
+                channel: channel, hostStaticKey: plan.hostStaticKey,
+                mode: plan.mode, deviceID: plan.deviceID, pairingPayload: plan.pairingPayload)
+        case .tailnet(let host, let port):
+            activeTransport = .tailnet
             connectTask = Task { [weak self] in
                 guard let self else { return }
                 do {
-                    let channel = try await self.tailnetChannel(host: tailnetHost, port: tailnetPort)
+                    let channel = try await self.tailnetChannel(host: host, port: port)
                     guard !Task.isCancelled else { channel.close(); return }
                     self.startClient(
-                        channel: channel, hostStaticKey: host.hostStaticKey,
-                        mode: .reconnect, deviceID: host.deviceID, pairingPayload: nil)
+                        channel: channel, hostStaticKey: plan.hostStaticKey,
+                        mode: plan.mode, deviceID: plan.deviceID, pairingPayload: plan.pairingPayload)
                 } catch {
                     guard !Task.isCancelled else { return }
-                    switch error {
-                    case TailnetError.notBuiltIn, TailnetError.notConfigured:
-                        // Retrying can't fix a missing auth key or a build without Tailscale.
-                        self.connectivity = .failed(error.localizedDescription)
-                    default:
-                        self.connectivity = .hostOffline
-                        self.scheduleRetry()
-                    }
+                    self.tailnetAttemptFailed(error, isPairing: plan.pairingPayload != nil)
                 }
             }
-        case .relay:
-            connectivity = .failed("Relay connections aren't supported yet.")
         }
     }
 
+    /// The tailnet is always the last candidate, so its failure ends the chain: terminal
+    /// for pairing and for anything retrying can't fix; otherwise offline + backoff.
+    private func tailnetAttemptFailed(_ error: Error, isPairing: Bool) {
+        if tryNextCandidate() { return }
+        if isPairing {
+            connectivity = .failed(error.localizedDescription)
+            return
+        }
+        switch error {
+        case TailnetError.notBuiltIn, TailnetError.notConfigured:
+            connectivity = .failed(error.localizedDescription)
+        default:
+            connectivity = .hostOffline
+            scheduleRetry()
+        }
+    }
+
+
     /// Create the `SyncClient` on an established channel and start consuming its events —
     /// the tail of every connect path, LAN or tailnet, pair or reconnect.
     private func startClient(
@@ -404,14 +476,38 @@ final class RemoteStore: ObservableObject {
     private func tailnetChannel(host: String, port: UInt16) async throws -> FDFrameChannel {
         guard TailnetSupport.isBuiltIn else { throw TailnetError.notBuiltIn }
         let config = Self.phoneTailnetConfig()
-        if config.authKey == nil, !config.hasExistingState {
-            throw TailnetError.notConfigured("Add your Tailscale auth key in Settings ▸ Tailscale first.")
-        }
         tailnetStatus = "Starting…"
+        // Mirror node status while the start is in flight. A first start with no auth key
+        // goes through the interactive browser login; pairing usually runs from the scanner
+        // sheet — not Settings — so take the user straight to the approval page.
+        let watcher = Task { [weak self] in
+            for await status in await TailnetNode.shared.statusStream() {
+                guard let self, !Task.isCancelled else { break }
+                self.tailnetStatus = status.label
+                if case .needsLogin(let url) = status, let loginURL = URL(string: url) {
+                    if self.tailnetLoginURL != loginURL {
+                        self.tailnetLoginURL = loginURL
+                        // Eject to Safari only for user-initiated pairing — the user is
+                        // actively watching. A routine reconnect that suddenly needs a
+                        // login (node revoked, state wiped) must not yank them out of the
+                        // app; Settings ▸ Tailscale carries the login link instead.
+                        if self.connectPlan?.pairingPayload != nil {
+                            UIApplication.shared.open(loginURL, options: [:], completionHandler: nil)
+                        }
+                    }
+                } else {
+                    self.tailnetLoginURL = nil
+                }
+            }
+        }
+        defer {
+            watcher.cancel()
+            tailnetLoginURL = nil
+        }
         do {
             try await TailnetNode.shared.ensureRunning(config: config)
         } catch TailnetError.timedOut(let message) {
-            // A login timeout won't fix itself — retrying would just block 45s per lap.
+            // A login/auth timeout won't fix itself — retrying would just block per lap.
             // Rethrow as .notConfigured so reconnect() treats it as terminal, not offline.
             tailnetStatus = await TailnetNode.shared.status.label
             throw TailnetError.notConfigured(message)
@@ -825,7 +921,11 @@ final class RemoteStore: ObservableObject {
         eventTask = Task { [weak self] in
             let stream = await client.start()
             for await event in stream {
-                await self?.handle(event, pairingPayload: pairingPayload)
+                // A replaced client's tail events (`.failed` is always chased by `.closed`)
+                // must not leak into the new attempt — they'd advance the candidate chain
+                // or schedule retries against a connection that no longer exists.
+                guard let self, self.client === client else { break }
+                await self.handle(event, pairingPayload: pairingPayload)
             }
         }
     }
@@ -836,6 +936,7 @@ final class RemoteStore: ObservableObject {
             break
         case .ready(let welcome):
             reconnectAttempts = 0
+            connectPlan = nil  // the chain found its transport
             connectivity = .connected(activeTransport)
             hostName = welcome.host.hostName
             capabilities = welcome.capabilities
@@ -917,12 +1018,28 @@ final class RemoteStore: ObservableObject {
             // Losing an approval race isn't an error worth interrupting for; the card
             // collapses on the matching `approvalResolved`.
             guard error.code != .alreadyResolved else { break }
+            // While the connect chain is still resolving a transport, a pre-ready error
+            // (e.g. "handshake closed" from a LAN probe about to fall back to tailnet) is
+            // routine, not news — the follow-on `.closed` advances the chain silently.
+            guard connectPlan == nil else { break }
             showError(error.message, sessionID: error.sessionID)
         case .failed(let message):
+            // Another candidate may still carry the session (e.g. LAN died → tailnet).
+            if tryNextCandidate() { break }
+            connectPlan = nil
             connectivity = .failed(message)
             scheduleRetry()
         case .closed:
-            if connectivity.isLive { connectivity = .reconnecting }
+            if !connectivity.isLive, tryNextCandidate() { break }
+            if connectivity.isLive {
+                connectivity = .reconnecting
+            } else if connectPlan?.pairingPayload != nil {
+                // A pairing chain died silently (every candidate closed pre-welcome).
+                // There's no retry loop before a pairing succeeds, so without a terminal
+                // state this would sit on "Connecting…" forever.
+                connectivity = .failed("Couldn't connect to your Mac — check that it's reachable, then scan again.")
+            }
+            connectPlan = nil
             scheduleRetry()
         }
     }
@@ -963,6 +1080,15 @@ final class RemoteStore: ObservableObject {
         retryTask = nil
         connectTask?.cancel()
         connectTask = nil
+        connectPlan = nil
+        teardownClient()
+    }
+
+    /// Drop just the current client/channel — what moving to the next transport candidate
+    /// needs, without discarding the rest of the plan.
+    private func teardownClient() {
+        lanConnectTimeout?.cancel()
+        lanConnectTimeout = nil
         eventTask?.cancel()
         eventTask = nil
         if let client { Task { await client.disconnect() } }
diff --git a/NucleicRemote/NucleicRemote/Net/NWFrameChannel.swift b/NucleicRemote/NucleicRemote/Net/NWFrameChannel.swift
index b1db453..ce62ed0 100644
--- a/NucleicRemote/NucleicRemote/Net/NWFrameChannel.swift
+++ b/NucleicRemote/NucleicRemote/Net/NWFrameChannel.swift
@@ -17,6 +17,16 @@ final class NWFrameChannel: FrameChannel, @unchecked Sendable {
     var onReady: (@Sendable () -> Void)?
     var onFailed: (@Sendable (String) -> Void)?
 
+    /// Whether TCP reached `.ready` — latched, thread-safe. The connect-timeout guard
+    /// polls this instead of relying on a callback that could race connection start.
+    private let stateLock = NSLock()
+    private var ready = false
+    var isReady: Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return ready
+    }
+
     init(endpoint: NWEndpoint) {
         let params = NWParameters.tcp
         params.includePeerToPeer = true
@@ -28,7 +38,7 @@ final class NWFrameChannel: FrameChannel, @unchecked Sendable {
 
         connection.stateUpdateHandler = { [weak self] state in
             switch state {
-            case .ready: self?.onReady?()
+            case .ready: self?.markReady(); self?.onReady?()
             case .failed(let error): self?.onFailed?("\(error)"); self?.continuation.finish()
             case .cancelled: self?.continuation.finish()
             default: break
@@ -38,6 +48,12 @@ final class NWFrameChannel: FrameChannel, @unchecked Sendable {
         receiveLoop()
     }
 
+    private func markReady() {
+        stateLock.lock()
+        ready = true
+        stateLock.unlock()
+    }
+
     func frames() -> AsyncStream<Data> { stream }
 
     func send(_ frame: Data) {
diff --git a/NucleicRemote/NucleicRemote/Views/SettingsView.swift b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
index fa3711e..67acaae 100644
--- a/NucleicRemote/NucleicRemote/Views/SettingsView.swift
+++ b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
@@ -56,8 +56,9 @@ struct SettingsView: View {
                     if !store.hostName.isEmpty {
                         LabeledContent("Mac", value: store.hostName)
                     }
-                    if let transport = IdentityStore.loadPairedHost()?.transportHint {
-                        LabeledContent("Transport", value: transport.label)
+                    // What this pairing can dial — the live transport is in Status above.
+                    if let host = IdentityStore.loadPairedHost() {
+                        LabeledContent("Transports", value: host.tailnetHost != nil ? "LAN + Tailnet" : "LAN")
                     }
                     Button("Reconnect") { store.reconnect() }
                         .disabled(!store.isPaired)
@@ -78,6 +79,11 @@ struct SettingsView: View {
                         if let status = store.tailnetStatus {
                             LabeledContent("Node", value: status)
                         }
+                        if let loginURL = store.tailnetLoginURL {
+                            Link(destination: loginURL) {
+                                Label("Open Tailscale login", systemImage: "arrow.up.forward.app")
+                            }
+                        }
                     } else {
                         Text("This build doesn't include Tailscale support.")
                             .foregroundStyle(.secondary)
@@ -85,7 +91,7 @@ struct SettingsView: View {
                 } header: {
                     Text("Tailscale")
                 } footer: {
-                    Text("Needed only when your Mac shares over Tailscale (Mac ▸ Settings ▸ Remote ▸ Connect via). Create an auth key in the Tailscale admin console (Settings ▸ Keys); it's kept in the Keychain and used once to join your tailnet — after that the phone stays registered.")
+                    Text("Needed only when your Mac shares over Tailscale (Mac ▸ Settings ▸ Remote ▸ Connect via). Leave the key empty to approve this iPhone in your browser on first connect, or create an auth key in the Tailscale admin console (kept in the Keychain, used once to join your tailnet).")
                 }
 
                 Section("This device") {

From 57d0ccc5f6410c029c278524d38eaa2840f2ec6f Mon Sep 17 00:00:00 2001
From: Andrew Blakeslee Moore <andrew@blakeslee.me>
Date: Fri, 3 Jul 2026 16:25:27 -0700
Subject: [PATCH 4/5] ios: surface the browser-login step on the pairing intro
 screen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A first tailnet pairing with no auth key detours through a Tailscale browser
login that can take minutes. The intro screen — the only UI an unpaired phone
has — showed just "Connecting to your Mac…" for that whole window, and if
the user closed Safari there was no way back to the login page (the Settings
tab with the login link only exists once paired). The intro's pairing status
now explains the approval step and links to the login page whenever the
embedded node is waiting on one.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../NucleicRemote/Views/SettingsView.swift     | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/NucleicRemote/NucleicRemote/Views/SettingsView.swift b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
index db30fc8..f19e205 100644
--- a/NucleicRemote/NucleicRemote/Views/SettingsView.swift
+++ b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
@@ -199,8 +199,22 @@ struct PairingIntroView: View {
     private var pairingStatus: some View {
         switch store.connectivity {
         case .connecting, .reconnecting:
-            Label("Connecting to your Mac…", systemImage: "arrow.triangle.2.circlepath")
-                .font(.footnote).foregroundStyle(.secondary)
+            // A first tailnet pairing with no auth key detours through a browser login
+            // that can take minutes — and this intro is the ONLY screen an unpaired phone
+            // has (no Settings tab yet), so the way back to the login page must live here.
+            if let loginURL = store.tailnetLoginURL {
+                VStack(spacing: 6) {
+                    Label("Approve this iPhone in your browser to join your tailnet.",
+                          systemImage: "person.crop.circle.badge.checkmark")
+                        .font(.footnote).foregroundStyle(.secondary)
+                        .multilineTextAlignment(.center).padding(.horizontal, 32)
+                    Link("Open the Tailscale login page", destination: loginURL)
+                        .font(.footnote.weight(.medium))
+                }
+            } else {
+                Label("Connecting to your Mac…", systemImage: "arrow.triangle.2.circlepath")
+                    .font(.footnote).foregroundStyle(.secondary)
+            }
         case .hostOffline:
             Label("Can't reach your Mac. Make sure it's on the same Wi‑Fi and remote access is on.",
                   systemImage: "wifi.exclamationmark")

From b0284f1da1ac812e37fe895bac6b71062e98fa8b Mon Sep 17 00:00:00 2001
From: Andrew Blakeslee Moore <andrew@blakeslee.me>
Date: Fri, 3 Jul 2026 17:40:28 -0700
Subject: [PATCH 5/5] =?UTF-8?q?nvrsion:=20Add:=20Adjust=20side=20padding?=
 =?UTF-8?q?=20on=20=E2=80=9CUpdate=20available=E2=80=9D=20card=20in=20side?=
 =?UTF-8?q?bar=20to=20match=20session=20entries=E2=80=99=20padding,=20fix?=
 =?UTF-8?q?=20internal=20tester=20invitation=20workflow=20for=20rapid=20Ca?=
 =?UTF-8?q?nary=20channel=20releases,=20and=20create=20a=20=E2=80=9Ctruste?=
 =?UTF-8?q?d=20tester=E2=80=9D=20system=20requiring=20approval=20to=20join?=
 =?UTF-8?q?=20internal=20testing=20groups.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Nucleic-Promote: 1
Co-authored-by: Nucleic <nucleic@blakeslee.xyz>
---
 NucleicRemote/NucleicRemote/Views/SettingsView.swift | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/NucleicRemote/NucleicRemote/Views/SettingsView.swift b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
index f19e205..8c563ad 100644
--- a/NucleicRemote/NucleicRemote/Views/SettingsView.swift
+++ b/NucleicRemote/NucleicRemote/Views/SettingsView.swift
@@ -109,6 +109,16 @@ struct SettingsView: View {
                     Text("Raw events are unrecognized backend output, shown for debugging.")
                 }
 
+                Section {
+                    Link(destination: URL(string: "https://nucleic.blakeslee.xyz/trusted-tester.html")!) {
+                        Label("Apply to be a trusted tester", systemImage: "person.badge.shield.checkmark")
+                    }
+                } header: {
+                    Text("Trusted tester")
+                } footer: {
+                    Text("This app ships through TestFlight. Apply for trusted-tester access to get earlier builds and shape where the app goes — we review your background and, if approved, add you to internal TestFlight.")
+                }
+
                 Section {
                     Toggle("Share anonymous usage", isOn: $shareAnonymousUsage)
                 } header: {