@mentra/engine 0.1.0-dev.0 → 0.1.0-dev.1

package/build/services/LocalMiniappRuntime.js

@@ -8,7 +8,7 @@
  * This runtime handles request dispatch, stream fan-out, and lifecycle
  * 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";
@@ -32,18 +32,30 @@ 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 { ISLAND_SETTINGS_KEYS, } from "../runtime/config";
 import { getAnalytics, getUiSeams } from "../runtime/bootstrap";
+import { invokeScanQrSeam } from "../runtime/scanQrSeam";
 import { normalizeStreamAudioConfig, normalizeStreamVideoConfig } from "../runtime/streamConfig";
+import { toLanguageHint } from "@mentra/cloud-protocol/languages";
+import { buildMiniappManifestSnapshot } from "../utils/miniappDiagnostics";
 import ttsModelManager from "./TTSModelManager";
 import { NavigationHandlers } from "./NavigationHandlers";
 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";
 /**
  * Strictness ordering for `location_stream` rate values. Higher index =
  * higher accuracy and higher power cost. The aggregate tier applied to
@@ -76,6 +88,14 @@ function withTimeout(promise, timeoutMs) {
     });
 }
 const LOG_TAG = "LOCAL_MINIAPP";
+const DIAGNOSTIC_MAX_LIST_ITEMS = 100;
+const DIAGNOSTIC_MAX_STRING_LENGTH = 512;
+function diagnosticStringList(values) {
+    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",
@@ -106,76 +126,32 @@ const REQUEST_WIFI_SETUP_TYPE = "miniapp_request_wifi_setup";
 // respawn path wired (MentraJSRouter.start), a genuinely dead context still
 // 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.__DEV__ === true;
-let bgcapHbTimer = null;
-let bgcapHbLast = 0;
-let bgcapTxCount = 0;
-let bgcapTxLastFinalAt = 0;
-let bgcapTxLastLogAt = 0;
-function bgcapStartHeartbeat() {
-    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() {
-    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) {
-    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(["on", "off"]);
 const RGB_LED_COLORS = new Set(["red", "green", "blue", "orange", "white"]);
 const CAMERA_FOV_MIN = 62;
 const CAMERA_FOV_MAX = 118;
-const CAMERA_FOV_DEFAULT = 102;
-const CAMERA_FOV_PRESETS = { narrow: 82, standard: CAMERA_FOV_DEFAULT, wide: 118 };
+const CAMERA_FOV_DEFAULT = 118;
+const CAMERA_FOV_PRESETS = { narrow: 82, standard: 102, wide: 118 };
 const CAMERA_ROI_POSITION_BY_NAME = { center: "center", bottom: "bottom", top: "top" };
-const CAMERA_ROI_POSITION_VALUES = { center: 0, bottom: 1, top: 2 };
+const localMiniappStorageBackend = {
+    get(key) {
+        const result = mmkvStorage.load(key);
+        return result.is_ok() ? result.value : null;
+    },
+    has(key) {
+        return mmkvStorage.load(key).is_ok();
+    },
+    set(key, value) {
+        mmkvStorage.save(key, value);
+    },
+    remove(key) {
+        mmkvStorage.remove(key);
+    },
+    keys() {
+        return mmkvStorage.getAllKeys();
+    },
+};
 // =============================================================================
 // Declared-permission record helper (for CONNECT_ACK / PERMISSIONS_UPDATE)
 // =============================================================================
@@ -292,10 +268,19 @@ class LocalMiniappRuntime {
     connectWaiters = new Map();
     /** Ref-counted stream subscriptions: stream → set of packageNames. */
     streamSubscribers = new Map();
+    /** Host observers for the Mentra Live button-capture policy. */
+    buttonPressSubscriberListeners = new Set();
     /** Guards one-time wiring of the cloud transcript/translation fan-out. */
     cloudResultsWired = false;
     cloudStatusWired = false;
     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.
+     */
+    transcriptionHintsByApp = new Map();
     /** Ping interval handle. */
     pingIntervalId = null;
     foregroundProbeTimers = new Map();
