@oxyhq/services 14.0.1 → 15.0.0

package/lib/module/ui/context/OxyContext.js

@@ -1,154 +1,60 @@
 "use strict";
 
-import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { OxyServices, oxyClient } from '@oxyhq/core';
-import { KeyManager } from '@oxyhq/core';
-import { runColdBoot, resolveCentralAuthUrl, registrableApex, SSO_CALLBACK_PATH, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, isCentralIdPOrigin, guardActive, allowSsoBounce, ssoNavigate, buildSsoBounceUrl, consumeSsoReturn } from '@oxyhq/core';
-import { toast } from '@oxyhq/bloom';
+import { KeyManager, runSessionColdBoot, installAuthRefreshHandler, startTokenRefreshScheduler, logger as loggerUtil } from '@oxyhq/core';
 import { useAuthStore } from "../stores/authStore.js";
 import { useShallow } from 'zustand/react/shallow';
 import { useLanguageManagement } from "../hooks/useLanguageManagement.js";
 import { useSessionManagement } from "../hooks/useSessionManagement.js";
-import { useAuthOperations, clearPriorSessionHintSafe } from "./hooks/useAuthOperations.js";
+import { useAuthOperations, clearPersistedAuthSafe } from "./hooks/useAuthOperations.js";
 import { useDeviceManagement } from "../hooks/useDeviceManagement.js";
 import { getStorageKeys, createPlatformStorage } from "../utils/storageHelpers.js";
-import { isInvalidSessionError, isTimeoutOrNetworkError } from "../utils/errorHandlers.js";
-import { readActiveAuthuser, clearSignedOut, isSilentRestoreSuppressed, markSignedOut, clearSsoBounceState } from "../utils/activeAuthuser.js";
 import { showBottomSheet as globalShowBottomSheet } from "../navigation/bottomSheetManager.js";
 import { useQueryClient } from '@tanstack/react-query';
 import { clearQueryCache } from "../hooks/queryClient.js";
 import { useAvatarPicker } from "../hooks/useAvatarPicker.js";
 import { useAccountStore } from "../stores/accountStore.js";
-import { logger as loggerUtil } from '@oxyhq/core';
-import { isWebBrowser } from "../hooks/useWebSSO.js";
-import { isCrossApexWeb, CrossApexDirectSignInError } from "../../utils/crossApex.js";
-import { createInSessionRefreshHandler, startTokenRefreshScheduler } from "./inSessionTokenRefresh.js";
-import { mintSessionViaPerApexIframe } from "./silentSessionRestore.js";
-import { createSessionClient, deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf } from "../session/index.js";
+import { isWebBrowser } from "../utils/isWebBrowser.js";
+import { createSessionClient, createPlatformAuthStateStore, deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf } from "../session/index.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 const OxyContext = /*#__PURE__*/createContext(null);
 
 /**
  * Result of {@link OxyContextState.signInWithPassword}.
  *
- * `'ok'` — the password was accepted and the resulting session has been
- * committed into context state (the SAME path SSO / silent-restore sessions
- * use), so `isAuthenticated` / `user` are updated and the session is durably persisted;
- * the caller can proceed (e.g. navigate into the app).
+ * `'ok'` — the password was accepted and the session committed (so
+ * `isAuthenticated` / `user` are updated and the refresh family persisted).
  *
  * `'2fa_required'` — the account has two-factor auth enabled, so NO session was
- * created. The caller must complete the challenge with the returned short-lived
- * `loginToken` (`POST /security/2fa/verify-login`) before a session exists.
+ * created. Complete the challenge with the returned short-lived `loginToken`
+ * via {@link OxyContextState.completeTwoFactorSignIn}.
  */
 
-// Active-authuser persistence helpers (web localStorage; native no-op) live in
-// `../utils/activeAuthuser` so the session-management and auth-operations hooks
-// can share them without re-importing this 1k-line context file.
-
-/**
- * Per-step fail-fast budget for the cold-boot silent iframe (`silentSignIn`
- * against the per-apex `/auth/silent` host).
- *
- * This step ONLY succeeds when a durable per-apex `fedcm_session` cookie exists
- * (established by a prior `/sso` bounce). On the common reload of a logged-out
- * tab — or a tab that restores via the now-earlier stored-session step — the
- * iframe never posts a message, so the full wait would be dead latency in front
- * of the terminal `/sso` bounce. `silentSignIn` already fails fast on a load
- * error via `iframe.onerror`; this caps the no-message case. 2.5s is well above
- * a same-origin iframe handshake without blocking cold boot for several seconds.
- */
-const SILENT_IFRAME_TIMEOUT = 2500;
-
 /**
- * Per-step fail-fast budget (ms) for the native shared-key cold-boot step
- * (`signInWithSharedIdentity`).
- *
- * That step does a challenge round-trip plus a verify against the shared
- * cross-app identity key; if the device holds no shared identity it returns
- * `null` quickly, but a slow/offline network must not let it block the cold
- * boot. 8s mirrors the stored-session bearer-validation budget
- * (`VALIDATION_TIMEOUT`) since both perform comparable bounded network work; on
- * expiry the step resolves to `null` and cold boot falls through (native then
- * reaches the unauthenticated backstop, web never runs this step at all).
- */
-const SHARED_KEY_SIGNIN_TIMEOUT = 8000;
-
-/**
- * HARD overall deadline (ms) for the entire cold-boot step loop —
- * defense-in-depth so a single non-settling step can NEVER hang auth resolution
- * forever (the production regression this guards against: a browser silent
- * credential/iframe probe that ignored its own abort signal left a step's
- * promise unsettled, so `runColdBoot` never advanced to the terminal `/sso`
- * bounce and auth hung indefinitely).
- *
- * Every step ALREADY bounds its own network work (the stored-session bearer
- * validation at 8s, the silent iframe at `SILENT_IFRAME_TIMEOUT` plus its hard
- * settle). On a healthy load the FIRST recovering step wins in a
- * single round-trip (1–3s) and the chain short-circuits long before this fires.
- * This budget only trips when one of those per-step bounds regresses.
- *
- * 20s is the chosen value: comfortably ABOVE the worst-case bounded
- * stored-session path under transient slowness (the 8s parallel validation
- * window plus a `switchSession` round-trip) so a genuinely slow-but-healthy
- * reload is never cut off, yet well BELOW the ~28–30s the previous
- * probe-first ordering took — and, critically, finite, so the user can never
- * sit on an indefinite spinner. When the deadline trips, `runColdBoot` keeps
- * iterating to the terminal `sso-bounce` step (whose navigation side effect
- * runs synchronously), so a genuine no-local-session first visit STILL reaches
- * the cross-domain `/sso` fallback. Native runs only the stored-session step,
- * which is bounded well under this, so the deadline never alters native flow.
+ * Fallback client-session validity window (ms) — 7 days — applied when a
+ * committed session does not carry an explicit `expiresAt`. This is only a
+ * local display hint for the multi-session store; the server remains the source
+ * of truth for actual session expiry.
  */
-const COLD_BOOT_OVERALL_DEADLINE = 20000;
+const DEFAULT_SESSION_VALIDITY_MS = 7 * 24 * 60 * 60 * 1000;
 
 /**
- * How long cold boot WAITS for the post-ladder SessionClient handoff
- * (`addCurrentAccount` + `start` + `syncFromClient`) before it resolves auth
- * and stops blocking. Once a ladder step planted a token the user is already
+ * How long the cold boot WAITS for the post-boot SessionClient handoff
+ * (`addCurrentAccount` + `start` + `syncFromClient`) before it resolves auth and
+ * stops blocking. Once a boot step planted a token the user is already
  * authenticated — the handoff only populates the multi-account set and the
  * server-authoritative active account, and those also arrive via the socket
- * subscription wired in `useEffect`. So on a slow/unresponsive backend we stop
- * AWAITING the handoff here (it keeps running in the background and projects
- * when it lands) rather than delaying `markAuthResolved` — otherwise the two
- * sequential `HttpService`-bounded REST calls could push auth resolution up to
- * ~10s past the ladder's own budget, reintroducing the exact spinner-stall
- * `COLD_BOOT_OVERALL_DEADLINE` exists to prevent. On the normal fast path the
- * handoff completes well within this, so the correct account shows with no
- * flash.
+ * subscription. So on a slow backend we stop AWAITING the handoff here (it keeps
+ * running in the background and projects when it lands) rather than delaying
+ * auth resolution.
  */
 const SESSION_HANDOFF_DEADLINE = 6000;
 
-/**
- * Per-session soft timeout (ms) for the parallel stored-session validation in
- * `restoreStoredSession`. Each `validateSession` call races against this timer
- * so a single slow/offline session never blocks the whole startup validation
- * sweep. Sessions that don't answer in time are treated as unvalidated and kept
- * in the persisted ID list; only explicit invalid-session responses are pruned.
- */
-const VALIDATION_TIMEOUT = 8000;
-const VALIDATION_TIMEOUT_RESULT = 'validation-timeout';
-/**
- * Fallback client-session validity window (ms) — 7 days — applied when a
- * restored account/session does not carry an explicit `expiresAt`. This is only
- * a local display/bookkeeping hint for the multi-session store; the server
- * remains the source of truth for actual session expiry. Used in the refresh
- * cookie restore, stored-session restore, and web-SSO session paths.
- */
-const DEFAULT_SESSION_VALIDITY_MS = 7 * 24 * 60 * 60 * 1000;
-
-/**
- * Minimum interval (ms) between visibility-driven IdP `/auth/session-check`
- * probes. Debounces the hidden-iframe session check so rapid tab focus/blur
- * cycles can't spawn a check-iframe storm; at most one probe runs per window.
- */
-const IDP_SESSION_CHECK_COOLDOWN = 30000;
+/** The internal commit input — a session plus the device-first extras that are
+ * not on the public `SessionLoginResponse` (a rotating refresh token, a device
+ * token). All extras optional so `SessionLoginResponse` is assignable. */
 
