@yemi33/minions 0.1.2382 → 0.1.2384

package/engine/shared.js

@@ -920,6 +920,9 @@ 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);
@@ -929,13 +932,16 @@ function safeWrite(p, data) {
   try {
     fs.writeFileSync(tmp, content);
     // Atomic rename — retry on Windows EPERM (file locking)
-    for (let attempt = 0; attempt < 5; attempt++) {
+    for (let attempt = 0; attempt < SAFE_WRITE_RENAME_ATTEMPTS; attempt++) {
       try {
         fs.renameSync(tmp, p);
         return;
       } catch (e) {
-        if (e.code === 'EPERM' && attempt < 4) {
-          const delay = 50 * (attempt + 1); // 50, 100, 150, 200ms
+        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
+          );
           sleepMs(delay);
           continue;
         }
@@ -946,7 +952,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 5 rename attempts failed for ${p}`);
+    throw new Error(`[safeWrite] All ${SAFE_WRITE_RENAME_ATTEMPTS} 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 */ }
@@ -1406,6 +1412,104 @@ 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,
@@ -1420,9 +1524,13 @@ function withFileLock(lockPath, fn, {
       const backoff = retryBackoffMs * Math.pow(2, attempt - 1);
       sleepMs(backoff);
     }
-    const start = Date.now();
     let fd = null;
-    while (Date.now() - start < timeoutMs) {
+    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) {
       try {
         const dir = path.dirname(lockPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -1432,7 +1540,11 @@ 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() }));
+          fs.writeSync(fd, JSON.stringify({
+            pid: process.pid,
+            ts: Date.now(),
+            owner: crypto.randomBytes(8).toString('hex'),
+          }));
         } catch { /* payload is advisory; lock semantics unaffected */ }
         break;
       } catch (err) {
@@ -1447,47 +1559,27 @@ function withFileLock(lockPath, fn, {
         const isLockRaceErr = err.code === 'EEXIST' ||
           (process.platform === 'win32' && err.code === 'EPERM');
         if (!isLockRaceErr) throw err;
-        // 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
+        const ownerIdentity = _readFileLockIdentity(lockPath);
+        if (ownerIdentity !== null && ownerIdentity !== lastOwnerIdentity) {
+          if (lastOwnerIdentity !== undefined) {
+            waitedMs = 0;
+            contentionCount = 0;
           }
-        } 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;
+          lastOwnerIdentity = ownerIdentity;
         }
-        sleepMs(retryDelayMs);
+        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;
       }
     }
     if (fd === null) {
@@ -1503,16 +1595,14 @@ 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') {
-        try { fs.closeSync(fd); } catch { /* cleanup */ }
-        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+        _releaseFileLock(lockPath, fd);
         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) {
-        try { fs.closeSync(fd); } catch { /* cleanup */ }
-        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+        _releaseFileLock(lockPath, fd);
       }
     }
   }
@@ -2602,6 +2692,62 @@ function isLiveCheckoutProject(project) {
   return resolveCheckoutMode(project) === CHECKOUT_MODES.LIVE;
 }
 
+// Persisted dispatch records must carry explicit checkout-mode provenance before
+// restart/orphan recovery may operate on project.localPath. Legacy live records
+// are accepted only while the current configured project still resolves live for
+// that work-item type. Any explicit worktree marker or current worktree config
+// fails closed.
+function isLiveCheckoutDispatchRecord(item, config) {
+  if (!item || typeof item !== 'object') return false;
+  const hasCheckoutMarker = Object.prototype.hasOwnProperty.call(item, 'checkoutMode');
+  const hasLegacyMarker = Object.prototype.hasOwnProperty.call(item, 'liveMode');
+  let explicitlyLive = false;
+  if (hasCheckoutMarker) {
+    if (item.checkoutMode !== CHECKOUT_MODES.LIVE) return false;
+    explicitlyLive = true;
+  } else if (hasLegacyMarker) {
+    if (item.liveMode !== true) return false;
+    explicitlyLive = true;
+  }
+
+  if (config !== undefined && config !== null) {
+    let projects;
+    try { projects = getProjects(config); } catch { return false; }
+    const projectRef = item.meta?.project;
+    const resolved = resolveProjectSource(projectRef, projects, { allowCentral: false }).project;
+    if (!resolved || resolveCheckoutMode(resolved, item.type) !== CHECKOUT_MODES.LIVE) return false;
+    if (!projectRef?.localPath || !resolved.localPath
+        || !sameResolvedPath(projectRef.localPath, resolved.localPath)) return false;
+    return explicitlyLive || !!item.originalRef;
+  }
+
+  return explicitlyLive;
+}
+
+function isDispatchExecutionPathSafe(item, config) {
+  if (!item || typeof item !== 'object') return false;
+  let projects;
+  try { projects = getProjects(config); } catch { return false; }
+
+  if (item.worktreePath) {
+    try {
+      assertWorktreeOutsideProjects(item.worktreePath, projects);
+      return isValidGitWorktree(item.worktreePath).ok;
+    } catch {
+      return false;
+    }
+  }
+  if (isLiveCheckoutDispatchRecord(item, config)) return true;
+  if (item.meta?.project) return false;
+  if (!item.executionCwd) return false;
+  try {
+    assertWorktreeOutsideProjects(item.executionCwd, projects);
+    return fs.existsSync(item.executionCwd);
+  } catch {
+    return false;
+  }
+}
+
 // W-mqvejug6000eeb20 — resolve the effective live-checkout auto-reset decision.
 // Precedence: an explicit per-project boolean (`project.liveCheckoutAutoReset`)
 // wins; otherwise the fleet-wide `engine.liveCheckoutAutoReset` applies;
