@yemi33/minions 0.1.2366 → 0.1.2368

package/docs/README.md

@@ -7,6 +7,7 @@ A navigable index of every Markdown file under `docs/`. Entries are grouped by a
 Hands-on stories and distribution guides for people running or evaluating Minions.
 
 - [blog-first-successful-dispatch.md](blog-first-successful-dispatch.md) — Narrative walkthrough of the first end-to-end agent dispatch and the seven failed spawn attempts that preceded it.
+- [architecture-review-2026-07-09.md](architecture-review-2026-07-09.md) — Architecture review covering engine orchestration, SQL/JSON state boundaries, runtime/process recovery, worktree lifecycle, pipelines/schedules, and prompt assembly, verified against `origin/main` at `b1b83dd2`.
 - [documentation-audit-2026-07-09.md](documentation-audit-2026-07-09.md) — Verified user-facing documentation audit covering runtime, CLI, storage, routing, and broken-link corrections.
 - [distribution.md](distribution.md) — How Minions is published (this repo: `@opg-microsoft/minions` to GitHub Packages; paired peer `@yemi33/minions` to npm) and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
 - [onboarding.md](onboarding.md) — Condensed first-30-minutes walkthrough for a new operator.
@@ -46,6 +47,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [harness-transparency.md](harness-transparency.md) — The `harnessUsed` self-report contract: capture (agent reports the skills / MCPs / commands / docs it used) → ground (engine cross-checks against `_harnessPropagated` and annotates `grounded:true\|false`, never dropping) → surface (PR comment, final agent note, work-item modal).
 - [kb-dedup-duplicate-pair-investigation.md](kb-dedup-duplicate-pair-investigation.md) — Investigation-only pass diffing suspected duplicate KB filename groups (content-hash dedup for agent-authored reviews/build-reports) to confirm true full-body duplication before any fix is proposed.
 - [kb-pr3223-cascade-archiving.md](kb-pr3223-cascade-archiving.md) — Findings from PR #3223: cascade-archiving PRDs when their linked markdown plan is archived, including the per-concern try/catch pattern and `source_plan` basename-matching invariant in `handlePlansArchive` (`dashboard.js`).
+- [kb-pr696-merge-conflict-docs.md](kb-pr696-merge-conflict-docs.md) — Findings from PR #696: resolving a merge conflict in `docs/kb-sweep.md` with stale line-number citations to `engine/kb-sweep.js`.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-06-09 against `engine.js` `tickInner()` and `routing.md`.
+> Last verified: 2026-07-10 against `engine.js` `tickInner()` and `routing.md`.
 
 How the minions engine finds work and dispatches agents automatically.
 
@@ -28,16 +28,19 @@ tick()
        checkPlanCompletion()     Mark plans completed when all features done/in-pr
   2.7 pollPrHumanComments()      Poll PR threads for human comments (wall-clock cadence from prPollCommentsEvery × tickInterval, default ≈ 12min)
        reconcilePrs() (ADO+GH)   Reconciliation sweep (runs regardless of poll flags)
+      reconcileSharedBranchPrs() Backfill the PR store for shared-branch plans whose aggregate remote PR is untracked/under-linked (runs unconditionally, like the other recovery sweeps)
   2.9 stallRecovery()            Auto-retry failed items blocking pending deps (every 120 ticks)
   3a. pruneStalePrDispatches()   Clear pending PR dispatches whose underlying PRs no longer warrant action
