codex-overleaf-link 1.6.1 → 1.6.3

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.6.1-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.6.3-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.6.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.1/install.sh)"
+CODEX_OVERLEAF_REF=v1.6.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.3/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.1/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.6.1'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.3/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.6.3'
 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.6.1 -- install-native
+npm exec --yes codex-overleaf-link@1.6.3 -- install-native
 ```
 
-Then add the extension yourself: download `codex-overleaf-link-extension-v1.6.1.zip` from the [v1.6.1 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.6.1), 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.6.3.zip` from the [v1.6.3 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.6.3), 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.6.1 -- install-native` |
-| Diagnose | `npm exec --yes codex-overleaf-link@1.6.1 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native` |
+| Install / update | `npm exec --yes codex-overleaf-link@1.6.3 -- install-native` |
+| Diagnose | `npm exec --yes codex-overleaf-link@1.6.3 -- doctor` |
+| Uninstall | `npm exec --yes codex-overleaf-link@1.6.3 -- uninstall-native` |
 
 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.6.1 GitHub Release contains:
+The v1.6.3 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.6.1.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.6.1.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.6.1.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
-- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.6.1` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.6.1` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v1.6.3.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v1.6.3.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-1.6.3.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
+- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.6.3` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.6.3` 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.6.1 GitHub Release contains:
 Remove the native host (use `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.6.3 -- uninstall-native
 ```
 
 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.6.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.1/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v1.6.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.3/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native --browser chromium
+npm exec --yes codex-overleaf-link@1.6.3 -- uninstall-native --browser chromium
 ```
 
 ## Features
@@ -172,6 +172,7 @@ npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native --browser chromium
 - **@ context** — attach specific files, `@compile-log`, or `@current-section` to the prompt.
 - **Composer attachments and binary writeback** — paste or drop PDFs, images, and files into the composer as turn-scoped Codex context, and review Codex-created assets before creating or replacing them in Overleaf.
 - **Codex Overleaf skills** — install reusable plugin-scoped skills through the slash menu, then let Codex auto-trigger them or select one explicitly for the next turn. Each skill has its own enable toggle, honored at run time.
+- **Parallel subagents (experimental)** — enable the `parallel-subagents` skill and Codex can fan a decomposable task (e.g. polish several sections) out to real parallel Codex workers that the native host runs for you. Workers own disjoint files; a single file is parallelized by slicing its sections (scatter–gather) or by serialized scoped jobs, so concurrent edits never clobber each other. Each subagent's progress streams into the timeline, and edits a worker was not assigned are withheld from writeback.
 - **Governance rules** — configure project read-only and writable path rules that block unsafe writeback before browser mutation.
 - **Sensitive preflight** — scan selected project context for likely secrets before sending it to Codex.
 - **Audit and diagnostics** — keep local run records and export redacted diagnostic bundles for issue reports.
@@ -185,6 +186,7 @@ npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native --browser chromium
 - **Fix a compile error** — choose Suggest mode, attach `@compile-log`, ask Codex to diagnose and patch the failing file, review the diff, apply it, then recompile from the panel.
 - **Rewrite a paragraph** — select the target file or `@current-section`, ask for a tone or clarity rewrite in Suggest mode, review the text diff, and accept only the hunks you want.
 - **Translate a section** — attach the source section with `@file` or `@current-section`, specify the target language and terminology constraints, then review the proposed replacement before writeback.
+- **Polish several sections at once** — enable the `parallel-subagents` skill, then ask Codex to polish multiple chapters or sections in parallel; it splits the work across subagents, runs them concurrently, and merges the results back for a single review.
 
 ## How It Works
 
