@voicethere/client 0.9.0 → 0.11.0

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

@@ -1,7 +1,7 @@
 import { createConnectionError, dispatchConnectionError, } from "../connection-errors.js";
 import { appendJoinToken } from "../resolve-connection.js";
 import { createLocalSessionError, emitSessionError, isSessionErrorEvent, parseLegacyAgentError, } from "../session-errors.js";
-import { buildWebRtcConnectionStatus, isHalfOpenConnection, formatWebRtcConnectTimeoutMessage, isWebRtcConnectionReady, resolveHalfOpenFailFastMs, resolveReadinessProfile, } from "./webrtc-connection-status.js";
+import { buildWebRtcConnectionStatus, CONNECTION_INTERRUPTED_MESSAGE, CONNECTION_LOST_MESSAGE, CONNECTION_RESTORED_MESSAGE, CONNECTION_SESSION_ENDED_MESSAGE, isHalfOpenConnection, formatWebRtcConnectTimeoutMessage, isWebRtcConnectionReady, resolveHalfOpenFailFastMs, 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";
@@ -58,6 +58,32 @@ function redactSignalingUrlForLog(url) {
         return url.split("?")[0] ?? url;
     }
 }
+/** Default total time from the first transport loss during which the client keeps trying. */
+export const DEFAULT_RECONNECT_BUDGET_MS = 45_000;
+/** ICE `disconnected` must last this long before recovery starts. */
+const ICE_DISCONNECTED_GRACE_MS = 2_000;
+/** Time the relay ICE recovery rejoin gets to reach readiness before escalating. */
+const ICE_RECOVERY_SETTLE_MS = 5_000;
+/** Time a same-session reconnect gets to reach readiness before the next attempt. */
+const RECONNECT_SETTLE_MS = 10_000;
+/** Reconnect signaling WebSocket must open within this time. */
+const SIGNALING_CONNECT_TIMEOUT_MS = 5_000;
+/** Delay before same-session reconnect attempt 1, 2, 3, then every later attempt. */
+const RECONNECT_BACKOFF_MS = [1_000, 2_000, 4_000, 5_000];
+/** The gateway rejected the reconnect token (HTTP 401): the session no longer exists. */
+class SessionEndedDuringReconnectError extends Error {
+    constructor() {
+        super("signaling rejected the reconnect token (HTTP 401)");
+        this.name = "SessionEndedDuringReconnectError";
+    }
+}
+/**
+ * Sent on the control channel when the integrator ends the session, so the runner
+ * closes immediately instead of holding a dropped peer through its network-drop grace.
+ */
+export const CLIENT_HANGUP_MESSAGE_TYPE = "client_hangup";
+/** Max wait for the hangup message to leave the send buffer during `disconnectAsync`. */
+const CLIENT_HANGUP_DRAIN_MS = 200;
 export const VOICE_AGENT_SERVER_PEER_ID = "voice-agent-server";
 export const VOICE_CONTROL_CHANNEL_LABEL = "voice-control";
 /** High-frequency binary sync channel (matches `@node-webrtc-rust/sdk/voice`). */
@@ -239,7 +265,15 @@ export async function connectBrowserVoiceSession(options) {
         }
     };
     const reconnectPolicy = options.reconnectPolicy ?? "same-session";
-    const maxAutoReconnectAttempts = options.maxAutoReconnectAttempts ?? 4;
+    const reconnectBudgetMs = options.reconnectBudgetMs ?? DEFAULT_RECONNECT_BUDGET_MS;
+    const statusMessages = {
+        interrupted: options.connectionStatusMessages?.interrupted ??
+            CONNECTION_INTERRUPTED_MESSAGE,
+        restored: options.connectionStatusMessages?.restored ?? CONNECTION_RESTORED_MESSAGE,
+        lost: options.connectionStatusMessages?.lost ?? CONNECTION_LOST_MESSAGE,
+        sessionEnded: options.connectionStatusMessages?.sessionEnded ??
+            CONNECTION_SESSION_ENDED_MESSAGE,
+    };
     const maxIceRecoveryAttempts = options.maxIceRecoveryAttempts ?? 1;
     const iceRecoveryStuckCheckingMs = options.iceRecoveryStuckCheckingMs ?? 12_000;
     let effectiveIceTransportPolicy = options.iceTransportPolicy;
