@glassly/engine 0.1.0-dev.0

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/GlassesReadiness.ts

@@ -0,0 +1,103 @@
+/**
+ * GlassesReadiness — the canonical connection predicates plus a wait-for-booted
+ * primitive.
+ *
+ * The predicates ("connected / booted / busy") are the single app-facing home
+ * for connection readiness: the app, the Connection coordinator, and the
+ * Pairing coordinator all read them through engine rather than re-deriving the
+ * same checks in three places. They are defined here over the btsdk
+ * `GlassesConnectionStatus` type through the public Bluetooth SDK package
+ * boundary.
+ *
+ * waitForGlassesReady is the new primitive those coordinators build on:
+ * "resolve once the glasses report fully booted, or false on timeout". It is
+ * host-store-agnostic — callers inject a snapshot getter + a subscribe fn — so
+ * it is unit-testable without a live device.
+ */
+import {
+  isBusyGlassesConnectionStatus,
+  isConnectedGlassesConnectionStatus,
+  isReadyGlassesConnectionStatus,
+  type GlassesConnectionStatus,
+} from "@glassly/bluetooth-sdk/types"
+
+import {BgTimer} from "../utils/timers"
+
+export type {GlassesConnectionStatus}
+
+/** True when the BLE link is established (regardless of boot state). */
+export function isGlassesConnected(connection: GlassesConnectionStatus): boolean {
+  return isConnectedGlassesConnectionStatus(connection)
+}
+
+/** True when connected AND the glasses OS has finished booting. */
+export function isGlassesReady(connection: GlassesConnectionStatus): boolean {
+  return isReadyGlassesConnectionStatus(connection)
+}
+
+/** True while the native link layer is mid scan / connect / bond. */
+export function isGlassesLinkLayerBusy(connection: GlassesConnectionStatus): boolean {
+  return isBusyGlassesConnectionStatus(connection)
+}
+
+export interface WaitForGlassesReadyOptions {
+  /** Current connection snapshot. */
+  getConnection: () => GlassesConnectionStatus
+  /** Subscribe to connection changes; returns an unsubscribe fn. */
+  subscribe: (listener: (connection: GlassesConnectionStatus) => void) => () => void
+  /** Resolve false after this many ms if still not ready. Default 35s — the pairing boot budget. */
+  timeoutMs?: number
+  /** Abort the wait early (e.g. the screen unmounted). Tears down the subscription + timer; resolves false. */
+  signal?: AbortSignal
+}
+
+/**
+ * Resolves true once the glasses report fully booted, false on timeout, or
+ * false if the optional signal aborts. Resolves immediately when already ready.
+ * Always tears down its subscription, timer, and abort listener before resolving.
+ */
+export function waitForGlassesReady(options: WaitForGlassesReadyOptions): Promise<boolean> {
+  const {getConnection, subscribe, timeoutMs = 35_000, signal} = options
+  return new Promise<boolean>((resolve) => {
+    if (signal?.aborted) {
+      resolve(false)
+      return
+    }
+    if (isGlassesReady(getConnection())) {
+      resolve(true)
+      return
+    }
+
+    let settled = false
+    let timer: number | null = null
+    let unsubscribe: (() => void) | null = null
+    let onAbort: (() => void) | null = null
+
+    const finish = (value: boolean) => {
+      if (settled) return
+      settled = true
+      if (unsubscribe) unsubscribe()
+      if (timer !== null) BgTimer.clearTimeout(timer)
+      if (onAbort && signal) signal.removeEventListener("abort", onAbort)
+      resolve(value)
+    }
+
+    if (signal) {
+      onAbort = () => finish(false)
+      signal.addEventListener("abort", onAbort)
+    }
+
+    unsubscribe = subscribe((connection) => {
+      if (isGlassesReady(connection)) finish(true)
+    })
+
+    if (settled) {
+      // subscribe() notified synchronously with a ready state, so finish() ran
+      // before unsubscribe was assigned and couldn't tear the subscription down.
+      // Do it now (and don't arm a timer).
+      unsubscribe()
+    } else {
+      timer = BgTimer.setTimeout(() => finish(isGlassesReady(getConnection())), timeoutMs)
+    }
+  })
+}

package/src/services/GlassesSettingsSync.ts

