codex-overleaf-link 2.5.0 → 2.5.1

package/README.md

@@ -2,16 +2,24 @@
   <img src="extension/assets/icons/codex-overleaf-icon.png" width="72" alt="Codex Overleaf Link">
   <h1>Codex Overleaf Link</h1>
   <p><strong>Empower Overleaf with Codex.</strong></p>
-  <p><img src="https://img.shields.io/badge/version-2.5.0-blue" alt="version 2.5.0"></p>
+  <p><img src="https://img.shields.io/badge/version-2.5.1-blue" alt="version 2.5.1"></p>
   <p>English | <a href="README.zh-CN.md">简体中文</a></p>
   <p>Chrome · macOS / Windows / Linux · Local Codex</p>
+  <p>
+    <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">
+    <a href="https://github.com/Ghqqqq/codex-overleaf-link/actions/workflows/test.yml"><img src="https://github.com/Ghqqqq/codex-overleaf-link/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+    <img src="https://img.shields.io/badge/runtime%20dependencies-0-orange" alt="zero npm runtime dependencies">
+    <img src="https://img.shields.io/badge/license-MIT-blue" alt="license">
+  </p>
 </div>
 
 Ask about the project, revise a passage, and review the result beside the PDF. Codex Overleaf Link brings a local Codex workflow into the Overleaf editor, with project context, model selection, and conversations in one place.
 
 ![The source editor, PDF preview, and a real Codex project review in the Example paper demo](assets/readme/2.5.0/overview@2x.png)
 
-*Actual 2.5.0 interface. A read-only review of the standard Overleaf example project.*
+*Interface captured on 2.5.0. A read-only review of the standard Overleaf example project.*
 
 <details>
 <summary>Read the conversation detail (native 2x PNG)</summary>
@@ -91,12 +99,14 @@ Connection shortcuts cover OpenAI-compatible and Anthropic-compatible APIs, Kimi
 
 > **Upgrading from an older version**
 >
-> **Versions earlier than 2.5.0 require a manual update to 2.5.0.** The in-extension **Update now** action cannot perform this upgrade. Run the installation command below, reload the extension in `chrome://extensions`, then refresh the Overleaf page.
+> **Local candidate:** 2.5.1 is being tested and has not been published. For this checkout, use `npm run build:content` followed by `npm run install:managed`. The version-pinned npm and download commands below apply after publication. The compatible 2.5.0 → 2.5.1 update migration is implemented and awaiting complete acceptance; it is not yet available through the public update feed.
+
+> **Versions earlier than 2.5.0 require a manual installation to move to the 2.5.x line.** The in-extension **Update now** action cannot perform this upgrade. Run the installation command below, reload the extension in `chrome://extensions`, then refresh the Overleaf page.
 
 **Prerequisites:** Chrome, Node.js 20+, and an installed, signed-in Codex CLI. Source installation also uses Git.
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
 1. Run the managed installer. It prints the extension directory.
@@ -150,14 +160,14 @@ Report the chosen release, installed Extension and Native Host versions, the bro
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v2.5.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.0/install.sh)"
+CODEX_OVERLEAF_REF=v2.5.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.1/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.0/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v2.5.0'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.1/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v2.5.1'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -166,7 +176,7 @@ The script checks the prerequisites, builds the extension, installs the native h
 ### Option C: npm
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
 Same result as Option B, without keeping a source checkout around.
@@ -249,17 +259,19 @@ The choice applies to every session in the current project; other projects keep
 
 Managed installs check GitHub for new signed stable releases on their own. When one is available, choose **Update now** in the notice or under **Settings → Software updates**. The update waits until every Overleaf tab is saved and no task is running, replaces the extension and native host together, and restores the previous version if the new one fails its health check. Drafts and prereleases are never picked up, and an update never adds Chrome permissions silently.
 
+The 2.5.1 candidate adds a compatible update from the published 2.5.0 installation through the same **Update now** action. Its signed package carries the startup-file fixes, retains recovery copies and progress, and reloads the extension before confirming the updated startup code. Bootstrap protocol 3 and existing Chrome permissions remain unchanged. This migration is still undergoing local acceptance; the candidate is unpublished.
+
 The updater respects HTTP(S) proxy environment variables and the macOS/Windows system proxy. SOCKS-only or PAC-only setups need an HTTP proxy endpoint.
 
 ### Coming from v2.4.x or earlier
 
