@yemi33/minions 0.1.2292 → 0.1.2294

package/engine/work-items-store.js

@@ -273,6 +273,18 @@ function _fileContentHash(filePath) {
 
 function _hydrateScopeFromJson(db, scope) {
   const jsonItems = _readJsonArrayFallback(scope);
+  // Preserve the SQL-only prd_item_id FK across the delete+reinsert. It is owned
+  // by the PRD dual-write (prd-store.js#_upsertPrd), NOT represented in the JSON
+  // mirror, so a naive rebuild-from-JSON silently zeroes it for the whole scope —
+  // regressing the WI↔PRD link every time the JSON diverges (the count would
+  // oscillate as the PRD mirror re-stamps and the next hydrate wipes it again).
+  // Snapshot before the DELETE, restore onto the rows that survive the rebuild.
+  const fkById = new Map();
+  try {
+    for (const r of db.prepare('SELECT id, prd_item_id FROM work_items WHERE scope = ? AND prd_item_id IS NOT NULL').all(scope)) {
+      fkById.set(r.id, r.prd_item_id);
+    }
+  } catch { /* column absent on a pre-v15 schema — nothing to preserve */ }
   // DELETE before re-insert: callers that wrote a smaller JSON file
   // (test cleanup() removing items) must end up with a smaller SQL state.
   db.prepare('DELETE FROM work_items WHERE scope = ?').run(scope);
@@ -298,6 +310,14 @@ function _hydrateScopeFromJson(db, scope) {
       now,
     );
   }
+  // Restore the FK for rows that still exist after the rebuild (a WI dropped
+  // from the JSON is gone, and its link goes with it — correct).
+  if (fkById.size) {
+    const restore = db.prepare('UPDATE work_items SET prd_item_id = ? WHERE scope = ? AND id = ?');
+    for (const [id, fk] of fkById) {
+      try { restore.run(fk, scope, id); } catch { /* best effort */ }
+    }
+  }
 }
 
 function applyWorkItemsMutation(scope, mutator) {
@@ -375,4 +395,5 @@ module.exports = {
   dropScope,
   _filePathForScope,
   _mirrorJsonFromSql,
+  _hydrateScopeFromJson, // exported for testing (prd_item_id-preservation)
 };

package/engine.js

@@ -168,7 +168,7 @@ const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, reconci
   syncPrsFromOutput, updatePrAfterReview, updatePrAfterFix, checkForLearnings, extractSkillsFromOutput,
   updateAgentHistory, updateMetrics, createReviewFeedbackForAuthor, parseAgentOutput, syncPrdFromPrs, persistVerifyPrsToPrd,
   isItemCompleted, classifyFailure: classifyFailureFallback, diagnoseEmptyOutput, processPendingRebases, resolveWorkItemPath,
-  mergeArtifactNotes, promoteCompletionArtifacts, pruneScopeMismatchDuplicatePrs } = require('./engine/lifecycle');
+  mergeArtifactNotes, promoteCompletionArtifacts, pruneScopeMismatchDuplicatePrs, collapseAllDuplicatePrRecords } = require('./engine/lifecycle');
 
 // ─── Diagnostics: memory + event-loop + GC sampler (P-a1b2c3d4 / P-b2c3d4e5) ─
 
@@ -196,9 +196,15 @@ function cleanupTempAgent(agentId) {
   try {
     const agentDir = path.join(AGENTS_DIR, agentId);
     // Keep output archive but remove temp agent directory (live-output.log etc.)
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    // Use _retryFsOp so Windows EBUSY/EPERM (AV / file indexer lock) is retried.
+    shared._retryFsOp(
+      () => fs.rmSync(agentDir, { recursive: true, force: true }),
+      `cleanupTempAgent(${agentId})`
+    );
     log('info', `Temp agent ${agentId} cleaned up`);
-  } catch { /* cleanup */ }
+  } catch (err) {
+    log('warn', `cleanupTempAgent: fs.rmSync failed for ${agentId}: ${err && err.message}`);
+  }
 }
 
 // Per-tick cache of refs that failed to fetch — avoids repeating 30s ETIMEDOUT for same missing ref
