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

package/src/services/WifiAdbRequest.ts

@@ -0,0 +1,53 @@
+export interface WifiAdbRequestDependencies {
+  isSystemPackage: (packageName: string) => boolean
+  setWifiAdbState: (enabled: boolean) => Promise<void>
+}
+
+export type WifiAdbRequestErrorCode = "NOT_PERMITTED" | "INVALID_ARGUMENT" | "INTERNAL"
+
+export type WifiAdbRequestResult =
+  | {ok: true}
+  | {
+      ok: false
+      error: {code: WifiAdbRequestErrorCode; message: string}
+    }
+
+/** Apply the SYSTEM-only Wi-Fi ADB policy before calling the native SDK. */
+export async function handleWifiAdbRequest(
+  packageName: string,
+  payload: Record<string, unknown>,
+  dependencies: WifiAdbRequestDependencies,
+): Promise<WifiAdbRequestResult> {
+  if (!dependencies.isSystemPackage(packageName)) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_PERMITTED",
+        message: "setWifiAdbState is restricted to system apps",
+      },
+    }
+  }
+
+  if (typeof payload.enabled !== "boolean") {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_ARGUMENT",
+        message: "enabled must be a boolean",
+      },
+    }
+  }
+
+  try {
+    await dependencies.setWifiAdbState(payload.enabled)
+    return {ok: true}
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "INTERNAL",
+        message: error instanceof Error ? error.message : "Wi-Fi ADB error",
+      },
+    }
+  }
+}

package/src/services/asg/asgCameraApi.ts

