@yemi33/minions 0.1.2148 → 0.1.2150

package/docs/worktree-lifecycle.md

@@ -0,0 +1,164 @@
+# Worktree Lifecycle
+
+Deep-dive for the four engine pieces that own git-worktree state for dispatch:
+the **pool** (recycling), the **live guard** (don't wipe an agent's work),
+the **quarantine path** (dirty/divergent → quarantine dir + retry), and the
+**Windows file-lock retry** (EPERM/EBUSY footgun). CLAUDE.md → Worktree
+Lifecycle keeps the cross-cutting invariants; the detail lives here.
+
+> Source of truth: `engine/worktree-pool.js`, `engine/shared.js#removeWorktree`
+> + `_retryFsOp`, `engine.js` (`_quarantineDirtyWorktree`, `_renameWithRetry`,
+> `_killGitDescendantsForWorktree`, `pruneOrphanWorktrees*`, `gcDispatchWorktreeIfOrphan`),
+> `engine/cleanup.js`. Last verified: 2026-06-09.
+
+## Live-worktree guard (W-mq5rwwss000f30a7)
+
+**Invariant:** every code path that wipes, renames, or recycles a worktree
+MUST call `shared.isWorktreePathLive(path, { db?, excludeDispatchId? })`
+first and skip on `true`. Originally added after W-mq5n1zx5000hcfb5 — an
+agent's worktree was wiped 4× consecutively by the reaper while the
+dispatch was still active.
+
+- **Backed by SQL** against `dispatches` (status IN ('pending','active')),
+  reading `json_extract(data, '$.worktreePath')` with a `data.meta.worktreePath`
+  fallback. The pending → active transition persists `item.worktreePath`
+  on the dispatch row so the guard has a path to correlate.
+- **Fails OPEN** (returns `true`) when SQLite is unreachable or the query
+  throws — better to leak a worktree than nuke an agent's unpushed work.
+- **Wired sites:** `shared.removeWorktree` (accepts `{ excludeDispatchId }`
+  forwarded to the guard); pool-return chain in `engine.js`
+  (`excludeDispatchId: id` so the dispatch can clean up its own worktree);
+  dispatch-end orphan GC (`gcDispatchWorktreeIfOrphan`); `_quarantineDirtyWorktree`
+  (returns `{ skipped: true, quarantinedPath: null }` on skip — callers
+  MUST honor `skipped` and not set `quarantined: true`); `engine/cleanup.js`
+  orphan-dir sweep.
+- **On skip:** drops a deduped operator note at
+  `notes/inbox/engine-worktree-skip-live-<basename>-<date>.md`.
+
+## Worktree pool (opt-in)
+
+`ENGINE_DEFAULTS.worktreePoolSize > 0` enables `engine/worktree-pool.js` to
+recycle worktree dirs across branches.
+
+- **Borrow** in `spawnAgent` only when (a) the new branch doesn't exist on
+  origin AND (b) the dispatch is not shared-branch / `useExistingBranch`.
+- **Return** in `onAgentClose` BEFORE `completeDispatch`:
+  `git reset --hard HEAD` → `git clean -fd` → `git fetch origin <main>`
+  → `git checkout --detach origin/<main>` → mark IDLE.
+- **State** at `engine/worktree-pool.json`; git ops outside any lock.
+
+## Quarantine path (dirty / divergent)
+
+When `discoverFromWorkItems` finds a worktree in a `WORKTREE_DIRTY`,
+`WORKTREE_DIVERGENT`, or post-stuck state, `_quarantineDirtyWorktree`
+moves it to `<root>/.quarantined/<basename>-<utc>` and lets the next tick
+recreate a clean worktree. Six layered defenses cover the Windows EBUSY
+race when git status descendants still hold packfile handles
+(W-mq5n1zx5000hcfb5; PR #3156).
+
+### Layer 1b — `--no-optional-locks` on every status probe (load-bearing)
+
+`_statusPorcelainCmd()` emits `git --no-optional-locks status …`. Skips
+the `.git/index.lock` acquire around the untracked-cache refresh inside
+`status`. Typical probe duration under AV scanning drops from 6–12s to
+<500ms, which removes the timeout that leaks the child in the first
+place. **Most incidents are closed by 1b alone.**
+Toggle: `ENGINE_DEFAULTS.statusProbeUseNoOptionalLocks` (default `true`).
+
+### Layer 1a — `_renameWithRetry` with jittered backoff
+
+6 attempts × 250 ms base × 2^N exponential + 200 ms random jitter
+(~16 s worst-case). Only retries on `EBUSY|EPERM|EACCES|ENOTEMPTY`;
+rethrows other codes immediately. Toggles:
+`ENGINE_DEFAULTS.quarantineRenameRetryAttempts` (6),
+`quarantineRenameRetryBaseMs` (250).
+
+### Layer 2a — `_killGitDescendantsForWorktree` (Windows-only)
+
+PowerShell sweep, 2 s timeout. Shell-out built via single-quoted literal
+(`'` escaped as `''`) so worktree-path interpolation is injection-safe.
+POSIX no-op. Best-effort — failure logged, never throws.
+Toggle: `ENGINE_DEFAULTS.statusProbeKillDescendantsWin32` (default `true`).
+
+### Layer 2b — `git worktree remove --force` fallback
+
+Triggers only when 1a exhausts retries; destroys worktree contents (no
+quarantine dir preserved). Toggle:
+`ENGINE_DEFAULTS.quarantineForceRemoveFallback` (default `true`).
+
+### Layer 1c — `FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED`
+
+Routed when `cleanResult.quarantineError && !cleanResult.quarantined`.
+Added to `dispatch.js#isRetryableFailureReason` never-retry set so the
+per-agent retry counter doesn't bump (env failure, not the agent's fault).
+The auto-recovery loop in `engine.js#discoverFromWorkItems` recognizes
+the new class via both enum check and regex on legacy `failReason`
+strings, then re-queues under the existing
+`ENGINE_DEFAULTS.quarantineAutoRecoveryMax` (default 2) cap.
+
+### Layer 3a/3b — metrics + inbox alert
+
+Counters at
+`metrics._engine.worktreeQuarantineOutcomes.{attempts, success, successAfterRetry, fallbackForceRemove, totalFailure}`.
+Total-failure path writes a structured inbox alert with the exact
+PowerShell/POSIX recovery commands and `git worktree prune` instructions.
+
+### Auto-recovery cap
+
+`discoverFromWorkItems` auto-recovers `WORKTREE_DIRTY`/`WORKTREE_DIVERGENT`
+quarantine (#2996) up to `ENGINE_DEFAULTS.quarantineAutoRecoveryMax`
+(default 2, tracked on `_quarantineRecoveryCount`); after the cap,
+`_quarantineRecoveryGaveUp` triggers a warn-once.
+
+## Windows file-lock on removal (footgun #6 detail)
+
+`fs.rmSync` against an active git worktree can lose to lingering file
+handles (CC log streams, virus scanners, Explorer previews).
+`shared.removeWorktree` retries via `shared._retryFsOp`
+(`worktreeRemoveRetryAttempts` × exponential `worktreeRemoveRetryBaseMs`,
+codes `EPERM|EBUSY|EACCES|ENOTEMPTY`).
+
+After `worktreeStuckThreshold` consecutive failures the path is
+**escalated**:
+
+- A `notes/inbox/engine-worktree-stuck-<basename>-<date>.md` note with
+  Windows holder-identification hints is written (deduped per UTC day).
+- Per-tick warns are suppressed for `worktreeStuckSuppressMs`.
+- The retry cadence drops to `worktreeStuckSlowRetryMs`.
+- When the holder finally releases, a
+  `worktree-recovered-<basename>` note clears the alert.
+
+**Don't fight this with `fs.rmSync({force:true})` outside
+`removeWorktree`** — you'll bypass the retry, escalation, and metrics
+layers.
+
+## Periodic prune (W-mq5o6bvy000x7191)
+
+`pruneWorktreesPeriodic` runs `pruneOrphanWorktrees` (in-root) +
+`pruneOrphanWorktreesFromGitRegistry` (out-of-root via
+`git worktree list --porcelain`) per project at
+`ENGINE_DEFAULTS.worktreePruneIntervalTicks` cadence — catches Windows
+EPERM/EBUSY stragglers that the dispatch-end GC couldn't reap and sweeps
+the `git worktree list` registry for OUT-of-root entries the in-root
+scanner is blind to.
+
+## Holder identification + opt-in auto-reap (W-mq6f2fe0000557fa)
+
+Orphan-sweep escalations also run `shared.findProcessesWithCwdInside(wt)`
+(cross-platform: PowerShell `Get-CimInstance Win32_Process` on Windows;
+`/proc/*/cwd` walk on Linux; `lsof -d cwd` + `ps` on macOS) and append a
+`## Live holders` section listing pid / cmdline / age to the
+`engine-worktree-stuck-<basename>` escalation note.
+
+Setting `engine.autoReapOrphanWorktreeHolders: true`
+(Settings → Worker Pool & Worktrees → "Auto-reap orphan worktree holders")
+additionally kills any holder whose `cmdline` matches `spawn-agent.js`
+AND references the worktree basename AND whose age exceeds
+`engine.agentTimeout * 2`, then retries `removeWorktree` once. Default
+**OFF** — killing a foreign process is destructive.
+
+- Scan timeout: `engine.orphanHolderScanTimeoutMs` (default 5000ms,
+  clamped 1000–30000).
+- Motivating incident: W-mq1k8z6o003acd89 / stuck `spawn-agent.js`
+  PID 16828 that the periodic prune couldn't shake loose without manual
+  intervention.

package/engine/ado.js

@@ -395,6 +395,24 @@ function applyAdoPrMetadata(pr, prData) {
     updated = true;
   }
 
+  // #3079 — Track target ref + clear stale merge-conflict dispatch state
+  // when the PR is retargeted. The same-head guard at engine.js:5676 and
+  // the MERGE_CONFLICT fingerprint at shared.js:6595 are now target-aware
+  // (via shared.prMergeConflictGuardKey), but pre-existing
+  // _lastDispatchByCause[MERGE_CONFLICT] / _noOpFixes[MERGE_CONFLICT]
+  // records would still block re-dispatch until something else cleared
+  // them. Reset them explicitly on retarget. First-poll seeding
+  // (no prior targetRefName) is a no-op so we don't strip state immediately
+  // after upsert.
+  const nextTargetRef = String(prData.targetRefName || '').trim();
+  if (nextTargetRef && pr.targetRefName !== nextTargetRef) {
+    if (shared.resetMergeConflictStateOnRetarget(pr, nextTargetRef)) {
+      log('info', `ADO: PR ${pr.id || '?'} retargeted ${pr.targetRefName} → ${nextTargetRef}, clearing stale MERGE_CONFLICT dispatch records`);
+    }
+    pr.targetRefName = nextTargetRef;
+    updated = true;
+  }
+
   return updated;
 }
 
