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

package/src/services/BlobStore.ts

@@ -97,22 +97,33 @@ interface ActiveReader {
 export class BlobStore {
   private readonly uploads = new Map<string, ActiveUpload>() // key: `${pkg} ${key}`
   private readonly readers = new Map<string, ActiveReader>() // key: host handle id
-  /** packageName → committed usage bytes, cached; invalidated on commit/delete/clear. */
+  /** user + package → committed usage bytes, cached; invalidated on commit/delete/clear. */
   private readonly usageCache = new Map<string, number>()
 
   constructor(private readonly hooks: BlobStoreHooks) {}
 
   // ---- path / meta helpers -------------------------------------------------
 
+  private currentIdentity(packageName: string): {userId: string; scope: string} {
+    const userId = this.hooks.getUserId().trim()
+    if (!userId) throw new Error("Mentra user identity is unavailable")
+    const scope = `${userId}\0${packageName}`
+    return {userId, scope}
+  }
+
   private dirFor(packageName: string): Directory {
-    const userId = sanitizeSegment(this.hooks.getUserId())
-    const dir = new Directory(Paths.document, ROOT_DIR_NAME, userId, sanitizeSegment(packageName))
+    const dir = new Directory(
+      Paths.document,
+      ROOT_DIR_NAME,
+      sanitizeSegment(this.currentIdentity(packageName).userId),
+      sanitizeSegment(packageName),
+    )
     if (!dir.exists) dir.create({intermediates: true})
     return dir
   }
 
   private metaPrefix(packageName: string): string {
-    return `${META_KEY_ROOT}${sanitizeSegment(this.hooks.getUserId())}_${packageName}_`
+    return `${META_KEY_ROOT}${sanitizeSegment(this.currentIdentity(packageName).userId)}_${packageName}_`
   }
 
   private metaKey(packageName: string, key: string): string {
@@ -163,17 +174,19 @@ export class BlobStore {
   }
 
   private committedUsage(packageName: string): number {
-    const cached = this.usageCache.get(packageName)
+    const {scope} = this.currentIdentity(packageName)
+    const cached = this.usageCache.get(scope)
     if (cached !== undefined) return cached
     let total = 0
     for (const m of this.allMeta(packageName)) total += m.bytes || 0
-    this.usageCache.set(packageName, total)
+    this.usageCache.set(scope, total)
     return total
   }
 
   private bumpUsage(packageName: string, delta: number): void {
-    const cur = this.usageCache.get(packageName)
-    if (cur !== undefined) this.usageCache.set(packageName, Math.max(0, cur + delta))
+    const {scope} = this.currentIdentity(packageName)
+    const cur = this.usageCache.get(scope)
+    if (cur !== undefined) this.usageCache.set(scope, Math.max(0, cur + delta))
   }
 
   private safeMd5(file: File, bytes: number): string | undefined {
@@ -509,7 +522,7 @@ export class BlobStore {
       } catch {
         /* best-effort */
       }
-      this.usageCache.set(packageName, 0)
+      this.usageCache.set(this.currentIdentity(packageName).scope, 0)
       this.hooks.sendResult(packageName, requestId, true)
     } catch (err) {
       this.fail(packageName, requestId, MiniappErrorCode.INTERNAL, err)

package/src/services/CloudAudioSubscriptionSync.ts

@@ -19,7 +19,19 @@ export class CloudAudioSubscriptionSync {
   private pendingKey = ""
 
   public begin(nextKey: string): boolean {
-    if (nextKey === this.lastAppliedKey || nextKey === this.pendingKey) {
+    // Exact duplicate of the write already in flight — nothing to do.
+    if (nextKey === this.pendingKey) {
+      return false
+    }
+    // Matches the last successfully applied set, but ONLY skip when nothing
+    // else is in flight. If a different write is pending (e.g. desired went
+    // fr-FR -> [] -> fr-FR while the [] write is still on the wire),
+    // lastAppliedKey is stale: it names what was applied BEFORE the in-flight
+    // write lands. Skipping here would drop the re-subscribe and strand the
+    // cloud on the intermediate (empty) set — captions silently die on any
+    // rapid A -> B -> A subscription churn. The cloud's own version counter
+    // resolves ordering between the concurrent writes, so sending both is safe.
+    if (nextKey === this.lastAppliedKey && this.pendingKey === "") {
       return false
     }
     this.pendingKey = nextKey

package/src/services/CloudClientService.ts

@@ -26,10 +26,12 @@ import {useSettingsStore, SETTINGS} from "../stores/settings"
 import {type CloudClientStatusSnapshot, type MiniappAuthToken} from "../runtime/config"
 import {createCloudUdpSocket} from "../utils/cloudClient/RnUdpAdapter"
 import {cloudSecureStore} from "../utils/cloudClient/cloudSecureStore"
+import {storage as mmkvStorage} from "../utils/storage"
 import {useCloudClientStatusStore} from "../stores/cloudClientStatus"
 import {islandNotifications} from "./NotificationsEmitter"
 import {BgTimer} from "../utils/timers"
 import {logCloudV2TranscriptMetric} from "./CloudTranscriptE2EMetrics"
+import {LocalMiniappUserIdentity} from "./LocalMiniappUserIdentity"
 import {nativeHttpResponseBody} from "./NativeHttpResponse"
 
 const LOG_TAG = "cloudClient"
@@ -40,6 +42,7 @@ type CloudCore = NonNullable<CloudClient["core"]>
 // been continuously NOT connected for this long. A quick reconnect cancels it; brief
 // flaps that recover don't fire. Raised as engine.notifications(connection_failed_persistent).
 const CLOUD_PERSISTENT_FAILURE_MS = 60_000
+const LOCAL_MINIAPP_USER_ID_KEY = "mentra.localMiniapp.userId"
 
 /** Cancel the pending persistent-failure alarm + re-arm for the next outage. */
 function clearPersistentFailureAlarm(): void {
@@ -75,6 +78,21 @@ let localDevRuntimeToken: {runtimeUrl: string; token: string; expiresAtMs: numbe
 let lc3FrameSizeUnsubscribe: (() => void) | null = null
 let coreTokenSyncPromise: Promise<string> | null = null
 
+const localMiniappUserIdentity = new LocalMiniappUserIdentity({
+  get(): string | null {
+    const result = mmkvStorage.load<string>(LOCAL_MINIAPP_USER_ID_KEY)
+    return result.is_ok() ? result.value : null
+  },
+  set(userId: string): void {
+    const result = mmkvStorage.save(LOCAL_MINIAPP_USER_ID_KEY, userId)
+    if (result.is_error()) throw result.error
+  },
+  remove(): void {
+    const result = mmkvStorage.remove(LOCAL_MINIAPP_USER_ID_KEY)
+    if (result.is_error()) throw result.error
+  },
+})
+
 const transcriptListeners = new Set<(d: TranscriptionData) => void>()
 const translationListeners = new Set<(d: TranslationData) => void>()
 const statusListeners = new Set<(snapshot: CloudClientStatusSnapshot) => void>()
@@ -114,6 +132,7 @@ async function syncCoreAccessTokenToBluetoothInternal(): Promise<string> {
   if (c !== client) {
     throw new Error("cloud client changed while syncing core token")
   }
+  localMiniappUserIdentity.remember(c.auth.identity.mentraUserId)
   const result = await useSettingsStore.getState().setSetting(SETTINGS.core_token.key, token, false)
   if (result.is_error()) {
     throw result.error
@@ -264,6 +283,13 @@ function ensureAuthWatch(): void {
   let reconnectPending = false
   try {
     const sub = auth.onStateChange((event, session) => {
+      if (event === "SIGNED_OUT") {
+        localMiniappUserIdentity.forget()
+        return
+      }
+      // A new sign-in may belong to a different account. Force the next
+      // storage request to resolve and persist that account's Core identity.
+      if (event === "SIGNED_IN") localMiniappUserIdentity.forget()
       if (!session?.token) return
       if (connected || reconnectPending) return
 
@@ -396,6 +422,12 @@ function construct(): void {
     // LC3 at 16 kHz with the frame size the encoder emits.
     audio: {codec: "lc3", sampleRate: 16000, frameSizeBytes: frameSizeBytes()},
     auth,
+    timers: {
+      setTimeout: (callback, delayMs) => BgTimer.setTimeout(callback, delayMs),
+      clearTimeout: (handle) => BgTimer.clearTimeout(handle as number),
+      setInterval: (callback, intervalMs) => BgTimer.setInterval(callback, intervalMs),
+      clearInterval: (handle) => BgTimer.clearInterval(handle as number),
+    },
     logger: cloudLogger,
   })
 
@@ -420,6 +452,7 @@ function construct(): void {
     if (c !== client) return
     connected = true
     console.log(`${LOG_TAG}: runtime connected`)
+    console.log(`${LOG_TAG}: debug: ws-session-debug connected`)
     // Cloud is up — cancel any pending persistent-failure alarm and re-arm for the
     // next outage.
     clearPersistentFailureAlarm()
@@ -436,6 +469,9 @@ function construct(): void {
     if (c !== client) return
     connected = false
     console.log(`${LOG_TAG}: runtime disconnected (${info.reason})`)
+    console.log(
+      `${LOG_TAG}: debug: ws-session-debug disconnected reason=${info.reason} willStayDown=${/superseded by newer session/i.test(info.reason)}`,
+    )
     // Arm the persistent-failure alarm once; if we're still down when it fires, raise
     // the notification. A reconnect within the window cancels it (onConnected above).
     if (!persistentFailureTimer && !persistentFailureNotified) {
@@ -518,6 +554,34 @@ export const cloudClientService = {
     return c.core.miniapps.getRegistry()
   },
 
+  /**
+   * Resolve the stable Core-owned Mentra user id.
+   *
+   * Storage must use this identity rather than the short-lived Core access
+   * token. A previously verified id is restored from MMKV so local miniapps
+   * remain available after an offline process restart. On first sign-in,
+   * callers join the auth module's single-flight exchange/refresh instead of
+   * falling back to an anonymous namespace.
+   */
+  async resolveMentraUserId(): Promise<string> {
+    return localMiniappUserIdentity.resolve(async () => {
+      if (!client) this.init()
+      const c = client
+      if (!c) throw new Error("cloud client not initialized")
+
+      await c.auth.getCoreToken()
+      if (c !== client) throw new Error("cloud client changed while resolving user identity")
+      return c.auth.identity.mentraUserId
+    })
+  },
+
+  /** Read the stable Mentra user id after async identity resolution. */
+  getMentraUserId(): string {
+    const userId = localMiniappUserIdentity.get()
+    if (!userId) throw new Error("Mentra user identity is unavailable")
+    return userId
+  },
+
   async getMiniappAuthToken(
     packageName: string,
     opts?: {minTtlMs?: number; devAttestation?: string},
@@ -549,6 +613,11 @@ export const cloudClientService = {
     clearPersistentFailureAlarm()
     const wasConnected = connected
     client = null
+    // stop() is part of the logout lifecycle and runs before the host emits
+    // SIGNED_OUT. Remove the persisted namespace owner here so a later account
+    // can never inherit it. A force-stop/process kill does not call stop(), so
+    // the cached id still survives the offline cold-start case.
+    localMiniappUserIdentity.forget()
     localDevRuntimeToken = null
     connected = false
     resetRuntimeStatus()
@@ -681,6 +750,11 @@ export const cloudClientService = {
         return getCoreClient().reports.complete(...args)
       },
     },
+    supportProfile: {
+      update(...args: Parameters<CloudCore["supportProfile"]["update"]>) {
+        return getCoreClient().supportProfile.update(...args)
+      },
+    },
   },
 
   hasAudioSubscriptions(): boolean {

package/src/services/ForegroundLocationPermission.ts

@@ -0,0 +1,24 @@
+export interface ForegroundLocationPermissionResponse {
+  status: string
+}
+
+export interface ForegroundLocationPermissionClient {
+  getForegroundPermissionsAsync(): Promise<ForegroundLocationPermissionResponse>
+  requestForegroundPermissionsAsync(): Promise<ForegroundLocationPermissionResponse>
+}
+
+/**
+ * Resolve foreground location permission without invoking an Activity-bound
+ * Android permission request while the app is backgrounded.
+ */
+export async function resolveForegroundLocationPermission(
+  client: ForegroundLocationPermissionClient,
+  getAppState: () => string,
+): Promise<ForegroundLocationPermissionResponse> {
+  const current = await client.getForegroundPermissionsAsync()
+  if (current.status === "granted" || getAppState() !== "active") {
+    return current
+  }
+
+  return client.requestForegroundPermissionsAsync()
+}

package/src/services/GlassesSettingsSync.ts

@@ -19,6 +19,7 @@ import {useSettingsStore, PAIRING_IDENTITY_KEYS} from "../stores/settings"
 import {useGlassesStore} from "../stores/glasses"
 import {createDebouncedPatchFlusher} from "../utils/debouncedPatch"
 import {isGlassesConnected} from "./GlassesReadiness"
+import micStateCoordinator from "./MicStateCoordinator"
 
 /**
  * Change-pushes are debounced (300ms) and merged so a burst of setSetting
@@ -28,7 +29,10 @@ import {isGlassesConnected} from "./GlassesReadiness"
 const flushBluetoothSettingsPatch = createDebouncedPatchFlusher<Record<string, unknown>>((patch) => {
   // Settings can change while the glasses are disconnected — a native
   // rejection must not surface as an unhandled promise rejection.
-  void Promise.resolve(BluetoothSdk.updateBluetoothSettings(patch)).catch((error) => {
+  // Apply mic overrides at flush time, not enqueue time: raw PCM can stop
+  // during the debounce window and a captured VAD=false would then be stale.
+  const runtimePatch = micStateCoordinator.applyRuntimeOverrides(patch)
+  void Promise.resolve(BluetoothSdk.updateBluetoothSettings(runtimePatch)).catch((error) => {
     console.warn("GlassesSettingsSync: updateBluetoothSettings failed:", error)
   })
 }, 300)
@@ -79,7 +83,8 @@ export async function pushAllBluetoothSettings(): Promise<void> {
   // Returns the native write promise so callers can await the seed before the
   // connect handshake replays settings to the glasses (otherwise the handshake
   // can race ahead and replay stale native settings).
-  await BluetoothSdk.updateBluetoothSettings(useSettingsStore.getState().getBluetoothSettings())
+  const settings = useSettingsStore.getState().getBluetoothSettings()
+  await BluetoothSdk.updateBluetoothSettings(micStateCoordinator.applyRuntimeOverrides(settings))
 }
 
 /**
@@ -91,7 +96,8 @@ export async function pushAllBluetoothSettings(): Promise<void> {
  * with pre-promotion empties (wiping the pairing it had just made).
  */
 export async function pushDeviceSettingsOnConnect(): Promise<void> {
-  await BluetoothSdk.updateBluetoothSettings(stripPairingIdentity(useSettingsStore.getState().getBluetoothSettings()))
+  const settings = stripPairingIdentity(useSettingsStore.getState().getBluetoothSettings())
+  await BluetoothSdk.updateBluetoothSettings(micStateCoordinator.applyRuntimeOverrides(settings))
 }
 
 export function startGlassesSettingsSync(): void {

package/src/services/GlassesStatusProjection.ts

@@ -12,21 +12,24 @@
  * Started by `engine.start()`. Idempotent.
  */
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import type {GlassesStatus} from "@mentra/bluetooth-sdk/internal"
 import {useCoreStore} from "../stores/core"
 import {useGlassesStore} from "../stores/glasses"
-import localMiniappRuntime from "./LocalMiniappRuntime"
 
 let unsubs: Array<() => void> = []
 let projectionRunId = 0
+let glassesStatusForwarder: ((status: Partial<GlassesStatus>) => void) | null = null
+let hydrationPromise: Promise<void> | null = null
 
-export function startGlassesStatusProjection(): void {
-  if (unsubs.length) return
+export function startGlassesStatusProjection(forwarder?: (status: Partial<GlassesStatus>) => void): Promise<void> {
+  if (forwarder) glassesStatusForwarder = forwarder
+  if (unsubs.length) return hydrationPromise ?? Promise.resolve()
 
   const runId = ++projectionRunId
   let bluetoothEventSeen = false
   let glassesEventSeen = false
 
-  void BluetoothSdk.getBluetoothStatus()
+  const bluetoothHydration = BluetoothSdk.getBluetoothStatus()
     .then((status) => {
       if (runId !== projectionRunId || bluetoothEventSeen) return
       useCoreStore.getState().setCoreInfo(status)
@@ -35,7 +38,7 @@ export function startGlassesStatusProjection(): void {
       console.warn("GlassesStatusProjection: getBluetoothStatus failed", error)
     })
 
-  void BluetoothSdk.getGlassesStatus()
+  const glassesHydration = BluetoothSdk.getGlassesStatus()
     .then((status) => {
       if (runId !== projectionRunId || glassesEventSeen) return
       useGlassesStore.getState().setGlassesInfo(status)
@@ -52,22 +55,27 @@ export function startGlassesStatusProjection(): void {
     }),
   )
 
-  // Glasses status -> glasses store (+ forward to local miniapps; clear any stale
-  // OTA-available flag on disconnect).
+  // Glasses status -> glasses store (+ optional full-runtime forwarding to local
+  // miniapps; clear any stale OTA-available flag on disconnect).
   unsubs.push(
     BluetoothSdk.onGlassesStatus((changed) => {
       glassesEventSeen = true
       useGlassesStore.getState().setGlassesInfo(changed)
-      localMiniappRuntime.forwardEvent("glasses_connection_state", changed)
+      glassesStatusForwarder?.(changed)
       if (changed.connection?.state === "disconnected") {
         useGlassesStore.getState().setOtaUpdateAvailable(null)
       }
     }),
   )
+
+  hydrationPromise = Promise.allSettled([bluetoothHydration, glassesHydration]).then(() => undefined)
+  return hydrationPromise
 }
 
 export function stopGlassesStatusProjection(): void {
   projectionRunId++
   unsubs.forEach((unsub) => unsub())
   unsubs = []
+  glassesStatusForwarder = null
+  hydrationPromise = null
 }

package/src/services/HotspotOtaTransport.ts

@@ -0,0 +1,184 @@
+import BluetoothSdk, {isEnabledHotspotStatus, MentraOtaServer} from "@mentra/bluetooth-sdk/internal"
+// One coordinator selects the native Android or iOS staging implementation at runtime.
+// eslint-disable-next-line react-native/split-platform-components
+import {PermissionsAndroid, Platform} from "react-native"
+import type {OtaCheckCurrentGlassesResult} from "./OtaUpdateCheckService"
+import {
+  cleanupArtifacts,
+  OtaArtifactError,
+  planArtifacts,
+  prepareArtifacts,
+  rewriteManifestForLocalServer,
+  type OtaArtifactDownloadProgress,
+  type PreparedOtaArtifact,
+} from "./OtaArtifactDownloader"
+import {disableHotspotWithRetry} from "./HotspotShutdown"
+import {localNetworkTransport} from "./asg/localNetworkTransport"
+
+export type HotspotOtaPhase = "idle" | "downloading" | "starting_hotspot" | "joining_hotspot" | "serving"
+
+export type HotspotOtaProgress = {
+  phase: HotspotOtaPhase
+  artifact?: OtaArtifactDownloadProgress
+}
+
+export type HotspotOtaErrorCode =
+  | "hotspot_wifi_permission_denied"
+  | "hotspot_start_failed"
+  | "hotspot_join_failed"
+  | "hotspot_server_failed"
+
+export class HotspotOtaTransportError extends Error {
+  constructor(
+    public readonly code: HotspotOtaErrorCode,
+    message: string,
+  ) {
+    super(message)
+    this.name = "HotspotOtaTransportError"
+  }
+}
+
+/** Owns the single phone-side endpoint and network lease for one hotspot OTA attempt. */
+class HotspotOtaTransport {
+  private active = false
+  private prepared: PreparedOtaArtifact[] = []
+  private hotspotRequested = false
+  private localNetworkConnected = false
+  private serverStarted = false
+  private teardownPromise: Promise<void> | null = null
+
+  async prepare(
+    checkResult: OtaCheckCurrentGlassesResult,
+    onProgress?: (progress: HotspotOtaProgress) => void,
+  ): Promise<string> {
+    if (this.teardownPromise) await this.teardownPromise
+    if (this.active) {
+      throw new Error("A hotspot OTA transport is already active")
+    }
+    if (!checkResult.manifestBody) {
+      throw new Error("The selected OTA check has no manifest body")
+    }
+
+    let phase: HotspotOtaPhase = "downloading"
+    try {
+      await this.ensureAndroidWifiPermission()
+      onProgress?.({phase: "downloading"})
+      this.prepared = await prepareArtifacts(
+        planArtifacts(checkResult),
+        (artifact) => onProgress?.({phase: "downloading", artifact}),
+        Platform.OS === "ios" ? this.downloadIosArtifact : undefined,
+      )
+
+      phase = "starting_hotspot"
+      onProgress?.({phase: "starting_hotspot"})
+      this.hotspotRequested = true
+      const hotspot = await BluetoothSdk.setHotspotState(true)
+      if (!isEnabledHotspotStatus(hotspot)) {
+        throw new HotspotOtaTransportError("hotspot_start_failed", "Mentra Live did not return hotspot credentials")
+      }
+      phase = "joining_hotspot"
+      onProgress?.({phase: "joining_hotspot"})
+      const scopedAddress = await localNetworkTransport.connect(hotspot.ssid, hotspot.password)
+      this.localNetworkConnected = true
+      let localAddress = scopedAddress
+      if (Platform.OS === "ios") {
+        try {
+          localAddress = await MentraOtaServer.waitForWifiAddress(hotspot.localIp, 15_000)
+        } catch (error) {
+          throw new HotspotOtaTransportError(
+            "hotspot_join_failed",
+            error instanceof Error ? error.message : String(error),
+          )
+        }
+      }
+      const artifactPaths = Object.fromEntries(this.prepared.map((artifact) => [artifact.sha256, artifact.filePath]))
+      // Start exactly one native listener to learn its selected port, then atomically replace
+      // the placeholder with the immutable rewritten manifest before ota_start is sent.
+      const server = await MentraOtaServer.startOtaServer("{}", artifactPaths, localAddress)
+      this.serverStarted = true
+      const manifest = rewriteManifestForLocalServer(checkResult.manifestBody, this.prepared, server.baseUrl)
+      const published = await MentraOtaServer.startOtaServer(manifest, artifactPaths, server.host)
+      if (published.manifestUrl !== server.manifestUrl) {
+        throw new Error("Local OTA server endpoint changed while publishing the manifest")
+      }
+      this.active = true
+      onProgress?.({phase: "serving"})
+      return published.manifestUrl
+    } catch (error) {
+      const joined = this.localNetworkConnected
+      await this.teardown()
+      if (error instanceof OtaArtifactError || error instanceof HotspotOtaTransportError) {
+        throw error
+      }
+      const message = error instanceof Error ? error.message : String(error)
+      if (phase === "starting_hotspot") {
+        throw new HotspotOtaTransportError("hotspot_start_failed", message)
+      }
+      if (phase === "joining_hotspot" && !joined) {
+        throw new HotspotOtaTransportError("hotspot_join_failed", message)
+      }
+      throw new HotspotOtaTransportError("hotspot_server_failed", message)
+    }
+  }
+
+  /** Android 13+ requires the nearby-WiFi runtime grant before WifiNetworkSpecifier is usable. */
+  private async ensureAndroidWifiPermission(): Promise<void> {
+    if (Platform.OS !== "android") return
+
+    const permission = PermissionsAndroid.PERMISSIONS.NEARBY_WIFI_DEVICES
+    if (await PermissionsAndroid.check(permission)) return
+    const result = await PermissionsAndroid.request(permission)
+    if (result !== PermissionsAndroid.RESULTS.GRANTED) {
+      throw new HotspotOtaTransportError(
+        "hotspot_wifi_permission_denied",
+        "Nearby devices permission is required to connect to the glasses hotspot",
+      )
+    }
+  }
+
+  private downloadIosArtifact = async (
+    entry: {url: string},
+    destination: string,
+    onProgress?: (bytesWritten: number, contentLength: number) => void,
+  ): Promise<{statusCode: number}> => {
+    const subscription = MentraOtaServer.addListener("artifactDownloadProgress", (event) => {
+      if (event.destination === destination) onProgress?.(event.bytesWritten, event.contentLength)
+    })
+    try {
+      return await MentraOtaServer.downloadArtifact(entry.url, destination)
+    } finally {
+      subscription.remove()
+    }
+  }
+
+  async teardown(): Promise<void> {
+    if (this.teardownPromise) return this.teardownPromise
+    this.teardownPromise = (async () => {
+      if (this.hotspotRequested) {
+        const hotspotStopped = await disableHotspotWithRetry(() => BluetoothSdk.setHotspotState(false), {
+          // A completed APK step has just replaced ASG. Let the new command path
+          // settle before asking it to tear down the SystemUI-owned access point.
+          initialDelayMs: this.serverStarted ? 750 : 0,
+        })
+        if (!hotspotStopped) {
+          console.warn("[OTA_PROGRESS] glasses hotspot shutdown was not confirmed after bounded retries")
+        }
+      }
+      if (this.serverStarted) await MentraOtaServer.stopOtaServer().catch(() => {})
+      if (this.localNetworkConnected) await localNetworkTransport.disconnect().catch(() => {})
+      await cleanupArtifacts().catch(() => {})
+      this.prepared = []
+      this.active = false
+      this.serverStarted = false
+      this.localNetworkConnected = false
+      this.hotspotRequested = false
+    })()
+    try {
+      await this.teardownPromise
+    } finally {
+      this.teardownPromise = null
+    }
+  }
+}
+
+export const hotspotOtaTransport = new HotspotOtaTransport()

package/src/services/HotspotShutdown.ts

@@ -0,0 +1,41 @@
+type HotspotState = {state: "disabled" | "enabled"}
+
+type HotspotShutdownOptions = {
+  attempts?: number
+  initialDelayMs?: number
+  retryDelayMs?: number
+  sleep?: (delayMs: number) => Promise<void>
+}
+
+const sleep = (delayMs: number) => new Promise<void>((resolve) => setTimeout(resolve, delayMs))
+
+/**
+ * Disable a glasses hotspot with a bounded retry. ASG APK replacement keeps the
+ * BLE link alive through BES, but the first command after the new ASG process
+ * appears can still land while its command path is settling.
+ */
+export async function disableHotspotWithRetry(
+  requestDisabled: () => Promise<HotspotState>,
+  options: HotspotShutdownOptions = {},
+): Promise<boolean> {
+  const attempts = Math.max(1, options.attempts ?? 2)
+  const initialDelayMs = Math.max(0, options.initialDelayMs ?? 0)
+  const retryDelayMs = Math.max(0, options.retryDelayMs ?? 500)
+  const wait = options.sleep ?? sleep
+
+  if (initialDelayMs > 0) await wait(initialDelayMs)
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      const status = await requestDisabled()
+      if (status.state === "disabled") return true
+    } catch {
+      // A lost command is indistinguishable from a response timeout here. Retry
+      // while the phone still owns the hotspot network and local server.
+    }
+
+    if (attempt < attempts && retryDelayMs > 0) await wait(retryDelayMs)
+  }
+
+  return false
+}