@@ -1071,7 +1071,13 @@ export class AsgCameraApiClient {
     capture: CaptureGroup,
     onProgress?: (bytesDownloaded: number, totalBytes: number) => void,
     abortSignal?: AbortSignal,
-  ): Promise<{captureDir: string; primaryPath: string; bracketPaths: string[]; sidecarPath?: string}> {
+  ): Promise<{
+    captureDir: string
+    primaryPath: string
+    bracketPaths: string[]
+    sidecarPath?: string
+    thumbnailPath?: string
+  }> {
     if (capture.files.some((file) => !file.size || file.size <= 0)) {
       // Preserve support for malformed manifests from pre-v2 development firmware.
       return this.downloadCaptureLegacyUnsafe(capture, onProgress, abortSignal)
@@ -1136,9 +1142,14 @@ export class AsgCameraApiClient {
         const leafName = sortedFiles[0].name.includes("/") ? sortedFiles[0].name.split("/").pop()! : sortedFiles[0].name
         primaryPath = `${captureDir}/${leafName}`
       }
+      const primaryFile = sortedFiles.find((file) => file.role === "primary") || sortedFiles[0]
+      const thumbnailPath =
+        capture.type === "video" && primaryFile
+          ? await this.downloadVideoThumbnail(primaryFile.name, `${captureDir}/.thumb.jpg`, abortSignal)
+          : undefined
       galleryTransferLedger.transition(capture.capture_id, "VERIFIED")
       onProgress?.(capture.total_size, capture.total_size)
-      return {captureDir, primaryPath, bracketPaths, sidecarPath}
+      return {captureDir, primaryPath, bracketPaths, sidecarPath, thumbnailPath}
     } catch (error) {
       galleryTransferLedger.recordFailure(capture.capture_id, error)
       throw error
@@ -1150,7 +1161,13 @@ export class AsgCameraApiClient {
     capture: CaptureGroup,
     onProgress?: (bytesDownloaded: number, totalBytes: number) => void,
     abortSignal?: AbortSignal,
-  ): Promise<{captureDir: string; primaryPath: string; bracketPaths: string[]; sidecarPath?: string}> {
+  ): Promise<{
+    captureDir: string
+    primaryPath: string
+    bracketPaths: string[]
+    sidecarPath?: string
+    thumbnailPath?: string
+  }> {
     const captureDir = localStorageService.getPhotoFilePath(capture.capture_id)
     console.log(
       `[ASG Camera API] downloadCapture: ${capture.capture_id} (${capture.files.length} files) -> ${captureDir}`,
@@ -1300,7 +1317,76 @@ export class AsgCameraApiClient {
       onProgress(totalBytes, totalBytes)
     }
 
-    return {captureDir, primaryPath, bracketPaths, sidecarPath}
+    const primaryFile = sortedFiles.find((file) => file.role === "primary") || sortedFiles[0]
+    const thumbnailPath =
+      capture.type === "video" && primaryFile
+        ? await this.downloadVideoThumbnail(primaryFile.name, `${captureDir}/.thumb.jpg`, abortSignal)
+        : undefined
+
+    return {captureDir, primaryPath, bracketPaths, sidecarPath, thumbnailPath}
+  }
+
+  /** Download an on-demand video thumbnail while the source capture is still on the glasses. */
+  private async downloadVideoThumbnail(
+    sourceFileName: string,
+    thumbnailPath: string,
+    abortSignal?: AbortSignal,
+  ): Promise<string | undefined> {
+    const partialPath = `${thumbnailPath}.partial`
+    const parentDir = thumbnailPath.substring(0, thumbnailPath.lastIndexOf("/"))
+
+    try {
+      if (parentDir && !(await RNFS.exists(parentDir))) {
+        await RNFS.mkdir(parentDir)
+      }
+      await RNFS.unlink(partialPath).catch(() => {})
+      const {jobId, promise} = localNetworkTransport.downloadFile({
+        fromUrl: `${this.baseUrl}/api/photo?file=${encodeURIComponent(sourceFileName)}`,
+        toFile: partialPath,
+        headers: {
+          "Accept": "image/jpeg",
+          "User-Agent": "MentraOS-Mobile/1.0",
+        },
+        connectionTimeout: 60000,
+        readTimeout: 60000,
+        progressDivider: 10,
+      })
+
+      let abortPollTimer: number | undefined
+      if (abortSignal) {
+        if (abortSignal.aborted) {
+          localNetworkTransport.stopDownload(jobId)
+          throw new Error("Sync cancelled")
+        }
+        abortPollTimer = BgTimer.setInterval(() => {
+          if (abortSignal.aborted) localNetworkTransport.stopDownload(jobId)
+        }, 500)
+      }
+
+      let result
+      try {
+        result = await promise
+      } finally {
+        if (abortPollTimer !== undefined) BgTimer.clearInterval(abortPollTimer)
+      }
+
+      if (abortSignal?.aborted) throw new Error("Sync cancelled")
+      if (result.statusCode !== 200 || result.bytesWritten <= 0) {
+        throw new Error(`HTTP ${result.statusCode}, ${result.bytesWritten} bytes`)
+      }
+
+      await RNFS.unlink(thumbnailPath).catch(() => {})
+      await RNFS.moveFile(partialPath, thumbnailPath)
+      console.log(`[ASG Camera API] Downloaded video thumbnail for ${sourceFileName}`)
+      return thumbnailPath
+    } catch (error) {
+      await RNFS.unlink(partialPath).catch(() => {})
+      if (abortSignal?.aborted || (error instanceof Error && error.message === "Sync cancelled")) {
+        throw new Error("Sync cancelled")
+      }
+      console.warn(`[ASG Camera API] Failed to download video thumbnail for ${sourceFileName}:`, error)
+      return undefined
+    }
   }
 
   /**
@@ -1421,15 +1507,20 @@ export class AsgCameraApiClient {
         mediaKind: isVideo ? "video" : "photo",
       })
       galleryTransferLedger.transition(captureId, "VERIFIED")
+      const thumbnailPath =
+        includeThumbnail && isVideo
+          ? await this.downloadVideoThumbnail(filename, localStorageService.getThumbnailFilePath(filename), abortSignal)
+          : undefined
       return {
         filePath: localFilePath,
+        thumbnailPath,
         mime_type: isVideo
           ? "video/mp4"
           : lowerName.endsWith(".png")
-          ? "image/png"
-          : lowerName.endsWith(".avif")
-          ? "image/avif"
-          : "image/jpeg",
+            ? "image/png"
+            : lowerName.endsWith(".avif")
+              ? "image/avif"
+              : "image/jpeg",
       }
     } catch (error) {
       galleryTransferLedger.recordFailure(captureId, error)

package/src/services/asg/gallerySyncService.ts

@@ -156,6 +156,10 @@ class GallerySyncService {
     }
 
     this.syncStartPromise = null
+    useGallerySyncStore.getState().setSyncStarting(false)
+    this.waitingForWifiRetry = false
+    this.wifiSettingsOpenedAt = null
+    this.startAborted = false
     this.isInitialized = false
     console.log("[GallerySyncService] Cleaned up")
   }
@@ -228,14 +232,23 @@ class GallerySyncService {
     if (!glassesConnected) {
       console.log("[GallerySyncService] Glasses disconnected - not retrying sync")
       this.waitingForWifiRetry = false
+      this.wifiSettingsOpenedAt = null
       return
     }
 
+    // The user has returned from the WiFi settings prompt, so the previous
+    // "Sync failed" state is no longer actionable. Make the button available
+    // immediately while the native WiFi state catches up; a successful check
+    // below will start the sync automatically.
+    if (store.syncState === "error" && store.lastError?.startsWith("WiFi disabled")) {
+      store.setSyncState("idle")
+    }
+
     // Check if WiFi is now enabled (Android only)
     // Use retry logic because WiFi status takes time to propagate after user enables it
     if (Platform.OS === "android") {
       const MAX_RETRIES = 5
-      const RETRY_DELAY_MS = 1000 // Wait 500ms between checks
+      const RETRY_DELAY_MS = 1000
 
       console.log("[GallerySyncService] Waiting for WiFi to initialize (may take a moment after enabling)...")
 
@@ -243,35 +256,28 @@ class GallerySyncService {
         try {
           await new Promise<void>((resolve) => BgTimer.setTimeout(() => resolve(), RETRY_DELAY_MS))
 
-          const netState = await NetInfo.fetch()
-          console.log(
-            `[GallerySyncService] WiFi check attempt ${attempt}/${MAX_RETRIES}: enabled=${netState.isWifiEnabled}`,
-          )
+          // NetInfo can remain stale after Android's WiFi settings close. Use
+          // the same native source as the normal sync preflight.
+          const wifiEnabled = await WifiManager.isEnabled()
+          console.log(`[GallerySyncService] WiFi check attempt ${attempt}/${MAX_RETRIES}: enabled=${wifiEnabled}`)
 
-          if (netState.isWifiEnabled === true) {
+          if (wifiEnabled) {
             console.log("[GallerySyncService] ✅ WiFi is now enabled - auto-retrying sync")
             this.waitingForWifiRetry = false
             this.wifiSettingsOpenedAt = null // Clear cooldown timestamp
-            // Clear previous error state
-            store.setSyncState("idle")
             // Auto-retry sync
             await this.startSync()
             return
           }
-
-          // If this was the last attempt, log and give up
-          if (attempt === MAX_RETRIES) {
-            console.log(
-              "[GallerySyncService] ❌ WiFi still disabled after all retries - user may need to tap sync manually",
-            )
-            this.waitingForWifiRetry = false
-            this.wifiSettingsOpenedAt = null // Clear cooldown timestamp
-          }
         } catch (error) {
           console.warn(`[GallerySyncService] Failed to check WiFi status on attempt ${attempt}:`, error)
           // Continue to next retry
         }
       }
+
+      console.log("[GallerySyncService] WiFi not detected after retries - leaving sync available for manual retry")
+      this.waitingForWifiRetry = false
+      this.wifiSettingsOpenedAt = null
     }
   }
 
@@ -378,8 +384,10 @@ class GallerySyncService {
       return this.syncStartPromise
     }
 
+    useGallerySyncStore.getState().setSyncStarting(true)
     this.syncStartPromise = this.runStartSync().finally(() => {
       this.syncStartPromise = null
+      useGallerySyncStore.getState().setSyncStarting(false)
     })
     return this.syncStartPromise
   }
@@ -1321,7 +1329,7 @@ class GallerySyncService {
       }
     }
     // Old firmware remains on the exact v2 endpoint/schema. Avoid expensive inline thumbnails;
-    // the UI can request them lazily after the primary transfer is safe.
+    // video thumbnails are fetched as small side downloads with their primary media.
     const syncResponse = await asgCameraApi.syncWithServer(clientId, lastSyncTime, false)
     const data = (syncResponse.data || syncResponse) as SyncManifestData
     if (data.captures) {
@@ -1915,6 +1923,7 @@ class GallerySyncService {
             bracketPaths: result.bracketPaths,
             sidecarPath: result.sidecarPath,
             thumbnailData: capture.thumbnail_data,
+            thumbnailPath: result.thumbnailPath,
             captureDir: result.captureDir,
             timestamp: capture.timestamp,
             totalSize: capture.total_size,
@@ -2251,7 +2260,7 @@ class GallerySyncService {
 
   /** True while pre-flight startSync work is in flight (before sync state transitions). */
   isSyncStarting(): boolean {
-    return this.syncStartPromise !== null
+    return useGallerySyncStore.getState().syncStarting
   }
 
   /**

package/src/services/asg/localNetworkTransport.ts

@@ -12,17 +12,12 @@ let nextJobId = 1_000_000
 const nativeJobs = new Map<number, string>()
 const cancelledNativeJobs = new Set<number>()
 
-export function shouldUseScopedLocalNetwork(
-  os: string,
-  platformVersion: number | string,
-  moduleAvailable: boolean,
-): boolean {
-  const level = typeof platformVersion === "number" ? platformVersion : Number.parseInt(platformVersion, 10)
-  return os === "android" && level >= 29 && moduleAvailable
+export function shouldUseScopedLocalNetwork(os: string, moduleAvailable: boolean): boolean {
+  return os === "android" && moduleAvailable
 }
 
 function supportsScopedConnection(): boolean {
-  return shouldUseScopedLocalNetwork(Platform.OS, Platform.Version, MentraLocalNetwork != null)
+  return shouldUseScopedLocalNetwork(Platform.OS, MentraLocalNetwork != null)
 }
 
 function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
@@ -46,15 +41,16 @@ export const localNetworkTransport = {
   supportsScopedConnection: (): boolean => supportsScopedConnection(),
   isScopedConnectionActive: (): boolean => scopedConnectionActive,
 
-  async connect(ssid: string, password: string): Promise<void> {
+  async connect(ssid: string, password: string): Promise<string | undefined> {
     scopedConnectionActive = false
     nativeJobs.clear()
     if (!supportsScopedConnection()) {
       await WifiManager.connectToProtectedSSID(ssid, password, false, false)
-      return
+      return undefined
     }
-    await MentraLocalNetwork!.connect(ssid, password)
+    const result = await MentraLocalNetwork!.connect(ssid, password)
     scopedConnectionActive = true
+    return result.localAddress
   },
 
   async disconnect(): Promise<void> {

package/src/services/audioPlaybackAssets.ts

@@ -0,0 +1,8 @@
+import type {AudioSource} from "expo-audio"
+
+/**
+ * A tiny bundled source used to detach completed or interrupted audio without
+ * destroying the reusable native player. If a media control later sends Play,
+ * only this silence can be resumed instead of the previous miniapp audio.
+ */
+export const SILENT_AUDIO_SOURCE: AudioSource = require("../assets/silence.wav")

package/src/services/glassesClockSync.ts

@@ -6,7 +6,7 @@ import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 import {BgTimer} from "../utils/timers"
 import {useGlassesStore} from "../stores/glasses"
 
-import {getAsgOtaVersionUrl} from "./asgOtaVersionUrl"
+import {resolveOtaManifestUrl} from "./otaManifestUrl"
 import {detectClockSkew} from "./gallerySyncClock"
 
 export const CLOCK_SETTLE_MS = 500
@@ -86,7 +86,7 @@ export async function handleOtaClockSkewFromGlasses(
 
       lastOtaClockFixAt = Date.now()
       const {buildNumber, otaVersionUrl} = useGlassesStore.getState()
-      const manifestUrl = getAsgOtaVersionUrl(otaVersionUrl, buildNumber)
+      const manifestUrl = resolveOtaManifestUrl(otaVersionUrl, buildNumber)
       console.log("[GlassesClockSync] ⏰ Restarting OTA with ota_start after clock fix")
       await BluetoothSdk.startOtaUpdate(manifestUrl)
       return true

package/src/services/manifestActions.ts

@@ -0,0 +1,30 @@
+import type {DeclaredAction} from "../types/applet"
+
+/**
+ * Normalize manifest actions defensively for installed and dev-sideloaded
+ * bundles. Input and output schemas are passed through as opaque JSON Schema.
+ */
+export function normalizeManifestActions(raw: unknown): DeclaredAction[] {
+  if (!Array.isArray(raw)) return []
+  const out: DeclaredAction[] = []
+  for (const a of raw as Array<{
+    id?: unknown
+    description?: unknown
+    parameters?: unknown
+    outputSchema?: unknown
+  }>) {
+    if (a && typeof a.id === "string" && typeof a.description === "string") {
+      out.push({
+        id: a.id,
+        description: a.description,
+        ...(a.parameters && typeof a.parameters === "object" && !Array.isArray(a.parameters)
+          ? {parameters: a.parameters as Record<string, unknown>}
+          : {}),
+        ...(a.outputSchema && typeof a.outputSchema === "object" && !Array.isArray(a.outputSchema)
+          ? {outputSchema: a.outputSchema as Record<string, unknown>}
+          : {}),
+      })
+    }
+  }
+  return out
+}

package/src/services/otaDisplayState.ts

@@ -18,38 +18,80 @@ export type DisplayState = "starting" | "updating" | "complete" | "failed" | "di
  *
  * Priority-ordered rules (first match wins):
  *   1. errorMsg !== ""                                          -> "failed"
- *   2. BES terminal + connected + sawReconnectEdge             -> "complete"
- *   3. BES terminal (any connection state)                     -> "restarting"
+ *   2. BES reboot recovery complete                             -> "complete"
+ *   3. BES reboot recovery awaiting reconnect                  -> "restarting"
+ *   4. BES terminal (any connection state)                     -> "restarting"
  *      (legacy-shaped BES "complete" counts only in install phase)
- *   4. apkCompletedViaBuildIncrease (legacy build-number port) -> "complete"
- *   5. otaStatus.status === "failed"                           -> "failed"
- *   6. otaStatus.status === "complete" (non-BES)               -> "complete"
+ *   6. apkCompletedViaBuildIncrease (legacy build-number port) -> "complete"
+ *   7. otaStatus.status === "failed"                           -> "failed"
+ *   8. otaStatus.status === "complete" (non-BES)               -> "complete"
  *      (unless legacy-shaped download-complete or held apk settle -> in flight)
- *   7. !connected + legacy in-flight complete (held apk)       -> "updating"
- *   8. !connected + APK step_complete with totalSteps > 1      -> "starting"   (expected reboot)
- *   9. !connected + BES in flight                              -> "restarting" (defensive)
- *   10. !connected                                             -> "disconnected"
- *   11. connected + in_progress | step_complete | legacy in-flight complete -> "updating"
- *   12. fallback                                               -> "starting"
+ *   9. !connected + legacy in-flight complete (held apk)       -> "updating"
+ *   10. !connected + APK step_complete with totalSteps > 1     -> "starting"   (expected reboot)
+ *   11. !connected + BES in flight                             -> "restarting" (defensive)
+ *   12. !connected                                             -> "disconnected"
+ *   13. connected + in_progress | step_complete | legacy in-flight complete -> "updating"
+ *   14. fallback                                               -> "starting"
  */
 export function deriveDisplayState(args: {
   otaStatus: OtaStatus | null
   otaProgress: OtaProgress | null
   connected: boolean
   errorMsg: string
+  /**
+   * Retained for host API compatibility. A session-wide reconnect edge is not
+   * sufficient for BES completion because it may belong to an earlier APK step.
+   */
   sawReconnectEdge: boolean
   /** Coordinator is holding a legacy apk install "complete" for the settle window (WP 8C). */
   legacyApkSettleHold?: boolean
   /** Legacy APK completion detected by build-number increase (WP 8C). */
   apkCompletedViaBuildIncrease?: boolean
+  /** Phone-observed BES disconnect/reconnect recovery, independent of stale OTA progress. */
+  besRestartRecovery?: "awaiting" | "complete" | null
+  /** Downgrade detour: the reconnected glasses reported exactly the pinned target version. */
+  versionChangeConverged?: boolean
+  /** True for the whole downgrade (version-change) session. */
+  versionChangeSession?: boolean
 }): DisplayState {
-  const {otaStatus, otaProgress, connected, errorMsg, sawReconnectEdge, legacyApkSettleHold, apkCompletedViaBuildIncrease} =
-    args
+  const {
+    otaStatus,
+    otaProgress,
+    connected,
+    errorMsg,
+    legacyApkSettleHold,
+    apkCompletedViaBuildIncrease,
+    besRestartRecovery,
+    versionChangeConverged,
+    versionChangeSession,
+  } = args
 
   if (errorMsg) return "failed"
 
+  // Downgrade detour completion: exact-version convergence after reconnect is the
+  // only completion signal (the wipe destroys ASG's ota_session, and the target is
+  // a LOWER build so no build-number increase fires). Outranks the stale install
+  // status still sitting in the store from before the handoff.
+  if (versionChangeConverged) return "complete"
+
+  // A BES reboot destroys or strands the glasses-side OTA session on older
+  // clients. Once the phone observed that reboot, stale pre-reboot progress must
+  // not move the UI from restarting back to updating.
+  if (besRestartRecovery === "complete") return "complete"
+  if (besRestartRecovery === "awaiting") return "restarting"
+
+  // In a version-change session, convergence (above) is the ONLY completion for the ASG
+  // downgrade. A bare non-firmware "complete" before convergence — the glasses refusing
+  // the downgrade (floor/gate) with no install, or a stale pre-handoff status — must never
+  // present as success. Firmware-step completions (mtk/bes) DO pass through: a combined
+  // downgrade+firmware manifest applies firmware first on its own pass, which must finish
+  // so the phone re-checks and re-offers the now-firmware-free downgrade.
+  const isFirmwareComplete = otaStatus?.stepType === "mtk" || otaStatus?.stepType === "bes"
+  if (versionChangeSession && otaStatus?.status === "complete" && !isFirmwareComplete) {
+    return connected ? "updating" : "disconnected"
+  }
+
   const besTerminal = isBesTerminal(otaStatus, otaProgress)
-  if (besTerminal && connected && sawReconnectEdge) return "complete"
   if (besTerminal) return "restarting"
 
   // Legacy build-number APK completion: the coordinator clears errorMsg when it fires,
@@ -85,8 +127,7 @@ export function deriveDisplayState(args: {
     // has not started); the legacy screen treated that drop as a plain disconnect.
     const besStatusInFlight =
       otaStatus?.stepType === "bes" && !(isLegacyShapedOtaStatus(otaStatus) && otaStatus.phase === "download")
-    const besInFlight =
-      besStatusInFlight || (otaProgress?.currentUpdate === "bes" && otaProgress?.stage === "install")
+    const besInFlight = besStatusInFlight || (otaProgress?.currentUpdate === "bes" && otaProgress?.stage === "install")
     if (besInFlight) return "restarting"
 
     return "disconnected"

package/src/services/otaInstallPolicy.ts

@@ -10,6 +10,7 @@ import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
 export const MINIMUM_OTA_STATUS_BUILD = 37
 
 export const MAX_RETRIES = 3
+/** Wait between ended native ota_start requests; never overlaps a pending request. */
 export const RETRY_INTERVAL_MS = 5000
 /** APK/BES and general install when progress events are expected */
 export const PROGRESS_TIMEOUT_MS = 120_000
@@ -19,8 +20,6 @@ export const DOWNLOAD_STUCK_TIMEOUT_MS = 70_000
 export const MTK_INSTALL_TIMEOUT_MS = 300_000
 /** Whole multi-step session cap */
 export const GLOBAL_OTA_TIMEOUT_MS = 20 * 60 * 1000
-/** After APK reboot, ASG OTA service needs time before next ota_start */
-export const POST_APK_OTA_START_DELAY_MS = 6000
 /** BLE keepalive during OTA */
 export const PING_INTERVAL_MS = 10_000
 /**
@@ -71,6 +70,8 @@ export const LEGACY_MTK_STALL_ZONE_MAX_PERCENT = 55
 export const LEGACY_MTK_SIM_FLOOR_PERCENT = 51
 export const LEGACY_MTK_SIM_CAP_PERCENT = 60
 
+export type OtaProtocolProfile = "legacy" | "unified"
+
 /**
  * Legacy-shaped ota_status: old (< 37) ASG builds send `ota_progress`, which the SDK
  * (Android MentraLive.kt / iOS MentraLive.swift) maps to a unified ota_status with
@@ -98,9 +99,34 @@ export function isLegacyShapedOtaSession(
   return Number.isFinite(build) && build > 0 && build < MINIMUM_OTA_STATUS_BUILD
 }
 
+/**
+ * Select the compatibility profile once at install-screen attach. The old split
+ * routes made this decision from the pre-update build and kept it for the whole
+ * mounted flow, even when an APK step restarted into a newer ASG build. Returning
+ * null leaves the coordinator undecided until the first meaningful OTA event.
+ */
+export function selectOtaProtocolProfile(
+  otaStatus: OtaStatus | null,
+  otaProgress: OtaProgress | null,
+  buildNumber: string | null | undefined,
+): OtaProtocolProfile | null {
+  const build = Number.parseInt(buildNumber ?? "", 10)
+  if (Number.isFinite(build) && build > 0) {
+    return build < MINIMUM_OTA_STATUS_BUILD ? "legacy" : "unified"
+  }
+  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus) ? "legacy" : "unified"
+  if (otaProgress) return "legacy"
+  return null
+}
+
 export const OtaProgressMessages = {
-  noAckResponse: "Unable to start update. Glasses did not respond.",
   stalledOrStuck: "Update may have failed. Ensure glasses have internet access and try again.",
   globalTimeout: "Update took too long. Please try again.",
   sendOtaStartFailed: "Failed to communicate with glasses.",
+  hotspotArtifactDownloadFailed: "Could not download the update to your phone. Check phone internet and try again.",
+  hotspotArtifactVerifyFailed: "The update package could not be verified. Please try again later.",
+  hotspotWifiPermissionDenied: "Allow nearby devices access so the phone can connect to the glasses hotspot.",
+  hotspotStartFailed: "Could not start the glasses hotspot. Please try again.",
+  hotspotJoinFailed: "Could not connect the phone to the glasses hotspot. Please try again.",
+  hotspotServerFailed: "Could not make the update available to the glasses. Please try again.",
 } as const

package/src/services/{asgOtaVersionUrl.ts → otaManifestUrl.ts}

@@ -1,6 +1,13 @@
+import {sdkPinnedOtaManifestUrl} from "@mentra/bluetooth-sdk/internal"
+
 import {SETTINGS, useSettingsStore} from "../stores/settings"
 
-const OTA_VERSION_URL_PROD = "https://ota.mentraglass.com/prod_live_version.json"
+// Legacy production manifest — pre-39 glasses install from this (they ignore ota_start's URL).
+const OTA_VERSION_URL_LEGACY_PROD = "https://ota.mentraglass.com/prod_live_version.json"
+// Modern production fleet manifest (v2). Only a last-resort fallback when the SDK-derived pin
+// URL is somehow unavailable; modern glasses honor ota_start's URL, so this must be the v2
+// artifact, not the legacy v1 rescue manifest.
+const OTA_VERSION_URL_PROD = "https://ota.mentraglass.com/prod_live_version_v2.json"
 
 function isLegacyAsgOtaStartBuild(glassesBuildNumber?: string | null): boolean {
   const buildNumber = Number.parseInt(glassesBuildNumber ?? "", 10)
@@ -20,12 +27,12 @@ function getOtaVersionUrlDevOverride(): string | null {
   return trimmed || null
 }
 
-export function getAsgOtaVersionUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string {
+export function resolveOtaManifestUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string {
   const deviceUrl = glassesUrl?.trim()
   if (isLegacyAsgOtaStartBuild(glassesBuildNumber)) {
     // Legacy glasses ignore ota_start.ota_version_url and install from their
     // compiled default, so the developer override does not apply to them either.
-    return deviceUrl || OTA_VERSION_URL_PROD
+    return deviceUrl || OTA_VERSION_URL_LEGACY_PROD
   }
 
   const devOverrideUrl = getOtaVersionUrlDevOverride()
@@ -37,5 +44,10 @@ export function getAsgOtaVersionUrl(glassesUrl?: string | null, glassesBuildNumb
   if (envUrl) {
     return envUrl
   }
-  return deviceUrl || OTA_VERSION_URL_PROD
+
+  // The phone owns manifest selection: modern glasses are driven with the manifest pinned to
+  // this app's Bluetooth SDK version. Modern ASG builds report no manifest URL of their own;
+  // a glasses-reported URL (older modern builds advertising their baked fleet default) is only
+  // a last resort when the SDK version is somehow unavailable.
+  return sdkPinnedOtaManifestUrl() || deviceUrl || OTA_VERSION_URL_PROD
 }