@@ -249,6 +283,17 @@ export async function connectBrowserVoiceSession(options) {
     let iceStuckWatchTimer;
     let iceCheckingSinceMs = null;
     let hasReachedReadyOnce = false;
+    /** Cap on same-session reconnect attempts: explicit option, else budget-driven once ready. */
+    const maxAutoReconnectAttemptsLimit = () => options.maxAutoReconnectAttempts ??
+        (hasReachedReadyOnce ? Number.POSITIVE_INFINITY : 4);
+    /** Wall-clock start of the current transport outage (null when healthy). */
+    let outageStartMs = null;
+    let outageRecoveryVia = "ice-restart";
+    /** True once the live PC is gone or ICE itself was lost, so "ready" means recovered. */
+    let outageRestoreEligible = false;
+    let budgetTimer;
+    let iceDisconnectedTimer;
+    let settleTimer;
     let awaitingReconnectedCallback = false;
     let lastReconnectAttemptForCallback = 0;
     let lastReconnectReason;
@@ -358,6 +403,7 @@ export async function connectBrowserVoiceSession(options) {
     };
     const updateConnectionSnapshot = (patch) => {
         Object.assign(connectionSnapshot, patch);
+        markRestoredIfRecovered();
         publishConnectionStatus();
         tryResolveConnected();
     };
@@ -426,27 +472,170 @@ export async function connectBrowserVoiceSession(options) {
         }
         options.onControlMessage?.(message);
     };
