@yemi33/minions 0.1.2102 → 0.1.2104

package/engine/dispatch.js

@@ -434,6 +434,8 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.PERMISSION_BLOCKED,
       FAILURE_CLASS.AUTH, // W-mpcuc8i80003a7b3 — git/network credential failure; mechanical retry won't fix missing az / GCM creds
       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.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
@@ -797,6 +799,8 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
             [FAILURE_CLASS.PERMISSION_BLOCKED]: 'permission or auth failure',
             [FAILURE_CLASS.AUTH]: 'ADO/git authentication failed (missing or expired credentials)',
             [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.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

@@ -1127,7 +1127,14 @@ async function pollPrHumanComments(config) {
         author: c.user?.login || 'Human',
         content: c.body || '',
         date,
-        _isAgent: false
+        _isAgent: false,
+        // Issue #2994: namespace GH comment ids by API source ("issue" from
+        // `/issues/N/comments` vs "review" from `/pulls/N/comments`). Each
+        // endpoint maintains its own id space, so two comments — one issue,
+        // one review — can collide on the same numeric id. Mirror the ADO
+        // poller's thread-aware key shape so the engine.js human-feedback
+        // same-head guard can dedup via a single comparable key.
+        _type: c._type,
       };
       allCommentEntries.push(entry);
 
@@ -1186,7 +1193,13 @@ async function pollPrHumanComments(config) {
     pr.humanFeedback = {
       lastProcessedCommentDate: latestDate,
       lastProcessedCommentId: String(newComments[newComments.length - 1].commentId),
-      lastProcessedCommentKey: String(newComments[newComments.length - 1].commentId),
+      // Issue #2994: namespaced key — `${type}:${commentId}` — for the
+      // engine.js human-feedback same-head guard. Mirrors ADO's
+      // `${threadId}:${commentId}` shape so the guard compares a single key
+      // form. Falls back to the bare id when `_type` is absent (defensive;
+      // every entry above sets it, but the pollPrHumanComments path in
+      // engine/ado.js writes the legacy format too).
+      lastProcessedCommentKey: `${newComments[newComments.length - 1]._type || ''}:${newComments[newComments.length - 1].commentId}`,
       pendingFix: true,
       feedbackContent,
       editsSeen,

package/engine/lifecycle.js

@@ -2004,8 +2004,39 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
     // noops so the symmetric same-head guard at engine.js:~2847 can short-circuit
     // when both the head SHA AND the lastProcessedCommentId match the recorded
     // dispatch. Other causes have no comment-id concept, so the field is omitted.
+    //
+    // Issue #2994: also capture `lastProcessedCommentKey` (the thread-aware
+    // form on ADO: `${threadId}:${commentId}`, type-namespaced on GH:
+    // `${type}:${commentId}`). ADO comment ids are per-thread (not globally
+    // unique), so a bare-id compare suppressed legitimate dispatches when two
+    // different discussions both began at comment id:1 on the same head SHA
+    // (live repro: office-bohemia/pullrequest/5284819, discussion 66508411
+    // suppressed because discussion 66487840 noop'd at comment id:1 on the
+    // same head a425ab05). PREFER the dispatch snapshot
+    // (`dispatchItem.meta.pr.humanFeedback`) over live `target.humanFeedback`:
+    // the poller can advance live state to a NEWER comment between dispatch
+    // and lifecycle, and we MUST persist the comment that actually triggered
+    // this dispatch — not the next one queued behind it. Fall back to live
+    // target when the dispatch builder didn't snapshot humanFeedback (older
+    // callers, manual re-dispatch paths).
     ...(cause === shared.PR_FIX_CAUSE.HUMAN_FEEDBACK
-      ? { lastProcessedCommentId: String(target.humanFeedback?.lastProcessedCommentId || '') }
+      ? (() => {
+          const dispatchedFeedback = dispatchItem?.meta?.pr?.humanFeedback;
+          const liveFeedback = target.humanFeedback;
+          const commentId = String(
+            (dispatchedFeedback && dispatchedFeedback.lastProcessedCommentId)
+              || (liveFeedback && liveFeedback.lastProcessedCommentId)
+              || ''
+          );
+          const commentKey = String(
+            (dispatchedFeedback && dispatchedFeedback.lastProcessedCommentKey)
+              || (liveFeedback && liveFeedback.lastProcessedCommentKey)
+              || ''
+          );
+          const out = { lastProcessedCommentId: commentId };
+          if (commentKey) out.lastProcessedCommentKey = commentKey;
+          return out;
+        })()
       : {}),
   };
   target.lastDispatchedAt = now;
@@ -2361,10 +2392,24 @@ function updatePrAfterFixError(pr, project, source, options = {}) {
     // engine.js human-feedback guard's commentId match still works once
     // indeterminate flips back off (which it doesn't here, but state shape
     // stays consistent across paths).
+    //
+    // Issue #2994: also carry/refresh `lastProcessedCommentKey` (thread-aware
+    // form) so the same-head guard can compare the per-thread key rather than
+    // the per-thread-collidable bare id. Preference order matches the noop
+    // path: prior record's key → dispatch snapshot → live target.
     if (cause === shared.PR_FIX_CAUSE.HUMAN_FEEDBACK) {
+      const dispatchedFeedback = dispatchItem?.meta?.pr?.humanFeedback;
+      const liveFeedback = target.humanFeedback;
       const commentId = prior?.lastProcessedCommentId
-        || String(target.humanFeedback?.lastProcessedCommentId || '');
+        || String((dispatchedFeedback && dispatchedFeedback.lastProcessedCommentId)
+          || (liveFeedback && liveFeedback.lastProcessedCommentId)
+          || '');
       if (commentId) next.lastProcessedCommentId = commentId;
+      const commentKey = prior?.lastProcessedCommentKey
+        || String((dispatchedFeedback && dispatchedFeedback.lastProcessedCommentKey)
+          || (liveFeedback && liveFeedback.lastProcessedCommentKey)
+          || '');
+      if (commentKey) next.lastProcessedCommentKey = commentKey;
     }
     target._lastDispatchByCause[cause] = next;
     result = { cause, indeterminate: true, errorClass };

package/engine/shared.js

@@ -3079,6 +3079,8 @@ const FAILURE_CLASS = {
   MAX_TURNS: 'max-turns',                 // Claude CLI error_max_turns — work in progress, retryable
   COMPLETION_NONCE_MISMATCH: 'completion-nonce-mismatch', // P-d2a8f6c1: completion JSON nonce did not match the per-spawn value injected via MINIONS_COMPLETION_NONCE — treat as forged/untrusted; ignore PR/noop/status fields from the report
   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.
   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
   INVALID_MANAGED_SPAWN: 'invalid-managed-spawn', // P-7a3b1c92: agents/<id>/managed-spawn.json failed validator (bad schema, broken workdir, executable/env not on allowlist, healthcheck shape wrong). Engine refuses to spawn any spec — agent must fix file; never retryable as-is.

package/engine.js

@@ -846,26 +846,49 @@ async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
 }
 
 // ─── assertCleanSharedWorktree (#2439) ──────────────────────────────────────
-// Engine-side preflight that prevents shared-branch dispatches from spawning
-// into a dirty worktree. Without this, the shared-branch playbook's "git status
-// + bail out" guard fires AFTER dispatch — converting an orchestration hygiene
-// problem into a fake implementation failure that also cascades to dependent
-// work items.
+// Engine-side preflight that prevents shared-branch (and PR-targeted reused —
+// see opts.quarantineOnUnsafe, issue #2996) dispatches from spawning into a
+// dirty worktree. Without this, the playbook's "git status + bail out" guard
+// fires AFTER dispatch — converting an orchestration hygiene problem into a
+// fake implementation failure that also cascades to dependent work items, and
+// (for PR-targeted reused worktrees) keeps redispatching agents into the same
+// contaminated state.
 //
 // Behavior:
-//   1. Run `git status --porcelain` in the target worktree.
-//   2. If clean → { clean: true, healed: false }.
-//   3. If dirty, decide whether self-heal is safe:
+//   1. Run `git status --porcelain` + `git rev-list --left-right --count
+//      refs/remotes/origin/<branch>...HEAD` in the target worktree.
+//   2. If clean AND not divergent → { clean: true, healed: false }.
+//      (Pure shared-branch callers pass quarantineOnUnsafe=false and DO NOT
+//      treat ahead-of-origin as dirty — that path's existing semantics are
+//      preserved. PR-targeted reused worktrees pass quarantineOnUnsafe=true
+//      and DO treat ahead-of-origin as unsafe because the underlying bug
+//      (#2996) was a 157-commit-ahead local branch.)
+//   3. If unsafe, decide:
 //      - Block (preserve dirty tree for inspection) when ANOTHER active
-//        dispatch claims the same branch (ownership ambiguity).
+//        dispatch claims the same branch (ownership ambiguity — NEVER
+//        quarantine, even when quarantineOnUnsafe=true).
 //      - Block when local commits exist that aren't on origin/<branch>
-//        (would lose unpushed work).
-//      - Otherwise reset --hard + clean -fd, then re-verify.
-//   4. Return { clean, healed, reason, dirtyFiles } so the caller can fail
-//      fast with a first-class DIRTY_WORKTREE reason and retry semantics.
-async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, dispatchId, gitOpts = {}) {
-  const result = { clean: false, healed: false, reason: null, dirtyFiles: [] };
-  // 1. Status probe
+//        (would lose unpushed work). When quarantineOnUnsafe=true,
+//        QUARANTINE instead: rename worktree to <path>-quarantine-<ts>,
+//        prune git's stale metadata, back up the local branch HEAD to
+//        refs/minions/quarantine/<sanitized>/<ts>, reset
+//        refs/heads/<branch> → origin/<branch>, and write a notes/inbox/
+//        engine-worktree-quarantine note with the diagnostics so a human
+//        can recover any unpushed work.
+//      - Otherwise (filesystem-only dirty) reset --hard + clean -fd, then
+//        re-verify.
+//   4. Return { clean, healed, reason, dirtyFiles, ahead, behind,
+//      quarantined, quarantinedPath, backupRef } so the caller can fail
+//      fast with a first-class DIRTY_WORKTREE / WORKTREE_DIRTY /
+//      WORKTREE_DIVERGENT reason and retry semantics.
+async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, dispatchId, gitOpts = {}, opts = {}) {
+  const quarantineOnUnsafe = !!opts.quarantineOnUnsafe;
+  const result = {
+    clean: false, healed: false, reason: null, dirtyFiles: [],
+    ahead: 0, behind: 0,
+    quarantined: false, quarantinedPath: null, backupRef: null,
+  };
+  // 1. Status probe (filesystem)
   let statusOut = '';
   try {
     const r = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
@@ -875,13 +898,43 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     result.error = e.message;
     return result;
   }
-  if (!statusOut) {
+  if (statusOut) {
+    result.dirtyFiles = statusOut.split('\n').map(l => l.trim()).filter(Boolean);
+  }
+  const filesystemDirty = result.dirtyFiles.length > 0;
+
+  // 2. Ahead/behind vs refs/remotes/origin/<branch>. Computed BEFORE the
+  //    early clean return so a divergent-but-clean worktree (no uncommitted
+  //    edits, but local branch is N commits ahead of origin) is caught when
+  //    the caller opted into quarantineOnUnsafe (issue #2996).
+  let upstreamKnown = false;
+  try {
+    const r = await execAsync(
+      `git rev-list --left-right --count refs/remotes/origin/${branchName}...HEAD`,
+      { ...gitOpts, cwd: worktreePath, timeout: 10000 },
+    );
+    const parts = String(r || '').trim().split(/\s+/);
+    const behind = parseInt(parts[0], 10);
+    const ahead = parseInt(parts[1], 10);
+    if (Number.isFinite(ahead) && Number.isFinite(behind)) {
+      result.ahead = ahead;
+      result.behind = behind;
+      upstreamKnown = true;
+    }
+  } catch (e) {
+    // origin/<branch> may not exist yet (never pushed). Mark unknown.
+    upstreamKnown = false;
+  }
+
+  const considerUnsafe = filesystemDirty || (quarantineOnUnsafe && (result.ahead > 0 || !upstreamKnown));
+  if (!considerUnsafe) {
     result.clean = true;
     return result;
   }
-  result.dirtyFiles = statusOut.split('\n').map(l => l.trim()).filter(Boolean);
 
-  // 2. Ownership check — another live dispatch on the same branch?
+  // 3. Ownership check — another live dispatch on the same branch?
+  //    NEVER quarantine in this case — the other dispatch may be using the
+  //    worktree right now. Always preserve.
   const sanitized = sanitizeBranch(branchName);
   let otherActive = false;
   try {
@@ -902,24 +955,38 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     return result;
   }
 
-  // 3. Unpushed-commit check — refuse to clean when local work would be lost.
-  //    `git log @{u}..HEAD --oneline` returns non-empty when there are commits
-  //    ahead of the upstream. If there is no upstream at all, treat as unsafe
-  //    to clean (we can't prove the local commits exist on origin).
-  let hasUnpushed = false;
-  try {
-    const r = await execAsync('git log @{u}..HEAD --oneline', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
-    hasUnpushed = (r || '').toString().trim().length > 0;
-  } catch (e) {
-    // No upstream configured (e.g., branch never pushed) — be conservative.
-    hasUnpushed = true;
-  }
+  // 4. Unpushed-commit check — refuse to reset when local work would be lost.
+  //    Use the ahead count we already computed (cheaper + correct vs.
+  //    `git log @{u}..HEAD` which needs an upstream config and silently
+  //    returns empty when missing).
+  const hasUnpushed = upstreamKnown ? result.ahead > 0 : true;
   if (hasUnpushed) {
-    result.reason = 'has-unpushed-commits';
+    result.reason = upstreamKnown ? 'has-unpushed-commits' : 'no-upstream';
+    if (quarantineOnUnsafe) {
+      try {
+        const q = await _quarantineDirtyWorktree(
+          rootDir, worktreePath, branchName, gitOpts,
+          {
+            dispatchId,
+            reason: result.reason,
+            ahead: result.ahead,
+            behind: result.behind,
+            dirtyFiles: result.dirtyFiles,
+          },
+        );
+        result.quarantined = true;
+        result.quarantinedPath = q.quarantinedPath;
+        result.backupRef = q.backupRef;
+      } catch (qErr) {
+        result.quarantineError = qErr.message;
+        log('error', `assertCleanSharedWorktree: quarantine failed for ${worktreePath}: ${qErr.message}`);
+      }
+    }
     return result;
   }
 
-  // 4. Safe to self-heal: reset + clean
+  // 5. Safe to self-heal (filesystem-dirty only, no unpushed commits, no
+  //    other active dispatch): reset + clean.
   try {
     await execAsync('git reset --hard HEAD', { ...gitOpts, cwd: worktreePath, timeout: 30000 });
     await execAsync('git clean -fd', { ...gitOpts, cwd: worktreePath, timeout: 30000 });
@@ -929,7 +996,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     return result;
   }
 
-  // 5. Re-verify
+  // 6. Re-verify
   try {
     const r2 = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
     const after = (r2 || '').toString().trim();
@@ -944,12 +1011,122 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     return result;
   }
 
-  log('info', `assertCleanSharedWorktree: auto-healed dirty shared-branch worktree ${worktreePath} on ${branchName} (${result.dirtyFiles.length} dirty files reset)`);
+  log('info', `assertCleanSharedWorktree: auto-healed dirty worktree ${worktreePath} on ${branchName} (${result.dirtyFiles.length} dirty files reset)`);
   result.clean = true;
   result.healed = true;
   return result;
 }
 
+// Quarantine a dirty/divergent reused worktree (#2996). Renames the worktree
+// directory to <path>-quarantine-<ts>, runs `git worktree prune` so git no
+// longer treats the missing path as an active checkout, backs up the local
+// branch HEAD to refs/minions/quarantine/<sanitized>/<ts>, and resets
+// refs/heads/<branch> → refs/remotes/origin/<branch> so the next dispatch
+// gets a fresh worktree on the origin tip. Writes a notes/inbox/
+// engine-worktree-quarantine note naming the dirty files + ahead/behind
+// counts so a human can recover any unpushed work.
+//
+// Caller MUST have already confirmed no other active dispatch holds the
+// branch (assertCleanSharedWorktree returns 'other-dispatch-active' before
+// invoking this). Renaming an active worktree out from under a running
+// agent would be catastrophic.
+async function _quarantineDirtyWorktree(rootDir, worktreePath, branchName, gitOpts, diag = {}) {
+  const ts = Date.now();
+  const quarantinedPath = `${worktreePath}-quarantine-${ts}`;
+
+  // Capture HEAD sha BEFORE renaming so we can back up the local branch ref.
+  let headSha = '';
+  try {
+    const r = await execAsync('git rev-parse HEAD', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
+    headSha = (r || '').toString().trim();
+  } catch (e) {
+    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.
+  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".
+  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>
+  // and reset refs/heads/<branch> → origin/<branch> so the next checkout
+  // starts on a clean origin tip rather than recreating the divergent state.
+  // Both ref ops are best-effort: if the local ref machinery is in a weird
+  // state we still want the worktree quarantine to stick.
+  const sanitizedRefSegment = sanitizeBranch(branchName).replace(/\//g, '-');
+  const backupRef = `refs/minions/quarantine/${sanitizedRefSegment}/${ts}`;
+  let backupRefCreated = false;
+  if (headSha) {
+    try {
+      await shared.shellSafeGit(['update-ref', backupRef, headSha], { ...gitOpts, cwd: rootDir, timeout: 10000 });
+      backupRefCreated = true;
+    } catch (e) {
+      log('warn', `_quarantineDirtyWorktree: backup-ref ${backupRef} failed: ${e.message}`);
+    }
+  }
+  try {
+    await shared.shellSafeGit(['fetch', 'origin', branchName], { ...gitOpts, cwd: rootDir, timeout: 30000 });
+  } catch (e) {
+    log('warn', `_quarantineDirtyWorktree: fetch origin/${branchName} after rename: ${e.message}`);
+  }
+  try {
+    await shared.shellSafeGit(
+      ['update-ref', `refs/heads/${branchName}`, `refs/remotes/origin/${branchName}`],
+      { ...gitOpts, cwd: rootDir, timeout: 10000 },
+    );
+    log('info', `_quarantineDirtyWorktree: reset refs/heads/${branchName} → refs/remotes/origin/${branchName}`);
+  } catch (e) {
+    log('warn', `_quarantineDirtyWorktree: reset refs/heads/${branchName} → origin/${branchName} failed: ${e.message}`);
+  }
+
+  // Notes/inbox diagnostic so a human (and future agents) can see why the
+  // worktree was moved and how to recover any unpushed work.
+  const dirtyFiles = Array.isArray(diag.dirtyFiles) ? diag.dirtyFiles : [];
+  const dirtyPreview = dirtyFiles.slice(0, 50).map(f => `- ${f}`).join('\n');
+  const dirtyTrailer = dirtyFiles.length > 50 ? `\n- ...and ${dirtyFiles.length - 50} more` : '';
+  const inboxBody = [
+    '# Engine quarantined a dirty reused worktree (#2996)',
+    '',
+    `- Dispatch: ${diag.dispatchId || '<unknown>'}`,
+    `- Branch: ${branchName}`,
+    `- Original worktree: ${worktreePath}`,
+    `- Quarantined to: ${quarantinedPath}`,
+    `- Reason: ${diag.reason || 'unsafe'}`,
+    `- Local commits ahead of origin: ${diag.ahead || 0}`,
+    `- Local commits behind origin: ${diag.behind || 0}`,
+    `- Dirty files (${dirtyFiles.length}):`,
+    dirtyPreview || '- (none reported)',
+    dirtyTrailer,
+    '',
+    '## Recovery',
+    '',
+    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.`,
+    '',
+    `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).`,
+    backupRefCreated ? `5. Delete the backup ref when done: \`git -C "${rootDir}" update-ref -d ${backupRef}\`.` : '',
+  ].filter(Boolean).join('\n');
+  try {
+    shared.writeToInbox('engine', `worktree-quarantine-${diag.dispatchId || sanitizedRefSegment}`, inboxBody);
+  } catch (e) {
+    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 };
+}
+
 async function recoverPartialWorktree(rootDir, worktreePath, branchName, gitOpts) {
   if (!branchName) return false;
   const existingWt = await findExistingWorktree(rootDir, branchName);
@@ -1214,6 +1391,11 @@ async function spawnAgent(dispatchItem, config) {
 
   if (branchName) {
     updateAgentStatus(id, AGENT_STATUS.WORKTREE_SETUP, `Setting up worktree for branch ${branchName}`);
+    // W-mpwy3mp5 (#2996): track whether we ended up reusing an existing
+    // worktree (rather than creating a fresh one) so the post-setup dirty/
+    // divergent gate knows to quarantine when a contaminated reused tree
+    // would otherwise loop fix-dispatch agents forever.
+    let worktreeReused = false;
     const wtDirName = shared.buildWorktreeDirName({
       dispatchId: id,
       projectName: project.name || 'default',
@@ -1244,6 +1426,7 @@ async function spawnAgent(dispatchItem, config) {
         throw assertErr;
       }
       worktreePath = existingWt;
+      worktreeReused = true;
       log('info', `Reusing existing worktree for ${branchName}: ${existingWt}`);
       // Probe origin first — locally-created branches that were never pushed
       // (orphan/timeout retry before first push) would otherwise emit a
@@ -1363,6 +1546,7 @@ async function spawnAgent(dispatchItem, config) {
                   }
                   log('info', `Shared branch ${branchName} already checked out at ${existingWtPath} — reusing`);
                   worktreePath = existingWtPath;
+                  worktreeReused = true;
                 } else {
                   // Branch is registered but path is missing on disk (#2454).
                   // git keeps the entry — sometimes locked: initializing — and
@@ -1437,6 +1621,7 @@ async function spawnAgent(dispatchItem, config) {
                     }
                     log('info', `Branch ${branchName} already checked out at ${existingWtPath} — reusing`);
                     worktreePath = existingWtPath;
+                    worktreeReused = true;
                   } else {
                     const pruned = await pruneStaleWorktreeForBranch(rootDir, branchName, _gitOpts);
                     if (pruned > 0) {
@@ -1524,6 +1709,7 @@ async function spawnAgent(dispatchItem, config) {
                         }
                         log('info', `Branch ${branchName} already checked out at ${existingWtPath} — reusing`);
                         worktreePath = existingWtPath;
+                        worktreeReused = true;
                       } else if (existingWtPath && !fs.existsSync(existingWtPath)) {
                         log('warn', `Branch ${branchName} tracked in missing dir ${existingWtPath} — pruning and recreating`);
                         try { await shared.shellSafeGit(['worktree', 'prune'], { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
@@ -1592,6 +1778,70 @@ async function spawnAgent(dispatchItem, config) {
       }
     }
 
+    // PR-targeted reused-worktree preflight (W-mpwy3mp5, #2996): when the
+    // engine ADOPTS an existing worktree for a non-shared-branch dispatch
+    // (typically a fix/build-fix or review on a PR branch), the worktree may
+    // be in any state — uncommitted edits from the previous agent, local
+    // commits never pushed, or even a manually-created tree (e.g.
+    // `copilot-pr<N>` next to the user's home dir). Without this gate, the
+    // playbook's "git status + bail out" guard fires AFTER dispatch and we
+    // burn an agent run on a no-op; worse, dispatch.js re-discovers the same
+    // PR-targeted item and loops the same dirty tree until a human notices.
+    //
+    // assertCleanSharedWorktree({ quarantineOnUnsafe: true }) self-heals
+    // filesystem-only dirt, but for has-unpushed-commits (the actual #2996
+    // case) it QUARANTINES the worktree — rename → prune → reset
+    // refs/heads/<branch> to origin/<branch> + back up the divergent HEAD
+    // under refs/minions/quarantine/<branch>/<ts> — so the next dispatch
+    // starts fresh. We mark the failure non-retryable (WORKTREE_DIVERGENT /
+    // WORKTREE_DIRTY) which routes through dispatch.js's neverRetry set;
+    // the 15-minute cooldown.js dedupe window then naturally gates the
+    // fresh dispatch.
+    //
+    // Why no `!meta?.useExistingBranch` guard: discoverFromWorkItems sets
+    // `useExistingBranch: true` for EVERY isPrTargeted WI (engine.js:5898),
+    // which is the exact category named in issue #2996 — fix/review/test
+    // dispatches against a PR branch. The previous revision of this gate
+    // included `&& !meta?.useExistingBranch` which excluded the entire bug
+    // class. The `branchStrategy !== 'shared-branch'` check above is
+    // sufficient to protect the existing shared-branch retryable
+    // DIRTY_WORKTREE block (shared-branch with featureBranch is the OTHER
+    // useExistingBranch:true case, and it's already filtered here).
+    if (
+      worktreeReused
+      && worktreePath
+      && fs.existsSync(worktreePath)
+      && branchName
+      && meta?.branchStrategy !== 'shared-branch'
+    ) {
+      _phaseT.dirtyReusedCheckStart = Date.now();
+      const cleanResult = await assertCleanSharedWorktree(
+        rootDir, worktreePath, branchName, id, _gitOpts,
+        { quarantineOnUnsafe: true },
+      );
+      _phaseT.dirtyReusedCheckEnd = Date.now();
+      if (!cleanResult.clean) {
+        const previewFiles = (cleanResult.dirtyFiles || []).slice(0, 5).join(', ');
+        const isDivergent = (cleanResult.ahead || 0) > 0 || cleanResult.reason === 'no-upstream';
+        const failureClassValue = isDivergent ? FAILURE_CLASS.WORKTREE_DIVERGENT : FAILURE_CLASS.WORKTREE_DIRTY;
+        const failureClassName = 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 : 'was not attempted (' + cleanResult.reason + ').'}`;
+        log('error', reasonMsg);
+        _cleanupPromptFiles();
+        completeDispatch(
+          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.` : ''}`,
+          { agentRetryable: false, failureClass: failureClassValue },
+        );
+        cleanupTempAgent(agentId);
+        return null;
+      }
+    }
+
     // Merge dependency PR branches into worktree (applies to both reused and new worktrees)
     if (worktreePath && fs.existsSync(worktreePath)) {
       cwd = worktreePath;
@@ -4609,6 +4859,33 @@ async function discoverFromPrs(config, project) {
       const currentHeadSha = String(pr.headSha || pr._adoSourceCommit || pr._adoHeadCommit || '').trim();
       const lastHumanDispatch = pr._lastDispatchByCause?.[shared.PR_FIX_CAUSE.HUMAN_FEEDBACK];
       const currentCommentId = String(pr.humanFeedback?.lastProcessedCommentId || '');
+      // Issue #2994: the bare commentId is per-thread on ADO (each discussion's
+      // first reply is id=1), so two threads' opening comments collide on the
+      // SAME head SHA and false-suppress legitimate new-thread dispatches.
+      // Live repro: ADO PR `office-bohemia#5284819`, discussion 66487840
+      // noop'd at comment id:1 on head a425ab05 → discussion 66508411 (a
+      // NEW thread, also at comment id:1, same head) suppressed for a full
+      // tick cycle until the operator inspected the dispatch log.
+      //
+      // Fix: compare the thread-aware key (`${threadId}:${commentId}` on ADO,
+      // `${type}:${commentId}` on GH for issue-vs-review namespacing) when
+      // BOTH sides have it; fall back to the legacy bare-id compare when
+      // BOTH lack it (covers PRs whose last dispatch record predates this
+      // fix). MIXED case = release: dispatch record predates the fix while
+      // the current poller has the key → don't risk a cross-thread false
+      // positive; let one extra dispatch through to refresh the record with
+      // the key on its next noop.
+      const currentCommentKey = String(pr.humanFeedback?.lastProcessedCommentKey || '');
+      const recordedCommentId = String(lastHumanDispatch?.lastProcessedCommentId || '');
+      const recordedCommentKey = String(lastHumanDispatch?.lastProcessedCommentKey || '');
+      let commentMatch = false;
+      if (currentCommentKey && recordedCommentKey) {
+        commentMatch = currentCommentKey === recordedCommentKey;
+      } else if (!currentCommentKey && !recordedCommentKey) {
+        commentMatch = !!(currentCommentId && recordedCommentId && currentCommentId === recordedCommentId);
+      }
+      // Else: mixed (one side has the key, other doesn't) → release the
+      // suppression so the next dispatch refreshes the record format.
       // Issue #2632: this same-head/same-comment guard MUST be cause-local. A
       // previous `continue` here aborted the whole PR iteration and starved
       // the build-failure / re-review / conflict-fix evaluation blocks below
@@ -4641,11 +4918,10 @@ async function discoverFromPrs(config, project) {
         && lastHumanDispatch.headSha
         && currentHeadSha
         && lastHumanDispatch.headSha === currentHeadSha
-        && lastHumanDispatch.lastProcessedCommentId
-        && currentCommentId
-        && lastHumanDispatch.lastProcessedCommentId === currentCommentId);
+        && commentMatch);
       if (skipHumanFeedback) {
-        log('info', `Skipping human-feedback fix for ${pr.id}: last human-feedback dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} and same comment ${currentCommentId.slice(0, 32)} (${(lastHumanDispatch.reason || '').slice(0, 120)})`);
+        const commentLabel = currentCommentKey || currentCommentId;
+        log('info', `Skipping human-feedback fix for ${pr.id}: last human-feedback dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} and same comment ${commentLabel.slice(0, 48)} (${(lastHumanDispatch.reason || '').slice(0, 120)})`);
       }
       if (!skipHumanFeedback) {
       const key = humanFixKey;
@@ -7432,7 +7708,7 @@ module.exports = {
   areDependenciesMet, // exported for testing (P-bf04-decompose-zero-children)
   parseConflictFiles, pruneAncestorDeps, preflightMergeSimulation, // exported for testing
   buildDepConflictFixItem, deriveConflictFixKey, // exported for testing (W-mpcwojgr000a0244)
-  isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, assertCleanSharedWorktree, // exported for testing
+  isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, assertCleanSharedWorktree, _quarantineDirtyWorktree, // exported for testing
   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.2102",
+  "version": "0.1.2104",
   "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"