@voicethere/client 0.7.14 → 0.7.16

package/dist/browser/browser-voice-session.js

@@ -4,7 +4,7 @@ import { createLocalSessionError, emitSessionError, isSessionErrorEvent, parseLe
 import { buildWebRtcConnectionStatus, isWebRtcConnectionReady, resolveReadinessProfile, } from "./webrtc-connection-status.js";
 import { collectWebRtcDiagnostics, } from "./webrtc-diagnostics.js";
 import { getDefaultBrowserRuntime, } from "./webrtc-runtime.js";
-import { closePeerConnectionAwaitable } from "./peer-connection-close.js";
+import { closePeerConnectionAwaitable, } from "./peer-connection-close.js";
 import { emitDiagnosticSafely, redactDiagnosticDetail, } from "./voice-session-diagnostics.js";
 import { waitForIceGatheringComplete } from "./wait-for-ice-gathering.js";
 import { isWebRtcConnectRetryError, WebRtcConnectRetryError, } from "./webrtc-connect-retry.js";
@@ -107,7 +107,8 @@ export async function connectBrowserVoiceSession(options) {
     let controlChannel = null;
     let syncChannel = null;
     let micStream = null;
-    const pendingIce = [];
+    /** ICE candidates queued by negotiation generation until that PC is ready. */
+    const pendingIceByGeneration = new Map();
     let connectionState = "new";
     let resolveConnected = null;
     let rejectConnected = null;
@@ -115,6 +116,63 @@ export async function connectBrowserVoiceSession(options) {
     let pendingConnectFailure = null;
     let stopMicPump = null;
     let gracefulDisconnect = false;
+    /** Bumped on each offer / disconnect so stale answer/ICE paths cannot resurrect. */
+    let negotiationGeneration = 0;
+    /** Serializes overlapping createAnswer/setLocalDescription/gather/send paths. */
+    let offerChain = Promise.resolve();
+    let disconnectAsyncInFlight = null;
+    /** Cached terminal disconnect outcome — repeats must not invent `closed` for a null pc. */
+    let terminalDisconnectResult = null;
+    /** Generation of the live PC (mirrors offer gen at create); ICE/handlers ignore mismatches. */
+    let activePcGeneration = 0;
+    /**
+     * Signaling/reconnect epoch. Incremented only when starting a reconnect flight
+     * or on disconnect (invalidates in-flight WS handlers).
+     */
+    let signalingEpoch = 0;
+    /** True single-flight: concurrent reconnect callers share this promise. */
+    let reconnectFlight = null;
+    /**
+     * After a timed_out/failed replace-close, further PC creation is blocked.
+     * The unsafe native PC may still be live — never invent `closed`.
+     */
+    let replacementBlockedResult = null;
+    /** Retained reference after failed replace-close (do not retry native close). */
+    let quarantinedPc = null;
+    /** Per-PC intentional retire tracking (replaces a global ignore boolean). */
+    const intentionallyRetiringPcs = new WeakSet();
+    const clearPendingIceGenerations = (keepGeneration) => {
+        if (keepGeneration === undefined) {
+            pendingIceByGeneration.clear();
+            return;
+        }
+        for (const generation of [...pendingIceByGeneration.keys()]) {
+            if (generation !== keepGeneration) {
+                pendingIceByGeneration.delete(generation);
+            }
+        }
+    };
+    const queuePendingIce = (generation, candidate) => {
+        const bucket = pendingIceByGeneration.get(generation);
+        if (bucket) {
+            bucket.push(candidate);
+        }
+        else {
+            pendingIceByGeneration.set(generation, [candidate]);
+        }
+    };
+    const drainPendingIce = async (targetPc, generation) => {
+        const bucket = pendingIceByGeneration.get(generation) ?? [];
+        pendingIceByGeneration.delete(generation);
+        for (const candidate of bucket) {
+            await targetPc.addIceCandidate(candidate).catch(() => undefined);
+        }
+    };
+    const assertReplacementAllowed = () => {
+        if (replacementBlockedResult) {
+            throw new Error(`peer replacement blocked: previous close ${replacementBlockedResult.status}`);
+        }
+    };
     const reconnectPolicy = options.reconnectPolicy ?? "same-session";
     const maxAutoReconnectAttempts = options.maxAutoReconnectAttempts ?? 4;
     let autoReconnectAttempts = 0;
@@ -150,6 +208,8 @@ export async function connectBrowserVoiceSession(options) {
             return;
         pendingConnectFailure = null;
         resolveConnected?.();
+        // Success path must drop waiter handles immediately (not only timeout/reject).
+        clearConnectedWait();
     };
     const updateConnectionSnapshot = (patch) => {
         Object.assign(connectionSnapshot, patch);
@@ -272,9 +332,11 @@ export async function connectBrowserVoiceSession(options) {
             debug?.warn("dc", "malformed", raw);
         }
     };
-    const wireBinaryChannel = (channel, kind) => {
+    const wireBinaryChannel = (channel, kind, isChannelCurrent) => {
         channel.binaryType = "arraybuffer";
         channel.onmessage = (event) => {
+            if (!isChannelCurrent())
+                return;
             if (typeof event.data === "string") {
                 if (kind === "control") {
                     handleControlJson(String(event.data));
@@ -304,21 +366,24 @@ export async function connectBrowserVoiceSession(options) {
         syncOutboundAudioTrack();
         debug?.info("voice", "mic_granted");
     }
-    let ignorePeerConnectionClose = false;
-    const resetPeerConnection = (options) => {
+    /**
+     * Retire the current PC with the awaitable close barrier.
+     * Callers that will create a replacement must abort when status is not `closed`.
+     * On timed_out/failed, quarantine and block all future replacements.
+     */
+    const retirePeerConnection = async (retireOptions) => {
+        if (replacementBlockedResult) {
+            return replacementBlockedResult;
+        }
         stopMicPump?.();
         stopMicPump = null;
         controlChannel = null;
         syncChannel = null;
-        if (pc) {
-            ignorePeerConnectionClose = true;
-            pc.close();
-            ignorePeerConnectionClose = false;
-        }
-        pc = null;
-        pendingIce.length = 0;
+        const localPc = pc;
+        activePcGeneration = 0;
+        clearPendingIceGenerations();
         connectionState = "new";
-        if (!options?.preserveConnectedWait) {
+        if (!retireOptions?.preserveConnectedWait) {
             connectedPromise = null;
             resolveConnected = null;
             rejectConnected = null;
@@ -331,13 +396,38 @@ export async function connectBrowserVoiceSession(options) {
             controlChannelOpen: false,
             syncChannelOpen: false,
         });
+        if (!localPc) {
+            return {
+                status: "closed",
+                mode: "sync",
+                durationMs: 0,
+                timedOut: false,
+            };
+        }
+        intentionallyRetiringPcs.add(localPc);
+        // Detach from live slot before awaiting close so handlers see identity change.
+        pc = null;
+        const closeResult = await closePeerConnectionAwaitable(localPc);
+        if (closeResult.status !== "closed") {
+            // Never invent closed later — retain unsafe PC, block replacement forever.
+            replacementBlockedResult = closeResult;
+            quarantinedPc = localPc;
+            terminalDisconnectResult = closeResult;
+            return closeResult;
+        }
+        return closeResult;
     };
-    const bindDataChannel = (channel, binding) => {
+    const bindDataChannel = (channel, binding, isPcCurrent) => {
         binding.assign(channel);
+        const isChannelCurrent = () => isPcCurrent() && binding.getAssigned() === channel;
         const markOpen = () => {
+            if (!isChannelCurrent())
+                return;
             updateConnectionSnapshot({ [binding.openField]: true });
         };
         channel.onopen = () => {
+            if (!isChannelCurrent())
+                return;
             debug?.info("dc", "open", binding.label);
             markOpen();
             binding.onOpen?.(channel);
@@ -345,17 +435,25 @@ export async function connectBrowserVoiceSession(options) {
         if (channel.readyState === "open")
             markOpen();
         channel.onclose = () => {
+            if (!isChannelCurrent())
+                return;
             debug?.info("dc", "close", binding.label);
             binding.assign(null);
             updateConnectionSnapshot({ [binding.openField]: false });
         };
-        wireBinaryChannel(channel, binding.kind);
+        channel.onerror = () => {
+            if (!isChannelCurrent())
+                return;
+            debug?.warn("dc", "error", binding.label);
+        };
+        wireBinaryChannel(channel, binding.kind, isChannelCurrent);
     };
-    const wireControl = (channel) => {
+    const wireControl = (channel, isPcCurrent) => {
         bindDataChannel(channel, {
             kind: "control",
             label: VOICE_CONTROL_CHANNEL_LABEL,
             openField: "controlChannelOpen",
+            getAssigned: () => controlChannel,
             assign: (next) => {
                 controlChannel = next;
             },
@@ -367,53 +465,74 @@ export async function connectBrowserVoiceSession(options) {
                     customer_context: options.customerContext,
                 }));
             },
-        });
+        }, isPcCurrent);
     };
-    const wireSync = (channel) => {
+    const wireSync = (channel, isPcCurrent) => {
         bindDataChannel(channel, {
             kind: "sync",
             label: VOICE_SYNC_CHANNEL_LABEL,
             openField: "syncChannelOpen",
+            getAssigned: () => syncChannel,
             assign: (next) => {
                 syncChannel = next;
             },
-        });
+        }, isPcCurrent);
     };
-    const onServerOffer = async (sdp) => {
+    const onServerOffer = async (sdp, offerGeneration) => {
         let step = "reset_peer_connection";
         const startedAtMs = Date.now();
         const logOfferStep = (name) => {
             debug?.info("signaling", "offer_step", `${name} elapsed_ms=${Date.now() - startedAtMs}`);
         };
+        const isOfferCurrent = () => offerGeneration === negotiationGeneration && !gracefulDisconnect;
         try {
+            if (!isOfferCurrent())
+                return;
+            assertReplacementAllowed();
             if (pc) {
-                ignorePeerConnectionClose = true;
-                pc.close();
-                ignorePeerConnectionClose = false;
-                pc = null;
-                pendingIce.length = 0;
-                controlChannel = null;
-                syncChannel = null;
-                connectionState = "new";
-                updateConnectionSnapshot({
-                    peerConnectionState: "new",
-                    inboundAudioTrack: false,
-                    outboundAudioTrack: false,
-                    controlChannelOpen: false,
-                    syncChannelOpen: false,
+                step = "await_previous_peer_close";
+                const closeResult = await retirePeerConnection({
+                    preserveConnectedWait: true,
                 });
+                emitDiagnosticSafely(options.onDiagnosticEvent, {
+                    type: "peer_close",
+                    status: closeResult.status,
+                    mode: closeResult.mode,
+                    durationMs: closeResult.durationMs,
+                    timedOut: closeResult.timedOut,
+                    context: "offer_replace",
+                    ...(closeResult.error !== undefined
+                        ? { error: redactDiagnosticDetail(closeResult.error) }
+                        : {}),
+                });
+                if (!isOfferCurrent())
+                    return;
+                if (closeResult.status !== "closed") {
+                    throw new Error(`cannot replace peer connection: previous close ${closeResult.status}`);
+                }
             }
             logOfferStep(step);
+            assertReplacementAllowed();
             step = "create_peer_connection";
             ensureConnectedPromise();
-            pc = new runtime.RTCPeerConnection({
+            const localPc = new runtime.RTCPeerConnection({
                 iceServers,
                 ...(options.iceTransportPolicy
                     ? { iceTransportPolicy: options.iceTransportPolicy }
                     : {}),
             });
+            pc = localPc;
+            activePcGeneration = offerGeneration;
+            const boundGeneration = offerGeneration;
+            const isPcCurrent = () => pc === localPc &&
+                activePcGeneration === boundGeneration &&
+                offerGeneration === negotiationGeneration &&
+                !gracefulDisconnect &&
+                !replacementBlockedResult;
             logOfferStep(step);
-            pc.ontrack = (event) => {
+            localPc.ontrack = (event) => {
+                if (!isPcCurrent())
+                    return;
                 if (event.track.kind !== "audio")
                     return;
                 const stream = event.streams[0] ?? new MediaStream([event.track]);
@@ -425,15 +544,19 @@ export async function connectBrowserVoiceSession(options) {
                 updateConnectionSnapshot({ inboundAudioTrack: true });
                 debug?.info("webrtc", "agent_audio_track");
             };
-            pc.ondatachannel = (event) => {
+            localPc.ondatachannel = (event) => {
+                if (!isPcCurrent())
+                    return;
                 if (event.channel.label === VOICE_CONTROL_CHANNEL_LABEL) {
-                    wireControl(event.channel);
+                    wireControl(event.channel, isPcCurrent);
                 }
                 else if (event.channel.label === VOICE_SYNC_CHANNEL_LABEL) {
-                    wireSync(event.channel);
+                    wireSync(event.channel, isPcCurrent);
                 }
             };
-            pc.onicecandidate = (event) => {
+            localPc.onicecandidate = (event) => {
+                if (!isPcCurrent())
+                    return;
                 if (event.candidate) {
                     sendToServer({
                         type: "ice-candidate",
@@ -442,41 +565,60 @@ export async function connectBrowserVoiceSession(options) {
                     });
                 }
             };
-            pc.onconnectionstatechange = () => {
-                connectionState = pc?.connectionState ?? "new";
+            localPc.onconnectionstatechange = () => {
+                const intentionalRetire = intentionallyRetiringPcs.has(localPc);
+                // Per-PC identity: never let a retired/stale PC mutate live globals.
+                if (pc !== localPc) {
+                    return;
+                }
+                if (!isPcCurrent() && !intentionalRetire)
+                    return;
+                connectionState = localPc.connectionState ?? "new";
                 debug?.info("webrtc", "connection_state", connectionState);
                 updateConnectionSnapshot({ peerConnectionState: connectionState });
                 if (connectionState === "connected") {
+                    if (!isPcCurrent())
+                        return;
                     autoReconnectAttempts = 0;
                     stopMicPump?.();
                     stopMicPump = null;
                     if (micStream && (options.micPump ?? "silent") === "silent") {
-                        stopMicPump = createMicPump(micStream, () => pc?.connectionState === "connected", debug);
+                        stopMicPump = createMicPump(micStream, () => pc === localPc && localPc.connectionState === "connected", debug);
                     }
                     syncOutboundAudioTrack();
                 }
                 else if (connectionState === "failed") {
+                    if (!isPcCurrent())
+                        return;
                     handleTransportFailure("failed", "webrtc_failed");
                 }
                 else if (connectionState === "closed") {
-                    if (ignorePeerConnectionClose || gracefulDisconnect) {
+                    if (intentionalRetire || gracefulDisconnect) {
                         if (gracefulDisconnect) {
                             rejectConnectedWait(new Error(`peer connection ${connectionState}`), false);
                         }
                         return;
                     }
+                    if (!isPcCurrent())
+                        return;
                     handleTransportFailure("closed", "webrtc_closed");
                 }
             };
-            pc.oniceconnectionstatechange = () => {
-                debug?.info("webrtc", "ice_connection_state", pc?.iceConnectionState ?? "unknown");
+            localPc.oniceconnectionstatechange = () => {
+                if (!isPcCurrent())
+                    return;
+                debug?.info("webrtc", "ice_connection_state", localPc.iceConnectionState ?? "unknown");
             };
-            pc.onicegatheringstatechange = () => {
-                debug?.info("webrtc", "ice_gathering_state", pc?.iceGatheringState ?? "unknown");
+            localPc.onicegatheringstatechange = () => {
+                if (!isPcCurrent())
+                    return;
+                debug?.info("webrtc", "ice_gathering_state", localPc.iceGatheringState ?? "unknown");
             };
             if (micStream) {
                 step = "attach_mic";
-                await attachMicTracks(pc, micStream);
+                await attachMicTracks(localPc, micStream);
+                if (!isPcCurrent())
+                    return;
                 syncOutboundAudioTrack();
                 if ((options.micPump ?? "silent") === "external") {
                     for (const track of micStream.getAudioTracks()) {
@@ -491,35 +633,49 @@ export async function connectBrowserVoiceSession(options) {
                 logOfferStep(step);
             }
             step = "set_remote_description";
+            if (!isOfferCurrent() || !isPcCurrent())
+                return;
             if (!remoteOfferHasIceUfrag(sdp)) {
                 throw new Error("set_remote_description called with no ice-ufrag (remote offer missing a=ice-ufrag)");
             }
-            await pc.setRemoteDescription(sdp);
+            await localPc.setRemoteDescription(sdp);
+            if (!isOfferCurrent() || !isPcCurrent())
+                return;
             logOfferStep(step);
             step = "drain_pending_ice";
-            for (const candidate of pendingIce.splice(0)) {
-                await pc.addIceCandidate(candidate);
-            }
+            if (!isOfferCurrent() || !isPcCurrent())
+                return;
+            await drainPendingIce(localPc, offerGeneration);
             logOfferStep(step);
             step = "create_answer";
-            const answer = await pc.createAnswer();
+            if (!isOfferCurrent() || !isPcCurrent())
+                return;
+            const answer = await localPc.createAnswer();
+            if (!isOfferCurrent() || !isPcCurrent())
+                return;
             logOfferStep(step);
             step = "set_local_description";
-            await pc.setLocalDescription(answer);
+            await localPc.setLocalDescription(answer);
+            if (!isOfferCurrent() || !isPcCurrent())
+                return;
             logOfferStep(step);
             step = "wait_ice_gathering";
-            await waitForIceGatheringComplete(pc);
+            await waitForIceGatheringComplete(localPc);
+            if (!isOfferCurrent() || !isPcCurrent())
+                return;
             logOfferStep(step);
             step = "send_answer";
             sendToServer({
                 type: "answer",
                 targetPeerId: VOICE_AGENT_SERVER_PEER_ID,
-                sdp: pc.localDescription,
+                sdp: localPc.localDescription,
             });
             debug?.info("signaling", "answer_sent");
             logOfferStep(step);
         }
         catch (error) {
+            if (!isOfferCurrent())
+                return;
             const detail = error instanceof Error ? error.message : String(error);
             const message = `WebRTC offer handler failed at ${step}: ${detail}`;
             debug?.error("signaling", "offer_handler_failed", `${message} elapsed_ms=${Date.now() - startedAtMs}`);
@@ -539,6 +695,20 @@ export async function connectBrowserVoiceSession(options) {
             }
         }
     };
+    /** One active negotiation at a time; newer offers supersede older generations. */
+    const enqueueServerOffer = (sdp) => {
+        if (replacementBlockedResult) {
+            debug?.warn("signaling", "offer_ignored_replacement_blocked", replacementBlockedResult.status);
+            return;
+        }
+        const offerGeneration = ++negotiationGeneration;
+        // Drop ICE buckets from prior generations; keep current gen for early candidates.
+        clearPendingIceGenerations(offerGeneration);
+        offerChain = offerChain
+            .catch(() => undefined)
+            .then(() => onServerOffer(sdp, offerGeneration));
+        void offerChain.catch(() => undefined);
+    };
     const scheduleAutoReconnect = (reason) => {
         if (gracefulDisconnect || reconnectPolicy === "new-session")
             return;
@@ -558,27 +728,44 @@ export async function connectBrowserVoiceSession(options) {
             });
         }, delayMs);
     };
-    const attachWsMessageHandler = () => {
-        if (!ws)
-            return;
-        ws.onmessage = (event) => {
+    const attachWsHandlers = (localWs, boundEpoch) => {
+        const isCurrentWs = () => ws === localWs && boundEpoch === signalingEpoch && !gracefulDisconnect;
+        localWs.onmessage = (event) => {
+            if (!isCurrentWs())
+                return;
             const message = JSON.parse(String(event.data));
             debug?.debug("signaling", message.type, message.peerId);
             switch (message.type) {
                 case "offer":
                     if (message.peerId === VOICE_AGENT_SERVER_PEER_ID && message.sdp) {
-                        void onServerOffer(message.sdp);
+                        enqueueServerOffer(message.sdp);
                     }
                     break;
                 case "ice-candidate":
                     if (message.peerId === VOICE_AGENT_SERVER_PEER_ID &&
                         message.candidate &&
-                        pc) {
-                        if (!pc.remoteDescription) {
-                            pendingIce.push(message.candidate);
+                        !gracefulDisconnect) {
+                        // Attribute to the latest negotiation generation (offer may already
+                        // be enqueued while PC is still null on the offerChain).
+                        const iceGeneration = negotiationGeneration;
+                        if (iceGeneration === 0)
+                            break;
+                        const targetPc = pc;
+                        if (targetPc &&
+                            activePcGeneration === iceGeneration &&
+                            pc === targetPc) {
+                            if (!targetPc.remoteDescription) {
+                                queuePendingIce(iceGeneration, message.candidate);
+                            }
+                            else {
+                                void targetPc.addIceCandidate(message.candidate).catch(() => {
+                                    /* ignore stale/failed ICE on captured PC */
+                                });
+                            }
                         }
                         else {
-                            void pc.addIceCandidate(message.candidate);
+                            // PC not yet materialized for this generation — queue for drain.
+                            queuePendingIce(iceGeneration, message.candidate);
                         }
                     }
                     break;
@@ -586,28 +773,86 @@ export async function connectBrowserVoiceSession(options) {
                     break;
             }
         };
+        localWs.onclose = () => {
+            if (!isCurrentWs())
+                return;
+            if (gracefulDisconnect || reconnectPolicy === "new-session")
+                return;
+            scheduleAutoReconnect("signaling_closed");
+        };
     };
-    const joinSignalingRoom = async (isReconnect) => {
+    const joinSignalingRoom = async (isReconnect, boundEpoch) => {
         if (isReconnect) {
-            resetPeerConnection({ preserveConnectedWait: true });
-            if (ws) {
-                ws.onclose = null;
-                ws.close();
-                ws = null;
+            assertReplacementAllowed();
+            const closeResult = await retirePeerConnection({
+                preserveConnectedWait: true,
+            });
+            emitDiagnosticSafely(options.onDiagnosticEvent, {
+                type: "peer_close",
+                status: closeResult.status,
+                mode: closeResult.mode,
+                durationMs: closeResult.durationMs,
+                timedOut: closeResult.timedOut,
+                context: "reconnect",
+                ...(closeResult.error !== undefined
+                    ? { error: redactDiagnosticDetail(closeResult.error) }
+                    : {}),
+            });
+            if (closeResult.status !== "closed") {
+                throw new Error(`reconnect blocked: peer close ${closeResult.status}`);
             }
+            if (boundEpoch !== signalingEpoch) {
+                return;
+            }
+            const previousWs = ws;
+            if (previousWs) {
+                previousWs.onclose = null;
+                previousWs.onmessage = null;
+                previousWs.onerror = null;
+                try {
+                    previousWs.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                if (ws === previousWs) {
+                    ws = null;
+                }
+            }
+        }
+        if (boundEpoch !== signalingEpoch) {
+            return;
         }
-        ws = new runtime.WebSocket(signalingUrl);
+        assertReplacementAllowed();
+        const nextWs = new runtime.WebSocket(signalingUrl);
+        if (boundEpoch !== signalingEpoch) {
+            try {
+                nextWs.close();
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
+        ws = nextWs;
         await new Promise((resolve, reject) => {
-            if (!ws)
-                return reject(new Error("WebSocket missing"));
-            ws.onopen = () => {
+            nextWs.onopen = () => {
+                if (ws !== nextWs || boundEpoch !== signalingEpoch) {
+                    reject(new Error("WebSocket superseded during reconnect"));
+                    return;
+                }
+                // sendSignal uses global ws — only send when this socket is current.
                 sendSignal({ type: "join", room: roomId, peerId });
                 debug?.info("signaling", "join_sent", `room=${roomId} peer=${peerId}`);
                 debug?.info("signaling", isReconnect ? "rejoined" : "joined", roomId);
                 updateConnectionSnapshot({ signalingJoined: true });
                 resolve();
             };
-            ws.onerror = () => {
+            nextWs.onerror = () => {
+                if (ws !== nextWs || boundEpoch !== signalingEpoch) {
+                    reject(new Error("WebSocket superseded during reconnect"));
+                    return;
+                }
                 dispatchConnectionError(createConnectionError("WebSocket error", {
                     subsystem: "webrtc",
                     sessionId: orchestratorSessionId,
@@ -618,31 +863,86 @@ export async function connectBrowserVoiceSession(options) {
                 reject(new Error("WebSocket error"));
             };
         });
-        attachWsMessageHandler();
-        ws.onclose = () => {
-            if (gracefulDisconnect || reconnectPolicy === "new-session")
-                return;
-            scheduleAutoReconnect("signaling_closed");
-        };
+        if (boundEpoch !== signalingEpoch) {
+            if (ws === nextWs) {
+                nextWs.onclose = null;
+                nextWs.onmessage = null;
+                try {
+                    nextWs.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                ws = null;
+            }
+            return;
+        }
+        attachWsHandlers(nextWs, boundEpoch);
         if (isReconnect) {
             debug?.info("session", "same_session_reconnect", orchestratorSessionId);
         }
     };
-    const reconnectSignaling = async () => {
-        await joinSignalingRoom(true);
+    const reconnectSignaling = () => {
+        if (gracefulDisconnect) {
+            return Promise.resolve();
+        }
+        if (replacementBlockedResult) {
+            return Promise.reject(new Error(`reconnect blocked: previous close ${replacementBlockedResult.status}`));
+        }
+        // True single-flight: all concurrent callers share one flight.
+        if (reconnectFlight) {
+            return reconnectFlight;
+        }
+        const epoch = ++signalingEpoch;
+        const flight = joinSignalingRoom(true, epoch).finally(() => {
+            if (reconnectFlight === flight) {
+                reconnectFlight = null;
+            }
+        });
+        reconnectFlight = flight;
+        return flight;
+    };
+    const cleanupFailedInitialJoin = () => {
+        const localWs = ws;
+        ws = null;
+        if (localWs) {
+            localWs.onclose = null;
+            localWs.onmessage = null;
+            localWs.onerror = null;
+            try {
+                localWs.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const localMic = micStream;
+        micStream = null;
+        localMic?.getTracks().forEach((track) => track.stop());
+        updateConnectionSnapshot({
+            signalingJoined: false,
+            outboundAudioTrack: false,
+        });
     };
-    await joinSignalingRoom(false);
+    try {
+        await joinSignalingRoom(false, signalingEpoch);
+    }
+    catch (error) {
+        cleanupFailedInitialJoin();
+        throw error;
+    }
     publishConnectionStatus();
+    // Do not log on every failed send — open/close transitions are already
+    // emitted once via bindDataChannel (`dc/open`, `dc/close`). Callers (e.g. e2e
+    // readiness polls) may probe often while connecting.
     const requireOpenControl = () => {
         if (!controlChannel || controlChannel.readyState !== "open") {
-            debug?.error("dc", "control_not_open");
             throw new Error("voice-control data channel is not open");
         }
         return controlChannel;
     };
     const requireOpenSync = () => {
         if (!syncChannel || syncChannel.readyState !== "open") {
-            debug?.error("dc", "sync_not_open");
             throw new Error("voicethere-sync data channel is not open");
         }
         return syncChannel;
@@ -664,21 +964,27 @@ export async function connectBrowserVoiceSession(options) {
             throw error;
         };
         while (true) {
-            if (isWebRtcConnectionReady(connectionSnapshot, readinessProfile))
+            if (isWebRtcConnectionReady(connectionSnapshot, readinessProfile)) {
+                clearConnectedWait();
                 return;
+            }
             if (pendingConnectFailure) {
                 throw pendingConnectFailure;
             }
+            if (gracefulDisconnect) {
+                throw new Error("disconnected");
+            }
             const remainingMs = deadlineMs - Date.now();
             if (remainingMs <= 0) {
                 throwConnectTimeout();
             }
             const waitPromise = ensureConnectedPromise();
+            let timer;
             try {
                 await Promise.race([
                     waitPromise,
                     new Promise((_, reject) => {
-                        setTimeout(() => {
+                        timer = setTimeout(() => {
                             reject(new Error("__wait_for_connected_timeout__"));
                         }, remainingMs);
                     }),
@@ -695,8 +1001,15 @@ export async function connectBrowserVoiceSession(options) {
                 }
                 throw error;
             }
-            if (isWebRtcConnectionReady(connectionSnapshot, readinessProfile))
+            finally {
+                // Success, retry, and disconnect paths must not leave a live timer.
+                if (timer)
+                    clearTimeout(timer);
+            }
+            if (isWebRtcConnectionReady(connectionSnapshot, readinessProfile)) {
+                clearConnectedWait();
                 return;
+            }
         }
     };
     return {
@@ -750,19 +1063,30 @@ export async function connectBrowserVoiceSession(options) {
         disconnect: () => {
             // Sync terminal invalidation — must not await native close (reconnect opens WS promptly).
             gracefulDisconnect = true;
+            negotiationGeneration += 1;
+            activePcGeneration = 0;
+            clearPendingIceGenerations();
+            // Invalidate in-flight reconnect WS handlers / epoch.
+            signalingEpoch += 1;
             if (reconnectTimer)
                 clearTimeout(reconnectTimer);
             reconnectTimer = undefined;
             stopMicPump?.();
             stopMicPump = null;
+            rejectConnected?.(new Error("disconnected"));
+            clearConnectedWait();
+            pendingConnectFailure = null;
+            const asyncOwnsPeerClose = disconnectAsyncInFlight !== null;
             const localControl = controlChannel;
             const localSync = syncChannel;
-            const localPc = pc;
+            const localPc = asyncOwnsPeerClose ? null : pc;
             const localWs = ws;
             const localMic = micStream;
             controlChannel = null;
             syncChannel = null;
-            pc = null;
+            if (!asyncOwnsPeerClose) {
+                pc = null;
+            }
             ws = null;
             micStream = null;
             try {
@@ -788,11 +1112,28 @@ export async function connectBrowserVoiceSession(options) {
                     /* ignore */
                 }
             }
-            try {
-                localPc?.close();
+            // Do not sync-close while disconnectAsync owns native close — that masks
+            // timed_out/failed outcomes from soak callers awaiting the async barrier.
+            // Also do not sync-close a quarantined PC (native close already timed out).
+            if (localPc && localPc !== quarantinedPc) {
+                intentionallyRetiringPcs.add(localPc);
+                try {
+                    localPc.close();
+                }
+                catch {
+                    /* ignore */
+                }
             }
-            catch {
-                /* ignore */
+            // If sync disconnect wins on an async-capable runtime, record an explicit
+            // sync terminal outcome — later disconnectAsync must not claim async close.
+            // Prefer retained replacement-blocked failure over inventing closed.
+            if (!asyncOwnsPeerClose && !terminalDisconnectResult) {
+                terminalDisconnectResult = replacementBlockedResult ?? {
+                    status: "closed",
+                    mode: "sync",
+                    durationMs: 0,
+                    timedOut: false,
+                };
             }
             localMic?.getTracks().forEach((track) => track.stop());
             updateConnectionSnapshot({
@@ -806,66 +1147,107 @@ export async function connectBrowserVoiceSession(options) {
             debug?.info("session", "disconnected");
         },
         disconnectAsync: async () => {
-            gracefulDisconnect = true;
-            if (reconnectTimer)
-                clearTimeout(reconnectTimer);
-            reconnectTimer = undefined;
-            stopMicPump?.();
-            stopMicPump = null;
-            const localControl = controlChannel;
-            const localSync = syncChannel;
-            const localPc = pc;
-            const localWs = ws;
-            const localMic = micStream;
-            controlChannel = null;
-            syncChannel = null;
-            pc = null;
-            ws = null;
-            micStream = null;
-            try {
-                localControl?.close();
+            if (terminalDisconnectResult) {
+                return terminalDisconnectResult;
             }
-            catch {
-                /* ignore */
+            if (replacementBlockedResult) {
+                // Unsafe old PC already retired/quarantined — surface that strict failure.
+                terminalDisconnectResult = replacementBlockedResult;
+                return replacementBlockedResult;
             }
-            try {
-                localSync?.close();
-            }
-            catch {
-                /* ignore */
+            if (disconnectAsyncInFlight) {
+                return disconnectAsyncInFlight;
             }
-            if (localWs) {
-                localWs.onclose = null;
-                localWs.onmessage = null;
-                localWs.onerror = null;
+            disconnectAsyncInFlight = (async () => {
+                gracefulDisconnect = true;
+                negotiationGeneration += 1;
+                activePcGeneration = 0;
+                clearPendingIceGenerations();
+                signalingEpoch += 1;
+                if (reconnectTimer)
+                    clearTimeout(reconnectTimer);
+                reconnectTimer = undefined;
+                stopMicPump?.();
+                stopMicPump = null;
+                rejectConnected?.(new Error("disconnected"));
+                clearConnectedWait();
+                pendingConnectFailure = null;
+                const localControl = controlChannel;
+                const localSync = syncChannel;
+                const localPc = pc;
+                const localWs = ws;
+                const localMic = micStream;
+                controlChannel = null;
+                syncChannel = null;
+                pc = null;
+                ws = null;
+                micStream = null;
                 try {
-                    localWs.close();
+                    localControl?.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                try {
+                    localSync?.close();
                 }
                 catch {
                     /* ignore */
                 }
+                if (localWs) {
+                    localWs.onclose = null;
+                    localWs.onmessage = null;
+                    localWs.onerror = null;
+                    try {
+                        localWs.close();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                localMic?.getTracks().forEach((track) => track.stop());
+                // Never retry native close on a quarantined PC after timed_out/failed.
+                const closeTarget = localPc && localPc !== quarantinedPc ? localPc : null;
+                if (closeTarget) {
+                    intentionallyRetiringPcs.add(closeTarget);
+                }
+                const closeResult = closeTarget
+                    ? await closePeerConnectionAwaitable(closeTarget)
+                    : (replacementBlockedResult ?? {
+                        status: "closed",
+                        mode: "sync",
+                        durationMs: 0,
+                        timedOut: false,
+                    });
+                terminalDisconnectResult = closeResult;
+                emitDiagnosticSafely(options.onDiagnosticEvent, {
+                    type: "peer_close",
+                    status: closeResult.status,
+                    mode: closeResult.mode,
+                    durationMs: closeResult.durationMs,
+                    timedOut: closeResult.timedOut,
+                    context: "disconnect",
+                    ...(closeResult.error !== undefined
+                        ? { error: redactDiagnosticDetail(closeResult.error) }
+                        : {}),
+                });
+                updateConnectionSnapshot({
+                    signalingJoined: false,
+                    peerConnectionState: "closed",
+                    inboundAudioTrack: false,
+                    outboundAudioTrack: false,
+                    controlChannelOpen: false,
+                    syncChannelOpen: false,
+                });
+                debug?.info("session", "disconnected", `peer_close=${closeResult.status}`);
+                return closeResult;
+            })();
+            try {
+                return await disconnectAsyncInFlight;
+            }
+            finally {
+                disconnectAsyncInFlight = null;
             }
-            localMic?.getTracks().forEach((track) => track.stop());
-            const closeResult = await closePeerConnectionAwaitable(localPc);
-            emitDiagnosticSafely(options.onDiagnosticEvent, {
-                type: "peer_close",
-                mode: closeResult.mode,
-                durationMs: closeResult.durationMs,
-                timedOut: closeResult.timedOut,
-                context: "disconnect",
-                ...(closeResult.error !== undefined
-                    ? { error: redactDiagnosticDetail(closeResult.error) }
-                    : {}),
-            });
-            updateConnectionSnapshot({
-                signalingJoined: false,
-                peerConnectionState: "closed",
-                inboundAudioTrack: false,
-                outboundAudioTrack: false,
-                controlChannelOpen: false,
-                syncChannelOpen: false,
-            });
-            debug?.info("session", "disconnected");
         },
     };
 }