@desklink/react-native 0.5.3 → 0.5.6

package/src/useDesktopSession.ts

@@ -10,6 +10,7 @@ import type {
     SessionFailure,
     SessionOpenRequest,
     SessionOpenResult,
+    SessionEvent,
     SessionSnapshot,
     Signaling,
     SurfaceGeometry,
@@ -55,8 +56,41 @@ const STALL_AFTER_MS = 1200;
  * trigger another restart while the window lasts.
  */
 const RESTART_GRACE_MS = 2500;
+/**
+ * How long a moving picture outlasts silent heartbeats, from the later of the
+ * last heartbeat and the picture's return from a freeze: after an outage the
+ * data channel lags the video, as SCTP's retransmissions back off (to 15 s,
+ * then 31 s, after the first loss).
+ */
+const QUIET_PICTURE_MS = 20_000;
 /** How long a restart offer may go unanswered before the next attempt. */
 const RESTART_REPLY_MS = 5000;
+/** A restart request unanswered this long means its carrier is dead, even if it never closed. */
+const RESTART_REQUEST_DEADLINE_MS = 1500;
+/** A dial that failed is retried this soon: the path may be back any moment. */
+const DIAL_RETRY_MS = 250;
+/** One dial's bound. Not shorter: Chromium throttles refused WebSocket handshakes. */
+const DIAL_TIMEOUT_MS = 5000;
+/** How long the host holds a session with no carrier (the bridge's `reattachMs`); past it, reopen. */
+const REATTACH_WINDOW_MS = 30_000;
+/**
+ * How long a reattached carrier waits for the old ICE pair before asking for
+ * a restart — the wait for a brief blip: on an unchanged path the old pair
+ * resumes in ~100 ms and only the carrier was missing, so the wait keeps the
+ * restart unspent while the picture comes back on its own.
+ */
+const REATTACH_GRACE_MS = 200;
+/**
+ * A picture still this long is a real outage, not a blip: the old pair is
+ * not resuming, so the wait that protects a blip would only cost the recovery
+ * its 2 s bar. The line separates the two measured regimes — blips of about
+ * a second heal on the old pair in ~100 ms; by 12 s the pair is gone. The
+ * picture's own last motion is the clock: a re-dialled carrier's age resets
+ * with every refused attempt, so it cannot tell the two apart.
+ */
+const REATTACH_GRACE_BLIP_MAX_MS = 4000;
+/** A real outage's wait: one stats beat — enough to see a picture already moving. */
+const REATTACH_GRACE_SETTLE_MS = 50;
 /**
  * How long the media path may carry nothing at all before a session that says
  * `live` stops saying so. The engine's transport state reaches the client over
@@ -98,6 +132,16 @@ export const REOPEN_BACKOFF_MS = [1000, 2000, 4000, 8000, 8000, 8000, 8000, 8000
  * A return after that reopens at once instead of spending restarts on it.
  */
 export const BACKGROUND_REOPEN_MS = 30_000;
+/**
+ * A peer that reaches ICE `failed` has lost its media path, not its session:
+ * the engine keeps the session alive for about 28 s after the path dies (its
+ * ICE `Failed` timer). So a client-side ICE failure holds the session — and
+ * its native handle — this long from the failure, whatever the carrier is
+ * doing, instead of throwing it away at once. A roam longer than the client's
+ * own ~15 s ICE `failed` then still returns to the same session. An SDP or
+ * candidate failure is not a lost path and stays terminal as it always was.
+ */
+export const HOLD_AFTER_FAILED_MS = 30_000;
 /**
  * A resumed app hears what queued up while it was suspended just after it
  * hears it is active again. A revocation among it decides whether a reopen is
@@ -105,6 +149,19 @@ export const BACKGROUND_REOPEN_MS = 30_000;
  */
 const RESUME_DRAIN_MS = 750;
 
+const DEADLINE = new Error('no reply in time');
+
+/** `promise`, or a DEADLINE rejection after `ms`; a value that lands later goes to `late`. */
+function withDeadline<T>(promise: Promise<T>, ms: number, late?: (value: T) => void): Promise<T> {
+    let expired = false;
+    return Promise.race([
+        promise.then((value) => { if (expired) late?.(value); return value; }),
+        new Promise<never>((_, reject) => setTimeout(() => { expired = true; reject(DEADLINE); }, ms)),
+    ]);
+}
+
+const errorCode = (error: unknown): unknown => (error as { code?: unknown } | null)?.code;
+
 /** The delay before attempt `n` (0-based), or null when the schedule is spent. */
 export function backoffDelay(schedule: readonly number[], attempt: number): number | null {
     return attempt < schedule.length ? schedule[attempt]! : null;
@@ -336,6 +393,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const mediaMovingAt = useRef<number | null>(null);
     /** Whether the picture of an open session has stopped advancing. */
     const frozen = useRef(false);
+    /** When a frozen picture last moved again, or 0 while it has not. */
+    const pictureBackAt = useRef(0);
     /** Renegotiation transients are not a new outage before this time. */
     const restartGraceUntil = useRef(0);
     /** ICE-restart attempts spent on the current drop. */
@@ -348,6 +407,12 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const restartCycles = useRef(0);
     /** The last ICE state the peer or the engine reported. */
     const iceConnected = useRef(false);
+    /**
+     * When the peer's own ICE last failed while the session was held, or null
+     * when the current failure is not an ICE one. Kept across the hold so the
+     * reopen effect can measure the remaining window.
+     */
+    const heldIceFailureAt = useRef<number | null>(null);
     /** The engine's restore token, for a consent-free reopen. Unset by hand. */
     const restoreToken = useRef<string | null>(null);
     /** The latest status and presentation, read by event handlers. */
@@ -360,6 +425,13 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const awaySince = useRef<number | null>(null);
     /** Guards every asynchronous callback against a session that already ended. */
     const generationToken = useRef(0);
+    /** Bumped per carrier adopted or dropped: an older carrier's events and replies are ignored. */
+    const carrierEpoch = useRef(0);
+    const unsubscribeCarrier = useRef<(() => void) | null>(null);
+    /** While the carrier is dead, whatever the status: the dial in flight and its retry. */
+    const dialing = useRef<{ inFlight: boolean; since: number; retry?: ReturnType<typeof setTimeout> } | null>(null);
+    /** Set with a reopen that skips its backoff: the host no longer holds the session at all. */
+    const reopenAtOnce = useRef(false);
     const optionsRef = useRef(options);
     optionsRef.current = options;
 
@@ -375,21 +447,30 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         optionsRef.current.onStateChange?.(next);
     }, []);
 
