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

package/src/services/OtaService.ts

@@ -15,11 +15,7 @@ import type {OtaStatus} from "@mentra/bluetooth-sdk/internal"
 import GlobalEventEmitter from "../utils/GlobalEventEmitter"
 import {useGlassesStore} from "../stores/glasses"
 import {handleOtaClockSkewFromGlasses} from "./glassesClockSync"
-import {
-  legacyOtaProgressFromOtaStatusEvent,
-  normalizeOtaStatusEvent,
-  otaStatusFromNormalized,
-} from "./otaLegacyMapping"
+import {legacyOtaProgressFromOtaStatusEvent, normalizeOtaStatusEvent, otaStatusFromNormalized} from "./otaLegacyMapping"
 
 let subs: Array<{remove: () => void}> = []
 
@@ -40,6 +36,16 @@ export function startOtaService(): void {
     }),
   )
 
+  // The glasses process restarted under a live BLE link (sid changed in
+  // glasses_ready/version_info_1). The physical connection never dropped, so this is
+  // the ONLY reconnect-edge signal the OTA coordinator gets after an APK install.
+  subs.push(
+    BluetoothSdk.addListener("glasses_session_changed", (event) => {
+      console.log(`[OTA] glasses_session_changed ${event.previous_sid || "<none>"} -> ${event.sid}`)
+      GlobalEventEmitter.emit("glasses_session_changed", {previousSid: event.previous_sid, sid: event.sid})
+    }),
+  )
+
   // Install progress / lifecycle. Updates both the new (otaStatus) and the legacy
   // (otaProgress) store shapes; auto-fixes clock skew on the relevant failures.
   subs.push(

package/src/services/OtaUpdateCheckService.ts

@@ -1,8 +1,19 @@
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 import type {OtaUpdateInfo} from "@mentra/bluetooth-sdk/internal"
 import {getGlassesSystemTimeMs, isGlassesConnected, useGlassesStore, waitForGlassesState} from "../stores/glasses"
+import {SETTINGS, useSettingsStore} from "../stores/settings"
 import {maybeFixGlassesClockFromVersionInfo} from "./glassesClockSync"
-import {getAsgOtaVersionUrl} from "./asgOtaVersionUrl"
+import {resolveOtaManifestUrl} from "./otaManifestUrl"
+
+/**
+ * Phone-side mirror of ASG's `DOWNGRADE_FLOOR_VERSION_CODE`. Set to the versionCode of the first
+ * release shipping the shared media root (the first downgrade-safe build). A non-positive value
+ * means downgrades are disabled, so the phone must NOT offer them — offering a downgrade the
+ * glasses' `DowngradeGate` will refuse leaves the version-change session with no install and the
+ * glasses reporting a bare "complete", which would otherwise present as false success. Keep this
+ * in lockstep with the ASG/recovery constant at release time.
+ */
+export const DOWNGRADE_FLOOR_VERSION_CODE = 0
 
 export interface VersionInfo {
   versionCode: number
@@ -18,11 +29,13 @@ export interface MtkPatch {
   start_firmware: string
   end_firmware: string
   url: string
+  sha256?: string
 }
 
 export interface BesFirmware {
   version: string
   url: string
+  sha256?: string
 }
 
 export interface VersionJson {
@@ -46,9 +59,23 @@ export interface OtaCheckResult {
   updates: string[]
   mtkPatch: MtkPatch | null
   besVersion: string | null
+  /** True when the pending APK step installs an OLDER build than the glasses currently run. */
+  isApkDowngrade: boolean
+  /**
+   * Raw manifest JSON (stringified) this check actually fetched, or null when the
+   * fetch failed. Lets change-watchers baseline on exactly what the check saw,
+   * instead of racing it with a second fetch of the same URL.
+   */
+  manifestBody: 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,
+   * unparseable, or carrying no valid ASG pin) — the remedy is updating the app.
+   */
+  checkFailureReason?: "network" | "pin_unavailable"
 }
 
-export type OtaCheckSkippedReason = "disconnected" | "missing_build"
+export type OtaCheckSkippedReason = "disconnected" | "missing_build" | "dev_build"
 
 export interface OtaCheckCurrentGlassesResult extends OtaCheckResult {
   updateInfo: OtaUpdateInfo | null
@@ -66,6 +93,8 @@ export interface OtaCheckCurrentGlassesOptions {
   waitForMtkVersionMs?: number
   refreshVersionInfo?: boolean
   fixClockBeforeCheck?: boolean
+  /** Downgrade floor override (defaults to DOWNGRADE_FLOOR_VERSION_CODE); for tests. */
+  floorVersionCode?: number
 }
 
 function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurrentGlassesResult {
@@ -76,6 +105,8 @@ function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurren
     updates: [],
     mtkPatch: null,
     besVersion: null,
+    isApkDowngrade: false,
+    manifestBody: null,
     updateInfo: null,
     isRequired: true,
     skippedReason,
@@ -86,46 +117,92 @@ function glassesConnectedNow(): boolean {
   return isGlassesConnected(useGlassesStore.getState().connection)
 }
 
-export async function fetchVersionInfo(url: string): Promise<VersionJson | null> {
+type ManifestFetchResult = {json: VersionJson | null; failureReason?: "network" | "pin_unavailable"}
+
+async function fetchVersionInfoDetailed(url: string): Promise<ManifestFetchResult> {
   try {
     const response = await fetch(url)
     if (!response.ok) {
       console.error("Failed to fetch version info:", response.status)
-      return null
+      // 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"}
+    }
+    try {
+      return {json: await response.json()}
+    } catch (parseError) {
+      console.error("OTA: manifest is not valid JSON:", parseError)
+      return {json: null, failureReason: "pin_unavailable"}
     }
-    return await response.json()
   } catch (error) {
     console.error("OTA: Error fetching version info:", error)
-    return null
+    return {json: null, failureReason: "network"}
   }
 }
 
+export async function fetchVersionInfo(url: string): Promise<VersionJson | null> {
+  return (await fetchVersionInfoDetailed(url)).json
+}
+
 export function checkVersionUpdateAvailable(
   currentBuildNumber: string | undefined,
   versionJson: VersionJson | null,
+  floorVersionCode: number = DOWNGRADE_FLOOR_VERSION_CODE,
 ): boolean {
+  return getApkUpdateDirection(currentBuildNumber, versionJson, floorVersionCode) !== null
+}
+
+/**
+ * Direction of the pending APK change, or null when the glasses already match the manifest.
+ * Every apps-shaped manifest the phone drives is an exact pin, so both directions are
+ * actionable (mirroring the glasses-side `DowngradeGate`); the ancient top-level manifest
+ * shape stays upgrade-only, and zeroed rescue pins are never actionable.
+ */
+export function getApkUpdateDirection(
+  currentBuildNumber: string | undefined,
+  versionJson: VersionJson | null,
+  floorVersionCode: number = DOWNGRADE_FLOOR_VERSION_CODE,
+): "upgrade" | "downgrade" | null {
   if (!currentBuildNumber || !versionJson) {
-    return false
+    return null
   }
 
   const currentVersion = parseInt(currentBuildNumber, 10)
   if (isNaN(currentVersion)) {
-    return false
+    return null
   }
 
   let serverVersion: number | undefined
+  let exactPin = false
 
-  if (versionJson.apps?.["com.mentra.asg_client"]) {
-    serverVersion = versionJson.apps["com.mentra.asg_client"].versionCode
+  const appEntry = versionJson.apps?.["com.mentra.asg_client"]
+  if (appEntry) {
+    serverVersion = appEntry.versionCode
+    exactPin = true
   } else if (versionJson.versionCode) {
     serverVersion = versionJson.versionCode
   }
 
   if (!serverVersion || isNaN(serverVersion)) {
-    return false
+    return null
   }
 
-  return serverVersion > currentVersion
+  if (serverVersion > currentVersion) {
+    return "upgrade"
+  }
+  // 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
+  ) {
+    return "downgrade"
+  }
+  return null
 }
 
 export function getLatestVersionInfo(versionJson: VersionJson | null): VersionInfo | null {
@@ -184,7 +261,7 @@ export function checkBesUpdate(besFirmware: BesFirmware | undefined, currentVers
   return compareVersions(besFirmware.version, currentVersion) > 0
 }
 
-function compareVersions(version1: string, version2: string): number {
+export function compareVersions(version1: string, version2: string): number {
   if (version1.includes(".") && version2.includes(".")) {
     const parts1 = version1.split(".")
     const parts2 = version2.split(".")
@@ -208,14 +285,62 @@ export async function checkForOtaUpdate(
   currentBuildNumber: string,
   currentMtkVersion?: string,
   currentBesVersion?: string,
+  floorVersionCode: number = DOWNGRADE_FLOOR_VERSION_CODE,
 ): Promise<OtaCheckResult> {
   try {
     console.log("OTA: Checking for OTA update - URL: " + otaVersionUrl + ", current build: " + currentBuildNumber)
-    const versionJson = await fetchVersionInfo(otaVersionUrl)
+    const fetched = await fetchVersionInfoDetailed(otaVersionUrl)
+    const versionJson = fetched.json
+    if (!versionJson) {
+      return {
+        hasCheckCompleted: false,
+        updateAvailable: false,
+        latestVersionInfo: null,
+        updates: [],
+        mtkPatch: null,
+        besVersion: null,
+        isApkDowngrade: false,
+        manifestBody: null,
+        checkFailureReason: fetched.failureReason ?? "network",
+      }
+    }
     const latestVersionInfo = getLatestVersionInfo(versionJson)
 
-    const apkUpdateAvailable = checkVersionUpdateAvailable(currentBuildNumber, versionJson)
-    console.log(`OTA: APK update available: ${apkUpdateAvailable} (current: ${currentBuildNumber})`)
+    // A manifest whose ASG pin is missing/zeroed cannot verify anything for modern
+    // glasses (zeroed pins are only legitimate in the frozen legacy rescue manifests
+    // that pre-39 glasses are checked against). Report the check as FAILED rather
+    // than silently completing as "up to date" — an unverifiable state must never
+    // present as a verified one.
+    const currentVersionNumber = parseInt(currentBuildNumber, 10)
+    const pinnedEntry = versionJson?.apps?.["com.mentra.asg_client"]
+    const pinnedVersion = pinnedEntry?.versionCode ?? versionJson?.versionCode
+    if (
+      versionJson &&
+      Number.isFinite(currentVersionNumber) &&
+      currentVersionNumber >= 39 &&
+      !(typeof pinnedVersion === "number" && pinnedVersion > 0)
+    ) {
+      console.error(
+        `OTA: manifest at ${otaVersionUrl} has no valid ASG pin (versionCode=${String(pinnedVersion)}) - treating check as failed`,
+      )
+      return {
+        hasCheckCompleted: false,
+        updateAvailable: false,
+        latestVersionInfo: null,
+        updates: [],
+        mtkPatch: null,
+        besVersion: null,
+        isApkDowngrade: false,
+        manifestBody: null,
+        checkFailureReason: "pin_unavailable",
+      }
+    }
+
+    const apkDirection = getApkUpdateDirection(currentBuildNumber, versionJson, floorVersionCode)
+    const apkUpdateAvailable = apkDirection !== null
+    console.log(
+      `OTA: APK update available: ${apkUpdateAvailable} (current: ${currentBuildNumber}, direction: ${apkDirection ?? "none"})`,
+    )
 
     const mtkPatch = findMatchingMtkPatch(versionJson?.mtk_patches, currentMtkVersion)
     const mtkUpdateAvailable = mtkPatch !== null
@@ -243,6 +368,8 @@ export async function checkForOtaUpdate(
       updates,
       mtkPatch,
       besVersion: versionJson?.bes_firmware?.version || null,
+      isApkDowngrade: apkDirection === "downgrade",
+      manifestBody: versionJson ? JSON.stringify(versionJson) : null,
     }
   } catch (error) {
     console.error("Error checking for OTA update:", error)
@@ -253,6 +380,9 @@ export async function checkForOtaUpdate(
       updates: [],
       mtkPatch: null,
       besVersion: null,
+      isApkDowngrade: false,
+      manifestBody: null,
+      checkFailureReason: "network",
     }
   }
 }
@@ -266,12 +396,25 @@ export async function checkCurrentGlassesForUpdate(
     waitForMtkVersionMs = 2000,
     refreshVersionInfo = true,
     fixClockBeforeCheck = true,
+    floorVersionCode = DOWNGRADE_FLOOR_VERSION_CODE,
   } = options
 
   if (!glassesConnectedNow()) {
     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")
+    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)
@@ -284,7 +427,10 @@ export async function checkCurrentGlassesForUpdate(
     buildNumber = useGlassesStore.getState().buildNumber
   }
 
-  if (!buildNumber) {
+  if (!buildNumber || !(parseInt(buildNumber, 10) > 0)) {
+    // Covers absent, non-numeric, and zero build numbers: a glasses version we
+    // cannot parse means nothing is verifiable, so skip rather than ghost an
+    // "up to date" result from a comparison that never really ran.
     return emptyCheckResult("missing_build")
   }
 
@@ -325,8 +471,8 @@ export async function checkCurrentGlassesForUpdate(
     })
   }
 
-  const manifestUrl = getAsgOtaVersionUrl(useGlassesStore.getState().otaVersionUrl, buildNumber)
-  const result = await checkForOtaUpdate(manifestUrl, buildNumber, mtkFirmwareVersion, besFirmwareVersion)
+  const manifestUrl = resolveOtaManifestUrl(useGlassesStore.getState().otaVersionUrl, buildNumber)
+  const result = await checkForOtaUpdate(manifestUrl, buildNumber, mtkFirmwareVersion, besFirmwareVersion, floorVersionCode)
 
   if (!result.hasCheckCompleted) {
     return {
@@ -360,6 +506,7 @@ export async function checkCurrentGlassesForUpdate(
     )
   }
   const updateAvailable = filteredUpdates.length > 0 && !!result.latestVersionInfo
+  const isApkDowngrade = result.isApkDowngrade && filteredUpdates.includes("apk")
   const updateInfo = updateAvailable
     ? {
         available: true,
@@ -367,6 +514,8 @@ export async function checkCurrentGlassesForUpdate(
         versionName: result.latestVersionInfo?.versionName || "",
         updates: filteredUpdates,
         totalSize: 0,
+        ...(filteredUpdates.includes("bes") && result.besVersion ? {besVersion: result.besVersion} : {}),
+        isDowngrade: isApkDowngrade,
       }
     : null
 
@@ -376,8 +525,19 @@ export async function checkCurrentGlassesForUpdate(
     ...result,
     updateAvailable,
     updates: filteredUpdates,
+    isApkDowngrade,
     updateInfo,
-    isRequired: result.latestVersionInfo?.isRequired !== false,
+    // Required-update policy: an EXPLICIT isRequired in the manifest is the
+    // release-engineering escape hatch and wins in both directions. When absent,
+    // upgrades keep the historical forced default, but downgrades are always
+    // skippable — a version change that resets glasses settings must be
+    // declinable unless someone explicitly forced it.
+    isRequired:
+      result.latestVersionInfo?.isRequired === true
+        ? true
+        : result.latestVersionInfo?.isRequired === false
+          ? false
+          : !isApkDowngrade,
     manifestUrl,
     buildNumber,
     mtkFirmwareVersion,

package/src/services/PhoneCalendarService.ts

@@ -1,4 +1,6 @@
 import * as Calendar from "expo-calendar"
+import {Platform} from "react-native"
+import {check, PERMISSIONS, RESULTS} from "react-native-permissions"
 
 import {MiniappErrorCode, type CalendarListResult} from "@mentra/miniapp"
 
@@ -12,14 +14,35 @@ import {
 
 export {PhoneCalendarError} from "./PhoneCalendarHelpers"
 
+type CalendarPermissionStatus = Awaited<
+  ReturnType<typeof Calendar.getCalendarPermissionsAsync>
+>["status"]
+
+/**
+ * expo-calendar reports anything below EventKit full access as not granted,
+ * so distinguish the states the user can actually fix. "Reopen the miniapp"
+ * is only true while the permission is undetermined — once iOS has resolved
+ * it (denied or write-only/limited), only Settings can change it.
+ */
+async function calendarPermissionMessage(status: CalendarPermissionStatus): Promise<string> {
+  if (status === "undetermined") {
+    return "Calendar permission has not been granted yet. Reopen the miniapp and allow calendar access."
+  }
+  if (Platform.OS === "ios") {
+    const writeOnly = await check(PERMISSIONS.IOS.CALENDARS_WRITE_ONLY).catch(() => null)
+    if (writeOnly === RESULTS.GRANTED || writeOnly === RESULTS.LIMITED) {
+      return 'Calendar access is limited to write-only. Enable "Full Access" for Mentra in Settings › Privacy & Security › Calendars.'
+    }
+    return "Calendar access is denied. Enable it for Mentra in Settings › Privacy & Security › Calendars."
+  }
+  return "Calendar access is denied. Enable the Calendar permission for Mentra in your phone's app settings."
+}
+
 export async function listPhoneCalendarEvents(request: CalendarListRequest): Promise<CalendarListResult> {
   const {startsAt, endsAt, limit} = validateCalendarListRequest(request)
   const permission = await Calendar.getCalendarPermissionsAsync()
   if (permission.status !== "granted") {
-    throw new PhoneCalendarError(
-      MiniappErrorCode.PERMISSION_DENIED,
-      "Calendar permission is not granted. Reopen the miniapp and grant calendar access.",
-    )
+    throw new PhoneCalendarError(MiniappErrorCode.PERMISSION_DENIED, await calendarPermissionMessage(permission.status))
   }
 
   const calendars = await Calendar.getCalendarsAsync(Calendar.EntityTypes.EVENT)

package/src/services/PhoneCameraFovCoordinator.ts

@@ -41,6 +41,21 @@ export class PhoneCameraFovCoordinator {
 
   constructor(private readonly legacyRestartSettleMs = LEGACY_CAMERA_RESTART_SETTLE_MS) {}
 
+  /** Report-safe FOV ownership snapshot for incident diagnostics. */
+  getDiagnosticSnapshot(): Record<string, unknown> {
+    return {
+      owners: [...this.overrides.entries()]
+        .sort(([, a], [, b]) => b.order - a.order)
+        .map(([packageName, entry]) => ({
+          packageName,
+          effective: entry.leaseId === this.effectiveLeaseId,
+          fov: entry.fov,
+          roiPosition: entry.roiPosition,
+        })),
+      legacyMode: this.legacyMode,
+    }
+  }
+
   setOverride(packageName: string, request: CameraFovRequest): Promise<CameraFovResult> {
     return this.enqueue(async () => {
       const previous = this.overrides.get(packageName)

package/src/services/PhoneNotificationsSync.ts

@@ -1,10 +1,15 @@
 /**
  * Phone-notifications sync — engine-owned. Pushes the notification-forwarding
- * config (`notifications_enabled` + `notifications_blocklist`) to the native
+ * operational kill switch + config (`android_notification_listener_enabled`
+ * and `notifications_blocklist`) to the native
  * NotificationListener via `CrustModule.setNotificationConfig`, so
- * `engine.phoneNotifications.setEnabled()/setBlocklist()` actually reach the
- * listener for ANY host — not just the Mentra app, where this used to live in
- * MantleManager. Android-only; a no-op elsewhere. Started by `engine.start()`.
+ * the blocklist reaches the listener for ANY host — not just the Mentra App,
+ * where this used to live in MantleManager. The Android service is desired by
+ * default now that its cold start is isolated from React Native. Native code
+ * keeps the component discoverable in Android's notification-access Settings,
+ * but only binds the service after access is granted. The debug setting remains
+ * a hidden emergency kill switch; Notify's running state gates presentation,
+ * not capture. Android-only; a no-op elsewhere. Started by `engine.start()`.
  */
 import {shallow} from "zustand/shallow"
 import CrustModule from "@mentra/crust"
@@ -15,12 +20,9 @@ let unsubscribe: (() => void) | null = null
 
 function pushConfig(): void {
   const s = useSettingsStore.getState()
-  const enabled = Boolean(s.getSetting(SETTINGS.notifications_enabled.key))
+  const listenerEnabled = Boolean(s.getSetting(SETTINGS.android_notification_listener_enabled.key))
   const blocklist = s.getSetting(SETTINGS.notifications_blocklist.key)
-  // Unconditional (matches the prior MantleManager sync) — the listener is
-  // Android-only, but CrustModule.setNotificationConfig is a safe no-op elsewhere;
-  // the Android-only gating lives on the facade's setEnabled/setBlocklist.
-  CrustModule.setNotificationConfig(enabled, Array.isArray(blocklist) ? blocklist : []).catch((err: unknown) =>
+  CrustModule.setNotificationConfig(listenerEnabled, Array.isArray(blocklist) ? blocklist : []).catch((err: unknown) =>
     console.warn(`PhoneNotificationsSync: setNotificationConfig failed: ${(err as Error)?.message ?? err}`),
   )
 }
@@ -30,7 +32,7 @@ export function startPhoneNotificationsSync(): void {
   pushConfig() // initial sync so the listener has the current config
   unsubscribe = useSettingsStore.subscribe(
     (state) => ({
-      enabled: state.getSetting(SETTINGS.notifications_enabled.key),
+      listenerEnabled: state.getSetting(SETTINGS.android_notification_listener_enabled.key),
       blocklist: state.getSetting(SETTINGS.notifications_blocklist.key),
     }),
     () => pushConfig(),

package/src/services/PhonePhotoCoordinator.ts

@@ -19,7 +19,7 @@
  */
 
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {PhotoSize} from "@mentra/bluetooth-sdk/internal"
+import type {PhotoSize, PhotoTransferMethod} from "@mentra/bluetooth-sdk/internal"
 import {cloudClientService} from "./CloudClientService"
 import {isGlassesConnected} from "./GlassesReadiness"
 import {useGlassesStore} from "../stores/glasses"
@@ -49,8 +49,8 @@ export interface PhotoOpts {
   /** Legacy cloud size names are normalized before the native take_photo command. */
   size?: "low" | "medium" | "high" | "max" | "small" | "large" | "full"
   mode?: "photo" | "text"
-  /** Force phone-relayed BLE delivery, or leave native on its auto Wi-Fi/BLE policy. */
-  transferMethod?: "auto" | "ble"
+  /** Select direct-only, phone-relayed BLE, or the default Wi-Fi/BLE fallback policy. */
+  transferMethod?: PhotoTransferMethod
   compress?: "none" | "low" | "medium" | "high"
   sound?: boolean
   saveToGallery?: boolean
@@ -60,8 +60,10 @@ export interface PhotoOpts {
   isoCap?: number
   noiseReduction?: boolean
   edgeEnhancement?: boolean
-  mfnr?: boolean
+  /** ZSL preview buffering. */
   zsl?: boolean
+  /** MFNR still capture. */
+  mfnr?: boolean
   ispDigitalGain?: number
   ispAnalogGain?: string
 }
@@ -91,6 +93,15 @@ export class PhotoError extends Error {
   }
 }
 
+function parsePhotoTransferMethod(value: unknown): PhotoTransferMethod | undefined {
+  if (value === undefined) return undefined
+  if (value === "auto" || value === "direct" || value === "ble") return value
+  throw new PhotoError(
+    "INVALID_ARGUMENT",
+    `Invalid transferMethod ${JSON.stringify(value)}. Expected "auto", "direct", or "ble".`,
+  )
+}
+
 interface ActiveRequest {
   packageName: string
   abort: AbortController
@@ -138,7 +149,18 @@ export class PhonePhotoCoordinator {
     {requestId: string; durationMs: number; expiryTimer?: ReturnType<typeof setTimeout>}
   >()
 
+  /** Report-safe camera ownership snapshot for incident diagnostics. */
+  getDiagnosticSnapshot(): Record<string, unknown> {
+    return {
+      captureOwners: [...new Set([...this.activeRequests.values()].map((request) => request.packageName))].sort(),
+      warmUpOwners: [...this.activeWarmUps.keys()].sort(),
+      activeCaptureCount: this.activeRequests.size,
+    }
+  }
+
   async takePhoto(packageName: string, opts: PhotoOpts): Promise<PhotoTaken> {
+    const transferMethod = parsePhotoTransferMethod(opts.transferMethod)
+
     // Pre-check: if glasses aren't even connected, the BLE photo command
     // would be sent into the void and we'd wait 30s for the cloud long-poll
     // to time out. Fail fast with a typed error.
@@ -241,7 +263,7 @@ export class PhonePhotoCoordinator {
         mode: opts.mode ?? "photo",
         webhookUrl: uploadUrl,
         authToken: null,
-        ...(isLoopbackUpload || opts.transferMethod === "ble" ? {transferMethod: "ble" as const} : {}),
+        ...(isLoopbackUpload ? {transferMethod: "ble" as const} : transferMethod ? {transferMethod} : {}),
         compress: toNativeCompression(opts.compress),
         save: opts.saveToGallery ?? false,
         sound: opts.sound ?? true,
@@ -251,8 +273,8 @@ export class PhonePhotoCoordinator {
         isoCap: opts.isoCap,
         noiseReduction: opts.noiseReduction,
         edgeEnhancement: opts.edgeEnhancement,
-        mfnr: opts.mfnr,
-        zsl: opts.zsl,
+        ...(opts.zsl != null ? {zsl: opts.zsl} : {}),
+        ...(opts.mfnr != null ? {mfnr: opts.mfnr} : {}),
         ispDigitalGain: opts.ispDigitalGain,
         ispAnalogGain: opts.ispAnalogGain,
       }).catch((err) => {
@@ -322,6 +344,8 @@ export class PhonePhotoCoordinator {
       mode?: "photo" | "text"
       exposureTimeNs?: number
       durationMs?: number
+      zsl?: boolean
+      mfnr?: boolean
     },
   ): Promise<void> {
     // Pre-check: if glasses aren't connected, the BLE warm-up command would be
@@ -347,6 +371,8 @@ export class PhonePhotoCoordinator {
         mode: opts.mode ?? "photo",
         exposureTimeNs: opts.exposureTimeNs ?? null,
         durationMs,
+        ...(opts.zsl != null ? {zsl: opts.zsl} : {}),
+        ...(opts.mfnr != null ? {mfnr: opts.mfnr} : {}),
       })
       if (this.activeWarmUps.get(packageName) === lease) {
         lease.expiryTimer = setTimeout(() => {