@@ -3428,9 +3574,9 @@ function resolvePollFlag(engineCfg, granularKey, legacyMacroKey) {
 
 // ─── Runtime Fleet Resolution (P-3b8e5f1d) ──────────────────────────────────
 //
-// Six helpers that are the single source of truth for "which CLI runtime + model
-// + budget + bare-mode applies to this spawn?". Engine code MUST go through
-// these — never read `agent.cli`, `engine.defaultCli`, etc. directly. Future
+// Runtime helpers are the single source of truth for "which CLI runtime + model
+// + tool ceiling + budget + bare-mode applies to this spawn?". Engine code MUST
+// go through these — never read `agent.cli`, `engine.defaultCli`, etc. directly. Future
 // agents adding new resolution rules should extend these helpers, not bypass
 // them.
 //
@@ -3476,28 +3622,27 @@ function resolveCcCli(engine) {
 /**
  * Resolve whether the Command Center / doc-chat path should route through the
  * persistent ACP worker pool. Priority:
- *   1. CC runtime guard — pool spawns `copilot --acp` (Agent Client Protocol).
- *      Claude Code does not implement ACP, and `_invokeCcStream` would silently
- *      switch a Claude operator's CC turns to copilot if the pool ran for them.
- *      Refuse the pool when CC runtime is not copilot, even if explicit-true is
- *      set. Future runtimes that don't implement ACP fall into the same bucket.
+ *   1. Runtime capability guard. Refuse the pool unless the selected adapter
+ *      declares `acpWorkerPool`, even if explicit-true is set, so pooling can
+ *      never switch the configured harness.
  *      (W-mphlriic00095f69)
  *   2. `engine.ccUseWorkerPool` explicit true/false — operator override wins
- *      *within* the copilot runtime
- *   3. Runtime-aware default: ON when CC runtime resolves to `copilot`
- *      (Copilot's cold-spawn is 18-21s on Windows — pool turns subsequent turns
- *      from 47-140s back into a few seconds).
+ *      within an ACP-capable runtime.
+ *   3. Runtime-aware default: ON for any ACP-capable adapter.
  *   4. ENGINE_DEFAULTS.ccUseWorkerPool — final fallback
  *
  * Strict boolean check on the override so a literal `false` opts out even on
- * Copilot, matching the "treat empty/null/undefined as unset" semantics used
+ * ACP runtimes, matching the "treat empty/null/undefined as unset" semantics used
  * throughout the resolve* helpers for boolean flags.
  */
 function resolveCcUseWorkerPool(engine) {
-  // Guard 1 (W-mphlriic00095f69): pool transport is ACP-only. If CC runtime
-  // isn't copilot, the pool cannot run regardless of operator opt-in — don't
-  // silently switch their runtime to copilot.
-  if (resolveCcCli(engine) !== 'copilot') return false;
+  let runtime;
+  try {
+    runtime = require('./runtimes').resolveRuntime(resolveCcCli(engine));
+  } catch {
+    return false;
+  }
+  if (runtime?.capabilities?.acpWorkerPool !== true) return false;
   if (engine && (engine.ccUseWorkerPool === true || engine.ccUseWorkerPool === false)) {
     return engine.ccUseWorkerPool;
   }
@@ -3511,7 +3656,7 @@ function resolveCcUseWorkerPool(engine) {
  * adapter (as returned by `resolveRuntime(resolveAgentCli(agent, engine))`)
  * rather than re-deriving it, since callers on the agent-spawn path already
  * have it in hand. Priority:
- *   1. Capability guard — pool transport is ACP-only (`copilot --acp`). Hard
+ *   1. Capability guard — pool transport is ACP-only. Hard
  *      false whenever `runtime.capabilities.acpWorkerPool` isn't `true`,
  *      regardless of operator override, so a future non-ACP runtime can never
  *      be silently routed through the pool (same rationale as
@@ -3585,6 +3730,17 @@ function resolveCcModel(engine) {
   return undefined;
 }
 
+/**
+ * Resolve the fleet tool ceiling for an agent spawn.
+ *
+ * `config.claude.allowedTools` predates runtime adapters but has always applied
+ * to every selected runtime. Keep that cross-runtime contract centralized here
+ * until the field is migrated to a runtime-neutral config namespace.
+ */
+function resolveAgentAllowedTools(config) {
+  return config?.claude?.allowedTools;
+}
+
 /**
  * Resolve the per-spawn USD budget cap. Priority:
  *   1. `agent.maxBudgetUsd`     — per-agent override
@@ -5473,6 +5629,11 @@ function isWorktreeRootInfraEntry(name) {
   return typeof name === 'string' && name.length > 0 && name.charCodeAt(0) === 46; // '.'
 }
 
+function _pathForComparison(filePath) {
+  const resolved = realPathForComparison(String(filePath));
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
 /**
  * True when `childPath` is strictly nested within `parentPath` (descendant,
  * NOT the same path). Cross-platform via `path.relative`; resilient to mixed
@@ -5481,8 +5642,8 @@ function isWorktreeRootInfraEntry(name) {
  */
 function isPathInside(childPath, parentPath) {
   if (!childPath || !parentPath) return false;
-  const childAbs = path.resolve(String(childPath));
-  const parentAbs = path.resolve(String(parentPath));
+  const childAbs = _pathForComparison(childPath);
+  const parentAbs = _pathForComparison(parentPath);
   const rel = path.relative(parentAbs, childAbs);
   if (rel === '') return false;
   if (rel.startsWith('..')) return false;
@@ -5502,12 +5663,17 @@ function isPathInside(childPath, parentPath) {
  */
 function isPathInsideOrEqual(childPath, parentPath) {
   if (!childPath || !parentPath) return false;
-  const childAbs = path.resolve(String(childPath));
-  const parentAbs = path.resolve(String(parentPath));
+  const childAbs = _pathForComparison(childPath);
+  const parentAbs = _pathForComparison(parentPath);
   if (childAbs === parentAbs) return true;
   return isPathInside(childAbs, parentAbs);
 }
 
+function pathsOverlap(firstPath, secondPath) {
+  return isPathInsideOrEqual(firstPath, secondPath)
+    || isPathInsideOrEqual(secondPath, firstPath);
+}
+
 /**
  * Parse `git worktree list --porcelain` output. Pure — callers run the
  * subprocess (sync `execSilent` or async `execAsync`) and feed stdout in.
@@ -5562,6 +5728,22 @@ function assertWorktreeOutsideProject(worktreePath, projectRoot) {
   throw err;
 }
 
+function assertWorktreeOutsideProjects(worktreePath, projectsOrConfig) {
+  const projects = Array.isArray(projectsOrConfig)
+    ? projectsOrConfig
+    : getProjects(projectsOrConfig);
+  for (const project of projects) {
+    if (!project?.localPath) continue;
+    if (!pathsOverlap(worktreePath, project.localPath)) continue;
+    const err = new Error(
+      `Refusing worktree path "${worktreePath}" — it overlaps configured operator checkout "${project.localPath}".`
+    );
+    err.code = 'WORKTREE_NESTED_IN_PROJECT';
+    err.protectedProject = project.name || '';
+    throw err;
+  }
+}
+
 /**
  * Resolve the project root directory used as the parent for git worktree paths
  * during dispatch. Centralizes the fallback that engine spawnAgent used to do
@@ -5702,9 +5884,11 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * @param {string} type — work type (e.g. 'fix', 'explore', 'meeting')
  * @param {string} minionsDir — MINIONS_DIR fallback anchor (ignored in live mode)
  * @param {{ workdir?: string|null }} [options] — optional per-WI overrides
- * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean, workdir?: string|null }}
+ * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean, readOnlyWorktree?: boolean, workdir?: string|null }}
  *   - For live mode (any type): { cwd: <abs localPath[/workdir]>, worktreeRootDir: null, liveMode: true }
- *   - For isolated read-only types: { cwd: <project dir[/workdir] or MINIONS_DIR>, worktreeRootDir: null }
+ *   - For project-bound isolated read-only types:
+ *     { cwd: null, worktreeRootDir: <project root>, readOnlyWorktree: true, workdir }
+ *   - For project-less read-only types: { cwd: <MINIONS_DIR[/workdir]>, worktreeRootDir: null }
  *   - For isolated code-mutating types: { cwd: null, worktreeRootDir: <project root>, workdir: <subpath|null> }
  *     (caller defaults cwd to worktreeRootDir before worktree creation,
  *      then runs shared.applyWorkdir(worktreePath, result.workdir) to land
@@ -5747,14 +5931,21 @@ function resolveSpawnPaths(project, type, minionsDir, options) {
 
   const isReadOnly = READ_ONLY_ROOT_TASK_TYPES.has(type);
   if (isReadOnly) {
-    let base = null;
-    if (project?.localPath) base = path.resolve(String(project.localPath));
-    else if (minionsDir) base = path.resolve(String(minionsDir));
-    else {
+    if (project?.localPath) {
+      if (workdir) _applyWorkdirOrThrow(path.resolve(String(project.localPath)), workdir);
+      return {
+        cwd: null,
+        worktreeRootDir: resolveProjectRootDir(project.localPath, minionsDir),
+        readOnlyWorktree: true,
+        workdir,
+      };
+    }
+    if (!minionsDir) {
       const err = new Error('Cannot resolve cwd for read-only spawn: no project.localPath and no MINIONS_DIR provided.');
       err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
       throw err;
     }
+    const base = path.resolve(String(minionsDir));
     const roCwd = _applyWorkdirOrThrow(base, workdir);
     return { cwd: roCwd, worktreeRootDir: null };
   }
@@ -5868,7 +6059,7 @@ function applyWorkdir(base, workdir) {
   const baseAbs = path.resolve(String(base));
   const joined = path.resolve(baseAbs, workdir);
   // Containment guard: resolved cwd must equal base or live strictly inside.
-  if (joined !== baseAbs && !joined.startsWith(baseAbs + path.sep)) {
+  if (!isPathInsideOrEqual(joined, baseAbs)) {
     return {
       cwd: baseAbs,
       error: 'workdir resolved outside base (containment escape): "' + workdir + '" → "' + joined + '" not inside "' + baseAbs + '"',
@@ -6043,7 +6234,7 @@ function validateProjectPath(pathStr, options = {}) {
 
 function parseSkillFrontmatter(content, filename) {
   let name = filename.replace('.md', '');
-  let trigger = '', description = '', project = 'any', author = '', created = '', allowedTools = '';
+  let trigger = '', description = '', project = 'any', author = '', created = '', allowedTools = '', scope = 'minions';
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (fmMatch) {
     const fm = fmMatch[1];
@@ -6055,8 +6246,52 @@ function parseSkillFrontmatter(content, filename) {
     author = m('author');
     created = m('created');
     allowedTools = m('allowed-tools');
+    scope = m('scope') || scope;
+  }
+  return { name, trigger, description, project, author, created, allowedTools, scope };
+}
+
+function syncBundledPersonalSkills(skillsDir, opts = {}) {
+  const result = { created: [], updated: [], unchanged: [] };
+  if (!skillsDir || !fs.existsSync(skillsDir)) return result;
+
+  const homeDir = opts.homeDir || os.homedir();
+  const { listRuntimes, resolveRuntime } = require('./runtimes');
+  const personalRoots = new Set();
+  for (const runtimeName of listRuntimes()) {
+    const runtime = resolveRuntime(runtimeName);
+    if (typeof runtime.getSkillWriteTargets !== 'function') continue;
+    const personal = runtime.getSkillWriteTargets({ homeDir }).personal;
+    if (typeof personal === 'string' && personal.trim()) {
+      personalRoots.add(path.resolve(personal));
+    }
+  }
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const sourcePath = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (!fs.existsSync(sourcePath)) continue;
+    const content = fs.readFileSync(sourcePath, 'utf8');
+    const skill = parseSkillFrontmatter(content, `${entry.name}.md`);
+    if (skill.scope !== 'minions') continue;
+    const skillName = String(skill.name || entry.name).replace(/[^a-z0-9-]/g, '-');
+    if (!skillName) throw new Error(`Bundled skill has an invalid name: ${sourcePath}`);
+
+    for (const personalRoot of personalRoots) {
+      const targetPath = path.join(personalRoot, skillName, 'SKILL.md');
+      const exists = fs.existsSync(targetPath);
+      if (exists && fs.readFileSync(targetPath, 'utf8') === content) {
+        result.unchanged.push(targetPath);
+        continue;
+      }
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.copyFileSync(sourcePath, targetPath);
+      result[exists ? 'updated' : 'created'].push(targetPath);
+    }
   }
-  return { name, trigger, description, project, author, created, allowedTools };
+  return result;
 }
 
 // ── PR → PRD Links ────────────────────────────────────────────────────────────
@@ -7740,6 +7975,7 @@ function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
     evidence.lastReviewedAt = pr?.lastReviewedAt || '';
     evidence.reviewedAt = review.reviewedAt || '';
     evidence.reviewNote = review.note || pr?.reviewNote || '';
+    evidence.findingId = prReviewFindingIdentity(pr);
     // #2979 — same rationale as BUILD_FAILURE: review feedback fingerprints
     // were sticky across force-push because reviewStatus / reviewedAt /
     // reviewNote don't change when the author rebases. Adding the head SHA
@@ -7751,6 +7987,23 @@ function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
   return crypto.createHash('sha1').update(JSON.stringify(evidence)).digest('hex').slice(0, 16);
 }
 
+function prReviewFindingIdentity(pr) {
+  const review = pr?.minionsReview || {};
+  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 || '',
+    threads,
+    note: review.note || pr?.reviewNote || '',
+  };
+  return `review-${crypto.createHash('sha1').update(JSON.stringify(evidence)).digest('hex').slice(0, 16)}`;
+}
+
 function getPrNoOpFixRecord(pr, cause) {
   if (!pr || !cause || !pr._noOpFixes || typeof pr._noOpFixes !== 'object') return null;
   const record = pr._noOpFixes[cause];
@@ -7993,6 +8246,14 @@ function _writeWorktreeSkipLiveInboxNote(worktreePath, callerTag, blockingInfo)
 function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
   const resolved = path.resolve(wtPath);
   const resolvedRoot = path.resolve(worktreeRoot) + path.sep;
+  let protectedProjects;
+  try {
+    protectedProjects = Array.isArray(opts.projects) ? opts.projects : getProjects(opts.config);
+    assertWorktreeOutsideProjects(resolved, protectedProjects);
+  } catch (err) {
+    log('warn', `removeWorktree: refusing to remove ${wtPath} — path is inside configured operator checkout${err?.protectedProject ? ` ${err.protectedProject}` : ''}`);
+    return false;
+  }
   if (!resolved.startsWith(resolvedRoot)) {
     log('warn', `removeWorktree: refusing to remove ${wtPath} — not under ${worktreeRoot}`);
     return false;
@@ -8510,7 +8771,7 @@ module.exports = {
   ENGINE_DEFAULTS,
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentUseWorkerPool, resolveAgentAcpPoolSize, resolveAgentModel, resolveCcModel,
-  resolveAgentMaxBudget, resolveAgentBareMode, resolvePropagateClaudeMdForNonClaudeRuntimes,
+  resolveAgentAllowedTools, resolveAgentMaxBudget, resolveAgentBareMode, resolvePropagateClaudeMdForNonClaudeRuntimes,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
@@ -8607,14 +8868,18 @@ module.exports = {
   WORKTREE_SCRATCH_DIR_NAME,
   isPathInside,
   isPathInsideOrEqual,
+  pathsOverlap,
   parseWorktreePorcelain,
   assertWorktreeOutsideProject,
+  assertWorktreeOutsideProjects,
   resolveProjectRootDir,
   resolveAgentTempBaseDir,
   resolveSpawnPaths,
   validateWorkItemWorkdir,
   applyWorkdir,
   READ_ONLY_ROOT_TASK_TYPES,
+  isLiveCheckoutDispatchRecord,
+  isDispatchExecutionPathSafe,
   isLiveCommandCenterPath,
   describeCcProtectedPaths,
   renderCcSystemPrompt,
@@ -8648,6 +8913,7 @@ module.exports = {
   PR_FIX_CAUSE,
   getPrFixAutomationCause,
   prFixEvidenceFingerprint,
+  prReviewFindingIdentity,
   prMergeConflictGuardKey,
   resetMergeConflictStateOnRetarget,
   getPrNoOpFixRecord,
@@ -8655,6 +8921,7 @@ module.exports = {
   getPrPausedCauses,
   isBuildFixIneffectivePaused,
   parseSkillFrontmatter,
+  syncBundledPersonalSkills,
   sleepMs,
   clearWorktreeFailureCache,
   removeWorktree,