@@ -974,7 +980,17 @@ async function runWorktreeAdd(rootDir, worktreePath, addArgs, gitOpts, worktreeC
           await shared.shellSafeGit(['worktree', 'remove', '--force', worktreePath], { ...gitOpts, cwd: rootDir, timeout: 30000 });
         } catch (rmErr) {
           log('warn', `runWorktreeAdd: worktree remove after partial checkout failed (${rmErr.message}) — falling back to fs-level cleanup`);
-          try { fs.rmSync(worktreePath, { recursive: true, force: true }); } catch {}
+          try {
+            // W-mqw3g5be000s934f: use _retryFsOp so transient Windows EBUSY/EPERM from
+            // antivirus or GVFS virtual-filesystem handles do not silently abandon cleanup.
+            shared._retryFsOp(
+              () => fs.rmSync(worktreePath, { recursive: true, force: true }),
+              `runWorktreeAdd: fs-level cleanup ${worktreePath}`,
+              { attempts: 3, baseMs: 100 },
+            );
+          } catch (fsErr) {
+            log('warn', `runWorktreeAdd: fs-level cleanup failed after retries (${fsErr.message}) — worktree directory may be leaked: ${worktreePath}`);
+          }
           try { await shared.shellSafeGit(['worktree', 'prune'], { ...gitOpts, cwd: rootDir, timeout: 15000 }); } catch {}
         }
         const incompleteErr = new Error(`GVFS incomplete checkout at ${worktreePath}: worktree add exited cleanly but no source files were checked out (only .git was written). Retriable.`);
