@mentra/engine 3.2.0-dev.261 → 3.2.0-dev.262

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.2.0",
-  "releaseIdentity": "3.2.0-dev.261",
-  "releaseSetId": "mentra-3.2.0-dev.261",
-  "sourceCommit": "ebd405ff0f311035faccac6e19b0a5a38b3a1483",
-  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.261.json",
-  "otaManifestSha256": "e9d88a258f276ee9ddc5396e9c5745f91f924449b802248e6d37dfe9bb8bb3ee"
+  "releaseIdentity": "3.2.0-dev.262",
+  "releaseSetId": "mentra-3.2.0-dev.262",
+  "sourceCommit": "545ed70c7afa46ca09b895d2dcd651b45510dbb5",
+  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.262.json",
+  "otaManifestSha256": "d1c4e63ae2c1cd8de479d4bbc57219d2b85e904c26a491441265f5182220125f"
 })

package/src/services/AcsMeetingService.ts

@@ -382,6 +382,11 @@ type NativeModule = {
   updateVideoSource(whepUrl: string): Promise<void>
   /** Force a WHEP rebuild on the current URL. Absent on natives that predate it. */
   restartVideoSource?(): Promise<void>
+  /**
+   * SoftAP: destroy the current ingest listener and bind a new one. Resolves with
+   * the new URL. Absent on natives that predate rebind; disabled natives reject.
+   */
+  rebindSoftApIngest?(): Promise<string>
   /**
    * Join the glasses hotspot as a scoped, internet-less network; resolves with this phone's
    * address on it. Absent on natives that predate SoftAP.
@@ -569,6 +574,13 @@ class AcsMeetingService {
   private lastMediaRestartAt = 0
   /** Callers parked in [waitForFirstFrame], woken by the next `mediaSource` verdict. */
   private readonly firstFrameWaiters = new Set<(error?: Error) => void>()
+  /**
+   * Bumped by [invalidateDecodedMedia]. A `live` verdict only counts for the wait that
+   * started after that bump if [liveEpoch] matches.
+   */
+  private decodedMediaEpoch = 0
+  /** [decodedMediaEpoch] at the moment the phone last reported `mediaSource: live`. */
+  private liveEpoch = -1
   /** Mid-call republish waiters: live resolves true, leave/timeout resolves false. Failed is ignored. */
   private readonly mediaLiveWaiters = new Set<(live: boolean) => void>()
   private scopedLostSub: {remove: () => void} | null = null
@@ -657,6 +669,32 @@ class AcsMeetingService {
     await getNative()?.forceCloseIngest?.()
   }
 
+  /**
+   * Destroy the current SoftAP ingest listener and bind a new one. The caller
+   * rejoins the hotspot first; native reads the current scoped address.
+   */
+  async rebindSoftApIngest(): Promise<string> {
+    const native = getNative()
+    if (!native?.rebindSoftApIngest) {
+      throw new Error("SoftAP ingest rebind is not available on this native")
+    }
+    this.invalidateDecodedMedia()
+    const url = await native.rebindSoftApIngest()
+    this.ingestUrl = url
+    return url
+  }
+
+  /**
+   * Forget a previously decoded first frame. Recovery must wait for a frame
+   * from the new ingest generation, not short-circuit on the last live verdict.
+   */
+  invalidateDecodedMedia(): void {
+    this.decodedMediaEpoch++
+    if (this.lastState.mediaSource === "live") {
+      this.lastState = {...this.lastState, mediaSource: "connecting", mediaSourceReason: "ingest_rebind"}
+    }
+  }
+
   /**
    * Is this phone's Wi-Fi radio on?
    *
@@ -795,9 +833,18 @@ class AcsMeetingService {
    *
    * @param timeoutMs how long to wait before treating the silence as a failure
    */
-  waitForFirstFrame(timeoutMs: number): Promise<void> {
-    if (this.lastState.mediaSource === "live") {
-      softapTrace("glasses_first_frame_already_received", {mediaSource: this.lastState.mediaSource})
+  waitForFirstFrame(timeoutMs: number, options: {fresh?: boolean} = {}): Promise<void> {
+    const liveThisGeneration =
+      this.lastState.mediaSource === "live" && this.liveEpoch === this.decodedMediaEpoch
+    // Join short-circuits on any live. Recovery (`fresh`) short-circuits only on a live
+    // from this ingest generation: the new WHIP first frame often lands during publish,
+    // before this wait starts. Waiting for a later `onState` then times out while video
+    // is already flowing, and the miniapp hangs up the ACS meeting.
+    if (liveThisGeneration) {
+      softapTrace(
+        options.fresh ? "glasses_first_frame_this_generation" : "glasses_first_frame_already_received",
+        {mediaSource: this.lastState.mediaSource, epoch: this.decodedMediaEpoch},
+      )
       return Promise.resolve()
     }
     const startedAt = Date.now()
@@ -1542,6 +1589,7 @@ class AcsMeetingService {
           participants: participants?.length,
           endReason: endReason ? `${endReason.code ?? "?"}/${endReason.subcode ?? "?"}` : undefined,
         })
+        if (mediaSource === "live") this.liveEpoch = this.decodedMediaEpoch
         this.settleFirstFrameWaiters(mediaSource)
         this.onState?.(packageName, state)
         // A remote hang-up, an ACS error or a dropped call never goes through `leave`, so without

package/src/services/LocalMiniappRuntime.ts

@@ -35,7 +35,7 @@ import {storage as mmkvStorage} from "../utils/storage/storage"
 import {BgTimer} from "../utils/timers"
 import devServerBridge from "./DevServerBridge"
 import {islandNotifications} from "./NotificationsEmitter"
-import {isGlassesConnected} from "./GlassesReadiness"
+import {isGlassesConnected, isGlassesReady, waitForGlassesReady} from "./GlassesReadiness"
 import {toMiniappConnectionData} from "./GlassesStatusProjection"
 import audioPlaybackService from "./AudioPlaybackService"
 import {phoneLocationService} from "./PhoneLocationService"
@@ -85,7 +85,7 @@ import type {ClientApp} from "../types/applet"
 import {useAppStatusStore} from "../stores/apps"
 import appRegistry, {getDevAppAttestation, getDevAppSourcePackage} from "./AppRegistry"
 import {resolveForegroundLocationPermission} from "./ForegroundLocationPermission"
-import {advanceMiniappPingLiveness} from "./MiniappLiveness"
+import {advanceMiniappPingLiveness, shouldHoldMiniappPingLiveness} from "./MiniappLiveness"
 import {listPhoneCalendarEvents, PhoneCalendarError} from "./PhoneCalendarService"
 import {LocalMiniappStorage} from "./LocalMiniappStorage"
 import acsMeetingService, {
@@ -102,6 +102,7 @@ import {
   createSoftapCallDeps,
   SoftapCallError,
   SoftapCallTransport,
+  RETURN_DEADLINE_MS,
   SOFTAP_STEPS,
   type SoftapProgress,
   type SoftapTeardownMode,
@@ -237,6 +238,11 @@ const FOREGROUND_LIVENESS_PROBE_TIMEOUT_MS = 2_500
  * rather than sit in "connecting" while the wearer waits.
  */
 const SOFTAP_FIRST_FRAME_MS = 20_000
+/**
+ * How long the BLE link must stay up before SoftAP recovery trusts it. Covers the gap between
+ * the hotspot dying and the phone noticing the link died with it.
+ */
+const GLASSES_LINK_SETTLE_MS = 4_000
 const REQUEST_WIFI_SETUP_TYPE = "miniapp_request_wifi_setup"
 // Unregister after this many missed pongs. Generous on purpose: a busy
 // context (heavy interim translation traffic) or OS scheduling while idle can
@@ -414,6 +420,14 @@ type SoftapAttempt = {
   /** The checklist as the miniapp last saw it; preflight rows live here until `start()` takes over. */
   progress: SoftapProgress
   scopedLostUnsub: (() => void) | null
+  /**
+   * Mid-call media rebuild. Single-flight while [recoveryActive] is true; the promise is
+   * cleared when that run settles so a later walk-away can start another. Joined to the
+   * attempt barrier so a late re-arm cannot resurrect resources after Leave/End.
+   */
+  recovery: Promise<void> | null
+  recoveryActive: boolean
+  recoveryDeadlineAt: number | null
   /**
    * The join itself, settled either way. A native call still in flight owns state the teardown
    * cannot see — a `createCallAgent` mid-sign-in — so the barrier covers this as well.
@@ -444,6 +458,27 @@ const SOFTAP_HOTSPOT_OFF_ACK_MS = 5_000
 /** After a forced close there is nothing left to wait for, so this only catches a real failure. */
 const SOFTAP_FORCED_VERIFY_MS = 500
 
+/**
+ * Rejection codes meaning the glasses replaced their Wi-Fi protocol session, not that the
+ * command failed.
+ *
+ * The glasses emit `wifi_protocol_session_ready` on every `glasses_ready`, which fires on BLE
+ * reconnects and ASG restarts — routine during a SoftAP teardown. The SDK cancels every pending
+ * Wi-Fi request when that lands, so a hotspot command in flight is lost even though nothing is
+ * actually wrong. `wifi_session_disconnected` is deliberately absent: that one is raised from the
+ * store update where the glasses went away, so there is nothing left to re-send to.
+ */
+const HOTSPOT_SESSION_REFRESH_CODES = new Set(["wifi_session_restarted", "wifi_session_changed"])
+
+/**
+ * Let the restarted ASG command path settle before re-sending.
+ *
+ * `handleSetHotspotState` returns false when its network manager is not up yet, which drops the
+ * command silently, so an immediate re-send would just race the same initialization. Mirrors the
+ * retry spacing `disableHotspotWithRetry` uses for the sibling ASG-replacement case.
+ */
+const HOTSPOT_SESSION_RETRY_DELAY_MS = 500
+
 /** Reject with [reason] if [work] has not settled in [ms]. The work itself is not cancellable. */
 function withTimeout<T>(work: Promise<T>, ms: number, reason: string): Promise<T> {
   return new Promise<T>((resolve, reject) => {
@@ -3654,6 +3689,7 @@ class LocalMiniappRuntime {
       this.sendToMiniapp(owner, {
         type: MiniappResponseType.MEETING_STATE,
         ...state,
+        ...this.softapRecoveryFields(attempt?.packageName === owner ? attempt : null),
       })
       if (attempt?.ownsResources && attempt.transport?.shouldRepublish(state.mediaSource)) {
         void attempt.transport.republish(state.mediaSourceReason ?? "mediaSource failed")
@@ -3865,8 +3901,12 @@ class LocalMiniappRuntime {
         phase: "starting",
         steps: SOFTAP_STEPS.map((step) => ({step, status: "pending" as const})),
         elapsedMs: 0,
+        mediaGeneration: 0,
       },
       scopedLostUnsub: null,
+      recovery: null,
+      recoveryActive: false,
+      recoveryDeadlineAt: null,
       body: null,
       teardown: null,
       settled,
@@ -3932,9 +3972,27 @@ class LocalMiniappRuntime {
       // join *is* in progress, and `idle` would make the miniapp think the call ended.
       state: current.state === "idle" ? "connecting" : current.state,
       softap: progress,
+      ...this.softapRecoveryFields(attempt),
     })
   }
 
+  private softapRecoveryFields(attempt: SoftapAttempt | null | undefined): {recovery?: {
+    active: boolean
+    generation?: number
+    deadlineAt?: number
+    phase?: string
+  }} {
+    if (!attempt?.recoveryDeadlineAt) return {}
+    return {
+      recovery: {
+        active: attempt.recoveryActive,
+        generation: attempt.transport?.currentMediaGeneration(),
+        deadlineAt: attempt.recoveryDeadlineAt,
+        phase: attempt.transport?.currentPhase(),
+      },
+    }
+  }
+
   /**
    * Narrates preflight work on the first row while it is still pending.
    *
@@ -3978,10 +4036,12 @@ class LocalMiniappRuntime {
     this.checkpointSoftapAttempt(attempt, "cleanup barrier")
     const cleanupError = this.softapCleanupError
     if (cleanupError) {
-      // Report once, allowing a retry after the wearer power-cycles the glasses.
+      // Cleared on read, so this refuses at most once and the next attempt always gets through —
+      // which is why the wearer is told to retry rather than to go power-cycle anything. The
+      // native reason stays in the trace: it names a leaked port, not something they can act on.
       this.softapCleanupError = null
       softapTraceFailure("softap_join_refused", {packageName, reason: cleanupError})
-      throw new Error(`Previous call cleanup failed: ${cleanupError}. Power-cycle the glasses hotspot and try again.`)
+      throw new Error("Previous call cleanup has not finished yet. Please try joining again.")
     }
     attempt.releaseHotspot = acquireGlassesHotspot()
     attempt.ownsResources = true
@@ -4011,7 +4071,8 @@ class LocalMiniappRuntime {
         token: args.token,
         displayName: args.displayName,
         video: args.video,
-        awaitFirstFrame: () => acsMeetingService.waitForFirstFrame(SOFTAP_FIRST_FRAME_MS),
+        awaitFirstFrame: (_report, options) =>
+          acsMeetingService.waitForFirstFrame(SOFTAP_FIRST_FRAME_MS, options),
         waitUntilLive: (timeoutMs) => acsMeetingService.waitUntilMediaLive(timeoutMs),
         subsystems: {
           setHotspotState: async (enabled) => {
@@ -4077,6 +4138,14 @@ class LocalMiniappRuntime {
           glassesLc3Uplink: () => acsMeetingService.glassesLc3UplinkActive(),
           startPublishing: (pkg, options) => phoneStreamCoordinator.startUnmanaged(pkg, options),
           stopPublishing: (pkg) => phoneStreamCoordinator.stop(pkg),
+          discardPendingBleStop: () => phoneStreamCoordinator.discardPendingBleStop(),
+          rebindIngest: async (report) => {
+            report?.("Rebinding the glasses video receiver on the hotspot")
+            const ingestUrl = await acsMeetingService.rebindSoftApIngest()
+            if (!ingestUrl) throw new Error("the rebound meeting reported no ingest URL")
+            report?.(`Receiver rebound at ${ingestUrl}`)
+            return {ingestUrl}
+          },
         },
       }),
     )
@@ -4109,14 +4178,7 @@ class LocalMiniappRuntime {
         reason: error.message,
         attemptAgeMs: Date.now() - attempt.startedAt,
       })
-      const current = acsMeetingService.getState()
-      this.sendToMiniapp(packageName, {
-        type: MiniappResponseType.MEETING_STATE,
-        ...current,
-        state: "error",
-        error: `SOFTAP_NETWORK_LOST: ${error.message}`,
-        softap: transport.progress(),
-      })
+      this.beginSoftapRecovery(attempt, transport, error)
     })
 
     // Sign in on the phone's current internet *before* the glasses hotspot takes DNS. On device,
@@ -4156,6 +4218,163 @@ class LocalMiniappRuntime {
     return state
   }
 
+  /**
+   * SoftAP loss is a media outage. Keep ACS, destroy generation N, wait for the glasses,
+   * then build generation N+1. Duplicate losses do not renew the deadline.
+   */
+  private beginSoftapRecovery(
+    attempt: SoftapAttempt,
+    transport: SoftapCallTransport,
+    error: {code: string; message: string},
+  ): void {
+    // Gate on the live flag, not the promise: a settled Promise is still truthy, so a second
+    // walk-away after a successful re-arm was dropped as "in-flight" and the glasses kept
+    // POSTing WHIP at a hotspot the phone had already left.
+    if (attempt.recoveryActive) {
+      softapTrace("softap_recovery_dropped", {attempt: attempt.id, cause: "in-flight"})
+      return
+    }
+    if (attempt.cancelled || this.softapAttempt !== attempt) {
+      softapTrace("softap_recovery_dropped", {
+        attempt: attempt.id,
+        cause: attempt.cancelled ? "retired" : "superseded",
+      })
+      return
+    }
+    const lostAt = Date.now()
+    attempt.recoveryDeadlineAt = lostAt + RETURN_DEADLINE_MS
+    attempt.recoveryActive = true
+    this.emitSoftapProgress(attempt, transport.progress())
+    softapTrace("softap_recovery_begin", {
+      attempt: attempt.id,
+      deadlineAt: attempt.recoveryDeadlineAt,
+      mediaGeneration: transport.currentMediaGeneration(),
+      reason: error.message,
+    })
+
+    let run!: Promise<void>
+    run = (async () => {
+      try {
+        await transport.recover(`${error.code}: ${error.message}`, {
+          wait: async () => {
+            const remaining = (attempt.recoveryDeadlineAt ?? 0) - Date.now()
+            if (remaining <= 0) {
+              throw new SoftapCallError("hotspot", "RETURN_DEADLINE", "The glasses did not return in time")
+            }
+            const ready = await this.waitForGlassesReturn(remaining, () => attempt.cancelled)
+            if (attempt.cancelled || this.softapAttempt !== attempt) {
+              throw new SoftapCallError("hotspot", "CANCELLED", "SoftAP recovery was cancelled")
+            }
+            if (!ready) {
+              throw new SoftapCallError("hotspot", "RETURN_DEADLINE", "The glasses did not return in time")
+            }
+          },
+        })
+        if (attempt.cancelled || this.softapAttempt !== attempt) return
+        this.emitSoftapProgress(attempt, transport.progress())
+        const current = acsMeetingService.getState()
+        this.sendToMiniapp(attempt.packageName, {
+          type: MiniappResponseType.MEETING_STATE,
+          ...current,
+          softap: transport.progress(),
+          ...this.softapRecoveryFields(attempt),
+        })
+        softapTrace("softap_recovery_live", {
+          attempt: attempt.id,
+          mediaGeneration: transport.currentMediaGeneration(),
+          elapsedMs: Date.now() - lostAt,
+        })
+      } catch (recoveryError) {
+        if (attempt.cancelled || this.softapAttempt !== attempt) return
+        const message = recoveryError instanceof Error ? recoveryError.message : String(recoveryError)
+        softapTraceFailure("softap_recovery_failed", {
+          attempt: attempt.id,
+          reason: message,
+          elapsedMs: Date.now() - lostAt,
+        })
+        const current = acsMeetingService.getState()
+        this.sendToMiniapp(attempt.packageName, {
+          type: MiniappResponseType.MEETING_STATE,
+          ...current,
+          state: "error",
+          error: `SOFTAP_NETWORK_LOST: ${error.message}`,
+          softap: transport.progress(),
+          recovery: {
+            active: false,
+            generation: transport.currentMediaGeneration(),
+            deadlineAt: attempt.recoveryDeadlineAt ?? undefined,
+            phase: transport.currentPhase(),
+          },
+        })
+      } finally {
+        attempt.recoveryActive = false
+        if (attempt.recovery === run) attempt.recovery = null
+      }
+    })()
+    attempt.recovery = run
+  }
+
+  /**
+   * Wait for a link the hotspot commands can actually use.
+   *
+   * The hotspot goes away a couple of seconds before the phone declares the BLE link dead, so the
+   * snapshot at loss time still reads "ready". Taking that at face value sent `set_hotspot_state`
+   * into a dying link twice, and each one burned its full timeout before the wearer was even back.
+   * Requiring the link to hold steady turns that into waiting, which is what the budget is for.
+   */
+  private async waitForGlassesReturn(timeoutMs: number, cancelled: () => boolean): Promise<boolean> {
+    const deadlineAt = Date.now() + timeoutMs
+    while (!cancelled()) {
+      const remaining = deadlineAt - Date.now()
+      if (remaining <= 0) return false
+      if (!isGlassesReady(useGlassesStore.getState().connection) && !(await this.awaitGlassesReady(remaining, cancelled))) {
+        return false
+      }
+      const settleMs = Math.min(GLASSES_LINK_SETTLE_MS, Math.max(0, deadlineAt - Date.now()))
+      if (await this.glassesLinkHoldsSteady(settleMs, cancelled)) return true
+    }
+    return false
+  }
+
+  private awaitGlassesReady(timeoutMs: number, cancelled: () => boolean): Promise<boolean> {
+    const controller = new AbortController()
+    const poll = setInterval(() => {
+      if (cancelled()) controller.abort()
+    }, 250)
+    return waitForGlassesReady({
+      getConnection: () => useGlassesStore.getState().connection,
+      subscribe: (listener) => useGlassesStore.subscribe((state) => state.connection, listener),
+      timeoutMs,
+      signal: controller.signal,
+    }).finally(() => clearInterval(poll))
+  }
+
+  /** True when the link stays ready for [ms]; false the moment it drops again. */
+  private glassesLinkHoldsSteady(ms: number, cancelled: () => boolean): Promise<boolean> {
+    if (ms <= 0) return Promise.resolve(isGlassesReady(useGlassesStore.getState().connection))
+    return new Promise<boolean>((resolve) => {
+      let done = false
+      const settle = (steady: boolean) => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        clearInterval(poll)
+        unsubscribe()
+        resolve(steady)
+      }
+      const unsubscribe = useGlassesStore.subscribe(
+        (state) => state.connection,
+        (connection) => {
+          if (!isGlassesReady(connection)) settle(false)
+        },
+      )
+      const poll = setInterval(() => {
+        if (cancelled()) settle(false)
+      }, 250)
+      const timer = setTimeout(() => settle(true), ms)
+    })
+  }
+
   /**
    * Cancels a SoftAP attempt and does not return until everything it owns has been released.
    *
@@ -4198,7 +4417,11 @@ class LocalMiniappRuntime {
           afterMs: SOFTAP_CLEANUP_STALL_LOG_MS,
         })
       }, SOFTAP_CLEANUP_STALL_LOG_MS)
-      void Promise.allSettled([attempt.teardown, attempt.body ?? Promise.resolve()]).then(() => {
+      void Promise.allSettled([
+        attempt.teardown,
+        attempt.body ?? Promise.resolve(),
+        attempt.recovery ?? Promise.resolve(),
+      ]).then(() => {
         clearTimeout(stallWatchdog)
         attempt.markSettled()
         if (this.softapAttempt === attempt) this.softapAttempt = null
@@ -4282,7 +4505,16 @@ class LocalMiniappRuntime {
       // so this is the caller's business, not a reason to block the next call.
       endFailure = await releaseStep("transport.stop", () => transport.stop(mode ? {mode} : {}))
       const undoFailures = transport.lastTeardownFailures()
-      if (undoFailures.length > 0) failures.push(`could not release ${undoFailures.join(", ")}`)
+      // A hotspot that did not ACK off is leftover ON — the next join wants it on and will
+      // call setHotspotState(true). Refusing that join is how we got hotspot_off_ack_timeout
+      // as a wearer-facing "power-cycle the glasses" dead end.
+      const blockingUndos = undoFailures.filter((step) => step !== "hotspot")
+      if (blockingUndos.length > 0) failures.push(`could not release ${blockingUndos.join(", ")}`)
+      if (undoFailures.includes("hotspot")) {
+        console.warn("[LocalMiniappRuntime] glasses hotspot undo timed out; next join will raise it again", {
+          attempt: attempt.id,
+        })
+      }
     }
     const scopedFailure = await releaseStep("leaveScopedNetwork", () => acsMeetingService.leaveScopedNetwork())
     if (scopedFailure) {
@@ -4384,11 +4616,30 @@ class LocalMiniappRuntime {
     if (endFailure) throw endFailure
   }
 
+  /**
+   * Send one hotspot command, re-sending it once if a session refresh cancelled it.
+   *
+   * The retry lives inside the unit chained onto [glassesHotspotCommand] rather than around it,
+   * which is what holds the invariant: one logical hotspot operation issues at most two native
+   * commands, and no later operation runs between them. A retry outside the queue would let an
+   * `on` land between the two halves of an `off` and leave the glasses in the opposite state.
+   *
+   * Re-sending is free because ASG compares against current state first and answers a same-state
+   * command with its current status instead of cycling the AP.
+   */
   private setGlassesHotspotState(enabled: boolean) {
-    const run = this.glassesHotspotCommand.then(
-      () => BluetoothSdk.setHotspotState(enabled),
-      () => BluetoothSdk.setHotspotState(enabled),
-    )
+    const send = async () => {
+      try {
+        return await BluetoothSdk.setHotspotState(enabled)
+      } catch (error) {
+        const code = (error as {code?: string} | null | undefined)?.code
+        if (!code || !HOTSPOT_SESSION_REFRESH_CODES.has(code)) throw error
+        softapTrace("softap_hotspot_session_retry", {enabled, code})
+        await new Promise<void>((resolve) => setTimeout(resolve, HOTSPOT_SESSION_RETRY_DELAY_MS))
+        return await BluetoothSdk.setHotspotState(enabled)
+      }
+    }
+    const run = this.glassesHotspotCommand.then(send, send)
     this.glassesHotspotCommand = run.then(
       () => undefined,
       () => undefined,
@@ -4406,9 +4657,9 @@ class LocalMiniappRuntime {
    * failure — the listener was still inside its 3s tombstone and the glasses AP was still up.
    *
    * A bound that expires is not success. It means the resource is still held by a call nobody is
-   * in any more, so it is taken by force and re-verified. Only if *that* fails does the next join
-   * get refused, which is a worse outcome than a slow teardown and a better one than two calls
-   * sharing a port.
+   * in any more, so it is taken by force and re-verified. An ingest port that is still held
+   * refuses the next join. A glasses hotspot that missed its off-ack does not — the next join
+   * wants the AP up and will raise it again.
    *
    * @returns failures to record; a non-empty list refuses the next join.
    */
@@ -4501,9 +4752,17 @@ class LocalMiniappRuntime {
           SOFTAP_HOTSPOT_OFF_ACK_MS,
           "hotspot_off_ack_timeout",
         )
-        if (status.state !== "disabled") failures.push(`the glasses hotspot is still ${status.state}`)
+        if (status.state !== "disabled") {
+          console.warn("[LocalMiniappRuntime] glasses hotspot still reported after disable; next join will raise it", {
+            attempt: attempt.id,
+            state: status.state,
+          })
+        }
       } catch (error) {
-        failures.push(`glasses hotspot off: ${error instanceof Error ? error.message : String(error)}`)
+        console.warn("[LocalMiniappRuntime] glasses hotspot off ack missed; next join will raise it", {
+          attempt: attempt.id,
+          reason: error instanceof Error ? error.message : String(error),
+        })
       }
     }
     softapTrace("softap_teardown_forced_done", {
@@ -5766,13 +6025,20 @@ class LocalMiniappRuntime {
     const toRemove: string[] = []
 
     for (const [packageName, app] of this.connectedApps) {
-      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
+      const holdPingLiveness = shouldHoldMiniappPingLiveness({
+        packageName,
+        softapPackageName: this.softapAttempt?.packageName,
+        softapCancelled: this.softapAttempt?.cancelled,
+      })
+      if (!holdPingLiveness) {
+        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
       }
-      app.unansweredPingRounds = liveness.unansweredPingRounds
 
       // Send PING — SDK auto-replies with PONG
       this.sendToMiniapp(packageName, {

package/src/services/MiniappLiveness.ts

@@ -3,6 +3,24 @@ export interface MiniappPingLivenessDecision {
   unansweredPingRounds: number
 }
 
+/**
+ * SoftAP join can spend a minute in native `prepareAgent` before the glasses
+ * hotspot even turns on. The JS bundle stays alive but may miss pongs while
+ * ACS is on the native thread. Unregistering for missed pings in that window
+ * cancels the join and leaves the UI stuck on the hotspot row.
+ */
+export function shouldHoldMiniappPingLiveness(args: {
+  packageName: string
+  softapPackageName?: string | null
+  softapCancelled?: boolean
+}): boolean {
+  return Boolean(
+    args.softapPackageName &&
+      args.softapPackageName === args.packageName &&
+      !args.softapCancelled,
+  )
+}
+
 /**
  * Advance liveness by one scheduled ping round.
  *