codex-overleaf-link 1.5.3 → 1.6.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.5.3-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.6.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">
@@ -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.5.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.5.3/install.sh)"
+CODEX_OVERLEAF_REF=v1.6.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.5.3/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.5.3'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.6.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.6.0'
 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.5.3 -- install-native
+npm exec --yes codex-overleaf-link@1.6.0 -- install-native
 ```
 
-Then add the extension yourself: download `codex-overleaf-link-extension-v1.5.3.zip` from the [v1.5.3 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.5.3), 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.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.
 
 ### 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.5.3 -- install-native` |
-| Diagnose | `npm exec --yes codex-overleaf-link@1.5.3 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@1.5.3 -- uninstall-native` |
+| 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` |
 
 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.5.3 GitHub Release contains:
+The v1.6.0 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.5.3.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.5.3.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.5.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.5.3` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.5.3` when run directly from the release artifact.
+- `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.
 - `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.5.3 GitHub Release contains:
 Remove the native host (use `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@1.5.3 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.6.0 -- 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.5.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.5.3/install.sh)" -- --browser chromium
+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
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.5.3 -- uninstall-native --browser chromium
+npm exec --yes codex-overleaf-link@1.6.0 -- uninstall-native --browser chromium
 ```
 
 ## Features
@@ -289,7 +289,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.5.3 -- install-native
+npm exec --yes codex-overleaf-link@1.6.0 -- install-native
 ```
 
 **The Windows popup or panel shows a Bash recovery command**
@@ -338,8 +338,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.5.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.5.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.5.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.5.3 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.5.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.5.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.5.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.5.3 -- uninstall-native --browser chromium` |
+| 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` |
 | 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

@@ -135,6 +135,10 @@
       };
     }
 
+    if (type.indexOf('codex.subagent.') === 0) {
+      return mapSubagentEvent(event, type, locale);
+    }
+
     if (type === 'codex.exec.started') {
       return {
         kind: 'activity',
@@ -202,6 +206,81 @@
     };
   }
 
