@yemi33/minions 0.1.1871 → 0.1.1872

package/CHANGELOG.md

@@ -1,8 +1,10 @@
 # Changelog
 
-## 0.1.1871 (2026-05-11)
+## 0.1.1872 (2026-05-11)
 
 ### Features
+-  Stale-HEAD guard on fix-task pushes (P-c8f2d5e3) (#2360)
+- Cached buildStatus invalidation on no-op completion (#2355)
 -  per-agent memory file architecture (P-f1c5a8b6) (#2354)
 -  Implement pre-dispatch acceptance criteria validation gate (P-a2d6b9c7) (#2352)
 

package/engine/lifecycle.js

@@ -1592,7 +1592,7 @@ async function detectPrFixBranchChange(meta, config) {
   return { changed: null, beforeHead, afterHead: remoteHead || '', reason: 'unable to prove branch head after fix' };
 }
 
-function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChange, config) {
+function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChange, config, noopReason) {
   const evidenceFingerprint = shared.prFixEvidenceFingerprint(target, cause);
   const prior = shared.getPrNoOpFixRecord(target, cause);
   const sameEvidence = prior?.evidenceFingerprint === evidenceFingerprint;
@@ -1623,6 +1623,20 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
     afterHead: branchChange?.afterHead || '',
   };
 
+  // Record a same-SHA dispatch outcome on the PR record so the eligibility
+  // filter can short-circuit duplicate build-fix dispatches against an
+  // unchanged commit. Reset happens implicitly when headSha advances and the
+  // discovery filter compares lastDispatchHeadSha to the current head.
+  const headSha = getPrFixBaselineHead(target);
+  target.lastDispatchedAt = now;
+  target.lastDispatchOutcome = 'noop';
+  target.lastDispatchHeadSha = headSha;
+  target.lastDispatchReason = String(
+    noopReason
+      || branchChange?.reason
+      || 'fix completed without changing the PR branch'
+  ).slice(0, 500);
+
   if (cause === shared.PR_FIX_CAUSE.HUMAN_FEEDBACK && target.humanFeedback) {
     target.humanFeedback.pendingFix = !paused;
     if (paused) target.humanFeedback.noOpPaused = true;
@@ -1639,6 +1653,14 @@ function clearPrNoOpFixAttempt(target, cause) {
   if (Object.keys(target._noOpFixes).length === 0) delete target._noOpFixes;
   if (target._lastNoOpFix?.cause === cause) delete target._lastNoOpFix;
   if (target.humanFeedback) delete target.humanFeedback.noOpPaused;
+  // The lastDispatch* trackers exist to prevent duplicate noop dispatches at
+  // the same head; once the agent actually pushed a fix we no longer want them
+  // to suppress a fresh dispatch (the SHA may have moved or the next failure
+  // is genuinely new).
+  delete target.lastDispatchedAt;
+  delete target.lastDispatchOutcome;
+  delete target.lastDispatchHeadSha;
+  delete target.lastDispatchReason;
 }
 
 function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId = '') {
@@ -1666,7 +1688,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
       target.minionsReview = next;
     };
     if (explicitlyChangedBranch && options.branchChange?.changed === false) {
-      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config);
+      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config, options.noopReason);
       result = { noOp: true, cause, paused: !!record.paused, count: record.count };
       log('warn', `Updated ${pr.id} → recorded no-op ${cause} fix attempt ${record.count}${record.paused ? ' (paused)' : ''}; PR branch was unchanged`);
       return prs;
@@ -1678,7 +1700,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
     // automation cause handled — a future tick with working detection must
     // be free to re-dispatch.
     if (explicitlyChangedBranch && options.branchChange?.changed === null) {
-      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config);
+      const record = recordPrNoOpFixAttempt(target, cause, source, options.dispatchItem, options.branchChange, options.config, options.noopReason);
       result = { noOp: true, cause, paused: !!record.paused, count: record.count, indeterminate: true };
       log('warn', `Updated ${pr.id} → recorded indeterminate ${cause} fix attempt ${record.count}${record.paused ? ' (paused)' : ''}; PR branch advance could not be verified${options.branchChange?.reason ? ` (${options.branchChange.reason})` : ''}`);
       return prs;
@@ -3208,6 +3230,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       dispatchItem,
       branchChange: prFixBranchChange,
       config,
+      noopReason: noopRationale || meta?._noopReason || '',
     });
     // (#984) Sync PRD status for PR-linked features: fix work items have a different ID
     // than the original PRD feature, so syncPrdItemStatus(fixWiId, ...) finds nothing.