@@ -289,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.6.1 -- install-native
+npm exec --yes codex-overleaf-link@1.6.3 -- install-native
 ```
 
 **The Windows popup or panel shows a Bash recovery command**
@@ -338,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.6.1 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.1 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.1 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.1 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.1 -- uninstall-native --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@1.6.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.3 -- install-native --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@1.6.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.3 -- 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

@@ -268,14 +268,14 @@
       return {
         ...base,
         status: 'warning',
-        title: textFor(locale, `⚠ 子代理波次改动了未授权文件 ${label}，该文件的改动将不会写回 Overleaf。`, `⚠ A subagent wave changed unowned file ${label}; its changes will NOT be written back to Overleaf.`)
+        title: textFor(locale, `⚠ 子代理改动了未分配给它的文件 ${label}，该改动已丢弃、未写回 Overleaf。如果该文件确实需要修改，请重新运行。`, `⚠ A subagent edited ${label}, which it was not assigned; that change was discarded and not written to Overleaf. Re-run if that file should be edited.`)
       };
     }
     if (type === 'codex.subagent.drained') {
       return {
         ...base,
         status: 'completed',
-        title: textFor(locale, '↳ 子代理已全部收尾。', '↳ All subagents drained.')
+        title: textFor(locale, '↳ 子代理已全部完成。', '↳ All subagents finished.')
       };
     }
     return { ...base, status: event.status || 'running', title: label };

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.6.1';
+  const BUILD_TARGET_VERSION = '1.6.3';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',

package/extension/src/shared/i18n.js

@@ -272,6 +272,8 @@
       modeAuto: 'Auto',
       modeAutoTitle: 'Write directly after authorization. Deletes still require confirmation.',
       addContext: 'Add @ context',
+      reasoningLabel: 'Reasoning effort',
+      speedLabel: 'Speed',
       requireReviewing: 'Track',
       requireReviewingTitle: 'When enabled, Codex checks or switches Overleaf Reviewing/Track Changes before writing. Deletes still require confirmation.',
       autoCompile: 'Compile',
@@ -347,6 +349,24 @@
       failureReason_section_next: 'Next',
       // FailureReason bilingual high-priority strings (design spec §15.4).
       // Each entry follows the §9 catalog copy. {file} / {activeFile} interpolate from the failure record.
+      failureReason_partial_write_needs_review_user: 'Some operations wrote to Overleaf; others were skipped.',
+      failureReason_partial_write_needs_review_next: 'Review the written files; use "Undo written parts" to roll back if needed.',
+      failureReason_codex_run_cancelled_user: 'The local Codex run was cancelled.',
+      failureReason_codex_run_cancelled_next: 'Start a new run when you are ready.',
+      failureReason_write_operation_failed_user: 'The editor write call for {file} failed.',
+      failureReason_write_operation_failed_next: 'Retry once the Overleaf editor is stable.',
+      failureReason_write_timeout_user: 'Overleaf did not accept the write to {file} before timeout.',
+      failureReason_write_timeout_next: 'Refresh Overleaf, then retry.',
+      failureReason_undo_operation_failed_user: 'The Overleaf undo or reject operation failed.',
+      failureReason_undo_operation_failed_next: 'Use Overleaf undo/review tools manually.',
+      failureReason_undo_partial_user: "Some of this run's writes were undone; others were skipped.",
+      failureReason_undo_partial_next: 'Review the remaining files and retry undo if it is safe.',
+      failureReason_accept_force_editing_failed_user: 'Codex could not enter a stable Editing mode to accept the changes.',
+      failureReason_accept_force_editing_failed_next: 'Switch Overleaf to Editing manually, then retry.',
+      failureReason_accept_replay_failed_user: 'Replaying the accepted content into {file} failed.',
+      failureReason_accept_replay_failed_next: 'Inspect the file in Overleaf, then retry.',
+      failureReason_native_request_failed_user: 'The request to the local Codex bridge failed.',
+      failureReason_native_request_failed_next: 'Open Diagnostics to check the bridge, then retry.',
       failureReason_project_snapshot_unavailable_user: 'Codex could not read the Overleaf project snapshot.',
       failureReason_project_snapshot_unavailable_next: 'Refresh Overleaf, then rerun the task.',
       failureReason_selected_context_unresolved_user: 'Codex could not resolve the requested selection or context.',
@@ -680,6 +700,8 @@
       modeAuto: '自动写入',
       modeAutoTitle: '授权后直接写入，删除仍需确认',
       addContext: '添加 @ 上下文',
+      reasoningLabel: '推理强度',
+      speedLabel: '速度',
       requireReviewing: '留痕',
       requireReviewingTitle: '开启后，写入前会确认并尝试切到 Overleaf Reviewing/Track Changes；删除仍需确认。',
       autoCompile: '编译',
@@ -754,6 +776,24 @@
       failureReason_section_code: '代码',
       failureReason_section_next: '下一步',
       // FailureReason 高优先级双语文案（设计规格 §15.4）。文案对应 §9 目录的英文 fallback。
+      failureReason_partial_write_needs_review_user: '部分操作已写入 Overleaf，其余被跳过。',
+      failureReason_partial_write_needs_review_next: '请检查已写入的文件；如需回滚，使用「撤销已写入部分」。',
+      failureReason_codex_run_cancelled_user: '本地 Codex 任务已取消。',
+      failureReason_codex_run_cancelled_next: '准备好后可以重新发起一轮任务。',
+      failureReason_write_operation_failed_user: '对 {file} 的编辑器写入调用失败。',
+      failureReason_write_operation_failed_next: '等 Overleaf 编辑器稳定后重试。',
+      failureReason_write_timeout_user: 'Overleaf 在超时前没有接受对 {file} 的写入。',
+      failureReason_write_timeout_next: '刷新 Overleaf 后重试。',
+      failureReason_undo_operation_failed_user: 'Overleaf 的撤销或拒绝操作失败。',
+      failureReason_undo_operation_failed_next: '请手动使用 Overleaf 的撤销/审阅工具。',
+      failureReason_undo_partial_user: '本轮的部分写入已撤销，其余被跳过。',
+      failureReason_undo_partial_next: '检查剩余文件，确认安全后再重试撤销。',
+      failureReason_accept_force_editing_failed_user: 'Codex 未能进入稳定的 Editing 模式来接受改动。',
+      failureReason_accept_force_editing_failed_next: '请手动把 Overleaf 切到 Editing，然后重试。',
+      failureReason_accept_replay_failed_user: '把已接受的内容回放到 {file} 时失败。',
+      failureReason_accept_replay_failed_next: '请在 Overleaf 中检查该文件后重试。',
+      failureReason_native_request_failed_user: '向本地 Codex bridge 的请求失败。',
+      failureReason_native_request_failed_next: '打开「诊断」检查 bridge 后重试。',
       failureReason_project_snapshot_unavailable_user: 'Codex 没能读到 Overleaf 项目快照。',
       failureReason_project_snapshot_unavailable_next: '请刷新 Overleaf，然后重试本轮任务。',
       failureReason_selected_context_unresolved_user: 'Codex 没能解析所选的内容或上下文。',

package/native-host/src/codexSessionRunner.js

@@ -3,6 +3,7 @@
 const { spawn } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const { version: PACKAGE_VERSION } = require('../../package.json');
 const { SUBAGENT_QUEUE_DIR, collectMirrorChangesDetailed, getProjectMirror, markMirrorDirty, syncOverleafToMirror } = require('./mirrorWorkspace');
 const { computeLineDiff } = require('./diffEngine');
 const { computeTextPatches } = require('./textPatch');
@@ -854,7 +855,7 @@ function runCodexAppServerSession(input) {
       await request('initialize', {
         clientInfo: {
           name: 'codex-overleaf-link',
-          version: '0.1.0'
+          version: PACKAGE_VERSION
         },
         capabilities: null
       });

package/native-host/src/skills/parallel-subagents/SKILL.md

@@ -78,12 +78,19 @@ Rules:
 ## 4. Poll for results
 
 ```bash
