@mentra/engine 0.1.0-dev.0 → 3.1.0-dev.10

package/src/services/asg/mediaProcessingQueue.ts

@@ -14,7 +14,8 @@ import {INVALID_DOWNLOADED_MEDIA, validateDownloadedMediaFile} from "./galleryMe
 import {reportInvalidGalleryMedia} from "./GalleryMediaIntegrityReportService"
 import {useGallerySyncStore} from "../../stores/gallerySync"
 import {BgTimer} from "../../utils/timers"
-import {MediaLibraryPermissions} from "../../utils/permissions/MediaLibraryPermissions"
+import {galleryTransferLedger, GalleryTransferEntry} from "./galleryTransferLedger"
+import {cameraRollExportCoordinator} from "./cameraRollExportCoordinator"
 
 const TAG = "[MediaProcessingQueue]"
 
@@ -48,6 +49,8 @@ export interface ProcessingItem {
   thumbnailPath?: string
   /** File names to delete from glasses after processing completes */
   deleteFromGlasses?: string[]
+  /** Negotiated gallery protocol; absent entries are inferred from the transfer ledger. */
+  protocolVersion?: number
 }
 
 class MediaProcessingQueue {
@@ -93,7 +96,7 @@ class MediaProcessingQueue {
   }
 
   /** Returns a promise that resolves when the queue is fully drained, or rejects on timeout. */
-  waitUntilDrained(timeoutMs: number = 600000): Promise<void> {
+  waitUntilDrained(timeoutMs: number = 4 * 60 * 60 * 1000): Promise<void> {
     if (!this.hasPending) return Promise.resolve()
     return new Promise((resolve, reject) => {
       const deadline = Date.now() + timeoutMs
@@ -112,6 +115,71 @@ class MediaProcessingQueue {
     })
   }
 
+  /** Retry durable export/ack work after an app restart without downloading media again. */
+  async retryPending(): Promise<{retried: number; failed: number}> {
+    let retried = 0
+    let failed = 0
+    for (let entry of galleryTransferLedger.pendingRecovery()) {
+      try {
+        if (entry.state === "RESTORE_PENDING") {
+          await asgCameraApi.restoreCapture(entry.captureId)
+          galleryTransferLedger.transition(entry.captureId, "DISCOVERED", {lastError: undefined})
+          retried++
+          continue
+        }
+        if (!entry.finalPath || !(await RNFS.exists(entry.finalPath))) {
+          throw new Error(`Recovery file is missing for ${entry.captureId}`)
+        }
+        // Rebuild a missing app index before any source acknowledgement, even when camera-roll
+        // saving is disabled or an export receipt was already committed before restart.
+        const downloadedFile = await this.recoverDownloadedFile(entry)
+        if (entry.state === "EXPORT_PENDING" || entry.state === "INDEXED") {
+          const shouldAutoSave = await cameraRollExportCoordinator.isAutoSaveEnabled()
+          entry = galleryTransferLedger.update(entry.captureId, {shouldAutoSave, lastError: undefined})
+          if (shouldAutoSave) {
+            if (entry.state !== "EXPORT_PENDING") {
+              entry = galleryTransferLedger.transition(entry.captureId, "EXPORT_PENDING")
+            }
+            const receipt = await cameraRollExportCoordinator.exportForSource(downloadedFile, entry.captureId)
+            entry = receipt
+              ? galleryTransferLedger.transition(entry.captureId, "EXPORTED", {assetReceipt: receipt})
+              : galleryTransferLedger.transition(entry.captureId, "INDEXED", {
+                  shouldAutoSave: false,
+                  lastError: undefined,
+                })
+          } else if (entry.state === "EXPORT_PENDING") {
+            entry = galleryTransferLedger.transition(entry.captureId, "INDEXED", {
+              shouldAutoSave: false,
+              lastError: undefined,
+            })
+          }
+        }
+        entry = galleryTransferLedger.transition(entry.captureId, "ACK_PENDING")
+        await this.acknowledgeEntry(entry)
+        galleryTransferLedger.transition(entry.captureId, "TRASHED", {lastError: undefined})
+        retried++
+      } catch (error) {
+        galleryTransferLedger.recordFailure(entry.captureId, error)
+        failed++
+        console.warn(`${TAG} Recovery remains pending for ${entry.captureId}:`, error)
+      }
+    }
+    return {retried, failed}
+  }
+
+  private async acknowledgeEntry(entry: GalleryTransferEntry): Promise<void> {
+    if (entry.protocolVersion >= 3) {
+      await asgCameraApi.acknowledgeCapture(entry.captureId, entry.ackId)
+      return
+    }
+    const result = await asgCameraApi.deleteFilesFromServer(
+      entry.deleteFromGlasses.length > 0 ? entry.deleteFromGlasses : [entry.captureId],
+    )
+    if (result.failed.length > 0 || result.deleted.length === 0) {
+      throw new Error(`Glasses did not acknowledge ${entry.captureId}`)
+    }
+  }
+
   /** Process items one at a time. */
   private async processLoop(): Promise<void> {
     if (this.isRunning) return
@@ -126,6 +194,10 @@ class MediaProcessingQueue {
       } catch (error) {
         console.error(`${TAG} Error processing ${item.id}:`, error)
         processFailed = true
+        const store = useGallerySyncStore.getState()
+        if (!store.failedFiles.includes(item.id)) {
+          store.onFileFailed(item.id, error instanceof Error ? error.message : String(error))
+        }
       }
 
       // Exit if generation changed (reset was called during processing)
@@ -136,9 +208,8 @@ class MediaProcessingQueue {
         // Success: increment processedFiles and remove from processingFiles set.
         store.onFileProcessed(item.id)
       } else {
-        // Failure: processItem already called onFileFailed. Calling onFileProcessed
-        // here would double-count the item (counted as both failed AND processed).
-        // Still clear the processingFiles entry so the UI doesn't show it as in-progress.
+        // Failure is counted exactly once above. Still clear the processingFiles entry so the UI
+        // does not show it as in-progress.
         const current = store.processingFiles
         if (current.has(item.id)) {
           const newSet = new Set(current)
@@ -158,6 +229,23 @@ class MediaProcessingQueue {
   private async processItem(item: ProcessingItem): Promise<void> {
     const startTime = Date.now()
     let filePathToSave = item.primaryPath
+    let ledgerEntry = galleryTransferLedger.get(item.id)
+    if (!ledgerEntry) {
+      ledgerEntry = galleryTransferLedger.ensureCapture(
+        {
+          capture_id: item.id,
+          type: item.type,
+          timestamp: item.timestamp || Date.now(),
+          total_size: item.totalSize,
+          files: (item.deleteFromGlasses?.length ? item.deleteFromGlasses : [item.id]).map((name, index) => ({
+            name,
+            size: index === 0 ? item.totalSize : 0,
+            role: index === 0 ? "primary" : "sidecar",
+          })),
+        },
+        item.protocolVersion || 2,
+      )
+    }
 
     // 1. HDR merge (photos with brackets only)
     if (item.shouldProcess && item.type === "photo" && item.bracketPaths && item.bracketPaths.length >= 3) {
@@ -231,9 +319,8 @@ class MediaProcessingQueue {
         mediaKind: item.type,
       })
     } catch (validationError: any) {
-      const reason =
-        validationError?.message?.includes(INVALID_DOWNLOADED_MEDIA) ?
-          validationError.message
+      const reason = validationError?.message?.includes(INVALID_DOWNLOADED_MEDIA)
+        ? validationError.message
         : `${INVALID_DOWNLOADED_MEDIA}: ${item.id}`
       console.error(`${TAG} Validation failed for ${item.id}: ${reason}`)
       reportInvalidGalleryMedia({
@@ -248,41 +335,23 @@ class MediaProcessingQueue {
       })
       const store = useGallerySyncStore.getState()
       store.onFileFailed(item.id, reason)
-      await RNFS.unlink(filePathToSave).catch(() => {})
-      for (const intermediate of [
-        item.primaryPath + ".hdr.jpg",
-        item.primaryPath + ".processed.jpg",
-        item.primaryPath + ".stabilized.mp4",
-      ]) {
-        if (intermediate !== filePathToSave) {
-          await RNFS.unlink(intermediate).catch(() => {})
-        }
-      }
+      galleryTransferLedger.recordFailure(item.id, validationError)
       throw new Error(reason)
     }
 
-    // 6. Save to camera roll
-    if (item.shouldAutoSave) {
-      const success = await MediaLibraryPermissions.saveToLibrary(filePathToSave, item.timestamp)
-      if (success) {
-        console.log(`${TAG} ✅ Saved to camera roll: ${item.id}`)
-      } else {
-        console.warn(`${TAG} ❌ Failed to save to camera roll: ${item.id}`)
-        // D1: Surface camera roll save failures to the UI
-        const store = useGallerySyncStore.getState()
-        store.onFileFailed(item.id, "camera roll save failed")
-      }
-    }
-
-    // 7. Save metadata
+    // 6. Commit the app-local index before any export or source acknowledgement. Use the final
+    // on-disk output metadata for camera-roll identity: processing can change byte size, while
+    // recovery reconstructs this row from the same file and the transfer ledger timestamp.
     const isVideo = item.type === "video"
+    const finalFileStat = await RNFS.stat(filePathToSave)
+    const finalFileSize = Number(finalFileStat.size)
     const downloadedFile = localStorageService.convertToDownloadedFile(
       {
         name: item.id,
         url: "",
         download: "",
-        size: item.totalSize,
-        modified: item.timestamp || Date.now(),
+        size: finalFileSize,
+        modified: ledgerEntry.timestamp,
         is_video: isVideo,
         thumbnail_data: item.thumbnailData,
         duration: item.duration,
@@ -293,15 +362,52 @@ class MediaProcessingQueue {
       localThumbnailPath,
       item.glassesModel,
     )
+    downloadedFile.capture_id = item.id
+    const shouldAutoSave = await cameraRollExportCoordinator.isAutoSaveEnabled()
     try {
       await localStorageService.saveDownloadedFile(downloadedFile)
+      ledgerEntry = galleryTransferLedger.transition(item.id, "INDEXED", {
+        finalPath: filePathToSave,
+        thumbnailPath: localThumbnailPath,
+        shouldAutoSave,
+      })
+      await cameraRollExportCoordinator.recordIndexed(
+        downloadedFile,
+        shouldAutoSave,
+        shouldAutoSave ? "SOURCE_BARRIER" : "HISTORICAL_BACKFILL",
+        item.id,
+      )
     } catch (metadataError) {
-      // D2: Clean up orphaned file if metadata save fails, then re-throw
-      console.error(`${TAG} Metadata save failed for ${item.id}, cleaning up file:`, metadataError)
-      await RNFS.unlink(filePathToSave).catch(() => {})
+      console.error(`${TAG} Metadata save failed for ${item.id}; retaining local and glasses copies:`, metadataError)
+      galleryTransferLedger.recordFailure(item.id, metadataError)
       throw metadataError
     }
 
+    // 7. While enabled, export is a durable, receipted step whose failures block ack. Turning
+    // auto-save off safely falls back to the already-verified app-local copy and later backfill.
+    if (shouldAutoSave) {
+      galleryTransferLedger.transition(item.id, "EXPORT_PENDING")
+      let receipt
+      try {
+        receipt = await cameraRollExportCoordinator.exportForSource(downloadedFile, item.id)
+      } catch (error) {
+        galleryTransferLedger.recordFailure(item.id, error)
+        throw error
+      }
+      if (receipt) {
+        ledgerEntry = galleryTransferLedger.transition(item.id, "EXPORTED", {
+          assetReceipt: receipt,
+        })
+        console.log(`${TAG} ✅ Saved to camera roll with receipt: ${item.id}`)
+      } else {
+        ledgerEntry = galleryTransferLedger.transition(item.id, "INDEXED", {
+          shouldAutoSave: false,
+          lastError: undefined,
+        })
+        console.log(`${TAG} Automatic camera-roll saving was disabled; keeping app-local copy: ${item.id}`)
+      }
+    }
+
     // S4: Clean up intermediate processing files
     const intermediates = [
       item.primaryPath + ".hdr.jpg",
@@ -326,8 +432,8 @@ class MediaProcessingQueue {
       name: item.id,
       url: localFileUrl,
       download: localFileUrl,
-      size: item.totalSize,
-      modified: item.timestamp || Date.now(),
+      size: finalFileSize,
+      modified: ledgerEntry.timestamp,
       is_video: isVideo,
       filePath: filePathToSave,
       mime_type: isVideo ? "video/mp4" : "image/jpeg",
@@ -336,35 +442,76 @@ class MediaProcessingQueue {
       duration: item.duration,
     })
 
-    // 9. Delete from glasses now that processing is complete — but only if the
-    // local file actually exists and has data. If the download was truncated or
-    // processing failed silently, we must not destroy the only good copy.
-    if (item.deleteFromGlasses && item.deleteFromGlasses.length > 0) {
+    // 9. Acknowledge only after VERIFIED -> INDEXED -> (EXPORTED). The server turns this into
+    // recoverable trash; failures remain ACK_PENDING and are retried without re-downloading.
+    const localFileExists = await RNFS.exists(filePathToSave)
+    const localStat = localFileExists ? await RNFS.stat(filePathToSave) : null
+    if (!localStat || localStat.size <= 0) {
+      const error = new Error(`Cannot acknowledge ${item.id}: committed local file is missing or empty`)
+      galleryTransferLedger.recordFailure(item.id, error)
+      throw error
+    }
+    ledgerEntry = galleryTransferLedger.transition(item.id, "ACK_PENDING")
+    try {
+      await this.acknowledgeEntry(ledgerEntry)
+      galleryTransferLedger.transition(item.id, "TRASHED", {lastError: undefined})
+    } catch (ackError) {
+      galleryTransferLedger.recordFailure(item.id, ackError)
+      throw ackError
+    }
+
+    const elapsed = Date.now() - startTime
+    console.log(`${TAG} ✅ Finished ${item.id} in ${elapsed}ms`)
+  }
+
+  /** Rebuild a missing app-local index row from the durable transfer ledger. */
+  private async recoverDownloadedFile(entry: GalleryTransferEntry) {
+    if (!entry.finalPath) throw new Error(`Recovery file is missing for ${entry.captureId}`)
+
+    // The transfer ledger is the durable source of truth for a committed generation. A local
+    // index row can survive an interrupted replacement and still point at an older/missing path,
+    // or contain the pre-processing size. Only reuse it when its path and identity still match the
+    // ledger's committed file; otherwise rebuild the row before export or source acknowledgement.
+    const finalPath = entry.finalPath.replace(/^file:\/\//, "")
+    const indexed = await localStorageService.getDownloadedFile(entry.captureId)
+    if (indexed) {
       try {
-        const localFileExists = await RNFS.exists(filePathToSave)
-        if (!localFileExists) {
-          console.error(`${TAG} Skipping glasses deletion for ${item.id}: local file missing at ${filePathToSave}`)
-        } else {
-          const localStat = await RNFS.stat(filePathToSave)
-          if (localStat.size === 0) {
-            console.error(`${TAG} Skipping glasses deletion for ${item.id}: local file is 0 bytes`)
-          } else if (item.totalSize > 0 && localStat.size < item.totalSize * 0.5) {
-            // If local file is less than 50% of expected size, something went wrong
-            console.error(
-              `${TAG} Skipping glasses deletion for ${item.id}: local file ${localStat.size} bytes is much smaller than expected ${item.totalSize} bytes`,
-            )
-          } else {
-            await asgCameraApi.deleteFilesFromServer(item.deleteFromGlasses)
-            console.log(`${TAG} 🗑️ Deleted ${item.deleteFromGlasses.join(", ")} from glasses`)
+        const indexedPath = indexed.filePath?.replace(/^file:\/\//, "")
+        if (indexedPath === finalPath && (await RNFS.exists(indexedPath))) {
+          const indexedStat = await RNFS.stat(indexedPath)
+          const indexedSize = Number(indexedStat.size)
+          if (indexedSize > 0 && indexed.size === indexedSize && indexed.modified === entry.timestamp) {
+            return indexed
           }
         }
-      } catch (deleteError) {
-        console.warn(`${TAG} Delete from glasses failed for ${item.id} (non-fatal):`, deleteError)
+      } catch (error) {
+        console.warn(`${TAG} Ignoring stale local index for ${entry.captureId}:`, error)
       }
     }
 
-    const elapsed = Date.now() - startTime
-    console.log(`${TAG} ✅ Finished ${item.id} in ${elapsed}ms`)
+    const stat = await RNFS.stat(finalPath)
+    const finalSize = Number(stat.size)
+    if (!Number.isFinite(finalSize) || finalSize <= 0) {
+      throw new Error(`Recovery file is missing or empty for ${entry.captureId}`)
+    }
+    const recovered = localStorageService.convertToDownloadedFile(
+      {
+        name: entry.captureId,
+        url: "",
+        download: "",
+        size: finalSize,
+        modified: entry.timestamp,
+        mime_type: entry.captureType === "video" ? "video/mp4" : "image/jpeg",
+        is_video: entry.captureType === "video",
+        filePath: finalPath,
+      },
+      finalPath,
+      entry.thumbnailPath,
+    )
+    recovered.capture_id = entry.captureId
+    recovered.assetReceipt = entry.assetReceipt
+    await localStorageService.saveDownloadedFile(recovered)
+    return recovered
   }
 }
 

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

@@ -32,7 +32,7 @@ export function isSyncManifestEmpty(syncData: {
   captures?: unknown[]
   changed_files?: unknown[]
 }): boolean {
-  if (syncData.api_version === 2 && syncData.captures && syncData.captures.length > 0) {
+  if ((syncData.api_version || 0) >= 2 && syncData.captures && syncData.captures.length > 0) {
     return false
   }
   return !syncData.changed_files || syncData.changed_files.length === 0

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,11 @@ export async function handleOtaClockSkewFromGlasses(
 
       lastOtaClockFixAt = Date.now()
       const {buildNumber, otaVersionUrl} = useGlassesStore.getState()
-      const manifestUrl = getAsgOtaVersionUrl(otaVersionUrl, buildNumber)
+      const manifestUrl = resolveOtaManifestUrl(otaVersionUrl, buildNumber)
+      if (!manifestUrl) {
+        console.warn("[GlassesClockSync] OTA restart skipped because this build has no manifest pin")
+        return false
+      }
       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

@@ -1,4 +1,4 @@
-import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk"
 
 import {isLegacyShapedOtaStatus} from "./otaInstallPolicy"
 
@@ -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

@@ -1,5 +1,5 @@
 /** Shared OTA progress watchdog timings (see progress-legacy.tsx / progress.tsx). */
-import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk"
 
 /**
  * First glasses `build_number` (ASG `versionCode`) that uses `progress.tsx` with unified
@@ -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/otaLegacyMapping.ts

@@ -1,4 +1,4 @@
-import type {OtaProgress, OtaProgressStatus, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+import type {OtaProgress, OtaProgressStatus, OtaStatus} from "@mentra/bluetooth-sdk"
 
 /** Normalized ota_status fields (snake_case) after bridging Core/expo (snake or camel). */
 export type NormalizedOtaStatusEvent = {