codex-overleaf-link 2.5.0 → 2.6.0

package/extension/src/backgroundUpdateCoordinator.js

@@ -37,8 +37,11 @@
     'codex-overleaf/consent-update-cancel',
     'codex-overleaf/consent-update-recover',
     'codex-overleaf/consent-update-dismiss',
-    'codex-overleaf/consent-update-reload'
+    'codex-overleaf/consent-update-reload',
+    'codex-overleaf/consent-update-rollback'
   ]);
+  const USER_ROLLBACK_REASON = 'update_user_rollback';
+  const RECOVERABLE_TRANSACTION_STATES = new Set(['awaiting_health', 'bootstrap_pending', 'bootstrap_rolling_back']);
 
   const policy = root.CodexOverleafUpdateConsent;
   const revocation = root.CodexOverleafUpdateRevocation;
@@ -98,6 +101,7 @@
   }
 
   async function startup() {
+    if (!await waitForBootstrapOwnership()) return;
     chrome.alarms?.create?.(CHECK_ALARM, {
       delayInMinutes: 0.5,
       periodInMinutes: CHECK_INTERVAL_MINUTES
@@ -155,6 +159,8 @@
         return dismissCompletedUpdate();
       case 'codex-overleaf/consent-update-reload':
         return reloadInstalledRuntime();
+      case 'codex-overleaf/consent-update-rollback':
+        return restorePreviousVersion();
       default:
         throw codedError('unknown_update_action', 'Unknown update action.');
     }
@@ -170,40 +176,50 @@
       operation.phase = 'checking';
       await setUpdateState({ ...currentState, state: 'checking', operationId: operation.id,
         cancelRequested: false, initiatedBy: manual ? 'manual' : 'automatic',
-        code: '', message: '', blocker: '', blockers: [], postponeUntil: LEGACY_GUARD }, { operation });
+        code: '', message: '', blocker: '', blockers: [], cooldownUntil: 0, postponeUntil: LEGACY_GUARD }, { operation });
       try {
         const result = await withTimeout(requestNative('update.check', {
-          operationId: operation.id, currentVersion: currentVersion(), etag: currentState.etag || ''
+          operationId: operation.id, currentVersion: currentVersion(), etag: currentState.etag || '', manual: manual === true
         }), CHECK_REQUEST_TIMEOUT_MS, codedError('update_check_timeout', 'The managed update check did not complete in time.'));
         assertOperation(operation);
         const checkedAt = Date.now();
-        if (result.available || (result.reason === 'not_modified'
-          && policy.compareStableVersions(currentState.latestVersion, currentVersion()) > 0)) {
+        if (result.available) {
           const latestVersion = result.latestVersion || currentState.latestVersion;
           await setConsentState({ ...consent,
-            ...(latestVersion !== consent.snoozedVersion ? { snoozedVersion: '', snoozedUntil: 0 } : {}),
+            ...(manual || latestVersion !== consent.snoozedVersion ? { snoozedVersion: '', snoozedUntil: 0 } : {}),
             lastPromptedVersion: latestVersion,
             lastPromptedAt: manual ? checkedAt : consent.lastPromptedAt
           }, { operation });
           await setUpdateState({ ...currentState, state: 'update_available', operationId: operation.id,
             currentVersion: result.currentVersion || currentVersion(), latestVersion,
             managed: true, etag: result.etag || currentState.etag || '', lastCheckedAt: checkedAt,
-            postponeUntil: LEGACY_GUARD, code: '', message: '', cancelRequested: false
+            postponeUntil: LEGACY_GUARD, code: '', message: '', cooldownUntil: 0, manualReason: {}, cancelRequested: false
           }, { operation });
-        } else if (result.reason === 'manual_install_required'
-          && policy.compareStableVersions(result.latestVersion, currentVersion()) > 0) {
+        } else if ((result.reason === 'manual_install_required'
+          && policy.compareStableVersions(result.latestVersion, currentVersion()) > 0)
+          || (result.reason === 'prerelease_promotion_requires_manual_update'
+            && result.latestVersion === (result.currentVersion || currentVersion()))) {
           await setUpdateState({ ...currentState, state: 'manual_install_required', operationId: operation.id,
             currentVersion: result.currentVersion || currentVersion(), latestVersion: result.latestVersion,
             managed: true, etag: result.etag || currentState.etag || '', lastCheckedAt: checkedAt,
-            postponeUntil: LEGACY_GUARD, code: 'update_bootstrap_upgrade_required', message: '',
+            postponeUntil: LEGACY_GUARD, code: result.reason === 'prerelease_promotion_requires_manual_update'
+              ? result.reason : result.code === 'update_bootstrap_source_mismatch'
+                ? result.code : 'update_bootstrap_upgrade_required', message: '', cooldownUntil: 0,
             manualReason: result.manualInstall?.reason || {}, cancelRequested: false
           }, { operation });
         } else {
           await setUpdateState({ ...currentState, state: 'idle', operationId: operation.id,
             currentVersion: result.currentVersion || currentVersion(),
             latestVersion: result.latestVersion || result.currentVersion || currentVersion(),
-            etag: result.etag || currentState.etag || '', lastCheckedAt: checkedAt,
-            postponeUntil: LEGACY_GUARD, transactionId: '', code: '', message: '', cancelRequested: false
+            // A 304 without a verified Native candidate is a cache miss. Drop
+            // its validator so the next normal check can obtain fresh bytes.
+            // A skipped version also needs fresh bytes when checked explicitly.
+            etag: ['not_modified', 'cooldown'].includes(result.reason) ? '' : result.etag || currentState.etag || '', lastCheckedAt: checkedAt,
+            postponeUntil: LEGACY_GUARD, transactionId: '',
+            code: result.reason === 'cooldown'
+              ? (result.cooldownReason === USER_ROLLBACK_REASON ? 'update_skipped_after_rollback' : 'update_cooldown') : '',
+            cooldownUntil: result.reason === 'cooldown' ? Number(result.cooldownUntil || 0) : 0,
+            manualReason: {}, message: '', cancelRequested: false
           }, { operation });
         }
         return getView();
@@ -500,7 +516,7 @@
   async function cancelUpdateCore() {
     const [state, consent] = await Promise.all([getUpdateState(), getConsentState()]);
     if (['applying', 'awaiting_health', 'rolling_back'].includes(state.state)
-      || activeOperation?.phase === 'applying' || state.recoveryPending) {
+      || ['applying', 'rolling_back'].includes(activeOperation?.phase) || state.recoveryPending) {
       throw codedError('update_revoke_too_late', 'The update is being installed or recovered.');
     }
     const operation = activeOperation;
@@ -555,8 +571,10 @@
 
 
   function reconcileRecoveryState() {
+    if (activeOperation?.phase === 'rolling_back') return getUpdateState();
     if (recoveryPromise) return recoveryPromise;
     recoveryPromise = (async () => {
+      if (!await waitForBootstrapOwnership()) return getUpdateState();
       const state = await getUpdateState();
       if (state.recoveryPending) return reconcileExpiredPhase();
       if (state.cancelRequested) return postponeUpdate();
@@ -584,7 +602,9 @@
 
 
   async function reconcileExpiredPhase() {
-    const state = await getUpdateState();
+    const recoveryOwner = await captureRecoveryOwner();
+    const state = recoveryOwner.state;
+    const recoveryOptions = { observed: true, recoveryOwner };
     if (!state.recoveryPending && (!state.deadlineAt || Date.now() <= state.deadlineAt
       || policy.isTerminalState(state.state))) return state;
     if (['checking', 'downloading'].includes(state.state)) {
@@ -597,32 +617,38 @@
       try {
         let status = await withTimeout(requestNative('update.status'), 10000,
           codedError('update_status_timeout', 'Update recovery status is unavailable.'));
+        await assertRecoveryOwner(recoveryOwner);
         let transaction = status.transaction;
         if (state.transactionId && transaction?.id !== state.transactionId) {
           throw codedError('update_transaction_mismatch', 'The update recovery transaction could not be matched.');
         }
+        if (transaction?.state === 'superseded') {
+          return settleSupersededTransaction(status, recoveryOwner);
+        }
         if (transaction?.state === 'staged' || (!transaction && status.installedAligned
           && status.activeVersion === state.currentVersion)) {
           if (state.operationId) await requestNative('update.cancel', { operationId: state.operationId });
+          await assertRecoveryOwner(recoveryOwner);
           const consent = await getConsentState();
           const authorizationId = consent.authorizationId || consent.revokingAuthorizationId;
           const targetVersion = consent.authorizedVersion || consent.revokingVersion || state.latestVersion;
+          await assertRecoveryOwner(recoveryOwner);
           if (authorizationId) await requestNative('update.revoke', { authorizationId, targetVersion });
-          await setConsentState(revocation.clear({ ...consent,
-            authorizedVersion: '', authorizationId: '', authorizedAt: 0
-          }));
-          return setUpdateState({ state: 'failed', recoveryPending: false, cancelRequested: false,
+          const completed = await setUpdateAndConsentState({ state: 'failed', recoveryPending: false, cancelRequested: false,
             operationId: '', code: 'update_not_applied', message: 'The update was stopped before installation. Retry when ready.'
-          }, { observed: true });
+          }, revocation.clear({ ...consent, authorizedVersion: '', authorizationId: '', authorizedAt: 0 }), recoveryOptions);
+          return completed.updateState;
         }
         if (transaction?.state === 'awaiting_health') {
           const rolledBack = await requestNative('update.rollback', {
             transactionId: transaction.id, expectedState: 'awaiting_health', reasonCode: 'update_health_timeout'
           });
+          await assertRecoveryOwner(recoveryOwner);
           if (rolledBack.state !== 'rolled_back' || rolledBack.version !== transaction.sourceVersion) {
             throw codedError('update_rollback_unconfirmed', 'Rollback returned incomplete evidence.');
           }
           status = await requestNative('update.status');
+          await assertRecoveryOwner(recoveryOwner);
           transaction = status.transaction;
         }
         if (transaction?.state === 'committed' && status.installedAligned
@@ -630,30 +656,121 @@
           return setUpdateState({ state: 'committed', currentVersion: transaction.targetVersion,
             latestVersion: transaction.targetVersion, transactionId: transaction.id,
             recoveryPending: false, cancelRequested: false, code: '', message: ''
-          }, { observed: true });
+          }, recoveryOptions);
         }
         if (transaction?.state === 'rolled_back' && status.installedAligned
           && status.activeVersion === transaction.sourceVersion
           && (!state.transactionId || transaction.id === state.transactionId)) {
-          const restored = await setUpdateState({ state: 'rolled_back', currentVersion: transaction.sourceVersion,
+          const userRestore = transaction.reasonCode === USER_ROLLBACK_REASON;
+          if ((userRestore || state.code === 'update_rollback_unconfirmed')
+            && !root.CodexOverleafUpdateRuntimeIdentity?.verifiedRollback(status)) {
+            throw codedError('update_rollback_unconfirmed', 'Rollback returned incomplete evidence.');
+          }
+          if (userRestore) {
+            const pending = (await chrome.storage.local.get(MANUAL_RELOAD_TABS_KEY))?.[MANUAL_RELOAD_TABS_KEY];
+            const tabs = await chrome.tabs.query({ url: OVERLEAF_MATCHES });
+            await assertRecoveryOwner(recoveryOwner);
+            await chrome.storage.local.set({ [UPDATE_RELOAD_TABS_KEY]: [],
+              [MANUAL_RELOAD_TABS_KEY]: pending?.targetVersion === transaction.sourceVersion ? pending : {
+                targetVersion: transaction.sourceVersion, tabIds: tabs.filter(isUsableEditorTab).map(tab => tab.id)
+              } });
+          }
+          const value = { state: 'rolled_back', currentVersion: transaction.sourceVersion,
             transactionId: transaction.id, recoveryPending: false, cancelRequested: false,
             code: transaction.reasonCode || 'update_rolled_back', message: 'The previous version has been restored.'
-          }, { observed: true });
+          };
+          const restored = userRestore
+            ? (await setUpdateAndConsentState({ ...value, latestVersion: transaction.targetVersion,
+              postponeUntil: LEGACY_GUARD, etag: '', cooldownUntil: 0
+            }, policy.normalizeConsentState({ snoozedVersion: transaction.targetVersion,
+              snoozedUntil: Date.now() + SNOOZE_MS }), recoveryOptions)).updateState
+            : await setUpdateState(value, recoveryOptions);
+          runtimeStatus = null;
+          if (userRestore) {
+            try { await requireReloadSafePoint(); } catch (_error) { return restored; }
+          }
+          if (recoveryOwner.generation !== operationGeneration) return getUpdateState();
           setTimeout(() => chrome.runtime.reload(), 0);
           return restored;
         }
         throw codedError('update_recovery_pending', 'The installed update result has not been confirmed.');
       } catch (error) {
+        if (error.code === 'update_recovery_superseded') return getUpdateState();
         return setUpdateState({ state: 'failed', recoveryPending: true, cancelRequested: false,
           code: safeCode(error), message: safeMessage(error)
-        }, { observed: true });
+        }, recoveryOptions).catch(writeError => {
+          if (writeError.code === 'update_recovery_superseded') return getUpdateState();
+          throw writeError;
+        });
       }
     }
     return state;
   }
 
+  async function captureRecoveryOwner() {
+    const generation = operationGeneration;
+    const [state, consent] = await Promise.all([getUpdateState(), getConsentState()]);
+    return { generation, state, consent };
+  }
+
+  function matchesRecoveryOwner(owner, state, consent) {
+    return owner && owner.generation === operationGeneration
+      && ['state', 'transactionId', 'operationId', 'currentVersion', 'latestVersion',
+        'recoveryPending', 'cancelRequested', 'lastCheckedAt', 'phaseStartedAt']
+        .every(key => state[key] === owner.state[key])
+      && ['authorizationId', 'authorizedVersion', 'revokingAuthorizationId', 'revokingVersion']
+        .every(key => consent[key] === owner.consent[key]);
+  }
+
+  async function assertRecoveryOwner(owner) {
+    const [state, consent] = await Promise.all([getUpdateState(), getConsentState()]);
+    assertRecoverySnapshot(owner, state, consent);
+  }
+
+  function assertRecoverySnapshot(owner, state, consent) {
+    if (owner && !matchesRecoveryOwner(owner, state, consent)) {
+      throw codedError('update_recovery_superseded', 'A newer update state replaced this recovery request.');
+    }
+  }
+
+  // Both startup recovery and the coordinator retire the same Native journal
+  // through this queue. The snapshot was captured before requesting status.
+  function settleSupersededTransaction(status, owner) {
+    return enqueueStateWrite(async () => {
+      const [previous, consent] = await Promise.all([getUpdateState(), getConsentState()]);
+      if (!matchesRecoveryOwner(owner, previous, consent)) return previous;
+      const transaction = status?.transaction;
+      const sameTargetReinstall = transaction?.reasonCode === 'update_reinstalled'
+        && status.activeVersion === transaction.targetVersion
+        && status.reinstalledPair?.extensionVersion === status.activeVersion
+        && status.reinstalledPair?.nativeVersion === status.activeVersion
+        && /^[0-9a-f]{64}$/.test(status.reinstalledPair.extensionSha256 || '')
+        && /^[0-9a-f]{64}$/.test(status.reinstalledPair.nativeSha256 || '');
+      if (activeOperation || transaction?.state !== 'superseded' || !transaction.id
+        || (previous.transactionId && previous.transactionId !== transaction.id)
+        || status.installedAligned !== true || status.activeVersion !== transaction.supersededByVersion
+        || (!sameTargetReinstall && policy.compareStableVersions(status.activeVersion, transaction.targetVersion) <= 0)
+        || policy.compareStableVersions(status.activeVersion, transaction.sourceVersion) <= 0
+        || ['authorized', 'bound'].includes(status.authorization?.state)
+        || (consent.authorizedVersion && consent.authorizedVersion !== transaction.targetVersion)
+        || (consent.revokingVersion && consent.revokingVersion !== transaction.targetVersion)) return previous;
+      const next = projectUpdateState(previous, { state: 'idle', currentVersion: status.activeVersion,
+        latestVersion: status.activeVersion, transactionId: '', operationId: '', recoveryPending: false,
+        cancelRequested: false, blocker: '', blockers: [], code: '', message: '', manualReason: {}, cooldownUntil: 0
+      }, { observed: true });
+      // Invalidate older awaits before yielding to storage, including recovery
+      // responses that describe this same retired transaction.
+      operationGeneration += 1;
+      await chrome.storage.local.set({ [UPDATE_STATE_KEY]: next,
+        [CONSENT_STATE_KEY]: policy.normalizeConsentState({}), [UPDATE_RELOAD_TABS_KEY]: [] });
+      runtimeStatus = null;
+      return next;
+    });
+  }
+
 
   async function handleObservedStateChange() {
+    if (!await waitForBootstrapOwnership()) return;
     await settleTerminalConsent();
     const [state, consent] = await Promise.all([getUpdateState(), getConsentState()]);
     if (!consent.authorizationId && !policy.isExecutionState(state.state)) {
@@ -682,9 +799,15 @@
       now: Date.now()
     });
     view.runtime = runtime;
+    // Native decides availability: a committed pair with its source still on
+    // disk, or any unsettled installation that recovery must finish anyway.
+    view.restorePrevious = !state.cancelRequested && !activeOperation
+      && (runtime.rollbackAvailable?.sourceVersion || (state.recoveryPending && state.transactionId))
+      ? { version: runtime.rollbackAvailable?.sourceVersion || '' } : null;
+    view.actions = { ...view.actions, restorePrevious: Boolean(view.restorePrevious) };
     const pending = (await chrome.storage.local.get(MANUAL_RELOAD_TABS_KEY))?.[MANUAL_RELOAD_TABS_KEY];
     const pagesPending = runtime.state === 'aligned' && pending?.targetVersion === runtime.installedVersion && pending.tabIds?.length;
-    if (runtime.state === 'reload_required' || pagesPending) {
+    if (!state.recoveryPending && (runtime.state === 'reload_required' || pagesPending)) {
       view.showPanel = true;
       view.state = { ...state, state: pagesPending ? 'reload_tabs_required' : 'reload_required',
         currentVersion: runtime.extensionVersion, latestVersion: runtime.installedVersion,
@@ -701,9 +824,9 @@
     runtimeStatusRead = withTimeout(requestNative('update.status'), 4000,
       codedError('update_status_timeout', 'Installed version inspection timed out.')).then(status => {
       runtimeStatusAt = Date.now();
-      runtimeStatus = root.CodexOverleafUpdateRuntimeIdentity.inspectInstalledRuntime(status, {
+      runtimeStatus = { ...root.CodexOverleafUpdateRuntimeIdentity.inspectInstalledRuntime(status, {
         extensionVersion: chrome.runtime.getManifest().version, runtimeVersion: currentVersion()
-      });
+      }), rollbackAvailable: status.rollbackAvailable || null };
       return runtimeStatus;
     }).catch(() => ({ state: 'unknown' })).finally(() => { runtimeStatusRead = null; });
     return runtimeStatusRead;
@@ -725,6 +848,9 @@
   }
 
   async function reloadInstalledRuntime() {
+    if ((await getUpdateState()).recoveryPending) {
+      throw codedError('update_rollback_unconfirmed', 'Confirm update recovery before reloading.');
+    }
     const runtime = await readRuntimeStatus(true);
     if (runtime.state === 'aligned') { await finishManualRuntimeReload(); return getView(); }
     if (runtime.state !== 'reload_required') throw codedError('update_reload_unavailable', 'No verified installed update is awaiting reload.');
@@ -736,7 +862,80 @@
     return getView();
   }
 
+  // Returns a committed update, or an update whose installation or recovery is
+  // unsettled, to the source pair Native still holds. Native owns the decision;
+  // the browser only supplies the transaction it observed and reloads after an
+  // exact readback.
+  async function restorePreviousVersion() {
+    if (activeOperation || cancellationPromise) {
+      throw codedError('update_transaction_in_progress', 'Another update operation is in progress.');
+    }
+    const operation = beginOperation();
+    operation.phase = 'rolling_back';
+    try {
+      const status = await requestNative('update.status');
+      assertOperation(operation);
+      const transaction = status.transaction;
+      const committed = transaction?.state === 'committed' && status.rollbackAvailable?.transactionId === transaction.id;
+      if (!transaction?.id || (!committed && !RECOVERABLE_TRANSACTION_STATES.has(transaction.state))) {
+        throw codedError('update_rollback_unavailable', 'No installed update can be restored to its previous version.');
+      }
+      // Page refresh happens after restoration, so it waits for the same saved
+      // and idle point as a reload of an installed update.
+      const tabs = await requireReloadSafePoint();
+      assertOperation(operation);
+      const generation = operation.generation;
+      clearIdleRetryTimer();
+      await setUpdateState({ state: 'rolling_back', transactionId: transaction.id,
+        currentVersion: transaction.targetVersion, latestVersion: transaction.targetVersion,
+        recoveryPending: false, cancelRequested: false, operationId: '', code: '', message: ''
+      }, { observed: true, generation });
+      try {
+        // Old source runtimes consume this key through their saved/idle check.
+        // The fixed Bootstrap's legacy list would refresh tabs unconditionally.
+        await chrome.storage.local.set({ [UPDATE_RELOAD_TABS_KEY]: [],
+          [MANUAL_RELOAD_TABS_KEY]: { targetVersion: transaction.sourceVersion, tabIds: tabs.map(tab => tab.id) } });
+        assertOperation(operation);
+        const rolledBack = await requestNative('update.rollback', { transactionId: transaction.id,
+          expectedState: transaction.state, reasonCode: USER_ROLLBACK_REASON });
+        assertOperation(operation);
+        const readback = await requestNative('update.status');
+        assertOperation(operation);
+        if (rolledBack.transactionId !== transaction.id || rolledBack.state !== 'rolled_back'
+          || rolledBack.version !== transaction.sourceVersion || readback.transaction?.id !== transaction.id
+          || readback.transaction.sourceVersion !== transaction.sourceVersion
+          || readback.transaction.targetVersion !== transaction.targetVersion
+          || !root.CodexOverleafUpdateRuntimeIdentity?.verifiedRollback({ ...readback,
+            transaction: { ...readback.transaction, bootstrapRevision: transaction.bootstrapRevision } })
+          || !['extensionVersion', 'nativeVersion', 'extensionSha256', 'nativeSha256', 'bootstrapSha256']
+            .every(key => readback.restoredPair[key] === rolledBack.restoredPair?.[key])) {
+          throw codedError('update_rollback_unconfirmed', 'Rollback returned incomplete evidence.');
+        }
+      } catch (error) {
+        await setUpdateState({ state: 'failed', transactionId: transaction.id, recoveryPending: true,
+          cancelRequested: false, code: safeCode(error), message: safeMessage(error)
+        }, { observed: true, generation }).catch(() => {});
+        throw error;
+      }
+      await setUpdateAndConsentState({ state: 'rolled_back', transactionId: transaction.id,
+        currentVersion: transaction.sourceVersion, latestVersion: transaction.targetVersion,
+        recoveryPending: false, cancelRequested: false, blocker: '', blockers: [],
+        postponeUntil: LEGACY_GUARD, etag: '', cooldownUntil: 0,
+        code: USER_ROLLBACK_REASON, message: 'You restored the previous version.'
+      }, policy.normalizeConsentState({ snoozedVersion: transaction.targetVersion,
+        snoozedUntil: Date.now() + SNOOZE_MS }), { observed: true, generation });
+      runtimeStatus = null;
+      // The disk restore is complete even if new work now prevents a reload.
+      // Keep the existing Reload action available without attempting rollback again.
+      try { await requireReloadSafePoint(); } catch (_error) { return getView(); }
+      assertOperation(operation);
+      setTimeout(() => chrome.runtime.reload(), 0);
+      return getView();
+    } finally { finishOperation(operation); }
+  }
+
   async function finishManualRuntimeReload() {
+    if ((await getUpdateState()).recoveryPending) return;
     const pending = (await chrome.storage.local.get(MANUAL_RELOAD_TABS_KEY))?.[MANUAL_RELOAD_TABS_KEY];
     if (!pending || !Array.isArray(pending.tabIds)) return;
     const runtime = await readRuntimeStatus(true);
@@ -784,9 +983,11 @@
   function setUpdateState(value, options = {}) {
     return enqueueStateWrite(async () => {
       assertWriteOwner(options);
-      const stored = await chrome.storage.local.get(UPDATE_STATE_KEY);
+      const stored = await chrome.storage.local.get(options.recoveryOwner
+        ? [UPDATE_STATE_KEY, CONSENT_STATE_KEY] : UPDATE_STATE_KEY);
       assertWriteOwner(options);
       const previous = policy.normalizeUpdateState(stored?.[UPDATE_STATE_KEY], currentVersion());
+      assertRecoverySnapshot(options.recoveryOwner, previous, policy.normalizeConsentState(stored?.[CONSENT_STATE_KEY]));
       const next = projectUpdateState(previous, value, options);
       await chrome.storage.local.set({ [UPDATE_STATE_KEY]: next });
       return next;
@@ -844,6 +1045,7 @@
       const stored = await chrome.storage.local.get([UPDATE_STATE_KEY, CONSENT_STATE_KEY]);
       assertWriteOwner(options);
       const previous = policy.normalizeUpdateState(stored?.[UPDATE_STATE_KEY], currentVersion());
+      assertRecoverySnapshot(options.recoveryOwner, previous, policy.normalizeConsentState(stored?.[CONSENT_STATE_KEY]));
       const updateState = projectUpdateState(previous, updateValue, options);
       const consentState = policy.normalizeConsentState(consentValue);
       await chrome.storage.local.set({ [UPDATE_STATE_KEY]: updateState, [CONSENT_STATE_KEY]: consentState });
@@ -869,12 +1071,20 @@
 
   function enqueuePolicyAction(action) {
     const generation = operationGeneration;
-    const guarded = () => generation !== operationGeneration || cancellationPromise ? getView() : action();
+    const guarded = async () => !await waitForBootstrapOwnership()
+      || generation !== operationGeneration || cancellationPromise ? getView() : action();
     const result = policyTail.then(guarded, guarded);
     policyTail = result.catch(() => {});
     return result;
   }
 
+  async function waitForBootstrapOwnership() {
+    const migration = await root.CodexOverleafBootstrapMigration?.ready?.();
+    if (migration?.continueInitialization === false) return false;
+    await root.__CODEX_OVERLEAF_BOOTSTRAP_READY__;
+    return true;
+  }
+
   function beginOperation(id) {
     const operation = { id: id || crypto.randomUUID(), generation: ++operationGeneration, phase: 'checking' };
     activeOperation = operation;
@@ -894,6 +1104,9 @@
   }
 
   function assertWriteOwner(options) {
+    if (options.recoveryOwner && options.recoveryOwner.generation !== operationGeneration) {
+      throw codedError('update_recovery_superseded', 'A newer update state replaced this recovery request.');
+    }
     if (options.operation) assertOperation(options.operation);
     if (options.generation !== undefined && options.generation !== operationGeneration) {
       throw codedError('update_network_cancelled', 'The update request was superseded.');
@@ -970,5 +1183,5 @@
       .slice(0, 300);
   }
 
-  root.CodexOverleafUpdateCoordinator = Object.freeze({ init });
+  root.CodexOverleafUpdateCoordinator = Object.freeze({ init, captureRecoveryOwner, settleSupersededTransaction });
 })(globalThis);

package/extension/src/backgroundUpdateSafety.js

@@ -0,0 +1,173 @@
+(function installBackgroundUpdateSafety(root) {
+  'use strict';
+  const blocked = () => ({ idle: false, saved: false, blockers: ['tab_probe_unavailable'] });
+  // Chrome storage serializes object keys independently of insertion order.
+  // Preserve every key/value and array position when comparing readback.
+  function sameStored(left, right) {
+    if (left === right) return true;
+    if (!left || !right || typeof left !== 'object' || typeof right !== 'object') return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+      return Array.isArray(left) && Array.isArray(right) && left.length === right.length
+        && left.every((value, index) => sameStored(value, right[index]));
+    }
+    const leftKeys = Object.keys(left), rightKeys = Object.keys(right);
+    return leftKeys.length === rightKeys.length
+      && leftKeys.every(key => Object.prototype.hasOwnProperty.call(right, key) && sameStored(left[key], right[key]));
+  }
+  function create(options) {
+    const bindings = new Map();
+    const tabsKey = 'codex-overleaf-managed-update-tabs-v1';
+    const guardKey = 'codex-overleaf-managed-update-guarded-tabs-v1';
+    async function ownerMatches(binding) {
+      if (!options.isExecutionLocked()) return false;
+      const response = await options.request({ id: crypto.randomUUID(), method: 'update.status',
+        params: { bootstrapRevision: String(root.__CODEX_OVERLEAF_BOOTSTRAP_REVISION__ || '') } });
+      const tx = response?.ok && response.result?.transaction;
+      return tx?.id === binding.transactionId && tx.targetVersion === binding.targetVersion
+        && tx.sourceVersion === binding.sourceVersion && tx.state === binding.expectedState;
+    }
+    async function snapshot(tabId, documentId) {
+      const results = await chrome.scripting.executeScript({ target: documentId ? { tabId, documentIds: [documentId] }
+        : { tabId, frameIds: [0] }, world: 'ISOLATED', func: () => ({ url: location.href }) });
+      const item = results?.length === 1 && results[0];
+      return item?.frameId === 0 && item.documentId && typeof item.result?.url === 'string'
+        ? { documentId: item.documentId, url: item.result.url } : null;
+    }
+    async function saveProbe(message, sender) {
+      const binding = bindings.get(sender?.tab?.id);
+      if (!binding || sender.id !== chrome.runtime.id || sender.frameId !== 0 || sender.documentId !== binding.documentId
+        || sender.url !== binding.url || message.token !== binding.token || message.transactionId !== binding.transactionId
+        || message.nonce !== binding.nonce || !await ownerMatches(binding)) return { ok: false };
+      const before = await snapshot(binding.tabId, binding.documentId);
+      if (before?.url !== binding.url) return { ok: false };
+      const results = await chrome.scripting.executeScript({ target: { tabId: binding.tabId, documentIds: [binding.documentId] },
+        world: 'MAIN', func: url => globalThis.CodexOverleafUpdateSafetyProbe?.probe(url), args: [binding.url] });
+      const after = await snapshot(binding.tabId, binding.documentId);
+      if (after?.url !== binding.url || message.nonce !== binding.nonce || !await ownerMatches(binding)
+        || results?.length !== 1 || results[0].documentId !== binding.documentId || results[0].frameId !== 0) return { ok: false };
+      return { ok: true, nonce: message.nonce, result: results[0].result };
+    }
+    chrome.runtime.onMessage.addListener((message, sender, respond) => {
+      if (message?.type !== 'codex-overleaf/migration-save-probe') return undefined;
+      saveProbe(message, sender).then(respond).catch(() => respond({ ok: false }));
+      return true;
+    });
+    async function probe(tab, owner) {
+      try {
+        const current = await snapshot(tab.id);
+        if (!current || current.url !== tab.url) return blocked();
+        let binding = bindings.get(tab.id);
+        if (binding && (binding.documentId !== current.documentId || binding.url !== current.url
+          || binding.transactionId !== owner.transactionId)) return blocked();
+        if (!binding) {
+          binding = { ...owner, ...current, tabId: tab.id, token: crypto.randomUUID(), nonce: '' };
+          if (!await ownerMatches(binding)) return blocked();
+          bindings.set(tab.id, binding);
+        }
+        binding.expectedState = owner.expectedState;
+        if (!binding.installed) {
+          const target = { tabId: tab.id, documentIds: [binding.documentId] };
+          await chrome.scripting.executeScript({ target, world: 'MAIN',
+            files: ['runtime/src/page/saveState.js', 'runtime/src/page/updateSafetyProbe.js'] });
+          await chrome.scripting.executeScript({ target, world: 'ISOLATED',
+            files: ['runtime/src/shared/pageRpcContract.js', 'runtime/src/content/updateIdle.js', 'runtime/src/content/updateSafetyReceiver.js'] });
+          const installed = await chrome.scripting.executeScript({ target, world: 'ISOLATED',
+            func: value => globalThis.CodexOverleafUpdateSafetyReceiver?.install(value, {
+              UpdateIdle: globalThis.CodexOverleafUpdateIdle, PageRpcContract: globalThis.CodexOverleafPageRpcContract
+            }), args: [binding] });
+          if (installed?.length !== 1 || installed[0].documentId !== binding.documentId
+            || installed[0].result?.ok !== true || installed[0].result.url !== binding.url) return blocked();
+          binding.installed = true;
+        }
+        if (!await ownerMatches(binding)) return blocked();
+        binding.nonce = crypto.randomUUID();
+        const nonce = binding.nonce;
+        let timer;
+        const response = await Promise.race([
+          chrome.tabs.sendMessage(tab.id, { type: 'codex-overleaf/migration-idle-probe', ...binding },
+            { documentId: binding.documentId }),
+          new Promise(resolve => { timer = setTimeout(() => resolve(null), 3500); })
+        ]).finally(() => clearTimeout(timer));
+        const after = await snapshot(tab.id, binding.documentId);
+        if (!response?.safetyOnly || response.token !== binding.token || response.transactionId !== binding.transactionId
+          || response.targetVersion !== binding.targetVersion || response.nonce !== nonce || response.url !== binding.url
+          || after?.url !== binding.url || !await ownerMatches(binding)) return blocked();
+        return response;
+      } catch (_) { return blocked(); }
+    }
+    async function protectReloadTabs(transaction) {
+      const owner = { transactionId: transaction.id, sourceVersion: transaction.sourceVersion,
+        targetVersion: transaction.targetVersion, expectedState: 'bootstrap_pending' };
+      if (!await ownerMatches(owner)) return false;
+      const stored = await chrome.storage.local.get([tabsKey, guardKey]);
+      if (stored[guardKey]?.transactionId === transaction.id && !stored[tabsKey]?.length) return true;
+      if (stored[guardKey]?.state === 'guarded' && stored[guardKey].transactionId !== transaction.id) {
+        const open = new Set((await chrome.tabs.query({})).map(tab => tab.id));
+        for (const entry of stored[guardKey].entries || []) {
+          if (!open.has(entry.tabId)) continue;
+          const current = await snapshot(entry.tabId).catch(() => null);
+          if (!entry.documentId || !current || current.documentId === entry.documentId) return false;
+        }
+      }
+      const entries = await Promise.all((stored[tabsKey] || []).map(async tabId => ({ tabId,
+        ...await snapshot(tabId).catch(() => null) })));
+      const guard = { transactionId: transaction.id, sourceVersion: transaction.sourceVersion,
+        targetVersion: transaction.targetVersion, state: 'guarded', entries };
+      const current = await chrome.storage.local.get([tabsKey, guardKey]);
+      if (!sameStored(current, stored) || !await ownerMatches(owner)) return false;
+      await chrome.storage.local.set({ [guardKey]: guard, [tabsKey]: [] });
+      const readback = await chrome.storage.local.get([tabsKey, guardKey]);
+      return sameStored(readback[guardKey], guard) && readback[tabsKey]?.length === 0;
+    }
+    async function releaseReloadTabs(transaction, expectedState = 'bootstrap_pending') {
+      const owner = { transactionId: transaction.id, sourceVersion: transaction.sourceVersion,
+        targetVersion: transaction.targetVersion, expectedState };
+      if (!await ownerMatches(owner)) return false;
+      const stored = await chrome.storage.local.get([tabsKey, guardKey]);
+      const guard = stored[guardKey];
+      if (guard?.transactionId !== transaction.id || guard.state !== 'guarded' || stored[tabsKey]?.length) return false;
+      const open = new Set((await chrome.tabs.query({})).map(tab => tab.id));
+      const ids = [];
+      for (const entry of guard.entries) {
+        if (!open.has(entry.tabId)) continue;
+        if (!entry.documentId || !entry.url) return false;
+        const current = await snapshot(entry.tabId, entry.documentId).catch(() => null);
+        if (current?.documentId !== entry.documentId || current?.url !== entry.url) return false;
+        ids.push(entry.tabId);
+      }
+      const again = await chrome.storage.local.get([tabsKey, guardKey]);
+      if (!sameStored(again[guardKey], guard) || again[tabsKey]?.length || !await ownerMatches(owner)) return false;
+      await chrome.storage.local.set({ [tabsKey]: ids, [guardKey]: { ...guard, state: 'ready' } });
+      return true;
+    }
+    async function revalidate(tabs, owner) {
+      if (!await ownerMatches(owner)) return false;
+      for (const tab of tabs) {
+        const binding = bindings.get(tab.id);
+        if (!binding || binding.transactionId !== owner.transactionId) continue;
+        if ((await probe(tab, owner)).idle !== true) return false;
+      }
+      return ownerMatches(owner);
+    }
+    async function hasReplacedReloadDocument(transaction) {
+      const owner = { transactionId: transaction.id, sourceVersion: transaction.sourceVersion,
+        targetVersion: transaction.targetVersion, expectedState: 'rolled_back' };
+      if (!await ownerMatches(owner)) return false;
+      const stored = await chrome.storage.local.get([tabsKey, guardKey]);
+      const guard = stored[guardKey];
+      if (guard?.transactionId !== transaction.id || guard.state !== 'guarded' || stored[tabsKey]?.length) return false;
+      const open = new Set((await chrome.tabs.query({})).map(tab => tab.id));
+      for (const entry of guard.entries) {
+        if (!open.has(entry.tabId) || !entry.documentId) continue;
+        const current = await snapshot(entry.tabId).catch(() => null);
+        if (current && current.documentId !== entry.documentId) {
+          const again = await chrome.storage.local.get([tabsKey, guardKey]);
+          return sameStored(again, stored) && await ownerMatches(owner);
+        }
+      }
+      return false;
+    }
+    return Object.freeze({ probe, protectReloadTabs, releaseReloadTabs, revalidate, hasReplacedReloadDocument });
+  }
+  root.CodexOverleafBackgroundUpdateSafety = Object.freeze({ create });
+})(globalThis);