codex-overleaf-link 1.2.6 → 1.3.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.2.6-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.3.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">
@@ -34,10 +34,10 @@ The recommended release path is npm-first for the native host, plus Chrome's req
 1. Install or update the native host with the pinned npm package:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.2.6 -- install-native
+npm exec --yes codex-overleaf-link@1.3.0 -- install-native
 ```
 
-2. Download `codex-overleaf-link-extension-v1.2.6.zip` from the [v1.2.6 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.2.6), then unzip it to a stable local folder.
+2. Download `codex-overleaf-link-extension-v1.3.0.zip` from the [v1.3.0 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.3.0), then unzip it to a stable local folder.
 
 3. Open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the unzipped extension folder.
 
@@ -48,14 +48,14 @@ If you modify the extension key or load a custom build that gets a different id,
 Source installer fallback for macOS / Linux, mainly for development or source checkout installs:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.2.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.6/install.sh)"
+CODEX_OVERLEAF_REF=v1.3.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.0/install.sh)"
 ```
 
 Source installer fallback for Windows from PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.6/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.2.6'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.3.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -66,19 +66,19 @@ npm installs, updates, uninstalls, and diagnoses the native host only. npm does
 Install or update the native host for the official release extension id:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.2.6 -- install-native
+npm exec --yes codex-overleaf-link@1.3.0 -- install-native
 ```
 
 Diagnose the registered native host:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.2.6 -- doctor
+npm exec --yes codex-overleaf-link@1.3.0 -- doctor
 ```
 
 Uninstall the native host:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native
 ```
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id.
@@ -116,10 +116,10 @@ If Chrome assigns a different extension id, rerun `npm run install:native -- --e
 <details>
 <summary><strong>Update</strong></summary>
 
-For a deterministic v1.2.6 update, run the pinned npm command. This is also the native mismatch recovery command shown by the popup and panel when they report **Native host update required**.
+For a deterministic v1.3.0 update, run the pinned npm command. This is also the native mismatch recovery command shown by the popup and panel when they report **Native host update required**.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.2.6 -- install-native
+npm exec --yes codex-overleaf-link@1.3.0 -- install-native
 ```
 
 If npm is unavailable, use the GitHub Release script fallback for your platform.
@@ -127,14 +127,14 @@ If npm is unavailable, use the GitHub Release script fallback for your platform.
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.2.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.6/install.sh)"
+CODEX_OVERLEAF_REF=v1.3.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.6/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.2.6'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.3.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -144,13 +144,13 @@ Then reload the extension in `chrome://extensions` and refresh the Overleaf page
 
 ## GitHub Release Artifacts
 
-The v1.2.6 GitHub Release contains:
+The v1.3.0 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.2.6.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.2.6.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.2.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.2.6` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.2.6` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v1.3.0.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v1.3.0.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-1.3.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.3.0` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.3.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.
@@ -161,13 +161,13 @@ The v1.2.6 GitHub Release contains:
 macOS / Linux:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native
 ```
 
 Windows PowerShell:
 
 ```powershell
-npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native
 ```
 
 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.
@@ -202,13 +202,13 @@ The uninstaller removes the Native Messaging registration, bridge executable, an
 Linux Chromium install or update:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.2.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.6/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v1.3.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.0/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native --browser chromium
+npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native --browser chromium
 ```
 
 ## Features
@@ -344,7 +344,7 @@ Composer attachments are turn-scoped Codex context. Limits are 8 attachments per
 Run the pinned npm native-host installer, 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.2.6 -- install-native
+npm exec --yes codex-overleaf-link@1.3.0 -- install-native
 ```
 
 If npm is unavailable, use the GitHub Release script fallback for your platform.
@@ -352,14 +352,14 @@ If npm is unavailable, use the GitHub Release script fallback for your platform.
 macOS/Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.2.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.6/install.sh)"
+CODEX_OVERLEAF_REF=v1.3.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.6/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.2.6'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.3.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -418,8 +418,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.2.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.6 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.6 -- uninstall-native --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@1.3.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.0 -- install-native --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.0 -- uninstall-native --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. |

package/extension/src/shared/agentTranscript.js

@@ -1046,56 +1046,57 @@
     const key = result.reasonKey || '';
     const code = result.code || '';
     const filePath = result.reasonParams?.filePath || operation?.path || operation?.from || operation?.to || '';
