codex-overleaf-link 2.5.0 → 2.5.1

package/extension/src/background.js

@@ -26,6 +26,8 @@ if (!globalThis.CodexOverleafStorageRunActions) {
   // registry and shared-module imports do not exist in this context.
   const storageDependencies = [
     ['CodexOverleafModuleRegistry', 'content/moduleRegistryKernel.js'],
+    ['CodexOverleafProjectFiles', 'shared/projectFiles.js'],
+    ['CodexOverleafDirectoryCleanupProof', 'shared/directoryCleanupProof.js'],
     ['CodexOverleafUndoOperations', 'shared/undoOperations.js'],
     ['CodexOverleafSelectionContext', 'shared/selectionContext.js'],
     ['CodexOverleafWritebackIntent', 'shared/writebackIntent.js'],
@@ -38,6 +40,10 @@ if (!globalThis.CodexOverleafStorageRunActions) {
     }
   }
 }
+if (!globalThis.CodexOverleafSharedSessionTransfer) {
+  const runtimeBase = String(globalThis.__CODEX_OVERLEAF_RUNTIME_BASE__ || '');
+  importScripts(runtimeBase ? chrome.runtime.getURL(`${runtimeBase}/src/shared/sharedSessionTransfer.js`) : 'shared/sharedSessionTransfer.js');
+}
 if (!globalThis.CodexOverleafSharedSessionsBackground) {
   const runtimeBase = String(globalThis.__CODEX_OVERLEAF_RUNTIME_BASE__ || '');
   importScripts(runtimeBase ? chrome.runtime.getURL(`${runtimeBase}/src/backgroundSharedSessions.js`) : 'backgroundSharedSessions.js');
@@ -47,6 +53,14 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
   const runtimeBase = String(globalThis.__CODEX_OVERLEAF_RUNTIME_BASE__ || '');
   importScripts(runtimeBase ? chrome.runtime.getURL(`${runtimeBase}/src/shared/updateRuntimeIdentity.js`) : 'shared/updateRuntimeIdentity.js');
 }