@@ -0,0 +1,140 @@
+/**
+ * Glasses settings sync — engine-owned. Keeps the connected glasses in sync with
+ * the phone's device settings (`BLUETOOTH_SETTING_KEYS`) over the bluetooth-sdk, so
+ * `engine.glasses.settings.set()` (and any other settings-store write) reaches the
+ * device for ANY host — not just the first-party Glassly app, where this used to live
+ * in MantleManager.
+ *
+ * Two triggers:
+ *   1. on change — push the keys that changed.
+ *   2. on (re)connect — push the FULL set, so a freshly-connected device gets the
+ *      phone's current settings (not just future changes).
+ *
+ * Started by `engine.start()`. Idempotent.
+ */
+import {shallow} from "zustand/shallow"
+
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+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
+ * calls becomes ONE BLE write (wire v2 keeps BLE JSON small and infrequent).
+ * The full on-connect/seed pushes stay direct — callers await their ordering.
+ */
+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.
+  // 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)
+
+/**
+ * The changed-keys diff for the change-push, MINUS the pairing-identity keys.
+ * Identity is native-authoritative (promoted on pairing success, cleared on
+ * forget, echoed down via save_setting) and reaches native only through the
+ * explicit full seeds. Pushing identity from the change subscription would
+ * close a feedback loop: native echo → store setSetting → change-push →
+ * native apply → echo…, which self-sustains the moment two different values
+ * are in flight (e.g. a boot demotion crossing a native promotion) and flaps
+ * the pairing UI.
+ */
+export function diffBluetoothSettingsForPush(
+  settings: Record<string, unknown>,
+  previous: Record<string, unknown>,
+): Record<string, unknown> {
+  const changed: Record<string, unknown> = {}
+  for (const key in settings) {
+    if (PAIRING_IDENTITY_KEYS.includes(key)) continue
+    if (settings[key] !== previous[key]) changed[key] = settings[key]
+  }
+  return changed
+}
+
+/** A copy of the settings record without the pairing-identity keys. */
+export function stripPairingIdentity(settings: Record<string, unknown>): Record<string, unknown> {
+  const stripped: Record<string, unknown> = {}
+  for (const key in settings) {
+    if (PAIRING_IDENTITY_KEYS.includes(key)) continue
+    stripped[key] = settings[key]
+  }
+  return stripped
+}
+
+let unsubChange: (() => void) | null = null
+let unsubConnect: (() => void) | null = null
+
+/**
+ * Push the FULL current device-settings set — identity included — to native.
+ * This is the explicit identity SEED, for the flows where native genuinely
+ * needs the phone's persisted identity BEFORE it can act: the device-store
+ * hydration at start, the pre-connect seed (connectDefault targets the seeded
+ * identity), the post-demotion re-push, and the abandon re-seed.
+ */
+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).
+  const settings = useSettingsStore.getState().getBluetoothSettings()
+  await BluetoothSdk.updateBluetoothSettings(micStateCoordinator.applyRuntimeOverrides(settings))
+}
+
+/**
+ * Push the device-settings set MINUS the pairing identity. The on-connect
+ * replay uses this: while connected, NATIVE owns the identity (it promotes at
+ * device-ready and echoes down), and the JS snapshot can be mid-relay stale —
+ * on Mentra Live "connected" lands together with device-ready, and a full
+ * replay raced the promotion echoes and overwrote the just-promoted identity
+ * with pre-promotion empties (wiping the pairing it had just made).
+ */
+export async function pushDeviceSettingsOnConnect(): Promise<void> {
+  const settings = stripPairingIdentity(useSettingsStore.getState().getBluetoothSettings())
+  await BluetoothSdk.updateBluetoothSettings(micStateCoordinator.applyRuntimeOverrides(settings))
+}
+
+export function startGlassesSettingsSync(): void {
+  if (unsubChange || unsubConnect) return
+
+  // 1. Push only the keys that changed (matching the prior MantleManager sync).
+  // Pairing identity is excluded — see diffBluetoothSettingsForPush.
+  unsubChange = useSettingsStore.subscribe(
+    (state) => state.getBluetoothSettings(),
+    (settings: Record<string, unknown>, previous: Record<string, unknown>) => {
+      const changed = diffBluetoothSettingsForPush(settings, previous)
+      if (Object.keys(changed).length > 0) {
+        flushBluetoothSettingsPatch(changed)
+      }
+    },
+    {equalityFn: shallow},
+  )
+
+  // 2. Push the device settings whenever the glasses transition to connected —
+  // identity EXCLUDED: native owns the identity it just promoted, and a full
+  // replay here raced the promotion echoes (see pushDeviceSettingsOnConnect).
+  let wasConnected = isGlassesConnected(useGlassesStore.getState().connection)
+  unsubConnect = useGlassesStore.subscribe(() => {
+    const connected = isGlassesConnected(useGlassesStore.getState().connection)
+    if (connected && !wasConnected) {
+      // Background sync: log-and-continue if the device drops right after connect.
+      void pushDeviceSettingsOnConnect().catch((error) => {
+        console.warn("GlassesSettingsSync: on-connect settings push failed:", error)
+      })
+    }
+    wasConnected = connected
+  })
+}
+
+export function stopGlassesSettingsSync(): void {
+  unsubChange?.()
+  unsubConnect?.()
+  unsubChange = null
+  unsubConnect = null
+}

