@yemi33/minions 0.1.2350 → 0.1.2352

package/engine/live-checkout.js

@@ -389,6 +389,45 @@ function _defaultWriteInboxNote(slug, content) {
   return require('./dispatch').writeInboxAlert(slug, content);
 }
 
+// Best-effort, side-effect-light resolution of `mainRef` as a restore target
+// when a captured originalRef is found to be contaminated (see
+// ENGINE_DISPATCH_BRANCH_PATTERN above). Mirrors the STALE-BASE GUARD's
+// local-main / auto-base-repair fallback (Step 4d) but never switches HEAD
+// itself — it only materializes a local `<mainRef>` branch (a plain ref op,
+// no checkout, no fetch, issue #226 preserved) when auto-base-repair is
+// enabled and no local ref already exists. Returns `{ ref, type }` on success
+// or `{ ref: null, type: null }` when mainRef cannot be resolved without a
+// fetch and auto-base-repair is disabled or unavailable.
+async function _resolveMainRefForRestore({ git, baseOpts, mainRef, autoBaseRepair, _resolveAutoBaseRepair, localPath, logFn }) {
+  try {
+    await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+    return { ref: mainRef, type: 'branch' };
+  } catch { /* fall through to auto-repair */ }
+
+  let wantBaseRepair = false;
+  if (typeof autoBaseRepair === 'boolean') {
+    wantBaseRepair = autoBaseRepair;
+  } else {
+    const resolver = (typeof _resolveAutoBaseRepair === 'function') ? _resolveAutoBaseRepair : _defaultResolveAutoBaseRepair;
+    try { wantBaseRepair = !!resolver(localPath); } catch { wantBaseRepair = false; }
+  }
+  if (!wantBaseRepair) return { ref: null, type: null };
+
+  try {
+    await git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${mainRef}`], baseOpts);
+  } catch {
+    return { ref: null, type: null };
+  }
+  try {
+    await git(['branch', '--no-track', mainRef, `refs/remotes/origin/${mainRef}`], baseOpts);
+    logFn('info',
+      `live-checkout: materialized local '${mainRef}' from 'origin/${mainRef}' (no fetch, issue #226 preserved) to correct a contaminated originalRef.`);
+    return { ref: mainRef, type: 'branch' };
+  } catch {
+    return { ref: null, type: null };
+  }
+}
+
 async function prepareLiveCheckout(opts = {}) {
   const {
     localPath,
@@ -842,6 +881,32 @@ async function prepareLiveCheckout(opts = {}) {
     // Plain checkout — NO --force, NO -B, NO pull. Operator owns local commits.
     const failed = await runCheckout(['checkout', branchName], { creating: false });
     if (failed) return failed;
+    // ── originalRef contamination invariant (W-mrb6an8300058fd8). ──────────
+    // originalRef was captured at Step 3 BEFORE this checkout, from whatever
+    // HEAD happened to be. If it itself looks like a prior dispatch's own
+    // engine-managed branch (`_looksLikeAgentBranch` — the same `work/<id>`
+    // check issue #608's dirty-tree self-heal uses above) — and this isn't an
+    // explicit PR-continuation (allowNonMainBase) — it is never a sane restore
+    // target: prefer mainRef instead, while still surfacing the anomaly via
+    // logFn rather than silently swallowing it.
+    if (!allowNonMainBase && originalRefType === 'branch' && originalRef && originalRef !== mainRef &&
+        _looksLikeAgentBranch(originalRef)) {
+      logFn(
+        `[live-checkout] originalRef anomaly: HEAD was on engine-managed branch '${originalRef}' before checking out '${branchName}' — ` +
+        `this looks like leftover contamination from an earlier dispatch, not a sane restore target. Attempting to correct to '${mainRef}'.`,
+        'warn'
+      );
+      const corrected = await _resolveMainRefForRestore({ git, baseOpts, mainRef, autoBaseRepair, _resolveAutoBaseRepair, localPath, logFn });
+      if (corrected.ref) {
+        originalRef = corrected.ref;
+        originalRefType = corrected.type;
+      } else {
+        logFn(
+          `[live-checkout] originalRef anomaly: could not resolve '${mainRef}' as a corrected restore target (no local ref, auto-base-repair disabled, or 'origin/${mainRef}' missing) — leaving originalRef as the contaminated '${originalRef}'; a human should verify the operator checkout manually.`,
+          'warn'
+        );
+      }
+    }
     return { ok: true, branch: branchName, created: false, originalRef, originalRefType };
   }
 
@@ -983,6 +1048,21 @@ async function prepareLiveCheckout(opts = {}) {
       }
       logFn('info',
         `live-checkout: HEAD was on '${headBranch}' (not base '${mainRef}') — switched to local '${mainRef}' before forking '${branchName}' (no fetch, issue #226 preserved)`);
+      // ── originalRef correction (W-mrb6an8300058fd8). ─────────────────────
+      // originalRef/originalRefType were captured at Step 3 from the STALE
+      // headBranch, BEFORE this self-heal ran. The tree has now been switched
+      // to the CORRECTED mainRef, so the value returned to the caller (and
+      // persisted on the dispatch record — engine.js spawnAgent ~line
+      // 3106-3122) must reflect mainRef, not the stale branch. Otherwise
+      // restoreLiveCheckoutAtDispatchEnd would put the operator checkout BACK
+      // onto the stale branch at dispatch end, propagating the contamination
+      // into every subsequent live-mode dispatch that captures HEAD (the
+      // exact recurrence observed on minions-opg 2026-07-07: HEAD landed on
+      // 'main' via this self-heal, but the persisted originalRef still said
+      // 'work/sched-daily-remove-merged-prs-…', so the dispatch-end restore
+      // switched the operator checkout back onto that stale branch).
+      originalRef = mainRef;
+      originalRefType = 'branch';
     }
   }
 

package/engine/queries.js

@@ -2878,63 +2878,72 @@ function _resolveCommonGitDir(gitDir) {
   return path.isAbsolute(raw) ? raw : path.resolve(gitDir, raw);
 }
 
-// Enumerate the per-project git ref files we watch for cache-busting:
-// logs/HEAD (per-worktree gitdir), FETCH_HEAD + refs/remotes/origin/* (common
-// gitdir for linked worktrees). Same paths as the fast-state mtime tracker
-// so callers see a coherent view across surfaces.
+// Enumerate the per-project git ref files we watch for cache-busting, split
+// into two groups (W-mrb6qnuc000785b2):
+//   identityFiles — HEAD + logs/HEAD, resolved against the PER-WORKTREE
+//     gitdir (`_resolveGitDir`). These are never shared across linked
+//     worktrees of the same repo, so a change here means THIS worktree's
+//     own branch/commit identity moved (opg-microsoft/minions#295, #381) —
+//     the only signal allowed to gate `gitStale: true` / hide the branch
+//     name in the dashboard.
+//   sharedFiles — FETCH_HEAD + refs/remotes/origin/<comparator>, resolved
+//     against the COMMON gitdir (`_resolveCommonGitDir`). These are written
+//     by ANY linked worktree of the same repo doing a `git fetch` — a
+//     legitimate signal that ahead/behind against origin may be stale and
+//     worth recomputing, but NOT a signal that this worktree's own branch
+//     identity changed. Lumping these into the same boolean as identityFiles
+//     produced a permanent "(refreshing...)" chip on repos with several
+//     active worktrees sharing one commondir, since some other worktree's
+//     fetch touches these files constantly.
+// Same paths as the fast-state mtime tracker so callers see a coherent view
+// across surfaces.
 function _projectGitRefFiles(localPath, configuredMainBranch) {
   const gitDir = _resolveGitDir(localPath);
   if (!gitDir) return null;
   const commonGitDir = _resolveCommonGitDir(gitDir);
-  const files = [
+  const identityFiles = [
     // opg-microsoft/minions#381 — track HEAD directly so a bare `git checkout`
     // (which rewrites .git/HEAD but may not advance logs/HEAD when reflog is
     // disabled or when the snapshot already reflects the post-checkout mtime)
-    // still triggers refsAdvanced=true and the gitStale marker on the next call.
+    // still triggers identityAdvanced=true and the gitStale marker on the
+    // next call.
     path.join(gitDir, 'HEAD'),
     path.join(gitDir, 'logs', 'HEAD'),
+  ];
+  const sharedFiles = [
     path.join(commonGitDir, 'FETCH_HEAD'),
   ];
   const comparator = configuredMainBranch && String(configuredMainBranch).trim();
   if (comparator) {
-    files.push(path.join(commonGitDir, 'refs', 'remotes', 'origin', comparator));
+    sharedFiles.push(path.join(commonGitDir, 'refs', 'remotes', 'origin', comparator));
   }
-  return files;
+  return { identityFiles, sharedFiles };
 }
 
-// Snapshot mtimeMs for each ref file. Missing files record `null`. Used as
-// the baseline that the next `getProjectGitStatus` call compares against —
-// inequality, not threshold-vs-timestamp, so the result is precision-
-// independent (Windows `Date.now()` can be 15ms coarse while NTFS mtime is
+// Snapshot mtimeMs for each ref file, grouped by identity vs shared (see
+// `_projectGitRefFiles`). Missing files record `null`. Used as the baseline
+// that the next `getProjectGitStatus` call compares against — inequality,
+// not threshold-vs-timestamp, so the result is precision-independent
+// (Windows `Date.now()` can be 15ms coarse while NTFS mtime is
 // sub-millisecond, which used to make threshold checks fire spuriously on
 // freshly-written files).
 function _snapshotProjectGitRefMtimes(localPath, configuredMainBranch) {
-  const files = _projectGitRefFiles(localPath, configuredMainBranch);
-  if (!files) return null;
-  const out = Object.create(null);
-  for (const f of files) {
-    try { out[f] = fs.statSync(f).mtimeMs; }
-    catch { out[f] = null; /* ENOENT recorded as null — flipping to present must bust */ }
-  }
-  return out;
+  const groups = _projectGitRefFiles(localPath, configuredMainBranch);
+  if (!groups) return null;
+  const statMtime = f => {
+    try { return fs.statSync(f).mtimeMs; }
+    catch { return null; /* ENOENT recorded as null — flipping to present must bust */ }
+  };
+  const identity = Object.create(null);
+  for (const f of groups.identityFiles) identity[f] = statMtime(f);
+  const shared = Object.create(null);
+  for (const f of groups.sharedFiles) shared[f] = statMtime(f);
+  return { identity, shared };
 }
 
-// Return true when ANY tracked ref file's mtime (or existence) differs from
-// the snapshot captured during the last probe. Replaces the older threshold-
-// vs-cachedTs check that suffered from `Date.now()`/`mtimeMs` resolution
-// races on Windows. Lets `getProjectGitStatus` bypass its 15s TTL after
-// `git pull`, `git fetch`, `git checkout`, etc. so the next /api/status
-// reflects the new HEAD / ahead-behind within one SPA poll instead of
-// waiting out the TTL (W-mphdmr8c00030124). Cost: 2-3 statSync per call —
-// well under the 'cheap' budget.
-function _projectGitRefsAdvancedSince(localPath, configuredMainBranch, snapshot) {
-  // No snapshot yet (legacy entry shape OR first call) — preserve the
-  // current cached value so the TTL-only fast-path still works. A real
-  // change still surfaces on the next /api/status because the fast-state
-  // mtime tracker watches the same files and will bust the upstream cache.
-  if (!snapshot) return false;
-  const current = _snapshotProjectGitRefMtimes(localPath, configuredMainBranch);
-  if (!current) return false;
+// Compare two flat {file: mtimeMs} maps and return true if ANY tracked
+// file's mtime (or existence) differs between them.
+function _refGroupChanged(current, snapshot) {
   for (const file of Object.keys(snapshot)) {
     if (current[file] !== snapshot[file]) return true;
   }
@@ -2946,16 +2955,54 @@ function _projectGitRefsAdvancedSince(localPath, configuredMainBranch, snapshot)
   return false;
 }
 
+// Return `{ identityAdvanced, aheadBehindAdvanced }` describing which
+// tracked ref groups changed since `snapshot` (W-mrb6qnuc000785b2):
+//   identityAdvanced    — THIS worktree's own HEAD/logs/HEAD moved. The only
+//                         signal that should gate `gitStale: true`.
+//   aheadBehindAdvanced — identityAdvanced OR the shared commondir files
+//                         (FETCH_HEAD / refs/remotes/origin/<comparator>)
+//                         changed — from a fetch in ANY linked worktree of
+//                         the same repo. Gates nulling ahead/behind and
+//                         bypassing the TTL to schedule a refresh, but never
+//                         gates gitStale on its own.
+// Replaces the older single-boolean threshold-vs-cachedTs check that
+// suffered from `Date.now()`/`mtimeMs` resolution races on Windows. Lets
+// `getProjectGitStatus` bypass its 15s TTL after `git pull`, `git fetch`,
+// `git checkout`, etc. so the next /api/status reflects the new HEAD /
+// ahead-behind within one SPA poll instead of waiting out the TTL
+// (W-mphdmr8c00030124). Cost: 2-4 statSync per call — well under the
+// 'cheap' budget.
+function _projectGitRefsAdvancedSince(localPath, configuredMainBranch, snapshot) {
+  // No snapshot yet (legacy entry shape OR first call) — preserve the
+  // current cached value so the TTL-only fast-path still works. A real
+  // change still surfaces on the next /api/status because the fast-state
+  // mtime tracker watches the same files and will bust the upstream cache.
+  if (!snapshot) return { identityAdvanced: false, aheadBehindAdvanced: false };
+  const current = _snapshotProjectGitRefMtimes(localPath, configuredMainBranch);
+  if (!current) return { identityAdvanced: false, aheadBehindAdvanced: false };
+  const identityAdvanced = _refGroupChanged(current.identity, snapshot.identity);
+  const sharedAdvanced = _refGroupChanged(current.shared, snapshot.shared);
+  return { identityAdvanced, aheadBehindAdvanced: identityAdvanced || sharedAdvanced };
+}
+
 function getProjectGitStatus(localPath, configuredMainBranch = null) {
   const norm = String(localPath || '').replace(/\\/g, '/');
   if (!norm) return PROJECT_GIT_STATUS_MISSING;
   const key = _projectGitStatusCacheKey(localPath, configuredMainBranch);
   const now = Date.now();
   const cached = _projectGitStatusCache.get(key);
-  // Compute ref-mtime freshness once. Used twice below: to gate the TTL
-  // fast-path AND to decide whether the stale-while-revalidate return
-  // should null out the known-stale ahead/behind counters (#2848).
-  const refsAdvanced = !!(cached && _projectGitRefsAdvancedSince(localPath, configuredMainBranch, cached.refMtimes));
+  // Compute ref-mtime freshness once. Used below to gate the TTL fast-path
+  // AND to decide whether the stale-while-revalidate return should null out
+  // the known-stale ahead/behind counters (#2848) and/or flag gitStale
+  // (opg-microsoft/minions#295, #381) — split so a fetch from an unrelated
+  // worktree sharing this repo's commondir (FETCH_HEAD /
+  // refs/remotes/origin/<comparator>) only refreshes ahead/behind quietly
+  // and never flags THIS project's branch display as stale
+  // (W-mrb6qnuc000785b2).
+  const advancement = cached
+    ? _projectGitRefsAdvancedSince(localPath, configuredMainBranch, cached.refMtimes)
+    : { identityAdvanced: false, aheadBehindAdvanced: false };
+  const refsAdvanced = advancement.aheadBehindAdvanced;
   // Within TTL: short-circuit ONLY when no tracked git ref has advanced
   // past cached.ts. Without the mtime gate, a freshly-pulled repo serves
   // the pre-pull ahead/behind counts for up to 15s + one SPA poll (~19s
@@ -2989,28 +3036,39 @@ function getProjectGitStatus(localPath, configuredMainBranch = null) {
   if (!cached) return PROJECT_GIT_STATUS_PENDING;
   // When tracked git refs have advanced past the cached snapshot, the
   // cached ahead/behind counts are known to be stale (e.g. user just ran
-  // `git pull` / `git fetch` and the local checkout is now current).
-  // Returning the cached value as-is would briefly display a misleading
-  // "behind: 8" after the user has already pulled to current — see
-  // yemi33/minions#2848. Null those specific counters so the dashboard
+  // `git pull` / `git fetch` — from THIS worktree or any other worktree
+  // sharing the same repo commondir — and the local checkout is now
+  // current). Returning the cached value as-is would briefly display a
+  // misleading "behind: 8" after the user has already pulled to current —
+  // see yemi33/minions#2848. Null those specific counters so the dashboard
   // shows a pending state for ahead/behind until the background probe
-  // settles. TTL-expiry fall-throughs (refsAdvanced=false) still return the
-  // prior counters because nothing local has actually changed there.
+  // settles. TTL-expiry fall-throughs (aheadBehindAdvanced=false) still
+  // return the prior counters because nothing has actually changed there.
   //
-  // opg-microsoft/minions#295: gitBranch/gitDirty on the cached value are
-  // ALSO known-stale once refs have advanced (e.g. the operator ran
-  // `git switch` / `git pull` directly in a live checkout outside the
-  // dashboard). The cached value still carries the OLD branch name, so a
-  // consumer rendering `gitBranch` as authoritative briefly shows the
-  // pre-switch branch as if current. We keep the cached gitBranch/gitDirty
-  // on the object (so the next poll can self-correct without a flash of
-  // "missing"), but add a `gitStale: true` marker so render paths can avoid
-  // presenting the known-stale branch/dirty as current and fall back to a
-  // neutral "refreshing" presentation. The async refresh scheduled above
-  // self-corrects on the next poll. We do NOT add a synchronous git probe
-  // here — status rebuild must never block the event loop.
+  // opg-microsoft/minions#295 / #381: gitBranch/gitDirty on the cached
+  // value are ALSO known-stale, but ONLY when THIS project's OWN
+  // per-worktree HEAD/logs/HEAD moved (identityAdvanced) — e.g. the
+  // operator ran `git switch` / `git pull` directly in a live checkout
+  // outside the dashboard, or a bare `git checkout` rewrote HEAD. A shared
+  // commondir file (FETCH_HEAD / refs/remotes/origin/<comparator>) changing
+  // because some OTHER linked worktree of the same repo fetched is NOT
+  // evidence this project's branch identity changed — gating gitStale on
+  // that shared signal produced a permanently-stuck "(refreshing...)" chip
+  // on repos with several active worktrees (W-mrb6qnuc000785b2). The cached
+  // value still carries the OLD branch name, so a consumer rendering
+  // `gitBranch` as authoritative briefly shows the pre-switch branch as if
+  // current when identityAdvanced fires. We keep the cached
+  // gitBranch/gitDirty on the object (so the next poll can self-correct
+  // without a flash of "missing"), but add a `gitStale: true` marker so
+  // render paths can avoid presenting the known-stale branch/dirty as
+  // current and fall back to a neutral "refreshing" presentation. The async
+  // refresh scheduled above self-corrects on the next poll. We do NOT add a
+  // synchronous git probe here — status rebuild must never block the event
+  // loop.
   if (refsAdvanced) {
-    return { ...cached.value, ahead: null, behind: null, gitStale: true };
+    const next = { ...cached.value, ahead: null, behind: null };
+    if (advancement.identityAdvanced) next.gitStale = true;
+    return next;
   }
   return cached.value;
 }

package/package.json

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