@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/shared.js

@@ -920,9 +920,6 @@ function safeJsonNoRestore(p, defaultValue = null) {
  * avoid temp file name collisions.
  */
 let _tmpCounter = 0;
-const SAFE_WRITE_RENAME_ATTEMPTS = 20;
-const SAFE_WRITE_RENAME_RETRY_BASE_MS = 50;
-const SAFE_WRITE_RENAME_RETRY_MAX_MS = 250;
 
 function safeWrite(p, data) {
   const dir = path.dirname(p);
@@ -932,16 +929,13 @@ function safeWrite(p, data) {
   try {
     fs.writeFileSync(tmp, content);
     // Atomic rename — retry on Windows EPERM (file locking)
-    for (let attempt = 0; attempt < SAFE_WRITE_RENAME_ATTEMPTS; attempt++) {
+    for (let attempt = 0; attempt < 5; attempt++) {
       try {
         fs.renameSync(tmp, p);
         return;
       } catch (e) {
-        if (e.code === 'EPERM' && attempt < SAFE_WRITE_RENAME_ATTEMPTS - 1) {
-          const delay = Math.min(
-            SAFE_WRITE_RENAME_RETRY_BASE_MS * (attempt + 1),
-            SAFE_WRITE_RENAME_RETRY_MAX_MS
-          );
+        if (e.code === 'EPERM' && attempt < 4) {
+          const delay = 50 * (attempt + 1); // 50, 100, 150, 200ms
           sleepMs(delay);
           continue;
         }
@@ -952,7 +946,7 @@ function safeWrite(p, data) {
     }
     // All rename attempts exhausted without throw — should not happen, but clean up
     try { fs.unlinkSync(tmp); } catch { /* cleanup */ }
-    throw new Error(`[safeWrite] All ${SAFE_WRITE_RENAME_ATTEMPTS} rename attempts failed for ${p}`);
+    throw new Error(`[safeWrite] All 5 rename attempts failed for ${p}`);
   } catch (err) {
     // Clean up tmp if it still exists, then re-throw — never silently swallow
     try { fs.unlinkSync(tmp); } catch { /* cleanup */ }
@@ -1412,104 +1406,6 @@ function pruneCrashDiagnosticsReports(config) {
   return removed;
 }
 
-const FILE_LOCK_RELEASE_ATTEMPTS = 5;
-const FILE_LOCK_RELEASE_RETRY_DELAY_MS = 25;
-const FILE_LOCK_RETRY_MAX_DELAY_MS = 250;
-
-function _releaseFileLock(lockPath, fd) {
-  try { fs.closeSync(fd); } catch { /* continue to path cleanup */ }
-
-  const attempts = process.platform === 'win32' ? FILE_LOCK_RELEASE_ATTEMPTS : 1;
-  for (let attempt = 0; attempt < attempts; attempt++) {
-    try {
-      fs.unlinkSync(lockPath);
-      return true;
-    } catch (err) {
-      if (err && err.code === 'ENOENT') return true;
-      const retryable = process.platform === 'win32'
-        && err && (err.code === 'EPERM' || err.code === 'EBUSY' || err.code === 'EACCES');
-      if (!retryable || attempt === attempts - 1) {
-        console.warn(`[withFileLock] Failed to release ${lockPath}: ${err?.message || err}`);
-        return false;
-      }
-      sleepMs(FILE_LOCK_RELEASE_RETRY_DELAY_MS * (attempt + 1));
-    }
-  }
-  return false;
-}
-
-function _isTransientFileLockPathError(err) {
-  return !!err && (err.code === 'ENOENT'
-    || (process.platform === 'win32' && err.code === 'EPERM'));
-}
-
-function _readFileLockState(lockPath) {
-  try {
-    const stat = fs.statSync(lockPath);
-    const raw = fs.readFileSync(lockPath, 'utf8');
-    let holderPid = null;
-    try {
-      const parsed = JSON.parse(raw);
-      if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) holderPid = parsed.pid;
-    } catch { /* legacy/empty/corrupt lock */ }
-    return { raw, holderPid, mtimeAge: Date.now() - stat.mtimeMs };
-  } catch (err) {
-    if (_isTransientFileLockPathError(err)) return null;
-    throw err;
-  }
-}
-
-function _readFileLockIdentity(lockPath) {
-  try {
-    return fs.readFileSync(lockPath, 'utf8');
-  } catch (err) {
-    if (_isTransientFileLockPathError(err)) return null;
-    throw err;
-  }
-}
-
-function _tryReapFileLock(lockPath) {
-  const claimPath = `${lockPath}.reap`;
-  let claimFd;
-  try {
-    claimFd = fs.openSync(claimPath, 'wx');
-    try {
-      fs.writeSync(claimFd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
-    } catch { /* claim existence provides serialization */ }
-  } catch (err) {
-    const contended = err && (err.code === 'EEXIST'
-      || (process.platform === 'win32' && err.code === 'EPERM'));
-    if (contended) return false;
-    throw err;
-  }
-
-  try {
-    const observed = _readFileLockState(lockPath);
-    if (!observed) return false;
-    const shouldReap = observed.holderPid !== null
-      ? !processUtils.isPidAlive(observed.holderPid) || observed.mtimeAge > LOCK_STALE_MS * 5
-      : observed.mtimeAge > LOCK_STALE_MS;
-    if (!shouldReap) return false;
-
-    // A holder can release and a successor can acquire between the PID probe
-    // and deletion. The reap claim excludes competing reapers; this identity
-    // check prevents the winner from deleting that successor's lock.
-    const currentRaw = _readFileLockIdentity(lockPath);
-    if (currentRaw === null) return false;
-    if (currentRaw !== observed.raw) return false;
-
-    try {
-      fs.unlinkSync(lockPath);
-      return true;
-    } catch (err) {
-      if (_isTransientFileLockPathError(err)) return false;
-      throw err;
-    }
-  } finally {
-    _releaseFileLock(claimPath, claimFd);
-  }
-}
-
 function withFileLock(lockPath, fn, {
   timeoutMs = 5000,
   retryDelayMs = 25,
@@ -1524,13 +1420,9 @@ function withFileLock(lockPath, fn, {
       const backoff = retryBackoffMs * Math.pow(2, attempt - 1);
       sleepMs(backoff);
     }
+    const start = Date.now();
     let fd = null;
-    const pollDelayMs = Math.max(1, Number(retryDelayMs) || 1);
-    const waitBudgetMs = Math.max(0, Number(timeoutMs) || 0);
-    let waitedMs = 0;
-    let contentionCount = 0;
-    let lastOwnerIdentity;
-    while (true) {
+    while (Date.now() - start < timeoutMs) {
       try {
         const dir = path.dirname(lockPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -1540,11 +1432,7 @@ function withFileLock(lockPath, fn, {
         // the lock's existence (not its contents) provides mutual exclusion, so
         // a write failure here must NOT abort acquisition.
         try {
-          fs.writeSync(fd, JSON.stringify({
-            pid: process.pid,
-            ts: Date.now(),
-            owner: crypto.randomBytes(8).toString('hex'),
-          }));
+          fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
         } catch { /* payload is advisory; lock semantics unaffected */ }
         break;
       } catch (err) {
@@ -1559,27 +1447,47 @@ function withFileLock(lockPath, fn, {
         const isLockRaceErr = err.code === 'EEXIST' ||
           (process.platform === 'win32' && err.code === 'EPERM');
         if (!isLockRaceErr) throw err;
-        const ownerIdentity = _readFileLockIdentity(lockPath);
-        if (ownerIdentity !== null && ownerIdentity !== lastOwnerIdentity) {
-          if (lastOwnerIdentity !== undefined) {
-            waitedMs = 0;
-            contentionCount = 0;
+        // PID-owned locks are safe to reap as soon as their owner is dead.
+        // Alive owners retain the 5× stale window; legacy/partial lockfiles
+        // without a readable PID retain the mtime-only stale window.
+        try {
+          const stat = fs.statSync(lockPath);
+          const mtimeAge = Date.now() - stat.mtimeMs;
+          let holderPid = null;
+          try {
+            const raw = fs.readFileSync(lockPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) {
+              holderPid = parsed.pid;
+            }
+          } catch { /* legacy/empty/corrupt lock → mtime-only fallback */ }
+
+          const shouldReap = holderPid !== null
+            ? !processUtils.isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5
+            : mtimeAge > LOCK_STALE_MS;
+
+          if (shouldReap) {
+            try {
+              fs.unlinkSync(lockPath);
+            } catch (unlinkErr) {
+              // ENOENT: another process deleted the lock between stat and unlink — safe to retry.
+              // EPERM on Windows: file is in 'pending delete' state from a concurrent
+              // reaper — the OS will finalize the delete shortly; retry will succeed.
+              const tolerable = unlinkErr.code === 'ENOENT' ||
+                (process.platform === 'win32' && unlinkErr.code === 'EPERM');
+              if (!tolerable) throw unlinkErr;
+            }
+            continue; // lock just removed — retry immediately
           }
-          lastOwnerIdentity = ownerIdentity;
+        } catch (staleErr) {
+          // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed.
+          // EPERM on Windows: file is in 'pending delete' state — statSync itself
+          // can fail; fall through to the normal retry sleep (W-mpd6lm1g000x195e).
+          const tolerable = staleErr.code === 'ENOENT' ||
+            (process.platform === 'win32' && staleErr.code === 'EPERM');
+          if (!tolerable) throw staleErr;
         }
-        if (_tryReapFileLock(lockPath)) continue;
-        // Count active retry sleeps rather than wall time. Host suspension must
-        // not consume the whole budget without another acquisition attempt.
-        if (waitedMs >= waitBudgetMs) break;
-        const backoffMs = Math.min(
-          pollDelayMs * Math.pow(2, Math.min(contentionCount, 4)),
-          FILE_LOCK_RETRY_MAX_DELAY_MS
-        );
-        const jitterMs = contentionCount === 0 ? 0 : Math.floor(Math.random() * pollDelayMs);
-        const delayMs = Math.min(waitBudgetMs - waitedMs, backoffMs + jitterMs);
-        sleepMs(delayMs);
-        waitedMs += delayMs;
-        contentionCount += 1;
+        sleepMs(retryDelayMs);
       }
     }
     if (fd === null) {
@@ -1595,52 +1503,143 @@ function withFileLock(lockPath, fn, {
       // completes, silently breaking mutual exclusion. Clean up our own fd /
       // lock first, then throw so the caller cannot ignore the failure.
       if (result && typeof result.then === 'function') {
-        _releaseFileLock(lockPath, fd);
+        try { fs.closeSync(fd); } catch { /* cleanup */ }
+        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
         fd = null; // suppress double-cleanup in `finally`
         throw new Error('withFileLock: fn must be synchronous; got Promise. Use synchronous operations only.');
       }
       return result;
     } finally {
       if (fd !== null) {
-        _releaseFileLock(lockPath, fd);
+        try { fs.closeSync(fd); } catch { /* cleanup */ }
+        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
       }
     }
   }
   throw lastErr;
 }
 
+const DELETE_JSON_FILE = Symbol('minions.deleteJsonFile');
+
 function mutateJsonFileLocked(filePath, mutateFn, {
   defaultValue = {},
   lockRetries,
   lockRetryBackoffMs,
   skipWriteIfUnchanged = false,
+  restoreOnRead = true,
+  writeDefaultOnInvalid = true,
+  exclusiveClaim = false,
   onWrote = null,
 } = {}) {
   const lockPath = `${filePath}.lock`;
   const retries = lockRetries ?? ENGINE_DEFAULTS.lockRetries;
   const retryBackoffMs = lockRetryBackoffMs ?? ENGINE_DEFAULTS.lockRetryBackoffMs;
   return withFileLock(lockPath, () => {
-    const fileExists = fs.existsSync(filePath);
-    let data = safeJson(filePath);
-    const parsedInvalid = fileExists && data === null;
-    if (data === null || typeof data !== 'object') data = Array.isArray(defaultValue) ? [...defaultValue] : { ...defaultValue };
-    const beforeSerialized = skipWriteIfUnchanged ? JSON.stringify(data) : null;
-    const next = mutateFn(data);
-    const finalData = next === undefined ? data : next;
-    const shouldWrite = !skipWriteIfUnchanged || parsedInvalid || JSON.stringify(finalData) !== beforeSerialized;
-    if (shouldWrite) {
-      const backupPath = filePath + '.backup';
-      try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
-      safeWrite(filePath, finalData);
-      // Side-effect hook fired only when an actual write happened. Callers
-      // use this to emit cache-invalidation signals (events table row) so
-      // skip-write-unchanged paths (dedup, idempotent no-op POSTs) don't
-      // produce spurious cache busts.
-      if (typeof onWrote === 'function') {
-        try { onWrote(finalData); } catch { /* hook errors must not break the write */ }
+    let fileExists = fs.existsSync(filePath);
+    let claimPath = null;
+    if (exclusiveClaim && fileExists) {
+      claimPath = `${filePath}.claim-${process.pid}-${uid()}`;
+      try {
+        fs.renameSync(filePath, claimPath);
+      } catch (error) {
+        if (!error || error.code !== 'ENOENT') throw error;
+        fileExists = false;
+        claimPath = null;
       }
     }
-    return finalData;
+    const readPath = claimPath || filePath;
+    const cleanupClaim = () => {
+      if (!claimPath) return;
+      for (const candidate of [claimPath, claimPath + '.backup']) {
+        try { fs.unlinkSync(candidate); } catch (error) {
+          if (error && error.code !== 'ENOENT') throw error;
+        }
+      }
+    };
+    const restoreClaim = () => {
+      if (!claimPath || !fs.existsSync(claimPath)) return;
+      try {
+        fs.copyFileSync(claimPath, filePath, fs.constants.COPYFILE_EXCL);
+        cleanupClaim();
+      } catch (error) {
+        if (error && error.code === 'EEXIST') {
+          cleanupClaim();
+          return;
+        }
+        throw error;
+      }
+    };
+
+    try {
+      let data = restoreOnRead ? safeJson(readPath) : safeJsonNoRestore(readPath);
+      const parsedInvalid = fileExists && data === null;
+      if (data === null || typeof data !== 'object') {
+        data = Array.isArray(defaultValue) ? [...defaultValue] : { ...defaultValue };
+      }
+      const beforeSerialized = skipWriteIfUnchanged ? JSON.stringify(data) : null;
+      const next = mutateFn(data, { fileExists, readPath });
+      if (next === DELETE_JSON_FILE) {
+        if (claimPath) {
+          if (fs.existsSync(filePath)) {
+            const error = new Error(`JSON file was replaced during mutation: ${filePath}`);
+            error.code = 'JSON_FILE_REPLACED';
+            throw error;
+          }
+          cleanupClaim();
+        } else {
+          for (const candidate of [filePath, filePath + '.backup']) {
+            try { fs.unlinkSync(candidate); } catch (error) {
+              if (error && error.code !== 'ENOENT') throw error;
+            }
+          }
+        }
+        return null;
+      }
+      const finalData = next === undefined ? data : next;
+      const shouldWrite = !skipWriteIfUnchanged
+        || (parsedInvalid && writeDefaultOnInvalid)
+        || JSON.stringify(finalData) !== beforeSerialized;
+      if (shouldWrite) {
+        if (claimPath) {
+          safeWrite(claimPath, finalData);
+          if (fs.existsSync(filePath)) {
+            const error = new Error(`JSON file was replaced during mutation: ${filePath}`);
+            error.code = 'JSON_FILE_REPLACED';
+            throw error;
+          }
+          try {
+            fs.copyFileSync(claimPath, filePath, fs.constants.COPYFILE_EXCL);
+          } catch (error) {
+            if (error && error.code === 'EEXIST') {
+              error.code = 'JSON_FILE_REPLACED';
+            }
+            throw error;
+          }
+          cleanupClaim();
+        } else {
+          const backupPath = filePath + '.backup';
+          try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
+          safeWrite(filePath, finalData);
+        }
+        // Side-effect hook fired only when an actual write happened. Callers
+        // use this to emit cache-invalidation signals (events table row) so
+        // skip-write-unchanged paths (dedup, idempotent no-op POSTs) don't
+        // produce spurious cache busts.
+        if (typeof onWrote === 'function') {
+          try { onWrote(finalData); } catch { /* hook errors must not break the write */ }
+        }
+      } else if (claimPath) {
+        restoreClaim();
+      }
+      return finalData;
+    } catch (error) {
+      if (claimPath && fs.existsSync(claimPath)) {
+        try { restoreClaim(); } catch (restoreError) {
+          error.restoreError = restoreError;
+        }
+      }
+      throw error;
+    }
   }, { retries, retryBackoffMs });
 }
 
@@ -2468,6 +2467,73 @@ function parseStreamJsonOutput(raw, runtimeName, opts) {
   return resolveRuntime(runtimeName).parseOutput(raw, opts || {});
 }
 
+// ── Stale resumed-session detection (W-ms0vk9nv000z985b) ────────────────────
+//
+// A `--resume`d CLI can die instantly, before it writes a single stdout byte,
+// when its persisted session is no longer usable. Two distinct signals, both
+// runtime-agnostic in shape (each adapter's CLI phrases them slightly
+// differently, so we match on the stable substrings actually emitted):
+//
+//   1. The backing conversation was purged from the runtime's session store.
+//   2. The directory the session was created in is gone — the engine removed
+//      or quarantined that worktree since the previous dispatch. Copilot
+//      reports this as `resume-auto-cd: ignoring persisted cwd <path> ...
+//      missing or not a directory` on stderr and then exits 1 with EMPTY
+//      stdout, so the failure otherwise classifies as a meaningless
+//      EMPTY_OUTPUT.
+//
+// Callers use this to (a) purge the cached session so the retry starts fresh
+// and (b) classify the failure as RUNTIME_SESSION_STALE instead of
+// EMPTY_OUTPUT. Prevention lives in each adapter's getResumeSessionId (it
+// refuses to hand back a session whose recorded cwd no longer exists); this
+// helper is the defense-in-depth for the race where the directory disappears
+// between resolution and spawn.
+const _STALE_RESUME_SESSION_PATTERNS = [
+  /no conversation found/i,
+  /ignoring persisted cwd/i,
+  /session (?:not found|no longer exists|has expired)/i,
+];
+
+function isStaleResumeSessionSignal(text) {
+  const value = text == null ? '' : String(text);
+  if (!value) return false;
+  return _STALE_RESUME_SESSION_PATTERNS.some(re => re.test(value));
+}
+
+/**
+ * PREVENTION side of the same bug (W-ms0vk9nv000z985b): decide whether a
+ * persisted session may be resumed given the directory it was created in.
+ *
+ * Runtime CLIs anchor a resumable session to the working directory it was
+ * started in. Minions gives most dispatches an engine-owned worktree that is
+ * removed, recycled, or quarantined once the dispatch ends — so by the time
+ * the same agent is dispatched again, the session's directory can be gone or
+ * a different path entirely. Handing that session id to `--resume` makes the
+ * CLI bail before it writes any stdout, which surfaced as an opaque
+ * `empty-output` failure.
+ *
+ * Returns a human-readable reason to REFUSE the resume, or null when the
+ * session is safe to resume. Sessions saved before this field existed carry no
+ * `cwd` and are treated as compatible — same opt-in convention as the
+ * `runtime` field, so deploying this cannot invalidate live sessions.
+ *
+ * Shared by every runtime adapter: the constraint is a property of how the
+ * engine manages worktrees, not of any one CLI.
+ */
+function staleResumeSessionCwdReason(sessionCwd, currentCwd) {
+  if (!sessionCwd || typeof sessionCwd !== 'string') return null;
+  let exists = false;
+  try { exists = fs.existsSync(sessionCwd); } catch { exists = false; }
+  if (!exists) return `session working directory no longer exists (${sessionCwd})`;
+  if (!currentCwd || typeof currentCwd !== 'string') return null;
+  const recorded = _normalizeWorktreePath(sessionCwd);
+  const current = _normalizeWorktreePath(currentCwd);
+  if (recorded && current && recorded !== current) {
+    return `session was created in ${sessionCwd} but this dispatch runs in ${currentCwd}`;
+  }
+  return null;
+}
+
 // ── Knowledge Base ──────────────────────────────────────────────────────────
 
 const KB_CATEGORIES = ['architecture', 'conventions', 'project-notes', 'build-reports', 'reviews'];
@@ -2502,6 +2568,7 @@ const KB_READABLE_CATEGORIES = Object.freeze([
   'consolidated', 'consolidation', 'consolidations',
   'team-memory', 'general', 'patterns',
 ]);
+/**
 /**
  * Detect engine-authored system alerts (dirty-tree refusals, worktree-skip-live
  * guard notices, blocked/conflicted live-checkout dispatches, managed-spawn
@@ -2926,6 +2993,7 @@ const ENGINE_DEFAULTS = {
   worktreeCreateTimeout: 300000, // 5min for git worktree add on large Windows repos
   worktreeCreateRetries: 1, // retry once on transient timeout/lock races
   worktreeRoot: '../worktrees',
+  worktreeMinFreeSpaceBytes: 10 * 1024 * 1024 * 1024, // fail-closed before checkout below 10 GiB; 0 disables
   worktreeCountCacheTtl: 30000, // 30s — TTL for cached _countWorktrees() result in dashboard
   // W-mq1habhf: timeout (ms) for the `git status --porcelain` probe inside
   // engine.js assertCleanSharedWorktree. The default 10s is fine for ordinary
@@ -2991,7 +3059,7 @@ const ENGINE_DEFAULTS = {
   // to before this knob existed. Flip via Dashboard → Settings → Auto-fix
   // & Review Loop, or set `engine.autoFixPaused: true` in config.json.
   autoFixPaused: false, // hard-stop kill-switch / master override (see comment above)
-  autoConsolidateMemory: false, // opt-in: periodically spawn engine/kb-sweep-runner.js from the tick loop (4h cadence). Inbox→notes consolidation already runs every tick via consolidateInbox; this flag only controls the KB sweep.
+  autoConsolidateMemory: true, // default-on: periodically spawn engine/kb-sweep-runner.js from the tick loop (4h cadence). Explicit false disables it; inbox→notes consolidation is independent.
   // W-mrktrokd — batteries-included default schedules. When true (default),
   // adding a project auto-creates its per-project git-fetch-freshness schedule
   // (`keep-branch-fresh-git-fetch-origin-<slug>`, cron `0 */12 *`, explore) and
@@ -3302,6 +3370,7 @@ const ENGINE_DEFAULTS = {
   preDispatchEvalMaxRejections: 5,
   completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
   autoApplyReviewVote: false, // Master gate for platform vote mutations; local verdicts remain informational when false.
+  createPrsAsDraft: false, // W-mrtdy7xv — when true, the playbook PR-creation guidance (engine/playbook.js#getPrCreateInstructions) tells agents to open normal Minions-created PRs as DRAFT (GitHub `gh pr create --draft`; ADO `az repos pr create --draft true`). Default false = behave exactly as today. Per-project-overridable via `project.createPrsAsDraft` (explicit boolean), resolved through `shared.resolveCreatePrsAsDraft(project, engine)` — a project can opt IN or OUT independent of this fleet-wide default. Aggregate/E2E verify PRs already open as draft via verify.md regardless of this flag; the engine-opened shared-branch aggregate PR is outside the playbook seam and unaffected.
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.
@@ -3326,10 +3395,46 @@ const ENGINE_DEFAULTS = {
   // Engine-scoped per the CLAUDE.md rule against `runtime.name === ...` branches at call sites — the runtime check
   // lives inside the helper (engine/spawn-agent.js#preApproveWorkspaceMcps) which no-ops for non-Claude runtimes.
   claudePreApproveWorkspaceMcps: true,
+  // W-mrdon0pe000l045a — propagate repo-authored CLAUDE.md instructions to
+  // runtimes that do NOT auto-discover CLAUDE.md natively (Copilot, Codex).
+  // When TRUE (default), the engine bounded-discovers the nearest applicable
+  // CLAUDE.md files for a dispatch and injects them as a "Project instructions
+  // (CLAUDE.md)" context layer (engine/playbook.js → engine/claude-md-context.js).
+  // Claude is always skipped — its own CLI already reads CLAUDE.md, so injecting
+  // it again would double the instructions. CLAUDE.md carries no split-brain
+  // risk for Copilot/Codex because those runtimes never read it themselves, so
+  // this is orthogonal to the native AGENTS.md / repo-instruction discovery that
+  // each runtime's CLI now owns (#817). Per-project override via
+  // `project.propagateClaudeMdForNonClaudeRuntimes`; resolved through
+  // `shared.resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine)`.
+  propagateClaudeMdForNonClaudeRuntimes: true,
+  // W-mrtdmtwq000kf391 — surface the repo HARNESS assets in effect for a
+  // dispatch (runtime + project) in the Minions-authored PR body. When TRUE
+  // (default), engine/playbook.js injects a PR-body appendix instructing the
+  // agent to append a fenced "## Repo harnesses used" section listing the
+  // dispatch's runtime, injected CLAUDE.md files, AGENTS.md discovery, MCP
+  // servers, and skills. Pure reporting via the read-only harness-diagnostics
+  // source (engine/harness-context.js → engine/preflight._runtimeHarnessRows +
+  // engine/claude-md-context.js); it never propagates or attests any asset.
+  includeHarnessSectionInPrBody: true,
   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: true,             // 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. On by default (PR #2492 cold-spawn measurements; matches engine/features.js's `ccUseWorkerPool` registry default) — opt out via `engine.ccUseWorkerPool: false`. **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.
+  ccUseWorkerPool: true,             // Route Copilot CC/doc-chat through a persistent `copilot --acp` worker per tab by default. Structurally Copilot-only: resolveCcUseWorkerPool forces false for runtimes without this transport.
+  // P-9b3d5f61 (Pool copilot agent dispatches through a shared ACP worker pool):
+  // when true AND the resolved runtime declares `capabilities.acpWorkerPool`,
+  // engine.js spawnAgent routes per-agent dispatches through
+  // engine/agent-worker-pool.js (persistent `copilot --acp` workers) instead of
+  // cold-spawning a fresh CLI per dispatch. Opt-in while fleet-pool lifecycle
+  // hardening remains newer than the established cold-spawn path. Structurally
+  // Copilot-only, same as
+  // ccUseWorkerPool: resolveAgentUseWorkerPool hard-returns false whenever the
+  // resolved runtime's capability flag isn't true, regardless of this override.
+  agentUseWorkerPool: false,
+  // P-9b3d5f61 — max concurrent ACP workers the per-agent pool
+  // (engine/agent-worker-pool.js) will keep warm. `undefined` = fall back to
+  // the fleet's `maxConcurrent` dispatch cap via resolveAgentAcpPoolSize, so
+  // the pool never queues more than the engine would have dispatched anyway.
+  agentAcpPoolSize: undefined,
   maxBudgetUsd: undefined,       // fleet USD ceiling for --max-budget-usd (per-agent override: agents.<id>.maxBudgetUsd). Honors 0 via ?? so a literal cap of $0 works
   disableModelDiscovery: false,  // skip runtime.listModels() REST calls fleet-wide (settings UI falls back to free-text)
   // W-mpmwxkrw000872ec — dashboard global font-size scale. Drives the
@@ -3376,27 +3481,49 @@ const ENGINE_DEFAULTS = {
   // the kill); holder details are appended to the inbox note either way.
   autoReapOrphanWorktreeHolders: false,
   // W-mqvejug6000eeb20 — fleet-wide fallback for live-checkout auto-reset.
-  // When ON, a dirty/broken live-checkout tree is `git fetch origin` +
-  // `git reset --hard origin/<branch>`'d before dispatch instead of failing
-  // LIVE_CHECKOUT_DIRTY. Per-project `project.liveCheckoutAutoReset` overrides
-  // this. Default FLIPPED BACK to false under W-mrawgw4q000a6bff: the original
-  // divergence problem this was ON to solve (dirty live-checkout trees
-  // accumulating `minions: auto-save agent WIP` commits) is now primarily
-  // addressed by `liveCheckoutAutoStash` (non-destructive — `git stash push`,
-  // recoverable via `git stash pop` — see `resolveLiveCheckoutAutoStash` /
-  // `applyLiveCheckoutAutoStash` in engine/live-checkout.js), which the
-  // stash-before-reset ordering (W-mrawgw4q000a6bff) now always attempts FIRST
-  // when both flags are enabled for a dispatch. Auto-reset remains available as
-  // an explicit opt-in (per-project `project.liveCheckoutAutoReset: true` or
-  // fleet `engine.liveCheckoutAutoReset: true`) for cases that specifically
-  // need the branch fast-forwarded/discarded to `origin/<mainRef>`, not just
-  // cleaned. Resolution precedence lives in `resolveLiveCheckoutAutoReset`
-  // (UNCHANGED by this flip). Fires ONLY on confirmed dirty-tree detection,
-  // never on mid-operation / blob-fetch / tooling failures.
+  // When ON, a dirty live-checkout tree is cleaned with `git reset --hard HEAD`
+  // + `git clean -fd` before dispatch instead of failing LIVE_CHECKOUT_DIRTY.
+  // The current branch and committed history are preserved. Per-project
+  // `project.liveCheckoutAutoReset` overrides this. Default false;
+  // `liveCheckoutAutoStash` gets first chance when both policies are enabled.
+  // Fires only on confirmed dirt, never on mid-operation / detached-HEAD /
+  // tooling failures.
   liveCheckoutAutoReset: false,
+  // W-mr3lunnq000o9f41 — opt-in companion to the live-checkout stale-base guard.
+  // When ON, a live-checkout dispatch that would fail LIVE_CHECKOUT_WRONG_BASE
+  // (HEAD on an unrelated topic branch AND no local `refs/heads/<mainBranch>` to
+  // fork from) is auto-recovered by materializing a local base branch from the
+  // `refs/remotes/origin/<mainBranch>` remote-tracking ref (a LOCAL ref — NO
+  // `git fetch`, so issue #226 is preserved) and forking cleanly off it.
+  // origin/<mainBranch> IS the correct base, so there is NO scope-contamination
+  // risk. Per-project `project.liveCheckoutAutoBaseRepair` overrides this.
+  // Resolution precedence lives in `resolveLiveCheckoutAutoBaseRepair`. Default
+  // OFF because the recovery's `git checkout <mainBranch>` may hydrate blobs on a
+  // partial clone (the one op issue #226 flagged as hang-prone headless); when it
+  // does hang it degrades to exactly the pre-existing fail-closed refusal.
+  liveCheckoutAutoBaseRepair: false,
+  // W-mrdlcud2000e630e — opt-in companion to the live-checkout stale-base guard.
+  // When ON, a live-checkout (or hybrid liveValidation) dispatch that is about to
+  // fork a NEW branch off the local `mainBranch` fast-forwards that local base to
+  // `origin/<mainBranch>` FIRST, but ONLY in the strictly-safe case: the tree is
+  // clean (the dirty-tree guard already covers this), HEAD is on `mainBranch`, the
+  // local base has ZERO commits ahead of `origin/<mainBranch>` (i.e. NOT the
+  // stale-base-with-unpushed-commits case — that refusal is unchanged), and the
+  // local base IS behind `origin/<mainBranch>`. It runs `git fetch origin
+  // <mainBranch>` then a `--ff-only` update — the ONE sanctioned live-mode fetch
+  // (issue #226 otherwise forbids fetching live checkouts, to preserve operator
+  // control over history rewrites); a fast-forward can never rewrite history or
+  // lose local commits (there are none ahead), and it NEVER touches a dirty tree
+  // or a mid-operation state. On fetch/network/auth failure it FAILS OPEN to the
+  // pre-existing (un-freshened) stale-base check. Per-project
+  // `project.liveCheckoutAutoFreshen` overrides this. Resolution precedence lives
+  // in `resolveLiveCheckoutAutoFreshen`. Default OFF (conservative — a human opts
+  // individual projects in). Only affects projects running in live/in-place
+  // (or hybrid liveValidation) checkout mode.
+  liveCheckoutAutoFreshen: false,
   orphanHolderScanTimeoutMs: 5000,          // 5s ceiling for the cross-platform holder scan (PowerShell / /proc walk / lsof)
   ccMaxTurns: 50, // max tool-use turns per CC/doc-chat call before CLI stops (per response, not per session)
-  ccWorkerIdleTimeoutMs: 30 * 60 * 1000, // W-mr0qs0vw: idle-reaper window for the persistent `copilot --acp` worker pool (engine/cc-worker-pool.js). After this much inactivity with no in-flight turn the warm ACP process is killed; the next message cold-spawns a fresh session with NO memory of prior turns (CC shows a "context cleared after inactivity" notice). Tradeoff: shorter = less idle memory/process footprint, longer = more context durability across gaps between messages. Wired into the pool via ccWorkerPool.setIdleTimeoutMs() on every reloadConfig(); clamped to [60000, 28800000] (1min–8h) in the settings POST handler.
+  ccWorkerIdleTimeoutMs: 30 * 60 * 1000, // W-mr0qs0vw: idle-reaper window for the persistent `copilot --acp` worker pool (engine/cc-worker-pool.js). After this much inactivity with no in-flight turn the warm ACP process is killed; the next message cold-spawns a fresh session with NO memory of prior turns (CC shows a "context cleared after inactivity" notice). Tradeoff: shorter = less idle memory/process footprint, longer = more context durability across gaps between messages. Wired into the pool via ccWorkerPool.setIdleTimeoutMs() on every reloadConfig(); clamped to [60000, 28800000] (1min–8h) in the settings POST handler. W-mr1qbj90000d30bd: `0` is an explicit "never idle-reap" sentinel that bypasses the clamp — cc-worker-pool.js maps it to an Infinity window so only an explicit closeTab kills the warm worker; Settings page exposes this as the "Never idle-reap CC workers" toggle.
   ccTurnTimeoutMs: 300000, // W-mpmwxni2000c25c7-b/-d: 5min per-turn no-progress watchdog. The window resets on every liveness signal — token chunk, tool-call notification, tool-update — so an actively-streaming CC/doc-chat turn (long shell command, deep search, sub-agent loop) survives indefinitely up to the outer CC_CALL_TIMEOUT_MS (~1h) ceiling. Only true silence past this window with no progress fires the cancel: the in-flight LLM call is aborted and the handler surfaces `{code:'cc-turn-timeout', retryable:true}` via the typed error envelope so the UI can stop the spinner and offer Retry. Clamped to [10000, 3600000] in the settings POST handler. Independent of CC_CALL_TIMEOUT_MS. Non-streaming doc-chat is the lone wall-clock exception (no progress hooks); see _raceCcDocChatTimeout in dashboard.js for the dual factory/promise shape.
   docSessionMaxEntries: 200, // cap doc-chat session map/disk store by least-recent activity (LRU; sessions are non-expiring otherwise)
   ccLiveStreamMaxAgeMs: 30 * 60 * 1000, // hard cap reconnect buffers if abort/cleanup stalls
@@ -3698,10 +3825,7 @@ function resolveCcUseWorkerPool(engine) {
  *      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.
+ *   3. `ENGINE_DEFAULTS.agentUseWorkerPool` — default OFF.
  */
 function resolveAgentUseWorkerPool(engine, runtime) {
   if (!runtime || !runtime.capabilities || runtime.capabilities.acpWorkerPool !== true) return false;
@@ -3839,6 +3963,24 @@ function resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine) {
   return true;
 }
 
+// W-mrxv648b — resolve the effective "create PRs as draft" flag for a dispatch.
+// Resolution order: per-project `project.createPrsAsDraft` (explicit boolean)
+// wins → else `engine.createPrsAsDraft` (explicit boolean) → else
+// ENGINE_DEFAULTS.createPrsAsDraft (false). Only an explicit boolean counts as
+// "set" at either level — undefined/null/absent falls through to the next tier
+// so operators can enable draft PRs fleet-wide while opting a specific project
+// OUT (or vice-versa). Pure, no I/O. Consumed by
+// engine/playbook.js#getPrCreateInstructions.
+function resolveCreatePrsAsDraft(project, engine) {
+  if (project && typeof project === 'object' && typeof project.createPrsAsDraft === 'boolean') {
+    return project.createPrsAsDraft;
+  }
+  if (engine && typeof engine === 'object' && typeof engine.createPrsAsDraft === 'boolean') {
+    return engine.createPrsAsDraft;
+  }
+  return ENGINE_DEFAULTS.createPrsAsDraft;
+}
+
 // ─── Legacy ccModel → defaultModel Migration ─────────────────────────────────
 //
 // Pre-P-3b8e5f1d, `engine.ccModel` was the single fleet-wide model knob (it
@@ -4705,6 +4847,9 @@ const FAILURE_CLASS = {
   OUT_OF_CONTEXT: 'out-of-context',       // Context window exhausted (token limit, context length)
   MAX_TURNS: 'max-turns',                 // Claude CLI error_max_turns — work in progress, retryable
   COMPLETION_NONCE_MISMATCH: 'completion-nonce-mismatch', // P-d2a8f6c1: completion JSON nonce did not match the per-spawn value injected via MINIONS_COMPLETION_NONCE — treat as forged/untrusted; ignore PR/noop/status fields from the report
+  COMPLETION_REPORT_MISSING: 'completion-report-missing', // W-mrju48xn000a5b84: mutating agent exited without a valid required JSON completion report; process exit alone is not proof of successful completion
+  RUNTIME_TRUNCATED_EXIT: 'runtime-truncated-exit', // W-ms0vk9nv000z985b: the runtime process exited 0 in the MIDDLE of a turn — it produced neither a terminal result (no final assistant text from the adapter's own parseOutput) nor the required completion report. Observed when Copilot exits 0 right after starting a long-running tool call (e.g. `npm test`): the last event is a tool start with no matching completion. This is a truncated runtime turn, NOT an agent that finished and forgot to write its report, so it gets its own explicitly-diagnosed class instead of the generic COMPLETION_REPORT_MISSING. Retryable — a fresh attempt normally runs to completion. The completion-report requirement itself is unchanged: the dispatch still fails.
+  RUNTIME_SESSION_STALE: 'runtime-session-stale', // W-ms0vk9nv000z985b: a `--resume`d runtime died because its persisted session is no longer usable — the CLI reported the backing conversation is gone, or its persisted working directory no longer exists (Copilot's `resume-auto-cd: ignoring persisted cwd ... missing or not a directory`, emitted when the worktree the session was created in has since been removed). Without this class the run surfaced as an opaque EMPTY_OUTPUT because the CLI exits 1 with no stdout at all. Retryable — the engine clears the cached session so the retry starts a fresh one.
   WORKTREE_PREFLIGHT: 'worktree-preflight', // Pre-spawn worktree validation rejected (nested-in-project, drive-root collapse) — never retryable
   WORKTREE_DIRTY: 'worktree-dirty',         // #2996: reused worktree had uncommitted edits and the engine could not auto-heal (or already quarantined). Non-retryable for this dispatch — next discovery cycle creates a fresh worktree.
   WORKTREE_DIVERGENT: 'worktree-divergent', // #2996: reused worktree's local branch was N commits ahead of origin (unsafe to reset, may contain unpushed agent work). Engine quarantined the worktree + backed up the local ref; non-retryable for this dispatch.
@@ -4735,8 +4880,92 @@ const FAILURE_CLASS = {
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 
+function resolveTerminalDispatchResult({
+  code,
+  agentReportedFailure = false,
+  autoRecovered = false,
+  benignNoop = false,
+  trustedCompletionSuccess = false,
+  hardContractFail = false,
+  nonceFail = false,
+  completionReportFail = false,
+  keepProcessesAcceptanceFail = false,
+  managedSpawnAcceptanceFail = false,
+  managedSpawnHealthcheckFail = false,
+} = {}) {
+  if (
+    hardContractFail
+    || nonceFail
+    || completionReportFail
+    || keepProcessesAcceptanceFail
+    || managedSpawnAcceptanceFail
+    || managedSpawnHealthcheckFail
+  ) {
+    return DISPATCH_RESULT.ERROR;
+  }
+  // A nonce-verified terminal-success completion report (trustedCompletionSuccess)
+  // must win over a kill-induced nonzero exit so a startup-timer / steering /
+  // watchdog kill that races a valid success report cannot persist a
+  // contradictory `workerState:failed` alongside `structuredCompletion.status:
+  // success` (incident ralph-fix-mrz8ka5g0015124a). It is gated by the same hard-
+  // failure early-returns above, so a forged/failed/contract-violating report can
+  // never ride this path to success.
+  return ((code === 0 && !agentReportedFailure) || autoRecovered || benignNoop || trustedCompletionSuccess)
+    ? DISPATCH_RESULT.SUCCESS
+    : DISPATCH_RESULT.ERROR;
+}
+
+function resolveTerminalWorkerState({ code, effectiveResult, errorReason } = {}) {
+  if (effectiveResult === DISPATCH_RESULT.SUCCESS) {
+    return {
+      status: AGENT_STATUS.FINISHED,
+      detail: code === 0
+        ? 'Agent completion validated'
+        : `Agent work recovered after process exit code ${code}`,
+    };
+  }
+  return {
+    status: AGENT_STATUS.FAILED,
+    detail: errorReason || (code === 0
+      ? 'Agent process exited but completion validation failed'
+      : `Agent exited with code ${code}`),
+  };
+}
+
+const _dispatchFinalizationOwners = new Map();
+const _dispatchFinalizationWaiters = new Map();
+
+function claimDispatchFinalization(dispatchId, owner) {
+  if (!dispatchId || !owner || _dispatchFinalizationOwners.has(dispatchId)) return false;
+  _dispatchFinalizationOwners.set(dispatchId, owner);
+  return true;
+}
+
+function releaseDispatchFinalization(dispatchId, owner) {
+  if (_dispatchFinalizationOwners.get(dispatchId) !== owner) return false;
+  _dispatchFinalizationOwners.delete(dispatchId);
+  const waiters = _dispatchFinalizationWaiters.get(dispatchId);
+  if (waiters) {
+    _dispatchFinalizationWaiters.delete(dispatchId);
+    for (const resolve of waiters) resolve();
+  }
+  return true;
+}
+
+function waitForDispatchFinalization(dispatchId) {
+  if (!_dispatchFinalizationOwners.has(dispatchId)) return Promise.resolve();
+  return new Promise(resolve => {
+    let waiters = _dispatchFinalizationWaiters.get(dispatchId);
+    if (!waiters) {
+      waiters = new Set();
+      _dispatchFinalizationWaiters.set(dispatchId, waiters);
+    }
+    waiters.add(resolve);
+  });
+}
+
 // Structured completion protocol — fields agents must produce in ```completion blocks
-const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts', 'nonce', 'securityFlags'];
+const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts', 'nonce', 'securityFlags', 'reviewLearnings', 'reviewLearningApplications'];
 
 const DEFAULT_AGENT_METRICS = {
   tasksCompleted: 0, tasksErrored: 0,
@@ -4778,13 +5007,14 @@ function _bumpPruneDefaultClaudeStrip() {
   } catch {}
 }
 
-function pruneDefaultClaudeConfig(config) {
+function pruneDefaultClaudeConfig(config, options = {}) {
+  const trackStrip = options.trackStrip !== false;
   if (!config || typeof config !== 'object') return false;
   const claude = config.claude;
   if (claude === undefined || claude === null) return false;
   if (typeof claude !== 'object' || Array.isArray(claude)) {
     delete config.claude;
-    _bumpPruneDefaultClaudeStrip();
+    if (trackStrip) _bumpPruneDefaultClaudeStrip();
     return true;
   }
 
@@ -4811,7 +5041,7 @@ function pruneDefaultClaudeConfig(config) {
     delete config.claude;
     changed = true;
   }
-  if (changed) _bumpPruneDefaultClaudeStrip();
+  if (changed && trackStrip) _bumpPruneDefaultClaudeStrip();
   return changed;
 }
 
@@ -5046,6 +5276,54 @@ function formatUnknownProjectError(projectName, projects = []) {
   return `Project "${projectName}" not found. Known projects: ${known}`;
 }
 
+function _parseProjectRepositoryIdentity(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+
+  const canonicalScope = _normalizeScopeString(raw);
+  if (canonicalScope) return { kind: 'scope', value: canonicalScope };
+
+  const remoteScope = _parseRemoteUrlToScope(raw);
+  if (remoteScope) return { kind: 'scope', value: remoteScope };
+
+  if (path.isAbsolute(raw) || raw.startsWith('.') || raw.includes('\\') || raw.includes(':')) {
+    return null;
+  }
+  const parts = raw
+    .replace(/\.git$/i, '')
+    .replace(/^\/+|\/+$/g, '')
+    .split('/')
+    .map(normalizePrScopeSegment)
+    .filter(Boolean);
+  if (parts.length === 1) return { kind: 'basename', value: parts[0] };
+  if (parts.length === 2 || parts.length === 3) return { kind: 'slug', value: parts.join('/') };
+  return null;
+}
+
+function _findProjectsByRepositoryIdentity(value, projects) {
+  const identity = _parseProjectRepositoryIdentity(value);
+  if (!identity) return [];
+
+  const matches = [];
+  for (const project of projects || []) {
+    if (!project) continue;
+    const scopes = getProjectAllPrScopes(project);
+    const matched = scopes.some(scope => {
+      if (identity.kind === 'scope') return scope === identity.value;
+      const slug = scope.slice(scope.indexOf(':') + 1);
+      if (identity.kind === 'slug') return slug === identity.value;
+      return slug.split('/').pop() === identity.value;
+    });
+    if (matched && !matches.includes(project)) matches.push(project);
+  }
+  return matches;
+}
+
+function _formatAmbiguousProjectRepositoryError(value, projects) {
+  const names = [...new Set(projects.map(project => project?.name).filter(Boolean))];
+  return `Repository identity "${value}" is ambiguous; it matches multiple configured projects: ${names.join(', ')}. Use an exact configured project name.`;
+}
+
 function findProjectByName(projects, projectName) {
   const name = String(projectName || '').trim().toLowerCase();
   if (!name) return null;
@@ -5066,9 +5344,12 @@ function resolveConfiguredProject(projectName, projectsOrConfig, options = {}) {
   const value = String(raw || '').trim();
   if (value) {
     const project = findProjectByNameOrPath(projects, value);
-    return project
-      ? { project, explicit: true, value }
-      : { project: null, explicit: true, value, error: formatUnknownProjectError(value, projects) };
+    if (project) return { project, explicit: true, value };
+    const repositoryMatches = _findProjectsByRepositoryIdentity(value, projects);
+    const error = repositoryMatches.length > 1
+      ? _formatAmbiguousProjectRepositoryError(value, repositoryMatches)
+      : formatUnknownProjectError(value, projects);
+    return { project: null, explicit: true, value, error };
   }
   if (options.defaultWhenSingle && projects.length === 1) {
     return { project: projects[0], explicit: false, value: '' };
@@ -5152,6 +5433,25 @@ function resolveProjectSource(source, projectsOrConfig, options = {}) {
     }
   }
 
+  // Repository identities are fallback aliases; exact configured names and
+  // paths above remain authoritative.
+  const repositoryMatches = _findProjectsByRepositoryIdentity(value, projects);
+  if (repositoryMatches.length === 1) {
+    return _projectSourceDescriptor(repositoryMatches[0], value, explicit, minionsDir);
+  }
+  if (repositoryMatches.length > 1) {
+    return {
+      project: null,
+      explicit: true,
+      value,
+      sourceName: '',
+      isCentral: false,
+      scope: null,
+      stateDir: null,
+      error: _formatAmbiguousProjectRepositoryError(value, repositoryMatches),
+    };
+  }
+
   return {
     project: null,
     explicit: true,
@@ -6216,6 +6516,7 @@ function buildSecurityHeaders() {
 // keys, and shell invocations — never bypass them for "internal" callers.
 
 const PROJECT_NAME_RE = /^[a-zA-Z0-9_\-]{1,64}$/;
+const CC_TURN_ID_MAX = 80;
 
 function _httpError(status, message, extra) {
   const err = new Error(message);
@@ -6271,6 +6572,14 @@ function validateProjectPath(pathStr, options = {}) {
   if (!fs.existsSync(resolved)) {
     throw _httpError(400, `Invalid project path: directory does not exist: ${resolved}`);
   }
+  let stat;
+  try { stat = fs.statSync(resolved); }
+  catch (e) {
+    throw _httpError(400, `Invalid project path: cannot inspect directory: ${resolved} (${e.message})`);
+  }
+  if (!stat.isDirectory()) {
+    throw _httpError(400, `Invalid project path: path is not a directory: ${resolved}`);
+  }
   const gitMarker = path.join(resolved, '.git');
   if (fs.existsSync(gitMarker)) return resolved; // .git dir OR worktree .git file
 
@@ -6900,20 +7209,66 @@ function getProjectAllPrScopes(project) {
 const _gitRemoteScopeCache = new Map();
 const GIT_REMOTE_SCOPE_CACHE_TTL_MS = 5 * 60 * 1000;
 
+function _remotePartsToScope(host, values) {
+  const parts = values.map((value, index) => {
+    let decoded = String(value || '');
+    try { decoded = decodeURIComponent(decoded); } catch { /* retain malformed input for a non-match */ }
+    if (index === values.length - 1) decoded = decoded.replace(/\.git$/i, '');
+    return normalizePrScopeSegment(decoded);
+  });
+  if (parts.some(part => !part)) return null;
+  return `${host}:${parts.join('/')}`;
+}
+
 // Best-effort parse of a git remote fetch URL into a canonical scope string.
 // Handles the URL shapes git itself produces for `git remote -v` output:
 // SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
-// and the two common ADO host forms (`dev.azure.com/org/project/_git/repo`,
-// `org.visualstudio.com/project/_git/repo`). Returns null when unrecognized.
-function _parseRemoteUrlToScope(url) {
-  const cleaned = String(url || '').trim().replace(/\.git$/i, '');
-  if (!cleaned) return null;
-  let m = cleaned.match(/github\.com[:/]+([^/]+)\/([^/]+)\/?$/i);
-  if (m) return `github:${normalizePrScopeSegment(m[1])}/${normalizePrScopeSegment(m[2])}`;
-  m = cleaned.match(/dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+)\/?$/i);
-  if (m) return `ado:${normalizePrScopeSegment(m[1])}/${normalizePrScopeSegment(m[2])}/${normalizePrScopeSegment(m[3])}`;
-  m = cleaned.match(/([^/@:]+)\.visualstudio\.com\/(?:DefaultCollection\/)?([^/]+)\/_git\/([^/]+)\/?$/i);
-  if (m) return `ado:${normalizePrScopeSegment(m[1])}/${normalizePrScopeSegment(m[2])}/${normalizePrScopeSegment(m[3])}`;
+// and ADO HTTPS/SSH clone URLs. Returns null when unrecognized.
+function _parseRemoteUrlToScope(remoteUrl) {
+  const raw = String(remoteUrl || '').trim();
+  if (!raw) return null;
+
+  let normalized = raw;
+  const scpMatch = raw.match(/^(?:([^@\s/:]+)@)?(github\.com|ssh\.dev\.azure\.com):(.+)$/i);
+  if (scpMatch) {
+    const user = scpMatch[1] ? `${scpMatch[1]}@` : '';
+    normalized = `ssh://${user}${scpMatch[2]}/${scpMatch[3]}`;
+  } else if (/^(?:github\.com|dev\.azure\.com|[^/\s]+\.visualstudio\.com)\//i.test(raw)) {
+    normalized = `https://${raw}`;
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    return null;
+  }
+  const protocol = parsed.protocol.toLowerCase();
+  if (!['http:', 'https:', 'ssh:', 'git:', 'git+ssh:'].includes(protocol)) return null;
+
+  const hostname = parsed.hostname.toLowerCase();
+  const parts = parsed.pathname.split('/').filter(Boolean);
+  if (hostname === 'github.com' && parts.length === 2) {
+    return _remotePartsToScope('github', parts);
+  }
+  if (hostname === 'dev.azure.com' &&
+      parts.length === 4 &&
+      String(parts[2]).toLowerCase() === '_git') {
+    return _remotePartsToScope('ado', [parts[0], parts[1], parts[3]]);
+  }
+  if (hostname.endsWith('.visualstudio.com')) {
+    const org = hostname.slice(0, -'.visualstudio.com'.length);
+    const offset = String(parts[0] || '').toLowerCase() === 'defaultcollection' ? 1 : 0;
+    if (org && parts.length === offset + 3 && String(parts[offset + 1]).toLowerCase() === '_git') {
+      return _remotePartsToScope('ado', [org, parts[offset], parts[offset + 2]]);
+    }
+  }
+  if (hostname === 'ssh.dev.azure.com' &&
+      ['ssh:', 'git+ssh:'].includes(protocol) &&
+      parts.length === 4 &&
+      String(parts[0]).toLowerCase() === 'v3') {
+    return _remotePartsToScope('ado', parts.slice(1));
+  }
   return null;
 }
 
@@ -8050,18 +8405,22 @@ function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
 
 function prReviewFindingIdentity(pr) {
   const review = pr?.minionsReview || {};
+  const persisted = String(review.findingIdentity || '').trim().toLowerCase();
+  if (/^review-[0-9a-f]{16}$/.test(persisted)) return persisted;
   const threads = Array.isArray(review.threads)
     ? review.threads.map(value => String(value)).filter(Boolean).sort()
     : [];
   const evidence = {
     pr: pr?.id || pr?.url || '',
     sourceItem: review.sourceItem || '',
-    dispatchId: review.dispatchId || '',
     reviewer: review.reviewer || '',
-    reviewedAt: review.reviewedAt || pr?.lastReviewedAt || '',
+    reviewedHeadSha: pr?.reviewedHeadSha || '',
     threads,
     note: review.note || pr?.reviewNote || '',
   };
+  if (!evidence.sourceItem && !evidence.reviewedHeadSha) {
+    evidence.dispatchId = review.dispatchId || '';
+  }
   return `review-${crypto.createHash('sha1').update(JSON.stringify(evidence)).digest('hex').slice(0, 16)}`;
 }
 
@@ -8165,6 +8524,7 @@ function isWorktreePathLive(worktreePath, opts = {}) {
   const target = _normalizeWorktreePath(worktreePath);
   if (!target) return false;
   const excludeDispatchId = opts.excludeDispatchId ? String(opts.excludeDispatchId) : null;
+  const excludeSpawnLeaseId = opts.excludeSpawnLeaseId ? String(opts.excludeSpawnLeaseId) : null;
   let db = opts.db || null;
   if (!db) {
     try { db = require('./db').getDb(); }
@@ -8182,7 +8542,8 @@ function isWorktreePathLive(worktreePath, opts = {}) {
     rows = db.prepare(`
       SELECT id,
              json_extract(data, '$.worktreePath') AS top_wt,
-             json_extract(data, '$.meta.worktreePath') AS meta_wt
+             json_extract(data, '$.meta.worktreePath') AS meta_wt,
+             json_extract(data, '$._spawnLeaseId') AS spawn_lease_id
       FROM dispatches
       WHERE status IN ('pending', 'active')
     `).all();
@@ -8191,7 +8552,9 @@ function isWorktreePathLive(worktreePath, opts = {}) {
     return true;
   }
   for (const row of rows || []) {
-    if (excludeDispatchId && String(row.id) === excludeDispatchId) continue;
+    if (excludeDispatchId && String(row.id) === excludeDispatchId) {
+      if (!excludeSpawnLeaseId || String(row.spawn_lease_id || '') === excludeSpawnLeaseId) continue;
+    }
     if (row.top_wt && _normalizeWorktreePath(row.top_wt) === target) return true;
     if (row.meta_wt && _normalizeWorktreePath(row.meta_wt) === target) return true;
   }
@@ -8214,6 +8577,7 @@ function getWorktreeBlockingDispatchInfo(worktreePath, opts = {}) {
     const target = _normalizeWorktreePath(worktreePath);
     if (!target) return null;
     const excludeDispatchId = opts.excludeDispatchId ? String(opts.excludeDispatchId) : null;
+    const excludeSpawnLeaseId = opts.excludeSpawnLeaseId ? String(opts.excludeSpawnLeaseId) : null;
     let db = opts.db || null;
     if (!db) {
       try { db = require('./db').getDb(); }
@@ -8223,12 +8587,15 @@ function getWorktreeBlockingDispatchInfo(worktreePath, opts = {}) {
     const rows = db.prepare(`
       SELECT id, status, updated_at,
              json_extract(data, '$.worktreePath') AS top_wt,
-             json_extract(data, '$.meta.worktreePath') AS meta_wt
+             json_extract(data, '$.meta.worktreePath') AS meta_wt,
+             json_extract(data, '$._spawnLeaseId') AS spawn_lease_id
       FROM dispatches
       WHERE status IN ('pending', 'active')
     `).all();
     for (const row of rows || []) {
-      if (excludeDispatchId && String(row.id) === excludeDispatchId) continue;
+      if (excludeDispatchId && String(row.id) === excludeDispatchId) {
+        if (!excludeSpawnLeaseId || String(row.spawn_lease_id || '') === excludeSpawnLeaseId) continue;
+      }
       const topMatch = row.top_wt && _normalizeWorktreePath(row.top_wt) === target;
       const metaMatch = row.meta_wt && _normalizeWorktreePath(row.meta_wt) === target;
       if (topMatch || metaMatch) {
@@ -8319,6 +8686,10 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
     log('warn', `removeWorktree: refusing to remove ${wtPath} — not under ${worktreeRoot}`);
     return false;
   }
+  if (hasProtectedQuarantineMarker(resolved)) {
+    log('warn', `removeWorktree: refusing to remove ${wtPath} — protected quarantine contains work without complete recovery refs`);
+    return false;
+  }
   // ── Data-loss hardening (W-mqecdoot) — NEVER recursively delete a real git
   //    main repository. ──────────────────────────────────────────────────────
   // The containment check above only proves `resolved` is *under* the
@@ -8378,6 +8749,7 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
     _writeWorktreeSkipLiveInboxNote(wtPath, 'shared.removeWorktree', blockingInfo);
     return false;
   }
+  const hadOwnerMarker = hasWorktreeOwnerMarker(resolved);
   _pruneRemoveWorktreeFailures();
   // Skip paths that failed 3+ times — retry after 1 hour cooldown
   const prior = _removeWorktreeFailures.get(resolved);
@@ -8433,6 +8805,7 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
           log('warn', `removeWorktree: rd /s /q fallback failed for ${wtPath}: ${rdErr.message}`);
         }
       }
+      _restoreWorktreeOwnerMarkerAfterFailedRemoval(resolved, hadOwnerMarker);
       const fail = _removeWorktreeFailures.get(resolved) || { count: 0, lastAttempt: 0 };
       fail.count++;
       fail.lastAttempt = Date.now();
@@ -8456,6 +8829,9 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
 // ownership before removal; a worktree with NO marker is treated as foreign
 // and left untouched (fail-open: leak a dir rather than nuke someone's work).
 const WORKTREE_OWNER_MARKER = '.minions-worktree';
+const WORKTREE_RETRY_PATH_MARKER = '.retry-';
+const WORKTREE_QUARANTINE_PROTECTION_MARKER = '.minions-quarantine-protected';
+const WORKTREE_QUARANTINE_PROTECTED_PATH_TOKEN = '-quarantine-protected-';
 
 // Best-effort stamp dropped right after a successful `git worktree add`. Never
 // throws — a missing marker only costs us the ability to auto-GC that dir.
@@ -8489,6 +8865,36 @@ function hasWorktreeOwnerMarker(worktreePath) {
   }
 }
 
+function hasProtectedQuarantineMarker(worktreePath) {
+  if (!worktreePath) return false;
+  try {
+    let current = path.resolve(worktreePath);
+    while (true) {
+      if (path.basename(current).includes(WORKTREE_QUARANTINE_PROTECTED_PATH_TOKEN)
+          || fs.existsSync(path.join(current, WORKTREE_QUARANTINE_PROTECTION_MARKER))) {
+        return true;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) return false;
+      current = parent;
+    }
+  } catch {
+    return true;
+  }
+}
+
+function _restoreWorktreeOwnerMarkerAfterFailedRemoval(worktreePath, hadOwnerMarker) {
+  if (!hadOwnerMarker || !worktreePath) return false;
+  let exists = false;
+  try { exists = fs.existsSync(worktreePath); } catch { return false; }
+  if (!exists) return false;
+  try {
+    const gitStat = fs.lstatSync(path.join(path.resolve(worktreePath), '.git'));
+    if (gitStat && gitStat.isDirectory()) return false;
+  } catch { /* a missing .git is expected for a partially removed worktree */ }
+  return writeWorktreeOwnerMarker(worktreePath, { restoredAfterFailedRemoval: true });
+}
+
 // True when a `git status --porcelain` line refers ONLY to the engine's own
 // worktree-ownership marker (.minions-worktree) at the worktree root (#284).
 // The marker is gitignored in the repo's current tree, but a reused worktree
@@ -8720,6 +9126,77 @@ function createBackoffTracker({ baseMs = 30000, maxMs = 10 * 60 * 1000 } = {}) {
   return { recordFailure, recordSuccess, isBackingOff, getState, _reset, _setForTest };
 }
 
+// ── npm package identity (W-ms1j8m54000g4a4a) ───────────────────────────────
+// Minions is published to more than one npm distribution channel: the public
+// `@yemi33/minions` and internal builds renamed by tools/prepare-package.js
+// (`INTERNAL_PACKAGE_NAME`, default `@yemishin_microsoft/minions`). Anything
+// that shells out to `npm view` / `npm install -g` / `npm uninstall -g` must
+// target the package that is ACTUALLY installed — hardcoding the public name
+// makes an internal install resolve versions against the wrong channel and
+// then install a SECOND package that claims the same `minions` bin, which npm
+// rejects with EEXIST.
+//
+// The identity is read from the installed package manifest rather than a
+// build-time constant, so a single codebase behaves correctly on every channel.
+const PUBLIC_PACKAGE_NAME = '@yemi33/minions';
+
+// npm's package-name rules, restricted to the subset we need: lowercase,
+// url-safe, optional `@scope/` prefix, ≤214 chars. Also the security gate for
+// the manifest-derived name — the result is interpolated into a shell command,
+// so anything outside this grammar (spaces, `;`, `&&`, path traversal) is
+// rejected rather than escaped.
+const NPM_PACKAGE_NAME_RE = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/;
+// Exact versions only (never a floating tag) — `npm view` output is echoed
+// straight back into `npm install -g <pkg>@<version>`.
+const NPM_VERSION_RE = /^[0-9][0-9a-zA-Z.+-]*$/;
+
+function isValidNpmPackageName(name) {
+  if (typeof name !== 'string' || !name || name.length > 214) return false;
+  return NPM_PACKAGE_NAME_RE.test(name);
+}
+
+function isValidNpmVersion(version) {
+  if (typeof version !== 'string' || !version || version.length > 256) return false;
+  return NPM_VERSION_RE.test(version);
+}
+
+// Resolve the active distribution's package name from `<pkgRoot>/package.json`.
+// Read fresh from disk (not require()) so an in-place npm update is observed
+// within the same process. Falls back to the public package whenever the
+// manifest is missing, unreadable, or carries a name we would not be willing to
+// put on a command line.
+function resolvePackageName(pkgRoot) {
+  if (typeof pkgRoot !== 'string' || !pkgRoot) return PUBLIC_PACKAGE_NAME;
+  try {
+    const name = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).name;
+    if (isValidNpmPackageName(name)) return name;
+  } catch {}
+  return PUBLIC_PACKAGE_NAME;
+}
+
+function assertNpmPackageName(pkgName) {
+  if (!isValidNpmPackageName(pkgName)) {
+    throw new Error(`Refusing to run npm against an invalid package name: ${JSON.stringify(pkgName)}`);
+  }
+  return pkgName;
+}
+
+function buildNpmViewVersionCommand(pkgName) {
+  return `npm view ${assertNpmPackageName(pkgName)} version`;
+}
+
+function buildNpmGlobalInstallCommand(pkgName, version) {
+  assertNpmPackageName(pkgName);
+  if (!isValidNpmVersion(version)) {
+    throw new Error(`Refusing to install an invalid npm version: ${JSON.stringify(version)}`);
+  }
+  return `npm install -g ${pkgName}@${version}`;
+}
+
+function buildNpmGlobalUninstallCommand(pkgName) {
+  return `npm uninstall -g ${assertNpmPackageName(pkgName)}`;
+}
+
 module.exports = {
   MINIONS_DIR,
   ENGINE_DIR,
@@ -8752,6 +9229,14 @@ module.exports = {
   // Node / node:sqlite version gate (issue #244)
   NODE_SQLITE_MIN_VERSION,
   compareDottedVersions,
+  // npm distribution identity (W-ms1j8m54000g4a4a)
+  PUBLIC_PACKAGE_NAME,
+  isValidNpmPackageName,
+  isValidNpmVersion,
+  resolvePackageName,
+  buildNpmViewVersionCommand,
+  buildNpmGlobalInstallCommand,
+  buildNpmGlobalUninstallCommand,
   nodeSupportsBuiltinSqlite,
   nodeSqliteRemediationLine,
   log,
@@ -8761,6 +9246,7 @@ module.exports = {
   safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore,
   safeWrite,
   mutateTextFileLocked,
+  DELETE_JSON_FILE,
   safeUnlink,
   createDispatchTmpDir,
   removeDispatchTmpDir,
@@ -8825,6 +9311,8 @@ module.exports = {
   cleanChildEnv,
   gitEnv,
   parseStreamJsonOutput,
+  isStaleResumeSessionSignal, // W-ms0vk9nv000z985b — stale `--resume` session/cwd detection
+  staleResumeSessionCwdReason, // W-ms0vk9nv000z985b — refuse resuming a session anchored to a dead/other worktree
   KB_CATEGORIES,
   KB_READABLE_CATEGORIES,
   classifyInboxItem,
@@ -8836,6 +9324,7 @@ module.exports = {
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentUseWorkerPool, resolveAgentAcpPoolSize, resolveAgentModel, resolveCcModel,
   resolveAgentAllowedTools, resolveAgentMaxBudget, resolveAgentBareMode, resolvePropagateClaudeMdForNonClaudeRuntimes,
+  resolveCreatePrsAsDraft,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
@@ -8846,6 +9335,8 @@ module.exports = {
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, COMPLETION_FIELDS,
+  resolveTerminalDispatchResult, resolveTerminalWorkerState,
+  claimDispatchFinalization, releaseDispatchFinalization, waitForDispatchFinalization,
   DEFAULT_AGENT_METRICS,
   DEFAULT_AGENTS,
   DEFAULT_CLAUDE,
@@ -8961,6 +9452,7 @@ module.exports = {
   HAS_DANGEROUS_KEY_MAX_DEPTH,
   HAS_DANGEROUS_KEY_MAX_NODES,
   validateProjectName,
+  CC_TURN_ID_MAX,
   validateProjectPath,
   CHECKOUT_MODES,
   validateCheckoutMode,
@@ -8993,8 +9485,13 @@ module.exports = {
   isWorktreePathLive,
   getWorktreeBlockingDispatchInfo,
   WORKTREE_OWNER_MARKER,
+  WORKTREE_RETRY_PATH_MARKER,
+  WORKTREE_QUARANTINE_PROTECTION_MARKER,
+  WORKTREE_QUARANTINE_PROTECTED_PATH_TOKEN,
   writeWorktreeOwnerMarker,
   hasWorktreeOwnerMarker,
+  hasProtectedQuarantineMarker,
+  _restoreWorktreeOwnerMarkerAfterFailedRemoval, // exported for testing
   isWorktreeOwnerMarkerStatusLine,
   _normalizeWorktreePath, // exported for testing
   _writeWorktreeSkipLiveInboxNote, // exported for testing