+  // Parallel-subagents lifecycle (v1.6): one human-readable line per state
+  // change; worker raw output never streams here (it lives in the queue's
+  // result files), so these lines plus the collapsed technical detail are the
+  // whole timeline footprint of a fan-out.
+  function mapSubagentEvent(event, type, locale) {
+    const detail = event.detail || {};
+    const label = String(event.title || detail.jobId || '').slice(0, 80);
+    const base = {
+      kind: 'activity',
+      visible: true,
+      technicalDetail: normalizeRawEvent(event)
+    };
+    if (type === 'codex.subagent.queued') {
+      return { ...base, status: 'running', title: textFor(locale, `↳ 子代理「${label}」已排队。`, `↳ Subagent "${label}" queued.`) };
+    }
+    if (type === 'codex.subagent.started') {
+      const active = Number(detail.activeWorkers) || 0;
+      const max = Number(detail.maxWorkers) || 0;
+      const slots = active && max ? `${active}/${max}` : '';
+      return {
+        ...base,
+        status: 'running',
+        title: slots
+          ? textFor(locale, `↳ 子代理「${label}」开始（${slots} 并行）。`, `↳ Subagent "${label}" started (${slots} parallel).`)
+          : textFor(locale, `↳ 子代理「${label}」开始。`, `↳ Subagent "${label}" started.`)
+      };
+    }
+    if (type === 'codex.subagent.completed') {
+      const seconds = Math.round((Number(detail.durationMs) || 0) / 1000);
+      return {
+        ...base,
+        status: 'completed',
+        title: seconds
+          ? textFor(locale, `↳ 子代理「${label}」完成（${seconds}s）。`, `↳ Subagent "${label}" completed (${seconds}s).`)
+          : textFor(locale, `↳ 子代理「${label}」完成。`, `↳ Subagent "${label}" completed.`)
+      };
+    }
+    if (type === 'codex.subagent.failed') {
+      const status = String(detail.status || 'failed');
+      const reason = String(detail.reason || '').slice(0, 120);
+      const zhStatus = status === 'timeout' ? '超时' : status === 'cancelled' ? '被取消' : '失败';
+      const enStatus = status === 'timeout' ? 'timed out' : status === 'cancelled' ? 'was cancelled' : 'failed';
+      return {
+        ...base,
+        status: 'warning',
+        title: reason
+          ? textFor(locale, `↳ 子代理「${label}」${zhStatus}：${reason}`, `↳ Subagent "${label}" ${enStatus}: ${reason}`)
+          : textFor(locale, `↳ 子代理「${label}」${zhStatus}。`, `↳ Subagent "${label}" ${enStatus}.`)
+      };
+    }
+    if (type === 'codex.subagent.rejected') {
+      const reason = String(detail.reason || 'rejected');
+      return {
+        ...base,
+        status: 'warning',
+        title: textFor(locale, `↳ 子代理任务「${label}」被拒绝（${reason}）。`, `↳ Subagent job "${label}" was rejected (${reason}).`)
+      };
+    }
+    if (type === 'codex.subagent.violation') {
+      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.`)
+      };
+    }
+    if (type === 'codex.subagent.drained') {
+      return {
+        ...base,
+        status: 'completed',
+        title: textFor(locale, '↳ 子代理已全部收尾。', '↳ All subagents drained.')
+      };
+    }
+    return { ...base, status: event.status || 'running', title: label };
+  }
+
   function mapCodexSessionEvent(event, locale) {
     const method = String(event.detail?.method || event.title || '');
     const params = event.detail?.params || {};

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

package/extension/src/shared/sessionState.js

@@ -852,6 +852,16 @@
     return compact;
   }
 
+  function compactCodexOverleafSkillsForStorage(skills) {
+    return (Array.isArray(skills) ? skills : [])
+      .slice(0, 32)
+      .map(skill => ({
+        id: String(skill?.id || '').trim().slice(0, 64),
+        name: String(skill?.name || '').trim().slice(0, 80)
+      }))
+      .filter(skill => skill.id);
+  }
+
   function compactPanelStateForStorage(input, limits) {
     const source = {
       ...DEFAULT_PANEL_STATE,
@@ -869,6 +879,11 @@
     const active = compactSessions.find(session => session.id === resolvedActiveId) || compactSessions[0] || null;
 
     return {
+      // The Codex-Overleaf skills catalog must survive reloads: the parallel-
+      // subagents broker gate reads it at run time, and before v1.6.1 it was
+      // stripped here — so the gate silently died after any reload until the
+      // Skills page was reopened.
+      codexOverleafSkills: compactCodexOverleafSkillsForStorage(source.codexOverleafSkills),
       mode: VALID_MODES.has(active?.mode) ? active.mode : normalizeMode(source.mode),
       model: normalizeTextField(active?.model || source.model || DEFAULT_PANEL_STATE.model, 80),
       reasoningEffort: VALID_REASONING.has(active?.reasoningEffort)

package/native-host/src/codexSessionRunner.js

@@ -3,7 +3,7 @@
 const { spawn } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { collectMirrorChangesDetailed, getProjectMirror, markMirrorDirty, syncOverleafToMirror } = require('./mirrorWorkspace');
+const { SUBAGENT_QUEUE_DIR, collectMirrorChangesDetailed, getProjectMirror, markMirrorDirty, syncOverleafToMirror } = require('./mirrorWorkspace');
 const { computeLineDiff } = require('./diffEngine');
 const { computeTextPatches } = require('./textPatch');
 const { buildCodexHomeEnv } = require('./codexHome');
@@ -17,6 +17,9 @@ const {
   loadSelectedCodexOverleafSkill,
   loadSelectedProjectSkills
 } = require('./localSkills');
+const { createSubagentBroker } = require('./subagentBroker');
+
+const PARALLEL_SUBAGENTS_SKILL_ID = 'parallel-subagents';
 
 const TURN_ATTACHMENTS_DIR = '.codex-overleaf-attachments';
 const MAX_TURN_ATTACHMENT_BYTES = 12 * 1024 * 1024;
@@ -80,27 +83,92 @@ async function runCodexSession({ params = {}, env = process.env, emit = () => {}
     fs.mkdirSync(runnerWorkspacePath, { recursive: true });
   }
   const runner = executeCodex || runCodexAppServerSession;
-  const runnerResult = await runner({
-    workspacePath: runnerWorkspacePath,
-    task: buildCodexTurnPrompt(params, mirror, projectLocalSkills, turnAttachments, codexSkillInvocationContext),
-    userTask: String(params.task || ''),
-    session: params.session || null,
-    threadId: params.threadId || '',
-    mode: params.mode || 'auto',
-    model: params.model || '',
-    reasoningEffort: params.reasoningEffort || '',
-    speedTier: normalizeSpeedTier(params.speedTier),
-    loadCodexLocalSkills: skillLoading.loadCodexLocalSkills,
-    loadCodexOverleafSkills: skillLoading.loadCodexOverleafSkills,
-    skillInvocation: effectiveSkillInvocation,
-    installCodexOverleafSkillsTarget: skillInstallTurn,
-    projectLocalSkills: null,
-    sandboxMode: settings.sandboxMode,
-    approvalPolicy: settings.approvalPolicy,
-    env,
-    emit,
-    signal
-  });
+  // Parallel-subagents broker (v1.6): activated solely by the official skill
+  // being enabled for this run. Workers are sibling Codex runs spawned by the
+  // host (fresh sandbox — never nested), confined to the same mirror; the
+  // broker enforces file ownership and wall-clock deadlines (spec §5-§7).
+  const subagentBroker = !skillInstallTurn
+    && skillLoading.loadCodexOverleafSkills !== false
+    && Array.isArray(params.enabledCodexOverleafSkillIds)
+    && params.enabledCodexOverleafSkillIds.includes(PARALLEL_SUBAGENTS_SKILL_ID)
+    ? createSubagentBroker({
+      workspacePath: mirror.workspacePath,
+      signal,
+      emit: (type, title, detail, status) => emitCodexEvent(emit, type, title, detail, status),
+      onMirrorDirty: () => markMirrorDirty({ projectId, rootDir, reason: 'subagent_run_cancelled' }),
+      runWorkerTask: ({ jobId, prompt, signal: workerSignal }) => runner({
+        workspacePath: mirror.workspacePath,
+        task: prompt,
+        userTask: `subagent:${jobId}`,
+        session: null,
+        threadId: '',
+        mode: params.mode || 'auto',
+        model: params.model || '',
+        reasoningEffort: params.reasoningEffort || '',
+        speedTier: normalizeSpeedTier(params.speedTier),
+        loadCodexLocalSkills: skillLoading.loadCodexLocalSkills,
+        loadCodexOverleafSkills: skillLoading.loadCodexOverleafSkills,
+        skillInvocation: null,
+        installCodexOverleafSkillsTarget: false,
+        projectLocalSkills: null,
+        // Recursion guard (spec S6): workers inherit skills EXCEPT the
+        // fan-out skill itself, stripped per worker app-server process.
+        disableCodexOverleafSkillIds: [PARALLEL_SUBAGENTS_SKILL_ID],
+        sandboxMode: settings.sandboxMode,
+        approvalPolicy: settings.approvalPolicy,
+        env,
+        // Worker raw events stay out of the parent timeline (spec §8);
+        // lifecycle events come from the broker, full text from result files.
+        emit: () => {},
+        signal: workerSignal
+      })
+    })
+    : null;
+  if (subagentBroker) {
+    subagentBroker.start();
+  } else if (!skillInstallTurn) {
+    // No broker this run: remove any stale queue from a previous brokered run
+    // so the model never reads a leftover closed handshake and reports the
+    // feature as half-available (v1.6.1 — observed in E2E).
+    fs.rmSync(path.join(mirror.workspacePath, SUBAGENT_QUEUE_DIR), { recursive: true, force: true });
+  }
+  let runnerResult;
+  try {
+    runnerResult = await runner({
+      workspacePath: runnerWorkspacePath,
+      task: buildCodexTurnPrompt(params, mirror, projectLocalSkills, turnAttachments, codexSkillInvocationContext),
+      userTask: String(params.task || ''),
+      session: params.session || null,
+      threadId: params.threadId || '',
+      mode: params.mode || 'auto',
+      model: params.model || '',
+      reasoningEffort: params.reasoningEffort || '',
+      speedTier: normalizeSpeedTier(params.speedTier),
+      loadCodexLocalSkills: skillLoading.loadCodexLocalSkills,
+      loadCodexOverleafSkills: skillLoading.loadCodexOverleafSkills,
+      skillInvocation: effectiveSkillInvocation,
+      installCodexOverleafSkillsTarget: skillInstallTurn,
+      projectLocalSkills: null,
+      sandboxMode: settings.sandboxMode,
+      approvalPolicy: settings.approvalPolicy,
+      env,
+      emit,
+      // While subagent workers are active, the parent idle watchdog resets
+      // instead of failing the run (spec P2-7 fix).
+      hasExternalActivity: subagentBroker ? () => subagentBroker.hasActiveWorkers() : undefined,
+      signal
+    });
+  } catch (error) {
+    if (subagentBroker) {
+      await subagentBroker.stop({ drain: false });
+    }
+    throw error;
+  }
+  // Parent turn finished: drain remaining workers so their edits are part of
+  // the single mirror diff below, then close the queue.
+  if (subagentBroker) {
+    await subagentBroker.stop({ drain: true });
+  }
   throwIfAborted(signal);
 
   if (skillInstallTurn) {
@@ -124,11 +192,27 @@ async function runCodexSession({ params = {}, env = process.env, emit = () => {}
     focusFiles: params.focusFiles || params.session?.focusFiles,
     restrictToFocusFiles: params.restrictToFocusFiles
   });
-  const rawSyncChanges = filteredChanges.changes;
+  let rawSyncChanges = filteredChanges.changes;
   const unsupportedChanges = [
     ...(collected.unsupportedChanges || []),
     ...filteredChanges.unsupportedChanges
   ];
+  // Spec S8: ownership violations hard-block writeback. Changes on violated
+  // paths are demoted to unsupportedChanges (surfaced, never auto-applied) —
+  // this must hold even when requireReviewing is off and ordinary
+  // syncChanges would write directly.
+  const subagentViolationPaths = subagentBroker ? subagentBroker.getViolationPaths() : null;
+  if (subagentViolationPaths && subagentViolationPaths.size) {
+    const blocked = rawSyncChanges.filter(change => subagentViolationPaths.has(change.path));
+    rawSyncChanges = rawSyncChanges.filter(change => !subagentViolationPaths.has(change.path));
+    for (const change of blocked) {
+      unsupportedChanges.push({
+        type: 'unsupported-local-file',
+        path: change.path,
+        reason: 'subagent_unauthorized_edit'
+      });
+    }
+  }
   if (rawSyncChanges.length || unsupportedChanges.length) {
     markMirrorDirty({
       projectId,
@@ -548,6 +632,40 @@ async function applyCodexSkillIsolation({ input = {}, childEnv = process.env, re
   return { disabled };
 }
 
+// Recursion guard (spec S6): disable specific Codex-Overleaf skills for one
+// app-server child process — used to strip `parallel-subagents` from worker
+// runs so an inheriting worker cannot discover the queue and fan out again.
+// Skill directories are named by skill id (<root>/<id>/SKILL.md).
+async function applyWorkerSkillStrip({ input = {}, request } = {}) {
+  const ids = Array.isArray(input.disableCodexOverleafSkillIds)
+    ? input.disableCodexOverleafSkillIds.filter(Boolean)
+    : [];
+  if (!ids.length || typeof request !== 'function') {
+    return { disabled: [] };
+  }
+  const listResult = await request('skills/list', {
+    cwd: input.workspacePath,
+    includeDisabled: true
+  });
+  const disabled = [];
+  for (const skill of flattenCodexSkillsList(listResult)) {
+    if (skill?.enabled === false) {
+      continue;
+    }
+    const skillDirName = path.basename(path.dirname(String(skill?.path || '')));
+    if (!ids.includes(skillDirName)) {
+      continue;
+    }
+    const params = buildSkillDisableParams(skill);
+    if (!params) {
+      continue;
+    }
+    await request('skills/config/write', params);
+    disabled.push(skillDirName);
+  }
+  return { disabled };
+}
+
 function flattenCodexSkillsList(listResult = {}) {
   const data = Array.isArray(listResult?.data) ? listResult.data : [];
   return data.flatMap(entry => Array.isArray(entry?.skills) ? entry.skills : []);
@@ -692,6 +810,13 @@ function runCodexAppServerSession(input) {
     });
     const idleTimeoutMs = parseOptionalPositiveInteger(childEnv.CODEX_OVERLEAF_CODEX_IDLE_TIMEOUT_MS) || 600000;
     const idleWatchdog = createCodexIdleWatchdog(idleTimeoutMs, ms => {
+      // While the subagent broker reports active workers the parent may be
+      // legitimately quiet (waiting on results); reset instead of failing
+      // (spec P2-7). The broker's own wall-clock deadlines bound the wait.
+      if (input.hasExternalActivity?.()) {
+        idleWatchdog.reset();
+        return;
+      }
       fail(new Error(`Codex app-server produced no events for ${ms}ms (idle watchdog); the run was aborted to release the project lock.`));
     });
     const onAbort = () => {
@@ -740,6 +865,10 @@ function runCodexAppServerSession(input) {
         request,
         emit: input.emit
       });
+      await applyWorkerSkillStrip({
+        input,
+        request
+      });
 
       if (input.threadId) {
         try {

package/native-host/src/localSkills.js

@@ -13,7 +13,7 @@ const MAX_SKILL_CONTENT_CHARS = MAX_SKILL_CONTENT_BYTES;
 const MAX_SKILL_PREVIEW_CHARS = 240;
 const PROJECT_SKILL_SCOPE = 'project';
 const CODEX_OVERLEAF_SKILL_SCOPE = 'codex-overleaf';
-const OFFICIAL_CODEX_OVERLEAF_SKILL_IDS = ['annotated-rewrite'];
+const OFFICIAL_CODEX_OVERLEAF_SKILL_IDS = ['annotated-rewrite', 'parallel-subagents'];
 
 function listProjectSkills({ projectId, rootDir } = {}) {
   const skillsDir = getProjectSkillsDir(projectId, { rootDir });

package/native-host/src/mirrorWorkspace.js

@@ -11,6 +11,10 @@ const NATIVE_OUTPUT_LIMIT_BYTES = 1024 * 1024;
 const SAFE_INLINE_BINARY_CHANGE_BYTES = 512 * 1024;
 const SAFE_NATIVE_RESPONSE_PAYLOAD_BYTES = NATIVE_OUTPUT_LIMIT_BYTES - (64 * 1024);
 const TURN_ATTACHMENTS_DIR = '.codex-overleaf-attachments';
+// Control plane for the parallel-subagents broker (v1.6). Lives inside the
+// workspace so the sandboxed model can write jobs, but is excluded from the
+// mirror scan so queue/result/log files can never enter Overleaf writeback.
+const SUBAGENT_QUEUE_DIR = '.codex-overleaf-subagents';
 
 function getProjectMirror(projectId, options = {}) {
   const rootDir = path.resolve(options.rootDir || getDefaultMirrorRoot(options));
@@ -521,7 +525,7 @@ function listWorkspaceFiles(workspacePath) {
 
   function walk(dir, prefix) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name === '.DS_Store' || entry.name === TURN_ATTACHMENTS_DIR) {
+      if (entry.name === '.DS_Store' || entry.name === TURN_ATTACHMENTS_DIR || entry.name === SUBAGENT_QUEUE_DIR) {
         continue;
       }
       const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -1004,6 +1008,7 @@ function verifyWorkspaceMatchesBaseline(workspacePath, baselineFiles = []) {
 }
 
 module.exports = {
+  SUBAGENT_QUEUE_DIR,
   NATIVE_OUTPUT_LIMIT_BYTES,
   SAFE_INLINE_BINARY_CHANGE_BYTES,
   SAFE_NATIVE_RESPONSE_PAYLOAD_BYTES,

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

@@ -0,0 +1,99 @@
+---
+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.
+---
+
+# Parallel Subagents
+
+The native host can run parallel Codex workers for you. You cannot spawn
+processes yourself (the sandbox forbids it) — instead you write **job files**
+into a queue directory and poll for **result files**. Each worker is a full
+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).
+- 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`.
+
+## 2. Handshake
+
+Read `.codex-overleaf-subagents/broker.json`. If it is missing or its
+`status` is not `ready`, the broker is off — do everything yourself. Respect
+`maxWorkers`, `maxJobsPerRun`, and `perWorkerTimeoutMs` (size each job to
+finish well inside it).
+
+## 3. Write jobs
+
+One job per slice. Each job OWNS its `files` exclusively — no file may appear
+in two jobs. Write atomically: create a temp file, then `mv` it to its final
+`.json` name.
+
+```bash
+cat > .codex-overleaf-subagents/jobs/.tmp-ch3 <<'JSON'
+{
+  "id": "ch3",
+  "title": "Polish chapter 3",
+  "task": "Polish sections/ch3.tex for grammar, flow, and concision. Keep all math and citations intact. Follow the shared style notes: <paste the style guidance here>.",
+  "files": ["sections/ch3.tex"],
+  "readOnlyContext": ["main.tex", "macros.tex"]
+}
+JSON
+mv .codex-overleaf-subagents/jobs/.tmp-ch3 .codex-overleaf-subagents/jobs/ch3.json
+```
+
+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.
+- `readOnlyContext`: files the worker may read but must not edit.
+
+## 4. Poll for results
+
+```bash
+while [ "$(ls .codex-overleaf-subagents/results/*.json 2>/dev/null | wc -l)" -lt <jobCount> ]; do
+  sleep 10
+  ls .codex-overleaf-subagents/results/ 2>/dev/null
+done
+```
+
+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)
+
+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
+
+- 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).
+- Mention any violations in your close-out so the user knows those edits were
+  withheld from writeback.
+
+## 7. 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

