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

package/dist/session/RealtimeSessionRuntime.js

@@ -1,13 +1,48 @@
 import { BehaviorSubject, Subject } from 'rxjs';
 import { Metadata } from '@memberjunction/core';
 import { UserInfoEngine } from '@memberjunction/core-entities';
-import { AIEngineBase } from '@memberjunction/ai-engine-base';
-import { MJGlobal } from '@memberjunction/global';
-import { DEFAULT_REALTIME_AUDIO_TRACKS } from '@memberjunction/ai';
-import { BaseRealtimeClient, LoadAssemblyAIRealtimeClient, LoadElevenLabsRealtimeClient, LoadGeminiRealtimeClient, LoadHuggingFaceRealtimeClient, LoadOpenAIRealtimeClient, LoadxAIRealtimeClient, REQUESTED_TRACKS_SESSION_KEY } from '@memberjunction/ai-realtime-client';
+import { AddRealtimeUsageRecord, AIEngineBase, HasRealtimeUsage } from '@memberjunction/ai-engine-base';
+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, 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';
+import { ClientSessionDeadline } from './client-session-deadline.js';
+import { RealtimeCaptures, REALTIME_CAPTURES_OFF, REALTIME_CAPTURE_OFFERS_NONE, } from './realtime-captures.js';
+import { REALTIME_MICROPHONE_NONE, ReadMicrophoneState, SameMicrophoneState } from './realtime-microphone.js';
+import { RealtimeSessionEventHub } from './session-event-hub.js';
 import { BuildNarrationInstructions } from '../narration/narration-template.js';
 import { ParseDelegationResultJson, FormatToolName } from './delegation-result-parser.js';
-import { BaseRealtimeChannelClient } from '../channels/base-realtime-channel-client.js';
+import { BaseRealtimeChannelClient, ChannelVideoSourceID } from '../channels/base-realtime-channel-client.js';
+import { DEFAULT_CHANNEL_SURFACE_PLACEMENT, ReadChannelSurfacePlacement } from '../channels/channel-surface-placement.js';
+import { ChannelActionDispatcher } from '../channels/channel-action-dispatcher.js';
+import { BuildChannelCatalogNote } from '../channels/channel-catalog-note.js';
+import { AppClientToolRegistry, DEFAULT_APP_TOOL_OWNER } from './app-client-tool-registry.js';
+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
@@ -15,6 +50,15 @@ import { BaseRealtimeChannelClient } from '../channels/base-realtime-channel-cli
  * default when the caller doesn't pass an explicit consent value.
  */
 export const REALTIME_RECORDING_CONSENT_KEY = 'mj.realtimeVoice.recordingConsent.v1';
+/**
+ * Relays usage onto the co-agent prompt run: token deltas, and the per-modality detail blocks as a
+ * JSON record (sent only when there are any; see `RelayRealtimeUsage` in MJServer).
+ */
+const RELAY_REALTIME_USAGE_MUTATION = `
+  mutation RelayRealtimeUsage($agentSessionId: String!, $inputTokens: Int!, $outputTokens: Int!, $usageDetailsJson: String) {
+    RelayRealtimeUsage(agentSessionId: $agentSessionId, inputTokens: $inputTokens, outputTokens: $outputTokens, usageDetailsJson: $usageDetailsJson)
+  }
+`;
 // Tree-shaking prevention: the OpenAI client is resolved dynamically through the
 // ClassFactory (by the server-reported Provider key), so this static call is what keeps
 // its @RegisterClass side effect from being eliminated by the bundler.
@@ -24,10 +68,37 @@ export const REALTIME_RECORDING_CONSENT_KEY = 'mj.realtimeVoice.recordingConsent
 // and this service stays component-free (it must stay importable in plain-node tests).
 LoadOpenAIRealtimeClient();
 LoadGeminiRealtimeClient();
+LoadGeminiEnterpriseRealtimeClient();
 LoadElevenLabsRealtimeClient();
 LoadAssemblyAIRealtimeClient();
 LoadxAIRealtimeClient();
 LoadHuggingFaceRealtimeClient();
+/**
+ * A registry row's surface placement. A row whose `UIConfig` is not valid JSON places its surface as a row without one
+ * does, so one bad row never costs the session its other channels.
+ */
+function readRowSurfacePlacement(row) {
+    try {
+        return ReadChannelSurfacePlacement(row.UIConfigObject);
+    }
+    catch {
+        console.warn(`[RealtimeSession] Channel '${row.Name}' has a UIConfig that is not valid JSON; its surface starts on its tab.`);
+        return DEFAULT_CHANNEL_SURFACE_PLACEMENT;
+    }
+}
+/** The same, for a row read over GraphQL, whose `UIConfig` arrives as the column's JSON text. */
+function readUIConfigTextSurfacePlacement(name, uiConfig) {
+    if (!uiConfig) {
+        return ReadChannelSurfacePlacement(null);
+    }
+    try {
+        return ReadChannelSurfacePlacement(JSON.parse(uiConfig));
+    }
+    catch {
+        console.warn(`[RealtimeSession] Channel '${name}' has a UIConfig that is not valid JSON; its surface starts on its tab.`);
+        return DEFAULT_CHANNEL_SURFACE_PLACEMENT;
+    }
+}
 /**
  * Converts a {@link RealtimeTrackDescriptor} to its JSON form for the session-config bag.
  *
@@ -67,6 +138,37 @@ function trackKeyFromJSON(raw) {
     }
     return `${direction}:${modality}`;
 }
+/** Whether a surface client tool handler's result is an object whose `Success` is `false`. */
+function reportsFailure(result) {
+    return typeof result === 'object' && result !== null && 'Success' in result && result.Success === false;
+}
+/** The failed result's `ErrorMessage` when it is text that is not blank, else `'Tool failed'`. */
+function failureMessage(result) {
+    const message = result.ErrorMessage;
+    return typeof message === 'string' && message.trim() ? message : 'Tool failed';
+}
+/**
+ * The `DOMException` name for each way the controller can fail to start the microphone, so a host that
+ * tells a denied microphone apart (`error.name === 'NotAllowedError'`) works the same with or without one.
+ */
+const MICROPHONE_ERROR_NAMES = {
+    denied: 'NotAllowedError',
+    'not-found': 'NotFoundError',
+    'in-use': 'NotReadableError',
+    unsupported: 'NotSupportedError',
+    error: 'Error',
+};
+/** What the user is told when the call's policy refuses a capture. */
+const CAPTURE_WORDING = {
+    camera: { NotInCall: 'The camera is not part of this call.', NotAllowed: 'This call cannot show the agent your camera' },
+    screen: { NotInCall: 'Screen sharing is not part of this call.', NotAllowed: 'This call cannot show the agent your screen' },
+};
+/** The error a failed microphone start reports, named as `getUserMedia` would have named it. */
+function microphoneStartError(reason, message) {
+    const error = new Error(message);
+    error.name = MICROPHONE_ERROR_NAMES[reason];
+    return error;
+}
 /**
  * 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
@@ -92,14 +194,15 @@ function trackKeyFromJSON(raw) {
 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;
         // ── Reactive UI state ──────────────────────────────────────────────────────
         this._connectionState$ = new BehaviorSubject('closed');
+        this._resuming$ = new BehaviorSubject(false);
         this._captions$ = new BehaviorSubject([]);
         this._active$ = new BehaviorSubject(false);
         this._delegationProgress$ = new Subject();
@@ -109,6 +212,7 @@ export class RealtimeSessionRuntime {
         this._agentName$ = new BehaviorSubject('Sage');
         this._modelName$ = new BehaviorSubject(null);
         this._minimized$ = new BehaviorSubject(false);
+        this._savingRecording$ = new BehaviorSubject(false);
         this._activeChannels$ = new BehaviorSubject([]);
         this._channelFocus$ = new Subject();
         // ─── Generic session-lifecycle events (consumed by RealtimeSessionsAdapter to
@@ -122,6 +226,16 @@ export class RealtimeSessionRuntime {
         this._channelActivity$ = new Subject();
         /** Current connection / turn state. */
         this.ConnectionState$ = this._connectionState$.asObservable();
+        /**
+         * Whether the call is resuming: moving to a new connection with its provider mid-call. `true` from a `'connecting'` the
+         * driver reports while the call is live, until the call is live again (`'listening'`, `'speaking'` or `'thinking'`),
+         * fails (`'error'`) or ends (`'closed'`). A call's first connect is not a resume, so it is `false` until the call has
+         * been live, and outside a call. Gemini Live resumes when Google ends a connection (`goAway`) and after a dropped
+         * socket, and the agent's video can stop for a few seconds meanwhile: a host can show that as a pause rather than as
+         * the agent leaving. It changes before {@link ConnectionState$} does, so a resume's `'connecting'` arrives with it
+         * already `true`.
+         */
+        this.Resuming$ = this._resuming$.asObservable();
         /** Live captions for both sides of the conversation. */
         this.Captions$ = this._captions$.asObservable();
         /** True while a session is open (mic button active, overlay shown). */
