@yemi33/minions 0.1.2345 → 0.1.2347

package/engine/shared.js

@@ -3193,6 +3193,24 @@ const ENGINE_DEFAULTS = {
     'build-reports': 14,
     'reviews': 30,
   },
+  // W-mr973knu — structural consolidation for the KB sweep (PRIMARY balloon
+  // fix; TTL above is the secondary safety net). The sweep groups boilerplate
+  // transient-category notes by (category, agent, kind, time-bucket) — where
+  // kind is the agent-failure `failureClass`, or a no-op / merge-conflict fix
+  // report — and rolls any group of at least `minGroupSize` notes into a single
+  // recoverable digest (`_digest-<agent>-<kind>-<period>.md`), archiving the
+  // originals to knowledge/_swept/. Unlike TTL expiry this collapses RECENT
+  // duplication too, so the KB shrinks continuously instead of only aging out.
+  // Only `categories` listed here are consolidated; durable categories
+  // (architecture, conventions) and per-agent memory are never touched.
+  // config.engine.kbConsolidation is merged over these defaults; set
+  // `enabled: false` or `categories: []` to disable.
+  kbConsolidation: {
+    enabled: true,
+    categories: ['project-notes', 'build-reports', 'reviews'],
+    minGroupSize: 5, // collapse a group only once it reaches this many near-duplicate notes
+    periodDays: 7,   // one digest per (agent, kind) per this many days
+  },
   // W-mqtvnnj1000357fa — fleet-wide fallback for live-checkout auto-stash. When
   // true, a dirty live-checkout tree is `git stash push --include-untracked`'d
   // before dispatch instead of failing with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY,
@@ -4698,12 +4716,19 @@ function mutateWatches(mutator) {
 function mutateMetrics(mutator) {
   const metricsPath = path.join(MINIONS_DIR, 'engine', 'metrics.json');
   const store = require('./metrics-store');
+  // W-mradg74d000rfd45 — the JSON mirror is now written INSIDE
+  // applyMetricsMutation's SQL transaction (before commit), not here
+  // after the fact. Mirroring post-commit left a cross-process window
+  // where a sibling process (dashboard vs. engine — separate Node
+  // processes, each with its own in-memory mirror-hash cache) could
+  // observe the newly committed SQL rows before the JSON file caught up
+  // and read stale/missing metrics off the sidecar. See
+  // metrics-store.js#applyMetricsMutation for the full rationale.
   const { wrote, result } = store.applyMetricsMutation((m) => {
     if (!m || typeof m !== 'object') m = {};
     return mutator(m) || m;
-  });
+  }, { mirrorPath: metricsPath });
   if (wrote) {
-    try { store._mirrorJsonFromSql(metricsPath); } catch { /* mirror best-effort */ }
     try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
   }
   return result;
