@memberjunction/realtime-runtime 6.2.0-edge.4 → 6.2.0-edge.5

package/dist/session/RealtimeSessionRuntime.js

@@ -5,7 +5,7 @@ import { AddRealtimeUsageRecord, AIEngineBase, HasRealtimeUsage } from '@memberj
 import { GraphQLRealtimeSessionClient } from '@memberjunction/graphql-dataprovider';
 import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
 import { DEFAULT_REALTIME_AUDIO_TRACKS, ParseRealtimeAvatarStatus, ParseRealtimeClientTransport } from '@memberjunction/ai';
-import { CompareExposure, DeclaresNativeTools, IsIdentityVerifiedEventPayload, NormalizeChannelKey, ParseRealtimeSessionClientPolicy, ResolveClientTools, SelectNativeChannelTools, UserExposureReason } from '@memberjunction/ai-core-plus';
+import { CompareExposure, DeclaresNativeTools, IsIdentityVerifiedEventPayload, NormalizeChannelKey, ParseRealtimeSessionClientPolicy, RECORDING_TERMINAL_MAX_BYTES, ResolveClientTools, SelectNativeChannelTools, UserExposureReason } from '@memberjunction/ai-core-plus';
 import { BaseRealtimeClient, LoadAssemblyAIRealtimeClient, LoadElevenLabsRealtimeClient, LoadGeminiEnterpriseRealtimeClient, LoadGeminiRealtimeClient, LoadHuggingFaceRealtimeClient, LoadOpenAIRealtimeClient, LoadxAIRealtimeClient, VideoSourceArbiter, REQUESTED_TRACKS_SESSION_KEY } from '@memberjunction/ai-realtime-client';
 import { DefaultRealtimeSessionLauncher, HasClientCredential } from './session-launcher.js';
 import { RequestsAgentVideo, ResolveAvatarNotice } from './avatar-notice.js';
@@ -23,6 +23,26 @@ import { AppClientToolRegistry, DEFAULT_APP_TOOL_OWNER } from './app-client-tool
 import { UserSettingsExposurePreferences } from './channel-exposure-preferences.js';
 import { BuildChannelCandidate, FindPreparedChannel, MergeToolMetadata, PreparedChannelsShowAgentVideo, ReconcileChannelsWithPolicy, ResolveLocalChannelScope, ToolsByChannelKey } from './channel-session-scope.js';
 import { RecordingShardQueue } from './RecordingShardQueue.js';
