From e112da757812e62227762d0bf701fb680a99dc84 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Tue, 15 Sep 2026 16:01:27 +0530
Subject: [PATCH] docs(desktop): preflight comments describe the OAuth-only
 branch; scope assertion via objectContaining

---
 apps/desktop/src/store/connections.test.ts | 13 ++++---------
 apps/desktop/src/store/connections.ts      | 11 ++++++-----
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/apps/desktop/src/store/connections.test.ts b/apps/desktop/src/store/connections.test.ts
index cc0a6115a3..737bb7db33 100644
--- a/apps/desktop/src/store/connections.test.ts
+++ b/apps/desktop/src/store/connections.test.ts
@@ -418,15 +418,10 @@ describe('selectConnection', () => {
       // Auth is refreshed externally; the very next click must work with the
       // same module and warm socket, without a cached failed readiness result.
       await selectConnection('homelab', { profile: 'scout' })
-      expect(api.mock.calls).toEqual(
-        Array.from({ length: 3 }, () => [
-          {
-            connectionId: 'homelab',
-            profile: 'scout',
-            path: '/api/profiles',
-            timeoutMs: 60_000
-          }
-        ])
+      expect(api.mock.calls.map(call => (call as unknown[])[0])).toEqual(
+        Array.from({ length: 3 }, () =>
+          expect.objectContaining({ connectionId: 'homelab', profile: 'scout', path: '/api/profiles' })
+        )
       )
       expect(openGatewayAgent.mock.calls).toEqual(Array.from({ length: 3 }, () => ['homelab', 'scout']))
       expect(ensureGatewayAgent).toHaveBeenCalledTimes(1)
diff --git a/apps/desktop/src/store/connections.ts b/apps/desktop/src/store/connections.ts
index 892ae85b4f..dcbbd04b9c 100644
--- a/apps/desktop/src/store/connections.ts
+++ b/apps/desktop/src/store/connections.ts
@@ -243,8 +243,9 @@ export async function initializeConnectionsRegistry(): Promise<DesktopConnection
  * never probes or opens remote gateways.
  *
  * Two phases, same commit contract as a Settings → Gateway apply (softSwitch):
- *  1. Prove target socket/REST readiness WITHOUT activating it. The previous
- *     source stays fully bound and painted, so a dead target loses nothing.
+ *  1. Dial the target — and for OAuth remotes prove a protected REST read —
+ *     WITHOUT activating it. The previous source stays fully bound and
+ *     painted, so a dead target loses nothing.
  *  2. Commit: beginGatewaySwitch() — barrier up, machine-context reset,
  *     session bindings wiped — then activate the already-open socket. The
  *     wipe runs inside the activation's serialized section, synchronously
@@ -355,9 +356,9 @@ export async function selectConnection(connectionId: string, options: SelectConn
       targetConnection.authMode === 'oauth' &&
       (targetConnection.kind === 'remote' || targetConnection.kind === 'cloud')
     ) {
-      // Retained sockets can outlive cookie/native OAuth REST auth. Prove a
-      // protected read on the destination before wiping. Keep the exact
-      // failure for caller UX (network failures must not become sign-in errors).
+      // Retained sockets can outlive cookie/native OAuth REST auth. Prove the
+      // cheapest protected read the target always serves before wiping. Keep
+      // the exact failure for caller UX (network failures are not sign-in errors).
       await withTimeout(
         getProfiles({ connectionId, profile: targetProfile }),
         SWITCH_DIAL_TIMEOUT_MS,