@mentra/engine 3.2.0-dev.115 → 3.2.0-dev.120

package/src/services/LocalMiniappRuntime.ts

@@ -67,7 +67,7 @@ import {
 } from "../runtime/config"
 import {getAnalytics, getUiSeams} from "../runtime/bootstrap"
 import {invokeScanQrSeam} from "../runtime/scanQrSeam"
-import {normalizeStreamAudioConfig, normalizeStreamVideoConfig} from "../runtime/streamConfig"
+import {normalizeStreamAudioConfig, normalizeStreamVideoConfig, resolveCaptureAudio} from "../runtime/streamConfig"
 import {toLanguageHint} from "@mentra/cloud-protocol/languages"
 import type {AudioSubscription, LanguageSource, TranscriptionData, TranslationData} from "@mentra/cloud-protocol"
 import {buildMiniappManifestSnapshot, type MiniappRuntimeDiagnosticSnapshot} from "../utils/miniappDiagnostics"
@@ -80,6 +80,7 @@ import {resolveForegroundLocationPermission} from "./ForegroundLocationPermissio
 import {advanceMiniappPingLiveness} from "./MiniappLiveness"
 import {listPhoneCalendarEvents, PhoneCalendarError} from "./PhoneCalendarService"
 import {LocalMiniappStorage} from "./LocalMiniappStorage"
+import acsMeetingService, {parseAcsOutgoingVideo, resolveAcsAudioSource} from "./AcsMeetingService"
 
 // =============================================================================
 // Types
