@yemi33/minions 0.1.2383 → 0.1.2385

package/engine/pooled-agent-process.js

@@ -27,6 +27,54 @@ const {
   encodePooledOutput,
 } = require('./runtimes');
 
+const CANCEL_GRACE_MS = 1500;
+const DESCENDANT_INITIAL_SNAPSHOT_MS = 3000;
+const DESCENDANT_SNAPSHOT_INTERVAL_MS = 30000;
+const TOOL_SNAPSHOT_DELAYS_MS = [250, 1000];
+
+const _internals = {
+  cancelGraceMs: CANCEL_GRACE_MS,
+  killVerifyDelayMs: 50,
+  listAllProcesses() {
+    return require('./shared').listAllProcessesAsync();
+  },
+  listProcessDescendants(pid, processes) {
+    return require('./shared').listProcessDescendants(pid, processes);
+  },
+  findProcessesWithCwdInside(cwd) {
+    return require('./shared').findProcessesWithCwdInsideAsync(cwd);
+  },
+  killByPidsImmediate(pids) {
+    return require('./shared').killByPidsImmediate(pids);
+  },
+  computeReapPlan(pids, agentId, opts) {
+    return require('./keep-process-sweep').computeReapPlan(pids, agentId, opts);
+  },
+};
+
+function dispatchOwnedDescendants(rootPid, baselinePids, processes) {
+  const baseline = baselinePids instanceof Map || baselinePids instanceof Set
+    ? baselinePids
+    : new Set(baselinePids || []);
+  const descendants = _internals.listProcessDescendants(rootPid, processes);
+  const processByPid = new Map((processes || []).map((entry) => [Number(entry.pid), entry]));
+  return descendants.filter((pid) => {
+    let current = Number(pid);
+    const seen = new Set();
+    while (current && current !== Number(rootPid) && !seen.has(current)) {
+      if (baseline instanceof Map && baseline.has(current)) {
+        const startedAt = Number(processByPid.get(current)?.startedAt) || 0;
+        if (startedAt > 0 && startedAt === baseline.get(current)) return false;
+      } else if (baseline.has(current)) {
+        return false;
+      }
+      seen.add(current);
+      current = Number(processByPid.get(current)?.ppid);
+    }
+    return true;
+  });
+}
+
 class PooledAgentProcess extends EventEmitter {
   /**
    * @param {object} opts
@@ -34,21 +82,30 @@ class PooledAgentProcess extends EventEmitter {
    * @param {object} opts.runtime - resolved runtime adapter
    * @param {string} opts.dispatchId
    * @param {string} opts.cwd
+   * @param {string} [opts.processCwd] - stable checkout used by the worker process
    * @param {string} [opts.model]
    * @param {string} [opts.effort]
    * @param {Array} [opts.mcpServers]
    * @param {Array<string>} [opts.hermeticDirs]
    * @param {object} [opts.processEnv] - worker-process environment
+   * @param {object} [opts.workerOptions] - adapter-owned process-scoped options
+   * @param {string} [opts.sessionId] - existing ACP session to load
    * @param {object} [opts.sessionContext] - trusted values scoped to this lease
+   * @param {string} [opts.agentId] - owner used for keep-processes validation
+   * @param {boolean} [opts.reapDescendants] - reap lease-created child processes
+   * @param {boolean} [opts.keepProcessesSkipWorkdirCheck]
    * @param {string} [opts.systemPromptText] - trusted system instructions
    * @param {string} opts.promptText - task/user prompt only
    */
   constructor({
-    pool, runtime, dispatchId, cwd, model, effort, mcpServers, hermeticDirs,
-    processEnv, sessionContext, systemPromptText, promptText,
+    pool, runtime, dispatchId, cwd, processCwd, model, effort, mcpServers, hermeticDirs,
+    processEnv, workerOptions, sessionId, sessionContext,
+    agentId, reapDescendants, keepProcessesSkipWorkdirCheck,
+    systemPromptText, promptText,
   }) {
     super();
     this.pid = null;
+    this._expectedWorkerStartedAt = 0;
     this.killed = false;
     this.exitCode = null;
     this.stdout = new PassThrough();
@@ -57,31 +114,68 @@ class PooledAgentProcess extends EventEmitter {
     this._runtime = runtime || resolveRuntimeByCapability('acpWorkerPool');
     this._dispatchId = dispatchId;
     this._handle = null;
+    this._handleDiscarded = false;
+    this._killExitCode = null;
+    this._cancelTimer = null;
+    this._cleanupPromise = null;
+    this._cleanupApplied = false;
     this._closed = false;
+    this._closePromise = new Promise((resolve) => { this._resolveClose = resolve; });
     this._startedAt = Date.now();
     this._runtimeOutputError = null;
+    this._agentId = agentId || null;
+    this._sessionCwd = cwd || null;
+    this._reapDescendants = reapDescendants === true;
+    this._keepProcessesSkipWorkdirCheck = keepProcessesSkipWorkdirCheck === true;
+    this._baselineDescendants = null;
+    this._baselineCwdHolders = new Map();
+    this._workerStartedAt = 0;
+    this._trackedLeaseDescendants = new Map();
+    this._initialDescendantTimer = null;
+    this._descendantTimer = null;
+    this._descendantCaptureQueued = false;
+    this._descendantSnapshotInFlight = null;
+    this._descendantCaptureQueued = false;
+    this._descendantTrackingFailed = false;
+    this._toolSnapshotTimers = new Set();
 
     // 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,
-      processEnv, sessionContext, systemPromptText, promptText,
+      cwd, processCwd, model, effort, mcpServers, hermeticDirs,
+      processEnv, workerOptions, sessionId, sessionContext,
+      systemPromptText, promptText,
     });
   }
 
   async _start({
-    cwd, model, effort, mcpServers, hermeticDirs,
-    processEnv, sessionContext, systemPromptText, promptText,
+    cwd, processCwd, model, effort, mcpServers, hermeticDirs,
+    processEnv, workerOptions, sessionId, sessionContext,
+    systemPromptText, promptText,
   }) {
     let handle;
     try {
-      handle = await this._pool.acquireWorker({
+      const acquireOptions = {
         runtime: this._runtime,
         dispatchId: this._dispatchId, cwd, model, effort, mcpServers, hermeticDirs,
         processEnv, sessionContext,
-      });
+      };
+      if (processCwd) acquireOptions.processCwd = processCwd;
+      if (workerOptions !== undefined) acquireOptions.workerOptions = workerOptions;
+      if (sessionId) acquireOptions.sessionId = sessionId;
+      handle = await this._pool.acquireWorker(acquireOptions);
     } catch (err) {
+      if (this.killed) return;
+      if (err && err.acpMethod === 'session/load') {
+        const missing = /(?:resource|session|conversation).*(?:not found|missing)|no conversation/i
+          .test(String(err.message || ''));
+        try {
+          this.stderr.write(`${missing ? 'No conversation found: ' : ''}${err.message}\n`);
+        } catch { /* best-effort */ }
+        this._finish(1);
+        return;
+      }
       // 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.
@@ -93,6 +187,7 @@ class PooledAgentProcess extends EventEmitter {
       // 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 */ }
+      this._finish(this._killExitCode ?? 143);
       return;
     }
 
@@ -101,10 +196,35 @@ class PooledAgentProcess extends EventEmitter {
     if (handle.currentModel) {
       this._writeRuntimeEvent({ kind: 'model', model: handle.currentModel });
     }
+    this._expectedWorkerStartedAt = Number(handle.processStartedAt) || 0;
     // 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');
+    if (this.killed) {
+      this._clearCancelTimer();
+      this._abandonHandle(handle);
+      this._handle = null;
+      this._finish(this._killExitCode ?? 143);
+      return;
+    }
+    const descendantTrackingReady = await this._snapshotDescendants();
+    if (this.killed) {
+      this._clearCancelTimer();
+      this._stopDescendantTracking();
+      if (descendantTrackingReady) this._discardHandle(handle);
+      else this._abandonHandle(handle);
+      this._handle = null;
+      this._finish(this._killExitCode ?? 143);
+      return;
+    }
+    if (!descendantTrackingReady) {
+      this._abandonHandle(handle);
+      this._handle = null;
+      try { this.stderr.write('Pooled worker process cleanup could not be initialized\n'); } catch { /* best-effort */ }
+      this._finish(1);
+      return;
+    }
 
     let sawError = false;
     try {
@@ -126,15 +246,28 @@ class PooledAgentProcess extends EventEmitter {
           sawError = true;
           try { this.stderr.write(String((err && err.message) || err) + '\n'); } catch { /* best-effort */ }
         },
+        onToolUse: () => this._captureAroundToolCall(),
+        onToolUpdate: () => { void this._captureLeaseDescendants(); },
       });
     } catch (err) {
       sawError = true;
       try { this.stderr.write(String((err && err.message) || err) + '\n'); } catch { /* best-effort */ }
     } finally {
-      try { handle.release(); } catch { /* best-effort */ }
+      this._clearCancelTimer();
+      const cleanup = await this._getLeaseCleanup();
+      try {
+        if (!cleanup.safe) {
+          sawError = true;
+          try { this.stderr.write('Pooled worker process cleanup could not be completed safely\n'); } catch { /* best-effort */ }
+        }
+        this._applyCleanupToHandle(handle, cleanup);
+        if (cleanup.abandon) this._abandonHandle(handle);
+        else if (this.killed || cleanup.discard) this._discardHandle(handle);
+        else if (!this._handleDiscarded) handle.release();
+      } catch { /* best-effort */ }
       this._handle = null;
     }
-    this._finish(sawError || this._runtimeOutputError ? 1 : 0);
+    this._finish(this._killExitCode ?? (sawError || this._runtimeOutputError ? 1 : 0));
   }
 
   _writeRuntimeEvent(event) {
@@ -152,29 +285,361 @@ class PooledAgentProcess extends EventEmitter {
     this.exitCode = code;
     try { this.stdout.end(); } catch { /* best-effort */ }
     try { this.stderr.end(); } catch { /* best-effort */ }
+    this._resolveClose(code);
     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).
+  waitForClose() {
+    return this._closePromise;
+  }
+
+  _discardHandle(handle) {
+    if (this._handleDiscarded) return;
+    this._handleDiscarded = true;
+    try {
+      if (typeof handle.discard === 'function') handle.discard();
+      else handle.release();
+    } catch { /* best-effort */ }
+  }
+
+  _abandonHandle(handle) {
+    if (this._handleDiscarded) return;
+    this._handleDiscarded = true;
+    try {
+      if (typeof handle.abandon === 'function') handle.abandon();
+      else handle.release();
+    } catch { /* best-effort */ }
+  }
+
+  _clearCancelTimer() {
+    if (this._cancelTimer) clearTimeout(this._cancelTimer);
+    this._cancelTimer = null;
+  }
+
+  _getLeaseCleanup() {
+    if (!this._cleanupPromise) this._cleanupPromise = this._reapLeaseDescendants();
+    return this._cleanupPromise;
+  }
+
+  _applyCleanupToHandle(handle, cleanup) {
+    if (this._cleanupApplied) return;
+    this._cleanupApplied = true;
+    if (cleanup.preservedPids.length > 0 && typeof handle.preserveDescendants === 'function') {
+      handle.preserveDescendants(cleanup.preservedPids);
+    }
+  }
+
+  _scheduleForcedCancellation(handle) {
+    const graceMs = Math.max(0, Number(_internals.cancelGraceMs) || 0);
+    this._cancelTimer = setTimeout(() => {
+      void (async () => {
+        try {
+          const cleanup = await this._getLeaseCleanup();
+          this._applyCleanupToHandle(handle, cleanup);
+          if (cleanup.abandon) this._abandonHandle(handle);
+          else this._discardHandle(handle);
+        } catch {
+          this._abandonHandle(handle);
+        }
+      })();
+    }, graceMs);
+  }
+
+  async _snapshotDescendants() {
+    if (!this._reapDescendants) return true;
+    if (!this.pid) return false;
+    try {
+      const holders = this._sessionCwd
+        ? await _internals.findProcessesWithCwdInside(this._sessionCwd)
+        : [];
+      const processes = await _internals.listAllProcesses();
+      if (!Array.isArray(processes) || processes.length === 0) throw new Error('process table unavailable');
+      const processByPid = new Map(processes.map((entry) => [Number(entry.pid), entry]));
+      this._workerStartedAt = Number(processByPid.get(this.pid)?.startedAt) || 0;
+      if (this._expectedWorkerStartedAt <= 0
+          || this._workerStartedAt !== this._expectedWorkerStartedAt) {
+        throw new Error('worker process identity changed before lease start');
+      }
+      this._baselineDescendants = new Map();
+      for (const pid of _internals.listProcessDescendants(this.pid, processes)) {
+        const startedAt = Number(processByPid.get(Number(pid))?.startedAt) || 0;
+        if (startedAt <= 0) throw new Error('process identity unavailable');
+        this._baselineDescendants.set(Number(pid), startedAt);
+      }
+      this._baselineCwdHolders = new Map();
+      for (const holder of holders) {
+        const pid = Number(holder.pid);
+        const current = processByPid.get(pid);
+        if (!current) continue;
+        const holderStartedAt = Number(holder.startedAt) || 0;
+        const currentStartedAt = Number(current.startedAt) || 0;
+        if (holderStartedAt <= 0 || currentStartedAt <= 0) {
+          throw new Error('cwd-holder process identity unavailable');
+        }
+        if (holderStartedAt === currentStartedAt) {
+          this._baselineCwdHolders.set(pid, currentStartedAt);
+        }
+      }
+      this._initialDescendantTimer = setTimeout(
+        () => { void this._captureLeaseDescendants(); },
+        DESCENDANT_INITIAL_SNAPSHOT_MS
+      );
+      this._descendantTimer = setInterval(
+        () => { void this._captureLeaseDescendants(); },
+        DESCENDANT_SNAPSHOT_INTERVAL_MS
+      );
+      if (this._initialDescendantTimer.unref) this._initialDescendantTimer.unref();
+      if (this._descendantTimer.unref) this._descendantTimer.unref();
+      return true;
+    } catch {
+      this._baselineDescendants = null;
+      this._descendantTrackingFailed = true;
+      return false;
+    }
+  }
+
+  async _captureLeaseDescendants() {
+    if (!(this._baselineDescendants instanceof Map) || !this.pid) return;
+    if (this._descendantSnapshotInFlight) {
+      this._descendantCaptureQueued = true;
+      try { await this._descendantSnapshotInFlight; } catch { /* owner records the failure */ }
+      return;
+    }
+    const capture = (async () => {
+      do {
+        this._descendantCaptureQueued = false;
+        const processes = await _internals.listAllProcesses();
+        if (!Array.isArray(processes) || processes.length === 0) throw new Error('process table unavailable');
+        const processByPid = new Map(processes.map((entry) => [Number(entry.pid), entry]));
+        if (Number(processByPid.get(this.pid)?.startedAt) !== this._workerStartedAt) {
+          throw new Error('worker process identity changed');
+        }
+        for (const pid of dispatchOwnedDescendants(this.pid, this._baselineDescendants, processes)) {
+          const startedAt = Number(processByPid.get(Number(pid))?.startedAt) || 0;
+          if (startedAt <= 0) throw new Error('process identity unavailable');
+          this._trackedLeaseDescendants.set(Number(pid), startedAt);
+        }
+      } while (this._descendantCaptureQueued);
+    })();
+    this._descendantSnapshotInFlight = capture;
+    try {
+      await capture;
+    } catch {
+      this._descendantTrackingFailed = true;
+    } finally {
+      if (this._descendantSnapshotInFlight === capture) this._descendantSnapshotInFlight = null;
+    }
+  }
+
+  _stopDescendantTracking() {
+    if (this._initialDescendantTimer) clearTimeout(this._initialDescendantTimer);
+    if (this._descendantTimer) clearInterval(this._descendantTimer);
+    this._initialDescendantTimer = null;
+    this._descendantTimer = null;
+    for (const timer of this._toolSnapshotTimers) clearTimeout(timer);
+    this._toolSnapshotTimers.clear();
+  }
+
+  _captureAroundToolCall() {
+    void this._captureLeaseDescendants();
+    for (const delayMs of TOOL_SNAPSHOT_DELAYS_MS) {
+      const timer = setTimeout(() => {
+        this._toolSnapshotTimers.delete(timer);
+        void this._captureLeaseDescendants();
+      }, delayMs);
+      this._toolSnapshotTimers.add(timer);
+    }
+  }
+
+  async _killAndVerify(identities) {
+    if (!(identities instanceof Map) || identities.size === 0) return true;
+    const before = await _internals.listAllProcesses();
+    if (!Array.isArray(before) || before.length === 0) {
+      throw new Error('process table unavailable before identity-bound kill');
+    }
+    const beforeByPid = new Map(before.map((entry) => [Number(entry.pid), entry]));
+    const pids = [];
+    for (const [pid, startedAt] of identities) {
+      const current = beforeByPid.get(pid);
+      if (!current) continue;
+      const currentStartedAt = Number(current.startedAt) || 0;
+      if (currentStartedAt <= 0) return false;
+      if (currentStartedAt === startedAt) pids.push(pid);
+    }
+    if (pids.length === 0) return true;
+    _internals.killByPidsImmediate(pids);
+    const delayMs = Math.max(0, Number(_internals.killVerifyDelayMs) || 0);
+    if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+    const processes = await _internals.listAllProcesses();
+    if (!Array.isArray(processes) || processes.length === 0) {
+      throw new Error('process table unavailable during kill verification');
+    }
+    const processByPid = new Map(processes.map((entry) => [Number(entry.pid), entry]));
+    return [...identities].every(([pid, startedAt]) => {
+      const current = processByPid.get(pid);
+      if (!current) return true;
+      const currentStartedAt = Number(current.startedAt) || 0;
+      return currentStartedAt > 0 && currentStartedAt !== startedAt;
+    });
+  }
+
+  async _reapLeaseDescendants() {
+    if (!this._reapDescendants || !this.pid) {
+      return { safe: true, discard: false, preservedPids: [] };
+    }
+    this._stopDescendantTracking();
+    const reapOpts = this._keepProcessesSkipWorkdirCheck ? { requireGitWorkdir: false } : {};
+    const failClosed = () => {
+      try {
+        const anchorState = _internals.computeReapPlan([], this._agentId, reapOpts);
+        return {
+          safe: false,
+          discard: true,
+          preservedPids: anchorState.record?.pids || [],
+          abandon: true,
+        };
+      } catch {
+        return { safe: false, discard: true, preservedPids: [], abandon: true };
+      }
+    };
+    try {
+      if (this._descendantSnapshotInFlight) await this._descendantSnapshotInFlight;
+      if (!(this._baselineDescendants instanceof Map)) {
+        return { ...failClosed(), abandon: true };
+      }
+      const cwdHolders = this._sessionCwd
+        ? await _internals.findProcessesWithCwdInside(this._sessionCwd)
+        : [];
+      const processes = await _internals.listAllProcesses();
+      if (!Array.isArray(processes) || processes.length === 0) {
+        return { ...failClosed(), abandon: true };
+      }
+      const processByPid = new Map(processes.map((entry) => [Number(entry.pid), entry]));
+      const rootChanged = Number(processByPid.get(this.pid)?.startedAt) !== this._workerStartedAt;
+      if (this._descendantTrackingFailed) {
+        return rootChanged ? { ...failClosed(), abandon: true } : failClosed();
+      }
+      const candidates = new Set();
+      const addKnownTree = (pid, expectedStartedAt) => {
+        const value = Number(pid);
+        const current = processByPid.get(value);
+        if (!current) return true;
+        const startedAt = Number(current.startedAt) || 0;
+        if (startedAt <= 0) return false;
+        if (startedAt !== expectedStartedAt) return true;
+        candidates.add(value);
+        for (const childPid of _internals.listProcessDescendants(value, processes)) {
+          const child = processByPid.get(Number(childPid));
+          const childStartedAt = Number(child?.startedAt) || 0;
+          if (childStartedAt <= 0) return false;
+          candidates.add(Number(childPid));
+        }
+        return true;
+      };
+      for (const [pid, startedAt] of this._trackedLeaseDescendants) {
+        if (!addKnownTree(pid, startedAt)) return failClosed();
+      }
+      for (const holder of cwdHolders) {
+        const pid = Number(holder.pid);
+        const current = processByPid.get(pid);
+        if (!current) continue;
+        const holderStartedAt = Number(holder.startedAt) || 0;
+        const currentStartedAt = Number(current.startedAt) || 0;
+        if (holderStartedAt <= 0 || currentStartedAt <= 0) return failClosed();
+        if (holderStartedAt !== currentStartedAt) continue;
+        if (this._baselineCwdHolders.get(pid) === currentStartedAt) continue;
+        if (!addKnownTree(pid, currentStartedAt)) return failClosed();
+      }
+      if (rootChanged) {
+        for (const [pid, startedAt] of this._baselineDescendants) {
+          if (!addKnownTree(pid, startedAt)) return failClosed();
+        }
+      } else {
+        for (const pid of dispatchOwnedDescendants(this.pid, this._baselineDescendants, processes)) {
+          const startedAt = Number(processByPid.get(Number(pid))?.startedAt) || 0;
+          if (startedAt <= 0) return failClosed();
+          candidates.add(Number(pid));
+        }
+      }
+      if (candidates.size === 0) {
+        return rootChanged
+          ? { ...failClosed(), abandon: true }
+          : { safe: true, discard: false, preservedPids: [] };
+      }
+      const plan = _internals.computeReapPlan([...candidates], this._agentId, reapOpts);
+      const candidateIdentities = new Map(plan.toKill.map((pid) => [
+        Number(pid),
+        Number(processByPid.get(Number(pid))?.startedAt) || 0,
+      ]));
+      if (await this._killAndVerify(candidateIdentities)) {
+        if (plan.kept.length > 0 && !rootChanged) {
+          const kept = new Set(plan.kept.map(Number));
+          const beforeDiscard = await _internals.listAllProcesses();
+          if (!Array.isArray(beforeDiscard) || beforeDiscard.length === 0) {
+            return { safe: false, discard: true, preservedPids: plan.kept, abandon: true };
+          }
+          const discardByPid = new Map(beforeDiscard.map((entry) => [Number(entry.pid), entry]));
+          if (Number(discardByPid.get(this.pid)?.startedAt) !== this._workerStartedAt) {
+            return { safe: false, discard: true, preservedPids: plan.kept, abandon: true };
+          }
+          const nonAnchoredDescendants = new Map();
+          for (const pid of _internals.listProcessDescendants(this.pid, beforeDiscard)) {
+            const value = Number(pid);
+            if (kept.has(value)) continue;
+            const startedAt = Number(discardByPid.get(value)?.startedAt) || 0;
+            if (startedAt <= 0) {
+              return { safe: false, discard: true, preservedPids: plan.kept, abandon: true };
+            }
+            nonAnchoredDescendants.set(value, startedAt);
+          }
+          if (!await this._killAndVerify(nonAnchoredDescendants)) {
+            return { safe: false, discard: true, preservedPids: plan.kept, abandon: true };
+          }
+        }
+        return {
+          safe: !rootChanged,
+          discard: rootChanged || plan.kept.length > 0,
+          preservedPids: plan.kept,
+          abandon: rootChanged,
+        };
+      }
+      // Discarding the whole worker would also kill explicitly anchored
+      // keep_processes children, so preserve the worker when such anchors exist.
+      return {
+        safe: false,
+        discard: true,
+        preservedPids: plan.kept,
+        abandon: true,
+      };
+    } catch {
+      return { ...failClosed(), abandon: true };
+    }
+  }
+
+  // child_process.kill()-shaped primitive. Cancels the in-flight ACP turn and
+  // releases its lease; the pool evicts the worker if that turn is not settled,
+  // preventing a cancelled response from leaking into the next dispatch.
   // 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;
+    this._killExitCode = 143;
     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);
