@mentra/engine 0.1.0-dev.0 → 3.1.0-beta.100

package/src/services/OtaInstallCoordinator.ts

@@ -2,8 +2,8 @@
  * OtaInstallCoordinator — engine-owned OTA install state machine (WP 8B).
  *
  * Owns every timer/retry/sequencing rule that used to live in the host screen
- * `mobile/src/app/ota/progress.tsx`: the global session timeout, the no-ack
- * retry watchdog, the stuck-at-zero watchdog, the progress-stall watchdog keyed
+ * `mobile/src/app/ota/progress.tsx`: the global session timeout, serialized
+ * ota_start retries, the stuck-at-zero watchdog, the progress-stall watchdog keyed
  * on a staleness signature, connect-edge arbitration (initial mount vs
  * reconnect vs post-APK reboot), the ota_query_status reply fallback, the ping
  * keepalive, the ota_start_ack / mtk_update_complete listeners, and terminal
@@ -11,27 +11,27 @@
  * `snapshot()`/`onSnapshot()` plus the `attach()/detach()/retry()/finish()`
  * commands (exposed as `engine.ota.installSession`).
  *
- * Behavior contract: everything here was MOVED, not changed — every timer
- * duration (see ./otaInstallPolicy), arbitration rule, and "[OTA_PROGRESS]"
- * log line is a field-debugging contract and stays byte-identical to the old
- * screen. The reaction pass mirrors the old component's effect ordering: a
+ * The reaction pass mirrors the old component's effect ordering: a
  * pass diffs the store-derived inputs (connected / otaStatus / otaProgress /
  * displayState / stall signature) exactly like the old effect dep arrays, and
  * state written mid-pass queues a follow-up pass — the same way a setState
  * during React effects scheduled a re-render after the current effect batch.
  */
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+import BluetoothSdk, {type OtaProgress, type OtaStatus} from "@mentra/bluetooth-sdk"
 import GlobalEventEmitter from "../utils/GlobalEventEmitter"
 import {isGlassesConnected, useGlassesStore} from "../stores/glasses"
