@yemi33/minions 0.1.2372 → 0.1.2374

package/engine/pooled-agent-process.js

@@ -0,0 +1,158 @@
+/**
+ * engine/pooled-agent-process.js — child_process-shaped facade over a leased
+ * engine/agent-worker-pool.js worker (P-1d8f0b93).
+ *
+ * engine.js#spawnAgent's downstream code (stdout/stderr `.on('data', ...)`
+ * handlers, the `onAgentClose` completion listener, PID-file/timeout
+ * bookkeeping, restart-reattach) is written entirely against the Node
+ * ChildProcess contract. Per the plan's explicit constraint ("do not fork
+ * spawnAgent into separate end-to-end completion implementations"),
+ * PooledAgentProcess wraps an agent-worker-pool.js lease behind that SAME
+ * shape — `.pid`, `.stdout`/`.stderr` (readable streams), `.kill()`,
+ * `.killed`, `.exitCode`, and `'close'`/`'error'` events — so spawnAgent's
+ * existing listener code (stdout/stderr capture, live-output.log writing,
+ * session-id capture, steering, trust-gate detection, archival) runs
+ * completely unmodified whether `proc` is a real child_process or a pooled
+ * ACP lease.
+ *
+ * Output translation (parity, not full fidelity): ACP `session/update` text
+ * chunks are re-encoded as the SAME Copilot JSONL event shape
+ * `engine/runtimes/copilot.js#parseOutput` already parses from a real
+ * `copilot` CLI stdout stream — `{"type":"assistant.message_delta","data":
+ * {"deltaContent":"..."}}` per chunk, plus a terminal `{"type":"result",
+ * "sessionId":...,"usage":{...}}` line once the turn completes. This is the
+ * minimum subset `parseOutput` needs to recover an equivalent `{text,
+ * sessionId, usage}` to the cold-spawn path (deltas alone populate its
+ * `pendingDeltaContent` accumulator; no `assistant.message`/`session.
+ * tools_updated`/`tool.execution_*` events are required for that recovery).
+ * Tool-call and model-announcement events are intentionally NOT synthesized
+ * — a deliberate, documented scope limit, not an oversight: the live-output
+ * log still gets the real text in real time either way, and `usage`'s
+ * cost/token fields are already null-for-copilot on the cold path (see
+ * `runtimes/copilot.js#parseOutput`), so nothing measurable is lost.
+ */
+
+const { EventEmitter } = require('events');
+const { PassThrough } = require('stream');
+
+class PooledAgentProcess extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {object} opts.pool - engine/agent-worker-pool.js module (or a test double)
+   * @param {string} opts.dispatchId
+   * @param {string} opts.cwd
+   * @param {string} [opts.model]
+   * @param {string} [opts.effort]
+   * @param {Array} [opts.mcpServers]
+   * @param {Array<string>} [opts.hermeticDirs]
+   * @param {string} opts.promptText - fully-built prompt (runtime.buildPrompt output)
+   */
+  constructor({ pool, dispatchId, cwd, model, effort, mcpServers, hermeticDirs, promptText }) {
+    super();
+    this.pid = null;
+    this.killed = false;
+    this.exitCode = null;
+    this.stdout = new PassThrough();
+    this.stderr = new PassThrough();
+    this._pool = pool;
+    this._dispatchId = dispatchId;
+    this._handle = null;
+    this._closed = false;
+    this._startedAt = Date.now();
+
+    // Fire-and-forget, mirroring child_process.spawn()'s async nature — the
+    // facade is usable (event listeners can be attached) immediately, before
+    // the underlying ACP worker has actually been acquired.
+    this._start({ cwd, model, effort, mcpServers, hermeticDirs, promptText });
+  }
+
+  async _start({ cwd, model, effort, mcpServers, hermeticDirs, promptText }) {
+    let handle;
+    try {
+      handle = await this._pool.acquireWorker({
+        dispatchId: this._dispatchId, cwd, model, effort, mcpServers, hermeticDirs,
+      });
+    } catch (err) {
+      // Mirrors child_process's 'error' event (spawn failed) — engine.js's
+      // existing `proc.on('error', ...)` handler already does the right
+      // thing (completeDispatch ERROR + cleanup) unmodified.
+      this.emit('error', err);
+      return;
+    }
+
+    if (this.killed) {
+      // kill() landed while acquisition was still in flight. No OS process
+      // was ever visible to anything downstream — just return the worker.
+      try { handle.release(); } catch { /* best-effort */ }
+      return;
+    }
+
+    this._handle = handle;
+    this.pid = typeof handle.pid === 'number' ? handle.pid : null;
+    // Lets engine.js write the PID-file equivalent (spawn-agent.js normally
+    // does this itself, from inside the child process) as soon as a real OS
+    // PID is known — see engine.js's pooled branch in spawnAgent().
+    this.emit('acquired');
+
+    let sawError = false;
+    await handle.stream(promptText, {
+      onChunk: (text) => {
+        if (!text) return;
+        this._writeStdoutEvent({ type: 'assistant.message_delta', data: { deltaContent: text } });
+      },
+      onDone: (result) => {
+        this._writeStdoutEvent({
+          type: 'result',
+          sessionId: handle.sessionId || null,
+          usage: {
+            totalApiDurationMs: Date.now() - this._startedAt,
+            stopReason: (result && result.stopReason) || null,
+          },
+        });
+      },
+      onError: (err) => {
+        sawError = true;
+        try { this.stderr.write(String((err && err.message) || err) + '\n'); } catch { /* best-effort */ }
+      },
+    });
+
+    try { handle.release(); } catch { /* best-effort */ }
+    this._finish(sawError ? 1 : 0);
+  }
+
+  _writeStdoutEvent(obj) {
+    try { this.stdout.write(JSON.stringify(obj) + '\n'); } catch { /* best-effort */ }
+  }
+
+  _finish(code) {
+    if (this._closed) return;
+    this._closed = true;
+    this.exitCode = code;
+    try { this.stdout.end(); } catch { /* best-effort */ }
+    try { this.stderr.end(); } catch { /* best-effort */ }
+    this.emit('close', code);
+  }
+
+  // child_process.kill()-shaped primitive. Cancels the in-flight ACP turn
+  // (if any) and releases the worker back to the pool rather than killing
+  // the shared OS process — killing it would collaterally affect whatever
+  // OTHER dispatch reuses that worker next (never a concurrent sibling, per
+  // the pool's 1-worker:1-active-dispatch invariant, but still a real
+  // process other queued dispatches may be waiting to reuse).
+  // Full timeout/steering-kill cancel-vs-kill wiring in engine/timeout.js is
+  // P-6e2a4c15 — this method is the primitive that work item calls into.
+  kill() {
+    if (this.killed) return true;
+    this.killed = true;
+    if (this._handle) {
+      try { this._handle.cancel(); } catch { /* best-effort */ }
+      try { this._handle.release(); } catch { /* best-effort */ }
+      this._finish(this.exitCode == null ? 143 : this.exitCode);
+    }
+    // If acquisition is still in flight, `_start` observes `this.killed` and
+    // releases the worker itself as soon as it lands — nothing more to do.
+    return true;
+  }
+}
+
+module.exports = { PooledAgentProcess };