@@ -0,0 +1,539 @@
+'use strict';
+
+// Parallel-subagents broker (v1.6, spec: docs/superpowers/specs/
+// 2026-06-10-v1.6-parallel-subagents-design.md).
+//
+// The sandboxed model cannot spawn processes (Seatbelt kills nested Codex at
+// client init — verified empirically), but it CAN write workspace files. The
+// broker runs in the native host (outside the sandbox), watches a file-based
+// job queue inside the mirror workspace, and fans each accepted job out to a
+// real sibling Codex run via an injected `runWorkerTask`. Ownership of files
+// is disjoint by protocol; violations are attributed at wave level and the
+// runner hard-blocks them from writeback (spec S5/S8).
+//
+// Everything time- or process-shaped is injectable so the unit suite can run
+// with fake workers and millisecond limits.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { SUBAGENT_QUEUE_DIR } = require('./mirrorWorkspace');
+
+const PROTOCOL_VERSION = 1;
+const JOB_ID_PATTERN = /^[a-z0-9-]{1,32}$/;
+const MAX_JOB_FILE_BYTES = 32 * 1024;
+const SUMMARY_LIMIT_CHARS = 2048;
+
+const DEFAULT_LIMITS = Object.freeze({
+  maxWorkers: 3,
+  maxJobsPerRun: 8,
+  perWorkerTimeoutMs: 300000,
+  brokerBudgetMs: 900000,
+  pollIntervalMs: 500,
+  drainGraceMs: 30000
+});
+
+function createSubagentBroker(options = {}) {
+  const workspacePath = options.workspacePath;
+  if (!workspacePath) {
+    throw new Error('subagent broker requires a workspacePath');
+  }
+  const runWorkerTask = options.runWorkerTask;
+  if (typeof runWorkerTask !== 'function') {
+    throw new Error('subagent broker requires a runWorkerTask function');
+  }
+  const emit = typeof options.emit === 'function' ? options.emit : () => {};
+  const onMirrorDirty = typeof options.onMirrorDirty === 'function' ? options.onMirrorDirty : () => {};
+  const parentSignal = options.signal || null;
+  const limits = { ...DEFAULT_LIMITS, ...(options.limits || {}) };
+
+  const queueRoot = path.join(workspacePath, SUBAGENT_QUEUE_DIR);
+  const jobsDir = path.join(queueRoot, 'jobs');
+  const resultsDir = path.join(queueRoot, 'results');
+  const logsDir = path.join(queueRoot, 'logs');
+
+  const jobs = new Map(); // id -> { job, status, startedAt, ownedBefore }
+  const seenFiles = new Set();
+  const violations = [];
+  const violationPaths = new Set();
+  let queued = [];
+  let running = new Map(); // id -> { controller, deadlineTimer, promise }
+  let acceptedCount = 0;
+  let startedAt = 0;
+  let accepting = false;
+  let pollTimer = null;
+  let waveIndex = 0;
+  let waveSnapshot = null; // { hashes: Map(path->hash), ownedUnion: Set, jobIds: [] }
+  let anyWorkerStarted = false;
+  let cancelled = false;
+  let closed = false;
+
+  function start() {
+    // Stale queue dirs from a previous run carry old results/logs — clear
+    // them so the model never reads another run's state (spec S9).
+    fs.rmSync(queueRoot, { recursive: true, force: true });
+    fs.mkdirSync(jobsDir, { recursive: true });
+    fs.mkdirSync(resultsDir, { recursive: true });
+    fs.mkdirSync(logsDir, { recursive: true });
+    startedAt = Date.now();
+    accepting = true;
+    writeBrokerFile('ready');
+    pollTimer = setInterval(pollOnce, limits.pollIntervalMs);
+    if (parentSignal) {
+      parentSignal.addEventListener('abort', onParentAbort, { once: true });
+    }
+  }
+
+  function writeBrokerFile(status) {
+    const payload = {
+      protocolVersion: PROTOCOL_VERSION,
+      status,
+      maxWorkers: limits.maxWorkers,
+      maxJobsPerRun: limits.maxJobsPerRun,
+      perWorkerTimeoutMs: limits.perWorkerTimeoutMs,
+      brokerBudgetMs: limits.brokerBudgetMs,
+      acceptedUntil: new Date(startedAt + limits.brokerBudgetMs - limits.perWorkerTimeoutMs).toISOString()
+    };
+    atomicWrite(path.join(queueRoot, 'broker.json'), JSON.stringify(payload, null, 2));
+  }
+
+  function atomicWrite(target, text) {
+    const tmp = path.join(path.dirname(target), `.tmp-${crypto.randomUUID()}`);
+    fs.writeFileSync(tmp, text);
+    fs.renameSync(tmp, target);
+  }
+
+  function pollOnce() {
+    if (closed || cancelled) {
+      return;
+    }
+    try {
+      intakeJobs();
+      fillSlots();
+    } catch (_error) {
+      // The queue is adversarial model output; the broker never throws on it.
+    }
+  }
+
+  function intakeJobs() {
+    if (!accepting || !fs.existsSync(jobsDir)) {
+      return;
+    }
+    for (const name of fs.readdirSync(jobsDir).sort()) {
+      if (!name.endsWith('.json') || name.startsWith('.tmp-') || seenFiles.has(name)) {
+        continue;
+      }
+      seenFiles.add(name);
+      admitJobFile(name);
+    }
+  }
+
+  function admitJobFile(name) {
+    const filePath = path.join(jobsDir, name);
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch (_error) {
+      return;
+    }
+    if (stat.size > MAX_JOB_FILE_BYTES) {
+      return writeRejection({ id: idFromFileName(name), reason: 'job_too_large' });
+    }
+    let job;
+    try {
+      job = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (_error) {
+      return writeRejection({ id: idFromFileName(name), reason: 'invalid_json' });
+    }
+    const rejection = validateJob(job);
+    if (rejection) {
+      return writeRejection({ id: jobIdOrFallback(job, name), ...rejection });
+    }
+    acceptedCount += 1;
+    jobs.set(job.id, { job, status: 'queued' });
+    queued.push(job.id);
+    emit('codex.subagent.queued', job.title || job.id, { jobId: job.id, files: job.files }, 'running');
+  }
+
+  function idFromFileName(name) {
+    return name.replace(/\.json$/, '').slice(0, 32) || 'unknown';
+  }
+
+  function jobIdOrFallback(job, name) {
+    return typeof job?.id === 'string' && job.id ? job.id.slice(0, 32) : idFromFileName(name);
+  }
+
+  function validateJob(job) {
+    if (!job || typeof job !== 'object') {
+      return { reason: 'invalid_json' };
+    }
+    if (typeof job.id !== 'string' || !JOB_ID_PATTERN.test(job.id)) {
+      return { reason: 'invalid_id' };
+    }
+    if (jobs.has(job.id)) {
+      return { reason: 'duplicate_id' };
+    }
+    if (acceptedCount >= limits.maxJobsPerRun) {
+      return { reason: 'too_many_jobs' };
+    }
+    if (typeof job.task !== 'string' || !job.task.trim()) {
+      return { reason: 'missing_task' };
+    }
+    if (!Array.isArray(job.files) || !job.files.length) {
+      return { reason: 'missing_files' };
+    }
+    const owned = [];
+    for (const file of job.files) {
+      const safe = safeWorkspaceRelativePath(file);
+      if (!safe) {
+        return { reason: 'unsafe_path', path: String(file) };
+      }
+      if (!fs.existsSync(path.join(workspacePath, safe))) {
+        return { reason: 'missing_file', path: safe };
+      }
+      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 };
+      }
+    }
+    // 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);
+    if (Date.now() + projectedWaves * limits.perWorkerTimeoutMs > startedAt + limits.brokerBudgetMs) {
+      return { reason: 'insufficient_time' };
+    }
+    job.files = owned;
+    job.readOnlyContext = Array.isArray(job.readOnlyContext)
+      ? job.readOnlyContext.map(safeWorkspaceRelativePath).filter(Boolean)
+      : [];
+    return null;
+  }
+
+  function safeWorkspaceRelativePath(value) {
+    if (typeof value !== 'string' || !value.trim()) {
+      return null;
+    }
+    const normalized = value.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!normalized || path.isAbsolute(normalized)) {
+      return null;
+    }
+    const segments = normalized.split('/');
+    if (segments.some(segment => segment === '..' || segment === '')) {
+      return null;
+    }
+    if (segments[0] === SUBAGENT_QUEUE_DIR) {
+      return null;
+    }
+    return segments.join('/');
+  }
+
+  function writeRejection(input) {
+    const result = {
+      id: input.id,
+      status: 'rejected',
+      reason: input.reason,
+      path: input.path,
+      conflictsWith: input.conflictsWith
+    };
+    writeResult(result);
+    emit('codex.subagent.rejected', input.id, result, 'warning');
+  }
+
+  function writeResult(result) {
+    atomicWrite(path.join(resultsDir, `${result.id}.json`), JSON.stringify(result, null, 2));
+  }
+
+  function fillSlots() {
+    while (accepting && !cancelled && queued.length && running.size < limits.maxWorkers) {
+      const jobId = queued.shift();
+      startWorker(jobs.get(jobId));
+    }
+  }
+
+  function startWorker(entry) {
+    const { job } = entry;
+    if (running.size === 0) {
+      beginWave();
+    }
+    anyWorkerStarted = true;
+    entry.status = 'running';
+    entry.startedAt = Date.now();
+    entry.wave = waveIndex;
+    entry.ownedBefore = hashPaths(job.files);
+    waveSnapshot.jobIds.push(job.id);
+    for (const file of job.files) {
+      waveSnapshot.ownedUnion.add(file);
+    }
+
+    const controller = new AbortController();
+    let timedOut = false;
+    const deadlineTimer = setTimeout(() => {
+      // Broker-owned wall-clock deadline (spec P1-5 fix): the runner's
+      // absolute timeout is an opt-in env override and the idle watchdog
+      // never fires on a chatty-but-stuck worker, so the broker is the only
+      // component positioned to bound worker wall-clock time.
+      timedOut = true;
+      controller.abort(new Error('subagent timeout'));
+    }, limits.perWorkerTimeoutMs);
+
+    emit('codex.subagent.started', job.title || job.id, {
+      jobId: job.id,
+      files: job.files,
+      activeWorkers: running.size + 1,
+      maxWorkers: limits.maxWorkers
+    }, 'running');
+
+    const promise = runWorkerTask({
+      jobId: job.id,
+      prompt: buildWorkerPrompt(job),
+      signal: controller.signal
+    }).then(workerResult => {
+      finishWorker(entry, {
+        status: 'completed',
+        summary: String(workerResult?.assistantMessage || '').slice(0, SUMMARY_LIMIT_CHARS),
+        tokensUsed: workerResult?.tokensUsed
+      }, workerResult);
+    }).catch(error => {
+      // Any broker-initiated abort that is not the wall-clock deadline
+      // (parent cancel, drain) reads as 'cancelled'; only genuine worker
+      // errors read as 'failed'.
+      const status = timedOut ? 'timeout' : controller.signal.aborted ? 'cancelled' : 'failed';
+      appendLog(job.id, `${status}: ${error?.stack || error?.message || String(error)}`);
+      finishWorker(entry, { status, reason: error?.message || String(error) });
+    }).finally(() => {
+      clearTimeout(deadlineTimer);
+      running.delete(job.id);
+      if (running.size === 0) {
+        endWave();
+      }
+      fillSlots();
+    });
+
+    running.set(job.id, { controller, deadlineTimer, promise });
+  }
+
+  function finishWorker(entry, resultFields, workerResult) {
+    const { job } = entry;
+    entry.status = resultFields.status;
+    const ownedAfter = hashPaths(job.files);
+    const changedFiles = job.files.filter(file => entry.ownedBefore.get(file) !== ownedAfter.get(file));
+    const result = {
+      id: job.id,
+      ...resultFields,
+      changedFiles,
+      durationMs: Date.now() - entry.startedAt
+    };
+    entry.result = result;
+    writeResult(result);
+    if (resultFields.status === 'completed' && workerResult?.assistantMessage) {
+      atomicWrite(path.join(resultsDir, `${job.id}.last-message.md`), String(workerResult.assistantMessage));
+    }
+    const eventType = resultFields.status === 'completed' ? 'codex.subagent.completed' : 'codex.subagent.failed';
+    emit(eventType, job.title || job.id, {
+      jobId: job.id,
+      status: resultFields.status,
+      reason: resultFields.reason,
+      changedFiles,
+      durationMs: result.durationMs
+    }, resultFields.status === 'completed' ? 'completed' : 'warning');
+  }
+
+  function appendLog(jobId, text) {
+    try {
+      fs.appendFileSync(path.join(logsDir, `${jobId}.log`), `${new Date().toISOString()} ${text}\n`);
+    } catch (_error) { /* logs are best-effort */ }
+  }
+
+  // ---- wave tracking (spec S5): owned attribution is per worker; unowned
+  // changes can only be attributed to the wave's set of suspects.
+  function beginWave() {
+    waveIndex += 1;
+    waveSnapshot = {
+      hashes: hashWorkspace(),
+      ownedUnion: new Set(),
+      jobIds: []
+    };
+  }
+
+  function endWave() {
+    if (!waveSnapshot) {
+      return;
+    }
+    const after = hashWorkspace();
+    const before = waveSnapshot.hashes;
+    const changed = new Set();
+    for (const [file, hash] of after) {
+      if (before.get(file) !== hash) {
+        changed.add(file);
+      }
+    }
+    for (const file of before.keys()) {
+      if (!after.has(file)) {
+        changed.add(file);
+      }
+    }
+    for (const file of changed) {
+      if (waveSnapshot.ownedUnion.has(file)) {
+        continue;
+      }
+      const violation = {
+        path: file,
+        wave: waveIndex,
+        suspects: [...waveSnapshot.jobIds, 'parent']
+      };
+      violations.push(violation);
+      violationPaths.add(file);
+      emit('codex.subagent.violation', file, violation, 'warning');
+    }
+    waveSnapshot = null;
+  }
+
+  function hashWorkspace() {
+    const hashes = new Map();
+    walk(workspacePath, '');
+    return hashes;
+
+    function walk(dir, prefix) {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch (_error) {
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.name === '.DS_Store' || entry.name === SUBAGENT_QUEUE_DIR || entry.name === '.codex-overleaf-attachments') {
+          continue;
+        }
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const absolute = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(absolute, relative);
+        } else if (entry.isFile()) {
+          hashes.set(relative, hashFile(absolute));
+        }
+      }
+    }
+  }
+
+  function hashPaths(files) {
+    const hashes = new Map();
+    for (const file of files) {
+      hashes.set(file, hashFile(path.join(workspacePath, file)));
+    }
+    return hashes;
+  }
+
+  function hashFile(absolute) {
+    try {
+      return crypto.createHash('sha1').update(fs.readFileSync(absolute)).digest('hex');
+    } catch (_error) {
+      return 'missing';
+    }
+  }
+
+  function buildWorkerPrompt(job) {
+    const readOnly = job.readOnlyContext.length
+      ? `- You may read these for context but must not modify them: ${job.readOnlyContext.join(', ')}.\n`
+      : '';
+    return [
+      '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/.',
+      '- Work fully autonomously; nobody can answer questions.',
+      '',
+      job.task
+    ].join('\n');
+  }
+
+  function onParentAbort() {
+    cancelled = true;
+    accepting = false;
+    for (const { controller } of running.values()) {
+      controller.abort(new Error('run cancelled'));
+    }
+    for (const jobId of queued.splice(0)) {
+      const entry = jobs.get(jobId);
+      entry.status = 'cancelled';
+      writeResult({ id: jobId, status: 'cancelled', reason: 'run cancelled' });
+    }
+    if (anyWorkerStarted) {
+      // Partial worker edits must be deterministically discarded: cancellation
+      // already skips writeback, and the dirty mark forces the next run's
+      // mirror sync to rebuild the workspace from Overleaf (spec P1-3 fix).
+      onMirrorDirty();
+    }
+    close();
+  }
+
+  async function stop({ drain = true } = {}) {
+    accepting = false;
+    if (drain && running.size) {
+      const grace = new Promise(resolve => {
+        setTimeout(resolve, limits.drainGraceMs);
+      });
+      await Promise.race([
+        Promise.allSettled([...running.values()].map(worker => worker.promise)),
+        grace
+      ]);
+    }
+    for (const { controller } of running.values()) {
+      controller.abort(new Error('broker drained'));
+    }
+    await Promise.allSettled([...running.values()].map(worker => worker.promise));
+    if (jobs.size) {
+      emit('codex.subagent.drained', 'subagents drained', {
+        jobs: jobs.size,
+        violations: violations.length
+      }, 'completed');
+    }
+    close();
+  }
+
+  function close() {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    if (pollTimer) {
+      clearInterval(pollTimer);
+    }
+    parentSignal?.removeEventListener?.('abort', onParentAbort);
+    try {
+      writeBrokerFile('closed');
+    } catch (_error) { /* workspace may already be gone */ }
+  }
+
+  return {
+    start,
+    stop,
+    pollOnce,
+    hasActiveWorkers: () => running.size > 0,
+    hasAcceptedJobs: () => jobs.size > 0,
+    getViolationPaths: () => new Set(violationPaths),
+    getAuditSummary: () => ({
+      jobs: [...jobs.values()].map(entry => ({
+        id: entry.job?.id,
+        title: entry.job?.title,
+        files: entry.job?.files,
+        status: entry.status,
+        reason: entry.result?.reason,
+        durationMs: entry.result?.durationMs
+      })),
+      violations: violations.slice()
+    })
+  };
+}
+
+module.exports = {
+  createSubagentBroker,
+  SUBAGENT_QUEUE_DIR,
+  DEFAULT_SUBAGENT_LIMITS: DEFAULT_LIMITS
+};

package/native-host/src/taskRunnerRuntime.js

@@ -291,6 +291,12 @@ function handleSkillsList(request, env) {
   try {
     const { CODEX_OVERLEAF_SKILL_SCOPE, listCodexOverleafSkills, listProjectSkills } = require('./localSkills');
     if (request.params?.scope === CODEX_OVERLEAF_SKILL_SCOPE) {
+      // Install/restore official skills before listing so newly shipped ones
+      // (e.g. parallel-subagents) appear in the Skills UI right after a
+      // runtime update instead of only after the next codex run (v1.6.1).
+      try {
+        require('./codexHome').ensureDefaultCodexOverleafSkills({ env });
+      } catch (_error) { /* listing still proceeds */ }
       return okResponse(request.id, listCodexOverleafSkills({ env }));
     }
     return okResponse(request.id, listProjectSkills({

package/package.json

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