+    const withDebug = reason => appendSkippedReasonDebug(reason, result);
     if (key === 'missingBaseFile' || code === 'missing_base_file') {
       const target = filePath || textFor(locale, '这个文件', 'this file');
-      return textFor(
+      return withDebug(textFor(
         locale,
         `${target} 在任务开始时没有被 Codex 读到。Codex 没有覆盖它；请刷新项目内容后重试。`,
         `${target} was not read when the task started. Codex did not overwrite it; refresh the project content and retry.`
-      );
+      ));
     }
     if (key === 'staleSnapshot' || code === 'stale_snapshot') {
       const target = filePath || textFor(locale, '这个文件', 'this file');
-      return textFor(
+      return withDebug(textFor(
         locale,
         `${target} 在任务执行期间被你或协作者改过，Codex 没有覆盖它。请查看差异后重试。`,
         `${target} changed while Codex was working, so Codex did not overwrite it. Review the diff and retry.`
-      );
+      ));
     }
     if (key === 'stalePatchLocation') {
-      return textFor(
+      return withDebug(textFor(
         locale,
         'Codex 要修改的位置已经无法和当前 Overleaf 内容对齐，所以没有写入。请重新运行任务。',
         'The edit location no longer matches the current Overleaf content, so nothing was written. Rerun the task.'
-      );
+      ));
     }
     if (key === 'stalePatchConflict' || code === 'stale_patch_range') {
-      return textFor(
+      return withDebug(textFor(
         locale,
         'Codex 要修改的具体位置已经被你或协作者改过，所以没有覆盖它。请查看差异后重试。',
         'The exact edit location was changed by you or a collaborator, so Codex did not overwrite it. Review the diff and retry.'
-      );
+      ));
     }
     if (code === 'stale_patch') {
-      return textFor(
+      return withDebug(textFor(
         locale,
         '这处内容已经和 Codex 读取时不同，所以没有写入。请重新运行，让 Codex 先读取你的最新 Overleaf 内容。',
         'This exact text changed since Codex read it, so nothing was written. Rerun after Codex reads the latest Overleaf content.'
-      );
+      ));
     }
     if (code === 'invalid_patch') {
-      return textFor(
+      return withDebug(textFor(
         locale,
         'Codex 生成的局部写入范围无效，所以没有写入。',
         'Codex produced an invalid local edit range, so nothing was written.'
-      );
+      ));
     }
     if (code === 'write_verification_failed') {
-      return textFor(
+      return withDebug(textFor(
         locale,
         '写入后读回内容和 Codex 预期不一致，已停止把这次操作标记为成功。请刷新 Overleaf 后重试。',
         'After writing, the editor content did not match Codex\'s expected result, so the write was not marked successful. Reload Overleaf and retry.'
-      );
+      ));
     }
     if (code === 'file_tree_verification_failed') {
       return textFor(
@@ -1120,7 +1121,42 @@
         `${target} was created by you or a collaborator while Codex was working, so Codex did not overwrite it. Review the diff and retry.`
       );
     }
-    return localizeVisibleReason(result.reason || result.error || result.code || textFor(locale, '未知原因', 'unknown reason'), locale);
+    return withDebug(localizeVisibleReason(result.reason || result.error || result.code || textFor(locale, '未知原因', 'unknown reason'), locale));
+  }
+
+  function appendSkippedReasonDebug(reason, result = {}) {
+    const debug = result.debug || result.diagnostics;
+    const text = formatSkippedReasonDebug(debug);
+    return text ? `${reason} [debug: ${text}]` : reason;
+  }
+
+  function formatSkippedReasonDebug(debug) {
+    if (!debug || typeof debug !== 'object') {
+      return '';
+    }
+    const parts = [];
+    const add = (key, value) => {
+      if (value === undefined || value === null || value === '') {
+        return;
+      }
+      parts.push(`${key}=${String(value)}`);
+    };
+    add('stage', debug.stage);
+    add('rev', debug.revision);
+    add('op', debug.operationPath);
+    add('active', debug.activePath);
+    add('initial', debug.initialActivePath);
+    add('last', debug.lastActivePath);
+    add('currentLen', debug.current?.length);
+    add('currentNorm', debug.current?.normalizedLength);
+    add('currentHash', debug.current?.hash);
+    add('baseKnown', debug.baseKnown);
+    add('baseLen', debug.base?.length);
+    add('baseNorm', debug.base?.normalizedLength);
+    add('baseHash', debug.base?.hash);
+    add('elapsed', debug.elapsedMs);
+    add('opened', debug.openedMethod);
+    return parts.join(', ');
   }
 
   function localizeVisibleReason(reason, locale = 'zh') {

package/extension/src/shared/compatibility.js

@@ -12,7 +12,7 @@
   const MIN_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_EXTENSION_VERSION = '1.0.0';
-  const BUILD_TARGET_VERSION = '1.2.6';
+  const BUILD_TARGET_VERSION = '1.3.0';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',

package/extension/src/shared/staleGuard.js

@@ -41,8 +41,20 @@
     }
 
     const baseContent = baseFileLookup.get(filePath);
+    if (!baseContent || baseContent.trim().length === 0) {
+      if (typeof console !== 'undefined') {
+        console.warn('[codex-overleaf] staleGuard: base empty for', filePath, '→ skipping check');
+      }
+      return { ok: true };
+    }
     const current = normalizeText(currentContent);
     if (current !== baseContent) {
+      if (typeof console !== 'undefined') {
+        console.warn('[codex-overleaf] staleGuard: STALE', filePath,
+          'base.length:', baseContent.length, 'current.length:', current.length,
+          'base[0..80]:', JSON.stringify(baseContent.slice(0, 80)),
+          'current[0..80]:', JSON.stringify(current.slice(0, 80)));
+      }
       const patchRangeFreshness = checkPatchRangeFreshness(operation, current);
       if (patchRangeFreshness) {
         return patchRangeFreshness;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-overleaf-link",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "Cross-platform Chrome bridge that connects Codex to the active Overleaf project.",
   "license": "MIT",
   "type": "commonjs",