-v2.5.0 adds `cn.overleaf.com` support, which needs a new Chrome permission, so it moves the install to Bootstrap protocol 3. Older updaters refuse that step by design rather than granting permissions themselves. **Update now will not work for this one release.** Run the installer once:
+v2.5.0 adds `cn.overleaf.com` support, which needs a new Chrome permission, so it moves the install to Bootstrap protocol 3. Older updaters refuse that step by design rather than granting permissions themselves. **Installations older than 2.5.0 need the full installer for this migration.** Run the installer once:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
-Then click **Reload** on the extension in `chrome://extensions` and refresh Overleaf. Your sessions, settings, provider keys and project mirrors are kept. Later releases update in place again.
+Then click **Reload** on the extension in `chrome://extensions` and refresh Overleaf. Your sessions, settings, provider keys and project mirrors are kept. In-place updates require the target release to pass the Bootstrap compatibility checks.
 
 From v2.5.0 on, a release that ever needs another reinstall is announced in the panel as **Reinstall needed for this update**, with the reason, the exact command for that version, and a copy button, instead of a failed update. New Overleaf sites no longer need a reinstall at all: the extension popup asks you to allow the site, and Chrome confirms it.
 
@@ -269,14 +281,14 @@ Checkout and Release-zip installs are unmanaged and always update by hand.
 
 | Action | Command |
 |---|---|
-| Install, repair or migrate | `npm exec --yes codex-overleaf-link@2.5.0 -- install-managed` |
-| Diagnose | `npm exec --yes codex-overleaf-link@2.5.0 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-managed` |
+| Install, repair or migrate | `npm exec --yes codex-overleaf-link@2.5.1 -- install-managed` |
+| Diagnose | `npm exec --yes codex-overleaf-link@2.5.1 -- doctor` |
+| Uninstall | `npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-managed` |
 
 npm installs, updates, and uninstalls the coordinated managed extension/native pair. The legacy `install-native` command remains available only for explicitly unmanaged extension directories:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-native
+npm exec --yes codex-overleaf-link@2.5.1 -- install-native
 ```
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id. On Linux Chromium, add `--browser chromium` to any of these.
@@ -286,13 +298,13 @@ Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extens
 <summary><strong>Uninstall</strong></summary>
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-managed
 ```
 
 This works in PowerShell too, and also removes installs made by `install.sh` / `install.ps1`. For an unmanaged checkout or native-only install, run `npm run uninstall:native` from the checkout, or:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-native
+npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-native
 ```
 
 An older native-only source install can also be removed with its bundled uninstaller:
@@ -315,7 +327,7 @@ Uninstalling removes the native host registration, bridge, managed extension and
 Rerun the installer, reload the extension in `chrome://extensions`, then refresh Overleaf:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
 For a checkout install, rebuild and rerun `npm run install:native` from the same checkout.
@@ -408,8 +420,8 @@ Chromium on macOS and Windows isn't supported yet. The extension runs on project
 Linux Chromium:
 
 ```bash
-CODEX_OVERLEAF_REF=v2.5.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.0/install.sh)" -- --browser chromium
-npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-managed --browser chromium
+CODEX_OVERLEAF_REF=v2.5.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.1/install.sh)" -- --browser chromium
+npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-managed --browser chromium
 ```
 
 ## Extension ID
@@ -423,7 +435,7 @@ illdpneeeopfffmiepaejglgmhpmdhdc
 If you load a custom build and Chrome gives it a different id, reinstall with that id so the native host's `allowed_origins` matches:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed --extension-id "<your-chrome-extension-id>"
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed --extension-id "<your-chrome-extension-id>"
 ```
 
 For an unmanaged extension, use `install-native --extension-id "<your-chrome-extension-id>"` instead. The source installers also read `CODEX_OVERLEAF_EXTENSION_ID`.
@@ -432,10 +444,10 @@ For an unmanaged extension, use `install-native --extension-id "<your-chrome-ext
 
 Each GitHub Release includes:
 