package/engine/spawn-agent.js

@@ -162,6 +162,81 @@ function formatProcessExitSentinel(exitCode, signal) {
   return `\n[process-exit] code=${exitCode}${signal ? ` signal=${signal}` : ''}\n`;
 }
 
+/**
+ * Pre-push stale-HEAD guard for fix-task dispatches (P-c8f2d5e3).
+ *
+ * When the engine reuses an existing worktree on a PR branch that was rebased
+ * upstream (force-push), the local HEAD can sit behind origin/<branch>. The
+ * first push from that worktree silently overwrites the rebased history — a
+ * confirmed silent-overwrite footgun captured in team memory.
+ *
+ * This helper runs:
+ *   git fetch origin <branch>
+ *   git rev-list --count HEAD..origin/<branch>
+ * inside the worktree. When the count is > 0 it throws a clear, actionable
+ * error so engine.spawnAgent can abort the dispatch before invoking the
+ * runtime CLI — i.e. before the agent has a chance to push.
+ *
+ * The fetch is best-effort: if origin doesn't have the ref yet (first push on
+ * a fresh branch, common for shared-branch plan items), the helper returns
+ * `{ ok: true, skipped: 'no-upstream' }` instead of failing — there's no
+ * rebased tip to overwrite. Any other fetch failure is also treated as a
+ * skip with `skipped: 'fetch-failed'` so transient network issues don't
+ * brick an otherwise-healthy dispatch.
+ *
+ * @param {object} args
+ * @param {string} args.branch - PR branch name (already sanitized)
+ * @param {string} args.cwd    - Worktree path
+ * @param {function} [args.exec] - Async exec(cmd, opts) — injectable for tests
+ * @param {object}   [args.gitOpts] - Options passed through to exec
+ * @returns {Promise<{ok: true, behindCount: number, skipped?: string}>}
+ * @throws {Error & {code: 'STALE_HEAD'}} when local HEAD is behind origin
+ */
+async function assertStaleHeadOk({ branch, cwd, exec, gitOpts } = {}) {
+  if (!branch) throw new Error('assertStaleHeadOk: branch is required');
+  if (!cwd) throw new Error('assertStaleHeadOk: cwd is required');
+  const execFn = typeof exec === 'function'
+    ? exec
+    : require('./shared').execAsync;
+  const opts = { ...(gitOpts || {}), cwd };
+
+  // Best-effort fetch. Branch-missing-on-origin is a legitimate state (first
+  // push on a freshly-cut feature branch) and must NOT block dispatch.
+  try {
+    await execFn(`git fetch origin "${branch}"`, opts);
+  } catch (err) {
+    const msg = (err && (err.stderr?.toString?.() || err.message || '')) + '';
+    if (/couldn'?t find remote ref|not found in upstream|unknown revision/i.test(msg)) {
+      return { ok: true, behindCount: 0, skipped: 'no-upstream' };
+    }
+    // Other failures (network/auth/timeout) — skip rather than block.
+    return { ok: true, behindCount: 0, skipped: 'fetch-failed' };
+  }
+
+  let countOut;
+  try {
+    countOut = await execFn(`git rev-list --count HEAD..origin/${branch}`, opts);
+  } catch (err) {
+    // origin/<branch> resolution failed AFTER fetch — treat as no-upstream.
+    return { ok: true, behindCount: 0, skipped: 'rev-list-failed' };
+  }
+  const raw = typeof countOut === 'string'
+    ? countOut
+    : (countOut?.stdout?.toString?.() ?? String(countOut ?? ''));
+  const behindCount = parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(behindCount) || behindCount <= 0) {
+    return { ok: true, behindCount: Number.isFinite(behindCount) ? behindCount : 0 };
+  }
+  const err = new Error(
+    `PR branch was rebased; local HEAD is stale (${behindCount} commits behind origin). ` +
+    `Run \`git pull --rebase origin ${branch}\` first.`
+  );
+  err.code = 'STALE_HEAD';
+  err.behindCount = behindCount;
+  err.branch = branch;
+  throw err;
+}
+
 // The orphan reaper recovers an agent's exit code by scanning live-output.log for
 // `[process-exit] code=N`. The previous design wrote the sentinel to stdout, hoping
 // the engine's stdout consumer (engine.js) would copy it into the file — but when
@@ -456,6 +531,6 @@ function main() {
   });
 }
 
-module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, createParentPipeForwarder };
+module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, createParentPipeForwarder, assertStaleHeadOk };
 
 if (require.main === module) main();