@@ -2600,6 +2618,7 @@ module.exports = {
   fetchAdoPrMetadata,
   fetchSinglePrBuildStatus,
   findOpenPrOnBranch,
+  applyAdoPrMetadata, // #3079 — exported for unit tests of targetRefName + retarget reset
   _resetAdoThrottle, // exported for testing
   _setAdoThrottleForTest, // exported for testing
   _setAdoTokenForTest, // exported for testing

package/engine/cli.js

@@ -163,8 +163,9 @@ function handleCommand(cmd, args) {
     //
     // `minions work --help` used to create ghost work items with title='--help'
     // because the bare-string `title` was truthy and bypassed the `!title`
-    // usage check. Same class of bug exists in `spawn`/`plan`/`complete` —
-    // every command that takes a positional arg and tests it with `if (!arg)`.
+    // usage check. The fix lives in per-command guards (`_isHelpArg` /
+    // `looksLikeFlagOrHelp`) on `work`/`spawn`/`plan`/`complete`, which print
+    // command-specific `Usage:` output. `pr` and `bridge` handle help inline.
     //
     // Intercept here so a single guard covers the whole command set. `pr` and
     // `bridge` already handle `help`/`--help`/`-h` inline (see their own

package/engine/dispatch.js

@@ -400,6 +400,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.WORKTREE_PREFLIGHT, // pre-spawn worktree validation — recompute will produce the same failure
       FAILURE_CLASS.WORKTREE_DIRTY,     // #2996: reused worktree was dirty and could not be auto-healed — non-retryable for this dispatch attempt; the engine quarantined the worktree so the next discovery cycle creates a fresh one
       FAILURE_CLASS.WORKTREE_DIVERGENT, // #2996: reused worktree's local branch had unpushed commits — engine quarantined + backed up the local ref; non-retryable for this dispatch (next discovery creates fresh worktree on origin/<branch>)
+      FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED, // W-mq5n1zx5: quarantine rename couldn't release the worktree dir even after retry + force-remove fallback. Non-retryable at the dispatch level so the per-agent retry counter isn't bumped (environmental, not the agent's fault); the WI auto-recovery loop in engine.js#discoverFromWorkItems re-queues without touching _retriesByAgent.
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR, // W-mp6k7ywi000fa33c — keep-pids cwd is not a real git worktree; re-running won't fix the structural issue
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA, // W-mp7i902u000l991f — keep-pids.json failed shape validation; re-running with the same wrong file won't fix it
       FAILURE_CLASS.INVALID_MANAGED_SPAWN, // W-mpbhxg3b000u8411 — managed-spawn.json failed validation; re-running with the same wrong file won't fix it
@@ -770,6 +771,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
             [FAILURE_CLASS.WORKTREE_PREFLIGHT]: 'worktree preflight rejected (nested in project root or rootDir collapsed to drive root)',
             [FAILURE_CLASS.WORKTREE_DIRTY]: 'reused worktree had uncommitted edits and could not be auto-healed (#2996) — engine quarantined the dir so the next dispatch creates a fresh worktree',
             [FAILURE_CLASS.WORKTREE_DIVERGENT]: 'reused worktree had unpushed local commits ahead of origin (#2996) — engine backed up the local ref and quarantined the dir so the next dispatch starts from origin/<branch>',
+            [FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED]: 'quarantine rename was blocked by the OS (Windows EBUSY/EPERM) even after retry + force-remove fallback — environmental, not the agent\'s fault; auto-recovery loop will re-queue without bumping per-agent retries',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR]: 'keep_processes cwd is not a real git worktree (rerun in a `git worktree add` directory)',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA]: 'keep-pids.json failed shape validation (wrong keys/types/values — see inbox alert for the canonical shape)',
             [FAILURE_CLASS.INVALID_MANAGED_SPAWN]: 'managed-spawn.json failed validation (bad schema, workdir, or allowlist — see inbox alert)',

