@yemi33/minions 0.1.1002 → 0.1.1004

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.1.1002 (2026-04-15)
+## 0.1.1004 (2026-04-15)
 
 ### Features
 - fix stopAfter=0 watch expiry — run forever for all conditions (#1117)
@@ -25,6 +25,7 @@
 - gate auto-fix conflict dispatch behind autoFixConflicts flag
 
 ### Fixes
+-  only gate reviews/fixes when no free agent slots remain
 -  extend auto-link fallback to ADO projects
 -  auto-link existing GitHub PR when agent completes without creating one
 -  preserve ordered lists across blank lines in markdown renderer
@@ -44,9 +45,9 @@
 -  move review verdict check before updateWorkItemStatus(DONE)
 -  address review feedback — move writeToInbox outside lock, add absolute condition auto-expire
 - fix watches feature gaps — human notifications, branch stub, status-change init, unique keys
--  skip isAlreadyDispatched in needsReReview to allow re-review within 1hr
 
 ### Other
+- refactor: migrate PR links to array format and consolidate shared helpers
 - docs: update CLAUDE.md with recent Minions architecture changes
 - chore: stop tracking runtime pipeline state
 - chore: strengthen prompts and routing

package/dashboard.js

@@ -2533,7 +2533,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
         const prLinks = shared.getPrLinks();
         const implContext = (plan.missing_features || []).map(f => {
           const wi = planWis.find(w => w.id === f.id);
-          const pr = allPrs.find(p => prLinks[p.id] === f.id || (p.prdItems || []).includes(f.id));
+          const pr = allPrs.find(p => (prLinks[p.id] || []).includes(f.id) || (p.prdItems || []).includes(f.id));
           return `- **${f.id}**: ${f.name} [status: ${wi?.status || f.status}]${pr ? ` (PR: ${pr.id}, branch: \`${pr.branch}\`)` : ''}`;
         }).join('\n');
 

package/engine/ado.js

@@ -17,6 +17,11 @@ function engine() {
 }
 
 const stripRefsHeads = s => (s || '').replace('refs/heads/', '');
+const getAdoPrUrl = (project, prNumber) => {
+  if (project.prUrlBase) return `${project.prUrlBase}${prNumber}`;
+  const repoPath = encodeURIComponent(project.repoName || project.repositoryId || '');
+  return `https://dev.azure.com/${project.adoOrg}/${project.adoProject}/_git/${repoPath}/pullrequest/${prNumber}`;
+};
 
 // ── Build/Review Status Helpers ───────────────────────────────────────────────
 
@@ -748,16 +753,7 @@ async function reconcilePrs(config) {
     }
 
     // Backfill prdItems from pr-links for any PR with empty array
-    const prLinks = shared.getPrLinks();
-    let backfilled = 0;
-    for (const pr of existingPrs) {
-      const linked = prLinks[pr.id];
-      if (linked && !(pr.prdItems || []).includes(linked)) {
-        pr.prdItems = Array.isArray(pr.prdItems) ? pr.prdItems : [];
-        pr.prdItems.push(linked);
-        backfilled++;
-      }
-    }
+    const backfilled = shared.backfillPrPrdItems(existingPrs, shared.getPrLinks());
 
     if (projectAdded > 0 || projectUpdated > 0 || backfilled > 0) {
       mutateJsonFileLocked(prPath, (currentPrs) => {
@@ -865,7 +861,7 @@ async function fetchSinglePrBuildStatus(project, prNumber) {
   }
 
   const votes = (prData.reviewers || []).map(r => r.vote);
-  const prUrl = `https://dev.azure.com/${project.adoOrg}/${project.adoProject}/_git/${project.repositoryId}/pullrequest/${prNumber}`;
+  const prUrl = getAdoPrUrl(project, prNumber);
 
   return {
     prNumber,
@@ -900,6 +896,10 @@ const getAdoThrottleState = () => _adoThrottle.getState();
  */
 async function findOpenPrOnBranch(project, branch) {
   if (!project.adoOrg || !project.adoProject || !project.repositoryId || !branch) return null;
+  if (isAdoThrottled()) {
+    log('debug', `[ado] Skipping branch PR lookup for ${project.name || project.repoName || 'unknown project'}:${branch} — throttled`);
+    return null;
+  }
   const token = await getAdoToken();
   if (!token) return null;
   const orgBase = shared.getAdoOrgBase(project);
@@ -909,7 +909,7 @@ async function findOpenPrOnBranch(project, branch) {
   const pr = (data.value || [])[0];
   if (!pr) return null;
   const prNumber = pr.pullRequestId;
-  const prUrl = project.prUrlBase ? `${project.prUrlBase}${prNumber}` : `https://dev.azure.com/${project.adoOrg}/${project.adoProject}/_git/${project.repositoryId}/pullrequest/${prNumber}`;
+  const prUrl = getAdoPrUrl(project, prNumber);
   return { prNumber, url: prUrl };
 }
 
@@ -940,4 +940,3 @@ module.exports = {
   _resetAdoThrottle, // exported for testing
   _setAdoThrottleForTest, // exported for testing
 };
-

package/engine/github.js

@@ -5,7 +5,7 @@
  */
 
 const shared = require('./shared');
-const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, mutateJsonFileLocked, MINIONS_DIR, addPrLink, getPrLinks, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, createThrottleTracker } = shared;
+const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, mutateJsonFileLocked, MINIONS_DIR, addPrLink, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, createThrottleTracker } = shared;
 const { getPrs } = require('./queries');
 const path = require('path');
 
@@ -691,16 +691,7 @@ async function reconcilePrs(config) {
     }
 
     // Backfill prdItems from pr-links for any PR with empty array
-    const prLinks = getPrLinks();
-    let backfilled = 0;
-    for (const pr of currentPrs) {
-      const linked = prLinks[pr.id];
-      if (linked && !(pr.prdItems || []).includes(linked)) {
-        pr.prdItems = Array.isArray(pr.prdItems) ? pr.prdItems : [];
-        pr.prdItems.push(linked);
-        backfilled++;
-      }
-    }
+    const backfilled = backfillPrPrdItems(currentPrs, getPrLinks());
 
     if (projectAdded > 0 || backfilled > 0) {
       mutateJsonFileLocked(prPath, (lockedPrs) => {
@@ -761,4 +752,3 @@ module.exports = {
   _ghPollBackoff,
   _ghThrottle, // exported for testing
 };
-

package/engine/lifecycle.js

@@ -111,8 +111,8 @@ function checkPlanCompletion(meta, config) {
       const prs = safeJson(prPath) || [];
       const prLinks = getPrLinks();
       for (const pr of prs) {
-        const linkedItemId = prLinks[pr.id];
-        if (linkedItemId && doneItems.find(w => w.id === linkedItemId)) {
+        const linkedItemIds = prLinks[pr.id] || [];
+        if (linkedItemIds.some(itemId => doneItems.find(w => w.id === itemId))) {
           prsCreated.push(pr);
         }
       }
@@ -199,8 +199,8 @@ function checkPlanCompletion(meta, config) {
       const prLinks = getPrLinks();
       const prs = (safeJson(shared.projectPrPath(p)) || [])
         .filter(pr => {
-          const linkedId = prLinks[pr.id];
-          return pr.status === PR_STATUS.ACTIVE && linkedId && doneItems.find(w => w.id === linkedId);
+          const linkedIds = prLinks[pr.id] || [];
+          return pr.status === PR_STATUS.ACTIVE && linkedIds.some(itemId => doneItems.find(w => w.id === itemId));
         });
       if (prs.length > 0) {
         projectPrs[p.name] = { project: p, prs, mainBranch: shared.resolveMainBranch(p.localPath, p.mainBranch) };
@@ -413,8 +413,8 @@ function cleanupPlanWorktrees(planFile, plan, projects, config) {
         const prs = safeJson(shared.projectPrPath(p)) || [];
         const prLinks = getPrLinks();
         for (const pr of prs) {
-          const linkedId = prLinks[pr.id];
-          if (linkedId && planItems.find(w => w.id === linkedId) && pr.branch) {
+          const linkedIds = prLinks[pr.id] || [];
+          if (linkedIds.some(itemId => planItems.find(w => w.id === itemId)) && pr.branch) {
             branchSlugs.add(shared.sanitizeBranch(pr.branch).toLowerCase());
           }
         }
@@ -1109,13 +1109,14 @@ async function handlePostMerge(pr, project, config, newStatus) {
   if (newStatus !== PR_STATUS.MERGED) return;
 
   // Resolve linked work item from pr-links or PR branch name
-  let mergedItemId = getPrLinks()[pr.id];
-  if (!mergedItemId && pr.branch) {
+  const mergedItemIds = [...(getPrLinks()[pr.id] || [])];
+  if (mergedItemIds.length === 0 && pr.branch) {
     const branchMatch = pr.branch.match(/(P-[a-z0-9]{6,})/i) || pr.branch.match(/(W-[a-z0-9]{6,})/i) || pr.branch.match(/(PL-[a-z0-9]{6,})/i);
-    if (branchMatch) mergedItemId = branchMatch[1];
+    if (branchMatch) mergedItemIds.push(branchMatch[1]);
   }
 
-  if (mergedItemId) {
+  if (mergedItemIds.length > 0) {
+    const mergedItemSet = new Set(mergedItemIds);
     // Mark PRD feature as implemented
     const prdDir = path.join(MINIONS_DIR, 'prd');
     try {
@@ -1124,49 +1125,62 @@ async function handlePostMerge(pr, project, config, newStatus) {
       for (const pf of planFiles) {
         const plan = safeJson(path.join(prdDir, pf));
         if (!plan?.missing_features) continue;
-        const feature = plan.missing_features.find(f => f.id === mergedItemId);
-        if (feature && feature.status !== WI_STATUS.DONE) {
-          feature.status = WI_STATUS.DONE;
+        let changed = false;
+        for (const feature of plan.missing_features) {
+          if (mergedItemSet.has(feature.id) && feature.status !== WI_STATUS.DONE) {
+            feature.status = WI_STATUS.DONE;
+            changed = true;
+            updated++;
+          }
+        }
+        if (changed) {
           shared.safeWrite(path.join(prdDir, pf), plan);
-          updated++;
         }
       }
-      if (updated > 0) log('info', `Post-merge: marked ${mergedItemId} as done for ${pr.id}`);
+      if (updated > 0) log('info', `Post-merge: marked ${mergedItemIds.join(', ')} as done for ${pr.id}`);
     } catch (err) { log('warn', `Post-merge PRD update: ${err.message}`); }
 
     // Mark work item as done
     const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
     for (const p of shared.getProjects(config)) wiPaths.push(shared.projectWorkItemsPath(p));
+    const remainingMergedIds = new Set(mergedItemIds);
     for (const wiPath of wiPaths) {
       try {
-        let found = false;
         mutateWorkItems(wiPath, items => {
-          const item = items.find(i => i.id === mergedItemId);
-          if (item && item.status !== WI_STATUS.DONE) {
-            log('info', `Post-merge: marking work item ${mergedItemId} as done (was ${item.status}) for ${pr.id}`);
-            item.status = WI_STATUS.DONE;
-            item.completedAt = ts();
-            item._mergedVia = pr.id;
-            found = true;
+          for (const item of items) {
+            if (!remainingMergedIds.has(item.id)) continue;
+            if (item.status !== WI_STATUS.DONE) {
+              log('info', `Post-merge: marking work item ${item.id} as done (was ${item.status}) for ${pr.id}`);
+              item.status = WI_STATUS.DONE;
+              item.completedAt = ts();
+              item._mergedVia = pr.id;
+            }
+            remainingMergedIds.delete(item.id);
           }
         });
-        if (found) break;
+        if (remainingMergedIds.size === 0) break;
       } catch (err) { log('warn', `Post-merge work item update: ${err.message}`); }
     }
 
     // Rebase dependent PRs onto main now that this dependency is merged
     try {
-      const dependentPrs = findDependentActivePrs(mergedItemId, config);
-      for (const { pr: depPr, project: depProject } of dependentPrs) {
-        if (isBranchActive(depPr.branch)) {
-          queuePendingRebase(depPr, depProject, mergedItemId);
-          log('info', `Post-merge rebase deferred: ${depPr.branch} locked by active agent`);
-          continue;
-        }
-        const result = await rebaseBranchOntoMain(depPr, depProject, config);
-        if (!result.success) {
-          shared.writeToInbox('engine', `rebase-fail-${depPr.id}`,
-            `# Rebase Failed: ${depPr.id}\n\nBranch \`${depPr.branch}\` could not be rebased onto main after dependency ${mergedItemId} merged.\n\nError: ${result.error}\n\nManual rebase may be needed.`);
+      const rebasedPrs = new Set();
+      for (const mergedItemId of mergedItemIds) {
+        const dependentPrs = findDependentActivePrs(mergedItemId, config);
+        for (const { pr: depPr, project: depProject } of dependentPrs) {
+          const rebaseKey = `${depProject.name}:${depPr.id}`;
+          if (rebasedPrs.has(rebaseKey)) continue;
+          rebasedPrs.add(rebaseKey);
+          if (isBranchActive(depPr.branch)) {
+            queuePendingRebase(depPr, depProject, mergedItemId);
+            log('info', `Post-merge rebase deferred: ${depPr.branch} locked by active agent`);
+            continue;
+          }
+          const result = await rebaseBranchOntoMain(depPr, depProject, config);
+          if (!result.success) {
+            shared.writeToInbox('engine', `rebase-fail-${depPr.id}`,
+              `# Rebase Failed: ${depPr.id}\n\nBranch \`${depPr.branch}\` could not be rebased onto main after dependency ${mergedItemId} merged.\n\nError: ${result.error}\n\nManual rebase may be needed.`);
+          }
         }
       }
     } catch (err) { log('warn', `Post-merge rebase phase error: ${err.message}`); }
@@ -1780,7 +1794,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // Detect implement tasks that completed without creating a PR
   if (effectiveSuccess && (type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX) && prsCreatedCount === 0 && meta?.item?.id && !meta?.item?.skipPr && meta?.project?.localPath) {
     // Check if a PR already exists linked to this work item (from a previous attempt)
-    let existingPrFound = Object.values(getPrLinks()).includes(meta.item.id);
+    let existingPrFound = Object.values(getPrLinks()).some(linkedIds => (linkedIds || []).includes(meta.item.id));
     // Also check pull-requests.json for PRs with matching prdItems or branch
     if (!existingPrFound) {
       const allProjects = shared.getProjects(config);
@@ -1800,22 +1814,49 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       if (projectObj) {
         try {
           let found = null;
-          if (projectObj.repoHost === 'github') {
+          const host = projectObj.repoHost || 'ado';
+          if (host === 'github') {
             const ghSlug = projectObj.prUrlBase?.match(/github\.com\/([^/]+\/[^/]+)\/pull/)?.[1];
             if (ghSlug) {
-              const raw = await execAsync(`gh pr list --head "${meta.branch}" --repo ${ghSlug} --json number,url,state --limit 1`, { timeout: 15000, windowsHide: true });
-              const hits = JSON.parse(raw || '[]');
-              if (hits.length > 0 && hits[0].state === 'OPEN') found = { prNumber: hits[0].number, url: hits[0].url };
+              // Retry up to 3 times — newly created PRs can take a few seconds to appear in the API
+              for (let attempt = 0; attempt < 3 && !found; attempt++) {
+                if (attempt > 0) await new Promise(r => setTimeout(r, 3000));
+                let raw = '';
+                try {
+                  raw = await execAsync(`gh pr list --head "${meta.branch}" --repo ${ghSlug} --json number,url,state --limit 1`, { timeout: 15000, windowsHide: true });
+                  const parsed = JSON.parse(raw || '[]');
+                  const hits = Array.isArray(parsed) ? parsed : [];
+                  if (hits.length > 0 && hits[0].state === 'OPEN') {
+                    found = { prNumber: hits[0].number, url: hits[0].url };
+                  } else if (attempt === 2) {
+                    log('warn', `Auto-link fallback: no open PR found on branch ${meta.branch} after 3 attempts (raw: ${(raw || '').slice(0, 200)})`);
+                  }
+                } catch (err) {
+                  if (attempt === 2) {
+                    const rawSuffix = raw ? ` (raw: ${raw.slice(0, 200)})` : '';
+                    log('warn', `Auto-link fallback: gh pr list lookup failed on branch ${meta.branch} after 3 attempts: ${err.message}${rawSuffix}`);
+                  }
+                }
+              }
             }
-          } else {
+          } else if (host === 'ado') {
             found = await require('./ado').findOpenPrOnBranch(projectObj, meta.branch);
+          } else {
+            log('debug', `Skipping branch PR lookup for unsupported repo host "${host}" on ${projectObj.name}`);
           }
           if (found) {
             const fullId = `PR-${found.prNumber}`;
             const prPath = shared.projectPrPath(projectObj);
             mutateJsonFileLocked(prPath, prs => {
               if (!Array.isArray(prs)) prs = [];
-              if (prs.some(p => p.id === fullId)) return prs;
+              const existingPr = prs.find(p => p.id === fullId);
+              if (existingPr) {
+                if (meta.item?.id) {
+                  if (!Array.isArray(existingPr.prdItems)) existingPr.prdItems = [];
+                  if (!existingPr.prdItems.includes(meta.item.id)) existingPr.prdItems.push(meta.item.id);
+                }
+                return prs;
+              }
               prs.push({
                 id: fullId, prNumber: found.prNumber, title: meta.item?.title || '',
                 agent: agentId, branch: meta.branch, reviewStatus: 'pending',
@@ -1825,7 +1866,6 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
               });
               return prs;
             });
-            if (meta.item?.id) addPrLink(fullId, meta.item.id);
             log('info', `Auto-linked existing PR ${fullId} on branch ${meta.branch} for ${meta.item?.id}`);
             existingPrFound = true;
           }
@@ -2069,4 +2109,3 @@ module.exports = {
   processPendingRebases,
   findDependentActivePrs,
 };
-

package/engine/queries.js

@@ -949,13 +949,15 @@ function getPrdInfo(config) {
   for (const pr of allPrs) prById[pr.id] = pr;
 
   const prdToPr = {};
-  const prLinks = shared.getPrLinks(); // { "PR-xxxx": "P-xxxx" }
-  for (const [prId, itemId] of Object.entries(prLinks)) {
+  const prLinks = shared.getPrLinks(); // { "PR-xxxx": ["P-xxxx", "P-yyyy"] }
+  for (const [prId, itemIds] of Object.entries(prLinks)) {
     const pr = prById[prId];
     const project = projects.find(p => p.name === pr?._project) || projects[0] || null;
     const url = pr?.url || (project?.prUrlBase ? project.prUrlBase + prId.replace('PR-', '') : '');
-    if (!prdToPr[itemId]) prdToPr[itemId] = [];
-    prdToPr[itemId].push({ id: prId, url, title: pr?.title || '', status: pr?.status || 'active', _project: pr?._project || '' });
+    for (const itemId of (itemIds || [])) {
+      if (!prdToPr[itemId]) prdToPr[itemId] = [];
+      prdToPr[itemId].push({ id: prId, url, title: pr?.title || '', status: pr?.status || 'active', _project: pr?._project || '' });
+    }
   }
   // Fallback: work item _pr field for anything still missing
   for (const wi of Object.values(wiById)) {
@@ -1091,4 +1093,3 @@ module.exports = {
   // Work items & PRD
   getWorkItems, getPrdInfo,
 };
-

package/engine/shared.js

@@ -859,6 +859,17 @@ function parseSkillFrontmatter(content, filename) {
 // Stable single-writer file: maps PR IDs → PRD item IDs.
 // Never touched by polling loops — only written when a PR is first linked to a PRD item.
 
+function normalizePrLinkItems(value) {
+  const items = Array.isArray(value) ? value : [value];
+  return [...new Set(items.filter(Boolean))];
+}
+
+function mergePrLinkItems(links, prId, itemIds) {
+  if (!prId) return;
+  const merged = new Set([...(links[prId] || []), ...normalizePrLinkItems(itemIds)]);
+  if (merged.size > 0) links[prId] = [...merged];
+}
+
 function getPrLinks() {
   const links = {};
   // Primary source: derive from all projects/*/pull-requests.json prdItems
@@ -870,9 +881,7 @@ function getPrLinks() {
         const prs = JSON.parse(fs.readFileSync(path.join(projectsDir, d.name, 'pull-requests.json'), 'utf8'));
         for (const pr of prs) {
           if (!pr.id) continue;
-          for (const itemId of (pr.prdItems || [])) {
-            if (itemId) links[pr.id] = itemId;
-          }
+          mergePrLinkItems(links, pr.id, pr.prdItems || []);
         }
       } catch { /* missing or invalid */ }
     }
@@ -881,17 +890,35 @@ function getPrLinks() {
   try {
     const static_ = JSON.parse(fs.readFileSync(PR_LINKS_PATH, 'utf8'));
     for (const [k, v] of Object.entries(static_)) {
-      if (!links[k]) links[k] = v;
+      if (!links[k]) mergePrLinkItems(links, k, v);
     }
   } catch { /* missing */ }
   return links;
 }
 
+function backfillPrPrdItems(prs, prLinks) {
+  let backfilled = 0;
+  for (const pr of prs) {
+    const linkedItems = prLinks[pr.id] || [];
+    if (linkedItems.length > 0) {
+      pr.prdItems = Array.isArray(pr.prdItems) ? pr.prdItems : [];
+      for (const linked of linkedItems) {
+        if (!pr.prdItems.includes(linked)) {
+          pr.prdItems.push(linked);
+          backfilled++;
+        }
+      }
+    }
+  }
+  return backfilled;
+}
+
 function addPrLink(prId, itemId) {
   if (!prId || !itemId) return;
-  const links = getPrLinks();
-  if (links[prId] === itemId) return; // already correct, no write needed
-  links[prId] = itemId;
+  const links = safeJson(PR_LINKS_PATH) || {};
+  const current = normalizePrLinkItems(links[prId]);
+  if (current.includes(itemId)) return; // already correct, no write needed
+  links[prId] = [...current, itemId];
   safeWrite(PR_LINKS_PATH, links);
 }
 
@@ -1184,5 +1211,5 @@ module.exports = {
   formatTranscriptEntry,
   _logBuffer, // exported for testing
   createThrottleTracker,
+  backfillPrPrdItems,
 };
-

package/engine.js

@@ -24,7 +24,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./engine/shared');
-const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS: DEFAULTS,
+const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS,
   WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, DISPATCH_RESULT, AGENT_STATUS,
   FAILURE_CLASS } = shared;
 const queries = require('./engine/queries');
@@ -241,8 +241,8 @@ function _maxTurnsForType(type, engineConfig) {
   // Priority: per-type config override → global config override → built-in per-type default → global default
   const perType = engineConfig.maxTurnsByType || {};
   if (perType[type]) return perType[type];
-  const globalOverride = engineConfig.maxTurns && engineConfig.maxTurns !== DEFAULTS.maxTurns ? engineConfig.maxTurns : null;
-  return globalOverride || _MAX_TURNS_BY_TYPE[type] || DEFAULTS.maxTurns;
+  const globalOverride = engineConfig.maxTurns && engineConfig.maxTurns !== ENGINE_DEFAULTS.maxTurns ? engineConfig.maxTurns : null;
+  return globalOverride || _MAX_TURNS_BY_TYPE[type] || ENGINE_DEFAULTS.maxTurns;
 }
 
 // Resolve dependency plan item IDs to their PR branches
@@ -373,8 +373,8 @@ async function spawnAgent(dispatchItem, config) {
   let cwd = rootDir;
   let worktreePath = null;
   let branchName = meta?.branch ? sanitizeBranch(meta.branch) : null;
-  const worktreeCreateTimeout = Math.max(60000, Number(engineConfig.worktreeCreateTimeout) || DEFAULTS.worktreeCreateTimeout);
-  const worktreeCreateRetries = Math.max(0, Math.min(3, Number(engineConfig.worktreeCreateRetries) || DEFAULTS.worktreeCreateRetries));
+  const worktreeCreateTimeout = Math.max(60000, Number(engineConfig.worktreeCreateTimeout) || ENGINE_DEFAULTS.worktreeCreateTimeout);
+  const worktreeCreateRetries = Math.max(0, Math.min(3, Number(engineConfig.worktreeCreateRetries) || ENGINE_DEFAULTS.worktreeCreateRetries));
   const _gitOpts = { stdio: 'pipe', timeout: 30000, windowsHide: true, env: shared.gitEnv() };
   const _worktreeGitOpts = { ..._gitOpts, timeout: worktreeCreateTimeout };
 
@@ -1021,7 +1021,7 @@ async function spawnAgent(dispatchItem, config) {
       // Build resume args
       const resumeArgs = [
         '--output-format', claudeConfig?.outputFormat || 'stream-json',
-        '--max-turns', String(engineConfig?.maxTurns || DEFAULTS.maxTurns),
+        '--max-turns', String(engineConfig?.maxTurns || ENGINE_DEFAULTS.maxTurns),
         '--verbose',
         '--permission-mode', claudeConfig?.permissionMode || 'bypassPermissions',
         '--resume', steerSessionId,
@@ -1427,7 +1427,7 @@ function reconcileItemsWithPrs(items, allPrs, { onlyIds } = {}) {
 
     let exactPr = allPrs.find(pr => (pr.prdItems || []).includes(wi.id));
     if (!exactPr) {
-      const linkedPrId = Object.keys(prLinks).find(prId => prLinks[prId] === wi.id);
+      const linkedPrId = Object.keys(prLinks).find(prId => (prLinks[prId] || []).includes(wi.id));
       if (linkedPrId) exactPr = allPrs.find(pr => pr.id === linkedPrId) || { id: linkedPrId };
     }
     // Branch-based matching: PR branch contains the work item ID (e.g. work/P-k7m2v9a1)
@@ -1901,8 +1901,8 @@ async function discoverFromPrs(config, project) {
   // Resolve poll-enabled per project — stale reviewStatus is untrustworthy without poller
   const isAdoProject = project?.repoHost !== 'github';
   const pollEnabled = isAdoProject
-    ? (config.engine?.adoPollEnabled ?? DEFAULTS.adoPollEnabled)
-    : (config.engine?.ghPollEnabled ?? DEFAULTS.ghPollEnabled);
+    ? (config.engine?.adoPollEnabled ?? ENGINE_DEFAULTS.adoPollEnabled)
+    : (config.engine?.ghPollEnabled ?? ENGINE_DEFAULTS.ghPollEnabled);
   const evalLoopEnabled = config.engine?.evalLoop !== false;
 
   // Collect active PR dispatches to prevent simultaneous review+fix on same PR
@@ -1935,7 +1935,7 @@ async function discoverFromPrs(config, project) {
     const awaitingReReview = reviewStatus === 'waiting' && !!pr.minionsReview?.fixedAt;
 
     // Review→fix cycle cap — stop review/fix dispatch after N iterations, but allow build fixes and conflict fixes
-    const evalMax = config.engine?.evalMaxIterations ?? DEFAULTS.evalMaxIterations;
+    const evalMax = config.engine?.evalMaxIterations ?? ENGINE_DEFAULTS.evalMaxIterations;
     const evalCycles = pr._reviewFixCycles || 0;
     const evalEscalated = evalCycles >= evalMax;
     if (evalEscalated && !pr._evalEscalated) {
@@ -2099,12 +2099,12 @@ async function discoverFromPrs(config, project) {
     // Grace period: after a build fix push, wait for CI to run before re-dispatching
     // Skip if build hasn't transitioned since last fix (still showing the old failure)
     if (pr._buildFixPushedAt && pr.buildStatus === 'failing') {
-      const gracePeriodMs = config.engine?.buildFixGracePeriod ?? DEFAULTS.buildFixGracePeriod;
+      const gracePeriodMs = config.engine?.buildFixGracePeriod ?? ENGINE_DEFAULTS.buildFixGracePeriod;
       if (Date.now() - new Date(pr._buildFixPushedAt).getTime() < gracePeriodMs) continue;
     }
-    const autoFixBuilds = config.engine?.autoFixBuilds ?? DEFAULTS.autoFixBuilds;
+    const autoFixBuilds = config.engine?.autoFixBuilds ?? ENGINE_DEFAULTS.autoFixBuilds;
     if (autoFixBuilds && pr.status === PR_STATUS.ACTIVE && pr.buildStatus === 'failing') {
-      const maxBuildFix = config.engine?.maxBuildFixAttempts ?? DEFAULTS.maxBuildFixAttempts;
+      const maxBuildFix = config.engine?.maxBuildFixAttempts ?? ENGINE_DEFAULTS.maxBuildFixAttempts;
 
       // Check if max retry cap reached — escalate to human instead of dispatching another fix
       if ((pr.buildFixAttempts || 0) >= maxBuildFix) {
@@ -2182,7 +2182,7 @@ async function discoverFromPrs(config, project) {
     }
 
     // PRs with merge conflicts — dispatch fix to resolve (gated by autoFixConflicts)
-    const autoFixConflicts = config.engine?.autoFixConflicts ?? DEFAULTS.autoFixConflicts;
+    const autoFixConflicts = config.engine?.autoFixConflicts ?? ENGINE_DEFAULTS.autoFixConflicts;
     if (autoFixConflicts && pr.status === PR_STATUS.ACTIVE && pr._mergeConflict && !fixDispatched) {
       const key = `conflict-fix-${project?.name || 'default'}-${pr.id}`;
       // Suppress re-dispatch for 10 min after last attempt — ADO/GitHub recomputes
@@ -2808,7 +2808,7 @@ function discoverCentralWorkItems(config) {
           meta: {
             dispatchKey: fanKey, source: 'central-work-item-fanout', item, parentKey: key,
             branch: fanBranch,
-            deadline: item.timeout ? Date.now() + item.timeout : Date.now() + (config.engine?.fanOutTimeout || config.engine?.agentTimeout || DEFAULTS.agentTimeout)
+            deadline: item.timeout ? Date.now() + item.timeout : Date.now() + (config.engine?.fanOutTimeout || config.engine?.agentTimeout || ENGINE_DEFAULTS.agentTimeout)
           }
         });
       }
@@ -3081,18 +3081,24 @@ async function discoverWork(config) {
     } catch (e) { log('warn', 'plan completion sweep: ' + e.message); }
   }
 
-  // Gate reviews and fixes: do not dispatch until all implement items are complete
+  // Gate reviews and fixes: only when at max concurrency — idle agents should pick up reviews
+  // even if implement items are in progress (implements get priority via sort order, not by blocking)
   const hasIncompleteImplements = queries.getWorkItems(config).some(i =>
     ['queued', 'pending', 'dispatched'].includes(i.status) && (i.type || '').startsWith('implement')
   );
   if (hasIncompleteImplements) {
-    if (allReviews.length > 0) {
-      log('info', `Gating ${allReviews.length} reviews — implement items still in progress`);
-      allReviews = [];
-    }
-    if (allFixes.length > 0) {
-      log('info', `Gating ${allFixes.length} fixes — implement items still in progress`);
-      allFixes = [];
+    const activeCount = (getDispatch().active || []).length;
+    const maxConcurrent = config.engine?.maxConcurrent ?? ENGINE_DEFAULTS.maxConcurrent;
+    const freeSlots = Math.max(0, maxConcurrent - activeCount);
+    if (freeSlots === 0) {
+      if (allReviews.length > 0) {
+        log('info', `Gating ${allReviews.length} reviews — implement items in progress and no free slots`);
+        allReviews = [];
+      }
+      if (allFixes.length > 0) {
+        log('info', `Gating ${allFixes.length} fixes — implement items in progress and no free slots`);
+        allFixes = [];
+      }
     }
   }
 
@@ -3204,10 +3210,10 @@ async function tickInner() {
     });
   }
 
-  const adoPollEnabled = config.engine?.adoPollEnabled ?? DEFAULTS.adoPollEnabled;
-  const ghPollEnabled = config.engine?.ghPollEnabled ?? DEFAULTS.ghPollEnabled;
-  const adoPollStatusEvery = Math.max(1, Number(config.engine?.adoPollStatusEvery) || DEFAULTS.adoPollStatusEvery);
-  const adoPollCommentsEvery = Math.max(1, Number(config.engine?.adoPollCommentsEvery) || DEFAULTS.adoPollCommentsEvery);
+  const adoPollEnabled = config.engine?.adoPollEnabled ?? ENGINE_DEFAULTS.adoPollEnabled;
+  const ghPollEnabled = config.engine?.ghPollEnabled ?? ENGINE_DEFAULTS.ghPollEnabled;
+  const adoPollStatusEvery = Math.max(1, Number(config.engine?.adoPollStatusEvery) || ENGINE_DEFAULTS.adoPollStatusEvery);
+  const adoPollCommentsEvery = Math.max(1, Number(config.engine?.adoPollCommentsEvery) || ENGINE_DEFAULTS.adoPollCommentsEvery);
 
   // 2.6. Poll PR status: build, review, merge (every adoPollStatusEvery ticks, default ~6 minutes)
   // Awaited so PR state is consistent before discoverWork reads it
@@ -3410,7 +3416,7 @@ async function tickInner() {
     if (busyAgents.has(item.agent)) {
       // Agent busy reassignment: if item has been waiting on a busy agent past the threshold,
       // try to find an alternative agent via routing. Skip explicitly assigned items.
-      const reassignMs = config.engine?.agentBusyReassignMs ?? DEFAULTS.agentBusyReassignMs;
+      const reassignMs = config.engine?.agentBusyReassignMs ?? ENGINE_DEFAULTS.agentBusyReassignMs;
       const isExplicitReassign = !!item.meta?.item?.agent;
       if (!isExplicitReassign && reassignMs > 0 && item._agentBusySince) {
         const busySinceMs = new Date(item._agentBusySince).getTime();

package/package.json

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