@mentra/engine 0.1.0-dev.0 → 3.1.0-dev.10

package/src/services/LocalMiniappRuntime.ts

@@ -9,7 +9,7 @@
  * management (connect/disconnect/ping).
  */
 
-import {Linking} from "react-native"
+import {AppState, Linking} from "react-native"
 import Share from "react-native-share"
 import * as Battery from "expo-battery"
 import * as Clipboard from "expo-clipboard"
@@ -45,9 +45,14 @@ import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator"
 import micStateCoordinator from "./MicStateCoordinator"
 import {BlobStore} from "./BlobStore"
 import {CloudAudioSubscriptionSync} from "./CloudAudioSubscriptionSync"
+import {phoneCameraFovCoordinator} from "./PhoneCameraFovCoordinator"
 import {phonePhotoCoordinator} from "./PhonePhotoCoordinator"
 import {phoneStreamCoordinator} from "./PhoneStreamCoordinator"
 import {phoneVideoCoordinator} from "./PhoneVideoCoordinator"
+import {runSentenceTtsPipeline} from "./SentenceTtsPipeline"
+import {summarizeTranscriptionRoutes, transcriptionDeliveryRoute} from "./TranscriptionRouting"
+import {prepareTtsSentences} from "./TtsTextSanitizer"
+import {handleWifiAdbRequest} from "./WifiAdbRequest"
 import {cloudClientService} from "./CloudClientService"
 import {miniappLauncher} from "./MiniappLauncher"
 import {
@@ -61,39 +66,51 @@ import {
   type TtsSynthesisResult,
 } from "../runtime/config"
 import {getAnalytics, getUiSeams} from "../runtime/bootstrap"
+import {invokeScanQrSeam} from "../runtime/scanQrSeam"
 import {normalizeStreamAudioConfig, normalizeStreamVideoConfig} from "../runtime/streamConfig"
-import type {
-  AudioSubscription,
-  LanguageSource,
-  TranscriptionData,
-  TranslationData,
-} from "@mentra/cloud-protocol"
+import {toLanguageHint} from "@mentra/cloud-protocol/languages"
+import type {AudioSubscription, LanguageSource, TranscriptionData, TranslationData} from "@mentra/cloud-protocol"
+import {buildMiniappManifestSnapshot, type MiniappRuntimeDiagnosticSnapshot} from "../utils/miniappDiagnostics"
 import ttsModelManager from "./TTSModelManager"
 import {NavigationHandlers} from "./NavigationHandlers"
 import type {ClientApp} from "../types/applet"
 import {useAppStatusStore} from "../stores/apps"
-import {DEV_APP_PACKAGE_NAME, getDevAppSourcePackage} from "./AppRegistry"
+import {getDevAppAttestation, getDevAppSourcePackage} from "./AppRegistry"
+import {resolveForegroundLocationPermission} from "./ForegroundLocationPermission"
+import {advanceMiniappPingLiveness} from "./MiniappLiveness"
+import {listPhoneCalendarEvents, PhoneCalendarError} from "./PhoneCalendarService"
+import {LocalMiniappStorage} from "./LocalMiniappStorage"
 
 // =============================================================================
 // Types
 // =============================================================================
 
 export interface InstalledMiniappManifest {
+  packageName?: string
   /** Human-facing app name (from miniapp.json `name`). Shown in the "Starting
    * <name>…" boot message; falls back to the package name when absent. */
   name?: string
+  version?: string
+  sdkVersion?: string
+  minHostVersion?: string
+  type?: string
+  entry?: {background?: string; ui?: string}
   permissions?: Array<{type: string; required?: boolean; description?: string}>
   hardwareRequirements?: Array<{type: string; level: string; description?: string}>
+  actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown; outputSchema?: unknown}>
 }
 
 type SpeakerStateValue = "idle" | "loading" | "playing" | "stopped" | "error"
 
 interface ConnectedMiniapp {
   subscriptions: Set<string>
+  /** Transcription streams this app explicitly requires to stay on-device. */
+  forceLocalTranscriptionStreams: Set<string>
+  /** Transcription streams with at least one listener using the default/cloud route. */
+  cloudTranscriptionStreams: Set<string>
   sendMessage: (raw: string) => void
   lastPongAt: number
-  /** BGCAP diagnostic: wall-clock of the most recent PING send, for PONG RTT. */
-  bgcapLastPingSentAt?: number
+  unansweredPingRounds: number
   installedManifest?: InstalledMiniappManifest
   authRefreshTimerId: number | null
   /**
@@ -122,6 +139,15 @@ interface ConnectedMiniapp {
   requestedLocationRate: string | null
 }
 
+interface SpeechRun {
+  id: string
+  cancelled: boolean
+  playbackRequestId?: string
+  onCancelled?: () => void
+}
+
+type TranscriptionEventSource = "cloud" | "local"
+
 /**
  * Strictness ordering for `location_stream` rate values. Higher index =
  * higher accuracy and higher power cost. The aggregate tier applied to
@@ -158,6 +184,16 @@ function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | nul
 }
 
 const LOG_TAG = "LOCAL_MINIAPP"
+const DIAGNOSTIC_MAX_LIST_ITEMS = 100
+const DIAGNOSTIC_MAX_STRING_LENGTH = 512
+
+function diagnosticStringList(values: Iterable<string>): string[] {
+  return [...values]
+    .map((value) => value.slice(0, DIAGNOSTIC_MAX_STRING_LENGTH))
+    .sort()
+    .slice(0, DIAGNOSTIC_MAX_LIST_ITEMS)
+}
+
 const SYSTEM_MINIAPP_PACKAGES = new Set([
   "com.mentra.camera",
   "com.mentra.gallery",
@@ -189,81 +225,34 @@ const REQUEST_WIFI_SETUP_TYPE = "miniapp_request_wifi_setup"
 // comes back automatically — this threshold only bounds how long that takes.
 const PING_TIMEOUT_THRESHOLD = 6 // ~30s
 
-// ===========================================================================
-// BGCAP: temporary background-caption telemetry (DIAGNOSTIC — remove after the
-// "captions fall behind then flood in waves" investigation lands a fix).
-//
-// Captions now run as a local miniapp inside the per-context JS engine
-// (Crust: QuickJS on Android / JSC on iOS), driven off a single serial
-// queue/executor with NO background awareness. The hypothesis is that the OS
-// starves/freezes that queue when the screen is off (iOS app suspension /
-// Android Doze), so inbound transcript deliveries pile up and drain in a burst
-// on resume. These logs measure exactly that. All lines are prefixed "BGCAP:"
-// so they're trivial to grep in incident logs and to delete. Cross-platform —
-// host-side only, no native changes.
-// ===========================================================================
-const BGCAP_TELEMETRY = false
 const TRANSCRIPT_TIMING_TELEMETRY = (globalThis as {__DEV__?: boolean}).__DEV__ === true
-let bgcapHbTimer: ReturnType<typeof setInterval> | null = null
-let bgcapHbLast = 0
-let bgcapTxCount = 0
-let bgcapTxLastFinalAt = 0
-let bgcapTxLastLogAt = 0
-
-function bgcapStartHeartbeat(): void {
-  if (!BGCAP_TELEMETRY || bgcapHbTimer !== null) return
-  bgcapHbLast = Date.now()
-  // PLAIN setInterval (NOT BgTimer): a plain JS timer only fires when the RN
-  // JS thread is actually executing. A gap >> 1s between ticks therefore proves
-  // the JS thread was suspended/throttled (iOS suspend / Android Doze) for that
-  // long — the smoking gun for the freeze. Silent when healthy; logs the stall
-  // duration when it happens. Pair with the "App state changed to:" lines.
-  bgcapHbTimer = setInterval(() => {
-    const now = Date.now()
-    const gap = now - bgcapHbLast
-    bgcapHbLast = now
-    if (gap > 2000) {
-      console.log(`BGCAP: host-js stall — no tick for ${gap}ms (RN JS thread frozen/throttled)`)
-    }
-  }, 1000)
-}
-
-function bgcapStopHeartbeat(): void {
-  if (bgcapHbTimer !== null) {
-    clearInterval(bgcapHbTimer)
-    bgcapHbTimer = null
-  }
-}
-
-// Rate-limited (1/s) summary of transcripts being FORWARDED to miniapps. Shows
-// whether transcripts keep arriving + being handed to the captions miniapp
-// during background. Compare its rate against the native "MAN: displayEvent"
-// (render) rate: fwd keeps flowing but render lags => miniapp executor is
-// starved; fwd itself stops => upstream (cloud delivery / RN thread) is the gap.
-function bgcapNoteTranscriptForward(isFinal: boolean): void {
-  if (!BGCAP_TELEMETRY) return
-  bgcapTxCount++
-  if (isFinal) bgcapTxLastFinalAt = Date.now()
-  const now = Date.now()
-  if (now - bgcapTxLastLogAt >= 1000) {
-    console.log(
-      `BGCAP: tx forwarded=${bgcapTxCount} in last ${now - bgcapTxLastLogAt}ms (lastFinal ${
-        bgcapTxLastFinalAt ? now - bgcapTxLastFinalAt : -1
-      }ms ago)`,
-    )
-    bgcapTxCount = 0
-    bgcapTxLastLogAt = now
-  }
-}
 
 const RGB_LED_ACTIONS = new Set<RgbLedAction>(["on", "off"])
 const RGB_LED_COLORS = new Set<RgbLedColor>(["red", "green", "blue", "orange", "white"])
 const CAMERA_FOV_MIN = 62
 const CAMERA_FOV_MAX = 118
-const CAMERA_FOV_DEFAULT = 102
-const CAMERA_FOV_PRESETS: Record<CameraFovPreset, number> = {narrow: 82, standard: CAMERA_FOV_DEFAULT, wide: 118}
+const CAMERA_FOV_DEFAULT = 118
+const CAMERA_FOV_PRESETS: Record<CameraFovPreset, number> = {narrow: 82, standard: 102, wide: 118}
 const CAMERA_ROI_POSITION_BY_NAME: Record<string, CameraRoiPosition> = {center: "center", bottom: "bottom", top: "top"}
-const CAMERA_ROI_POSITION_VALUES: Record<CameraRoiPosition, 0 | 1 | 2> = {center: 0, bottom: 1, top: 2}
+
+const localMiniappStorageBackend = {
+  get(key: string): unknown | null {
+    const result = mmkvStorage.load<unknown>(key)
+    return result.is_ok() ? result.value : null
+  },
+  has(key: string): boolean {
+    return mmkvStorage.load<unknown>(key).is_ok()
+  },
+  set(key: string, value: unknown): void {
+    mmkvStorage.save(key, value)
+  },
+  remove(key: string): void {
+    mmkvStorage.remove(key)
+  },
+  keys(): string[] {
+    return mmkvStorage.getAllKeys()
+  },
+}
 
 // =============================================================================
 // Declared-permission record helper (for CONNECT_ACK / PERMISSIONS_UPDATE)
@@ -406,11 +395,22 @@ class LocalMiniappRuntime {
   /** Ref-counted stream subscriptions: stream → set of packageNames. */
   private streamSubscribers: Map<string, Set<string>> = new Map()
 
+  /** Host observers for the Mentra Live button-capture policy. */
+  private buttonPressSubscriberListeners = new Set<(packageNames: string[]) => void>()
+
   /** Guards one-time wiring of the cloud transcript/translation fan-out. */
   private cloudResultsWired = false
   private cloudStatusWired = false
   private cloudAudioSubscriptionSync = new CloudAudioSubscriptionSync()
 
+  /**
+   * Per-miniapp language hints from TRANSCRIPTION_CONFIG (issue 021 WP3).
+   * Bare ISO 639-1 codes, already registry-validated by the SDK and
+   * re-normalized here (defense in depth). Merged (union) into the auto-mode
+   * cloud transcription subscription in buildCloudAudioSubscriptions.
+   */
+  private transcriptionHintsByApp = new Map<string, string[]>()
+
   /** Ping interval handle. */
   private pingIntervalId: number | null = null
   private foregroundProbeTimers: Map<string, number> = new Map()
@@ -427,6 +427,7 @@ class LocalMiniappRuntime {
 
   /** Pending cloud requests: requestId → packageName that originated the request. */
   private pendingCloudRequests: Map<string, {packageName: string; envelopeRequestId?: string}> = new Map()
+  private speechRuns = new Map<string, SpeechRun>()
 
   // Browser fallback token auth — HMAC-signed blob with a phone-local
   // secret. Both issuer and verifier are the same process, so the
@@ -436,6 +437,99 @@ class LocalMiniappRuntime {
 
   private constructor() {}
 
+  /** Snapshot of miniapps actively subscribed to hardware button events. */
+  public getButtonPressSubscribers(): string[] {
+    return [...(this.streamSubscribers.get(MiniappStreamType.BUTTON_PRESS) ?? [])].sort()
+  }
+
+  /** Observe active hardware-button subscriptions. */
+  public onButtonPressSubscribersChanged(listener: (packageNames: string[]) => void): () => void {
+    this.buttonPressSubscriberListeners.add(listener)
+    return () => this.buttonPressSubscriberListeners.delete(listener)
+  }
+
+  /** Report-safe live miniapp/subscription/resource snapshot. */
+  public getDiagnosticSnapshot(nowMs = Date.now()): MiniappRuntimeDiagnosticSnapshot {
+    const connectedApps = [...this.connectedApps.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .slice(0, DIAGNOSTIC_MAX_LIST_ITEMS)
+      .map(([packageName, app]) => ({
+        packageName: packageName.slice(0, DIAGNOSTIC_MAX_STRING_LENGTH),
+        handshakeComplete: this.handshookApps.has(packageName),
+        subscriptions: diagnosticStringList(app.subscriptions),
+        lastMessageAgeMs: Math.max(0, nowMs - app.lastPongAt),
+        requestedLocationRate: app.requestedLocationRate,
+        hasActiveSpeakerStream: app.activeSpeakerStreamId !== undefined,
+        ...(app.installedManifest
+          ? {
+              manifest: buildMiniappManifestSnapshot(app.installedManifest, {
+                packageName,
+                name: app.installedManifest.name,
+                version: app.installedManifest.version,
+                type: app.installedManifest.type,
+              }),
+            }
+          : {}),
+      }))
+    const subscriptionsByStream = Object.fromEntries(
+      [...this.streamSubscribers.entries()]
+        .filter(([, packageNames]) => packageNames.size > 0)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .slice(0, DIAGNOSTIC_MAX_LIST_ITEMS)
+        .map(([stream, packageNames]) => [
+          stream.slice(0, DIAGNOSTIC_MAX_STRING_LENGTH),
+          diagnosticStringList(packageNames),
+        ]),
+    )
+
+    return {
+      connectedApps,
+      subscriptionsByStream,
+      resources: {
+        display: localDisplayManager.getDiagnosticSnapshot(),
+        camera: phonePhotoCoordinator.getDiagnosticSnapshot(),
+        video: phoneVideoCoordinator.getDiagnosticSnapshot(),
+        stream: phoneStreamCoordinator.getDiagnosticSnapshot(),
+        cameraFov: phoneCameraFovCoordinator.getDiagnosticSnapshot(),
+      },
+    }
+  }
+
+  private replaceStreamSubscribers(
+    packageName: string,
+    previousStreams: Iterable<string>,
+    nextStreams: Iterable<string>,
+  ) {
+    const previousButtonSubscribers = this.getButtonPressSubscribers().join("\u0000")
+
+    for (const stream of previousStreams) {
+      const subscribers = this.streamSubscribers.get(stream)
+      if (!subscribers) continue
+      subscribers.delete(packageName)
+      if (subscribers.size === 0) this.streamSubscribers.delete(stream)
+    }
+
+    for (const stream of nextStreams) {
+      let subscribers = this.streamSubscribers.get(stream)
+      if (!subscribers) {
+        subscribers = new Set()
+        this.streamSubscribers.set(stream, subscribers)
+      }
+      subscribers.add(packageName)
+    }
+
+    const nextButtonSubscribers = this.getButtonPressSubscribers()
+    if (previousButtonSubscribers !== nextButtonSubscribers.join("\u0000")) {
+      for (const listener of this.buttonPressSubscriberListeners) {
+        try {
+          listener(nextButtonSubscribers)
+        } catch (error) {
+          console.warn(`${LOG_TAG}: button press subscriber listener threw:`, error)
+        }
+      }
+    }
+  }
+
   /**
    * Generate an HMAC-signed local session token for browser fallback auth.
    * Token format: base64(JSON({userId, packageName, exp})).base64(HMAC-SHA256(payload, secret))
@@ -640,6 +734,7 @@ class LocalMiniappRuntime {
     // dangling references. The WebView will re-subscribe after its CONNECT.
     if (this.connectedApps.has(packageName)) {
       const existing = this.connectedApps.get(packageName)!
+      this.cancelSpeech(packageName)
       // A crash respawn replaces the ConnectedMiniapp without going through
       // unregisterApp(). Abort the old incarnation's native PCM player before
       // its only stream id is lost. Target the exact stream rather than using
@@ -649,10 +744,7 @@ class LocalMiniappRuntime {
       if (existingSpeakerStreamId) {
         existing.activeSpeakerStreamId = undefined
         void audioPlaybackService.abortStream(existingSpeakerStreamId).catch((error) => {
-          console.warn(
-            `${LOG_TAG}: failed to abort speaker stream while replacing ${packageName}`,
-            error,
-          )
+          console.warn(`${LOG_TAG}: failed to abort speaker stream while replacing ${packageName}`, error)
         })
       }
       if (existing.authRefreshTimerId !== null) {
@@ -663,20 +755,17 @@ class LocalMiniappRuntime {
         BgTimer.clearTimeout(existing.authRetryTimerId)
         existing.authRetryTimerId = null
       }
-      for (const stream of existing.subscriptions) {
-        const subs = this.streamSubscribers.get(stream)
-        if (subs) {
-          subs.delete(packageName)
-          if (subs.size === 0) this.streamSubscribers.delete(stream)
-        }
-      }
+      this.replaceStreamSubscribers(packageName, existing.subscriptions, [])
       this.recomputeMicRequirements()
       this.updateCloudSubscriptions()
     }
     this.connectedApps.set(packageName, {
       subscriptions: new Set(),
+      forceLocalTranscriptionStreams: new Set(),
+      cloudTranscriptionStreams: new Set(),
       sendMessage: sendFn,
       lastPongAt: Date.now(),
+      unansweredPingRounds: 0,
       installedManifest,
       authRefreshTimerId: null,
       authRetryTimerId: null,
@@ -797,6 +886,7 @@ class LocalMiniappRuntime {
 
   public unregisterApp(packageName: string): void {
     console.log(`${LOG_TAG}: unregisterApp(${packageName})`)
+    const releasedMicGateOverride = micStateCoordinator.clearMiniappGateOverrides(packageName)
     this.clearForegroundProbe(packageName)
     this.clearMiniappAuthRefresh(packageName)
     this.clearMiniappAuthDeliveryRetry(packageName)
@@ -805,23 +895,44 @@ class LocalMiniappRuntime {
     // the early-return so it runs even if the connectedApps entry is already gone.
     this.handshookApps.delete(packageName)
     this.flushConnectWaiters(packageName, new Error(`${packageName} unregistered before connect`))
+    // Drop this app's transcription hints; the cloud subscription rebuild
+    // below (via replaceStreamSubscribers) re-derives the hint union without it.
+    this.transcriptionHintsByApp.delete(packageName)
+
+    // Warm-up is a request-owned camera lease. Cancel it even if the app record was already
+    // removed so a close racing the camera-open promise cannot leave the sensor running.
+    // Keep camera teardown ordered: restoring FOV can restart the HAL, so the warm-up lease must
+    // finish closing the sensor before FOV reconciliation begins. Continue to FOV cleanup even if
+    // warm-up cancellation fails; phone ownership remains retryable until the ASG lease TTL.
+    void phonePhotoCoordinator
+      .stopWarmUpForApp(packageName)
+      .catch((error) => {
+        console.warn(`${LOG_TAG}: failed to stop camera warm-up for ${packageName} on unregister`, error)
+      })
+      .then(() => phoneCameraFovCoordinator.releaseForApp(packageName))
+      .catch((error) => {
+        console.warn(`${LOG_TAG}: failed to release camera FOV override for ${packageName} on unregister`, error)
+      })
     const app = this.connectedApps.get(packageName)
-    if (!app) return
-
-    // Remove from all stream subscriber sets
-    for (const stream of app.subscriptions) {
-      const subs = this.streamSubscribers.get(stream)
-      if (subs) {
-        subs.delete(packageName)
-        if (subs.size === 0) {
-          this.streamSubscribers.delete(stream)
-        }
+    if (!app) {
+      if (releasedMicGateOverride) {
+        void micStateCoordinator.syncEffectiveGatePolicy(this.getConfiguredMicGates()).catch((error) => {
+          console.warn(`${LOG_TAG}: failed to restore mic gate policy for ${packageName}`, error)
+        })
       }
+      return
     }
 
+    // Remove from all stream subscriber sets
+    this.replaceStreamSubscribers(packageName, app.subscriptions, [])
+
     // Reset per-session warning dedup so a relaunch surfaces issues again.
     resetPermissionWarnings(packageName)
 
+    // Cancel lookahead/in-flight synthesis before stopping the current file so
+    // an interrupted sentence cannot advance and reclaim playback.
+    this.cancelSpeech(packageName)
+
     // Stop audio for this app
     audioPlaybackService.stopForApp(packageName)
 
@@ -880,6 +991,11 @@ class LocalMiniappRuntime {
 
     this.connectedApps.delete(packageName)
     this.recomputeMicRequirements()
+    if (releasedMicGateOverride) {
+      void micStateCoordinator.syncEffectiveGatePolicy(this.getConfiguredMicGates()).catch((error) => {
+        console.warn(`${LOG_TAG}: failed to restore mic gate policy for ${packageName}`, error)
+      })
+    }
     this.updateCloudSubscriptions()
 
     if (this.connectedApps.size === 0) {
@@ -984,6 +1100,9 @@ class LocalMiniappRuntime {
       case MiniappRequestType.LOCATION_POLL:
         this.handleLocationPoll(packageName, requestId)
         break
+      case MiniappRequestType.CALENDAR_LIST_EVENTS:
+        void this.handleCalendarListEvents(packageName, payload, requestId)
+        break
       case MiniappRequestType.NAVIGATION_START:
         this.navigationHandlers.handleStart(packageName, payload, requestId)
         break
@@ -1050,9 +1169,18 @@ class LocalMiniappRuntime {
       case MiniappRequestType.CAMERA_FOV:
         void this.handleCameraFov(packageName, payload, requestId)
         break
+      case MiniappRequestType.SET_WIFI_ADB_STATE:
+        void this.handleSetWifiAdbState(packageName, payload, requestId)
+        break
       case MiniappRequestType.IMU_SET_ENABLED:
         this.handleImuSetEnabled(packageName, payload, requestId)
         break
+      case MiniappRequestType.MIC_SET_VAD_ENABLED:
+        void this.handleMicSetVadEnabled(packageName, payload, requestId)
+        break
+      case MiniappRequestType.MIC_SET_LOUDNESS_GATE_ENABLED:
+        void this.handleMicSetLoudnessGateEnabled(packageName, payload, requestId)
+        break
       case MiniappRequestType.PING:
         // SDK should handle this itself; reply PONG just in case
         this.sendToMiniapp(packageName, {type: MiniappResponseType.PONG}, requestId)
@@ -1060,23 +1188,6 @@ class LocalMiniappRuntime {
       case MiniappResponseType.PONG: {
         // Liveness already touched above for every inbound message; the
         // PONG carries no other action.
-        // BGCAP: measure PING→PONG round-trip ONLY here (a real pong), not in
-        // handlePong (which fires for every inbound envelope). RTT = how long
-        // the miniapp's own JS engine (Crust serial queue) took to answer — a
-        // large value means that queue was starved (the transcript→display
-        // layer). bgcapLastPingSentAt holds the OLDEST outstanding ping (see
-        // doPingRound), so a multi-round background stall reports its full
-        // duration on the first pong after resume.
-        if (BGCAP_TELEMETRY) {
-          const app = this.connectedApps.get(packageName)
-          if (app?.bgcapLastPingSentAt != null) {
-            const rtt = Date.now() - app.bgcapLastPingSentAt
-            if (rtt > 1500) {
-              console.log(`BGCAP: ${packageName} pong rtt=${rtt}ms (miniapp JS engine was starved)`)
-            }
-            app.bgcapLastPingSentAt = undefined
-          }
-        }
         break
       }
 
@@ -1092,52 +1203,83 @@ class LocalMiniappRuntime {
       case MiniappRequestType.DOWNLOAD:
         this.handleDownload(packageName, payload, requestId)
         break
+      case MiniappRequestType.SCAN_QR:
+        void this.handleScanQr(packageName, payload, requestId)
+        break
 
       // Persistent binary blob storage (session.blob)
       case MiniappRequestType.BLOB_CREATE:
-        this.blobStore.handleCreate(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleCreate(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_WRITE:
-        this.blobStore.handleWrite(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleWrite(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_COMMIT:
-        this.blobStore.handleCommit(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleCommit(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_ABORT:
-        this.blobStore.handleAbort(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleAbort(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_SET_FROM_URL:
-        void this.blobStore.handleSetFromUrl(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleSetFromUrl(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_IMPORT:
-        void this.blobStore.handleImport(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleImport(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_GET:
-        this.blobStore.handleGet(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () => this.blobStore.handleGet(packageName, payload, requestId))
         break
       case MiniappRequestType.BLOB_LIST:
-        this.blobStore.handleList(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleList(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_USAGE:
-        this.blobStore.handleUsage(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleUsage(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_DELETE:
-        this.blobStore.handleDelete(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleDelete(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_CLEAR:
-        this.blobStore.handleClear(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleClear(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_OPEN_READ:
-        this.blobStore.handleOpenRead(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleOpenRead(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_READ:
-        this.blobStore.handleRead(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleRead(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_CLOSE_READ:
-        this.blobStore.handleCloseRead(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleCloseRead(packageName, payload, requestId),
+        )
         break
       case MiniappRequestType.BLOB_SHARE:
-        void this.blobStore.handleShare(packageName, payload, requestId)
+        this.enqueueBlobRequest(packageName, requestId, () =>
+          this.blobStore.handleShare(packageName, payload, requestId),
+        )
         break
 
       // Cloud-coordinated features
@@ -1194,8 +1336,20 @@ class LocalMiniappRuntime {
         })
         break
 
+      case MiniappRequestType.TRANSCRIPTION_CONFIG:
+        this.handleTranscriptionConfig(packageName, payload, requestId)
+        break
+
       default:
+        // NACK instead of silent drop (issue 021 S3): an SDK that sends a
+        // request this runtime doesn't implement must get a rejected promise,
+        // not a permanently-pending silent gap. One-shots (no requestId) can
+        // only be logged.
         console.warn(`${LOG_TAG}: Unknown request type from ${packageName}: ${requestType}`)
+        this.sendResult(packageName, requestId, false, undefined, {
+          code: MiniappErrorCode.NOT_IMPLEMENTED,
+          message: `Unknown or unimplemented request type: ${requestType}`,
+        })
         break
     }
   }
@@ -1220,6 +1374,7 @@ class LocalMiniappRuntime {
 
     // Update lastPongAt so it doesn't time out right away
     existing.lastPongAt = Date.now()
+    existing.unansweredPingRounds = 0
 
     // Read current glasses capabilities from the settings store
     const defaultWearable = useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.defaultWearable) as
@@ -1276,9 +1431,12 @@ class LocalMiniappRuntime {
   }
 
   private async requestMiniappAuth(packageName: string, opts?: {minTtlMs?: number}): Promise<MiniappAuthToken | null> {
-    const authPackageName = packageName === DEV_APP_PACKAGE_NAME ? getDevAppSourcePackage() : packageName
-    if (!authPackageName) return null
-    return cloudClientService.getMiniappAuthToken(authPackageName, opts)
+    const authPackageName = getDevAppSourcePackage(packageName) ?? packageName
+    const devAttestation = getDevAppAttestation(packageName) ?? undefined
+    return cloudClientService.getMiniappAuthToken(authPackageName, {
+      ...opts,
+      ...(devAttestation ? {devAttestation} : {}),
+    })
   }
 
   private async handleAuthRefresh(
@@ -1424,18 +1582,65 @@ class LocalMiniappRuntime {
     }
   }
 
+  /**
+   * TRANSCRIPTION_CONFIG (issue 021 WP3): store the miniapp's language hints
+   * and rebuild the cloud subscription set so the auto-mode subscription
+   * carries them. Replies with a REQUEST_RESULT so the SDK's configure()
+   * promise settles: unknown hint values are an error, not a silent drop.
+   */
+  private handleTranscriptionConfig(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    const app = this.connectedApps.get(packageName)
+    if (!app) return
+
+    const config = (payload.config ?? {}) as Record<string, unknown>
+    const rawHints = config.languageHints
+    if (rawHints !== undefined && !Array.isArray(rawHints)) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: "languageHints must be an array of language codes",
+      })
+      return
+    }
+
+    if (rawHints === undefined || rawHints.length === 0) {
+      this.transcriptionHintsByApp.delete(packageName)
+    } else {
+      // Defense in depth: the SDK already validated, but the wire is untyped.
+      const hints: string[] = []
+      const invalid: string[] = []
+      for (const raw of rawHints as unknown[]) {
+        const hint = typeof raw === "string" ? toLanguageHint(raw) : null
+        if (hint) hints.push(hint)
+        else invalid.push(String(raw))
+      }
+      if (invalid.length > 0) {
+        this.sendResult(packageName, requestId, false, undefined, {
+          code: MiniappErrorCode.INTERNAL,
+          message: `Unknown language hint(s): ${invalid.join(", ")}`,
+        })
+        return
+      }
+      this.transcriptionHintsByApp.set(packageName, [...new Set(hints)].sort())
+    }
+
+    this.updateCloudSubscriptions()
+    this.sendResult(packageName, requestId, true, {applied: true})
+  }
+
   private handleSubscribe(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
     const app = this.connectedApps.get(packageName)
     if (!app) return
 
     const rawStreams = (payload.subscriptions ?? payload.streams) as
-      | (string | {stream: string; rate?: string})[]
+      | (string | {stream: string; rate?: string; forceLocal?: boolean; includeCloud?: boolean})[]
       | undefined
     // Normalize: objects like {stream: "location_stream", rate: "realtime"} → extract stream name
     // "location_stream" is the rate-bearing alias for "location_update".
     // The strictest rate wins when multiple `location_stream` entries appear
     // in one SUBSCRIBE — the same rule we apply across apps.
     let requestedLocationRate: string | null = null
+    const forceLocalTranscriptionStreams = new Set<string>()
+    const cloudTranscriptionStreams = new Set<string>()
     const streams = rawStreams?.map((s) => {
       if (typeof s === "object" && s !== null) {
         if (s.stream === "location_stream") {
@@ -1444,8 +1649,15 @@ class LocalMiniappRuntime {
           }
           return "location_update"
         }
+        if (s.forceLocal === true && s.stream.startsWith("transcription:")) {
+          forceLocalTranscriptionStreams.add(s.stream)
+        }
+        if (s.stream.startsWith("transcription:") && (s.forceLocal !== true || s.includeCloud === true)) {
+          cloudTranscriptionStreams.add(s.stream)
+        }
         return s.stream
       }
+      if (s.startsWith("transcription:")) cloudTranscriptionStreams.add(s)
       return s
     }) as string[] | undefined
     if (!Array.isArray(streams)) {
@@ -1469,7 +1681,6 @@ class LocalMiniappRuntime {
       if (s === "location_update") return "LOCATION"
       if (s === "phone_notification") return "READ_NOTIFICATIONS"
       if (s === "phone_notification_dismissed") return "READ_NOTIFICATIONS"
-      if (s === "calendar_event") return "CALENDAR"
       return null
     }
 
@@ -1489,27 +1700,16 @@ class LocalMiniappRuntime {
       }
     }
 
-    // Remove old subscriptions for this app
-    for (const oldStream of app.subscriptions) {
-      const subs = this.streamSubscribers.get(oldStream)
-      if (subs) {
-        subs.delete(packageName)
-        if (subs.size === 0) {
-          this.streamSubscribers.delete(oldStream)
-        }
-      }
-    }
-
     // Add new subscriptions
+    const previousSubscriptions = app.subscriptions
     app.subscriptions = new Set(streams)
-    for (const stream of streams) {
-      let subs = this.streamSubscribers.get(stream)
-      if (!subs) {
-        subs = new Set()
-        this.streamSubscribers.set(stream, subs)
-      }
-      subs.add(packageName)
-    }
+    app.forceLocalTranscriptionStreams = new Set(
+      [...forceLocalTranscriptionStreams].filter((stream) => app.subscriptions.has(stream)),
+    )
+    app.cloudTranscriptionStreams = new Set(
+      [...cloudTranscriptionStreams].filter((stream) => app.subscriptions.has(stream)),
+    )
+    this.replaceStreamSubscribers(packageName, previousSubscriptions, app.subscriptions)
 
     this.recomputeMicRequirements()
     this.updateCloudSubscriptions()
@@ -1527,6 +1727,37 @@ class LocalMiniappRuntime {
     this.emitInitialSnapshots(packageName, streams)
   }
 
+  private async handleCalendarListEvents(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    const app = this.connectedApps.get(packageName)
+    const declared = app?.installedManifest?.permissions?.some(
+      (permission) => permission.type?.toUpperCase() === "CALENDAR",
+    )
+    if (!declared) {
+      logPermissionNotDeclared(packageName, "CALENDAR", "to list calendar events", '{"type": "CALENDAR"}')
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+        message: 'CALENDAR permission not declared in miniapp.json. Add {"type": "CALENDAR"} to the permissions array.',
+        permission: "CALENDAR",
+      })
+      return
+    }
+
+    try {
+      const result = await listPhoneCalendarEvents(payload)
+      this.sendResult(packageName, requestId, true, result)
+    } catch (error) {
+      const known = error instanceof PhoneCalendarError
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: known ? error.code : MiniappErrorCode.INTERNAL,
+        message: error instanceof Error ? error.message : "Failed to read phone calendar events",
+      })
+    }
+  }
+
   /**
    * For state-bearing streams (battery, connection), deliver the current value
    * immediately on subscribe. Other streams (button press, transcription, etc.)
@@ -1725,6 +1956,7 @@ class LocalMiniappRuntime {
     const volume = typeof payload.volume === "number" ? payload.volume : 1.0
     const stopOtherAudio = payload.stopOtherAudio !== false
 
+    this.cancelSpeech(packageName)
     this.setSpeakerState(packageName, "loading")
     audioPlaybackService.play(
       {requestId: audioRequestId, audioUrl, appId: packageName, volume, stopOtherAudio},
@@ -1760,6 +1992,7 @@ class LocalMiniappRuntime {
   }
 
   private handleStopAudio(packageName: string, _payload: Record<string, unknown>, requestId?: string): void {
+    this.cancelSpeech(packageName)
     audioPlaybackService.stopForApp(packageName)
     this.setSpeakerState(packageName, "stopped")
     this.sendResult(packageName, requestId, true)
@@ -1965,108 +2198,221 @@ class LocalMiniappRuntime {
   }
 
   private async handleSpeak(packageName: string, payload: Record<string, unknown>, requestId?: string): Promise<void> {
-    const text = payload.text as string | undefined
-    if (!text) {
+    const rawText = payload.text
+    const rawSentences =
+      typeof rawText === "string"
+        ? [rawText.trim()].filter(Boolean)
+        : Array.isArray(rawText)
+          ? rawText
+              .filter((sentence): sentence is string => typeof sentence === "string")
+              .map((sentence) => sentence.trim())
+              .filter(Boolean)
+          : []
+    const enableSanitization = payload.enableSanitization !== false
+    const sentences = prepareTtsSentences(rawSentences, enableSanitization)
+    if (sentences.length === 0) {
       this.sendResult(packageName, requestId, false, undefined, {
         code: MiniappErrorCode.INTERNAL,
-        message: "speak requires text",
+        message: "speak requires text or a non-empty sentence list with speakable content",
       })
       return
     }
+    const cloudText = sentences.join(" ")
 
-    try {
-      const voice = ((payload.voice_id ?? payload.voice) as string) || "default"
-      const audioRequestId = requestId || `tts_${Date.now()}`
-      const volume = typeof payload.volume === "number" ? payload.volume : 1.0
-      const stopOtherAudio = payload.stopOtherAudio !== false
-      const voiceSettings =
-        payload.voice_settings && typeof payload.voice_settings === "object"
-          ? (payload.voice_settings as Record<string, unknown>)
-          : undefined
-      const speed = typeof voiceSettings?.speed === "number" ? voiceSettings.speed : undefined
-
-      this.setSpeakerState(packageName, "loading")
-
-      const voiceExplicit = payload.voice_id !== undefined || payload.voice !== undefined
-      const offlineSupportsVoice =
-        !voiceExplicit || voice === "default" || ttsModelManager.getAvailableLanguages().some((l) => l.code === voice)
-
-      const modelId = typeof payload.model_id === "string" ? payload.model_id : undefined
-      const cloudConnected = cloudClientService.isConnected()
-      console.log(
-        `${LOG_TAG}: TTS decision for ${packageName}: cloudConnected=${cloudConnected}, runtimeTts=yes, offlineVoice=${offlineSupportsVoice}`,
-      )
+    const voice = ((payload.voice_id ?? payload.voice) as string) || "default"
+    const audioRequestId = requestId || `tts_${Date.now()}`
+    const volume = typeof payload.volume === "number" ? payload.volume : 1.0
+    const stopOtherAudio = payload.stopOtherAudio !== false
+    const voiceSettings =
+      payload.voice_settings && typeof payload.voice_settings === "object"
+        ? (payload.voice_settings as Record<string, unknown>)
+        : undefined
+    const speed = typeof voiceSettings?.speed === "number" ? voiceSettings.speed : undefined
+    const run: SpeechRun = {id: audioRequestId, cancelled: false}
+
+    this.cancelSpeech(packageName)
+    this.speechRuns.set(packageName, run)
+    this.setSpeakerState(packageName, "loading")
 
-      let terminalSent = false
-      const sendPlaybackResult = (
-        success: boolean,
-        error: string | null,
-        duration: number | null,
-        fallbackErrorMessage: string,
-      ) => {
-        if (terminalSent) return
-        terminalSent = true
+    let terminalSent = false
+    const sendPlaybackResult = (
+      success: boolean,
+      error: string | null,
+      duration: number | null,
+      fallbackErrorMessage: string,
+      completed = success,
+      errorCode: MiniappErrorCode = MiniappErrorCode.TTS_UPSTREAM_ERROR,
+    ) => {
+      if (terminalSent) return
+      terminalSent = true
+
+      // A superseded run still owns its bridge request, but it no longer owns
+      // the package's shared speaker state.
+      const ownsSpeakerState = this.speechRuns.get(packageName) === run
+      if (ownsSpeakerState) this.speechRuns.delete(packageName)
+
+      if (ownsSpeakerState) {
         if (success) {
           this.setSpeakerState(packageName, "stopped", {durationMs: duration ?? undefined})
         } else {
           this.setSpeakerState(packageName, "error", {
-            errorCode: MiniappErrorCode.TTS_UPSTREAM_ERROR,
+            errorCode,
             errorMessage: error ?? fallbackErrorMessage,
             durationMs: duration ?? undefined,
           })
         }
-        this.sendResult(
-          packageName,
-          requestId,
-          success,
-          {completed: success, duration},
-          error
-            ? {
-                code: MiniappErrorCode.TTS_UPSTREAM_ERROR,
-                message: error,
-              }
-            : undefined,
-        )
       }
 
+      this.sendResult(
+        packageName,
+        requestId,
+        success,
+        {completed, duration},
+        error
+          ? {
+              code: errorCode,
+              message: error,
+            }
+          : undefined,
+      )
+    }
+    run.onCancelled = () => sendPlaybackResult(true, null, null, "tts playback stopped", false)
+
+    try {
+      const voiceExplicit = payload.voice_id !== undefined || payload.voice !== undefined
+      const offlineSupportsVoice =
+        !voiceExplicit || voice === "default" || ttsModelManager.getAvailableLanguages().some((l) => l.code === voice)
+
+      const modelId = typeof payload.model_id === "string" ? payload.model_id : undefined
+      const forceLocal = payload.forceLocal === true
+      const cloudConnected = cloudClientService.isConnected()
+      console.log(
+        `${LOG_TAG}: TTS decision for ${packageName}: cloudConnected=${cloudConnected}, runtimeTts=yes, offlineVoice=${offlineSupportsVoice}, forceLocal=${forceLocal}`,
+      )
+
       const playOfflineTts = async (reason?: string): Promise<boolean> => {
+        if (run.cancelled) return true
         if (!offlineSupportsVoice || !(await ttsModelManager.isModelAvailable())) {
           return false
         }
+        if (run.cancelled) return true
+
+        const languageCode = ttsModelManager.getAvailableLanguages().some((l) => l.code === voice) ? voice : undefined
+        const offlineSentences = sentences
+
+        if (offlineSentences.length > 1) {
+          let firstSentence: TtsSynthesisResult
+          try {
+            firstSentence = await ttsModelManager.synthesizeToFile(offlineSentences[0], {languageCode, speed})
+          } catch (offlineErr) {
+            if (run.cancelled) return true
+            console.warn(
+              `${LOG_TAG}: offline sentence TTS synthesize failed${reason ? ` after ${reason}` : ""}:`,
+              offlineErr,
+            )
+            return false
+          }
+
+          if (run.cancelled) {
+            await Promise.resolve(firstSentence.cleanup?.())
+            return true
+          }
+          void runSentenceTtsPipeline({
+            sentences: offlineSentences,
+            firstAudio: firstSentence,
+            run,
+            synthesize: (sentence) => ttsModelManager.synthesizeToFile(sentence, {languageCode, speed}),
+            play: (audio, index) =>
+              new Promise((resolve) => {
+                const sentenceRequestId = `${audioRequestId}_sentence_${index}`
+                run.playbackRequestId = sentenceRequestId
+                audioPlaybackService.play(
+                  {
+                    requestId: sentenceRequestId,
+                    audioUrl: audio.audioUrl,
+                    appId: packageName,
+                    volume,
+                    stopOtherAudio,
+                  },
+                  (_responseId, success, error, duration, completionReason) => {
+                    if (run.playbackRequestId === sentenceRequestId) run.playbackRequestId = undefined
+                    resolve({success, completed: completionReason === "completed", error, duration})
+                  },
+                )
+              }),
+            onCleanupError: (cleanupError) => {
+              console.warn(`${LOG_TAG}: sentence TTS cleanup failed`, cleanupError)
+            },
+          }).then(
+            ({success, completed, error, duration}) => {
+              sendPlaybackResult(success, error, duration, "offline sentence tts playback failed", completed)
+            },
+            (pipelineError: unknown) => {
+              const message = pipelineError instanceof Error ? pipelineError.message : String(pipelineError)
+              sendPlaybackResult(false, message, null, "offline sentence tts playback failed", false)
+            },
+          )
+          queueMicrotask(() => {
+            if (this.speechRuns.get(packageName) === run) this.setSpeakerState(packageName, "playing")
+          })
+          return true
+        }
 
         let offlineGenerated: TtsSynthesisResult | undefined
 
         try {
-          const languageCode = ttsModelManager.getAvailableLanguages().some((l) => l.code === voice) ? voice : undefined
-          offlineGenerated = await ttsModelManager.synthesizeToFile(text, {languageCode, speed})
+          offlineGenerated = await ttsModelManager.synthesizeToFile(offlineSentences[0], {languageCode, speed})
         } catch (offlineErr) {
+          if (run.cancelled) return true
           console.warn(`${LOG_TAG}: offline TTS synthesize failed${reason ? ` after ${reason}` : ""}:`, offlineErr)
           return false
         }
 
         const generated = offlineGenerated
+        if (run.cancelled) {
+          await Promise.resolve(generated.cleanup?.())
+          return true
+        }
+        run.playbackRequestId = audioRequestId
         audioPlaybackService.play(
-          {requestId: audioRequestId, audioUrl: generated.audioUrl, appId: packageName, volume, stopOtherAudio},
-          (_respId, success, error, duration) => {
+          {
+            requestId: audioRequestId,
+            audioUrl: generated.audioUrl,
+            appId: packageName,
+            volume,
+            stopOtherAudio,
+          },
+          (_respId, success, error, duration, completionReason) => {
+            if (run.playbackRequestId === audioRequestId) run.playbackRequestId = undefined
             void Promise.resolve(generated.cleanup?.()).catch((cleanupError) => {
               console.warn(`${LOG_TAG}: offline TTS cleanup failed`, cleanupError)
             })
-            sendPlaybackResult(success, error, duration, "offline tts playback failed")
+            sendPlaybackResult(
+              success,
+              error,
+              duration,
+              "offline tts playback failed",
+              completionReason === "completed",
+            )
           },
         )
-        queueMicrotask(() => this.setSpeakerState(packageName, "playing"))
+        queueMicrotask(() => {
+          if (this.speechRuns.get(packageName) === run) this.setSpeakerState(packageName, "playing")
+        })
         return true
       }
 
       const playCloudTts = async (fallbackToOffline: boolean): Promise<boolean> => {
+        if (run.cancelled) return true
         let source: Awaited<ReturnType<typeof cloudClientService.tts.speak>>
         try {
-          source = await cloudClientService.tts.speak(text, {
+          source = await cloudClientService.tts.speak(cloudText, {
             ...(voiceExplicit && voice !== "default" ? {voice_id: voice} : {}),
             ...(modelId ? {model_id: modelId} : {}),
             ...(voiceSettings ? {voice_settings: voiceSettings} : {}),
           })
         } catch (cloudErr) {
+          if (run.cancelled) return true
           const error = cloudErr instanceof Error ? cloudErr.message : String(cloudErr)
           console.warn(`${LOG_TAG}: cloud TTS source failed: ${error}`)
           if (fallbackToOffline && (await playOfflineTts("cloud tts source failed"))) {
@@ -2076,10 +2422,20 @@ class LocalMiniappRuntime {
           return true
         }
 
+        if (run.cancelled) return true
+
+        run.playbackRequestId = audioRequestId
         await Promise.resolve(
           audioPlaybackService.play(
-            {requestId: audioRequestId, audioUrl: source.audioUrl, appId: packageName, volume, stopOtherAudio},
-            (_respId, success, error, duration) => {
+            {
+              requestId: audioRequestId,
+              audioUrl: source.audioUrl,
+              appId: packageName,
+              volume,
+              stopOtherAudio,
+            },
+            (_respId, success, error, duration, completionReason) => {
+              if (run.playbackRequestId === audioRequestId) run.playbackRequestId = undefined
               if (!success && fallbackToOffline) {
                 void playOfflineTts("cloud tts playback failed").then((started) => {
                   if (!started) {
@@ -2088,14 +2444,26 @@ class LocalMiniappRuntime {
                 })
                 return
               }
-              sendPlaybackResult(success, error, duration, "tts failed")
+              sendPlaybackResult(success, error, duration, "tts failed", completionReason === "completed")
             },
           ),
         )
-        queueMicrotask(() => this.setSpeakerState(packageName, "playing"))
+        queueMicrotask(() => {
+          if (this.speechRuns.get(packageName) === run) this.setSpeakerState(packageName, "playing")
+        })
         return true
       }
 
+      if (forceLocal) {
+        if (await playOfflineTts()) {
+          return
+        }
+        if (run.cancelled) return
+        const message = "tts unavailable: forceLocal requested but offline TTS model is not available"
+        sendPlaybackResult(false, message, null, message, false, MiniappErrorCode.TTS_LOCAL_UNAVAILABLE)
+        return
+      }
+
       if (cloudConnected && (await playCloudTts(true))) {
         return
       }
@@ -2111,28 +2479,23 @@ class LocalMiniappRuntime {
       }
 
       const message = "tts unavailable: no cloud TTS URL or offline TTS model"
-      this.setSpeakerState(packageName, "error", {
-        errorCode: MiniappErrorCode.TTS_UPSTREAM_ERROR,
-        errorMessage: message,
-      })
-      this.sendResult(packageName, requestId, false, undefined, {
-        code: MiniappErrorCode.TTS_UPSTREAM_ERROR,
-        message,
-      })
+      sendPlaybackResult(false, message, null, message, false)
     } catch (err) {
       console.error(`${LOG_TAG}: speak error:`, err)
       const message = err instanceof Error ? err.message : "TTS error"
-      this.setSpeakerState(packageName, "error", {
-        errorCode: MiniappErrorCode.TTS_UPSTREAM_ERROR,
-        errorMessage: message,
-      })
-      this.sendResult(packageName, requestId, false, undefined, {
-        code: MiniappErrorCode.TTS_UPSTREAM_ERROR,
-        message,
-      })
+      sendPlaybackResult(false, message, null, "TTS error", false)
     }
   }
 
+  private cancelSpeech(packageName: string): void {
+    const run = this.speechRuns.get(packageName)
+    if (!run) return
+    run.cancelled = true
+    this.speechRuns.delete(packageName)
+    if (run.playbackRequestId) audioPlaybackService.cancelPlayback(run.playbackRequestId)
+    run.onCancelled?.()
+  }
+
   private async handleRgbLed(packageName: string, payload: Record<string, unknown>, requestId?: string): Promise<void> {
     const coerceNumber = (value: unknown, fallback: number): number => {
       const coerced = Number(value)
@@ -2164,7 +2527,17 @@ class LocalMiniappRuntime {
 
   private async handleLocationPoll(packageName: string, requestId?: string): Promise<void> {
     try {
-      const {status} = await Location.requestForegroundPermissionsAsync()
+      // Expo's Android requestForegroundPermissionsAsync always delegates to
+      // Activity.requestPermissions(), even when permission is already granted.
+      // Calling it after the user presses Home therefore waits until the Activity
+      // resumes. Read the current grant first, and only enter the prompt flow
+      // while the Activity is actually foregrounded.
+      const permissionStartedAt = Date.now()
+      const permission = await resolveForegroundLocationPermission(Location, () => AppState.currentState)
+      const {status} = permission
+      console.log(
+        `${LOG_TAG}: location poll permission status=${status} appState=${AppState.currentState} elapsed=${Date.now() - permissionStartedAt}ms`,
+      )
       if (status !== "granted") {
         this.sendResult(packageName, requestId, false, undefined, {
           code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
@@ -2177,8 +2550,11 @@ class LocalMiniappRuntime {
       // a fresh fix if the cache is empty. Use Low accuracy on the fresh
       // path so we get a cell/wifi-tower fix in ~1s instead of waiting
       // for full GPS warm-up.
+      const locationStartedAt = Date.now()
       const cached = await Location.getLastKnownPositionAsync({maxAge: 60_000})
+      console.log(`${LOG_TAG}: location poll cache hit=${cached !== null} elapsed=${Date.now() - locationStartedAt}ms`)
       const location = cached ?? (await Location.getCurrentPositionAsync({accuracy: Location.Accuracy.Low}))
+      console.log(`${LOG_TAG}: location poll resolved elapsed=${Date.now() - locationStartedAt}ms`)
 
       this.sendResult(packageName, requestId, true, {
         lat: location.coords.latitude,
@@ -2220,10 +2596,70 @@ class LocalMiniappRuntime {
   private readonly blobStore = new BlobStore({
     sendResult: (packageName, requestId, ok, result, error) =>
       this.sendResult(packageName, requestId, ok, result, error),
-    getUserId: () =>
-      (useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.coreToken) as string | undefined) || "anonymous",
+    getUserId: () => cloudClientService.getMentraUserId(),
+  })
+  private readonly blobRequestQueues = new Map<string, Promise<void>>()
+
+  private readonly simpleStorage = new LocalMiniappStorage({
+    backend: localMiniappStorageBackend,
+    getUserId: () => cloudClientService.resolveMentraUserId(),
   })
 
+  /**
+   * BlobStore's file helpers are synchronous once a user namespace is selected,
+   * but first-boot Core auth is not. Queue requests per app behind stable
+   * identity resolution so CREATE/WRITE/COMMIT ordering survives that wait.
+   */
+  private enqueueBlobRequest(
+    packageName: string,
+    requestId: string | undefined,
+    operation: () => Promise<void> | void,
+  ): void {
+    const app = this.connectedApps.get(packageName)
+    const previous = this.blobRequestQueues.get(packageName) ?? Promise.resolve()
+    const queued = previous.then(async () => {
+      try {
+        await cloudClientService.resolveMentraUserId()
+      } catch (err) {
+        console.error(`${LOG_TAG}: blob identity error:`, err)
+        this.sendResult(packageName, requestId, false, undefined, {
+          code: MiniappErrorCode.NOT_CONNECTED,
+          message: "Blob storage is unavailable before sign-in completes",
+        })
+        return
+      }
+
+      // unregisterApp() or a crash-respawn may have replaced this app while
+      // identity resolution was pending. Never replay an old context's request
+      // against its replacement.
+      if (!app || this.connectedApps.get(packageName) !== app) return
+
+      // Invoke in request order, but do not keep the queue occupied for the
+      // lifetime of an async picker, download, or share sheet. CREATE/WRITE/
+      // COMMIT are synchronous and therefore still dispatch strictly in order.
+      try {
+        const pending = operation()
+        if (pending) {
+          void pending.catch((err) => this.handleBlobRequestError(packageName, requestId, err))
+        }
+      } catch (err) {
+        this.handleBlobRequestError(packageName, requestId, err)
+      }
+    })
+    this.blobRequestQueues.set(packageName, queued)
+    void queued.finally(() => {
+      if (this.blobRequestQueues.get(packageName) === queued) this.blobRequestQueues.delete(packageName)
+    })
+  }
+
+  private handleBlobRequestError(packageName: string, requestId: string | undefined, err: unknown): void {
+    console.error(`${LOG_TAG}: blob request error:`, err)
+    this.sendResult(packageName, requestId, false, undefined, {
+      code: MiniappErrorCode.INTERNAL,
+      message: err instanceof Error ? err.message : "Blob storage error",
+    })
+  }
+
   /**
    * Heading is a sensor stream — start the native compass when any mini
    * app is subscribed to "heading_update", stop it when none are.
@@ -2299,12 +2735,6 @@ class LocalMiniappRuntime {
   // Storage helpers
   // ---------------------------------------------------------------------------
 
-  private getStorageKeyPrefix(packageName: string): string {
-    const userId =
-      (useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.coreToken) as string | undefined) || "anonymous"
-    return `mentraos_localstorage_${userId}_${packageName}_`
-  }
-
   private async handleStorageGet(
     packageName: string,
     payload: Record<string, unknown>,
@@ -2319,9 +2749,8 @@ class LocalMiniappRuntime {
         })
         return
       }
-      const fullKey = this.getStorageKeyPrefix(packageName) + key
-      const result = mmkvStorage.load<unknown>(fullKey)
-      this.sendResult(packageName, requestId, true, {key, value: result.is_ok() ? result.value : null})
+      const value = await this.simpleStorage.get(packageName, key)
+      this.sendResult(packageName, requestId, true, {key, value})
     } catch (err) {
       console.error(`${LOG_TAG}: storage_get error:`, err)
       this.sendResult(packageName, requestId, false, undefined, {
@@ -2345,8 +2774,7 @@ class LocalMiniappRuntime {
         })
         return
       }
-      const fullKey = this.getStorageKeyPrefix(packageName) + key
-      mmkvStorage.save(fullKey, payload.value ?? null)
+      await this.simpleStorage.set(packageName, key, payload.value ?? null)
       this.sendResult(packageName, requestId, true)
     } catch (err) {
       console.error(`${LOG_TAG}: storage_set error:`, err)
@@ -2371,8 +2799,7 @@ class LocalMiniappRuntime {
         })
         return
       }
-      const fullKey = this.getStorageKeyPrefix(packageName) + key
-      mmkvStorage.remove(fullKey)
+      await this.simpleStorage.delete(packageName, key)
       this.sendResult(packageName, requestId, true)
     } catch (err) {
       console.error(`${LOG_TAG}: storage_delete error:`, err)
@@ -2389,9 +2816,7 @@ class LocalMiniappRuntime {
     requestId?: string,
   ): Promise<void> {
     try {
-      const prefix = this.getStorageKeyPrefix(packageName)
-      const allKeys = mmkvStorage.getAllKeys()
-      const keys = allKeys.filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length))
+      const keys = await this.simpleStorage.keys(packageName)
       this.sendResult(packageName, requestId, true, {keys})
     } catch (err) {
       console.error(`${LOG_TAG}: storage_list error:`, err)
@@ -2404,11 +2829,7 @@ class LocalMiniappRuntime {
 
   private async handleStorageClear(packageName: string, requestId?: string): Promise<void> {
     try {
-      const prefix = this.getStorageKeyPrefix(packageName)
-      const allKeys = mmkvStorage.getAllKeys()
-      for (const k of allKeys) {
-        if (k.startsWith(prefix)) mmkvStorage.remove(k)
-      }
+      await this.simpleStorage.clear(packageName)
       this.sendResult(packageName, requestId, true)
     } catch (err) {
       console.error(`${LOG_TAG}: storage_clear error:`, err)
@@ -2433,9 +2854,8 @@ class LocalMiniappRuntime {
         })
         return
       }
-      const fullKey = this.getStorageKeyPrefix(packageName) + key
-      const result = mmkvStorage.load<unknown>(fullKey)
-      this.sendResult(packageName, requestId, true, {has: result.is_ok()})
+      const has = await this.simpleStorage.has(packageName, key)
+      this.sendResult(packageName, requestId, true, {has})
     } catch (err) {
       console.error(`${LOG_TAG}: storage_has error:`, err)
       this.sendResult(packageName, requestId, false, undefined, {
@@ -2447,17 +2867,7 @@ class LocalMiniappRuntime {
 
   private async handleStorageGetAll(packageName: string, requestId?: string): Promise<void> {
     try {
-      const prefix = this.getStorageKeyPrefix(packageName)
-      const allKeys = mmkvStorage.getAllKeys()
-      const values: Record<string, string> = {}
-      for (const k of allKeys) {
-        if (!k.startsWith(prefix)) continue
-        const r = mmkvStorage.load<unknown>(k)
-        if (r.is_ok()) {
-          const v = r.value
-          values[k.slice(prefix.length)] = typeof v === "string" ? v : String(v ?? "")
-        }
-      }
+      const values = await this.simpleStorage.getAll(packageName)
       this.sendResult(packageName, requestId, true, {values})
     } catch (err) {
       console.error(`${LOG_TAG}: storage_get_all error:`, err)
@@ -2482,10 +2892,7 @@ class LocalMiniappRuntime {
         })
         return
       }
-      const prefix = this.getStorageKeyPrefix(packageName)
-      for (const [key, value] of Object.entries(values)) {
-        mmkvStorage.save(prefix + key, value ?? null)
-      }
+      await this.simpleStorage.setMultiple(packageName, values)
       this.sendResult(packageName, requestId, true)
     } catch (err) {
       console.error(`${LOG_TAG}: storage_set_multiple error:`, err)
@@ -2496,6 +2903,36 @@ class LocalMiniappRuntime {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Wi-Fi ADB
+  // ---------------------------------------------------------------------------
+
+  private async handleSetWifiAdbState(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    const result = await handleWifiAdbRequest(packageName, payload, {
+      isSystemPackage: (candidate) => this.isSystemPackage(candidate),
+      setWifiAdbState: async (enabled) => {
+        console.log(`${LOG_TAG}: set_wifi_adb_state enabled=${enabled} from ${packageName}`)
+        try {
+          await BluetoothSdk.setWifiAdbState(enabled)
+        } catch (error) {
+          console.error(`${LOG_TAG}: set_wifi_adb_state error:`, error)
+          throw error
+        }
+      },
+    })
+
+    if (result.ok) {
+      this.sendResult(packageName, requestId, true)
+      return
+    }
+
+    this.sendResult(packageName, requestId, false, undefined, result.error)
+  }
+
   // ---------------------------------------------------------------------------
   // Camera FOV
   // ---------------------------------------------------------------------------
@@ -2524,17 +2961,7 @@ class LocalMiniappRuntime {
         "preset" in request ? `preset=${request.preset}` : `fov=${request.fov} roi=${request.roiPosition ?? "center"}`
       console.log(`${LOG_TAG}: camera_fov_set ${description}`)
 
-      // Camera FOV is a direct btsdk call now (was the host-injected `cameraSettings`
-      // runtime hook — a pure BluetoothSdk.setCameraFov passthrough with no host coupling).
-      const result = await BluetoothSdk.setCameraFov(request)
-
-      useSettingsStore
-        .getState()
-        .setSetting(
-          ISLAND_SETTINGS_KEYS.cameraFov,
-          {fov: result.fov, roi_position: CAMERA_ROI_POSITION_VALUES[result.roiPosition]},
-          false,
-        )
+      const result = await phoneCameraFovCoordinator.setOverride(packageName, request)
       this.sendResult(packageName, requestId, true, result)
     } catch (err) {
       console.error(`${LOG_TAG}: camera_fov error:`, err)
@@ -2571,6 +2998,124 @@ class LocalMiniappRuntime {
     }
   }
 
+  /**
+   * Lifecycle-scoped glasses-side VAD override from a miniapp
+   * (session.mic.setVoiceActivityDetectionEnabled). Requires MICROPHONE in the
+   * miniapp manifest. Mentra Live only today — other models no-op via DeviceStore.
+   */
+  private async handleMicSetVadEnabled(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    const app = this.connectedApps.get(packageName)
+    const hasMicPermission = app?.installedManifest?.permissions?.some((p) => p.type === "MICROPHONE")
+    if (!hasMicPermission) {
+      logPermissionNotDeclared(packageName, "MICROPHONE", "to set VAD enabled", `{"type": "MICROPHONE"}`)
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+        message: `MICROPHONE permission not declared in miniapp.json. Add {"type": "MICROPHONE"} to the "permissions" array.`,
+        permission: "MICROPHONE",
+        operation: MiniappRequestType.MIC_SET_VAD_ENABLED,
+      })
+      return
+    }
+
+    if (typeof payload.enabled !== "boolean") {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: "enabled must be a boolean",
+      })
+      return
+    }
+
+    try {
+      const enabled = payload.enabled
+      console.log(`${LOG_TAG}: mic_set_vad_enabled ${enabled} (by ${packageName})`)
+      await micStateCoordinator.setMiniappGateOverride(packageName, "vad", enabled, this.getConfiguredMicGates())
+      this.sendResult(packageName, requestId, true)
+    } catch (err) {
+      console.error(`${LOG_TAG}: mic_set_vad_enabled error:`, err)
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "VAD set-enabled error",
+      })
+    }
+  }
+
+  /**
+   * Lifecycle-scoped center-mic loudness gate ("Barrier") override from a miniapp
+   * (session.mic.setLoudnessGateEnabled). Requires MICROPHONE in the miniapp
+   * manifest. Mentra Live only today — other models no-op via DeviceStore.
+   */
+  private async handleMicSetLoudnessGateEnabled(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    const app = this.connectedApps.get(packageName)
+    const hasMicPermission = app?.installedManifest?.permissions?.some((p) => p.type === "MICROPHONE")
+    if (!hasMicPermission) {
+      logPermissionNotDeclared(packageName, "MICROPHONE", "to set loudness gate enabled", `{"type": "MICROPHONE"}`)
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+        message: `MICROPHONE permission not declared in miniapp.json. Add {"type": "MICROPHONE"} to the "permissions" array.`,
+        permission: "MICROPHONE",
+        operation: MiniappRequestType.MIC_SET_LOUDNESS_GATE_ENABLED,
+      })
+      return
+    }
+
+    if (typeof payload.enabled !== "boolean") {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: "enabled must be a boolean",
+      })
+      return
+    }
+
+    try {
+      const enabled = payload.enabled
+      console.log(`${LOG_TAG}: mic_set_loudness_gate_enabled ${enabled} (by ${packageName})`)
+      await micStateCoordinator.setMiniappGateOverride(
+        packageName,
+        "loudnessGate",
+        enabled,
+        this.getConfiguredMicGates(),
+      )
+      this.sendResult(packageName, requestId, true)
+    } catch (err) {
+      console.error(`${LOG_TAG}: mic_set_loudness_gate_enabled error:`, err)
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "Loudness gate set-enabled error",
+      })
+    }
+  }
+
+  /**
+   * session.system.scanQr — host camera overlay. Must not clear miniapp
+   * foreground; the host seam is responsible for presenting a Modal on top.
+   */
+  private async handleScanQr(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    try {
+      const result = await invokeScanQrSeam(getUiSeams().scanQr, payload)
+      this.sendResult(packageName, requestId, true, result)
+    } catch (err) {
+      if (!getUiSeams().scanQr) {
+        console.warn(`${LOG_TAG}: scanQr seam missing — QR overlay is not registered`)
+      }
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: (err as {code?: string} | null | undefined)?.code || MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "QR scan failed",
+      })
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // System utilities (share, open URL, clipboard, download)
   // ---------------------------------------------------------------------------