package/engine/runtimes/copilot.js

@@ -1285,6 +1285,11 @@ const capabilities = {
   // `--attachment <path>` works in non-interactive mode (live-tested; see W-mqv7324u0021db5d).
   // Base64 payloads are materialized to tmp files inside llmTmpDir before spawn.
   imageInput: true,
+  // P-9b3d5f61: `copilot --acp` speaks the Agent Client Protocol, so per-agent
+  // dispatches can route through a persistent ACP worker pool
+  // (engine/agent-worker-pool.js) instead of cold-spawning per dispatch.
+  // Claude/Codex do not implement ACP — this flag is absent (falsy) there.
+  acpWorkerPool: true,
 };
 
 // Install hint surfaced when `resolveBinary()` returns null. Covers all

package/engine/shared.js

@@ -2945,6 +2945,26 @@ function resolveLiveCheckoutAutoBaseRepair(project, engine) {
   return false;
 }
 
+// W-mrdlcud2000e630e (companion to the stale-base guard) — resolve the
+// live-checkout auto-freshen decision. Per-project `liveCheckoutAutoFreshen`
+// wins, else fleet-wide `engine.liveCheckoutAutoFreshen`, else false (opt-in).
+// When ON, prepareLiveCheckout — BEFORE the stale-base guard, and ONLY when the
+// tree is clean, HEAD is on mainRef, and the local mainRef has ZERO commits
+// ahead of origin/<mainRef> but IS behind it — runs `git fetch origin <mainRef>`
+// + a fast-forward-only update of the local mainRef so the new branch forks off
+// the freshest safe base. This is the ONLY live-mode path that fetches/mutates
+// local mainRef; the ahead>0 stale-base refusal is untouched, and a fetch
+// failure fails open to the pre-existing (un-freshened) behavior. Default OFF.
+function resolveLiveCheckoutAutoFreshen(project, engine) {
+  if (project && typeof project === 'object' && typeof project.liveCheckoutAutoFreshen === 'boolean') {
+    return project.liveCheckoutAutoFreshen;
+  }
+  if (engine && typeof engine === 'object' && typeof engine.liveCheckoutAutoFreshen === 'boolean') {
+    return engine.liveCheckoutAutoFreshen;
+  }
+  return false;
+}
+
 function validateCheckoutMode(value) {
   if (value === undefined || value === null || value === '') return undefined;
   if (typeof value !== 'string') {
@@ -3466,6 +3486,7 @@ const ENGINE_DEFAULTS = {
   copilotStreamMode: 'on',           // Copilot --stream <on|off>: 'on' streams assistant.message_delta events live; 'off' batches them
   copilotReasoningSummaries: false,  // Copilot --enable-reasoning-summaries (Anthropic-family models only)
   ccUseWorkerPool: false,            // Sub-task C of W-mp2w003600196c51 (CC perf): when true AND CC runtime is copilot, _invokeCcStream routes through engine/cc-worker-pool.js (persistent `copilot --acp` per CC tab) instead of spawning a fresh CLI per turn. Off by default — opt-in feature flag. **Structurally copilot-only**: the pool spawns `copilot --acp` (Agent Client Protocol); Claude Code does not implement ACP, so resolveCcUseWorkerPool returns false on non-copilot CC runtimes even with explicit-true (W-mphlriic00095f69 — prevents silent runtime switch). Engine/agent dispatch path stays per-process regardless.
+  agentUseWorkerPool: false,         // P-9b3d5f61: mirrors ccUseWorkerPool's shape but for the fleet agent-dispatch path (engine/agent-worker-pool.js). Opt-in, default OFF — see resolveAgentUseWorkerPool in engine/shared.js for the full priority chain and rationale.
   // PR #321 — "kill auth-popup storm". Copilot spawns and authenticates EVERY
   // MCP server in `$COPILOT_HOME/mcp-config.json` on every process start, even
   // when the corresponding tool is hidden from the model via
@@ -3845,6 +3866,58 @@ function resolveCcUseWorkerPool(engine) {
   return true; // CC runtime is copilot — default ON (cold-start savings)
 }
 
+/**
+ * P-9b3d5f61 — Resolve whether a per-agent spawn should route through the
+ * persistent ACP worker pool (engine/agent-worker-pool.js). Mirrors
+ * resolveCcUseWorkerPool's shape but takes the already-resolved runtime
+ * adapter (as returned by `resolveRuntime(resolveAgentCli(agent, engine))`)
+ * rather than re-deriving it, since callers on the agent-spawn path already
+ * have it in hand. Priority:
+ *   1. Capability guard — pool transport is ACP-only (`copilot --acp`). Hard
+ *      false whenever `runtime.capabilities.acpWorkerPool` isn't `true`,
+ *      regardless of operator override, so a future non-ACP runtime can never
+ *      be silently routed through the pool (same rationale as
+ *      resolveCcUseWorkerPool's CC-runtime guard, W-mphlriic00095f69).
+ *   2. `engine.agentUseWorkerPool` explicit true/false — operator override
+ *      wins *within* an ACP-capable runtime.
+ *   3. `ENGINE_DEFAULTS.agentUseWorkerPool` (false) — opt-in, default OFF.
+ *      Deliberately different from CC's default-true: the fleet dispatch path
+ *      has a much larger MCP-auth-popup / isolation surface than the single
+ *      CC singleton, so this stays off until proven safe.
+ */
+function resolveAgentUseWorkerPool(engine, runtime) {
+  if (!runtime || !runtime.capabilities || runtime.capabilities.acpWorkerPool !== true) return false;
+  if (engine && (engine.agentUseWorkerPool === true || engine.agentUseWorkerPool === false)) {
+    return engine.agentUseWorkerPool;
+  }
+  return ENGINE_DEFAULTS.agentUseWorkerPool;
+}
+
+/**
+ * P-9b3d5f61 — Resolve the max concurrent ACP workers the per-agent pool
+ * (engine/agent-worker-pool.js) should keep warm. Priority:
+ *   1. `engine.agentAcpPoolSize` — explicit operator override
+ *   2. `engine.maxConcurrent`    — fleet dispatch concurrency cap (so the
+ *      pool never queues more than the engine would have dispatched anyway)
+ *   3. `ENGINE_DEFAULTS.maxConcurrent` — hardcoded fallback
+ *
+ * Non-numeric or non-positive overrides are ignored and fall through to the
+ * next tier (defensive against bad Settings-UI/env input).
+ */
+function resolveAgentAcpPoolSize(engine) {
+  const explicit = engine ? engine.agentAcpPoolSize : undefined;
+  if (explicit !== undefined && explicit !== null) {
+    const n = typeof explicit === 'number' ? explicit : Number(explicit);
+    if (!Number.isNaN(n) && n > 0) return n;
+  }
+  const fleet = engine ? engine.maxConcurrent : undefined;
+  if (fleet !== undefined && fleet !== null) {
+    const n = typeof fleet === 'number' ? fleet : Number(fleet);
+    if (!Number.isNaN(n) && n > 0) return n;
+  }
+  return ENGINE_DEFAULTS.maxConcurrent;
+}
+
 /**
  * Resolve the model for a per-agent spawn. Priority:
  *   1. `agent.model`            — per-agent override
@@ -8981,7 +9054,7 @@ module.exports = {
   isEngineSystemAlert,
   ENGINE_DEFAULTS,
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
-  resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,
+  resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentUseWorkerPool, resolveAgentAcpPoolSize, resolveAgentModel, resolveCcModel,
   resolveAgentMaxBudget, resolveAgentBareMode,
   resolveCopilotAgentDisabledMcpServers,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
@@ -9120,6 +9193,7 @@ module.exports = {
   isLiveCheckoutProject,
   resolveLiveCheckoutAutoReset,
   resolveLiveCheckoutAutoBaseRepair,
+  resolveLiveCheckoutAutoFreshen,
   validatePid,
   PR_FIX_CAUSE,
   getPrFixAutomationCause,

package/engine/timeout.js

@@ -234,6 +234,31 @@ function checkDeferredStranded(activeProcesses, config) {
   }
 }
 
+// P-6e2a4c15 — cancel-vs-kill for pooled dispatches. A pooled dispatch's
+// `activeProcesses` record (`info`) carries `_pooled: true` (stamped by
+// engine.js#spawnAgent, P-1d8f0b93) and its `.proc` is a PooledAgentProcess
+// facade whose `.pid` is the SHARED, long-lived ACP worker's real OS pid —
+// not a per-dispatch child process. Every OS-level kill helper in this file
+// (`shared.killGracefully`, `shared.killImmediate`, `_escalatePlatformKill`)
+// ultimately runs `taskkill /F /T /PID <pid>` or SIGKILLs that pid's whole
+// process tree. Doing that to a pooled dispatch would kill the shared worker
+// out from under every OTHER dispatch waiting to reuse it from the pool —
+// exactly the collateral-damage risk `PooledAgentProcess#kill()` (P-1d8f0b93)
+// was built to avoid: it cancels the in-flight ACP turn and releases the
+// worker back to the pool without touching the OS process. Route every kill
+// request here through this helper so no call site can accidentally bypass
+// that primitive for a pooled record.
+function killTrackedProcess(info, { graceMs } = {}) {
+  if (!info || !info.proc) return;
+  if (info._pooled && typeof info.proc.kill === 'function') {
+    try { info.proc.kill(); }
+    catch (err) { try { log('warn', `Pooled dispatch cancel failed for ${info.agentId || '?'}: ${err.message}`); } catch {} }
+    return;
+  }
+  if (graceMs == null) shared.killImmediate(info.proc);
+  else shared.killGracefully(info.proc, graceMs);
+}
+
 // W-mq066js7000fff1f-c (Gap C): runs the kill-retry escalation ladder for an
 // already-steered process whose `_steeringAt` is set but which hasn't exited.
 // Caller is `checkSteering` per-tick loop; `info` is the `activeProcesses`
@@ -253,7 +278,7 @@ function _runSteeringKillLadder(id, info, config) {
   if (attempts < cap) {
     if (attempts === 0) {
       log('warn', `Steering: ${info.agentId} (${id}) didn't exit ${Math.round(wait / 1000)}s after kill — retrying gracefully`);
-      try { shared.killGracefully(info.proc, 5000); }
+      try { killTrackedProcess(info, { graceMs: 5000 }); }
       catch (err) { try { log('warn', `Steering kill retry (graceful) failed for ${info.agentId}: ${err.message}`); } catch {} }
     } else {
       log('warn', `Steering: ${info.agentId} (${id}) survived attempt ${attempts} — escalating (attempt ${attempts + 1}/${cap})`);
@@ -287,6 +312,13 @@ function _runSteeringKillLadder(id, info, config) {
 }
 
 function _escalatePlatformKill(info) {
+  // Pooled dispatches never reach the OS-level escalation path — cancel the
+  // ACP turn and release the worker instead of taskkill/SIGKILLing the
+  // shared worker process. See killTrackedProcess's comment above.
+  if (info?._pooled && info.proc && typeof info.proc.kill === 'function') {
+    try { info.proc.kill(); } catch { /* best-effort */ }
+    return;
+  }
   const pid = info?.proc?.pid;
   if (!pid) return;
   if (process.platform === 'win32') {
@@ -418,7 +450,7 @@ function checkSteering(config) {
         fs.appendFileSync(liveLogPath, `\n[steering] Message received but no session to resume. Killing agent — your message will be delivered on retry.\n`);
       } catch { /* optional */ }
 
-      shared.killImmediate(info.proc);
+      killTrackedProcess(info);
       info._steeringAt = Date.now();
       info._steeringNoSession = true;
       continue;
@@ -442,7 +474,7 @@ function checkSteering(config) {
       } catch { /* best-effort */ }
     }
 
-    shared.killImmediate(info.proc);
+    killTrackedProcess(info);
   }
 }
 
