codex-overleaf-link 1.6.0 → 1.6.2

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.0-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.6.2-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.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.0/install.sh)"
+CODEX_OVERLEAF_REF=v1.6.2 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.2/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.0/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.6.0'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.2/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.6.2'
 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.0 -- install-native
+npm exec --yes codex-overleaf-link@1.6.2 -- install-native
 ```
 
-Then add the extension yourself: download `codex-overleaf-link-extension-v1.6.0.zip` from the [v1.6.0 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.6.0), 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.2.zip` from the [v1.6.2 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.6.2), 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.0 -- install-native` |
-| Diagnose | `npm exec --yes codex-overleaf-link@1.6.0 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native` |
+| Install / update | `npm exec --yes codex-overleaf-link@1.6.2 -- install-native` |
+| Diagnose | `npm exec --yes codex-overleaf-link@1.6.2 -- doctor` |
+| Uninstall | `npm exec --yes codex-overleaf-link@1.6.2 -- 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.0 GitHub Release contains:
+The v1.6.2 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.6.0.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.6.0.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.6.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.6.0` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.6.0` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v1.6.2.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v1.6.2.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-1.6.2.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.2` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.6.2` 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.0 GitHub Release contains:
 Remove the native host (use `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.6.2 -- 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.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.0/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v1.6.2 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.2/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native --browser chromium
+npm exec --yes codex-overleaf-link@1.6.2 -- uninstall-native --browser chromium
 ```
 
 ## Features
@@ -172,6 +172,7 @@ npm exec --yes codex-overleaf-link@1.6.0 -- 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.0 -- 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.0 -- install-native
+npm exec --yes codex-overleaf-link@1.6.2 -- 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.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.0 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@1.6.2 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.2 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.2 -- install-native` | `npm exec --yes codex-overleaf-link@1.6.2 -- install-native --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@1.6.2 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.2 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.2 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.6.2 -- 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.0';
+  const BUILD_TARGET_VERSION = '1.6.2';
   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/skills/parallel-subagents/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: parallel-subagents
 description: >
-  When a task decomposes into independent work on two or more SEPARATE files
-  (polish chapters, per-section fixes), fan it out: write job files to the
-  subagent queue and the host runs real parallel Codex workers for you. Use
-  only when file ownership can be split cleanly; fall back to sequential work
-  for a single monolithic file.
+  When a task decomposes into independent slices — separate files, OR
+  separate sections of ONE file — fan it out: write job files to the subagent
+  queue and the host runs real parallel Codex workers for you. For a single
+  file, extract per-section slice files into the queue's work/ zone, let
+  workers polish them in parallel, then reassemble (scatter-gather). Every
+  job must state an explicit, non-overlapping scope.
 ---
 
 # Parallel Subagents
@@ -18,18 +19,26 @@ Codex agent confined to the files you assign it.
 ## 1. When to use
 
 Use this when ALL of these hold:
-- The task splits into ≥ 2 independent slices, each touching **different
-  files** (e.g. one chapter file per slice).
+- The task splits into ≥ 2 independent slices: different **files**, or
+  different **sections of one file** (use the scatter-gather workflow in §5).
 - Slices do not depend on each other's output.
 - Each slice is small enough to finish in a few minutes.
 
 Do NOT use it (work sequentially yourself instead) when:
-- The project keeps everything in one monolithic file — never split one file
-  across jobs.
 - Slices are deeply cross-referenced and must be edited together.
 - There are fewer than 2 real slices.
 - The handshake file below is missing or not `ready`.
 
+## 1b. Explicit scope — the iron rule
+
+Every job's `task` MUST state its exact working scope, and scopes MUST NOT
+overlap:
+- multi-file job: name the file(s) and what inside them is in scope;
+- single-file slice job: name the section (`\section{...}` title) and quote
+  the slice's exact first and last source lines.
+Never write two jobs whose scopes could touch the same text. If you cannot
+state a slice's boundaries precisely, do that slice yourself instead.
+
 ## 2. Handshake
 
 Read `.codex-overleaf-subagents/broker.json`. If it is missing or its
@@ -60,40 +69,87 @@ Rules:
 - `id`: lowercase letters/digits/hyphens, ≤ 32 chars, unique.
 - `task`: complete, self-contained instructions — workers cannot ask
   questions. Repeat shared style guidance in EVERY job.
-- `files`: workspace-relative paths the job may edit. Keep ownership
-  disjoint across jobs.
+- `files`: workspace-relative paths the job may edit — project files or
+  slice files under `.codex-overleaf-subagents/work/`. Jobs that share a
+  file are admitted but run ONE AT A TIME (the broker serializes them);
+  disjoint jobs run in parallel.
 - `readOnlyContext`: files the worker may read but must not edit.
 
 ## 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`.
 
-## 5. Wave discipline (important)
+## 5. Single file? Two safe modes
+
+Two workers must NEVER edit the same file at the same moment (whole-file
+writes race and silently drop each other's edits) — the broker guarantees
+this for you. Pick per task:
+
+**Mode A — serialized scoped jobs (simple, no slicing).** Just write one job
+per section, all owning the same file, each `task` stating its exact section
+scope (iron rule §1b). The broker runs them one at a time, each seeing the
+previous job's output. No parallel speedup within that file (jobs on OTHER
+files still run alongside), but zero assembly work. Prefer this for 2-3
+sections or quick passes.
+
+**Mode B — scatter-gather slices (true parallelism).** For a big file where
+wall-clock matters, give each worker its own physical slice:
+
+1. **Scatter** — for each independent section, copy its EXACT text (from its
+   `\section{...}` line up to, not including, the next `\section`) into a
+   slice file, verbatim, atomically:
+   `cat > .codex-overleaf-subagents/work/.tmp-sec2 <<'EOF' ... EOF` then
+   `mv .codex-overleaf-subagents/work/.tmp-sec2 .codex-overleaf-subagents/work/sec2.tex`.
+   Preamble, frontmatter, and anything you cannot bound precisely stays with
+   you.
+2. **Jobs** — one per slice. `files` = that slice file only. The `task` must
+   say: this is a fragment of `<original file>` covering section `<title>`
+   (quote first + last line); polish it IN PLACE; do not add a preamble or
+   document wrapper; keep the project's edit conventions (e.g.
+   annotated-rewrite). Put the original file in `readOnlyContext` so the
+   worker sees surrounding context.
+3. **Gather** — after all results: verify each slice still starts with its
+   `\section{...}` line, then replace the corresponding original block in
+   the source file with the slice content, one section at a time, yourself.
+   If a slice lost its boundary line, treat that slice as failed and redo it
+   inline.
+
+Slice files live inside the queue zone, so they are scratch: they never sync
+to Overleaf — only your reassembled edits to the real file do.
+
+## 6. Wave discipline (important)
 
 While any job is queued or running, do **not** edit project files yourself —
 write jobs, poll, wait. Do your own edits before the first job or after the
 last result. Files changed during a wave that no job owns are reported as
 ownership violations and **excluded from the Overleaf writeback**.
 
