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

package/dist/session/RealtimeSessionRuntime.d.ts

@@ -15,6 +15,31 @@ import type { RealtimeContextActionResult } from '../channels/channel-contract-t
 import { type AppClientToolRegistration } from './app-client-tool-registry.js';
 import { type IChannelExposurePreferences } from './channel-exposure-preferences.js';
 import { type RealtimeSessionStartOptions } from './channel-session-scope.js';
+import { type IRecordingShardStore } from './RecordingShardStore.js';
+import type { IRecordingTransport } from './RecordingTransport.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 declare 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 declare const RECORDER_STOP_TIMEOUT_MS = 2000;
+/** Options of {@link RealtimeSessionRuntime.SendRecordingTerminal}. */
+export interface RecordingTerminalOptions {
+    /**
+     * False when the call may continue — the host's `visibilitychange → hidden` handler. The server then
+     * stamps the counts but assembles only after its grace period, so switching tabs does not rewrite the
+     * recording each time. Defaults to true (`pagehide`: the page is going away).
+     */
+    Final?: boolean;
+}
 /**
  * `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
@@ -224,6 +249,15 @@ export interface RealtimeSessionRunOptions {
      */
     readonly appContext?: AppContextSnapshot | null;
 }
+/** Why a call ended, as the runtime reports it on `SessionEnded$`. */
+export type SessionEndReason = 'explicit' | 'error';
+/** The `CloseReason` values a client may stamp on its own session row; the others belong to the server. */
+export type ClientCloseReason = 'Explicit' | 'Error';
+/** Thrown by a start while a call is live: the runtime holds one driver, and never replaces a live one. */
+export declare class RealtimeSessionAlreadyActiveError extends Error {
+    readonly ActiveAgentSessionId: string | null;
+    constructor(ActiveAgentSessionId: string | null);
+}
 /**
  * Drives a **client-direct** real-time voice session: the browser mints an ephemeral
  * token from the MJ server, then connects DIRECTLY to the realtime provider. Audio
@@ -250,9 +284,9 @@ export declare class RealtimeSessionRuntime {
     protected readonly mediaHost: IRealtimeMediaHost;
     /**
      * @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: IRealtimeMediaHost);
     private _connectionState$;
@@ -322,10 +356,11 @@ export declare class RealtimeSessionRuntime {
     readonly Minimized$: Observable<boolean>;
     /**
      * 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.).
      */
     readonly SavingRecording$: Observable<boolean>;
     /** Synchronous read of {@link SavingRecording$}. */