@@ -619,7 +651,7 @@ function checkTimeouts(config) {
     if (elapsed > itemTimeout) {
       log('warn', `Agent ${info.agentId} (${id}) hit hard timeout after ${Math.round(elapsed / 1000)}s — killing`);
       dispatch().updateAgentStatus(id, AGENT_STATUS.TIMED_OUT, `Hard timeout after ${Math.round(elapsed / 1000)}s`);
-      shared.killGracefully(info.proc, 5000);
+      killTrackedProcess(info, { graceMs: 5000 });
     }
   }
 
@@ -700,7 +732,7 @@ function checkTimeouts(config) {
     runPostCompletionHooks(item, item.agent, processExitCode, fullLogForHooks, config, { detectPhantom: true, expectedNonce, completionNonceRequired }).catch(e => log('warn', 'post-completion hooks: ' + e.message));
 
     if (hasProcess) {
-      shared.killImmediate(activeProcesses.get(item.id)?.proc);
+      killTrackedProcess(activeProcesses.get(item.id));
       activeProcesses.delete(item.id);
     }
   }
@@ -815,7 +847,7 @@ function checkTimeouts(config) {
           // Clear the cached session so retry does not re-enter the same stuck --resume path.
           try { shared.safeUnlink(path.join(AGENTS_DIR, item.agent, 'session.json')); } catch {}
           activeProcesses.delete(item.id);
-          shared.killGracefully(procInfo.proc, 5000);
+          killTrackedProcess(procInfo, { graceMs: 5000 });
           deadItems.push({ item, reason, failureClass: FAILURE_CLASS.TIMEOUT });
         }
       }
