codex-overleaf-link 1.8.6 → 1.9.0

package/README.md

@@ -3,7 +3,7 @@
   <h1>Codex Overleaf Link</h1>
   <p><strong>Empower Overleaf with Codex.</strong></p>
   <p>
-    <img src="https://img.shields.io/badge/version-1.8.6-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.9.0-blue" alt="version">
     <img src="https://img.shields.io/badge/platform-macOS%20%2F%20Windows%20%2F%20Linux-lightgrey" alt="platform">
     <img src="https://img.shields.io/badge/chrome-MV3-green" alt="chrome manifest v3">
     <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node version">
@@ -38,14 +38,14 @@ One command installs the native host **and** sets up the extension: the script r
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.8.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.8.6/install.sh)"
+CODEX_OVERLEAF_REF=v1.9.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.9.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.8.6/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.8.6'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.9.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.9.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -56,10 +56,10 @@ Then, in the `chrome://extensions` tab the script opened: enable **Developer mod
 `npm exec` installs and updates the **native host only** — it does not include the Chrome extension. Use it if you prefer a pinned npm package to a source checkout.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.8.6 -- install-native
+npm exec --yes codex-overleaf-link@1.9.0 -- install-managed
 ```
 
-Then add the extension yourself: download `codex-overleaf-link-extension-v1.8.6.zip` from the [v1.8.6 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.8.6), unzip it to a stable folder, and in `chrome://extensions` enable **Developer mode**, click **Load unpacked**, and select that folder.
+Then add the extension yourself: download `codex-overleaf-link-extension-v1.9.0.zip` from the [v1.9.0 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.9.0), unzip it to a stable folder, and in `chrome://extensions` enable **Developer mode**, click **Load unpacked**, and select that folder.
 
 ### Open Overleaf
 
@@ -86,9 +86,9 @@ npm installs, updates, uninstalls, and diagnoses the native host only. npm does
 
 | Action | Command |
 |--------|---------|
-| Install / update | `npm exec --yes codex-overleaf-link@1.8.6 -- install-native` |
-| Diagnose | `npm exec --yes codex-overleaf-link@1.8.6 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@1.8.6 -- uninstall-native` |
+| Install / update | `npm exec --yes codex-overleaf-link@1.9.0 -- install-managed` |
+| Diagnose | `npm exec --yes codex-overleaf-link@1.9.0 -- doctor` |
+| Uninstall | `npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-managed` |
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id.
 