@@ -158,6 +272,15 @@ export class RealtimeSessionRuntime {
          * pure presentation state, reset to `false` at session start and teardown.
          */
         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 — 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();
         /**
          * The session's ACTIVE interactive-channel plugins, resolved from the `MJ: AI Agent
          * Channels` registry at session start (one instance per session, per channel). Emits
@@ -165,6 +288,57 @@ export class RealtimeSessionRuntime {
          * one surface tab per plugin — it never knows any concrete channel type.
          */
         this.ActiveChannels$ = this._activeChannels$.asObservable();
+        this._videoSources$ = new BehaviorSubject([]);
+        /**
+         * The video sources the agent is perceiving or could perceive right now (a whiteboard, a remote browser, a
+         * shared screen), with whether each is on and whether its frames are reaching the model. Empty when no
+         * session is live or nothing has offered a frame source. This is what the "agent can see" control renders;
+         * toggle one with {@link SetVideoSourceEnabled}.
+         */
+        this.VideoSources$ = this._videoSources$.asObservable();
+        this._captures$ = new BehaviorSubject(REALTIME_CAPTURES_OFF);
+        /**
+         * The user's camera and screen share: off, starting, on (with the stream to show the user) or failed (with the
+         * reason). Both off outside a session. Start and stop them with {@link StartCamera}, {@link StartScreenShare},
+         * {@link StopCamera} and {@link StopScreenShare}; while one is on, it is also a source on {@link VideoSources$}.
+         */
+        this.Captures$ = this._captures$.asObservable();
+        this._captureOffers$ = new BehaviorSubject(REALTIME_CAPTURE_OFFERS_NONE);
+        /**
+         * Which captures the call offers, now and on every change. A capture is offered while the call is connected, the model
+         * takes inbound video, the host can open it (a camera controller; screen sharing) and the call's policy admits it (its
+         * channel is in the call and may show the agent pixels). A host shows its Camera and Share controls from this. Neither
+         * is offered outside a call.
+         */
+        this.CaptureOffers$ = this._captureOffers$.asObservable();
+        this._microphone$ = new BehaviorSubject(REALTIME_MICROPHONE_NONE);
+        /**
+         * The call's microphone, now and on every change: the one in use and the ones the user can move it to with
+         * {@link SwitchMicrophone}, as the host's camera-and-microphone controller lists them. Offered from the moment the call
+         * connects until it ends, and kept current as devices come and go. When the call loses its microphone (the one in use
+         * fails and so does the fallback to the default, or the last one goes away), its `Failure` says why: the agent hears
+         * nothing until the user picks a microphone, which opens it again. {@link REALTIME_MICROPHONE_NONE} outside a call and
+         * on a host without a controller, which opens the microphone itself (`IRealtimeMediaHost.AcquireMicrophone`).
+         */
+        this.Microphone$ = this._microphone$.asObservable();
+        this._agentVideo$ = new BehaviorSubject(null);
+        /**
+         * The agent's video (an avatar) while the model sends it: a live stream, or a player that owns the `<video>` element.
+         * `null` until the video arrives, for a model that sends none, and outside a call. The driver hands it over once it is
+         * live, and a newer one replaces it. A host shows it with `AttachVideoSource`; a channel that sinks outbound video
+         * follows it through its context, and counts as used once it arrives, so the host shows that channel's surface.
+         */
+        this.AgentVideo$ = this._agentVideo$.asObservable();
+        this._avatarNotice$ = new BehaviorSubject(null);
+        /**
+         * Why the call shows no avatar the agent asked for: set once per call, after it connects, when the model renders none,
+         * the persona has no face for it, the app shows no agent video (`host`) or the browser can't play it (`browser`); with
+         * no `Reason` when the mint gave one this version doesn't know, such as a newer server's. `null` when there is nothing
+         * to say (no avatar asked for, the avatar shows, or the mint reported no status) and after the call ends. A provider
+         * resume inside the call does not set it again. A host turns the reason into words once, for example "Audio only: this
+         * voice model can't show an avatar".
+         */
+        this.AvatarNotice$ = this._avatarNotice$.asObservable();
         /**
          * Channel requests to enter / leave the FOCUS layout (see
          * {@link RealtimeChannelFocusEvent}). Fired when a plugin calls its host context's
@@ -208,7 +382,11 @@ export class RealtimeSessionRuntime {
          */
         /** Conversation id the SERVER created for this session (null when the host supplied one). */
         this.createdConversationId = null;
-        /** The session's conversation id (supplied or server-created). */
+        /**
+         * The session's conversation id (supplied or server-created). While a start's mint runs, the
+         * conversation the start asked for; null when it asked the server to create one. Null after
+         * teardown.
+         */
         this.sessionConversationId = null;
         /** First final user utterance of the live session (the naming seed). */
         this.firstUserTranscript = null;
@@ -219,8 +397,28 @@ export class RealtimeSessionRuntime {
         // ── Session internals ──────────────────────────────────────────────────────
         /** The provider-direct realtime client driving the live session (ClassFactory-resolved). */
         this.client = null;
-        /** The mic capture stream — acquired here (permission UX) and handed to the client. */
+        /**
+         * The mic capture stream — acquired here (permission UX) and handed to the client. A microphone the controller opens
+         * again after the call lost one replaces it.
+         */
         this.localStream = null;
+        /**
+         * Whether the user muted the call's microphone, as {@link ToggleMute} last reported it. While the call has no microphone
+         * track there is nothing to mute, and a microphone opened again after the call lost one starts this way.
+         */
+        this.microphoneMuted = false;
+        /** The host's camera-and-microphone controller for this session, when the host offers one. */
+        this.localMedia = null;
+        /** Follows the controller's microphone, so a swapped-in track or a reopened microphone reaches the driver and the recorder. */
+        this.localMediaSubscription = null;
+        /**
+         * Whether the call offers its microphone for switching ({@link Microphone$}, {@link SwitchMicrophone}): from the moment
+         * the client is connected until the call ends. Not before: a driver still connecting may have bound the old track.
+         */
+        this.microphoneOffered = false;
+        /** The live session's camera and screen share; created once the client is connected. */
+        this.captures = null;
+        this.capturesSubscription = null;
         this.agentSessionId = null;
         /**
          * The application the active session runs in (sources the server-side app config cascade +
@@ -246,16 +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;
-        /** 0-based index of the next recording shard to upload. */
-        this.segmentIndex = 0;
+        /** 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;
+        /**
+         * True once a drain ran with a transport; the drain then does nothing until a recording ends and
+         * re-arms it ({@link rearmPendingShardDrain}).
+         */
+        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
@@ -266,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}.
@@ -310,6 +553,11 @@ export class RealtimeSessionRuntime {
         this.pendingUsageInput = 0;
         /** Accumulated output-token delta since the last flush. */
         this.pendingUsageOutput = 0;
+        /**
+         * Accumulated per-modality usage since the last flush (input and output detail blocks, avatar
+         * video seconds included), relayed in full; `null` when no update carried any.
+         */
+        this.pendingUsageDetails = null;
         /** Pending debounced usage flush; also force-flushed at teardown. */
         this.usageFlushTimer = null;
         /** Active push-status subscription that feeds delegation progress; cleared on teardown. */
@@ -352,7 +600,20 @@ export class RealtimeSessionRuntime {
          */
         this.teardownInFlight = null;
         /**
-         * Why the last session start failed, or `null` when none has.
+         * 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
+         * nothing.
+         *
+         * The host gets one release per opening, after the opening returns. A release while the microphone is still
+         * opening undoes nothing: the React Native host puts iOS into the call audio category inside `AcquireMicrophone`,
+         * after the permission prompt. So {@link runTeardown} releases an opening that has returned and leaves one still
+         * opening to its start, which releases it once it returns ({@link unwindAbandonedStart}), unless a newer start has
+         * opened the microphone since; that start's own end releases it. Whoever releases clears this first, so no
+         * opening is released twice.
+         */
+        this.microphoneLease = null;
+        /**
+         * Why the latest session start failed, or `null` when it has not. Each start clears it ({@link beginSessionStart}).
          *
          * The runtime reports failure as `'error'` on {@link ConnectionState$}, which is enough to show
          * *that* something went wrong but not *what* — and the difference matters at exactly one point:
@@ -361,6 +622,11 @@ export class RealtimeSessionRuntime {
          * runtime's own try/catch, so the host never sees that rejection itself.
          */
         this.lastStartError = null;
+        /**
+         * The fatal error the call's client reported, or `null` when it has reported none. Each start clears it
+         * ({@link beginSessionStart}). See {@link LastSessionError}.
+         */
+        this.lastSessionError = null;
         /**
          * Pending DEBOUNCED channel-state saves, keyed by channel name. Each entry keeps the
          * LATEST serialized state plus the session id captured while the session was live —
@@ -377,13 +643,102 @@ export class RealtimeSessionRuntime {
          */
         this.usedChannelNames = new Set();
         this._provider = null;
+        this._launcher = new DefaultRealtimeSessionLauncher();
+        /**
+         * Loads channel code on demand. Called, with the `ClientPluginClass` keys of every channel about to be
+         * resolved (the registry's rows plus the host's declarations), after the registry is read and before any
+         * plugin is built — so a host can register a heavy channel's class only when the session could use it.
+         * It must resolve once the classes it knows are registered; a rejection is logged, never fatal.
+         */
+        this.ChannelClassLoader = null;
+        // ── Session events (server → this session's client) ────────────────────────
+        this._sessionEvents$ = new Subject();
+        /**
+         * Every event the server publishes to THIS session, for the session's life (identity verification
+         * today; apps add their own types). Hot, with no replay — subscribe before the session starts, once,
+         * and it keeps working across sessions. The runtime has already acted on the events it understands
+         * (see {@link handleIdentityVerified}) by the time one reaches here; this stream is for the host UI.
+         *
+         * Silent when the session's provider has no subscription transport (see {@link createSessionEventSource}).
+         */
+        this.SessionEvents$ = this._sessionEvents$.asObservable();
+        /** Keeps the live session's event stream open; null between sessions. */
+        this.sessionEventHub = null;
+        /** Per-type handlers the runtime runs (before publishing on {@link SessionEvents$}) for events it understands. */
+        this.sessionEventHandlers = new Map([
+            ['identity.verified', (event) => this.handleIdentityVerified(event)]
+        ]);
+        /**
+         * What the agent should SAY the moment the user's identity is verified, or `null` (the default) to
+         * say nothing — the agent is still told, silently, through a context note. A string is used as the
+         * instruction verbatim; a function receives the verified payload (e.g. to greet by name) and returns
+         * the instruction, or `null` to stay silent for this verification.
+         */
+        this.IdentityVerifiedSpokenResponse = null;
+        this.clientDeadline = new ClientSessionDeadline();
+        // ── Interactive channels (registry-driven + host-declared plugins) ─────────
+        //
+        // A session's channels come from two places — the `MJ: AI Agent Channels` registry and the channels
+        // the host declares — and pass through three stages:
+        //
+        //   1. PREPARE  (before mint)  construct the plugins, read their descriptors, report them as
+        //                              candidates, and work out the scope the browser can decide alone.
+        //   2. MINT                    the server scopes the candidates with the agent/app cascade and the
+        //                              registry's kill switch, and returns the resolved policy.
+        //   3. ACTIVATE (after mint)   initialize exactly the policy's channels: `open-on-start`/`headless`
+        //                              ones mount now, `on-demand` ones wait to be opened through ContextTool.
+        //
+        // Nothing is initialized before the policy is known, so a channel the server vetoes never runs.
+        /** Whether the channel catalog note still has to be sent (see {@link flushChannelCatalogNote}). */
+        this.catalogNotePending = false;
+        /** Plugins resolved for the current start but not yet initialized. Consumed by {@link activateChannels}. */
+        this.preparedChannels = [];
+        /** The scope the browser resolves on its own — the fallback when no server policy comes back. */
+        this.localChannelScope = null;
+        /** `on-demand` channels that are in the session but not opened yet (initialized only when opened). */
+        this.advertisedChannels = [];
+        /** What the policy resolved for each in-session channel, keyed by normalized channel key. */
+        this.resolvedChannels = new Map();
+        /** The prior session's saved channel states, kept so an `on-demand` channel opened later is restored too. */
+        this.priorChannelStates = {};
+        /** The app/static client-tool tiers the server resolved for this session. */
+        this.sessionClientTools = null;
+        /** Validates and routes channel-addressed `ContextTool` calls. */
+        this.channelDispatcher = new ChannelActionDispatcher({
+            FindChannel: (key) => this.findDispatchableChannel(key),
+            ListChannelKeys: () => this.listAddressableChannelKeys(),
+            ActivateChannel: (plugin) => this.mountAdvertisedChannel(plugin),
+        });
+        /** Where the user's per-channel "how much can the agent see" choices are kept. Replace with {@link SetExposurePreferences}. */
+        this.exposurePreferences = new UserSettingsExposurePreferences(() => this.canPersistUserSettings());
+        /** The channel whose surface the user is looking at, kept so it applies to an arbiter created after it was set. */
+        this.focusedChannelKey = null;
+        this.stopWatchingVideoSources = null;
         /**
          * Host registry of surface CLIENT TOOLS (Name → handler), fed by the host (Explorer) from the
-         * active surface's `SetAgentClientTools`. The headless ClientContextChannel's `ContextTool` proxy
-         * executes against this via {@link executeAppClientTool}. Keys are lower-cased for case-insensitive
-         * model-supplied action names.
+         * active surface's `SetAgentClientTools` and from its always-on globals. The headless
+         * ClientContextChannel's `ContextTool` proxy executes against this via {@link executeAppClientTool}.
+         * Owner-keyed — see {@link AppClientToolRegistry}.
          */
-        this.appClientToolHandlers = new Map();
+        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() {
+        return this._savingRecording$.value;
+    }
+    /** Synchronous access to {@link AvatarNotice$}'s current value. */
+    get CurrentAvatarNotice() {
+        return this._avatarNotice$.value;
     }
     /** Synchronous access to the session's active interactive-channel plugins. */
     get ActiveChannels() {
@@ -444,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
@@ -480,10 +847,113 @@ export class RealtimeSessionRuntime {
     set Provider(value) {
         this._provider = value;
     }
+    /**
+     * How this runtime mints a session — the stock `StartRealtimeClientSession` mutation unless a host
+     * installs its own {@link IRealtimeSessionLauncher} (a guest-session exchange, a deployment-specific
+     * mutation). Everything after the mint — channel scoping, the driver, transcripts, teardown — is
+     * unchanged. Assign `null` to restore the default.
+     */
+    get Launcher() {
+        return this._launcher;
+    }
+    set Launcher(value) {
+        this._launcher = value ?? new DefaultRealtimeSessionLauncher();
+    }
+    /**
+     * The client's copy of the session's absolute deadline (`null` when none is known). A host that
+     * knows the session's cap at start sets it with {@link SetSessionDeadline}; verification extends it
+     * from the server's `identity.verified` payload. The SERVER enforces the real deadline — this exists
+     * so the host can end the call gracefully first and show a countdown. It only ever moves later by
+     * the server's word, so nothing a client does can extend the real one.
+     */
+    get SessionDeadline$() {
+        return this.clientDeadline.Deadline$;
+    }
+    /** Synchronous access to {@link SessionDeadline$}. */
+    get SessionDeadline() {
+        return this.clientDeadline.Value;
+    }
+    /** Sets the baseline deadline a host knows at session start (`null` clears). See {@link SessionDeadline$}. */
+    SetSessionDeadline(deadline) {
+        this.clientDeadline.Set(deadline);
+    }
+    /**
+     * Builds the transport that reads the session's events. The default rides the session's GraphQL
+     * provider; it returns `null` — "no session events here" — for a provider with no subscription
+     * support (a test double, a host on another transport), which the runtime tolerates. Override to
+     * supply another transport.
+     */
+    createSessionEventSource() {
+        const provider = this.Provider;
+        if (!provider || typeof provider.Subscribe !== 'function') {
+            return null;
+        }
+        return new GraphQLRealtimeSessionClient(provider);
+    }
+    /** Opens the live session's event stream. Best-effort: never disturbs the call. */
+    startSessionEvents(agentSessionId) {
+        this.stopSessionEvents();
+        try {
+            const source = this.createSessionEventSource();
+            if (!source) {
+                return;
+            }
+            this.sessionEventHub = new RealtimeSessionEventHub(source, (event) => this.routeSessionEvent(agentSessionId, event));
+            this.sessionEventHub.Start(agentSessionId);
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Could not start the session event stream:', error);
+        }
+    }
+    stopSessionEvents() {
+        this.sessionEventHub?.Stop();
+        this.sessionEventHub = null;
+    }
+    /** Routes one event to its per-type handler, then publishes it. An event for another session is dropped. */
+    routeSessionEvent(expectedSessionId, event) {
+        if (event.AgentSessionID !== expectedSessionId || this.agentSessionId !== expectedSessionId) {
+            console.warn(`[RealtimeSession] Dropped a '${event.Type}' event addressed to another session.`);
+            return;
+        }
+        try {
+            this.sessionEventHandlers.get(event.Type)?.(event);
+        }
+        catch (error) {
+            console.error(`[RealtimeSession] Handling the '${event.Type}' session event failed:`, error);
+        }
+        this._sessionEvents$.next(event);
+    }
+    /**
+     * `identity.verified`: keep the client's deadline in step with the server's, tell the model — as a
+     * silent, structured note — who it is now talking to, and, when the host configured it, have it say
+     * something about that. The payload is validated again here (it crossed a wire); the name rides as
+     * JSON so user-entered text can never break out of the note's frame.
+     */
+    handleIdentityVerified(event) {
+        if (event.Type !== 'identity.verified' || !IsIdentityVerifiedEventPayload(event.Payload)) {
+            console.warn('[RealtimeSession] Ignored a malformed identity.verified event.');
+            return;
+        }
+        const payload = event.Payload;
+        this.clientDeadline.Extend(payload.MaxSessionDeadlineIso);
+        this.SendContextNote(`[identity] verified ${JSON.stringify({ email: payload.VerifiedEmail, name: payload.VerifiedName, method: payload.Method })} ` +
+            '(background context — the user has proven they control this email address; treat them as verified. Do not read this note aloud.)');
+        const spoken = typeof this.IdentityVerifiedSpokenResponse === 'function' ? this.IdentityVerifiedSpokenResponse(payload) : this.IdentityVerifiedSpokenResponse;
+        if (spoken && spoken.trim().length > 0 && this.client && this.isSessionLive()) {
+            this.requestChannelSpokenResponse(spoken.trim());
+        }
+    }
     /** True when a session is currently open. */
     get IsActive() {
         return this._active$.value;
     }
+    /**
+     * True when a session is open or starting for `conversationId`. Ids are compared without
+     * regard to case.
+     */
+    IsActiveFor(conversationId) {
+        return this.IsActive && conversationId != null && UUIDsEqual(this.sessionConversationId, conversationId);
+    }
     /**
      * Start a client-direct voice session fronting `targetAgentId`.
      *
@@ -514,38 +984,62 @@ 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,
      *   the server-side Media channel resolves THIS collection as the agent's media kit for the session,
      *   taking precedence over the agent's `DefaultMediaCollectionID`. The server UUID-validates it
      *   (malformed ⇒ ignored, the agent default applies). Omit/`null` to use the agent default kit.
+     * @param applicationId Optional application the session runs in (sources the app config cascade,
+     *   including `Application.AgentSettings.Realtime.Channels`).
+     * @param appContext Optional live app-context snapshot injected into the companion prompt at mint.
+     * @param options Optional per-start extras — chiefly the channels the HOST brings
+     *   ({@link RealtimeSessionStartOptions.HostChannels}), the way a connect-only embed with no
+     *   registry gets channels at all, and the fork the session starts on
+     *   ({@link RealtimeSessionStartOptions.ConversationBranchID}; omitted is Main, where its transcript is written).
      */
-    async StartRealtimeSession(targetAgentId, conversationId, lastSessionId, agentName, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, mediaCollectionId, applicationId, appContext) {
+    async StartRealtimeSession(targetAgentId, conversationId, lastSessionId, agentName, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, mediaCollectionId, applicationId, appContext, options) {
         if (this.IsActive) {
             return; // a session is already running — ignore duplicate starts
         }
         const consent = this.beginSessionStart({ agentName, recordingConsent, applicationId, appContext });
-        // Captured BEFORE startChannels so the mint carries exactly the snapshot the prologue
+        this.sessionConversationId = conversationId ?? null;
+        // A teardown while the channels are prepared or the mint runs bumps this; see the checks below.
+        const generation = this.startGeneration;
+        // Captured BEFORE the channels are prepared so the mint carries exactly the snapshot the prologue
         // resolved, whatever a channel plugin may push in the meantime.
         const effectiveAppContext = this._appContext$.value;
         let session;
         try {
-            // Resolve + initialize the interactive-channel plugins FIRST: their client-executed
-            // tool sets must be declared to the realtime model at session mint.
-            const allClientTools = [...(clientTools ?? []), ...(await this.startChannels())];
-            session = await this.mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, allClientTools, coAgentId, configOverridesJson, consent, this.recordingStartedAtIso, mediaCollectionId, this.applicationId, effectiveAppContext);
+            // Resolve the interactive-channel plugins FIRST (constructed, not started): the tools of the
+            // channels mounted with the session must be declared to the realtime model at mint, and the
+            // server needs the candidates to scope them. Nothing is initialized until the policy is known.
+            const scope = await this.prepareChannelScope(options?.HostChannels);
+            const allClientTools = [...(clientTools ?? []), ...scope.NativeTools];
+            session = await this.mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, allClientTools, coAgentId, configOverridesJson, consent, this.recordingStartedAtIso, mediaCollectionId, this.applicationId, effectiveAppContext, scope.CandidatesJson, scope.ShowsAgentVideo, options?.ConversationBranchID ?? null);
         }
         catch (error) {
+            // An ended or replaced start only logs its failure: the error state and the teardown belong
+            // to the session that is current now, which a newer start may own.
+            if (this.startGeneration !== generation) {
+                console.error('[RealtimeSession] A start that was already ended failed:', error);
+                return;
+            }
             await this.failSessionStart(error);
             return;
         }
+        // The host ended the start while the mint ran. That teardown had no session id to close, so
+        // close the minted row here, and touch no shared state: a newer start may already own it.
+        if (this.startGeneration !== generation) {
+            await this.closeServerSession(session.AgentSessionId);
+            return;
+        }
         if (!this.hostCanUseProvider(session.Provider)) {
             await this.abortUnusableSession(session);
             return;
         }
-        await this.runMintedSession(session, conversationId ?? null, consent);
+        await this.runMintedSession(session, conversationId ?? null, consent, options?.CameraCheck === true);
     }
     /**
      * Declares which provider keys this host can actually carry audio for.
@@ -581,7 +1075,7 @@ export class RealtimeSessionRuntime {
         // published them on ActiveChannels$; skipping teardown would leave them undisposed, their tool
         // handlers registered, and their subscriptions live until the next start replaced them.
         this.agentSessionId = session.AgentSessionId ?? this.agentSessionId;
-        this._connectionState$.next('error');
+        this.setConnectionState('error');
         await this.teardown(true);
     }
     /**
@@ -600,7 +1094,8 @@ export class RealtimeSessionRuntime {
      * owns that half too.
      *
      * @param result The minted session — the same ten fields the `StartRealtimeClientSession`
-     *   mutation returns. `EphemeralToken` and `Provider` are what actually open the call.
+     *   mutation returns. `EphemeralToken` and `Provider` are what actually open the call; a relay
+     *   session opens with its `Transport` and `RelayUrl` instead, so a host must pass those on.
      * @param options Host-side inputs the result cannot carry; see {@link RealtimeSessionRunOptions}.
      *   Every field defaults exactly as its {@link StartRealtimeSession} counterpart does.
      */
@@ -614,16 +1109,20 @@ export class RealtimeSessionRuntime {
             return;
         }
         const consent = this.beginSessionStart(effectiveOptions);
-        await this.runMintedSession(result, effectiveOptions.conversationId ?? null, consent);
+        await this.runMintedSession(result, effectiveOptions.conversationId ?? null, consent, false);
     }
     /**
-     * Start prologue shared by both entry points: 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 reports to the server and
-     * the run half uses to decide whether to record.
+     * 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
+     * reports to the server and the run half uses to decide whether to record.
      */
     beginSessionStart(options) {
+        // Before this start publishes anything: hosts read LastStartError as this start's states arrive,
+        // so from the first of them it must describe this start, not an earlier one.
+        this.lastStartError = null;
+        this.lastSessionError = null;
         // App awareness (Move 1/3/4): the application the session runs in (sources the app config
         // cascade + RelevantAgents → allowed-agent union) and the live app-context snapshot injected
         // into the companion prompt at mint. Stored so the ClientContextChannel can stream subsequent
@@ -641,7 +1140,10 @@ export class RealtimeSessionRuntime {
         }
         this.resetState();
         this._active$.next(true);
-        this._connectionState$.next('connecting');
+        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();
@@ -651,12 +1153,18 @@ export class RealtimeSessionRuntime {
     /**
      * The RUN half of a session start, shared by both entry points: consume the minted result, open
      * 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.
+     * 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}).
      */
-    async runMintedSession(session, inputConversationId, consent) {
+    async runMintedSession(session, inputConversationId, consent, cameraCheck) {
         // Captured up front: every await below is a window in which the host can end the session.
         const generation = this.startGeneration;
         try {
+            // Mount the channels the resolved policy puts in the session. Deliberately BEFORE the session
+            // id is adopted: `ActiveChannels$` consumers (the sessions adapter) treat an emission that
+            // arrives while no session id is set as the INITIAL set, whose opens they synthesize from
+            // `SessionStarted$` — activating after the id is set would announce every channel twice.
+            this.applySessionClientPolicy(session);
             this.agentSessionId = session.AgentSessionId;
             // A null input conversationId means the SERVER created a fresh conversation for
             // this session — track it so the host can fold it into the cached list, select
@@ -671,20 +1179,39 @@ export class RealtimeSessionRuntime {
             this.applyPriorChannelStates(session.PriorChannelStatesJson);
             const client = this.createRealtimeClient(session.Provider);
             this.client = client;
+            this.watchVideoSources(client);
             this.wireClientHandlers(client);
             // Everything past here awaits on hardware and the network, during which the host may end the
-            // session. Each await is followed by a staleness check so an abandoned start releases what it
-            // just acquired instead of leaving a live microphone and a live call behind it.
-            this.localStream = await this.mediaHost.AcquireMicrophone();
+            // session. Each await is followed by a staleness check, before any failure is reported, so an
+            // abandoned start releases what it just acquired instead of leaving a live microphone and a live
+            // call behind it, and reports nothing to a host that has ended the call.
+            const lease = { Opening: true };
+            this.microphoneLease = lease;
+            const microphone = await this.openMicrophone().finally(() => {
+                lease.Opening = false;
+            });
+            this.localStream = microphone.Stream;
             if (this.startGeneration !== generation) {
-                await this.unwindAbandonedStart(session, client);
+                await this.unwindAbandonedStart(session, client, lease);
                 return;
             }
-            await client.Connect(this.BuildClientConfig(session), this.localStream);
+            if (microphone.Error) {
+                throw microphone.Error;
+            }
+            const clientConfig = this.BuildClientConfig(session);
+            const connectError = await this.connectClient(client, clientConfig, microphone.Stream);
             if (this.startGeneration !== generation) {
-                await this.unwindAbandonedStart(session, client);
+                await this.unwindAbandonedStart(session, client, lease);
                 return;
             }
+            if (connectError) {
+                throw connectError;
+            }
+            // Tracks are negotiated now, so a capture can tell whether the model takes video, and the call whether it shows
+            // the avatar its agent asked for. The driver holds the microphone now, so the user may switch it.
+            this.openCaptures(client, cameraCheck);
+            this.offerMicrophone();
+            this.publishAvatarNotice(session, clientConfig, client);
             // Notify active channels that the session client is connected and tracks are established
             for (const channel of this._activeChannels$.value) {
                 try {
@@ -694,6 +1221,10 @@ export class RealtimeSessionRuntime {
                     console.error(`[RealtimeSession] Error in channel '${channel.ChannelName}' OnSessionStarted:`, err);
                 }
             }
+            // Tell the model which channels exist and how to use them, from the channels' own descriptors —
+            // as soon as the control channel is usable (which may be right now, or a moment after Connect).
+            this.catalogNotePending = true;
+            this.flushChannelCatalogNote();
             // Start browser-side recording (mic + agent mix) when consented. Best-effort: an
             // unsupported browser / missing remote stream degrades gracefully (mic-only or off)
             // and never blocks the call. The remote stream may still be null here (the WebRTC
@@ -718,6 +1249,8 @@ export class RealtimeSessionRuntime {
             // SessionsObserver bridge. Emitting AFTER Connect() guarantees both that
             // agentSessionId is set (line ~468) AND the realtime client is connected,
             // so consumers can act on it without re-checking either condition.
+            // The session's own event stream (identity verification, app events) stays open for its life.
+            this.startSessionEvents(this.agentSessionId);
             this._sessionStarted$.next({
                 sessionId: this.agentSessionId,
                 channelNames: this._activeChannels$.value.map(c => c.ChannelName),
@@ -730,18 +1263,42 @@ export class RealtimeSessionRuntime {
             await this.failSessionStart(error);
         }
     }
+    /**
+     * Tells the host, once per call, why it shows no avatar ({@link AvatarNotice$}): from the mint's status, whether this
+     * session asked for the agent's video, and whether that track is live now that the call is connected.
+     */
+    publishAvatarNotice(session, config, client) {
+        const notice = ResolveAvatarNotice(ParseRealtimeAvatarStatus(session.AvatarStatusJson), RequestsAgentVideo(config), client.IsTrackEstablished('video', 'outbound'));
+        if (notice) {
+            this._avatarNotice$.next(notice);
+        }
+    }
     /**
      * Releases everything a start acquired after the host had already ended the session.
      *
      * Reached only when {@link teardown} ran while this start was awaiting the microphone or the
-     * provider connection. Teardown found nothing to release because nothing existed yet, so this
-     * start owns the cleanup: stop the microphone, close the provider connection, and close the
-     * server-side session row that the mint created.
+     * provider connection, whether that wait then succeeded or failed: the host has ended the call,
+     * so a failure there is not reported. Teardown could not release what did not exist yet, so this
+     * start owns the cleanup: stop the microphone, hand it back to the host when teardown left that
+     * to it ({@link microphoneLease}), close the provider connection, and close the server-side
+     * session row that the mint created when no teardown has closed it or is closing it.
+     *
+     * @param lease This start's opening of the microphone.
      */
-    async unwindAbandonedStart(session, client) {
+    async unwindAbandonedStart(session, client, lease) {
         console.warn('[RealtimeSession] Session was ended while starting — releasing the partial session.');
+        this.closeCaptures();
+        this.closeLocalMedia();
         this.localStream?.getTracks().forEach(t => t.stop());
         this.localStream = null;
+        this.microphoneMuted = false;
+        // Teardown left the release to this start when the microphone was still opening. A cleared or
+        // replaced lease means teardown already released it, or a newer start has opened the microphone
+        // since and its own end releases it.
+        if (this.microphoneLease === lease) {
+            this.microphoneLease = null;
+            await this.releaseMicrophone();
+        }
         try {
             await client.Disconnect();
         }
@@ -751,27 +1308,321 @@ export class RealtimeSessionRuntime {
         // Only clear the shared slots when they still point at THIS attempt — a newer start may
         // already have replaced them.
         if (this.client === client) {
+            this.unwatchVideoSources();
+            this.clearAgentVideo();
             this.client = null;
         }
-        // Close the server session only if teardown has NOT already done so. It nulls `agentSessionId`
-        // after closing, so a still-matching id means this attempt still owns the row; a cleared one
-        // means the teardown that invalidated this start already closed it, and closing again would
-        // send a second `CloseAgentSession` for one session.
-        if (session.AgentSessionId && this.agentSessionId === session.AgentSessionId) {
+        // Close the server session only if no teardown has closed it or is closing it. Teardown nulls
+        // `agentSessionId` after closing, so a cleared id means the teardown that invalidated this start
+        // already closed it. A teardown still running closes it itself and then reports the end on
+        // `SessionEnded$`: closing it here as well would send a second `CloseAgentSession` for one
+        // session, and clearing the id would leave that teardown no session to report.
+        if (session.AgentSessionId && this.agentSessionId === session.AgentSessionId && !this.teardownInFlight) {
             this.agentSessionId = null;
             await this.closeServerSession(session.AgentSessionId);
         }
     }
     /**
-     * Why the last session start failed, or `null` when the last start succeeded or none has run.
+     * Opens the user's microphone: through the host's controller when it offers one, otherwise through
+     * {@link IRealtimeMediaHost.AcquireMicrophone}. A failure is returned rather than thrown, so the caller can
+     * first check whether the start was abandoned meanwhile (a teardown disposes the controller, which fails a
+     * start still in flight) and unwind quietly instead of reporting an error nobody is waiting for.
+     */
+    async openMicrophone() {
+        const controller = this.mediaHost.CreateLocalMediaController?.() ?? null;
+        if (!controller) {
+            try {
+                return { Stream: await this.mediaHost.AcquireMicrophone(), Error: null };
+            }
+            catch (error) {
+                return { Stream: null, Error: error instanceof Error ? error : new Error(String(error)) };
+            }
+        }
+        this.localMedia = controller;
+        const started = await controller.Start('microphone');
+        if (started.Status === 'failed') {
+            return { Stream: null, Error: microphoneStartError(started.Reason, started.Message) };
+        }
+        this.followMicrophone(controller, started.Stream);
+        return { Stream: started.Stream, Error: null };
+    }
+    /**
+     * Opens the provider connection. As with {@link openMicrophone}, a failure is returned rather than thrown, so the
+     * caller can first check whether the start was abandoned meanwhile and unwind quietly instead of reporting an error
+     * nobody is waiting for: a teardown disconnects the client, which with most drivers fails a connection still opening.
+     */
+    async connectClient(client, config, microphone) {
+        try {
+            await client.Connect(config, microphone);
+            return null;
+        }
+        catch (error) {
+            return error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    /**
+     * Moves the driver and the recorder onto the call's microphone whenever the controller gives it a new track. A device
+     * switch, or a lost device replaced by the default, swaps a track into the same stream, and the controller carries the
+     * old track's mute over. A microphone opened again after the call lost one comes in a new stream: its track takes the
+     * call's mute, and the stream becomes the one {@link ToggleMute} and the teardown act on. Mid-swap the stream holds no
+     * track, so only a finished swap is followed. Every report also keeps {@link Microphone$} current once the call offers
+     * it.
+     */
+    followMicrophone(controller, stream) {
+        let followedStream = stream;
+        let followedTrack = stream.getAudioTracks()[0] ?? null;
+        this.localMediaSubscription = controller.State$.subscribe((media) => {
+            const current = controller.GetStream('microphone') ?? followedStream;
+            const track = current.getAudioTracks()[0] ?? null;
+            if (track && track !== followedTrack) {
+                if (current !== followedStream) {
+                    track.enabled = !this.microphoneMuted;
+                    this.localStream = current;
+                    followedStream = current;
+                }
+                followedTrack = track;
+                this.recorder?.ReplaceMicrophone?.(current);
+                this.client?.ReplaceMicrophone?.(current)?.catch((error) => {
+                    console.error('[RealtimeSession] The realtime driver could not move to the new microphone:', error);
+                });
+            }
+            this.publishMicrophone(media);
+        });
+    }
+    /** The client is connected: the call offers its microphone on {@link Microphone$}, and {@link SwitchMicrophone} moves it. */
+    offerMicrophone() {
+        if (!this.localMedia) {
+            return;
+        }
+        this.microphoneOffered = true;
+        this.publishMicrophone(this.localMedia.State);
+    }
+    /** Publishes the call's microphone from the controller's state while the call offers it, when it names a change. */
+    publishMicrophone(media) {
+        if (!this.microphoneOffered) {
+            return;
+        }
+        const current = this._microphone$.value;
+        const next = ReadMicrophoneState(media, current);
+        if (!SameMicrophoneState(next, current)) {
+            this._microphone$.next(next);
+        }
+    }
+    /** Stops following the controller and disposes it, which releases its devices; the call no longer offers a microphone. */
+    closeLocalMedia() {
+        this.localMediaSubscription?.unsubscribe();
+        this.localMediaSubscription = null;
+        this.localMedia?.Dispose();
+        this.localMedia = null;
+        this.microphoneOffered = false;
+        if (this._microphone$.value !== REALTIME_MICROPHONE_NONE) {
+            this._microphone$.next(REALTIME_MICROPHONE_NONE);
+        }
+    }
+    /**
+     * Creates the session's camera and screen share and mirrors their state on {@link Captures$}. With `cameraCheck`, the
+     * call's first camera start waits for {@link ConfirmCamera}.
+     */
+    openCaptures(client, cameraCheck) {
+        this.closeCaptures();
+        const captures = new RealtimeCaptures({
+            Client: client,
+            LocalMedia: this.localMedia,
+            Host: this.mediaHost,
+            CreateSampler: this.hostFrameSampler(),
+            Admit: (kind) => this.admitCapture(kind),
+            CameraCheck: cameraCheck,
+        });
+        this.captures = captures;
+        this.capturesSubscription = captures.States$.subscribe((states) => this._captures$.next(states));
+        this.refreshCaptureOffers();
+    }
+    /**
+     * The host's frame sampler for the captures ({@link IRealtimeMediaHost.CreateFrameSampler}), or `undefined` when it offers
+     * none and the captures use the DOM default.
+     */
+    hostFrameSampler() {
+        const host = this.mediaHost;
+        const create = host.CreateFrameSampler;
+        return create ? (stream, options) => create.call(host, stream, options) : undefined;
+    }
+    /** Stops the camera and screen share, if any, and reports both off. */
+    closeCaptures() {
+        this.capturesSubscription?.unsubscribe();
+        this.capturesSubscription = null;
+        this.captures?.Dispose();
+        this.captures = null;
+        if (this._captures$.value !== REALTIME_CAPTURES_OFF) {
+            this._captures$.next(REALTIME_CAPTURES_OFF);
+        }
+        this.refreshCaptureOffers();
+    }
+    /** Works out which captures the call offers ({@link CaptureOffers$}) and publishes a change. */
+    refreshCaptureOffers() {
+        const offers = this.captures && this.client?.SupportsInboundVideo ? { Camera: this.canOffer('camera'), Screen: this.canOffer('screen') } : REALTIME_CAPTURE_OFFERS_NONE;
+        const current = this._captureOffers$.value;
+        if (offers.Camera !== current.Camera || offers.Screen !== current.Screen) {
+            this._captureOffers$.next(offers);
+        }
+    }
+    /** Whether the host can open a capture and the call's policy admits it. */
+    canOffer(kind) {
+        const hostCanOpen = kind === 'camera' ? this.localMedia !== null : typeof this.mediaHost.RequestDisplayCapture === 'function';
+        return hostCanOpen && this.admitCapture(kind).Admitted;
+    }
+    /** What a capture reports when there is no live session to show it to. */
+    noSessionCapture() {
+        return { Status: 'failed', Failure: 'no-session', Message: 'There is no call to share with.' };
+    }
+    /**
+     * The session's policy for a capture. The channel that fronts it (its `CaptureKind`) must be in the session, open or
+     * advertised, and the server's policy must let the agent see pixels through it (the agent's configuration and any
+     * zero-data-retention rule). The user's own "agent can see" choice for the channel does not refuse a start: it decides
+     * whether the frames reach the model.
+     */
+    admitCapture(kind) {
+        const channel = this.findCaptureChannel(kind)?.Plugin;
+        if (!channel) {
+            return { Admitted: false, Message: CAPTURE_WORDING[kind].NotInCall };
+        }
+        const resolved = this.GetResolvedChannel(channel.ChannelName);
+        const allowed = resolved?.Exposure ?? resolved?.MaxExposure ?? channel.GetDescriptor().MaxExposure;
+        if (allowed !== 'pixels') {
+            const reasons = (resolved?.ExposureLimits ?? []).map((limit) => limit.Reason);
+            return { Admitted: false, Message: reasons.length > 0 ? `${CAPTURE_WORDING[kind].NotAllowed}: ${reasons.join('; ')}.` : `${CAPTURE_WORDING[kind].NotAllowed}.` };
+        }
+        return { Admitted: true, ChannelKey: channel.ChannelName, VisibleToAgent: channel.Exposure === 'pixels' };
+    }
+    /** The channel in the session, open or advertised, that fronts a capture. */
+    findCaptureChannel(kind) {
+        const open = this._activeChannels$.value.find((c) => c.CaptureKind === kind);
+        if (open) {
+            return { Plugin: open, IsOpen: true };
+        }
+        const advertised = this.advertisedChannels.find((p) => p.Plugin.CaptureKind === kind);
+        return advertised ? { Plugin: advertised.Plugin, IsOpen: false } : null;
+    }
+    /**
+     * Brings up the channel that fronts a capture once the capture is starting, so the host shows its surface: an advertised
+     * channel is opened (and announces itself to the agent), an open one counts as used.
+     */
+    async revealCaptureChannel(kind) {
+        const state = kind === 'camera' ? this.captures?.States.Camera : this.captures?.States.Screen;
+        const channel = state?.Status === 'starting' ? this.findCaptureChannel(kind) : null;
+        if (!channel) {
+            return;
+        }
+        if (channel.IsOpen) {
+            this.noteChannelActivity(channel.Plugin);
+            return;
+        }
+        const opened = await this.OpenChannel(channel.Plugin.ChannelName);
+        if (!opened.Success) {
+            console.warn(`[RealtimeSession] Could not open channel '${channel.Plugin.ChannelName}' for the ${kind}: ${opened.ErrorMessage ?? opened.ErrorCode}`);
+        }
+    }
+    /**
+     * Starts the user's camera and shows it to the agent. Call it from the user's click: it may ask for camera
+     * permission. Resolves with the camera's state; a failure (no session, a model that takes no video, a refused
+     * permission) is a state with a message, never a throw. While the camera is on, it is a source on
+     * {@link VideoSources$}, and it stops by itself if the device goes away.
+     *
+     * When the host shows a camera check ({@link RealtimeSessionStartOptions.CameraCheck}), the call's first start
+     * resolves still starting, with `Checking` set and the stream for the host to preview. The agent sees the camera
+     * once the host calls {@link ConfirmCamera}; {@link StopCamera} is the user's "not now".
+     *
+     * @param deviceId The camera to open; the system default when absent.
+     */
+    async StartCamera(deviceId) {
+        if (!this.captures) {
+            return this.noSessionCapture();
+        }
+        const started = this.captures.Start('camera', { DeviceID: deviceId });
+        await this.revealCaptureChannel('camera');
+        return started;
+    }
+    /** Stops the user's camera. Safe to call when it is off. */
+    StopCamera() {
+        this.captures?.Stop('camera');
+    }
+    /**
+     * Moves the user's camera to another device while it is open (being checked or on): one of the camera's `Devices` on
+     * {@link Captures$}. The stream stays the same. Resolves with the camera's state; nothing changes while the camera is
+     * off.
+     *
+     * @param deviceId The camera to move to.
+     */
+    async SwitchCamera(deviceId) {
+        return this.captures ? this.captures.SwitchCamera(deviceId) : this.noSessionCapture();
+    }
+    /**
+     * Moves the call's microphone to another device: one of the `Devices` on {@link Microphone$}. The host's controller
+     * swaps the new track into the same stream and carries the mute over, and the driver and the call's recording move to
+     * it, so the agent keeps hearing the user. When the new microphone cannot open, the controller goes back to the one in
+     * use. While the call has no microphone open (it lost the one in use and the default, or the last one went away), the
+     * pick opens one again: the driver and the recording move to it, and it keeps the call's mute. Resolves with the
+     * microphone's state once the switch is over. Nothing changes outside a call or on a host without a controller.
+     *
+     * @param deviceId The microphone to move to.
+     */
+    async SwitchMicrophone(deviceId) {
+        const controller = this.localMedia;
+        if (controller && this.microphoneOffered) {
+            const status = controller.State.Microphone.Status;
+            const live = status === 'on' || status === 'starting';
+            await (live ? controller.SwitchDevice('microphone', deviceId) : controller.Start('microphone', deviceId));
+        }
+        return this._microphone$.value;
+    }
+    /**
+     * The user checked the camera and turned it on: the agent sees it from now on, and later camera starts in this call
+     * skip the check. Returns the camera's state; unless the camera is waiting for its check (see {@link StartCamera}),
+     * nothing changes.
+     */
+    ConfirmCamera() {
+        return this.captures ? this.captures.ConfirmCamera() : this.noSessionCapture();
+    }
+    /**
+     * Asks the user for a screen, window or browser tab (or one panel of the page) and shows it to the agent. Call it
+     * from the user's click: the browser's picker needs one. Resolves with the share's state; a failure (no session,
+     * a model that takes no video, a closed picker, a host that cannot share) is a state with a message. The share
+     * also stops when the user ends it from the browser's own bar.
+     *
+     * @param options What the picker offers first, or the panel to share and its name (`PanelLabel`), which the share's
+     *   state carries and the agent sees as "<name> (shared panel)".
+     */
+    async StartScreenShare(options) {
+        if (!this.captures) {
+            return this.noSessionCapture();
+        }
+        const started = this.captures.Start('screen', options);
+        await this.revealCaptureChannel('screen');
+        return started;
+    }
+    /** Stops the user's screen share. Safe to call when nothing is shared. */
+    StopScreenShare() {
+        this.captures?.Stop('screen');
+    }
+    /**
+     * Why the latest session start failed, or `null` when it has not failed or none has run.
      *
      * Read it when {@link ConnectionState$} reports `'error'`, to tell a denied microphone apart from
-     * a provider or backend failure and show copy the user can act on. Cleared at the start of every
-     * session.
+     * a provider or backend failure and show copy the user can act on. Each start clears it before it
+     * reports `'connecting'`, so it never describes an earlier start.
      */
     get LastStartError() {
         return this.lastStartError;
     }
+    /**
+     * The fatal error the call's client reported, or `null` when it has reported none.
+     *
+     * Read it when {@link ConnectionState$} reports `'error'` on a call that was live, to tell a call that reached its time
+     * limit (`Code` `'time-limit'`; {@link DescribeCallEnd} words it) from a dropped connection. Each start clears it before
+     * it reports `'connecting'`.
+     */
+    get LastSessionError() {
+        return this.lastSessionError;
+    }
     /**
      * The single failure path for a session start (mint half or run half): report it, latch the
      * overlay into 'error', and unwind whatever the half-built session already opened.
@@ -779,7 +1630,7 @@ export class RealtimeSessionRuntime {
     async failSessionStart(error) {
         console.error('[RealtimeSession] Failed to start session:', error);
         this.lastStartError = error instanceof Error ? error : new Error(String(error));
-        this._connectionState$.next('error');
+        this.setConnectionState('error');
         await this.teardown(false);
     }
     /**
@@ -816,16 +1667,21 @@ 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. */
+    /**
+     * Mute / unmute the local microphone track. Returns the new muted state. While the call has no microphone track (a
+     * switch is putting a new one in, or the call lost its microphone) there is nothing to mute: nothing changes, and it
+     * returns the call's mute, which the next microphone keeps. Outside a call it returns `false`.
+     */
     ToggleMute() {
         const tracks = this.localStream?.getAudioTracks() ?? [];
         if (tracks.length === 0) {
-            return false;
+            return this.microphoneMuted;
         }
         const muted = tracks[0].enabled; // currently enabled → becomes muted
         this.client?.SetMuted(muted);
+        this.microphoneMuted = muted;
         return muted;
     }
     // ── Client-executed UI tools ───────────────────────────────────────────────
@@ -895,13 +1751,21 @@ export class RealtimeSessionRuntime {
         return this.client;
     }
     /**
-     * Relays a video frame to the underlying realtime client if active.
+     * Relays a video frame straight to the underlying realtime client, if a session is live.
+     *
+     * It bypasses the session's {@link VideoSourceArbiter}: the frame overrides the source the arbiter picked, and the
+     * model is not told what it is looking at. Channels no longer send through it (their context's `SendVideoFrame` goes
+     * through the arbiter); a host that shows the model something registers a source there instead, as
+     * `ChannelInboundVideoBridge` does.
+     *
+     * @returns `true` when the client accepted and sent the frame; `false` when no session is live, the
+     *   client cannot take video frames, or the client dropped the frame.
      */
     SendVideoFrame(base64Image, mimeType) {
         if (!this.client || !this.isSessionLive()) {
-            return;
+            return false;
         }
-        this.client.SendVideoFrame?.(base64Image, mimeType);
+        return this.client.SendVideoFrame?.(base64Image, mimeType) === true;
     }
     /**
      * Checks whether a media track is established on the active realtime client.
@@ -948,12 +1812,16 @@ 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) {
-                // The agent's WebRTC audio track usually lands AFTER Connect() resolves, so `remoteStream`
-                // above is typically null and we'd capture mic-only. Attach the agent stream whenever it
-                // arrives (fires immediately if already present) so the recording includes the agent voice.
+                // 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
+                // drivers (Gemini, ElevenLabs, AssemblyAI, xAI, HuggingFace) publish at Connect, so
+                // `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) {
@@ -961,201 +1829,928 @@ export class RealtimeSessionRuntime {
             this.recorder = null;
         }
     }
-    /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
-    startSegmentFlushing() {
-        this.segmentIndex = 0;
-        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);
+    }
+    /** 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;
+        }
+    }
+    /**
+     * Starts telling the server this session is still in use (#3533).
+     *
+     * **Why the server cannot work this out on its own.** In the client-direct topology the audio
+     * goes browser → provider over WebRTC. The server sees the mint, a few channel actions in the
+     * first seconds, and then nothing at all — so `SessionManager.RecordActivity` stops being
+     * reached while the conversation is still going. `LastActiveAt` freezes ~45 seconds in, and
+     * `SessionJanitor` — which cannot distinguish an active call from an abandoned one — force-closes
+     * it at `closeThresholdMinutes`, mid-sentence, taking the user's surfaces with it. A session
+     * whose channels are all client-side (whiteboard, media) goes quiet from the server's point of
+     * view almost immediately.
+     *
+     * The browser is the only participant that knows the call is alive, so it is the one that has to
+     * say so. Raising `closeThresholdMinutes` is not the fix — it just makes the janitor slower at
+     * its real job (reaping rows orphaned by a crash) without making liveness observable.
+     *
+     * The pulse is best-effort by design: a failed beat is logged and skipped, never surfaced to the
+     * user and never allowed to end the session. Losing one beat costs nothing because the threshold
+     * is many beats wide; turning a transient network blip into a visible error would be a worse
+     * failure than the one this fixes. Write amplification is bounded on the server side too, where
+     * `SessionManager.Heartbeat` coalesces persisted writes.
+     */
+    startLivenessPulse() {
+        this.stopLivenessPulse();
+        this.livenessTimer = setInterval(() => { void this.pulseLiveness(); }, RealtimeSessionRuntime.livenessPulseMs);
+    }
+    /** Stops the liveness pulse. Idempotent — safe on a session that never started one. */
+    stopLivenessPulse() {
+        if (this.livenessTimer) {
+            clearInterval(this.livenessTimer);
+            this.livenessTimer = null;
+        }
+    }
+    /**
+     * One liveness beat. Reads the session id at fire time rather than closing over it, so a beat
+     * that fires during teardown finds `null` and does nothing instead of resurrecting a closed row.
+     */
+    async pulseLiveness() {
+        const agentSessionId = this.agentSessionId;
+        if (!agentSessionId) {
+            return;
+        }
+        const mutation = `
+      mutation AgentSessionHeartbeat($agentSessionId: String!) {
+        AgentSessionHeartbeat(agentSessionId: $agentSessionId)
+      }
+    `;
+        try {
+            await this.gql().ExecuteGQL(mutation, { agentSessionId });
+        }
+        catch (error) {
+            // Best-effort: the next beat is 60s away and the janitor threshold is many beats wide.
+            console.warn('[RealtimeSession] Liveness pulse failed (session continues):', error);
+        }
+    }
+    /**
+     * 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 flushRecordingShards() {
+        const recorder = this.recorder;
+        const pipeline = this.recordingShards;
+        if (!recorder || !pipeline) {
+            return;
+        }
+        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);
+    }
+    /**
+     * 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) {
+        const recorder = this.recorder;
+        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;
+        this.userSpeechStartMs = null;
+        this.userSpeechStartSuperseded = false;
+        if (!recorder || !pipeline) {
+            this.recorder = null;
+            this.recordingShards = null;
+            return null;
+        }
+        try {
+            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;
+            }
+            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 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;
+        }
+    }
+    /**
+     * 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 stopRecorder(recorder, sessionId) {
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), RECORDER_STOP_TIMEOUT_MS);
+        });
+        try {
+            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] Recorder failed to stop for session ${sessionId}; ending the recording at the packets already encoded:`, error);
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * 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 awaitRecordingTerminal(pending) {
+        const sessionId = pending.Pipeline.SessionID;
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), RECORDING_TERMINAL_ACK_TIMEOUT_MS);
+        });
+        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();
+        }
+    }
+    /**
+     * The resolved behavior of an in-session channel (display, exposure ceiling, config, what put it
+     * in the session), or `null` when the channel is not in this session. Hosts and overlays read the
+     * resolved display from here rather than from the channel's code default.
+     *
+     * @param channelName The channel's key (case-insensitive).
+     */
+    GetResolvedChannel(channelName) {
+        return this.resolvedChannels.get(NormalizeChannelKey(channelName)) ?? null;
+    }
+    /**
+     * Replaces the store the user's per-channel exposure choices are kept in. The default persists them in
+     * the signed-in user's settings (`mj.realtime.visualPerception.v1`) and keeps them in memory for an
+     * anonymous principal or a connect-only embed; a host that remembers them somewhere else supplies its own.
+     */
+    SetExposurePreferences(preferences) {
+        this.exposurePreferences = preferences;
+    }
+    /** The store the user's per-channel exposure choices are currently kept in (so a host can wrap it). */
+    get ExposurePreferences() {
+        return this.exposurePreferences;
+    }
+    /** Whether user settings can be written: a signed-in user on a provider that has entity metadata. */
+    canPersistUserSettings() {
+        const provider = this.Provider;
+        return Boolean(provider?.CurrentUser?.ID) && (provider?.Entities?.length ?? 0) > 0;
+    }
+    /**
+     * How much of a channel the model may perceive right now: the channel's ceiling, lowered by the server's
+     * policy and the user's choice. `null` when the channel is not in this session.
+     *
+     * @param channelName The channel's key (case-insensitive).
+     */
+    GetChannelExposure(channelName) {
+        return this.findDispatchableChannel(channelName)?.Plugin.Exposure ?? null;
+    }
+    /**
+     * The user's own choice of how much of a channel the agent may perceive. Takes effect immediately
+     * (frames and notes the new level forbids stop, and the model is told), and is remembered per channel key
+     * for next time. The level can only LOWER what the server's policy allows; choosing `'pixels'` for a channel
+     * the agent's policy capped at `'state'` changes nothing.
+     *
+     * @param channelName The channel's key (case-insensitive).
+     * @param level The user's choice; `undefined` clears it (back to what policy allows).
+     * @returns `false` when the channel is not in this session (nothing is applied, but the choice is still remembered).
+     */
+    SetUserChannelExposure(channelName, level) {
+        this.exposurePreferences.Set(channelName, level);
+        const channel = this.findDispatchableChannel(channelName);
+        if (!channel) {
+            return false;
+        }
+        this.applyChannelExposure(channel.Plugin);
+        return true;
+    }
+    /** Pushes a channel's current exposure inputs (server policy, user choice) into the channel. */
+    applyChannelExposure(plugin) {
+        const resolved = this.GetResolvedChannel(plugin.ChannelName);
+        const user = this.exposurePreferences.Get(plugin.ChannelName);
+        const reasons = (resolved?.ExposureLimits ?? []).map((limit) => limit.Reason);
+        // The user's limit binds only when it is lower than what the server allows; otherwise it changes nothing
+        // and the agent should not be told about it.
+        const allowed = resolved?.Exposure ?? plugin.GetDescriptor().MaxExposure;
+        if (user !== undefined && CompareExposure(user, allowed) < 0) {
+            reasons.push(UserExposureReason(user));
+        }
+        plugin.ApplyExposure({ Policy: resolved?.Exposure, User: user, Reasons: reasons });
+        // A capture this channel fronts follows it: the agent sees its frames only while the channel's exposure allows pixels.
+        const kind = plugin.CaptureKind;
+        if (kind) {
+            this.captures?.SetVisibleToAgent(kind, plugin.Exposure === 'pixels');
+        }
+        this.syncChannelVideoSource(plugin);
+    }
+    /**
+     * Sends a frame from a channel's context ({@link RealtimeChannelContext.SendVideoFrame}, deprecated) through the
+     * session's {@link VideoSourceArbiter}, as the channel's own source: it reaches the model only while the arbiter picks
+     * that source, and the arbiter tells the model when it switches. The source registers with the first frame, under the
+     * id the channel's own frame bridge uses, switched on only while the channel's exposure allows pixels.
+     */
+    sendChannelVideoFrame(plugin, base64Image, mimeType) {
+        const client = this.client;
+        if (!client || !this.isSessionLive() || !client.IsTrackEstablished('video', 'inbound')) {
+            return;
+        }
+        const arbiter = VideoSourceArbiter.ForSink(client);
+        const descriptor = plugin.GetDescriptor();
+        const sourceId = ChannelVideoSourceID(descriptor.Key, plugin.InstanceId);
+        if (!arbiter.HasSource(sourceId)) {
+            arbiter.RegisterSource({
+                SourceID: sourceId,
+                Label: descriptor.DisplayName,
+                Kind: 'surface',
+                ChannelKey: descriptor.Key,
+                Enabled: plugin.Exposure === 'pixels',
+            });
+        }
+        arbiter.PushFrame(sourceId, base64Image, mimeType);
+    }
+    /**
+     * Keeps a channel's video source at the arbiter, when it has one, in step with the channel's exposure: on while the
+     * agent may see its pixels, off otherwise. Quiet, because the channel tells the model about its own exposure change.
+     */
+    syncChannelVideoSource(plugin) {
+        if (!this.client) {
+            return;
+        }
+        const arbiter = VideoSourceArbiter.ForSink(this.client);
+        const sourceId = ChannelVideoSourceID(plugin.GetDescriptor().Key, plugin.InstanceId);
+        if (arbiter.HasSource(sourceId)) {
+            arbiter.SetSourceEnabled(sourceId, plugin.Exposure === 'pixels', false);
+        }
+    }
+    /** Follows the session client's video-source arbiter so {@link VideoSources$} reflects it. */
+    watchVideoSources(client) {
+        this.unwatchVideoSources();
+        const arbiter = VideoSourceArbiter.ForSink(client);
+        arbiter.SetFocusedChannel(this.focusedChannelKey);
+        this.stopWatchingVideoSources = arbiter.OnChange(() => this._videoSources$.next(arbiter.GetSources()));
+        this._videoSources$.next(arbiter.GetSources());
+    }
+    /**
+     * Tells the session which channel's surface the user is looking at (`null` for none, e.g. the activity tab).
+     * When the model can see only one video source and several are live, the one the user is looking at is the one
+     * it sees (after an explicit pick, and after a camera or screen share the user started). Safe to call before the
+     * session is live: it applies when the connection comes up.
+     *
+     * @param channelKey The focused channel's key, as it appears on {@link VideoSources$} entries' `ChannelKey`.
+     */
+    SetFocusedChannel(channelKey) {
+        this.focusedChannelKey = channelKey;
+        if (this.client) {
+            VideoSourceArbiter.ForSink(this.client).SetFocusedChannel(channelKey);
+        }
+    }
+    /** Stops following the arbiter and clears {@link VideoSources$}. Safe to call when nothing is watched. */
+    unwatchVideoSources() {
+        this.stopWatchingVideoSources?.();
+        this.stopWatchingVideoSources = null;
+        if (this._videoSources$.value.length > 0) {
+            this._videoSources$.next([]);
+        }
+    }
+    /**
+     * Turns the agent's view of one video source on or off — what the "agent can see" control calls.
+     *
+     * A source that belongs to a channel goes through {@link SetUserChannelExposure}, so the choice is
+     * remembered per channel and the channel itself tells the model. Any other source (a camera or screen
+     * share that is not a channel) is switched at the arbiter, which tells the model.
+     *
+     * @param sourceId The source's id (from {@link VideoSources$}).
+     * @param enabled Whether the agent may see it.
+     * @returns `false` when there is no such source.
+     */
+    SetVideoSourceEnabled(sourceId, enabled) {
+        const client = this.client;
+        if (!client) {
+            return false;
+        }
+        const arbiter = VideoSourceArbiter.ForSink(client);
+        const source = arbiter.GetSources().find((s) => s.SourceID === sourceId);
+        if (!source) {
+            return false;
+        }
+        if (source.ChannelKey && this.findDispatchableChannel(source.ChannelKey)) {
+            return this.SetUserChannelExposure(source.ChannelKey, enabled ? undefined : 'state');
+        }
+        return arbiter.SetSourceEnabled(sourceId, enabled);
+    }
+    /**
+     * Picks the video source the agent sees: what the "agent can see" control calls when more sources are on than the
+     * model takes. The pick beats every other rule (a camera or screen share the user started, the surface the user is
+     * looking at) until it is cleared, or its source is turned off or leaves. The pick shows on {@link VideoSources$}
+     * (`Picked`), and the model is told when what it sees changes.
+     *
+     * @param sourceId The source's id (from {@link VideoSources$}), or `null` to let the call decide again.
+     * @returns `false` with no live session, or for a source that is not there or is turned off.
+     */
+    SelectVideoSource(sourceId) {
+        return this.client ? VideoSourceArbiter.ForSink(this.client).SelectSource(sourceId) : false;
+    }
+    /**
+     * The `on-demand` channels that are in the session but not open yet — what the agent can open
+     * through `ContextTool`. A fresh array; empty before a session starts and after teardown.
+     */
+    get AdvertisedChannels() {
+        return this.advertisedChannels.map((p) => p.Plugin);
     }
-    /** Stops the periodic crash-recovery shard flush. */
-    stopSegmentFlushing() {
-        if (this.segmentTimer) {
-            clearInterval(this.segmentTimer);
-            this.segmentTimer = null;
-        }
+    /**
+     * Resolves, initializes and mounts the session's channels in one step using the scope the browser
+     * can decide alone (code defaults + host declarations), and returns the native tools to declare at
+     * mint. This is the single-step composition of {@link prepareChannelScope} + {@link activateChannels}
+     * that a session start spreads across the mint; it is kept as a unit because it is the cleanest seam
+     * for exercising the plugin plumbing without a mint.
+     */
+    async startChannels(hostChannels) {
+        const scope = await this.prepareChannelScope(hostChannels);
+        this.activateChannels(this.localChannelScope?.Channels ?? []);
+        return scope.NativeTools;
     }
     /**
-     * Starts telling the server this session is still in use (#3533).
-     *
-     * **Why the server cannot work this out on its own.** In the client-direct topology the audio
-     * goes browser → provider over WebRTC. The server sees the mint, a few channel actions in the
-     * first seconds, and then nothing at all — so `SessionManager.RecordActivity` stops being
-     * reached while the conversation is still going. `LastActiveAt` freezes ~45 seconds in, and
-     * `SessionJanitor` — which cannot distinguish an active call from an abandoned one — force-closes
-     * it at `closeThresholdMinutes`, mid-sentence, taking the user's surfaces with it. A session
-     * whose channels are all client-side (whiteboard, media) goes quiet from the server's point of
-     * view almost immediately.
+     * Stage 1: constructs the channel plugins (registry rows and host declarations), reads their
+     * descriptors, resolves the scope the browser can decide alone, and builds what the mint needs —
+     * the native tools to declare and the candidates to report. Starts nothing.
      *
-     * The browser is the only participant that knows the call is alive, so it is the one that has to
-     * say so. Raising `closeThresholdMinutes` is not the fix — it just makes the janitor slower at
-     * its real job (reaping rows orphaned by a crash) without making liveness observable.
-     *
-     * The pulse is best-effort by design: a failed beat is logged and skipped, never surfaced to the
-     * user and never allowed to end the session. Losing one beat costs nothing because the threshold
-     * is many beats wide; turning a transient network blip into a visible error would be a worse
-     * failure than the one this fixes. Write amplification is bounded on the server side too, where
-     * `SessionManager.Heartbeat` coalesces persisted writes.
+     * @param hostChannels Channels the host brings to this session.
+     * @returns The native tools to declare at mint, the candidates as JSON (`null` when there are none,
+     *   so a channel-less session sends exactly the mint it always did), and whether the host could show the agent's
+     *   video ({@link PreparedChannelsShowAgentVideo}).
      */
-    startLivenessPulse() {
-        this.stopLivenessPulse();
-        this.livenessTimer = setInterval(() => { void this.pulseLiveness(); }, RealtimeSessionRuntime.livenessPulseMs);
-    }
-    /** Stops the liveness pulse. Idempotent — safe on a session that never started one. */
-    stopLivenessPulse() {
-        if (this.livenessTimer) {
-            clearInterval(this.livenessTimer);
-            this.livenessTimer = null;
-        }
+    async prepareChannelScope(hostChannels) {
+        this.discardUnmountedChannels();
+        const prepared = await this.prepareChannels(hostChannels);
+        this.preparedChannels = prepared;
+        const candidates = prepared.map((p) => BuildChannelCandidate(p, p.Plugin.GetDescriptor()));
+        const local = ResolveLocalChannelScope(candidates);
+        this.localChannelScope = local;
+        for (const excluded of local.Excluded) {
+            console.warn(`[RealtimeSession] Channel '${excluded.Key}' is not in this session (${excluded.Reason}).`);
+        }
+        const nativeTools = SelectNativeChannelTools(local.Channels, ToolsByChannelKey(candidates));
+        // `Registry` is the browser's own view and never goes over the wire: the server reads the registry itself.
+        const wire = candidates.map(({ Registry: _registry, ...candidate }) => candidate);
+        return { NativeTools: nativeTools, CandidatesJson: wire.length > 0 ? JSON.stringify(wire) : null, ShowsAgentVideo: PreparedChannelsShowAgentVideo(prepared) };
     }
     /**
-     * One liveness beat. Reads the session id at fire time rather than closing over it, so a beat
-     * that fires during teardown finds `null` and does nothing instead of resurrecting a closed row.
+     * Constructs a plugin for every active-or-inactive registry row and every host declaration. An
+     * INACTIVE row is constructed too — only to learn its key so the kill switch can name it — and is
+     * never initialized. A plugin whose descriptor cannot be read is skipped (logged), never fatal.
      */
-    async pulseLiveness() {
-        const agentSessionId = this.agentSessionId;
-        if (!agentSessionId) {
-            return;
-        }
-        const mutation = `
-      mutation AgentSessionHeartbeat($agentSessionId: String!) {
-        AgentSessionHeartbeat(agentSessionId: $agentSessionId)
-      }
-    `;
-        try {
-            await this.gql().ExecuteGQL(mutation, { agentSessionId });
+    async prepareChannels(hostChannels) {
+        const rows = await this.fetchChannelDefinitions();
+        await this.loadChannelClasses([...rows.map((r) => r.ClientPluginClass), ...(hostChannels ?? []).map((d) => d.ClientPluginClass)]);
+        const prepared = [];
+        for (const row of rows) {
+            const plugin = this.resolveChannelPlugin(row);
+            if (plugin) {
+                plugin.ApplySurfacePlacement(row.SurfacePlacement);
+                prepared.push({ Plugin: plugin, Key: plugin.ChannelName, Registry: row.IsActive ? 'active' : 'inactive' });
+            }
         }
-        catch (error) {
-            // Best-effort: the next beat is 60s away and the janitor threshold is many beats wide.
-            console.warn('[RealtimeSession] Liveness pulse failed (session continues):', error);
+        for (const declaration of hostChannels ?? []) {
+            const plugin = this.createHostChannelPlugin(declaration);
+            if (!plugin) {
+                continue;
+            }
+            const existing = FindPreparedChannel(prepared, plugin.ChannelName);
+            if (existing) {
+                // The host's instance replaces the registry's (it may carry the host's collaborators); the
+                // registry row's state — notably the kill switch, and where its surface shows — still applies.
+                plugin.ApplySurfacePlacement(existing.Plugin.SurfacePlacement);
+                existing.Plugin = plugin;
+                existing.HostDeclaration = declaration;
+            }
+            else {
+                prepared.push({ Plugin: plugin, Key: plugin.ChannelName, Registry: 'none', HostDeclaration: declaration });
+            }
         }
+        return prepared.filter((p) => this.canDescribe(p));
     }
     /**
-     * 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.
+     * Gives a host that loads channel code on demand (a widget that keeps a heavy channel in its own download)
+     * the chance to load it before the plugins are built. Never fatal: a loader that throws is logged and the
+     * channel simply is not available, exactly as if its class had never been registered.
+     *
+     * @param keys The `ClientPluginClass` keys of every channel about to be resolved (blank/absent ones included).
      */
-    async flushRecordingSegment() {
-        const recorder = this.recorder;
-        const agentSessionId = this.agentSessionId;
-        if (!recorder || !agentSessionId) {
+    async loadChannelClasses(keys) {
+        const loader = this.ChannelClassLoader;
+        if (!loader) {
             return;
         }
-        try {
-            const audioBase64 = await recorder.SnapshotNewSegmentBase64();
-            if (!audioBase64) {
-                return;
-            }
-            const index = this.segmentIndex++;
-            const mutation = `
-        mutation UploadRealtimeRecordingSegment($agentSessionId: String!, $segmentIndex: Int!, $audioBase64: String!, $mimeType: String!) {
-          UploadRealtimeRecordingSegment(agentSessionId: $agentSessionId, segmentIndex: $segmentIndex, audioBase64: $audioBase64, mimeType: $mimeType)
+        const wanted = [...new Set(keys.map((k) => k?.trim() ?? '').filter((k) => k.length > 0))];
+        if (wanted.length === 0) {
+            return;
         }
-      `;
-            // 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=${recorder.SampleRate}`;
-            await this.gql().ExecuteGQL(mutation, { agentSessionId, segmentIndex: index, audioBase64, mimeType: shardMime });
+        try {
+            await loader(wanted);
         }
         catch (error) {
-            console.warn('[RealtimeSession] Failed to flush recording shard:', error);
+            console.error('[RealtimeSession] The channel class loader failed — channels that needed it are left out:', error);
         }
     }
-    /**
-     * Stops the active recorder and uploads the captured audio via `UploadRealtimeRecording`.
-     * Fully best-effort and wrapped in try/catch — recording upload must NEVER block teardown.
-     * No-op when nothing was recorded or there's no session id to attach the file to.
-     */
-    async stopAndUploadRecording(agentSessionId) {
-        this.stopSegmentFlushing();
-        const recorder = this.recorder;
-        this.recorder = null;
-        this.currentTurnStartMs = null;
-        this.turnAudioStartCaptured = false;
-        if (!recorder) {
-            return;
-        }
+    /** Whether a prepared plugin's descriptor can be read; logs and rejects one that throws. */
+    canDescribe(prepared) {
         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 || !agentSessionId) {
-                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — empty recording or no session id.');
-                return;
-            }
-            await this.uploadRecording(agentSessionId, audioBase64, mimeType, peaks);
+            prepared.Plugin.GetDescriptor();
+            return true;
         }
         catch (error) {
-            console.warn('[RealtimeSession] Failed to stop/upload call recording:', error);
+            console.error(`[RealtimeSession] Channel '${prepared.Key}' has an unreadable descriptor — leaving it out:`, error);
+            return false;
         }
     }
-    /**
-     * Runs the `UploadRealtimeRecording` mutation; failures are logged, never thrown. 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.
-     */
-    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
+    /** Builds a plugin from a host declaration; `null` (logged) when it names nothing buildable. */
+    createHostChannelPlugin(declaration) {
+        if (declaration.Create) {
+            try {
+                return declaration.Create();
+            }
+            catch (error) {
+                console.error('[RealtimeSession] A host-declared channel factory threw — leaving the channel out:', error);
+                return null;
+            }
         }
-      }
-    `;
-        const result = await this.gql().ExecuteGQL(mutation, {
-            agentSessionId,
-            audioBase64,
-            mimeType,
-            consent: true,
-            peaks
-        });
-        const payload = result?.UploadRealtimeRecording;
-        if (!payload?.Success) {
-            console.warn(`[RealtimeSession] ❌ recording upload reported failure: ${payload?.ErrorMessage ?? 'unknown error'} (full result: ${JSON.stringify(result)})`);
+        const key = declaration.ClientPluginClass?.trim();
+        if (!key) {
+            console.warn('[RealtimeSession] A host-declared channel names neither ClientPluginClass nor Create — ignoring it.');
+            return null;
         }
+        return this.resolveChannelPlugin({ Name: key, ClientPluginClass: key, IsActive: true });
     }
-    // ── Interactive channels (registry-driven plugins) ─────────────────────────
     /**
-     * Resolves, instantiates and initializes the session's interactive-channel plugins from
-     * the `MJ: AI Agent Channels` registry, publishes them on {@link ActiveChannels$}, and
-     * returns their aggregated client-executed tool declarations for the session mint.
-     * Tolerant by design: registry/resolution failures degrade to "no channels" — the voice
-     * session itself always proceeds.
+     * Stage 3: initializes the channels the resolved policy puts in the session. `open-on-start` and
+     * `headless` channels are mounted and published on {@link ActiveChannels$}; `on-demand` channels
+     * are held until opened. Prepared plugins the policy left out are dropped without ever having run.
      */
-    async startChannels() {
-        const channels = await this.loadActiveChannels();
-        for (const plugin of channels) {
-            this.initializeChannel(plugin);
+    activateChannels(channels) {
+        const reconciled = ReconcileChannelsWithPolicy(this.preparedChannels, channels);
+        for (const key of reconciled.Unknown) {
+            console.warn(`[RealtimeSession] The session policy names channel '${key}' but this host has no plugin for it — ignoring it.`);
+        }
+        this.resolvedChannels.clear();
+        this.advertisedChannels = [];
+        const mounted = [];
+        for (const { Prepared, Resolved } of reconciled.InSession) {
+            this.resolvedChannels.set(NormalizeChannelKey(Resolved.Key), Resolved);
+            // Exposure is applied BEFORE the channel initializes, so what it requests of the model (a video
+            // track, in particular) already reflects what policy allows.
+            this.applyChannelExposure(Prepared.Plugin);
+            if (Resolved.DisplayPolicy === 'on-demand') {
+                this.advertisedChannels.push(Prepared);
+            }
+            else {
+                this.mountChannel(Prepared, Resolved);
+                mounted.push(Prepared.Plugin);
+            }
         }
-        this._activeChannels$.next(channels);
-        return channels.flatMap(plugin => plugin.GetToolDefinitions());
+        this.preparedChannels = [];
+        this._activeChannels$.next(mounted);
     }
     /**
-     * Loads the ACTIVE channel definitions from the registry and resolves each row's
-     * `ClientPluginClass` through the MJ ClassFactory into a per-session plugin instance —
-     * the client-side mirror of how realtime-model drivers resolve from `BaseRealtimeModel`
-     * / `BaseRealtimeClient`. Rows whose plugin class isn't registered are skipped (logged),
-     * never fatal.
+     * Applies the mint's outcome to the channel set: the server's policy when it sent a usable one,
+     * else the scope the browser resolved on its own. A policy can only SELECT among the plugins this
+     * host prepared — it cannot add one.
      */
-    async loadActiveChannels() {
-        const rows = await this.fetchChannelDefinitions();
-        const channels = [];
-        for (const row of rows) {
-            const plugin = this.resolveChannelPlugin(row);
-            if (plugin) {
-                channels.push(plugin);
-            }
+    applySessionClientPolicy(session) {
+        const policy = ParseRealtimeSessionClientPolicy(session.ClientPolicyJson);
+        if (session.ClientPolicyJson && !policy) {
+            console.warn('[RealtimeSession] The mint returned a client policy this runtime cannot read — resolving channels locally.');
         }
-        return channels;
+        this.sessionClientTools = policy?.ClientTools ?? null;
+        if (this.preparedChannels.length === 0) {
+            this.resolvedChannels.clear();
+            return; // nothing was prepared (a host that mints and runs the session itself) — no channel set to apply
+        }
+        this.activateChannels(policy?.Channels ?? this.localChannelScope?.Channels ?? []);
+    }
+    /** Drops plugins that were prepared for a start that never mounted them. They were never initialized, so there is nothing to release. */
+    discardUnmountedChannels() {
+        this.preparedChannels = [];
+        this.advertisedChannels = [];
+        this.localChannelScope = null;
     }
     /**
-     * Reads the ACTIVE `MJ: AI Agent Channels` rows. With entity metadata: from {@link AIEngineBase}'s
-     * cached `AgentChannels` (provider-scoped engine instance, lazy `Config` — no RunView round-trip;
-     * the engine's BaseEntity-event reactivity keeps the registry fresh). On a connect-only provider:
-     * one `RunDynamicView` query ({@link fetchChannelDefinitionsOverGraphQL}). Failures are logged and
-     * degrade to an empty list — channel availability must never block the voice session.
+     * Loads the `MJ: AI Agent Channels` registry rows (ACTIVE AND INACTIVE — an inactive row is the master
+     * kill switch, so the scope decision has to see it). With entity metadata: from {@link AIEngineBase}'s
+     * cached `AgentChannels` (provider-scoped engine instance, lazy `Config` — no RunView round-trip; the
+     * engine's BaseEntity-event reactivity keeps the registry fresh). On a connect-only provider: one
+     * `RunDynamicView` query ({@link fetchChannelDefinitionsOverGraphQL}). Failures are logged and degrade to an
+     * empty list — channel availability must never block the voice session.
      */
     async fetchChannelDefinitions() {
         // A connect-only provider (ConnectGraphQLClient — anonymous embeds) has no entity metadata,
@@ -1168,9 +2763,13 @@ export class RealtimeSessionRuntime {
         try {
             const engine = AIEngineBase.GetProviderInstance(this.Provider, AIEngineBase);
             await engine.Config(false, undefined, this.Provider);
-            return (engine.AgentChannels ?? [])
-                .filter(c => c.IsActive)
-                .map(c => ({ ID: c.ID, Name: c.Name, ClientPluginClass: c.ClientPluginClass }));
+            return (engine.AgentChannels ?? []).map((c) => ({
+                ID: c.ID,
+                Name: c.Name,
+                ClientPluginClass: c.ClientPluginClass,
+                IsActive: c.IsActive,
+                SurfacePlacement: readRowSurfacePlacement(c),
+            }));
         }
         catch (error) {
             console.warn('[RealtimeSession] Channel registry unavailable — starting with no channels:', error);
@@ -1178,10 +2777,10 @@ export class RealtimeSessionRuntime {
         }
     }
     /**
-     * The connect-only path of {@link fetchChannelDefinitions}: the same ACTIVE `MJ: AI Agent Channels`
-     * rows, read with a dynamic view because a connect-only client has no entity metadata to build a
-     * typed RunView from. Same tolerance as the engine path — a failure is logged and means "no
-     * channels", never a blocked session.
+     * The connect-only path of {@link fetchChannelDefinitions}: the same `MJ: AI Agent Channels` rows, active
+     * and inactive (an inactive row is the kill switch), read with a dynamic view because a connect-only client
+     * has no entity metadata to build a typed RunView from. Same tolerance as the engine path — a failure is
+     * logged and means "no channels", never a blocked session.
      */
     async fetchChannelDefinitionsOverGraphQL() {
         const query = `query RealtimeChannelRegistry($input: RunDynamicViewInput!) {
@@ -1189,7 +2788,7 @@ export class RealtimeSessionRuntime {
     }`;
         try {
             const result = (await this.gql().ExecuteGQL(query, {
-                input: { EntityName: 'MJ: AI Agent Channels', ExtraFilter: 'IsActive = 1', Fields: ['ID', 'Name', 'ClientPluginClass', 'IsActive'] },
+                input: { EntityName: 'MJ: AI Agent Channels', Fields: ['ID', 'Name', 'ClientPluginClass', 'IsActive', 'UIConfig'] },
             }));
             const view = result?.RunDynamicView;
             if (!view?.Success) {
@@ -1198,8 +2797,13 @@ export class RealtimeSessionRuntime {
             }
             return (view.Results ?? [])
                 .map((r) => JSON.parse(r.Data))
-                .filter((row) => row.IsActive === true)
-                .map((row) => ({ ID: row.ID, Name: row.Name, ClientPluginClass: row.ClientPluginClass }));
+                .map((row) => ({
+                ID: row.ID,
+                Name: row.Name,
+                ClientPluginClass: row.ClientPluginClass,
+                IsActive: row.IsActive === true,
+                SurfacePlacement: readUIConfigTextSurfacePlacement(row.Name, row.UIConfig),
+            }));
         }
         catch (error) {
             console.warn('[RealtimeSession] Channel registry unavailable — starting with no channels:', error instanceof Error ? error.message : String(error));
@@ -1211,16 +2815,23 @@ export class RealtimeSessionRuntime {
      * checked first, exactly like the realtime-client drivers) and instantiates a fresh
      * per-session plugin. Returns `null` (logged) when no plugin is registered for the key
      * — e.g. its Load function was never called or the package isn't included client-side.
+     * An inactive row is resolved quietly: it only needs to be named, and a missing plugin for a
+     * channel nobody wants is not worth a warning.
      */
     resolveChannelPlugin(row) {
         const key = row.ClientPluginClass?.trim();
+        const quiet = !row.IsActive;
         if (!key) {
-            console.warn(`[RealtimeSession] Channel '${row.Name}' has no ClientPluginClass — skipping.`);
+            if (!quiet) {
+                console.warn(`[RealtimeSession] Channel '${row.Name}' has no ClientPluginClass — skipping.`);
+            }
             return null;
         }
         const registration = MJGlobal.Instance.ClassFactory.GetRegistration(BaseRealtimeChannelClient, key);
         if (!registration) {
-            console.warn(`[RealtimeSession] No client plugin registered for channel '${row.Name}' (key '${key}') — skipping.`);
+            if (!quiet) {
+                console.warn(`[RealtimeSession] No client plugin registered for channel '${row.Name}' (key '${key}') — skipping.`);
+            }
             return null;
         }
         const plugin = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeChannelClient, key);
@@ -1231,24 +2842,157 @@ export class RealtimeSessionRuntime {
         return plugin;
     }
     /**
-     * Wires one plugin into the session: hands it its host context and registers its
-     * prefix-routed local tool executor (so `<ToolNamePrefix>*` calls run in the browser
-     * through {@link BaseRealtimeChannelClient.ApplyAgentTool}, never the server relay).
+     * Wires one plugin into the session: hands it its host context (carrying its resolved config) and,
+     * when it has native tools, registers its prefix-routed local tool executor (so `<ToolNamePrefix>*`
+     * calls run in the browser through {@link BaseRealtimeChannelClient.ApplyAgentTool}, never the
+     * server relay). A channel with no tool prefix has no native route — it is reached through
+     * `ContextTool` — and registering an empty prefix would match EVERY tool name.
      */
-    initializeChannel(plugin) {
-        plugin.Initialize(this.buildChannelContext(plugin));
+    mountChannel(prepared, resolved) {
+        const plugin = prepared.Plugin;
+        plugin.Initialize(this.buildChannelContext(plugin, resolved?.Config));
+        if (plugin.ToolNamePrefix.length === 0) {
+            return;
+        }
         this.RegisterClientToolHandler(plugin.ToolNamePrefix, (toolName, argsJson) => {
             // The agent is ACTING on this channel — surface-discovery signal for the overlay
             // (first activity registers + auto-reveals + focuses the channel tab) before the
             // tool applies. Record the channel as USED so the overlay tabs it (channels other
             // than the whiteboard are tab-less until they're first used).
-            this.usedChannelNames.add(plugin.ChannelName);
-            this._channelActivity$.next(plugin);
+            this.noteChannelActivity(plugin);
+            // A native tool whose result would show the agent what exposure policy withholds is refused here, as it is on the
+            // ContextTool route; the legacy tool-result shape carries the reason.
+            const withheld = plugin.FindVerbForNativeTool(toolName);
+            const refusal = withheld ? plugin.RefuseVerbForExposure(withheld) : null;
+            if (refusal) {
+                return JSON.stringify({ success: false, errorCode: 'exposure_restricted', error: refusal });
+            }
             return plugin.ApplyAgentTool(toolName, argsJson);
         });
     }
+    /** Records that the agent acted on a channel (the overlay's first-use reveal signal). */
+    noteChannelActivity(plugin) {
+        this.usedChannelNames.add(plugin.ChannelName);
+        this._channelActivity$.next(plugin);
+    }
+    /**
+     * Mounts an advertised `on-demand` channel when the agent opens it: initializes it, restores its
+     * prior-session state, publishes it on {@link ActiveChannels$} (so the overlay can give it a tab)
+     * and, if the call is already connected, tells it so. If initialization throws the channel goes
+     * back to being advertised, so the agent can retry or move on.
+     */
+    async mountAdvertisedChannel(plugin) {
+        const index = this.advertisedChannels.findIndex((p) => p.Plugin === plugin);
+        if (index < 0) {
+            return; // already mounted (or never advertised) — the dispatcher opens it regardless
+        }
+        const [prepared] = this.advertisedChannels.splice(index, 1);
+        try {
+            this.mountChannel(prepared, this.GetResolvedChannel(prepared.Key) ?? undefined);
+        }
+        catch (error) {
+            this.advertisedChannels.splice(index, 0, prepared);
+            throw error;
+        }
+        this.restorePriorChannelState(plugin);
+        this._activeChannels$.next([...this._activeChannels$.value, plugin]);
+        if (this.isSessionLive()) {
+            this.notifyChannelSessionStarted(plugin);
+        }
+    }
+    /** Tells a channel the session is connected, containing anything it throws. */
+    notifyChannelSessionStarted(channel) {
+        try {
+            channel.OnSessionStarted?.();
+        }
+        catch (err) {
+            console.error(`[RealtimeSession] Error in channel '${channel.ChannelName}' OnSessionStarted:`, err);
+        }
+    }
+    /** Finds a session channel (open or merely advertised) for the dispatcher. */
+    findDispatchableChannel(key) {
+        const id = NormalizeChannelKey(key);
+        const open = this._activeChannels$.value.find((c) => NormalizeChannelKey(c.ChannelName) === id);
+        if (open) {
+            return { Plugin: open, IsOpen: true };
+        }
+        const advertised = this.advertisedChannels.find((p) => NormalizeChannelKey(p.Key) === id);
+        return advertised ? { Plugin: advertised.Plugin, IsOpen: false } : null;
+    }
+    /** The keys the agent can address, for "unknown channel" messages — channels with nothing to address are left out. */
+    listAddressableChannelKeys() {
+        const addressable = (plugin) => {
+            const descriptor = plugin.GetDescriptor();
+            return descriptor.Verbs.length > 0 || descriptor.Inputs !== undefined;
+        };
+        return [
+            ...this._activeChannels$.value.filter(addressable).map((c) => c.ChannelName),
+            ...this.advertisedChannels.filter((p) => addressable(p.Plugin)).map((p) => p.Key),
+        ];
+    }
+    /**
+     * Runs a channel-addressed `ContextTool` call (the {@link RealtimeChannelContext.DispatchContextAction}
+     * implementation): validates it, opens an `on-demand` channel when asked, runs the verb, and on
+     * success records the channel as used so the overlay reveals its tab. Never throws.
+     */
+    async dispatchContextAction(request) {
+        const result = await this.channelDispatcher.Dispatch(request);
+        if (result.Success) {
+            const channel = this.findDispatchableChannel(request.Target.Channel);
+            if (channel) {
+                this.noteChannelActivity(channel.Plugin);
+            }
+        }
+        return result;
+    }
+    /**
+     * Opens (and seeds) a channel from the HOST — the same path the agent's `open` action takes: the channel
+     * is mounted if it was only advertised, its `Inputs` schema validates `inputs`, and it announces itself to
+     * the model. A channel that is already open is re-seeded. Never throws; a refusal is a structured result.
+     *
+     * @param channelKey The channel to open (case-insensitive).
+     * @param inputs Seed inputs, validated against the channel's descriptor.
+     */
+    OpenChannel(channelKey, inputs = {}) {
+        return this.dispatchContextAction({ Target: { Channel: channelKey }, Action: 'open', Params: inputs });
+    }
+    /**
+     * Tells the model which channels exist and how to use them — rendered from the channels' own
+     * descriptors, so a new channel needs no prompt change. Sent ONCE, the first moment the control
+     * channel is usable — a context note sent before then is dropped, and `Connect` can resolve before the
+     * provider reports `listening`, so this runs at start and again on each state change until it has gone.
+     * A session whose only channels describe themselves through native tools sends nothing.
+     */
+    flushChannelCatalogNote() {
+        if (!this.catalogNotePending || !this.isSessionLive()) {
+            return;
+        }
+        this.catalogNotePending = false;
+        const entries = [
+            ...this._activeChannels$.value.map((plugin) => this.catalogEntry(plugin, true)),
+            ...this.advertisedChannels.map((p) => this.catalogEntry(p.Plugin, false)),
+        ];
+        const note = BuildChannelCatalogNote(entries);
+        if (note) {
+            this.SendContextNote(note);
+        }
+    }
+    /** One catalog entry: a channel's descriptor, whether it is open, and whether its tools were declared natively. */
+    catalogEntry(plugin, isOpen) {
+        const display = this.GetResolvedChannel(plugin.ChannelName)?.DisplayPolicy;
+        const descriptor = plugin.GetDescriptor();
+        const entry = {
+            Descriptor: descriptor,
+            IsOpen: isOpen,
+            HasNativeTools: isOpen && display !== undefined && DeclaresNativeTools(display) && plugin.GetToolDefinitions().length > 0,
+        };
+        if (CompareExposure(plugin.Exposure, descriptor.MaxExposure) < 0) {
+            entry.ExposureLimit = { Effective: plugin.Exposure, Ceiling: descriptor.MaxExposure, Reasons: [...plugin.ExposureReasons] };
+        }
+        return entry;
+    }
     /** Builds the host-services context one channel plugin sees (its only line to the session). */
-    buildChannelContext(plugin) {
+    buildChannelContext(plugin, channelConfig) {
         // Capture the service in a local so the AgentSessionID getter reads the SERVICE's live
         // field (not the object literal's `this`) every time it's accessed.
         const service = this;
@@ -1275,55 +3019,107 @@ export class RealtimeSessionRuntime {
             // (Explorer) feeds both; absent on hosts that supply no app context / register no client tools.
             AppContext$: this.AppContext$,
             ExecuteClientTool: (name, params) => this.executeAppClientTool(name, params),
+            // The session's server events (identity verification, app events), for a channel that reacts to them.
+            SessionEvents$: this.SessionEvents$,
+            // Channel-addressed ContextTool calls: validated against the verb's schema, open `on-demand` channels.
+            DispatchContextAction: (request) => this.dispatchContextAction(request),
+            // This channel's resolved configuration (host defaults beneath agent/app config).
+            ChannelConfig: channelConfig ?? {},
             get Client() {
                 return service.client;
             },
-            SendVideoFrame: (base64Image, mimeType) => this.SendVideoFrame(base64Image, mimeType),
-            IsTrackEstablished: (modality, direction) => this.IsTrackEstablished(modality, direction)
+            // Through the arbiter, as this channel's source (deprecated: channels use a ChannelInboundVideoBridge).
+            SendVideoFrame: (base64Image, mimeType) => this.sendChannelVideoFrame(plugin, base64Image, mimeType),
+            IsTrackEstablished: (modality, direction) => this.IsTrackEstablished(modality, direction),
+            // The camera and screen share, for a channel that fronts one: their state, and the user's clicks on its surface.
+            Captures$: this.Captures$,
+            StartCapture: (kind) => (kind === 'camera' ? this.StartCamera() : this.StartScreenShare()),
+            StopCapture: (kind) => (kind === 'camera' ? this.StopCamera() : this.StopScreenShare()),
+            // The video sources and which of them the model is sent, so a capture's channel says the agent sees it only then.
+            VideoSources$: this.VideoSources$,
+            // The agent's video, the call's state and its resumes, for a channel that shows the agent.
+            AgentVideo$: this.AgentVideo$,
+            ConnectionState$: this.ConnectionState$,
+            Resuming$: this.Resuming$
         };
     }
     /**
-     * Replaces the set of host-registered surface client tools the realtime ContextTool can execute.
-     * The host calls this at session start and whenever the active surface's tool set changes (the
-     * continuous-capability half of client-context delivery). Passing `[]` clears them.
+     * Registers the tools ONE source of the host can run for the realtime `ContextTool`, replacing only
+     * that source's previous set — other owners' tools are untouched. A host with two sources (Explorer's
+     * always-available globals and the active surface's tools) registers each under its own owner key, so
+     * refreshing the surface's tools can neither drop the globals nor leave the previous surface's tools
+     * behind. Passing `[]` clears just that owner. When two owners register the same tool name, the
+     * later-registered owner wins.
      *
-     * @param tools The current surface client tools (name + handler). Descriptions/schemas ride the
-     *   app-context manifest separately; only the executable handler is needed here.
+     * Calling it with one argument (the original form) registers under {@link DEFAULT_APP_TOOL_OWNER}, so
+     * a host with a single source behaves exactly as before.
+     *
+     * @param tools The owner's complete current set (name + handler; description/schema optional).
+     * @param owner A stable key naming the source (e.g. `'explorer.surface'`). Defaults to a shared owner.
      */
-    RegisterAppClientTools(tools) {
-        this.appClientToolHandlers.clear();
-        for (const tool of tools) {
-            if (tool?.Name && typeof tool.Handler === 'function') {
-                this.appClientToolHandlers.set(tool.Name.trim().toLowerCase(), tool.Handler);
-            }
-        }
+    RegisterAppClientTools(tools, owner = DEFAULT_APP_TOOL_OWNER) {
+        this.appToolRegistry.Register(owner, tools);
+    }
+    /** Removes one owner's tools (and its place in the collision order). No-op when it has none. */
+    UnregisterAppClientTools(owner) {
+        this.appToolRegistry.Unregister(owner);
+    }
+    /** Removes every owner's tools. */
+    ClearAppClientTools() {
+        this.appToolRegistry.Clear();
+    }
+    /**
+     * The client tools in effect right now, resolved through the same unified resolver the server uses
+     * (`override → session → app → static`, first match wins): the host's registered tools (described
+     * by the manifest the host streams when it did not describe them itself) first, then the app and
+     * agent tiers the server resolved at mint. Only the host-registered tools can RUN here; the
+     * other tiers describe what the app declares.
+     */
+    resolveAppClientTools() {
+        const manifest = this._appContext$.value?.Capabilities?.Tools ?? [];
+        return ResolveClientTools({
+            agentId: '',
+            sessionTools: MergeToolMetadata(this.appToolRegistry.ToMetadata(), manifest),
+            appTools: this.sessionClientTools?.App,
+            staticTools: this.sessionClientTools?.Static,
+        });
     }
     /**
      * Executes a host-registered surface client tool by name (the {@link RealtimeChannelContext.ExecuteClientTool}
      * implementation). Tolerant: an unknown tool or a thrown handler resolves to a structured
-     * `Success: false` result the channel narrates — never throws.
+     * `Success: false` result the channel narrates — never throws. A tool the app declares but the host has
+     * not registered a handler for says so, instead of reading like a typo. A handler that returns an object with
+     * `Success: false` also gives `Success: false`, with the handler's `ErrorMessage` and its object as `Result`.
      *
      * @param name The tool name (the model's `action`).
      * @param params The tool parameters.
      * @returns A structured result for the channel to serialize back to the model.
      */
     async executeAppClientTool(name, params) {
-        const handler = this.appClientToolHandlers.get((name ?? '').trim().toLowerCase());
+        const handler = this.appToolRegistry.Find(name)?.Handler;
         if (!handler) {
-            const available = Array.from(this.appClientToolHandlers.keys()).join(', ');
-            return {
-                Success: false,
-                ErrorMessage: `No client tool named "${name}" is available on this surface. Available: ${available || '(none)'}.`
-            };
+            return { Success: false, ErrorMessage: this.describeMissingClientTool(name) };
         }
         try {
             const result = await handler(params ?? {});
-            return { Success: true, Result: result };
+            return reportsFailure(result)
+                ? { Success: false, ErrorMessage: failureMessage(result), Result: result }
+                : { Success: true, Result: result };
         }
         catch (error) {
             return { Success: false, ErrorMessage: error instanceof Error ? error.message : String(error) };
         }
     }
+    /** The model-readable reason a client tool could not run. */
+    describeMissingClientTool(name) {
+        const available = this.appToolRegistry.Names().join(', ');
+        const wanted = (name ?? '').trim().toLowerCase();
+        const declared = this.resolveAppClientTools().find((t) => t.Name.trim().toLowerCase() === wanted);
+        if (declared) {
+            return `The client tool "${name}" is declared for this app but this surface has not registered it, so it cannot run right now. Available: ${available || '(none)'}.`;
+        }
+        return `No client tool named "${name}" is available on this surface. Available: ${available || '(none)'}.`;
+    }
     /**
      * Runs a channel-specific GraphQL operation through the live session's provider (the
      * {@link RealtimeChannelContext.ExecuteServerAction} implementation). Best-effort: any
@@ -1360,35 +3156,39 @@ export class RealtimeSessionRuntime {
      * never affected.
      */
     applyPriorChannelStates(statesJson) {
+        this.priorChannelStates = {};
         if (!statesJson) {
             return;
         }
-        let states;
         try {
             const parsed = JSON.parse(statesJson);
             if (parsed === null || typeof parsed !== 'object') {
                 return;
             }
-            states = parsed;
+            this.priorChannelStates = parsed;
         }
         catch {
             console.warn('[RealtimeSession] PriorChannelStatesJson was malformed — starting channels fresh');
             return;
         }
         for (const plugin of this._activeChannels$.value) {
-            const state = states[plugin.ChannelName];
-            if (typeof state === 'string' && state.length > 0) {
-                try {
-                    const restored = plugin.RestoreState(state);
-                    if (!restored) {
-                        console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' declined its prior-session state — starting fresh`);
-                    }
-                }
-                catch (error) {
-                    console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' restore threw — starting fresh`, error);
-                }
+            this.restorePriorChannelState(plugin);
+        }
+    }
+    /** Offers one plugin its prior-session state, if there is one. Rejections and throws are logged, never fatal. */
+    restorePriorChannelState(plugin) {
+        const state = this.priorChannelStates[plugin.ChannelName];
+        if (typeof state !== 'string' || state.length === 0) {
+            return;
+        }
+        try {
+            if (!plugin.RestoreState(state)) {
+                console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' declined its prior-session state — starting fresh`);
             }
         }
+        catch (error) {
+            console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' restore threw — starting fresh`, error);
+        }
     }
     /**
      * Persists a channel's state as a first-class versioned artifact (`MJ: Artifacts`) via the
@@ -1478,6 +3278,13 @@ export class RealtimeSessionRuntime {
             this._activeChannels$.next([]);
         }
         this.usedChannelNames.clear();
+        // Channels that were prepared or advertised but never mounted were never initialized, so there is
+        // nothing to dispose — only the bookkeeping to forget.
+        this.discardUnmountedChannels();
+        this.catalogNotePending = false;
+        this.resolvedChannels.clear();
+        this.priorChannelStates = {};
+        this.sessionClientTools = null;
     }
     // ── Realtime client resolution + wiring ────────────────────────────────────
     /**
@@ -1500,12 +3307,14 @@ export class RealtimeSessionRuntime {
     }
     /**
      * Builds the client-direct session config the realtime client connects with.
-     * Aggregates tracks sourced by active channels under {@link REQUESTED_TRACKS_SESSION_KEY} so the driver
-     * can negotiate them (e.g., establishing inbound video streaming for Whiteboard / RemoteBrowser).
+     * Aggregates the tracks active channels source and sink under {@link REQUESTED_TRACKS_SESSION_KEY} so the
+     * driver can negotiate them (e.g., inbound video for Whiteboard / RemoteBrowser, outbound video for a
+     * channel that shows the agent's video). A track the model does not support resolves to `'unsupported'`.
+     * The session's transport and relay URL go to the driver as minted (an unknown transport is left out: direct).
      */
     BuildClientConfig(session) {
         const sessionConfig = this.parseSessionConfig(session.SessionConfigJson);
-        const channelTracks = this._activeChannels$.value.flatMap((c) => c.GetSourcedTracks());
+        const channelTracks = this._activeChannels$.value.flatMap((c) => [...c.GetSourcedTracks(), ...c.GetSunkTracks()]);
         if (channelTracks.length > 0) {
             // The requested tracks cross a JSON boundary — the driver reads them back out of the session
             // config bag (`GeminiRealtimeClient.parseSessionConfig`). A `RealtimeTrackDescriptor` is NOT
@@ -1530,11 +3339,14 @@ export class RealtimeSessionRuntime {
             }
             sessionConfig[REQUESTED_TRACKS_SESSION_KEY] = Array.from(trackMap.values());
         }
+        const transport = ParseRealtimeClientTransport(session.Transport);
         return {
             Provider: session.Provider,
             Model: session.Model,
             EphemeralToken: session.EphemeralToken,
             ExpiresAt: session.ExpiresAt,
+            ...(transport ? { Transport: transport } : {}),
+            ...(session.RelayUrl ? { RelayUrl: session.RelayUrl } : {}),
             SessionConfig: sessionConfig
         };
     }
@@ -1570,6 +3382,9 @@ export class RealtimeSessionRuntime {
         });
         client.OnError((error) => {
             console.error('[RealtimeSession] Provider error event:', JSON.stringify(error), error);
+            if (error.Fatal && this.client === client) {
+                this.lastSessionError = error;
+            }
         });
         // Usage telemetry: accumulate the driver's per-response token DELTAS and relay them to
         // the server (onto the co-agent AIPromptRun) debounced + once at teardown. Providers
@@ -1586,12 +3401,41 @@ 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));
+    }
+    /**
+     * The model's video arrived: publish it on {@link AgentVideo$}, and mark each channel that shows it (one that sinks
+     * outbound video) as used, so the host shows its surface. A client the session has already let go of is ignored, so a
+     * late frame cannot bring the video back after the call.
+     */
+    onAgentVideo(client, video) {
+        if (this.client !== client) {
+            return;
+        }
+        this._agentVideo$.next(video);
+        for (const channel of this._activeChannels$.value) {
+            if (channel.ShowsAgentVideo) {
+                this.noteChannelActivity(channel);
+            }
+        }
+    }
+    /** Clears {@link AgentVideo$} when the call's client goes. */
+    clearAgentVideo() {
+        if (this._agentVideo$.value !== null) {
+            this._agentVideo$.next(null);
+        }
     }
     /** Maps a client state event onto the UI connection state. */
     onClientStateChange(state) {
         const mapped = this.mapClientState(state);
         if (mapped) {
-            this._connectionState$.next(mapped);
+            this.setConnectionState(mapped);
+            this.flushChannelCatalogNote();
         }
     }
     /**
@@ -1620,6 +3464,17 @@ export class RealtimeSessionRuntime {
         const state = this._connectionState$.value;
         return state === 'listening' || state === 'speaking' || state === 'thinking';
     }
+    /**
+     * Moves {@link ConnectionState$} to `state`, and {@link Resuming$} first: a `'connecting'` while the call is live, or
+     * already resuming, is a resume; any other state ends one. Every state change goes through here.
+     */
+    setConnectionState(state) {
+        const resuming = state === 'connecting' && (this._resuming$.value || this.isSessionLive());
+        if (resuming !== this._resuming$.value) {
+            this._resuming$.next(resuming);
+        }
+        this._connectionState$.next(state);
+    }
     // ── Transcript policy ──────────────────────────────────────────────────────
     /**
      * Applies transcript policy to client transcript events. Interim deltas don't become
@@ -1653,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 = '';
@@ -1727,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') {
@@ -1744,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));
@@ -1776,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;
         }
@@ -1786,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 ───────────────────────────────────────────────────────────
     /**
@@ -1809,7 +3697,7 @@ export class RealtimeSessionRuntime {
             void this.relayToolTurn(call.ToolName, call.ArgumentsJson, resultJson);
             return;
         }
-        this._connectionState$.next('thinking');
+        this.setConnectionState('thinking');
         if (this.inFlightCallIds.size === 0) {
             // A fresh delegation burst: anchor the first-update delay and clear the digest
             // buffer. Deliberately NOT reset: lastDelegationNarrationAt (the 8s spacing floor
@@ -1906,6 +3794,40 @@ export class RealtimeSessionRuntime {
             RunID: parsed.RunID,
             Artifacts: parsed.Artifacts
         });
+        if (parsed.Success && parsed.Artifacts && parsed.Artifacts.length > 0) {
+            void this.offerDelegationArtifacts(parsed.Artifacts);
+        }
+    }
+    /**
+     * Offers a delegated run's artifacts to the channels that host artifacts (an Interactive Component channel
+     * shows a component artifact, or swaps in a newer version of one it already shows). Each channel is asked
+     * first whether it wants them; an advertised, unopened channel that does is mounted before it is handed
+     * them. One channel failing never stops the others, and nothing here can fail the delegation result,
+     * which has already been emitted.
+     */
+    async offerDelegationArtifacts(artifacts) {
+        const candidates = [
+            ...this._activeChannels$.value.map((plugin) => ({ Plugin: plugin, IsOpen: true })),
+            ...this.advertisedChannels.map((prepared) => ({ Plugin: prepared.Plugin, IsOpen: false }))
+        ];
+        for (const { Plugin: plugin, IsOpen: isOpen } of candidates) {
+            try {
+                const config = this.GetResolvedChannel(plugin.ChannelName)?.Config ?? {};
+                if (!plugin.AcceptsDelegationArtifacts(artifacts, config)) {
+                    continue;
+                }
+                if (!isOpen) {
+                    await this.mountAdvertisedChannel(plugin);
+                }
+                await plugin.OnDelegationArtifacts(artifacts);
+                if (!isOpen) {
+                    this.noteChannelActivity(plugin); // the channel was mounted for this: reveal its tab
+                }
+            }
+            catch (error) {
+                console.error(`[RealtimeSession] Channel '${plugin.ChannelName}' failed to take a delegated run's artifacts:`, error);
+            }
+        }
     }
     // ── Explicit delegation cancellation (server cancel channel) ───────────────
     /**
@@ -1996,44 +3918,34 @@ export class RealtimeSessionRuntime {
         }
     }
     // ── Session minting (GraphQL) ──────────────────────────────────────────────
-    /** Calls the `StartRealtimeClientSession` mutation to obtain an ephemeral token + config. */
-    async mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, recordingStartedAt, mediaCollectionId, applicationId, appContext) {
-        const mutation = `
-      mutation StartRealtimeClientSession($targetAgentId: String!, $conversationId: String, $lastSessionId: String, $preferredModelId: String, $clientToolsJson: String, $coAgentId: String, $configOverridesJson: String, $recordingConsent: Boolean, $recordingStartedAt: String, $mediaCollectionId: String, $applicationId: String, $appContextJson: String) {
-        StartRealtimeClientSession(targetAgentId: $targetAgentId, conversationId: $conversationId, lastSessionId: $lastSessionId, preferredModelId: $preferredModelId, clientToolsJson: $clientToolsJson, coAgentId: $coAgentId, configOverridesJson: $configOverridesJson, recordingConsent: $recordingConsent, recordingStartedAt: $recordingStartedAt, mediaCollectionId: $mediaCollectionId, applicationId: $applicationId, appContextJson: $appContextJson) {
-          AgentSessionId
-          ConversationId
-          Provider
-          Model
-          EphemeralToken
-          ExpiresAt
-          SessionConfigJson
-          ModelName
-          NarrationInstructionsTemplate
-          PriorChannelStatesJson
-        }
-      }
-    `;
-        const variables = {
-            targetAgentId,
-            conversationId: conversationId ?? null,
-            lastSessionId: lastSessionId ?? null,
-            preferredModelId: preferredModelId ?? null,
-            clientToolsJson: clientTools && clientTools.length > 0 ? JSON.stringify(clientTools) : null,
-            coAgentId: coAgentId ?? null,
-            configOverridesJson: configOverridesJson ?? null,
-            recordingConsent: recordingConsent ?? false,
-            recordingStartedAt: recordingStartedAt ?? null,
-            mediaCollectionId: mediaCollectionId ?? null,
-            applicationId: applicationId ?? null,
-            appContextJson: appContext ? JSON.stringify(appContext) : null
-        };
-        const result = await this.gql().ExecuteGQL(mutation, variables);
-        const payload = result?.StartRealtimeClientSession;
-        if (!payload?.EphemeralToken) {
-            throw new Error('StartRealtimeClientSession returned no ephemeral token');
-        }
-        return payload;
+    /**
+     * Mints a session through the installed {@link Launcher} — by default the stock
+     * `StartRealtimeClientSession` mutation (see {@link DefaultRealtimeSessionLauncher}). `showsAgentVideo` is whether
+     * one of the session's channels could show the agent's video; without one the server asks the model for no avatar.
+     * `conversationBranchId` is the fork the session starts on; `null` is Main.
+     */
+    async mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, recordingStartedAt, mediaCollectionId, applicationId, appContext, channelCandidatesJson, showsAgentVideo, conversationBranchId) {
+        const result = await this._launcher.Launch({
+            TargetAgentId: targetAgentId,
+            ConversationId: conversationId ?? null,
+            LastSessionId: lastSessionId ?? null,
+            PreferredModelId: preferredModelId ?? null,
+            ClientTools: clientTools ?? [],
+            CoAgentId: coAgentId ?? null,
+            ConfigOverridesJson: configOverridesJson ?? null,
+            RecordingConsent: recordingConsent ?? false,
+            RecordingStartedAt: recordingStartedAt ?? null,
+            MediaCollectionId: mediaCollectionId ?? null,
+            ApplicationId: applicationId ?? null,
+            AppContext: appContext ?? null,
+            ChannelCandidatesJson: channelCandidatesJson ?? null,
+            ConversationBranchId: conversationBranchId ?? null,
+            ...(showsAgentVideo === undefined ? {} : { ShowsAgentVideo: showsAgentVideo })
+        }, { Provider: this.Provider });
+        if (!HasClientCredential(result)) {
+            throw new Error('The session launcher returned no ephemeral token (or, for a relay session, no relay URL)');
+        }
+        return result;
     }
     /** Calls the `ExecuteRealtimeSessionTool` mutation; returns the ResultJson string. */
     async executeSessionTool(callId, toolName, argsJson) {
@@ -2090,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 = `
@@ -2172,16 +4118,28 @@ export class RealtimeSessionRuntime {
     /**
      * Accumulates one usage DELTA from the realtime client (per-response token counts —
      * the `OnUsage` contract shape) and schedules the debounced relay. Negative / non-finite
-     * values are clamped to 0; an all-zero delta is dropped without arming the timer.
+     * values are clamped to 0; an all-zero delta is dropped without arming the timer. The
+     * update's input and output detail blocks add into the pending details by the record's
+     * rules (amounts add up, inbound video running totals keep the larger value), so an update
+     * that carries only avatar video seconds still counts.
      */
     onUsageDelta(usage) {
         const input = this.clampUsageDelta(usage.InputTokens);
         const output = this.clampUsageDelta(usage.OutputTokens);
-        if (input === 0 && output === 0) {
+        const details = AddRealtimeUsageRecord(null, { Input: usage.InputTokenDetails, Output: usage.OutputTokenDetails });
+        const hasDetails = HasRealtimeUsage(details);
+        if (input === 0 && output === 0 && !hasDetails) {
             return;
         }
         this.pendingUsageInput += input;
         this.pendingUsageOutput += output;
+        if (hasDetails) {
+            this.pendingUsageDetails = AddRealtimeUsageRecord(this.pendingUsageDetails, details);
+        }
+        this.armUsageFlush();
+    }
+    /** Schedules the debounced usage relay unless one is already pending. */
+    armUsageFlush() {
         if (!this.usageFlushTimer) {
             this.usageFlushTimer = setTimeout(() => {
                 this.usageFlushTimer = null;
@@ -2206,24 +4164,26 @@ export class RealtimeSessionRuntime {
         const sessionId = agentSessionId ?? this.agentSessionId;
         const input = this.pendingUsageInput;
         const output = this.pendingUsageOutput;
-        if (!sessionId || (input === 0 && output === 0)) {
+        const details = this.pendingUsageDetails;
+        if (!sessionId || (input === 0 && output === 0 && !details)) {
             return;
         }
         this.pendingUsageInput = 0;
         this.pendingUsageOutput = 0;
+        this.pendingUsageDetails = null;
         try {
-            const mutation = `
-        mutation RelayRealtimeUsage($agentSessionId: String!, $inputTokens: Int!, $outputTokens: Int!) {
-          RelayRealtimeUsage(agentSessionId: $agentSessionId, inputTokens: $inputTokens, outputTokens: $outputTokens)
-        }
-      `;
-            await this.gql().ExecuteGQL(mutation, { agentSessionId: sessionId, inputTokens: input, outputTokens: output });
+            // The details argument is sent only when there are details, so a token-only relay is unchanged.
+            const variables = { agentSessionId: sessionId, inputTokens: input, outputTokens: output, ...(details ? { usageDetailsJson: JSON.stringify(details) } : {}) };
+            await this.gql().ExecuteGQL(RELAY_REALTIME_USAGE_MUTATION, variables);
         }
         catch (error) {
             console.error('[RealtimeSession] Failed to relay usage telemetry:', error);
             // Re-accumulate so a later debounce / the teardown flush retries the same deltas.
             this.pendingUsageInput += input;
             this.pendingUsageOutput += output;
+            if (details) {
+                this.pendingUsageDetails = AddRealtimeUsageRecord(this.pendingUsageDetails, details);
+            }
         }
     }
     /** Cancels the pending debounced usage flush and zeroes the accumulators (teardown tail). */
@@ -2234,6 +4194,7 @@ export class RealtimeSessionRuntime {
         }
         this.pendingUsageInput = 0;
         this.pendingUsageOutput = 0;
+        this.pendingUsageDetails = null;
     }
     // ── Delegated-run progress streaming ───────────────────────────────────────
     /**
@@ -2513,43 +4474,70 @@ export class RealtimeSessionRuntime {
             return;
         }
         this.teardownInFlight = this.runTeardown(closeServerSession).finally(() => {
+            if (this._savingRecording$.value) {
+                this._savingRecording$.next(false);
+            }
             this.teardownInFlight = null;
         });
         await this.teardownInFlight;
     }
     /** The body of {@link teardown}; never called concurrently with itself. */
     async runTeardown(closeServerSession) {
+        // Arm BEFORE any await so a tab closed in the first milliseconds of teardown is still guarded.
+        if (this.recorder) {
+            this._savingRecording$.next(true);
+        }
         // First: stop asserting liveness. A pulse racing the close would re-stamp LastActiveAt on a
         // session we are deliberately ending, leaving an Idle row the janitor then has to age out.
         this.stopLivenessPulse();
         this.teardownDelegationProgress();
+        this.stopSessionEvents();
+        this.clientDeadline.Clear();
         // Channels first: flush any unsaved channel state WHILE the live session id is still
         // 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
         // tracks it was handed — track.stop() is idempotent).
+        this.closeLocalMedia();
         this.localStream?.getTracks().forEach(t => t.stop());
         this.localStream = null;
-        // Hand the platform back whatever acquiring the microphone changed. Stopping the tracks is not
+        this.microphoneMuted = false;
+        // Hand the platform back whatever opening the microphone changed. Stopping the tracks is not
         // the same thing: iOS, for instance, is put into a record-and-play audio category for the call,
         // and leaving it there changes the route and volume behaviour of every sound the app makes
-        // afterwards. Best-effort by contract — a failure here must never block ending a call.
-        try {
-            await this.mediaHost.ReleaseMicrophone?.();
-        }
-        catch (error) {
-            console.error('[RealtimeSession] Media host failed to release the microphone:', error);
+        // afterwards. A microphone still opening is left to its start, which releases it once the
+        // opening returns ({@link microphoneLease}).
+        const lease = this.microphoneLease;
+        if (lease && !lease.Opening) {
+            this.microphoneLease = null;
+            await this.releaseMicrophone();
         }
         if (this.client) {
-            await this.client.Disconnect();
-            this.client = null;
+            // A stranded Active session is worse than a noisy socket: a driver that throws on Disconnect
+            // (socket already gone) must not stop the server session from being closed below.
+            try {
+                await this.client.Disconnect();
+            }
+            catch (error) {
+                console.error(`[RealtimeSession] Driver failed to disconnect (session ${this.agentSessionId}); continuing teardown:`, error);
+            }
+            finally {
+                this.unwatchVideoSources();
+                this.clearAgentVideo();
+                this.client = null;
+            }
         }
-        // Stop + upload the call recording WHILE the live session id is still set (the file is
-        // attached to it). Best-effort and never blocks teardown — stopAndUploadRecording swallows
-        // its own errors. No-op when nothing was recorded.
-        await this.stopAndUploadRecording(this.agentSessionId);
-        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) {
@@ -2561,18 +4549,28 @@ export class RealtimeSessionRuntime {
         if (closeServerSession && this.agentSessionId) {
             await this.closeServerSession(this.agentSessionId);
         }
+        // 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).
         const closedSessionId = this.agentSessionId;
         this.agentSessionId = null;
+        this.sessionConversationId = null;
         this.narrationTemplate = null;
         this.clientToolHandlers.clear();
         this._modelName$.next(null);
+        if (this._avatarNotice$.value !== null) {
+            this._avatarNotice$.next(null);
+        }
         this.SetMinimized(false);
         this._active$.next(false);
         if (this._connectionState$.value !== 'error') {
-            this._connectionState$.next('closed');
+            this.setConnectionState('closed');
         }
         // Surface generic session-ended for the conversations runtime bridge.
         // `closeServerSession=true` means the user explicitly called EndRealtimeSession;
@@ -2584,6 +4582,18 @@ export class RealtimeSessionRuntime {
             });
         }
     }
+    /**
+     * 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.
+     */
+    async releaseMicrophone() {
+        try {
+            await this.mediaHost.ReleaseMicrophone?.();
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Media host failed to release the microphone:', error);
+        }
+    }
     /** Calls the `CloseAgentSession` mutation (provisioned in P4b). */
     async closeServerSession(agentSessionId) {
         try {
@@ -2609,13 +4619,18 @@ export class RealtimeSessionRuntime {
         this.pendingUserCaption = '';
         this.hasActiveInterimUserCaption = false;
         this.SetMinimized(false);
-        this.stopSegmentFlushing();
-        this.segmentIndex = 0;
+        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;
     }
     /** The GraphQL provider used for relay mutations. */
     gql() {