@mentra/engine 0.1.0-dev.1 → 3.1.0-beta.103

package/src/services/OtaUpdateCheckService.ts

@@ -1,9 +1,9 @@
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {OtaUpdateInfo} from "@mentra/bluetooth-sdk/internal"
+import BluetoothSdk, {type OtaUpdateInfo} from "@mentra/bluetooth-sdk"
+import {ENGINE_RELEASE_METADATA} from "../generated/releaseMetadata"
 import {getGlassesSystemTimeMs, isGlassesConnected, useGlassesStore, waitForGlassesState} from "../stores/glasses"
-import {SETTINGS, useSettingsStore} from "../stores/settings"
 import {maybeFixGlassesClockFromVersionInfo} from "./glassesClockSync"
-import {resolveOtaManifestUrl} from "./otaManifestUrl"
+import {hasConfiguredModernOtaManifestPin, resolveOtaManifestUrl} from "./otaManifestUrl"
+import {resolveOtaReleaseVersion} from "./otaReleaseVersion"
 
 /**
  * Phone-side mirror of ASG's `DOWNGRADE_FLOOR_VERSION_CODE`. Set to the versionCode of the first
@@ -39,6 +39,7 @@ export interface BesFirmware {
 }
 
 export interface VersionJson {
+  releaseVersion?: string
   apps?: {
     [packageName: string]: VersionInfo
   }
@@ -67,6 +68,8 @@ export interface OtaCheckResult {
    * instead of racing it with a second fetch of the same URL.
    */
   manifestBody: string | null
