@yemi33/minions 0.1.2351 → 0.1.2352

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.2351",
+  "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"