codex-overleaf-link 2.3.6 → 2.4.1

package/README.md

@@ -1,9 +1,13 @@
+> [!NOTE]
+> This development branch can contain unreleased changes. Version-pinned commands below apply after the corresponding release is published. Published installers are available from the [latest stable release](https://github.com/Ghqqqq/codex-overleaf-link/releases/latest).
+
 <div align="center">
   <img src="extension/assets/icons/codex-overleaf-icon.png" width="96" alt="Codex Overleaf Link">
   <h1>Codex Overleaf Link</h1>
+  <p><strong>English</strong> | <a href="README.zh-CN.md" lang="zh-CN">简体中文</a></p>
   <p><strong>Empower Overleaf with Codex.</strong></p>
   <p>
-    <img src="https://img.shields.io/badge/version-2.3.6-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-2.4.1-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 +42,14 @@ Codex Overleaf Link adds a Codex panel directly inside Overleaf and mirrors the
 - **Project rules and preflight** — read-only / writable path rules gate browser writes; sensitive-content detection checks task context before sending it to Codex. File focus prioritizes context; use project rules to enforce writable paths.
 - **Models and skills** — discover local Codex models, choose supported reasoning and speed settings, and install or select Codex Overleaf skills from the slash menu. Skill loading and individual skill enablement are configurable.
 - **Local records and diagnostics** — preserve run outcomes and recovery evidence, inspect diagnostics, and export redacted issue-report bundles. Plugin Codex sessions use an isolated home.
+- **OT warm mirror** (Operational Transformation) keeps focused mirror files warm through optional, read-only observation of active Overleaf text edits. It is off by default and falls back to the normal snapshot path when unavailable, stale, or inconsistent. Overleaf writeback still uses the page bridge.
+
+OT freshness expires after 30 seconds, and focused warm starts still verify current file content through the page bridge. OT observation never establishes whole-project freshness or replaces the Overleaf writeback path.
 
 ### Experimental features
 
 - **Third-party model providers** — configure Responses API, OpenAI-compatible Chat Completions, or Anthropic Messages endpoints in Settings. The local Codex CLI remains the agent runtime, with local protocol bridges adapting the selected endpoint. Compatibility varies by model and gateway; the built-in Codex provider remains the default.
 - **Parallel subagents** — enable the `parallel-subagents` skill for decomposable tasks. The native host runs workers with assigned files; the skill can split a single file into section jobs. Worker progress appears in the timeline, and detected ownership violations are withheld from Overleaf writeback.
-- **OT warm mirror** — optional, read-only observation of active Overleaf text edits keeps focused mirror files warm. It is off by default and falls back to the normal snapshot path when unavailable, stale, or inconsistent. Overleaf writeback still uses the page bridge.
-
-OT freshness expires after 30 seconds, and focused warm starts still verify current file content through the page bridge. OT observation never establishes whole-project freshness or replaces the Overleaf writeback path.
 
 ## Requirements
 
@@ -61,36 +65,50 @@ OT freshness expires after 30 seconds, and focused warm starts still verify curr
 
 ## Install
 
-Codex Overleaf Link has two parts: a **native host** (a local Node bridge) and the **Chrome extension**. Pick one of the two install paths below, then open Overleaf.
+Codex Overleaf Link has two parts: a **native host** (a local Node bridge) and the **Chrome extension**. Installation with Codex is recommended; the installer script and npm commands remain available below.
+
+Chrome may require a manual **Load unpacked** or **Reload** action. Codex should explain any remaining browser step and respect browser and operating-system permission boundaries.
+
+### Option A: Let Codex install it (recommended)
+
+Give the following prompt to Codex with terminal access on the computer where Chrome runs:
 
-Either way, the final **Load unpacked** click is manual — Chrome does not let any installer or script load an unpacked extension for you.
+```text
+Install Codex Overleaf Link from https://github.com/Ghqqqq/codex-overleaf-link on this computer.
 
-### Option A — installer script (recommended)
+Read the official README and installation scripts first. Detect the operating system and check Node.js >= 20, Codex CLI, and any other prerequisites required by the selected installation method.
+Use the latest published stable GitHub release, excluding drafts and prereleases, unless a specific version was requested. Use the documented managed installation method and install matching Extension and Native Host versions; do not substitute an unreleased main checkout.
+Reuse the existing Chrome profile and managed installation when available. Preserve project files, session history, settings, and provider credentials. Do not print secrets or remove an existing installation without approval.
+Complete the terminal-side setup and checks. If Chrome requires a manual Load unpacked or Reload action, provide the exact managed extension folder and the remaining steps; do not bypass browser restrictions.
+Report the chosen release, installed Extension and Native Host versions, the browser-loaded version when observable, and the native connection check. Matching on-disk versions alone do not prove Chrome has loaded the update. Clearly identify anything still requiring manual action.
+```
+
+### Option B: installer script
 
 One command installs the managed native host **and** managed extension runtime. On macOS/Linux it also creates the visible `~/Codex Overleaf Link Extension` shortcut when that path is available. The script attempts to copy the extension path on macOS and Windows; on macOS it also attempts to open Chrome's extensions page. Every platform prints the folder to load. Future signed stable updates target this same managed directory.
 
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v2.3.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.3.6/install.sh)"
+CODEX_OVERLEAF_REF=v2.4.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.4.1/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.3.6/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v2.3.6'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.4.1/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v2.4.1'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
 Then open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and choose the extension folder printed by the installer. If the installer reports that it copied the path, you can paste it into the folder picker.
 