-## 6. Integrate
+## 7. Integrate
 
 - For each `completed` job: read its summary, spot-check the owned files, and
   smooth terminology/transitions ACROSS slice boundaries yourself.
 - For each `failed` / `timeout` / `rejected` job: do that slice inline
-  yourself now (check `reason`; a `file_conflict` means you mis-partitioned).
+  yourself now (check `reason`).
 - Mention any violations in your close-out so the user knows those edits were
   withheld from writeback.
 
-## 7. Close out
+## 8. Close out
 
 End with a per-slice one-liner (job → what changed) plus an overall summary.
 This becomes the run report the user reads.

package/native-host/src/subagentBroker.js

@@ -76,6 +76,7 @@ function createSubagentBroker(options = {}) {
     fs.mkdirSync(jobsDir, { recursive: true });
     fs.mkdirSync(resultsDir, { recursive: true });
     fs.mkdirSync(logsDir, { recursive: true });
+    fs.mkdirSync(path.join(queueRoot, 'work'), { recursive: true });
     startedAt = Date.now();
     accepting = true;
     writeBrokerFile('ready');
@@ -194,15 +195,10 @@ function createSubagentBroker(options = {}) {
       }
       owned.push(safe);
     }
-    for (const [otherId, entry] of jobs) {
-      if (entry.status === 'rejected') {
-        continue;
-      }
-      const overlap = entry.job.files.find(file => owned.includes(file));
-      if (overlap) {
-        return { reason: 'file_conflict', path: overlap, conflictsWith: otherId };
-      }
-    }
+    // Overlapping ownership no longer rejects: same-file jobs are admitted
+    // and SERIALIZED by the scheduler (fillSlots never runs two jobs whose
+    // files intersect). Prompt-scoped same-file delegation is then safe —
+    // the physical lost-update race only exists under concurrency (v1.6.1).
     // Wave-aware admission: the parent turn has no default absolute deadline,
     // so the broker enforces its own wall-clock envelope across ALL waves.
     const projectedWaves = Math.ceil((queued.length + running.size + 1) / limits.maxWorkers);