package/engine/github.js

@@ -748,6 +748,20 @@ async function pollPrStatus(config) {
       updated = true;
     }
 
+    // #3079 — Track GitHub target branch name + clear stale merge-conflict
+    // dispatch state when the PR is retargeted (e.g. `gh pr edit --base
+    // master` after parent PR merges). Mirrors ado.js applyAdoPrMetadata.
+    // First-poll seeding (no prior baseRefName) is a no-op so we don't
+    // strip state immediately after upsert.
+    const nextBaseRefName = String(prData.base?.ref || '').trim();
+    if (nextBaseRefName && pr.baseRefName !== nextBaseRefName) {
+      if (shared.resetMergeConflictStateOnRetarget(pr, nextBaseRefName)) {
+        log('info', `GitHub: PR ${pr.id} retargeted ${pr.baseRefName} → ${nextBaseRefName}, clearing stale MERGE_CONFLICT dispatch records`);
+      }
+      pr.baseRefName = nextBaseRefName;
+      updated = true;
+    }
+
     // P-w1a3f9b2 — Phase 1.1: plumb mergeable / isDraft / mergeStateStatus /
     // headRefOid onto the PR object so watches captureState (engine/watches.js)
     // and future predicates (Phase 2.1: head-commit-change, mergeable-flipped,