+tries=0
 while [ "$(ls .codex-overleaf-subagents/results/*.json 2>/dev/null | wc -l)" -lt <jobCount> ]; do
   sleep 10
+  tries=$((tries + 1))
+  if [ "$tries" -ge 60 ]; then break; fi   # ~10 min cap: never poll forever
   ls .codex-overleaf-subagents/results/ 2>/dev/null
 done
 ```
 
+If the loop hits the cap, a result never arrived (e.g. a lost or duplicate
+`id`). Do not keep waiting: read whatever results exist and finish the
+remaining slices yourself inline.
+
 Then read each `results/<id>.json` (`status`: completed | failed | rejected |
 timeout | cancelled; `summary`; `changedFiles`) and, when you need the full
 close-out, `results/<id>.last-message.md`.

package/native-host/src/subagentBroker.js

@@ -269,7 +269,21 @@ function createSubagentBroker(options = {}) {
         return;
       }
       const [jobId] = queued.splice(index, 1);
-      startWorker(jobs.get(jobId));
+      const entry = jobs.get(jobId);
+      try {
+        startWorker(entry);
+      } catch (error) {
+        // A job is spliced out of `queued` before it starts; if startWorker
+        // throws it would vanish with no result, hanging a lead still polling
+        // for its count. Emit a failed result so the poll loop can proceed.
+        if (entry) {
+          entry.status = 'failed';
+        }
+        appendLog(jobId, `start_failed: ${error?.stack || error?.message || String(error)}`);
+        try {
+          writeResult({ id: jobId, status: 'failed', reason: error?.message || 'subagent failed to start' });
+        } catch (_writeError) { /* result dir may be gone */ }
+      }
     }
   }
 
@@ -340,6 +354,17 @@ function createSubagentBroker(options = {}) {
     entry.status = resultFields.status;
     const ownedAfter = hashPaths(job.files);
     const changedFiles = job.files.filter(file => entry.ownedBefore.get(file) !== ownedAfter.get(file));
+    if (resultFields.status !== 'completed' && changedFiles.length) {
+      // A worker that did not finish cleanly (timeout / cancelled / failed)
+      // may have left a half-written file on disk. The mirror scan would
+      // otherwise ship that partial edit straight to Overleaf, so withhold it
+      // the same way ownership violations are withheld — the runner's S8
+      // demotion reads getViolationPaths() and drops these from writeback
+      // (spec S8 safety extension, v1.6.2).
+      for (const file of changedFiles) {
+        violationPaths.add(file);
+      }
+    }
     const result = {
       id: job.id,
       ...resultFields,
@@ -495,19 +520,39 @@ function createSubagentBroker(options = {}) {
 
   async function stop({ drain = true } = {}) {
     accepting = false;
+    // Queued-but-unstarted jobs would otherwise vanish with no result file,
+    // hanging a lead still polling for its job count. Settle them first
+    // (mirrors onParentAbort's queue handling).
+    for (const jobId of queued.splice(0)) {
+      const entry = jobs.get(jobId);
+      if (entry) {
+        entry.status = 'cancelled';
+      }
+      writeResult({ id: jobId, status: 'cancelled', reason: 'The run ended before this subagent started.' });
+    }
     if (drain && running.size) {
+      let graceTimer = null;
       const grace = new Promise(resolve => {
-        setTimeout(resolve, limits.drainGraceMs);
+        graceTimer = setTimeout(resolve, limits.drainGraceMs);
       });
       await Promise.race([
         Promise.allSettled([...running.values()].map(worker => worker.promise)),
         grace
       ]);
+      // The grace timer gates an awaited race; if the workers settled first it
+      // must be cleared or it keeps the event loop alive for drainGraceMs
+      // (the "keep timers gated, then clear" discipline from c3cd357).
+      if (graceTimer) {
+        clearTimeout(graceTimer);
+      }
     }
     for (const { controller } of running.values()) {
       controller.abort(new Error('broker drained'));
     }
-    await Promise.allSettled([...running.values()].map(worker => worker.promise));
+    // Bounded final settle: a worker that ignores its abort must not hang
+    // stop() forever — that strands codex.run and leaks the project lock (the
+    // very zombie-lock case handleCodexCancel exists to recover from).
+    await settleRunningWithin(limits.drainGraceMs);
     if (jobs.size) {
       emit('codex.subagent.drained', 'subagents drained', {
         jobs: jobs.size,
@@ -517,6 +562,23 @@ function createSubagentBroker(options = {}) {
     close();
   }
 
+  async function settleRunningWithin(timeoutMs) {
+    if (!running.size) {
+      return;
+    }
+    let timer = null;
+    const fallback = new Promise(resolve => {
+      timer = setTimeout(resolve, Math.max(0, timeoutMs));
+    });
+    await Promise.race([
+      Promise.allSettled([...running.values()].map(worker => worker.promise)),
+      fallback
+    ]);
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+
   function close() {
     if (closed) {
       return;

package/package.json

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