+  /** Coordinated release identity for the selected OTA pin. */
+  releaseVersion: string | null
   /**
    * Why the check failed, when it did. "network" is retryable (connection/server
    * trouble); "pin_unavailable" is permanent for this app build (manifest 404/gone,
@@ -107,6 +110,7 @@ function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurren
     besVersion: null,
     isApkDowngrade: false,
     manifestBody: null,
+    releaseVersion: null,
     updateInfo: null,
     isRequired: true,
     skippedReason,
@@ -123,20 +127,23 @@ async function fetchVersionInfoDetailed(url: string): Promise<ManifestFetchResul
   try {
     const response = await fetch(url)
     if (!response.ok) {
-      console.error("Failed to fetch version info:", response.status)
+      console.warn("Failed to fetch version info:", response.status)
       // 4xx: the manifest does not exist (or is gone) — permanent for this app
       // build, retrying cannot help. Everything else is transient server/network
       // trouble and retryable.
-      return {json: null, failureReason: response.status >= 400 && response.status < 500 ? "pin_unavailable" : "network"}
+      return {
+        json: null,
+        failureReason: response.status >= 400 && response.status < 500 ? "pin_unavailable" : "network",
+      }
     }
     try {
       return {json: await response.json()}
     } catch (parseError) {
-      console.error("OTA: manifest is not valid JSON:", parseError)
+      console.warn("OTA: manifest is not valid JSON:", parseError)
       return {json: null, failureReason: "pin_unavailable"}
     }
   } catch (error) {
-    console.error("OTA: Error fetching version info:", error)
+    console.warn("OTA: Error fetching version info:", error)
     return {json: null, failureReason: "network"}
   }
 }
@@ -194,12 +201,7 @@ export function getApkUpdateDirection(
   // Downgrades require an exact pin AND a target at/above the enabled floor. A non-positive floor
   // disables downgrades entirely, matching ASG's fail-closed DowngradeGate — so the phone never
   // offers what the glasses would refuse.
-  if (
-    serverVersion < currentVersion &&
-    exactPin &&
-    floorVersionCode > 0 &&
-    serverVersion >= floorVersionCode
-  ) {
+  if (serverVersion < currentVersion && exactPin && floorVersionCode > 0 && serverVersion >= floorVersionCode) {
     return "downgrade"
   }
   return null
@@ -301,6 +303,7 @@ export async function checkForOtaUpdate(
         besVersion: null,
         isApkDowngrade: false,
         manifestBody: null,
+        releaseVersion: null,
         checkFailureReason: fetched.failureReason ?? "network",
       }
     }
@@ -332,6 +335,7 @@ export async function checkForOtaUpdate(
         besVersion: null,
         isApkDowngrade: false,
         manifestBody: null,
+        releaseVersion: null,
         checkFailureReason: "pin_unavailable",
       }
     }
@@ -370,6 +374,12 @@ export async function checkForOtaUpdate(
       besVersion: versionJson?.bes_firmware?.version || null,
       isApkDowngrade: apkDirection === "downgrade",
       manifestBody: versionJson ? JSON.stringify(versionJson) : null,
+      releaseVersion: resolveOtaReleaseVersion({
+        manifestReleaseVersion: versionJson.releaseVersion,
+        manifestUrl: otaVersionUrl,
+        packagedManifestUrl: ENGINE_RELEASE_METADATA.otaManifestUrl,
+        packagedReleaseIdentity: ENGINE_RELEASE_METADATA.releaseIdentity,
+      }),
     }
   } catch (error) {
     console.error("Error checking for OTA update:", error)
@@ -382,6 +392,7 @@ export async function checkForOtaUpdate(
       besVersion: null,
       isApkDowngrade: false,
       manifestBody: null,
+      releaseVersion: null,
       checkFailureReason: "network",
     }
   }
@@ -403,22 +414,19 @@ export async function checkCurrentGlassesForUpdate(
     return emptyCheckResult("disconnected")
   }
 
-  const embeddedManifestUrl = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()
-  const superMode = useSettingsStore.getState().getSetting(SETTINGS.super_mode.key)
-  const overrideUrl = useSettingsStore.getState().getSetting(SETTINGS.ota_version_url.key)
-  const overrideActive = superMode && typeof overrideUrl === "string" && overrideUrl.trim() !== ""
-  if (!embeddedManifestUrl && !overrideActive) {
-    console.log("OTA: check skipped - mobile app has no embedded OTA manifest pin")
+  if (!hasConfiguredModernOtaManifestPin()) {
+    console.log("OTA: check skipped - this app or Engine package has no embedded OTA manifest pin")
     return emptyCheckResult("dev_build")
   }
-  if (!embeddedManifestUrl) {
-    console.log("OTA: no embedded manifest pin, but super-mode manifest override is active - checking anyway")
-  }
 
   if (refreshVersionInfo) {
-    void BluetoothSdk.requestVersionInfo().catch((error) => {
-      console.warn("OTA: Failed to request version_info from glasses:", error)
-    })
+    void BluetoothSdk.requestVersionInfo()
+      .then((versionInfo) => {
+        useGlassesStore.getState().setGlassesInfo(versionInfo)
+      })
+      .catch((error) => {
+        console.warn("OTA: Failed to request version_info from glasses:", error)
+      })
   }
 
   let buildNumber = useGlassesStore.getState().buildNumber
@@ -472,7 +480,17 @@ export async function checkCurrentGlassesForUpdate(
   }
 
   const manifestUrl = resolveOtaManifestUrl(useGlassesStore.getState().otaVersionUrl, buildNumber)
-  const result = await checkForOtaUpdate(manifestUrl, buildNumber, mtkFirmwareVersion, besFirmwareVersion, floorVersionCode)
+  if (!manifestUrl) {
+    console.log("OTA: check skipped - no OTA manifest pin resolved")
+    return emptyCheckResult("dev_build")
+  }
+  const result = await checkForOtaUpdate(
+    manifestUrl,
+    buildNumber,
+    mtkFirmwareVersion,
+    besFirmwareVersion,
+    floorVersionCode,
+  )
 
   if (!result.hasCheckCompleted) {
     return {

package/src/services/PhonePhotoCoordinator.ts

@@ -166,7 +166,7 @@ export class PhonePhotoCoordinator {
     // to time out. Fail fast with a typed error.
     //
     // We DON'T pre-check `hasCamera` here — the canonical capability data
-    // lives in `getModelCapabilities(deviceModel)` from @mentra/types and
+    // lives in `getModelCapabilities(deviceModel)` from @mentra/engine and
     // pulling that into this file would add a cross-package import. If a
     // cameraless device receives the BLE photo command, the glasses-side
     // handler will return a photo_response error within ~1s and the gated

package/src/services/PhoneStreamCoordinator.ts

@@ -813,12 +813,6 @@ export class PhoneStreamCoordinator {
       for (const reject of entry.hlsReadyRejecters) reject(pendingErr)
       entry.hlsReadyResolvers = []
       entry.hlsReadyRejecters = []
-      // Cloudflare DELETE is fire-and-forget — failing it doesn't undo the
-      // BLE stop we're about to do, and Cloudflare's idle-input scavenger
-      // will eventually clean up leaked inputs.
-      teardownManagedStream(entry.liveInputId).catch((err) => {
-        console.warn("[STREAM] teardownManagedStream failed:", err)
-      })
     }
 
     try {
@@ -833,6 +827,16 @@ export class PhoneStreamCoordinator {
       // Only clear if we're still the active entry (defensive — runExclusive
       // serializes us, so this should always be true).
       if (this.current === entry) this.current = null
+
+      if (entry.kind === "managed") {
+        // Start remote cleanup only after the publisher has stopped, but do not
+        // hold the local transition lock on an unbounded network request. The
+        // runtime's durable cleanup queue owns retries if this request fails or
+        // the app exits before Cloudflare finishes finalizing the recording.
+        void teardownManagedStream(entry.liveInputId).catch((err) => {
+          console.warn("[STREAM] teardownManagedStream failed:", err)
+        })
+      }
     }
   }
 }

package/src/services/StreamLifecycleController.ts

@@ -3,9 +3,9 @@
  * `setActive(true)` starts the timer; each tick sends a keep-alive with a
  * fresh ackId; `maxMissedAcks` consecutive timeouts fire `onTimeout`.
  *
- * Mirror of `cloud/packages/cloud/src/services/streaming/StreamLifecycleController.ts`
- * — kept byte-equivalent except for the `LifecycleLogger` interface (pino
- * isn't a phone dep). Behavior changes must land in both files.
+ * Phone-owned successor to the retired cloud stream lifecycle controller.
+ * It uses the local `LifecycleLogger` interface because pino is not a phone
+ * dependency.
  */
 
 export interface LifecycleLogger {

package/src/services/asg/localNetworkTransport.ts

@@ -1,5 +1,5 @@
 import * as RNFS from "@dr.pogodin/react-native-fs"
-import {MentraLocalNetwork, type LocalNetworkDownloadProgress} from "@mentra/bluetooth-sdk/internal"
+import {otaLocalNetwork, type OtaLocalNetworkDownloadProgress} from "@mentra/bluetooth-sdk/ota-transport"
 import {Buffer} from "buffer"
 import {Platform} from "react-native"
 import WifiManager from "react-native-wifi-reborn"
@@ -17,7 +17,7 @@ export function shouldUseScopedLocalNetwork(os: string, moduleAvailable: boolean
 }
 
 function supportsScopedConnection(): boolean {
-  return shouldUseScopedLocalNetwork(Platform.OS, MentraLocalNetwork != null)
+  return shouldUseScopedLocalNetwork(Platform.OS, otaLocalNetwork.isAvailable())
 }
 
 function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
@@ -48,25 +48,25 @@ export const localNetworkTransport = {
       await WifiManager.connectToProtectedSSID(ssid, password, false, false)
       return undefined
     }
-    const result = await MentraLocalNetwork!.connect(ssid, password)
+    const result = await otaLocalNetwork.connect(ssid, password)
     scopedConnectionActive = true
     return result.localAddress
   },
 
   async disconnect(): Promise<void> {
     if (supportsScopedConnection()) {
-      await MentraLocalNetwork!.disconnect().catch(() => {})
+      await otaLocalNetwork.disconnect().catch(() => {})
     }
     scopedConnectionActive = false
     nativeJobs.clear()
   },
 
   async fetch(url: string | URL | Request, init?: RequestInit, timeoutMs = 30_000): Promise<Response> {
-    if (!scopedConnectionActive || !MentraLocalNetwork || typeof url !== "string") {
+    if (!scopedConnectionActive || !otaLocalNetwork.isAvailable() || typeof url !== "string") {
       return globalThis.fetch(url, init)
     }
 
-    const nativeModule = MentraLocalNetwork
+    const nativeModule = otaLocalNetwork
     const id = requestId("request")
     const signal = init?.signal
     const cancel = () => void nativeModule.cancel(id)
@@ -92,13 +92,13 @@ export const localNetworkTransport = {
   },
 
   downloadFile(options: DownloadOptions): DownloadHandle {
-    if (!scopedConnectionActive || !MentraLocalNetwork) return RNFS.downloadFile(options)
+    if (!scopedConnectionActive || !otaLocalNetwork.isAvailable()) return RNFS.downloadFile(options)
 
     const jobId = nextJobId++
     const id = requestId("download")
     let began = false
     nativeJobs.set(jobId, id)
-    const subscription = MentraLocalNetwork.addListener("downloadProgress", (event: LocalNetworkDownloadProgress) => {
+    const subscription = otaLocalNetwork.onDownloadProgress((event: OtaLocalNetworkDownloadProgress) => {
       if (event.requestId !== id) return
       if (!began) {
         began = true
@@ -116,14 +116,15 @@ export const localNetworkTransport = {
       })
     })
 
-    const promise = MentraLocalNetwork.download(
-      id,
-      options.fromUrl,
-      options.toFile,
-      options.headers || {},
-      options.connectionTimeout || 30_000,
-      options.readTimeout || 30_000,
-    )
+    const promise = otaLocalNetwork
+      .download(
+        id,
+        options.fromUrl,
+        options.toFile,
+        options.headers || {},
+        options.connectionTimeout || 30_000,
+        options.readTimeout || 30_000,
+      )
       .then((result) => {
         if (!began) {
           options.begin?.({
@@ -154,16 +155,16 @@ export const localNetworkTransport = {
 
   stopDownload(jobId: number): void {
     const nativeId = nativeJobs.get(jobId)
-    if (nativeId && MentraLocalNetwork) {
+    if (nativeId && otaLocalNetwork.isAvailable()) {
       cancelledNativeJobs.add(jobId)
-      void MentraLocalNetwork.cancel(nativeId)
+      void otaLocalNetwork.cancel(nativeId)
       return
     }
     RNFS.stopDownload(jobId)
   },
 }
 
-MentraLocalNetwork?.addListener("networkLost", () => {
+otaLocalNetwork.onNetworkLost(() => {
   scopedConnectionActive = false
   nativeJobs.clear()
 })

package/src/services/glassesClockSync.ts

@@ -2,7 +2,7 @@
  * Push phone time to glasses only when clock skew is detected (gallery sync, OTA, etc.).
  */
 
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import BluetoothSdk from "@mentra/bluetooth-sdk"
 import {BgTimer} from "../utils/timers"
 import {useGlassesStore} from "../stores/glasses"
 
@@ -87,6 +87,10 @@ export async function handleOtaClockSkewFromGlasses(
       lastOtaClockFixAt = Date.now()
       const {buildNumber, otaVersionUrl} = useGlassesStore.getState()
       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/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"
 

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
@@ -32,6 +32,8 @@ export const PING_INTERVAL_MS = 10_000
 export const QUERY_REPLY_TIMEOUT_MS = 6000
 /** 15s lockout on the Continue button after a BES restart, to prevent an accidental tap. */
 export const BES_CONTINUE_LOCKOUT_MS = 15_000
+/** Fail closed if a BES reboot never reconnects; normal restarts complete in a fraction of this window. */
+export const BES_RESTART_TIMEOUT_MS = 120_000
 
 // --- Legacy old-build (< MINIMUM_OTA_STATUS_BUILD) OTA policy (WP 8C) ---
 //
@@ -51,6 +53,7 @@ export const LEGACY_MTK_INSTALL_TIMEOUT_MS = MTK_INSTALL_TIMEOUT_MS + LEGACY_EXT
 export const LEGACY_GLOBAL_OTA_TIMEOUT_MS = GLOBAL_OTA_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
 export const LEGACY_PING_INTERVAL_MS = PING_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS
 export const LEGACY_BES_CONTINUE_LOCKOUT_MS = BES_CONTINUE_LOCKOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_BES_RESTART_TIMEOUT_MS = BES_RESTART_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
 /**
  * After a legacy apk `install FINISHED` observed in-flight, the legacy screen held the
  * completed state for 12s (+20s pad) so the ASG process restart settles (and fresh
@@ -122,6 +125,7 @@ export function selectOtaProtocolProfile(
 export const OtaProgressMessages = {
   stalledOrStuck: "Update may have failed. Ensure glasses have internet access and try again.",
   globalTimeout: "Update took too long. Please try again.",
+  restartTimeout: "Glasses did not finish restarting. Restart them before trying the update 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.",

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 = {

package/src/services/otaManifestPolicy.ts

@@ -0,0 +1,42 @@
+const OTA_VERSION_URL_LEGACY_PROD = "https://ota.mentraglass.com/prod_live_version.json"
+
+function trimmed(value?: string | null): string | null {
+  const result = value?.trim()
+  return result || null
+}
+
+export function isLegacyAsgOtaStartBuild(glassesBuildNumber?: string | null): boolean {
+  const buildNumber = Number.parseInt(glassesBuildNumber ?? "", 10)
+  return Number.isFinite(buildNumber) && buildNumber < 39
+}
+
+export function selectModernOtaManifestPin({
+  developerOverride,
+  hostReleasePin,
+  engineReleasePin,
+}: {
+  developerOverride?: string | null
+  hostReleasePin?: string | null
+  engineReleasePin?: string | null
+}): string | null {
+  return trimmed(developerOverride) || trimmed(hostReleasePin) || trimmed(engineReleasePin)
+}
+
+export function resolveOtaManifestPolicy({
+  glassesUrl,
+  glassesBuildNumber,
+  developerOverride,
+  hostReleasePin,
+  engineReleasePin,
+}: {
+  glassesUrl?: string | null
+  glassesBuildNumber?: string | null
+  developerOverride?: string | null
+  hostReleasePin?: string | null
+  engineReleasePin?: string | null
+}): string | null {
+  if (isLegacyAsgOtaStartBuild(glassesBuildNumber)) {
+    return trimmed(glassesUrl) || OTA_VERSION_URL_LEGACY_PROD
+  }
+  return selectModernOtaManifestPin({developerOverride, hostReleasePin, engineReleasePin})
+}

package/src/services/otaManifestUrl.ts

@@ -1,20 +1,6 @@
-import {sdkPinnedOtaManifestUrl} from "@mentra/bluetooth-sdk/internal"
-
+import {ENGINE_RELEASE_METADATA} from "../generated/releaseMetadata"
 import {SETTINGS, useSettingsStore} from "../stores/settings"
-
-// 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)
-  // ASG builds before 39 ignore ota_start.ota_version_url, so compare against
-  // the URL they will actually use.
-  return Number.isFinite(buildNumber) && buildNumber < 39
-}
+import {resolveOtaManifestPolicy, selectModernOtaManifestPin} from "./otaManifestPolicy"
 
 function getOtaVersionUrlDevOverride(): string | null {
   // Super mode only: a wrong OTA manifest can brick glasses, so a saved
@@ -27,27 +13,32 @@ function getOtaVersionUrlDevOverride(): string | null {
   return trimmed || null
 }
 
-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_LEGACY_PROD
-  }
+function getHostReleasePin(): string | null {
+  const value = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()
+  return value || null
+}
 
-  const devOverrideUrl = getOtaVersionUrlDevOverride()
-  if (devOverrideUrl) {
-    return devOverrideUrl
-  }
+function getEmbeddedEngineReleasePin(): string | null {
+  const value = ENGINE_RELEASE_METADATA.otaManifestUrl?.trim()
+  return value || null
+}
 
-  const envUrl = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()
-  if (envUrl) {
-    return envUrl
-  }
+export function hasConfiguredModernOtaManifestPin(): boolean {
+  return Boolean(
+    selectModernOtaManifestPin({
+      developerOverride: getOtaVersionUrlDevOverride(),
+      hostReleasePin: getHostReleasePin(),
+      engineReleasePin: getEmbeddedEngineReleasePin(),
+    }),
+  )
+}
 
-  // 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
+export function resolveOtaManifestUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string | null {
+  return resolveOtaManifestPolicy({
+    glassesUrl,
+    glassesBuildNumber,
+    developerOverride: getOtaVersionUrlDevOverride(),
+    hostReleasePin: getHostReleasePin(),
+    engineReleasePin: getEmbeddedEngineReleasePin(),
+  })
 }

package/src/services/otaReleaseVersion.ts

@@ -0,0 +1,22 @@
+const COORDINATED_RELEASE_VERSION = /^\d+\.\d+\.\d+(?:-(?:dev|beta)\.[1-9]\d*)?$/
+
+type OtaReleaseVersionInput = {
+  manifestReleaseVersion?: string | null
+  manifestUrl: string
+  packagedManifestUrl?: string | null
+  packagedReleaseIdentity?: string | null
+}
+
+function validReleaseVersion(version: string | null | undefined): string | null {
+  const trimmed = version?.trim()
+  return trimmed && COORDINATED_RELEASE_VERSION.test(trimmed) ? trimmed : null
+}
+
+/** Resolve the label for the selected OTA pin, including stable promotion of exact beta OTA bytes. */
+export function resolveOtaReleaseVersion(input: OtaReleaseVersionInput): string | null {
+  const packagedRelease = validReleaseVersion(input.packagedReleaseIdentity)
+  if (packagedRelease && input.packagedManifestUrl?.trim() === input.manifestUrl.trim()) {
+    return packagedRelease
+  }
+  return validReleaseVersion(input.manifestReleaseVersion)
+}

package/src/stores/appVisibility.ts

@@ -0,0 +1,3 @@
+/** Combine registry-enforced visibility with the user's home-screen choice. */
+export const resolveHiddenStatus = (registryHidden: boolean, userHidden: boolean): boolean =>
+  registryHidden || userHidden

package/src/stores/apps.ts

@@ -25,6 +25,7 @@ import {islandNotifications} from "../services/NotificationsEmitter"
 import sttModelManager from "../services/STTModelManager"
 import {miniappLauncher} from "../services/MiniappLauncher"
 import {miniappRunningRegistry} from "../services/MiniappRunningRegistry"
+import {resolveHiddenStatus} from "./appVisibility"
 import {SETTINGS, useSettingsStore} from "./settings"
 import BluetoothSdk from "@mentra/bluetooth-sdk"
 
@@ -221,7 +222,12 @@ function projectApps(previousState: AppStatusState, localApps: ClientApp[]): Cli
       ...app,
       screenshot: previousByPackage.get(app.packageName)?.screenshot ?? app.screenshot,
       compatibility: HardwareCompatibility.checkCompatibility(app.hardwareRequirements, capabilities),
-      hidden: previousState.getHiddenStatus(app.packageName),
+      // A registry source can force an app off the primary home screen (for
+      // example, Miniapp Developer while its home-screen setting is disabled).
+      // Compose that gate with the user's persisted home-screen layout instead
+      // of replacing it, otherwise a default-false persisted value makes a
+      // source-hidden app visible again during projection.
+      hidden: resolveHiddenStatus(app.hidden, previousState.getHiddenStatus(app.packageName)),
       // Derive the foreground flag from the store's single source of truth
       // (`foregroundedPackage`), NOT from the previous snapshot. Carrying it over
       // per-app meant a refresh that momentarily omitted an app (e.g. the

package/src/stores/core.ts

@@ -1,13 +1,13 @@
 import {create} from "zustand"
 import {subscribeWithSelector} from "zustand/middleware"
-import type {BluetoothStatus} from "@mentra/bluetooth-sdk/internal"
+import type {PublicBluetoothStatus} from "@mentra/bluetooth-sdk"
 
-export interface CoreState extends BluetoothStatus {
-  setCoreInfo: (info: Partial<BluetoothStatus>) => void
+export interface CoreState extends PublicBluetoothStatus {
+  setCoreInfo: (info: Partial<PublicBluetoothStatus>) => void
   reset: () => void
 }
 
-const initialState: BluetoothStatus = {
+const initialState: PublicBluetoothStatus = {
   // state:
   searching: false,
   searchingController: false,

package/src/stores/glasses.ts

@@ -1,12 +1,12 @@
 import type {
   GlassesConnectionStatus,
-  GlassesStatus,
   HotspotStatus,
   OtaProgress,
   OtaStatus,
   OtaUpdateInfo,
+  PublicGlassesStatus,
   WifiStatus,
-} from "@mentra/bluetooth-sdk/internal"
+} from "@mentra/bluetooth-sdk"
 import {isGlassesConnected, isGlassesLinkLayerBusy, isGlassesReady} from "../services/GlassesReadiness"
 import {create} from "zustand"
 import {subscribeWithSelector} from "zustand/middleware"
@@ -20,7 +20,14 @@ export const selectGlassesConnected = (state: {connection: GlassesConnectionStat
 
 export const selectGlassesReady = (state: {connection: GlassesConnectionStatus}) => isGlassesReady(state.connection)
 
-export interface GlassesState extends GlassesStatus {
+type EngineGlassesStatus = PublicGlassesStatus & {
+  otaUpdateAvailable: OtaUpdateInfo | null
+  otaProgress: OtaProgress | null
+  otaInProgress: boolean
+  otaVersionUrl: string
+}
+
+export interface GlassesState extends EngineGlassesStatus {
   systemTimeMs: number
   wifiStatusKnown: boolean
   setGlassesInfo: (info: GlassesInfoUpdate) => void
@@ -53,7 +60,7 @@ type LegacyHotspotFields = {
   hotspotLocalIp?: string
 }
 
-type GlassesInfoUpdate = Partial<GlassesStatus> & LegacyWifiFields & LegacyHotspotFields
+type GlassesInfoUpdate = Partial<EngineGlassesStatus> & LegacyWifiFields & LegacyHotspotFields
 
 function wifiFromLegacyFields(info: LegacyWifiFields): WifiStatus | null {
   if (info.wifiConnected === true) {
@@ -80,7 +87,7 @@ function hotspotFromLegacyFields(info: LegacyHotspotFields): HotspotStatus | nul
   return null
 }
 
-export const getGlasesInfoPartial = (state: GlassesStatus) => {
+export const getGlasesInfoPartial = (state: EngineGlassesStatus) => {
   const wifi = state.wifi
   const connected = isGlassesConnected(state.connection)
   return {
@@ -98,7 +105,7 @@ export const getGlasesInfoPartial = (state: GlassesStatus) => {
   }
 }
 
-interface GlassesStore extends GlassesStatus {
+interface GlassesStore extends EngineGlassesStatus {
   systemTimeMs: number
   mtkUpdatedThisSession: boolean
   wifiStatusKnown: boolean

package/src/stores/settings.ts

@@ -994,9 +994,9 @@ export const useSettingsStore = create<SettingsState>()(
         // easy to get backwards. TestFlight and the App Store receive the SAME
         // binary, so promotion does not change EXPO_PUBLIC_BUILD_ENV and this
         // reset never fires on it. Promotion is safe for a different reason:
-        // the publishing lane bakes prod URLs (staging-builds.yml defaults
-        // cloud_env to prod), so a promoted build was pointed at production the
-        // whole time. The same holds for Android internal-track to production.
+        // the publishing lane bakes the selected release cloud environment, and
+        // production promotes the already-tested binary. The same holds for
+        // Android beta-track to production.
         //
         // The residual gap is therefore an override pinned while already on a
         // prod-labelled build, which no label comparison can see. That is a