@@ -2933,10 +2949,10 @@ async function spawnAgent(dispatchItem, config) {
                   try { await shared.shellSafeGit(['worktree', 'prune'], { ..._gitOpts, cwd: rootDir, timeout: 15000 }); } catch { /* optional */ }
                   removeStaleIndexLock(rootDir);
                   // Clean up partial worktree directory from the failed -b
-                  // attempt. Keep this a RAW fs.rmSync: this husk pre-dates
-                  // `git worktree add`, so git does not yet own it and
-                  // shared.removeWorktree's `git worktree remove --force` would
-                  // no-op on it (P-b3d9a162). Two guards before the delete:
+                  // attempt. This husk pre-dates `git worktree add`, so git
+                  // does not yet own it and shared.removeWorktree's
+                  // `git worktree remove --force` would no-op on it
+                  // (P-b3d9a162). Two guards before the delete:
                   //   1. isWorktreePathLive (fail-open): skip if another
                   //      dispatch raced onto this path — it returns true on a
                   //      SQL outage, so we leak the husk rather than nuke a
@@ -2945,6 +2961,7 @@ async function spawnAgent(dispatchItem, config) {
                   //      carries its own `.git` DIRECTORY (a mis-pointed
                   //      worktreePath onto a real repo) — a linked worktree's
                   //      `.git` is a FILE, so this never blocks a real husk.
+                  // W-mqw3i9vp000tcfaf: use shared._retryFsOp so Windows EBUSY/EPERM doesn't brick the branch.
                   try {
                     const _huskGit = path.join(worktreePath, '.git');
                     let _huskIsRealRepo = false;
@@ -2952,9 +2969,14 @@ async function spawnAgent(dispatchItem, config) {
                     if (fs.existsSync(worktreePath)
                         && !_huskIsRealRepo
                         && !shared.isWorktreePathLive(worktreePath, { excludeDispatchId: id })) {
-                      fs.rmSync(worktreePath, { recursive: true, force: true });
+                      shared._retryFsOp(
+                        () => fs.rmSync(worktreePath, { recursive: true, force: true }),
+                        `husk cleanup before -b retry ${branchName}`
+                      );
                     }
-                  } catch { /* optional */ }
+                  } catch (rmErr) {
+                    log('warn', `spawnAgent: husk cleanup failed before -b retry for ${branchName}: ${rmErr.message?.split('\n')[0]}`);
+                  }
                   try {
                     await runWorktreeAdd(rootDir, worktreePath, ['-b', branchName, _freshCreateBase], _worktreeGitOpts, 0);
                   } catch (e1b) {
@@ -5863,54 +5885,6 @@ function materializePlansAsWorkItems(config) {
       return mutator(current) || current;
     }, { defaultValue: fallback || {}, ...options });
   };
-  const declaredProjectPrdFilename = (fileName, projectName) => {
-    const match = String(fileName || '').match(/-(\d{4}-\d{2}-\d{2}(?:-\d+)?)\.json$/);
-    if (!match) return null;
-    return safePrdFilenameForProject(projectName, match[1]);
-  };
-  const migratePrdFilenameReferences = (oldFileName, newFileName) => {
-    if (!oldFileName || !newFileName || oldFileName === newFileName) return 0;
-    let migrated = 0;
-    const wiPaths = new Set([path.join(MINIONS_DIR, 'work-items.json')]);
-    for (const project of getProjects(config)) wiPaths.add(projectWorkItemsPath(project));
-    for (const wiPath of wiPaths) {
-      if (!fs.existsSync(wiPath)) continue;
-      mutateWorkItems(wiPath, (items) => {
-        for (const wi of items) {
-          if (!wi || typeof wi !== 'object') continue;
-          if (wi.sourcePlan === oldFileName) {
-            wi.sourcePlan = newFileName;
-            migrated++;
-          }
-          if (wi._artifacts?.sourcePlan === oldFileName) {
-            wi._artifacts.sourcePlan = newFileName;
-            migrated++;
-          }
-        }
-        return items;
-      });
-    }
-    if (fs.existsSync(DISPATCH_PATH)) {
-      mutateDispatch((dispatch) => {
-        for (const queue of ['pending', 'active', 'completed']) {
-          for (const entry of dispatch[queue] || []) {
-            const metaItem = entry?.meta?.item;
-            if (!metaItem || typeof metaItem !== 'object') continue;
-            if (metaItem.sourcePlan === oldFileName) {
-              metaItem.sourcePlan = newFileName;
-              migrated++;
-            }
-            if (metaItem._prdFilename === oldFileName) {
-              metaItem._prdFilename = newFileName;
-              migrated++;
-            }
-          }
-        }
-        return dispatch;
-      });
-    }
-    return migrated;
-  };
   const enforceDeclaredPlanProject = (fileName, currentPlan) => {
     if (!currentPlan?.source_plan) return { fileName, plan: currentPlan };
     let declaredProject = '';
@@ -5938,95 +5912,18 @@ function materializePlansAsWorkItems(config) {
       return planData;
     }, { skipWriteIfUnchanged: true });
 
-    let nextFileName = fileName;
-    const desiredFileName = declaredProjectPrdFilename(fileName, declaredProject);
-    if (desiredFileName && desiredFileName.toLowerCase() !== String(fileName).toLowerCase()) {
-      const fromPath = path.join(PRD_DIR, fileName);
-      const desiredPath = shared.sanitizePath(desiredFileName, PRD_DIR);
-      // W-mq8qdai6 — refuse to rename into a name owned by an archived PRD.
-      // `shared.uniquePath` only scans the live `prd/` directory; without this
-      // guard, an archived PRD with the canonical "<project>-<date>.json" name
-      // would silently collide with the rename target. The dashboard joins
-      // work items to PRDs by basename (sourcePlan === <prd filename>), so a
-      // live↔archive name collision bleeds the archived PRD's done items,
-      // verify task, and PRs into the live PRD's view (the bug-fix-plan vs
-      // minions-opg-2026-06-10 incident).
-      const archiveBasenames = new Set(
-        safeReadDir(path.join(PRD_DIR, 'archive'))
-          .filter(f => f.endsWith('.json'))
-          .map(f => f.toLowerCase())
-      );
-      if (archiveBasenames.has(desiredFileName.toLowerCase())) {
-        log('warn', `Plan project enforcement: skipping rename of ${fileName} to ${desiredFileName} — would collide with archived PRD`);
-      } else {
-        const toPath = shared.uniquePath(desiredPath);
-        const toBasename = path.basename(toPath);
-        if (archiveBasenames.has(toBasename.toLowerCase())) {
-          // uniquePath bumped past a live conflict (e.g. <name>-2.json) but
-          // the bumped name itself is owned by an archived PRD — same risk.
-          log('warn', `Plan project enforcement: skipping rename of ${fileName} to ${toBasename} — would collide with archived PRD`);
-        } else {
-          // W-mqfevwrm — Serialize the rename behind file locks on BOTH the
-          // source and destination paths so a concurrent `mutateJsonFileLocked`
-          // on either name cannot interleave (creating a divergent ghost PRD
-          // or losing data). Move the `.backup` sidecar along with the `.json`
-          // so the canonical name retains its restore-from-backup safety net
-          // — without this, deleting the renamed `.json` (concurrent sweep,
-          // plan-completion purge, etc.) leaves no `.backup` under the new
-          // name and the PRD is permanently lost (live incident 2026-06-15:
-          // `minions-opg-2026-06-10.json` gone, only the OLD-name `.backup`
-          // survived, all 9 WIs orphaned). The OLD-name `.backup` is removed
-          // so it cannot resurrect a ghost PRD on a future read of the OLD
-          // path (W-mouptdh1000h9f39-style landmine).
-          try {
-            withFileLock(`${fromPath}.lock`, () => {
-              withFileLock(`${toPath}.lock`, () => {
-                // Re-verify under both locks — another tick may have raced
-                // ahead and either deleted the source or claimed the dest.
-                if (!fs.existsSync(fromPath)) {
-                  log('warn', `Plan project enforcement: source ${fileName} disappeared before rename (raced)`);
-                  return;
-                }
-                if (fs.existsSync(toPath)) {
-                  log('warn', `Plan project enforcement: destination ${toBasename} appeared before rename (raced) — skipping`);
-                  return;
-                }
-                fs.renameSync(fromPath, toPath);
-                // Move the `.backup` sidecar along with the primary `.json`
-                // so safeJson's restore-from-backup path stays viable under
-                // the new canonical name. Both ops are best-effort: missing
-                // `.backup` is normal (nothing to move) and an unlink failure
-                // on the OLD-name `.backup` is logged but non-fatal.
-                const fromBackup = `${fromPath}.backup`;
-                const toBackup = `${toPath}.backup`;
-                if (fs.existsSync(fromBackup)) {
-                  try {
-                    fs.renameSync(fromBackup, toBackup);
-                  } catch (be) {
-                    // Fall back to copy + unlink if rename across the same dir
-                    // surfaces a Windows EPERM (AV/Search Indexer hold).
-                    try {
-                      fs.copyFileSync(fromBackup, toBackup);
-                      try { fs.unlinkSync(fromBackup); } catch { /* best-effort */ }
-                    } catch (ce) {
-                      log('warn', `Plan project enforcement: could not move .backup sidecar ${fileName}.backup → ${toBasename}.backup: ${be.message} / ${ce.message}`);
-                    }
-                  }
-                }
-                nextFileName = toBasename;
-                const migrated = migratePrdFilenameReferences(fileName, nextFileName);
-                if (migrated > 0) log('info', `Plan project enforcement: migrated ${migrated} PRD reference(s) from ${fileName} to ${nextFileName}`);
-                changed = true;
-              });
-            });
-          } catch (e) {
-            log('warn', `Plan project enforcement: could not rename ${fileName} to ${toBasename}: ${e.message}`);
-          }
-        }
-      }
-    }
-    if (changed) log('info', `Plan project enforcement: preserved declared project "${declaredProject}" for ${nextFileName}`);
-    return { fileName: nextFileName, plan: normalizedPlan };
+    // Phase 10 step 4.3 — the PRD filename is NO LONGER renamed to the canonical
+    // "<project>-<date>.json". That rename existed only to keep the basename
+    // identity (sourcePlan === <prd filename>) and the live↔archive collision
+    // guard (footgun #7) working. With the surrogate-key model — archive is an
+    // in-place flag (no move) and the WI↔PRD-item join is the stable SQL FK
+    // (work_items.prd_item_id), not the basename — the rename is dead weight and
+    // its own machinery (the `.backup` sidecar move, migratePrdFilenameReferences,
+    // the rename-race window that prd-rename-race.test.js guarded) is retired.
+    // The SEMANTIC enforcement above (declared project on the PRD + its features)
+    // still runs; only the file-move is gone.
+    if (changed) log('info', `Plan project enforcement: preserved declared project "${declaredProject}" for ${fileName}`);
+    return { fileName, plan: normalizedPlan };
   };
 
   // Enforce: PRDs must be .json — auto-rename .md files that contain valid PRD JSON