package/engine/lifecycle.js

@@ -2291,6 +2291,15 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
           return out;
         })()
       : {}),
+    // #3079 — MERGE_CONFLICT noops record the composite guard key (source
+    // head + base SHA + target ref name). The same-head guard at
+    // engine.js:5676 reads this back and compares against the current
+    // PR's prMergeConflictGuardKey, so a retarget (target ref change) or
+    // a parent-merge (base SHA change) naturally releases the pause even
+    // when the source head didn't move.
+    ...(cause === shared.PR_FIX_CAUSE.MERGE_CONFLICT
+      ? { mergeConflictKey: shared.prMergeConflictGuardKey(target) }
+      : {}),
   };
   target.lastDispatchedAt = now;
   target.lastDispatchOutcome = 'noop';
@@ -2664,6 +2673,14 @@ function updatePrAfterFixError(pr, project, source, options = {}) {
           || '');
       if (commentKey) next.lastProcessedCommentKey = commentKey;
     }
+    // #3079 — Refresh mergeConflictKey from live target state so a
+    // mid-flight retarget reflects in the agent-error record too. The
+    // engine.js skipConflictFix guard prefers mergeConflictKey over
+    // legacy headSha; without this refresh, the prior record's stale
+    // key could re-fire the suppression even after a retarget.
+    if (cause === shared.PR_FIX_CAUSE.MERGE_CONFLICT) {
+      next.mergeConflictKey = shared.prMergeConflictGuardKey(target);
+    }
     target._lastDispatchByCause[cause] = next;
     result = { cause, indeterminate: true, errorClass };
     log('warn', `Updated ${pr.id} → recorded ${cause} agent-error fix attempt (indeterminate=true) — same-head guard relaxed for next tick${errorMessage ? ` (${errorMessage.slice(0, 80)})` : ''}`);

package/engine/shared.js