-  3.  discoverWork()             Scan ALL linked projects for new tasks
-  4.  updateSnapshot()           Write identity/now.md
-  4a. memoryBaseline()           Sample RSS/heap/GC every memoryBaselineEveryTicks ticks (default 6 ≈ 60s)
-  4b. heapSnapshotRequest()      Serve a pending guard-token heap-snapshot request, if any
-  5.  dispatch                   Spawn agents for pending items (up to maxConcurrent)
+  3.  dispatch existing pending  Spawn agents for items already durable in dispatch.pending (up to maxConcurrent) — runs BEFORE discovery so a slow pre-dispatch validator can't starve already-queued work
+  4.  discoverWork()             Scan ALL linked projects for new tasks
+  5.  updateSnapshot()           Write identity/now.md
+  5a. memoryBaseline()           Sample RSS/heap/GC every memoryBaselineEveryTicks ticks (default 6 ≈ 60s)
+  5b. heapSnapshotRequest()      Serve a pending guard-token heap-snapshot request, if any
 ```
 
 > When `control.state === 'stopping'`, only steps 1–1c run; discovery and dispatch are skipped while live agents drain.
+>
+> Dispatch of already-pending work runs before `discoverWork()`, not after (`engine.js` comment: "Process pending dispatches before discovery. discoverWork() runs pre-dispatch LLM validation for newly found work; a slow validator must not starve runnable entries that are already durable in dispatch.pending.").
 
 ## Work Discovery
 

package/engine/lifecycle.js

@@ -2593,6 +2593,18 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
       }
     }
     target.lastReviewedAt = ts();
+    // W-mrej8p740006b0bf — SHA-based review freshness. Persist the exact head
+    // SHA the review verdict actually evaluated instead of leaning on
+    // lastReviewedAt/lastPushedAt ordering, which flips "already reviewed"
+    // true purely because the verdict was *recorded* after a mid-review push
+    // landed — even though the verdict evaluated the prior head. Prefer the
+    // SHA captured at dispatch time (meta.reviewHeadSha, stamped by
+    // engine.js's review/re-review dispatch builders); fall back to the
+    // current live head for older dispatches that predate that capture (best
+    // effort — matches the previous timestamp-only behavior for those).
+    const dispatchReviewedHeadSha = String(dispatchItem?.meta?.reviewHeadSha || '').trim();
+    const liveHeadShaAtCompletion = getPrFixBaselineHead(target);
+    target.reviewedHeadSha = dispatchReviewedHeadSha || liveHeadShaAtCompletion || target.reviewedHeadSha || '';
     // A verdict landed cleanly this time — clear any stale missing-verdict flag.
     delete target._reviewVerdictMissing;
     delete target._reviewVerdictMissingCount;

package/engine.js

@@ -7378,6 +7378,42 @@ function getPrCauseBase(pr) {
     || '';
 }
 
+// W-mrej8p740006b0bf — SHA-based review freshness. A review is only
+// considered to cover the PR's CURRENT head when the recorded
+// `reviewedHeadSha` (the exact SHA the completed review verdict evaluated —
+// stamped by lifecycle.js#updatePrAfterReview from the dispatch's captured
+// `meta.reviewHeadSha`) matches the live head. This replaces the previous
+// `pr.lastPushedAt <= pr.lastReviewedAt` timestamp-ordering check, which
+// flips true purely because the verdict was *persisted* after a mid-review
+// push landed — even though the verdict evaluated the prior head (root cause
+// of github:opg-microsoft/minions#821: a commit pushed while a review was in
+// flight silently suppressed automatic re-review). Falls back to the legacy
+// timestamp comparison for PR records that predate `reviewedHeadSha`
+// capture, so existing open PRs don't all spuriously need re-review the
+// moment this ships.
+function isPrReviewCurrent(pr) {
+  if (pr?.reviewedHeadSha) {
+    const currentHead = getPrCauseHead(pr);
+    return !!currentHead && pr.reviewedHeadSha === currentHead;
+  }
+  return !!(pr?.lastReviewedAt && (!pr?.lastPushedAt || pr.lastPushedAt <= pr.lastReviewedAt));
+}
+
+// Same SHA-freshness signal applied to the WAITING → re-review gate. A fix
+// is "reviewed-stale" when the tracked `reviewedHeadSha` no longer matches
+// the live head — checked in addition to (not instead of) the existing
+// `fixedAt` vs `lastReviewedAt` timestamp comparison, so a mid-review push
+// during a re-review dispatch is caught the same way as the first-review
+// race above.
+function isPrFixedAfterReview(pr) {
+  const timestampSaysFixed = !!(pr?.minionsReview?.fixedAt &&
+    (!pr?.lastReviewedAt || pr.minionsReview.fixedAt > pr.lastReviewedAt));
+  if (timestampSaysFixed) return true;
+  if (!pr?.reviewedHeadSha) return false;
+  const currentHead = getPrCauseHead(pr);
+  return !!currentHead && pr.reviewedHeadSha !== currentHead;
+}
+
 function getPrAutomationCauseKey(kind, pr) {
   if (kind === 'review-feedback') {
     const reviewRef = pr?.minionsReview?.dispatchId
@@ -7648,7 +7684,7 @@ async function discoverFromPrs(config, project) {
     // PRs needing review: evalLoop gates the entire review+fix cycle; pollEnabled ensures reviewStatus is fresh
     const reviewEnabled = evalLoopEnabled && pollEnabled && autoReviewPrs;
     const reReviewEnabled = evalLoopEnabled && pollEnabled && autoReReviewPrs;
-    const alreadyReviewed = pr.lastReviewedAt && (!pr.lastPushedAt || pr.lastPushedAt <= pr.lastReviewedAt);
+    const alreadyReviewed = isPrReviewCurrent(pr);
     const needsReview = reviewEnabled && reviewStatus === REVIEW_STATUS.PENDING && !alreadyReviewed;
     if (needsReview) {
       const key = getPrReviewCooldownKey('review', project, pr, prDisplayId);
@@ -7694,7 +7730,7 @@ async function discoverFromPrs(config, project) {
           pr_author: pr.agent || '', pr_url: pr.url || '',
         }, `Review ${pr.id}: ${pr.title}`, {
           dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta,
-          deferReviewerResolution: true,
+          deferReviewerResolution: true, reviewHeadSha: getPrCauseHead(pr),
         });
         if (deferred) {
           deferred._pendingReason = 'no_non_author_reviewer';
@@ -7707,7 +7743,7 @@ async function discoverFromPrs(config, project) {
       const item = buildPrDispatch(agentId, config, project, pr, 'review', {
         pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: prBranch,
         pr_author: pr.agent || '', pr_url: pr.url || '',
-      }, `Review ${pr.id}: ${pr.title}`, { dispatchKey: key, cooldownKey: key, source: 'pr', pr, branch: prBranch, project: projMeta });
+      }, `Review ${pr.id}: ${pr.title}`, { dispatchKey: key, cooldownKey: key, source: 'pr', pr, branch: prBranch, project: projMeta, reviewHeadSha: getPrCauseHead(pr) });
       if (item) { newWork.push(item); fixDispatched = true; }
     }
 
@@ -7861,8 +7897,7 @@ async function discoverFromPrs(config, project) {
 
     // Re-review after fix: trigger when a fix was pushed after the last minions review,
     // or when no minions review has completed yet (e.g. human-feedback-only fix path).
-    const fixedAfterReview = !!(pr.minionsReview?.fixedAt &&
-      (!pr.lastReviewedAt || pr.minionsReview.fixedAt > pr.lastReviewedAt));
+    const fixedAfterReview = isPrFixedAfterReview(pr);
     const needsReReview = reReviewEnabled && reviewStatus === REVIEW_STATUS.WAITING &&
       fixedAfterReview && !fixDispatched;
     if (needsReReview) {
@@ -7909,7 +7944,7 @@ async function discoverFromPrs(config, project) {
           pr_author: pr.agent || '', pr_url: pr.url || '',
         }, `Review ${pr.id}: ${pr.title}`, {
           dispatchKey: key, cooldownKey: key, source: 'pr', pr, branch: prBranch, project: projMeta,
-          deferReviewerResolution: true,
+          deferReviewerResolution: true, reviewHeadSha: getPrCauseHead(pr),
         });
         if (deferred) {
           deferred._pendingReason = 'no_non_author_reviewer';
@@ -7922,7 +7957,7 @@ async function discoverFromPrs(config, project) {
       const item = buildPrDispatch(agentId, config, project, pr, 'review', {
         pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: prBranch,
         pr_author: pr.agent || '', pr_url: pr.url || '',
-      }, `Review ${pr.id}: ${pr.title}`, { dispatchKey: key, cooldownKey: key, source: 'pr', pr, branch: prBranch, project: projMeta });
+      }, `Review ${pr.id}: ${pr.title}`, { dispatchKey: key, cooldownKey: key, source: 'pr', pr, branch: prBranch, project: projMeta, reviewHeadSha: getPrCauseHead(pr) });
       if (item) { newWork.push(item); }
     }
 
@@ -11716,6 +11751,7 @@ module.exports = {
   _isOutputTruncated, AGENT_OUTPUT_CAP_BYTES, // P-8e4c2a17: exported for testing (OUTPUT_TRUNCATED detection)
   promoteCheckpointSteeringForClose, // exported for testing
   normalizePrBranch, resolvePrBranch, prCausePart, getPrCauseHead, getPrCauseBase, getPrAutomationCauseKey, getPrAutomationDispatchKey, // exported for testing
+  isPrReviewCurrent, isPrFixedAfterReview, // exported for testing (W-mrej8p740006b0bf — SHA-based review freshness)
   ensurePrBranchForDispatch, isWithinLinkGraceWindow, PR_LINK_GRACE_WINDOW_MS, // exported for testing (W-mphm0kt0000cebc3)
 
   // Playbooks

package/package.json

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