package/engine.js

@@ -28,6 +28,7 @@ const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS,
   WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, DISPATCH_RESULT, AGENT_STATUS,
   FAILURE_CLASS } = shared;
 const { resolveRuntime } = require('./engine/runtimes');
+const { assertStaleHeadOk } = require('./engine/spawn-agent');
 const queries = require('./engine/queries');
 
 // ─── Paths ──────────────────────────────────────────────────────────────────
@@ -1114,6 +1115,41 @@ async function spawnAgent(dispatchItem, config) {
     log('warn', `Agent ${agentId} running ${type} task in main repo (no worktree) for ${id} — changes may land on master directly`);
   }
 
+  // ── Stale-HEAD guard for fix-task pushes (P-c8f2d5e3) ────────────────────
+  // When a PR branch is rebased upstream (force-push), a reused worktree can
+  // sit on local HEAD that's behind origin/<branch>. The first push from that
+  // worktree silently overwrites the rebased history. Fix-task dispatches are
+  // the canonical case: they always target an existing PR branch the engine
+  // already polled. Abort dispatch BEFORE invoking the runtime CLI so the
+  // agent never gets a chance to push over the rebased tip.
+  // Read-only and non-fix dispatches are out of scope — implement tasks cut
+  // their own branch from main, and review/verify don't push.
+  if (type === WORK_TYPE.FIX && branchName && worktreePath && cwd === worktreePath) {
+    try {
+      const guard = await assertStaleHeadOk({
+        branch: branchName,
+        cwd: worktreePath,
+        exec: execAsync,
+        gitOpts: { ..._gitOpts, timeout: 15000 },
+      });
+      if (guard.skipped) {
+        log('info', `Stale-HEAD guard skipped for ${id} (${branchName}): ${guard.skipped}`);
+      }
+    } catch (err) {
+      if (err && err.code === 'STALE_HEAD') {
+        log('error', `Stale-HEAD guard rejected fix dispatch ${id} on ${branchName}: ${err.message}`);
+        _cleanupPromptFiles();
+        completeDispatch(id, DISPATCH_RESULT.ERROR, err.message.slice(0, 300));
+        cleanupTempAgent(agentId);
+        return null;
+      }
+      // Non-STALE_HEAD failures from the guard itself shouldn't block dispatch
+      // (the guard is conservative by design — fetch/network issues fall through
+      // to skipped:'fetch-failed'). Log and continue.
+      log('warn', `Stale-HEAD guard error for ${id} (${branchName}): ${err.message}`);
+    }
+  }
+
   // ── Runtime + opts resolution (P-2a6d9c4f) ────────────────────────────────
   // Every CLI-specific knob flows through the runtime adapter resolved from
   // resolveAgentCli(agent, engine). Engine code MUST NOT branch on
@@ -2936,6 +2972,20 @@ async function discoverFromPrs(config, project) {
     const autoFixBuilds = config.engine?.autoFixBuilds ?? ENGINE_DEFAULTS.autoFixBuilds;
     if (pollEnabled && autoFixBuilds && pr.status === PR_STATUS.ACTIVE && pr.buildStatus === 'failing'
       && !isPrNoOpFixCauseSuppressed(pr, shared.PR_FIX_CAUSE.BUILD_FAILURE)) {
+      // P-b7e1c4d2: skip when the most recent dispatch already noop'd against
+      // the same head SHA — chronic across PRs #2315–#2323 where every fix
+      // agent rebutted "this is a pre-existing master baseline" but the
+      // cached buildStatus:failing kept re-triggering the loop. The check
+      // clears automatically once a new commit lands (lastDispatchHeadSha
+      // stops matching the current head).
+      const currentHeadSha = String(pr.headSha || pr._adoSourceCommit || pr._adoHeadCommit || '').trim();
+      if (pr.lastDispatchOutcome === 'noop'
+        && pr.lastDispatchHeadSha
+        && currentHeadSha
+        && pr.lastDispatchHeadSha === currentHeadSha) {
+        log('info', `Skipping build-fix for ${pr.id}: last dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} (${(pr.lastDispatchReason || '').slice(0, 120)})`);
+        continue;
+      }
       const buildCauseKey = getPrAutomationCauseKey('build', pr);
       const key = getPrAutomationDispatchKey(`build-fix-${project?.name || 'default'}-${prDisplayId}`, buildCauseKey);
       if (isPrAutomationCauseHandledOrPending(project, pr, buildCauseKey)) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1871",
+  "version": "0.1.1872",
   "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"