@@ -2715,10 +3260,20 @@ class LocalMiniappRuntime {
       const result = await phonePhotoCoordinator.takePhoto(packageName, {
         size: payload.size as "low" | "medium" | "high" | "max" | "small" | "large" | "full" | undefined,
         mode: payload.mode as "photo" | "text" | undefined,
+        transferMethod: payload.transferMethod as "auto" | "direct" | "ble" | undefined,
         compress: payload.compress as "none" | "low" | "medium" | "high" | undefined,
         sound: payload.sound as boolean | undefined,
         saveToGallery: payload.saveToGallery as boolean | undefined,
         exposureTimeNs: payload.exposureTimeNs as number | undefined,
+        iso: payload.iso as number | null | undefined,
+        aeExposureDivisor: payload.aeExposureDivisor as number | undefined,
+        isoCap: payload.isoCap as number | undefined,
+        noiseReduction: payload.noiseReduction as boolean | undefined,
+        edgeEnhancement: payload.edgeEnhancement as boolean | undefined,
+        zsl: payload.zsl as boolean | undefined,
+        mfnr: payload.mfnr as boolean | undefined,
+        ispDigitalGain: payload.ispDigitalGain as number | undefined,
+        ispAnalogGain: payload.ispAnalogGain as string | undefined,
       })
       this.sendResult(packageName, requestId, true, result)
     } catch (err) {
@@ -2753,8 +3308,11 @@ class LocalMiniappRuntime {
     try {
       await phonePhotoCoordinator.warmUpCamera(packageName, {
         size: payload.size as "low" | "medium" | "high" | "max" | undefined,
+        mode: payload.mode as "photo" | "text" | undefined,
         exposureTimeNs: payload.exposureTimeNs as number | undefined,
         durationMs: payload.durationMs as number | undefined,
+        zsl: payload.zsl as boolean | undefined,
+        mfnr: payload.mfnr as boolean | undefined,
       })
       this.sendResult(packageName, requestId, true)
     } catch (err) {
@@ -2847,6 +3405,7 @@ class LocalMiniappRuntime {
         video: normalizeStreamVideoConfig(payload.video),
         audio: normalizeStreamAudioConfig(payload.audio),
         sound: payload.sound as boolean | undefined,
+        authToken: typeof payload.authToken === "string" ? payload.authToken : undefined,
       })
       this.sendResult(packageName, requestId, true, result)
     } catch (err) {
@@ -2942,7 +3501,7 @@ class LocalMiniappRuntime {
       return
     }
     try {
-      await requestWifiSetup(payload.reason as string | undefined)
+      await requestWifiSetup(payload.reason as string | undefined, packageName)
       this.sendResult(packageName, requestId, true)
     } catch (err) {
       this.sendResult(packageName, requestId, false, undefined, {
@@ -3006,27 +3565,12 @@ class LocalMiniappRuntime {
       }
     }
 
-    // Remove old subscriptions for this app
-    for (const oldStream of app.subscriptions) {
-      const subs = this.streamSubscribers.get(oldStream)
-      if (subs) {
-        subs.delete(packageName)
-        if (subs.size === 0) {
-          this.streamSubscribers.delete(oldStream)
-        }
-      }
-    }
-
     // Add new subscriptions
+    const previousSubscriptions = app.subscriptions
     app.subscriptions = new Set(streams)
-    for (const stream of streams) {
-      let subs = this.streamSubscribers.get(stream)
-      if (!subs) {
-        subs = new Set()
-        this.streamSubscribers.set(stream, subs)
-      }
-      subs.add(packageName)
-    }
+    app.forceLocalTranscriptionStreams.clear()
+    app.cloudTranscriptionStreams = new Set(streams.filter((stream) => stream.startsWith("transcription:")))
+    this.replaceStreamSubscribers(packageName, previousSubscriptions, app.subscriptions)
 
     this.recomputeMicRequirements()
     this.updateCloudSubscriptions()
@@ -3037,6 +3581,16 @@ class LocalMiniappRuntime {
   // Mic requirements
   // ===========================================================================
 
+  private getConfiguredMicGates(): {vadEnabled: boolean | null; loudnessGateEnabled: boolean | null} {
+    const bluetoothSettings = useSettingsStore.getState().getBluetoothSettings()
+    const configuredVad = bluetoothSettings.voice_activity_detection_enabled
+    const configuredLoudnessGate = bluetoothSettings.loudness_gate_enabled
+    return {
+      vadEnabled: typeof configuredVad === "boolean" ? configuredVad : null,
+      loudnessGateEnabled: typeof configuredLoudnessGate === "boolean" ? configuredLoudnessGate : null,
+    }
+  }
+
   private recomputeMicRequirements(): void {
     let anyPcm = false
     let anyLc3 = false
@@ -3045,7 +3599,11 @@ class LocalMiniappRuntime {
       if (stream === "audio_chunk") anyPcm = true
       if (stream.startsWith("transcription:") || stream.startsWith("translation:") || stream === "vad") anyLc3 = true
     }
-    micStateCoordinator.setLocalRequirements({pcm: anyPcm, lc3: anyLc3})
+    micStateCoordinator.setLocalRequirements({
+      pcm: anyPcm,
+      lc3: anyLc3,
+      ...this.getConfiguredMicGates(),
+    })
   }
 
   /**
@@ -3058,19 +3616,34 @@ class LocalMiniappRuntime {
   private updateCloudSubscriptions(): void {
     const cloudStreams = new Set<string>()
     let transcriptionLang: string | null = null
+    let forceLocalTranscriptionLang: string | null = null
+    let hasForceLocalTranscription = false
     for (const [stream, subscribers] of this.streamSubscribers) {
       if (subscribers.size === 0) continue
-      // Only transcription / translation need cloud delivery. Location,
-      // notifications, and calendar events are sourced natively on the phone
-      // and forwarded to miniapps directly via MantleManager — no cloud hop.
-      if (stream.startsWith("transcription:") || stream.startsWith("translation:")) {
+      // Only transcription / translation need cloud delivery. Location and
+      // notifications are sourced natively on the phone — no cloud hop.
+      if (stream.startsWith("translation:")) {
         cloudStreams.add(stream)
       }
-      if (stream.startsWith("transcription:") && transcriptionLang === null) {
-        transcriptionLang = stream.substring("transcription:".length)
+      if (stream.startsWith("transcription:")) {
+        const language = stream.substring("transcription:".length)
+        if (transcriptionLang === null) transcriptionLang = language
+
+        const routes = summarizeTranscriptionRoutes(subscribers, (packageName) =>
+          this.appTranscriptionRoutesForSubscription(packageName, stream),
+        )
+        if (routes.hasForceLocalSubscriber) {
+          hasForceLocalTranscription = true
+          if (forceLocalTranscriptionLang === null) forceLocalTranscriptionLang = language
+        }
+        if (routes.hasCloudSubscriber) cloudStreams.add(stream)
       }
     }
-    localSttFallbackCoordinator.onSubscriptionChange(transcriptionLang !== null, transcriptionLang)
+    localSttFallbackCoordinator.onSubscriptionChange(
+      transcriptionLang !== null,
+      forceLocalTranscriptionLang ?? transcriptionLang,
+      hasForceLocalTranscription,
+    )
 
     // Mirror the same set as typed AudioSubscription[] and push it to the cloud
     // runtime.
@@ -3108,12 +3681,21 @@ class LocalMiniappRuntime {
    */
   private buildCloudAudioSubscriptions(cloudStreams: Set<string>): AudioSubscription[] {
     const subs: AudioSubscription[] = []
+    // Union of every connected app's TRANSCRIPTION_CONFIG hints. Hints only
+    // apply to the auto-mode TRANSCRIPTION subscription (the wire schema has
+    // no hints field on specific-language sources — the language IS the hint
+    // there), and are deliberately NOT attached to translation sources.
+    const hintUnion = [...new Set([...this.transcriptionHintsByApp.values()].flat())].sort()
     const langSource = (code: string): LanguageSource =>
       code === "auto" || code === "*" ? {mode: "auto"} : {mode: "specific", code}
     for (const stream of cloudStreams) {
       if (stream.startsWith("transcription:")) {
         const lang = stream.substring("transcription:".length)
-        subs.push({kind: "transcription", language: langSource(lang)})
+        const source = langSource(lang)
+        subs.push({
+          kind: "transcription",
+          language: source.mode === "auto" && hintUnion.length > 0 ? {mode: "auto", hints: hintUnion} : source,
+        })
       } else if (stream.startsWith("translation:")) {
         const parts = stream.split(":")
         // Only `translation:<source>:<target>` maps cleanly; a concrete target
@@ -3168,21 +3750,25 @@ class LocalMiniappRuntime {
           } text="${d.text.slice(0, 48)}"`,
         )
       }
-      this.forwardEvent(`transcription:${d.resolvedLanguage}`, {
-        type: "transcription",
-        text: d.text,
-        isFinal: d.isFinal,
-        utteranceId: d.utteranceId,
-        transcribeLanguage: d.resolvedLanguage,
-        detectedLanguage: d.languageDetected ? d.resolvedLanguage : undefined,
-        startTime: d.startMs,
-        endTime: d.endMs,
-        speakerId: d.speakerId,
-        duration: d.durationMs,
-        provider: d.provider,
-        confidence: d.confidence,
-        __hostReceivedAt: receivedAt,
-      })
+      this.forwardEvent(
+        `transcription:${d.resolvedLanguage}`,
+        {
+          type: "transcription",
+          text: d.text,
+          isFinal: d.isFinal,
+          utteranceId: d.utteranceId,
+          transcribeLanguage: d.resolvedLanguage,
+          detectedLanguage: d.languageDetected ? d.resolvedLanguage : undefined,
+          startTime: d.startMs,
+          endTime: d.endMs,
+          speakerId: d.speakerId,
+          duration: d.durationMs,
+          provider: d.provider,
+          confidence: d.confidence,
+          __hostReceivedAt: receivedAt,
+        },
+        "cloud",
+      )
     })
 
     cloudClientService.onTranslation((d: TranslationData) => {
@@ -3265,7 +3851,7 @@ class LocalMiniappRuntime {
    * - Cloud sends "head_up" → miniapp protocol uses "head_position" (HEAD_POSITION)
    * - Cloud sends "VAD" (uppercase) → miniapp protocol uses "vad" (lowercase)
    */
-  public forwardEvent(streamType: string, data: unknown): void {
+  public forwardEvent(streamType: string, data: unknown, transcriptionSource?: TranscriptionEventSource): void {
     // Translate cloud event names to miniapp protocol stream types
     const normalizedStream = this.normalizeStreamType(streamType)
 
@@ -3340,16 +3926,14 @@ class LocalMiniappRuntime {
 
     if (matchedSubs.size === 0 && !perGestureStream) return
 
-    // BGCAP: count transcripts only once we know they're actually being handed
-    // to a subscriber. If the captions miniapp is unregistered/respawning (or
-    // hasn't subscribed yet) the cloud may still push transcripts that match no
-    // one — counting those would falsely show "forwarded" during the exact gap
-    // the diagnostic is meant to expose.
-    if (BGCAP_TELEMETRY && normalizedStream.startsWith("transcription:")) {
-      bgcapNoteTranscriptForward(!!(data as {isFinal?: boolean} | null)?.isFinal)
-    }
-
     for (const packageName of matchedSubs) {
+      let transcriptionRoute: "default" | "forceLocal" | "all" | undefined
+      if (normalizedStream.startsWith("transcription:") && transcriptionSource) {
+        const routes = this.appTranscriptionRoutesForEvent(packageName, normalizedStream)
+        transcriptionRoute =
+          transcriptionDeliveryRoute(transcriptionSource, routes, cloudClientService.isConnected()) ?? undefined
+        if (!transcriptionRoute) continue
+      }
       if (TRANSCRIPT_TIMING_TELEMETRY && normalizedStream.startsWith("transcription:")) {
         const transcript = data as {text?: string; isFinal?: boolean; __hostReceivedAt?: number} | null
         const now = Date.now()
@@ -3371,6 +3955,7 @@ class LocalMiniappRuntime {
         type: MiniappResponseType.EVENT,
         streamType: normalizedStream,
         data: outboundData,
+        ...(transcriptionRoute ? {transcriptionRoute} : {}),
       })
     }
 
@@ -3390,6 +3975,38 @@ class LocalMiniappRuntime {
     }
   }
 
+  private appTranscriptionRoutesForSubscription(
+    packageName: string,
+    stream: string,
+  ): {
+    cloud: boolean
+    forceLocal: boolean
+  } {
+    const app = this.connectedApps.get(packageName)
+    return {
+      cloud: app?.cloudTranscriptionStreams.has(stream) === true,
+      forceLocal: app?.forceLocalTranscriptionStreams.has(stream) === true,
+    }
+  }
+
+  private appTranscriptionRoutesForEvent(
+    packageName: string,
+    stream: string,
+  ): {
+    cloud: boolean
+    forceLocal: boolean
+  } {
+    const app = this.connectedApps.get(packageName)
+    const autoStream = `${MiniappStreamType.TRANSCRIPTION}:auto`
+    return {
+      cloud:
+        app?.cloudTranscriptionStreams.has(stream) === true || app?.cloudTranscriptionStreams.has(autoStream) === true,
+      forceLocal:
+        app?.forceLocalTranscriptionStreams.has(stream) === true ||
+        app?.forceLocalTranscriptionStreams.has(autoStream) === true,
+    }
+  }
+
   /**
    * Translate cloud event names to miniapp stream type values.
    */
@@ -3934,7 +4551,6 @@ class LocalMiniappRuntime {
   // ===========================================================================
 
   private ensurePingLoop(): void {
-    bgcapStartHeartbeat() // BGCAP diagnostic
     if (this.pingIntervalId !== null) return
 
     this.pingIntervalId = BgTimer.setInterval(() => {
@@ -3943,7 +4559,6 @@ class LocalMiniappRuntime {
   }
 
   private stopPingLoop(): void {
-    bgcapStopHeartbeat() // BGCAP diagnostic
     if (this.pingIntervalId !== null) {
       BgTimer.clearInterval(this.pingIntervalId)
       this.pingIntervalId = null
@@ -3951,23 +4566,18 @@ class LocalMiniappRuntime {
   }
 
   private doPingRound(): void {
-    const now = Date.now()
-    const staleThreshold = PING_INTERVAL_MS * PING_TIMEOUT_THRESHOLD
-
     const toRemove: string[] = []
 
     for (const [packageName, app] of this.connectedApps) {
-      if (now - app.lastPongAt > staleThreshold) {
+      const liveness = advanceMiniappPingLiveness(app.unansweredPingRounds, PING_TIMEOUT_THRESHOLD)
+      if (liveness.shouldUnregister) {
         console.warn(`${LOG_TAG}: ${packageName} missed ${PING_TIMEOUT_THRESHOLD} pings, unregistering`)
         toRemove.push(packageName)
         continue
       }
+      app.unansweredPingRounds = liveness.unansweredPingRounds
 
       // Send PING — SDK auto-replies with PONG
-      // BGCAP: stamp the OLDEST outstanding ping only — don't overwrite, or a
-      // background stall (pings keep firing on the native BgTimer while the
-      // miniapp engine is frozen) would reset the clock and hide its duration.
-      if (BGCAP_TELEMETRY && app.bgcapLastPingSentAt == null) app.bgcapLastPingSentAt = now
       this.sendToMiniapp(packageName, {
         type: MiniappRequestType.PING,
       })
@@ -3989,6 +4599,7 @@ class LocalMiniappRuntime {
     const app = this.connectedApps.get(packageName)
     if (app) {
       app.lastPongAt = Date.now()
+      app.unansweredPingRounds = 0
       this.clearForegroundProbe(packageName)
     }
   }
@@ -4016,7 +4627,17 @@ class LocalMiniappRuntime {
 
     // Belt-and-suspenders: clear any remaining state
     this.pendingCloudRequests.clear()
+    const hadButtonPressSubscribers = this.getButtonPressSubscribers().length > 0
     this.streamSubscribers.clear()
+    if (hadButtonPressSubscribers) {
+      for (const listener of this.buttonPressSubscriberListeners) {
+        try {
+          listener([])
+        } catch (error) {
+          console.warn(`${LOG_TAG}: button press subscriber listener threw during cleanup:`, error)
+        }
+      }
+    }
     this.connectedApps.clear()
     for (const timerId of this.foregroundProbeTimers.values()) {
       BgTimer.clearTimeout(timerId)