@@ -310,12 +295,95 @@ class LocalMiniappRuntime {
     onLivenessTimeout = null;
     /** Pending cloud requests: requestId → packageName that originated the request. */
     pendingCloudRequests = new Map();
+    speechRuns = new Map();
     // Browser fallback token auth — HMAC-signed blob with a phone-local
     // secret. Both issuer and verifier are the same process, so the
     // secret never leaves the device.
     localSecret = `miniapp_${Date.now()}_${Math.random().toString(36).slice(2, 14)}`;
     usedTokens = new Set();
     constructor() { }
+    /** Snapshot of miniapps actively subscribed to hardware button events. */
+    getButtonPressSubscribers() {
+        return [...(this.streamSubscribers.get(MiniappStreamType.BUTTON_PRESS) ?? [])].sort();
+    }
+    /** Observe active hardware-button subscriptions. */
+    onButtonPressSubscribersChanged(listener) {
+        this.buttonPressSubscriberListeners.add(listener);
+        return () => this.buttonPressSubscriberListeners.delete(listener);
+    }
+    /** Report-safe live miniapp/subscription/resource snapshot. */
+    getDiagnosticSnapshot(nowMs = Date.now()) {
+        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(),
+            },
+        };
+    }
+    replaceStreamSubscribers(packageName, previousStreams, nextStreams) {
+        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))
@@ -502,6 +570,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
@@ -522,21 +591,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,
@@ -656,6 +721,7 @@ class LocalMiniappRuntime {
     }
     unregisterApp(packageName) {
         console.log(`${LOG_TAG}: unregisterApp(${packageName})`);
+        const releasedMicGateOverride = micStateCoordinator.clearMiniappGateOverrides(packageName);
         this.clearForegroundProbe(packageName);
         this.clearMiniappAuthRefresh(packageName);
         this.clearMiniappAuthDeliveryRetry(packageName);
@@ -664,21 +730,39 @@ 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);
         // Tear down this app's blob state: abort in-flight uploads + close readers
@@ -728,6 +812,11 @@ class LocalMiniappRuntime {
         localDisplayManager.onUnmount(packageName);
         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) {
             this.stopPingLoop();
@@ -824,6 +913,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;
@@ -890,9 +982,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);
@@ -900,23 +1001,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;
             }
             case MiniappRequestType.SHARE:
@@ -931,51 +1015,54 @@ 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
             case MiniappRequestType.PHOTO:
@@ -1028,8 +1115,19 @@ class LocalMiniappRuntime {
                     message: "Dashboard API is deferred in v1",
                 });
                 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;
         }
     }
@@ -1046,6 +1144,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);
         const capabilities = getModelCapabilities(defaultWearable || DeviceTypes.NONE);