-- `codex-overleaf-link-extension-v2.5.0.zip`: the extension, for manual unpacked installation.
-- `codex-overleaf-native-host-v2.5.0.tar.gz`: the native host runtime used by the installers.
-- `codex-overleaf-update-v2.5.0.tar.gz`: the combined bundle the in-product updater downloads.
-- `codex-overleaf-link-2.5.0.tgz`: the npm package behind the `npm exec` commands.
+- `codex-overleaf-link-extension-v2.5.1.zip`: the extension, for manual unpacked installation.
+- `codex-overleaf-native-host-v2.5.1.tar.gz`: the native host runtime used by the installers.
+- `codex-overleaf-update-v2.5.1.tar.gz`: the combined bundle the in-product updater downloads.
+- `codex-overleaf-link-2.5.1.tgz`: the npm package behind the `npm exec` commands.
 - `install.sh` and `install.ps1`: installers pinned to this release.
 - `uninstall-native-host.mjs` plus its helpers `nativeHostPlatform.js`, `manifest.js` and `runtimeInstaller.js`.
 - `SHA256SUMS`, `release-manifest.json` and `release-manifest.sig`: checksums and the Ed25519-signed release metadata the updater verifies.
@@ -473,7 +485,7 @@ Native Messaging registration:
 | macOS Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.codex.overleaf.json` |
 | Linux Chrome | `~/.config/google-chrome/NativeMessagingHosts/com.codex.overleaf.json` |
 | Linux Chromium | `~/.config/chromium/NativeMessagingHosts/com.codex.overleaf.json` |
-| Windows Chrome | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` → `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime\com.codex.overleaf.json` |
+| Windows Chrome | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` → `%LOCALAPPDATA%\codex-overleaf\native-messaging-hosts\com.codex.overleaf.json` |
 
 To remove everything:
 

package/README.zh-CN.md

@@ -2,16 +2,24 @@
   <img src="extension/assets/icons/codex-overleaf-icon.png" width="72" alt="Codex Overleaf Link">
   <h1>Codex Overleaf Link</h1>
   <p><strong>Empower Overleaf with Codex.</strong></p>
-  <p><img src="https://img.shields.io/badge/version-2.5.0-blue" alt="version 2.5.0"></p>
+  <p><img src="https://img.shields.io/badge/version-2.5.1-blue" alt="version 2.5.1"></p>
   <p><a href="README.md">English</a> | 简体中文</p>
   <p>Chrome · macOS / Windows / Linux · 本地 Codex</p>
+  <p>
+    <img src="https://img.shields.io/badge/platform-macOS%20%2F%20Windows%20%2F%20Linux-lightgrey" alt="支持平台">
+    <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.js 版本要求">
+    <a href="https://github.com/Ghqqqq/codex-overleaf-link/actions/workflows/test.yml"><img src="https://github.com/Ghqqqq/codex-overleaf-link/actions/workflows/test.yml/badge.svg" alt="测试状态"></a>
+    <img src="https://img.shields.io/badge/runtime%20dependencies-0-orange" alt="无 npm 运行时依赖">
+    <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT 许可证">
+  </p>
 </div>
 
 理解项目、修改段落、对照 PDF 查看结果。Codex Overleaf Link 把本地 Codex 工作流带进 Overleaf 编辑器，让项目上下文、模型选择和写作对话留在同一个工作区。
 
 ![Example paper 演示项目中的源码、PDF 和真实 Codex 项目导览](assets/readme/2.5.0/overview@2x.png)
 
-*2.5.0 当前界面实拍，展示对 Overleaf 默认示例项目的一次只读导览。*
+*2.5.0 界面实拍，展示对 Overleaf 默认示例项目的一次只读导览。*
 
 <details>
 <summary>展开对话细节（原生 2× PNG）</summary>
@@ -91,12 +99,14 @@
 
 > **从旧版本升级**
 >
-> **2.5.0 之前的版本需要手动更新到 2.5.0。** 本次升级无法通过插件内的“立即更新”完成。运行下方安装命令后，在 `chrome://extensions` 中重新加载扩展，并刷新 Overleaf 页面。
+> **本地候选版本：** 2.5.1 正在测试，尚未发布。当前源码可依次运行 `npm run build:content`、`npm run install:managed` 进行本机完整安装；下方固定版本的 npm 和下载命令在发布后适用。`2.5.0 → 2.5.1` 的兼容升级迁移已经实现，仍待完整验收，目前无法从公开更新源取得该候选版本。
+
+> **2.5.0 之前的版本需要通过完整安装迁移到 2.5.x。** 本次升级无法通过插件内的“立即更新”完成。运行下方安装命令后，在 `chrome://extensions` 中重新加载扩展，并刷新 Overleaf 页面。
 
 **准备条件：** Chrome、Node.js 20+，以及已安装并登录的 Codex CLI。源码安装还需要 Git。
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
 1. 运行托管安装命令，取得安装器输出的扩展目录。
