@yemi33/minions 0.1.2372 → 0.1.2373

package/engine/cleanup.js

@@ -1387,25 +1387,37 @@ async function runCleanup(config, verbose = false) {
     log('info', `Cleanup: cleared ${cleaned.doneRetryCounts} stale retry count(s) from done work items`);
   }
   // PRD items (missing_features[].status)
+  // Read+mutate+write happens inside prdStore.mutatePrd's single transaction
+  // (not readPrd -> mutate-in-JS -> writePrd) so a concurrent writer (another
+  // engine tick, a dashboard API request, or a second process) can't have its
+  // changes clobbered by this pass's stale in-memory copy (lost-update race —
+  // writePrd's _upsertPrd does a full-column data=? replace, not a merge).
   try {
     const prdStore = require('./prd-store');
     const prdFiles = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
     for (const pf of prdFiles) {
       const prdPath = path.join(PRD_DIR, pf);
-      const prd = prdStore.readPrd(prdPath);
+      // Cheap out-of-transaction peek to skip PRDs that clearly need no work;
+      // the authoritative decision (and the write) happens inside mutatePrd.
+      const peek = prdStore.readPrd(prdPath);
+      const needsMigration = peek?.missing_features?.some(feat =>
+        LEGACY_DONE_ALIASES.has(feat.status) || feat.status === LEGACY_NEEDS_REVIEW_STATUS);
+      if (!needsMigration) continue;
       let migrated = 0;
-      if (prd?.missing_features) {
-        for (const feat of prd.missing_features) {
-          if (LEGACY_DONE_ALIASES.has(feat.status)) {
-            feat.status = shared.WI_STATUS.DONE;
-            migrated++;
-          } else if (feat.status === LEGACY_NEEDS_REVIEW_STATUS) {
-            feat.status = shared.WI_STATUS.FAILED;
-            migrated++;
+      prdStore.mutatePrd(prdPath, (prd) => {
+        if (prd?.missing_features) {
+          for (const feat of prd.missing_features) {
+            if (LEGACY_DONE_ALIASES.has(feat.status)) {
+              feat.status = shared.WI_STATUS.DONE;
+              migrated++;
+            } else if (feat.status === LEGACY_NEEDS_REVIEW_STATUS) {
+              feat.status = shared.WI_STATUS.FAILED;
+              migrated++;
+            }
           }
         }
-      }
-      if (migrated > 0) prdStore.writePrd(prdPath, prd);
+        return prd;
+      });
       if (migrated > 0) {
         log('info', `Migrated ${migrated} legacy PRD item status(es) in ${pf}`);
       }
@@ -1413,6 +1425,8 @@ async function runCleanup(config, verbose = false) {
   } catch (e) { log('warn', 'migrate PRD legacy statuses: ' + e.message); }
 
   // Reset orphaned PRD item statuses — dispatched/failed with no matching work item (#779)
+  // Same lost-update concern as above: use prdStore.mutatePrd so the read,
+  // in-JS mutation, and write are one atomic transaction.
   cleaned.orphanedPrdStatuses = 0;
   try {
     const wiIds = new Set(
@@ -1426,16 +1440,17 @@ async function runCleanup(config, verbose = false) {
       const peek = prdStore.readPrd(prdPath);
       if (!peek?.missing_features) continue;
       let reset = 0;
-      const prd = peek;
-      if (prd?.missing_features) {
-        for (const feat of prd.missing_features) {
-          if ((feat.status === shared.WI_STATUS.DISPATCHED || feat.status === shared.WI_STATUS.FAILED) && !wiIds.has(feat.id)) {
-            feat.status = shared.WI_STATUS.PENDING;
-            reset++;
+      prdStore.mutatePrd(prdPath, (prd) => {
+        if (prd?.missing_features) {
+          for (const feat of prd.missing_features) {
+            if ((feat.status === shared.WI_STATUS.DISPATCHED || feat.status === shared.WI_STATUS.FAILED) && !wiIds.has(feat.id)) {
+              feat.status = shared.WI_STATUS.PENDING;
+              reset++;
+            }
           }
         }
-      }
-      if (reset > 0) prdStore.writePrd(prdPath, prd);
+        return prd;
+      });
       if (reset > 0) {
         log('info', `Reset ${reset} orphaned PRD item status(es) → pending in ${pf}`);
         cleaned.orphanedPrdStatuses += reset;

package/engine/cli.js

@@ -614,6 +614,25 @@ const commands = {
       let reattached = 0;
       for (const item of activeOnStart) {
         const agentId = item.agent;
+
+        // P-3f5b7d26 — a pooled dispatch (engine.js#spawnAgent, item.pooled
+        // persisted at dispatch-time) can NEVER be reattached, regardless of
+        // what the PID file says. The ACP worker child
+        // (engine/acp-transport.js#spawnAcp) is not spawned with
+        // `detached: true` like the cold-spawn path, and even on the rare
+        // chance its OS process survived the restart, the freshly-started
+        // engine's engine/agent-worker-pool.js always cold-starts with an
+        // empty worker set — there is no in-process handle whose stdio could
+        // be reconnected to that PID. Treating a live-but-orphaned worker PID
+        // as "still running" here would silently hang the dispatch forever
+        // instead of routing it to the standard "agent died mid-run, mark for
+        // retry" path (timeout.js's confirmedDeadAtRestart handling below).
+        if (item.pooled) {
+          e.engineRestartGraceExempt.add(item.id);
+          e.log('info', `Restart: ${agentId} (${item.id}) was a pooled dispatch — not reattachable, marking for retry`);
+          continue;
+        }
+
         let agentPid = readDispatchPid(item.id);
 
         if (!agentPid) {

package/engine/live-checkout.js

@@ -395,6 +395,27 @@ function _defaultResolveAutoBaseRepair(localPath) {
   }
 }
 
+// W-mrdlcud2000e630e — production default for resolving the live-checkout
+// auto-freshen decision when the caller (engine.js spawnAgent) does not pass an
+// explicit `autoFreshen` boolean. Mirrors `_defaultResolveAutoReset` /
+// `_defaultResolveAutoBaseRepair`: self-resolve from config.json by matching the
+// project on `localPath`, defer to `shared.resolveLiveCheckoutAutoFreshen`. Runs
+// only on the new-branch-fork path when HEAD is on mainRef (cold, not hot).
+// Fails CLOSED — any config read error returns false so a glitch can never
+// silently trigger the one sanctioned live-mode fetch.
+function _defaultResolveAutoFreshen(localPath) {
+  try {
+    const config = shared.safeJson(path.join(shared.MINIONS_DIR, 'config.json')) || {};
+    const projects = shared.getProjects(config);
+    const norm = (p) => path.resolve(String(p || '')).replace(/\\/g, '/').toLowerCase();
+    const target = norm(localPath);
+    const project = projects.find((p) => p && p.localPath && norm(p.localPath) === target) || null;
+    return shared.resolveLiveCheckoutAutoFreshen(project, config.engine);
+  } catch {
+    return false;
+  }
+}
+
 // W-mqvejug6000eeb20 — production default inbox-note writer for the auto-reset
 // audit trail. Lazily required to avoid a load-order cycle (dispatch.js does not
 // require live-checkout.js, but the lazy require keeps this module importable in
@@ -443,6 +464,110 @@ async function _resolveMainRefForRestore({ git, baseOpts, mainRef, autoBaseRepai
   }
 }
 
+// W-mrdlcud2000e630e — AUTO-FRESHEN (opt-in). The ONE sanctioned live-mode fetch.
+// Called from prepareLiveCheckout BEFORE the STALE-BASE GUARD, only when: the
+// tree is clean (Step 1 already bailed on a dirty tree), no mid-operation state
+// (Step 2), HEAD is on `mainRef`, and this is NOT an allowNonMainBase
+// (PR-targeted / shared-branch) dispatch. Fetches `origin <mainRef>` then
+// fast-forwards the local `mainRef` to `origin/<mainRef>` ONLY in the strictly
+// safe case — ZERO commits ahead of origin (i.e. NOT the stale-base-with-
+// unpushed-commits case, which must keep hitting the guard's refusal) AND
+// strictly behind. A `--ff-only` merge can never rewrite history or drop local
+// commits (there are none ahead). Every failure path (fetch error, divergence
+// unknown, ahead>0, up-to-date, ff refusal) returns WITHOUT mutating so the
+// caller falls through to the pre-existing stale-base check unchanged
+// ("fail open"). Best-effort audit: a low-noise inbox note + info log record the
+// before/after SHA only when a freshen actually happened (never on every
+// dispatch). Never throws.
+async function _maybeAutoFreshenLocalMain(opts = {}) {
+  const { git, baseOpts, mainRef, branchName, logFn, wiId, dispatchId, writeNote } = opts;
+  const log = (typeof logFn === 'function') ? logFn : () => {};
+  // Step 1: the ONE sanctioned live-mode fetch. Fail OPEN on any error.
+  try {
+    await git(['fetch', 'origin', mainRef], baseOpts);
+  } catch (fetchErr) {
+    log(
+      `[live-checkout] auto-freshen: 'git fetch origin ${mainRef}' failed ` +
+      `(${String((fetchErr && fetchErr.message) || fetchErr).slice(0, 200)}); ` +
+      `failing open to the existing stale-base check with the un-fetched local ref.`,
+      'warn'
+    );
+    return { freshened: false, reason: 'fetch-failed' };
+  }
+  // Step 2: compute divergence against the freshly-updated origin/<mainRef>.
+  let ahead = -1;
+  let behind = -1;
+  try {
+    const aheadRaw = await git(['rev-list', '--count', `refs/remotes/origin/${mainRef}..${mainRef}`], baseOpts);
+    ahead = parseInt((typeof aheadRaw === 'string' ? aheadRaw : '').trim(), 10);
+    if (Number.isNaN(ahead)) ahead = -1;
+    const behindRaw = await git(['rev-list', '--count', `${mainRef}..refs/remotes/origin/${mainRef}`], baseOpts);
+    behind = parseInt((typeof behindRaw === 'string' ? behindRaw : '').trim(), 10);
+    if (Number.isNaN(behind)) behind = -1;
+  } catch {
+    log(
+      `[live-checkout] auto-freshen: could not compute divergence of local '${mainRef}' vs 'origin/${mainRef}' ` +
+      `after fetch; proceeding to the existing stale-base check.`,
+      'debug'
+    );
+    return { freshened: false, reason: 'divergence-unknown' };
+  }
+  // Step 3: only the strictly-safe case. ahead>0 must fall through UNTOUCHED to
+  // the STALE-BASE GUARD refusal; up-to-date/behind-unknown needs no freshen.
+  if (ahead !== 0 || behind <= 0) {
+    return { freshened: false, reason: ahead > 0 ? 'ahead' : 'up-to-date' };
+  }
+  let beforeSha = '';
+  let afterSha = '';
+  try {
+    const beforeRaw = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+    beforeSha = (typeof beforeRaw === 'string' ? beforeRaw : '').trim();
+  } catch { /* best-effort — informational only */ }
+  // Step 4: fast-forward-only. HEAD is on mainRef (caller-gated), so a plain
+  // `git merge --ff-only origin/<mainRef>` advances the checked-out base. If it
+  // unexpectedly fails (e.g. a race committed onto local mainRef between the
+  // ahead-count and here), FAIL OPEN — the stale-base guard below still protects
+  // against forking off a contaminated base.
+  try {
+    await git(['merge', '--ff-only', `refs/remotes/origin/${mainRef}`], baseOpts);
+  } catch (ffErr) {
+    log(
+      `[live-checkout] auto-freshen: fast-forward of '${mainRef}' to 'origin/${mainRef}' failed ` +
+      `(${String((ffErr && ffErr.message) || ffErr).slice(0, 200)}); failing open to the existing stale-base check.`,
+      'warn'
+    );
+    return { freshened: false, reason: 'ff-failed' };
+  }
+  try {
+    const afterRaw = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+    afterSha = (typeof afterRaw === 'string' ? afterRaw : '').trim();
+  } catch { /* best-effort — informational only */ }
+  log(
+    `[live-checkout] auto-freshen: fast-forwarded local '${mainRef}' ${behind} commit(s) ` +
+    `from ${beforeSha.slice(0, 12) || '(unknown)'} to ${afterSha.slice(0, 12) || '(unknown)'} ` +
+    `(origin/${mainRef}) before forking '${branchName}' (liveCheckoutAutoFreshen).`,
+    'info'
+  );
+  // Best-effort low-noise audit trail. Only fires on an actual freshen (rare),
+  // so it never alert-spams a healthy dispatch. Never throws.
+  try {
+    const write = (typeof writeNote === 'function') ? writeNote : _defaultWriteInboxNote;
+    const slug = `live-checkout-autofreshen-${wiId || dispatchId || 'unknown'}`;
+    const body = [
+      `# Live-checkout auto-freshen of '${mainRef}'`,
+      '',
+      `The live-checkout base branch \`${mainRef}\` was behind \`origin/${mainRef}\` by ${behind} commit(s)`,
+      `with no local-ahead commits, so \`liveCheckoutAutoFreshen\` fast-forwarded it before forking`,
+      `\`${branchName}\`. This is a non-destructive \`--ff-only\` update (no history rewrite, no lost work):`,
+      '',
+      `- before: \`${beforeSha || '(unknown)'}\``,
+      `- after:  \`${afterSha || '(unknown)'}\` (= \`origin/${mainRef}\`)`,
+    ].join('\n');
+    write(slug, body);
+  } catch { /* best-effort audit note */ }
+  return { freshened: true, before: beforeSha, after: afterSha, behind };
+}
+
 async function prepareLiveCheckout(opts = {}) {
   const {
     localPath,
@@ -466,11 +591,18 @@ async function prepareLiveCheckout(opts = {}) {
                      // defers to `_resolveAutoBaseRepair`. When enabled, the
                      // wrong-base recovery may materialize a local base branch from
                      // `refs/remotes/origin/<mainRef>` (no fetch) instead of failing.
+    autoFreshen, // W-mrdlcud2000e630e: tri-state. `true`/`false` short-circuits
+                 // config resolution; `undefined` (the engine.js call shape)
+                 // defers to `_resolveAutoFreshen`. When enabled AND HEAD is on
+                 // mainRef with zero local-ahead commits but behind origin, the
+                 // ONE sanctioned live-mode `git fetch origin <mainRef>` +
+                 // `--ff-only` fast-forward runs before the stale-base guard.
     _git,       // private injection for testing — defaults to shared.shellSafeGit
     _exists,    // private injection for testing — defaults to fs.existsSync
     _rm,        // private injection for testing — defaults to fs.rmSync (recursive, force)
     _resolveAutoReset, // private injection for testing — defaults to config-based resolver
     _resolveAutoBaseRepair, // private injection for testing — defaults to config-based resolver
+    _resolveAutoFreshen, // private injection for testing — defaults to config-based resolver
     _writeInboxNote,   // private injection for testing — defaults to dispatch.writeInboxAlert
     _sleep,            // private injection for testing — defaults to a real setTimeout-based sleep
   } = opts;
@@ -1082,6 +1214,41 @@ async function prepareLiveCheckout(opts = {}) {
   }
 
 
+  // ── Step 4d-freshen: AUTO-FRESHEN (opt-in, W-mrdlcud2000e630e). ────────
+  // BEFORE the STALE-BASE GUARD, optionally fast-forward the local base branch
+  // to origin/<mainRef> so the new branch forks off the freshest safe base.
+  // This is the ONE sanctioned live-mode fetch (issue #226 otherwise forbids
+  // fetching live checkouts to preserve operator control over history rewrites).
+  //
+  // Scope mirrors the STALE-BASE GUARD's skip conditions EXACTLY: it runs only
+  // when HEAD is on mainRef (`curBranch === mainRef` — the base we fork off) and
+  // this is NOT an allowNonMainBase (PR-targeted fix / shared-branch
+  // continuation) dispatch. The dirty-tree bail (Step 1) and mid-operation
+  // preflight (Step 2) have already run, so a dirty or mid-operation tree never
+  // reaches here — the freshen is never attempted on one.
+  //
+  // The helper only fast-forwards in the strictly-safe case (zero commits ahead
+  // of origin AND behind origin); the ahead>0 stale-base case is left UNTOUCHED
+  // so the guard below still refuses it. A `--ff-only` update can never rewrite
+  // history or drop local commits, and any fetch/network/ff failure fails OPEN
+  // to the un-freshened stale-base check. Applies uniformly to plain live mode
+  // and hybrid mode's liveValidation dispatch (both reuse this preflight).
+  if (!allowNonMainBase && curBranch && curBranch === mainRef) {
+    let wantFreshen = false;
+    if (typeof autoFreshen === 'boolean') {
+      wantFreshen = autoFreshen;
+    } else {
+      const resolver = (typeof _resolveAutoFreshen === 'function') ? _resolveAutoFreshen : _defaultResolveAutoFreshen;
+      try { wantFreshen = !!resolver(localPath); } catch { wantFreshen = false; }
+    }
+    if (wantFreshen) {
+      await _maybeAutoFreshenLocalMain({
+        git, baseOpts, mainRef, branchName, logFn, wiId, dispatchId,
+        writeNote: (typeof _writeInboxNote === 'function') ? _writeInboxNote : undefined,
+      });
+    }
+  }
+
   // ── Step 4d: STALE-BASE GUARD (W-mr98op8w000ma4ad). ───────────────────
   // We are about to fork a NEW branch off the CURRENT HEAD. In the common
   // live-mode case HEAD sits on the project base ref (mainRef). Step 1 (dirty
@@ -1877,6 +2044,7 @@ module.exports = {
   _looksLikeAgentBranch,
   _extractBranchFromPorcelainHeader,
   _commitAgentWipWithRetry,
+  _maybeAutoFreshenLocalMain,
   capDirtyFileLines,
   DIRTY_ALERT_MAX_LINES,
   LIVE_CHECKOUT_AUTO_CLEAN_PATTERNS,

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,