+import { RecordingShardWindow } from './RecordingShardWindow.js';
+import { CreateRecordingShardStore } from './RecordingShardStore.js';
+import { CreateRecordingTransportForProvider, DeleteStoredRecordingShard, DrainStoredRecordingShardsOnce } from './RecordingShardDrain.js';
+/**
+ * How long teardown waits for the server to acknowledge the recording's terminal request, measured
+ * from after `CloseAgentSession`. The terminal is `keepalive`, so it completes even if the page goes
+ * away; the wait only keeps `SavingRecording$` (and so a host's "don't close yet" guard) up while the
+ * server has not confirmed. Bounded so a dead server can never hold the End of a call hostage —
+ * unacknowledged shards stay in the local store and the server janitor assembles what arrived.
+ */
+export const RECORDING_TERMINAL_ACK_TIMEOUT_MS = 3000;
+/**
+ * How long teardown waits for the recorder to stop and flush its encoder. `Stop()` runs BEFORE
+ * `CloseAgentSession`, so a wedged encoder must not be able to hold the End of a call (and the
+ * server session) open; past this the recording ends at the packets already encoded.
+ */
+export const RECORDER_STOP_TIMEOUT_MS = 2000;
+function describeRecordingFailure(failure) {
+    return failure instanceof Error ? failure.message : String(failure);
+}
 /**
  * `MJ: User Settings` key for the per-user "record this voice call" consent toggle. Stored as
  * the literal string `'true'`/`'false'` (read with `=== 'true'`), cross-device via
@@ -174,9 +194,9 @@ function microphoneStartError(reason, message) {
 export class RealtimeSessionRuntime {
     /**
      * @param mediaHost the platform's media capabilities. The runtime never touches `navigator`,
-     *                  `Blob` or `FileReader` itself — microphone acquisition and audio recording
-     *                  are the host's, because both are platform-specific product decisions
-     *                  (permission UX, container format, where the bytes live).
+     *                  `Blob` or `FileReader` itself — microphone acquisition and audio capture/encoding
+     *                  are the host's, because both are platform-specific (permission UX, which
+     *                  encoder the platform offers).
      */
     constructor(mediaHost) {
         this.mediaHost = mediaHost;
@@ -254,10 +274,11 @@ export class RealtimeSessionRuntime {
         this.Minimized$ = this._minimized$.asObservable();
         /**
          * True while the end-of-call recording is being saved: from the first statement of a teardown
-         * that holds a recorder until that teardown settles. False at construction and for unrecorded
-         * sessions. Exists for #5195: the page must stay open until the consolidated upload lands, or
-         * the recording is lost. The runtime is platform-free, so hosts own the reaction (a browser
-         * `beforeunload` guard, a "saving" indicator, etc.).
+         * that holds a recorder until that teardown settles — which includes waiting (at most
+         * {@link RECORDING_TERMINAL_ACK_TIMEOUT_MS}) for the server to acknowledge the recording's terminal
+         * request. False at construction and for unrecorded sessions. Exists for #5195; the runtime is
+         * platform-free, so hosts own the reaction (a "saving" indicator, a disabled navigation button,
+         * etc.).
          */
         this.SavingRecording$ = this._savingRecording$.asObservable();
         /**
@@ -423,23 +444,40 @@ export class RealtimeSessionRuntime {
         // ── Browser-side call recording ────────────────────────────────────────────
         /**
          * The active session's audio recorder (mic + agent mix), or `null` when the user didn't
-         * consent or the browser can't record. Created after the client connects; stopped + uploaded
-         * at teardown.
+         * consent or the browser can't record. Created after the client connects; its packets are
+         * shipped as 5 s shards during the call, and it is stopped at teardown.
          */
         this.recorder = null;
         /** ISO timestamp of when recording started — sent to the server on session start. */
         this.recordingStartedAtIso = null;
-        /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
-        this.segmentTimer = null;
+        /** Interval that cuts and uploads a shard every {@link recordingShardFlushMs} during a recording. */
+        this.shardFlushTimer = null;
+        /**
+         * The current recording's shard pipeline (window → store → queue → transport), or null when not
+         * recording. A fresh pipeline per recording keeps a flush still in flight from a previous session
+         * off this session's indexes. Its queue is closed when the recording ends; anything it had not
+         * delivered stays in the local store for the next-load drain.
+         */
+        this.recordingShards = null;
+        /**
+         * Bytes of this page's recording `keepalive` requests still in flight. The browser's keepalive budget
+         * is per page, and closing a tab fires `visibilitychange` and `pagehide` back to back, so each dispatch
+         * budgets against what the previous one has not finished sending.
+         */
+        this.keepaliveBytesInFlight = 0;
+        /** `sessionId/index` of shards whose `keepalive` copy is still in flight; never sent twice at once. */
+        this.keepaliveShardsInFlight = new Set();
+        /** The durable local shard store, created on first use and shared by every recording of this runtime. */
+        this.shardStore = null;
         /**
-         * Owns shard indexing and retry for the current recording: it assigns each shard its index and
-         * keeps failed shards to resend under that same index. A fresh queue per recording keeps a flush
-         * still in flight from a previous session off this session's indexes. Null when not recording.
-         * A recording that ends discards its queue, and any retained shard with it: the consolidated
-         * end-of-call upload supersedes them, and if that upload is lost too, server-side recovery
-         * (#5196) fills the gap with silence.
+         * True once a drain ran with a transport; the drain then does nothing until a recording ends and
+         * re-arms it ({@link rearmPendingShardDrain}).
          */
-        this.shardQueue = null;
+        this.pendingShardsDrained = false;
+        /** Bumped by every re-arm, so a drain already in flight cannot mark itself done over a re-arm. */
+        this.drainGeneration = 0;
+        /** The drain in flight, so overlapping callers share it instead of uploading the same shards twice. */
+        this.drainInFlight = null;
         // ── Server-side liveness ───────────────────────────────────────────────────
         /**
          * Interval that tells the server this session is still in use, or `null` when no session is
@@ -450,12 +488,33 @@ export class RealtimeSessionRuntime {
          * Recording-relative ms offset at which the IN-FLIGHT (not-yet-finalized) turn's audio
          * actually BEGAN — captured the moment that turn's audio/text starts flowing (its first
          * interim transcript), NOT inherited from the previous turn's end. `null` before the first
-         * turn / between turns (until the next turn's audio starts). Sent as `utteranceStartMs` on
-         * the turn's final transcript so per-turn timing lines up with the recording even when a
-         * tool-call / silence gap sits between turns (the inherit-previous-end model mis-stamped
-         * the post-gap turn at the pre-gap offset). See {@link markTurnAudioStart}.
+         * turn / between turns (until the next turn's audio starts), and it stays `null` for a turn
+         * whose start was never measured. Sent as `utteranceStartMs` on the turn's final transcript
+         * AS-IS — `null` is relayed as `null`, never replaced with 0 — so per-turn timing lines up
+         * with the recording even when a tool-call / silence gap sits between turns (the
+         * inherit-previous-end model mis-stamped the post-gap turn at the pre-gap offset). See
+         * {@link markTurnAudioStart}. A user speech onset signalled by the client does NOT land here;
+         * it has its own slot, {@link userSpeechStartMs}.
          */
         this.currentTurnStartMs = null;
+        /**
+         * Recording-relative ms offset of the first user speech onset the client signalled
+         * (`OnUserSpeechStart`) since the last final user transcript, or `null` when none was signalled.
+         * It has its own slot, apart from {@link currentTurnStartMs}, so a user onset never claims the
+         * assistant turn's start: OpenAI user transcripts arrive asynchronously, often after the
+         * assistant's interims (or its final) for the reply have already flowed. See
+         * {@link markUserSpeechStart}.
+         */
+        this.userSpeechStartMs = null;
+        /**
+         * `true` once an assistant turn has finalized after {@link userSpeechStartMs} was stamped BEFORE
+         * that turn began. The held onset may still be claimed by a late user transcript (OpenAI
+         * transcribes asynchronously), but the NEXT onset replaces it: an onset no transcript ever claimed
+         * (a VAD false positive, a failed transcription) must not become the start of the next real user
+         * turn. A barge-in onset (stamped during the assistant turn) is not superseded by that turn's
+         * final. An EMPTY user transcript releases the onset outright (see onClientTranscript).
+         */
+        this.userSpeechStartSuperseded = false;
         /**
          * Wall-anchor of the SESSION clock (#3832): `performance.now()` at the moment the call went
          * live, or `null` before any call has. Read only through {@link nowTurnOffsetMs}.
@@ -662,6 +721,16 @@ export class RealtimeSessionRuntime {
          * Owner-keyed — see {@link AppClientToolRegistry}.
          */
         this.appToolRegistry = new AppClientToolRegistry();
+        // Re-upload shards a previous, interrupted call left in the local store. Deferred a tick so a
+        // host can assign `Provider` right after construction; when it still has no transport the drain
+        // defers itself and session start tries again. Unref'd so it never holds a Node process open.
+        const drainTimer = setTimeout(() => {
+            void this.DrainPendingRecordingShards();
+        }, 0);
+        // Node returns a Timeout object with unref(); browsers return a number.
+        if (typeof drainTimer === 'object' && drainTimer !== null && 'unref' in drainTimer && typeof drainTimer.unref === 'function') {
+            drainTimer.unref();
+        }
     }
     /** Synchronous read of {@link SavingRecording$}. */
     get IsSavingRecording() {
@@ -730,8 +799,20 @@ export class RealtimeSessionRuntime {
     UpdateAppContext(snapshot) {
         this._appContext$.next(snapshot);
     }
-    /** How often crash-recovery shards are flushed during a recording. */
-    static { this.segmentFlushMs = 15000; }
+    /** How often packets are cut into shards: the 5 s shard window, so each tick seals about one window. */
+    static { this.recordingShardFlushMs = 5000; }
+    /**
+     * Bytes of `keepalive` request bodies one terminal may use, the tail included. Browsers share about
+     * 64 KiB of in-flight keepalive bodies per page; the brief reserves 48 KiB of it for the recording,
+     * leaving room for a host's own close beacon (Caliber sends one from `pagehide` too).
+     */
+    static { this.recordingKeepaliveBudgetBytes = RECORDING_TERMINAL_MAX_BYTES; }
+    /**
+     * Most runs one drain call makes (each run is itself bounded): it runs again when it was re-armed while
+     * running, or when a run deleted shards the server refused for good, which frees the page for the
+     * shards behind them.
+     */
+    static { this.maxDrainRunsPerCall = 3; }
     /**
      * How often the client asserts liveness. Comfortably under `SessionJanitor`'s
      * `closeThresholdMinutes` (15 by default) so several pulses must be missed in a row before a
@@ -903,7 +984,7 @@ export class RealtimeSessionRuntime {
      *   pickers, and never synthesize overrides beyond what the user explicitly chose.
      *   Omit/`null` for the server's defaults (today's behavior).
      * @param recordingConsent Optional EXPLICIT "record this call" consent for THIS session. When
-     *   `true`, the browser records a mic + agent-audio mix and uploads it at session end. When
+     *   `true`, the browser records a mic + agent-audio mix and uploads it as 5 s Opus shards during the call. When
      *   omitted/`null`, the per-user persisted preference (`mj.realtimeVoice.recordingConsent.v1`
      *   via {@link UserInfoEngine}) is read as the default. `false` never records.
      * @param mediaCollectionId Optional per-session media-kit override (`MJ: Collections.ID`). When set,
@@ -1060,6 +1141,9 @@ export class RealtimeSessionRuntime {
         this.resetState();
         this._active$.next(true);
         this.setConnectionState('connecting');
+        // A drain the constructor deferred (no provider/transport yet) gets its second chance here, and
+        // runs whether or not THIS session records: the pending shards belong to an earlier call.
+        void this.DrainPendingRecordingShards();
         // Resolve recording consent for this session: explicit value wins, else the per-user
         // persisted preference. Computed before mint so it can be reported to the server.
         const consent = options.recordingConsent ?? this.readPersistedRecordingConsent();
@@ -1583,7 +1667,7 @@ export class RealtimeSessionRuntime {
         }
         client.SendText(trimmed);
         // Relay as a user turn — same path spoken input uses (caption + persisted transcript).
-        void this.onUserTranscript(trimmed);
+        void this.onUserTranscript(trimmed, 'typed');
     }
     /**
      * Mute / unmute the local microphone track. Returns the new muted state. While the call has no microphone track (a
@@ -1728,6 +1812,8 @@ export class RealtimeSessionRuntime {
             // turn one's cue wherever the clocks happen to differ.
             this.currentTurnStartMs = recorder.IsRecording ? 0 : null;
             this.turnAudioStartCaptured = false;
+            this.userSpeechStartMs = null;
+            this.userSpeechStartSuperseded = false;
             if (this.recorder) {
                 // WebRTC drivers (OpenAI): the agent's track usually lands AFTER Connect() resolves, so
                 // `remoteStream` above is null here and this handler attaches it later. PCM-playback
@@ -1735,7 +1821,7 @@ export class RealtimeSessionRuntime {
                 // `remoteStream` is already set and the handler fires immediately with the same stream;
                 // AttachRemoteStream is idempotent, so it is mixed only once.
                 client.OnRemoteMediaStream?.((stream) => this.recorder?.AttachRemoteStream(stream));
-                this.startSegmentFlushing();
+                this.startShardFlushing();
             }
         }
         catch (error) {
@@ -1743,16 +1829,159 @@ export class RealtimeSessionRuntime {
             this.recorder = null;
         }
     }
-    /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
-    startSegmentFlushing() {
-        this.shardQueue = new RecordingShardQueue();
-        this.segmentTimer = setInterval(() => { void this.flushRecordingSegment(); }, RealtimeSessionRuntime.segmentFlushMs);
+    // ── Recording shards (MJ#5294) ───────────────────────────────────────────────
+    //
+    // The recorder hands over Opus packets; the runtime cuts them into 5 s `MJOPUS1` shards, writes
+    // each one to the local store BEFORE its upload starts, uploads it as raw bytes, and deletes it from
+    // the store only on the server's ack. The call ends with a `keepalive` terminal request carrying the
+    // final partial shard and the counts the server needs to know it has everything.
+    /**
+     * Builds the transport for shard uploads and terminal requests. The default posts to MJAPI's REST
+     * recording routes, derived from the session's GraphQL provider configuration, with credentials
+     * read per request so a refreshed token is used. Returns null — shards then wait in the local
+     * store — when the provider has no URL (a test double, a provider that is not GraphQL, or one not
+     * configured yet). Override to supply another transport.
+     */
+    createRecordingTransport() {
+        return CreateRecordingTransportForProvider(this.Provider);
+    }
+    /**
+     * Builds the durable local shard store. The default is IndexedDB where the host has it and a no-op
+     * store elsewhere (Node, some React Native runtimes). Called once per runtime. Override to supply
+     * another store.
+     */
+    createRecordingShardStore() {
+        return CreateRecordingShardStore(globalThis.indexedDB);
     }
-    /** Stops the periodic crash-recovery shard flush. */
-    stopSegmentFlushing() {
-        if (this.segmentTimer) {
-            clearInterval(this.segmentTimer);
-            this.segmentTimer = null;
+    /** The provider's signed-in user, or null (no provider yet, or an anonymous page). */
+    signedInUserID() {
+        return this.Provider?.CurrentUser?.ID ?? null;
+    }
+    /** The runtime's shard store, created on first use. */
+    ensureShardStore() {
+        this.shardStore ??= this.createRecordingShardStore();
+        return this.shardStore;
+    }
+    /**
+     * Re-uploads shards an earlier, interrupted call left in the local store (crash, closed tab, dead
+     * network), each under its OWN session id and index, oldest first, at most
+     * {@link MAX_DRAINED_SHARDS_PER_LOAD} per runtime. A shard is deleted only on the server's ack.
+     *
+     * Runs once per runtime instance, re-armed whenever a recording ends (which may leave shards behind
+     * for the next session start on the same page). When there is no transport yet (no provider configuration, e.g.
+     * before login) it returns 0 WITHOUT marking itself done, so a later call — session start — drains
+     * instead of the shards being skipped for this page. Concurrent calls share one run. Never rejects.
+     *
+     * @returns the number of shards the server acknowledged in this call.
+     */
+    DrainPendingRecordingShards() {
+        if (this.pendingShardsDrained) {
+            return Promise.resolve(0);
+        }
+        this.drainInFlight ??= this.drainPendingShards().finally(() => {
+            this.drainInFlight = null;
+        });
+        return this.drainInFlight;
+    }
+    /** Makes the next {@link DrainPendingRecordingShards} call run again, even one already in flight. */
+    rearmPendingShardDrain() {
+        this.pendingShardsDrained = false;
+        this.drainGeneration++;
+    }
+    /**
+     * The body of {@link DrainPendingRecordingShards}, up to {@link maxDrainRunsPerCall} runs. It runs
+     * again after a re-arm while a run is in flight (a recovery after an outage gave up on more shards),
+     * because the running pass listed the store before those shards were there; and after a run deleted
+     * refused shards, because those filled the page that the shards behind them now get.
+     */
+    async drainPendingShards() {
+        try {
+            const transport = this.createRecordingTransport();
+            if (!transport) {
+                return 0;
+            }
+            let delivered = 0;
+            for (let run = 1; run <= RealtimeSessionRuntime.maxDrainRunsPerCall; run++) {
+                // A re-arm while this run is in flight must win over this run marking itself done.
+                const generation = this.drainGeneration;
+                const outcome = await this.drainStoredShardsOnce(transport);
+                delivered += outcome.Delivered;
+                // Done only when every listed shard was delivered or refused for good: a drain during an outage
+                // must not stop the next session start or recovery from trying again.
+                this.pendingShardsDrained = generation === this.drainGeneration && outcome.Delivered + outcome.Refused === outcome.Listed;
+                if (generation === this.drainGeneration && outcome.Refused === 0) {
+                    break;
+                }
+            }
+            return delivered;
+        }
+        catch (error) {
+            console.warn(`[RealtimeSession] Draining stored recording shards failed: ${describeRecordingFailure(error)}; will retry at the next session start.`, error);
+            return 0;
+        }
+    }
+    /** One drain pass over the signed-in user's stored shards (see {@link DrainStoredRecordingShardsOnce}). */
+    drainStoredShardsOnce(transport) {
+        return DrainStoredRecordingShardsOnce(this.ensureShardStore(), transport, this.signedInUserID());
+    }
+    /** Builds this recording's shard pipeline and starts the 5 s flush. */
+    startShardFlushing() {
+        const sessionId = this.agentSessionId;
+        if (!sessionId) {
+            // Unreachable in practice (the session id is adopted before recording starts), but without
+            // one there is nowhere to send shards, so say so rather than recording into the void.
+            console.warn('[RealtimeSession] Recording started without an agent session id; shards will not be saved.');
+            return;
+        }
+        const transport = this.createRecordingTransport();
+        if (!transport) {
+            console.warn(`[RealtimeSession] No recording transport for session ${sessionId} (provider has no REST configuration); shards are kept in the local store only.`);
+        }
+        // True once the queue gave up on a shard and until an upload succeeds again: that first success
+        // re-sends what the queue dropped meanwhile (see recoverStoredShardsAfterOutage).
+        let shardsGivenUp = false;
+        this.recordingShards = {
+            SessionID: sessionId,
+            UserID: this.signedInUserID(),
+            Window: new RecordingShardWindow(),
+            Transport: transport,
+            // Closes over this recording's session id and transport — never the runtime's current ones.
+            Queue: new RecordingShardQueue(async (shard) => {
+                if (!transport) {
+                    return false;
+                }
+                const acked = (await transport.UploadShard(sessionId, shard)) === 'Acked';
+                if (acked) {
+                    await this.deleteStoredShard(sessionId, shard.Index);
+                    if (shardsGivenUp) {
+                        shardsGivenUp = false;
+                        this.recoverStoredShardsAfterOutage(sessionId);
+                    }
+                }
+                return acked;
+            }, () => {
+                shardsGivenUp = true;
+            }),
+        };
+        this.shardFlushTimer = setInterval(() => { void this.flushRecordingShards(); }, RealtimeSessionRuntime.recordingShardFlushMs);
+    }
+    /**
+     * Uploads succeed again after failing: re-sends, from the local store, the shards the queue gave up
+     * on during the outage. The queue's attempts run out after about 10 s of a dead network (or an
+     * expired token), and without this those shards would wait for a later page load — which a widget
+     * guest never makes — leaving a permanent gap. Runs in the background, outside any page-lifecycle
+     * handler, so the IndexedDB read is allowed. Never rejects.
+     */
+    recoverStoredShardsAfterOutage(sessionId) {
+        console.log(`[RealtimeSession] Recording uploads for session ${sessionId} recovered; re-sending stored shards.`);
+        this.rearmPendingShardDrain();
+        void this.DrainPendingRecordingShards();
+    }
+    /** Stops the periodic shard flush. */
+    stopShardFlushing() {
+        if (this.shardFlushTimer) {
+            clearInterval(this.shardFlushTimer);
+            this.shardFlushTimer = null;
         }
     }
     /**
@@ -1811,128 +2040,344 @@ export class RealtimeSessionRuntime {
         }
     }
     /**
-     * Uploads the chunks captured since the last flush as one crash-recovery shard (durability only;
-     * the canonical file is still the full upload at teardown). Best-effort — never disturbs the call:
-     * a failed shard is retained by the queue and resent under its own index on later flushes, up to a
-     * bounded number of attempts (#5197).
+     * One 5 s tick: cuts the packets encoded since the last tick into shards, stores each one, then
+     * uploads them. Best-effort — never disturbs the call and never rejects. Overlapping ticks are
+     * safe: `Append` and `SealTail` are synchronous, so indexes are assigned in order, and the queue
+     * bounds how many flushes upload at once. A failed shard is retained by the queue and resent under
+     * its own index on later ticks (#5197), and stays in the store until acknowledged.
+     *
+     * Every tick seals whatever it took, even under a full window (the window's 250-packet and byte caps
+     * still split a larger batch). Capture starts slightly after this timer, so a tick almost never
+     * holds exactly 250 packets; sealing only full windows would leave nearly 5 s of encoded audio in
+     * memory at every moment, unstored and unsent, which a killed tab loses.
      */
-    async flushRecordingSegment() {
+    async flushRecordingShards() {
         const recorder = this.recorder;
-        const agentSessionId = this.agentSessionId;
-        const queue = this.shardQueue;
-        if (!recorder || !agentSessionId || !queue) {
+        const pipeline = this.recordingShards;
+        if (!recorder || !pipeline) {
             return;
         }
-        // Read once: a shard's sample rate is fixed at capture, and the recorder may be stopped by the
-        // time a retry of it runs.
-        const sampleRate = recorder.SampleRate;
-        await queue.Flush(() => recorder.SnapshotNewSegmentBase64(), (segmentIndex, audioBase64) => this.uploadRecordingShard(agentSessionId, sampleRate, segmentIndex, audioBase64));
+        let sealed;
+        try {
+            sealed = pipeline.Window.Append(recorder.TakeEncodedPackets());
+            const tick = pipeline.Window.SealTail();
+            if (tick) {
+                sealed.push(tick);
+            }
+        }
+        catch (error) {
+            console.warn(`[RealtimeSession] Failed to take encoded recording packets for session ${pipeline.SessionID}; this tick's audio is lost:`, error);
+            return;
+        }
+        await this.storeShards(pipeline, sealed);
+        await pipeline.Queue.Flush(sealed);
+    }
+    /** Writes shards to the local store, in order, before their upload starts. Never rejects. */
+    async storeShards(pipeline, shards) {
+        const store = this.ensureShardStore();
+        for (const shard of shards) {
+            try {
+                await store.Put({ SessionID: pipeline.SessionID, UserID: pipeline.UserID, Index: shard.Index, Bytes: shard.Bytes, SavedAt: Date.now() });
+            }
+            catch (error) {
+                // The store contract is never-throw; an override that does must still not stop the upload.
+                console.warn(`[RealtimeSession] Failed to store recording shard ${pipeline.SessionID}/${shard.Index}; uploading it anyway:`, error);
+            }
+        }
+    }
+    /** Removes an acknowledged shard from the local store. Never rejects. */
+    deleteStoredShard(sessionId, index) {
+        return DeleteStoredRecordingShard(this.ensureShardStore(), sessionId, index);
     }
     /**
-     * Sends one shard and reports whether the server stored it. The resolver reports a failed
-     * ownership load or storage write as `false`, not as an error — that is how #5197 lost a shard
-     * without a single client-side log line — so the typed result must be checked, not just the absence
-     * of a throw.
+     * Tells the server, right now, how much of the recording exists — for a host's `pagehide` and
+     * `visibilitychange → hidden` handlers, where the page may be gone a moment later. Synchronous:
+     * it seals the pending partial shard and fires the `keepalive` terminal with it, then re-sends
+     * with `keepalive` whatever the server has not acknowledged yet (see
+     * {@link dispatchRecordingTerminal}), and returns without waiting. Never stops the recorder: after
+     * a `hidden` the call may well continue, and later audio simply starts the next shard index (the
+     * tail is sealed, so no index is ever re-sent with different bytes). Also works while End is still
+     * stopping the recorder, which is exactly when a host that does not await End navigates away.
+     * No-op when nothing is recording, there is no session id or no transport, or nothing was
+     * captured. Never throws.
+     *
+     * Deliberately opens NO IndexedDB transaction inside the handler: a `pagehide` handler gets a few
+     * milliseconds, and a store write started there could not complete during unload anyway. The
+     * shards it sealed are written to the store from a `setTimeout(0)` task after the handler returns:
+     * on a page that is merely hidden (the call goes on) that keeps the durable copy until the server
+     * acknowledges it; on a page that is unloading the task just never runs.
      */
-    async uploadRecordingShard(agentSessionId, sampleRate, segmentIndex, audioBase64) {
-        const mutation = `
-      mutation UploadRealtimeRecordingSegment($agentSessionId: String!, $segmentIndex: Int!, $audioBase64: String!, $mimeType: String!) {
-        UploadRealtimeRecordingSegment(agentSessionId: $agentSessionId, segmentIndex: $segmentIndex, audioBase64: $audioBase64, mimeType: $mimeType)
-      }
-    `;
-        // Shards are HEADER-LESS raw little-endian PCM16 (mime audio/L16 with the capture sample rate),
-        // NOT individually-playable WAV — recovery is concatenate-in-order then WAV-wrap. The canonical
-        // seekable WAV is the consolidated end-of-call upload below.
-        const shardMime = `audio/L16;rate=${sampleRate}`;
-        const result = (await this.gql().ExecuteGQL(mutation, {
-            agentSessionId,
-            segmentIndex,
-            audioBase64,
-            mimeType: shardMime,
-        }));
-        return result?.UploadRealtimeRecordingSegment === true;
-    }
-    /**
-     * Stops the active recorder and encodes the captured audio. Split from the upload so teardown can
-     * close the server session in between (#5195). Best-effort: returns `null` when nothing was
-     * recorded or the stop failed (warned) — it must NEVER block teardown.
-     */
-    async stopRecording() {
-        this.stopSegmentFlushing();
-        // Close the queue with the recording: its retained shards (base64 audio) are released now, not at
-        // the next session start, and a flush still in flight stops sending, so no resend lands after the
-        // end-of-call upload below has deleted the shards.
-        this.shardQueue?.Close();
-        this.shardQueue = null;
+    SendRecordingTerminal(options) {
         const recorder = this.recorder;
-        this.recorder = null;
+        const pipeline = this.recordingShards;
+        if (!recorder || !pipeline || !pipeline.Transport) {
+            return;
+        }
+        try {
+            const sealed = pipeline.Window.Append(recorder.TakeEncodedPackets());
+            const tail = pipeline.Window.SealTail();
+            if (pipeline.Window.LastSealedIndex < 0) {
+                return;
+            }
+            const final = options?.Final ?? true;
+            if (sealed.length === 0 && !tail && pipeline.FinalTerminal?.LastSealedIndex === pipeline.Window.LastSealedIndex) {
+                return;
+            }
+            void this.dispatchRecordingTerminal(pipeline, sealed, tail, true, final);
+        }
+        catch (error) {
+            console.warn(`[RealtimeSession] Failed to send the recording terminal for session ${pipeline.SessionID}:`, error);
+        }
+    }
+    /**
+     * Fires the terminal request, then re-sends with `keepalive` every shard the server has not
+     * acknowledged, then stores the shards sealed for this terminal. Shared by End and the page-lifecycle
+     * handlers. Everything that needs the network is dispatched synchronously, before any storage work,
+     * because the page may close at any moment from here on: an ordinary `fetch` is aborted on unload,
+     * and a `keepalive` one is not.
+     *
+     * - The terminal goes first so it always gets the keepalive budget. The server waits for the shards
+     *   the terminal says exist, and assembles as soon as the last missing one arrives.
+     * - The re-sent shards are the queue's unacknowledged ones (on the wire, waiting in a batch, or
+     *   retained after a failure) plus `sealedNow`, oldest first, within
+     *   {@link recordingKeepaliveBudgetBytes} together with the tail. A `sealedNow` shard that does not
+     *   fit, or whose keepalive upload fails, goes through the ordinary queue instead (it may still
+     *   land if the page stays). The queue keeps its own shards either way; a duplicate is acked as one.
+     * - `sealedNow` and the tail are stored after the dispatch, from a `setTimeout(0)` task when called
+     *   from a page-lifecycle handler (`deferStore`). A shard's stored copy is deleted on its ack, after
+     *   the store write, so a fast ack can never leave an orphan row.
+     *
+     * Resolves true when the terminal was acknowledged. Never rejects.
+     */
+    dispatchRecordingTerminal(pipeline, sealedNow, tail, deferStore, final) {
+        const sessionId = pipeline.SessionID;
+        const terminalAcked = this.sendRecordingTerminal(pipeline, tail, final);
+        const toStore = tail ? [...sealedNow, tail] : sealedNow;
+        let stored = Promise.resolve();
+        if (toStore.length > 0) {
+            stored = deferStore ? this.storeShardsLater(pipeline, toStore) : this.storeShards(pipeline, toStore);
+        }
+        this.resendUnacknowledgedWithKeepalive(pipeline, sealedNow, stored);
+        const ackedPromise = terminalAcked.then(async (acked) => {
+            await stored;
+            if (!tail) {
+                return acked;
+            }
+            if (acked) {
+                await this.deleteStoredShard(sessionId, tail.Index);
+            }
+            else {
+                // Retried as an ordinary shard; a Flush on a closed queue (the recording ended) is a logged no-op.
+                await pipeline.Queue.Flush([tail]);
+            }
+            return acked;
+        });
+        if (final) {
+            pipeline.FinalTerminal = { LastSealedIndex: pipeline.Window.LastSealedIndex, Acked: terminalAcked };
+        }
+        return ackedPromise;
+    }
+    /** Counts `bytes` against the page's keepalive budget until `request` settles. */
+    trackKeepalive(bytes, request) {
+        this.keepaliveBytesInFlight += bytes;
+        return request.finally(() => {
+            this.keepaliveBytesInFlight -= bytes;
+        });
+    }
+    /**
+     * The `keepalive` re-send part of {@link dispatchRecordingTerminal}, budgeted against everything this
+     * page still has in flight (the terminal just sent included). A shard whose `keepalive` copy is already
+     * on the wire is not sent again. Never throws.
+     */
+    resendUnacknowledgedWithKeepalive(pipeline, sealedNow, stored) {
+        const transport = pipeline.Transport;
+        const sessionId = pipeline.SessionID;
+        const fresh = new Set(sealedNow.map((shard) => shard.Index));
+        const toQueue = (shard) => stored.then(() => pipeline.Queue.Flush([shard]));
+        const byIndex = new Map();
+        for (const shard of [...pipeline.Queue.Unacknowledged(), ...sealedNow]) {
+            byIndex.set(shard.Index, shard);
+        }
+        for (const shard of [...byIndex.values()].sort((a, b) => a.Index - b.Index)) {
+            const key = `${sessionId}/${shard.Index}`;
+            if (this.keepaliveShardsInFlight.has(key)) {
+                continue;
+            }
+            const budget = RealtimeSessionRuntime.recordingKeepaliveBudgetBytes - this.keepaliveBytesInFlight;
+            if (!transport || shard.Bytes.length > budget) {
+                if (fresh.has(shard.Index)) {
+                    void toQueue(shard);
+                }
+                continue;
+            }
+            this.keepaliveShardsInFlight.add(key);
+            void this.trackKeepalive(shard.Bytes.length, transport.UploadShard(sessionId, shard, { Keepalive: true }).then((outcome) => outcome === 'Acked'))
+                .finally(() => this.keepaliveShardsInFlight.delete(key))
+                .catch((error) => {
+                console.warn(`[RealtimeSession] Keepalive upload of recording shard ${sessionId}/${shard.Index} failed: ${describeRecordingFailure(error)}`, error);
+                return false;
+            })
+                .then(async (acked) => {
+                await stored;
+                if (acked) {
+                    await this.deleteStoredShard(sessionId, shard.Index);
+                }
+                else if (fresh.has(shard.Index)) {
+                    await pipeline.Queue.Flush([shard]);
+                }
+            });
+        }
+    }
+    /**
+     * Stores shards from a `setTimeout(0)` task rather than now — the path for shards sealed inside a
+     * page-lifecycle handler, which must not open an IndexedDB transaction itself. Resolves once they
+     * are stored (never, if the page unloads first). Never rejects.
+     */
+    storeShardsLater(pipeline, shards) {
+        return new Promise((resolve) => {
+            setTimeout(() => {
+                void this.storeShards(pipeline, shards).then(resolve);
+            }, 0);
+        });
+    }
+    /**
+     * Sends the terminal request for a pipeline whose tail is already sealed. Resolves true on a server
+     * ack and logs the outcome with the session id. Never rejects.
+     */
+    async sendRecordingTerminal(pipeline, tail, final) {
+        const lastShardIndex = pipeline.Window.LastSealedIndex;
+        const capturedSamples = pipeline.Window.SealedSamples;
+        const context = `session ${pipeline.SessionID} (last shard ${lastShardIndex}, ${capturedSamples} samples)`;
+        if (!pipeline.Transport) {
+            console.warn(`[RealtimeSession] Recording terminal NOT sent for ${context}: no recording transport; stored shards are drained on a later load.`);
+            return false;
+        }
+        try {
+            const acked = await this.trackKeepalive(tail?.Bytes.length ?? 0, pipeline.Transport.SendTerminal(pipeline.SessionID, {
+                Tail: tail?.Bytes ?? null,
+                LastShardIndex: lastShardIndex,
+                CapturedSamples: capturedSamples,
+                Final: final,
+            }));
+            if (!acked) {
+                console.warn(`[RealtimeSession] Recording terminal for ${context} was not acknowledged; the server janitor assembles what arrived.`);
+            }
+            return acked;
+        }
+        catch (error) {
+            console.warn(`[RealtimeSession] Recording terminal for ${context} failed: ${describeRecordingFailure(error)}`, error);
+            return false;
+        }
+    }
+    /**
+     * Ends the recording at teardown and STARTS its terminal request: stops the recorder (flushing the
+     * encoder), cuts the remaining packets into shards with the tail trimmed to the recorder's captured
+     * sample count, and dispatches the `keepalive` terminal plus `keepalive` re-sends of everything not
+     * yet acknowledged, before storing anything ({@link dispatchRecordingTerminal}). Teardown awaits the
+     * returned terminal only after `CloseAgentSession` ({@link awaitRecordingTerminal}), so the small,
+     * critical close never waits behind the recording (#5195).
+     *
+     * The recorder and pipeline stay visible to {@link SendRecordingTerminal} until the recorder has
+     * stopped: a `pagehide` in that window (a host that navigates away without awaiting End) still
+     * sends what was captured, and End then continues at the next index.
+     *
+     * Returns null when nothing was recording or nothing was captured (no terminal is sent then).
+     * Best-effort: never throws, never blocks teardown on the network.
+     */
+    async finishRecording() {
+        this.stopShardFlushing();
+        const recorder = this.recorder;
+        const pipeline = this.recordingShards;
         this.currentTurnStartMs = null;
         this.turnAudioStartCaptured = false;
-        if (!recorder) {
+        this.userSpeechStartMs = null;
+        this.userSpeechStartSuperseded = false;
+        if (!recorder || !pipeline) {
+            this.recorder = null;
+            this.recordingShards = null;
             return null;
         }
         try {
-            // Capture the recorder MIME (now 'audio/wav') BEFORE Stop() — the getter reads '' once stopped.
-            const mimeType = recorder.MimeType;
-            const audioBase64 = await recorder.StopAndEncode();
-            // Read the real waveform peaks computed during capture (survives the stop via the snapshot).
-            const peaks = recorder.GetPeaks();
-            if (!audioBase64) {
-                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — empty recording.');
+            const capturedSamples = await this.stopRecorder(recorder, pipeline.SessionID);
+            this.recorder = null;
+            this.recordingShards = null;
+            const sealed = pipeline.Window.Append(recorder.TakeEncodedPackets());
+            // Without a count from the recorder the tail keeps every packet it holds (SealTail's default).
+            const tail = pipeline.Window.SealTail(capturedSamples === null ? undefined : Math.max(0, capturedSamples - pipeline.Window.SealedSamples));
+            if (pipeline.Window.LastSealedIndex < 0) {
+                pipeline.Queue.Close();
                 return null;
             }
-            return { MimeType: mimeType, AudioBase64: audioBase64, Peaks: peaks };
+            if (sealed.length === 0 && !tail && pipeline.FinalTerminal?.LastSealedIndex === pipeline.Window.LastSealedIndex) {
+                return { Pipeline: pipeline, Acked: pipeline.FinalTerminal.Acked };
+            }
+            return { Pipeline: pipeline, Acked: this.dispatchRecordingTerminal(pipeline, sealed, tail, false, true) };
         }
         catch (error) {
-            console.warn('[RealtimeSession] Failed to stop call recording:', error);
+            console.warn(`[RealtimeSession] Failed to finish the call recording for session ${pipeline.SessionID}; stored shards are drained at the next session start or load:`, error);
+            this.recorder = null;
+            this.recordingShards = null;
+            pipeline.Queue.Close();
+            this.rearmPendingShardDrain();
             return null;
         }
     }
     /**
-     * Uploads a recording returned by {@link stopRecording}. Never throws. No-op when there is
-     * nothing to upload; warns when there is no session id to attach the file to.
+     * Stops the recorder, bounded by {@link RECORDER_STOP_TIMEOUT_MS}. Resolves the captured sample
+     * count, or null when the recorder threw or did not finish in time (logged) — the caller then ends
+     * the recording at the packets already encoded. Never rejects.
      */
-    async uploadStoppedRecording(agentSessionId, recording) {
-        if (!recording) {
-            return;
-        }
-        if (!agentSessionId) {
-            console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — no session id.');
-            return;
-        }
+    async stopRecorder(recorder, sessionId) {
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), RECORDER_STOP_TIMEOUT_MS);
+        });
         try {
-            await this.uploadRecording(agentSessionId, recording.AudioBase64, recording.MimeType, recording.Peaks);
+            const outcome = await Promise.race([recorder.Stop(), timedOut]);
+            if (outcome === 'timeout') {
+                console.warn(`[RealtimeSession] Recorder did not stop within ${RECORDER_STOP_TIMEOUT_MS}ms for session ${sessionId}; ending the recording at the packets already encoded.`);
+                return null;
+            }
+            return outcome;
         }
         catch (error) {
-            console.warn(`[RealtimeSession] Failed to upload call recording for session ${agentSessionId}:`, error);
+            console.warn(`[RealtimeSession] Recorder failed to stop for session ${sessionId}; ending the recording at the packets already encoded:`, error);
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
         }
     }
     /**
-     * Runs the `UploadRealtimeRecording` mutation. A `Success:false` payload is logged; a transport
-     * rejection propagates to `uploadStoppedRecording`, which catches and logs it. Sends the
-     * capture-time waveform `peaks` (max-abs per bucket, normalized 0..1) so the server can persist a
-     * `peaks.json` sidecar for fast waveform rendering without re-decoding the audio.
+     * Waits for the terminal {@link finishRecording} started, bounded by
+     * {@link RECORDING_TERMINAL_ACK_TIMEOUT_MS}, logs the outcome, then closes the recording's queue
+     * (anything it had not delivered stays in the local store for the next-load drain). Never throws.
      */
-    async uploadRecording(agentSessionId, audioBase64, mimeType, peaks) {
-        const mutation = `
-      mutation UploadRealtimeRecording($agentSessionId: String!, $audioBase64: String!, $mimeType: String!, $consent: Boolean, $peaks: [Float!]) {
-        UploadRealtimeRecording(agentSessionId: $agentSessionId, audioBase64: $audioBase64, mimeType: $mimeType, consent: $consent, peaks: $peaks) {
-          Success
-          FileID
-          ErrorMessage
-        }
-      }
-    `;
-        const result = await this.gql().ExecuteGQL(mutation, {
-            agentSessionId,
-            audioBase64,
-            mimeType,
-            consent: true,
-            peaks
+    async awaitRecordingTerminal(pending) {
+        const sessionId = pending.Pipeline.SessionID;
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), RECORDING_TERMINAL_ACK_TIMEOUT_MS);
         });
-        const payload = result?.UploadRealtimeRecording;
-        if (!payload?.Success) {
-            console.warn(`[RealtimeSession] ❌ recording upload reported failure: ${payload?.ErrorMessage ?? 'unknown error'} (full result: ${JSON.stringify(result)})`);
+        try {
+            const outcome = await Promise.race([pending.Acked.then((ok) => (ok ? 'ack' : 'failed')), timedOut]);
+            if (outcome === 'ack') {
+                console.log(`[RealtimeSession] Recording terminal acknowledged for session ${sessionId}.`);
+            }
+            else if (outcome === 'timeout') {
+                console.warn(`[RealtimeSession] Recording terminal for session ${sessionId} not acknowledged within ${RECORDING_TERMINAL_ACK_TIMEOUT_MS}ms; ending anyway (the keepalive request may still land).`);
+            }
+            // 'failed' was already logged with its reason by sendRecordingTerminal.
+        }
+        finally {
+            clearTimeout(timer);
+            pending.Pipeline.Queue.Close();
+            // The recording may have left shards in the store (an unacknowledged tail, windows the queue
+            // still held or had on the wire at Close), so re-arm the drain for the next session start on
+            // this page. Re-armed here, after the wait, so it never races the recording's own terminal;
+            // and unconditionally, because whether a fire-and-forget upload landed is not known here and
+            // a drain of an empty store costs one read.
+            this.rearmPendingShardDrain();
         }
     }
     /**
@@ -2956,6 +3401,11 @@ export class RealtimeSessionRuntime {
         client.OnInterruption(() => {
             this.cancelPendingNarration();
         });
+        // The provider VAD saw the user start speaking. Final-only user-transcript drivers (OpenAI,
+        // HuggingFace, xAI) emit no user interim, so this is their only real user-turn start. It goes
+        // to its own slot, not the shared turn slot: the user transcript arrives asynchronously, so the
+        // assistant's reply may already be streaming and must keep its own start.
+        client.OnUserSpeechStart(() => this.markUserSpeechStart());
         client.OnRemoteVideo((video) => this.onAgentVideo(client, video));
     }
     /**
@@ -3058,6 +3508,11 @@ export class RealtimeSessionRuntime {
             }
             return;
         }
+        if (transcript.Role === 'User' && transcript.Text.trim().length === 0) {
+            // An empty final user transcript (a VAD false positive, an empty transcription) never reaches
+            // relayTranscript, so release its onset here: it must not become the next real turn's start.
+            this.releaseUserSpeechStart();
+        }
         if (transcript.Role === 'Assistant') {
             this.hasActiveInterimUserCaption = false;
             this.pendingUserCaption = '';
@@ -3132,11 +3587,10 @@ export class RealtimeSessionRuntime {
      * - NORMAL turns only — NARRATION interims are ephemeral and never persisted, so they must not
      *   claim the next real turn's start slot.
      *
-     * Works for any role whose driver surfaces interim deltas (all drivers for the assistant; the
-     * relevant case here — the post-tool-gap assistant answer — and user-interim drivers like
-     * Gemini/AssemblyAI). For final-only user turns (OpenAI/xAI/ElevenLabs) no interim arrives, so
-     * {@link relayTranscript} falls back to the seeded/prior start — the gap case that drifts is the
-     * assistant answer, which always has interims.
+     * Stamped on a turn's first interim transcript (all drivers for the assistant — the post-tool-gap
+     * assistant answer — and user-interim drivers like Gemini/AssemblyAI). Final-only user turns
+     * (OpenAI-protocol drivers) take their start from {@link markUserSpeechStart}'s own slot
+     * instead; one with no speech-start signal either (ElevenLabs) relays `null` as-is.
      */
     markTurnAudioStart(kind) {
         if (this.turnAudioStartCaptured || kind === 'narration') {
@@ -3149,15 +3603,39 @@ export class RealtimeSessionRuntime {
         this.currentTurnStartMs = offset;
         this.turnAudioStartCaptured = true;
     }
+    /**
+     * Stamps {@link userSpeechStartMs} when the client signals that the user began to speak. Keeps
+     * the FIRST onset since the last final user transcript: the VAD fires again after a
+     * mid-sentence pause, and that second onset is not where the utterance began. An onset that an
+     * assistant turn which began after it has since superseded ({@link userSpeechStartSuperseded}) is
+     * replaced instead.
+     */
+    markUserSpeechStart() {
+        if (this.userSpeechStartMs !== null && !this.userSpeechStartSuperseded) {
+            return;
+        }
+        const offset = this.nowTurnOffsetMs();
+        if (offset === null) {
+            return;
+        }
+        this.userSpeechStartMs = offset;
+        this.userSpeechStartSuperseded = false;
+    }
+    /** Ends the held user onset: a final user transcript (empty or not) closed the utterance it began. */
+    releaseUserSpeechStart() {
+        this.userSpeechStartMs = null;
+        this.userSpeechStartSuperseded = false;
+    }
     /**
      * The current per-turn offset in ms — the RECORDER's clock when one runs (an offset into a
      * seekable file), else the SESSION clock (#3832: orderable and displayable, not seekable),
      * else `null` before any call is live. One function so the two stamp sites cannot disagree
-     * about which clock a session is on.
+     * about which clock a session is on. Always whole milliseconds: the offsets travel as GraphQL
+     * `Int`, which refuses a fraction, and a 48 kHz sample clock rarely lands on a whole millisecond.
      */
     nowTurnOffsetMs() {
         if (this.recorder) {
-            return this.recorder.NowOffsetMs();
+            return Math.round(this.recorder.NowOffsetMs());
         }
         if (this.sessionClockStartMs !== null) {
             return Math.max(0, Math.round(performance.now() - this.sessionClockStartMs));
@@ -3181,8 +3659,13 @@ export class RealtimeSessionRuntime {
         }
         this.appendCaption({ Role: role, Text: text });
     }
-    /** Finalizes the user turn: push a caption + relay the final transcript. */
-    async onUserTranscript(transcript) {
+    /**
+     * Finalizes the user turn: push a caption + relay the final transcript.
+     *
+     * @param source `'typed'` for a {@link SendText} turn: it has no speech onset, so it neither takes
+     *   nor clears the held one (a spoken transcript may still be pending for it).
+     */
+    async onUserTranscript(transcript, source = 'speech') {
         if (transcript.trim().length === 0) {
             return;
         }
@@ -3191,7 +3674,7 @@ export class RealtimeSessionRuntime {
             this.firstUserTranscript = transcript;
         }
         this.appendCaption({ Role: 'User', Text: transcript });
-        await this.relayTranscript('user', transcript);
+        await this.relayTranscript('user', transcript, false, source);
     }
     // ── Tool calling ───────────────────────────────────────────────────────────
     /**
@@ -3519,37 +4002,71 @@ export class RealtimeSessionRuntime {
      * Relays a final transcript turn to MJ via `RelayRealtimeTranscript`.
      *
      * When the session is being recorded, per-turn timing rides along: `utteranceEndMs` is the
-     * recording-relative offset at finalization, and `utteranceStartMs` is the offset captured by
-     * {@link markTurnAudioStart} when THIS turn's audio actually began (its first interim) — NOT
-     * inherited from the previous turn's end. That distinction is the timing fix: when a tool-call
-     * / silence gap sits between turns, the post-gap turn's audio starts much later, so inheriting
-     * the prior turn's end stamped the cue ~gap-length too early. Both are omitted (left `null`)
-     * when the session isn't being recorded.
+     * recording-relative offset at finalization, and `utteranceStartMs` is where THIS turn's audio
+     * actually began — NOT inherited from the previous turn's end. For a user turn whose onset the
+     * client signalled, that is {@link userSpeechStartMs}; otherwise it is the offset captured by
+     * {@link markTurnAudioStart} on the turn's first interim. That distinction is the timing fix:
+     * when a tool-call / silence gap sits between turns, the post-gap turn's audio starts much
+     * later, so inheriting the prior turn's end stamped the cue ~gap-length too early. Both are
+     * omitted (left `null`) when the session isn't being recorded. `utteranceStartMs` is also
+     * `null` when no start was measured for this turn; it is never replaced with a placeholder 0.
      *
      * A correction (`replacesPrevious`) doesn't open a new turn, so it carries no start and doesn't
      * reset the per-turn start guard. After a normal finalization the guard is cleared so the NEXT
-     * turn re-stamps its start from where ITS audio begins.
+     * turn re-stamps its start from where ITS audio begins — except for a user turn that used its
+     * own speech-start slot, which leaves the shared slot alone (it may hold the in-flight
+     * assistant turn's start). Every final user transcript, corrections included, clears the
+     * speech-start slot.
      *
      * @param replacesPrevious CORRECTION semantics: the server updates the session's most
      *   recent persisted turn of this role IN PLACE instead of appending (e.g. ElevenLabs'
      *   post-barge-in `agent_response_correction`).
+     * @param source `'typed'` for a user turn sent with {@link SendText}: it does not read or clear
+     *   {@link userSpeechStartMs}, which belongs to the user's speech.
      */
-    async relayTranscript(role, text, replacesPrevious = false) {
+    async relayTranscript(role, text, replacesPrevious = false, source = 'speech') {
         if (!this.agentSessionId) {
             return;
         }
+        // Every final user transcript closes the signalled onset — a correction too, since it ends the
+        // same utterance — so a later onset (an xAI mid-sentence resume) can't leak into the next turn.
+        let userSpeechStartMs = null;
+        if (role === 'user' && source === 'speech') {
+            userSpeechStartMs = this.userSpeechStartMs;
+            this.releaseUserSpeechStart();
+        }
         // Per-turn timing against whichever clock the session is on (#3832): the recorder's when one
-        // runs, else the session clock. `utteranceStartMs` is where this turn's audio actually began
-        // (captured by markTurnAudioStart on the first interim); the `?? 0` fallback covers a turn
-        // whose interim was missed / a final-only first turn.
+        // runs, else the session clock. `utteranceStartMs` is where this turn's audio actually began.
+        // It is null when no start was measured for this turn (a final-only driver with no speech-start
+        // signal), so the server stores NULL rather than a placeholder 0.
         const utteranceEndMs = this.nowTurnOffsetMs();
-        const utteranceStartMs = utteranceEndMs !== null && !replacesPrevious ? (this.currentTurnStartMs ?? 0) : null;
-        if (utteranceEndMs !== null && !replacesPrevious) {
+        const opensTurn = utteranceEndMs !== null && !replacesPrevious;
+        let utteranceStartMs = null;
+        if (opensTurn && userSpeechStartMs !== null) {
+            // A user turn with a signalled onset. Leave the shared slot alone: the user transcript
+            // arrives asynchronously, so it may already hold the in-flight assistant reply's start.
+            utteranceStartMs = userSpeechStartMs;
+            if (!this.turnAudioStartCaptured) {
+                // No turn has captured a start, so the slot holds only the recording-start seed (0). This
+                // user turn was the first turn; drop the seed so a later unmeasured turn relays null, not 0.
+                this.currentTurnStartMs = null;
+            }
+        }
+        else if (opensTurn) {
+            utteranceStartMs = this.currentTurnStartMs;
             // This turn is finalized — arm the NEXT turn to re-stamp its start from its own first
             // interim (handles a tool-call gap before the next turn). Stop inheriting this end as the
-            // next start. `null` means "not yet captured"; relay falls back to `?? 0` if no interim fires.
+            // next start. `null` means "not yet captured" and is relayed as-is if nothing stamps it.
             this.currentTurnStartMs = null;
             this.turnAudioStartCaptured = false;
+            if (role === 'assistant' && this.userSpeechStartMs !== null && (utteranceStartMs === null || this.userSpeechStartMs < utteranceStartMs)) {
+                // The floor moved on past an onset that began BEFORE this assistant turn: a late user
+                // transcript may still claim it, but the next onset replaces it (see userSpeechStartSuperseded).
+                // An onset that began DURING this turn is a barge-in; it belongs to the user speech still
+                // pending, so it stays the first onset. With no measured assistant start we cannot tell, and
+                // treat the onset as earlier.
+                this.userSpeechStartSuperseded = true;
+            }
         }
         try {
             const mutation = `
@@ -3980,6 +4497,14 @@ export class RealtimeSessionRuntime {
         // set (the captured per-save id covers the race anyway), then dispose the plugins.
         this.flushAllChannelSaves();
         this.disposeChannels();
+        // End the recording and START its keepalive terminal request now: stop the recorder (which flushes
+        // the encoder) before anything else that awaits. A tab closed right after End gets only the pagehide
+        // terminal, which carries packets already encoded; releasing the mic and disconnecting the driver can
+        // take long enough for the page to die first, and the audio still inside the encoder would be lost.
+        // It also goes out before the usage flush and the close, so it is on the wire if the page dies during
+        // either. Best-effort — finishRecording never throws. Null when nothing was recorded.
+        const recordingTerminal = await this.finishRecording();
+        this.recordingStartedAtIso = null;
         // The camera and screen share go first: the camera runs on the controller closed next.
         this.closeCaptures();
         // Defensive: stop the mic even when Connect never ran (the client also stops the
@@ -4013,11 +4538,6 @@ export class RealtimeSessionRuntime {
                 this.client = null;
             }
         }
-        // Stop + encode the call recording now (the recorder must be detached before the session id is
-        // cleared); the upload itself happens after the close below. Best-effort — stopRecording
-        // swallows its own errors. Null when nothing was recorded.
-        const recording = await this.stopRecording();
-        this.recordingStartedAtIso = null;
         // Final usage flush WHILE the live session id is still set (the relay mutation also
         // accepts a Closed session, so ordering vs. CloseAgentSession is belt-and-braces).
         if (this.usageFlushTimer) {
@@ -4029,11 +4549,12 @@ export class RealtimeSessionRuntime {
         if (closeServerSession && this.agentSessionId) {
             await this.closeServerSession(this.agentSessionId);
         }
-        // Upload AFTER the close. The WAV is tens of MB and takes seconds; a page unload aborts the
-        // request, and nothing after an aborted await ever runs — so the small, critical close goes
-        // first (#5195). The server accepts the upload on a Closed session (loadOwnedSession does not
-        // check status), and uploadStoppedRecording never throws.
-        await this.uploadStoppedRecording(this.agentSessionId, recording);
+        // Wait for the terminal's ack only AFTER the close: nothing after an aborted await ever runs, so
+        // the small, critical close must never queue behind the recording (#5195). Bounded by
+        // RECORDING_TERMINAL_ACK_TIMEOUT_MS; SavingRecording$ stays up until it settles.
+        if (recordingTerminal) {
+            await this.awaitRecordingTerminal(recordingTerminal);
+        }
         // Capture the session id BEFORE we null it so the lifecycle emit carries it.
         // Skip emitting when there was no live session (defensive — teardown is safe
         // to call without an active session).
@@ -4098,12 +4619,16 @@ export class RealtimeSessionRuntime {
         this.pendingUserCaption = '';
         this.hasActiveInterimUserCaption = false;
         this.SetMinimized(false);
-        this.stopSegmentFlushing();
-        this.shardQueue = null;
+        this.stopShardFlushing();
+        // Defensive: teardown already ended any previous recording; a stray pipeline must not keep sending.
+        this.recordingShards?.Queue.Close();
+        this.recordingShards = null;
         this.recorder = null;
         this.recordingStartedAtIso = null;
         this.currentTurnStartMs = null;
         this.turnAudioStartCaptured = false;
+        this.userSpeechStartMs = null;
+        this.userSpeechStartSuperseded = false;
         this.usedChannelNames.clear();
         this.microphoneMuted = false;
     }