-    const emitAutoReconnectExhausted = (reason) => {
+    const clearRecoveryTimers = () => {
+        if (budgetTimer)
+            clearTimeout(budgetTimer);
+        if (iceDisconnectedTimer)
+            clearTimeout(iceDisconnectedTimer);
+        if (settleTimer)
+            clearTimeout(settleTimer);
+        budgetTimer = undefined;
+        iceDisconnectedTimer = undefined;
+        settleTimer = undefined;
+    };
+    /** Terminal recovery failure: stop retrying, tell the integrator, publish `lost`. */
+    const failRecovery = (input) => {
         if (gracefulDisconnect)
             return;
         awaitingReconnectedCallback = false;
-        debug?.warn("session", "auto_reconnect_exhausted", reason);
+        debug?.warn("session", input.logName, input.logDetail);
         gracefulDisconnect = true;
+        clearRecoveryTimers();
+        if (reconnectTimer)
+            clearTimeout(reconnectTimer);
+        reconnectTimer = undefined;
+        // Invalidate in-flight reconnect flights and their WebSocket handlers.
+        signalingEpoch += 1;
         notifySessionError(createLocalSessionError({
-            code: "WEBRTC_RECONNECT_EXHAUSTED",
-            message: `Auto-reconnect exhausted after ${maxAutoReconnectAttempts} attempts (${reason})`,
+            code: input.code,
+            message: input.errorMessage,
             sessionId: orchestratorSessionId,
             recoverable: false,
         }));
+        rejectConnectedWait(new Error(input.errorMessage), false);
         updateConnectionSnapshot({
             signalingJoined: false,
             controlChannelOpen: false,
             syncChannelOpen: false,
+            recovery: {
+                state: "lost",
+                reason: input.code,
+                message: input.statusMessage,
+            },
             ...(connectionSnapshot.peerConnectionState !== "closed"
                 ? { peerConnectionState: "closed" }
                 : {}),
         });
     };
+    const emitAutoReconnectExhausted = (reason) => {
+        const elapsedMs = outageStartMs !== null ? Date.now() - outageStartMs : undefined;
+        failRecovery({
+            code: "WEBRTC_RECONNECT_EXHAUSTED",
+            errorMessage: `Auto-reconnect exhausted after ${autoReconnectAttempts} attempts${elapsedMs !== undefined ? ` in ${elapsedMs} ms` : ""} (${reason})`,
+            statusMessage: statusMessages.lost,
+            logName: "auto_reconnect_exhausted",
+            logDetail: reason,
+        });
+    };
+    const endSessionDuringReconnect = () => {
+        failRecovery({
+            code: "SESSION_ENDED_DURING_RECONNECT",
+            errorMessage: statusMessages.sessionEnded,
+            statusMessage: statusMessages.sessionEnded,
+            logName: "session_ended_during_reconnect",
+            logDetail: "reconnect token rejected with HTTP 401",
+        });
+    };
+    /**
+     * Start tracking a transport outage (only after the session was ready once).
+     * The budget runs from the first loss, not from when recovery work begins.
+     */
+    const beginOutage = (reason, lossAtMs, iceLost) => {
+        if (!hasReachedReadyOnce || gracefulDisconnect)
+            return;
+        if (reconnectPolicy === "new-session")
+            return;
+        if (outageStartMs !== null)
+            return;
+        outageStartMs = lossAtMs;
+        outageRecoveryVia = "ice-restart";
+        outageRestoreEligible = iceLost;
+        const remainingMs = Math.max(0, reconnectBudgetMs - (Date.now() - lossAtMs));
+        budgetTimer = setTimeout(() => {
+            budgetTimer = undefined;
+            emitAutoReconnectExhausted("budget_exhausted");
+        }, remainingMs);
+        debug?.warn("session", "transport_lost", reason);
+        updateConnectionSnapshot({
+            recovery: {
+                state: "interrupted",
+                sinceMs: Date.now() - lossAtMs,
+                message: statusMessages.interrupted,
+            },
+        });
+    };
+    /** Called from {@link updateConnectionSnapshot}; assigns `recovery` without publishing. */
+    const markRestoredIfRecovered = () => {
+        if (outageStartMs === null || gracefulDisconnect)
+            return;
+        if (!outageRestoreEligible)
+            return;
+        if (!isWebRtcConnectionReady(connectionSnapshot, readinessProfile))
+            return;
+        const ice = connectionSnapshot.iceConnectionState;
+        if (ice === "disconnected" || ice === "failed" || ice === "closed")
+            return;
+        const downtimeMs = Date.now() - outageStartMs;
+        outageStartMs = null;
+        outageRestoreEligible = false;
+        clearRecoveryTimers();
+        debug?.info("session", "transport_restored", `downtime_ms=${downtimeMs} via=${outageRecoveryVia}`);
+        connectionSnapshot.recovery = {
+            state: "restored",
+            downtimeMs,
+            via: outageRecoveryVia,
+            message: statusMessages.restored,
+        };
+    };
+    const clearIceDisconnectedTimer = () => {
+        if (iceDisconnectedTimer)
+            clearTimeout(iceDisconnectedTimer);
+        iceDisconnectedTimer = undefined;
+    };
+    /** Escalate when a recovery rejoin does not reach readiness in time. */
+    const armSettleTimer = (ms, reason) => {
+        if (outageStartMs === null || gracefulDisconnect)
+            return;
+        if (settleTimer)
+            clearTimeout(settleTimer);
+        settleTimer = setTimeout(() => {
+            settleTimer = undefined;
+            if (outageStartMs === null || gracefulDisconnect)
+                return;
+            debug?.warn("session", "recovery_settle_timeout", reason);
+            scheduleAutoReconnect(`${reason}_timeout`);
+        }, ms);
+    };
+    /** ICE/PC `disconnected`: start recovery if it lasts longer than the grace period. */
+    const noteIceDisconnected = (localPc) => {
+        if (!hasReachedReadyOnce || gracefulDisconnect)
+            return;
+        if (reconnectPolicy === "new-session")
+            return;
+        if (iceDisconnectedTimer || outageStartMs !== null)
+            return;
+        const lossAtMs = Date.now();
+        iceDisconnectedTimer = setTimeout(() => {
+            iceDisconnectedTimer = undefined;
+            if (pc !== localPc || gracefulDisconnect)
+                return;
+            beginOutage("ice_disconnected", lossAtMs, true);
+            startRecovery("ice_disconnected");
+        }, ICE_DISCONNECTED_GRACE_MS);
+    };
+    const startRecovery = (reason) => {
+        if (gracefulDisconnect || reconnectPolicy === "new-session")
+            return;
+        if (canIceRecover()) {
+            scheduleIceRecovery(reason);
+        }
+        else if (canAutoReconnectTransport()) {
+            scheduleAutoReconnect(reason);
+        }
+        else {
+            emitAutoReconnectExhausted(reason);
+        }
+    };
     const ensureConnectedPromise = () => {
         if (!connectedPromise) {
             connectedPromise = new Promise((resolve, reject) => {
@@ -465,7 +654,7 @@ export async function connectBrowserVoiceSession(options) {
     const canAutoReconnectTransport = () => {
         if (gracefulDisconnect || reconnectPolicy === "new-session")
             return false;
-        return autoReconnectAttempts < maxAutoReconnectAttempts;
+        return autoReconnectAttempts < maxAutoReconnectAttemptsLimit();
     };
     const reconnectInfo = (reason) => ({
         reason: reason ?? lastReconnectReason ?? "unknown",
@@ -504,7 +693,13 @@ export async function connectBrowserVoiceSession(options) {
         if (reconnectTimer)
             clearTimeout(reconnectTimer);
         reconnectTimer = setTimeout(() => {
-            void reconnectSignaling().catch((error) => {
+            void reconnectSignaling()
+                .then(() => armSettleTimer(ICE_RECOVERY_SETTLE_MS, "ice_recovery"))
+                .catch((error) => {
+                if (error instanceof SessionEndedDuringReconnectError) {
+                    endSessionDuringReconnect();
+                    return;
+                }
                 debug?.warn("session", "ice_recovery_failed", error instanceof Error ? error.message : String(error));
                 if (canAutoReconnectTransport()) {
                     scheduleAutoReconnect(reason);
@@ -592,6 +787,8 @@ export async function connectBrowserVoiceSession(options) {
     const handleTransportFailure = (state, reconnectReason) => {
         stopMicPump?.();
         stopMicPump = null;
+        clearIceDisconnectedTimer();
+        beginOutage(reconnectReason, Date.now(), state === "failed");
         if (!gracefulDisconnect) {
             if (state === "failed") {
                 notifySessionError({
@@ -624,8 +821,8 @@ export async function connectBrowserVoiceSession(options) {
             scheduleAutoReconnect(reconnectReason);
         }
         else if (!gracefulDisconnect &&
-            maxAutoReconnectAttempts > 0 &&
-            autoReconnectAttempts >= maxAutoReconnectAttempts) {
+            maxAutoReconnectAttemptsLimit() > 0 &&
+            autoReconnectAttempts >= maxAutoReconnectAttemptsLimit()) {
             emitAutoReconnectExhausted(reconnectReason);
         }
     };
@@ -715,6 +912,9 @@ export async function connectBrowserVoiceSession(options) {
         }
         stopMicPump?.();
         stopMicPump = null;
+        clearIceDisconnectedTimer();
+        if (outageStartMs !== null)
+            outageRestoreEligible = true;
         controlChannel = null;
         syncChannel = null;
         const localPc = pc;
@@ -931,6 +1131,7 @@ export async function connectBrowserVoiceSession(options) {
                 if (connectionState === "connected") {
                     if (!isPcCurrent())
                         return;
+                    clearIceDisconnectedTimer();
                     autoReconnectAttempts = 0;
                     iceRecoveryAttempts = 0;
                     stopIceStuckWatch();
@@ -941,6 +1142,11 @@ export async function connectBrowserVoiceSession(options) {
                     }
                     syncOutboundAudioTrack();
                 }
+                else if (connectionState === "disconnected") {
+                    if (!isPcCurrent())
+                        return;
+                    noteIceDisconnected(localPc);
+                }
                 else if (connectionState === "failed") {
                     if (!isPcCurrent())
                         return;
@@ -963,6 +1169,13 @@ export async function connectBrowserVoiceSession(options) {
                     return;
                 const iceConnectionState = localPc.iceConnectionState ?? "new";
                 debug?.info("webrtc", "ice_connection_state", iceConnectionState);
+                if (iceConnectionState === "disconnected") {
+                    noteIceDisconnected(localPc);
+                }
+                else if (iceConnectionState === "connected" ||
+                    iceConnectionState === "completed") {
+                    clearIceDisconnectedTimer();
+                }
                 updateConnectionSnapshot({ iceConnectionState });
             };
             localPc.onicegatheringstatechange = () => {
@@ -1107,7 +1320,8 @@ export async function connectBrowserVoiceSession(options) {
     const scheduleAutoReconnect = (reason) => {
         if (gracefulDisconnect || reconnectPolicy === "new-session")
             return;
-        if (autoReconnectAttempts >= maxAutoReconnectAttempts) {
+        beginOutage(reason, Date.now(), false);
+        if (autoReconnectAttempts >= maxAutoReconnectAttemptsLimit()) {
             emitAutoReconnectExhausted(reason);
             return;
         }
@@ -1116,16 +1330,37 @@ export async function connectBrowserVoiceSession(options) {
         awaitingReconnectedCallback = true;
         lastReconnectReason = reason;
         options.onReconnecting?.(autoReconnectAttempts, reconnectInfo(reason));
-        const delayMs = Math.min(1000 * 2 ** (autoReconnectAttempts - 1), 8000);
+        const delayMs = RECONNECT_BACKOFF_MS[Math.min(autoReconnectAttempts - 1, RECONNECT_BACKOFF_MS.length - 1)];
         if (reconnectTimer)
             clearTimeout(reconnectTimer);
+        if (settleTimer)
+            clearTimeout(settleTimer);
+        settleTimer = undefined;
         reconnectTimer = setTimeout(() => {
-            void reconnectSignaling().catch((error) => {
+            outageRecoveryVia = "reconnect";
+            void reconnectSignaling()
+                .then(() => armSettleTimer(RECONNECT_SETTLE_MS, "reconnect"))
+                .catch((error) => {
+                if (error instanceof SessionEndedDuringReconnectError) {
+                    endSessionDuringReconnect();
+                    return;
+                }
                 debug?.warn("session", "auto_reconnect_failed", error instanceof Error ? error.message : String(error));
                 scheduleAutoReconnect(reason);
             });
         }, delayMs);
     };
+    /**
+     * One structured line per signaling WebSocket failure (token redacted).
+     * `httpStatus` is only known on runtimes that expose the upgrade response (Node `ws`).
+     */
+    const logSignalingFailure = (input) => {
+        const elapsedMs = Date.now() - (outageStartMs ?? input.startedAtMs);
+        const reason = input.close?.reason && input.close.reason.length > 0
+            ? input.close.reason
+            : "n/a";
+        debug?.error("signaling", "ws_error", `signaling ws failed attempt=${autoReconnectAttempts} elapsed=${elapsedMs} phase=${input.phase} code=${input.close?.code ?? "n/a"} reason=${reason} httpStatus=${input.httpStatus ?? "n/a"} wasClean=${input.close?.wasClean ?? "n/a"} url=${redactSignalingUrlForLog(input.url)}`);
+    };
     const attachWsHandlers = (localWs, boundEpoch) => {
         const isCurrentWs = () => ws === localWs && boundEpoch === signalingEpoch && !gracefulDisconnect;
         localWs.onmessage = (event) => {
@@ -1171,17 +1406,39 @@ export async function connectBrowserVoiceSession(options) {
                     break;
             }
         };
-        localWs.onclose = () => {
+        localWs.onclose = (event) => {
             if (!isCurrentWs())
                 return;
             if (gracefulDisconnect || reconnectPolicy === "new-session")
                 return;
+            logSignalingFailure({
+                phase: "open",
+                url: signalingUrl,
+                startedAtMs: Date.now(),
+                close: event,
+            });
             scheduleAutoReconnect("signaling_closed");
         };
     };
     const joinSignalingRoom = async (isReconnect, boundEpoch) => {
         if (isReconnect) {
             assertReplacementAllowed();
+            // Close the old socket ourselves first; never wait for it to notice the outage.
+            const staleWs = ws;
+            if (staleWs) {
+                staleWs.onclose = null;
+                staleWs.onmessage = null;
+                staleWs.onerror = null;
+                try {
+                    staleWs.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                if (ws === staleWs) {
+                    ws = null;
+                }
+            }
             const closeResult = await retirePeerConnection({
                 preserveConnectedWait: true,
             });
@@ -1222,7 +1479,9 @@ export async function connectBrowserVoiceSession(options) {
             return;
         }
         assertReplacementAllowed();
-        const nextWs = new runtime.WebSocket(signalingUrl);
+        const connectUrl = signalingUrl;
+        const connectStartedAtMs = Date.now();
+        const nextWs = new runtime.WebSocket(connectUrl);
         if (boundEpoch !== signalingEpoch) {
             try {
                 nextWs.close();
@@ -1233,8 +1492,63 @@ export async function connectBrowserVoiceSession(options) {
             return;
         }
         ws = nextWs;
+        const httpStatusOf = () => {
+            const status = nextWs.httpStatus;
+            return typeof status === "number" ? status : undefined;
+        };
         await new Promise((resolve, reject) => {
+            let connectTimer;
+            let done = false;
+            /** `error` is followed by `close` (with code/reason) in the next task; wait for it briefly. */
+            let errorTimer;
+            const settle = () => {
+                if (connectTimer)
+                    clearTimeout(connectTimer);
+                connectTimer = undefined;
+                if (errorTimer)
+                    clearTimeout(errorTimer);
+                errorTimer = undefined;
+            };
+            /** Connect-phase failure: log once, then reject (401 on reconnect = session gone). */
+            const failConnect = (close, error) => {
+                if (done)
+                    return;
+                done = true;
+                settle();
+                const httpStatus = httpStatusOf();
+                logSignalingFailure({
+                    phase: "connect",
+                    url: connectUrl,
+                    startedAtMs: connectStartedAtMs,
+                    httpStatus,
+                    close,
+                });
+                reject(isReconnect && httpStatus === 401
+                    ? new SessionEndedDuringReconnectError()
+                    : error);
+            };
+            if (isReconnect) {
+                connectTimer = setTimeout(() => {
+                    connectTimer = undefined;
+                    if (ws !== nextWs || boundEpoch !== signalingEpoch) {
+                        reject(new Error("WebSocket superseded during reconnect"));
+                        return;
+                    }
+                    nextWs.onopen = null;
+                    nextWs.onerror = null;
+                    nextWs.onclose = null;
+                    try {
+                        nextWs.close();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    failConnect(undefined, new Error(`WebSocket did not open within ${SIGNALING_CONNECT_TIMEOUT_MS}ms`));
+                }, SIGNALING_CONNECT_TIMEOUT_MS);
+            }
             nextWs.onopen = () => {
+                done = true;
+                settle();
                 if (ws !== nextWs || boundEpoch !== signalingEpoch) {
                     reject(new Error("WebSocket superseded during reconnect"));
                     return;
@@ -1248,6 +1562,7 @@ export async function connectBrowserVoiceSession(options) {
             };
             nextWs.onerror = () => {
                 if (ws !== nextWs || boundEpoch !== signalingEpoch) {
+                    settle();
                     reject(new Error("WebSocket superseded during reconnect"));
                     return;
                 }
@@ -1257,8 +1572,16 @@ export async function connectBrowserVoiceSession(options) {
                     peerId,
                     kind: "signaling-ws",
                 }), { fallbackLog: false });
-                debug?.error("signaling", "ws_error", redactSignalingUrlForLog(signalingUrl));
-                reject(new Error("WebSocket error"));
+                errorTimer ??= setTimeout(() => {
+                    errorTimer = undefined;
+                    failConnect(undefined, new Error("WebSocket error"));
+                }, 0);
+            };
+            // Close before open (with or without a preceding `error`) carries code/reason.
+            nextWs.onclose = (event) => {
+                if (ws !== nextWs || boundEpoch !== signalingEpoch)
+                    return;
+                failConnect(event, new Error("WebSocket closed before open"));
             };
         });
         if (boundEpoch !== signalingEpoch) {
@@ -1344,6 +1667,23 @@ export async function connectBrowserVoiceSession(options) {
         }
         return syncChannel;
     };
+    /**
+     * Best-effort explicit hangup on the control channel. Only for integrator-initiated
+     * ends, never for reconnects or unintentional loss.
+     */
+    const sendClientHangup = () => {
+        const channel = controlChannel;
+        if (!channel || channel.readyState !== "open")
+            return null;
+        try {
+            channel.send(JSON.stringify({ type: CLIENT_HANGUP_MESSAGE_TYPE }));
+            debug?.info("session", "client_hangup_sent");
+            return channel;
+        }
+        catch {
+            return null;
+        }
+    };
     const waitForConnected = async (timeoutMs = 60_000) => {
         const deadlineMs = Date.now() + timeoutMs;
         const halfOpenFailFastMs = resolveHalfOpenFailFastMs(readinessProfile, timeoutMs);
@@ -1538,6 +1878,8 @@ export async function connectBrowserVoiceSession(options) {
         },
         disconnect: () => {
             // Sync terminal invalidation — must not await native close (reconnect opens WS promptly).
+            if (!gracefulDisconnect)
+                sendClientHangup();
             gracefulDisconnect = true;
             negotiationGeneration += 1;
             activePcGeneration = 0;
@@ -1547,6 +1889,7 @@ export async function connectBrowserVoiceSession(options) {
             if (reconnectTimer)
                 clearTimeout(reconnectTimer);
             reconnectTimer = undefined;
+            clearRecoveryTimers();
             awaitingReconnectedCallback = false;
             stopMicPump?.();
             stopMicPump = null;
@@ -1636,6 +1979,15 @@ export async function connectBrowserVoiceSession(options) {
                 return disconnectAsyncInFlight;
             }
             disconnectAsyncInFlight = (async () => {
+                const hangupChannel = gracefulDisconnect ? null : sendClientHangup();
+                if (hangupChannel) {
+                    const drainDeadline = Date.now() + CLIENT_HANGUP_DRAIN_MS;
+                    while (hangupChannel.readyState === "open" &&
+                        (hangupChannel.bufferedAmount ?? 0) > 0 &&
+                        Date.now() < drainDeadline) {
+                        await new Promise((resolve) => setTimeout(resolve, 10));
+                    }
+                }
                 gracefulDisconnect = true;
                 negotiationGeneration += 1;
                 activePcGeneration = 0;
@@ -1644,6 +1996,7 @@ export async function connectBrowserVoiceSession(options) {
                 if (reconnectTimer)
                     clearTimeout(reconnectTimer);
                 reconnectTimer = undefined;
+                clearRecoveryTimers();
                 awaitingReconnectedCallback = false;
                 stopMicPump?.();
                 stopMicPump = null;