@glassly/engine 0.1.0-dev.1 → 0.1.0-dev.100

package/src/services/LocalDisplayManager.ts

@@ -2,8 +2,8 @@
  * LocalDisplayManager
  *
  * Phone-side arbiter for display requests originating from LOCAL miniapps
- * (the @glassly/miniapp SDK). Mirrors the user-facing behavior of the cloud
- * DisplayManager for the features that matter on the phone:
+ * (the @glassly/miniapp SDK). Preserves the retired cloud display manager's
+ * user-facing behavior for the features that matter on the phone:
  *
  *   - boot message ("Starting <AppName>…") with a bounded window
  *   - durationMs auto-clear
@@ -115,12 +115,50 @@ class LocalDisplayManager {
 
   private coreApp: string | null = null
   private coreAppDisplay: ActiveDisplay | null = null
-  private currentDisplay: ActiveDisplay | null = null
+  private _currentDisplay: ActiveDisplay | null = null
   private backgroundLock: BackgroundLock | null = null
 
+  /** Fired when the display transitions between empty and occupied (any package, system screens included). */
+  private activeDisplayListeners = new Set<(active: boolean) => void>()
+
+  private get currentDisplay(): ActiveDisplay | null {
+    return this._currentDisplay
+  }
+
+  private set currentDisplay(value: ActiveDisplay | null) {
+    const wasActive = this._currentDisplay !== null
+    this._currentDisplay = value
+    const isActive = value !== null
+    if (wasActive === isActive) return
+    for (const listener of this.activeDisplayListeners) {
+      try {
+        listener(isActive)
+      } catch (error) {
+        console.error(`${LOG_TAG}: onActiveDisplayChange listener failed:`, error)
+      }
+    }
+  }
+
+  /** True while anything (miniapp or system screen) is on the glasses display. */
+  public hasActiveDisplay(): boolean {
+    return this._currentDisplay !== null
+  }
+
+  /** Subscribe to empty↔occupied display transitions. Returns an unsubscribe. */
+  public onActiveDisplayChange(listener: (active: boolean) => void): () => void {
+    this.activeDisplayListeners.add(listener)
+    return () => this.activeDisplayListeners.delete(listener)
+  }
+
   private bootingApp: BootingApp | null = null
   private bootQueue: Map<string, {payload: DisplayPayload; resolve?: DisplayRequestResolver}> = new Map()
 
+  /** While true the dashboard owns the glasses: main frames are retained but not sent. */
+  private dashboardActive = false
+
+  /** Miniapp whose visible frame is temporarily covered by an OS exit notice. */
+  private exitingApp: {packageName: string; coveredDisplay: ActiveDisplay} | null = null
+
   private expiryTimerId: number | null = null
 
   /** Reconnect-replay subscription state (attachToRuntime). */
@@ -200,7 +238,7 @@ class LocalDisplayManager {
    */
   public showSystemNotice(text: string, durationMs: number = SYSTEM_NOTICE_DURATION_MS): void {
     if (!isGlassesConnected(useGlassesStore.getState().connection)) return
-    if (this.bootingApp) return
+    if (this.bootingApp || this.exitingApp) return
     console.log(`${LOG_TAG}: showSystemNotice("${text}")`)
     this.sendNow(SYSTEM_NOTICE_PKG, {
       view: "main",
@@ -228,6 +266,88 @@ class LocalDisplayManager {
     }
   }
 
+  /**
+   * The package that currently owns the glasses screen, for gesture-claim
+   * arbitration (see LocalMiniappRuntime.foregroundClaimsGesture). This is
+   * glasses ownership, not the phone's Compositor foreground: a background
+   * miniapp rendering to the glasses with the phone pocketed is the owner.
+   *
+   * The live frame's owner wins; a background app that holds the display lock
+   * but has no frame up right now (between renders) still counts. System
+   * frames (boot, notices) own nothing claimable. Returns null when the
+   * glasses are idle.
+   */
+  public getGestureOwner(): string | null {
+    const current = this.currentDisplay?.packageName ?? null
+    if (current && current !== SYSTEM_BOOT_PKG && current !== SYSTEM_NOTICE_PKG) return current
+    const lock = this.backgroundLock
+    if (lock && this.now() <= lock.expiresAt) return lock.packageName
+    return null
+  }
+
+  /**
+   * The miniapp whose frame is visibly on the glasses right now.
+   *
+   * Unlike getGestureOwner(), this deliberately does not fall back to a
+   * background display lock: a lock holder with no live frame is not visible
+   * and therefore must not be closed by the system double-tap gesture.
+   */
+  public getVisibleMiniappPackageName(): string | null {
+    const current = this.currentDisplay?.packageName ?? null
+    if (!current || current === SYSTEM_BOOT_PKG || current === SYSTEM_NOTICE_PKG) return null
+    return current
+  }
+
+  /**
+   * Cover the currently visible miniapp with a persistent system exit notice.
+   * While it is up, miniapp display traffic is held off so a streaming app
+   * cannot immediately overwrite the notice. The caller completes the normal
+   * stop flow and then calls finishMiniappExit(); onUnmount does the same as a
+   * safety net.
+   */
+  public beginMiniappExit(packageName: string, text: string): boolean {
+    if (this.exitingApp !== null) return this.exitingApp.packageName === packageName
+    const coveredDisplay = this.currentDisplay
+    if (!coveredDisplay || this.getVisibleMiniappPackageName() !== packageName) return false
+
+    console.log(`${LOG_TAG}: beginMiniappExit(${packageName})`)
+    this.exitingApp = {packageName, coveredDisplay}
+    this.clearExpiryTimer()
+    this.sendNow(SYSTEM_NOTICE_PKG, {
+      view: "main",
+      layout: {layoutType: "text_wall", text},
+    })
+    return true
+  }
+
+  /** Remove an exit notice and resume the display state normal app teardown leaves behind. */
+  public finishMiniappExit(packageName: string): void {
+    if (this.exitingApp?.packageName !== packageName) return
+    console.log(`${LOG_TAG}: finishMiniappExit(${packageName})`)
+    this.exitingApp = null
+
+    if (this.currentDisplay?.packageName !== SYSTEM_NOTICE_PKG) return
+    this.currentDisplay = null
+    this.tryRestoreCoreDisplay()
+    if (!this.currentDisplay) this.sendClear()
+  }
+
+  /** Cancel the handoff and put back the frame the exit notice covered. */
+  public cancelMiniappExit(packageName: string): void {
+    if (this.exitingApp?.packageName !== packageName) return
+    const covered = this.exitingApp.coveredDisplay
+    this.exitingApp = null
+
+    if (this.currentDisplay?.packageName !== SYSTEM_NOTICE_PKG) return
+    if (covered.expiresAt === null || covered.expiresAt > this.now()) {
+      this.restoreDisplay(covered)
+    } else {
+      this.currentDisplay = null
+      this.tryRestoreCoreDisplay()
+      if (!this.currentDisplay) this.sendClear()
+    }
+  }
+
   /** Report-safe ownership snapshot for incident diagnostics. */
   public getDiagnosticSnapshot(): Record<string, unknown> {
     return {
@@ -235,6 +355,7 @@ class LocalDisplayManager {
       currentDisplayPackageName: this.currentDisplay?.packageName ?? null,
       backgroundLockPackageName: this.backgroundLock?.packageName ?? null,
       bootingPackageName: this.bootingApp?.packageName ?? null,
+      exitingPackageName: this.exitingApp?.packageName ?? null,
     }
   }
 
@@ -297,6 +418,49 @@ class LocalDisplayManager {
         this.sendClear()
       }
     }
+
+    this.finishMiniappExit(packageName)
+  }
+
+  // ===========================================================================
+  // Dashboard switching (called from DashboardCoordinator)
+  // ===========================================================================
+
+  /**
+   * Dashboard cover state. On deactivate the retained main frame repaints
+   * (scenes replay create-based; legacy re-sends), or the glasses clear.
+   */
+  public setDashboardActive(active: boolean): void {
+    if (this.dashboardActive === active) return
+    this.dashboardActive = active
+    useDisplayStore.getState().setDashboardActive(active)
+    if (active) return
+    sceneRenderer.markViewStale("dashboard")
+    const current = this.currentDisplay
+    if (current && (current.expiresAt === null || this.now() < current.expiresAt)) {
+      this.replayCurrent()
+    } else {
+      this.sendClear()
+    }
+  }
+
+  /** Dashboard renderers only; bypasses arbitration and main ownership state. */
+  public renderDashboard(packageName: string, payload: DisplayPayload): void {
+    if (!this.dashboardActive) return
+    if (payload.scene) {
+      sceneRenderer.emitScene(packageName, "dashboard", payload.scene)
+      return
+    }
+    if (!payload.layout) return
+    const rawEvent = {view: "dashboard", layout: payload.layout}
+    let processedEvent: Record<string, unknown>
+    try {
+      processedEvent = displayProcessor.processDisplayEvent(rawEvent as any)
+    } catch (err) {
+      console.error(`${LOG_TAG}: DisplayProcessor error, using raw event:`, err)
+      processedEvent = rawEvent
+    }
+    this.pushToNative(processedEvent)
   }
 
   // ===========================================================================
@@ -313,10 +477,18 @@ class LocalDisplayManager {
    * the boot queue (resolved when drained or superseded).
    */
   public request(packageName: string, payload: DisplayPayload, resolve?: DisplayRequestResolver): void {
-    // Dashboard view: pass straight through (no throttle/arbitration). Local
-    // dashboard rendering is currently a stub on the phone anyway.
+    // Keep the OS exit notice visible for its short handoff window. Without
+    // this, streaming captions/terminal frames can replace it immediately.
+    if (this.exitingApp !== null) {
+      resolve?.({status: "blocked", reason: "a miniapp exit notice is active"})
+      return
+    }
+
+    // Dashboard view: only visible while the dashboard covers the glasses.
+    // Local miniapp dashboard content remains a stub.
     if (payload.view === "dashboard") {
-      this.sendNow(packageName, payload, resolve)
+      this.renderDashboard(packageName, payload)
+      resolve?.({status: "displayed"})
       return
     }
 
@@ -557,6 +729,23 @@ class LocalDisplayManager {
       processedEvent = rawEvent
     }
 
+    // While the dashboard covers the glasses, main frames only update the
+    // retained state; setDashboardActive(false) replays the latest.
+    if (!this.dashboardActive) this.pushToNative(processedEvent)
+
+    this.currentDisplay = {packageName, processedEvent, expiresAt}
+
+    this.clearExpiryTimer()
+    if (expiresAt !== null) {
+      const delay = Math.max(0, expiresAt - this.now())
+      this.expiryTimerId = BgTimer.setTimeout(() => {
+        this.expiryTimerId = null
+        this.handleExpiry(packageName)
+      }, delay)
+    }
+  }
+
+  private pushToNative(processedEvent: Record<string, unknown>): void {
     try {
       // The display output path is a direct btsdk call now (was a host sendDisplayEvent
       // hook) so a bare OEM renders to the glasses without wiring it.
@@ -569,17 +758,6 @@ class LocalDisplayManager {
     } catch (err) {
       console.error(`${LOG_TAG}: native display failed:`, err)
     }
-
-    this.currentDisplay = {packageName, processedEvent, expiresAt}
-
-    this.clearExpiryTimer()
-    if (expiresAt !== null) {
-      const delay = Math.max(0, expiresAt - this.now())
-      this.expiryTimerId = BgTimer.setTimeout(() => {
-        this.expiryTimerId = null
-        this.handleExpiry(packageName)
-      }, delay)
-    }
   }
 
   private handleExpiry(packageName: string): void {
@@ -785,6 +963,8 @@ class LocalDisplayManager {
     this.coreAppDisplay = null
     this.currentDisplay = null
     this.backgroundLock = null
+    this.exitingApp = null
+    this.dashboardActive = false
     this.bootQueue.clear()
     this.now = () => Date.now()
     this.unsubscribeGlassesStatus?.()

package/src/services/LocalMiniappRuntime.ts

@@ -52,6 +52,7 @@ import {normalizeAiTier, resolveAiTier} from "./AiTierResolution"
 import type {AiTier, AiTierProvider, SavedLlmKeys} from "./AiTierResolution"
 import {HttpError} from "@glassly/cloud-client"
 import localDisplayManager from "./LocalDisplayManager"
+import {claimsGesture} from "./gestureClaims"
 import nativeNavigationService from "./NativeNavigationService"
 import type {DisplayPayload} from "./LocalDisplayManager"
 import headingService from "./HeadingService"
@@ -539,6 +540,8 @@ class LocalMiniappRuntime {
 
   /** Connected miniapps keyed by packageName. */
   private connectedApps: Map<string, ConnectedMiniapp> = new Map()
+  /** Per-app claimed gestures (CLAIM_GESTURES) — see foregroundClaimsGesture. */
+  private gestureClaims: Map<string, Set<string>> = new Map()
 
   /**
    * Packages that have completed their CONNECT handshake (sent
@@ -1173,6 +1176,7 @@ class LocalMiniappRuntime {
     // core app's saved frame).
     localDisplayManager.onUnmount(packageName)
 
+    this.gestureClaims.delete(packageName)
     this.connectedApps.delete(packageName)
     this.recomputeMicRequirements()
     if (releasedMicGateOverride) {
@@ -1251,6 +1255,9 @@ class LocalMiniappRuntime {
       case MiniappRequestType.SUBSCRIBE:
         this.handleSubscribe(packageName, payload, requestId)
         break
+      case MiniappRequestType.CLAIM_GESTURES:
+        this.handleClaimGestures(packageName, payload, requestId)
+        break
       case MiniappRequestType.DISPLAY:
         this.handleDisplay(packageName, payload, requestId)
         break
@@ -1858,6 +1865,36 @@ class LocalMiniappRuntime {
     this.sendResult(packageName, requestId, true, {applied: true})
   }
 
+  /**
+   * CLAIM_GESTURES (session.input.setClaimedGestures): the app declares which
+   * touch gestures it handles itself, replacing its previous claim set.
+   * Claims suppress the host's default behavior for those gestures (today:
+   * double_tap → dashboard/head-up in DeviceEventRouter) but ONLY while the
+   * claiming app is the one in front of the user — see
+   * {@link foregroundClaimsGesture}. Cleared on app stop.
+   */
+  private handleClaimGestures(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    if (!this.connectedApps.has(packageName)) {
+      this.sendResult(packageName, requestId, true)
+      return
+    }
+    const raw = payload.gestures
+    const gestures = Array.isArray(raw) ? raw.filter((g): g is string => typeof g === "string") : []
+    if (gestures.length === 0) this.gestureClaims.delete(packageName)
+    else this.gestureClaims.set(packageName, new Set(gestures))
+    this.sendResult(packageName, requestId, true)
+  }
+
+  /** True iff the miniapp in front of the user has claimed `gesture`. */
+  public foregroundClaimsGesture(gesture: string): boolean {
+    return claimsGesture(
+      this.gestureClaims,
+      gesture,
+      localDisplayManager.getGestureOwner(),
+      useAppStatusStore.getState().foregroundedPackage,
+    )
+  }
+
   private handleSubscribe(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
     const app = this.connectedApps.get(packageName)
     if (!app) return

package/src/services/MiniappExitGesture.ts

@@ -0,0 +1,76 @@
+export const MINIAPP_EXIT_NOTICE_MS = 1500
+
+interface ExitGestureApp {
+  packageName: string
+  name: string
+  running: boolean
+}
+
+interface ExitGestureState {
+  apps: ExitGestureApp[]
+  foregroundedPackage: string | null
+  clearForeground: () => void
+  stop: (packageName: string) => Promise<void>
+}
+
+export interface ExitGestureDependencies {
+  getState: () => ExitGestureState
+  getVisiblePackageName: () => string | null
+  beginExitNotice: (packageName: string, text: string) => boolean
+  finishExitNotice: (packageName: string) => void
+  cancelExitNotice: (packageName: string) => void
+  setTimeout: (callback: () => void, delay: number) => number
+  clearTimeout: (timerId: number) => void
+}
+
+/** Owns the short double-tap → exit-notice → normal-stop handoff. */
+export class MiniappExitGesture {
+  private pending: {packageName: string; timerId: number} | null = null
+
+  public constructor(private readonly deps: ExitGestureDependencies) {}
+
+  /** Returns true when the system gesture was consumed by a visible miniapp exit. */
+  public tryExitVisibleMiniapp(): boolean {
+    // Swallow repeat taps while the notice is already counting down.
+    if (this.pending) return true
+
+    const packageName = this.deps.getVisiblePackageName()
+    if (!packageName) return false
+
+    const app = this.deps.getState().apps.find((candidate) => candidate.packageName === packageName)
+    if (!app?.running) return false
+
+    const name = app.name.trim() || packageName
+    if (!this.deps.beginExitNotice(packageName, `Exiting ${name}…`)) return false
+
+    const timerId = this.deps.setTimeout(() => {
+      const state = this.deps.getState()
+      if (state.foregroundedPackage === packageName) state.clearForeground()
+
+      const stillRunning = state.apps.some((candidate) => candidate.packageName === packageName && candidate.running)
+      const stop = stillRunning ? state.stop(packageName) : Promise.resolve()
+      void stop
+        .catch((error) => {
+          console.error(`MiniappExitGesture: failed to stop ${packageName}:`, error)
+        })
+        .finally(() => {
+          if (this.pending?.packageName === packageName) this.pending = null
+          // LocalMiniappRuntime.onUnmount normally finishes the notice. This
+          // fallback also handles a failed/no-op teardown.
+          this.deps.finishExitNotice(packageName)
+        })
+    }, MINIAPP_EXIT_NOTICE_MS)
+
+    this.pending = {packageName, timerId}
+    return true
+  }
+
+  /** Cancel an in-flight handoff when the device-event router shuts down. */
+  public reset(): void {
+    if (!this.pending) return
+    const {packageName, timerId} = this.pending
+    this.pending = null
+    this.deps.clearTimeout(timerId)
+    this.deps.cancelExitNotice(packageName)
+  }
+}

package/src/services/OtaAutoChain.ts

@@ -0,0 +1,130 @@
+import type {OtaCheckCurrentGlassesResult} from "./OtaUpdateCheckService"
+
+export const MAX_OTA_AUTO_CHAIN_PASSES = 8
+export const OTA_AUTO_CHAIN_RECONNECT_TIMEOUT_MS = 120_000
+
+type OtaAutoChainSession = {
+  approvedDowngrade: boolean
+  passCount: number
+  releaseRange: OtaAutoChainReleaseRange
+  reconnectDeadline: number | null
+  seenFingerprints: Set<string>
+}
+
+export type OtaAutoChainReleaseRange = {
+  fromVersion: string | null
+  toVersion: string | null
+  /** Exact coordinated release identity for the OTA pin, absent for legacy manifests. */
+  releaseVersion?: string | null
+}
+
+export type OtaAutoChainAdvanceResult =
+  | {advance: true; passCount: number}
+  | {advance: false; reason: "inactive" | "duplicate" | "max_passes" | "downgrade_not_approved"}
+
+let session: OtaAutoChainSession | null = null
+
+/**
+ * Identify the exact update offer that produced one OTA pass. Including the
+ * observed versions and manifest body lets a changed manifest advance while a
+ * stale post-install version_info response is rejected as a duplicate.
+ */
+export function otaAutoChainFingerprint(result: OtaCheckCurrentGlassesResult): string {
+  return JSON.stringify({
+    manifestUrl: result.manifestUrl ?? "",
+    manifestBody: result.manifestBody ?? "",
+    buildNumber: result.buildNumber ?? "",
+    mtkFirmwareVersion: result.mtkFirmwareVersion ?? "",
+    besFirmwareVersion: result.besFirmwareVersion ?? "",
+    updates: result.updates,
+    targetBuildNumber: result.updateInfo?.versionCode ?? result.latestVersionInfo?.versionCode ?? 0,
+    targetBesVersion: result.besVersion ?? "",
+    mtkPatch: result.mtkPatch
+      ? {
+          startFirmware: result.mtkPatch.start_firmware,
+          endFirmware: result.mtkPatch.end_firmware,
+          url: result.mtkPatch.url,
+        }
+      : null,
+  })
+}
+
+/** Start a chain after the user explicitly approves its first update pass. */
+export function beginOtaAutoChain(
+  initialFingerprint: string,
+  approvedDowngrade: boolean,
+  releaseRange: OtaAutoChainReleaseRange,
+): void {
+  session = {
+    approvedDowngrade,
+    passCount: 1,
+    releaseRange: {...releaseRange},
+    reconnectDeadline: null,
+    seenFingerprints: new Set([initialFingerprint]),
+  }
+}
+
+export function isOtaAutoChainActive(): boolean {
+  return session !== null
+}
+
+export function otaAutoChainReleaseRange(): OtaAutoChainReleaseRange | null {
+  return session ? {...session.releaseRange} : null
+}
+
+/** End the current chain. Safe to call when no chain is active. */
+export function stopOtaAutoChain(): void {
+  session = null
+}
+
+/**
+ * Start (or continue) the bounded wait for glasses that are rebooting between
+ * passes. Re-renders must not extend the original deadline indefinitely.
+ */
+export function otaAutoChainReconnectWaitRemaining(now = performance.now()): number | null {
+  if (!session) return null
+
+  session.reconnectDeadline ??= now + OTA_AUTO_CHAIN_RECONNECT_TIMEOUT_MS
+  return Math.max(0, session.reconnectDeadline - now)
+}
+
+/** A successful reconnect allows a future pass to establish a fresh wait. */
+export function clearOtaAutoChainReconnectWait(): void {
+  if (session) session.reconnectDeadline = null
+}
+
+/**
+ * Admit the next pass of an active chain. Repeated offers, unexpectedly
+ * destructive downgrades, and runaway chains fail closed and end automation.
+ */
+export function tryAdvanceOtaAutoChain(
+  fingerprint: string,
+  isDowngrade: boolean,
+  targetVersion: string | null,
+  releaseVersion: string | null = null,
+): OtaAutoChainAdvanceResult {
+  if (!session) {
+    return {advance: false, reason: "inactive"}
+  }
+
+  if (isDowngrade && !session.approvedDowngrade) {
+    stopOtaAutoChain()
+    return {advance: false, reason: "downgrade_not_approved"}
+  }
+
+  if (session.seenFingerprints.has(fingerprint)) {
+    stopOtaAutoChain()
+    return {advance: false, reason: "duplicate"}
+  }
+
+  if (session.passCount >= MAX_OTA_AUTO_CHAIN_PASSES) {
+    stopOtaAutoChain()
+    return {advance: false, reason: "max_passes"}
+  }
+
+  session.seenFingerprints.add(fingerprint)
+  session.passCount += 1
+  if (targetVersion) session.releaseRange.toVersion = targetVersion
+  if (releaseVersion) session.releaseRange.releaseVersion = releaseVersion
+  return {advance: true, passCount: session.passCount}
+}

package/src/services/OtaErrorMapping.ts

@@ -0,0 +1,80 @@
+import type {OtaProgress, OtaStatus} from "../facades/ota"
+
+export const BES_INSTALL_RESTART_MESSAGE =
+  "Restart your glasses to safely exit firmware update mode before trying again"
+
+function isDownloadPhaseSnapshot(
+  otaStatus: OtaStatus | null | undefined,
+  otaProgress: OtaProgress | null | undefined,
+): boolean {
+  if (otaStatus?.phase === "download") {
+    return true
+  }
+  if (otaProgress?.stage === "download") {
+    return true
+  }
+  return false
+}
+
+/**
+ * Offer Change WiFi whenever the OTA flow failed while the glasses were in the
+ * download step (any download failure — network, SSL, size cap, verify, etc.).
+ *
+ * Also covers phone-side watchdog failures that fire while the store still shows
+ * an active download phase (stall / global timeout mid-download).
+ */
+export function shouldShowChangeWifiForOtaDownloadFailure(
+  otaStatus: OtaStatus | null | undefined,
+  otaProgress: OtaProgress | null | undefined,
+  localErrorMessage: string,
+): boolean {
+  if (otaStatus?.status === "failed" && otaStatus.phase === "download") {
+    return true
+  }
+  if (otaProgress?.status === "FAILED" && otaProgress.stage === "download") {
+    return true
+  }
+  if (localErrorMessage && isDownloadPhaseSnapshot(otaStatus, otaProgress)) {
+    return true
+  }
+  return false
+}
+
+export function getOtaErrorMessage(error?: string): string {
+  switch (error) {
+    case "no_internet":
+      return "Glasses WiFi has no internet connection"
+    case "clock_skew":
+      return "Glasses clock is wrong — syncing time from your phone, then retrying update check"
+    case "ssl_error":
+      return "Secure connection failed — try a different WiFi network"
+    case "download_failed":
+      return "Download failed — check glasses WiFi connection"
+    case "firmware_too_large":
+      return "Firmware file is unexpectedly large — please contact support"
+    case "firmware_verify_failed":
+      return "Firmware verification failed — please try again or contact support"
+    case "apk_verify_failed":
+      return "Update verification failed — please try again or contact support"
+    case "install_failed":
+      return "Install failed — please try again"
+    default:
+      return error || "Update failed"
+  }
+}
+
+/**
+ * Once a BES install has started, any failure conservatively requires a glasses restart. This
+ * avoids adding a BES-specific error code to the wire protocol and, more importantly, never offers
+ * an unsafe retry when a generic failure or silence may mean BES entered its raw OTA parser.
+ */
+export function shouldRequireGlassesRebootForBesFailure(
+  otaStatus: OtaStatus | null | undefined,
+  _otaProgress: OtaProgress | null | undefined,
+  localErrorMessage: string,
+): boolean {
+  if (otaStatus?.stepType !== "bes" || otaStatus.phase !== "install") {
+    return false
+  }
+  return otaStatus.status === "failed" || Boolean(localErrorMessage)
+}