@@ -4877,6 +4902,7 @@ const FAILURE_CLASS = {
   LIVE_CHECKOUT_MID_OPERATION: 'live-checkout-mid-operation', // P-a7f3c1d9 (live-checkout dispatch mode): spawnAgent could not switch/create the target branch in project.localPath because the operator tree is mid-operation — an in-progress merge/rebase/cherry-pick/bisect or a detached HEAD. Distinct from LIVE_CHECKOUT_DIRTY (uncommitted changes): here the tree may be clean but the branch op cannot proceed. Engine refuses to spawn (it never runs `git reset`/`git clean`/`git rebase --abort` against the operator tree). Non-retryable — operator must finish or abort the in-progress operation, or checkout a branch, before re-dispatch.
   LIVE_CHECKOUT_BLOB_FETCH: 'live-checkout-blob-fetch', // PL-live-checkout-reliability-hardening (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because the tree could not be materialized — on a Scalar/GVFS-managed ADO partial (blobless) clone, switching onto a branch whose tree differs from HEAD hydrates the changed paths' blobs through the GVFS cache server (`*.gvfscache.dev.azure.com`), a different endpoint than the main git remote that receives NO auth in the headless engine shell, so the fetch fails DETERMINISTICALLY. Distinct from LIVE_CHECKOUT_FAILED (transient) because retrying reproduces it identically — surfaced once as an operator-actionable refusal instead of retry-storming to the cap. Non-retryable — the operator hydrates the branch once with their own credentials (`git checkout <branch>` interactively, or `scalar prefetch` / `git -C <repo> fetch`), then re-dispatches. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded half-populated.
   LIVE_CHECKOUT_WORKTREE_CONFLICT: 'live-checkout-worktree-conflict', // W-mr28h2j2000y0de1 (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because that exact branch is ALSO checked out in a SECOND worktree elsewhere (a leftover from a prior isolated-worktree dispatch, a manually-created worktree, or a stale worktree left by a checkoutMode change). git refuses deterministically with `fatal: '<branch>' is already used by worktree at '<path>'`. Distinct from LIVE_CHECKOUT_FAILED (transient) because this is a STRUCTURAL conflict — it does NOT clear on retry, ever, until a human or the engine removes/reassigns the other worktree; retrying just reproduces it identically and burns maxRetries. Non-retryable — the operator either `git worktree remove <path>` (freeing the branch) if that worktree is stale, or finishes/commits/pushes from it directly if it holds real WIP. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded.
+  LIVE_CHECKOUT_STALE_BASE: 'live-checkout-stale-base', // W-mr98op8w000ma4ad (live-checkout dispatch mode, STALE-BASE GUARD): spawnAgent was about to fork a NEW branch off the operator's current HEAD while HEAD sits on the project base ref (mainRef), but the LOCAL mainRef tip has DIVERGED from origin/<mainRef> with unpushed commit(s) (`git rev-list --count origin/<mainRef>..<mainRef>` > 0). Forking would silently inherit that COMMITTED contamination into the new branch and its PR — the exact scope-contamination class first seen on ADO PR 5411214 and recurring on AB#12016662 / ADO PR 5419146. Survives the dirty check (contamination is committed, not uncommitted) and cannot be caught by a headBranch !== mainRef check (headBranch IS mainRef here). Detected WITHOUT a fetch (issue #226) via the existing origin/<mainRef> remote-tracking ref. Distinct from LIVE_CHECKOUT_FAILED (transient) because the contaminated local base does NOT change on retry — it reproduces identically until a human reconciles the local base branch. Non-retryable — the engine NEVER resets/cleans the operator's local mainRef; the operator must reconcile it (push/reset/rebase their own way), then re-dispatch. The guard SKIPS (proceeds normally) when HEAD is not on mainRef, when no local origin/<mainRef> ref exists (local-only/no-remote repo), or when the divergence count cannot be computed.
   LIVE_CHECKOUT_WRONG_BASE: 'live-checkout-wrong-base', // W-mr3lunnq000o9f41 (live-checkout dispatch mode): a NEW-branch fork was requested but the operator's checkout HEAD is on an unrelated topic/feature branch, NOT the project base (mainRef), and prepareLiveCheckout could not switch to a LOCAL base ref (no `refs/heads/<mainRef>`, or the local checkout itself failed). Forking off the stale HEAD would silently bake every commit already on that branch into the new branch AND its PR — committed-history scope contamination that survives the dirty/mid-operation preflights (the ADO PR 5411214 incident: ~22 unrelated OCM files, author-disavowed). The engine never fetches origin/<mainRef> in live mode (issue #226) so it cannot self-heal a missing local base. Non-retryable — the operator must `git checkout <mainRef>` in the operator checkout before re-dispatch. Does NOT fire for PR-targeted fixes or shared-branch continuations (those pass allowNonMainBase, intentionally continuing a non-main branch), nor when HEAD is already on mainRef, nor when a local mainRef ref exists (the guard switches to it and forks cleanly). OPT-IN AUTO-RECOVERY (`liveCheckoutAutoBaseRepair`, per-project > fleet-wide, default OFF): when enabled AND a `refs/remotes/origin/<mainRef>` remote-tracking ref exists, the guard materializes a local `<mainRef>` branch from it (a LOCAL ref op — still no `git fetch`, issue #226 preserved; origin/<mainRef> IS the base so no contamination) and forks cleanly instead of failing — eliminating the manual `git checkout <mainRef>` step. Still fails closed when neither a local base nor an origin-tracking base ref exists, or when the base checkout itself fails/hangs.
   INVALID_WORKDIR: 'invalid-workdir',     // P-714ef144: dispatch carried a meta.workdir override that failed validation — non-string, absolute path, drive-letter prefix, null byte, ".." segment, or post-resolve containment escape against project.localPath / worktree root. Engine refuses to spawn (the subpath would either be unreachable on disk or point outside the operator's allowed surface). Non-retryable — operator must fix the WI's meta.workdir before re-dispatch. Inbox alert lists the offending value + the resolved-vs-base mismatch.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).

package/engine.js

@@ -2934,6 +2934,83 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // W-mr98op8w000ma4ad: STALE-BASE GUARD refusal. prepareLiveCheckout was about
+    // to fork a NEW branch off the operator's current HEAD while HEAD sits on the
+    // project base ref (mainRef), but the LOCAL mainRef tip has diverged from
+    // origin/<mainRef> with unpushed commit(s). Forking would silently bake that
+    // committed contamination into the new branch and its PR (the scope-leak class
+    // first seen on ADO PR 5411214, recurring on AB#12016662 / ADO PR 5419146).
+    // Deterministic — a contaminated local base reproduces identically on retry —
+    // so it gets its own non-retryable FAILURE_CLASS instead of LIVE_CHECKOUT_FAILED's
+    // bounded retry-storm. The engine NEVER resets/cleans the operator's local
+    // mainRef; the operator must reconcile it themselves, then re-dispatch.
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'stale-main') {
+      const _staleMainRef = typeof _liveResult.mainRef === 'string' && _liveResult.mainRef ? _liveResult.mainRef : 'main';
+      const _staleAhead = Number.isFinite(_liveResult.ahead) ? _liveResult.ahead : 0;
+      const _localSha = typeof _liveResult.localMainSha === 'string' && _liveResult.localMainSha ? _liveResult.localMainSha : '(unknown)';
+      const _originSha = typeof _liveResult.originMainSha === 'string' && _liveResult.originMainSha ? _liveResult.originMainSha : '(unknown)';
+      const _alertBody = [
+        '# Live-checkout blocked: local base branch has diverged (stale/contaminated base)',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**New branch (refused):** ${branchName}`,
+        `**Base ref:** ${_staleMainRef}`,
+        `**Local ${_staleMainRef}:** ${_localSha}`,
+        `**origin/${_staleMainRef}:** ${_originSha}`,
+        `**Unpushed commits on local ${_staleMainRef}:** ${_staleAhead}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine refused to fork \`${branchName}\` off local \`${_staleMainRef}\` because your local \`${_staleMainRef}\` is **${_staleAhead} commit(s) ahead of \`origin/${_staleMainRef}\`**. Those commits were never pushed — forking a new branch (and its PR) off this base would silently inherit them, contaminating an otherwise-clean change with unrelated commits. The working tree was clean (no uncommitted changes), so the dirty check could not catch this: the contamination is COMMITTED. Your tree was left untouched — the engine never resets, cleans, or rebases your \`${_staleMainRef}\`.`,
+        '',
+        '## Recovery',
+        '',
+        `Reconcile your local \`${_staleMainRef}\` so it no longer carries unpushed commits, then re-dispatch. Pick ONE, depending on whether those commits are real work:`,
+        '',
+        `1. **If the extra commits are real work you want to keep** — move them onto their own branch, then reset \`${_staleMainRef}\` to the remote:`,
+        '',
+        '```',
+        `git -C "${cwd}" branch salvage-${_staleMainRef} ${_staleMainRef}`,
+        `git -C "${cwd}" checkout ${_staleMainRef}`,
+        `git -C "${cwd}" reset --hard origin/${_staleMainRef}`,
+        '```',
+        '',
+        `2. **If the extra commits are leftover junk** (e.g. a prior dispatch's abandoned WIP) — discard them by resetting \`${_staleMainRef}\` to the remote (this DISCARDS those commits):`,
+        '',
+        '```',
+        `git -C "${cwd}" checkout ${_staleMainRef}`,
+        `git -C "${cwd}" reset --hard origin/${_staleMainRef}`,
+        '```',
+        '',
+        `The salvage branch in option 1 keeps the commits recoverable; both leave \`${_staleMainRef}\` matching \`origin/${_staleMainRef}\` so the next dispatch forks off a clean base.`,
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-stale-base-${_wiIdForAlert}`, _alertBody); }
+      catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
+      try {
+        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (_wiPath && dispatchItem.meta?.item?.id) {
+          mutateJsonFileLocked(_wiPath, (data) => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
+            if (wi) wi._pendingReason = 'live_checkout_stale_base';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = `live-checkout blocked: local ${_staleMainRef} is ${_staleAhead} commit(s) ahead of origin/${_staleMainRef} (would contaminate ${branchName})`;
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        `Live-checkout STALE-BASE GUARD: forking ${branchName} off local ${_staleMainRef} would inherit ${_staleAhead} unpushed commit(s) not on origin/${_staleMainRef}. Deterministic — operator must reconcile the local base branch (the engine never resets it) before re-dispatch. Retrying is provably useless.`,
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
     // PL-live-checkout-reliability-hardening: a clean spawn clears the two-strike
     // dirty counter so a project that was transiently dirty once isn't treated as

package/package.json

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