+if (!globalThis.CodexOverleafBootstrapMigration) {
+  const runtimeBase = String(globalThis.__CODEX_OVERLEAF_RUNTIME_BASE__ || '');
+  importScripts(runtimeBase ? chrome.runtime.getURL(`${runtimeBase}/src/backgroundBootstrapMigration.js`) : 'backgroundBootstrapMigration.js');
+}
+if (!globalThis.CodexOverleafBackgroundUpdateSafety) {
+  const runtimeBase = String(globalThis.__CODEX_OVERLEAF_RUNTIME_BASE__ || '');
+  importScripts(runtimeBase ? chrome.runtime.getURL(`${runtimeBase}/src/backgroundUpdateSafety.js`) : 'backgroundUpdateSafety.js');
+}
 
 (function initBackground() {
   'use strict';
@@ -83,7 +97,12 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
     'codex.providers.delete',
     'skills.list',
     'skills.install',
-    'skills.remove'
+    'skills.remove',
+    'writing-style.get',
+    'writing-style.set',
+    'codex.thread.fork',
+    'asset.readChunk',
+    'asset.release'
   ]);
   const RECOVERABLE_COMPATIBILITY_METHODS = new Set([
     'bridge.ping',
@@ -99,12 +118,38 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
   const pending = new Map();
   const runJournals = new Map();
   const journalWrites = new Map();
+  const journalLoads = new Map();
   const ownerBindings = new Map();
   const ownerCancelTimers = new Map();
   const RUN_JOURNAL_PREFIX = 'codex-overleaf:run-journal:';
   const RUN_JOURNAL_MAX_EVENTS = 300;
   const RUN_JOURNAL_MAX_BYTES = 512 * 1024;
   const managedBootstrapRuntime = isManagedBootstrapRuntime();
+  const migrationSafety = globalThis.CodexOverleafBackgroundUpdateSafety.create({
+    request: payload => sendNativeRequest(payload, null, { skipCompatibility: true }),
+    isExecutionLocked: () => managedBootstrapRuntime && managedUpdateExecutionLocked
+  });
+  let extensionInstallIdentity = { managed: managedBootstrapRuntime };
+  let installIdentityRead;
+  function readExtensionInstallIdentity() {
+    if (!managedBootstrapRuntime) return Promise.resolve(extensionInstallIdentity);
+    if (!installIdentityRead) installIdentityRead = (async () => {
+      try {
+        const response = await fetch(chrome.runtime.getURL('.codex-overleaf-managed-extension.json'));
+        const marker = response.ok ? await response.json() : null;
+        if (marker?.managedBy === 'codex-overleaf-link' && marker.kind === 'extension'
+          && marker.installIdentity?.extensionId === getCurrentExtensionId())
+          extensionInstallIdentity = { ...marker.installIdentity, managed: true };
+      } catch (_) { /* Old or missing marker: never guess the installation root. */ }
+      return extensionInstallIdentity;
+    })();
+    return installIdentityRead;
+  }
+  async function withExtensionInstallIdentity(request, response) {
+    return request?.method === 'bridge.ping'
+      ? { ...response, extensionInstallIdentity: await readExtensionInstallIdentity() } : response;
+  }
+
   globalThis.CodexOverleafNativeBridge = Object.freeze({
     requestInternal: payload => requestManagedInternal(payload),
     getPendingState: () => ({
@@ -114,6 +159,14 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
   });
 
   if (managedBootstrapRuntime) {
+    globalThis.CodexOverleafBootstrapMigration.init({
+      request: payload => sendNativeRequest(payload, null, { skipCompatibility: true }),
+      verifySafety: verifyManagedUpdateSafety,
+      protectReloadTabs: transaction => migrationSafety.protectReloadTabs(transaction),
+      releaseReloadTabs: (transaction, state) => migrationSafety.releaseReloadTabs(transaction, state),
+      hasReplacedReloadDocument: transaction => migrationSafety.hasReplacedReloadDocument(transaction),
+      setExecutionLocked: value => { managedUpdateExecutionLocked = value; }
+    });
     chrome.storage?.onChanged?.addListener((changes, area) => {
       if (area !== 'local' || !changes[MANAGED_UPDATE_STATE_KEY]?.newValue) {
         return;
@@ -193,13 +246,11 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
     }
 
     sendNativeRequest(message.payload, sender)
+      .then(result => withExtensionInstallIdentity(message.payload, result))
       .then(result => sendResponse(result))
       .catch(error => {
         const userFacingError = toUserFacingNativeError(error);
-        sendResponse({
-          ok: false,
-          error: userFacingError
-        });
+        withExtensionInstallIdentity(message.payload, { ok: false, error: userFacingError }).then(sendResponse);
       });
 
     return true;
@@ -221,13 +272,24 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
         return;
       }
       if (message.type === 'bind') {
-        ownerBindings.set(portConnection, {
+        const binding = {
           requestId,
           projectKey: String(message.projectKey || ''),
-          documentId: String(portConnection.sender?.documentId || '')
-        });
-        clearTimeout(ownerCancelTimers.get(requestId));
-        ownerCancelTimers.delete(requestId);
+          documentId: String(portConnection.sender?.documentId || ''),
+          tabId: portConnection.sender?.tab?.id,
+          clientRunId: String(message.clientRunId || ''),
+          sessionId: String(message.sessionId || '')
+        };
+        ownerBindings.set(portConnection, binding);
+        restoreRunJournal(binding).then(journal => {
+          if (ownerBindings.get(portConnection) !== binding || !journal || runJournals.get(requestId) !== journal) return;
+          clearTimeout(ownerCancelTimers.get(requestId));
+          ownerCancelTimers.delete(requestId);
+          if (!journal.ownerLost) return;
+          journal.ownerLost = false;
+          journal.updatedAt = new Date().toISOString();
+          return queueJournalWrite(requestId);
+        }).catch(() => {});
       }
     });
     portConnection.onDisconnect.addListener(() => {
@@ -306,6 +368,7 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
         resolve,
         reject,
         tabId: sender?.tab?.id,
+        documentId: String(sender?.documentId || ''),
         request,
         method: request.method,
         retryClass: getNativeRetryClass(request.method),
@@ -328,6 +391,10 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
   }
 
   async function requestManagedInternal(payload) {
+    if (managedBootstrapRuntime && ['update.status', 'update.confirm'].includes(payload?.method)) {
+      payload = { ...payload, params: { ...payload.params,
+        bootstrapRevision: String(globalThis.__CODEX_OVERLEAF_BOOTSTRAP_REVISION__ || '') } };
+    }
     if (managedBootstrapRuntime && payload?.method === 'update.apply') {
       const gate = await verifyManagedUpdateSafety();
       if (!gate.ok) {
@@ -345,15 +412,25 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
         throw error;
       }
     }
-    return sendNativeRequest(payload, null, { skipCompatibility: true });
+    const response = await sendNativeRequest(payload, null, { skipCompatibility: true });
+    if (payload?.method === 'update.confirm') {
+      globalThis.CodexOverleafBootstrapMigration.observeConfirmation(payload.params, response);
+    }
+    return response;
   }
 
-  async function verifyManagedUpdateSafety() {
-    const tabs = await chrome.tabs.query({ url: MANAGED_OVERLEAF_MATCHES }).catch(() => []);
-    const editorTabs = tabs.filter(tab => (
+  async function verifyManagedUpdateSafety(migrationOwner) {
+    const tabs = await chrome.tabs.query({ url: MANAGED_OVERLEAF_MATCHES }).catch(() => null);
+    const editorTabs = (Array.isArray(tabs) ? tabs : []).filter(tab => (
       isManagedEditorTab(tab) && !tab.discarded && tab.status !== 'unloaded'
     ));
-    const probes = await Promise.all(editorTabs.map(tab => probeManagedUpdateTab(tab.id)));
+    const probes = await Promise.all(editorTabs.map(async tab => {
+      const result = await probeManagedUpdateTab(tab.id);
+      return migrationOwner && result?.blockers?.includes('tab_probe_unavailable')
+        ? migrationSafety.probe(tab, migrationOwner) : result;
+    }));
+    // An unknown inventory cannot establish an idle safe point, even when Native is idle.
+    if (!Array.isArray(tabs)) probes.push({ idle: false, blockers: ['tab_inventory_unavailable'] });
     const nativeGate = await sendNativeRequest({
       id: crypto.randomUUID(),
       method: 'update.canApply',
@@ -365,6 +442,12 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
         message: getErrorMessage(error, 'Native Host update safety check failed.')
       }
     }));
+    if (migrationOwner) {
+      const after = await chrome.tabs.query({ url: MANAGED_OVERLEAF_MATCHES }).catch(() => null);
+      const inventory = values => JSON.stringify((values || []).map(tab => [tab.id, tab.url, tab.discarded, tab.status]).sort());
+      if (!after || inventory(after) !== inventory(tabs)) probes.push({ idle: false, blockers: ['tab_probe_unavailable'] });
+      else if (!await migrationSafety.revalidate(editorTabs, migrationOwner)) probes.push({ idle: false, blockers: ['tab_probe_unavailable'] });
+    }
     const pendingState = globalThis.CodexOverleafNativeBridge?.getPendingState?.() || {};
     const backgroundBlockers = Number(pendingState.executionRequests || 0) > 0
       ? ['background_execution_pending']
@@ -391,13 +474,15 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
       return { idle: false, blockers: ['tab_unavailable'] };
     }
     try {
-      return await Promise.race([
+      const response = await Promise.race([
         chrome.tabs.sendMessage(tabId, { type: 'codex-overleaf/update-idle-probe' }),
         new Promise(resolve => setTimeout(() => resolve({
           idle: false,
           blockers: ['tab_probe_timeout']
         }), 3500))
       ]);
+      return typeof response?.idle === 'boolean' ? response
+        : { idle: false, blockers: ['tab_probe_unavailable'] };
     } catch (_error) {
       return { idle: false, blockers: ['tab_probe_unavailable'] };
     }
@@ -434,6 +519,11 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
   }
 
   async function reconcileManagedUpdateTransaction() {
+    const migration = await globalThis.CodexOverleafBootstrapMigration.ready();
+    if (!migration.continueInitialization) return;
+    await globalThis.__CODEX_OVERLEAF_BOOTSTRAP_READY__;
+    const coordinator = globalThis.CodexOverleafUpdateCoordinator;
+    const recoveryOwner = await coordinator?.captureRecoveryOwner?.();
     const response = await sendNativeRequest({
       id: crypto.randomUUID(),
       method: 'update.status',
@@ -445,22 +535,7 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
 
     const transaction = response.result?.transaction || null;
     if (transaction?.state === 'superseded') {
-      const activeVersion = response.result?.activeVersion || chrome.runtime.getManifest().version;
-      await chrome.storage.local.remove([
-        MANAGED_UPDATE_CONSENT_KEY,
-        MANAGED_UPDATE_TABS_KEY
-      ]);
-      await setManagedUpdateState({
-        state: 'idle',
-        managed: true,
-        currentVersion: activeVersion,
-        latestVersion: activeVersion,
-        transactionId: '',
-        blocker: '',
-        blockers: [],
-        code: '',
-        message: ''
-      });
+      await coordinator?.settleSupersededTransaction?.(response.result, recoveryOwner);
       return;
     }
     const state = await getManagedUpdateState();
@@ -521,6 +596,16 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
       return null;
     }
 
+    const params = request.params || {};
+    if (request.method === 'codex.run' && params.focusFilesAreLiteral === true
+      && (params.restrictToFocusFiles === true || (Array.isArray(params.focusFiles) && params.focusFiles.length))
+      && evidence?.native?.capabilities?.literalProjectPaths !== true) {
+      return { ...createNativeUpdateRequiredBlock(request.method, {
+        ...evidence, status: 'native_capability_missing', classification: 'incompatible'
+      }), message: 'This Native Host does not support literal project paths. Reload the extension after installing the coordinated build.',
+      missingCapabilities: ['literalProjectPaths'] };
+    }
+
     if (isNativeMethodAllowedByCompatibility(request.method, evidence)) {
       return null;
     }
@@ -621,12 +706,13 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
     const command = CodexOverleafCompatibility?.buildInstallCommand?.(
       getNativeRecommendedVersion(evidence),
       evidence.native?.platform || evidence.platform,
-      getCurrentExtensionId()
+      getCurrentExtensionId(),
+      extensionInstallIdentity
     );
     if (command) {
       return command;
     }
-    return evidence.updateCommand || evidence.installCommand;
+    return managedBootstrapRuntime ? '' : evidence.updateCommand || evidence.installCommand;
   }
 
   function getCurrentExtensionId() {
@@ -911,6 +997,8 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
       task: sanitizeJournalString(params.task).slice(0, 12000),
       mode: String(params.mode || ''),
       model: String(params.model || ''),
+      ownerTabId: pendingRequest.tabId,
+      ownerDocumentId: pendingRequest.documentId,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
       terminal: false,
@@ -918,6 +1006,7 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
       nextSequence: 1,
       events: []
     };
+    invalidateJournalLoad(id);
     runJournals.set(id, journal);
     pruneInMemoryRunJournals();
     return queueJournalWrite(id);
@@ -982,9 +1071,9 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
   }
 
   function sanitizeJournalString(value) {
+    // Journal replay is conversation recovery. Credential configuration is not
+    // copied by createRunJournal; quoted values in model events stay intact.
     return String(value || '')
-      .replace(/\b(?:sk|hf|glpat|npm|ghp|github_pat|AKIA|AIza)[_-]?[A-Za-z0-9_-]{12,}\b/g, '[REDACTED]')
-      .replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, '[REDACTED]')
       .replace(/(?:file:\/\/)?\/(?:Users|home|private|var|opt|Library)\/[^\s"'<>]+/g, '[local path]')
       .slice(0, 131072);
   }
@@ -994,11 +1083,15 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
     if (!storage || !runJournals.has(id)) {
       return Promise.resolve();
     }
+    const journal = runJournals.get(id);
+    const snapshot = JSON.parse(JSON.stringify(journal));
+    return queueJournalStorage(id, () => runJournals.get(id) === journal
+      ? storage.set({ [RUN_JOURNAL_PREFIX + id]: snapshot }) : undefined);
+  }
+
+  function queueJournalStorage(id, operation) {
     const previous = journalWrites.get(id) || Promise.resolve();
-    const snapshot = JSON.parse(JSON.stringify(runJournals.get(id)));
-    const next = previous.catch(() => {}).then(() => storage.set({
-      [RUN_JOURNAL_PREFIX + id]: snapshot
-    }));
+    const next = previous.catch(() => {}).then(operation);
     journalWrites.set(id, next);
     return next.finally(() => {
       if (journalWrites.get(id) === next) {
@@ -1007,7 +1100,67 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
     });
   }
 
+  function invalidateJournalLoad(id) {
+    const load = journalLoads.get(id);
+    if (load) load.cancelled = true;
+    journalLoads.delete(id);
+  }
+
+  function journalMatchesBinding(journal, binding) {
+    return journal?.requestId === binding.requestId && Boolean(binding.projectKey)
+      && journal.projectKey === binding.projectKey
+      && (!Number.isInteger(journal.ownerTabId) || journal.ownerTabId === binding.tabId)
+      && (!journal.ownerDocumentId || journal.ownerDocumentId === binding.documentId)
+      && (!binding.clientRunId || journal.clientRunId === binding.clientRunId)
+      && (!binding.sessionId || journal.sessionId === binding.sessionId);
+  }
+
+  function hasRunOwner(binding) {
+    return Array.from(ownerBindings.values()).some(owner => owner.requestId === binding.requestId
+      && owner.projectKey === binding.projectKey && owner.tabId === binding.tabId
+      && owner.documentId === binding.documentId && owner.clientRunId === binding.clientRunId
+      && owner.sessionId === binding.sessionId);
+  }
+
+  async function restoreRunJournal(binding) {
+    const id = binding.requestId;
+    if (runJournals.has(id)) {
+      const journal = runJournals.get(id);
+      return journalMatchesBinding(journal, binding) ? journal : null;
+    }
+    if (!chrome.storage?.session || !binding.projectKey) return null;
+    let load = journalLoads.get(id);
+    if (!load) {
+      load = { cancelled: false };
+      load.promise = (async () => {
+        await (journalWrites.get(id) || Promise.resolve()).catch(() => {});
+        if (load.cancelled) return null;
+        const values = await chrome.storage.session.get(RUN_JOURNAL_PREFIX + id);
+        const stored = values?.[RUN_JOURNAL_PREFIX + id];
+        if (load.cancelled || !journalMatchesBinding(stored, binding) || !Array.isArray(stored.events)) return null;
+        const journal = runJournals.get(id) || stored;
+        trimRunJournal(journal);
+        runJournals.set(id, journal);
+        return journal;
+      })().finally(() => {
+        if (journalLoads.get(id) === load) journalLoads.delete(id);
+      });
+      journalLoads.set(id, load);
+    }
+    const journal = await load.promise;
+    return journalMatchesBinding(journal, binding) ? journal : null;
+  }
+
+  function removeRunJournal(id) {
+    invalidateJournalLoad(id);
+    runJournals.delete(id);
+    // Retain the chain until removal completes; old queued writes cannot follow it.
+    return queueJournalStorage(id, () => !runJournals.has(id)
+      ? chrome.storage?.session?.remove?.(RUN_JOURNAL_PREFIX + id) : undefined);
+  }
+
   async function listRunJournals(projectKey) {
+    await Promise.allSettled(Array.from(journalLoads.values(), load => load.promise));
     await Promise.allSettled(Array.from(journalWrites.values()));
     const storage = chrome.storage?.session;
     if (!storage) {
@@ -1017,7 +1170,8 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
     const entries = Object.entries(values || {})
       .filter(([key, value]) => key.startsWith(RUN_JOURNAL_PREFIX)
         && (!projectKey || value?.projectKey === projectKey)
-        && (value?.terminal || value?.ownerLost))
+        && (value?.terminal || value?.ownerLost)
+        && !Array.from(ownerBindings.values()).some(binding => journalMatchesBinding(value, binding)))
       .sort((a, b) => String(a[1]?.createdAt || '').localeCompare(String(b[1]?.createdAt || '')));
     return entries.slice(-16).map(([_key, value]) => value);
   }
@@ -1031,9 +1185,7 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
       .sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')))
       .slice(0, runJournals.size - 16);
     for (const journal of oldest) {
-      runJournals.delete(journal.requestId);
-      journalWrites.delete(journal.requestId);
-      chrome.storage?.session?.remove?.(RUN_JOURNAL_PREFIX + journal.requestId).catch?.(() => {});
+      removeRunJournal(journal.requestId).catch(() => {});
     }
   }
 
@@ -1041,27 +1193,26 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
     if (!id) {
       return;
     }
-    await (journalWrites.get(id) || Promise.resolve()).catch(() => {});
-    runJournals.delete(id);
-    journalWrites.delete(id);
-    await chrome.storage?.session?.remove?.(RUN_JOURNAL_PREFIX + id);
+    await removeRunJournal(id);
   }
 
   async function interruptOwnerlessRun(binding) {
     ownerCancelTimers.delete(binding.requestId);
-    if (Array.from(ownerBindings.values()).some(value => value.requestId === binding.requestId)) {
+    if (hasRunOwner(binding)) {
       return;
     }
-    const journal = runJournals.get(binding.requestId);
+    const journal = await restoreRunJournal(binding).catch(() => null);
+    if (hasRunOwner(binding)) return;
+    if (journal && runJournals.get(binding.requestId) !== journal) return;
     if (journal) {
       journal.ownerLost = true;
       journal.updatedAt = new Date().toISOString();
       await queueJournalWrite(binding.requestId).catch(() => {});
     }
-    if (!pending.has(binding.requestId)) {
-      return;
-    }
+    if (hasRunOwner(binding)) return;
+    if (journal && runJournals.get(binding.requestId) !== journal) return;
     try {
+      if (!pending.has(binding.requestId) || !journalMatchesBinding(journal, binding)) return;
       sendNativeCancel({
         method: 'codex.cancel',
         params: {
@@ -1071,6 +1222,8 @@ if (!globalThis.CodexOverleafUpdateRuntimeIdentity) {
       });
     } catch (_error) {
       // The original request disconnect path will settle the journal.
+    } finally {
+      pruneInMemoryRunJournals();
     }
   }
 })();

package/extension/src/backgroundBootstrapMigration.js

@@ -0,0 +1,181 @@
+(function initBootstrapMigration(root) {
+  'use strict';
+
+  const UPDATE_STATE_KEY = 'codex-overleaf-managed-update-state-v1';
+  const RETRY_ALARM = 'codex-overleaf-bootstrap-migration-retry';
+  const RETRY_MS = 4000;
+  const MAX_WAIT_MS = 2 * 60 * 1000;
+  let readyPromise;
+  let lockedOwner;
+  let setExecutionLocked;
+
+  function init(options) {
+    if (readyPromise) return readyPromise;
+    readyPromise = prepare(options);
+    return readyPromise;
+  }
+
+  async function prepare(options) {
+    let transaction;
+    let reloadProtected = false;
+    let rollbackState = 'bootstrap_pending';
+    const revision = String(root.__CODEX_OVERLEAF_BOOTSTRAP_REVISION__ || '');
+    const request = async (method, params = {}) => {
+      const response = await options.request({ id: crypto.randomUUID(), method,
+        params: { ...params, bootstrapRevision: revision } });
+      if (!response?.ok) throw Object.assign(new Error(response?.error?.message || 'Managed update request failed.'),
+        { code: response?.error?.code || 'update_health_failed' });
+      return response.result || {};
+    };
+    try {
+      const status = await request('update.status');
+      transaction = status.transaction;
+      if (transaction?.state !== 'bootstrap_pending') return { continueInitialization: true };
+      options.setExecutionLocked(true);
+      lockedOwner = { id: transaction.id, targetVersion: transaction.targetVersion, revision };
+      setExecutionLocked = options.setExecutionLocked;
+      if (!transaction.id || transaction.targetVersion !== root.CodexOverleafCompatibility?.BUILD_TARGET_VERSION) {
+        throw codedError('The running update does not match the pending Bootstrap transaction.');
+      }
+      reloadProtected = await options.protectReloadTabs(transaction);
+      if (!reloadProtected) throw codedError('The previous page refresh list could not be protected.');
+      await writeState({ state: 'awaiting_health', transactionId: transaction.id,
+        latestVersion: transaction.targetVersion, code: '', message: '' });
+
+      // The first reload may leave old content contexts alive. Recheck the same
+      // idle/save contract before replacing their loader and reloading again.
+      const deadline = Date.now() + MAX_WAIT_MS;
+      while (true) {
+        const gate = await options.verifySafety({ transactionId: transaction.id, targetVersion: transaction.targetVersion,
+          sourceVersion: transaction.sourceVersion, expectedState: 'bootstrap_pending' });
+        if (gate?.ok) break;
+        if (Date.now() >= deadline) throw codedError('The Bootstrap update did not reach a safe point.');
+        await writeState({ blockers: gate?.error?.blockers || ['busy'] });
+        await waitForRetry();
+        const refreshed = await request('update.status');
+        if (refreshed.transaction?.id !== transaction.id || refreshed.transaction?.state !== 'bootstrap_pending') {
+          throw Object.assign(codedError('The pending Bootstrap transaction changed before activation.'), { restoredStatus: refreshed });
+        }
+      }
+
+      const result = await request('update.bootstrap', { transactionId: transaction.id });
+      if (result.transactionId !== transaction.id || result.targetVersion !== transaction.targetVersion) {
+        throw codedError('The Bootstrap activation result does not match the pending update.');
+      }
+      await writeState({ blockers: [], blocker: '' });
+      if (result.state === 'reload_required') {
+        // Only one reload per worker. Native owns the persistent attempt limit
+        // so a broken target cannot create a loop across worker restarts.
+        chrome.runtime.reload();
+        return { continueInitialization: false, state: result.state };
+      }
+      if (result.state !== 'awaiting_health' || revision !== '3.1' || result.bootstrapRevision !== revision) {
+        throw codedError('The updated Bootstrap did not provide its loaded revision.');
+      }
+      rollbackState = 'awaiting_health';
+      if (!await options.releaseReloadTabs(transaction, 'awaiting_health')) throw codedError('The original page identities could not be confirmed.');
+      return { continueInitialization: true, state: result.state };
+    } catch (error) {
+      if (!transaction || transaction.state !== 'bootstrap_pending') return { continueInitialization: true };
+      if (!reloadProtected) {
+        await writeState({ state: 'failed', recoveryPending: true, code: 'update_recovery_pending' }).catch(() => {});
+        return { continueInitialization: false, state: 'failed' };
+      }
+      const code = /^[a-z0-9_]{1,80}$/.test(error?.code || '') ? error.code : 'update_health_failed';
+      await writeState({ state: 'rolling_back', code }).catch(() => {});
+      let restored = false;
+      try {
+        let status = error.restoredStatus;
+        let rollback = status && { transactionId: status.transaction?.id, state: status.transaction?.state,
+          version: status.activeVersion, restoredPair: status.restoredPair };
+        if (!hasRestoredSource(transaction, rollback, status)) {
+          rollback = await request('update.rollback', { transactionId: transaction.id,
+            expectedState: rollbackState, reasonCode: code });
+          status = await request('update.status');
+        }
+        if (!hasRestoredSource(transaction, rollback, status)) throw codedError('Bootstrap rollback is unconfirmed.');
+        await writeState({ state: 'rolled_back', currentVersion: transaction.sourceVersion,
+          transactionId: transaction.id, recoveryPending: false, blockers: [], blocker: '', code });
+        restored = true;
+        while (true) {
+          try {
+            // A new document must never inherit the old document's refresh
+            // authorization. The source worker sees an empty legacy list;
+            // the guarded evidence remains for a later natural/user refresh.
+            if (await options.hasReplacedReloadDocument(transaction)) break;
+            const gate = await options.verifySafety({ transactionId: transaction.id, targetVersion: transaction.targetVersion,
+              sourceVersion: transaction.sourceVersion, expectedState: 'rolled_back' });
+            if (gate?.ok && await options.releaseReloadTabs(transaction, 'rolled_back')) break;
+          } catch (_) { /* Restored files stay restored while a page probe retries. */ }
+          await waitForRetry();
+        }
+        chrome.runtime.reload();
+        return { continueInitialization: false, state: 'rolled_back' };
+      } catch (_rollbackError) {
+        if (restored) return { continueInitialization: false, state: 'rolled_back' };
+        await writeState({ state: 'failed', recoveryPending: true, transactionId: transaction.id,
+          code: 'update_recovery_pending', message: 'The installed update result has not been confirmed.' }).catch(() => {});
+        return { continueInitialization: false, state: 'failed' };
+      }
+    } finally {
+      await chrome.alarms?.clear?.(RETRY_ALARM).catch?.(() => {});
+    }
+  }
+
+  async function writeState(patch) {
+    const stored = await chrome.storage.local.get(UPDATE_STATE_KEY);
+    const state = root.CodexOverleafManagedUpdateProjection.transition(stored[UPDATE_STATE_KEY] || {}, patch,
+      { currentVersion: chrome.runtime.getManifest().version });
+    await chrome.storage.local.set({ [UPDATE_STATE_KEY]: state });
+  }
+
+  function waitForRetry() {
+    return new Promise(resolve => {
+      let settled = false;
+      let timer;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        chrome.alarms?.onAlarm?.removeListener?.(onAlarm);
+        resolve();
+      };
+      const onAlarm = alarm => { if (alarm?.name === RETRY_ALARM) finish(); };
+      chrome.alarms?.onAlarm?.addListener?.(onAlarm);
+      chrome.alarms?.create?.(RETRY_ALARM, { delayInMinutes: 0.5 });
+      timer = setTimeout(finish, RETRY_MS);
+    });
+  }
+
+  function hasRestoredSource(transaction, rollback, status) {
+    const pair = status?.restoredPair;
+    return rollback?.transactionId === transaction.id && rollback.state === 'rolled_back'
+      && rollback.version === transaction.sourceVersion && status?.transaction?.id === transaction.id
+      && status.transaction.state === 'rolled_back' && status.activeVersion === transaction.sourceVersion
+      && status.installedAligned === true && pair?.extensionVersion === transaction.sourceVersion
+      && pair?.nativeVersion === transaction.sourceVersion
+      && /^[0-9a-f]{64}$/.test(pair.extensionSha256 || '') && /^[0-9a-f]{64}$/.test(pair.nativeSha256 || '')
+      && /^[0-9a-f]{64}$/.test(pair.bootstrapSha256 || '')
+      && ['extensionVersion', 'nativeVersion', 'extensionSha256', 'nativeSha256', 'bootstrapSha256']
+        .every(key => pair[key] === rollback.restoredPair?.[key]);
+  }
+
+  function codedError(message) {
+    return Object.assign(new Error(message), { code: 'update_health_failed' });
+  }
+
+  function observeConfirmation(params, response) {
+    if (!lockedOwner || !response?.ok || response.result?.state !== 'committed'
+      || response.result.version !== lockedOwner.targetVersion || params?.transactionId !== lockedOwner.id
+      || params.extensionVersion !== lockedOwner.targetVersion || params.nativeVersion !== lockedOwner.targetVersion
+      || params.bootstrapRevision !== lockedOwner.revision || lockedOwner.revision !== '3.1') return;
+    lockedOwner = null;
+    setExecutionLocked(false);
+  }
+
+  root.CodexOverleafBootstrapMigration = Object.freeze({
+    init,
+    observeConfirmation,
+    ready: () => readyPromise || Promise.resolve({ continueInitialization: true })
+  });
+})(globalThis);