@@ -2352,6 +2352,30 @@ const ENGINE_DEFAULTS = {
   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.
   prNoOpFixPauseAttempts: 2, // pause one PR automation cause after repeated no-op fixes for unchanged evidence
   quarantineAutoRecoveryMax: 2, // #2996 follow-up: cap on auto-flipping WORKTREE_DIRTY/WORKTREE_DIVERGENT failures back to pending (the quarantine is self-healing so the next dispatch starts clean; the cap prevents infinite loops if quarantine itself keeps failing).
+  // W-mq5n1zx5 — Layer 1a/2b: harden the quarantine rename path against
+  // Windows EBUSY/EPERM races where a lingering `git.exe` descendant (leaked
+  // by a status-probe timeout) still holds packfile handles when we try to
+  // rename the worktree dir out of the way. With these on, the engine
+  // retries the rename with jittered backoff (worst case ≈ baseMs * 2^N + N
+  // jitter), then — if everything still fails — asks git to tear down its
+  // own worktree record via `git worktree remove --force` so the next
+  // dispatch isn't blocked by a half-renamed tree. Each knob is overridable
+  // via `config.engine.<name>`.
+  quarantineRenameRetryAttempts: 6,
+  quarantineRenameRetryBaseMs: 250,
+  quarantineForceRemoveFallback: true,
+  // W-mq5n1zx5 — Layer 1b/2a: pre-empt the EBUSY race itself. (1b)
+  // `--no-optional-locks` tells git to skip the .git/index.lock acquire
+  // around the untracked-cache refresh in status; typical probe duration
+  // under AV drops from 6–12s to <500ms, removing the timeout that
+  // creates the leaked child in the first place. (2a) On Windows only,
+  // before attempting the rename we walk live git.exe processes whose
+  // command line points at the worktree path and Stop-Process them, so
+  // a still-alive descendant from a previous status probe doesn't pin
+  // packfile handles. Both gates are belt-and-suspenders — most
+  // incidents are closed by (1b) alone — but both are cheap and idempotent.
+  statusProbeUseNoOptionalLocks: true,
+  statusProbeKillDescendantsWin32: true,
   completionReportRetentionDays: 90, // retain completion report sidecars beyond capped dispatch history
   completionReportMaxFiles: 5000, // hard cap for completion report sidecars during cleanup
   // P-bfa2c-cors-wildcard: extra Origins permitted to receive an
@@ -2538,6 +2562,17 @@ const ENGINE_DEFAULTS = {
   worktreeStuckThreshold: 10,               // consecutive removal failures before escalation
   worktreeStuckSuppressMs: 60 * 60 * 1000,  // 60min — suppress per-tick warn after escalation
   worktreeStuckSlowRetryMs: 30 * 60 * 1000, // 30min — slow-cadence retry window after escalation
+  // W-mq6f2fe0000557fa — orphan-worktree GC: identify the OS process holding
+  // a stuck worktree's cwd and, behind this opt-in flag, kill it. Default OFF
+  // because killing a foreign process is destructive; flipping on rescues the
+  // engine from the W-mq1k8z6o003acd89 / PID 16828 lock-spin pattern automatically.
+  // Auto-reap only fires for processes whose cmdline matches `spawn-agent.js`
+  // AND whose age exceeds `agentTimeout * 2` AND that have no live dispatch row
+  // — i.e. unambiguous orphan agents the engine forgot about. The holder scan
+  // itself ALWAYS runs on every orphan-sweep escalation (the flag only gates
+  // the kill); holder details are appended to the inbox note either way.
+  autoReapOrphanWorktreeHolders: 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)
   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)