@@ -1091,10 +1190,12 @@ class LocalMiniappRuntime {
         this.flushConnectWaiters(packageName);
     }
     async requestMiniappAuth(packageName, opts) {
-        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 } : {}),
+        });
     }
     async handleAuthRefresh(packageName, payload, requestId) {
         try {
@@ -1231,6 +1332,51 @@ class LocalMiniappRuntime {
             this.deliverInitialMiniappAuth(packageName, undefined, 0);
         }
     }
+    /**
+     * 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.
+     */
+    handleTranscriptionConfig(packageName, payload, requestId) {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        const config = (payload.config ?? {});
+        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 = [];
+            const invalid = [];
+            for (const raw of rawHints) {
+                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 });
+    }
     handleSubscribe(packageName, payload, requestId) {
         const app = this.connectedApps.get(packageName);
         if (!app)
@@ -1241,6 +1387,8 @@ class LocalMiniappRuntime {
         // The strictest rate wins when multiple `location_stream` entries appear
         // in one SUBSCRIBE — the same rule we apply across apps.
         let requestedLocationRate = null;
+        const forceLocalTranscriptionStreams = new Set();
+        const cloudTranscriptionStreams = new Set();
         const streams = rawStreams?.map((s) => {
             if (typeof s === "object" && s !== null) {
                 if (s.stream === "location_stream") {
@@ -1249,8 +1397,16 @@ 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;
         });
         if (!Array.isArray(streams)) {
@@ -1276,8 +1432,6 @@ class LocalMiniappRuntime {
                 return "READ_NOTIFICATIONS";
             if (s === "phone_notification_dismissed")
                 return "READ_NOTIFICATIONS";
-            if (s === "calendar_event")
-                return "CALENDAR";
             return null;
         };
         for (const stream of streams) {
@@ -1295,26 +1449,12 @@ class LocalMiniappRuntime {
                 return;
             }
         }
-        // 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();
         this.recomputeHeadingSubscription();
@@ -1329,6 +1469,30 @@ class LocalMiniappRuntime {
         // to wait for the first change event.
         this.emitInitialSnapshots(packageName, streams);
     }
+    async handleCalendarListEvents(packageName, payload, requestId) {
+        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.)
@@ -1518,6 +1682,7 @@ class LocalMiniappRuntime {
         const audioRequestId = requestId || `local_${Date.now()}`;
         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 }, (_respId, success, error, duration) => {
             if (success) {
@@ -1544,6 +1709,7 @@ class LocalMiniappRuntime {
         queueMicrotask(() => this.setSpeakerState(packageName, "playing"));
     }
     handleStopAudio(packageName, _payload, requestId) {
+        this.cancelSpeech(packageName);
         audioPlaybackService.stopForApp(packageName);
         this.setSpeakerState(packageName, "stopped");
         this.sendResult(packageName, requestId, true);
@@ -1730,84 +1896,184 @@ class LocalMiniappRuntime {
         }
     }
     async handleSpeak(packageName, payload, requestId) {
-        const text = payload.text;
-        if (!text) {
+        const rawText = payload.text;
+        const rawSentences = typeof rawText === "string"
+            ? [rawText.trim()].filter(Boolean)
+            : Array.isArray(rawText)
+                ? rawText
+                    .filter((sentence) => 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;
         }
-        try {
-            const voice = (payload.voice_id ?? payload.voice) || "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
-                : 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}`);
-            let terminalSent = false;
-            const sendPlaybackResult = (success, error, duration, fallbackErrorMessage) => {
-                if (terminalSent)
-                    return;
-                terminalSent = true;
+        const cloudText = sentences.join(" ");
+        const voice = (payload.voice_id ?? payload.voice) || "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
+            : undefined;
+        const speed = typeof voiceSettings?.speed === "number" ? voiceSettings.speed : undefined;
+        const run = { id: audioRequestId, cancelled: false };
+        this.cancelSpeech(packageName);
+        this.speechRuns.set(packageName, run);
+        this.setSpeakerState(packageName, "loading");
+        let terminalSent = false;
+        const sendPlaybackResult = (success, error, duration, fallbackErrorMessage, completed = success, errorCode = 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) => {
+                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;
+                    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) => {
+                        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;
                 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;
-                audioPlaybackService.play({ requestId: audioRequestId, audioUrl: generated.audioUrl, appId: packageName, volume, stopOtherAudio }, (_respId, success, error, duration) => {
+                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, 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(() => {
+                    if (this.speechRuns.get(packageName) === run)
+                        this.setSpeakerState(packageName, "playing");
                 });
-                queueMicrotask(() => this.setSpeakerState(packageName, "playing"));
                 return true;
             };
             const playCloudTts = async (fallbackToOffline) => {
+                if (run.cancelled)
+                    return true;
                 let source;
                 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"))) {
@@ -1816,7 +2082,18 @@ class LocalMiniappRuntime {
                     sendPlaybackResult(false, error, null, "tts failed");
                     return true;
                 }
-                await Promise.resolve(audioPlaybackService.play({ requestId: audioRequestId, audioUrl: source.audioUrl, appId: packageName, volume, stopOtherAudio }, (_respId, success, error, duration) => {
+                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, completionReason) => {
+                    if (run.playbackRequestId === audioRequestId)
+                        run.playbackRequestId = undefined;
                     if (!success && fallbackToOffline) {
                         void playOfflineTts("cloud tts playback failed").then((started) => {
                             if (!started) {
@@ -1825,11 +2102,24 @@ 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;
             }
@@ -1842,28 +2132,24 @@ class LocalMiniappRuntime {
                 return;
             }
             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);
         }
     }
+    cancelSpeech(packageName) {
+        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?.();
+    }
     async handleRgbLed(packageName, payload, requestId) {
         const coerceNumber = (value, fallback) => {
             const coerced = Number(value);
@@ -1885,7 +2171,15 @@ class LocalMiniappRuntime {
     }
     async handleLocationPoll(packageName, requestId) {
         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,
@@ -1897,8 +2191,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,
                 lng: location.coords.longitude,
@@ -1933,8 +2230,64 @@ class LocalMiniappRuntime {
      */
     blobStore = new BlobStore({
         sendResult: (packageName, requestId, ok, result, error) => this.sendResult(packageName, requestId, ok, result, error),
-        getUserId: () => useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.coreToken) || "anonymous",
+        getUserId: () => cloudClientService.getMentraUserId(),
+    });
+    blobRequestQueues = new Map();
+    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.
+     */
+    enqueueBlobRequest(packageName, requestId, operation) {
+        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);
+        });
+    }
+    handleBlobRequestError(packageName, requestId, err) {
+        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.
@@ -2009,10 +2362,6 @@ class LocalMiniappRuntime {
     // ---------------------------------------------------------------------------
     // Storage helpers
     // ---------------------------------------------------------------------------
-    getStorageKeyPrefix(packageName) {
-        const userId = useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.coreToken) || "anonymous";
-        return `mentraos_localstorage_${userId}_${packageName}_`;
-    }
     async handleStorageGet(packageName, payload, requestId) {
         try {
             const key = payload.key;
@@ -2023,9 +2372,8 @@ class LocalMiniappRuntime {
                 });
                 return;
             }
-            const fullKey = this.getStorageKeyPrefix(packageName) + key;
-            const result = mmkvStorage.load(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);
@@ -2045,8 +2393,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) {
@@ -2067,8 +2414,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) {
@@ -2081,9 +2427,7 @@ class LocalMiniappRuntime {
     }
     async handleStorageList(packageName, _payload, requestId) {
         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) {
@@ -2096,12 +2440,7 @@ class LocalMiniappRuntime {
     }
     async handleStorageClear(packageName, requestId) {
         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) {
@@ -2122,9 +2461,8 @@ class LocalMiniappRuntime {
                 });
                 return;
             }
-            const fullKey = this.getStorageKeyPrefix(packageName) + key;
-            const result = mmkvStorage.load(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);
@@ -2136,18 +2474,7 @@ class LocalMiniappRuntime {
     }
     async handleStorageGetAll(packageName, requestId) {
         try {
-            const prefix = this.getStorageKeyPrefix(packageName);
-            const allKeys = mmkvStorage.getAllKeys();
-            const values = {};
-            for (const k of allKeys) {
-                if (!k.startsWith(prefix))
-                    continue;
-                const r = mmkvStorage.load(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) {
@@ -2168,10 +2495,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) {
@@ -2183,6 +2507,29 @@ class LocalMiniappRuntime {
         }
     }
     // ---------------------------------------------------------------------------
+    // Wi-Fi ADB
+    // ---------------------------------------------------------------------------
+    async handleSetWifiAdbState(packageName, payload, requestId) {
+        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
     // ---------------------------------------------------------------------------
     async handleCameraFov(packageName, payload, requestId) {
@@ -2202,12 +2549,7 @@ class LocalMiniappRuntime {
             const request = normalizeCameraFovPayload(payload);
             const description = "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) {
@@ -2244,6 +2586,103 @@ 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.
+     */
+    async handleMicSetVadEnabled(packageName, payload, requestId) {
+        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.
+     */
+    async handleMicSetLoudnessGateEnabled(packageName, payload, requestId) {
+        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.
+     */
+    async handleScanQr(packageName, payload, requestId) {
+        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?.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "QR scan failed",
+            });
+        }
+    }
     // ---------------------------------------------------------------------------
     // System utilities (share, open URL, clipboard, download)
     // ---------------------------------------------------------------------------
@@ -2371,10 +2810,20 @@ class LocalMiniappRuntime {
             const result = await phonePhotoCoordinator.takePhoto(packageName, {
                 size: payload.size,
                 mode: payload.mode,
+                transferMethod: payload.transferMethod,
                 compress: payload.compress,
                 sound: payload.sound,
                 saveToGallery: payload.saveToGallery,
                 exposureTimeNs: payload.exposureTimeNs,
+                iso: payload.iso,
+                aeExposureDivisor: payload.aeExposureDivisor,
+                isoCap: payload.isoCap,
+                noiseReduction: payload.noiseReduction,
+                edgeEnhancement: payload.edgeEnhancement,
+                zsl: payload.zsl,
+                mfnr: payload.mfnr,
+                ispDigitalGain: payload.ispDigitalGain,
+                ispAnalogGain: payload.ispAnalogGain,
             });
             this.sendResult(packageName, requestId, true, result);
         }
@@ -2404,8 +2853,11 @@ class LocalMiniappRuntime {
         try {
             await phonePhotoCoordinator.warmUpCamera(packageName, {
                 size: payload.size,
+                mode: payload.mode,
                 exposureTimeNs: payload.exposureTimeNs,
                 durationMs: payload.durationMs,
+                zsl: payload.zsl,
+                mfnr: payload.mfnr,
             });
             this.sendResult(packageName, requestId, true);
         }
@@ -2485,6 +2937,7 @@ class LocalMiniappRuntime {
                 video: normalizeStreamVideoConfig(payload.video),
                 audio: normalizeStreamAudioConfig(payload.audio),
                 sound: payload.sound,
+                authToken: typeof payload.authToken === "string" ? payload.authToken : undefined,
             });
             this.sendResult(packageName, requestId, true, result);
         }
@@ -2563,7 +3016,7 @@ class LocalMiniappRuntime {
             return;
         }
         try {
-            await requestWifiSetup(payload.reason);
+            await requestWifiSetup(payload.reason, packageName);
             this.sendResult(packageName, requestId, true);
         }
         catch (err) {
@@ -2622,26 +3075,12 @@ class LocalMiniappRuntime {
                 return { ok: false, error: "MICROPHONE permission not declared in miniapp.json" };
             }
         }
-        // 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();
         return { ok: true };
@@ -2649,6 +3088,15 @@ class LocalMiniappRuntime {
     // ===========================================================================
     // Mic requirements
     // ===========================================================================
+    getConfiguredMicGates() {
+        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,
+        };
+    }
     recomputeMicRequirements() {
         let anyPcm = false;
         let anyLc3 = false;
@@ -2660,7 +3108,11 @@ class LocalMiniappRuntime {
             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(),
+        });
     }
     /**
      * Recompute the aggregated v2 cloud subscription list across all local miniapps.
@@ -2672,20 +3124,31 @@ class LocalMiniappRuntime {
     updateCloudSubscriptions() {
         const cloudStreams = new Set();
         let transcriptionLang = null;
+        let forceLocalTranscriptionLang = 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.
         this.ensureCloudResultsWired();
@@ -2720,11 +3183,20 @@ class LocalMiniappRuntime {
      */
     buildCloudAudioSubscriptions(cloudStreams) {
         const subs = [];
+        // 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) => 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(":");
@@ -2787,7 +3259,7 @@ class LocalMiniappRuntime {
                 provider: d.provider,
                 confidence: d.confidence,
                 __hostReceivedAt: receivedAt,
-            });
+            }, "cloud");
         });
         cloudClientService.onTranslation((d) => {
             this.forwardEvent(`translation:${d.source.language}:${d.target.language}`, {
@@ -2858,7 +3330,7 @@ class LocalMiniappRuntime {
      * - Cloud sends "head_up" → miniapp protocol uses "head_position" (HEAD_POSITION)
      * - Cloud sends "VAD" (uppercase) → miniapp protocol uses "vad" (lowercase)
      */
-    forwardEvent(streamType, data) {
+    forwardEvent(streamType, data, transcriptionSource) {
         // Translate cloud event names to miniapp protocol stream types
         const normalizedStream = this.normalizeStreamType(streamType);
         // Collect all subscribers: exact match, plus wildcard matches for streams
@@ -2938,15 +3410,15 @@ 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?.isFinal);
-        }
         for (const packageName of matchedSubs) {
+            let transcriptionRoute;
+            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;
                 const now = Date.now();
@@ -2964,6 +3436,7 @@ class LocalMiniappRuntime {
                 type: MiniappResponseType.EVENT,
                 streamType: normalizedStream,
                 data: outboundData,
+                ...(transcriptionRoute ? { transcriptionRoute } : {}),
             });
         }
         // Send a separate envelope to per-gesture subscribers tagged with the
@@ -2981,6 +3454,22 @@ class LocalMiniappRuntime {
             }
         }
     }
+    appTranscriptionRoutesForSubscription(packageName, stream) {
+        const app = this.connectedApps.get(packageName);
+        return {
+            cloud: app?.cloudTranscriptionStreams.has(stream) === true,
+            forceLocal: app?.forceLocalTranscriptionStreams.has(stream) === true,
+        };
+    }
+    appTranscriptionRoutesForEvent(packageName, stream) {
+        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.
      */
@@ -3469,7 +3958,6 @@ class LocalMiniappRuntime {
     // Ping / pong liveness
     // ===========================================================================
     ensurePingLoop() {
-        bgcapStartHeartbeat(); // BGCAP diagnostic
         if (this.pingIntervalId !== null)
             return;
         this.pingIntervalId = BgTimer.setInterval(() => {
@@ -3477,28 +3965,22 @@ class LocalMiniappRuntime {
         }, PING_INTERVAL_MS);
     }
     stopPingLoop() {
-        bgcapStopHeartbeat(); // BGCAP diagnostic
         if (this.pingIntervalId !== null) {
             BgTimer.clearInterval(this.pingIntervalId);
             this.pingIntervalId = null;
         }
     }
     doPingRound() {
-        const now = Date.now();
-        const staleThreshold = PING_INTERVAL_MS * PING_TIMEOUT_THRESHOLD;
         const toRemove = [];
         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,
             });
@@ -3518,6 +4000,7 @@ class LocalMiniappRuntime {
         const app = this.connectedApps.get(packageName);
         if (app) {
             app.lastPongAt = Date.now();
+            app.unansweredPingRounds = 0;
             this.clearForegroundProbe(packageName);
         }
     }
@@ -3541,7 +4024,18 @@ 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);