-    const fail = useCallback((failure: SessionFailure) => {
+    const fail = useCallback((failure: SessionFailure, ice = false) => {
+        heldIceFailureAt.current = failure.code === 'transport' && ice && nativeRef.current != null ? Date.now() : null;
         update({ status: 'failed', failure });
         optionsRef.current.onError?.(failure);
     }, [update]);
 
-    const refuse = useCallback((message: string, code: SessionFailure['code'] = 'platform') => {
-        fail({ code, message });
+    const refuse = useCallback((message: string, code: SessionFailure['code'] = 'platform', ice = false) => {
+        fail({ code, message }, ice);
     }, [fail]);
 
     /** A transport loss is one event no matter how many sides report it: the
      * peer's `failed` state and its `failure` event would otherwise spend the
-     * reopen budget twice for the same outage. */
-    const transportFailed = useCallback((message: string = UNREACHABLE_DESKTOP) => {
-        if (statusRef.current === 'failed') return;
-        refuse(message, 'transport');
+     * reopen budget twice for the same outage. While dialing, it stays
+     * `reconnecting`.
+     *
+     * `ice` marks a failure of the peer's own media path (its ICE `failed`
+     * state, or a `failure` event whose reason is `ice`). While the session is
+     * held and has not been revoked, that is not the end of the session: the
+     * reopen effect keeps it for `HOLD_AFTER_FAILED_MS` first. */
+    const transportFailed = useCallback((message: string = UNREACHABLE_DESKTOP, ice = false): boolean => {
+        if (dialing.current !== null) return false;
+        if (ice && statusRef.current === 'failed') return false;
+        refuse(message, 'transport', ice);
+        return true;
     }, [refuse]);
 
     const cancelRestart = useCallback(() => {
@@ -412,20 +493,69 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         firstFrameTimer.current = null;
     }, []);
 
+    const stopDialing = useCallback(() => { clearTimeout(dialing.current?.retry); dialing.current = null; }, []);
+
     /**
      * A first connection that stays frameless for this long is not going to
      * arrive: report why instead of leaving an empty picture on screen.
      */
     const armFirstFrame = useCallback(() => {
         cancelFirstFrame();
-        firstFrameTimer.current = setTimeout(() => {
-            firstFrameTimer.current = null;
-            if (presentedRef.current || statusRef.current !== 'connecting') return;
-            transportFailed(NO_PICTURE);
-        }, FIRST_FRAME_AFTER_MS);
-    }, [cancelFirstFrame, transportFailed]);
+        const watch: () => void = () => {
+            firstFrameTimer.current = setTimeout(() => {
+                firstFrameTimer.current = null;
+                const status = statusRef.current;
+                if (!presentedRef.current && status === 'failed' && heldIceFailureAt.current !== null) {
+                    watch();
+                    return;
+                }
+                if (presentedRef.current || (status !== 'connecting' && status !== 'reconnecting')) return;
+                stopDialing();
+                transportFailed(NO_PICTURE);
+            }, FIRST_FRAME_AFTER_MS);
+        };
+        watch();
+    }, [cancelFirstFrame, stopDialing, transportFailed]);
 
     const scheduleRestartRef = useRef<(delay: number) => void>(() => undefined);
+    const dialRef = useRef<() => void>(() => undefined);
+    const carrierEventRef = useRef<(event: SessionEvent) => void>(() => undefined);
+
+    /** Stop listening to the carrier; a dead one is also closed, so nothing more is sent on it. */
+    const dropCarrier = useCallback((dead: boolean) => {
+        carrierEpoch.current += 1;
+        unsubscribeCarrier.current?.();
+        unsubscribeCarrier.current = null;
+        const channel = signaling.current;
+        signaling.current = null;
+        if (dead) channel?.close?.();
+    }, []);
+
+    const adoptCarrier = useCallback((channel: Signaling) => {
+        dropCarrier(false);
+        const epoch = carrierEpoch.current;
+        signaling.current = channel;
+        unsubscribeCarrier.current = channel.subscribe((event) => {
+            if (epoch === carrierEpoch.current) carrierEventRef.current(event);
+        });
+    }, [dropCarrier]);
+
+    /** Carrier `epoch` is dead: drop it hard and, while a session is held, dial a new one. */
+    const carrierLost = useCallback((epoch: number) => {
+        if (epoch !== carrierEpoch.current || signaling.current == null) return;
+        dropCarrier(true);
+        if (dialing.current !== null || opened.current == null) return;
+        dialing.current = { inFlight: false, since: Date.now() };
+        dialRef.current();
+    }, [dropCarrier]);
+
+    /** Whether a request on carrier `epoch` failed because that carrier is gone; the dial loop then owns it. */
+    const carrierFailed = useCallback((epoch: number, error: unknown): boolean => {
+        if (epoch !== carrierEpoch.current) return true;
+        if (error !== DEADLINE && errorCode(error) !== 'transport') return false;
+        carrierLost(epoch);
+        return true;
+    }, [carrierLost]);
 
     /**
      * Spend one restart from the backoff schedule, or reopen when the schedule
@@ -465,20 +595,33 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             if (statusRef.current !== 'reconnecting') return;
             const openedRef = opened.current;
             const channel = signaling.current;
-            if (openedRef == null || channel == null) {
+            if (openedRef == null) {
                 spendRestartAttempt();
                 return;
             }
+            // No carrier: the dial loop restarts once it has a new one.
+            if (channel == null) return;
+            const epoch = carrierEpoch.current;
+            const token = generationToken.current;
             void (async () => {
                 try {
-                    await channel.request('session.restart_ice', {
+                    await withDeadline(channel.request('session.restart_ice', {
                         session_id: openedRef.sessionId,
                         generation: openedRef.generation,
-                    });
-                } catch {
+                    }), RESTART_REQUEST_DEADLINE_MS);
+                } catch (error) {
+                    if (token !== generationToken.current || carrierFailed(epoch, error)) return;
+                    // The host no longer holds this session: reopen without waiting out a backoff.
+                    if (errorCode(error) === 'session' || errorCode(error) === 'generation') {
+                        attempts.current = 0;
+                        reopenAtOnce.current = transportFailed('the desktop no longer holds this session; reopening it');
+                        return;
+                    }
                     spendRestartAttempt();
                     return;
                 }
+                // A late reply from a replaced carrier or session says nothing about this one.
+                if (epoch !== carrierEpoch.current || token !== generationToken.current) return;
                 if (statusRef.current !== 'reconnecting') return;
                 restartGraceUntil.current = Date.now() + RESTART_GRACE_MS;
                 restartCycles.current += 1;
@@ -501,10 +644,12 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 }, replyMs);
             })();
         }, delay);
-    }, [spendRestartAttempt, transportFailed]);
+    }, [spendRestartAttempt, transportFailed, carrierFailed]);
 
     useEffect(() => {
         scheduleRestartRef.current = scheduleRestart;
+        dialRef.current = dial;
+        carrierEventRef.current = onCarrierEvent;
         checkStallRef.current = checkStall;
         mediaWatchRef.current = checkMedia;
     });
@@ -526,6 +671,11 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const onTransportState = useCallback((state: string, trackIce = true, skipGrace = false) => {
         // Synthetic stall reports say nothing about ICE itself.
         if (trackIce) iceConnected.current = state === 'connected' || state === 'completed';
+        if (heldIceFailureAt.current !== null && statusRef.current === 'failed'
+            && (state === 'connected' || state === 'completed')) {
+            heldIceFailureAt.current = null;
+            update({ status: 'reconnecting' });
+        }
         const mapped = connectionStatusFor(state, statusRef.current, presentedRef.current && !frozen.current);
         if (mapped === null) return;
         // A transport that answers while the picture is frozen is not a
@@ -596,9 +746,10 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 mediaMovingAt.current = Date.now();
                 if (!frozen.current) return;
                 frozen.current = false;
+                pictureBackAt.current = Date.now();
                 // The picture advances again, so the transport can be believed
                 // for this session: live returns without waiting for it to say so.
-                if (statusRef.current === 'reconnecting') onTransportState('connected', false);
+                if (statusRef.current === 'reconnecting' || (statusRef.current === 'failed' && heldIceFailureAt.current !== null)) onTransportState('connected', false);
                 return;
             }
             if (mediaMovingAt.current === null) return;
@@ -612,6 +763,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         }, () => undefined);
     }, [armMedia, onTransportState]);
 
+    const pictureMoving = useCallback((within: number): boolean => mediaMovingAt.current !== null && Date.now() - mediaMovingAt.current < within, []);
+
     /**
      * One stall check: quiet too long while the session should be talking
      * means the path is stalled, even when ICE has not said so yet. Only
@@ -634,8 +787,19 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             stallTimer.current = setTimeout(() => checkStallRef.current(), restartGraceUntil.current - Date.now());
             return;
         }
+        // The outage's own silence is not the data channel lagging the
+        // picture: that lag starts when the picture comes back. Until the
+        // heartbeat catches up, the picture is held to the freeze bar: a
+        // still desktop's keepalive frames, a second apart, read up to
+        // 1.5 s apart through the stats poll.
+        const lagging = pictureBackAt.current > lastPingAt.current;
+        const lagMs = Date.now() - Math.max(lastPingAt.current, pictureBackAt.current);
+        if (pictureMoving(lagging ? FROZEN_AFTER_MS : STALL_AFTER_MS) && !frozen.current && lagMs < QUIET_PICTURE_MS) {
+            stallTimer.current = setTimeout(() => checkStallRef.current(), STALL_AFTER_MS);
+            return;
+        }
         onTransportState('disconnected', false);
-    }, [onTransportState]);
+    }, [onTransportState, pictureMoving]);
 
     /**
      * One engine heartbeat: the path works. It clears a stall the watchdog
@@ -733,6 +897,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     /** Drop everything this process holds for a session the engine has ended. */
     const discardSession = useCallback(() => {
         generationToken.current += 1;
+        cancelFirstFrame();
         const id = nativeRef.current;
         nativeRef.current = null;
         inputEnabled.current = false;
@@ -741,6 +906,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         pendingOffer.current = null;
         pendingCandidates.current = [];
         pendingCursorEvents.current = [];
+        heldIceFailureAt.current = null;
         restartGraceUntil.current = 0;
         restartCycles.current = 0;
         // A new session has its own media path: the last one's counts and its
@@ -750,14 +916,15 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         mediaRef.current = null;
         mediaMovingAt.current = null;
         frozen.current = false;
+        pictureBackAt.current = 0;
         opened.current = null;
-        signaling.current = null;
+        dropCarrier(false);
         setNativeId(null);
         // An armed modifier belongs to the session it was armed in.
         modifiersRef.current = NO_MODIFIERS;
         setModifiers(NO_MODIFIERS);
         if (id != null) nativeDesklink?.closeSession(id);
-    }, []);
+    }, [cancelFirstFrame, dropCarrier]);
 
     /** Tell the host a session is over; a failure is nothing the user can act on. */
     const endRemote = useCallback(async (
@@ -780,6 +947,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         cancelRestart();
         cancelStall();
         cancelFirstFrame();
+        stopDialing();
         restoreToken.current = null;
         const openedRef = opened.current;
         const owner = signaling.current;
@@ -787,10 +955,98 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         if (closeRemote) await endRemote(openedRef, owner);
         update({ status: 'ended', presented: false, failure: null });
         void reason;
-    }, [cancelReconnect, cancelRestart, cancelStall, cancelFirstFrame, endRemote, discardSession, update]);
+    }, [cancelReconnect, cancelRestart, cancelStall, cancelFirstFrame, stopDialing, endRemote, discardSession, update]);
+
+    /**
+     * One engine event from the live carrier. Subscribed before the open,
+     * because the engine's offer and its first candidates can beat the open
+     * result back: anything that arrives before the native session exists is
+     * stashed and replayed into it.
+     */
+    const onCarrierEvent = useCallback((event: SessionEvent) => {
+        const native = nativeRef.current;
+        const held = opened.current;
+        const current = event.sessionId === undefined || held == null || held.sessionId === event.sessionId;
+        switch (event.kind) {
+            case 'carrier-closed':
+                carrierLost(carrierEpoch.current);
+                return;
+            case 'description':
+                if (event.description.type !== 'offer') return;
+                if (native == null || held == null) {
+                    pendingOffer.current = { sdp: event.description.sdp, sessionId: event.sessionId };
+                    return;
+                }
+                if (!current) return;
+                // A mid-session re-offer is a restart this session asked
+                // for, through its policy or directly: renegotiation
+                // transients after it are expected, not a new outage.
+                if (presentedRef.current) restartGraceUntil.current = Date.now() + RESTART_GRACE_MS;
+                nativeDesklink?.setRemoteDescription(native, 'offer', event.description.sdp);
+                return;
+            case 'candidate':
+                if (native == null || held == null) {
+                    pendingCandidates.current.push({
+                        candidate: event.candidate.candidate,
+                        sdpMid: event.candidate.sdpMid ?? null,
+                        sdpMLineIndex: event.candidate.sdpMLineIndex ?? null,
+                        sessionId: event.sessionId,
+                    });
+                    return;
+                }
+                if (!current) return;
+                nativeDesklink?.addRemoteCandidate(
+                    native,
+                    event.candidate.candidate,
+                    event.candidate.sdpMid ?? null,
+                    event.candidate.sdpMLineIndex ?? null,
+                );
+                return;
+            case 'cursor':
+                if (held == null) {
+                    pendingCursorEvents.current.push(event);
+                    return;
+                }
+                if (current) optionsRef.current.onCursor?.(event);
+                return;
+            case 'state':
+                if (!current) return;
+                diagnostics.current.transport = event.transport;
+                // Before the session exists there is nothing to map onto.
+                if (held != null) onTransportState(String(event.transport ?? '').toLowerCase());
+                update({ diagnostics: { ...diagnostics.current } });
+                return;
+            case 'restoreToken':
+                // The live session's grant for a consent-free reopen.
+                if (current && held != null) restoreToken.current = event.token;
+                return;
+            case 'revoked':
+                // Nothing held: the reopen policy owns recovery, and a
+                // dead session's late revocation must not end it.
+                if (held == null || !current) return;
+                // A lost path is an outage, not a verdict: the reopen
+                // policy asks for fresh authority. Any other code, or
+                // none, is the session's authority ending.
+                if (event.code === 'transport') {
+                    transportFailed(event.reason);
+                    return;
+                }
+                void teardown(event.reason, false);
+                update({ status: 'ended', failure: { code: 'revoked', message: event.reason } });
+                return;
+            default:
+                return;
+        }
+    }, [carrierLost, onTransportState, teardown, transportFailed, update]);
 