@@ -98,13 +98,13 @@ To update, re-run any of the [native host installers](#install) — they install
 
 ## GitHub Release Artifacts
 
-The v1.8.6 GitHub Release contains:
+The v1.9.0 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.8.6.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.8.6.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.8.6.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
-- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.8.6` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.8.6` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v1.9.0.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v1.9.0.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-1.9.0.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
+- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.9.0` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.9.0` when run directly from the release artifact.
 - `uninstall-native-host.mjs`: native host uninstaller that removes the Chrome Native Messaging manifest, bridge executable, and runtime copy.
 - `nativeHostPlatform.js`, `manifest.js`, `runtimeInstaller.js`: helper files required by the loose uninstaller asset.
 - `SHA256SUMS` and `release-manifest.json`: checksum and artifact metadata for release verification.
@@ -115,7 +115,7 @@ The v1.8.6 GitHub Release contains:
 Remove the native host (use `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@1.8.6 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-managed
 ```
 
 The same command works on Windows PowerShell. If you installed from a manual checkout or source installer, you can also run `npm run uninstall:native` inside the repo, use `node ~/.codex-overleaf/source/scripts/uninstall-native-host.mjs` on macOS / Linux, or use `node $env:LOCALAPPDATA\CodexOverleaf\source\scripts\uninstall-native-host.mjs` on Windows PowerShell.
@@ -150,13 +150,13 @@ Then remove the extension from `chrome://extensions`. To delete local data: on m
 Linux Chromium install or update:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.8.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.8.6/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v1.9.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.9.0/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.8.6 -- uninstall-native --browser chromium
+npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-managed --browser chromium
 ```
 
 ## Features
@@ -291,7 +291,7 @@ Composer attachments are turn-scoped Codex context. Limits are 8 attachments per
 Re-run any [native host installer](#install), reload the extension in `chrome://extensions`, then refresh the Overleaf tab. This also fixes extension/native version mismatch and native protocol mismatch.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.8.6 -- install-native
+npm exec --yes codex-overleaf-link@1.9.0 -- install-managed
 ```
 
 **The Windows popup or panel shows a Bash recovery command**
@@ -340,8 +340,8 @@ Use this matrix for release-candidate signoff and compatibility reports. Record
 | Browser/channel/version | Google Chrome channel and version. | Google Chrome channel and version. | Google Chrome channel and version. | Chromium channel/package and version. |
 | Install mode | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout; native host installed with `--browser chromium`. |
 | Extension id | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. |
-| Installer/update command | `npm exec --yes codex-overleaf-link@1.8.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.8.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.8.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.8.6 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.8.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.8.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.8.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.8.6 -- uninstall-native --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@1.9.0 -- install-managed` | `npm exec --yes codex-overleaf-link@1.9.0 -- install-managed` | `npm exec --yes codex-overleaf-link@1.9.0 -- install-managed` | `npm exec --yes codex-overleaf-link@1.9.0 -- install-managed --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-managed --browser chromium` |
 | Manifest/registry path | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.codex.overleaf.json` | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` -> `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime\com.codex.overleaf.json` | `~/.config/google-chrome/NativeMessagingHosts/com.codex.overleaf.json` | `~/.config/chromium/NativeMessagingHosts/com.codex.overleaf.json` |
 | Bridge/runtime/source path | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `%LOCALAPPDATA%\CodexOverleaf\codex-overleaf-bridge.cmd`; runtime `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime`; source `%LOCALAPPDATA%\CodexOverleaf\source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. |
 | Node/Git/Codex/TeX | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. |
@@ -371,3 +371,27 @@ Contributions are welcome. Please open an issue before submitting large changes
 ## License
 
 [MIT](LICENSE)
+
+## Managed Stable Updates (v1.9)
+
+The recommended v1.9 installation owns one stable unpacked-extension directory and a versioned native-host directory:
+
+```bash
+npm exec --yes codex-overleaf-link@1.9.0 -- install-managed
+```
+
+Load the printed extension path once from `chrome://extensions`. Starting with the next signed stable release, Codex Overleaf Link checks GitHub Releases automatically, downloads and verifies the coordinated extension/native-host bundle, waits until every connected Overleaf tab is saved and idle, and then updates both components together. A failed health check restores the previous version automatically.
+
+The stable updater ignores drafts and prereleases, performs no telemetry, and cannot add Chrome permissions silently. Releases that require a newer Bootstrap protocol display manual migration guidance.
+
+The legacy native-only installer remains available for source or unmanaged extension directories:
+
+```bash
+npm exec --yes codex-overleaf-link@1.9.0 -- install-native
+```
+
+Legacy native-only installations can be removed with:
+
+```bash
+npm exec --yes codex-overleaf-link@1.9.0 -- uninstall-native
+```

package/bin/codex-overleaf-link.mjs

@@ -18,6 +18,8 @@ function printHelp() {
   console.log(`codex-overleaf-link ${packageJson.version}
 
 Commands:
+  install-managed   Install the managed extension and native host
+  uninstall-managed Remove the managed extension and native host
   install-native    Install the native host
   uninstall-native  Uninstall the native host
   doctor            Check local native host setup
@@ -29,6 +31,7 @@ const OPTION_DEFINITIONS = {
   '--extension-id': { key: 'extensionId', takesValue: true },
   '--browser': { key: 'browser', takesValue: true },
   '--runtime-root': { key: 'runtimeRoot', takesValue: true },
+  '--managed-root': { key: 'managedRoot', takesValue: true },
   '--force': { key: 'force', takesValue: false },
   '--keep-runtime': { key: 'keepRuntime', takesValue: false },
   '--reveal-paths': { key: 'revealPaths', takesValue: false },
@@ -56,6 +59,21 @@ const UNINSTALL_NATIVE_OPTIONS = new Set([
   '--help'
 ]);
 
+const INSTALL_MANAGED_OPTIONS = new Set([
+  '--extension-id',
+  '--browser',
+  '--managed-root',
+  '--json',
+  '--help'
+]);
+
+const UNINSTALL_MANAGED_OPTIONS = new Set([
+  '--browser',
+  '--managed-root',
+  '--json',
+  '--help'
+]);
+
 function parseNativeArgs(argv, allowedOptions) {
   const parsed = {};
 
@@ -139,6 +157,46 @@ switch (command) {
       console.log(packageJson.version);
     }
     break;
+  case 'install-managed': {
+    let installArgs;
+    try {
+      installArgs = parseNativeArgs(args, INSTALL_MANAGED_OPTIONS);
+    } catch (error) {
+      exitWithError(error);
+    }
+    if (installArgs.help) {
+      printHelp();
+      break;
+    }
+    try {
+      const { formatInstallManagedHuman, installManaged } = await import('../scripts/install-managed.mjs');
+      const result = installManaged({ ...installArgs, packageRoot });
+      process.stdout.write(installArgs.json ? JSON.stringify(result, null, 2) + '\n' : formatInstallManagedHuman(result));
+    } catch (error) {
+      exitWithError(error);
+    }
+    break;
+  }
+  case 'uninstall-managed': {
+    let uninstallArgs;
+    try {
+      uninstallArgs = parseNativeArgs(args, UNINSTALL_MANAGED_OPTIONS);
+    } catch (error) {
+      exitWithError(error);
+    }
+    if (uninstallArgs.help) {
+      printHelp();
+      break;
+    }
+    try {
+      const { uninstallManaged } = await import('../scripts/uninstall-managed.mjs');
+      const result = uninstallManaged(uninstallArgs);
+      process.stdout.write(uninstallArgs.json ? JSON.stringify(result, null, 2) + '\n' : 'Removed managed Codex Overleaf Link installation.\n');
+    } catch (error) {
+      exitWithError(error);
+    }
+    break;
+  }
   case 'install-native': {
     let installArgs;
     try {

package/extension/bootstrap/background.js

@@ -0,0 +1,404 @@
+'use strict';
+
+const CODEX_OVERLEAF_HOST = 'com.codex.overleaf';
+const RUNTIME_SCRIPT_ID = 'codex-overleaf-managed-runtime';
+const UPDATE_STATE_KEY = 'codex-overleaf-managed-update-state-v1';
+const UPDATE_RELOAD_TABS_KEY = 'codex-overleaf-managed-update-tabs-v1';
+const CHECK_ALARM = 'codex-overleaf-stable-update-check';
+const IDLE_ALARM = 'codex-overleaf-staged-update-idle';
+const OVERLEAF_MATCHES = [
+  'https://www.overleaf.com/project/*',
+  'https://overleaf.com/project/*'
+];
+const APPLYING_STATES = new Set(['applying', 'awaiting_health', 'rolling_back']);
+
+let runtimeLoadError = null;
+try {
+  globalThis.__CODEX_OVERLEAF_RUNTIME_BASE__ = 'runtime';
+  importScripts(
+    chrome.runtime.getURL('runtime/src/shared/compatibility.js'),
+    chrome.runtime.getURL('runtime/src/background.js')
+  );
+} catch (error) {
+  runtimeLoadError = error;
+}
+
+chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+  if (message?.type === 'codex-overleaf/update-get-state') {
+    getUpdateState().then(sendResponse);
+    return true;
+  }
+  if (message?.type === 'codex-overleaf/update-check-now') {
+    checkAndStage({ manual: true }).then(sendResponse).catch(error => sendResponse(failureBody(error)));
+    return true;
+  }
+  if (message?.type === 'codex-overleaf/update-postpone') {
+    postponeUpdate().then(sendResponse);
+    return true;
+  }
+  return undefined;
+});
+
+chrome.alarms.onAlarm.addListener(alarm => {
+  if (alarm.name === CHECK_ALARM) {
+    checkAndStage().catch(() => {});
+  }
+  if (alarm.name === IDLE_ALARM) {
+    tryApplyStagedUpdate().catch(() => {});
+  }
+});
+
+initializeBootstrap().catch(async error => {
+  await setUpdateState({ state: 'failed', code: safeCode(error), message: safeMessage(error) });
+});
+
+async function initializeBootstrap() {
+  try {
+    await registerManagedRuntime();
+  } catch (error) {
+    runtimeLoadError = runtimeLoadError || error;
+  }
+
+  if (runtimeLoadError) {
+    await rollbackBrokenRuntime(runtimeLoadError);
+    return;
+  }
+
+  const nativeStatus = await requestInternal({ method: 'update.status', params: {} }).catch(() => null);
+  const transaction = nativeStatus?.ok ? nativeStatus.result?.transaction : null;
+  if (transaction?.state === 'awaiting_health') {
+    await confirmPendingUpdate(transaction);
+  } else if (transaction?.state === 'rolled_back') {
+    await reloadPendingOverleafTabs();
+  }
+
+  chrome.alarms.create(CHECK_ALARM, { delayInMinutes: 0.5, periodInMinutes: 24 * 60 });
+  const state = await getUpdateState();
+  if (state.state === 'staged' || state.state === 'waiting_for_idle') {
+    chrome.alarms.create(IDLE_ALARM, { delayInMinutes: 0.1 });
+  }
+}
+
+async function registerManagedRuntime() {
+  const response = await fetch(chrome.runtime.getURL('runtime/runtime-manifest.json'), { cache: 'no-store' });
+  if (!response.ok) {
+    throw new Error('Managed runtime manifest could not be loaded.');
+  }
+  const manifest = await response.json();
+  validateRuntimeManifest(manifest);
+  const registered = await chrome.scripting.getRegisteredContentScripts({ ids: [RUNTIME_SCRIPT_ID] });
+  if (registered.length) {
+    await chrome.scripting.unregisterContentScripts({ ids: [RUNTIME_SCRIPT_ID] });
+  }
+  await chrome.scripting.registerContentScripts([{
+    id: RUNTIME_SCRIPT_ID,
+    matches: manifest.matches,
+    js: ['bootstrap/runtimeContext.js', ...manifest.js.map(value => 'runtime/' + value)],
+    css: manifest.css.map(value => 'runtime/' + value),
+    runAt: manifest.runAt || 'document_idle',
+    persistAcrossSessions: true
+  }]);
+}
+
+function validateRuntimeManifest(manifest) {
+  if (!manifest || manifest.schemaVersion !== 1 || !Array.isArray(manifest.matches) || !Array.isArray(manifest.js) || !Array.isArray(manifest.css)) {
+    throw new Error('Managed runtime manifest is invalid.');
+  }
+  if (!manifest.matches.length || manifest.matches.some(value => !OVERLEAF_MATCHES.includes(value))) {
+    throw new Error('Managed runtime match patterns are invalid.');
+  }
+  const paths = [...manifest.js, ...manifest.css];
+  if (!manifest.js.length || paths.some(value => typeof value !== 'string' || value.startsWith('/') || value.includes('..') || !/^[a-zA-Z0-9_./-]+$/.test(value))) {
+    throw new Error('Managed runtime file list is invalid.');
+  }
+}
+
+async function checkAndStage(options = {}) {
+  const current = await getUpdateState();
+  if (APPLYING_STATES.has(current.state)) {
+    return current;
+  }
+  if (!options.manual && Number(current.postponeUntil || 0) > Date.now()) {
+    return current;
+  }
+  await setUpdateState({ ...current, state: 'checking', code: '', message: '' });
+  const checked = await requestInternal({
+    method: 'update.check',
+    params: {
+      currentVersion: chrome.runtime.getManifest().version,
+      etag: current.etag || ''
+    }
+  });
+  if (!checked?.ok) {
+    const code = checked?.error?.code || 'update_check_failed';
+    if (code === 'update_not_managed') {
+      return setUpdateState({ state: 'idle', managed: false, code, message: checked.error.message });
+    }
+    throw nativeError(checked);
+  }
+  const checkResult = checked.result || {};
+  if (!checkResult.available) {
+    return setUpdateState({
+      state: 'idle',
+      managed: checkResult.managed !== false,
+      currentVersion: chrome.runtime.getManifest().version,
+      latestVersion: checkResult.latestVersion || chrome.runtime.getManifest().version,
+      etag: checkResult.etag || current.etag || '',
+      lastCheckedAt: Date.now(),
+      code: checkResult.reason || '',
+      message: ''
+    });
+  }
+
+  await setUpdateState({
+    ...current,
+    state: 'update_available',
+    managed: true,
+    currentVersion: chrome.runtime.getManifest().version,
+    latestVersion: checkResult.latestVersion,
+    etag: checkResult.etag || '',
+    lastCheckedAt: Date.now()
+  });
+  await setUpdateState({ state: 'downloading', managed: true, currentVersion: chrome.runtime.getManifest().version, latestVersion: checkResult.latestVersion });
+  const staged = await requestInternal({ method: 'update.stage', params: {} });
+  if (!staged?.ok) {
+    throw nativeError(staged);
+  }
+  await setUpdateState({
+    state: 'staged',
+    managed: true,
+    currentVersion: chrome.runtime.getManifest().version,
+    latestVersion: staged.result.targetVersion,
+    transactionId: staged.result.transactionId,
+    stagedAt: Date.now()
+  });
+  await broadcastUpdateState('staged');
+  chrome.alarms.create(IDLE_ALARM, { delayInMinutes: 0.1 });
+  return tryApplyStagedUpdate();
+}
+
+async function tryApplyStagedUpdate() {
+  const state = await getUpdateState();
+  if (!['staged', 'waiting_for_idle'].includes(state.state)) {
+    return state;
+  }
+  if (Number(state.postponeUntil || 0) > Date.now()) {
+    return state;
+  }
+  const tabs = await chrome.tabs.query({ url: OVERLEAF_MATCHES });
+  const probes = await Promise.all(tabs.map(tab => probeTabIdle(tab)));
+  const tabBlocker = probes.find(probe => probe.idle !== true);
+  const nativeGate = await requestInternal({ method: 'update.canApply', params: {} });
+  if (tabBlocker || !nativeGate?.ok || nativeGate.result?.idle !== true) {
+    const waiting = await setUpdateState({
+      ...state,
+      state: 'waiting_for_idle',
+      blocker: tabBlocker?.blockers?.[0] || nativeGate?.result?.blockers?.[0] || 'busy'
+    });
+    chrome.alarms.create(IDLE_ALARM, { delayInMinutes: 1 });
+    return waiting;
+  }
+
+  await chrome.storage.local.set({ [UPDATE_RELOAD_TABS_KEY]: tabs.map(tab => tab.id).filter(Number.isInteger) });
+  await setUpdateState({ ...state, state: 'applying', blocker: '' });
+  await broadcastUpdateState('applying');
+  const applied = await requestInternal({
+    method: 'update.apply',
+    params: { transactionId: state.transactionId }
+  });
+  if (!applied?.ok) {
+    throw nativeError(applied);
+  }
+  await setUpdateState({ ...state, state: 'awaiting_health', latestVersion: applied.result.targetVersion });
+  chrome.runtime.reload();
+  return { state: 'awaiting_health' };
+}
+
+async function probeTabIdle(tab) {
+  if (!Number.isInteger(tab?.id)) {
+    return { idle: false, blockers: ['tab_unavailable'] };
+  }
+  try {
+    return await withTimeout(
+      chrome.tabs.sendMessage(tab.id, { type: 'codex-overleaf/update-idle-probe' }),
+      3500,
+      { idle: false, blockers: ['tab_probe_timeout'] }
+    );
+  } catch (_error) {
+    return { idle: false, blockers: ['tab_probe_unavailable'] };
+  }
+}
+
+async function confirmPendingUpdate(transaction) {
+  const targetVersion = transaction.targetVersion;
+  const runtimeHealthy = await verifyPendingRuntimeHealth(targetVersion);
+  if (!runtimeHealthy) {
+    await rollbackBrokenRuntime(new Error('Updated Overleaf content runtime did not report the target version.'));
+    return;
+  }
+  const ping = await requestInternal({ method: 'bridge.ping', params: {} }).catch(() => null);
+  if (!ping?.ok || ping.result?.version !== targetVersion) {
+    await rollbackBrokenRuntime(new Error('Updated native host did not report the target version.'));
+    return;
+  }
+  const confirmed = await requestInternal({
+    method: 'update.confirm',
+    params: {
+      transactionId: transaction.id,
+      extensionVersion: chrome.runtime.getManifest().version,
+      nativeVersion: ping.result.version
+    }
+  });
+  if (!confirmed?.ok) {
+    await rollbackBrokenRuntime(nativeError(confirmed));
+    return;
+  }
+  await setUpdateState({
+    state: 'committed',
+    managed: true,
+    currentVersion: targetVersion,
+    latestVersion: targetVersion,
+    lastCheckedAt: Date.now()
+  });
+  await chrome.storage.local.remove(UPDATE_RELOAD_TABS_KEY);
+  await broadcastUpdateState('committed');
+}
+
+async function verifyPendingRuntimeHealth(targetVersion) {
+  const tabIds = await getPendingOverleafTabIds();
+  if (!tabIds.length) return true;
+  await Promise.allSettled(tabIds.map(tabId => chrome.tabs.reload(tabId)));
+  const remaining = new Set(tabIds);
+  const deadline = Date.now() + 20000;
+  while (remaining.size && Date.now() < deadline) {
+    await Promise.all([...remaining].map(async tabId => {
+      try {
+        const response = await withTimeout(
+          chrome.tabs.sendMessage(tabId, { type: 'codex-overleaf/runtime-health-probe' }),
+          2500,
+          null
+        );
+        if (response?.ok === true && response.version === targetVersion) {
+          remaining.delete(tabId);
+        }
+      } catch (_error) {
+        // The tab may still be reloading; retry until the bounded deadline.
+      }
+    }));
+    if (remaining.size) await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  return remaining.size === 0;
+}
+
+async function rollbackBrokenRuntime(error) {
+  await setUpdateState({ state: 'rolling_back', code: safeCode(error), message: safeMessage(error) });
+  const rolledBack = await requestInternal({
+    method: 'update.rollback',
+    params: { reasonCode: safeCode(error) }
+  }).catch(() => null);
+  if (rolledBack?.ok) {
+    await setUpdateState({ state: 'rolled_back', code: safeCode(error), currentVersion: rolledBack.result.version });
+    chrome.runtime.reload();
+    return;
+  }
+  await setUpdateState({ state: 'failed', code: safeCode(error), message: safeMessage(error) });
+}
+
+async function reloadPendingOverleafTabs() {
+  const tabIds = await getPendingOverleafTabIds();
+  await chrome.storage.local.remove(UPDATE_RELOAD_TABS_KEY);
+  await Promise.allSettled(tabIds.map(tabId => chrome.tabs.reload(tabId)));
+}
+
+async function getPendingOverleafTabIds() {
+  const stored = await chrome.storage.local.get(UPDATE_RELOAD_TABS_KEY);
+  const tabIds = Array.isArray(stored[UPDATE_RELOAD_TABS_KEY]) ? stored[UPDATE_RELOAD_TABS_KEY] : [];
+  const openTabs = await chrome.tabs.query({ url: OVERLEAF_MATCHES });
+  const openIds = new Set(openTabs.map(tab => tab.id).filter(Number.isInteger));
+  return [...new Set(tabIds.filter(tabId => Number.isInteger(tabId) && openIds.has(tabId)))];
+}
+
+async function postponeUpdate() {
+  const state = await getUpdateState();
+  return setUpdateState({ ...state, postponeUntil: Date.now() + 24 * 60 * 60 * 1000 });
+}
+
+async function requestInternal(payload) {
+  if (globalThis.CodexOverleafNativeBridge?.requestInternal) {
+    return globalThis.CodexOverleafNativeBridge.requestInternal({
+      id: crypto.randomUUID(),
+      ...payload
+    });
+  }
+  return new Promise((resolve, reject) => {
+    chrome.runtime.sendNativeMessage(CODEX_OVERLEAF_HOST, {
+      id: crypto.randomUUID(),
+      ...payload
+    }, response => {
+      const error = chrome.runtime.lastError;
+      if (error) reject(new Error(error.message));
+      else resolve(response);
+    });
+  });
+}
+
+async function getUpdateState() {
+  const stored = await chrome.storage.local.get(UPDATE_STATE_KEY);
+  return stored[UPDATE_STATE_KEY] || {
+    state: 'idle',
+    managed: true,
+    currentVersion: chrome.runtime.getManifest().version,
+    latestVersion: chrome.runtime.getManifest().version
+  };
+}
+
+async function setUpdateState(next) {
+  const value = {
+    state: next.state || 'idle',
+    managed: next.managed !== false,
+    currentVersion: next.currentVersion || chrome.runtime.getManifest().version,
+    latestVersion: next.latestVersion || next.currentVersion || chrome.runtime.getManifest().version,
+    etag: next.etag || '',
+    lastCheckedAt: Number(next.lastCheckedAt || 0),
+    stagedAt: Number(next.stagedAt || 0),
+    postponeUntil: Number(next.postponeUntil || 0),
+    transactionId: next.transactionId || '',
+    blocker: next.blocker || '',
+    code: next.code || '',
+    message: String(next.message || '').slice(0, 300)
+  };
+  await chrome.storage.local.set({ [UPDATE_STATE_KEY]: value });
+  return value;
+}
+
+async function broadcastUpdateState(state) {
+  const tabs = await chrome.tabs.query({ url: OVERLEAF_MATCHES });
+  await Promise.allSettled(tabs.filter(tab => Number.isInteger(tab.id)).map(tab => (
+    chrome.tabs.sendMessage(tab.id, { type: 'codex-overleaf/update-state', state })
+  )));
+}
+
+function withTimeout(promise, timeoutMs, fallback) {
+  return Promise.race([
+    promise,
+    new Promise(resolve => setTimeout(() => resolve(fallback), timeoutMs))
+  ]);
+}
+
+function nativeError(response) {
+  const error = new Error(response?.error?.message || 'Managed update request failed.');
+  error.code = response?.error?.code || 'update_request_failed';
+  return error;
+}
+
+function safeCode(error) {
+  return /^[a-z0-9_]{1,80}$/.test(String(error?.code || '')) ? error.code : 'update_health_failed';
+}
+
+function safeMessage(error) {
+  return String(error?.message || 'Managed update failed.').replace(/(?:file:\/\/)?(?:[A-Za-z]:[\\/]|\/Users\/|\/home\/)[^\s]*/g, '[local path]').slice(0, 300);
+}
+
+function failureBody(error) {
+  return { ok: false, error: { code: safeCode(error), message: safeMessage(error) } };
+}