@yemi33/minions 0.1.2109 → 0.1.2110

package/docs/onboarding.md

@@ -2,7 +2,7 @@
 
 A fast, hands-on walkthrough for new contributors. Follow the eight steps below in order. Each step is independent enough that you can stop, take a break, and resume without losing state.
 
-> **Prerequisites:** Node.js 18+, Git, and a working Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) authenticated against your Anthropic API key or Claude Max subscription. See the top-level [README.md](../README.md#prerequisites) for the full list.
+> **Prerequisites:** Node.js 22.5+ (required by `package.json#engines` for the `node:sqlite` runtime backing the state DB), Git, and a working Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) authenticated against your Anthropic API key or Claude Max subscription. See the top-level [README.md](../README.md#prerequisites) for the full list.
 
 > **Screenshots:** This walkthrough is intentionally text-only on the first pass. If you want annotated dashboard screenshots, run the [`capture-demos`](../README.md#dashboard) skill after Step 5; it drives Playwright over the running dashboard and writes images you can drop alongside each section.
 
@@ -15,7 +15,7 @@ You only need to clone if you intend to modify Minions itself. End users normall
 ```bash
 git clone https://github.com/yemi33/minions.git ~/minions-dev
 cd ~/minions-dev
-npm install     # installs dev tooling (Playwright); engine itself has zero deps
+npm install     # installs dev tooling (Playwright) + the lone runtime dep (@azure-devops/mcp); engine is otherwise built on Node built-ins
 ```
 
 You should now have:

package/engine.js

@@ -877,7 +877,15 @@ async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
 //        can recover any unpushed work.
 //      - Otherwise (filesystem-only dirty) reset --hard + clean -fd, then
 //        re-verify.
-//   4. Return { clean, healed, reason, dirtyFiles, ahead, behind,
+//   4. W-mpykcky7: when the branch has no upstream AND the worktree is
+//      filesystem-clean AND HEAD is at the project main branch tip (caller
+//      passes opts.mainBranch), treat as safe-to-reuse — there are no
+//      local-only commits to lose. Without this, every reused worktree
+//      whose previous agent exited without making any commits gets
+//      quarantined in a false-positive loop. Any uncertainty (rev-list
+//      error, main missing, commitsAheadOfMain > 0) falls through to the
+//      conservative quarantine path.
+//   5. Return { clean, healed, reason, dirtyFiles, ahead, behind,
 //      quarantined, quarantinedPath, backupRef } so the caller can fail
 //      fast with a first-class DIRTY_WORKTREE / WORKTREE_DIRTY /
 //      WORKTREE_DIVERGENT reason and retry semantics.
@@ -955,7 +963,42 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     return result;
   }
 
-  // 4. Unpushed-commit check — refuse to reset when local work would be lost.
+  // 4. No-upstream-but-at-main safe-path (W-mpykcky7). When the worktree's
+  //    branch has no upstream (never pushed), the original #2996 gate
+  //    conservatively assumed unpushed work and quarantined. But if the
+  //    worktree is filesystem-clean AND HEAD is at the project main branch
+  //    tip (no local-only commits beyond main), there is nothing to lose —
+  //    reuse is safe. Common case: a previous agent exited without making
+  //    any commits, leaving HEAD == origin/<mainBranch>. Falls through to
+  //    the conservative quarantine path on any uncertainty (rev-list error,
+  //    main branch missing, commitsAheadOfMain > 0).
+  //    Invariants preserved from #2996:
+  //      - filesystemDirty still quarantines (we're past that gate only if
+  //        statusOut was empty).
+  //      - upstreamKnown && ahead > 0 still quarantines below (untouched).
+  //      - other-dispatch-active (above) still returns without quarantine.
+  if (!filesystemDirty && !upstreamKnown && opts.mainBranch) {
+    let commitsAheadOfMain = null;
+    try {
+      const r = await execAsync(
+        `git rev-list ${opts.mainBranch}..HEAD --count`,
+        { ...gitOpts, cwd: worktreePath, timeout: 10000 },
+      );
+      const parsed = parseInt(String(r || '').trim(), 10);
+      if (Number.isFinite(parsed)) commitsAheadOfMain = parsed;
+    } catch {
+      // rev-list error (main missing locally, fetch failed, etc.) — fall
+      // through to the conservative quarantine path. Don't loosen on
+      // uncertainty.
+    }
+    if (commitsAheadOfMain === 0) {
+      result.clean = true;
+      result.reason = 'no-upstream-but-at-main';
+      return result;
+    }
+  }
+
+  // 5. Unpushed-commit check — refuse to reset when local work would be lost.
   //    Use the ahead count we already computed (cheaper + correct vs.
   //    `git log @{u}..HEAD` which needs an upstream config and silently
   //    returns empty when missing).
@@ -985,7 +1028,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     return result;
   }
 
-  // 5. Safe to self-heal (filesystem-dirty only, no unpushed commits, no
+  // 6. Safe to self-heal (filesystem-dirty only, no unpushed commits, no
   //    other active dispatch): reset + clean.
   try {
     await execAsync('git reset --hard HEAD', { ...gitOpts, cwd: worktreePath, timeout: 30000 });
@@ -996,7 +1039,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     return result;
   }
 
-  // 6. Re-verify
+  // 7. Re-verify
   try {
     const r2 = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
     const after = (r2 || '').toString().trim();
@@ -1759,7 +1802,10 @@ async function spawnAgent(dispatchItem, config) {
     // implementation failures and cascading dependent items.
     if (worktreePath && fs.existsSync(worktreePath) && meta?.branchStrategy === 'shared-branch' && branchName) {
       _phaseT.cleanCheckStart = Date.now();
-      const cleanResult = await assertCleanSharedWorktree(rootDir, worktreePath, branchName, id, _gitOpts);
+      const cleanResult = await assertCleanSharedWorktree(
+        rootDir, worktreePath, branchName, id, _gitOpts,
+        { mainBranch: shared.resolveMainBranch(rootDir, project.mainBranch) },
+      );
       _phaseT.cleanCheckEnd = Date.now();
       if (!cleanResult.clean) {
         const previewFiles = (cleanResult.dirtyFiles || []).slice(0, 5).join(', ');
@@ -1817,7 +1863,7 @@ async function spawnAgent(dispatchItem, config) {
       _phaseT.dirtyReusedCheckStart = Date.now();
       const cleanResult = await assertCleanSharedWorktree(
         rootDir, worktreePath, branchName, id, _gitOpts,
-        { quarantineOnUnsafe: true },
+        { quarantineOnUnsafe: true, mainBranch: shared.resolveMainBranch(rootDir, project.mainBranch) },
       );
       _phaseT.dirtyReusedCheckEnd = Date.now();
       if (!cleanResult.clean) {

package/package.json

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