@opengeni/react 1.4.0 → 1.4.4

package/src/hooks/use-goal.ts

@@ -84,6 +84,9 @@ export function useGoal(
   const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
   const generation = useRef(0);
   const targetKeyRef = useRef<string | null>(null);
+  // True after the server answered 404. Only a goal event can create a goal,
+  // so turn/session traffic must not refetch (and 404) while none exists.
+  const goalAbsentRef = useRef(false);
   const loadAbort = useRef<AbortController | null>(null);
 
   const retireLoads = useCallback(() => {
@@ -105,6 +108,7 @@ export function useGoal(
         signal: controller.signal,
       });
       if (ticket === generation.current) {
+        goalAbsentRef.current = false;
         setGoal(fetched);
         setError(null);
         setLoading(false);
@@ -115,6 +119,7 @@ export function useGoal(
       }
       if (cause instanceof OpenGeniApiError && cause.status === 404) {
         // No goal is a normal state, not an error.
+        goalAbsentRef.current = true;
         setGoal(null);
         setError(null);
       } else {
@@ -130,6 +135,7 @@ export function useGoal(
     const targetKey = `${workspaceId} ${sessionId ?? ""}`;
     if (targetKeyRef.current !== targetKey) {
       targetKeyRef.current = targetKey;
+      goalAbsentRef.current = false;
       setGoal(null);
       setError(null);
     }
@@ -181,7 +187,12 @@ export function useGoal(
   ]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
-  useSessionEventTrigger(client, workspaceId, sessionId, isGoalRefreshEvent, scheduleRefresh, {
+  const isRefreshEvent = useCallback(
+    (event: SessionEvent) =>
+      goalAbsentRef.current ? isGoalEvent(event) : isGoalRefreshEvent(event),
+    [],
+  );
+  useSessionEventTrigger(client, workspaceId, sessionId, isRefreshEvent, scheduleRefresh, {
     enabled,
     ...(sharedEvents !== undefined ? { events: sharedEvents } : {}),
   });

package/src/hooks/use-realtime-voice-models.ts

@@ -0,0 +1,67 @@
+import type { WorkspaceRealtimeModelCatalogResponse } from "@opengeni/sdk";
+import { useEffect, useState } from "react";
+
+type CatalogClient = {
+  getWorkspaceRealtimeModelCatalog?: (
+    workspaceId: string,
+    options?: { signal?: AbortSignal | undefined },
+  ) => Promise<WorkspaceRealtimeModelCatalogResponse>;
+};
+
+type AvailableVoiceModels = WorkspaceRealtimeModelCatalogResponse["models"];
+
+const CACHE_TTL_MS = 60_000;
+const cache = new WeakMap<
+  object,
+  Map<string, { models: Promise<AvailableVoiceModels>; expiresAt: number }>
+>();
+
+function load(client: CatalogClient, workspaceId: string): Promise<AvailableVoiceModels> {
+  let byWorkspace = cache.get(client);
+  if (!byWorkspace) {
+    byWorkspace = new Map();
+    cache.set(client, byWorkspace);
+  }
+  const hit = byWorkspace.get(workspaceId);
+  if (hit && hit.expiresAt > Date.now()) return hit.models;
+  // A throwing structural client (one without voice) just means no voice.
+  const models = Promise.resolve()
+    .then(() => client.getWorkspaceRealtimeModelCatalog!(workspaceId))
+    .then((catalog) => catalog.models.filter((model) => model.available));
+  const entry = { models, expiresAt: Date.now() + CACHE_TTL_MS };
+  byWorkspace.set(workspaceId, entry);
+  models.catch(() => {
+    if (byWorkspace.get(workspaceId) === entry) byWorkspace.delete(workspaceId);
+  });
+  return models;
+}
+
+/**
+ * Voice models this user can start right now in the workspace, or an empty
+ * list while unknown, disabled, unsupported (older API or proxy), or failed.
+ * Availability is advisory; Opengeni still admits and meters every call.
+ */
+export function useRealtimeVoiceModels(
+  client: unknown,
+  workspaceId: string,
+  enabled: boolean,
+): AvailableVoiceModels {
+  const [models, setModels] = useState<AvailableVoiceModels>([]);
+  useEffect(() => {
+    setModels([]);
+    const catalogClient = client as CatalogClient;
+    if (!enabled || !workspaceId) return;
+    if (typeof catalogClient.getWorkspaceRealtimeModelCatalog !== "function") return;
+    let live = true;
+    load(catalogClient, workspaceId).then(
+      (available) => {
+        if (live) setModels(available);
+      },
+      () => undefined,
+    );
+    return () => {
+      live = false;
+    };
+  }, [client, workspaceId, enabled]);
+  return models;
+}

package/src/hooks/use-voice-input.ts

@@ -11,6 +11,7 @@ import {
 } from "../voice-recording-store";
 import {
   acquireDefaultVoiceRecordingOwnerLease,
+  liveVoiceRecordingOwnerIds,
   type VoiceRecordingOwnerLease,
 } from "../voice-recording-owner";
 import { appendFinalTranscript } from "./use-transcription";
@@ -65,6 +66,10 @@ export type UseVoiceInputResult = {
   stream: MediaStream | null;
   recordingId: string | null;
   durationSeconds: number;
+  /** Wall-clock start of the current capture (epoch ms), or null when not recording. */
+  recordingStartedAt: number | null;
+  /** Capture stops and transcribes automatically after this many seconds. */
+  maxRecordingSeconds: number | null;
   locallySaved: boolean;
   hasRecoverableRecording: boolean;
   savedTranscript: string | null;
@@ -75,7 +80,10 @@ export type UseVoiceInputResult = {
   retry: () => void;
   /** Explicitly insert a durably saved transcript whose prior handoff may be uncertain. */
   insertSavedTranscript: () => Promise<void>;
-  /** Cancel active work. A stopped/transcribing recording remains recoverable. */
+  /**
+   * Cancel active work without losing speech: a recording longer than a few
+   * seconds and any stopped/transcribing recording stay locally recoverable.
+   */
   cancel: () => void;
   /** Intentionally delete the current durable recording. */
   discard: () => Promise<void>;
@@ -85,6 +93,8 @@ export const VOICE_RECORDING_TIMESLICE_MILLISECONDS = 5_000;
 export const VOICE_RECORDING_OWNER_HEARTBEAT_MILLISECONDS = 5_000;
 export const VOICE_RECORDING_OWNER_STALE_MILLISECONDS = 30_000;
 export const VOICE_RECORDING_CLIENT_MAX_DURATION_SECONDS = 600;
+// Cancel deletes only an accidental start; anything longer is kept for the user.
+const VOICE_RECORDING_DISCARD_ON_CANCEL_MAX_MILLISECONDS = 3_000;
 export const VOICE_RECORDING_RESUMABLE_CLIENT_MAX_DURATION_SECONDS = 8 * 60 * 60;
 export const VOICE_RECORDING_RECOVERY_STATUS_POLL_MILLISECONDS = 2_000;
 export const VOICE_RECORDING_RECOVERY_MAX_MUTATION_DELAY_MILLISECONDS = 30_000;
@@ -159,6 +169,9 @@ export function useVoiceInput({
   const recorderRef = useRef<MediaRecorder | null>(null);
   const streamRef = useRef<MediaStream | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Cancel/Escape/voice takeover keep a real dictation instead of deleting it.
+  const holdOnStopRef = useRef(false);
+  const recordingStartedAtRef = useRef(0);
   const automaticRetryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const automaticRetryAttemptRef = useRef(0);
   const ownerHeartbeatTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -321,15 +334,31 @@ export function useVoiceInput({
         generation === generationRef.current && workspaceIdRef.current === workspaceId;
       const [store, ownerId] = await Promise.all([ensureStore(), ensureOwnerId()]);
       if (!active()) return;
-      const staleBefore = new Date(
+      const heartbeatStaleBefore = new Date(
         readNow().getTime() - VOICE_RECORDING_OWNER_STALE_MILLISECONDS,
       ).toISOString();
-      await store.cleanupHandedOffManifests({ ownerId, staleBefore }).catch(() => undefined);
+      await store
+        .cleanupHandedOffManifests({ ownerId, staleBefore: heartbeatStaleBefore })
+        .catch(() => undefined);
       if (!active()) return;
-      const manifests = await store.listRecoverableManifests(workspaceId, {
-        ownerId,
-        staleBefore,
-      });
+      // A closed or crashed tab releases its owner lock at once: recover its
+      // recording now rather than after the heartbeat window (the user who
+      // reopens the app right away must still see their dictation).
+      const liveOwners =
+        createOwnerIdRef.current === undefined ? await liveVoiceRecordingOwnerIds() : null;
+      if (!active()) return;
+      const staleBefore = liveOwners ? readNow().toISOString() : heartbeatStaleBefore;
+      const manifests = (
+        await store.listRecoverableManifests(workspaceId, { ownerId, staleBefore })
+      ).filter(
+        (manifest) =>
+          !liveOwners ||
+          !manifest.ownerId ||
+          manifest.ownerId === ownerId ||
+          !liveOwners.has(manifest.ownerId) ||
+          !manifest.ownerHeartbeatAt ||
+          manifest.ownerHeartbeatAt <= heartbeatStaleBefore,
+      );
       if (!active()) return;
       for (const candidate of manifests) {
         try {
@@ -353,14 +382,20 @@ export function useVoiceInput({
           }
           rememberManifest(claimed);
           beginOwnerHeartbeat(claimed);
+          const transcriptReady =
+            claimed.finalizationState === "transcript-ready" && claimed.transcriptText !== null;
           setStatus(
-            claimed.finalizationState === "transcript-ready" && claimed.transcriptText !== null
+            transcriptReady
               ? "transcript-ready"
               : claimed.recoveryMode === "automatic"
                 ? "retrying"
                 : "recovered",
           );
-          setError(null);
+          // An append-mode transcript may already be in the draft (the page
+          // closed between appending and recording the handoff).
+          setError(
+            transcriptReady && candidate.handoffMode === "append" ? "handoff_uncertain" : null,
+          );
           return;
         } catch (reason) {
           if (reason instanceof VoiceRecordingOwnedError) continue;
@@ -464,8 +499,9 @@ export function useVoiceInput({
 
         automaticRetryAttemptRef.current = 0;
         if (ready.handoffMode === "explicit") {
+          // Never appended: offer an explicit insert, not an "already inserted?" warning.
           setStatus("transcript-ready");
-          setError("handoff_uncertain");
+          setError(null);
           focusInput();
           return;
         }
@@ -824,6 +860,15 @@ export function useVoiceInput({
               await preserveForRetry(retained, attemptCaptureLimitError, generation);
               return;
             }
+            if (holdOnStopRef.current) {
+              holdOnStopRef.current = false;
+              const retained = await updateManifestBestEffort(stopped, {
+                recoveryMode: "manual",
+                handoffMode: "explicit",
+              });
+              await preserveForRetry(retained, null, generation);
+              return;
+            }
             await finalizePersistedRecording(generation);
           });
       };
@@ -832,6 +877,8 @@ export function useVoiceInput({
         resolveCaptureSettledRef.current = resolve;
       });
       attemptRecordingStartedAt = readNow().getTime();
+      recordingStartedAtRef.current = attemptRecordingStartedAt;
+      holdOnStopRef.current = false;
       recorder.start(VOICE_RECORDING_TIMESLICE_MILLISECONDS);
       recorderStarted = true;
       setStatus("recording");
@@ -1069,7 +1116,27 @@ export function useVoiceInput({
   ]);
 
   const cancel = useCallback(() => {
-    if (status === "recording" || status === "requesting-permission") {
+    if (status === "recording") {
+      const recorder = recorderRef.current;
+      const elapsed = readNow().getTime() - recordingStartedAtRef.current;
+      if (
+        recorder &&
+        recorder.state !== "inactive" &&
+        elapsed >= VOICE_RECORDING_DISCARD_ON_CANCEL_MAX_MILLISECONDS
+      ) {
+        // Never delete real speech on Cancel/Escape: stop, keep it locally, and
+        // let the user transcribe or explicitly discard it.
+        if (timerRef.current) clearTimeout(timerRef.current);
+        timerRef.current = null;
+        holdOnStopRef.current = true;
+        setStatus("saving");
+        recorder.stop();
+        return;
+      }
+      void discard();
+      return;
+    }
+    if (status === "requesting-permission") {
       void discard();
       return;
     }
@@ -1093,7 +1160,7 @@ export function useVoiceInput({
         await preserveForRetry(retained, null, generation);
       });
     }
-  }, [discard, preserveForRetry, status, updateManifestBestEffort]);
+  }, [discard, preserveForRetry, readNow, status, updateManifestBestEffort]);
 
   useEffect(() => {
     const current = manifestRef.current;
@@ -1156,6 +1223,8 @@ export function useVoiceInput({
     const onKeyDown = (event: KeyboardEvent) => {
       if (
         event.key === "Escape" &&
+        // A dialog, menu, or popover that handled Escape owns it.
+        !event.defaultPrevented &&
         (status === "requesting-permission" ||
           status === "recording" ||
           status === "saving" ||
@@ -1179,6 +1248,19 @@ export function useVoiceInput({
       automaticRetryTimerRef.current = null;
       const manifest = manifestRef.current;
       const ownerReady = ownerIdPromiseRef.current;
+      const knownOwnerId = ownerIdRef.current;
+      const ownerLease = ownerLeaseRef.current;
+      const closingStore = storeRef.current;
+      const ownsClosingStore = ownsStoreRef.current;
+      // Detach synchronously: a remount of this instance (React StrictMode,
+      // keyed re-render) must open a fresh store and owner instead of reusing
+      // the connection this cleanup is about to close.
+      storeRef.current = null;
+      storePromiseRef.current = null;
+      ownerIdRef.current = null;
+      ownerIdPromiseRef.current = null;
+      ownerLeaseRef.current = null;
+      manifestRef.current = null;
       stopOwnerHeartbeat();
       const recorder = recorderRef.current;
       let captureSettled = persistenceQueueRef.current;
@@ -1190,9 +1272,8 @@ export function useVoiceInput({
       void captureSettled
         .catch(() => undefined)
         .then(async () => {
-          const ownerId =
-            ownerIdRef.current ?? (ownerReady ? await ownerReady.catch(() => null) : null);
-          const store = storeRef.current;
+          const ownerId = knownOwnerId ?? (ownerReady ? await ownerReady.catch(() => null) : null);
+          const store = closingStore;
           if (store && manifest && ownerId) {
             const wasProcessing =
               statusRef.current === "saving" ||
@@ -1221,12 +1302,11 @@ export function useVoiceInput({
               )
               .catch(() => undefined);
           }
-          if (ownsStoreRef.current) await store?.close();
+          if (ownsClosingStore) await store?.close();
         })
         .catch(() => undefined)
         .finally(() => {
-          ownerLeaseRef.current?.release();
-          ownerLeaseRef.current = null;
+          ownerLease?.release();
         });
     },
     [clearCaptureRuntime, readNow, stopOwnerHeartbeat],
@@ -1239,6 +1319,17 @@ export function useVoiceInput({
     stream,
     recordingId,
     durationSeconds,
+    recordingStartedAt: status === "recording" ? recordingStartedAtRef.current || null : null,
+    maxRecordingSeconds: capability
+      ? Math.min(
+          capability.resumable && isResumableVoiceInputClient(client)
+            ? capability.resumable.maxDurationSeconds
+            : capability.maxDurationSeconds,
+          capability.resumable && isResumableVoiceInputClient(client)
+            ? VOICE_RECORDING_RESUMABLE_CLIENT_MAX_DURATION_SECONDS
+            : VOICE_RECORDING_CLIENT_MAX_DURATION_SECONDS,
+        )
+      : null,
     locallySaved,
     hasRecoverableRecording: manifestRef.current !== null && status !== "recording",
     savedTranscript:

package/src/realtime/embedded-voice.tsx

@@ -0,0 +1,81 @@
+import type { EffectiveSessionControl, SessionEvent, SessionStatus } from "@opengeni/sdk";
+import { projectSessionRealtimeLifecycle } from "@opengeni/sdk/realtime";
+import { useEffect, useMemo, useState } from "react";
+
+import {
+  RealtimeVoiceControl,
+  useSessionRealtime,
+  type RealtimeModelOption,
+} from "./realtime-control";
+
+/**
+ * The stock conversation's live voice button (lazy chunk). The conversation
+ * mounts it only when the workspace catalog offers an available voice model;
+ * this owns choosing among those models and the call itself.
+ */
+export default function EmbeddedRealtimeVoice(props: {
+  /** The conversation's client, which serves the realtime routes (or a proxy of them). */
+  client: unknown;
+  workspaceId: string;
+  /** Available voice models, already filtered by the conversation. */
+  models: readonly RealtimeModelOption[];
+  sessionId: string;
+  sessionStatus: SessionStatus;
+  effectiveControl: EffectiveSessionControl;
+  events: SessionEvent[];
+  eventsReady: boolean;
+  onVoiceActiveChange?: ((active: boolean) => void) | undefined;
+}) {
+  const lifecycle = useMemo(() => projectSessionRealtimeLifecycle(props.events), [props.events]);
+  // A call already running (this browser after reload, or another one) fixes the model.
+  const activeModel =
+    lifecycle?.state === "active" && !(Date.parse(lifecycle.leaseExpiresAt) <= Date.now())
+      ? lifecycle.model
+      : null;
+  const [chosen, setChosen] = useState<string | null>(null);
+  const fallback = props.models.find((model) => model.recommended) ?? props.models[0]!;
+  const selected =
+    props.models.find((model) => model.id === (activeModel ?? chosen)) ??
+    (activeModel ? { ...fallback, id: activeModel } : fallback);
+  const realtime = useSessionRealtime({
+    client: props.client as Parameters<typeof useSessionRealtime>[0]["client"],
+    workspaceId: props.workspaceId,
+    sessionId: props.sessionId,
+    sessionStatus: props.sessionStatus,
+    effectiveControl: props.effectiveControl,
+    events: props.events,
+    eventsReady: props.eventsReady,
+    codexConnected: false,
+    model: selected.id,
+    modelAvailable: selected.available,
+    modelUnavailableReason: selected.unavailableReason,
+  });
+  const voiceActive = realtime.snapshot.mode?.state === "active";
+  const onVoiceActiveChange = props.onVoiceActiveChange;
+  useEffect(() => {
+    onVoiceActiveChange?.(voiceActive);
+  }, [onVoiceActiveChange, voiceActive]);
+  useEffect(() => () => onVoiceActiveChange?.(false), [onVoiceActiveChange]);
+
+  return (
+    <RealtimeVoiceControl
+      snapshot={realtime.snapshot}
+      canStart={realtime.canStart}
+      admissionBlocker={realtime.admissionBlocker}
+      modelAvailable={selected.available}
+      menuSide="top"
+      modelMenu="split"
+      showDiagnostics={false}
+      audioRef={realtime.audioRef}
+      selectedModel={selected}
+      models={props.models}
+      onSelectModel={realtime.lifecycleActive ? undefined : setChosen}
+      onStart={realtime.start}
+      onStop={realtime.stop}
+      onRetry={realtime.retry}
+      onRetryAudibleOutput={realtime.retryAudibleOutput}
+      onSetInputMuted={realtime.setInputMuted}
+      onSetOutputMuted={realtime.setOutputMuted}
+    />
+  );
+}

package/src/realtime/realtime-control.tsx

@@ -1,3 +1,7 @@
+import {
+  COMPOSER_VOICE_INPUT_START_EVENT,
+  composerVoiceEventScope,
+} from "../composer-voice-events";
 import { type EffectiveSessionControl, type SessionEvent, type SessionStatus } from "@opengeni/sdk";
 import {
   hasStoredSessionRealtimeOwnerProof,
@@ -22,6 +26,7 @@ import {
   SquareIcon,
   Volume2Icon,
   VolumeXIcon,
+  XIcon,
 } from "lucide-react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import {
@@ -72,7 +77,7 @@ export type RealtimeModelOption = {
 function realtimeRefusalLabel(code: string | null | undefined): string | null {
   switch (code) {
     case "insufficient_credits":
-      return "Out of credits";
+      return "Credits needed";
     case "allowance_exhausted":
     case "monthly_model_cost_limit":
       return "Usage limit reached";
@@ -103,19 +108,30 @@ type RealtimeModelProvider = (typeof REALTIME_MODEL_PROVIDERS)[number];
 
 const REALTIME_PROVIDER_META: Record<
   RealtimeModelProvider,
-  { billingClass: BillingClass; hint: string }
+  { billingClass: BillingClass; label: string; hint: string }
 > = {
-  OpenGeni: { billingClass: "opengeni_credits", hint: "Will use credits" },
+  // The wire value keeps its historical spelling; the product name is Opengeni.
+  OpenGeni: { billingClass: "opengeni_credits", label: "Opengeni", hint: "Uses Opengeni credits" },
   "Connected Codex": {
     billingClass: "codex_subscription",
+    label: "Connected Codex",
     hint: "ChatGPT / Codex plan",
   },
   "Connected SuperGrok": {
     billingClass: "supergrok_subscription",
+    label: "Connected SuperGrok",
     hint: "SuperGrok / xAI plan",
   },
-  "Your Gateway": { billingClass: "byok", hint: "Billed to your AI Gateway" },
+  "Your Gateway": {
+    billingClass: "byok",
+    label: "Your Gateway",
+    hint: "Billed to your AI Gateway",
+  },
 };
+/** Display name; the catalog's `provider` value stays the wire identifier. */
+function realtimeProviderLabel(provider: RealtimeModelProvider): string {
+  return provider === "OpenGeni" ? "Opengeni" : provider;
+}
 const REALTIME_MODEL_STORAGE_PREFIX = "opengeni:realtime-model";
 const REALTIME_MODEL_CATALOG_CACHE_TTL_MS = 60_000;
 const REALTIME_MODEL_CATALOG_CACHE_MAX_WORKSPACES = 64;
@@ -541,14 +557,13 @@ export function SessionRealtimeControl(props: {
     }
     if (!canStart) return;
     autostartStartedRef.current = true;
-    void start()
-      .then(() => {
-        autostartModelRef.current = null;
-        onRealtimeAutostartConsumed?.();
-      })
-      .catch(() => {
-        autostartStartedRef.current = false;
-      });
+    // One automatic attempt. A failed start stays visible with its reason and
+    // the user retries explicitly; re-arming would loop on a definitive refusal.
+    const consume = () => {
+      autostartModelRef.current = null;
+      onRealtimeAutostartConsumed?.();
+    };
+    void start().then(consume, consume);
   }, [
     canStart,
     lifecycleActive,
@@ -584,6 +599,18 @@ export function SessionRealtimeControl(props: {
   );
 }
 
+/**
+ * First available model; otherwise the model whose blocker the user can act on
+ * (for example adding credits) rather than an unrelated "connect" prompt.
+ */
+function fallbackRealtimeModelId(models: readonly RealtimeModelOption[]): SessionRealtimeModel {
+  return (
+    models.find((model) => model.available)?.id ??
+    models.find((model) => model.unavailableCode)?.id ??
+    CODEX_LIVE_MODEL.id
+  );
+}
+
 export function useRealtimeModelSelection(options: {
   client?: RealtimeControllerClient | undefined;
   workspaceId?: string | undefined;
@@ -610,7 +637,7 @@ export function useRealtimeModelSelection(options: {
     if (initialCachedCatalog.some((model) => model.id === preferred && model.available)) {
       return preferred;
     }
-    return initialCachedCatalog.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
+    return fallbackRealtimeModelId(initialCachedCatalog);
   });
 
   useEffect(() => {
@@ -621,7 +648,7 @@ export function useRealtimeModelSelection(options: {
       setCatalog(models);
       setSelectedModelId((current) => {
         if (models.some((model) => model.id === current && model.available)) return current;
-        return models.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
+        return fallbackRealtimeModelId(models);
       });
     };
     const cached = readCachedRealtimeModelCatalog(client, workspaceId);
@@ -848,6 +875,11 @@ export function RealtimeVoiceControl(props: {
     props.snapshot.status !== "active" &&
     props.snapshot.diagnostic?.recoverable === true;
   const audioBlocked = props.snapshot.audibleOutput === "blocked" && !props.snapshot.outputMuted;
+  // A call that ended in a failure keeps its reason on screen, not only in a
+  // tooltip or the model menu, until the user starts again or changes model.
+  const startFailed = props.snapshot.status === "error" && !modeOwned;
+  const failureText =
+    status.label === "Voice unavailable" ? status.detail : `${status.label}. ${status.detail}`;
   const mainDisabled =
     props.snapshot.status === "stopping" ||
     props.snapshot.status === "lost_owner" ||
@@ -859,7 +891,11 @@ export function RealtimeVoiceControl(props: {
       ? "Retry voice connection"
       : modeOwned
         ? "End voice conversation"
-        : `Start voice with ${selectedModel.label}`;
+        : !props.canStart && status.phase === "unavailable"
+          ? `${status.label}: ${status.detail}`
+          : startFailed
+            ? `Try voice again with ${selectedModel.label}`
+            : `Start voice with ${selectedModel.label}`;
   const runMainAction = audioBlocked
     ? props.onRetryAudibleOutput
     : retryConnection
@@ -876,6 +912,20 @@ export function RealtimeVoiceControl(props: {
     selectedModel.provider,
   );
   const [pickerDirection, setPickerDirection] = useState<1 | -1>(1);
+  const [failureDismissed, setFailureDismissed] = useState(false);
+  useEffect(() => {
+    if (!startFailed) setFailureDismissed(false);
+  }, [startFailed]);
+  const rootRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!startFailed) return;
+    // Starting dictation in this composer supersedes a stale start failure.
+    const scope = composerVoiceEventScope(rootRef.current);
+    if (!scope) return;
+    const dismiss = () => setFailureDismissed(true);
+    scope.addEventListener(COMPOSER_VOICE_INPUT_START_EVENT, dismiss);
+    return () => scope.removeEventListener(COMPOSER_VOICE_INPUT_START_EVENT, dismiss);
+  }, [startFailed]);
 
   useEffect(() => {
     if (!pickerOpen) setPickerProvider(selectedModel.provider);
@@ -883,6 +933,7 @@ export function RealtimeVoiceControl(props: {
 
   return (
     <div
+      ref={rootRef}
       role="group"
       aria-label="Realtime voice"
       data-picker-side={props.menuSide ?? "top"}
@@ -964,6 +1015,20 @@ export function RealtimeVoiceControl(props: {
           </motion.div>
         ) : null}
       </AnimatePresence>
+      {startFailed && !failureDismissed ? (
+        <button
+          type="button"
+          data-realtime-attention=""
+          data-testid="realtime-failure-reason"
+          title="Dismiss"
+          aria-label={`Dismiss: ${failureText}`}
+          onClick={() => setFailureDismissed(true)}
+          className="og-realtime-failure mr-1.5 inline-flex min-w-0 items-center gap-1 rounded-og-sm text-right text-og-xs leading-tight text-og-status-failed outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent/45"
+        >
+          <span className="og-realtime-failure-label line-clamp-2 max-w-56">{failureText}</span>
+          <XIcon className="size-3 shrink-0 opacity-70" aria-hidden />
+        </button>
+      ) : null}
       <div className="inline-flex shrink-0 items-center">
         <motion.button
           type="button"
@@ -1220,7 +1285,7 @@ export function RealtimeModelPickerMenu(props: {
   const body = props.provider ? (
     <div data-testid="realtime-model-picker-models">
       <PickerBackHeader
-        label={props.provider}
+        label={realtimeProviderLabel(props.provider)}
         icon={
           <BillingClassMark
             billingClass={REALTIME_PROVIDER_META[props.provider].billingClass}
@@ -1263,7 +1328,7 @@ export function RealtimeModelPickerMenu(props: {
         return (
           <PickerNavRow
             key={provider}
-            label={provider}
+            label={realtimeProviderLabel(provider)}
             hint={meta.hint}
             icon={<BillingClassMark billingClass={meta.billingClass} aria-label="" />}
             active={props.selectedModel.provider === provider}

package/src/voice-recording-owner.ts

@@ -98,6 +98,28 @@ async function createUnderlyingOwnerLease(): Promise<UnderlyingOwnerLease> {
   return { ownerId, release: () => undefined };
 }
 
+/**
+ * Owner ids whose document still holds its Web Lock, or null when this browser
+ * cannot answer. A lock is released the moment its tab closes or crashes, so a
+ * recording whose owner is absent here is recoverable immediately instead of
+ * after the heartbeat stale window.
+ */
+export async function liveVoiceRecordingOwnerIds(): Promise<ReadonlySet<string> | null> {
+  if (!hasWebLocks() || typeof navigator.locks.query !== "function") return null;
+  try {
+    const snapshot = await navigator.locks.query();
+    const live = new Set<string>();
+    for (const lock of [...(snapshot.held ?? []), ...(snapshot.pending ?? [])]) {
+      if (lock.name?.startsWith(VOICE_RECORDING_OWNER_LOCK_PREFIX)) {
+        live.add(lock.name.slice(VOICE_RECORDING_OWNER_LOCK_PREFIX.length));
+      }
+    }
+    return live;
+  } catch {
+    return null;
+  }
+}
+
 function hasWebLocks(): boolean {
   return (
     typeof navigator !== "undefined" &&