@@ -150,14 +160,14 @@ Report the chosen release, installed Extension and Native Host versions, the bro
 macOS / Linux：
 
 ```bash
-CODEX_OVERLEAF_REF=v2.5.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.0/install.sh)"
+CODEX_OVERLEAF_REF=v2.5.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.1/install.sh)"
 ```
 
 Windows PowerShell：
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.0/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v2.5.0'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.1/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v2.5.1'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -166,7 +176,7 @@ powershell -ExecutionPolicy Bypass -File install.ps1
 ### 方式 C：npm
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
 效果和方式 B 一样，只是不用保留源码目录。
@@ -249,19 +259,21 @@ Auto 不会逐段等你确认，但删除文件、新建或替换图片和 PDF
 
 托管安装会自动去 GitHub 检查新的已签名正式版。有更新时，在提示里或 **设置 → 软件更新** 里点**立即更新**。更新会等所有 Overleaf 标签页都保存好、没有任务在跑时才开始，扩展和 native host 一起替换；新版本健康检查不通过会自动回到旧版本。草稿和预发布版本不会被选中，更新也不会悄悄增加 Chrome 权限。
 
+2.5.1 候选版本补充了从已发布 2.5.0 安装出发的兼容迁移，继续使用同一个**立即更新**入口。签名更新包携带启动文件修复，替换时保留恢复副本和进度，重载扩展并确认新版启动代码后才报告成功。Bootstrap 协议仍为3，Chrome 权限保持原有范围。这条迁移仍在本地验收，候选版本尚未发布。
+
 更新器会使用 HTTP(S) 代理环境变量以及 macOS/Windows 系统代理。只有 SOCKS 或 PAC 的环境需要提供一个 HTTP 代理地址。
 
 ### 从 v2.4.x 或更早版本升级
 
-v2.5.0 新增了 `cn.overleaf.com` 支持，需要一项新的 Chrome 权限，因此安装结构升级到了 Bootstrap 协议 3。旧版更新器按设计会拒绝这一步，而不是自己去加权限。**这一版没法通过“立即更新”升级**。请手动运行一次安装：
+v2.5.0 新增了 `cn.overleaf.com` 支持，需要一项新的 Chrome 权限，因此安装结构升级到了 Bootstrap 协议 3。旧版更新器按设计会拒绝这一步，新增权限需通过完整安装取得。**早于 2.5.0 的安装需要通过完整安装完成这次迁移**。请手动运行一次安装：
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
-然后在 `chrome://extensions` 里点扩展的**重新加载**，再刷新 Overleaf。会话、设置、模型服务的 key 和项目镜像都会保留。之后的版本又可以在插件里直接更新。
+然后在 `chrome://extensions` 里点扩展的**重新加载**，再刷新 Overleaf。会话、设置、模型服务的 key 和项目镜像都会保留。后续版本需通过 Bootstrap 兼容检查，才能支持插件内更新。
 
