@yemi33/minions 0.1.2405 → 0.1.2407

package/engine/comment-format.js

@@ -57,7 +57,7 @@ function linkifyBrandTrailer(text) {
 //   - model       concrete runtime execution model (optional)
 //   - no field may contain `--` (would close the HTML comment early)
 
-const { normalizeExecutionModel } = require('./execution-model');
+const { normalizeExecutionModel, UNKNOWN_MODEL } = require('./execution-model');
 
 const AGENT_ID_RE = /^[a-z][a-z0-9-]{0,30}$/;
 const KIND_RE = /^[a-z][a-z0-9-]{0,30}$/;
@@ -104,24 +104,63 @@ function _encodeMarkerModel(model) {
   return encoded.includes('--') ? encoded.replace(/-/g, '%2D') : encoded;
 }
 
+// A genuinely-absent model must NOT be recorded in the hidden marker — the
+// `unknown` sentinel is the signal that no runtime/model evidence exists, so we
+// omit the segment entirely (W-mryk8hf1) rather than persisting `model=unknown`.
+function _isKnownModel(model) {
+  return !!model && model !== UNKNOWN_MODEL;
+}
+
 function _buildMarker({ agentId, kind, workItemId, model }) {
   _validateMarkerInputs({ agentId, kind, workItemId, model });
   const wi = (workItemId !== undefined && workItemId !== null) ? ` wi=${workItemId}` : '';
-  const modelPart = model ? ` model=${_encodeMarkerModel(model)}` : '';
+  const modelPart = _isKnownModel(model) ? ` model=${_encodeMarkerModel(model)}` : '';
   return `<!-- minions:agent=${agentId} kind=${kind}${wi}${modelPart} -->`;
 }
 
 const MODEL_SIGNOFF_RE =
   /(\b(?:Review|Reviewed|Fixed|Verified|Rebased) by (?:Minions|\[Minions\]\([^)]+\)) \([^\r\n)]*? · )[^)\r\n]+(\))/g;
 