-/**
- * Hard timeout (ms) for a single visibility-driven IdP `/auth/session-check`
- * iframe. If the IdP never posts a `oxy-session-check` message back, the iframe
- * and its listener are torn down after this budget so a non-responsive check
- * can never leak an iframe or a `message` listener.
- */
-const IDP_SESSION_CHECK_TIMEOUT = 5000;
 function getHttpStatus(error) {
   if (!error || typeof error !== 'object') {
     return undefined;
@@ -173,51 +79,6 @@ function getHttpStatus(error) {
 function isUnauthorizedStatus(error) {
   return getHttpStatus(error) === 401;
 }
-
-/**
- * Whether `idpOrigin` is a same-site, first-party host of the current page —
- * i.e. it shares the page's registrable apex (last two labels), so a "no
- * session" answer from its `/auth/session-check` iframe is authoritative for
- * THIS app and may force a local sign-out.
- *
- * On a cross-site IdP (or any host whose relationship to the page can't be
- * positively established) this returns `false`, so the visibility-driven check
- * may surface a session-ended toast but MUST NOT clear local state — a
- * third-party / undetermined IdP answer can never force logout. Returns `false`
- * off-browser.
- */
-function isSameSiteIdP(idpOrigin) {
-  // Native defines a global `window` but no `window.location`; guard the
-  // latter so reading `.hostname` can never throw off-browser. (Only reachable
-  // from the web-only visibility check, but kept robust for parity.)
-  if (typeof window === 'undefined' || typeof window.location === 'undefined') {
-    return false;
-  }
-  let idpHostname;
-  try {
-    idpHostname = new URL(idpOrigin).hostname;
-  } catch (parseError) {
-    if (__DEV__) {
-      loggerUtil.debug('Invalid IdP origin while checking same-site session status', {
-        component: 'OxyContext'
-      }, parseError);
-    }
-    return false;
-  }
-  const pageHostname = window.location.hostname;
-  if (!idpHostname || !pageHostname) return false;
-  if (idpHostname === pageHostname) return true;
-  const pageApex = registrableApex(pageHostname);
-  const idpApex = registrableApex(idpHostname);
-  // Require a real registrable apex (not a shared/public suffix) AND an exact
-  // apex match AND that the IdP host is the page apex itself or a subdomain of it.
-  if (!pageApex || idpApex !== pageApex) return false;
-  return idpHostname === pageApex || idpHostname.endsWith(`.${pageApex}`);
-}
-function isOnSsoCallbackPath() {
-  return isWebBrowser() && window.location.pathname === SSO_CALLBACK_PATH;
-}
-const useBrowserLayoutEffect = typeof document !== 'undefined' ? useLayoutEffect : useEffect;
 let cachedUseFollowHook = null;
 const loadUseFollowHook = () => {
   if (cachedUseFollowHook) {
@@ -260,19 +121,11 @@ export const OxyProvider = ({
     if (providedOxyServices) {
       oxyServicesRef.current = providedOxyServices;
     } else if (baseURL) {
-      // Target the CENTRAL IdP for TRUE cross-domain SSO. Every RP
-      // (mention.earth, homiio.com, alia.onl, …) delegates to the one central
-      // `auth.oxy.so` — it owns the host-only `fedcm_session` cookie and the
-      // central session store reached via `api.oxy.so`, so a single sign-in
-      // there is observed by all RPs through the opaque-code `/sso` bounce.
-      // `resolveCentralAuthUrl(authWebUrl)` returns the explicit `authWebUrl`
-      // prop when provided (explicit always wins) and the central default
-      // otherwise. This is NOT per-apex auto-detection — central SSO is
-      // deliberately central. A consumer-provided `OxyServices` instance is
-      // never mutated; only the baseURL-only construction path applies this.
+      // `authWebUrl` now only points the OAuth "Sign in with Oxy" third-party
+      // link builder at the central auth host; there is no cold-boot redirect.
       oxyServicesRef.current = new OxyServices({
         baseURL,
-        authWebUrl: resolveCentralAuthUrl(authWebUrl),
+        authWebUrl,
         authRedirectUri
       });
     } else {
@@ -280,6 +133,15 @@ export const OxyProvider = ({
     }
   }
   const oxyServices = oxyServicesRef.current;
+
+  // The device-first persisted auth-state store (per-origin refresh family on
+  // web; SecureStore session blob + shared-keychain device token on native).
+  // Built ONCE per provider mount.
+  const authStoreRef = useRef(null);
+  if (!authStoreRef.current) {
+    authStoreRef.current = createPlatformAuthStateStore();
+  }
+  const authStore = authStoreRef.current;
   const {
     user,
     isAuthenticated,
@@ -299,13 +161,6 @@ export const OxyProvider = ({
   })));
   const [tokenReady, setTokenReady] = useState(true);
   const [hasAccessToken, setHasAccessToken] = useState(() => Boolean(oxyServices.getAccessToken()));
-  // Whether the FIRST cold-boot auth restore has concluded. Starts `false`
-  // (auth undetermined) and flips to `true` exactly once — monotonic, never
-  // reverts. It now flips the MOMENT a session commits (the common reload case
-  // unblocks immediately, without waiting for the rest of the cold-boot chain),
-  // with the restore `finally` as the no-session/error backstop. The ref makes
-  // the flip idempotent across both sites so the setters fire at most once. See
-  // `isAuthResolved` on the context type for the consumer contract.
   const [authResolved, setAuthResolved] = useState(false);
   const authResolvedRef = useRef(false);
   const userRef = useRef(user);
@@ -313,24 +168,12 @@ export const OxyProvider = ({
   userRef.current = user;
   isAuthenticatedRef.current = isAuthenticated;
   const [initialized, setInitialized] = useState(false);
-  const [ssoCallbackIntercepting, setSsoCallbackIntercepting] = useState(false);
   const setAuthState = useAuthStore.setState;
 
   // Keep the shared `oxyClient` singleton's token store in lockstep with the
-  // session owned by THIS provider's instance. Many apps construct their api
-  // clients against the exported `oxyClient` singleton (reading
-  // `oxyClient.getAccessToken()` to build Authorization headers) while passing
-  // only `baseURL` to OxyProvider — in which case the provider owns a DIFFERENT
-  // `OxyServices` instance and the singleton would otherwise never receive the
-  // token, producing `Authorization: Bearer null`.
-  //
-  // Subscribing to `onTokensChanged` mirrors EVERY token mutation — sign-in,
-  // session restore, switch, silent refresh, and sign-out/clear — onto the
-  // singleton at the single source of truth in @oxyhq/core, with no per-app
-  // plumbing and regardless of which auth code path fired.
-  //
-  // When the app passed the singleton itself as `oxyServices` (Mention's
-  // pattern), `oxyServices === oxyClient`, so we skip the redundant self-write.
+  // session owned by THIS provider's instance (many apps build API clients
+  // against the exported singleton while passing only `baseURL` here). Skipped
+  // when the app passed the singleton itself as `oxyServices`.
   useEffect(() => {
     if (oxyServices === oxyClient) {
       return;
@@ -342,10 +185,6 @@ export const OxyProvider = ({
         oxyClient.clearTokens();
       }
     };
-
-    // Seed the singleton with whatever token the instance already holds (it may
-    // have been planted synchronously before this effect ran — e.g. a token set
-    // during the same tick as mount), then keep it in sync going forward.
     applyToSingleton(oxyServices.getAccessToken());
     return oxyServices.onTokensChanged(applyToSingleton);
   }, [oxyServices]);
@@ -357,39 +196,16 @@ export const OxyProvider = ({
     }
   }, []);
   const storageKeys = useMemo(() => getStorageKeys(storageKeyPrefix), [storageKeyPrefix]);
-
-  // The app's Oxy OAuth client id surfaced on the context so the cross-app
-  // device sign-in components (SignInModal / OxyAuthScreen) can identify the
-  // requesting app to `POST /auth/session/create`. Normalized to a trimmed
-  // non-empty string, or `null` when the consumer did not configure one — the
-  // sign-in components surface a clear configuration error in that case rather
-  // than falling back to any display string.
   const clientId = useMemo(() => {
     const trimmed = clientIdProp?.trim();
     return trimmed ? trimmed : null;
   }, [clientIdProp]);
 
-  // Storage initialization.
-  //
-  // `storage` (state) drives render-time gating (`isStorageReady`) and the
-  // hooks below. But it is `null` for a brief window after mount while
-  // `createPlatformStorage()` resolves (a microtask on web; a dynamic
-  // `import()` on native). Any persistence path that fires during that window
-  // — e.g. an interactive password sign-in the instant the screen mounts —
-  // would read `storage === null` and SILENTLY skip writing the session,
-  // leaving the user signed-in in-memory but with nothing to restore on
-  // reload.
-  //
-  // To make persistence robust regardless of timing we ALSO expose the storage
-  // as an awaitable promise (`getReadyStorage`). Persistence code awaits the
-  // ready instance instead of branching on the possibly-null state, so a write
-  // is never silently dropped just because it raced storage init.
+  // Local display/bookkeeping storage (session id list, language). Distinct
+  // from `authStore` (the durable credential blob). Exposed as an awaitable so
+  // a persistence write is never dropped because it raced storage init.
   const storageRef = useRef(null);
   const [storage, setStorage] = useState(null);
-
-  // A single, stable deferred that resolves with the initialized storage. Built
-  // lazily via a ref initializer so the resolver is captured exactly once and
-  // the promise identity is stable across renders.
   const buildStorageDeferred = () => {
     let resolve = () => undefined;
     const promise = new Promise(res => {
@@ -405,40 +221,9 @@ export const OxyProvider = ({
     storageReadyRef.current = buildStorageDeferred();
   }
   const storageReady = storageReadyRef.current;
-
-  // Resolve the storage instance that is guaranteed to be ready. Returns the
-  // already-initialized instance synchronously when available, otherwise awaits
-  // the init promise. Never resolves to `null`.
-  const getReadyStorage = useCallback(() => {
-    if (storageRef.current) {
-      return Promise.resolve(storageRef.current);
-    }
-    return storageReady.promise;
-  }, [storageReady]);
-
-  // Clear the durable "had a signed-in Oxy session before" hint.
-  //
-  // The hint (`storageKeys.priorSession`) is WRITTEN whenever a session is
-  // established/restored — every commit funnels through `persistSessionDurably`,
-  // and the stored-session reload winner sets it directly to backfill
-  // pre-existing installs. It lives in the SAME `storageKeyPrefix`-scoped
-  // durable store as the session ids, so it SURVIVES a session expiring; it is
-  // cleared ONLY here, on EXPLICIT full sign-out (wired into `clearAllAccountData`
-  // and the `useAuthOperations` logout paths — never the passive token-expiry
-  // path). At cold boot the hint is read into `hadPriorSession` and feeds
-  // `allowSsoBounce`: a RETURNING visitor (hint present) whose local session has
-  // lapsed still gets ONE terminal `/sso` establish bounce so a central-only
-  // cross-domain session recovers, while a truly first-time anonymous visitor is
-  // never force-redirected.
-  const clearPriorSessionHint = useCallback(async () => {
-    const readyStorage = await getReadyStorage();
-    await readyStorage.removeItem(storageKeys.priorSession);
-  }, [getReadyStorage, storageKeys.priorSession]);
   useEffect(() => {
     let mounted = true;
     createPlatformStorage().then(storageInstance => {
-      // Resolve the ready-promise even if the component unmounted: in-flight
-      // persistence awaiting it must still complete against a real store.
       storageRef.current = storageInstance;
       storageReady.resolve(storageInstance);
       if (mounted) {
@@ -458,10 +243,6 @@ export const OxyProvider = ({
       mounted = false;
     };
   }, [logger, onError, storageReady]);
-
-  // Offline queuing is now handled by TanStack Query mutations
-  // No need for custom offline queue
-
   const {
     currentLanguage,
     metadata: currentLanguageMetadata,
@@ -501,117 +282,72 @@ export const OxyProvider = ({
     queryClient
   });
 
-  // Session-sync integration layer (Fase 3-A -> 3-B). Built ONCE per
-  // `oxyServices` instance via a lazy ref (mirrors the `oxyServicesRef`
-  // pattern above) so the underlying `SessionClient` — and its socket
-  // connection, once started — is never recreated across renders.
-  //
-  // ADDITIVE + INERT for this task: `client.start()` is NOT called here (that
-  // is Task 2's job, which also retires the 8-step cold boot below). Until
-  // then `client.getState()` never advances past `null`, so `syncFromClient`
-  // is a guaranteed no-op in production — the existing cold-boot-driven state
-  // remains the sole authority. The wiring exists so the projection can be
-  // exercised in isolation against a controlled client before the authority
-  // flip.
+  // Refs so callbacks below can invoke the latest session-management functions
+  // without widening dependency arrays.
+  const switchSessionRef = useRef(switchSession);
+  switchSessionRef.current = switchSession;
+  const clearSessionStateRef = useRef(clearSessionState);
+  clearSessionStateRef.current = clearSessionState;
+  const setActiveSessionIdRef = useRef(setActiveSessionId);
+  setActiveSessionIdRef.current = setActiveSessionId;
+  const loginSuccessRef = useRef(loginSuccess);
+  loginSuccessRef.current = loginSuccess;
+  const onAuthStateChangeRef = useRef(onAuthStateChange);
+  onAuthStateChangeRef.current = onAuthStateChange;
+
+  // Flip the auth-resolution gate (`authResolved` + `tokenReady`) the moment a
+  // session commits or the boot concludes signed out. Idempotent + monotonic.
+  const markAuthResolved = useCallback(() => {
+    if (authResolvedRef.current) {
+      return;
+    }
+    authResolvedRef.current = true;
+    setTokenReady(true);
+    setAuthResolved(true);
+  }, []);
+  const markAuthResolvedRef = useRef(markAuthResolved);
+  markAuthResolvedRef.current = markAuthResolved;
+
+  // Server-authoritative device session client. Built ONCE per `oxyServices`
+  // instance. `onUnauthenticated` (a device signout-all pushed over the socket,
+  // or bootstrapped as zero-account) clears the persisted store + local state so
+  // a reload does not try to restore a session the device no longer has.
   const sessionClientPairRef = useRef(null);
   if (!sessionClientPairRef.current) {
-    sessionClientPairRef.current = createSessionClient(oxyServices);
+    sessionClientPairRef.current = createSessionClient(oxyServices, authStore, () => {
+      clearPersistedAuthSafe(authStore, logger);
+      void clearSessionStateRef.current().catch(clearError => {
+        logger('Failed to clear local state on remote sign-out', clearError);
+      });
+    });
   }
   const {
     client: sessionClient,
     host: sessionClientHost
   } = sessionClientPairRef.current;
 
-  // Cold-boot registration dedup (Task 5). `handleWebSSOSession` (declared
-  // below) is the single commit funnel for every web ladder step that mints a
-  // session (`sso-return`, `shared-key-signin`, `silent-iframe`) — it registers
-  // the recovered account into the device set
-  // itself (`sessionClient.addCurrentAccount()`). The cold-boot post-ladder
-  // handoff ALSO registers, but only as a FALLBACK for the `stored-session`
-  // step, which commits through a completely different path
-  // (`switchSessionRef`) and never touches `sessionClient` on its own. This
-  // ref lets the handoff detect "did a ladder step already register this
-  // boot?" and skip a redundant second `POST /session/device/add`. Reset at
-  // the start of every cold-boot pass.
-  const registeredDuringBootRef = useRef(false);
-
-  // Projects `client.getState()` onto the exposed `sessions` / `activeSessionId`
-  // / `user` via the SAME setters the existing cold-boot/session-management
-  // paths use. This is the SOLE authority for both a locally-initiated mutation
-  // (switch/logout resolving here) AND a REMOTELY-pushed `session_state` (the
-  // `device:<deviceId>` socket owned by `client.start()`, subscribed to below) —
-  // there is no per-domain `useSessionSocket` anymore.
-  //
-  // GAP FIX (Task 4): when the pushed/bootstrapped state reports ZERO device
-  // accounts, this device has been fully signed out — either by the LOCAL
-  // `logout()`/`logoutAll()` mutation (which also runs its own explicit
-  // cleanup) or, just as importantly, by a REMOTE actor (another tab/device
-  // removing the last session, or an admin revoking every device account)
-  // pushing that same empty state over the socket. The prior per-domain
-  // `useSessionSocket` forced a local sign-out in this situation
-  // (`triggerLocalSignOut`); without an equivalent here a remote full sign-out
-  // would leave `user`/`isAuthenticated`/the bearer token stale until the next
-  // 401. Route through the SAME `clearSessionState()` a local full sign-out
-  // uses (authStore reset, token clear, query-cache clear, storage clear) —
-  // idempotent with the local-logout caller's own explicit call.
-  //
-  // DELIBERATE-SIGN-OUT GUARD (Task 5): a zero-account state — however it
-  // arrived — is just as terminal as a local `logout()`/`logoutAll()`, so it
-  // sets the SAME durable "deliberately signed out" flag (web-only,
-  // best-effort) that those two callers set directly. Without this, a remote
-  // full wipe would leave the flag unset, and the `silent-iframe` cold-boot
-  // step could silently re-mint a session from a still-live per-apex
-  // `fedcm_session` cookie right after this device was authoritatively signed
-  // out everywhere.
-  //
-  // REMOTE-SIGN-OUT SUPPRESSION FIX (review H1): the terminal `sso-bounce`
-  // cold-boot step is gated on the durable prior-session hint
-  // (`allowSsoBounce` = `hasPriorSession || hasLocalSession`), NOT on the
-  // deliberately-signed-out flag set above. Leaving that hint in place after a
-  // REMOTE full sign-out means the next reload still performs one terminal
-  // `/sso` establish bounce, which can silently re-mint a session from a
-  // still-live central `fedcm_session` — signing the user back in right after
-  // they were signed out everywhere. Clear the SAME cleanup set the LOCAL
-  // `logout()`/`logoutAll()` paths use (`useAuthOperations.ts`) — SSO bounce
-  // state + the prior-session hint — so a remote sign-out is indistinguishable
-  // from a local one to the next cold boot.
+  // Projects `client.getState()` onto the exposed `sessions`/`activeSessionId`/
+  // `user`. Sole authority for both locally-initiated mutations (switch/logout)
+  // AND remotely-pushed `session_state` over the `device:<deviceId>` socket.
   const syncFromClient = useCallback(async () => {
     const state = sessionClient.getState();
     if (state === null) {
-      // INERT: no session state has been bootstrapped (client.start() has not
-      // run). Never overwrite the existing cold-boot-driven state.
       return;
     }
     if (state.accounts.length === 0) {
       sessionClientHost.setCurrentAccountId(null);
-      if (isWebBrowser()) {
-        markSignedOut();
-      }
-      clearSsoBounceState();
-      clearPriorSessionHintSafe(clearPriorSessionHint, logger);
+      clearPersistedAuthSafe(authStore, logger);
       await clearSessionState();
       return;
     }
-    // LAST-WRITE-WINS GUARD (review I3): `syncFromClient` is called
-    // concurrently — once per socket `notify()` push AND once per direct
-    // mutation call — and each invocation captures `state` before an async
-    // profile fetch (`getUsersByIds`). `SessionClient`'s own state is
-    // monotonic by revision, but this projection previously was not: a
-    // SLOWER, OLDER fetch resolving AFTER a newer one would still apply its
-    // now-stale captured `state`, clobbering `user`/`sessions`/
-    // `activeSessionId` back to an outdated account. Capture the revision
-    // this fetch is FOR, then after the await, re-read the client's current
-    // state and bail if it has since moved past the captured revision — a
-    // fresher call has already applied (or will apply) the current truth.
+    // Last-write-wins guard: capture the revision this projection is for, then
+    // after the async profile fetch bail if a fresher state has landed.
     const capturedRevision = state.revision;
     const ids = accountIdsOf(state);
     let users = [];
     try {
       users = ids.length > 0 ? await oxyServices.getUsersByIds(ids) : [];
     } catch (fetchError) {
-      // Invoked fire-and-forget from the socket `notify()` subscription, so a
-      // rejected profile fetch would surface as an unhandled rejection. Log and
-      // bail; the next `notify()`/mutation will re-project the current truth.
       logger('Failed to resolve account profiles during syncFromClient', fetchError);
       return;
     }
@@ -627,7 +363,9 @@ export const OxyProvider = ({
       loginSuccess(activeUser);
     }
     sessionClientHost.setCurrentAccountId(latest.activeAccountId);
-  }, [oxyServices, sessionClient, sessionClientHost, updateSessions, setActiveSessionId, loginSuccess, clearSessionState, clearPriorSessionHint, logger]);
+  }, [oxyServices, sessionClient, sessionClientHost, authStore, updateSessions, setActiveSessionId, loginSuccess, clearSessionState, logger]);
+  const syncFromClientRef = useRef(syncFromClient);
+  syncFromClientRef.current = syncFromClient;
   useEffect(() => {
     return sessionClient.subscribe(() => {
       void syncFromClient();
@@ -639,13 +377,13 @@ export const OxyProvider = ({
     logoutAll
   } = useAuthOperations({
     oxyServices,
+    store: authStore,
     storage,
     activeSessionId,
     setActiveSessionId,
     updateSessions,
     saveActiveSessionId,
     clearSessionState,
-    clearPriorSessionHint,
     switchSession,
     sessionClient,
     syncFromClient,
@@ -658,13 +396,8 @@ export const OxyProvider = ({
     setAuthState,
     logger
   });
-
-  // Clear all account data (sessions, cache, etc.)
   const clearAllAccountData = useCallback(async () => {
-    // Clear TanStack Query cache (in-memory)
     queryClient.clear();
-
-    // Clear persisted query cache
     if (storage) {
       try {
         await clearQueryCache(storage);
@@ -672,22 +405,13 @@ export const OxyProvider = ({
         logger('Failed to clear persisted query cache', error);
       }
     }
-
-    // Clear session state (sessions, activeSessionId, storage)
     await clearSessionState();
-
-    // Explicit FULL sign-out: drop the durable returning-user hint so the next
-    // cold boot treats this device as a first-time anonymous visitor (no forced
-    // `/sso` bounce). NOT done on the passive token-expiry path, so an expired
-    // session still recovers via a returning-user bounce.
-    await clearPriorSessionHint();
-
-    // Reset account store
+    // Explicit FULL wipe: also drop the persisted refresh family so a reload
+    // finds nothing to restore.
+    await authStore.clear();
     useAccountStore.getState().reset();
-
-    // Clear HTTP service cache
     oxyServices.clearCache();
-  }, [queryClient, storage, clearSessionState, clearPriorSessionHint, logger, oxyServices]);
+  }, [queryClient, storage, clearSessionState, authStore, logger, oxyServices]);
   const {
     getDeviceSessions,
     logoutAllDeviceSessions,
@@ -701,13 +425,12 @@ export const OxyProvider = ({
   });
   const useFollowHook = loadUseFollowHook();
 
-  // Refs for mutable callbacks to avoid stale closures in restoreSessionsFromStorage (#187)
-  const switchSessionRef = useRef(switchSession);
-  switchSessionRef.current = switchSession;
-  const updateSessionsRef = useRef(updateSessions);
-  updateSessionsRef.current = updateSessions;
-  const clearSessionStateRef = useRef(clearSessionState);
-  clearSessionStateRef.current = clearSessionState;
+  // Token-change side effects: an invalidated bearer (HttpService clears tokens
+  // on an unrecoverable 401 and emits `null`) must locally sign out an
+  // authenticated user so `isAuthenticated` never lingers true with no token.
+  // The persisted store is NOT cleared here — the refresh handler already
+  // cleared it if the family was revoked; a transient null leaves it intact so a
+  // later reload can still restore.
   const clearingInvalidTokenRef = useRef(false);
   useEffect(() => {
     const handleTokenChange = accessToken => {
@@ -740,1124 +463,279 @@ export const OxyProvider = ({
     return oxyServices.onTokensChanged(handleTokenChange);
   }, [logger, oxyServices]);
 
-  // In-session access-token refresh (SDK-owned; every Expo RP inherits it).
-  //
-  // The services path never installed an `authRefreshHandler`, so the owner
-  // `HttpService.refreshAccessToken` short-circuited to null and a 15-minute
-  // access token expired with the app open while `isAuthenticated` stayed true —
-  // a zombie logged-in state whose cross-apex feed calls 401-looped. Here we (1)
-  // install a handler that re-mints a fresh token WITHOUT a reload using the SAME
-  // durable silent-restore arms cold boot uses, and (2) start a proactive
-  // scheduler that refreshes ~60s before expiry (and on tab-focus / app-
-  // foreground) so the common case never even hits the reactive 401 path. The
-  // linked client (`createLinkedClient`) delegates its refresh back to this owner
-  // handler, so it is fixed for free.
-  //
-  // Runs once per `oxyServices` instance (stable, ref-constructed), and BEFORE
-  // any cold-boot request can 401: cold boot is gated on async storage init, so
-  // this synchronous mount effect installs the handler first. On cleanup the
-  // handler is detached and the scheduler torn down (timer + foreground listener)
-  // so nothing leaks across a provider remount. `setAuthRefreshHandler` is
-  // optional-chained to tolerate partial test stubs.
+  // Unified in-session refresh (SDK-owned; every RP inherits it). Installs the
+  // ONE core refresh handler (rotate the persisted refresh family; native falls
+  // back to the shared keychain) plus the proactive scheduler that refreshes
+  // ~60s before expiry and on tab-focus. Replaces the deleted services-local
+  // `inSessionTokenRefresh` module.
   useEffect(() => {
-    oxyServices.httpService.setAuthRefreshHandler?.(createInSessionRefreshHandler(oxyServices));
+    const dispose = installAuthRefreshHandler({
+      oxy: oxyServices,
+      store: authStore
+    });
     const scheduler = startTokenRefreshScheduler(oxyServices);
     return () => {
       scheduler.dispose();
-      oxyServices.httpService.setAuthRefreshHandler?.(null);
+      dispose();
     };
-  }, [oxyServices]);
-
-  // Durable, navigation-safe session persistence.
-  //
-  // Writes the active-session id and appends the session id to the durable
-  // `session_ids` list, awaiting the READY storage instance (never the possibly
-  // -null `storage` state) so a write is never dropped because it raced storage
-  // init. Callers MUST invoke this BEFORE any work that can trigger a route
-  // navigation (`onAuthStateChange`) — navigation can interrupt a still-pending
-  // async write, which is exactly what once left `session_ids` empty after a
-  // successful sign-in. Shared by the SSO/silent-restore path and the cold-boot
-  // refresh-cookie restore so both land the same durable record.
-  const persistSessionDurably = useCallback(async sessionId => {
-    const readyStorage = await getReadyStorage();
-    await readyStorage.setItem(storageKeys.activeSessionId, sessionId);
-    const existingIds = await readyStorage.getItem(storageKeys.sessionIds);
-    let sessionIds = [];
-    try {
-      sessionIds = existingIds ? JSON.parse(existingIds) : [];
-    } catch (parseError) {
-      logger('Failed to parse persisted session ids; replacing corrupted storage value', parseError);
-    }
-    if (!sessionIds.includes(sessionId)) {
-      sessionIds.push(sessionId);
-      await readyStorage.setItem(storageKeys.sessionIds, JSON.stringify(sessionIds));
-    }
-    // A session is now durably committed — set the returning-user hint so a
-    // future cold boot whose local session has lapsed still gets ONE `/sso`
-    // establish bounce (see `markPriorSessionHint`). Every web commit path
-    // (silent iframe / SSO return / password / cookie restore) funnels
-    // through here, so this is the single chokepoint for the hint.
-    await readyStorage.setItem(storageKeys.priorSession, '1');
-  }, [getReadyStorage, logger, storageKeys.activeSessionId, storageKeys.sessionIds, storageKeys.priorSession]);
-
-  // Refs so the cold-boot restore can plant session state without widening its
-  // dependency array (mirrors the existing ref pattern above).
-  const setActiveSessionIdRef = useRef(setActiveSessionId);
-  setActiveSessionIdRef.current = setActiveSessionId;
-  const loginSuccessRef = useRef(loginSuccess);
-  loginSuccessRef.current = loginSuccess;
-  const onAuthStateChangeRef = useRef(onAuthStateChange);
-  onAuthStateChangeRef.current = onAuthStateChange;
-
-  // Flip the auth-resolution gate (`authResolved` + `tokenReady`) the MOMENT a
-  // session commits, instead of waiting for the whole cold-boot chain to finish.
-  // Idempotent and monotonic via `authResolvedRef`: the first call wins and the
-  // setters fire at most once, so the restore `finally` backstop becomes a no-op
-  // once a commit site has already marked resolution. Called from EVERY place a
-  // user is actually committed (the iframe/SSO path
-  // `handleWebSSOSession` and the stored-session path) so the common reload
-  // case unblocks the loading gate without sitting behind the remaining
-  // (now-skipped) cold-boot steps.
-  const markAuthResolved = useCallback(() => {
-    if (authResolvedRef.current) {
-      return;
-    }
-    authResolvedRef.current = true;
-    setTokenReady(true);
-    setAuthResolved(true);
-  }, []);
-  const markAuthResolvedRef = useRef(markAuthResolved);
-  markAuthResolvedRef.current = markAuthResolved;
-
-  // `handleWebSSOSession` is declared further down (it depends on values that
-  // are only available there). The iframe/SSO cold-boot steps need to commit
-  // a recovered session through it, so we route the call through a ref that is
-  // populated once the callback exists. The ref is assigned synchronously on
-  // every render before the cold-boot effect can fire (the effect is gated on
-  // `storage` + `initialized`, both of which settle after first render).
-  const handleWebSSOSessionRef = useRef(null);
-
-  // Native (and offline) stored-session restore — the ONLY restore path that
-  // runs on React Native, and the web fallback when no cross-domain step won.
-  //
-  // Stored-session restore. Web uses this only as a fast local winner after
-  // URL-return handling; native uses it as the durable SecureStore path. Native
-  // first plants the shared access token from KeyManager, then validates the
-  // stored session ids with the bearer already in memory.
-  const restoreStoredSession = useCallback(async () => {
-    if (!storage) {
-      return false;
-    }
-    const storedSessionIdsJson = await storage.getItem(storageKeys.sessionIds);
-    const storedSessionIdsFromStorage = storedSessionIdsJson ? JSON.parse(storedSessionIdsJson) : [];
-    let storedActiveSessionId = await storage.getItem(storageKeys.activeSessionId);
-    // OPTIONAL HINT ONLY (no longer a gate). Nothing writes the active-`authuser`
-    // marker since the SessionClient cutover (`writeActiveAuthuser` was deleted),
-    // so it is `null` on every fresh install; when a legacy value is present it
-    // is used purely to backfill `clientSession.authuser` for the active session
-    // below. It MUST NOT decide whether restore is attempted — see the guard.
-    const storedActiveAuthuser = isWebBrowser() ? readActiveAuthuser() : null;
-
-    // On web with no in-memory bearer, bail ONLY when there is genuinely nothing
-    // to restore — neither a stored active id NOR any stored session ids. A
-    // surviving `sessionIds` list (e.g. the active-id key was removed after a
-    // server-side revocation while sibling sessions remain) MUST still be
-    // validated over the network and have a valid session elected as active
-    // below. The old guard also required the deleted `activeAuthuser` marker,
-    // which since the cutover is never written — that made EVERY web reload
-    // whose local bearer had lapsed bail before any validation. Native always
-    // proceeds (it plants the shared KeyManager bearer next).
-    if (isWebBrowser() && !oxyServices.getAccessToken() && storedActiveSessionId === null && storedSessionIdsFromStorage.length === 0) {
-      return false;
-    }
-    const nativeSharedSession = !isWebBrowser() ? await KeyManager.getSharedSession().catch(() => null) : null;
-    if (nativeSharedSession?.accessToken) {
-      oxyServices.setTokens(nativeSharedSession.accessToken);
-      storedActiveSessionId = storedActiveSessionId ?? nativeSharedSession.sessionId;
-    }
-    const storedSessionIds = Array.from(new Set([...storedSessionIdsFromStorage, ...(nativeSharedSession?.sessionId ? [nativeSharedSession.sessionId] : [])]));
-    let validSessions = [];
-    let unvalidatedSessionIds = [];
-    if (storedSessionIds.length > 0) {
-      // Validate all sessions in parallel (with a per-session timeout) to avoid
-      // sequential blocking that freezes the app on startup
-      const results = await Promise.allSettled(storedSessionIds.map(async sessionId => {
-        const timeoutPromise = new Promise(resolve => setTimeout(() => resolve(VALIDATION_TIMEOUT_RESULT), VALIDATION_TIMEOUT));
-        const validationPromise = oxyServices.validateSession(sessionId, {
-          useHeaderValidation: true
-        }).catch(validationError => {
-          if (!isInvalidSessionError(validationError) && !isTimeoutOrNetworkError(validationError)) {
-            logger('Session validation failed during init', validationError);
-          } else if (__DEV__ && isTimeoutOrNetworkError(validationError)) {
-            loggerUtil.debug('Session validation timeout (expected when offline)', {
-              component: 'OxyContext',
-              method: 'restoreStoredSession'
-            }, validationError);
-          }
-          return null;
-        });
-        return Promise.race([validationPromise, timeoutPromise]).then(validation => {
-          if (validation === VALIDATION_TIMEOUT_RESULT) {
-            return {
-              sessionId,
-              timedOut: true
-            };
-          }
-          if (validation?.valid && validation.user) {
-            const now = new Date();
-            const clientSession = {
-              sessionId,
-              deviceId: '',
-              expiresAt: new Date(now.getTime() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
-              lastActive: now.toISOString(),
-              userId: validation.user.id?.toString() ?? '',
-              isCurrent: sessionId === storedActiveSessionId
-            };
-            if (isWebBrowser() && sessionId === storedActiveSessionId && storedActiveAuthuser !== null) {
-              clientSession.authuser = storedActiveAuthuser;
-            }
-            return {
-              session: clientSession,
-              timedOut: false
-            };
-          }
-          return {
-            session: null,
-            timedOut: false
-          };
-        });
-      }));
-      for (const result of results) {
-        if (result.status !== 'fulfilled') continue;
-        const value = result.value;
-        if (value.timedOut) {
-          unvalidatedSessionIds.push(value.sessionId);
-        } else if (value.session) {
-          validSessions.push(value.session);
-        }
-      }
-
-      // Persist validated sessions while preserving soft-timed-out IDs. This
-      // still clears sessions that were explicitly rejected as invalid, but
-      // avoids logging out valid secondary accounts solely because the API was
-      // slow during startup.
-      updateSessionsRef.current(validSessions, {
-        merge: false,
-        preserveSessionIds: unvalidatedSessionIds
-      });
-    }
-    if (storedActiveSessionId) {
+  }, [oxyServices, authStore]);
+
+  // ── Session commit funnel ────────────────────────────────────────────────
+  // The single place a session becomes committed: plant tokens, persist the
+  // rotating refresh family, register the account into the server-authoritative
+  // device set, and hydrate the full user. Used by the QR device flow
+  // (`handleWebSession`), password sign-in, 2FA completion, and the cold boot.
+  const commitSession = useCallback(async (input, options) => {
+    if (input.accessToken) {
+      oxyServices.setTokens(input.accessToken);
+    }
+
+    // Persist the durable blob when a rotating refresh token is present
+    // (trusted-lane sign-ins). The cold boot has usually persisted already;
+    // this is idempotent. A missing refresh token means the session survives
+    // reload via the device cookie (web) / shared keychain (native) instead.
+    if (input.refreshToken && input.userId) {
       try {
-        await switchSessionRef.current(storedActiveSessionId);
-        // The stored session is committed (this is native's ONLY restore path
-        // and the common web reload winner). Unblock the auth-resolution gate
-        // immediately so the loading screen clears without waiting for the
-        // remaining cold-boot steps to be evaluated/short-circuited (idempotent).
-        markAuthResolvedRef.current();
-        // Backfill the returning-user hint. A reload winner already had the hint
-        // set at original sign-in, but pre-existing installs (signed in before
-        // this hint shipped) get it set here so their NEXT lapse-and-return still
-        // earns one `/sso` establish bounce. `storage` is non-null (guarded at
-        // the top of this callback); best-effort, never blocks restore.
-        await storage.setItem(storageKeys.priorSession, '1');
-        return true;
-      } catch (switchError) {
-        // Silently handle expected errors (invalid sessions, timeouts, network issues)
-        if (isInvalidSessionError(switchError)) {
-          // The stored active id was rejected server-side. Clear it and drop the
-          // dead session from the local view, then FALL THROUGH to the election
-          // below to promote a surviving valid session — a stale/removed active
-          // marker must not strand the other still-valid accounts.
-          await storage.removeItem(storageKeys.activeSessionId);
-          validSessions = validSessions.filter(session => session.sessionId !== storedActiveSessionId);
-          updateSessionsRef.current(validSessions, {
-            merge: false,
-            preserveSessionIds: unvalidatedSessionIds
-          });
-          // Don't log expected session errors during restoration
-        } else if (isTimeoutOrNetworkError(switchError)) {
-          // Timeout/network — the stored active session may still be valid; we
-          // just could not confirm it. Do NOT elect a different session (that
-          // could switch accounts under the user); leave restore to a retry / the
-          // remaining cold-boot steps.
-          if (__DEV__) {
-            loggerUtil.debug('Active session validation timeout (expected when offline)', {
-              component: 'OxyContext',
-              method: 'restoreStoredSession'
-            }, switchError);
-          }
-          return false;
-        } else {
-          // Only log unexpected errors, and do not elect on an ambiguous failure.
-          logger('Active session validation error', switchError);
-          return false;
-        }
+        const deviceToken = (await authStore.loadDeviceToken()) ?? undefined;
+        const next = {
+          sessionId: input.sessionId,
+          refreshToken: input.refreshToken,
+          userId: input.userId,
+          ...(deviceToken ? {
+            deviceToken
+          } : {}),
+          ...(input.accessToken ? {
+            accessToken: input.accessToken
+          } : {}),
+          ...(input.expiresAt ? {
+            expiresAt: input.expiresAt
+          } : {})
+        };
+        await authStore.save(next);
+      } catch (persistError) {
+        logger('Failed to persist auth state on commit', persistError);
       }
     }
 
-    // Election fallback. Reached when there is no usable stored active id —
-    // either it was never persisted (e.g. removed after a server-side revocation
-    // while sibling sessions survived) or it was just rejected as invalid above.
-    // Promote the FIRST validated session to active and commit it through the
-    // same `switchSession` path. The server owns which account is truly active,
-    // so any valid session is a safe provisional active — the post-restore
-    // SessionClient handoff reconciles the real active account immediately after.
-    const electedSession = validSessions[0];
-    if (electedSession) {
-      try {
-        await switchSessionRef.current(electedSession.sessionId);
-        await storage.setItem(storageKeys.activeSessionId, electedSession.sessionId);
-        await storage.setItem(storageKeys.priorSession, '1');
-        markAuthResolvedRef.current();
-        return true;
-      } catch (electionError) {
-        // Activation requires an in-memory bearer on web; without one (a plain
-        // web reload) the switch throws and recovery defers to the cross-domain
-        // cold-boot steps. Invalid/timeout/network are expected here — surface
-        // only genuinely unexpected failures.
-        if (!isInvalidSessionError(electionError) && !isTimeoutOrNetworkError(electionError)) {
-          logger('Elected session activation error', electionError);
-        }
-      }
+    // Fast local mirror so the UI updates before the server round-trip; the
+    // SessionClient projection below overwrites it with server truth.
+    if (input.userId) {
+      const now = new Date();
+      updateSessions([{
+        sessionId: input.sessionId,
+        deviceId: input.deviceId ?? '',
+        expiresAt: input.expiresAt || new Date(now.getTime() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
+        lastActive: now.toISOString(),
+        userId: input.userId,
+        isCurrent: true
+      }], {
+        merge: true
+      });
+      setActiveSessionId(input.sessionId);
     }
-    return false;
-  }, [logger, oxyServices, storage, storageKeys.activeSessionId, storageKeys.sessionIds, storageKeys.priorSession]);
-
-  // Shared in-flight `runSsoReturn` promise — see the CONCURRENCY note on
-  // `runSsoReturn` below. Lets the eager interception effect and the cold-boot
-  // `sso-return` step share one `consumeSsoReturn` invocation race-free.
-  const inFlightSsoReturnRef = useRef(null);
 
-  // Central cross-domain SSO return handler (web). A THIN wrapper over core's
-  // `consumeSsoReturn`, which performs the entire security-critical kernel —
-  // parse the IdP redirect fragment, validate the CSRF `state`, strip the
-  // fragment FIRST, exchange the opaque single-use code, restore the user's
-  // pre-bounce destination (same-origin only), and set the per-origin
-  // NO_SESSION loop breaker on every non-ok outcome — and RETURNS the exchanged
-  // session (or `null`) WITHOUT committing. We preserve services' contract by
-  // committing the returned session here via `handleWebSSOSession`. Shared by
-  // the `sso-return` cold-boot step AND the bfcache `pageshow` re-evaluation, so
-  // the same kernel runs exactly once per delivered fragment regardless of how
-  // the page was (re)shown.
-  //
-  // Returns `true` when a session was committed (caller short-circuits), `false`
-  // otherwise. Off-browser `consumeSsoReturn` is a no-op returning `null`, so
-  // this returns `false` (native never reaches it).
-  //
-  // CONCURRENCY: the eager SSO-callback interception effect and the cold-boot
-  // `sso-return` step can both invoke this in the same tick when we land on the
-  // callback path. `consumeSsoReturn` strips the fragment FIRST, so a naive
-  // second invocation would parse an already-stripped URL and return `null` —
-  // leaving the losing caller with no session (and on an `ok` outcome could let
-  // the terminal bounce fire spuriously). The FIRST call's promise is memoised in
-  // `inFlightSsoReturnRef` and SHARED with every concurrent caller, so the single
-  // `consumeSsoReturn` invocation — and its single commit via `handleWebSSOSession`
-  // — is delivered identically to both paths. Cleared once it settles so a later,
-  // genuinely-separate return (e.g. a bfcache restore) runs a fresh pass.
-  const runSsoReturn = useCallback(() => {
-    if (inFlightSsoReturnRef.current) {
-      return inFlightSsoReturnRef.current;
-    }
-    const inFlight = consumeSsoReturn(oxyServices, {
-      isWeb: isWebBrowser,
-      onExchangeError: error => {
-        if (__DEV__) {
-          loggerUtil.debug('SSO code exchange failed (treating as no session)', {
-            component: 'OxyContext',
-            method: 'runSsoReturn'
-          }, error);
-        }
-      }
-    }).then(async session => {
-      if (!session) {
-        return false;
-      }
-      const commitWebSession = handleWebSSOSessionRef.current;
-      if (!commitWebSession) {
-        return false;
+    // Register into the device set. A deliberate sign-in ACTIVATES the account
+    // (`registerAndActivate`); the cold boot only ensures membership and lets
+    // the server's own `activeAccountId` win (`addCurrentAccount`). Both then
+    // start the socket + project. Best-effort — a failure never fails the
+    // sign-in (cold boot re-registers on the next load).
+    try {
+      if (options.activate) {
+        await sessionClient.registerAndActivate(input.userId);
+      } else {
+        await sessionClient.addCurrentAccount();
       }
-      await commitWebSession(session);
-      return true;
-    }).finally(() => {
-      inFlightSsoReturnRef.current = null;
-    });
-    inFlightSsoReturnRef.current = inFlight;
-    return inFlight;
-  }, [oxyServices]);
-
-  // Cold boot — the single, ordered, short-circuit session-recovery sequence,
-  // consuming the SAME `runColdBoot` core primitive as `WebOxyProvider`. The
-  // FIRST step that yields a session wins; every later step is skipped. Each
-  // web-only step is gated by `isWebBrowser()`, so on native ONLY
-  // `stored-session` runs.
-  //
-  // Order (web): SSO return → stored session → shared-key sign-in (native
-  // only, disabled here) → silent iframe (per-apex, the durable reload path)
-  // → SSO bounce (terminal). This is a pure TOKEN-ACQUISITION ladder — it
-  // mints the first per-domain access token by whichever means recovers one
-  // fastest. Once a token is acquired (or the ladder exhausts), the
-  // SERVER-authoritative `SessionClient` takes over: `addCurrentAccount` +
-  // `start` bootstrap the device session set and multi-account/active-account
-  // state from `GET /session/device/state`, so WHICH account is active is
-  // decided server-side, not by a client-persisted slot. There is no oxy_rt
-  // refresh-cookie restore step in this ladder, and no FedCM step — FedCM was
-  // removed from the client sign-in/cold-boot path entirely (Chrome-only, and
-  // its fast/silent failure mode combined with a caller's auth-guard effect
-  // could re-trigger sign-in in a tight loop; see `CrossDomainAuth`'s doc
-  // comment in `@oxyhq/core`).
-  //
-  // LATENCY (FIX A): `stored-session` runs BEFORE the slow no-redirect
-  // `silent-iframe` probe. On a normal reload the local bearer validates in
-  // one round-trip and wins, so `runColdBoot` short-circuits and never sits
-  // through that probe's timeout. `sso-return` MUST stay first — it consumes
-  // the URL fragment before anything can strip it. On a first visit with no
-  // local session, `stored-session` skips and the cross-domain fallback chain
-  // (silent-iframe → sso-bounce) runs exactly as before; the per-apex silent
-  // iframe still restores a durable cross-domain session on reload WITHOUT a
-  // top-level bounce, so when it wins `sso-bounce` never fires (no flash, no
-  // loop).
-  // Order (native): stored session only (every web-only step is disabled
-  // off-browser).
-  const restoreSessionsFromStorage = useCallback(async () => {
-    if (!storage) {
-      return;
+      await sessionClient.start();
+      await syncFromClient();
+    } catch (registrationError) {
+      loggerUtil.warn('commitSession: device-set registration failed', {
+        component: 'OxyContext',
+        method: 'commitSession'
+      }, registrationError);
     }
-    setTokenReady(false);
-    // Fresh per-boot flag — see the declaration comment above `sessionClient`.
-    registeredDuringBootRef.current = false;
-    const commitWebSession = handleWebSSOSessionRef.current;
 
-    // FIX-B precondition flag: set true the instant the (now-earlier)
-    // `stored-session` step recovers a local bearer session. The slow
-    // web-only `silent-iframe` probe is `enabled` on `!storedSessionRestored`
-    // so it is explicitly skipped once a local session won. `runColdBoot`
-    // already short-circuits on the first `{kind:'session'}`, so on a winning
-    // reload that `enabled` body is never even reached — this flag makes the
-    // intent explicit and is redundant-safe. On a first-visit-no-local-session,
-    // `stored-session` skips, this stays false, and the probe runs as before.
-    let storedSessionRestored = false;
-
-    // FIX-B smart-gate input: has this device/app EVER had a signed-in Oxy
-    // session (the durable `priorSession` hint, set on every commit, cleared
-    // only on explicit full sign-out)? Read ONCE here — synchronously usable by
-    // the terminal `sso-bounce` `enabled` gate below — so a RETURNING visitor
-    // whose local session has lapsed still earns one `/sso` establish bounce,
-    // while a truly first-time anonymous visitor is never force-redirected.
-    // `storage` is non-null (guarded above); a read failure is treated as "no
-    // prior session" (fail safe toward anonymous-browse).
-    let hadPriorSession = false;
+    // Hydrate the full user (the commit input carries only minimal data). Fall
+    // back to the minimal shape if the profile fetch fails.
+    let fullUser = null;
     try {
-      hadPriorSession = (await storage.getItem(storageKeys.priorSession)) === '1';
-    } catch (priorSessionReadError) {
+      fullUser = await oxyServices.getCurrentUser();
+    } catch (profileError) {
       if (__DEV__) {
-        loggerUtil.debug('Failed to read prior-session hint (treating as first-time visitor)', {
+        loggerUtil.debug('Failed to fetch full user on commit; using minimal fallback', {
           component: 'OxyContext',
-          method: 'restoreSessionsFromStorage'
-        }, priorSessionReadError);
+          method: 'commitSession'
+        }, profileError);
       }
+      fullUser = input.user ?? null;
+    }
+    if (fullUser) {
+      loginSuccess(fullUser);
+      onAuthStateChangeRef.current?.(fullUser);
     }
+    markAuthResolvedRef.current();
+  }, [oxyServices, authStore, updateSessions, setActiveSessionId, sessionClient, syncFromClient, loginSuccess, logger]);
+  const commitSessionRef = useRef(commitSession);
+  commitSessionRef.current = commitSession;
+
+  // Public `handleWebSession`: commit a session from the QR device flow. It is a
+  // deliberate sign-in on THIS device, so it activates the account.
+  const handleWebSession = useCallback(async session => {
+    if (!session?.user || !session?.sessionId || !session.accessToken) {
+      throw new Error('Session response did not include a usable session');
+    }
+    await commitSession({
+      sessionId: session.sessionId,
+      accessToken: session.accessToken,
+      // deviceFlow threads a rotating refresh token on the runtime object
+      // even though `SessionLoginResponse` does not type it.
+      refreshToken: session.refreshToken,
+      deviceId: session.deviceId,
+      expiresAt: session.expiresAt,
+      userId: session.user.id,
+      user: session.user
+    }, {
+      activate: true
+    });
+  }, [commitSession]);
 
-    // DELIBERATELY-SIGNED-OUT gate (web): when the user pressed "Sign out", the
-    // per-apex `fedcm_session` cookie can still be live, so the AUTOMATIC
-    // `silent-iframe` step below would re-mint a session on the very next cold
-    // boot and sign the user back in without intent. Read the durable flag
-    // ONCE here (synchronously usable by the step `enabled` gate) and skip
-    // that step while it is set. Any deliberate sign-in clears it. The
-    // `sso-bounce` step is already self-suppressed after sign-out (its
-    // `hasPriorSession` hint is cleared), and the local `stored-session`
-    // restore step is unaffected — a deliberate sign-out clears those
-    // credentials anyway.
-    const silentRestoreBlocked = isSilentRestoreSuppressed();
+  // Keyless password sign-in: username/email + password.
+  const signInWithPassword = useCallback(async (identifier, password, opts) => {
+    const deviceToken = (await authStore.loadDeviceToken()) ?? undefined;
+    const result = await oxyServices.passwordSignIn(identifier, password, {
+      deviceToken,
+      deviceName: opts?.deviceName,
+      deviceFingerprint: opts?.deviceFingerprint
+    });
+    if ('twoFactorRequired' in result) {
+      return {
+        status: '2fa_required',
+        loginToken: result.loginToken
+      };
+    }
+    // `passwordSignIn` already planted the access token on the session arm.
+    await commitSession({
+      sessionId: result.sessionId,
+      accessToken: result.accessToken,
+      refreshToken: result.refreshToken,
+      deviceId: result.deviceId,
+      expiresAt: result.expiresAt,
+      userId: result.user.id,
+      user: result.user
+    }, {
+      activate: true
+    });
+    return {
+      status: 'ok'
+    };
+  }, [oxyServices, authStore, commitSession]);
+  const completeTwoFactorSignIn = useCallback(async params => {
+    const deviceToken = (await authStore.loadDeviceToken()) ?? undefined;
+    const result = await oxyServices.completeTwoFactorSignIn({
+      loginToken: params.loginToken,
+      token: params.token,
+      backupCode: params.backupCode,
+      deviceToken,
+      deviceName: params.deviceName
+    });
+    await commitSession({
+      sessionId: result.sessionId,
+      accessToken: result.accessToken,
+      refreshToken: result.refreshToken,
+      deviceId: result.deviceId,
+      expiresAt: result.expiresAt,
+      userId: result.user.id,
+      user: result.user
+    }, {
+      activate: true
+    });
+  }, [oxyServices, authStore, commitSession]);
+
+  // ── Cold boot ────────────────────────────────────────────────────────────
+  // The single device-first session restore. Runs ONCE after storage init.
+  // `runSessionColdBoot` resolves the device's session (bootstrap-return →
+  // stored-tokens → shared-key (native) → bootstrap-hop (web)) WITHOUT ever
+  // redirecting to a login page; an unresolved boot ends signed-out and the app
+  // renders its "Sign in with Oxy" affordance. On a winning boot the token is
+  // already planted + persisted, so `onSession` only hands off to the
+  // SessionClient (membership + active account + realtime socket) and marks
+  // auth resolved. `onSignedOut` marks auth resolved with no session.
+  const runColdBoot = useCallback(async () => {
+    setTokenReady(false);
     try {
-      const outcome = await runColdBoot({
-        steps: [{
-          // 0) Central SSO return: we are landing back from an `auth.oxy.so/sso`
-          // bounce with the result in the URL fragment. Parse it, validate the
-          // CSRF state, exchange the opaque code, and commit. On any non-ok
-          // outcome `runSsoReturn` sets the per-origin NO_SESSION flag so the
-          // terminal `sso-bounce` step is disabled — the loop breaker.
-          id: 'sso-return',
-          enabled: () => isWebBrowser(),
-          run: async () => {
-            const committed = await runSsoReturn();
-            return committed ? {
-              kind: 'session',
-              session: true
-            } : {
-              kind: 'skip'
-            };
-          }
-        }, {
-          // 2) Stored-session bearer restore. NO `enabled` gate — runs on ALL
-          // platforms. This is native's ONLY restore path (every web-only step
-          // is disabled off-browser, so native reaches exactly this) AND the
-          // common WEB reload winner.
-          //
-          // ORDERING (FIX A): this step now runs BEFORE the slow web-only
-          // `silent-iframe` probe. On a normal reload the local bearer
-          // validates in one round-trip and wins; `runColdBoot`
-          // then short-circuits and never even evaluates the slow
-          // no-redirect probe that would otherwise time out (the ~20-30s
-          // serial stall). The `sso-return` step stays AHEAD of this one —
-          // it must consume the URL fragment before any later step (or
-          // anything else) strips it. On a first visit with no local
-          // session this step skips and the cross-domain fallback chain
-          // (silent-iframe → sso-bounce) runs exactly as before.
-          id: 'stored-session',
-          run: async () => {
-            const restored = await restoreStoredSession();
-            if (restored) {
-              // FIX-B: record the win so the slow probes below explicitly skip
-              // (belt-and-suspenders; `runColdBoot` already short-circuits).
-              storedSessionRestored = true;
-              return {
-                kind: 'session',
-                session: true
-              };
-            }
-            return {
-              kind: 'skip'
-            };
-          }
-        }, {
-          // 2.5) Shared-key SSO (NATIVE ONLY) — same-device, no interaction.
-          //
-          // When a sibling Oxy app (the Commons identity vault) has written
-          // the cross-app shared identity into the `group.so.oxy.shared`
-          // keychain, this mints THIS app's session from it silently:
-          // `signInWithSharedIdentity()` proves control of the shared key
-          // (challenge → sign → verify, which plants the tokens server-side)
-          // and returns a `SessionLoginResponse`, which we commit through the
-          // SAME path the web SSO steps use (`handleWebSSOSession`), so state,
-          // durable persistence, profile fetch, and `markAuthResolved` all run
-          // identically. Returns `null` when no shared identity is present, so
-          // a device without Commons simply falls through.
-          //
-          // ORDERING: runs immediately AFTER `stored-session` (an already
-          // restored local bearer always wins first — `storedSessionRestored`
-          // gates this off) and BEFORE the web-only probes (which are gated
-          // off on native anyway). Native-only: `enabled` requires
-          // `!isWebBrowser()`, and the core method also returns `null` on web,
-          // so `WebOxyProvider` / the web path are entirely unaffected.
-          // Bounded by `SHARED_KEY_SIGNIN_TIMEOUT` so a slow/offline network
-          // cannot stall cold boot.
-          id: 'shared-key-signin',
-          enabled: () => !isWebBrowser() && !storedSessionRestored,
-          run: async () => {
-            if (!commitWebSession) {
-              return {
-                kind: 'skip'
-              };
-            }
-            let timeoutId;
-            const session = await Promise.race([oxyServices.signInWithSharedIdentity?.() ?? Promise.resolve(null), new Promise(resolve => {
-              timeoutId = setTimeout(() => resolve(null), SHARED_KEY_SIGNIN_TIMEOUT);
-            })]).finally(() => {
-              if (timeoutId !== undefined) {
-                clearTimeout(timeoutId);
-              }
-            });
-            if (!session) {
-              return {
-                kind: 'skip'
-              };
-            }
-            await commitWebSession(session);
-            // Record the win so the (web-only) probes below explicitly skip —
-            // belt-and-suspenders; `runColdBoot` already short-circuits on the
-            // first `{kind:'session'}`, and those probes are off on native.
-            storedSessionRestored = true;
-            return {
-              kind: 'session',
-              session: true
-            };
-          }
-        }, {
-          // 3) First-party silent iframe at the PER-APEX IdP — the DURABLE
-          // cross-domain reload-restore path. The durable session lives as a
-          // first-party `fedcm_session` cookie on `auth.<rp-apex>` (e.g.
-          // `auth.mention.earth`), established during the `/sso` bounce's
-          // `/sso/establish` hop. That host is SAME-SITE to the RP page, so
-          // the cookie is first-party under Safari ITP / Firefox TCP — and
-          // an iframe read is NOT a top-level navigation, so it restores on
-          // reload with NO flash and works in a backgrounded tab. This is the
-          // step that prevents the re-bounce loop: when it finds a session,
-          // the terminal `sso-bounce` never fires.
-          //
-          // The per-apex iframe mint itself lives in
-          // `mintSessionViaPerApexIframe` (shared verbatim with the in-session
-          // refresh handler so the two paths can never drift): it points the
-          // iframe at `autoDetectAuthWebUrl()` and skips when there is no
-          // per-apex IdP (localhost/IP/single-label/off-browser). Web only; on
-          // native `isWebBrowser()` gates it off, so native never runs an
-          // iframe.
-          //
-          // FIX-B: additionally skipped when `stored-session` already won.
-          // FIX-D: bounded by `SILENT_IFRAME_TIMEOUT` (plus `iframe.onerror`
-          // fail-fast in core) so a no-message iframe cannot stall cold boot.
-          id: 'silent-iframe',
-          enabled: () => !storedSessionRestored && !silentRestoreBlocked && isWebBrowser(),
-          run: async () => {
-            if (!commitWebSession) {
-              return {
-                kind: 'skip'
-              };
-            }
-            // Shared with the in-session refresh handler: the ONE
-            // implementation of "mint a first-party per-apex token without a
-            // reload" lives in `silentSessionRestore` so cold boot and refresh
-            // never drift.
-            const session = await mintSessionViaPerApexIframe(oxyServices, SILENT_IFRAME_TIMEOUT);
-            if (!session) {
-              return {
-                kind: 'skip'
-              };
-            }
-            await commitWebSession(session);
-            return {
-              kind: 'session',
-              session: true
-            };
-          }
-        }, {
-          // 4) SSO bounce (TERMINAL, web only, at most once). No local session
-          // was found by any step above. Top-level navigate to the central
-          // `auth.oxy.so/sso?prompt=none` so the IdP can either mint a session
-          // (returning an opaque code we exchange on the callback) or report
-          // `none`. This step tears the document down on success — its `skip`
-          // result is only observed if `assign` no-ops. Disabled on the IdP
-          // itself, once the NO_SESSION flag is set, or while a bounce guard is
-          // still active (loop + self-heal protection).
-          id: 'sso-bounce',
-          enabled: () => {
-            // Smart gate (SDK-owned, shared with `WebOxyProvider` via core's
-            // `allowSsoBounce`). The terminal `/sso` establish-bounce is the
-            // ONLY cold-boot step that can recover a session living SOLELY at
-            // the central IdP (a cross-apex RP whose local session expired),
-            // and it is what plants the per-apex `fedcm_session` cookie the
-            // earlier silent-iframe step relies on. So it is allowed iff a
-            // prior-signed-in hint exists OR a local session was recovered this
-            // boot (`storedSessionRestored`, always false here — an earlier step
-            // would have won — but passed for spec fidelity): a RETURNING user
-            // still gets ONE bounce, while a truly first-time anonymous visitor
-            // does NOT (anonymous browse). The per-tab loop guards below
-            // (`ssoNoSessionKey`, `ssoAttemptedKey`, `guardActive`) still cap an
-            // allowed bounce at one per cold boot.
-            if (!allowSsoBounce({
-              hasPriorSession: hadPriorSession,
-              hasLocalSession: storedSessionRestored
-            })) {
-              return false;
-            }
-            if (!isWebBrowser() || window.top !== window.self) {
-              return false;
-            }
-            const origin = window.location.origin;
-            if (isCentralIdPOrigin(origin)) {
-              return false;
-            }
-            if (window.sessionStorage.getItem(ssoNoSessionKey(origin)) === '1') {
-              return false;
-            }
-            if (window.sessionStorage.getItem(ssoAttemptedKey(origin)) === '1') {
-              return false;
-            }
-            if (guardActive(window.sessionStorage, origin, Date.now())) {
-              return false;
+      await runSessionColdBoot({
+        oxy: oxyServices,
+        store: authStore,
+        platform: {
+          isWeb: isWebBrowser(),
+          isNative: !isWebBrowser()
+        },
+        onSession: async session => {
+          // Bound how long auth resolution waits for the handoff — the token is
+          // already planted, so on a slow backend we proceed and let the handoff
+          // land asynchronously (the socket subscription re-projects when it does).
+          const handoff = commitSessionRef.current({
+            sessionId: session.sessionId,
+            accessToken: session.accessToken,
+            userId: session.userId
+          }, {
+            activate: false
+          });
+          let handoffDeadlineId;
+          await Promise.race([handoff, new Promise(resolve => {
+            handoffDeadlineId = setTimeout(resolve, SESSION_HANDOFF_DEADLINE);
+          })]).finally(() => {
+            if (handoffDeadlineId !== undefined) {
+              clearTimeout(handoffDeadlineId);
             }
-            return true;
-          },
-          run: async () => {
-            const origin = window.location.origin;
-            const state = oxyServices.generateSsoState();
-            window.sessionStorage.setItem(ssoStateKey(origin), state);
-            window.sessionStorage.setItem(ssoGuardKey(origin), String(Date.now()));
-            window.sessionStorage.setItem(ssoDestKey(origin), window.location.href);
-            // OUTCOME-INDEPENDENT once-guard: mark the probe attempted the instant we
-            // commit to the bounce, so even if the callback never lands cleanly no
-            // second bounce can ever fire this tab (the definitive loop breaker).
-            window.sessionStorage.setItem(ssoAttemptedKey(origin), '1');
-            const url = buildSsoBounceUrl(origin, state, oxyServices.config?.authWebUrl);
-
-            // TERMINAL: the document is torn down by this navigation. The
-            // `skip` below is only reached if `assign` is a no-op (e.g. the
-            // navigation is blocked); in that case we fall through
-            // unauthenticated, which is correct.
-            ssoNavigate(url);
-            return {
-              kind: 'skip'
-            };
-          }
-        }],
+          });
+          markAuthResolvedRef.current();
+        },
+        onSignedOut: () => {
+          markAuthResolvedRef.current();
+        },
         onStepError: (id, error) => {
           if (__DEV__) {
             loggerUtil.debug(`Cold-boot step "${id}" errored (non-fatal, falling through)`, {
               component: 'OxyContext',
-              method: 'restoreSessionsFromStorage'
+              method: 'runColdBoot'
             }, error);
           }
-        },
-        // Defense-in-depth: a single step whose promise never settles can no
-        // longer block the chain forever. On expiry the runner keeps iterating
-        // to the terminal `sso-bounce`
-        // step so a genuine no-local-session visit still reaches the
-        // cross-domain `/sso` fallback; the `finally` backstop flips
-        // `authResolved` regardless. See `COLD_BOOT_OVERALL_DEADLINE`.
-        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
-        onStepDeadline: id => {
-          if (__DEV__) {
-            loggerUtil.debug(`Cold-boot step "${id}" exceeded the overall deadline (abandoned, falling through)`, {
-              component: 'OxyContext',
-              method: 'restoreSessionsFromStorage'
-            });
-          }
         }
       });
-      if (__DEV__ && outcome.kind === 'session') {
-        loggerUtil.debug(`Cold boot recovered a session via "${outcome.via}"`, {
-          component: 'OxyContext',
-          method: 'restoreSessionsFromStorage'
-        });
-      }
-
-      // TOKEN LADDER → SESSIONCLIENT AUTHORITY HANDOFF. The steps above are
-      // ONLY a token-acquisition ladder — they mint the first per-domain
-      // access token by whichever means recovers one fastest. Once a session
-      // is known (either this cold boot committed one via the ladder, or an
-      // access token is already held in memory — e.g. a prior render already
-      // planted it), hand off to the server-authoritative `SessionClient`:
-      // `addCurrentAccount` registers this recovered account+session into the
-      // server `DeviceSession` (derives identity from the bearer), `start`
-      // bootstraps the full device-session state (server `activeAccountId` +
-      // `activeToken`) and connects the realtime socket, and `syncFromClient`
-      // projects that state onto the exposed `sessions`/`activeSessionId`/
-      // `user`. This is what lets a switched (managed/org) account survive
-      // reload: the SERVER, not a client-persisted slot, owns which account is
-      // active. Never call the client when no session was acquired — an
-      // anonymous visitor must stay logged out. Failures are logged and
-      // swallowed; they must never throw out of cold boot.
-      //
-      // `addCurrentAccount` is SKIPPED when `registeredDuringBootRef` is
-      // already `true` — every ladder step except `stored-session` commits
-      // through `handleWebSSOSession`, which registers the account itself
-      // (see its own `sessionClient.addCurrentAccount()` call). Without this
-      // guard a winning `sso-return` / `shared-key-signin` / `silent-iframe`
-      // step would register the SAME account twice
-      // (`POST /session/device/add` called back-to-back). `start()` and
-      // `syncFromClient()` still always run — `start()` is idempotent
-      // (no-ops once already started) and is what connects the realtime
-      // socket for the first time.
-      if (outcome.kind === 'session' || oxyServices.getAccessToken()) {
-        // Self-contained: never throws (own try/catch), so it is safe to let it
-        // outlive the race below and finish in the background if the deadline
-        // trips — the socket subscription then projects the state when it lands.
-        const handoff = (async () => {
-          try {
-            if (!registeredDuringBootRef.current) {
-              // Nested guard: registering this account into the device set is
-              // best-effort. If it throws, `start()` must STILL run so the
-              // realtime socket connects and state projects — cold boot
-              // re-registers the account into the device set on the next load.
-              try {
-                await sessionClient.addCurrentAccount();
-              } catch (addAccountErr) {
-                loggerUtil.warn('cold-boot: addCurrentAccount failed; continuing to start()', {
-                  component: 'OxyContext',
-                  method: 'restoreSessionsFromStorage'
-                }, addAccountErr);
-              }
-            }
-            await sessionClient.start();
-            await syncFromClient();
-          } catch (startErr) {
-            loggerUtil.warn('cold-boot: SessionClient start failed', {
-              component: 'OxyContext',
-              method: 'restoreSessionsFromStorage'
-            }, startErr);
-          }
-        })();
-        // Bound how long auth resolution waits for the handoff (see
-        // `SESSION_HANDOFF_DEADLINE`): the token is already planted, so on a
-        // slow backend we proceed to `markAuthResolved` and let the handoff
-        // complete asynchronously rather than stalling the spinner.
-        let handoffDeadlineId;
-        await Promise.race([handoff, new Promise(resolve => {
-          handoffDeadlineId = setTimeout(resolve, SESSION_HANDOFF_DEADLINE);
-        })]).finally(() => {
-          if (handoffDeadlineId !== undefined) {
-            clearTimeout(handoffDeadlineId);
-          }
-        });
-      }
     } catch (error) {
       if (__DEV__) {
-        loggerUtil.error('Auth init error', error instanceof Error ? error : new Error(String(error)), {
+        loggerUtil.error('Cold boot error', error instanceof Error ? error : new Error(String(error)), {
           component: 'OxyContext',
-          method: 'restoreSessionsFromStorage'
+          method: 'runColdBoot'
         });
       }
-      await clearSessionStateRef.current();
     } finally {
-      // Backstop: mark auth resolved on EVERY exit path — success, no-session,
-      // AND error→catch→finally — and on native (which only runs the
-      // `stored-session` step), so the gate can never hang `false`. Idempotent
-      // via `markAuthResolved`'s ref: when a commit site already flipped it
-      // mid-chain (the common reload case), this is a no-op. When no session was
-      // recovered (the unauthenticated/error path), this is where `tokenReady` +
-      // `authResolved` finally flip. Monotonic — never reverts on later restores.
-      markAuthResolved();
+      // Backstop: resolve on every exit path so the gate can never hang.
+      markAuthResolvedRef.current();
     }
-  }, [oxyServices, storage, storageKeys.priorSession, restoreStoredSession, runSsoReturn, markAuthResolved, sessionClient, syncFromClient]);
+  }, [oxyServices, authStore]);
   useEffect(() => {
     if (!storage || initialized) {
       return;
     }
     setInitialized(true);
-    restoreSessionsFromStorage().catch(error => {
-      if (__DEV__) {
-        logger('Failed to restore sessions from storage', error);
-      }
-    });
-  }, [restoreSessionsFromStorage, storage, initialized, logger]);
-
-  // bfcache re-evaluation (web only, registered once). When a page is restored
-  // from the back/forward cache (`e.persisted`) NO cold boot re-runs — React
-  // state is resurrected as-is — yet the page may have been frozen mid-bounce
-  // and resurrected ON the SSO callback with a fresh fragment in the URL. Re-run
-  // the `sso-return` parse so the opaque code is still exchanged (and the
-  // fragment stripped + NO_SESSION flag maintained) on a bfcache restore. Routed
-  // through a ref so the listener registers exactly once and never churns with
-  // `runSsoReturn`'s identity.
-  const runSsoReturnRef = useRef(runSsoReturn);
-  runSsoReturnRef.current = runSsoReturn;
-  useEffect(() => {
-    if (!isWebBrowser()) {
-      return;
-    }
-    const onPageShow = event => {
-      if (!event.persisted) {
-        return;
-      }
-      runSsoReturnRef.current().catch(error => {
-        if (__DEV__) {
-          loggerUtil.debug('bfcache SSO return re-evaluation failed (non-fatal)', {
-            component: 'OxyContext',
-            method: 'onPageShow'
-          }, error);
-        }
-      });
-    };
-    window.addEventListener('pageshow', onPageShow);
-    return () => window.removeEventListener('pageshow', onPageShow);
-  }, []);
-
-  // EAGER, universal SSO-callback interception (web only, once on mount).
-  //
-  // When the central IdP redirects the RP back to the internal callback path
-  // ({@link SSO_CALLBACK_PATH}), the app's own router would otherwise mount on
-  // `/__oxy/sso-callback` — a route NO app declares — and briefly flash its
-  // +not-found screen before the storage-gated cold-boot `sso-return` step gets
-  // a chance to strip the fragment and restore the real destination.
-  //
-  // This effect fires the SAME `runSsoReturn` kernel the instant we hydrate ON
-  // the callback path, BEFORE the cold boot (which awaits storage init). The
-  // first render intentionally matches the app/router's static HTML; the
-  // browser layout effect then hides the internal route and consumes the
-  // callback before the first visible paint. That keeps SSR/SSG hydration stable
-  // while still ensuring no app needs a `/__oxy/sso-callback` route.
-  //
-  // It is purely ADDITIVE. The later cold-boot `sso-return` step stays as
-  // defense-in-depth for the non-callback-path case; `consumeSsoReturn` strips
-  // the fragment first, so once this eager pass has run the cold-boot step is a
-  // harmless idempotent no-op (a second parse of the now-fragment-less URL
-  // returns `null`). The path guard scopes this strictly to the callback path,
-  // so a normal page load is untouched. Routed through `runSsoReturnRef` (the
-  // SAME ref the bfcache handler uses) so deps stay `[]` and it registers once.
-  //
-  // Timing: `handleWebSSOSessionRef.current` is assigned SYNCHRONOUSLY during
-  // render (see below, around the `handleWebSSOSession` declaration), and effects
-  // run only after the render commits, so on an `ok` outcome the commit path is
-  // already wired when this fires at eager-mount time. If for any reason it were
-  // not yet set, the later cold-boot `sso-return` step would commit it — but the
-  // ref IS set during render, so the eager `ok` commit works.
-  useBrowserLayoutEffect(() => {
-    if (!isOnSsoCallbackPath()) {
-      setSsoCallbackIntercepting(false);
-      return;
-    }
-    let mounted = true;
-    setSsoCallbackIntercepting(true);
-    runSsoReturnRef.current().catch(error => {
-      if (__DEV__) {
-        loggerUtil.debug('Eager SSO callback interception failed (non-fatal)', {
-          component: 'OxyContext',
-          method: 'eagerSsoCallbackIntercept'
-        }, error);
-      }
-    }).finally(() => {
-      if (mounted) {
-        setSsoCallbackIntercepting(false);
-      }
-    });
-    return () => {
-      mounted = false;
-    };
-  }, []);
-
-  // Web SSO: automatically check for cross-domain session on web platforms.
-  // Updates all state and persists session metadata.
-  const handleWebSSOSession = useCallback(async session => {
-    if (!session?.user || !session?.sessionId) {
+    runColdBoot().catch(error => {
       if (__DEV__) {
-        loggerUtil.warn('handleWebSSOSession: Invalid session', {
-          component: 'OxyContext'
-        });
+        logger('Cold boot failed', error);
       }
-      return;
-    }
-    if (!session.accessToken) {
-      throw new Error('Session response did not include an access token');
-    }
-    oxyServices.httpService.setTokens(session.accessToken);
-
-    // A committed web session re-enables automatic silent restore: clear the
-    // durable "deliberately signed out" flag. This funnel is reached by deliberate
-    // sign-ins (password, `/sso` return) AND by the silent
-    // cold-boot steps — but those are GATED on the flag, so when it is set they
-    // never run and never reach here; clearing is therefore only hit on a genuine
-    // (re-)sign-in or when restore was already permitted, both correct.
-    clearSignedOut();
-
-    // Register this recovered account+session into the server-authoritative
-    // device-session set. Every web primary-session restore funnels through
-    // here — per-apex `/auth/silent` iframe,
-    // central `/sso` return, and keyless password sign-in — and each of them
-    // needs the resulting account added to the device's `DeviceSession` doc so
-    // the sign-in persists across reload / other tabs / devices and the
-    // realtime `device:<deviceId>` socket has an account to track.
-    // `sessionClient.addCurrentAccount()` (`POST /session/device/add`) derives
-    // identity from the bearer this function just planted above;
-    // `syncFromClient()` reprojects the resulting server state onto the
-    // exposed sessions/activeSessionId/user. Best-effort: a failure here must
-    // NEVER fail the sign-in itself — cold boot re-registers this account into
-    // the device set on the next load regardless. `registeredDuringBootRef` is
-    // flipped on success so the cold-boot post-ladder handoff (which reaches
-    // every step, including this one) does not redundantly re-register the
-    // SAME account with a second `POST /session/device/add`.
-    try {
-      await sessionClient.addCurrentAccount();
-      registeredDuringBootRef.current = true;
-      await syncFromClient();
-    } catch (registrationError) {
-      loggerUtil.warn('handleWebSSOSession: failed to register session into device set', {
-        component: 'OxyContext',
-        method: 'handleWebSSOSession'
-      }, registrationError);
-    }
-    const clientSession = {
-      sessionId: session.sessionId,
-      deviceId: session.deviceId || '',
-      expiresAt: session.expiresAt || new Date(Date.now() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
-      lastActive: new Date().toISOString(),
-      userId: session.user.id?.toString() ?? '',
-      isCurrent: true
-    };
-    updateSessions([clientSession], {
-      merge: true
     });
-    setActiveSessionId(session.sessionId);
-
-    // Persist to storage BEFORE fetching the profile and BEFORE notifying the
-    // auth-state-change callback. The token is planted and the in-memory store
-    // is updated above; durably committing the session id here — ahead of
-    // `getCurrentUser()` / `loginSuccess` / `onAuthStateChange` — is critical
-    // because `onAuthStateChange` triggers a route navigation that can
-    // interrupt/supersede a still-pending async write. Persisting first
-    // guarantees the durable record lands; that is exactly what was missing
-    // when `oxy_session_session_ids` came back empty after a successful SSO
-    // sign-in (the user appeared logged in until reload, then had no session to
-    // restore). `persistSessionDurably` awaits the READY storage instance rather
-    // than reading the possibly-null `storage` state, so a sign-in fired the
-    // instant the screen mounts (before storage-init populates state) is not
-    // silently dropped.
-    await persistSessionDurably(session.sessionId);
-
-    // Fetch the full user profile now that we have a valid access token and the
-    // session is durably persisted. The session only carries MinimalUserData;
-    // the store and callbacks expect a full User. The navigation kicked off by
-    // `onAuthStateChange` now happens only after the durable write is committed.
-    let fullUser;
-    try {
-      fullUser = await oxyServices.getCurrentUser();
-    } catch (profileError) {
-      if (__DEV__) {
-        loggerUtil.debug('Failed to fetch full user after web session; using session user fallback', {
-          component: 'OxyContext',
-          method: 'handleWebSSOSession'
-        }, profileError);
-      }
-      // If the profile fetch fails, fall back to the minimal data from the session
-      // so the user is still logged in (the store accepts User, but the shapes overlap at runtime).
-      fullUser = session.user;
-    }
-    loginSuccess(fullUser);
-    // A session is now committed (per-apex iframe /
-    // SSO-return all funnel through here) — unblock the auth-resolution
-    // gate immediately, ahead of the cold-boot chain returning (idempotent).
-    markAuthResolvedRef.current();
-    onAuthStateChange?.(fullUser);
-  }, [oxyServices, updateSessions, setActiveSessionId, loginSuccess, onAuthStateChange, persistSessionDurably, sessionClient, syncFromClient]);
-
-  // Expose `handleWebSSOSession` to the cold-boot iframe/SSO steps,
-  // which reference it through a ref because they are declared above this
-  // callback. Assigned synchronously on every render so the ref is populated
-  // before the cold-boot effect (gated on `storage`/`initialized`) can fire.
-  handleWebSSOSessionRef.current = handleWebSSOSession;
-
-  // Keyless native sign-in: username/email + password. The slimmed Accounts app
-  // (which no longer holds a local identity key) uses this; it commits a
-  // successful session through the SAME `handleWebSSOSession` path SSO
-  // use, so state, durable persistence, profile fetch, and `markAuthResolved`
-  // all run identically. The API returns either a full session OR a two-factor
-  // handoff (`{ twoFactorRequired, loginToken }`) — we surface the latter as a
-  // discriminated result so the caller can run the 2FA challenge without any
-  // session being committed.
-  const signInWithPassword = useCallback(async (identifier, password, opts) => {
-    // On a cross-apex web RP a direct password sign-in mints a bearer against
-    // the Oxy API but establishes no `fedcm_session`, so the session would be
-    // lost on reload. Refuse it and direct the app to the durable IdP popup
-    // ("Continue with Oxy"). Native and same-apex `*.oxy.so` are unaffected.
-    if (isCrossApexWeb()) {
-      throw new CrossApexDirectSignInError();
-    }
-    const response = await oxyServices.signIn(identifier, password, opts?.deviceName, opts?.deviceFingerprint);
-    // Core types `signIn` as `SessionLoginResponse`, but the API may instead
-    // return a 2FA challenge handoff. Widen with optional fields (no `any`) to
-    // read them — the added members are optional, so the base type is
-    // assignable to this intersection.
-    const maybeTwoFactor = response;
-    if (maybeTwoFactor.twoFactorRequired && maybeTwoFactor.loginToken) {
-      return {
-        status: '2fa_required',
-        loginToken: maybeTwoFactor.loginToken
-      };
-    }
-    // Full session — commit it through the shared web-session path.
-    await handleWebSSOSession(response);
-    return {
-      status: 'ok'
-    };
-  }, [oxyServices, handleWebSSOSession]);
-
-  // Cross-domain silent SSO is owned ENTIRELY by the `silent-iframe` cold-boot
-  // step above (the ordered `runColdBoot` sequence) plus the terminal
-  // `sso-bounce` fallback. There is no post-boot safety net here: the FedCM
-  // silent post-boot retry that used to run via `useWebSSO` was removed along
-  // with the rest of the client FedCM surface (Chrome-only; see
-  // `CrossDomainAuth`'s doc comment in `@oxyhq/core` for the production
-  // incident that motivated the removal).
+  }, [runColdBoot, storage, initialized, logger]);
 
-  // IdP session validation via lightweight iframe check
-  // When user returns to tab, verify auth.oxy.so still has their session
-  // If session is gone (cleared/logged out), clear local session too
-  //
-  // KEPT (session-sync cutover audit, Task 5): this is NOT redundant with the
-  // `SessionClient` socket (`device:<deviceId>`, `session_state` push). That
-  // socket only fires for revocations that flow through oxy-api's
-  // `DeviceSession` authority (`POST /session/device/signout` and friends). A
-  // sign-out at the CENTRAL IdP itself (`auth.oxy.so`'s own `AuthSession` /
-  // `fedcm_session` — e.g. a direct IdP-side sign-out, or an admin/security
-  // revocation there) does not currently touch `DeviceSession` at all, so no
-  // socket push follows — this iframe poll is the ONLY mechanism that catches
-  // it today. A future phase should move this server-side (IdP deactivation
-  // -> `DeviceSession` update -> broadcast over the same socket), at which
-  // point this client-side poll becomes redundant and can be deleted.
-  const lastIdPCheckRef = useRef(0);
-  const pendingIdPCleanupRef = useRef(null);
-
-  // Use the RESOLVED IdP origin (the auto-detected `auth.<rp-apex>` planted on
-  // the instance config), not the raw `authWebUrl` prop — on a cross-domain RP
-  // the prop is undefined but the instance was constructed with the detected
-  // value, so the check must target the same first-party IdP the cold-boot
-  // iframe used.
-  const resolvedAuthWebUrl = oxyServices.config?.authWebUrl;
-  useEffect(() => {
-    if (!isWebBrowser() || !user || !initialized) return;
-    const idpOrigin = resolvedAuthWebUrl || 'https://auth.oxy.so';
-    const checkIdPSession = () => {
-      // Debounce: check at most once per cooldown window
-      const now = Date.now();
-      if (now - lastIdPCheckRef.current < IDP_SESSION_CHECK_COOLDOWN) return;
-      lastIdPCheckRef.current = now;
-
-      // Clean up any in-flight check before starting a new one
-      pendingIdPCleanupRef.current?.();
-
-      // Load hidden iframe to check IdP session via postMessage
-      const iframe = document.createElement('iframe');
-      iframe.style.cssText = 'display:none;width:0;height:0;border:0';
-      iframe.src = `${idpOrigin}/auth/session-check?client_id=${encodeURIComponent(window.location.origin)}`;
-      let cleaned = false;
-      const cleanup = () => {
-        if (cleaned) return;
-        cleaned = true;
-        window.removeEventListener('message', handleMessage);
-        iframe.remove();
-      };
-      const handleMessage = async event => {
-        if (event.origin !== idpOrigin) return;
-        if (event.data?.type !== 'oxy-session-check') return;
-        cleanup();
-        if (!event.data.hasSession) {
-          // Only a SAME-SITE, first-party IdP answer is authoritative enough to
-          // force a local sign-out. On a cross-site / undetermined IdP the
-          // "no session" answer must never clear local state (a third-party
-          // can't be trusted to end this app's session). Surface the toast in
-          // both cases, but gate the destructive `clearSessionState()`.
-          if (isSameSiteIdP(idpOrigin)) {
-            toast.info('Your session has ended. Please sign in again.');
-            await clearSessionState();
-          }
-        }
-      };
-      window.addEventListener('message', handleMessage);
-      document.body.appendChild(iframe);
-      setTimeout(cleanup, IDP_SESSION_CHECK_TIMEOUT);
-      pendingIdPCleanupRef.current = cleanup;
-    };
-    const handleVisibilityChange = () => {
-      if (document.visibilityState === 'visible') {
-        checkIdPSession();
-      }
-    };
-    document.addEventListener('visibilitychange', handleVisibilityChange);
-    return () => {
-      document.removeEventListener('visibilitychange', handleVisibilityChange);
-      pendingIdPCleanupRef.current?.();
-      pendingIdPCleanupRef.current = null;
-    };
-  }, [user, initialized, clearSessionState, resolvedAuthWebUrl]);
-
-  // Exposed `refreshSessions`: re-bootstraps the server-authoritative device
-  // state (`GET /session/device/state`, the SAME request `SessionClient.start()`
-  // makes) and reprojects it via `syncFromClient` — a manual pull-to-refresh
-  // counterpart to the realtime `device:<deviceId>` socket `client.start()`
-  // already owns (there is no per-domain `useSessionSocket` anymore; a REMOTE
-  // sign-out or account change arrives over that socket and is handled by
-  // `syncFromClient`'s subscription below, including the full-sign-out gap fix
-  // documented above it).
+  // Exposed `refreshSessions`: re-bootstrap the server-authoritative device
+  // state and reproject — the manual counterpart to the realtime socket.
   const refreshSessionsForContext = useCallback(async () => {
     await sessionClient.bootstrap();
     await syncFromClient();
   }, [sessionClient, syncFromClient]);
 
-  // Exposed `switchSession`: routes through the server-authoritative
-  // `SessionClient` (Fase 3-B) rather than `useSessionManagement`'s own
-  // `switchSession` (which remains, unchanged, for `useAuthOperations`'
-  // internal same-user duplicate-session dedup — a different, legacy
-  // session-validate concept unrelated to switching the device's ACTIVE
-  // account). Resolves the target account from the current device state,
-  // asks the server to switch, reprojects, and returns the now-active user.
+  // Exposed `switchSession`: route through the server-authoritative
+  // `SessionClient`. Resolve the target account from the current device state,
+  // ask the server to switch, reproject, and return the now-active user.
   const switchSessionForContext = useCallback(async sessionId => {
     const targetAccountId = sessionClient.getState()?.accounts.find(account => account.sessionId === sessionId)?.accountId;
     if (!targetAccountId) {
@@ -1871,21 +749,11 @@ export const OxyProvider = ({
     }
     return activeUser;
   }, [sessionClient, syncFromClient]);
-
-  // Identity management wrappers (delegate to KeyManager)
-  const hasIdentity = useCallback(async () => {
-    return KeyManager.hasIdentity();
-  }, []);
-  const getPublicKey = useCallback(async () => {
-    return KeyManager.getPublicKey();
-  }, []);
-
-  // Create showBottomSheet function that uses the global function
+  const hasIdentity = useCallback(async () => KeyManager.hasIdentity(), []);
+  const getPublicKey = useCallback(async () => KeyManager.getPublicKey(), []);
   const showBottomSheetForContext = useCallback(screenOrConfig => {
     globalShowBottomSheet(screenOrConfig);
   }, []);
-
-  // Avatar picker extracted into dedicated hook
   const {
     openAvatarPicker
   } = useAvatarPicker({
@@ -1896,10 +764,8 @@ export const OxyProvider = ({
     showBottomSheet: showBottomSheetForContext
   });
 
-  // --- Account graph state ---
+  // ── Account graph ──────────────────────────────────────────────────────────
   const [accounts, setAccounts] = useState([]);
-
-  // Load the unified account graph when authenticated
   const refreshAccounts = useCallback(async () => {
     if (!isAuthenticated || !tokenReady || !oxyServices.getAccessToken()) {
       setAccounts([]);
@@ -1926,34 +792,13 @@ export const OxyProvider = ({
       refreshAccounts();
     }
   }, [isAuthenticated, initialized, tokenReady, refreshAccounts]);
-
-  // Shared post-switch side effects, run identically regardless of which
-  // `switchToAccount` branch handled the switch below: reload the switchable
-  // account graph (the new active account's relationships differ) and
-  // invalidate every query so all data refetches as the new account.
   const runPostAccountSwitchSideEffects = useCallback(async () => {
     await refreshAccounts();
     queryClient.invalidateQueries();
   }, [refreshAccounts, queryClient]);
 
   // Switch the active session INTO an account from the unified graph. In the
-  // REAL-SESSION model this is identical to switching device sign-ins: the
-  // whole app becomes that account. There is exactly ONE uniform path for
-  // that — the device's server-authoritative `SessionClient.switchAccount()`
-  // — used for EVERY switch, org/managed accounts included:
-  //
-  //  - If `accountId` is ALREADY registered on this device's multi-account
-  //    set (a prior `switchToAccount`/sign-in already added it), switch
-  //    straight through `sessionClient.switchAccount()` — the SAME path
-  //    `switchSession` uses for ordinary device sessions. No new session is
-  //    minted, so no session churn / deactivation of the account's existing
-  //    session (H4).
-  //  - Only the FIRST time an account is switched into does it need minting:
-  //    `oxyServices.switchToAccount` mints+plants a real session, then
-  //    `sessionClient.addCurrentAccount()` registers it into the device set
-  //    (server-set httpOnly `oxy_rt_<authuser>` cookie, so the session joins
-  //    the device multi-account set and survives reload / `refresh-all`).
-  //    Every subsequent switch into that same account takes the branch above.
+  // real-session model this is identical to switching device sign-ins.
   const switchToAccount = useCallback(async accountId => {
     const deviceState = sessionClient.getState();
     if (deviceState?.accounts.some(account => account.accountId === accountId)) {
@@ -1966,72 +811,22 @@ export const OxyProvider = ({
     if (!result?.user || !result?.sessionId) {
       throw new Error('Account switch did not return a valid session');
     }
-
-    // A switch is a deliberate sign-in into an account: re-enable automatic silent
-    // restore by clearing any prior "deliberately signed out" flag.
-    clearSignedOut();
-
-    // `oxyServices.switchToAccount` already planted `result.accessToken` as the
-    // active token; mirror the minted session into the multi-account store and
-    // mark it current. The device account SET (and its `authuser` slot
-    // numbering) is server-authoritative via `SessionClient` — the
-    // `addCurrentAccount` + `syncFromClient` reprojection below supersedes this
-    // local mirror with the server's own state.
-    const now = new Date();
-    const clientSession = {
+    // `oxyServices.switchToAccount` already planted the access token; commit
+    // the minted session through the shared funnel (persist + register +
+    // hydrate) as a deliberate activation.
+    await commitSession({
       sessionId: result.sessionId,
-      deviceId: result.deviceId || '',
-      expiresAt: result.expiresAt || new Date(now.getTime() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
-      lastActive: now.toISOString(),
-      userId: result.user.id?.toString() ?? '',
-      isCurrent: true
-    };
-    updateSessions([clientSession], {
-      merge: true
+      accessToken: result.accessToken,
+      refreshToken: result.refreshToken,
+      deviceId: result.deviceId,
+      expiresAt: result.expiresAt,
+      userId: result.user.id,
+      user: result.user
+    }, {
+      activate: true
     });
-    setActiveSessionId(result.sessionId);
-    await persistSessionDurably(result.sessionId);
-
-    // Register the switched-to account into the device's server-authoritative
-    // multi-account set (the SAME `SessionClient.addCurrentAccount()` the
-    // cold-boot handoff uses — it derives identity from the bearer, which
-    // `oxyServices.switchToAccount` already planted above) and reproject
-    // state, so the switch persists across reload / other tabs / devices
-    // instead of only living in this provider's local session-management
-    // state. Best-effort: the token for the new account is already planted, so
-    // a transient failure here must NEVER reject the switch — fall through to
-    // `loginSuccess`/`onAuthStateChange` so the UI reflects the switched-to
-    // account (cold boot re-registers into the device set on next load).
-    // Mirrors the same guard in `handleWebSSOSession`.
-    try {
-      await sessionClient.addCurrentAccount();
-      await syncFromClient();
-    } catch (registrationError) {
-      loggerUtil.warn('switchToAccount: failed to register account into device set', {
-        component: 'OxyContext',
-        method: 'switchToAccount'
-      }, registrationError);
-    }
-
-    // Fetch the canonical User for the new account (the switch result carries
-    // only MinimalUserData); fall back to that minimal shape if the profile
-    // fetch fails so the app still reflects the switched identity.
-    let fullUser;
-    try {
-      fullUser = await oxyServices.getCurrentUser();
-    } catch (profileError) {
-      if (__DEV__) {
-        loggerUtil.debug('Failed to fetch full user after account switch; using switch result user', {
-          component: 'OxyContext',
-          method: 'switchToAccount'
-        }, profileError);
-      }
-      fullUser = result.user;
-    }
-    loginSuccess(fullUser);
-    onAuthStateChange?.(fullUser);
     await runPostAccountSwitchSideEffects();
-  }, [oxyServices, updateSessions, setActiveSessionId, persistSessionDurably, sessionClient, syncFromClient, loginSuccess, onAuthStateChange, runPostAccountSwitchSideEffects]);
+  }, [oxyServices, sessionClient, syncFromClient, commitSession, runPostAccountSwitchSideEffects]);
   const createAccountFn = useCallback(async data => {
     const account = await oxyServices.createAccount(data);
     await refreshAccounts();
@@ -2060,7 +855,8 @@ export const OxyProvider = ({
     getPublicKey,
     signIn,
     signInWithPassword,
-    handleWebSession: handleWebSSOSession,
+    completeTwoFactorSignIn,
+    handleWebSession,
     logout,
     logoutAll,
     switchSession: switchSessionForContext,
@@ -2082,25 +878,20 @@ export const OxyProvider = ({
     switchToAccount,
     refreshAccounts,
     createAccount: createAccountFn
-  }), [activeSessionId, signIn, signInWithPassword, handleWebSSOSession, currentLanguage, currentLanguageMetadata, currentLanguageName, currentNativeLanguageName, error, getDeviceSessions, hasAccessToken, canUsePrivateApi, isPrivateApiPending, getPublicKey, hasIdentity, isAuthenticated, isLoading, logout, logoutAll, logoutAllDeviceSessions, oxyServices, storageKeyPrefix, clientId, refreshSessionsForContext, sessions, setLanguage, storage, switchSessionForContext, tokenReady, hasAccessToken, canUsePrivateApi, isPrivateApiPending, authResolved, updateDeviceName, clearAllAccountData, useFollowHook, user, showBottomSheetForContext, openAvatarPicker, accounts, switchToAccount, refreshAccounts, createAccountFn]);
+  }), [user, sessions, activeSessionId, isAuthenticated, isLoading, tokenReady, hasAccessToken, canUsePrivateApi, isPrivateApiPending, authResolved, storage, error, currentLanguage, currentLanguageMetadata, currentLanguageName, currentNativeLanguageName, hasIdentity, getPublicKey, signIn, signInWithPassword, completeTwoFactorSignIn, handleWebSession, logout, logoutAll, switchSessionForContext, refreshSessionsForContext, setLanguage, getDeviceSessions, logoutAllDeviceSessions, updateDeviceName, clearSessionState, clearAllAccountData, storageKeyPrefix, clientId, oxyServices, useFollowHook, showBottomSheetForContext, openAvatarPicker, accounts, switchToAccount, refreshAccounts, createAccountFn]);
   return /*#__PURE__*/_jsx(OxyContext.Provider, {
     value: contextValue,
-    children: ssoCallbackIntercepting ? null : children
+    children: children
   });
 };
 export const OxyContextProvider = OxyProvider;
 
 /**
  * Loading-state stub used when `useOxy()` is called outside an OxyProvider.
- * All async methods reject with a clear error so misuse is caught early
- * instead of silently no-oping and leaving the UI in a bad state.
+ * All async methods reject with a clear error so misuse is caught early.
  */
 const PROVIDER_MISSING_ERROR_MESSAGE = 'OxyProvider is not mounted. Wrap your app in <OxyProvider> before calling useOxy() methods.';
 const rejectMissingProvider = () => Promise.reject(new Error(PROVIDER_MISSING_ERROR_MESSAGE));
-
-// A stub OxyServices instance so the public type contract is preserved.
-// Calling network methods on it before a provider mounts will fail with
-// a descriptive baseURL — preferable to a null-pointer crash at the call site.
 const LOADING_STATE_OXY_SERVICES = new OxyServices({
   baseURL: 'about:blank'
 });
@@ -2125,6 +916,7 @@ const LOADING_STATE = {
   getPublicKey: () => Promise.resolve(null),
   signIn: () => rejectMissingProvider(),
   signInWithPassword: () => rejectMissingProvider(),
+  completeTwoFactorSignIn: () => rejectMissingProvider(),
   handleWebSession: () => rejectMissingProvider(),
   logout: () => rejectMissingProvider(),
   logoutAll: () => rejectMissingProvider(),
@@ -2153,5 +945,4 @@ export const useOxy = () => {
   }
   return context;
 };
-export default OxyContext;
 //# sourceMappingURL=OxyContext.js.map