-### Option B — npm managed install
+### Option C: npm managed install
 
 `npm exec` installs the same managed native host and extension runtime without keeping a source checkout. Use it if you prefer a pinned npm package.
 
 ```bash
-npm exec --yes codex-overleaf-link@2.3.6 -- install-managed
+npm exec --yes codex-overleaf-link@2.4.1 -- install-managed
 ```
 
 Then, in `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the managed extension path printed by the command. The Release extension zip remains available for explicitly unmanaged/manual installations.
@@ -132,7 +150,10 @@ There are two task modes, Ask and Auto. Track is a separate setting for Auto wri
 
 Auto text writes do not wait for a per-hunk approval step. Deletes and binary create/overwrite operations require separate confirmation. Track applies to supported text edits; it does not make every file-tree or binary operation reversible.
 
-**Accept** finalizes this run's tracked text edits and leaves Overleaf in Editing mode. If the operation unexpectedly creates new tracked changes, the extension attempts to roll it back and reports what could be verified.
+**Accept** is intended to finalize a run's tracked text edits and leaves Overleaf in Editing mode. If the operation unexpectedly creates new tracked changes, the extension attempts to roll it back and reports what could be verified.
+
+> [!WARNING]
+> Do not use the run card's **Accept** action when the affected files contain unrelated pending tracked changes from other runs or collaborators. Review and accept those changes individually in Overleaf's native Review panel. An Accepted badge or successful compilation alone does not prove that unrelated pending changes were preserved.
 
 **Undo** uses the run's saved recovery information. Concurrent changes or incomplete verification can prevent a full restoration. Cancel stops further work but does not automatically undo writes that already reached Overleaf; inspect the run card for the written parts and available recovery actions.
 
@@ -191,7 +212,6 @@ Update downloads retry transient network failures within a bounded time budget,
 
 After a manual reinstall, installed files and running components are shown separately. Use the reload action once Overleaf is saved and idle; pending Overleaf tabs can then refresh. A disk replacement alone is not reported as a successfully health-confirmed update.
 
-
 Managed installations **check** for signed stable updates automatically. When an update is available, choose **Update now** in the update notice or **Settings → Software updates** to authorize that version. The updater then downloads and verifies the coordinated extension/native bundle, waits until connected Overleaf tabs are saved and idle and the native host has no active work, and applies both components together. A failed health check restores the previous version. The update notice also offers postponement and progress details.
 
 Stable updates use signed release metadata and artifact hashes; draft and prerelease versions are not selected. Releases that require a different Bootstrap protocol need a managed reinstall. The updater does not silently add Chrome permissions.
@@ -208,9 +228,9 @@ npm installs, updates, and uninstalls the coordinated managed extension/native p
 
 | Action | Command |
 |--------|---------|
-| Install / recover / migrate | `npm exec --yes codex-overleaf-link@2.3.6 -- install-managed` |
-| Diagnose | `npm exec --yes codex-overleaf-link@2.3.6 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-managed` |
+| Install / recover / migrate | `npm exec --yes codex-overleaf-link@2.4.1 -- install-managed` |
+| Diagnose | `npm exec --yes codex-overleaf-link@2.4.1 -- doctor` |
+| Uninstall | `npm exec --yes codex-overleaf-link@2.4.1 -- uninstall-managed` |
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id.
 
@@ -221,7 +241,7 @@ Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extens
 Remove the managed extension/native installation (append `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-managed