+      this._scheduleForcedCancellation(this._handle);
+    } else if (this._pool && typeof this._pool.cancelAcquire === 'function') {
+      try { this._pool.cancelAcquire(this._dispatchId); } catch { /* best-effort */ }
+      this._finish(this._killExitCode);
+    } else {
+      this._finish(this._killExitCode);
     }
-    // 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 };
+module.exports = {
+  PooledAgentProcess,
+  dispatchOwnedDescendants, // exported for testing
+  _internals, // exported for testing
+};

package/engine/pr-action.js

@@ -184,19 +184,17 @@ function buildCreatePrFollowups({ project, branch, contextOnly = false, checkout
 
   let message;
   if (checkoutMode === 'worktree') {
-    // Worktree-mode projects: the server moves the live-checkout changes into an
-    // isolated worktree and restores the live checkout clean, so the commit /
-    // push / PR all happen OFF the operator's tree. CC never runs git in the
-    // live checkout — that is what kept leaking commits onto `main`.
+    // Worktree-mode projects: copy pre-existing operator changes into an
+    // isolated worktree without modifying their checkout.
     message =
-      `Create a PR from the local changes you just made in the ${proj} project. ` +
-      `This project uses isolated worktrees, so do NOT commit, branch, or push in its live checkout. ` +
-      `Steps: (1) call POST /api/pr-action/prepare-create-pr-worktree with {"project":"${proj}"} — the server moves your uncommitted changes into a fresh isolated worktree, restores the live checkout clean, and returns {worktreePath, branch, baseBranch}; ` +
+      `Create a PR from the pre-existing operator changes in the ${proj} project. ` +
+      `This project uses isolated worktrees, so do NOT edit, commit, branch, clean, reset, or push in its operator checkout. ` +
+      `Steps: (1) call POST /api/pr-action/prepare-create-pr-worktree with {"project":"${proj}"} — the server copies the uncommitted changes into a fresh isolated worktree, leaves the operator checkout unchanged, and returns {worktreePath, branch, baseBranch}; ` +
       `(2) run all git from inside worktreePath (use \`git -C <worktreePath> ...\`): stage and commit the changes on the returned branch with a clear conventional-commit message; ` +
       `(3) push that branch; (4) open a PR against baseBranch using the right CLI for the repo host (gh for GitHub, az repos for ADO); ` +
       `(5) link it by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}; ` +
       `(6) finally call POST /api/pr-action/cleanup-create-pr-worktree with {"project":"${proj}","worktreePath":"<worktreePath>"} to remove the worktree. ` +
-      `Never git-commit/-push in the live checkout. Then show me the PR URL.`;
+      `Do not clean up the operator's original changes; report that they remain untouched. Then show me the PR URL.`;
   } else {
     // Live-checkout projects: operate in place, but ALWAYS build the PR on a
     // fresh branch off the up-to-date origin/<mainBranch> tip — never off