@@ -3682,6 +3717,7 @@ const FAILURE_CLASS = {
   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.
+  WORKTREE_QUARANTINE_ENV_BLOCKED: 'worktree-quarantine-env-blocked', // W-mq5n1zx5: quarantine rename was attempted but the OS refused to release the worktree dir (Windows EBUSY/EPERM/EACCES from a lingering git.exe descendant). Engine retried with jittered backoff and (when enabled) `git worktree remove --force`; if all paths failed we surface this dedicated class so the WI auto-recovery loop can re-queue WITHOUT bumping the per-agent retry counter (the failure is environmental, not the agent's fault).
   DEPENDENCY_MERGE_SETUP: 'dependency-merge-setup', // Dependency pre-merge plumbing (stash/status/reset) failed before a real file conflict was verified. Retryable so a fresh worktree can recover.
   INVALID_KEEP_PROCESSES_WORKDIR: 'invalid-keep-processes-workdir', // W-mp6k7ywi000fa33c: keep-pids.json declared a cwd that is not a real git worktree (likely a selective copy of the repo) — never retryable; agent must rerun in a real worktree
   INVALID_KEEP_PROCESSES_SCHEMA: 'invalid-keep-processes-schema', // W-mp7i902u000l991f: keep-pids.json failed validation for a reason other than workdir (pids-missing, ttl-too-long, expires_at-missing, pids-too-many, port-invalid, etc.) — agent wrote the wrong shape; never retryable until they fix the file
@@ -6239,6 +6275,189 @@ function listAllProcesses() {
   return process.platform === 'win32' ? _winListProcesses() : _unixListProcesses();
 }
 
+// W-mq6f2fe0000557fa — orphan-worktree GC: identify OS processes whose cwd
+// is at or inside `dir`. Cross-platform with a fail-open contract: on any
+// error or timeout we return [] (the caller continues with its existing
+// escalation path and an unenriched note).
+//
+// Return shape: [{ pid, cmdline, startedAt, ageMs }, ...]
+//   - pid: numeric OS pid
+//   - cmdline: full command line as a single string (best-effort; possibly truncated)
+//   - startedAt: ms-since-epoch process start time (0 when unknown)
+//   - ageMs: Date.now() - startedAt (0 when startedAt is 0)
+//
+// Platform notes:
+//   - Windows: PowerShell `Get-CimInstance Win32_Process` filtered by the
+//     worktree basename appearing in CommandLine. (Win32_Process does not
+//     expose the working directory; the basename match is the most-reliable
+//     heuristic — every spawn-agent invocation embeds the dispatch id, which
+//     is the worktree basename, in its argv.)
+//   - Linux: walk `/proc/*/cwd` and keep PIDs whose readlinkSync resolves
+//     under `dir`. Cmdline read from `/proc/<pid>/cmdline` (NUL-separated).
+//     Start time derived from stat() mtime of the cwd entry as a proxy.
+//   - macOS: `lsof -F p -d cwd` filtered by directory, then `ps -p <pid>` for
+//     cmdline + start time.
+function findProcessesWithCwdInside(dir, opts = {}) {
+  if (!dir || typeof dir !== 'string') return [];
+  let resolved;
+  try { resolved = path.resolve(dir); } catch { return []; }
+  if (!resolved) return [];
+  const timeoutMs = Number(opts.timeoutMs) > 0
+    ? Number(opts.timeoutMs)
+    : (ENGINE_DEFAULTS.orphanHolderScanTimeoutMs || 5000);
+  const now = Date.now();
+
+  try {
+    if (process.platform === 'win32') {
+      return _findWindowsProcessesWithCwdInside(resolved, timeoutMs, now);
+    }
+    if (process.platform === 'linux') {
+      return _findLinuxProcessesWithCwdInside(resolved, timeoutMs, now);
+    }
+    return _findMacProcessesWithCwdInside(resolved, timeoutMs, now);
+  } catch { return []; }
+}
+
+function _findWindowsProcessesWithCwdInside(resolved, timeoutMs, now) {
+  // Win32_Process exposes CommandLine but not the cwd. Match by basename of
+  // the worktree dir (the dispatch id like W-mq1k8z6o003acd89) appearing in
+  // the cmdline — every spawn-agent prompt-file path embeds it.
+  const basename = path.basename(resolved);
+  if (!basename || basename.length < 3) return [];
+  // PowerShell-quote: outer escape ' as ''
+  const psBasename = basename.replace(/'/g, "''");
+  const psResolved = resolved.replace(/'/g, "''");
+  // Use -like with wildcards on BOTH basename and full path so a process
+  // whose cmdline carries the worktree dir (but a different basename
+  // anywhere in argv) also matches.
+  const script = `Get-CimInstance Win32_Process | Where-Object { ($_.CommandLine -like '*${psBasename}*') -or ($_.CommandLine -like '*${psResolved}*') } | ForEach-Object { [PSCustomObject]@{ pid = $_.ProcessId; cmdline = $_.CommandLine; startedAt = if ($_.CreationDate) { [int64](([datetimeoffset]$_.CreationDate).ToUnixTimeMilliseconds()) } else { 0 } } } | ConvertTo-Json -Compress -Depth 2`;
+  let raw;
+  try {
+    raw = _execSync(
+      `powershell -NoProfile -NonInteractive -Command "${script}"`,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }
+    );
+  } catch { return []; }
+  if (!raw || !String(raw).trim()) return [];
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { return []; }
+  const arr = Array.isArray(parsed) ? parsed : [parsed];
+  const out = [];
+  for (const r of arr) {
+    if (!r) continue;
+    const pid = Number(r.pid);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    const startedAt = Number(r.startedAt) || 0;
+    out.push({
+      pid,
+      cmdline: r.cmdline ? String(r.cmdline) : '',
+      startedAt,
+      ageMs: startedAt > 0 ? Math.max(0, now - startedAt) : 0,
+    });
+  }
+  return out;
+}
+
+function _findLinuxProcessesWithCwdInside(resolved, _timeoutMs, now) {
+  // /proc walk: scan numeric entries, readlink cwd, keep matches.
+  let entries;
+  try { entries = fs.readdirSync('/proc'); }
+  catch { return []; }
+  const prefix = resolved + path.sep;
+  const out = [];
+  for (const e of entries) {
+    if (!/^\d+$/.test(e)) continue;
+    const pid = Number(e);
+    let cwd;
+    try { cwd = fs.readlinkSync(`/proc/${pid}/cwd`); }
+    catch { continue; }
+    if (!cwd) continue;
+    if (cwd !== resolved && !cwd.startsWith(prefix)) continue;
+    let cmdline = '';
+    try {
+      const buf = fs.readFileSync(`/proc/${pid}/cmdline`);
+      cmdline = buf.toString('utf8').replace(/\0/g, ' ').trim();
+    } catch { /* cmdline read can fail on race */ }
+    let startedAt = 0;
+    try {
+      const st = fs.statSync(`/proc/${pid}`);
+      startedAt = st && st.ctimeMs ? Math.floor(st.ctimeMs) : 0;
+    } catch { /* stat can fail on race */ }
+    out.push({
+      pid,
+      cmdline,
+      startedAt,
+      ageMs: startedAt > 0 ? Math.max(0, now - startedAt) : 0,
+    });
+  }
+  return out;
+}
+
+function _findMacProcessesWithCwdInside(resolved, timeoutMs, now) {
+  // `lsof -a -d cwd -F pn` emits PID then cwd path. Filter for dir matches,
+  // then run a single `ps` pass to enrich cmdline + start time.
+  let raw;
+  try {
+    raw = _execSync('lsof -a -d cwd -F pn 2>/dev/null', {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024,
+    });
+  } catch { return []; }
+  if (!raw) return [];
+  const prefix = resolved + path.sep;
+  const pids = new Set();
+  let currentPid = null;
+  for (const line of String(raw).split(/\r?\n/)) {
+    if (!line) continue;
+    const tag = line[0];
+    const val = line.slice(1);
+    if (tag === 'p') {
+      const n = Number(val);
+      currentPid = Number.isInteger(n) && n > 0 ? n : null;
+    } else if (tag === 'n' && currentPid != null) {
+      if (val === resolved || val.startsWith(prefix)) pids.add(currentPid);
+    }
+  }
+  if (pids.size === 0) return [];
+  const out = [];
+  for (const pid of pids) {
+    let line;
+    try {
+      line = String(_execSync(`ps -p ${pid} -o lstart=,command=`, {
+        stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, encoding: 'utf8',
+      }) || '').trim();
+    } catch { line = ''; }
+    let startedAt = 0;
+    let cmdline = '';
+    if (line) {
+      // ps lstart= emits "Mon Jun  9 07:04:33 2026" (24 chars), then cmdline.
+      const lstart = line.slice(0, 24).trim();
+      cmdline = line.slice(24).trim();
+      const parsed = Date.parse(lstart);
+      if (!Number.isNaN(parsed)) startedAt = parsed;
+    }
+    out.push({
+      pid,
+      cmdline,
+      startedAt,
+      ageMs: startedAt > 0 ? Math.max(0, now - startedAt) : 0,
+    });
+  }
+  return out;
+}
+
+// W-mq6f2fe0000557fa — clear the per-path failure cooldown entry so the
+// post-holder-reap retry can attempt removeWorktree even though the path
+// has already failed >= 3 times. Without this, the cooldown silently
+// suppresses the retry and the orphan dir is left stuck.
+function clearWorktreeFailureCache(wtPath) {
+  if (!wtPath) return false;
+  try {
+    const resolved = path.resolve(wtPath);
+    return _removeWorktreeFailures.delete(resolved);
+  } catch { return false; }
+}
+
 // Cross-check a single PID's command line for a Minions agent invocation
 // (`claude` or `copilot`, including the `node spawn-agent.js --runtime <name>`
 // wrapper and `gh copilot` fallback). Used by orphan/recycled-PID safety:
@@ -6573,6 +6792,61 @@ function _prHeadSha(pr) {
   return String(pr?.headRefOid || pr?.headSha || pr?._adoSourceCommit || pr?._adoHeadCommit || '').trim();
 }
 
+// Target-branch base SHA, normalized across hosts. GitHub PRs carry `baseSha`
+// (engine/github.js:746-749); ADO PRs carry `_adoTargetCommit`
+// (engine/ado.js:1168-1172, inline in pollPrStatus).
+function _prBaseSha(pr) {
+  return String(pr?.baseSha || pr?._adoTargetCommit || '').trim();
+}
+
+// Target ref name, normalized across hosts. GitHub PRs carry `baseRefName`
+// (e.g. "master"); ADO PRs carry `targetRefName` (e.g. "refs/heads/main").
+function _prTargetRefName(pr) {
+  return String(pr?.baseRefName || pr?.targetRefName || '').trim();
+}
+
+// #3079 — Composite key the engine uses to gate merge-conflict re-dispatch.
+// The same-head guard at engine.js:5676 previously compared only source head
+// SHA, missing the case where a PR is retargeted (e.g. parent branch → main)
+// without the source moving. Including the base SHA and target ref name makes
+// the guard target-aware so retargets naturally release the pause.
+function prMergeConflictGuardKey(pr) {
+  return `${_prHeadSha(pr)}|${_prBaseSha(pr)}|${_prTargetRefName(pr)}`;
+}
+
+// #3079 — Helper invoked by the ADO + GitHub poller metadata-apply paths.
+// When the PR's target ref changes (user retargeted via gh pr edit --base or
+// ADO PR edit), clear the stale MERGE_CONFLICT records so the next tick can
+// re-evaluate the conflict against the new target. Other causes
+// (BUILD_FAILURE, REVIEW_FEEDBACK, HUMAN_FEEDBACK) are untouched — they are
+// not target-sensitive. First-poll seeding (no prior target ref recorded)
+// is a no-op so we don't strip state immediately after an upsert.
+//
+// Returns true when state was actually mutated (callers may use this to set
+// the surrounding "updated" flag and trigger a persist).
+function resetMergeConflictStateOnRetarget(pr, newTargetRef) {
+  if (!pr) return false;
+  const next = String(newTargetRef || '').trim();
+  if (!next) return false;
+  const prior = _prTargetRefName(pr);
+  // First-poll seeding: no prior value → record new value via the caller,
+  // do NOT clear merge-conflict state.
+  if (!prior) return false;
+  if (prior === next) return false;
+  let changed = false;
+  if (pr._lastDispatchByCause && pr._lastDispatchByCause[PR_FIX_CAUSE.MERGE_CONFLICT]) {
+    delete pr._lastDispatchByCause[PR_FIX_CAUSE.MERGE_CONFLICT];
+    if (Object.keys(pr._lastDispatchByCause).length === 0) delete pr._lastDispatchByCause;
+    changed = true;
+  }
+  if (pr._noOpFixes && pr._noOpFixes[PR_FIX_CAUSE.MERGE_CONFLICT]) {
+    delete pr._noOpFixes[PR_FIX_CAUSE.MERGE_CONFLICT];
+    if (Object.keys(pr._noOpFixes).length === 0) delete pr._noOpFixes;
+    changed = true;
+  }
+  return changed;
+}
+
 function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
   const review = pr?.minionsReview || {};
   const feedback = pr?.humanFeedback || {};
@@ -6596,6 +6870,16 @@ function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
     evidence.mergeConflict = !!pr?._mergeConflict;
     evidence.mergeStatus = pr?.mergeStatus || '';
     evidence.mergeConflictDetail = pr?._mergeConflictDetail || '';
+    // #3079 — same rationale as BUILD_FAILURE / REVIEW_FEEDBACK in #2979:
+    // without head/base/target fields the fingerprint was sticky across a
+    // rebase + force-push AND across a PR retarget, so existing
+    // _noOpFixes[MERGE_CONFLICT] pauses never released. Adding head + base
+    // SHA + target ref name gives MERGE_CONFLICT the same natural-unsticking
+    // property the other auto-fix causes already have.
+    evidence.headRefOid = _prHeadSha(pr);
+    evidence.baseSha = _prBaseSha(pr);
+    evidence.targetRefName = _prTargetRefName(pr);
+    evidence.lastPushedAt = pr?.lastPushedAt || '';
   } else {
     evidence.reviewStatus = pr?.reviewStatus || '';
     evidence.lastReviewedAt = pr?.lastReviewedAt || '';
@@ -7221,6 +7505,8 @@ module.exports = {
   PR_FIX_CAUSE,
   getPrFixAutomationCause,
   prFixEvidenceFingerprint,
+  prMergeConflictGuardKey,
+  resetMergeConflictStateOnRetarget,
   getPrNoOpFixRecord,
   isPrNoOpFixCausePaused,
   getPrPausedCauses,
@@ -7233,6 +7519,8 @@ module.exports = {
   killByPidsImmediate,
   isProcessCommandLineMatchingAgent,
   listAllProcesses,
+  findProcessesWithCwdInside,
+  clearWorktreeFailureCache,
   listProcessDescendants,
   listProcessReachable,
   removeWorktree,