@@ -6420,6 +6317,19 @@ function materializePlansAsWorkItems(config) {
         log('info', `Re-opened work item ${itemId} in ${rProjName} (cross-project, PRD item set to ${rItem.status})`);
       }
 
+      // Stamp workItemId onto each newly created PRD item immediately after WI creation (P-b3c2d4e5).
+      // Uses mutatePrdLocked so the write is protected by a file lock — not a bare safeWrite.
+      if (newlyCreatedIds.size > 0) {
+        try {
+          mutatePrdLocked(file, plan, (current) => {
+            for (const feature of (current.missing_features || [])) {
+              if (newlyCreatedIds.has(feature.id)) feature.workItemId = feature.id;
+            }
+            return current;
+          }, { skipWriteIfUnchanged: true });
+        } catch (e) { log('warn', `workItemId stamp failed for ${file}: ${e.message}`); }
+      }
+
       totalCreated += created;
     }
 
@@ -8314,6 +8224,45 @@ function normalizeAc(ac) {
  * @param {string} [options.workType] - Work type (used for ASK-specific vars)
  * @returns {{ needsReview: boolean, checkpointCount: number|null }} checkpoint side-effect info
  */
+/**
+ * SHERLOC (P-mqyp0008v022w3x4): detect prior completed explore WI that
+ * references this fix WI via its `references` array. Returns the explore
+ * WI's `resultSummary` string, or '' when none found.
+ *
+ * Lookup: scan all work items for type=explore, status=done, non-empty
+ * resultSummary, and a reference whose URL includes the fix WI's ID.
+ * The explore WI is expected to have been dispatched as a pre-localization
+ * step and to carry a back-reference to the fix WI it was researching.
+ *
+ * @param {object} item  - the fix work item being dispatched
+ * @param {object} config - engine config (passed to getWorkItems)
+ * @returns {string}
+ */
+function resolvePriorExploreContext(item, config) {
+  if (!item || !item.id) return '';
+  try {
+    const allItems = queries.getWorkItems(config, { enrich: false });
+    const candidates = allItems.filter(wi =>
+      wi.type === WORK_TYPE.EXPLORE &&
+      DONE_STATUSES.has(wi.status) &&
+      wi.resultSummary &&
+      Array.isArray(wi.references) &&
+      wi.references.some(r => r && typeof r.url === 'string' && r.url.includes(item.id))
+    );
+    if (candidates.length === 0) return '';
+    // Prefer most recently completed; fall back to most recently created.
+    candidates.sort((a, b) => {
+      const ta = a.completedAt || a.created || '';
+      const tb = b.completedAt || b.created || '';
+      return tb.localeCompare(ta);
+    });
+    return candidates[0].resultSummary || '';
+  } catch (e) {
+    log('warn', `resolvePriorExploreContext for ${item.id}: ${e.message}`);
+    return '';
+  }
+}
+
 function buildWorkItemDispatchVars(item, vars, config, options = {}) {
   const { worktreePath, includeNotes = true, workType } = options;
 
@@ -8370,6 +8319,13 @@ function buildWorkItemDispatchVars(item, vars, config, options = {}) {
     vars.notes_content = 'See the **Team Notes** section above for the latest shared team context.';
   }
 
+  // SHERLOC (P-mqyp0008v022w3x4): inject prior explore context for fix dispatches.
+  // When a completed explore WI has a reference to this fix WI, surface its
+  // resultSummary so the fix agent starts with pre-localized fault context.
+  if (workType === WORK_TYPE.FIX) {
+    vars.prior_explore_context = resolvePriorExploreContext(item, config);
+  }
+
   // Resolve implicit context references (e.g., "ripley's plan", "the latest plan")
   const resolvedCtx = resolveTaskContext(item, config);
   if (resolvedCtx.additionalContext) {
@@ -9947,6 +9903,15 @@ async function tickInner() {
       log('warn', `[pull-requests] scope-mismatch sweep error: ${err?.message || err}`);
     }
 
+    // P-e9f0a2b4 — Collapse prNumber duplicates (different canonical IDs, same
+    // prNumber) that accumulated before upsert-time dedup was added. One mutation
+    // per affected scope per reconcile tick; normally a no-op after first run.
+    try {
+      collapseAllDuplicatePrRecords(config);
+    } catch (err) {
+      log('warn', `[pull-requests] collapse-duplicates sweep error: ${err?.message || err}`);
+    }
+
     // P-6b3a9f78 — Shared-branch PR reconciler (recovery sweep). Backfills the
     // engine PR store for shared-branch plans whose aggregate remote PR exists
     // but is untracked / under-linked, so the dashboard renders the single
@@ -10403,15 +10368,12 @@ async function tickInner() {
       } else {
         // P-a3f9b205: surface the per-project live-mode gate. Order matters:
         // max_concurrency / agent_busy / branch_locked are all more specific
-        // and win when both apply. Also check the pending item's own resolved
-        // checkout mode so worktree-mode items on hybrid projects are not
-        // falsely annotated live_checkout_busy (mirrors seeding guard above).
+        // and win when both apply.
         const itemProjName = item.project || item.meta?.project?.name || null;
         if (
           itemProjName
           && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
           && postLiveProjectsInUse.has(itemProjName)
-          && shared.resolveCheckoutMode(shared.findProjectByName(shared.getProjects(config), itemProjName), item.type) === 'live'
         ) {
           reason = 'live_checkout_busy';
         }
@@ -10607,6 +10569,8 @@ module.exports = {
 
   // Shared helpers (used by lifecycle.js and tests)
   reconcileItemsWithPrs, detectDependencyCycles,
+  safePrdProjectSlug, safePrdFilenameForProject, // exported for testing (W-mqyn7joo0004079f)
+  isSoftFixDispatch, // exported for testing (W-mqyn7joo0004079f)
   areDependenciesMet, // exported for testing (P-bf04-decompose-zero-children)
   parseConflictFiles, pruneAncestorDeps, preflightMergeSimulation, // exported for testing
   resolveDependencyBranches, buildCrossRepoDepsSection, // exported for testing (P-faea3206)
@@ -10627,6 +10591,7 @@ module.exports = {
 
   // Playbooks
   renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS, buildWorkItemDispatchVars,
+  resolvePriorExploreContext, // exported for testing (P-mqyp0008v022w3x4 SHERLOC)
   renderProjectWorkItemPromptForAgent, // exported for testing
 
   // Timeout / Steering / Idle (re-exported from engine/timeout.js)

package/package.json

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

package/playbooks/fix.md

@@ -19,6 +19,15 @@ When `{{pr_id}}`/`{{pr_branch}}` identify an existing pull request, this is a fi
 
 {{checkpoint_context}}
 
+{{#prior_explore_context}}
+## Exploration Context
+
+A prior explore work item investigated this issue. Use this context as your starting point for fault localization:
+
+{{prior_explore_context}}
+
+{{/prior_explore_context}}
+
 ## Review Findings to Address
 
 {{review_note}}