@yemi33/minions 0.1.2371 → 0.1.2373

package/dashboard/js/settings.js

@@ -1132,6 +1132,7 @@ async function saveSettings() {
       liveCheckoutAutoStash: !!document.getElementById('set-liveCheckoutAutoStash')?.checked,
       liveCheckoutAutoReset: !!document.getElementById('set-liveCheckoutAutoReset')?.checked,
       liveCheckoutAutoBaseRepair: !!document.getElementById('set-liveCheckoutAutoBaseRepair')?.checked,
+      liveCheckoutAutoFreshen: !!document.getElementById('set-liveCheckoutAutoFreshen')?.checked,
       orphanHolderScanTimeoutMs: document.getElementById('set-orphanHolderScanTimeoutMs')?.value,
       statusProbeKillTimeoutMs: document.getElementById('set-statusProbeKillTimeoutMs')?.value,
       adoPollEnabled: document.getElementById('set-adoPollEnabled').checked,

package/dashboard.js

@@ -7854,23 +7854,35 @@ const server = http.createServer(async (req, res) => {
       return jsonReply(res, 200, _plansCache);
     }
     const fsp = fs.promises;
-    const dirs = [
-      { dir: PLANS_DIR, archived: false },
-      { dir: path.join(PLANS_DIR, 'archive'), archived: true },
-      { dir: PRD_DIR, archived: false },
-      { dir: path.join(PRD_DIR, 'archive'), archived: true },
-    ];
-    // Load central work items from the SQL-backed store to check for completed
-    // plan-to-prd conversions.
-    const centralWi = require('./engine/work-items-store').readWorkItemsForScope('central');
+    // W-mrffmjaf002f08f0 — PRD JSON is SQL-authoritative (engine/prd-store.js);
+    // no PRD JSON file is guaranteed to exist on disk post SQL-only cutover
+    // (migration 018), so PRD plan cards AND conversion state are read from
+    // prdStore.listPrdRows() below, not fs.readdir(PRD_DIR). This is also what
+    // fixes the underlying bug: a completed SQL PRD's source_plan must mark
+    // its Markdown draft "converted" even once the plan-to-prd work item that
+    // produced it has aged out of central work-item retention.
+    const prdRows = prdStore.listPrdRows();
     const completedPrdFiles = new Set(
-      centralWi.filter(w => w.type === WORK_TYPE.PLAN_TO_PRD && DONE_STATUSES.has(w.status) && w.planFile)
-        .map(w => w.planFile)
+      prdRows.filter(r => r.plan && r.plan.source_plan).map(r => r.plan.source_plan)
     );
+    // Defense-in-depth union with the legacy central-WI signal, in case a
+    // conversion work item completed but its PRD row somehow lacks
+    // source_plan; SQL PRD rows above remain the primary, canonical source.
+    const centralWi = require('./engine/work-items-store').readWorkItemsForScope('central');
+    for (const w of centralWi) {
+      if (w.type === WORK_TYPE.PLAN_TO_PRD && DONE_STATUSES.has(w.status) && w.planFile) {
+        completedPrdFiles.add(w.planFile);
+      }
+    }
+
     const plans = [];
-    for (const { dir, archived } of dirs) {
-      const allFiles = (await fsp.readdir(dir).catch(() => []))
-        .filter(f => f.endsWith('.json') || f.endsWith('.md'));
+
+    // --- Markdown source plans (plans/*.md + plans/archive/*.md, file-backed) ---
+    for (const { dir, archived } of [
+      { dir: PLANS_DIR, archived: false },
+      { dir: path.join(PLANS_DIR, 'archive'), archived: true },
+    ]) {
+      const allFiles = (await fsp.readdir(dir).catch(() => [])).filter(f => f.endsWith('.md'));
       const dirResults = await Promise.all(allFiles.map(async f => {
         const filePath = path.join(dir, f);
         const [content, stat] = await Promise.all([
@@ -7878,107 +7890,110 @@ const server = http.createServer(async (req, res) => {
           fsp.stat(filePath).catch(() => null),
         ]);
         const updatedAt = stat ? new Date(stat.mtimeMs).toISOString() : '';
-        const isJson = f.endsWith('.json');
-        if (isJson) {
-          try {
-            const plan = JSON.parse(content);
-            const status = plan.status || (plan.requires_approval && !plan.approvedAt ? 'awaiting-approval' : 'active');
-            // W-mqacrzis0003df4a Bug 2 — fresh staleness from plans/*.md mtime.
-            // plan.planStale lags by an engine tick; stat the source plan here
-            // so the Plans tab does not silently mirror a stale-but-cached false.
-            let freshStale = false;
-            if (!archived && plan.source_plan) {
-              try {
-                const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
-                const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
-                if (recorded && sourceMtime > recorded) freshStale = true;
-              } catch { /* source plan may have been deleted/renamed */ }
-            }
-            // P-e8d49105 — _projects rollup feeds the plan-card multi-badge
-            // path in dashboard/js/render-plans.js. For PRD JSONs, walk
-            // missing_features[].project (order-preserving dedup) and fall
-            // back to plan.project for items that omit it. Single-project
-            // plans collapse to a single-element array, identical to today's
-            // single `p.project` badge.
-            const _projects = [];
-            const _seen = new Set();
-            for (const it of (plan.missing_features || [])) {
-              const proj = (it && it.project) || plan.project || '';
-              if (proj && !_seen.has(proj)) { _seen.add(proj); _projects.push(proj); }
-            }
-            if (_projects.length === 0 && plan.project) _projects.push(plan.project);
-            // P-66b1faec — _perProjectProgress feeds the per-project status
-            // pills in the plan card meta line (dashboard/js/render-plans.js
-            // renderPlanCard). Group missing_features by item.project (with
-            // fallback to plan.project) and count `status === 'done'` per
-            // bucket. Keys are first-seen order so the rendered pill row is
-            // stable. Always emitted on PRD JSON records (possibly empty);
-            // MD drafts omit it since they carry no item-level statuses.
-            const _perProjectProgress = {};
-            for (const it of (plan.missing_features || [])) {
-              const proj = (it && it.project) || plan.project || '';
-              if (!proj) continue;
-              if (!_perProjectProgress[proj]) _perProjectProgress[proj] = { complete: 0, total: 0 };
-              _perProjectProgress[proj].total += 1;
-              if (it && it.status === 'done') _perProjectProgress[proj].complete += 1;
-            }
-            return {
-              file: f, format: 'prd', archived,
-              project: plan.project || '',
-              _projects,
-              _perProjectProgress,
-              summary: plan.plan_summary || '',
-              status,
-              branchStrategy: plan.branch_strategy || 'parallel',
-              featureBranch: plan.feature_branch || '',
-              itemCount: (plan.missing_features || []).length,
-              generatedBy: plan.generated_by || '',
-              generatedAt: plan.generated_at || '',
-              completedAt: plan.completedAt || '',
-              updatedAt,
-              requiresApproval: plan.requires_approval || false,
-              revisionFeedback: plan.revision_feedback || null,
-              sourcePlan: plan.source_plan || null,
-              archiveReady: plan._archiveReady || false,
-              archiveReadyAt: plan._archiveReadyAt || null,
-              planStale: freshStale || plan.planStale || false,
-            };
-          } catch { return null; /* JSON parse fallback */ }
-        } else {
-          const titleMatch = content.match(/^#\s+(?:Plan:\s*)?(.+)/m);
-          const projectMatch = content.match(/\*\*Project:\*\*\s*(.+)/m);
-          const authorMatch = content.match(/\*\*Author:\*\*\s*(.+)/m);
-          const dateMatch = content.match(/\*\*Date:\*\*\s*(.+)/m);
-          const versionMatch = f.match(/-v(\d+)/);
-          // P-e8d49105 — for MD drafts, the cross-repo marker / **Projects:**
-          // line is the source of truth (parsed by shared.extractPlanTargetProjects).
-          // If neither is present, fall back to the singular **Project:** header
-          // so single-project drafts render the same badge as today.
-          const declaredProject = projectMatch ? projectMatch[1].trim() : '';
-          const targetProjects = shared.extractPlanTargetProjects(content);
-          const _projects = targetProjects.length > 0
-            ? targetProjects
-            : (declaredProject ? [declaredProject] : []);
-          return {
-            file: f, format: 'draft', archived,
-            project: declaredProject,
-            _projects,
-            summary: titleMatch ? titleMatch[1].trim() : f.replace('.md', ''),
-            status: archived ? 'completed' : completedPrdFiles.has(f) ? 'converted' : 'draft',
-            branchStrategy: '',
-            featureBranch: '',
-            itemCount: (content.match(/^\d+\.\s+\*\*/gm) || []).length,
-            generatedBy: authorMatch ? authorMatch[1].trim() : '',
-            generatedAt: dateMatch ? dateMatch[1].trim() : '',
-            updatedAt,
-            requiresApproval: false,
-            revisionFeedback: null,
-            version: versionMatch ? parseInt(versionMatch[1]) : null,
-          };
-        }
+        const titleMatch = content.match(/^#\s+(?:Plan:\s*)?(.+)/m);
+        const projectMatch = content.match(/\*\*Project:\*\*\s*(.+)/m);
+        const authorMatch = content.match(/\*\*Author:\*\*\s*(.+)/m);
+        const dateMatch = content.match(/\*\*Date:\*\*\s*(.+)/m);
+        const versionMatch = f.match(/-v(\d+)/);
+        // P-e8d49105 — for MD drafts, the cross-repo marker / **Projects:**
+        // line is the source of truth (parsed by shared.extractPlanTargetProjects).
+        // If neither is present, fall back to the singular **Project:** header
+        // so single-project drafts render the same badge as today.
+        const declaredProject = projectMatch ? projectMatch[1].trim() : '';
+        const targetProjects = shared.extractPlanTargetProjects(content);
+        const _projects = targetProjects.length > 0
+          ? targetProjects
+          : (declaredProject ? [declaredProject] : []);
+        return {
+          file: f, format: 'draft', archived,
+          project: declaredProject,
+          _projects,
+          summary: titleMatch ? titleMatch[1].trim() : f.replace('.md', ''),
+          status: archived ? 'completed' : completedPrdFiles.has(f) ? 'converted' : 'draft',
+          branchStrategy: '',
+          featureBranch: '',
+          itemCount: (content.match(/^\d+\.\s+\*\*/gm) || []).length,
+          generatedBy: authorMatch ? authorMatch[1].trim() : '',
+          generatedAt: dateMatch ? dateMatch[1].trim() : '',
+          updatedAt,
+          requiresApproval: false,
+          revisionFeedback: null,
+          version: versionMatch ? parseInt(versionMatch[1]) : null,
+        };
       }));
       for (const r of dirResults) if (r) plans.push(r);
     }
+
+    // --- PRD JSON records (prd/*.json + prd/archive/*.json, SQL-backed) ---
+    for (const row of prdRows) {
+      const plan = row.plan;
+      if (!plan || typeof plan !== 'object') continue;
+      const archived = !!row.archived;
+      const f = row.filename;
+      const updatedAt = row.updatedAt ? new Date(row.updatedAt).toISOString() : '';
+      const status = plan.status || (plan.requires_approval && !plan.approvedAt ? 'awaiting-approval' : 'active');
+      // W-mqacrzis0003df4a Bug 2 — fresh staleness from plans/*.md mtime.
+      // plan.planStale lags by an engine tick; stat the source plan here
+      // so the Plans tab does not silently mirror a stale-but-cached false.
+      let freshStale = false;
+      if (!archived && plan.source_plan) {
+        try {
+          const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
+          const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
+          if (recorded && sourceMtime > recorded) freshStale = true;
+        } catch { /* source plan may have been deleted/renamed */ }
+      }
+      // P-e8d49105 — _projects rollup feeds the plan-card multi-badge
+      // path in dashboard/js/render-plans.js. For PRD JSONs, walk
+      // missing_features[].project (order-preserving dedup) and fall
+      // back to plan.project for items that omit it. Single-project
+      // plans collapse to a single-element array, identical to today's
+      // single `p.project` badge.
+      const _projects = [];
+      const _seen = new Set();
+      for (const it of (plan.missing_features || [])) {
+        const proj = (it && it.project) || plan.project || '';
+        if (proj && !_seen.has(proj)) { _seen.add(proj); _projects.push(proj); }
+      }
+      if (_projects.length === 0 && plan.project) _projects.push(plan.project);
+      // P-66b1faec — _perProjectProgress feeds the per-project status
+      // pills in the plan card meta line (dashboard/js/render-plans.js
+      // renderPlanCard). Group missing_features by item.project (with
+      // fallback to plan.project) and count `status === 'done'` per
+      // bucket. Keys are first-seen order so the rendered pill row is
+      // stable. Always emitted on PRD JSON records (possibly empty);
+      // MD drafts omit it since they carry no item-level statuses.
+      const _perProjectProgress = {};
+      for (const it of (plan.missing_features || [])) {
+        const proj = (it && it.project) || plan.project || '';
+        if (!proj) continue;
+        if (!_perProjectProgress[proj]) _perProjectProgress[proj] = { complete: 0, total: 0 };
+        _perProjectProgress[proj].total += 1;
+        if (it && it.status === 'done') _perProjectProgress[proj].complete += 1;
+      }
+      plans.push({
+        file: f, format: 'prd', archived,
+        project: plan.project || '',
+        _projects,
+        _perProjectProgress,
+        summary: plan.plan_summary || '',
+        status,
+        branchStrategy: plan.branch_strategy || 'parallel',
+        featureBranch: plan.feature_branch || '',
+        itemCount: (plan.missing_features || []).length,
+        generatedBy: plan.generated_by || '',
+        generatedAt: plan.generated_at || '',
+        completedAt: plan.completedAt || '',
+        updatedAt,
+        requiresApproval: plan.requires_approval || false,
+        revisionFeedback: plan.revision_feedback || null,
+        sourcePlan: plan.source_plan || null,
+        archiveReady: plan._archiveReady || false,
+        archiveReadyAt: plan._archiveReadyAt || null,
+        planStale: freshStale || plan.planStale || false,
+      });
+    }
+
     plans.sort((a, b) => (b.generatedAt || '').localeCompare(a.generatedAt || ''));
     _plansCache = plans;
     _plansCacheTs = Date.now();

package/docs/live-checkout-mode.md

@@ -153,6 +153,33 @@ A count `> 0` returns `{ ok:false, reason:'stale-main', mainRef, ahead, localMai
 
 `spawnAgent` completes the dispatch non-retryably with the dedicated **`FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE`** (`'live-checkout-stale-base'`; in `dispatch.js`'s `neverRetry` set) plus a `live-checkout-stale-base-<wi-id>` inbox alert and a `_pendingReason: 'live_checkout_stale_base'` stamp — instead of `LIVE_CHECKOUT_FAILED` (retryable) retry-storming an identical structural failure to `maxRetries`. The engine **never** resets, cleans, or rebases the operator's local `mainRef` — surfacing it as a refusal keeps history rewrites in the operator's hands, consistent with the dirty and mid-operation refusals. The alert's recovery guidance offers two paths: salvage the extra commits onto their own branch then `git reset --hard origin/<mainRef>`, or discard them with the same reset — either leaves `mainRef` matching `origin/<mainRef>` so the next dispatch forks off a clean base.
 
+#### 6b. Opt-in auto-freshen (`liveCheckoutAutoFreshen`, W-mrdlcud2000e630e)
+
+The STALE-BASE GUARD (§6) only counts the **local-ahead** side: local `mainRef` merely being **behind** `origin/<mainRef>` (ahead == 0, behind > 0) is silently allowed to fork off a stale-but-safe base. Issue #226 is the reason the engine never auto-fetches live checkouts — preserving operator control over history rewrites. **Auto-freshen** is the narrow, opt-in exception that lets a live (or hybrid liveValidation) dispatch work off the freshest safe base without ever risking a history rewrite or data loss.
+
+Enabling **`liveCheckoutAutoFreshen`** (per-project `project.liveCheckoutAutoFreshen` > fleet-wide `engine.liveCheckoutAutoFreshen` > **`false`**, resolved by `shared.resolveLiveCheckoutAutoFreshen`) makes `prepareLiveCheckout` — **before** the STALE-BASE GUARD, as `_maybeAutoFreshenLocalMain` — fast-forward the local base when, and **only** when, **all** of these hold:
+
+- the tree is **clean** (the Guarantee 2 dirty-tree bail already ran — auto-freshen is never attempted on a dirty tree, and the mid-operation preflight of Guarantee 5 has already refused any in-progress op);
+- HEAD is on `mainRef` (the branch it is about to fork off);
+- this is **not** an `allowNonMainBase` dispatch (PR-targeted fixes / shared-branch continuations are exempt — same skip condition as §6/§7);
+- local `mainRef` has **ZERO** commits ahead of `origin/<mainRef>` — i.e. **not** the stale-base-with-unpushed-commits case; that path stays UNTOUCHED and still hits §6's refusal;
+- local `mainRef` **is** behind `origin/<mainRef>` (behind > 0).
+
+When they hold it runs the **one sanctioned live-mode fetch** — `git fetch origin <mainRef>` — then a **fast-forward-only** update, `git merge --ff-only refs/remotes/origin/<mainRef>` (HEAD is on `mainRef`, so this advances the checked-out base). A `--ff-only` update can never rewrite history or drop local commits (there are none ahead), so the no-data-loss guarantee is preserved even though issue #226's blanket no-fetch rule is relaxed for this one case.
+
+- **Fails open.** Any fetch/network/auth failure, an uncomputable divergence, or an unexpected `--ff-only` refusal (e.g. a race committed onto local `mainRef`) returns **without mutating**, so the dispatch proceeds to the existing stale-base check exactly as if auto-freshen were off. A freshen-step hiccup never hard-fails the dispatch.
+- **Low-noise audit.** On a successful freshen it logs an `info` line and writes a `live-checkout-autofreshen-<wi-id>` inbox note recording the before/after local `mainRef` SHA — **only** when a freshen actually happened (never on every dispatch), so it does not alert-spam.
+- **Uniform across live and hybrid.** Hybrid mode reuses the same live-checkout preflight for its `liveValidation` dispatch path, so the flag applies to both without extra wiring.
+- **Scope-narrow.** The ahead>0 STALE-BASE GUARD refusal is deliberately **unchanged**; auto-freshen only adds a safe fast-forward for the ahead==0/behind>0 case. Default **OFF** — a human opts individual projects in.
+
+Enable it fleet-wide via **Settings → "Live-checkout auto-freshen (fleet-wide)"**, or in `config.json`:
+
+```jsonc
+{ "engine": { "liveCheckoutAutoFreshen": true } }        // fleet-wide
+// or per-project (wins over fleet-wide):
+{ "projects": [ { "name": "office", "checkoutMode": "live", "liveCheckoutAutoFreshen": true } ] }
+```
+
 
 ### 7. Refuse on stale non-main base when forking a new branch (W-mr3lunnq000o9f41)
 

package/docs/runtime-adapters.md

@@ -82,10 +82,113 @@ real behavioral split appears between adapters.
 | `resumeBookkeepingTurn` | ✓ | — | — | Claude CLI injects a synthetic "Continue from where you left off." meta turn on `--resume`; CC prompts must tell the model not to treat it as user intent. |
 | `streamConsumer` | ✓ | ✓ | ✓ | Adapter implements `createStreamConsumer(ctx)` — required by `engine/llm.js` accumulator. |
 | `imageInput` | ✓ | ✓ | ✗ | Runtime accepts `images: [{mimeType, dataBase64}]` and delivers them to the CLI. Claude: Anthropic Messages base64 content-block envelope via `--input-format stream-json`. Copilot: base64 payloads materialized to tmp files and passed as `--attachment <path>` (W-mqv7324u0021db5d). When false, `_resolveImageOpts` returns a typed `model-unavailable` error. |
+| `acpWorkerPool` | ✗ | ✓ | ✗ | Runtime supports `<bin> --acp` (Agent Client Protocol), so it can be routed through a persistent worker pool instead of cold-spawning a fresh CLI process per turn/dispatch. Two independent consumers gate on this flag: `engine/cc-worker-pool.js` (CC/doc-chat tabs, `resolveCcUseWorkerPool`) and `engine/agent-worker-pool.js` (fleet agent dispatch, `resolveAgentUseWorkerPool`). Both resolvers hard-return `false` whenever this flag isn't `true` on the resolved runtime, regardless of any operator override, so a future non-ACP runtime can never be silently pooled. See [ACP Worker Pool](#acp-worker-pool-fleet-agent-dispatch) below. |
 
 When a behavior is genuinely uniform across all current adapters, it still gets
 a flag if a future runtime might disagree — flags are cheap.
 
+## ACP Worker Pool (Fleet Agent Dispatch)
+
+Copilot's `acpWorkerPool` capability backs **two** independent opt-in pools that
+avoid cold-spawning a fresh `copilot` CLI process for every turn/dispatch. Both
+share the same spawn + JSON-RPC transport (`engine/acp-transport.js`) but have
+different ownership models:
+
+| Pool | Module | Ownership model | Config | Default |
+|------|--------|------------------|--------|---------|
+| CC / doc-chat | `engine/cc-worker-pool.js` | 1 worker permanently owned per CC tab, kept warm for the tab's lifetime | `engine.ccUseWorkerPool` | `true` (Copilot CC) — see [docs/command-center.md](./command-center.md) |
+| Fleet agent dispatch | `engine/agent-worker-pool.js` | 1 worker leased to exactly one **active** dispatch at a time, returned to a shared free set on release — not owned for the dispatch's whole life | `engine.agentUseWorkerPool` + `engine.agentAcpPoolSize` | `false` (opt-in) |
+
+This section covers the fleet agent pool (P-9b3d5f61 / P-1d8f0b93 / P-4c6e8a72).
+
+### Config keys
+
+| Key | Resolver | Chain | Default |
+|-----|----------|-------|---------|
+| `engine.agentUseWorkerPool` | `shared.resolveAgentUseWorkerPool(engine, runtime)` | 1. Hard `false` unless `runtime.capabilities.acpWorkerPool === true` (Copilot only). 2. `engine.agentUseWorkerPool` explicit `true`/`false` override. 3. `ENGINE_DEFAULTS.agentUseWorkerPool`. | `false` |
+| `engine.agentAcpPoolSize` | `shared.resolveAgentAcpPoolSize(engine)` | 1. `engine.agentAcpPoolSize` (positive number, else ignored). 2. `engine.maxConcurrent` (fleet dispatch concurrency cap). 3. `ENGINE_DEFAULTS.maxConcurrent`. | `ENGINE_DEFAULTS.maxConcurrent` (currently `5`) |
+
+`agentUseWorkerPool` is deliberately **opt-in** (`false` by default), unlike
+`ccUseWorkerPool`'s default-`true` — the fleet dispatch path has a much larger
+MCP-auth-popup / isolation surface than the single CC singleton, so it stays
+off until proven safe in a given operator's environment. `agentAcpPoolSize`
+defaults to the same cap the engine would already use for cold-spawn
+concurrency (`maxConcurrent`), so enabling the pool never queues more
+concurrent dispatches than the fleet would have run anyway — it only changes
+*how* those dispatches get a CLI process, not how many run at once.
+
+### How dispatches route through the pool
+
+When `resolveAgentUseWorkerPool` resolves `true`, `engine.js#spawnAgent` skips
+`node engine/spawn-agent.js` and instead calls `engine/agent-worker-pool.js#acquireWorker`,
+wrapping the lease in `engine/pooled-agent-process.js#PooledAgentProcess` — a
+child_process-shaped facade (`.pid`, `.stdout`/`.stderr`, `.kill()`,
+`'close'`/`'error'`) so the rest of `spawnAgent`'s downstream code (stdout/stderr
+handlers, PID-file writing, live-output.log, timeout/steering cancel-vs-kill,
+restart-reattach) runs unmodified regardless of whether `proc` is a real OS
+process or a pooled lease. Assignment strategy, in order:
+
+1. A **free** worker whose MCP-server set already matches wins first — reused
+   via a fresh `session/new`, no respawn.
+2. Otherwise another free worker is **evicted** (closed) and a replacement is
+   spawned fresh with the requested MCP servers/cwd (MCP servers are resolved
+   at `copilot --acp` process boot, so a changed server set requires a full
+   respawn, not just a new session).
+3. Otherwise, if the pool has room (fewer than `agentAcpPoolSize` workers
+   allocated across free + busy + in-flight-spawn), a brand-new worker spawns.
+4. Otherwise the request queues FIFO until a `release()` or worker crash frees
+   a slot.
+
+Dispatch records persist `item.pooled = true` on disk (`dispatch.json`), not
+just the in-memory `activeProcesses._pooled` flag (which is wiped on engine
+restart) — the on-disk flag is what tells the restart-reattach path
+(`engine/cli.js`) that a live worker PID is a pooled lease, not a resumable
+cold-spawned child process.
+
+### Isolation tradeoff — read this before enabling `agentUseWorkerPool`
+
+**Enabling the pool bounds the MCP-auth-popup / cross-dispatch isolation risk
+by pool size — it does not eliminate it.** Cold-spawn gives every dispatch its
+own fresh OS process and its own `COPILOT_HOME`; the pool instead keeps up to
+`agentAcpPoolSize` `copilot --acp` processes warm and reuses them across
+dispatches whenever the MCP-server set matches. Concretely:
+
+- A worker process — and anything an MCP server inside it authenticated,
+  cached, or leaked into process memory during a prior dispatch — can be
+  handed to a **different** dispatch/work item next, as long as the MCP-server
+  set is unchanged. There is no per-dispatch process boundary the way
+  cold-spawn provides.
+- The blast radius of a compromised or misbehaving MCP server is capped at
+  `agentAcpPoolSize` concurrently-warm workers, not the whole fleet — but it is
+  **not zero**. A larger pool size widens the number of dispatches that could
+  share exposure to the same warm worker over its lifetime; a smaller pool
+  size narrows it at the cost of more evictions/respawns (and therefore more
+  MCP-auth prompts) when the requested MCP-server set changes between
+  dispatches.
+- This mirrors the same tradeoff `engine.ccUseWorkerPool` already accepts for
+  CC tabs (see [docs/command-center.md](./command-center.md)), which is why
+  `agentUseWorkerPool` defaults `false`: the fleet dispatch surface has more,
+  and more varied, work items than a single CC session, so the exposure window
+  per warm worker is larger and the default stays conservative until an
+  operator has evaluated the tradeoff for their own MCP-server set.
+
+Operators enabling `engine.agentUseWorkerPool` should choose `agentAcpPoolSize`
+deliberately: a pool size of `1` gives the strongest isolation (still weaker
+than cold-spawn, since consecutive dispatches on that single worker still
+share process state) at the cost of maximum serialization/respawns; a larger
+pool size trades some isolation for parallelism and fewer respawns.
+
+### See Also (ACP pool)
+
+- `engine/agent-worker-pool.js` — pool mechanics, assignment strategy, JSDoc header.
+- `engine/pooled-agent-process.js` — the child_process-shaped facade and its
+  documented output-translation scope limits (no tool-call/model-announcement
+  event synthesis — a deliberate parity gap, not an oversight).
+- `test/unit/agent-worker-pool.test.js`, `test/integration/agent-pool-dispatch.test.js`,
+  `test/unit/pooled-cold-parity-matrix.test.js`, `test/unit/pooled-cancel-vs-kill.test.js`,
+  `test/unit/pooled-dispatch-restart-reattach.test.js` — pool mechanics, end-to-end
+  flow, cold/pooled parity matrix, cancel-vs-kill, and restart-reattach coverage.
+
 ## CC vs Agent Runtime Independence
 
 Command Center (CC) / doc-chat and the agent fleet are two **independent**