-从 v2.5.0 起，如果以后某个版本又需要重新安装，面板会直接提示“这次更新需要重新安装”，写明原因，给出对应版本的命令和复制按钮，而不是显示更新失败。新增 Overleaf 站点也不再需要重装：扩展弹窗会请你允许访问该站点，Chrome 确认后即可使用。
+从 v2.5.0 起，如果以后某个版本又需要重新安装，面板会直接提示“这次更新需要重新安装”，写明原因，给出对应版本的命令和复制按钮。新增 Overleaf 站点也不再需要重装：扩展弹窗会请你允许访问该站点，Chrome 确认后即可使用。
 
 源码安装和 Release zip 安装不受托管，始终需要手动更新。
 
@@ -269,14 +281,14 @@ npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
 
 | 操作 | 命令 |
 |---|---|
-| 安装、修复或迁移 | `npm exec --yes codex-overleaf-link@2.5.0 -- install-managed` |
-| 诊断 | `npm exec --yes codex-overleaf-link@2.5.0 -- doctor` |
-| 卸载 | `npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-managed` |
+| 安装、修复或迁移 | `npm exec --yes codex-overleaf-link@2.5.1 -- install-managed` |
+| 诊断 | `npm exec --yes codex-overleaf-link@2.5.1 -- doctor` |
+| 卸载 | `npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-managed` |
 
 npm 负责安装、更新和卸载配套的托管扩展与 native host。旧的 `install-native` 命令只用于明确不受托管的扩展目录：
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-native
+npm exec --yes codex-overleaf-link@2.5.1 -- install-native
 ```
 
 只有自定义或开发版扩展 id 与官方 id 不同时，才需要 `--extension-id <chrome-extension-id>`。Linux Chromium 请在以上命令后加 `--browser chromium`。
@@ -286,13 +298,13 @@ npm exec --yes codex-overleaf-link@2.5.0 -- install-native
 <summary><strong>卸载</strong></summary>
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-managed
 ```
 
 PowerShell 里同样可用，也能卸载 `install.sh` / `install.ps1` 装的版本。源码安装或只装了 native host 的情况，在源码目录里执行 `npm run uninstall:native`，或者：
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-native
+npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-native
 ```
 
 旧的 native-only 源码安装也可以用它自带的卸载脚本：
@@ -315,7 +327,7 @@ node "$env:LOCALAPPDATA\CodexOverleaf\source\scripts\uninstall-native-host.mjs"
 重新运行安装器，在 `chrome://extensions` 里重新加载扩展，再刷新 Overleaf：
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed
 ```
 
 源码安装请在同一个源码目录里重新构建，并重新执行 `npm run install:native`。
@@ -408,8 +420,8 @@ macOS 和 Windows 上的 Chromium 暂不支持。扩展在 `overleaf.com`、`www
 Linux Chromium：
 
 ```bash
-CODEX_OVERLEAF_REF=v2.5.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.0/install.sh)" -- --browser chromium
-npm exec --yes codex-overleaf-link@2.5.0 -- uninstall-managed --browser chromium
+CODEX_OVERLEAF_REF=v2.5.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.5.1/install.sh)" -- --browser chromium
+npm exec --yes codex-overleaf-link@2.5.1 -- uninstall-managed --browser chromium
 ```
 
 ## 扩展 ID
@@ -423,7 +435,7 @@ illdpneeeopfffmiepaejglgmhpmdhdc
 如果你加载的是自己构建的版本，Chrome 给了不同的 id，就用那个 id 重新安装，让 native host 的 `allowed_origins` 对得上：
 
 ```bash
-npm exec --yes codex-overleaf-link@2.5.0 -- install-managed --extension-id "<your-chrome-extension-id>"
+npm exec --yes codex-overleaf-link@2.5.1 -- install-managed --extension-id "<your-chrome-extension-id>"
 ```
 
 不受托管的扩展改用 `install-native --extension-id "<your-chrome-extension-id>"`。源码安装器也会读取 `CODEX_OVERLEAF_EXTENSION_ID` 环境变量。
@@ -432,10 +444,10 @@ npm exec --yes codex-overleaf-link@2.5.0 -- install-managed --extension-id "<you
 
 每个 GitHub Release 包含：
 