+// Matches the visible sign-off when its model segment is the `unknown` sentinel,
+// capturing everything up to (but excluding) the ` · unknown` so it can be
+// dropped — turning `(Ripley — Explorer · unknown)` into `(Ripley — Explorer)`.
+const UNKNOWN_MODEL_SIGNOFF_RE =
+  /(\b(?:Review|Reviewed|Fixed|Verified|Rebased) by (?:Minions|\[Minions\]\([^)]+\)) \([^\r\n)]*?) · unknown(\))/g;
+
+/**
+ * Stamp the concrete runtime execution model into the visible sign-off.
+ *
+ * Three cases, mirroring the execution-model resolver's evidence outcomes:
+ *   - known model            → replace the model segment with it.
+ *   - `unknown` sentinel      → the resolver positively determined no runtime/
+ *                               model evidence exists, so omit the whole
+ *                               ` · <model>` segment rather than printing it
+ *                               (W-mryk8hf1). The footer degrades to
+ *                               `(<name> — <role>)`.
+ *   - no opinion (falsy/null) → leave any concrete model the agent wrote
+ *                               intact, but still drop a bare ` · unknown`
+ *                               sentinel so the footer never advertises it.
+ */
 function stampExecutionModel(text, model) {
+  if (typeof text !== 'string') return text;
   const normalized = normalizeExecutionModel(model);
-  if (!normalized || typeof text !== 'string') return text;
-  return text.replace(MODEL_SIGNOFF_RE, (_match, prefix, suffix) => `${prefix}${normalized}${suffix}`);
+  if (_isKnownModel(normalized)) {
+    return text.replace(MODEL_SIGNOFF_RE, (_match, prefix, suffix) => `${prefix}${normalized}${suffix}`);
+  }
+  if (normalized === UNKNOWN_MODEL) {
+    // prefix ends with " · " — drop that separator along with the model segment.
+    return text.replace(MODEL_SIGNOFF_RE, (_match, prefix, suffix) => `${prefix.replace(/ · $/, '')}${suffix}`);
+  }
+  return text.replace(UNKNOWN_MODEL_SIGNOFF_RE, (_match, prefix, suffix) => `${prefix}${suffix}`);
 }
 
 function _stampLeadingMarkerModel(text, model) {
-  if (!model || typeof text !== 'string') return text;
+  if (typeof text !== 'string') return text;
+  // Rewrite the leading marker whenever a model value is supplied. A known model
+  // is recorded; the `unknown` sentinel rebuilds the marker without `model=`
+  // (buildMarker omits it), stripping any pre-existing stale model=. A
+  // genuinely-absent (falsy/null) model leaves the marker untouched.
+  if (!normalizeExecutionModel(model)) return text;
   return text.replace(MINIONS_COMMENT_MARKER_RE, (marker, agentId, kind, workItemId) => {
     if (marker !== text.slice(0, marker.length)) return marker;
     return _buildMarker({ agentId, kind, workItemId, model });

package/engine/spawn-agent.js

@@ -203,26 +203,78 @@ function formatProcessExitSentinel(exitCode, signal) {
   return `\n[process-exit] code=${exitCode}${signal ? ` signal=${signal}` : ''}\n`;
 }
 
+// Parse a `git rev-list --count <range>` result into a finite integer (NaN on
+// failure). Tolerates string / {stdout} return shapes and Windows CRLF.
+async function _revListCount(execFn, range, opts) {
+  const out = await execFn(`git rev-list --count ${range}`, opts);
+  const raw = typeof out === 'string'
+    ? out
+    : (out?.stdout?.toString?.() ?? String(out ?? ''));
+  const n = parseInt(String(raw).trim(), 10);
+  return Number.isFinite(n) ? n : NaN;
+}
+
+// Return the list of dirty porcelain lines in the worktree, EXCLUDING the
+// engine's own `.minions-worktree` ownership marker (which a reused worktree
+// can surface as untracked without meaning the tree carries real work).
+async function _worktreeDirtyFiles(execFn, opts) {
+  const out = await execFn('git status --porcelain', opts);
+  const raw = typeof out === 'string'
+    ? out
+    : (out?.stdout?.toString?.() ?? String(out ?? ''));
+  const shared = require('./shared');
+  return String(raw)
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .filter((line) => !shared.isWorktreeOwnerMarkerStatusLine(line));
+}
+
 /**
- * Pre-push stale-HEAD guard for fix-task dispatches (P-c8f2d5e3).
+ * Pre-push stale-HEAD guard + safe behind-only refresh for fix-task dispatches
+ * (P-c8f2d5e3; safe-refresh extension W-mrza78rc001s6241).
+ *
+ * When the engine reuses an existing worktree on a PR branch, its local HEAD
+ * can sit behind origin/<branch> for two very different reasons:
+ *
+ *   1. The branch was force-pushed / rebased upstream so local history and
+ *      remote history DIVERGED. Pushing from here silently overwrites the
+ *      rebased tip — a confirmed silent-overwrite footgun. This MUST be
+ *      refused.
+ *   2. The branch simply advanced on origin (more commits pushed) while the
+ *      fresh, engine-owned, clean worktree has NO local-only commits. This is
+ *      a plain fast-forward; refusing it needlessly aborts otherwise-healthy
+ *      fix dispatches (the recurring PR #921 / #944 failures). Here we can
+ *      safely refresh to the remote tip before the agent starts.
  *
- * 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.
+ * The helper runs `git fetch origin <branch>` then computes both the behind
+ * (`HEAD..origin/<branch>`) and ahead (`origin/<branch>..HEAD`) counts:
  *
- * 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.
+ *   - behind == 0                         → `{ ok: true, behindCount: 0 }`
+ *   - behind > 0 && ahead > 0 (diverged)  → throw STALE_HEAD (fail closed)
+ *   - behind > 0 && ahead == 0 (pure behind), worktree clean & engine-owned,
+ *     and `autoRefresh` is on → `git merge --ff-only origin/<branch>` and
+ *     return `{ ok: true, refreshed: true, behindCount, aheadCount: 0,
+ *     previousHead, newHead }`
+ *   - anything unproven (dirty tree, cannot prove engine ownership, ahead
+ *     lookup failed, ff-only rejected after bounded retries) → throw
+ *     STALE_HEAD (fail closed, never discards data)
  *
- * 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
+ * Cleanliness and ahead/behind are RE-COMPUTED immediately before the ref
+ * change to close the race where the branch moved (locally or via a concurrent
+ * fetch) between the checks and the merge. A remote that advances again during
+ * preparation triggers bounded re-evaluation (`maxRefreshAttempts`) rather than
+ * an opaque failure — each attempt re-fetches and re-decides.
+ *
+ * `--ff-only` is intentionally non-destructive: it errors (leaving HEAD
+ * untouched) whenever HEAD is no longer an ancestor of origin/<branch>, so no
+ * local commit or working-tree change is ever discarded. Branch continuity is
+ * preserved (HEAD stays on the same local branch, fast-forwarded) which keeps
+ * the agent's later `--force-with-lease` push safe.
+ *
+ * The fetch is best-effort: a branch missing on origin (first push on a fresh
+ * branch, common for shared-branch plan items) returns
+ * `{ ok: true, skipped: 'no-upstream' }`; any other fetch failure returns
+ * `{ ok: true, skipped: 'fetch-failed' }` so transient network issues don't
  * brick an otherwise-healthy dispatch.
  *
  * @param {object} args
@@ -230,10 +282,25 @@ function formatProcessExitSentinel(exitCode, signal) {
  * @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
+ * @param {boolean}  [args.autoRefresh=true] - Enable safe behind-only refresh
+ * @param {function} [args.isEngineOwned] - Predicate(cwd) proving engine
+ *   ownership; defaults to the `.minions-worktree` marker check
+ * @param {number}   [args.maxRefreshAttempts=3] - Bounded re-evaluation budget
+ * @returns {Promise<{ok: true, behindCount: number, aheadCount?: number,
+ *   refreshed?: boolean, previousHead?: string, newHead?: string,
+ *   skipped?: string}>}
+ * @throws {Error & {code: 'STALE_HEAD'}} when local HEAD is behind origin and
+ *   cannot be safely fast-forwarded
  */
-async function assertStaleHeadOk({ branch, cwd, exec, gitOpts } = {}) {
+async function assertStaleHeadOk({
+  branch,
+  cwd,
+  exec,
+  gitOpts,
+  autoRefresh = true,
+  isEngineOwned,
+  maxRefreshAttempts = 3,
+} = {}) {
   if (!branch) throw new Error('assertStaleHeadOk: branch is required');
   if (!cwd) throw new Error('assertStaleHeadOk: cwd is required');
   const execFn = typeof exec === 'function'
@@ -241,39 +308,114 @@ async function assertStaleHeadOk({ branch, cwd, exec, gitOpts } = {}) {
     : 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' };
+  // Proof of engine ownership. Absence = cannot prove current-dispatch-safe,
+  // so we never mutate the ref. Defaults to the `.minions-worktree` marker the
+  // engine stamps on every worktree it creates (engine.js writeWorktreeOwnerMarker).
+  const ownerOk = () => {
+    if (typeof isEngineOwned === 'function') {
+      try { return !!isEngineOwned(cwd); } catch { return false; }
     }
-    // Other failures (network/auth/timeout) — skip rather than block.
-    return { ok: true, behindCount: 0, skipped: 'fetch-failed' };
-  }
+    try { return require('./shared').hasWorktreeOwnerMarker(cwd); } catch { return false; }
+  };
 
-  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 attempts = Math.max(1, Math.trunc(Number(maxRefreshAttempts) || 0));
+  let lastBehind = 0;
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    // Best-effort fetch, re-run each attempt so a remote that advanced during
+    // preparation is re-observed. Branch-missing-on-origin is a legitimate
+    // state (first push on a freshly-cut feature branch) and must NOT block.
+    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 behind;
+    try {
+      behind = await _revListCount(execFn, `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' };
+    }
+    if (!Number.isFinite(behind) || behind <= 0) {
+      return { ok: true, behindCount: Number.isFinite(behind) ? behind : 0 };
+    }
+    lastBehind = behind;
+
+    // Behind > 0. Distinguish a safe pure-behind fast-forward from an unsafe
+    // divergence (any local-only commit).
+    let ahead;
+    try {
+      ahead = await _revListCount(execFn, `origin/${branch}..HEAD`, opts);
+    } catch {
+      ahead = NaN; // unknown → fail closed below
+    }
+
+    const canRefresh = autoRefresh
+      && Number.isFinite(ahead) && ahead === 0
+      && ownerOk();
+    if (!canRefresh) {
+      break; // diverged / unproven → fall through to STALE_HEAD (fail closed)
+    }
+
+    // Worktree must be clean (ignoring the engine ownership marker) — never
+    // fast-forward over uncommitted work.
+    let dirty;
+    try {
+      dirty = await _worktreeDirtyFiles(execFn, opts);
+    } catch {
+      break; // couldn't prove cleanliness → fail closed
+    }
+    if (dirty.length > 0) break;
+
+    // Re-compute ahead/behind IMMEDIATELY before changing the ref to close the
+    // race where the branch moved between the checks and the merge.
+    let behind2, ahead2;
+    try {
+      behind2 = await _revListCount(execFn, `HEAD..origin/${branch}`, opts);
+      ahead2 = await _revListCount(execFn, `origin/${branch}..HEAD`, opts);
+    } catch {
+      continue; // transient — bounded re-evaluation
+    }
+    if (!Number.isFinite(behind2) || behind2 <= 0) {
+      // Concurrently became current — nothing to refresh, nothing stale.
+      return { ok: true, behindCount: 0, refreshed: false };
+    }
+    if (!Number.isFinite(ahead2) || ahead2 !== 0) {
+      break; // became divergent under us → fail closed
+    }
+
+    let previousHead = null;
+    try { previousHead = String(await execFn('git rev-parse HEAD', opts)).trim(); } catch { /* best effort */ }
+    try {
+      await execFn(`git merge --ff-only "origin/${branch}"`, opts);
+    } catch {
+      continue; // ref moved under us → bounded re-evaluation, never destructive
+    }
+    let newHead = null;
+    try { newHead = String(await execFn('git rev-parse HEAD', opts)).trim(); } catch { /* best effort */ }
+    return {
+      ok: true,
+      refreshed: true,
+      behindCount: behind2,
+      aheadCount: 0,
+      previousHead,
+      newHead,
+    };
   }
+
   const err = new Error(
-    `PR branch was rebased; local HEAD is stale (${behindCount} commits behind origin). ` +
+    `PR branch was rebased; local HEAD is stale (${lastBehind} commits behind origin). ` +
     `Run \`git pull --rebase origin ${branch}\` first.`
   );
   err.code = 'STALE_HEAD';
-  err.behindCount = behindCount;
+  err.behindCount = lastBehind;
   err.branch = branch;
   throw err;
 }

package/engine.js

@@ -4778,7 +4778,9 @@ async function spawnAgent(dispatchItem, config) {
         exec: execAsync,
         gitOpts: { ..._gitOpts, timeout: 15000 },
       });
-      if (guard.skipped) {
+      if (guard.refreshed) {
+        log('info', `Stale-HEAD guard fast-forwarded ${id} (${branchName}) ${guard.behindCount} commit(s) to origin tip: ${guard.previousHead?.slice(0, 8)} → ${guard.newHead?.slice(0, 8)}`);
+      } else if (guard.skipped) {
         log('info', `Stale-HEAD guard skipped for ${id} (${branchName}): ${guard.skipped}`);
       }
     } catch (err) {

package/package.json

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