@@ -867,7 +899,18 @@ function checkTimeouts(config) {
 
     if (!processAlive && (canReapDeadProcess || silentMs > staleOrphanTimeout) && (Date.now() > engineRestartGraceUntil || canReapDeadProcess)) {
       // Last-resort PID check: lost tracked handle but OS process may still be alive.
-      if (isOsPidAliveForDispatch(item.id)) {
+      // P-3f5b7d26 — SKIPPED for pooled dispatches (item.pooled, persisted by
+      // engine.js#spawnAgent). The PID recorded for a pooled dispatch is the
+      // shared ACP worker's real OS pid (engine/acp-transport.js#spawnAcp),
+      // whose command line is literally `copilot --acp ...` — it would always
+      // pass isProcessCommandLineMatchingAgent's `cmdline.includes('copilot')`
+      // check below even though that worker has no relationship to THIS
+      // dispatch (a fresh engine's agent-worker-pool.js always cold-starts
+      // empty; the pool never reconnects a restart-era worker to any prior
+      // dispatch). Without this guard a coincidentally-still-alive (or
+      // PID-recycled) worker process would be misread as "still running",
+      // parking the dispatch forever instead of routing it to retry.
+      if (!item.pooled && isOsPidAliveForDispatch(item.id)) {
         // Cross-check the PID's command line: a recycled OS PID can be alive
         // under an unrelated process (Windows reuses PIDs aggressively). Without
         // this cmdline gate, the dispatch is parked indefinitely as 'active'
@@ -1018,4 +1061,5 @@ module.exports = {
   _resetSteeringStoreCacheForTest, _setSteeringStoreForTest,
   // exported for testing — steering clamp helpers and deferred checkpoint
   _clampSteeringDeferredMaxMs, _clampSteeringMaxKillRetries, _appendLiveOutputLine, deferSteeringUntilCheckpoint,
+  killTrackedProcess, _escalatePlatformKill, // exported for testing — P-6e2a4c15 cancel-vs-kill
 };

package/engine.js

@@ -36,6 +36,12 @@ const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS,
   FAILURE_CLASS, resolvePollFlag } = shared;
 const { resolveRuntime } = require('./engine/runtimes');
 const { assertStaleHeadOk, preApproveWorkspaceMcps } = require('./engine/spawn-agent');
+// P-1d8f0b93 — fleet ACP worker pool + its child_process-shaped facade.
+// NOTE: engine/agent-worker-pool.js is a DIFFERENT module from the
+// dashboard's single-tab CC pool (engine.js must never import that one —
+// see the cc-tab-pool wiring regression guard test).
+const agentWorkerPool = require('./engine/agent-worker-pool');
+const { PooledAgentProcess } = require('./engine/pooled-agent-process');
 const adoGitAuth = require('./engine/ado-git-auth');
 const queries = require('./engine/queries');
 const dispatchEvents = require('./engine/dispatch-events');
@@ -4458,6 +4464,18 @@ async function spawnAgent(dispatchItem, config) {
   const resolvedModel = runtime.resolveModel(shared.resolveAgentModel(agentConfig, engineConfig));
   const resolvedMaxBudget = shared.resolveAgentMaxBudget(agentConfig, engineConfig);
   const resolvedBare = shared.resolveAgentBareMode(agentConfig, engineConfig);
+  // P-1d8f0b93 — pool a copilot dispatch through the persistent ACP worker
+  // pool (engine/agent-worker-pool.js) instead of cold-spawning a fresh CLI
+  // process, when the capability + config gate allows it. Structurally
+  // copilot-only (runtime.capabilities.acpWorkerPool) — see
+  // shared.resolveAgentUseWorkerPool for the exact precedence chain.
+  const useAgentPool = shared.resolveAgentUseWorkerPool(engineConfig, runtime);
+  if (useAgentPool) {
+    // Idempotent — cheap to call on every pooled dispatch so a live config
+    // change (agentAcpPoolSize / maxConcurrent) takes effect without a
+    // separate engine-restart-only wiring hook.
+    agentWorkerPool.setPoolSize(shared.resolveAgentAcpPoolSize(engineConfig));
+  }
 
   // W-mpg6isvy000xca4d — On retry after FAILURE_CLASS.MODEL_UNAVAILABLE, swap
   // to the runtime-appropriate fallback model. Two paths gated on
@@ -4582,7 +4600,14 @@ async function spawnAgent(dispatchItem, config) {
   childEnv.MINIONS_NO_AUTO_OPEN = '1';
   // MCP-free copilot config so agents never pop a per-spawn Microsoft auth
   // window — see _applyAgentCopilotHome / shared.resolveAgentCopilotHome.
-  _applyAgentCopilotHome(childEnv);
+  // P-1d8f0b93 — SKIPPED for pooled dispatches: the pooled ACP worker is a
+  // long-lived process shared across many dispatches, so it always uses the
+  // operator's REAL COPILOT_HOME (this is the isolation-removal half of the
+  // pooling feature — MCP-auth-popup risk becomes bounded by pool size
+  // instead of eliminated per-dispatch; documented tradeoff in the plan).
+  if (!useAgentPool) {
+    _applyAgentCopilotHome(childEnv);
+  }
   // Keep agent scratch off a (possibly full) system drive — anchors TEMP/TMP to
   // the worktree volume. See _applyAgentTempEnv / shared.resolveAgentTempBaseDir.
   _applyAgentTempEnv(childEnv, project);
@@ -4614,6 +4639,14 @@ async function spawnAgent(dispatchItem, config) {
   const spawnScript = path.join(ENGINE_DIR, 'spawn-agent.js');
 
   const spawnArgs = [spawnScript, promptPath, sysPromptPath, ...args];
+  // P-1d8f0b93 — the pooled-dispatch branch further down (agentWorkerPool
+  // acquireWorker) accepts an optional `hermeticDirs` (workspace-manifest
+  // `allowed_repos` beyond the primary cwd — see engine/agent-worker-pool.js
+  // header doc). Repository harness discovery (skills/commands/--add-dir) is
+  // now delegated entirely to the native runtime CLI (#817), so there is no
+  // longer an engine-computed add-dir set to reuse here; leave it empty and
+  // let agentWorkerPool's `_applyHermeticDirs` no-op as designed.
+  const addDirs = [];
 
   // Live output file — stamped BEFORE child process is spawned (#W-mo248lkjwgsu).
   // Writing the stub pre-spawn lets the orphan detector distinguish three failure modes
@@ -4687,12 +4720,43 @@ async function spawnAgent(dispatchItem, config) {
     // exactly — the agent's process already starts here, but cd-ing around or
     // sub-shells can drift, so the env var is the stable anchor.
     childEnv.MINIONS_AGENT_CWD = cwd;
-    proc = runFile(process.execPath, spawnArgs, {
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: childEnv,
-      detached: true,
-    });
+    if (!useAgentPool) {
+      proc = runFile(process.execPath, spawnArgs, {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: childEnv,
+        detached: true,
+      });
+    } else {
+      // P-1d8f0b93 — pooled copilot dispatch. No separate spawn-agent.js
+      // child process exists, so build the SAME combined prompt text that
+      // process would have received via runtime.buildPrompt(...) directly
+      // here, and hand it to a PooledAgentProcess facade instead of
+      // cold-spawning. Everything downstream (stdout/stderr handlers,
+      // onAgentClose, live-output.log, PID-file writing below) treats `proc`
+      // identically to a real child_process either way.
+      const pooledPromptText = runtime.buildPrompt(fullTaskPrompt, systemPrompt, { sessionId: cachedSessionId });
+      proc = new PooledAgentProcess({
+        pool: agentWorkerPool,
+        dispatchId: id,
+        cwd,
+        model: effectiveModel,
+        effort: requestedEffort,
+        // Mirrors the CC worker pool's convention (dashboard.js) — a single
+        // flat top-level config array, not per-agent-resolved.
+        mcpServers: (engineConfig && engineConfig.mcpServers) || [],
+        hermeticDirs: addDirs,
+        promptText: pooledPromptText,
+      });
+      // The child_process PID file is normally written asynchronously by
+      // spawn-agent.js itself (engine/spawn-agent.js:606) once it starts.
+      // There is no such child process here, so the engine writes the
+      // equivalent file itself as soon as the pool hands back a real OS PID
+      // (mirrors that write: async, best-effort, same `String(pid)` shape).
+      proc.on('acquired', () => {
+        try { fs.writeFile(pidFilePath, String(proc.pid || ''), () => {}); } catch { /* best-effort */ }
+      });
+    }
     _phaseT.spawnCallEnd = Date.now();
 
     // Seed realActivityMap and stamp PID immediately — BEFORE any handlers (#W-mo25loq8kjer).
@@ -4720,6 +4784,11 @@ async function spawnAgent(dispatchItem, config) {
         _runtimeResumeAwaitingFirstOutput: true,
       } : {}),
       _pendingSteeringFiles: pendingSteering.entries,
+      // P-1d8f0b93 — marks a pooled dispatch so engine/timeout.js's
+      // cancel-vs-kill wiring (P-6e2a4c15, killTrackedProcess /
+      // _escalatePlatformKill) can route `.kill()` to cancel+release the
+      // ACP worker instead of SIGKILL/taskkill on the shared worker's OS pid.
+      ...(useAgentPool ? { _pooled: true } : {}),
     };
     activeProcesses.set(id, initialProcInfo);
     registeredInActiveProcesses = true;
@@ -6008,6 +6077,11 @@ async function spawnAgent(dispatchItem, config) {
     // route output parsing through the right adapter. Also surfaces the choice
     // in dispatch.json for debugging multi-runtime fleets.
     item.runtimeName = runtimeName;
+    // P-3f5b7d26 — persist pooled on the DISK record (activeProcesses/_pooled
+    // is wiped on restart); cli.js's reattach path needs this since a pooled
+    // ACP worker isn't spawned detached and a fresh pool cold-starts empty —
+    // a live worker PID must never be mistaken for a resumable dispatch.
+    if (useAgentPool) item.pooled = true;
     // W-mq5rwwss000f30a7 — persist the worktree path so the live-worktree
     // guard (shared.isWorktreePathLive) can correlate destructive callers
     // (removeWorktree, cleanup orphan-dir sweep, pool-return, quarantine)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2372",
+  "version": "0.1.2374",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"