@yemi33/minions 0.1.2147 → 0.1.2149

package/engine.js

@@ -918,6 +918,109 @@ async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
   return removed;
 }
 
+// W-mq5n1zx5 — Layer 1b: status-probe command builder. Honors the
+// ENGINE_DEFAULTS.statusProbeUseNoOptionalLocks toggle so operators can
+// disable the flag if a future git release breaks something. Default ON:
+// `--no-optional-locks` tells git to skip the .git/index.lock acquire
+// around the untracked-cache refresh that runs inside `status`. Without
+// the flag, a 6–12s probe under aggressive AV scanning is normal; with
+// it, typical probes drop to <500ms, which removes the timeout that
+// leaks the git.exe descendant that later pins packfile handles and
+// breaks the quarantine rename.
+function _statusPorcelainCmd() {
+  return ENGINE_DEFAULTS.statusProbeUseNoOptionalLocks
+    ? 'git --no-optional-locks status --porcelain'
+    : 'git status --porcelain';
+}
+
+// W-mq5n1zx5 — Layer 1a: rename worktree dir with jittered backoff. The
+// raw `fs.renameSync` used to throw Windows EBUSY/EPERM/EACCES if a
+// lingering `git.exe` descendant (typically leaked by a status-probe
+// timeout) still held a packfile handle. We retry with capped exponential
+// backoff + random jitter so the descendant has time to exit on its own.
+// Worst-case wall time ≈ baseMs * (2^attempts) ≈ 16s when attempts=6,
+// baseMs=250 — small enough not to wedge a tick, large enough to clear
+// the typical race. Throws the LAST error on exhaustion so the caller
+// can decide whether to fall back to `git worktree remove --force`.
+async function _renameWithRetry(src, dst, opts = {}) {
+  const attempts = Number(opts.attempts) > 0
+    ? Number(opts.attempts)
+    : ENGINE_DEFAULTS.quarantineRenameRetryAttempts;
+  const baseMs = Number(opts.baseMs) > 0
+    ? Number(opts.baseMs)
+    : ENGINE_DEFAULTS.quarantineRenameRetryBaseMs;
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try { fs.renameSync(src, dst); return { attempts: i + 1 }; }
+    catch (e) {
+      if (!['EBUSY', 'EPERM', 'EACCES', 'ENOTEMPTY'].includes(e.code)) throw e;
+      lastErr = e;
+      if (i < attempts - 1) {
+        const delay = baseMs * (2 ** i) + Math.random() * 200;
+        await new Promise(r => setTimeout(r, delay));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+// W-mq5n1zx5 — Layer 2a: on Windows, kill any live `git.exe` descendants
+// whose command line points at the quarantine target path. We never
+// tracked the PID of the `git status --porcelain` child that the probe
+// timed out on, so we can't kill by PID — instead we shell out to
+// PowerShell's CIM cmdlets to find matching processes and Stop-Process
+// them. Cheap (<2s) and idempotent — if no descendants are alive, the
+// CIM query returns nothing and exits 0. POSIX is a no-op (the EBUSY
+// race is Windows-specific). Best-effort; failure is logged but never
+// blocks the quarantine.
+function _killGitDescendantsForWorktree(worktreePath) {
+  if (process.platform !== 'win32') return { killed: 0, skipped: true };
+  if (!ENGINE_DEFAULTS.statusProbeKillDescendantsWin32) return { killed: 0, skipped: true };
+  if (!worktreePath) return { killed: 0, skipped: true };
+  // PowerShell expects single-quoted literals; escape any embedded single
+  // quote by doubling it (PowerShell's standard single-quote escape).
+  const safePath = String(worktreePath).replace(/'/g, "''");
+  const ps = [
+    "$ErrorActionPreference='SilentlyContinue';",
+    `$matches = Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'git.exe' -and $_.CommandLine -like '*${safePath}*' };`,
+    "if ($matches) { $matches | ForEach-Object { Stop-Process -Id $_.ProcessId -Force; $_.ProcessId }; }",
+  ].join(' ');
+  try {
+    const out = shared.execSilent(`powershell -NoProfile -Command "${ps.replace(/"/g, '\\"')}"`, { timeout: 2000, encoding: 'utf8' });
+    const killed = String(out || '').split(/\r?\n/).map(s => s.trim()).filter(Boolean).length;
+    if (killed > 0) log('info', `_killGitDescendantsForWorktree: killed ${killed} git.exe descendant(s) holding ${worktreePath}`);
+    return { killed };
+  } catch (e) {
+    log('warn', `_killGitDescendantsForWorktree: powershell probe failed: ${e.message}`);
+    return { killed: 0, error: e.message };
+  }
+}
+
+// W-mq5n1zx5 — Layer 3a: bump the rolling counters for quarantine rename
+// outcomes (attempts, success, successAfterRetry, fallbackForceRemove,
+// totalFailure). Best-effort; metrics failures must not break the
+// quarantine path. The shape lives under metrics._engine.worktreeQuarantineOutcomes
+// so it sits beside the other _engine.* engine-internal telemetry.
+function _bumpQuarantineOutcome(key, delta = 1) {
+  try {
+    shared.mutateMetrics((metrics) => {
+      if (!metrics._engine) metrics._engine = {};
+      if (!metrics._engine.worktreeQuarantineOutcomes) {
+        metrics._engine.worktreeQuarantineOutcomes = {
+          attempts: 0, success: 0, successAfterRetry: 0,
+          fallbackForceRemove: 0, totalFailure: 0,
+        };
+      }
+      const o = metrics._engine.worktreeQuarantineOutcomes;
+      o[key] = (o[key] || 0) + delta;
+      return metrics;
+    });
+  } catch (e) {
+    log('warn', `_bumpQuarantineOutcome(${key}): ${e.message}`);
+  }
+}
+
+
 // ─── assertCleanSharedWorktree (#2439) ──────────────────────────────────────
 // Engine-side preflight that prevents shared-branch (and PR-targeted reused —
 // see opts.quarantineOnUnsafe, issue #2996) dispatches from spawning into a
@@ -980,7 +1083,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
   // 1. Status probe (filesystem)
   let statusOut = '';
   try {
-    const r = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs });
+    const r = await execAsync(_statusPorcelainCmd(), { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs });
     statusOut = (r || '').toString().trim();
   } catch (e) {
     // W-mq1habhf: previously this bailed out with the bad worktree intact,
@@ -1186,7 +1289,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
 
   // 7. Re-verify
   try {
-    const r2 = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs });
+    const r2 = await execAsync(_statusPorcelainCmd(), { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs });
     const after = (r2 || '').toString().trim();
     if (after) {
       result.reason = 'dirty-after-clean';
@@ -1218,9 +1321,23 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
 // branch (assertCleanSharedWorktree returns 'other-dispatch-active' before
 // invoking this). Renaming an active worktree out from under a running
 // agent would be catastrophic.
+//
+// W-mq5n1zx5 — layered defense against Windows EBUSY: (Layer 2a) kill
+// lingering git.exe descendants whose command-line points at the worktree
+// before touching the path; (Layer 1a) retry the rename with jittered
+// backoff; (Layer 2b) if every retry still fails, fall back to
+// `git worktree remove --force` so git tears down its own metadata + dir
+// rather than leaving a half-quarantined tree behind; (Layer 3a) emit
+// outcome counters to metrics._engine.worktreeQuarantineOutcomes;
+// (Layer 3b) when EVERY path fails, write a dedicated inbox alert naming
+// the manual recovery command. The throw-or-return contract is unchanged
+// for callers: a thrown error means the caller's `result.quarantineError`
+// field is populated and `result.quarantined` stays false (env-blocked
+// path); a normal return means quarantine succeeded.
 async function _quarantineDirtyWorktree(rootDir, worktreePath, branchName, gitOpts, diag = {}) {
   const ts = Date.now();
   const quarantinedPath = `${worktreePath}-quarantine-${ts}`;
+  _bumpQuarantineOutcome('attempts', 1);
 
   // Capture HEAD sha BEFORE renaming so we can back up the local branch ref.
   let headSha = '';
@@ -1231,24 +1348,112 @@ async function _quarantineDirtyWorktree(rootDir, worktreePath, branchName, gitOp
     log('warn', `_quarantineDirtyWorktree: rev-parse HEAD failed for ${worktreePath}: ${e.message} — backup ref will be skipped`);
   }
 
-  // Rename the worktree dir. Once this succeeds the worktree is functionally
-  // quarantined; subsequent failures only affect ref bookkeeping.
   // W-mq5rwwss000f30a7 — never quarantine (=rename out from under) a worktree
   // that a live dispatch still claims. Quarantine breaks the agent's cwd just
-  // as completely as removeWorktree would.
+  // as completely as removeWorktree would. Check before any destructive work
+  // (including the kill-descendants sweep below) so we don't disturb a live
+  // agent's git child processes either.
   if (shared.isWorktreePathLive(worktreePath)) {
     log('warn', `_quarantineDirtyWorktree: skip — live dispatch in ${worktreePath}`);
     shared._writeWorktreeSkipLiveInboxNote(worktreePath, '_quarantineDirtyWorktree');
     return { quarantinedPath: null, backupRef: null, skipped: true };
   }
-  fs.renameSync(worktreePath, quarantinedPath);
 
-  // Prune git's stale worktree metadata so the next `git worktree add` for
-  // the same branch isn't blocked by "branch is already used by worktree".
+  // W-mq5n1zx5 Layer 2a: pre-emptively kill any git.exe descendants whose
+  // command line points at the worktree. The status-probe child that timed
+  // out earlier may still be alive holding packfile handles; if so, the
+  // rename below will fail with EBUSY/EPERM until the descendant exits.
+  // POSIX is a no-op. Best-effort; failure here is non-fatal.
+  _killGitDescendantsForWorktree(worktreePath);
+
+  // W-mq5n1zx5 Layer 1a: rename with jittered backoff. Replaces the bare
+  // `fs.renameSync(worktreePath, quarantinedPath)` that used to throw
+  // Windows EBUSY uncatchably and burn the WI's auto-recovery budget.
+  let renameAttempts = 0;
+  let renameError = null;
   try {
-    await shared.shellSafeGit(['worktree', 'prune'], { ...gitOpts, cwd: rootDir, timeout: 15000 });
+    const r = await _renameWithRetry(worktreePath, quarantinedPath);
+    renameAttempts = r.attempts || 1;
   } catch (e) {
-    log('warn', `_quarantineDirtyWorktree: worktree prune after rename: ${e.message}`);
+    renameError = e;
+  }
+
+  // W-mq5n1zx5 Layer 2b: if the rename retries exhausted, fall back to
+  // `git worktree remove --force`. This DESTROYS the worktree contents
+  // (no forensics dir), so it's last-resort only — gated on the
+  // quarantineForceRemoveFallback engine default. The next dispatch will
+  // create a fresh worktree on the origin tip, which is the same outcome
+  // the rename path would produce, just without the recovery dir.
+  let forceRemoved = false;
+  let forceRemoveError = null;
+  if (renameError && ENGINE_DEFAULTS.quarantineForceRemoveFallback) {
+    log('warn', `_quarantineDirtyWorktree: rename failed after ${renameAttempts || ENGINE_DEFAULTS.quarantineRenameRetryAttempts} attempt(s) (${renameError.code || renameError.message}); falling back to git worktree remove --force`);
+    try {
+      await shared.shellSafeGit(['worktree', 'remove', '--force', worktreePath], { ...gitOpts, cwd: rootDir, timeout: 30000 });
+      forceRemoved = true;
+      log('warn', `_quarantineDirtyWorktree: git worktree remove --force succeeded for ${worktreePath} (no quarantine dir preserved)`);
+    } catch (e) {
+      forceRemoveError = e;
+      log('error', `_quarantineDirtyWorktree: git worktree remove --force ALSO failed: ${e.message}`);
+    }
+  }
+
+  // If neither the rename retries nor the force-remove fallback succeeded,
+  // we are env-blocked: the worktree dir is still on disk and git still
+  // thinks it owns it. Write a dedicated inbox alert (Layer 3b) and rethrow
+  // the original rename error so the caller's quarantineError branch fires.
+  if (renameError && !forceRemoved) {
+    _bumpQuarantineOutcome('totalFailure', 1);
+    const sanitizedRefSegmentEnv = sanitizeBranch(branchName).replace(/\//g, '-');
+    const failBody = [
+      '# Engine quarantine TOTAL FAILURE — manual recovery required (W-mq5n1zx5)',
+      '',
+      `- Dispatch: ${diag.dispatchId || '<unknown>'}`,
+      `- Branch: ${branchName}`,
+      `- Worktree path (STILL PRESENT): ${worktreePath}`,
+      `- Reason: ${diag.reason || 'unsafe'}`,
+      `- Rename attempts: ${renameAttempts || ENGINE_DEFAULTS.quarantineRenameRetryAttempts}`,
+      `- Last rename error: ${renameError.code || ''} ${renameError.message}`,
+      `- Force-remove fallback: ${ENGINE_DEFAULTS.quarantineForceRemoveFallback ? `tried, failed (${forceRemoveError ? forceRemoveError.message : 'unknown'})` : 'disabled'}`,
+      '',
+      '## Manual recovery',
+      '',
+      '1. Find any live `git.exe` (or other) processes still holding the dir:',
+      `   \`Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*${worktreePath}*' }\``,
+      '2. Stop them: `Stop-Process -Id <pid> -Force`',
+      '3. Force-remove the dir:',
+      `   Windows: \`Remove-Item -Recurse -Force "${worktreePath}"\` (or \`rmdir /s /q "${worktreePath}"\` from cmd.exe)`,
+      `   POSIX:   \`rm -rf "${worktreePath}"\``,
+      `4. Prune git's stale worktree metadata: \`git -C "${rootDir}" worktree prune\``,
+      '',
+      'After this, the next dispatch for the branch will create a fresh worktree.',
+    ].join('\n');
+    try {
+      shared.writeToInbox('engine', `worktree-quarantine-failed-${diag.dispatchId || sanitizedRefSegmentEnv}`, failBody);
+    } catch (e) {
+      log('warn', `_quarantineDirtyWorktree: totalFailure writeToInbox failed: ${e.message}`);
+    }
+    throw renameError;
+  }
+
+  // Track outcome bucket for the successful path (rename or force-remove).
+  if (forceRemoved) {
+    _bumpQuarantineOutcome('fallbackForceRemove', 1);
+  } else if (renameAttempts > 1) {
+    _bumpQuarantineOutcome('successAfterRetry', 1);
+  }
+  _bumpQuarantineOutcome('success', 1);
+
+  // Prune git's stale worktree metadata so the next `git worktree add` for
+  // the same branch isn't blocked by "branch is already used by worktree".
+  // Skipped on the force-removed path — `git worktree remove --force` already
+  // wipes its own metadata entry.
+  if (!forceRemoved) {
+    try {
+      await shared.shellSafeGit(['worktree', 'prune'], { ...gitOpts, cwd: rootDir, timeout: 15000 });
+    } catch (e) {
+      log('warn', `_quarantineDirtyWorktree: worktree prune after rename: ${e.message}`);
+    }
   }
 
   // Backup the local branch HEAD to refs/minions/quarantine/<sanitized>/<ts>
@@ -1293,7 +1498,9 @@ async function _quarantineDirtyWorktree(rootDir, worktreePath, branchName, gitOp
     `- Dispatch: ${diag.dispatchId || '<unknown>'}`,
     `- Branch: ${branchName}`,
     `- Original worktree: ${worktreePath}`,
-    `- Quarantined to: ${quarantinedPath}`,
+    forceRemoved
+      ? `- Force-removed via \`git worktree remove --force\` (no quarantine dir preserved — W-mq5n1zx5 Layer 2b)`
+      : `- Quarantined to: ${quarantinedPath}${renameAttempts > 1 ? ` (rename took ${renameAttempts} attempt(s) — W-mq5n1zx5 Layer 1a)` : ''}`,
     `- Reason: ${diag.reason || 'unsafe'}`,
     `- Local commits ahead of origin: ${diag.ahead || 0}`,
     `- Local commits behind origin: ${diag.behind || 0}`,
@@ -1305,12 +1512,20 @@ async function _quarantineDirtyWorktree(rootDir, worktreePath, branchName, gitOp
     '',
     backupRefCreated
       ? `The local branch HEAD was backed up to \`${backupRef}\` (${headSha.slice(0, 12)}) and \`refs/heads/${branchName}\` was reset to \`refs/remotes/origin/${branchName}\`.`
-      : `Backup ref was NOT created (HEAD sha unavailable). The local branch ref was still reset to \`refs/remotes/origin/${branchName}\` if possible. Inspect the quarantined directory directly to recover unpushed work.`,
+      : `Backup ref was NOT created (HEAD sha unavailable). The local branch ref was still reset to \`refs/remotes/origin/${branchName}\` if possible.${forceRemoved ? ' Worktree contents were destroyed by the force-remove fallback — no quarantine dir to inspect.' : ' Inspect the quarantined directory directly to recover unpushed work.'}`,
     '',
-    `1. Inspect the quarantined diff: \`git -C "${rootDir}" diff refs/remotes/origin/${branchName}${backupRefCreated ? ` ${backupRef}` : ''} -- .\``,
-    `2. Cherry-pick the commits you want from \`${backupRefCreated ? backupRef : `<inspect ${quarantinedPath}>`}\` onto a fresh ${branchName} worktree.`,
-    `3. Inspect uncommitted edits inside the quarantined dir directly: \`${quarantinedPath}\`.`,
-    `4. Delete the quarantined dir when done: \`Remove-Item -Recurse -Force "${quarantinedPath}"\` (Windows) or \`rm -rf "${quarantinedPath}"\` (POSIX).`,
+    forceRemoved
+      ? `1. The worktree dir was force-removed; there is no quarantine dir to inspect. If the local branch ref still has divergent commits, recover from \`${backupRefCreated ? backupRef : 'reflog'}\`.`
+      : `1. Inspect the quarantined diff: \`git -C "${rootDir}" diff refs/remotes/origin/${branchName}${backupRefCreated ? ` ${backupRef}` : ''} -- .\``,
+    forceRemoved
+      ? ''
+      : `2. Cherry-pick the commits you want from \`${backupRefCreated ? backupRef : `<inspect ${quarantinedPath}>`}\` onto a fresh ${branchName} worktree.`,
+    forceRemoved
+      ? ''
+      : `3. Inspect uncommitted edits inside the quarantined dir directly: \`${quarantinedPath}\`.`,
+    forceRemoved
+      ? ''
+      : `4. Delete the quarantined dir when done: \`Remove-Item -Recurse -Force "${quarantinedPath}"\` (Windows) or \`rm -rf "${quarantinedPath}"\` (POSIX).`,
     backupRefCreated ? `5. Delete the backup ref when done: \`git -C "${rootDir}" update-ref -d ${backupRef}\`.` : '',
   ].filter(Boolean).join('\n');
   try {
@@ -1319,8 +1534,13 @@ async function _quarantineDirtyWorktree(rootDir, worktreePath, branchName, gitOp
     log('warn', `_quarantineDirtyWorktree: writeToInbox failed: ${e.message}`);
   }
 
-  log('warn', `Quarantined dirty worktree ${worktreePath} → ${quarantinedPath} (branch ${branchName}, ${diag.ahead || 0} ahead, ${diag.behind || 0} behind, ${dirtyFiles.length} dirty files)`);
-  return { quarantinedPath, backupRef: backupRefCreated ? backupRef : null };
+  log('warn', `Quarantined dirty worktree ${worktreePath} → ${forceRemoved ? '<force-removed>' : quarantinedPath} (branch ${branchName}, ${diag.ahead || 0} ahead, ${diag.behind || 0} behind, ${dirtyFiles.length} dirty files${renameAttempts > 1 ? `, rename retries=${renameAttempts}` : ''}${forceRemoved ? ', force-remove fallback' : ''})`);
+  return {
+    quarantinedPath: forceRemoved ? null : quarantinedPath,
+    backupRef: backupRefCreated ? backupRef : null,
+    forceRemoved,
+    renameAttempts,
+  };
 }
 
 async function recoverPartialWorktree(rootDir, worktreePath, branchName, gitOpts) {
@@ -2070,8 +2290,23 @@ async function spawnAgent(dispatchItem, config) {
         // no-upstream / dirty-after-clean stay non-retryable because they
         // protect potentially-unpushed agent work.
         const isStatusProbeFailed = cleanResult.reason === 'status-failed';
-        const failureClassValue = isDivergent ? FAILURE_CLASS.WORKTREE_DIVERGENT : FAILURE_CLASS.WORKTREE_DIRTY;
-        const failureClassName = isDivergent ? 'WORKTREE_DIVERGENT' : 'WORKTREE_DIRTY';
+        // W-mq5n1zx5 Layer 1c: when quarantine itself errored (rename retries
+        // + force-remove fallback all failed) the worktree dir is still on
+        // disk and the failure is purely environmental — a lingering git.exe
+        // descendant or AV scan holding handles. Route through a dedicated
+        // WORKTREE_QUARANTINE_ENV_BLOCKED class so the dispatch-side retry
+        // counter doesn't bump (agentRetryable:false → non-retryable branch
+        // → no _retriesByAgent / _retryCount mutation) and the WI auto-
+        // recovery loop in discoverFromWorkItems re-queues this item under
+        // the existing _quarantineRecoveryCount cap. This stops env failures
+        // from burning the per-agent retry budget the way they did before.
+        const isQuarantineEnvBlocked = !!(cleanResult.quarantineError && !cleanResult.quarantined);
+        const failureClassValue = isQuarantineEnvBlocked
+          ? FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED
+          : (isDivergent ? FAILURE_CLASS.WORKTREE_DIVERGENT : FAILURE_CLASS.WORKTREE_DIRTY);
+        const failureClassName = isQuarantineEnvBlocked
+          ? 'WORKTREE_QUARANTINE_ENV_BLOCKED'
+          : (isDivergent ? 'WORKTREE_DIVERGENT' : 'WORKTREE_DIRTY');
         const reasonMsg = cleanResult.quarantined
           ? `${failureClassName}: reused worktree at ${worktreePath} was dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} dirty file(s)${previewFiles ? ': ' + previewFiles : ''}) — quarantined to ${cleanResult.quarantinedPath}. Next dispatch will start fresh.`
           : `${failureClassName}: reused worktree at ${worktreePath} is dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} file(s)${previewFiles ? ': ' + previewFiles : ''}). Quarantine ${cleanResult.quarantineError ? 'errored: ' + cleanResult.quarantineError : (cleanResult.quarantineSkipped ? 'was skipped — another live dispatch claims the worktree (see notes/inbox/ engine-worktree-skip-live note).' : 'was not attempted (' + cleanResult.reason + ').')}`;
@@ -2081,7 +2316,7 @@ async function spawnAgent(dispatchItem, config) {
           id,
           DISPATCH_RESULT.ERROR,
           reasonMsg.slice(0, 500),
-          `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996). Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : (cleanResult.quarantineSkipped ? ' Quarantine was skipped because another live dispatch claims this worktree path; this dispatch will not auto-retry until the live claimant clears.' : '')}`,
+          `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996). Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : (cleanResult.quarantineSkipped ? ' Quarantine was skipped because another live dispatch claims this worktree path; this dispatch will not auto-retry until the live claimant clears.' : '')}${isQuarantineEnvBlocked ? ' Environmental quarantine failure (Windows EBUSY); WI auto-recovery loop will re-queue without bumping per-agent retry counter.' : ''}`,
           { agentRetryable: isStatusProbeFailed && cleanResult.quarantined, failureClass: failureClassValue },
         );
         cleanupTempAgent(agentId);
@@ -2260,7 +2495,10 @@ async function spawnAgent(dispatchItem, config) {
           let stashed = false;
           if (!depMergeFailed && !skipDepMerge && prunedDeps.length > 0) {
             try {
-              const statusOut = gitOutputToString(await shared.shellSafeGit(['status', '--porcelain'], { ..._gitOpts, cwd: worktreePath })).trim();
+              const statusArgs = ENGINE_DEFAULTS.statusProbeUseNoOptionalLocks
+                ? ['--no-optional-locks', 'status', '--porcelain']
+                : ['status', '--porcelain'];
+              const statusOut = gitOutputToString(await shared.shellSafeGit(statusArgs, { ..._gitOpts, cwd: worktreePath })).trim();
               if (statusOut) {
                 await shared.shellSafeGit(['stash', 'push', '--include-untracked', '-m', 'engine: stash before dep re-merge'], { ..._gitOpts, cwd: worktreePath });
                 stashed = true;
@@ -2501,7 +2739,7 @@ async function spawnAgent(dispatchItem, config) {
   if (worktreePath && fs.existsSync(worktreePath)) {
     _phaseT.dirtyProbeStart = Date.now();
     try {
-      const dirtyResult = await execAsync('git status --porcelain', { ..._gitOpts, cwd: worktreePath, timeout: 10000 });
+      const dirtyResult = await execAsync(_statusPorcelainCmd(), { ..._gitOpts, cwd: worktreePath, timeout: 10000 });
       const dirtyOutput = (dirtyResult.stdout || '').trim();
       if (dirtyOutput) {
         const dirtyFiles = dirtyOutput.split('\n').map(l => l.trim()).filter(Boolean);
@@ -5666,19 +5904,28 @@ async function discoverFromPrs(config, project) {
       // starvation guarantee.
       const conflictCauseKey = getPrAutomationCauseKey('merge-conflict', pr);
       const key = getPrAutomationDispatchKey(`conflict-fix-${project?.name || 'default'}-${prDisplayId}`, conflictCauseKey);
-      // W-mpritzcr0004afc5 (#2955): per-cause same-head guard mirroring the
-      // build-failure block above. `_conflictFixedAt` is a 10-min wall-clock
-      // suppression for ADO/GH mergeStatus lag; `_lastDispatchByCause` is a
-      // headSha-pinned suppression for repeated agent noops on an unchanged
-      // base+head pair. Both must fire (their windows are independent).
+      // W-mpritzcr0004afc5 (#2955) + #3079: per-cause same-head guard mirroring
+      // the build-failure block above. `_conflictFixedAt` is a 10-min wall-clock
+      // suppression for ADO/GH mergeStatus lag; `_lastDispatchByCause` is now
+      // a (head+base+targetRef)-pinned suppression for repeated agent noops on
+      // an unchanged source+base+target tuple. #3079: prior version compared
+      // only headSha, so retargeting a PR (e.g. parent-branch → main after
+      // parent merge) never released the pause even though the base SHA and
+      // target ref had changed and conflicts may have become resolvable.
+      const currentGuardKey = shared.prMergeConflictGuardKey(pr);
       const currentHeadSha = String(pr.headSha || pr._adoSourceCommit || pr._adoHeadCommit || '').trim();
       const lastConflictDispatch = pr._lastDispatchByCause?.[shared.PR_FIX_CAUSE.MERGE_CONFLICT];
-      const skipConflictFix = !!(lastConflictDispatch?.outcome === 'noop'
-        && lastConflictDispatch.headSha
+      // Prefer the new mergeConflictKey (post-#3079); fall back to legacy
+      // headSha compare so PRs paused before this fix don't loop forever.
+      const lastGuardKey = lastConflictDispatch?.mergeConflictKey;
+      const guardKeyMatches = !!(lastGuardKey && currentGuardKey && lastGuardKey === currentGuardKey);
+      const legacyHeadMatches = !lastGuardKey && !!(lastConflictDispatch?.headSha
         && currentHeadSha
         && lastConflictDispatch.headSha === currentHeadSha);
+      const skipConflictFix = !!(lastConflictDispatch?.outcome === 'noop'
+        && (guardKeyMatches || legacyHeadMatches));
       if (skipConflictFix) {
-        log('info', `Skipping conflict-fix for ${pr.id}: last merge-conflict dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} (${(lastConflictDispatch.reason || '').slice(0, 120)})`);
+        log('info', `Skipping conflict-fix for ${pr.id}: last merge-conflict dispatch was noop on the same source+base+target (${(lastConflictDispatch.reason || '').slice(0, 120)})`);
         continue;
       }
       // Suppress re-dispatch for 10 min after last attempt — ADO/GitHub recomputes
@@ -5966,6 +6213,18 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     // failure via the qa-session-draft-failed / qa-session-execute-failed
     // path. (See playbooks/qa-session-draft.md → "Failure path" section.)
     ..._buildRunnerBriefVars(item, project),
+    // W-mq16xtdx001a347e + W-mq1cczi90006b21f — escape hatches for dispatches
+    // that should NOT be steered toward project-local skills (e.g. when the
+    // diff under review IS that skill, so a meta-review needs first-principles).
+    // Default OFF — the project skills block is the whole point of these WIs
+    // and should surface on every applicable dispatch by default.
+    //
+    // Both meta names are honored:
+    //   - meta.skipProjectReviewSkills (PR-82 alias, review-only suppression)
+    //   - meta.skipProjectSkills       (W-mq1cczi90006b21f, generic suppression)
+    // Either flag suppresses both blocks on the dispatch.
+    skip_project_review_skills: !!(item.meta && item.meta.skipProjectReviewSkills),
+    skip_project_skills: !!(item.meta && (item.meta.skipProjectSkills || item.meta.skipProjectReviewSkills)),
   };
   const cpResult = buildWorkItemDispatchVars(item, vars, config, {
     worktreePath: vars.worktree_path || root,
@@ -6139,8 +6398,10 @@ function discoverFromWorkItems(config, project) {
       const fr = String(item.failReason || '');
       const isQuarantineFail = item._failureClass === FAILURE_CLASS.WORKTREE_DIRTY
         || item._failureClass === FAILURE_CLASS.WORKTREE_DIVERGENT
+        || item._failureClass === FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED
         || /\bWORKTREE_DIRTY\b/.test(fr)
-        || /\bWORKTREE_DIVERGENT\b/.test(fr);
+        || /\bWORKTREE_DIVERGENT\b/.test(fr)
+        || /\bWORKTREE_QUARANTINE_ENV_BLOCKED\b/.test(fr);
       if (isQuarantineFail) {
         item._quarantineRecoveryCount = (item._quarantineRecoveryCount || 0) + 1;
         const cap = ENGINE_DEFAULTS.quarantineAutoRecoveryMax || 2;
@@ -8270,6 +8531,7 @@ module.exports = {
   gitOutputToString, gitErrorOutput, classifyDepMergeFailureOutput, listUnmergedFiles, // exported for testing
   buildDepConflictFixItem, deriveConflictFixKey, // exported for testing (W-mpcwojgr000a0244)
   isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, assertCleanSharedWorktree, _quarantineDirtyWorktree, // exported for testing
+  _renameWithRetry, _statusPorcelainCmd, _killGitDescendantsForWorktree, _bumpQuarantineOutcome, // exported for testing (W-mq5n1zx5)
   pruneStaleWorktreeForBranch, // exported for testing
   findExistingWorktree, // exported for testing
   probeBranchOnRemote, // exported for testing (W-mphnm6a1000281b8)

package/package.json

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

package/playbooks/fix.md

@@ -44,6 +44,10 @@ Before editing, split the feedback into:
 
 ## Health Check
 
+{{#project_skills_block}}
+{{project_skills_block}}
+
+{{/project_skills_block}}
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{pr_branch}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
 
 ### Branch-mismatch guard (issue #2999)

package/playbooks/implement-shared.md

@@ -45,6 +45,10 @@ Do ALL work in the worktree.
 
 ## Health Check
 
+{{#project_skills_block}}
+{{project_skills_block}}
+
+{{/project_skills_block}}
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{branch_name}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
 
 ## Working Style

package/playbooks/implement.md

@@ -38,6 +38,10 @@ If this feature spans multiple projects, inspect the relevant repos, make change
 
 ## Health Check
 
+{{#project_skills_block}}
+{{project_skills_block}}
+
+{{/project_skills_block}}
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch. If the worktree is dirty or on the wrong branch, report the issue and stop.
 
 ## Working Style

package/playbooks/plan-to-prd.md

@@ -17,6 +17,10 @@ A user has provided a plan. Analyze it against the codebase and produce a struct
 
 ## Instructions
 
+{{#project_skills_block}}
+{{project_skills_block}}
+
+{{/project_skills_block}}
 1. **Read the plan carefully** — understand the goals, scope, and requirements
    - If the plan declares `Project: <name>` (including `**Project:** <name>`), the engine has resolved `{{project_name}}` from that declaration. Preserve `{{project_name}}` for the top-level `project`, default item `project`, filename, and implementation framing; do not let contextual mentions of another product or repository override it.
 2. **Check for an existing PRD** — if the engine provides `existing_prd_json` below, a PRD already exists for this plan. See "Reusing an Existing PRD" section for how to preserve item IDs and done statuses. If no existing PRD is provided, this is a fresh run — all items start as `"missing"`.

package/playbooks/plan.md

@@ -27,6 +27,10 @@ A user has described a feature they want built. Your job is to create a detailed
 - Identify the core goal, constraints, and success criteria
 - Note any ambiguities that need to be called out
 
+{{#project_skills_block}}
+{{project_skills_block}}
+
+{{/project_skills_block}}
 ### 2. Explore the Codebase
 - Read `CLAUDE.md` at repo root and relevant directories
 - Map the areas of code that this feature will touch

package/playbooks/review.md

@@ -27,10 +27,10 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    git diff {{main_branch}}...origin/{{pr_branch}}
    ```
 
-{{#project_review_skills_block}}
-{{project_review_skills_block}}
+{{#project_skills_block}}
+{{project_skills_block}}
 
-{{/project_review_skills_block}}
+{{/project_skills_block}}
 2. Think about deploy risk before commenting:
    - What user-visible behavior changed?
    - What dependencies, callers, or tests could be affected?

package/bin/minions.js.rej

@@ -1,16 +0,0 @@
-diff a/bin/minions.js b/bin/minions.js	(rejected hunks)
-@@ -852,6 +852,14 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
- 
-   Dashboard:
-     minions dash                     Start web dashboard (default :7331)
-+
-+  Watchdog (out-of-process recovery):
-+    minions watchdog install [--interval=5]
-+                                      Register OS scheduler task to probe + heal every N minutes
-+                                      (Windows Task Scheduler / macOS launchd / Linux systemd --user)
-+    minions watchdog uninstall       Remove the scheduled task (idempotent)
-+    minions watchdog status          Show registration + last-run details from the OS scheduler
-+    minions watchdog tick            One-shot probe + recovery (used by the scheduler; safe to run by hand)
- ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
-   Dev mode (this checkout, contributors only):
-     minions --dev <cmd>              Run against this checkout instead of ~/.minions/

package/dashboard/slim/body.html.rej

@@ -1,11 +0,0 @@
-diff a/dashboard/slim/body.html b/dashboard/slim/body.html	(rejected hunks)
-@@ -8,7 +8,8 @@
-          silently break (handler attaches before crash, button still renders,
-          click fires but no global handler). addEventListener attaches inside
-          the same scope and is observable in DevTools when wiring fails. -->
--    <button id="slim-new-chat-btn" class="icon-btn" title="New chat (opens a new tab)">&#x270E;</button>
-+    <button id="slim-back-classic-btn" class="topbar-back-btn" title="Return to the classic dashboard">&#8592; Classic dashboard</button>
-+    <button id="slim-report-bug-btn" class="topbar-back-btn" title="Report a bug in Minions">Report Bug</button>
-     <button id="slim-settings-btn" class="icon-btn" title="Settings">&#9881;</button>
-   </div>
- </div>

package/dashboard/slim/js/command-send.js.rej

@@ -1,12 +0,0 @@
-diff a/dashboard/slim/js/command-send.js b/dashboard/slim/js/command-send.js	(rejected hunks)
-@@ -195,8 +195,8 @@
-   }
- 
-   // ── Wiring ──────────────────────────────────────────────────────
--  var newChatBtn = document.getElementById('slim-new-chat-btn');
--  if (newChatBtn) newChatBtn.addEventListener('click', function() { newTab(); });
-+  // (The header "new chat" button was replaced by "Report Bug"; new tabs are
-+  // created via the "+" affordance in the chat tab bar — see renderTabBar.)
-   sendBtn.addEventListener('click', sendMessage);
-   stopBtn.addEventListener('click', abortActive);
-   inputEl.addEventListener('keydown', function(ev) {

package/dashboard/slim/js/history.js.rej

@@ -1,26 +0,0 @@
-diff a/dashboard/slim/js/history.js b/dashboard/slim/js/history.js	(rejected hunks)
-@@ -96,7 +83,12 @@
-       chip.title = 'review';
-     } else {
-       chip.className = 'completions-card-type-chip';
--      chip.textContent = typeEmoji(c.type);
-+      // Known types → Fluent icon via CSS mask (data-type); unknown → "•" glyph.
-+      if (c.type && TYPE_ICON_SET[c.type]) {
-+        chip.setAttribute('data-type', c.type);
-+      } else {
-+        chip.textContent = '•';
-+      }
-       if (c.type) chip.title = c.type;
-     }
-     railTop.appendChild(chip);
-@@ -105,7 +97,9 @@
-     railBottom.className = 'completions-card-rail-bottom';
-     var icon = document.createElement('span');
-     icon.className = 'completions-card-status-icon ' + status;
--    icon.textContent = status === 'active' ? '●' : (status === 'ok' ? '✓' : (status === 'warn' ? '⚠' : '✕'));
-+    // ok/warn/fail render as Fluent icons via the status class (CSS mask in
-+    // styles.css); the live 'active' state keeps its pulsing dot.
-+    if (status === 'active') icon.textContent = '●';
-     icon.title = status === 'active' ? 'Running' : (status === 'ok' ? 'Success' : (status === 'warn' ? 'Partial' : 'Failure'));
-     var sep = document.createElement('span');
-     sep.className = 'completions-card-rail-sep';