@@ -229,6 +225,13 @@ function createSubagentBroker(options = {}) {
       return null;
     }
     if (segments[0] === SUBAGENT_QUEUE_DIR) {
+      // The queue control plane (jobs/results/logs/broker.json) is never
+      // ownable — but the work/ scratch zone IS: single-file fan-out slices
+      // live there (v1.6.1 scatter-gather), excluded from writeback by the
+      // mirror-scan rule yet fully owned/hashed like any other job file.
+      if (segments[1] === 'work' && segments.length >= 3) {
+        return segments.join('/');
+      }
       return null;
     }
     return segments.join('/');
@@ -252,8 +255,35 @@ function createSubagentBroker(options = {}) {
 
   function fillSlots() {
     while (accepting && !cancelled && queued.length && running.size < limits.maxWorkers) {
-      const jobId = queued.shift();
-      startWorker(jobs.get(jobId));
+      const runningFiles = new Set();
+      for (const id of running.keys()) {
+        for (const file of jobs.get(id).job.files) {
+          runningFiles.add(file);
+        }
+      }
+      // FIFO with skip: pick the first queued job whose ownership does not
+      // intersect any running job's files — overlapping jobs wait their turn
+      // (temporal exclusivity replaces the old overlap rejection).
+      const index = queued.findIndex(id => !jobs.get(id).job.files.some(file => runningFiles.has(file)));
+      if (index === -1) {
+        return;
+      }
+      const [jobId] = queued.splice(index, 1);
+      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 */ }
+      }
     }
   }
 
@@ -324,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,
@@ -408,6 +449,10 @@ function createSubagentBroker(options = {}) {
         return;
       }
       for (const entry of entries) {
+        // The whole queue zone (incl. the work/ slice scratch) stays out of
+        // wave hashing: scratch can never reach Overleaf, same-wave slices
+        // are all in the owned union anyway, and a lead staggering slice
+        // creation mid-wave must not read as a violation (v1.6.1).
         if (entry.name === '.DS_Store' || entry.name === SUBAGENT_QUEUE_DIR || entry.name === '.codex-overleaf-attachments') {
           continue;
         }
@@ -446,7 +491,7 @@ function createSubagentBroker(options = {}) {
       'You are a subagent working on one slice of a larger task.',
       'HARD CONSTRAINTS:',
       `- You may modify ONLY these files: ${job.files.join(', ')}.`,
-      readOnly + '- Do not modify, create, or delete any other file. Do not touch .codex-overleaf-subagents/.',
+      readOnly + '- Do not modify, create, or delete any other file. Inside .codex-overleaf-subagents/ you may touch ONLY the slice files listed above (if any).',
       '- Work fully autonomously; nobody can answer questions.',
       '',
       job.task
@@ -475,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,
@@ -497,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.0",
+  "version": "1.6.2",
   "description": "Cross-platform Chrome bridge that connects Codex to the active Overleaf project.",
   "license": "MIT",
   "type": "commonjs",