-    const establish = useCallback(async () => {
+    /** Open a session on `given`, a carrier the dial loop just authorized, or on a fresh authorization. */
+    const establish = useCallback(async (given?: { signaling: Signaling; session: SessionOpenRequest }) => {
         if (nativeRef.current != null) return;
+        // While a dead carrier is replaced, the dial loop opens on the new one.
+        if (given === undefined && dialing.current !== null) {
+            dialRef.current();
+            return;
+        }
         const token = ++generationToken.current;
         pendingCursorEvents.current = [];
         if (!(await loadPlatform())) {
@@ -800,93 +1056,17 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         if (token !== generationToken.current) return;
         update({ status: 'opening', failure: null, presented: false });
 
-        let authorization: { signaling: Signaling; session: SessionOpenRequest };
-        try {
-            authorization = await optionsRef.current.authorize();
-        } catch (error) {
-            const code = (error as { code?: unknown } | null)?.code === 'transport' ? 'transport' : 'permission';
-            refuse(error instanceof Error ? error.message : 'the desktop was not authorized', code);
-            return;
-        }
-        if (token !== generationToken.current) return;
-        signaling.current = authorization.signaling;
-
-        // Subscribed before the open, because the engine's offer and its first
-        // candidates can beat the open result back. Anything that arrives
-        // before the native session exists is stashed and replayed into it.
-        authorization.signaling.subscribe((event) => {
-            if (token !== generationToken.current) return;
-            const native = nativeRef.current;
-            const held = opened.current;
-            const current = event.sessionId === undefined || held == null || held.sessionId === event.sessionId;
-            switch (event.kind) {
-                case 'description':
-                    if (event.description.type !== 'offer') return;
-                    if (native == null || held == null) {
-                        pendingOffer.current = { sdp: event.description.sdp, sessionId: event.sessionId };
-                        return;
-                    }
-                    if (!current) return;
-                    // A mid-session re-offer is a restart this session asked
-                    // for, through its policy or directly: renegotiation
-                    // transients after it are expected, not a new outage.
-                    if (presentedRef.current) restartGraceUntil.current = Date.now() + RESTART_GRACE_MS;
-                    nativeDesklink?.setRemoteDescription(native, 'offer', event.description.sdp);
-                    return;
-                case 'candidate':
-                    if (native == null || held == null) {
-                        pendingCandidates.current.push({
-                            candidate: event.candidate.candidate,
-                            sdpMid: event.candidate.sdpMid ?? null,
-                            sdpMLineIndex: event.candidate.sdpMLineIndex ?? null,
-                            sessionId: event.sessionId,
-                        });
-                        return;
-                    }
-                    if (!current) return;
-                    nativeDesklink?.addRemoteCandidate(
-                        native,
-                        event.candidate.candidate,
-                        event.candidate.sdpMid ?? null,
-                        event.candidate.sdpMLineIndex ?? null,
-                    );
-                    return;
-                case 'cursor':
-                    if (held == null) {
-                        pendingCursorEvents.current.push(event);
-                        return;
-                    }
-                    if (current) optionsRef.current.onCursor?.(event);
-                    return;
-                case 'state':
-                    if (!current) return;
-                    diagnostics.current.transport = event.transport;
-                    // Before the session exists there is nothing to map onto.
-                    if (held != null) onTransportState(String(event.transport ?? '').toLowerCase());
-                    update({ diagnostics: { ...diagnostics.current } });
-                    return;
-                case 'restoreToken':
-                    // The live session's grant for a consent-free reopen.
-                    if (current && held != null) restoreToken.current = event.token;
-                    return;
-                case 'revoked':
-                    // Nothing held: the reopen policy owns recovery, and a
-                    // dead session's late revocation must not end it.
-                    if (held == null || !current) return;
-                    // A lost path is an outage, not a verdict: the reopen
-                    // policy asks for fresh authority. Any other code, or
-                    // none, is the session's authority ending.
-                    if (event.code === 'transport') {
-                        transportFailed(event.reason);
-                        return;
-                    }
-                    void teardown(event.reason, false);
-                    update({ status: 'ended', failure: { code: 'revoked', message: event.reason } });
-                    return;
-                default:
-                    return;
+        let authorization = given;
+        if (authorization === undefined) {
+            try {
+                authorization = await optionsRef.current.authorize();
+            } catch (error) {
+                refuse(error instanceof Error ? error.message : 'the desktop was not authorized', errorCode(error) === 'transport' ? 'transport' : 'permission');
+                return;
             }
-        });
+            if (token !== generationToken.current) return;
+            adoptCarrier(authorization.signaling);
+        }
 
         let openedResult: SessionOpenResult;
         try {
@@ -967,7 +1147,76 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 await endRemote(openedResult, authorization.signaling);
             }
         }
-    }, [armFirstFrame, discardSession, endRemote, refuse, teardown, transportFailed, update, onTransportState]);
+    }, [adoptCarrier, armFirstFrame, discardSession, endRemote, refuse, update]);
+
+    /** Dial a carrier to replace a dead one, one authorize() at a time; reattach the session or open anew. */
+    const dial = useCallback(() => {
+        const run = dialing.current;
+        if (run === null || run.inFlight) return;
+        clearTimeout(run.retry);
+        run.inFlight = true;
+        void (async () => {
+            let authorization: { signaling: Signaling; session: SessionOpenRequest };
+            try {
+                authorization = await withDeadline(optionsRef.current.authorize(), DIAL_TIMEOUT_MS, (late) => late.signaling.close?.());
+            } catch (error) {
+                if (dialing.current !== run) return;
+                run.inFlight = false;
+                if (error === DEADLINE || errorCode(error) === 'transport') {
+                    run.retry = setTimeout(() => dialRef.current(), DIAL_RETRY_MS);
+                    return;
+                }
+                // A refused pairing is final: a revoked phone must not reattach.
+                const message = error instanceof Error ? error.message : 'the desktop was not authorized';
+                await teardown(message, true);
+                update({ failure: { code: 'permission', message } });
+                return;
+            }
+            if (dialing.current !== run) {
+                authorization.signaling.close?.();
+                return;
+            }
+            stopDialing();
+            // Past the reattach window the host has ended the held session: open anew on this carrier.
+            if (Date.now() - run.since >= REATTACH_WINDOW_MS) discardSession();
+            adoptCarrier(authorization.signaling);
+            if (opened.current == null) {
+                attempts.current = 0;
+                cancelReconnect();
+                void establish(authorization);
+                return;
+            }
+            // A picture that has only just stopped may still be riding its
+            // old ICE pair back: on an unchanged path that pair resumes in
+            // ~100 ms, so a brief blip waits that moment out before a restart
+            // is spent. A picture still past the line is a real outage — the
+            // wait shortens to one stats beat, because waiting out a blip
+            // that never comes would cost the recovery its bar.
+            const held = opened.current, before = mediaRef.current;
+            cancelRestart();
+            const stillMs = mediaMovingAt.current === null ? Infinity : Date.now() - mediaMovingAt.current;
+            const graceMs = stillMs < REATTACH_GRACE_BLIP_MAX_MS ? REATTACH_GRACE_MS : REATTACH_GRACE_SETTLE_MS;
+            restartTimer.current = setTimeout(() => {
+                restartTimer.current = null;
+                void getStats().catch(() => []).then((rows) => {
+                    if (opened.current !== held || dialing.current !== null) return;
+                    // The picture moves: only the carrier was missing.
+                    if ((mediaCounts(rows)?.frames ?? 0) > (before?.frames ?? Infinity)) {
+                        if (statusRef.current === 'reconnecting' || (statusRef.current === 'failed' && heldIceFailureAt.current !== null)) onTransportState('connected', false);
+                        return;
+                    }
+                    if (statusRef.current !== 'reconnecting') update({ status: 'reconnecting' });
+                    restartAttempts.current = restartCycles.current = 0;
+                    // A transport `disconnected` that landed while the stats read
+                    // above was in flight armed `scheduleRestart(RESTART_AFTER_MS)`;
+                    // without clearing it first the request here would return early
+                    // on the armed timer and the restart would slip by up to 2 s.
+                    cancelRestart();
+                    scheduleRestart(0);
+                });
+            }, graceMs);
+        })();
+    }, [adoptCarrier, cancelReconnect, cancelRestart, discardSession, establish, getStats, onTransportState, scheduleRestart, stopDialing, teardown, update]);
 
     /**
      * Open (or reopen) the session with fresh authority. A deliberate call
@@ -979,8 +1228,15 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         restartAttempts.current = 0;
         restartCycles.current = 0;
         cancelRestart();
+        if (heldIceFailureAt.current !== null && statusRef.current === 'failed') {
+            const owner = signaling.current;
+            const openedRef = opened.current;
+            heldIceFailureAt.current = null;
+            discardSession();
+            void endRemote(openedRef, owner);
+        }
         await establish();
-    }, [cancelRestart, establish]);
+    }, [cancelRestart, discardSession, endRemote, establish]);
 
     // Native events: answer, candidates, control replies, presentation, failure.
     useEffect(() => {
@@ -998,6 +1254,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 if (event.sessionId !== nativeRef.current) return;
                 const openedRef = opened.current;
                 const channel = signaling.current;
+                const epoch = carrierEpoch.current;
                 switch (event.name) {
                     case 'answer': {
                         const sdp = String(event.payload.sdp ?? '');
@@ -1006,7 +1263,11 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                             session_id: openedRef.sessionId,
                             generation: openedRef.generation,
                             description: { type: 'answer', sdp },
-                        }).catch(() => refuse('the desktop refused our answer', 'transport'));
+                        }).catch((error) => {
+                            // A dead or replaced carrier is the dial loop's, not a refusal.
+                            if (carrierFailed(epoch, error) || opened.current !== openedRef) return;
+                            refuse('the desktop refused our answer', 'transport');
+                        });
                         return;
                     }
                     case 'candidate': {
@@ -1017,7 +1278,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                             candidate: String(event.payload.candidate ?? ''),
                             sdpMid: (event.payload.sdpMid as string | null) ?? null,
                             sdpMLineIndex: (event.payload.sdpMLineIndex as number | null) ?? null,
-                        }).catch(() => undefined);
+                        }).catch((error) => { carrierFailed(epoch, error); });
                         return;
                     }
                     case 'track':
@@ -1097,7 +1358,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         // The peer's connection state, as it happens: Android
                         // and iOS already emit this, and web matches them.
                         const state = String(event.payload.state ?? '').toLowerCase();
-                        if (state === 'failed') transportFailed();
+                        if (state === 'failed') transportFailed(UNREACHABLE_DESKTOP, true);
                         else onTransportState(state);
                         return;
                     }
@@ -1107,7 +1368,9 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         else if (typeof event.payload.text === 'string') typeText(event.payload.text);
                         return;
                     case 'failure':
-                        transportFailed();
+                        // Only an ICE failure is held; an SDP or candidate
+                        // failure is terminal exactly as before.
+                        transportFailed(UNREACHABLE_DESKTOP, String(event.payload.reason ?? '') === 'ice');
                         return;
                     case 'closed':
                         return;
@@ -1121,7 +1384,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             dropped = true;
             subscription?.remove();
         };
-    }, [transportFailed, onTransportState, cancelRestart, spendRestartAttempt, notePing, teardown, update, pressKey, typeText, armMedia]);
+    }, [transportFailed, onTransportState, cancelRestart, spendRestartAttempt, notePing, teardown, update, pressKey, typeText, armMedia, carrierFailed]);
 
     const copyRemoteToLocal = useCallback(async (writeLocal: (text: string) => Promise<void>) => {
         if (!inputEnabled.current) throw new Error('Desktop control is off.');
@@ -1171,26 +1434,62 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     // across about a minute: a session that was revoked must not be reopened
     // on the strength of the old grant, and an outage that outlasts one
     // attempt must not spend the whole budget while the network is still down.
+    //
+    // An ICE failure is the one exception. It means the peer's path died, not
+    // that the engine ended the session, so the held session (and its native
+    // handle) is kept for HOLD_AFTER_FAILED_MS from the failure, whatever the
+    // carrier watch is doing; a roam that outlasts the client's own ~15 s ICE
+    // `failed` can then reattach and restart ICE on the same session. Only a
+    // failure that is not ICE — SDP, candidate, a revoked transport — drops the
+    // session at once, exactly as before.
     useEffect(() => {
-        if (snapshot.status !== 'failed') return;
+        const immediate = reopenAtOnce.current;
+        reopenAtOnce.current = false;
+        if (snapshot.status !== 'failed') {
+            heldIceFailureAt.current = null;
+            return;
+        }
         if (snapshot.failure?.code !== 'transport') return;
-        // The failed session is dead on the engine side. Drop its handle and
-        // close the remote session whether or not another attempt is left: a
-        // failure the user can retry by hand must not sit behind a stale
-        // native handle that makes `connect()` a no-op.
-        const owner = signaling.current;
-        const openedRef = opened.current;
-        cancelRestart();
-        discardSession();
-        void endRemote(openedRef, owner);
-        const wait = backoffDelay(REOPEN_BACKOFF_MS, attempts.current);
-        if (wait === null) return;
-        attempts.current += 1;
-        update({ status: 'reconnecting' });
-        reconnectTimer.current = setTimeout(() => {
-            reconnectTimer.current = null;
-            void establish();
-        }, wait);
+        const reopen = () => {
+            // The failed session is dead on the engine side. Drop its handle and
+            // close the remote session whether or not another attempt is left: a
+            // failure the user can retry by hand must not sit behind a stale
+            // native handle that makes `connect()` a no-op.
+            const owner = signaling.current;
+            const openedRef = opened.current;
+            cancelRestart();
+            discardSession();
+            void endRemote(openedRef, owner);
+            // With the carrier dead, the dial loop opens on the first one that comes up.
+            if (dialing.current !== null) {
+                update({ status: 'reconnecting' });
+                return;
+            }
+            const wait = immediate ? 0 : backoffDelay(REOPEN_BACKOFF_MS, attempts.current);
+            if (wait === null) return;
+            attempts.current += 1;
+            update({ status: 'reconnecting' });
+            reconnectTimer.current = setTimeout(() => {
+                reconnectTimer.current = null;
+                void establish();
+            }, wait);
+        };
+        const failedAt = heldIceFailureAt.current;
+        const remaining = failedAt === null ? 0 : HOLD_AFTER_FAILED_MS - (Date.now() - failedAt);
+        if (remaining <= 0) {
+            heldIceFailureAt.current = null;
+            reopen();
+            return;
+        }
+        // Hold: leave the session and its handle in place, and only drop them
+        // when the window lapses with no recovery. A recovery that takes the
+        // status off `failed` runs this effect's cleanup and clears the timer.
+        const holdTimer = setTimeout(() => {
+            if (statusRef.current !== 'failed') return;
+            heldIceFailureAt.current = null;
+            reopen();
+        }, remaining);
+        return () => clearTimeout(holdTimer);
     }, [establish, cancelRestart, discardSession, endRemote, snapshot.status, snapshot.failure, update]);
 
     useEffect(() => () => {
@@ -1208,9 +1507,10 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         const openedRef = opened.current;
         const owner = signaling.current;
         opened.current = null;
-        signaling.current = null;
+        stopDialing();
+        dropCarrier(false);
         void endRemote(openedRef, owner);
-    }, [cancelReconnect, endRemote]);
+    }, [cancelReconnect, endRemote, stopDialing, dropCarrier]);
 
     // A phone that goes to the background must not leave a remote button held:
     // the desktop cannot know the finger left the glass. This is the same