package/src/services/GlassesStatusProjection.ts

@@ -0,0 +1,73 @@
+/**
+ * Glasses status projection — engine-owned. Subscribes to the native bluetooth-sdk
+ * status events and projects them into the engine device stores, so engine's own
+ * services (which react to those stores) work for ANY host — not just the first-party
+ * Glassly app, where this used to live in MantleManager.
+ *
+ * This is the INBOUND mirror of GlassesSettingsSync: that pushes the settings store
+ * OUT to the device; this pulls device status IN to the stores. It's the feed that
+ * the rest of the engine runtime depends on (MicStateCoordinator, the settings-sync
+ * on-connect trigger, the facade read-models all read these stores).
+ *
+ * Started by `engine.start()`. Idempotent.
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import {useCoreStore} from "../stores/core"
+import {useGlassesStore} from "../stores/glasses"
+import localMiniappRuntime from "./LocalMiniappRuntime"
+
+let unsubs: Array<() => void> = []
+let projectionRunId = 0
+
+export function startGlassesStatusProjection(): void {
+  if (unsubs.length) return
+
+  const runId = ++projectionRunId
+  let bluetoothEventSeen = false
+  let glassesEventSeen = false
+
+  void BluetoothSdk.getBluetoothStatus()
+    .then((status) => {
+      if (runId !== projectionRunId || bluetoothEventSeen) return
+      useCoreStore.getState().setCoreInfo(status)
+    })
+    .catch((error) => {
+      console.warn("GlassesStatusProjection: getBluetoothStatus failed", error)
+    })
+
+  void BluetoothSdk.getGlassesStatus()
+    .then((status) => {
+      if (runId !== projectionRunId || glassesEventSeen) return
+      useGlassesStore.getState().setGlassesInfo(status)
+    })
+    .catch((error) => {
+      console.warn("GlassesStatusProjection: getGlassesStatus failed", error)
+    })
+
+  // Bluetooth-adapter status -> core store.
+  unsubs.push(
+    BluetoothSdk.onBluetoothStatus((changed) => {
+      bluetoothEventSeen = true
+      useCoreStore.getState().setCoreInfo(changed)
+    }),
+  )
+
+  // Glasses status -> glasses store (+ forward 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)
+      if (changed.connection?.state === "disconnected") {
+        useGlassesStore.getState().setOtaUpdateAvailable(null)
+      }
+    }),
+  )
+}
+
+export function stopGlassesStatusProjection(): void {
+  projectionRunId++
+  unsubs.forEach((unsub) => unsub())
+  unsubs = []
+}

package/src/services/HeadingService.ts

@@ -0,0 +1,122 @@
+/**
+ * HeadingService
+ *
+ * Thin singleton over the native compass stream exposed by `crust`.
+ * Works on both Android and iOS via CLLocationManager (iOS) / SensorManager (Android).
+ *
+ * Reference-counted: the underlying SensorManager subscription starts on
+ * the first listener and stops when the last one unsubscribes. Late
+ * subscribers get the most recently emitted heading replayed
+ * synchronously so the UI doesn't have to wait for the next sensor tick.
+ */
+
+import CrustModule from "@glassly/crust"
+
+const LOG_TAG = "HEADING_SERVICE"
+
+export type HeadingListener = (degrees: number) => void
+
+class HeadingService {
+  private static instance: HeadingService | null = null
+  private listeners = new Set<HeadingListener>()
+  private nativeSub: {remove: () => void} | null = null
+  private lastDegrees: number | null = null
+  private nativeStarted = false
+  /** While true, an external source (glasses magnetometer) owns the stream and phone-compass ticks are dropped. */
+  private externalSourceActive = false
+
+  private constructor() {}
+
+  public static getInstance(): HeadingService {
+    if (!HeadingService.instance) {
+      HeadingService.instance = new HeadingService()
+    }
+    return HeadingService.instance
+  }
+
+  /** While active, phone compass updates are suppressed in favor of pushExternalHeading(). */
+  public setExternalSourceActive(active: boolean): void {
+    if (this.externalSourceActive === active) return
+    this.externalSourceActive = active
+    console.log(`${LOG_TAG}: external heading source ${active ? "active" : "inactive"}`)
+  }
+
+  /** Fan an external heading (degrees 0…359) out to listeners; no-op unless the external source is active. */
+  public pushExternalHeading(degrees: number): void {
+    if (!this.externalSourceActive) return
+    if (!Number.isFinite(degrees)) return
+    this.lastDegrees = degrees
+    this.listeners.forEach((l) => {
+      try {
+        l(degrees)
+      } catch (err) {
+        console.error(`${LOG_TAG}: listener threw`, err)
+      }
+    })
+  }
+
+  public addListener(listener: HeadingListener): () => void {
+    this.listeners.add(listener)
+    if (!this.nativeStarted) {
+      this.startNative()
+    }
+    if (this.lastDegrees != null) {
+      try {
+        listener(this.lastDegrees)
+      } catch (err) {
+        console.error(`${LOG_TAG}: listener threw on replay`, err)
+      }
+    }
+    return () => {
+      this.listeners.delete(listener)
+      if (this.listeners.size === 0) {
+        this.stopNative()
+      }
+    }
+  }
+
+  private async startNative(): Promise<void> {
+    if (this.nativeStarted) return
+    this.nativeStarted = true
+    this.nativeSub = CrustModule.addListener("onHeading", (data) => {
+      if (this.externalSourceActive) return
+      const deg = Number(data.degrees)
+      if (!Number.isFinite(deg)) return
+      this.lastDegrees = deg
+      this.listeners.forEach((l) => {
+        try {
+          l(deg)
+        } catch (err) {
+          console.error(`${LOG_TAG}: listener threw`, err)
+        }
+      })
+    })
+    try {
+      const result = await CrustModule.startHeading()
+      if (!result.ok) {
+        console.warn(`${LOG_TAG}: startHeading failed — ${result.error}`)
+      } else {
+        console.log(`${LOG_TAG}: started`)
+      }
+    } catch (err) {
+      console.error(`${LOG_TAG}: startHeading threw`, err)
+    }
+  }
+
+  private async stopNative(): Promise<void> {
+    if (!this.nativeStarted) return
+    this.nativeStarted = false
+    this.nativeSub?.remove()
+    this.nativeSub = null
+    this.lastDegrees = null
+    try {
+      await CrustModule.stopHeading()
+      console.log(`${LOG_TAG}: stopped`)
+    } catch (err) {
+      console.error(`${LOG_TAG}: stopHeading threw`, err)
+    }
+  }
+}
+
+const headingService = HeadingService.getInstance()
+export default headingService

package/src/services/HotspotOtaTransport.ts

@@ -0,0 +1,184 @@
+import BluetoothSdk, {isEnabledHotspotStatus, OtaServer} from "@glassly/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 OtaServer.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 OtaServer.startOtaServer("{}", artifactPaths, localAddress)
+      this.serverStarted = true
+      const manifest = rewriteManifestForLocalServer(checkResult.manifestBody, this.prepared, server.baseUrl)
+      const published = await OtaServer.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 = OtaServer.addListener("artifactDownloadProgress", (event) => {
+      if (event.destination === destination) onProgress?.(event.bytesWritten, event.contentLength)
+    })
+    try {
+      return await OtaServer.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 OtaServer.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
+}