@mentra/engine 3.2.0-dev.226 → 3.2.0-dev.232

package/src/services/PhoneStreamCoordinator.ts

@@ -35,10 +35,12 @@
 
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 import type {StreamResolvedConfig, StreamStartRequest, StreamStatusEvent} from "@mentra/bluetooth-sdk/internal"
+import {createManagedWebRtcRelay, type ManagedRelay} from "./ManagedWebRtcRelay"
 import {isGlassesConnected} from "./GlassesReadiness"
 import {phoneCameraFovCoordinator} from "./PhoneCameraFovCoordinator"
 import {useGlassesStore} from "../stores/glasses"
 
+import {BgTimer} from "../utils/timers"
 import {slimStreamStatusEvent, streamStatusSignature} from "./slimStreamStatus"
 import {
   getManagedStreamStatus,
@@ -176,13 +178,15 @@ interface ManagedEntry {
   hlsUrl: string
   dashUrl: string
   webrtcUrl?: string
+  stopping?: boolean
+  relay?: ManagedRelay
   publisherStart?: StreamPublisherStartResult
   subscribers: Set<string>
   hlsReady: boolean
   hlsReadyResolvers: Array<(result: ManagedStartResult) => void>
   hlsReadyRejecters: Array<(err: Error) => void>
-  cloudflareTimer?: ReturnType<typeof setTimeout>
-  hlsTimer?: ReturnType<typeof setInterval>
+  cloudflareTimer?: ReturnType<typeof BgTimer.setTimeout>
+  hlsTimer?: ReturnType<typeof BgTimer.setInterval>
   hlsAttempts: number
   /** Cloudflare status probes made during this stream session. */
   cloudflareAttempts: number
@@ -208,7 +212,7 @@ export class StreamConflictError extends Error {
 
 interface SuspendedState {
   since: number
-  graceTimer: ReturnType<typeof setTimeout>
+  graceTimer: ReturnType<typeof BgTimer.setTimeout>
   /** Consecutive Cloudflare probes that saw no publisher during this suspension. */
   publisherGoneProbes: number
 }
@@ -218,6 +222,7 @@ export class PhoneStreamCoordinator {
   private statusSubscriber: StatusSubscriber | null = null
   private idCounter = 0
   private readonly timings: TimingConfig
+  private readonly relayFactory: typeof createManagedWebRtcRelay
   private readonly linkSource: GlassesLinkSource
   private readonly pendingCameraChanges: () => Promise<void>
   private unsubscribeLink: (() => void) | null = null
@@ -228,7 +233,7 @@ export class PhoneStreamCoordinator {
    * the slot) so a publisher that outlived its input does not keep pushing
    * until its own watchdog fires.
    */
-  private pendingBleStop: {streamId: string} | null = null
+  private pendingBleStop: {streamId: string; hotspot?: boolean} | null = null
   /**
    * Serializes state transitions (start, stop, teardown). Without it, a
    * second `start*` racing with the first can pass the `this.current === null`
@@ -245,8 +250,13 @@ export class PhoneStreamCoordinator {
 
   constructor(
     timings: CoordinatorTimings = {},
-    deps: {linkSource?: GlassesLinkSource; pendingCameraChanges?: () => Promise<void>} = {},
+    deps: {
+      linkSource?: GlassesLinkSource
+      pendingCameraChanges?: () => Promise<void>
+      relayFactory?: typeof createManagedWebRtcRelay
+    } = {},
   ) {
+    this.relayFactory = deps.relayFactory ?? createManagedWebRtcRelay
     this.timings = {...DEFAULT_TIMINGS, ...timings}
     this.linkSource = deps.linkSource ?? storeLinkSource
     this.pendingCameraChanges = deps.pendingCameraChanges ?? (() => phoneCameraFovCoordinator.whenSettled())
@@ -300,7 +310,10 @@ export class PhoneStreamCoordinator {
    * check covers the multi-subscriber case.
    */
   owns(streamId: string): boolean {
-    return this.current !== null && this.current.streamId === streamId
+    return (
+      this.current !== null &&
+      (this.current.streamId === streamId || (this.current.kind === "managed" && !!this.current.relay?.owns(streamId)))
+    )
   }
 
   /** Report-safe stream ownership snapshot for incident diagnostics. */
@@ -342,6 +355,7 @@ export class PhoneStreamCoordinator {
     return this.runExclusive(async () => {
       await cameraReady
       this.assertGlassesConnected()
+      await this.flushPendingBleStop()
       if (this.current) {
         throw new StreamConflictError(
           "STREAM_ALREADY_ACTIVE",
@@ -407,6 +421,7 @@ export class PhoneStreamCoordinator {
     const decision = await this.runExclusive(async (): Promise<JoinDecision> => {
       await cameraReady
       this.assertGlassesConnected()
+      await this.flushPendingBleStop()
       if (this.current && this.current.kind === "unmanaged") {
         throw new StreamConflictError(
           "STREAM_ALREADY_ACTIVE",
@@ -417,6 +432,17 @@ export class PhoneStreamCoordinator {
       // Join an existing managed stream if one is already running.
       if (this.current && this.current.kind === "managed") {
         const existing = this.current
+        if (existing.stopping)
+          throw new StreamConflictError(
+            "STREAM_CLEANUP_PENDING",
+            "Previous stream cleanup has not completed; retry stop first",
+          )
+        if (opts.ingest !== undefined && (opts.ingest === "whip") !== (existing.mode === "webrtc")) {
+          throw new StreamConflictError(
+            "STREAM_MODE_CONFLICT",
+            "Stop the existing stream before switching playback modes",
+          )
+        }
         // 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.
@@ -436,7 +462,13 @@ export class PhoneStreamCoordinator {
       // and joins instead of double-provisioning.
       const provision = await provisionManagedStream(opts.restreamDestinations)
       const streamId = this.mintId("m")
-      const ingestUrl = pickIngestUrl(provision, opts.ingest)
+      let ingestUrl: string
+      try {
+        ingestUrl = pickIngestUrl(provision, opts.ingest)
+      } catch (error) {
+        await teardownManagedStream(provision.liveInputId).catch(() => undefined)
+        throw error
+      }
       const mode: ManagedEntry["mode"] = ingestUrl === provision.webrtcPublishUrl ? "webrtc" : "hls"
 
       const entry: ManagedEntry = {
@@ -466,17 +498,40 @@ export class PhoneStreamCoordinator {
       })
 
       try {
-        const event = await BluetoothSdk.startStream({
-          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} : {}),
-          ...(typeof opts.captureAudio === "boolean" ? {captureAudio: opts.captureAudio} : {}),
-        })
-        entry.publisherStart = publisherStartResult(streamId, event)
+        if (mode === "webrtc") {
+          entry.relay = this.relayFactory(
+            {streamId, ingestUrl, ...opts},
+            (status, reason) => {
+              if (this.current === entry && !entry.stopping)
+                this.fanout({streamId, source: "coordinator", status, data: {reason, transport: "softap_relay"}})
+            },
+            (error) => {
+              void this.runExclusive(async () => {
+                if (this.current !== entry) return
+                this.fanout({streamId, source: "coordinator", status: "error", data: {reason: error.message}})
+                await this.teardownLocked("relay_failed")
+              }).catch((cleanupError) => console.warn("[STREAM] relay cleanup failed", cleanupError))
+            },
+            () => this.linkSource.isConnected(),
+            () => {
+              this.pendingBleStop = {streamId, hotspot: true}
+              this.attachLink()
+            },
+          )
+        }
+        const event = entry.relay
+          ? await entry.relay.start()
+          : await BluetoothSdk.startStream({
+              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} : {}),
+              ...(typeof opts.captureAudio === "boolean" ? {captureAudio: opts.captureAudio} : {}),
+            })
+        entry.publisherStart = {...publisherStartResult(streamId, event), streamId}
         console.info("[STREAM_STARTUP]", {
           streamId,
           stage: "publisher_ready",
@@ -484,8 +539,14 @@ export class PhoneStreamCoordinator {
           elapsedMs: Date.now() - startupStartedAtMs,
         })
       } catch (err) {
-        this.current = null
-        await teardownManagedStream(provision.liveInputId).catch(() => undefined)
+        entry.stopping = true
+        try {
+          await entry.relay?.stop()
+          this.current = null
+          await this.flushPendingBleStop()
+        } finally {
+          await teardownManagedStream(provision.liveInputId).catch(() => undefined)
+        }
         throw err
       }
 
@@ -500,6 +561,9 @@ export class PhoneStreamCoordinator {
       return {kind: "fresh", entry}
     })
 
+    if (this.current !== decision.entry || decision.entry.stopping) {
+      throw new Error("Stream stopped before playback readiness")
+    }
     if (decision.kind === "join" && decision.immediate) {
       return decision.immediate
     }
@@ -520,6 +584,15 @@ export class PhoneStreamCoordinator {
   }
 
   async stop(packageName: string, streamId?: string): Promise<void> {
+    // Cancel in-flight native preparation immediately; cleanup remains serialized below.
+    const pending = this.current
+    if (
+      pending?.kind === "managed" &&
+      (!streamId || pending.streamId === streamId) &&
+      pending.subscribers.size === 1 &&
+      pending.subscribers.has(packageName)
+    )
+      pending.relay?.cancel()
     await this.runExclusive(async () => {
       if (!this.current) return
 
@@ -549,6 +622,10 @@ export class PhoneStreamCoordinator {
    */
   handleGlassesStatus(event: StreamStatusEvent): void {
     if (!this.current) return
+    if (this.current.kind === "managed" && this.current.relay) {
+      this.current.relay.handleGlassesStatus(event)
+      return
+    }
     if (event.streamId && event.streamId !== this.current.streamId) return
 
     const includeResolvedConfig = !this.resolvedConfigForwarded && !!event.resolvedConfig
@@ -579,12 +656,7 @@ export class PhoneStreamCoordinator {
     if (event.terminal === true || isGiveUp || isStopped) {
       const reason = isGiveUp ? "glasses_gave_up" : event.status === "error" ? "glasses_error" : "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})
-      })
+      this.requestTeardown(targetStreamId, reason, {sendBleStop: false})
     }
   }
 
@@ -608,7 +680,9 @@ export class PhoneStreamCoordinator {
       if (this.current && this.suspended) {
         this.resumeLocked()
       } else if (!this.current && this.pendingBleStop) {
-        this.flushPendingBleStop()
+        void this.runExclusive(() => this.flushPendingBleStop()).catch((error) =>
+          console.warn("[STREAM] deferred cleanup failed", error),
+        )
       }
       return
     }
@@ -619,7 +693,7 @@ export class PhoneStreamCoordinator {
     const entry = this.current
     if (!entry) return
     const since = Date.now()
-    const graceTimer = setTimeout(() => this.onGraceExpired(entry.streamId), this.timings.glassesGraceMs)
+    const graceTimer = BgTimer.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,
@@ -637,7 +711,7 @@ export class PhoneStreamCoordinator {
     const entry = this.current
     const suspended = this.suspended
     if (!entry || !suspended) return
-    clearTimeout(suspended.graceTimer)
+    BgTimer.clearTimeout(suspended.graceTimer)
     this.suspended = null
     const suspendedMs = Date.now() - suspended.since
     console.info("[STREAM] BLE link back; stream resumed", {streamId: entry.streamId, suspendedMs})
@@ -668,20 +742,33 @@ export class PhoneStreamCoordinator {
       status: "error",
       data: {reason: LINK_STATUS.reason, teardownReason: reason, ...detail},
     })
+    this.requestTeardown(streamId, reason)
+  }
+
+  /** Event/timer failures have no awaiting caller; retain and report cleanup errors locally. */
+  private requestTeardown(streamId: string, reason: string, options: {sendBleStop?: boolean} = {}): void {
     void this.runExclusive(async () => {
       if (this.current?.streamId !== streamId) return
-      await this.teardownLocked(reason)
+      await this.teardownLocked(reason, options)
+    }).catch((error) => {
+      console.warn("[STREAM] cleanup failed", error)
+      if (this.current?.streamId === streamId) {
+        this.fanout({streamId, source: "coordinator", status: "error", data: {reason: "cleanup_failed"}})
+      }
     })
   }
 
-  private flushPendingBleStop(): void {
+  private async flushPendingBleStop(): Promise<void> {
     const pending = this.pendingBleStop
-    if (!pending) return
-    this.pendingBleStop = null
+    if (!pending || this.current || !this.linkSource.isConnected()) return
     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())
+    await BluetoothSdk.stopStream()
+    if (pending.hotspot) {
+      const result = await BluetoothSdk.setHotspotState(false)
+      if (result.state !== "disabled") throw new Error("Deferred hotspot shutdown was not confirmed")
+    }
+    if (this.pendingBleStop === pending) this.pendingBleStop = null
+    this.detachLinkIfIdle()
   }
 
   // ===========================================================================
@@ -708,7 +795,7 @@ export class PhoneStreamCoordinator {
     const pollingStartedAtMs = Date.now()
 
     const scheduleNext = () => {
-      if (this.current !== entry) return
+      if (this.current !== entry || entry.stopping) return
       const waitingForWebRtc = entry.mode === "webrtc" && !entry.hlsReady
       const elapsedMs = Date.now() - pollingStartedAtMs
       const remainingMs = Math.max(0, connectTimeoutMs - elapsedMs)
@@ -717,16 +804,17 @@ export class PhoneStreamCoordinator {
         this.timings.cloudflareStartupPollInitialMs * 2 ** Math.min(Math.max(0, entry.cloudflareAttempts - 1), 10),
       )
       const delayMs = waitingForWebRtc ? Math.min(startupDelayMs, remainingMs) : this.timings.cloudflareStatusPollMs
-      entry.cloudflareTimer = setTimeout(() => void poll(), delayMs)
+      entry.cloudflareTimer = BgTimer.setTimeout(() => void poll(), delayMs)
     }
 
     const poll = async () => {
-      if (this.current !== entry) return
+      if (this.current !== entry || entry.stopping) return
       const requestStartedAtMs = Date.now()
       let keepPolling = true
       entry.cloudflareAttempts += 1
       try {
         const status: CloudflareStatus = await getManagedStreamStatus(entry.liveInputId)
+        if (this.current !== entry || entry.stopping) return
         console.debug("[STREAM_STARTUP]", {
           streamId: entry.streamId,
           stage: "cloudflare_probe",
@@ -791,15 +879,13 @@ export class PhoneStreamCoordinator {
                 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")
-              })
+              this.requestTeardown(targetStreamId, "webrtc_not_connected")
               keepPolling = false
             }
           }
         }
       } catch (err) {
+        if (this.current !== entry || entry.stopping) return
         console.warn("[STREAM] cloudflare status poll failed:", err)
         if (entry.mode === "webrtc" && !entry.hlsReady && Date.now() - pollingStartedAtMs >= connectTimeoutMs) {
           const timeoutErr = new Error(`WebRTC ingest status could not be confirmed after ${connectTimeoutMs}ms`)
@@ -807,10 +893,7 @@ export class PhoneStreamCoordinator {
           entry.hlsReadyResolvers = []
           entry.hlsReadyRejecters = []
           const targetStreamId = entry.streamId
-          void this.runExclusive(async () => {
-            if (this.current?.streamId !== targetStreamId) return
-            await this.teardownLocked("webrtc_status_unavailable")
-          })
+          this.requestTeardown(targetStreamId, "webrtc_status_unavailable")
           keepPolling = false
         }
       } finally {
@@ -827,13 +910,14 @@ export class PhoneStreamCoordinator {
     // 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
+      if (this.current !== entry || entry.stopping) 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 (this.current !== entry || entry.stopping) return
         if (res.status === 200) {
           entry.hlsReady = true
           console.info("[STREAM_STARTUP]", {
@@ -844,7 +928,7 @@ export class PhoneStreamCoordinator {
             elapsedMs: Date.now() - entry.startupStartedAtMs,
           })
           if (entry.hlsTimer) {
-            clearInterval(entry.hlsTimer)
+            BgTimer.clearInterval(entry.hlsTimer)
             entry.hlsTimer = undefined
           }
           const result = managedStartResult(entry)
@@ -864,7 +948,7 @@ export class PhoneStreamCoordinator {
       }
       if (entry.hlsAttempts >= this.timings.hlsReadinessMaxAttempts) {
         if (entry.hlsTimer) {
-          clearInterval(entry.hlsTimer)
+          BgTimer.clearInterval(entry.hlsTimer)
           entry.hlsTimer = undefined
         }
         const err = new Error(
@@ -880,16 +964,13 @@ export class PhoneStreamCoordinator {
           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")
-        })
+        this.requestTeardown(targetStreamId, "hls_not_ready")
       }
     }
-    setTimeout(() => {
+    BgTimer.setTimeout(() => {
       // Guard: stream may have been torn down during the initial delay.
-      if (this.current !== entry) return
-      entry.hlsTimer = setInterval(tick, this.timings.hlsReadinessPollMs)
+      if (this.current !== entry || entry.stopping) return
+      entry.hlsTimer = BgTimer.setInterval(tick, this.timings.hlsReadinessPollMs)
     }, this.timings.hlsReadinessInitialDelayMs)
   }
 
@@ -921,7 +1002,7 @@ export class PhoneStreamCoordinator {
     this.resolvedConfigForwarded = false
 
     if (this.suspended) {
-      clearTimeout(this.suspended.graceTimer)
+      BgTimer.clearTimeout(this.suspended.graceTimer)
       this.suspended = null
     }
 
@@ -929,7 +1010,7 @@ export class PhoneStreamCoordinator {
     // 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}
+      this.pendingBleStop = {streamId: entry.streamId, hotspot: entry.kind === "managed" && !!entry.relay}
       console.warn("[STREAM] BLE link down during teardown; stopStream deferred", {
         streamId: entry.streamId,
         reason,
@@ -937,8 +1018,9 @@ export class PhoneStreamCoordinator {
     }
 
     if (entry.kind === "managed") {
-      if (entry.cloudflareTimer) clearTimeout(entry.cloudflareTimer)
-      if (entry.hlsTimer) clearInterval(entry.hlsTimer)
+      entry.stopping = true
+      if (entry.cloudflareTimer) BgTimer.clearTimeout(entry.cloudflareTimer)
+      if (entry.hlsTimer) BgTimer.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)
@@ -946,8 +1028,11 @@ export class PhoneStreamCoordinator {
       entry.hlsReadyRejecters = []
     }
 
+    // Relay stop owns the BLE publisher, native peers and hotspot. Keep the entry on failure
+    // so another start cannot acquire resources whose teardown has not been confirmed.
+    if (entry.kind === "managed" && entry.relay) await entry.relay.stop()
     try {
-      if (sendBleStop && linkUp) {
+      if (sendBleStop && linkUp && !(entry.kind === "managed" && entry.relay)) {
         await BluetoothSdk.stopStream()
       }
     } catch (err) {
@@ -958,8 +1043,6 @@ 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
         // hold the local transition lock on an unbounded network request. The
@@ -969,6 +1052,9 @@ export class PhoneStreamCoordinator {
           console.warn("[STREAM] teardownManagedStream failed:", err)
         })
       }
+      // BLE can recover while native cleanup is draining; no second link event is required.
+      await this.flushPendingBleStop()
+      this.detachLinkIfIdle()
     }
   }
 }
@@ -976,7 +1062,7 @@ export class PhoneStreamCoordinator {
 function pickIngestUrl(p: ProvisionResult, preference?: "srt" | "whip" | "rtmp"): string {
   // Glasses' StreamCommandHandler detects protocol from URL prefix.
   //
-  // Default priority: SRT > RTMP > WHIP. SRT first: Cloudflare's WebRTC (WHIP)
+  // Default priority: SRT > RTMP. WHIP is explicit. 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
@@ -991,11 +1077,7 @@ function pickIngestUrl(p: ProvisionResult, preference?: "srt" | "whip" | "rtmp")
   // 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
-      : preference === "rtmp"
-      ? p.rtmpUrl || p.srtUrl || p.webrtcPublishUrl
-      : p.srtUrl || p.rtmpUrl || p.webrtcPublishUrl
+    preference === "whip" ? p.webrtcPublishUrl : preference === "rtmp" ? p.rtmpUrl || p.srtUrl : p.srtUrl || p.rtmpUrl
   if (!url) {
     throw new Error("Cloudflare provision returned no usable ingest URL")
   }

package/src/services/SoftapCallTransport.ts

@@ -107,6 +107,8 @@ export interface SoftapCallDeps {
   /** Join the hotspot without taking the phone's default route. Resolves to the phone's own IPv4. */
   joinScopedNetwork(ssid: string, passphrase: string, report?: SoftapStepReporter): Promise<string | undefined>
   leaveScopedNetwork(): Promise<void>
+  /** Interrupt a pending native join while retaining its cleanup barrier. Unsupported hosts wait. */
+  cancelScopedNetworkJoin?(): Promise<void>
   /**
    * Join the meeting. This is what binds the local WHIP listener and arms the ACS raw outputs, so
    * it must resolve before the glasses are told to publish.
@@ -411,7 +413,7 @@ export class SoftapCallTransport {
           throw new Error("the meeting reported no ingest URL")
         }
         this.ingestUrl = ingestUrl
-        softapTrace("acs_joined", {ingestUrl})
+        softapTrace("acs_receiver_ready", {ingestUrl})
         report(`Receiver ready at ${ingestUrl}`)
       })
 
@@ -424,10 +426,10 @@ export class SoftapCallTransport {
       })
 
       await this.step(generation, "live", "NO_FIRST_FRAME", async (report) => {
-        report("Waiting for the first video frame to reach Teams")
+        report("Waiting for the first glasses video frame on this phone")
         await this.deps.awaitFirstFrame(report)
-        softapTrace("first_frame_in_acs")
-        report("Video is live in the meeting")
+        softapTrace("first_glasses_frame_received")
+        report("Glasses video is reaching this phone")
       })
 
       if (generation !== this.generation) {
@@ -500,9 +502,21 @@ export class SoftapCallTransport {
       // this call is still coming". Deliberately unbounded: a native call that never returns must
       // hold the next call back, never let it race this one's cleanup.
       if (running) {
+        const cancellation =
+          running.step === "scopedJoin" && this.deps.cancelScopedNetworkJoin
+            ? Promise.resolve()
+                .then(() => this.deps.cancelScopedNetworkJoin!())
+                .catch((error) => {
+                  if (!this.teardownFailures.includes("scopedJoin")) this.teardownFailures.push("scopedJoin")
+                  softapTraceFailure("softap_join_cancel_failed", {
+                    reason: error instanceof Error ? error.message : String(error),
+                  })
+                })
+            : undefined
         softapTrace("softap_stop_waiting_for_step", {step: running.step})
         const waitStartedAt = Date.now()
         await running.settled
+        await cancellation
         // This wait is unbounded by design, so its duration is the difference between "the leave
         // was slow" and "the leave was held by a native call that had not returned".
         softapTrace("softap_stop_step_settled", {step: running.step, waitedMs: Date.now() - waitStartedAt})
@@ -707,9 +721,10 @@ export function createSoftapCallDeps(args: {
   /** Resolves when the meeting reports a frame reached ACS; rejects on a failed feed. */
   awaitFirstFrame: () => Promise<void>
   subsystems: {
-    setHotspotState: (enabled: boolean) => Promise<{state: string; ssid?: string; password?: string}>
-    joinScopedNetwork: (ssid: string, passphrase: string) => Promise<string | undefined>
+    setHotspotState: (enabled: boolean) => Promise<{state: string; ssid?: string; password?: string; localIp?: string}>
+    joinScopedNetwork: (ssid: string, passphrase: string, gateway?: string) => Promise<string | undefined>
     leaveScopedNetwork: () => Promise<void>
+    cancelScopedNetworkJoin?: () => Promise<void>
     joinMeeting: (
       packageName: string,
       options: {
@@ -767,6 +782,7 @@ export function createSoftapCallDeps(args: {
 }): SoftapCallDeps {
   const {packageName, subsystems} = args
   const hotspotBroadcastWaitMs = args.hotspotBroadcastWaitMs ?? HOTSPOT_BROADCAST_WAIT_MS
+  let gatewayAddress: string | undefined
   return {
     startHotspot: async (report) => {
       const enable = async () => {
@@ -778,6 +794,7 @@ export function createSoftapCallDeps(args: {
           throw new Error("the glasses hotspot reported no password")
         }
         report?.(`Glasses report hotspot ${status.ssid} enabled`)
+        gatewayAddress = status.localIp
         return {ssid: status.ssid, passphrase: status.password}
       }
       try {
@@ -808,7 +825,9 @@ export function createSoftapCallDeps(args: {
     },
     joinScopedNetwork: async (ssid, passphrase, report) => {
       const joinOnce = (nextSsid: string, nextPassphrase: string) =>
-        subsystems.joinScopedNetwork(nextSsid, nextPassphrase)
+        gatewayAddress
+          ? subsystems.joinScopedNetwork(nextSsid, nextPassphrase, gatewayAddress)
+          : subsystems.joinScopedNetwork(nextSsid, nextPassphrase)
       let address: string | undefined
       try {
         address = await joinOnce(ssid, passphrase)
@@ -821,6 +840,7 @@ export function createSoftapCallDeps(args: {
         await subsystems.setHotspotState(false)
         const status = await subsystems.setHotspotState(true)
         if (status.state !== "enabled" || !status.ssid || !status.password) throw error
+        gatewayAddress = status.localIp
         if (hotspotBroadcastWaitMs > 0) {
           report?.(
             `Giving the hotspot ${Math.round(hotspotBroadcastWaitMs / 1000)}s to start broadcasting`,
@@ -848,6 +868,7 @@ export function createSoftapCallDeps(args: {
       return address
     },
     leaveScopedNetwork: () => subsystems.leaveScopedNetwork(),
+    cancelScopedNetworkJoin: subsystems.cancelScopedNetworkJoin,
     joinMeeting: async ({ssid, passphrase, bindAddress}, report) => {
       // The hotspot join just took this phone off Wi-Fi, so the route Teams needs is whatever
       // Android promoted in its place. Waiting for it to validate is what stopped the ACS join