@mentra/engine 0.1.0-beta.0

package/src/services/PhoneStreamCoordinator.ts

@@ -0,0 +1,777 @@
+/**
+ * PhoneStreamCoordinator — owns all local-miniapp streaming on the phone.
+ *
+ * Architecture:
+ *   miniapp → SDK → LocalMiniappRuntime → coordinator
+ *           coordinator → BluetoothSdk (BLE → glasses publisher)
+ *           coordinator ↔ cloudStreamApi (managed only, cloud-v2 runtime provisioning)
+ *           coordinator ↔ StreamLifecycleController (keep-alive heartbeat)
+ *           coordinator → status listeners → routed back to miniapp(s)
+ *
+ * Single-stream constraint:
+ *   At most ONE stream is active across all miniapps. The exception is that
+ *   multiple miniapps can subscribe to a single managed stream that's already
+ *   running — Cloudflare muxes one ingest into many viewers, so subscribers
+ *   share the same playback URLs. Refcounted; teardown happens when the last
+ *   subscriber releases.
+ *
+ * Status routing:
+ *   Glasses publisher status arrives over BLE as `stream_status` events with
+ *   a `streamId`. The coordinator's `owns(streamId)` lookup lets MantleManager
+ *   route phone-owned status events here (not to cloud). For managed streams,
+ *   we additionally poll Cloudflare's live-input status every 5s to surface
+ *   what the OTHER end of the pipe sees.
+ *
+ * Important: this is the ONLY place that mints `streamId`s for phone-owned
+ * 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.
+ */
+
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import type {
+  KeepAliveAckEvent,
+  StreamResolvedConfig,
+  StreamStartRequest,
+  StreamStatusEvent,
+} from "@mentra/bluetooth-sdk/internal"
+import {isGlassesConnected} from "./GlassesReadiness"
+import {useGlassesStore} from "../stores/glasses"
+
+import {StreamLifecycleController, type LifecycleLogger} from "./StreamLifecycleController"
+import {slimStreamStatusEvent, streamStatusSignature} from "./slimStreamStatus"
+import {
+  getManagedStreamStatus,
+  provisionManagedStream,
+  teardownManagedStream,
+  type CloudflareStatus,
+  type ProvisionResult,
+  type RestreamDestinationInput,
+} from "./cloudStreamApi"
+
+/**
+ * Default cadence + thresholds. Exposed via {@link CoordinatorTimings} so tests
+ * can shorten them; production code should never override these.
+ */
+const DEFAULT_TIMINGS = {
+  keepAliveIntervalMs: 15_000,
+  ackTimeoutMs: 10_000,
+  maxMissedAcks: 3,
+  cloudflareStatusPollMs: 5_000,
+  // Cloudflare typically needs ~5-10s after first frame before HLS is live.
+  hlsReadinessInitialDelayMs: 5_000,
+  hlsReadinessPollMs: 2_000,
+  hlsReadinessMaxAttempts: 30,
+} as const
+
+type TimingConfig = {[K in keyof typeof DEFAULT_TIMINGS]: number}
+export type CoordinatorTimings = Partial<TimingConfig>
+
+// Console-backed minimal logger; replaces pino on the phone.
+const consoleLogger: LifecycleLogger = {
+  child: (bindings) => ({
+    ...consoleLogger,
+    debug: (...args) => console.debug("[STREAM]", bindings, ...args),
+    warn: (...args) => console.warn("[STREAM]", bindings, ...args),
+    error: (...args) => console.error("[STREAM]", bindings, ...args),
+  }),
+  debug: (...args) => console.debug("[STREAM]", ...args),
+  warn: (...args) => console.warn("[STREAM]", ...args),
+  error: (...args) => console.error("[STREAM]", ...args),
+}
+
+export interface StartUnmanagedOptions {
+  streamUrl: string
+  video?: StreamStartRequest["video"]
+  audio?: StreamStartRequest["audio"]
+  sound?: boolean
+}
+
+export interface StartManagedOptions {
+  restreamDestinations?: RestreamDestinationInput[]
+  video?: StreamStartRequest["video"]
+  audio?: StreamStartRequest["audio"]
+  sound?: boolean
+  /**
+   * Ingest protocol preference — a real latency/durability trade on Cloudflare:
+   *   - "srt" (default): SRT ingest -> LL-HLS playback (~10-20s glass-to-screen),
+   *     with shareable HLS/DASH URLs and automatic recording.
+   *   - "whip": WebRTC ingest -> WHEP playback (<1s glass-to-screen), but NO
+   *     HLS/DASH playback and NO recording (Cloudflare limitation; the returned
+   *     hlsUrl will serve 204 forever).
+   */
+  ingest?: "srt" | "whip"
+}
+
+export interface StreamPublisherStartResult {
+  streamId: string
+  status: string
+  resolvedConfig?: StreamResolvedConfig
+}
+
+export interface ManagedStartResult extends StreamPublisherStartResult {
+  liveInputId: string
+  /** Playback mode this stream supports: "hls" (SRT/RTMP ingest — use hlsUrl/
+   *  dashUrl, recording on) or "webrtc" (WHIP ingest — use webrtcUrl/WHEP,
+   *  sub-second, no HLS, no recording). */
+  mode: "hls" | "webrtc"
+  hlsUrl: string
+  dashUrl: string
+  webrtcUrl?: string
+}
+
+export type StreamStatusUpdate = {
+  streamId: string
+  source: "glasses" | "cloudflare" | "coordinator"
+  status: string
+  data?: Record<string, unknown>
+}
+
+export type StatusSubscriber = (packageName: string, update: StreamStatusUpdate) => void
+
+interface UnmanagedEntry {
+  kind: "unmanaged"
+  streamId: string
+  packageName: string
+  streamUrl: string
+}
+
+interface ManagedEntry {
+  kind: "managed"
+  streamId: string
+  liveInputId: string
+  ingestUrl: string
+  /** Playback mode the chosen ingest supports: SRT/RTMP feed HLS; WHIP feeds
+   *  only WHEP. Readiness is gated differently per mode. */
+  mode: "hls" | "webrtc"
+  hlsUrl: string
+  dashUrl: string
+  webrtcUrl?: string
+  publisherStart?: StreamPublisherStartResult
+  subscribers: Set<string>
+  hlsReady: boolean
+  hlsReadyResolvers: Array<(result: ManagedStartResult) => void>
+  hlsReadyRejecters: Array<(err: Error) => void>
+  cloudflareTimer?: ReturnType<typeof setInterval>
+  hlsTimer?: ReturnType<typeof setInterval>
+  hlsAttempts: number
+  /** webrtc mode: CF status polls seen while waiting for first "connected". */
+  connectAttempts: number
+}
+
+type Entry = UnmanagedEntry | ManagedEntry
+
+export class StreamConflictError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    /** Pipeline stage that failed (provision | command | publish | playback). */
+    public readonly stage?: string,
+    /** Transport in play at the failure (cloud-rest | ble | wifi). */
+    public readonly transport?: string,
+  ) {
+    super(message)
+    this.name = "StreamConflictError"
+  }
+}
+
+/**
+ * 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",
+    )
+  }
+}
+
+export class PhoneStreamCoordinator {
+  private current: Entry | null = null
+  private lifecycle: StreamLifecycleController | null = null
+  private statusSubscriber: StatusSubscriber | null = null
+  private idCounter = 0
+  private readonly timings: TimingConfig
+  /**
+   * Serializes state transitions (start, stop, teardown). Without it, a
+   * second `start*` racing with the first can pass the `this.current === null`
+   * pre-check while the first is still awaiting its provision/BLE work, and
+   * end up provisioning two separate streams. A teardown racing with a start
+   * can clear `current` mid-stop and let the start fire BLE writes that
+   * collide with the in-flight stopStream.
+   */
+  private inFlight: Promise<void> = Promise.resolve()
+  /** Drop identical stream_status fanouts within one session. */
+  private lastFanoutSignature: string | null = null
+  /** Send full resolvedConfig only once per stream session. */
+  private resolvedConfigForwarded = false
+
+  constructor(timings: CoordinatorTimings = {}) {
+    this.timings = {...DEFAULT_TIMINGS, ...timings}
+  }
+
+  /**
+   * Run `work` under the transition lock. Each call awaits the previous
+   * transition before re-evaluating preconditions, so e.g. two concurrent
+   * `startManaged` calls are observed sequentially.
+   */
+  private async runExclusive<T>(work: () => Promise<T>): Promise<T> {
+    const prev = this.inFlight
+    let release!: () => void
+    this.inFlight = new Promise<void>((r) => (release = r))
+    try {
+      await prev
+      return await work()
+    } finally {
+      release()
+    }
+  }
+
+  /**
+   * Register the function that routes status updates to miniapps.
+   * LocalMiniappRuntime wires this so updates become EVENT envelopes on the
+   * `stream_status` stream for every subscribing miniapp.
+   */
+  setStatusSubscriber(cb: StatusSubscriber): void {
+    this.statusSubscriber = cb
+  }
+
+  /**
+   * True when a phone-owned stream currently uses this streamId. For managed
+   * streams, all subscribers share the same streamId so a single equality
+   * check covers the multi-subscriber case.
+   */
+  owns(streamId: string): boolean {
+    return this.current !== null && this.current.streamId === streamId
+  }
+
+  async startUnmanaged(
+    packageName: string,
+    opts: StartUnmanagedOptions,
+  ): Promise<StreamPublisherStartResult> {
+    // Pre-check the obvious-bad input before queueing — the lock is for
+    // serializing state transitions, not for validating arguments.
+    if (!opts.streamUrl || typeof opts.streamUrl !== "string") {
+      throw new StreamConflictError("STREAM_URL_REQUIRED", "streamUrl is required")
+    }
+    assertGlassesConnected()
+    return this.runExclusive(async () => {
+      if (this.current) {
+        throw new StreamConflictError(
+          "STREAM_ALREADY_ACTIVE",
+          `A ${this.current.kind} stream is already active. Stop it before starting a new one.`,
+        )
+      }
+
+      const streamId = this.mintId("u")
+      const entry: UnmanagedEntry = {
+        kind: "unmanaged",
+        streamId,
+        packageName,
+        streamUrl: opts.streamUrl,
+      }
+      // Claim the slot BEFORE the BLE call so a concurrent caller waiting on
+      // the lock sees the in-progress entry and rejects with the conflict.
+      this.current = entry
+
+      try {
+        const event = await BluetoothSdk.startExternallyManagedStream({
+          type: "start_stream",
+          streamUrl: opts.streamUrl,
+          streamId,
+          sound: opts.sound ?? true,
+          // The native bridge rejects explicit `undefined` values ("Value is
+          // undefined, expected an Object") — only include what was provided.
+          ...(opts.video !== undefined ? {video: opts.video} : {}),
+          ...(opts.audio !== undefined ? {audio: opts.audio} : {}),
+        })
+        const result = publisherStartResult(streamId, event)
+        this.startLifecycle(streamId)
+        return result
+      } catch (err) {
+        this.current = null
+        throw err
+      }
+    })
+  }
+
+  async startManaged(
+    packageName: string,
+    opts: StartManagedOptions,
+  ): Promise<ManagedStartResult> {
+    // 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()
+    type JoinDecision =
+      | {kind: "join"; entry: ManagedEntry; immediate: ManagedStartResult | null}
+      | {kind: "fresh"; entry: ManagedEntry}
+
+    const decision = await this.runExclusive(async (): Promise<JoinDecision> => {
+      if (this.current && this.current.kind === "unmanaged") {
+        throw new StreamConflictError(
+          "STREAM_ALREADY_ACTIVE",
+          "An unmanaged stream is already active. Stop it before starting a managed stream.",
+        )
+      }
+
+      // Join an existing managed stream if one is already running.
+      if (this.current && this.current.kind === "managed") {
+        const existing = this.current
+        // Restream destinations are immutable after provision — a second
+        // caller trying to dictate destinations on an already-live stream
+        // is a likely bug or a feature we don't yet support.
+        if (opts.restreamDestinations && opts.restreamDestinations.length > 0) {
+          throw new StreamConflictError(
+            "STREAM_DESTINATIONS_LOCKED",
+            "Restream destinations cannot be modified on an already-running managed stream.",
+          )
+        }
+        existing.subscribers.add(packageName)
+        const immediate: ManagedStartResult | null = existing.hlsReady
+          ? managedStartResult(existing)
+          : null
+        return {kind: "join", entry: existing, immediate}
+      }
+
+      // Fresh provision — claim slot BEFORE awaiting Cloudflare so a
+      // concurrent caller queued behind us sees a managed stream in flight
+      // and joins instead of double-provisioning.
+      const provision = await provisionManagedStream(opts.restreamDestinations)
+      const streamId = this.mintId("m")
+      const ingestUrl = pickIngestUrl(provision, opts.ingest)
+      const mode: ManagedEntry["mode"] =
+        ingestUrl === provision.webrtcPublishUrl ? "webrtc" : "hls"
+
+      const entry: ManagedEntry = {
+        kind: "managed",
+        streamId,
+        liveInputId: provision.liveInputId,
+        ingestUrl,
+        mode,
+        hlsUrl: provision.hlsUrl,
+        dashUrl: provision.dashUrl,
+        webrtcUrl: provision.webrtcUrl,
+        subscribers: new Set([packageName]),
+        hlsReady: false,
+        hlsReadyResolvers: [],
+        hlsReadyRejecters: [],
+        hlsAttempts: 0,
+        connectAttempts: 0,
+      }
+      this.current = entry
+
+      try {
+        const event = await BluetoothSdk.startExternallyManagedStream({
+          type: "start_stream",
+          streamUrl: ingestUrl,
+          streamId,
+          sound: opts.sound ?? true,
+          // See startUnmanaged: the native bridge rejects explicit `undefined`.
+          ...(opts.video !== undefined ? {video: opts.video} : {}),
+          ...(opts.audio !== undefined ? {audio: opts.audio} : {}),
+        })
+        entry.publisherStart = publisherStartResult(streamId, event)
+      } catch (err) {
+        this.current = null
+        await teardownManagedStream(provision.liveInputId).catch(() => undefined)
+        throw err
+      }
+
+      this.startLifecycle(streamId)
+      this.startCloudflareStatusPoll(entry)
+      // hls mode: readiness = a real HLS manifest exists. webrtc mode: HLS
+      // never materializes (Cloudflare WHIP limitation) — readiness resolves
+      // off the status poll's first "connected" instead.
+      if (entry.mode === "hls") {
+        this.startHlsReadinessPoll(entry)
+      }
+      return {kind: "fresh", entry}
+    })
+
+    if (decision.kind === "join" && decision.immediate) {
+      return decision.immediate
+    }
+
+    // Wait for playback readiness OUTSIDE the lock — readiness can take ~10s
+    // and we don't want to block other transitions for that long.
+    return new Promise<ManagedStartResult>((resolve, reject) => {
+      decision.entry.hlsReadyResolvers.push(resolve)
+      decision.entry.hlsReadyRejecters.push(reject)
+    })
+  }
+
+  async stop(packageName: string, streamId?: string): Promise<void> {
+    await this.runExclusive(async () => {
+      if (!this.current) return
+
+      // If a streamId was passed but doesn't match, ignore — silent no-op
+      // matches the cloud's tolerant behavior.
+      if (streamId && this.current.streamId !== streamId) return
+
+      if (this.current.kind === "managed") {
+        const entry = this.current
+        entry.subscribers.delete(packageName)
+        if (entry.subscribers.size > 0) {
+          // Other miniapps still subscribed; keep the stream alive.
+          return
+        }
+      } else if (this.current.packageName !== packageName) {
+        // Unmanaged stream: only the owner can stop it.
+        return
+      }
+
+      await this.teardownLocked("explicit_stop")
+    })
+  }
+
+  /**
+   * Called by MantleManager when a `stream_status` event arrives from glasses
+   * and the registry says it's phone-owned.
+   */
+  handleGlassesStatus(event: StreamStatusEvent): void {
+    if (!this.current) return
+    if (event.streamId && event.streamId !== this.current.streamId) return
+
+    this.lifecycle?.recordActivity()
+    const includeResolvedConfig = !this.resolvedConfigForwarded && !!event.resolvedConfig
+    if (includeResolvedConfig) this.resolvedConfigForwarded = true
+    const slimData = slimStreamStatusEvent(event, {includeResolvedConfig})
+    const signature = streamStatusSignature(slimData)
+    if (signature === this.lastFanoutSignature) return
+    this.lastFanoutSignature = signature
+
+    this.fanout({
+      streamId: this.current.streamId,
+      source: "glasses",
+      status: event.status,
+      data: slimData,
+    })
+
+    // Glasses-reported TERMINAL states unwind the coordinator. Terminal means
+    // the publisher gave up or stopped — NOT a transient `kind:"error"`: the
+    // glasses publisher auto-recovers (error → reconnecting → reconnected),
+    // and tearing down on the first hiccup deletes the live input out from
+    // under a publisher that comes right back (it then retries into a dead
+    // input forever). A publisher that errors and never recovers is reaped by
+    // the keep-alive ack timeout. Queue the teardown through the transition
+    // lock so it serializes with any start/stop currently in flight.
+    const isStopped =
+      (event.kind === "lifecycle" && event.status === "stopped") ||
+      (event.kind === "snapshot" && event.status === "stopped")
+    const isGiveUp = event.kind === "reconnect" && event.status === "reconnect_failed"
+    if (isGiveUp || isStopped) {
+      const reason = isGiveUp ? "glasses_gave_up" : "glasses_stopped"
+      const targetStreamId = this.current.streamId
+      void this.runExclusive(async () => {
+        // The stream we wanted to tear down may already be gone (e.g. another
+        // teardown won the lock and unwound it). Guard before acting.
+        if (this.current?.streamId !== targetStreamId) return
+        await this.teardownLocked(reason, {sendBleStop: false})
+      })
+    }
+  }
+
+  /** Called by MantleManager when a phone-owned keep_alive_ack arrives. */
+  handleKeepAliveAck(event: KeepAliveAckEvent): void {
+    if (!event.ackId) return
+    this.lifecycle?.handleAck(event.ackId)
+  }
+
+  // ===========================================================================
+  // Internal
+  // ===========================================================================
+
+  private mintId(prefix: "u" | "m"): string {
+    this.idCounter += 1
+    return `phone-${prefix}-${Date.now().toString(36)}-${this.idCounter}`
+  }
+
+  private startLifecycle(streamId: string): void {
+    this.lifecycle?.dispose()
+    const ctrl = new StreamLifecycleController(
+      {
+        logger: consoleLogger,
+        streamId,
+        keepAliveIntervalMs: this.timings.keepAliveIntervalMs,
+        ackTimeoutMs: this.timings.ackTimeoutMs,
+        maxMissedAcks: this.timings.maxMissedAcks,
+      },
+      {
+        sendKeepAlive: async (ackId) => {
+          await BluetoothSdk.sendExternallyManagedStreamKeepAlive({
+            type: "keep_stream_alive",
+            streamId,
+            ackId,
+          })
+        },
+        onTimeout: async () => {
+          this.fanout({
+            streamId,
+            source: "coordinator",
+            status: "error",
+            data: {reason: "keep_alive_timeout"},
+          })
+          await this.runExclusive(async () => {
+            // The stream this timeout was bound to may already be gone.
+            if (this.current?.streamId !== streamId) return
+            await this.teardownLocked("keep_alive_timeout")
+          })
+        },
+      },
+    )
+    ctrl.setActive(true)
+    this.lifecycle = ctrl
+  }
+
+  private startCloudflareStatusPoll(entry: ManagedEntry): void {
+    // webrtc mode: how many polls to wait for the first "connected" before
+    // declaring the publisher never reached Cloudflare. Mirrors the HLS
+    // readiness budget (~60s at the default 5s cadence).
+    const maxConnectAttempts = Math.max(
+      1,
+      Math.ceil(
+        (this.timings.hlsReadinessMaxAttempts * this.timings.hlsReadinessPollMs) /
+          this.timings.cloudflareStatusPollMs,
+      ),
+    )
+    const poll = async () => {
+      if (this.current !== entry) return
+      try {
+        const status: CloudflareStatus = await getManagedStreamStatus(entry.liveInputId)
+        this.fanout({
+          streamId: entry.streamId,
+          source: "cloudflare",
+          status: status.isConnected ? "connected" : "disconnected",
+          data: status as unknown as Record<string, unknown>,
+        })
+        // webrtc mode readiness: first "connected" means WHEP playback is
+        // available (WebRTC playback follows the ingest directly; there is no
+        // manifest to probe).
+        if (entry.mode === "webrtc" && !entry.hlsReady) {
+          if (status.isConnected) {
+            entry.hlsReady = true
+            const result = managedStartResult(entry)
+            for (const r of entry.hlsReadyResolvers) r(result)
+            entry.hlsReadyResolvers = []
+            entry.hlsReadyRejecters = []
+            this.fanout({
+              streamId: entry.streamId,
+              source: "coordinator",
+              status: "webrtc_ready",
+              data: result as unknown as Record<string, unknown>,
+            })
+          } else {
+            entry.connectAttempts += 1
+            if (entry.connectAttempts >= maxConnectAttempts) {
+              const err = new Error(
+                `WebRTC ingest never reached Cloudflare after ${entry.connectAttempts} status polls`,
+              )
+              for (const reject of entry.hlsReadyRejecters) reject(err)
+              entry.hlsReadyResolvers = []
+              entry.hlsReadyRejecters = []
+              this.fanout({
+                streamId: entry.streamId,
+                source: "coordinator",
+                status: "error",
+                data: {reason: "webrtc_not_connected"},
+              })
+              const targetStreamId = entry.streamId
+              void this.runExclusive(async () => {
+                if (this.current?.streamId !== targetStreamId) return
+                await this.teardownLocked("webrtc_not_connected")
+              })
+            }
+          }
+        }
+      } catch (err) {
+        console.warn("[STREAM] cloudflare status poll failed:", err)
+      }
+    }
+    entry.cloudflareTimer = setInterval(poll, this.timings.cloudflareStatusPollMs)
+    // Don't fire immediately — Cloudflare wouldn't have first-frame yet.
+  }
+
+  private startHlsReadinessPoll(entry: ManagedEntry): void {
+    // Skip the first few seconds — Cloudflare doesn't have first-frame yet,
+    // and the HEAD requests would all 404 and burn battery.
+    const tick = async () => {
+      if (this.current !== entry) return
+      entry.hlsAttempts += 1
+      try {
+        // Require a real manifest (200 with a body), not just res.ok — the
+        // playback edge returns 204 No Content while the input has no
+        // HLS-capable frames (e.g. WebRTC ingest), and 204 is "ok".
+        const res = await fetch(entry.hlsUrl, {method: "HEAD"})
+        if (res.status === 200) {
+          entry.hlsReady = true
+          if (entry.hlsTimer) {
+            clearInterval(entry.hlsTimer)
+            entry.hlsTimer = undefined
+          }
+          const result = managedStartResult(entry)
+          for (const r of entry.hlsReadyResolvers) r(result)
+          entry.hlsReadyResolvers = []
+          entry.hlsReadyRejecters = []
+          this.fanout({
+            streamId: entry.streamId,
+            source: "coordinator",
+            status: "hls_ready",
+            data: result as unknown as Record<string, unknown>,
+          })
+          return
+        }
+      } catch {
+        // 404 / network blip is expected while Cloudflare warms up.
+      }
+      if (entry.hlsAttempts >= this.timings.hlsReadinessMaxAttempts) {
+        if (entry.hlsTimer) {
+          clearInterval(entry.hlsTimer)
+          entry.hlsTimer = undefined
+        }
+        const err = new Error(
+          `HLS playback URL did not become ready after ${this.timings.hlsReadinessMaxAttempts} attempts`,
+        )
+        for (const reject of entry.hlsReadyRejecters) reject(err)
+        entry.hlsReadyResolvers = []
+        entry.hlsReadyRejecters = []
+        this.fanout({
+          streamId: entry.streamId,
+          source: "coordinator",
+          status: "error",
+          data: {reason: "hls_not_ready"},
+        })
+        const targetStreamId = entry.streamId
+        void this.runExclusive(async () => {
+          if (this.current?.streamId !== targetStreamId) return
+          await this.teardownLocked("hls_not_ready")
+        })
+      }
+    }
+    setTimeout(() => {
+      // Guard: stream may have been torn down during the initial delay.
+      if (this.current !== entry) return
+      entry.hlsTimer = setInterval(tick, this.timings.hlsReadinessPollMs)
+    }, this.timings.hlsReadinessInitialDelayMs)
+  }
+
+  private fanout(update: StreamStatusUpdate): void {
+    if (!this.current || !this.statusSubscriber) return
+    const targets =
+      this.current.kind === "managed"
+        ? Array.from(this.current.subscribers)
+        : [this.current.packageName]
+    for (const pkg of targets) {
+      try {
+        this.statusSubscriber(pkg, update)
+      } catch (err) {
+        console.warn("[STREAM] statusSubscriber threw:", err)
+      }
+    }
+  }
+
+  /**
+   * Run teardown of the currently-active stream. Caller must hold the
+   * transition lock (see {@link runExclusive}). Keeps `this.current`
+   * populated until BluetoothSdk.stopStream resolves so a concurrent caller
+   * waiting on the lock can't claim the slot mid-stop and have its
+   * startStream BLE write collide with our in-flight stopStream.
+   */
+  private async teardownLocked(reason: string, options: {sendBleStop?: boolean} = {}): Promise<void> {
+    const entry = this.current
+    if (!entry) return
+    const sendBleStop = options.sendBleStop !== false
+
+    this.lastFanoutSignature = null
+    this.resolvedConfigForwarded = false
+
+    // 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
+
+    if (entry.kind === "managed") {
+      if (entry.cloudflareTimer) clearInterval(entry.cloudflareTimer)
+      if (entry.hlsTimer) clearInterval(entry.hlsTimer)
+      // Reject any still-pending HLS readiness waiters.
+      const pendingErr = new Error(`Stream torn down: ${reason}`)
+      for (const reject of entry.hlsReadyRejecters) reject(pendingErr)
+      entry.hlsReadyResolvers = []
+      entry.hlsReadyRejecters = []
+      // Cloudflare DELETE is fire-and-forget — failing it doesn't undo the
+      // BLE stop we're about to do, and Cloudflare's idle-input scavenger
+      // will eventually clean up leaked inputs.
+      teardownManagedStream(entry.liveInputId).catch((err) => {
+        console.warn("[STREAM] teardownManagedStream failed:", err)
+      })
+    }
+
+    try {
+      if (sendBleStop) {
+        await BluetoothSdk.stopStream()
+      }
+    } catch (err) {
+      console.warn("[STREAM] BluetoothSdk.stopStream failed:", err)
+    } finally {
+      // Release the slot AFTER the BLE stop finished, so the next start can
+      // safely write its own start_stream without colliding with ours.
+      // 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
+    }
+  }
+}
+
+function pickIngestUrl(p: ProvisionResult, preference?: "srt" | "whip"): string {
+  // Glasses' StreamCommandHandler detects protocol from URL prefix.
+  //
+  // Default priority: SRT > RTMP > WHIP. SRT first: Cloudflare's WebRTC (WHIP)
+  // ingest does NOT feed HLS/DASH playback or recording — a WHIP-ingested
+  // managed stream reports "connected" while its hlsUrl serves 204 forever,
+  // which breaks the managed contract (subscribers share HLS playback). SRT
+  // also survives office firewalls that kill RTMPS:443 mid-handshake.
+  //
+  // "whip" preference flips the trade: sub-second WHEP playback for
+  // live-monitor use cases, accepting no HLS and no recording.
+  //
+  // Throw if none resolved so the caller's Promise rejects with a clear
+  // message rather than the glasses' "unknown protocol" error.
+  const url =
+    preference === "whip"
+      ? p.webrtcPublishUrl || p.srtUrl || p.rtmpUrl
+      : p.srtUrl || p.rtmpUrl || p.webrtcPublishUrl
+  if (!url) {
+    throw new Error("Cloudflare provision returned no usable ingest URL")
+  }
+  return url
+}
+
+function publisherStartResult(streamId: string, event?: StreamStatusEvent): StreamPublisherStartResult {
+  return {
+    streamId: event?.streamId || streamId,
+    status: event?.status ?? "streaming",
+    ...(event?.resolvedConfig ? {resolvedConfig: event.resolvedConfig} : {}),
+  }
+}
+
+function managedStartResult(entry: ManagedEntry): ManagedStartResult {
+  const publisher = entry.publisherStart ?? publisherStartResult(entry.streamId)
+  return {
+    ...publisher,
+    streamId: entry.streamId,
+    liveInputId: entry.liveInputId,
+    mode: entry.mode,
+    hlsUrl: entry.hlsUrl,
+    dashUrl: entry.dashUrl,
+    webrtcUrl: entry.webrtcUrl,
+  }
+}
+
+// Singleton — coordinator's single-stream constraint is process-wide.
+export const phoneStreamCoordinator = new PhoneStreamCoordinator()