@@ -416,13 +451,13 @@ export declare class RealtimeSessionRuntime {
      * Fired EXACTLY ONCE per session as teardown begins, with the prior
      * `agentSessionId` (so subscribers can correlate against `SessionStarted$`'s
      * sessionId) and the client-distinguishable reason — `'explicit'` when the
-     * user called `EndRealtimeSession`, `'error'` when teardown ran from a catch
-     * block. Server-side close paths (janitor, shutdown) do NOT propagate here —
+     * user called `EndRealtimeSession`, `'error'` when the runtime ended the call over a failure: a
+     * failed start, or a fatal error from the provider mid-call. Server-side close paths (janitor, shutdown) do NOT propagate here —
      * they happen out-of-process and have no client push channel today.
      */
     readonly SessionEnded$: Observable<{
         sessionId: string;
-        reason: 'explicit' | 'error';
+        reason: SessionEndReason;
     }>;
     /**
      * Fires with the channel PLUGIN every time the agent ACTS on that channel (a tool call
@@ -536,25 +571,54 @@ export declare class RealtimeSessionRuntime {
     private narrationTemplate;
     /**
      * 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.
      */
     private recorder;
     /** ISO timestamp of when recording started — sent to the server on session start. */
     private recordingStartedAtIso;
-    /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
-    private segmentTimer;
+    /** Interval that cuts and uploads a shard every {@link recordingShardFlushMs} during a recording. */
+    private shardFlushTimer;
     /**
-     * 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.
+     * 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.
      */
-    private shardQueue;
-    /** How often crash-recovery shards are flushed during a recording. */
-    private static readonly segmentFlushMs;
+    private recordingShards;
+    /** How often packets are cut into shards: the 5 s shard window, so each tick seals about one window. */
+    private static readonly recordingShardFlushMs;
+    /**
+     * 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).
+     */
+    private static readonly recordingKeepaliveBudgetBytes;
+    /**
+     * 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.
+     */
+    private keepaliveBytesInFlight;
+    /** `sessionId/index` of shards whose `keepalive` copy is still in flight; never sent twice at once. */
+    private readonly keepaliveShardsInFlight;
+    /**
+     * 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.
+     */
+    private static readonly maxDrainRunsPerCall;
+    /** The durable local shard store, created on first use and shared by every recording of this runtime. */
+    private shardStore;
+    /**
+     * True once a drain ran with a transport; the drain then does nothing until a recording ends and
+     * re-arms it ({@link rearmPendingShardDrain}).
+     */
+    private pendingShardsDrained;
+    /** Bumped by every re-arm, so a drain already in flight cannot mark itself done over a re-arm. */
+    private drainGeneration;
+    /** The drain in flight, so overlapping callers share it instead of uploading the same shards twice. */
+    private drainInFlight;
     /**
      * Interval that tells the server this session is still in use, or `null` when no session is
      * running. See {@link startLivenessPulse} for why the server cannot work this out itself.
@@ -571,12 +635,40 @@ export declare 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}.
      */
     private currentTurnStartMs;
+    /**
+     * 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}.
+     */
+    private userSpeechStartMs;
+    /**
+     * `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).
+     */
+    private userSpeechStartSuperseded;
+    /**
+     * Recording-relative ms offsets of user speech onsets keyed by the provider's conversation item id
+     * (`input_audio_buffer.speech_started.item_id`), paired with the matching final user transcript
+     * (`RealtimeClientTranscript.ItemId`) so a late user transcript never claims a later turn's onset
+     * (MJ#5902). Unkeyed drivers continue to use {@link userSpeechStartMs}.
+     */
+    private readonly userSpeechStartByItemId;
     /**
      * 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}.
@@ -673,6 +765,15 @@ export declare class RealtimeSessionRuntime {
      * two `SessionEnded$` emissions for one session.
      */
     private teardownInFlight;
+    /**
+     * True from the moment a start finishes (connected, liveness pulse running) until the slot is
+     * released. A driver's Fatal ends the call only while this is set: during a start, drivers emit
+     * Fatal from their socket handlers while Connect is still pending, and the start's own failure path
+     * ({@link failSessionStart}) is what reports that error, whether Connect then rejects or resolves
+     * (runMintedSession checks {@link lastSessionError} after Connect). Not {@link isSessionLive}: drivers move the
+     * state to 'listening' from inside Connect, and a live call that is resuming reads 'connecting'.
+     */
+    private callWentLive;
     /**
      * The latest start's opening of the host's microphone, until {@link IRealtimeMediaHost.ReleaseMicrophone} hands it
      * back; `null` when no opening is owed a release, so a session that ends before asking for the microphone releases
@@ -801,6 +902,21 @@ export declare class RealtimeSessionRuntime {
      * regard to case.
      */
     IsActiveFor(conversationId: string | null | undefined): boolean;
+    /**
+     * Takes the runtime's one driver slot for a new start; the two starts call it after awaiting any
+     * teardown in flight, and only when no End arrived during that wait (a changed {@link startGeneration}).
+     *
+     * A teardown still in flight is awaited rather than read as "busy": ending a call and starting the
+     * next one back to back is normal host behaviour (a retry, a re-mounted surface), and the flag it
+     * used to read flips only at the END of teardown, so the start was dropped with nothing to show
+     * for it — a bare `undefined`, which hosts had to guess at (MJ#4629). A call that is genuinely
+     * live is refused with an error the host can show; it is never silently ignored, and never
+     * overwritten, since a driver no slot points at can never be stopped again.
+     *
+     * Deliberately synchronous: the start's state must be set in the tick the host called it in, or an
+     * End issued straight after the Start (a user tapping back during the mint) finds nothing to abandon.
+     */
+    private claimSessionSlot;
     /**
      * Start a client-direct voice session fronting `targetAgentId`.
      *
@@ -831,7 +947,7 @@ export declare 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,
@@ -895,8 +1011,8 @@ export declare class RealtimeSessionRuntime {
     /**
      * Start prologue shared by both entry points: clear the last start's failure, bind the app layer,
      * publish the agent name, reset per-session state, and flip the session live (which is ALSO what
-     * makes the `IsActive` guard suppress duplicate starts while the mint is still in flight — hence it
-     * runs before minting, not after). Returns the resolved recording consent, which the mint half
+     * makes {@link claimSessionSlot} refuse a second start with {@link RealtimeSessionAlreadyActiveError}
+     * while the mint is still in flight — hence it runs before minting, not after). Returns the resolved recording consent, which the mint half
      * reports to the server and the run half uses to decide whether to record.
      */
     private beginSessionStart;
@@ -905,6 +1021,8 @@ export declare class RealtimeSessionRuntime {
      * the provider connection, and go live. `inputConversationId` is the conversation the START asked
      * for (null ⇒ "server, make me one") — the result alone can't distinguish the two. `cameraCheck` is
      * whether the host shows a camera check ({@link RealtimeSessionStartOptions.CameraCheck}).
+     * `generation` is the {@link startGeneration} the entry point captured before its first await; every
+     * await below is a window in which the host can end the session, and so was every await before this.
      */
     private runMintedSession;
     /**
@@ -1058,6 +1176,15 @@ export declare class RealtimeSessionRuntime {
      * overlay into 'error', and unwind whatever the half-built session already opened.
      */
     private failSessionStart;
+    /**
+     * Ends the call over a failure: a failed start, an unusable provider, or a fatal provider error.
+     *
+     * The teardown is claimed BEFORE `'error'` is published. `ConnectionState$` emits synchronously, and a
+     * host may end the call the moment it sees `'error'` (MobileApp's voice screen does); claimed first, that
+     * host's End joins this teardown instead of starting its own as `'explicit'`, so the row still closes as
+     * `Error` and `SessionEnded$` still says `'error'`. Teardown keeps a terminal `'error'` state.
+     */
+    private endOnFailure;
     /**
      * End the active session: stop the mic, tear down the provider connection, and close
      * the server-side agent session. Safe to call when no session is active.
@@ -1155,10 +1282,60 @@ export declare class RealtimeSessionRuntime {
      * nothing (the recorder disables itself).
      */
     private startRecording;
-    /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
-    private startSegmentFlushing;
-    /** Stops the periodic crash-recovery shard flush. */
-    private stopSegmentFlushing;
+    /**
+     * 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.
+     */
+    protected createRecordingTransport(): IRecordingTransport | null;
+    /**
+     * 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.
+     */
+    protected createRecordingShardStore(): IRecordingShardStore;
+    /** The provider's signed-in user, or null (no provider yet, or an anonymous page). */
+    private signedInUserID;
+    /** The runtime's shard store, created on first use. */
+    private ensureShardStore;
+    /**
+     * 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(): Promise<number>;
+    /** Makes the next {@link DrainPendingRecordingShards} call run again, even one already in flight. */
+    private rearmPendingShardDrain;
+    /**
+     * 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.
+     */
+    private drainPendingShards;
+    /** One drain pass over the signed-in user's stored shards (see {@link DrainStoredRecordingShardsOnce}). */
+    private drainStoredShardsOnce;
+    /** Builds this recording's shard pipeline and starts the 5 s flush. */
+    private startShardFlushing;
+    /**
+     * 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.
+     */
+    private recoverStoredShardsAfterOutage;
+    /** Stops the periodic shard flush. */
+    private stopShardFlushing;
     /**
      * Starts telling the server this session is still in use (#3533).
      *
@@ -1190,37 +1367,109 @@ export declare class RealtimeSessionRuntime {
      */
     private pulseLiveness;
     /**
-     * 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.
+     */
+    private flushRecordingShards;
+    /** Writes shards to the local store, in order, before their upload starts. Never rejects. */
+    private storeShards;
+    /** Removes an acknowledged shard from the local store. Never rejects. */
+    private deleteStoredShard;
+    /**
+     * 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.
+     */
+    SendRecordingTerminal(options?: RecordingTerminalOptions): void;
+    /**
+     * 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.
      */
-    private flushRecordingSegment;
+    private dispatchRecordingTerminal;
+    /** Counts `bytes` against the page's keepalive budget until `request` settles. */
+    private trackKeepalive;
     /**
-     * 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.
+     * 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.
      */
-    private uploadRecordingShard;
+    private resendUnacknowledgedWithKeepalive;
     /**
-     * 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.
+     * 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.
      */
-    private stopRecording;
+    private storeShardsLater;
     /**
-     * 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.
+     * 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.
      */
-    private uploadStoppedRecording;
+    private sendRecordingTerminal;
     /**
-     * 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.
+     * 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.
      */
-    private uploadRecording;
+    private finishRecording;
+    /**
+     * 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.
+     */
+    private stopRecorder;
+    /**
+     * 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.
+     */
+    private awaitRecordingTerminal;
     /** Whether the channel catalog note still has to be sent (see {@link flushChannelCatalogNote}). */
     private catalogNotePending;
     /** Plugins resolved for the current start but not yet initialized. Consumed by {@link activateChannels}. */
@@ -1624,18 +1873,38 @@ export declare 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.
      */
     private markTurnAudioStart;
+    /**
+     * Stamps the user speech onset when the client signals that the user began to speak. When the
+     * driver supplies a conversation `itemId`, records the FIRST onset for that item in
+     * {@link userSpeechStartByItemId} so a mid-sentence pause that re-fires with the same id keeps the
+     * original start. When no `itemId` is supplied, stamps the single-slot {@link userSpeechStartMs}
+     * fallback (keeping the first onset unless {@link userSpeechStartSuperseded} is set).
+     */
+    private markUserSpeechStart;
+    /**
+     * Ends the held user onset: a final user transcript (empty or not) closed the utterance it began.
+     * When `itemId` is supplied, deletes only that item's entry in {@link userSpeechStartByItemId};
+     * otherwise clears the unkeyed single slot.
+     */
+    private releaseUserSpeechStart;
+    /**
+     * Consumes and deletes the onset recorded for `itemId` in {@link userSpeechStartByItemId}. When a
+     * matching onset is found, also deletes any remaining map entry with an earlier offset so a VAD
+     * false positive whose transcription never arrived cannot accumulate in the map.
+     */
+    private takeKeyedUserSpeechStart;
     /**
      * 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.
      */
     private nowTurnOffsetMs;
     /**
@@ -1644,7 +1913,13 @@ export declare class RealtimeSessionRuntime {
      * client's caption window).
      */
     private replaceLastCaption;
-    /** Finalizes the user turn: push a caption + relay the final 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).
+     * @param itemId Provider conversation item id (`RealtimeClientTranscript.ItemId`) when present.
+     */
     private onUserTranscript;
     /**
      * Routes a provider tool call: names matching a registered client-tool prefix execute
@@ -1738,20 +2013,28 @@ export declare 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} or {@link userSpeechStartByItemId}, which belong to the user's speech.
+     * @param itemId Provider conversation item id (`RealtimeClientTranscript.ItemId`) when present.
      */
     private relayTranscript;
     /**
@@ -1870,18 +2153,34 @@ export declare class RealtimeSessionRuntime {
     /** Tears down the delegation progress subscription and resets the narration throttle. */
     private teardownDelegationProgress;
     /**
-     * Tears down all client resources and (optionally) closes the server session.
-     * @param closeServerSession when true, calls `CloseAgentSession` on the server.
+     * Tears down all client resources and closes the server session when one was minted.
+     *
+     * The server row is closed whichever way the call ended: a start that failed after the mint used to
+     * leave its row `Active` until the janitor's staleness sweep, 15 minutes later, so every host that
+     * counts live sessions saw a phantom call (MJ#6013). The janitor remains the fallback for a client
+     * that dies before it can say anything; it is never the plan.
+     *
+     * @param end why the call ended — `'explicit'` when the host or user ended it, `'error'` when the
+     *   runtime ended it because the start or the call failed. Reported on `SessionEnded$` and stamped on
+     *   the server row as its `CloseReason` (`Explicit` / `Error`).
      */
     private teardown;
     /** The body of {@link teardown}; never called concurrently with itself. */
     private runTeardown;
+    /** The teardown's work: stop the call, hand back what it held, and close the server session. */
+    private releaseCallResources;
+    /** Clears the slot and tells the host the call ended; runs even when {@link releaseCallResources} threw. */
+    private releaseSessionSlot;
     /**
      * Calls the host's {@link IRealtimeMediaHost.ReleaseMicrophone}. Best-effort by contract: a failure
      * is logged and never thrown, because it must never block ending a call.
      */
     private releaseMicrophone;
-    /** Calls the `CloseAgentSession` mutation (provisioned in P4b). */
+    /**
+     * Calls the `CloseAgentSession` mutation (provisioned in P4b) with why the client ended the call, which
+     * the server stamps as the row's `CloseReason`. Requires a server that accepts the `closeReason`
+     * argument (MJ#6013); the runtime and the server ship together.
+     */
     private closeServerSession;
     /** Pushes a caption onto the live list (immutable update for change detection). */
     private appendCaption;