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

package/build/services/OtaInstallCoordinator.js

@@ -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,24 +11,42 @@
  * `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 BluetoothSdk 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 } from "./HotspotOtaTransport";
 import { deriveDisplayState } from "./otaDisplayState";
-import { BES_CONTINUE_LOCKOUT_MS, DOWNLOAD_STUCK_TIMEOUT_MS, GLOBAL_OTA_TIMEOUT_MS, LEGACY_APK_COMPLETION_SETTLE_MS, LEGACY_BES_CONTINUE_LOCKOUT_MS, LEGACY_DOWNLOAD_STUCK_TIMEOUT_MS, LEGACY_GLOBAL_OTA_TIMEOUT_MS, LEGACY_MTK_INSTALL_TIMEOUT_MS, LEGACY_MTK_SIM_CAP_PERCENT, LEGACY_MTK_SIM_FLOOR_PERCENT, LEGACY_MTK_SIM_TICK_MS, LEGACY_MTK_STALL_DETECT_MS, LEGACY_MTK_STALL_ZONE_MAX_PERCENT, LEGACY_MTK_STALL_ZONE_MIN_PERCENT, LEGACY_PING_INTERVAL_MS, LEGACY_PROGRESS_TIMEOUT_MS, LEGACY_RETRY_INTERVAL_MS, MAX_RETRIES, 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, } from "./otaInstallPolicy";
+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, LEGACY_MTK_SIM_CAP_PERCENT, LEGACY_MTK_SIM_FLOOR_PERCENT, LEGACY_MTK_SIM_TICK_MS, LEGACY_MTK_STALL_DETECT_MS, LEGACY_MTK_STALL_ZONE_MAX_PERCENT, LEGACY_MTK_STALL_ZONE_MIN_PERCENT, LEGACY_PING_INTERVAL_MS, LEGACY_PROGRESS_TIMEOUT_MS, LEGACY_RETRY_INTERVAL_MS, MAX_RETRIES, MTK_INSTALL_TIMEOUT_MS, OtaProgressMessages, PING_INTERVAL_MS, PROGRESS_TIMEOUT_MS, QUERY_REPLY_TIMEOUT_MS, RETRY_INTERVAL_MS, isLegacyShapedOtaSession, isLegacyShapedOtaStatus, selectOtaProtocolProfile, } from "./otaInstallPolicy";
 function isTerminalForWatchdog(d) {
     return d === "complete" || d === "failed" || d === "restarting";
 }
+function hotspotPreflightErrorMessage(error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? String(error.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, otaProgress, displayState) {
     if (displayState !== "starting" && displayState !== "updating")
@@ -80,6 +98,11 @@ function hasRecoveringOtaReply(otaStatus, otaProgress) {
 }
 class OtaInstallCoordinator {
     attached = false;
+    preparedCheckResult = null;
+    selectedTransport = "wifi";
+    hotspotManifestUrl = null;
+    hotspotPhase = "idle";
+    hotspotArtifactPercent = null;
     // Genuinely session-local state (was component state/refs).
     errorMsg = "";
     sawReconnectEdge = false;
@@ -97,6 +120,28 @@ class OtaInstallCoordinator {
     apkExpectedInSession = false;
     // Latched when the legacy build-number completion fires; projected as "complete".
     apkCompletedViaBuildIncrease = false;
+    // The split routes selected legacy/unified behavior before navigation. Keep
+    // that choice sticky while an APK step upgrades ASG mid-flow.
+    protocolProfile = 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.
+    besRestartExpected = false;
+    besRestartDisconnectObserved = false;
+    besRestartRecovery = 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.
+    versionChangeSession = false;
+    versionChangeTarget = null;
+    // Set once ASG reports the apk install has started (the handoff point after which
+    // ASG dies and the recovery worker owns the transaction).
+    versionChangeInstallStarted = false;
+    // Latched when a reconnect reports buildNumber === versionChangeTarget.
+    versionChangeConverged = false;
     // Holds a legacy apk install FINISHED out of "complete" for the settle window.
     legacyApkSettleHold = false;
     // Display-only legacy MTK install stall simulation.
@@ -108,15 +153,21 @@ class OtaInstallCoordinator {
     retryTimeout = null;
     stuckTimeout = null;
     progressTimeout = null;
-    postApkDelay = null;
     pingInterval = null;
     queryReplyTimeout = null;
     continueLockoutTimer = null;
+    restartRecoveryTimeout = null;
     legacyApkSettleTimer = null;
     mtkStallDetectTimer = null;
     mtkSimTickTimer = null;
-    // Retry / ack bookkeeping (no glasses source)
-    hasReceivedAck = false;
+    // Request / retry bookkeeping (no glasses source)
+    // At most one apk-install status poll in flight (native rejects concurrent queries).
+    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.
+    otaStartOwnership = null;
     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.
@@ -138,6 +189,24 @@ class OtaInstallCoordinator {
     storeUnsubscribe = null;
     snapshotCheckers = new Set();
     // --- public surface (engine.ota.installSession) ---
+    /** Select the transport at the existing install entry point before the progress route attaches. */
+    prepare(checkResult) {
+        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
@@ -149,6 +218,14 @@ class OtaInstallCoordinator {
             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),
@@ -180,13 +257,63 @@ 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() {
-        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;
@@ -195,16 +322,17 @@ 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)) {
@@ -222,12 +350,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() {
+    async finish() {
+        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();
     }
     /**
      * Abandon an interrupted session (the super-mode skip): terminal cleanup
@@ -235,8 +368,8 @@ class OtaInstallCoordinator {
      * deriveDisplayState doesn't resurrect the stale install when the host
      * navigates away and back through /ota routes.
      */
-    discard() {
-        this.finish();
+    async discard() {
+        await this.finish();
         const store = useGlassesStore.getState();
         store.setOtaStatus(null);
         store.setOtaProgress(null);
@@ -255,16 +388,44 @@ 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.
+     */
+    isInVersionChangeDetour() {
+        return this.versionChangeSession && this.versionChangeInstallStarted && !this.versionChangeConverged;
+    }
+    /** Downgrade-detour sub-phase for the progress narrative (see OtaInstallSnapshot). */
+    deriveVersionChangePhase(connected) {
+        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
@@ -297,10 +458,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;
@@ -314,6 +481,24 @@ class OtaInstallCoordinator {
         this.lastStallSig = "";
         this.reactQueued = false;
     }
+    /** Begin a genuinely new command attempt only after native ownership has settled. */
+    prepareFreshOtaStartAttempt() {
+        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. */
+    resetBesRestartAttempt() {
+        this.besRestartExpected = false;
+        this.besRestartDisconnectObserved = false;
+        this.besRestartRecovery = null;
+    }
     /** Notify snapshot subscribers of a coordinator-internal state change. */
     emitInternalChange() {
         for (const check of Array.from(this.snapshotCheckers))
@@ -363,14 +548,18 @@ class OtaInstallCoordinator {
         this.mtkSimulatedPercent = next;
         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. */
     isLegacySessionShapeNow() {
+        if (this.protocolProfile)
+            return this.protocolProfile === "legacy";
         const state = useGlassesStore.getState();
-        return isLegacyShapedOtaSession(state.otaStatus, state.otaProgress, this.initialBuildNumber || state.buildNumber);
+        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);
     }
     react() {
         if (!this.attached)
@@ -418,6 +607,18 @@ class OtaInstallCoordinator {
             this.handleLegacyInstallCompleteEdge(otaStatus);
         }
         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,
@@ -427,6 +628,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);
@@ -481,6 +685,62 @@ class OtaInstallCoordinator {
             console.log("[OTA_PROGRESS] legacy mtk install complete — marking MTK updated this session");
             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
@@ -516,7 +776,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) {
@@ -528,21 +788,23 @@ 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();
         }
@@ -563,7 +825,11 @@ 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) {
@@ -583,19 +849,26 @@ 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);
-            }
+            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);
         }
-        if (displayStateChanged && displayState === "failed") {
-            this.clearPerStepTimers();
+        else if (displayStateChanged) {
+            this.clearRestartRecoveryTimeout();
         }
         // Legacy MTK install stall simulation (WP 8C-e): display-only. The simulation
         // timers only ever touch the projected snapshot percent — they never feed back
@@ -609,91 +882,128 @@ class OtaInstallCoordinator {
         // completions (which never produce a `complete` ota_status).
         if (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).
+     */
+    runReconnectArbitration(label) {
+        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;
     }
     runConnectEdge(connected) {
         const prev = this.prevConnected;
         this.prevConnected = connected;
         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);
-            return;
-        }
-        if (becameConnected) {
-            console.log("[OTA_PROGRESS] connect-edge: reconnected, sending ota_query_status");
-            void BluetoothSdk.sendOtaQueryStatus();
-            this.armQueryReplyFallback("reconnect");
+        // 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;
         }
+        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
         // still begins an explicit install.
         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");
         }
     }
     // --- BLE OTA event listeners (engine GlobalEventEmitter, fed by OtaService) ---
     handleAck = () => {
-        if (this.hasReceivedAck)
+        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.
+     */
+    handleGlassesSessionChanged = () => {
+        this.runReconnectArbitration("session-change");
+    };
     handleMtkComplete = () => {
         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);
     };
     // --- legacy (< 37) compatibility, ported from progress-legacy.tsx (WP 8C) ---
@@ -732,6 +1042,34 @@ class OtaInstallCoordinator {
             }, LEGACY_APK_COMPLETION_SETTLE_MS);
         }
     }
+    isBesRestartExpected(otaStatus, otaProgress, legacySession) {
+        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. */
+    completeBesRestartRecovery() {
+        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;
@@ -795,10 +1133,45 @@ 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.
+     */
+    maybePollApkInstallStatus() {
+        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}).
      */
@@ -806,6 +1179,9 @@ class OtaInstallCoordinator {
         if (this.hasFirstActivity)
             return;
         this.hasFirstActivity = true;
+        if (this.otaStartOwnership?.outcome === "pending") {
+            this.otaStartOwnership.outcome = "acknowledged";
+        }
         this.clearRetryTimeout();
     }
     /**
@@ -828,7 +1204,7 @@ 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;
@@ -844,35 +1220,12 @@ class OtaInstallCoordinator {
             this.setErrorMsg(OtaProgressMessages.globalTimeout);
         }, globalTimeoutMs);
     }
-    armAckAndStuckWatchdogsOnly() {
-        this.clearRetryTimeout();
+    armStuckWatchdogOnly() {
         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();
@@ -888,27 +1241,123 @@ class OtaInstallCoordinator {
             this.setErrorMsg(OtaProgressMessages.stalledOrStuck);
         }, stuckTimeoutMs);
     }
-    async sendOtaStartWithWatchdogs(retryAlreadyCounted = false) {
+    /** Arm the 0%-stuck watchdog only when this logical session has none. */
+    maybeArmStuckWatchdog() {
+        if (this.stuckTimeout || this.hasFirstNonZeroProgress)
+            return;
+        this.armStuckWatchdogOnly();
+    }
+    sendOtaStartWithWatchdogs() {
+        // 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 = {
+            outcome: "pending",
+            promise: Promise.resolve(),
+        };
+        ownership.promise = this.performOtaStart(ownership);
+        this.otaStartOwnership = ownership;
+        return ownership.promise;
+    }
+    async performOtaStart(ownership) {
+        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);
             }
@@ -918,12 +1367,22 @@ class OtaInstallCoordinator {
             }
         }
     }
+    async teardownHotspotTransport() {
+        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
@@ -940,17 +1399,27 @@ 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);
     }
@@ -980,12 +1449,6 @@ class OtaInstallCoordinator {
         }
         this.globalTimeoutStarted = false;
     }
-    clearPostApkDelay() {
-        if (this.postApkDelay) {
-            clearTimeout(this.postApkDelay);
-            this.postApkDelay = null;
-        }
-    }
     clearPingInterval() {
         if (this.pingInterval) {
             clearInterval(this.pingInterval);
@@ -1004,6 +1467,12 @@ class OtaInstallCoordinator {
             this.continueLockoutTimer = null;
         }
     }
+    clearRestartRecoveryTimeout() {
+        if (this.restartRecoveryTimeout) {
+            clearTimeout(this.restartRecoveryTimeout);
+            this.restartRecoveryTimeout = null;
+        }
+    }
     clearLegacyApkSettleTimer() {
         if (this.legacyApkSettleTimer) {
             clearTimeout(this.legacyApkSettleTimer);
@@ -1031,7 +1500,6 @@ class OtaInstallCoordinator {
         this.clearRetryTimeout();
         this.clearStuckTimeout();
         this.clearProgressTimeout();
-        this.clearPostApkDelay();
         this.clearQueryReplyTimeout();
     }
     clearAllOtaTimers() {
@@ -1040,6 +1508,7 @@ class OtaInstallCoordinator {
         this.clearPingInterval();
         this.clearLegacyApkSettleTimer();
         this.clearMtkSimulationTimers();
+        this.clearRestartRecoveryTimeout();
     }
 }
 /** Singleton — one install session machine per app process (matches the single progress screen). */