-import {getAsgOtaVersionUrl} from "./asgOtaVersionUrl"
+import {resolveOtaManifestUrl} from "./otaManifestUrl"
+import {hotspotOtaTransport, type HotspotOtaPhase} from "./HotspotOtaTransport"
+import type {OtaCheckCurrentGlassesResult} from "./OtaUpdateCheckService"
 import {deriveDisplayState, type DisplayState} from "./otaDisplayState"
 import {
   BES_CONTINUE_LOCKOUT_MS,
+  BES_RESTART_TIMEOUT_MS,
   DOWNLOAD_STUCK_TIMEOUT_MS,
   GLOBAL_OTA_TIMEOUT_MS,
   LEGACY_APK_COMPLETION_SETTLE_MS,
   LEGACY_BES_CONTINUE_LOCKOUT_MS,
+  LEGACY_BES_RESTART_TIMEOUT_MS,
   LEGACY_DOWNLOAD_STUCK_TIMEOUT_MS,
   LEGACY_GLOBAL_OTA_TIMEOUT_MS,
   LEGACY_MTK_INSTALL_TIMEOUT_MS,
@@ -48,18 +48,41 @@ import {
   MTK_INSTALL_TIMEOUT_MS,
   OtaProgressMessages,
   PING_INTERVAL_MS,
-  POST_APK_OTA_START_DELAY_MS,
   PROGRESS_TIMEOUT_MS,
   QUERY_REPLY_TIMEOUT_MS,
   RETRY_INTERVAL_MS,
   isLegacyShapedOtaSession,
   isLegacyShapedOtaStatus,
+  selectOtaProtocolProfile,
+  type OtaProtocolProfile,
 } from "./otaInstallPolicy"
 
 function isTerminalForWatchdog(d: DisplayState): boolean {
   return d === "complete" || d === "failed" || d === "restarting"
 }
 
+function hotspotPreflightErrorMessage(error: unknown): string {
+  const code =
+    typeof error === "object" && error !== null && "code" in error ? String((error as {code: unknown}).code) : ""
+  switch (code) {
+    case "artifact_download_failed":
+      return OtaProgressMessages.hotspotArtifactDownloadFailed
+    case "artifact_verify_failed":
+    case "manifest_invalid":
+      return OtaProgressMessages.hotspotArtifactVerifyFailed
+    case "hotspot_wifi_permission_denied":
+      return OtaProgressMessages.hotspotWifiPermissionDenied
+    case "hotspot_start_failed":
+      return OtaProgressMessages.hotspotStartFailed
+    case "hotspot_join_failed":
+      return OtaProgressMessages.hotspotJoinFailed
+    case "hotspot_server_failed":
+      return OtaProgressMessages.hotspotServerFailed
+    default:
+      return OtaProgressMessages.hotspotServerFailed
+  }
+}
+
 /** Non-empty when glasses are actively reporting work — drives stall timeout reset. */
 function buildProgressStalenessSignature(
   otaStatus: OtaStatus | null,
@@ -134,10 +157,38 @@ export interface OtaInstallSnapshot {
    * +1% ticks up to 60% purely to reassure the user. Render max(real, simulated).
    */
   mtkInstallStallSimulatedPercent: number | null
+  /** True for a downgrade (version-change) session — the UI narrates it differently. */
+  isVersionChange: boolean
+  /** True once the glasses reported the exact pinned target (the downgrade truly completed). */
+  versionChangeConverged: boolean
+  /**
+   * Sub-phase of the downgrade detour for the progress narrative, or null when not
+   * in one: "installing" before the handoff, "restarting" while the glasses are dark
+   * (uninstall / factory flicker / target install), "verifying" once reconnected and
+   * checking the version. Completion is the "complete" displayState.
+   */
+  versionChangePhase: "installing" | "restarting" | "verifying" | null
+  /** Pre-ota_start phone staging/join state for a hotspot attempt. */
+  hotspotPhase: HotspotOtaPhase
+  hotspotArtifactPercent: number | null
+  /** Transport selected from the checked glasses capabilities and Wi-Fi state. */
+  transport: "wifi" | "hotspot"
+}
+
+type OtaStartOutcome = "pending" | "acknowledged" | "rejected"
+
+interface OtaStartOwnership {
+  outcome: OtaStartOutcome
+  promise: Promise<void>
 }
 
 class OtaInstallCoordinator {
   private attached = false
+  private preparedCheckResult: OtaCheckCurrentGlassesResult | null = null
+  private selectedTransport: "wifi" | "hotspot" = "wifi"
+  private hotspotManifestUrl: string | null = null
+  private hotspotPhase: HotspotOtaPhase = "idle"
+  private hotspotArtifactPercent: number | null = null
 
   // Genuinely session-local state (was component state/refs).
   private errorMsg = ""
@@ -157,6 +208,30 @@ class OtaInstallCoordinator {
   private apkExpectedInSession = false
   // Latched when the legacy build-number completion fires; projected as "complete".
   private apkCompletedViaBuildIncrease = false
+  // The split routes selected legacy/unified behavior before navigation. Keep
+  // that choice sticky while an APK step upgrades ASG mid-flow.
+  private protocolProfile: OtaProtocolProfile | null = null
+
+  // BES reboot recovery. Native bridges normalize explicit BES success to a
+  // terminal status; pre-37 flows additionally retain the legacy screen's
+  // lost-FINISHED fallback. Completion still requires a BES-specific observed
+  // disconnect -> reconnect lifecycle, never the generic session reconnect flag.
+  private besRestartExpected = false
+  private besRestartDisconnectObserved = false
+  private besRestartRecovery: "awaiting" | "complete" | null = null
+
+  // Downgrade detour (version-change mode). Captured at attach from the selected
+  // update: the pinned target is a LOWER build, executed by the recovery worker via
+  // uninstall->reinstall, so the phone must NOT drive ota_start on the intermediate
+  // reconnect (the passive factory build) and completion is exact-version
+  // convergence, not a build-number increase.
+  private versionChangeSession = false
+  private versionChangeTarget: number | null = null
+  // Set once ASG reports the apk install has started (the handoff point after which
+  // ASG dies and the recovery worker owns the transaction).
+  private versionChangeInstallStarted = false
+  // Latched when a reconnect reports buildNumber === versionChangeTarget.
+  private versionChangeConverged = false
   // Holds a legacy apk install FINISHED out of "complete" for the settle window.
   private legacyApkSettleHold = false
   // Display-only legacy MTK install stall simulation.
@@ -169,16 +244,22 @@ class OtaInstallCoordinator {
   private retryTimeout: ReturnType<typeof setTimeout> | null = null
   private stuckTimeout: ReturnType<typeof setTimeout> | null = null
   private progressTimeout: ReturnType<typeof setTimeout> | null = null
-  private postApkDelay: ReturnType<typeof setTimeout> | null = null
   private pingInterval: ReturnType<typeof setInterval> | null = null
   private queryReplyTimeout: ReturnType<typeof setTimeout> | null = null
   private continueLockoutTimer: ReturnType<typeof setTimeout> | null = null
+  private restartRecoveryTimeout: ReturnType<typeof setTimeout> | null = null
   private legacyApkSettleTimer: ReturnType<typeof setTimeout> | null = null
   private mtkStallDetectTimer: ReturnType<typeof setTimeout> | null = null
   private mtkSimTickTimer: ReturnType<typeof setInterval> | null = null
 
-  // Retry / ack bookkeeping (no glasses source)
-  private hasReceivedAck = false
+  // Request / retry bookkeeping (no glasses source)
+  // At most one apk-install status poll in flight (native rejects concurrent queries).
+  private apkInstallPollInFlight = false
+  // The native SDK owns one ota_start request until its application-level ack or
+  // timeout. Keep pending ownership across attach/detach, and retain the settled
+  // outcome while attached so Retry/query fallback cannot reinterpret an accepted
+  // command as permission to start a second OTA transaction.
+  private otaStartOwnership: OtaStartOwnership | null = null
   private hasFirstActivity = false
   // Stuck-at-zero watchdog clears only on first NON-ZERO progress; "first activity"
   // alone (e.g. ota_status with stepPercent=0) used to clear it too eagerly.
@@ -206,6 +287,25 @@ class OtaInstallCoordinator {
 
   // --- public surface (engine.ota.installSession) ---
 
+  /** Select the transport at the existing install entry point before the progress route attaches. */
+  prepare(checkResult: OtaCheckCurrentGlassesResult): "wifi" | "hotspot" {
+    const state = useGlassesStore.getState()
+    if (!state.wifiStatusKnown) {
+      throw new Error("Glasses Wi-Fi status is not available")
+    }
+    const hotspotSupported = state.hotspotOtaVersion === 1
+    const wifiConnected = state.wifi.state === "connected"
+    if (!wifiConnected && !hotspotSupported) {
+      throw new Error("Connected glasses require Wi-Fi for OTA")
+    }
+    this.preparedCheckResult = checkResult
+    this.selectedTransport = wifiConnected ? "wifi" : "hotspot"
+    this.hotspotManifestUrl = null
+    this.hotspotPhase = "idle"
+    this.hotspotArtifactPercent = null
+    return this.selectedTransport
+  }
+
   /**
    * Bind the state machine to a mounted progress screen. Idempotent per
    * attach/detach cycle. Runs the initial-mount arbitration (send ota_start
@@ -216,6 +316,18 @@ class OtaInstallCoordinator {
     if (this.attached) return
     this.attached = true
     this.resetSessionState()
+    const initialState = useGlassesStore.getState()
+    this.protocolProfile = selectOtaProtocolProfile(
+      initialState.otaStatus,
+      initialState.otaProgress,
+      initialState.buildNumber,
+    )
+    const selected = initialState.otaUpdateAvailable
+    if (selected?.isDowngrade && typeof selected.versionCode === "number" && selected.versionCode > 0) {
+      this.versionChangeSession = true
+      this.versionChangeTarget = selected.versionCode
+      console.log(`[OTA_PROGRESS] version-change (downgrade) session, target=${selected.versionCode}`)
+    }
     this.prevConnected = isGlassesConnected(useGlassesStore.getState().connection)
     this.storeUnsubscribe = useGlassesStore.subscribe(() => this.react())
     // Mount pass: every reaction block runs once (like all effects on mount),
@@ -246,14 +358,67 @@ class OtaInstallCoordinator {
     }
     GlobalEventEmitter.off("ota_start_ack", this.handleAck)
     GlobalEventEmitter.off("mtk_update_complete", this.handleMtkComplete)
+    GlobalEventEmitter.off("glasses_session_changed", this.handleGlassesSessionChanged)
     this.clearAllOtaTimers()
     this.clearContinueLockoutTimer()
+    // Only native command ownership survives a remount. Once the command has
+    // settled, the glasses store/durable ota_status is the session authority.
+    if (this.otaStartOwnership?.outcome !== "pending") {
+      this.otaStartOwnership = null
+    }
     this.resetSessionState()
   }
 
   /** Retry after a failure: clear state and re-send ota_start (if connected). */
   retry(): void {
-    console.log("[OTA_PROGRESS] retry pressed, clearing state and re-sending ota_start")
+    // While the recovery worker owns the detour (apk install latched, not yet
+    // converged), the phone must not drive: an ota_start now would push the
+    // factory/surviving build into a parallel download-install, and a second
+    // handoff would begin()/REPLACE the live transaction under the running
+    // worker. Retry just re-enters the reconcile wait — convergence or the
+    // session timeout decides the real outcome.
+    if (this.isInVersionChangeDetour()) {
+      console.log("[OTA_PROGRESS] retry during version-change detour — re-entering wait (no ota_start)")
+      this.setErrorMsg("")
+      this.emitInternalChange()
+      return
+    }
+    const store = useGlassesStore.getState()
+    const otaStatus = store.otaStatus
+    const otaProgress = store.otaProgress
+    const authoritativeFailure = otaStatus?.status === "failed" || otaProgress?.status === "FAILED"
+    const hasUnfinishedSession =
+      (!!otaStatus &&
+        otaStatus.status !== "idle" &&
+        otaStatus.status !== "failed" &&
+        otaStatus.status !== "complete") ||
+      (!!otaProgress && otaProgress.status !== "FAILED" && otaProgress.status !== "FINISHED")
+    const shouldReconcile =
+      this.otaStartOwnership?.outcome === "pending" ||
+      (!authoritativeFailure &&
+        (this.otaStartOwnership?.outcome === "acknowledged" || this.hasFirstActivity || hasUnfinishedSession))
+
+    if (shouldReconcile) {
+      console.log("[OTA_PROGRESS] retry pressed for an existing OTA session — reconciling without ota_start")
+      this.clearPerStepTimers()
+      this.clearLegacyApkSettleTimer()
+      this.clearMtkSimulationTimers()
+      this.clearContinueLockoutTimer()
+      this.setErrorMsg("")
+      this.maybeStartGlobalTimeout()
+      this.maybeArmStuckWatchdog()
+      if (isGlassesConnected(store.connection)) {
+        if (this.otaStartOwnership?.outcome === "pending") {
+          void this.sendOtaStartWithWatchdogs()
+        } else {
+          void BluetoothSdk.queryOtaStatus().catch(() => {})
+          this.armQueryReplyFallback("retry")
+        }
+      }
+      return
+    }
+
+    console.log("[OTA_PROGRESS] retry pressed after a rejected or terminal attempt — starting a fresh ota_start")
     // Batch like the old event handler: React ran the whole handler (including
     // the ota_start send) before re-rendering + re-running effects.
     const wasReacting = this.reacting
@@ -262,16 +427,16 @@ class OtaInstallCoordinator {
       this.clearPerStepTimers()
       this.clearLegacyApkSettleTimer()
       this.clearMtkSimulationTimers()
+      this.clearContinueLockoutTimer()
       this.retryCount = 0
-      this.hasFirstActivity = false
-      this.hasReceivedAck = false
+      if (!this.prepareFreshOtaStartAttempt()) return
+      this.resetBesRestartAttempt()
       this.setSawReconnectEdge(false)
       this.setErrorMsg("")
-      this.setApkCompletedViaBuildIncrease(false)
+      this.setContinueButtonDisabled(false)
       this.setLegacyApkSettleHold(false)
       this.setMtkSimulatedPercent(null)
       this.lastRealMtkProgress = 0
-      const store = useGlassesStore.getState()
       store.setOtaProgress(null)
       store.setOtaStatus(null)
       if (isGlassesConnected(useGlassesStore.getState().connection)) {
@@ -288,12 +453,17 @@ class OtaInstallCoordinator {
    * stays in the screen): clear the selected update, and after an APK step
    * clear the stale build number so the next check re-reads version_info.
    */
-  finish(): void {
+  async finish(): Promise<void> {
+    if (this.otaStartOwnership?.outcome !== "pending") {
+      this.otaStartOwnership = null
+    }
     useGlassesStore.getState().setOtaUpdateAvailable(null)
     if (this.apkStepSeen) {
-      BluetoothSdk.updateGlasses({buildNumber: ""})
       useGlassesStore.getState().setGlassesInfo({buildNumber: ""})
     }
+    // The post-install check needs internet again. Do not let callers leave the
+    // terminal screen while Android still owns the no-internet hotspot route.
+    await this.teardownHotspotTransport()
   }
 
   /**
@@ -302,8 +472,8 @@ class OtaInstallCoordinator {
    * deriveDisplayState doesn't resurrect the stale install when the host
    * navigates away and back through /ota routes.
    */
-  discard(): void {
-    this.finish()
+  async discard(): Promise<void> {
+    await this.finish()
     const store = useGlassesStore.getState()
     store.setOtaStatus(null)
     store.setOtaProgress(null)
@@ -323,17 +493,45 @@ class OtaInstallCoordinator {
         sawReconnectEdge: this.sawReconnectEdge,
         legacyApkSettleHold: this.legacyApkSettleHold,
         apkCompletedViaBuildIncrease: this.apkCompletedViaBuildIncrease,
+        besRestartRecovery: this.besRestartRecovery,
+        versionChangeConverged: this.versionChangeConverged,
+        versionChangeSession: this.versionChangeSession,
       }),
       errorMsg: this.errorMsg,
-      continueButtonDisabled: this.continueButtonDisabled,
+      // Keep Continue disabled while the expected BES reboot is still in flight.
+      continueButtonDisabled: this.continueButtonDisabled || this.besRestartRecovery === "awaiting",
       connected,
       // Copies: the snapshot must not hand callers mutable references into the store.
       otaStatus: otaStatus ? {...otaStatus} : null,
       otaProgress: otaProgress ? {...otaProgress} : null,
       mtkInstallStallSimulatedPercent: this.mtkSimulatedPercent,
+      isVersionChange: this.versionChangeSession,
+      versionChangeConverged: this.versionChangeConverged,
+      versionChangePhase: this.deriveVersionChangePhase(connected),
+      hotspotPhase: this.hotspotPhase,
+      hotspotArtifactPercent: this.hotspotArtifactPercent,
+      transport: this.selectedTransport,
     }
   }
 
+  /**
+   * True while the recovery worker owns the downgrade transaction (after the apk install
+   * started, before convergence). During this window ASG is being uninstalled/reinstalled and
+   * cannot answer the phone, so the coordinator must not ping, poll ota_query_status, or arm the
+   * progress-stall watchdog — doing so drives the passive factory build and fails the session
+   * before the target reconnects. Completion is exact-version convergence, detected separately.
+   */
+  private isInVersionChangeDetour(): boolean {
+    return this.versionChangeSession && this.versionChangeInstallStarted && !this.versionChangeConverged
+  }
+
+  /** Downgrade-detour sub-phase for the progress narrative (see OtaInstallSnapshot). */
+  private deriveVersionChangePhase(connected: boolean): "installing" | "restarting" | "verifying" | null {
+    if (!this.versionChangeSession || this.versionChangeConverged) return null
+    if (!this.versionChangeInstallStarted) return "installing"
+    return connected ? "verifying" : "restarting"
+  }
+
   /**
    * Subscribe to install snapshot changes, deduped on the projected JSON.
    * Fires on glasses-store changes AND coordinator-internal state changes
@@ -367,10 +565,16 @@ class OtaInstallCoordinator {
     this.initialBuildNumber = null
     this.apkExpectedInSession = false
     this.apkCompletedViaBuildIncrease = false
+    this.protocolProfile = null
+    this.resetBesRestartAttempt()
+    this.versionChangeSession = false
+    this.versionChangeTarget = null
+    this.versionChangeInstallStarted = false
+    this.versionChangeConverged = false
     this.legacyApkSettleHold = false
     this.mtkSimulatedPercent = null
     this.lastRealMtkProgress = 0
-    this.hasReceivedAck = false
+    this.apkInstallPollInFlight = false
     this.hasFirstActivity = false
     this.hasFirstNonZeroProgress = false
     this.retryCount = 0
@@ -385,6 +589,26 @@ class OtaInstallCoordinator {
     this.reactQueued = false
   }
 
+  /** Begin a genuinely new command attempt only after native ownership has settled. */
+  private prepareFreshOtaStartAttempt(): boolean {
+    if (this.otaStartOwnership?.outcome === "pending") {
+      console.error("[OTA_PROGRESS] refused fresh ota_start while native still owns the previous request")
+      return false
+    }
+    this.otaStartOwnership = null
+    this.hasFirstActivity = false
+    this.hasFirstNonZeroProgress = false
+    this.setApkCompletedViaBuildIncrease(false)
+    return true
+  }
+
+  /** Reset only the reboot lifecycle that belongs to one install attempt. */
+  private resetBesRestartAttempt(): void {
+    this.besRestartExpected = false
+    this.besRestartDisconnectObserved = false
+    this.besRestartRecovery = null
+  }
+
   /** Notify snapshot subscribers of a coordinator-internal state change. */
   private emitInternalChange(): void {
     for (const check of Array.from(this.snapshotCheckers)) check()
@@ -434,18 +658,21 @@ class OtaInstallCoordinator {
     this.emitInternalChange()
   }
 
-  /**
-   * Legacy-session shape (WP 8C): event shape wins once events exist; before any event
-   * only the session-start build number can tell (falls back to the live build number
-   * until it is captured). Old builds get the LEGACY_* padded policy durations.
-   */
+  /** Legacy/unified policy is selected once, matching the old sticky route choice. */
   private isLegacySessionShapeNow(): boolean {
+    if (this.protocolProfile) return this.protocolProfile === "legacy"
     const state = useGlassesStore.getState()
-    return isLegacyShapedOtaSession(
+    const selected = selectOtaProtocolProfile(
       state.otaStatus,
       state.otaProgress,
       this.initialBuildNumber || state.buildNumber,
     )
+    if (selected) {
+      this.protocolProfile = selected
+      console.log(`[OTA_PROGRESS] protocol profile selected: ${selected}`)
+      return selected === "legacy"
+    }
+    return isLegacyShapedOtaSession(state.otaStatus, state.otaProgress, state.buildNumber)
   }
 
   private react(): void {
@@ -498,6 +725,19 @@ class OtaInstallCoordinator {
 
     const legacySession = this.isLegacySessionShapeNow()
 
+    if (this.isBesRestartExpected(otaStatus, otaProgress, legacySession)) {
+      this.besRestartExpected = true
+    }
+
+    // Port the legacy route's actual reboot invariant before deriving display
+    // state, so reconnecting with stale BES in_progress@100 never renders updating.
+    if (connectedChanged && !connected && this.besRestartExpected && this.besRestartRecovery === null) {
+      this.besRestartDisconnectObserved = true
+      this.besRestartRecovery = "awaiting"
+      console.log("[OTA_PROGRESS] BES restart disconnect observed — awaiting reconnect verification")
+    }
+    if (this.besRestartRecovery === "awaiting" && connected) this.completeBesRestartRecovery()
+
     // Derived UI state — the glasses data IS the source of truth.
     const displayState = deriveDisplayState({
       otaStatus,
@@ -507,6 +747,9 @@ class OtaInstallCoordinator {
       sawReconnectEdge: this.sawReconnectEdge,
       legacyApkSettleHold: this.legacyApkSettleHold,
       apkCompletedViaBuildIncrease: this.apkCompletedViaBuildIncrease,
+      besRestartRecovery: this.besRestartRecovery,
+      versionChangeConverged: this.versionChangeConverged,
+      versionChangeSession: this.versionChangeSession,
     })
     const stallSig = buildProgressStalenessSignature(otaStatus, otaProgress, displayState)
     const stallDuration = progressTimeoutDurationMs(otaStatus, otaProgress, legacySession)
@@ -572,6 +815,73 @@ class OtaInstallCoordinator {
       useGlassesStore.getState().setMtkUpdatedThisSession(true)
     }
 
+    // Version-change (downgrade) install started: once ASG reports the apk install
+    // phase, the handoff to the recovery worker has happened. From here the phone
+    // stops driving ota_start (see runConnectEdge) and waits for exact-version
+    // convergence — the wipe means no resumable ASG session and no build increase.
+    if (
+      this.versionChangeSession &&
+      !this.versionChangeInstallStarted &&
+      // Only latch from a status that belongs to THIS session: an install/apk status is a
+      // response to our own acknowledged ota_start, so a leftover from a prior session
+      // sitting in the store at mount cannot prematurely enter the detour wait (which would
+      // suppress ota_start and hang the fresh downgrade until the global timeout).
+      this.otaStartOwnership?.outcome === "acknowledged" &&
+      otaStatus?.stepType === "apk" &&
+      otaStatus.phase === "install"
+    ) {
+      console.log("[OTA_PROGRESS] version-change: apk install started — entering detour wait")
+      this.versionChangeInstallStarted = true
+      this.emitInternalChange()
+    }
+
+    // Ownership refuted: ASG emits install/STARTED BEFORE handing off, so the latch above can
+    // be set even when no transaction ends up owning the detour. Recovery answers every
+    // handoff synchronously, so exactly three error codes prove non-ownership and release the
+    // latch: downgrade_handoff_refused (recovery's explicit verdict),
+    // downgrade_handoff_failed (no verdict at all — recovery dead/missing, so it never began),
+    // and downgrade_transaction_stalled (the long-stop past recovery's own stale give-up).
+    // An accepted-but-slow transaction emits NONE of these (acceptance cancels the short
+    // watchdog), so the latch is never released while a live worker owns the staged artifact
+    // — which recovery additionally claims by rename at acceptance.
+    if (
+      this.versionChangeInstallStarted &&
+      !this.versionChangeConverged &&
+      otaStatus?.status === "failed" &&
+      (otaStatus.error === "downgrade_handoff_refused" ||
+        otaStatus.error === "downgrade_handoff_failed" ||
+        otaStatus.error === "downgrade_transaction_stalled")
+    ) {
+      console.log(
+        `[OTA_PROGRESS] version-change: no transaction owns the detour (${otaStatus.error}) — releasing latch`,
+      )
+      this.versionChangeInstallStarted = false
+      this.emitInternalChange()
+    }
+
+    // Version-change convergence: the reconnected glasses report exactly the pinned
+    // target. This is the ONLY completion signal for a downgrade (lower build, no
+    // increase, wiped session). Mirrors the legacy build-increase latch but by equality.
+    if (
+      this.versionChangeSession &&
+      this.versionChangeInstallStarted &&
+      !this.versionChangeConverged &&
+      this.versionChangeTarget !== null &&
+      buildNumberChanged &&
+      buildNumber
+    ) {
+      const currentBuild = Number.parseInt(buildNumber, 10)
+      if (Number.isFinite(currentBuild) && currentBuild === this.versionChangeTarget) {
+        console.log(`[OTA_PROGRESS] version-change converged: glasses report target ${currentBuild}, completing`)
+        this.clearPerStepTimers()
+        this.clearGlobalTimeout()
+        this.apkStepSeen = true
+        this.setErrorMsg("")
+        this.versionChangeConverged = true
+        this.emitInternalChange()
+      }
+    }
+
     // Legacy APK completion by build-number increase (WP 8C-c): old builds reboot into
     // the new build without a reliable explicit reconnect status; the fresh version_info
     // build number is the completion signal (ported from progress-legacy.tsx, which
@@ -614,7 +924,7 @@ class OtaInstallCoordinator {
 
     /**
      * Connect-edge — the only place that decides to send ota_start /
-     * ota_query_status, handles POST_APK delay, and flips sawReconnectEdge
+     * ota_query_status and flips sawReconnectEdge
      * on the false -> true transition that signals the BES reboot completed.
      */
     if (connectedChanged) {
@@ -628,23 +938,26 @@ class OtaInstallCoordinator {
     if (isMount) {
       GlobalEventEmitter.on("ota_start_ack", this.handleAck)
       GlobalEventEmitter.on("mtk_update_complete", this.handleMtkComplete)
+      GlobalEventEmitter.on("glasses_session_changed", this.handleGlassesSessionChanged)
     }
 
     // Ping keepalive while an OTA is actively running (legacy sessions pinged on the
     // padded interval — old builds slept less eagerly and pings are costlier for them).
     if (connectedChanged || displayStateChanged) {
       this.clearPingInterval()
-      const active = connected && (displayState === "starting" || displayState === "updating")
+      const active =
+        connected && (displayState === "starting" || displayState === "updating") && !this.isInVersionChangeDetour()
       if (active) {
         void BluetoothSdk.ping().catch(() => {})
         const pingIntervalMs = legacySession ? LEGACY_PING_INTERVAL_MS : PING_INTERVAL_MS
         this.pingInterval = setInterval(() => {
           void BluetoothSdk.ping().catch(() => {})
+          this.maybePollApkInstallStatus()
         }, pingIntervalMs)
       }
     }
 
-    // Any glasses activity (ota_status or otaProgress) clears the no-ack retry watchdog.
+    // Any glasses activity proves the logical ota_start was accepted.
     if ((otaStatusChanged || otaProgressChanged) && (otaStatus || otaProgress)) {
       this.onFirstActivity()
     }
@@ -667,7 +980,10 @@ class OtaInstallCoordinator {
     // update that doesn't change the signature keeps the same timer running
     // instead of forever re-extending the deadline.
     if (stallSigChanged || displayStateChanged) {
-      if (displayState !== "starting" && displayState !== "updating") {
+      if (this.isInVersionChangeDetour()) {
+        // Recovery worker owns the transaction; there are no progress events to stall on.
+        this.clearProgressTimeout()
+      } else if (displayState !== "starting" && displayState !== "updating") {
         this.clearProgressTimeout()
       } else if (!stallSig) {
         this.clearProgressTimeout()
@@ -685,20 +1001,24 @@ class OtaInstallCoordinator {
 
     // Lockout on Continue button after BES restart to prevent accidental tap
     // (15s unified, 35s for legacy-shaped sessions — WP 8C-f).
-    if (displayStateChanged) {
+    if (displayStateChanged && displayState === "restarting") {
       this.clearContinueLockoutTimer()
-      if (displayState === "restarting") {
-        const lockoutMs = legacySession ? LEGACY_BES_CONTINUE_LOCKOUT_MS : BES_CONTINUE_LOCKOUT_MS
-        this.setContinueButtonDisabled(true)
-        this.continueLockoutTimer = setTimeout(() => {
-          this.continueLockoutTimer = null
-          this.setContinueButtonDisabled(false)
-        }, lockoutMs)
-      }
-    }
-
-    if (displayStateChanged && displayState === "failed") {
-      this.clearPerStepTimers()
+      this.clearRestartRecoveryTimeout()
+      const lockoutMs = legacySession ? LEGACY_BES_CONTINUE_LOCKOUT_MS : BES_CONTINUE_LOCKOUT_MS
+      const restartTimeoutMs = legacySession ? LEGACY_BES_RESTART_TIMEOUT_MS : BES_RESTART_TIMEOUT_MS
+      this.setContinueButtonDisabled(true)
+      this.continueLockoutTimer = setTimeout(() => {
+        this.continueLockoutTimer = null
+        this.setContinueButtonDisabled(false)
+      }, lockoutMs)
+      this.restartRecoveryTimeout = setTimeout(() => {
+        this.restartRecoveryTimeout = null
+        if (this.computeDisplayStateNow() !== "restarting") return
+        console.log(`[OTA_PROGRESS] watchdog: glasses did not finish restarting in ${restartTimeoutMs}ms`)
+        this.setErrorMsg(OtaProgressMessages.restartTimeout)
+      }, restartTimeoutMs)
+    } else if (displayStateChanged) {
+      this.clearRestartRecoveryTimeout()
     }
 
     // Legacy MTK install stall simulation (WP 8C-e): display-only. The simulation
@@ -716,8 +1036,54 @@ class OtaInstallCoordinator {
       displayStateChanged &&
       (displayState === "complete" || displayState === "restarting" || displayState === "failed")
     ) {
+      if (displayState === "failed") {
+        this.clearPerStepTimers()
+      }
       useGlassesStore.getState().setOtaUpdateAvailable(null)
+      if (displayState === "complete" || displayState === "failed") {
+        void this.teardownHotspotTransport()
+      }
+    }
+  }
+
+  /**
+   * Reconnect arbitration shared by the physical BLE connect edge and the
+   * glasses_session_changed signal. The latter exists because the BES keeps the BLE
+   * link alive across asg_client restarts (APK OTA): no physical edge ever fires, so
+   * the changed process session id is the only reconnect signal the coordinator gets
+   * (incident rep_01KY6BJ0B7A4RBMQ7VN39KAE5E). Always returns true (the caller's
+   * edge handling is complete).
+   */
+  private runReconnectArbitration(label: string): boolean {
+    console.log(`[OTA_PROGRESS] ${label}: false->true, flipping sawReconnectEdge=true`)
+    // A physical reconnect passed through the disconnect branch first, which cleared
+    // these timers; a session-change edge never disconnects, so a fallback armed by an
+    // earlier mount/query could otherwise fire alongside the arbitration below and send
+    // a duplicate ota_start. Clearing here is a no-op on the physical path.
+    this.clearQueryReplyTimeout()
+    this.setSawReconnectEdge(true)
+
+    if (this.besRestartDisconnectObserved) {
+      console.log(`[OTA_PROGRESS] ${label}: BES reboot reconnect observed — no ota_query_status`)
+      this.completeBesRestartRecovery()
+      return true
+    }
+
+    // Legacy apk settle window (WP 8C): the glasses restarting into the new build is
+    // the EXPECTED reconnect here — the legacy screen took no action on it. Skip the
+    // query/fallback; the settle timer (or the build-number increase) completes.
+    if (this.legacyApkSettleHold) {
+      console.log(`[OTA_PROGRESS] ${label}: reconnect during legacy apk settle hold — no query`)
+      return true
+    }
+
+    console.log(`[OTA_PROGRESS] ${label}: reconnected, sending ota_query_status`)
+    if (this.otaStartOwnership?.outcome === "pending") {
+      void this.sendOtaStartWithWatchdogs()
     }
+    void BluetoothSdk.queryOtaStatus().catch(() => {})
+    this.armQueryReplyFallback("reconnect")
+    return true
   }
 
   private runConnectEdge(connected: boolean): void {
@@ -726,54 +1092,30 @@ class OtaInstallCoordinator {
 
     if (!connected) {
       console.log("[OTA_PROGRESS] connect-edge: disconnected")
-      this.clearPostApkDelay()
-      // Also drop a pending query-reply fallback: firing ota_start into a dead
-      // link can only produce a false "failed" state, and the reconnect edge
-      // re-queries and re-arms this fallback anyway.
+      // Also drop pending query/retry sends: firing ota_start into a dead link
+      // can only produce a false "failed" state. Reconnect arbitration first
+      // queries durable status and re-arms the one permitted fallback.
       this.clearQueryReplyTimeout()
+      this.clearRetryTimeout()
       return
     }
 
     const becameConnected = prev === false && connected === true
-    if (becameConnected) {
-      console.log("[OTA_PROGRESS] connect-edge: false->true, flipping sawReconnectEdge=true")
-      this.setSawReconnectEdge(true)
-    }
-
-    // Legacy apk settle window (WP 8C): the glasses restarting into the new build is
-    // the EXPECTED reconnect here — the legacy screen took no action on it. Skip the
-    // query/fallback; the settle timer (or the build-number increase) completes.
-    if (becameConnected && this.legacyApkSettleHold) {
-      console.log("[OTA_PROGRESS] connect-edge: reconnect during legacy apk settle hold — no query")
+    if (becameConnected && this.runReconnectArbitration("connect-edge")) {
       return
     }
 
-    const storeState = useGlassesStore.getState()
-    const s = storeState.otaStatus
-    const postApkAwaiting =
-      s?.stepType === "apk" && (s?.totalSteps ?? 0) > 1 && (s.status === "step_complete" || s.status === "complete")
-
-    if (becameConnected && postApkAwaiting) {
-      console.log("[OTA_PROGRESS] connect-edge: post-APK reboot detected, arming POST_APK delay for sendOtaStart")
-      this.clearPostApkDelay()
-      this.postApkDelay = setTimeout(() => {
-        this.postApkDelay = null
-        this.retryCount = 0
-        this.hasFirstActivity = false
-        this.hasFirstNonZeroProgress = false
-        this.hasReceivedAck = false
-        console.log("[OTA_PROGRESS] POST_APK delay fired, sending ota_start")
-        void this.sendOtaStartWithWatchdogs()
-      }, POST_APK_OTA_START_DELAY_MS)
+    // Version-change detour: after the install started, EVERY reconnect is expected
+    // (the passive factory build, then the target). Do NOT send ota_start/query — the
+    // factory build would treat the pin as a plain upgrade and start a redundant
+    // download racing the recovery worker. Convergence (buildNumber === target) is
+    // detected in the reaction pass; here we simply take no action.
+    if (this.versionChangeSession && this.versionChangeInstallStarted && !this.versionChangeConverged) {
+      console.log("[OTA_PROGRESS] connect-edge: reconnect during version-change detour — no query (expected)")
       return
     }
 
-    if (becameConnected) {
-      console.log("[OTA_PROGRESS] connect-edge: reconnected, sending ota_query_status")
-      void BluetoothSdk.sendOtaQueryStatus()
-      this.armQueryReplyFallback("reconnect")
-      return
-    }
+    const storeState = useGlassesStore.getState()
 
     // Initial mount (prev === current === true). If no session yet, kick off ota_start.
     // An idle ota_status has an empty sessionId; treat it as no session so ota_start
@@ -781,19 +1123,25 @@ class OtaInstallCoordinator {
     const isIdleStatus = !!storeState.otaStatus && storeState.otaStatus.sessionId === ""
     const noSessionYet = (!storeState.otaStatus && !storeState.otaProgress) || isIdleStatus
     if (noSessionYet) {
+      if (!isIdleStatus && this.otaStartOwnership?.outcome === "acknowledged") {
+        console.log("[OTA_PROGRESS] initial mount, acknowledged session has no cached status — reconciling")
+        void BluetoothSdk.queryOtaStatus().catch(() => {})
+        this.armQueryReplyFallback("initial-mount")
+        return
+      }
       console.log(
         isIdleStatus
           ? "[OTA_PROGRESS] initial mount, idle status (no sessionId), sending ota_start"
           : "[OTA_PROGRESS] initial mount, no session in store, sending ota_start",
       )
       this.retryCount = 0
-      this.hasFirstActivity = false
-      this.hasFirstNonZeroProgress = false
-      this.hasReceivedAck = false
+      if (isIdleStatus && this.otaStartOwnership?.outcome !== "pending" && !this.prepareFreshOtaStartAttempt()) {
+        return
+      }
       void this.sendOtaStartWithWatchdogs()
     } else {
       console.log("[OTA_PROGRESS] initial mount, session exists, sending ota_query_status")
-      void BluetoothSdk.sendOtaQueryStatus()
+      void BluetoothSdk.queryOtaStatus().catch(() => {})
       this.armQueryReplyFallback("initial-mount")
     }
   }
@@ -801,18 +1149,28 @@ class OtaInstallCoordinator {
   // --- BLE OTA event listeners (engine GlobalEventEmitter, fed by OtaService) ---
 
   private readonly handleAck = (): void => {
-    if (this.hasReceivedAck) return
+    const ownership = this.otaStartOwnership
+    if (!ownership || ownership.outcome === "rejected") return
+    if (ownership.outcome === "acknowledged") return
     console.log("[OTA_PROGRESS] ota_start_ack received")
-    this.hasReceivedAck = true
+    ownership.outcome = "acknowledged"
     this.clearRetryTimeout()
   }
 
+  /**
+   * The asg process restarted while the BES kept the BLE link up (sid change observed
+   * by the bridge): treat it exactly like a physical reconnect edge.
+   */
+  private readonly handleGlassesSessionChanged = (): void => {
+    this.runReconnectArbitration("session-change")
+  }
+
   private readonly handleMtkComplete = (): void => {
     console.log("[OTA_PROGRESS] mtk_update_complete received")
     this.clearProgressTimeout()
     this.onFirstActivity()
     this.onFirstNonZeroProgress()
-    void BluetoothSdk.sendOtaQueryStatus()
+    void BluetoothSdk.queryOtaStatus().catch(() => {})
     useGlassesStore.getState().setMtkUpdatedThisSession(true)
   }
 
@@ -834,7 +1192,9 @@ class OtaInstallCoordinator {
     }
 
     if (this.errorMsg) {
-      console.log("[OTA_PROGRESS] legacy install complete arrived after a failure — completing (legacy last-write-wins)")
+      console.log(
+        "[OTA_PROGRESS] legacy install complete arrived after a failure — completing (legacy last-write-wins)",
+      )
       this.setErrorMsg("")
       this.clearLegacyApkSettleTimer()
       this.setLegacyApkSettleHold(false)
@@ -860,6 +1220,43 @@ class OtaInstallCoordinator {
     }
   }
 
+  private isBesRestartExpected(
+    otaStatus: OtaStatus | null,
+    otaProgress: OtaProgress | null,
+    legacySession: boolean,
+  ): boolean {
+    const statusReadyToRestart =
+      otaStatus?.stepType === "bes" &&
+      otaStatus.phase === "install" &&
+      (otaStatus.status === "step_complete" || otaStatus.status === "complete")
+    const progressReadyToRestart =
+      legacySession &&
+      otaProgress?.currentUpdate === "bes" &&
+      otaProgress.stage === "install" &&
+      otaProgress.status === "FINISHED"
+
+    // progress-legacy treated a BES disconnect during active installation as the
+    // expected power cycle even when its terminal FINISHED event was lost. Keep
+    // that fallback only for the sticky pre-37 profile selected when the flow began.
+    const legacyInstallInProgress =
+      legacySession &&
+      ((otaStatus?.stepType === "bes" && otaStatus.phase === "install" && otaStatus.status === "in_progress") ||
+        (otaProgress?.currentUpdate === "bes" &&
+          otaProgress.stage === "install" &&
+          (otaProgress.status === "STARTED" || otaProgress.status === "PROGRESS")))
+    return statusReadyToRestart || progressReadyToRestart || legacyInstallInProgress
+  }
+
+  /** Complete only after a protocol-authorized BES restart traverses disconnect -> reconnect. */
+  private completeBesRestartRecovery(): void {
+    if (!this.besRestartDisconnectObserved || this.besRestartRecovery !== "awaiting") return
+    console.log("[OTA_PROGRESS] BES restart reconnected — completing by reboot edge")
+    this.clearPerStepTimers()
+    this.setErrorMsg("")
+    this.besRestartRecovery = "complete"
+    this.emitInternalChange()
+  }
+
   /**
    * Legacy MTK install stall simulation (WP 8C-e), ported verbatim: the MTK system
    * install typically stalls around 49-50%. Every real event restarts stall detection;
@@ -935,17 +1332,54 @@ class OtaInstallCoordinator {
       sawReconnectEdge: this.sawReconnectEdge,
       legacyApkSettleHold: this.legacyApkSettleHold,
       apkCompletedViaBuildIncrease: this.apkCompletedViaBuildIncrease,
+      besRestartRecovery: this.besRestartRecovery,
+      versionChangeConverged: this.versionChangeConverged,
+      versionChangeSession: this.versionChangeSession,
     })
   }
 
   /**
-   * "Glasses are talking to us" — clears the no-ack retry watchdog only.
+   * During an APK install the package installer kills and restarts the glasses
+   * process, and the new process's completion push can lose its startup race
+   * against the UART transport (incident rep_01KY31HEMTSBSMK8DVMNXJ5XGG: the
+   * phone sat on a stale "install in_progress 0%" until the stall watchdog
+   * failed a successful update). The persisted session on the glasses always
+   * knows the truth, so poll ota_query_status on the keepalive tick while an
+   * apk step sits in its install phase — the reply either confirms progress or
+   * delivers the missed completion. Gated to the apk install phase so a stray
+   * idle reply can't disturb an active download; legacy (< 37) builds ignore
+   * the query, which is harmless.
+   *
+   * The native query pends up to 15s and rejects a concurrent call with
+   * request_in_flight — longer than the 10s tick — so exactly one poll is kept
+   * in flight (the glasses being slow to answer IS the silent-restart window
+   * this poll exists for) and rejections are swallowed: the next tick retries.
+   */
+  private maybePollApkInstallStatus(): void {
+    if (this.isInVersionChangeDetour()) return
+    if (this.apkInstallPollInFlight) return
+    const s = useGlassesStore.getState().otaStatus
+    if (s?.stepType === "apk" && s.phase === "install" && s.status === "in_progress") {
+      this.apkInstallPollInFlight = true
+      void BluetoothSdk.queryOtaStatus()
+        .catch(() => {})
+        .finally(() => {
+          this.apkInstallPollInFlight = false
+        })
+    }
+  }
+
+  /**
+   * "Glasses are talking to us" — suppresses retry if the native request later rejects.
    * Important: this does NOT clear the stuck-at-zero watchdog; that one fires
    * on real progress > 0% (see {@link onFirstNonZeroProgress}).
    */
   private onFirstActivity(): void {
     if (this.hasFirstActivity) return
     this.hasFirstActivity = true
+    if (this.otaStartOwnership?.outcome === "pending") {
+      this.otaStartOwnership.outcome = "acknowledged"
+    }
     this.clearRetryTimeout()
   }
 
@@ -968,7 +1402,8 @@ class OtaInstallCoordinator {
     // Legacy-shape check happens once, when the session cap is armed at the first
     // ota_start send (WP 8C-b): old builds get the padded legacy cap for the whole
     // session; a session that starts unified keeps the unified cap.
-    const globalTimeoutMs = this.isLegacySessionShapeNow() ? LEGACY_GLOBAL_OTA_TIMEOUT_MS : GLOBAL_OTA_TIMEOUT_MS
+    const globalTimeoutMs =
+      this.versionChangeSession || this.isLegacySessionShapeNow() ? LEGACY_GLOBAL_OTA_TIMEOUT_MS : GLOBAL_OTA_TIMEOUT_MS
     this.globalTimeout = setTimeout(() => {
       this.globalTimeout = null
       this.globalTimeoutStarted = false
@@ -984,37 +1419,14 @@ class OtaInstallCoordinator {
     }, globalTimeoutMs)
   }
 
-  private armAckAndStuckWatchdogsOnly(): void {
-    this.clearRetryTimeout()
+  private armStuckWatchdogOnly(): void {
     this.clearStuckTimeout()
 
     // Durations resolved at arm time (WP 8C-b): legacy-shaped sessions get the
     // padded values progress-legacy.tsx used for old (< 37) builds.
     const legacySession = this.isLegacySessionShapeNow()
-    const retryIntervalMs = legacySession ? LEGACY_RETRY_INTERVAL_MS : RETRY_INTERVAL_MS
     const stuckTimeoutMs = legacySession ? LEGACY_DOWNLOAD_STUCK_TIMEOUT_MS : DOWNLOAD_STUCK_TIMEOUT_MS
 
-    this.retryTimeout = setTimeout(() => {
-      this.retryTimeout = null
-      if (this.hasReceivedAck || this.hasFirstActivity) return
-      if (this.computeDisplayStateNow() !== "starting") return
-      if (this.retryCount < MAX_RETRIES - 1) {
-        this.retryCount += 1
-        this.hasReceivedAck = false
-        console.log(
-          `[OTA_PROGRESS] watchdog: no ack in ${retryIntervalMs}ms, retrying ota_start (attempt ${this.retryCount})`,
-        )
-        void this.sendOtaStartWithWatchdogs(true)
-          .then(() => {
-            this.armAckAndStuckWatchdogsOnly()
-          })
-          .catch(() => {})
-      } else {
-        console.log(`[OTA_PROGRESS] watchdog: ota_start ack never received after ${MAX_RETRIES} attempts, failing`)
-        this.setErrorMsg(OtaProgressMessages.noAckResponse)
-      }
-    }, retryIntervalMs)
-
     this.stuckTimeout = setTimeout(() => {
       this.stuckTimeout = null
       const d = this.computeDisplayStateNow()
@@ -1030,26 +1442,130 @@ class OtaInstallCoordinator {
     }, stuckTimeoutMs)
   }
 
-  private async sendOtaStartWithWatchdogs(retryAlreadyCounted = false): Promise<void> {
+  /** Arm the 0%-stuck watchdog only when this logical session has none. */
+  private maybeArmStuckWatchdog(): void {
+    if (this.stuckTimeout || this.hasFirstNonZeroProgress) return
+    this.armStuckWatchdogOnly()
+  }
+
+  private sendOtaStartWithWatchdogs(): Promise<void> {
+    // INVARIANT BACKSTOP — not normal control flow. Every entry point that can drive the
+    // glasses (connect-edge, query fallback, retry, mount) carries its own detour gate with the
+    // right behavior for that site; this final check only exists so that a FUTURE entry point
+    // that forgets its gate degrades to a refused send + loud log instead of a corrupted
+    // transaction (an ota_start mid-detour starts a parallel install on the factory build and
+    // can trigger a second handoff). If this ever fires, a missed site gate exists — fix it.
+    if (this.isInVersionChangeDetour()) {
+      console.error(
+        "[OTA_PROGRESS] BACKSTOP: refused ota_start during a latched version-change detour — a caller is missing its detour gate",
+      )
+      return Promise.resolve()
+    }
+    const existingOwnership = this.otaStartOwnership
+    if (existingOwnership?.outcome === "pending") {
+      this.maybeStartGlobalTimeout()
+      if (this.selectedTransport === "wifi" || this.hotspotManifestUrl) this.maybeArmStuckWatchdog()
+      console.log("[OTA_PROGRESS] ota_start already pending — adopting existing native request")
+      return existingOwnership.promise
+    }
+    if (existingOwnership?.outcome === "acknowledged") {
+      this.maybeStartGlobalTimeout()
+      this.maybeArmStuckWatchdog()
+      console.log("[OTA_PROGRESS] ota_start already acknowledged — refusing duplicate start")
+      return Promise.resolve()
+    }
+    if (existingOwnership?.outcome === "rejected" && !this.prepareFreshOtaStartAttempt()) {
+      return Promise.resolve()
+    }
     this.maybeStartGlobalTimeout()
-    this.hasReceivedAck = false
-    this.armAckAndStuckWatchdogsOnly()
+    if (this.selectedTransport === "wifi" || this.hotspotManifestUrl) this.maybeArmStuckWatchdog()
+
+    const ownership: OtaStartOwnership = {
+      outcome: "pending",
+      promise: Promise.resolve(),
+    }
+    ownership.promise = this.performOtaStart(ownership)
+    this.otaStartOwnership = ownership
+    return ownership.promise
+  }
+
+  private async performOtaStart(ownership: OtaStartOwnership): Promise<void> {
+    let nativeStartAttempted = false
     try {
       const state = useGlassesStore.getState()
-      const otaVersionUrl = getAsgOtaVersionUrl(state.otaVersionUrl, state.buildNumber)
-      console.log(`[OTA_PROGRESS] sending ota_start with manifest URL: ${otaVersionUrl}`)
+      let otaVersionUrl = resolveOtaManifestUrl(state.otaVersionUrl, state.buildNumber)
+      if (this.selectedTransport === "hotspot") {
+        if (!this.hotspotManifestUrl) {
+          if (!this.preparedCheckResult) {
+            throw new Error("No selected OTA check is available for hotspot staging")
+          }
+          this.hotspotManifestUrl = await hotspotOtaTransport.prepare(this.preparedCheckResult, (progress) => {
+            this.hotspotPhase = progress.phase
+            this.hotspotArtifactPercent = progress.artifact?.artifactPercent ?? null
+            this.emitInternalChange()
+          })
+        }
+        otaVersionUrl = this.hotspotManifestUrl
+        this.maybeArmStuckWatchdog()
+      }
+      if (!otaVersionUrl) {
+        throw new Error("OTA is disabled because this build has no immutable manifest pin")
+      }
+      console.log(`[OTA_PROGRESS] sending ota_start with ${this.selectedTransport} manifest URL: ${otaVersionUrl}`)
+      nativeStartAttempted = true
       await BluetoothSdk.startOtaUpdate(otaVersionUrl)
+      if (this.otaStartOwnership !== ownership) return
+      // The public SDK promise resolves only from ota_start_ack. Treat that
+      // resolution as the acknowledgement even if the parallel event dispatch
+      // reaches the coordinator later (or is dropped by a remount).
+      this.handleAck()
     } catch (err) {
       console.warn("[OTA_PROGRESS] sendOtaStart threw", err)
-      this.clearRetryTimeout()
+
+      if (this.otaStartOwnership !== ownership) return
+
+      if (this.selectedTransport === "hotspot" && !nativeStartAttempted) {
+        ownership.outcome = "rejected"
+        this.clearStuckTimeout()
+        await this.teardownHotspotTransport()
+        if (this.attached) this.setErrorMsg(hotspotPreflightErrorMessage(err))
+        return
+      }
+
+      // A received ota_status/legacy progress event, or the exact legacy APK
+      // build-number proof, proves that this logical start was accepted. Its
+      // application-level ack may be lost while the update continues; never
+      // create another transaction or fail a live, restarting, or completed
+      // session because that stale promise timed out.
+      if (this.hasFirstActivity || this.apkCompletedViaBuildIncrease) {
+        ownership.outcome = "acknowledged"
+        console.log("[OTA_PROGRESS] ota_start rejection arrived after acceptance proof — ignoring stale rejection")
+        return
+      }
+
+      ownership.outcome = "rejected"
+      if (!this.attached) return
       this.clearStuckTimeout()
+      if (!isGlassesConnected(useGlassesStore.getState().connection)) {
+        console.log(
+          "[OTA_PROGRESS] ota_start request ended while disconnected; deferring retry to reconnect arbitration",
+        )
+        return
+      }
       if (this.retryCount < MAX_RETRIES - 1) {
-        if (!retryAlreadyCounted) {
-          this.retryCount += 1
-        }
+        this.retryCount += 1
         const retryIntervalMs = this.isLegacySessionShapeNow() ? LEGACY_RETRY_INTERVAL_MS : RETRY_INTERVAL_MS
+        console.log(
+          `[OTA_PROGRESS] ota_start request ended without ack or activity; retrying after ${retryIntervalMs}ms (attempt ${
+            this.retryCount + 1
+          }/${MAX_RETRIES})`,
+        )
         this.retryTimeout = setTimeout(() => {
           this.retryTimeout = null
+          if (!isGlassesConnected(useGlassesStore.getState().connection)) {
+            console.log("[OTA_PROGRESS] ota_start retry paused while disconnected; reconnect arbitration will resume")
+            return
+          }
           void this.sendOtaStartWithWatchdogs()
         }, retryIntervalMs)
       } else {
@@ -1059,18 +1575,28 @@ class OtaInstallCoordinator {
     }
   }
 
+  private async teardownHotspotTransport(): Promise<void> {
+    if (this.selectedTransport !== "hotspot" && !this.hotspotManifestUrl) return
+    await hotspotOtaTransport.teardown()
+    this.hotspotManifestUrl = null
+    this.hotspotPhase = "idle"
+    this.hotspotArtifactPercent = null
+    this.emitInternalChange()
+  }
+
   /**
    * After sending ota_query_status, wait QUERY_REPLY_TIMEOUT_MS for the glasses
-   * to reply with a useful ota_status. If nothing arrives (e.g. the glasses'
-   * OTA session was wiped between mount and reconnect), or the glasses reply
-   * with an explicit "idle" status (no session), fall back to ota_start so the
-   * user doesn't sit on a spinner forever.
+   * to reply with a useful ota_status. A unified session may start again only
+   * after an explicit "idle" reply, or after a locally rejected ota_start has
+   * produced no activity and no authoritative reply across reconnect. Legacy
+   * builds ignore ota_query_status, so their established timeout fallback
+   * remains the compatibility path.
    *
    * Cleared as soon as a non-idle otaStatus or any otaProgress lands in the
    * store (see the reaction block above). An idle reply intentionally does NOT
    * cancel the fallback, so reconnects against a wiped/lost session still recover.
    */
-  private armQueryReplyFallback(reason: "reconnect" | "initial-mount"): void {
+  private armQueryReplyFallback(reason: "reconnect" | "initial-mount" | "retry"): void {
     this.clearQueryReplyTimeout()
     this.queryReplyTimeout = setTimeout(() => {
       this.queryReplyTimeout = null
@@ -1081,21 +1607,24 @@ class OtaInstallCoordinator {
       // whatever legacy-shaped status/progress sits in the store is a pre-query
       // leftover, not a reply — a NEW legacy event would have cleared this timer
       // through the reaction pass. Only a unified reply suppresses the fallback.
-      const legacySession = isLegacyShapedOtaSession(
-        state.otaStatus,
-        state.otaProgress,
-        this.initialBuildNumber || state.buildNumber,
-      )
+      const legacySession = this.isLegacySessionShapeNow()
       if (!legacySession && hasRecoveringOtaReply(state.otaStatus, state.otaProgress)) return
+      const explicitIdle = state.otaStatus?.status === "idle"
+      const rejectedStart = this.otaStartOwnership?.outcome === "rejected"
+      if (!legacySession && !explicitIdle && !rejectedStart) {
+        console.log(
+          `[OTA_PROGRESS] watchdog: ota_query_status got no authoritative idle reply in ${QUERY_REPLY_TIMEOUT_MS}ms (reason=${reason}); preserving the existing session`,
+        )
+        return
+      }
       // Don't fire if we've left the active phase (e.g. user backed out, error overlay).
       if (isTerminalForWatchdog(this.computeDisplayStateNow())) return
-      console.log(
-        `[OTA_PROGRESS] watchdog: ota_query_status got no useful reply in ${QUERY_REPLY_TIMEOUT_MS}ms (reason=${reason}), falling back to ota_start`,
-      )
+      let fallbackCause = "legacy query timeout"
+      if (explicitIdle) fallbackCause = "idle ota_status"
+      else if (rejectedStart) fallbackCause = "rejected ota_start with no recovery reply"
+      console.log(`[OTA_PROGRESS] watchdog: ${fallbackCause} (reason=${reason}), falling back to ota_start`)
       this.retryCount = 0
-      this.hasFirstActivity = false
-      this.hasFirstNonZeroProgress = false
-      this.hasReceivedAck = false
+      if (this.otaStartOwnership?.outcome !== "pending" && !this.prepareFreshOtaStartAttempt()) return
       void this.sendOtaStartWithWatchdogs()
     }, QUERY_REPLY_TIMEOUT_MS)
   }
@@ -1131,13 +1660,6 @@ class OtaInstallCoordinator {
     this.globalTimeoutStarted = false
   }
 
-  private clearPostApkDelay(): void {
-    if (this.postApkDelay) {
-      clearTimeout(this.postApkDelay)
-      this.postApkDelay = null
-    }
-  }
-
   private clearPingInterval(): void {
     if (this.pingInterval) {
       clearInterval(this.pingInterval)
@@ -1159,6 +1681,13 @@ class OtaInstallCoordinator {
     }
   }
 
+  private clearRestartRecoveryTimeout(): void {
+    if (this.restartRecoveryTimeout) {
+      clearTimeout(this.restartRecoveryTimeout)
+      this.restartRecoveryTimeout = null
+    }
+  }
+
   private clearLegacyApkSettleTimer(): void {
     if (this.legacyApkSettleTimer) {
       clearTimeout(this.legacyApkSettleTimer)
@@ -1188,7 +1717,6 @@ class OtaInstallCoordinator {
     this.clearRetryTimeout()
     this.clearStuckTimeout()
     this.clearProgressTimeout()
-    this.clearPostApkDelay()
     this.clearQueryReplyTimeout()
   }
 
@@ -1198,6 +1726,7 @@ class OtaInstallCoordinator {
     this.clearPingInterval()
     this.clearLegacyApkSettleTimer()
     this.clearMtkSimulationTimers()
+    this.clearRestartRecoveryTimeout()
   }
 }