+npm exec --yes codex-overleaf-link@2.4.1 -- uninstall-managed
 ```
 
 The same command works in Windows PowerShell. It also applies to current `install.sh` / `install.ps1` installations, which install the managed pair.
@@ -229,7 +249,7 @@ The same command works in Windows PowerShell. It also applies to current `instal
 For an unmanaged checkout or native-only installation, use `npm run uninstall:native` from the checkout, or:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-native
+npm exec --yes codex-overleaf-link@2.4.1 -- uninstall-native
 ```
 
 If you are removing an older native-only source installation and still have its source checkout, its bundled uninstaller can also be invoked directly:
@@ -239,7 +259,7 @@ node ~/.codex-overleaf/source/scripts/uninstall-native-host.mjs
 ```
 
 ```powershell
-node $env:LOCALAPPDATA\CodexOverleaf\source\scripts\uninstall-native-host.mjs
+node "$env:LOCALAPPDATA\CodexOverleaf\source\scripts\uninstall-native-host.mjs"
 ```
 
 `uninstall-managed` removes the registered Native Messaging host, bridge executable, managed extension, and versioned native runtime. `uninstall-native` removes the native-only registration and runtime copy. Neither command clears browser session history/settings, project mirrors, plugin Codex history, provider credentials, or stored skills.