-- `codex-overleaf-link-extension-v2.5.0.zip`：扩展本体，用于手动加载。
-- `codex-overleaf-native-host-v2.5.0.tar.gz`：安装器使用的 native host 运行时。
-- `codex-overleaf-update-v2.5.0.tar.gz`：插件内更新下载的合并包。
-- `codex-overleaf-link-2.5.0.tgz`：`npm exec` 命令背后的 npm 包。
+- `codex-overleaf-link-extension-v2.5.1.zip`：扩展本体，用于手动加载。
+- `codex-overleaf-native-host-v2.5.1.tar.gz`：安装器使用的 native host 运行时。
+- `codex-overleaf-update-v2.5.1.tar.gz`：插件内更新下载的合并包。
+- `codex-overleaf-link-2.5.1.tgz`：`npm exec` 命令背后的 npm 包。
 - `install.sh` 和 `install.ps1`：固定到本版本的安装器。
 - `uninstall-native-host.mjs` 及其依赖 `nativeHostPlatform.js`、`manifest.js`、`runtimeInstaller.js`。
 - `SHA256SUMS`、`release-manifest.json` 和 `release-manifest.sig`：校验和，以及更新器会验证的 Ed25519 签名元数据。
@@ -473,7 +485,7 @@ Native Messaging 注册位置：
 | macOS Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.codex.overleaf.json` |
 | Linux Chrome | `~/.config/google-chrome/NativeMessagingHosts/com.codex.overleaf.json` |
 | Linux Chromium | `~/.config/chromium/NativeMessagingHosts/com.codex.overleaf.json` |
-| Windows Chrome | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` → `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime\com.codex.overleaf.json` |
+| Windows Chrome | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` → `%LOCALAPPDATA%\codex-overleaf\native-messaging-hosts\com.codex.overleaf.json` |
 
 彻底删除：
 

package/extension/bootstrap/background.js

@@ -1,5 +1,7 @@
 'use strict';
 
+globalThis.__CODEX_OVERLEAF_BOOTSTRAP_REVISION__ = '3.1';
+
 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';
@@ -75,7 +77,7 @@ chrome.alarms.onAlarm.addListener(alarm => {
   }
 });
 
-initializeBootstrap().catch(async error => {
+globalThis.__CODEX_OVERLEAF_BOOTSTRAP_READY__ = initializeBootstrap().catch(async error => {
   await setUpdateState({ state: 'failed', code: safeCode(error), message: safeMessage(error) });
 });
 
@@ -91,6 +93,8 @@ async function initializeBootstrap() {
     return;
   }
 
+  const migration = await globalThis.CodexOverleafBootstrapMigration?.ready?.();
+  if (migration?.continueInitialization === false) return;
   const nativeStatus = await requestInternal({ method: 'update.status', params: {} }).catch(() => null);
   const transaction = nativeStatus?.ok ? nativeStatus.result?.transaction : null;
   if (transaction?.state === 'awaiting_health') {
@@ -381,12 +385,12 @@ 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.'));
+    await rollbackBrokenRuntime(new Error('Updated Overleaf content runtime did not report the target version.'), transaction);
     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.'));
+    await rollbackBrokenRuntime(new Error('Updated native host did not report the target version.'), transaction);
     return;
   }
   const native = ping.result || {};
@@ -399,19 +403,20 @@ async function confirmPendingUpdate(transaction) {
       native.protocolVersion < protocolRange.min ||
       native.protocolVersion > protocolRange.max ||
       missingCapabilities.length) {
-    await rollbackBrokenRuntime(new Error('Updated native host did not pass protocol and capability health checks.'));
+    await rollbackBrokenRuntime(new Error('Updated native host did not pass protocol and capability health checks.'), transaction);
     return;
   }
   const confirmed = await requestInternal({
     method: 'update.confirm',
     params: {
       transactionId: transaction.id,
+      bootstrapRevision: String(globalThis.__CODEX_OVERLEAF_BOOTSTRAP_REVISION__ || ''),
       extensionVersion: chrome.runtime.getManifest().version,
       nativeVersion: ping.result.version
     }
   });
   if (!confirmed?.ok) {
-    await rollbackBrokenRuntime(nativeError(confirmed));
+    await rollbackBrokenRuntime(nativeError(confirmed), transaction);
     return;
   }
   await setUpdateState({
@@ -451,20 +456,56 @@ async function verifyPendingRuntimeHealth(targetVersion) {
   return remaining.size === 0;
 }
 
-async function rollbackBrokenRuntime(error) {
+async function rollbackBrokenRuntime(error, transaction) {
   await setUpdateState({ state: 'rolling_back', code: safeCode(error), message: safeMessage(error) });
+  let pending = transaction;
+  let readback;
+  if (!pending) {
+    readback = await requestInternal({ method: 'update.status', params: {} }).catch(() => null);
+    pending = readback?.ok ? readback.result?.transaction : null;
+  }
+  // A status recovery may have completed an interrupted apply before this
+  // loader obtained its transaction. The same source-byte proof is required.
+  if (isRollbackReadback(readback, pending)) {
+    await setUpdateState({ state: 'rolled_back', code: safeCode(error), currentVersion: pending.sourceVersion, transactionId: pending.id });
+    chrome.runtime.reload();
+    return;
+  }
+  if (!pending?.id || !pending.sourceVersion || !['applying', 'bootstrap_pending', 'awaiting_health', 'committed'].includes(pending.state)) {
+    await setUpdateState({ state: 'failed', code: safeCode(error), message: safeMessage(error) });
+    return;
+  }
   const rolledBack = await requestInternal({
     method: 'update.rollback',
-    params: { reasonCode: safeCode(error) }
+    params: { reasonCode: safeCode(error), transactionId: pending.id, expectedState: pending.state }
   }).catch(() => null);
-  if (rolledBack?.ok) {
-    await setUpdateState({ state: 'rolled_back', code: safeCode(error), currentVersion: rolledBack.result.version });
+  if (rolledBack?.ok && rolledBack.result?.transactionId === pending.id
+    && rolledBack.result?.state === 'rolled_back' && rolledBack.result?.version === pending.sourceVersion) {
+    readback = await requestInternal({ method: 'update.status', params: {} }).catch(() => null);
+  }
+  if (rolledBack?.result?.restoredPair && isRollbackReadback(readback, pending, rolledBack.result.restoredPair)) {
+    await setUpdateState({ state: 'rolled_back', code: safeCode(error), currentVersion: pending.sourceVersion, transactionId: pending.id });
     chrome.runtime.reload();
     return;
   }
   await setUpdateState({ state: 'failed', code: safeCode(error), message: safeMessage(error) });
 }
 
+function isRollbackReadback(response, transaction, expectedPair) {
+  const status = response?.ok ? response.result : null;
+  const pair = status?.restoredPair;
+  return Boolean(transaction?.id && 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 || '')
+    && (!(transaction.bootstrapRevision || status.transaction.bootstrapRevision || expectedPair?.bootstrapSha256)
+      || (/^[0-9a-f]{64}$/.test(pair.bootstrapSha256 || '')
+        && (!expectedPair || pair.bootstrapSha256 === expectedPair.bootstrapSha256)))
+    && (!expectedPair || ['extensionVersion', 'nativeVersion', 'extensionSha256', 'nativeSha256']
+      .every(key => pair[key] === expectedPair[key])));
+}
+
 async function reloadPendingOverleafTabs() {
   const tabIds = await getPendingOverleafTabIds();
   await chrome.storage.local.remove(UPDATE_RELOAD_TABS_KEY);
@@ -485,6 +526,8 @@ async function postponeUpdate() {
 }
 
 async function requestInternal(payload) {
+  if (payload?.method === 'update.status') payload = { ...payload,
+    params: { ...payload.params, bootstrapRevision: String(globalThis.__CODEX_OVERLEAF_BOOTSTRAP_REVISION__ || '') } };
   if (globalThis.CodexOverleafNativeBridge?.requestInternal) {
     return globalThis.CodexOverleafNativeBridge.requestInternal({
       id: crypto.randomUUID(),

package/extension/bootstrap/manifest.template.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Codex Overleaf Link",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Connect the active Overleaf project to a local Codex bridge.",
   "icons": {
     "16": "assets/icons/icon16.png",

package/extension/bootstrap/popup.html

@@ -13,6 +13,7 @@
     <main id="popup-shell" data-bootstrap-shell>
       <p class="popup-note">Codex Overleaf Link could not load its runtime. Rerun the installer, then reload the extension.</p>
     </main>
+    <script src="popupFallback.js"></script>
     <script src="../runtime/src/shared/compatibility.js"></script>
     <script src="../runtime/src/popup.js"></script>
     <script src="updateStatus.js"></script>

package/extension/bootstrap/popupFallback.js

@@ -0,0 +1,55 @@
+(function localizePopupFallback() {
+  'use strict';
+
+  const preferenceKeys = ['codexOverleafGlobalPrefsV1', 'codexOverleafPrefs'];
+  let revision = 0;
+  let recoveryReloaded = false;
+
+  async function refreshFallback() {
+    const requestRevision = ++revision;
+    let preferences = {};
+    try {
+      const stored = await chrome.storage.local.get(preferenceKeys);
+      preferences = stored.codexOverleafGlobalPrefsV1?.values || stored.codexOverleafPrefs || {};
+    } catch (_) { /* A missing language preference uses the product default. */ }
+    if (requestRevision !== revision) return;
+    const shell = document.querySelector('[data-bootstrap-shell]');
+    const message = shell?.querySelector('p');
+    // The healthy runtime replaces this shell. Late preference reads must
+    // never change the runtime's content or its current language.
+    if (!message) return;
+    const chinese = preferences.locale === 'zh';
+    document.documentElement.lang = chinese ? 'zh-CN' : 'en';
+    message.textContent = chinese
+      ? 'Codex Overleaf Link 无法加载运行组件。请重新运行安装程序，再重新加载扩展。'
+      : 'Codex Overleaf Link could not load its runtime. Rerun the installer, then reload the extension.';
+  }
+
+  chrome.storage.onChanged.addListener((changes, area) => {
+    if (area === 'local' && preferenceKeys.some(key => changes[key])) refreshFallback();
+  });
+  refreshFallback();
+
+  // This independent extension page can still start when the worker/runtime
+  // cannot. Native decides whether a persisted migration needs recovery; the
+  // popup never guesses a transaction or sends an unbound rollback request.
+  document.addEventListener?.('DOMContentLoaded', () => {
+    setTimeout(() => {
+      if (!document.querySelector('[data-bootstrap-shell]') || !chrome.runtime?.sendNativeMessage) return;
+      chrome.runtime.sendNativeMessage('com.codex.overleaf', {
+        id: crypto.randomUUID(), method: 'update.status', params: { bootstrapRecovery: true }
+      }, response => {
+        if (chrome.runtime.lastError || recoveryReloaded || !document.querySelector('[data-bootstrap-shell]')) return;
+        const status = response?.ok ? response.result : null;
+        const transaction = status?.transaction;
+        const pair = status?.restoredPair;
+        if (!transaction?.id || transaction.state !== 'rolled_back' || !transaction.sourceVersion
+          || status.activeVersion !== transaction.sourceVersion || status.installedAligned !== true
+          || pair?.extensionVersion !== transaction.sourceVersion || pair?.nativeVersion !== transaction.sourceVersion
+          || !['extensionSha256', 'nativeSha256', 'bootstrapSha256'].every(key => /^[0-9a-f]{64}$/.test(pair[key] || ''))) return;
+        recoveryReloaded = true;
+        chrome.runtime.reload();
+      });
+    }, 250);
+  }, { once: true });
+})();

package/extension/bootstrap/updateStatus.js

@@ -17,6 +17,7 @@
     tab_not_idle: 'An Overleaf tab is still busy.',
     native_project_locked: 'The native host still holds a project lock.',
     native_run_active: 'The native host is still processing a Codex run.',
+    native_process_stop_unconfirmed: 'A previous Codex process has not yet confirmed its exit.',
     native_gate_unavailable: 'The native host could not report whether it is idle.',
     native_not_idle: 'The native host is still busy.',
     busy: 'An update safety check is still busy.'