@@ -953,6 +954,9 @@ class LocalMiniappRuntime {
     void phoneVideoCoordinator.stopForApp(packageName).catch((error) => {
       console.warn(`${LOG_TAG}: failed to stop video recording for ${packageName} on unregister`, error)
     })
+    void acsMeetingService.leaveIfOwner(packageName).catch((error) => {
+      console.warn(`${LOG_TAG}: failed to leave ACS meeting for ${packageName} on unregister`, error)
+    })
 
     // Detach the per-app nav event forwarder but leave the native nav session
     // running. The user may have just closed the mini-app UI and will reopen
@@ -1307,6 +1311,21 @@ class LocalMiniappRuntime {
       case MiniappRequestType.MANAGED_STREAM_STOP:
         void this.handleManagedStreamStop(packageName, payload, requestId)
         break
+      case MiniappRequestType.MEETING_JOIN:
+        void this.handleMeetingJoin(packageName, payload, requestId)
+        break
+      case MiniappRequestType.MEETING_LEAVE:
+        void this.handleMeetingLeave(packageName, requestId)
+        break
+      case MiniappRequestType.MEETING_SET_MUTED:
+        void this.handleMeetingSetMuted(packageName, payload, requestId)
+        break
+      case MiniappRequestType.MEETING_UPDATE_VIDEO_SOURCE:
+        void this.handleMeetingUpdateVideoSource(packageName, payload, requestId)
+        break
+      case MiniappRequestType.MEETING_GET_STATE:
+        void this.handleMeetingGetState(packageName, requestId)
+        break
       case REQUEST_WIFI_SETUP_TYPE:
         void this.handleRequestWifiSetup(packageName, payload, requestId)
         break
@@ -1409,6 +1428,7 @@ class LocalMiniappRuntime {
         packageName,
         capabilities,
         permissions: declaredPermissions,
+        hostFeatures: {captureAudio: true},
         ...(initialAuth ? {auth: initialAuth} : {}),
       },
       requestId,
@@ -3406,6 +3426,7 @@ class LocalMiniappRuntime {
         audio: normalizeStreamAudioConfig(payload.audio),
         sound: payload.sound as boolean | undefined,
         authToken: typeof payload.authToken === "string" ? payload.authToken : undefined,
+        captureAudio: resolveCaptureAudio(payload.captureAudio, resolveAcsAudioSource().source),
       })
       this.sendResult(packageName, requestId, true, result)
     } catch (err) {
@@ -3462,6 +3483,7 @@ class LocalMiniappRuntime {
         audio: normalizeStreamAudioConfig(payload.audio),
         sound: payload.sound as boolean | undefined,
         ingest: payload.ingest as "srt" | "whip" | undefined,
+        captureAudio: resolveCaptureAudio(payload.captureAudio, resolveAcsAudioSource().source),
       })
       this.sendResult(packageName, requestId, true, result)
     } catch (err) {
@@ -3482,6 +3504,125 @@ class LocalMiniappRuntime {
     return this.handleStreamStop(packageName, payload, requestId)
   }
 
+  private ensureMeetingStateBridge(): void {
+    acsMeetingService.setStateHandler((owner, state) => {
+      this.sendToMiniapp(owner, {
+        type: MiniappResponseType.MEETING_STATE,
+        ...state,
+      })
+    })
+  }
+
+  private async handleMeetingJoin(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    this.ensureMeetingStateBridge()
+    const meetingUrl = typeof payload.meetingUrl === "string" ? payload.meetingUrl : ""
+    const token = typeof payload.token === "string" ? payload.token : ""
+    const videoSource = payload.videoSource as {type?: string; url?: string} | undefined
+    const whepUrl = videoSource?.type === "whep" ? videoSource.url ?? "" : ""
+    const displayName = typeof payload.displayName === "string" ? payload.displayName : undefined
+    if (!meetingUrl || !token || !whepUrl) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: "meetingUrl, token, and a WHEP videoSource are required",
+      })
+      return
+    }
+    try {
+      let video: ReturnType<typeof parseAcsOutgoingVideo>
+      try {
+        video = parseAcsOutgoingVideo(payload.video)
+      } catch (error) {
+        this.sendResult(packageName, requestId, false, undefined, {
+          code: MiniappErrorCode.INVALID_ARGUMENT,
+          message: error instanceof Error ? error.message : "Invalid meeting video",
+        })
+        return
+      }
+      const state = await acsMeetingService.join(packageName, {
+        meetingUrl,
+        token,
+        whepUrl,
+        displayName,
+        ...(video ? {video} : {}),
+      })
+      this.sendResult(packageName, requestId, true, state)
+    } catch (err) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "ACS meeting join failed",
+      })
+    }
+  }
+
+  private async handleMeetingLeave(packageName: string, requestId?: string): Promise<void> {
+    try {
+      await acsMeetingService.leave(packageName)
+      this.sendResult(packageName, requestId, true)
+    } catch (err) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "ACS meeting leave failed",
+      })
+    }
+  }
+
+  private async handleMeetingSetMuted(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    try {
+      const state = await acsMeetingService.setMuted(packageName, Boolean(payload.muted))
+      this.sendResult(packageName, requestId, true, state)
+    } catch (err) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "ACS mute failed",
+      })
+    }
+  }
+
+  private async handleMeetingUpdateVideoSource(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    const videoSource = payload.videoSource as {type?: string; url?: string} | undefined
+    const whepUrl = videoSource?.type === "whep" ? videoSource.url ?? "" : ""
+    if (!whepUrl) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: "videoSource must be a WHEP URL",
+      })
+      return
+    }
+    try {
+      await acsMeetingService.updateVideoSource(packageName, whepUrl)
+      this.sendResult(packageName, requestId, true)
+    } catch (err) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "ACS video source update failed",
+      })
+    }
+  }
+
+  private async handleMeetingGetState(packageName: string, requestId?: string): Promise<void> {
+    try {
+      const state = await acsMeetingService.readState(packageName)
+      this.sendResult(packageName, requestId, true, state)
+    } catch (err) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "ACS getState failed",
+      })
+    }
+  }
+
   /**
    * session.glasses.requestWifiSetup — open the phone's glasses Wi-Fi setup
    * flow. The host owns the actual UI via the `engine.configure({ui})` seam;

package/src/services/MentraJSRouter.ts

@@ -469,7 +469,13 @@ export class MentraJSRouter {
     //    dead and let the host surface a "tap to retry" banner.
     if (iface === "__error") {
       const payload = this.tryParseArgs(msg.argsJson)
-      this.logger.error(`[${packageName}] ${method}`, payload)
+      // ready_nack is a liveness probe, not a crash. Logging it at error
+      // painted WHIP-start queue delay as a Mentra-Call exception.
+      if (method === "ready_nack") {
+        this.logger.warn(`[${packageName}] ${method}`, payload)
+      } else {
+        this.logger.error(`[${packageName}] ${method}`, payload)
+      }
       if (this.crashController) {
         // Only treat "exception" + "unhandledRejection" + "uncaught" as
         // crash signals. `console.error` calls also flow through the

package/src/services/PhoneCameraFovCoordinator.ts

@@ -90,6 +90,40 @@ export class PhoneCameraFovCoordinator {
     })
   }
 
+  /**
+   * Re-assert the current override on the glasses.
+   *
+   * The on-connect device-settings push replays the persistent `camera_fov`,
+   * so glasses that connect mid-call come up at the user's saved value and
+   * silently drop a miniapp's override — a Mentra Call wearer loses the 102°
+   * bottom crop by connecting their glasses after joining.
+   *
+   * The effective lease is recomputed inside [enqueue], not captured at call
+   * time: a `setOverride` or `releaseForApp` already queued ahead of this must
+   * win, and it is this coordinator that has to be the authoritative last
+   * writer. Sends the complete override — `fov` *and* `roiPosition` — because
+   * the scalar alone leaves the ROI wherever the persistent setting put it.
+   *
+   * No-op in legacy mode: those commands restart the camera HAL, which is far
+   * too expensive to fire on every reconnect.
+   */
+  reapplyEffectiveOverride(): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.legacyMode) return
+      const leaseId = this.effectiveLeaseId
+      if (!leaseId) return
+      const entry = [...this.overrides.values()].find((candidate) => candidate.leaseId === leaseId)
+      if (!entry) return
+      await BluetoothSdk.setCameraFovOverride({
+        leaseId,
+        fov: entry.fov,
+        roiPosition: entry.roiPosition,
+        ttlMs: CAMERA_FOV_OVERRIDE_TTL_MS,
+      })
+      this.scheduleRefresh()
+    })
+  }
+
   releaseForApp(packageName: string): Promise<void> {
     return this.enqueue(async () => {
       const removed = this.overrides.get(packageName)

package/src/services/PhoneStreamCoordinator.ts

@@ -26,6 +26,18 @@
  * streams. We use a `phone-` prefix so they're trivially distinguishable from
  * cloud-minted IDs in logs and from cloud-SDK app streams that flow through
  * the legacy path.
+ *
+ * BLE link loss is a SUSPENDED state, not a failure:
+ *   The glasses publisher keeps pushing over Wi-Fi when the phone's Bluetooth
+ *   link drops; only our keep-alives stop reaching it. While the store says
+ *   the glasses are disconnected we pause the heartbeat (so we don't count
+ *   misses we caused ourselves), fan out `suspended`, and give the link
+ *   `glassesGraceMs` to come back. On reconnect we resume, heartbeat at once,
+ *   and fan out `resumed` with the SAME streamId — no re-provision. The grace
+ *   ends early when Cloudflare reports the publisher gone for two probes in
+ *   a row (glasses powered off, not a BLE hiccup). If the grace expires the
+ *   stream is torn down with reason `glasses_disconnected`, and the BLE stop
+ *   the glasses never received is sent on the next reconnect.
  */
 
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
@@ -65,11 +77,40 @@ const DEFAULT_TIMINGS = {
   hlsReadinessInitialDelayMs: 5_000,
   hlsReadinessPollMs: 2_000,
   hlsReadinessMaxAttempts: 30,
+  // How long a stream survives a BLE link drop before we give up on it. Must
+  // stay under the glasses publisher's own 60s no-keep-alive watchdog with
+  // margin for the resume heartbeat's round trip.
+  glassesGraceMs: 45_000,
+  // Consecutive Cloudflare "publisher disconnected" probes while suspended
+  // before we conclude the glasses are off (not just out of BLE range).
+  suspendedPublisherGoneProbes: 2,
 } as const
 
 type TimingConfig = {[K in keyof typeof DEFAULT_TIMINGS]: number}
 export type CoordinatorTimings = Partial<TimingConfig>
 
+/**
+ * Where the coordinator learns whether the phone↔glasses BLE link is up.
+ * Injected so tests can drive link transitions without the zustand store.
+ */
+export interface GlassesLinkSource {
+  isConnected(): boolean
+  /** Fires on every connected↔disconnected transition. */
+  subscribe(listener: (connected: boolean) => void): () => void
+}
+
+const storeLinkSource: GlassesLinkSource = {
+  isConnected: () => isGlassesConnected(useGlassesStore.getState().connection),
+  subscribe: (listener) => useGlassesStore.subscribe((s) => isGlassesConnected(s.connection), listener),
+}
+
+/** Reasons carried on coordinator-sourced `stream_status` fanouts for link events. */
+export const LINK_STATUS = {
+  suspended: "suspended",
+  resumed: "resumed",
+  reason: "glasses_disconnected",
+} as const
+
 // Console-backed minimal logger; replaces pino on the phone.
 const consoleLogger: LifecycleLogger = {
   child: (bindings) => ({
@@ -90,6 +131,7 @@ export interface StartUnmanagedOptions {
   sound?: boolean
   /** Optional Bearer token for WHIP Authorization (custom authenticated endpoints). */
   authToken?: string
+  captureAudio?: boolean
 }
 
 export interface StartManagedOptions {
@@ -108,6 +150,8 @@ export interface StartManagedOptions {
    *     that drop WHIP/SRT UDP.
    */
   ingest?: "srt" | "whip" | "rtmp"
+  /** When false, glasses skip encoding their mic for this WHIP session. */
+  captureAudio?: boolean
 }
 
 export interface StreamPublisherStartResult {
@@ -184,20 +228,11 @@ export class StreamConflictError extends Error {
   }
 }
 
-/**
- * Fail fast if glasses aren't connected — BEFORE provisioning. Without this a
- * managed start would create a provider live input, fail the BLE command, and
- * tear the input down again: a slow, billable no-op with a confusing error.
- */
-function assertGlassesConnected(): void {
-  if (!isGlassesConnected(useGlassesStore.getState().connection)) {
-    throw new StreamConflictError(
-      "GLASSES_NOT_CONNECTED",
-      "Glasses are not connected",
-      "command",
-      "ble",
-    )
-  }
+interface SuspendedState {
+  since: number
+  graceTimer: ReturnType<typeof setTimeout>
+  /** Consecutive Cloudflare probes that saw no publisher during this suspension. */
+  publisherGoneProbes: number
 }
 
 export class PhoneStreamCoordinator {
@@ -206,6 +241,16 @@ export class PhoneStreamCoordinator {
   private statusSubscriber: StatusSubscriber | null = null
   private idCounter = 0
   private readonly timings: TimingConfig
+  private readonly linkSource: GlassesLinkSource
+  private unsubscribeLink: (() => void) | null = null
+  private suspended: SuspendedState | null = null
+  /**
+   * A stream was torn down while the BLE link was down, so the glasses never
+   * got `stopStream`. Sent on the next reconnect (if no new stream has claimed
+   * the slot) so a publisher that outlived its input does not keep pushing
+   * until its own watchdog fires.
+   */
+  private pendingBleStop: {streamId: string} | null = null
   /**
    * Serializes state transitions (start, stop, teardown). Without it, a
    * second `start*` racing with the first can pass the `this.current === null`
@@ -220,8 +265,30 @@ export class PhoneStreamCoordinator {
   /** Send full resolvedConfig only once per stream session. */
   private resolvedConfigForwarded = false
 
-  constructor(timings: CoordinatorTimings = {}) {
+  constructor(timings: CoordinatorTimings = {}, deps: {linkSource?: GlassesLinkSource} = {}) {
     this.timings = {...DEFAULT_TIMINGS, ...timings}
+    this.linkSource = deps.linkSource ?? storeLinkSource
+  }
+
+  /**
+   * Fail fast if glasses aren't connected — BEFORE provisioning. Without this a
+   * managed start would create a provider live input, fail the BLE command, and
+   * tear the input down again: a slow, billable no-op with a confusing error.
+   */
+  private assertGlassesConnected(): void {
+    if (!this.linkSource.isConnected()) {
+      throw new StreamConflictError(
+        "GLASSES_NOT_CONNECTED",
+        "Glasses are not connected",
+        "command",
+        "ble",
+      )
+    }
+  }
+
+  /** True while the active stream is parked on a dropped BLE link. */
+  isSuspended(): boolean {
+    return this.suspended !== null
   }
 
   /**
@@ -261,7 +328,11 @@ export class PhoneStreamCoordinator {
 
   /** Report-safe stream ownership snapshot for incident diagnostics. */
   getDiagnosticSnapshot(): Record<string, unknown> {
-    if (!this.current) return {active: false}
+    if (!this.current) return {active: false, pendingBleStop: this.pendingBleStop?.streamId ?? null}
+    const link = {
+      suspended: this.suspended !== null,
+      ...(this.suspended ? {suspendedForMs: Date.now() - this.suspended.since} : {}),
+    }
     return this.current.kind === "managed"
       ? {
           active: true,
@@ -270,12 +341,14 @@ export class PhoneStreamCoordinator {
           subscribers: [...this.current.subscribers].sort(),
           mode: this.current.mode,
           playbackReady: this.current.hlsReady,
+          ...link,
         }
       : {
           active: true,
           kind: this.current.kind,
           streamId: this.current.streamId,
           ownerPackageName: this.current.packageName,
+          ...link,
         }
   }
 
@@ -288,7 +361,7 @@ export class PhoneStreamCoordinator {
     if (!opts.streamUrl || typeof opts.streamUrl !== "string") {
       throw new StreamConflictError("STREAM_URL_REQUIRED", "streamUrl is required")
     }
-    assertGlassesConnected()
+    this.assertGlassesConnected()
     return this.runExclusive(async () => {
       if (this.current) {
         throw new StreamConflictError(
@@ -319,6 +392,7 @@ export class PhoneStreamCoordinator {
           ...(opts.video !== undefined ? {video: opts.video} : {}),
           ...(opts.audio !== undefined ? {audio: opts.audio} : {}),
           ...(opts.authToken ? {authToken: opts.authToken} : {}),
+          ...(typeof opts.captureAudio === "boolean" ? {captureAudio: opts.captureAudio} : {}),
         })
         const result = publisherStartResult(streamId, event)
         this.startLifecycle(streamId)
@@ -346,7 +420,7 @@ export class PhoneStreamCoordinator {
     // Two-phase: the entry-claim runs under the transition lock; the wait for
     // HLS readiness happens AFTER the lock releases so a long warm-up doesn't
     // block subsequent start/stop transitions on this coordinator.
-    assertGlassesConnected()
+    this.assertGlassesConnected()
     type JoinDecision =
       | {kind: "join"; entry: ManagedEntry; immediate: ManagedStartResult | null}
       | {kind: "fresh"; entry: ManagedEntry}
@@ -422,6 +496,7 @@ export class PhoneStreamCoordinator {
           // See startUnmanaged: the native bridge rejects explicit `undefined`.
           ...(opts.video !== undefined ? {video: opts.video} : {}),
           ...(opts.audio !== undefined ? {audio: opts.audio} : {}),
+          ...(typeof opts.captureAudio === "boolean" ? {captureAudio: opts.captureAudio} : {}),
         })
         entry.publisherStart = publisherStartResult(streamId, event)
         console.info("[STREAM_STARTUP]", {
@@ -543,6 +618,109 @@ export class PhoneStreamCoordinator {
     this.lifecycle?.handleAck(event.ackId)
   }
 
+  // ===========================================================================
+  // BLE link suspension
+  // ===========================================================================
+
+  private attachLink(): void {
+    if (this.unsubscribeLink) return
+    this.unsubscribeLink = this.linkSource.subscribe((connected) => this.handleLinkChange(connected))
+  }
+
+  private detachLinkIfIdle(): void {
+    if (this.current || this.pendingBleStop || !this.unsubscribeLink) return
+    this.unsubscribeLink()
+    this.unsubscribeLink = null
+  }
+
+  private handleLinkChange(connected: boolean): void {
+    if (connected) {
+      if (this.current && this.suspended) {
+        this.resumeLocked()
+      } else if (!this.current && this.pendingBleStop) {
+        this.flushPendingBleStop()
+      }
+      return
+    }
+    if (this.current && !this.suspended) this.suspend()
+  }
+
+  private suspend(): void {
+    const entry = this.current
+    if (!entry) return
+    const since = Date.now()
+    // Pause the heartbeat: misses now would be our own fault, not the
+    // publisher's, and counting them would reap a stream that is still live.
+    this.lifecycle?.setActive(false)
+    const graceTimer = setTimeout(() => this.onGraceExpired(entry.streamId), this.timings.glassesGraceMs)
+    this.suspended = {since, graceTimer, publisherGoneProbes: 0}
+    console.warn("[STREAM] BLE link lost; stream suspended", {
+      streamId: entry.streamId,
+      graceMs: this.timings.glassesGraceMs,
+    })
+    this.fanout({
+      streamId: entry.streamId,
+      source: "coordinator",
+      status: LINK_STATUS.suspended,
+      data: {reason: LINK_STATUS.reason, graceMs: this.timings.glassesGraceMs, since},
+    })
+  }
+
+  private resumeLocked(): void {
+    const entry = this.current
+    const suspended = this.suspended
+    if (!entry || !suspended) return
+    clearTimeout(suspended.graceTimer)
+    this.suspended = null
+    const suspendedMs = Date.now() - suspended.since
+    console.info("[STREAM] BLE link back; stream resumed", {streamId: entry.streamId, suspendedMs})
+    // Resume and heartbeat immediately: the glasses watchdog has been running
+    // the whole time, so the first keep-alive must not wait another interval.
+    this.lifecycle?.setActive(true)
+    this.lifecycle?.tickNow()
+    // A resumed session is a fresh status baseline for subscribers.
+    this.lastFanoutSignature = null
+    this.fanout({
+      streamId: entry.streamId,
+      source: "coordinator",
+      status: LINK_STATUS.resumed,
+      data: {reason: LINK_STATUS.reason, suspendedMs},
+    })
+  }
+
+  private onGraceExpired(streamId: string): void {
+    if (this.current?.streamId !== streamId || !this.suspended) return
+    this.failSuspended(streamId, "glasses_disconnected", {publisherGone: false})
+  }
+
+  /**
+   * End a suspended stream. `publisherGone` distinguishes "glasses are off and
+   * Cloudflare confirms nothing is publishing" from "grace ran out with the
+   * publisher possibly still alive" — miniapps word the two differently.
+   */
+  private failSuspended(streamId: string, reason: string, detail: {publisherGone: boolean}): void {
+    this.fanout({
+      streamId,
+      source: "coordinator",
+      status: "error",
+      data: {reason: LINK_STATUS.reason, teardownReason: reason, ...detail},
+    })
+    void this.runExclusive(async () => {
+      if (this.current?.streamId !== streamId) return
+      await this.teardownLocked(reason)
+    })
+  }
+
+  private flushPendingBleStop(): void {
+    const pending = this.pendingBleStop
+    if (!pending) return
+    this.pendingBleStop = null
+    console.info("[STREAM] BLE link back; sending deferred stopStream", pending)
+    void BluetoothSdk.stopStream()
+      .catch((err) => console.warn("[STREAM] deferred stopStream failed:", err))
+      .finally(() => this.detachLinkIfIdle())
+  }
+
   // ===========================================================================
   // Internal
   // ===========================================================================
@@ -552,7 +730,11 @@ export class PhoneStreamCoordinator {
     return `phone-${prefix}-${Date.now().toString(36)}-${this.idCounter}`
   }
 
+  /** BLE keep-alives. StreamLifecycleController uses BgTimer so they survive MentraOS backgrounding. */
   private startLifecycle(streamId: string): void {
+    // A new stream supersedes any deferred stop for the previous one.
+    this.pendingBleStop = null
+    this.attachLink()
     this.lifecycle?.dispose()
     const ctrl = new StreamLifecycleController(
       {
@@ -631,6 +813,20 @@ export class PhoneStreamCoordinator {
           status: status.isConnected ? "connected" : "disconnected",
           data: status as unknown as Record<string, unknown>,
         })
+        // While the BLE link is down, Cloudflare is the only witness to the
+        // publisher. Two consecutive "nobody is publishing" probes mean the
+        // glasses are off, not merely out of Bluetooth range — stop waiting.
+        if (this.suspended) {
+          if (status.isConnected) {
+            this.suspended.publisherGoneProbes = 0
+          } else {
+            this.suspended.publisherGoneProbes += 1
+            if (this.suspended.publisherGoneProbes >= this.timings.suspendedPublisherGoneProbes) {
+              this.failSuspended(entry.streamId, "glasses_disconnected_publisher_gone", {publisherGone: true})
+              keepPolling = false
+            }
+          }
+        }
         // webrtc mode readiness: first "connected" means WHEP playback is
         // available (WebRTC playback follows the ingest directly; there is no
         // manifest to probe).
@@ -799,12 +995,28 @@ export class PhoneStreamCoordinator {
     this.lastFanoutSignature = null
     this.resolvedConfigForwarded = false
 
+    if (this.suspended) {
+      clearTimeout(this.suspended.graceTimer)
+      this.suspended = null
+    }
+
     // Dispose the lifecycle controller immediately so it doesn't fire one
     // more keep-alive against a stream we're tearing down. The transition
     // lock guarantees no new lifecycle is started concurrently.
     this.lifecycle?.dispose()
     this.lifecycle = null
 
+    // With the link down a BLE write can only fail (and hold the transition
+    // lock for the native timeout). Defer it to the next reconnect instead.
+    const linkUp = this.linkSource.isConnected()
+    if (sendBleStop && !linkUp) {
+      this.pendingBleStop = {streamId: entry.streamId}
+      console.warn("[STREAM] BLE link down during teardown; stopStream deferred", {
+        streamId: entry.streamId,
+        reason,
+      })
+    }
+
     if (entry.kind === "managed") {
       if (entry.cloudflareTimer) clearTimeout(entry.cloudflareTimer)
       if (entry.hlsTimer) clearInterval(entry.hlsTimer)
@@ -816,7 +1028,7 @@ export class PhoneStreamCoordinator {
     }
 
     try {
-      if (sendBleStop) {
+      if (sendBleStop && linkUp) {
         await BluetoothSdk.stopStream()
       }
     } catch (err) {
@@ -827,6 +1039,7 @@ export class PhoneStreamCoordinator {
       // Only clear if we're still the active entry (defensive — runExclusive
       // serializes us, so this should always be true).
       if (this.current === entry) this.current = null
+      this.detachLinkIfIdle()
 
       if (entry.kind === "managed") {
         // Start remote cleanup only after the publisher has stopped, but do not