@@ -255,7 +275,7 @@ Remove the extension entry from `chrome://extensions` as well. To erase saved Co
 For a managed installation, rerun the [managed installer](#install), reload the extension in `chrome://extensions`, then refresh the Overleaf tab. This recovers the coordinated extension/native pair after an incomplete installation or incompatible runtime update.
 
 ```bash
-npm exec --yes codex-overleaf-link@2.3.6 -- install-managed
+npm exec --yes codex-overleaf-link@2.4.1 -- install-managed
 ```
 
 For an unmanaged checkout, rebuild the extension and reinstall its native host from the same checkout. Use PowerShell installation commands on Windows.
@@ -284,6 +304,8 @@ The stale-write guard checks the original content and expected patch ranges. It
 
 Track requires an Overleaf Reviewing state that the extension can verify. Accept and Undo depend on the run's actual writes and saved recovery evidence; some operations or later collaborator edits prevent full recovery. Follow the run card's specific next action. Turning Track off selects ordinary Editing for future Auto runs.
 
+If files were written but Accept is missing, inspect the actual changes in Overleaf before retrying. Repeating a task solely to recover the button can duplicate edits. Export redacted diagnostics with the run result when reporting the issue.
+
 **Governance blocked write**
 
 Project governance rules can mark paths read-only or restrict writable paths. Switch to ask-only mode, adjust the project governance settings, or narrow the requested edit to an allowed path.
@@ -376,13 +398,13 @@ The shipped extension targets `https://overleaf.com/project` and `https://www.ov
 Linux Chromium install or update:
 
 ```bash
-CODEX_OVERLEAF_REF=v2.3.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.3.6/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v2.4.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.4.1/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-managed --browser chromium
+npm exec --yes codex-overleaf-link@2.4.1 -- uninstall-managed --browser chromium
 ```
 
 ## Extension ID
@@ -396,27 +418,27 @@ illdpneeeopfffmiepaejglgmhpmdhdc
 The installer uses this id by default. For a managed installation with a custom id, rerun the managed installer with the id shown in `chrome://extensions`:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.3.6 -- install-managed --extension-id <your-chrome-extension-id>
+npm exec --yes codex-overleaf-link@2.4.1 -- install-managed --extension-id "<your-chrome-extension-id>"
 ```
 
 For an unmanaged extension, use the native-only installer:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.3.6 -- install-native --extension-id <your-chrome-extension-id>
+npm exec --yes codex-overleaf-link@2.4.1 -- install-native --extension-id "<your-chrome-extension-id>"
 ```
 
 Both npm commands work in PowerShell. Source installers also accept the `CODEX_OVERLEAF_EXTENSION_ID` environment variable. The Native Messaging manifest's `allowed_origins` must match the loaded extension id.
 
 ## GitHub Release Artifacts
 
-The v2.3.6 GitHub Release contains:
+The v2.4.1 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v2.3.6.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v2.3.6.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-update-v2.3.6.tar.gz`: coordinated extension/native bundle used by the managed updater.
-- `codex-overleaf-link-2.3.6.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
-- `install.sh`: release-pinned macOS / Linux installer that defaults to `v2.3.6` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v2.3.6` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v2.4.1.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v2.4.1.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-update-v2.4.1.tar.gz`: coordinated extension/native bundle used by the managed updater.
+- `codex-overleaf-link-2.4.1.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
+- `install.sh`: release-pinned macOS / Linux installer that defaults to `v2.4.1` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v2.4.1` 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`, `release-manifest.json`, and `release-manifest.sig`: checksums, release metadata, and its Ed25519 signature.
@@ -467,6 +489,8 @@ Full uninstall and data deletion:
 3. Remove the extension entry from `chrome://extensions` in each browser profile. Chrome removes that extension's `chrome.storage.local` settings when it is uninstalled. See the [Chrome storage API documentation](https://developer.chrome.com/docs/extensions/reference/api/storage#storage_areas).
 4. To erase all remaining default filesystem data, including project mirrors, plugin Codex history, provider credentials, skills, and source checkouts, use the appropriate command below. Also remove any custom installation roots you configured.
 
+**The following commands permanently delete data in the listed directories. Back up any project mirrors, history, or configuration that must be kept before running them.**
+
 macOS/Linux:
 
 ```bash
@@ -491,8 +515,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 | Managed pair recommended; unmanaged Release zip or checkout also available. | Same as macOS Chrome. | Same as macOS Chrome. | Managed or unmanaged; register 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@2.3.6 -- install-managed` | `npm exec --yes codex-overleaf-link@2.3.6 -- install-managed` | `npm exec --yes codex-overleaf-link@2.3.6 -- install-managed` | `npm exec --yes codex-overleaf-link@2.3.6 -- install-managed --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.3.6 -- uninstall-managed --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@2.4.1 -- install-managed` | `npm exec --yes codex-overleaf-link@2.4.1 -- install-managed` | `npm exec --yes codex-overleaf-link@2.4.1 -- install-managed` | `npm exec --yes codex-overleaf-link@2.4.1 -- install-managed --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@2.4.1 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.4.1 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.4.1 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.4.1 -- 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` |
 | Managed runtime paths | `~/.codex-overleaf/managed/extension` and `~/.codex-overleaf/managed/native`. | `%LOCALAPPDATA%\CodexOverleaf\managed\extension` and `%LOCALAPPDATA%\CodexOverleaf\managed\native`. | Same as macOS Chrome. | Same as macOS Chrome. |
 | Node/Git/Codex/TeX | Record exact versions; see [Requirements](#requirements) for installation and provider prerequisites. | Same as macOS Chrome. | Same as macOS Chrome. | Same as macOS Chrome. |
@@ -513,6 +537,10 @@ Contributions are welcome. Please open an issue before submitting large changes
 3. Run `npm test` and ensure all tests pass.
 4. Submit a pull request with a clear description.
 
+Keep [README.md](README.md) and [README.zh-CN.md](README.zh-CN.md) aligned when changing behavior, version pins, installation commands, or troubleshooting. Translate prose while preserving commands, file paths, and API identifiers.
+
 ## License
 
 [MIT](LICENSE)
+
+<p align="center"><strong>English</strong> | <a href="README.zh-CN.md" lang="zh-CN">简体中文</a></p>