@yemi33/minions 0.1.1637 → 0.1.1639

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1639 (2026-04-30)
+
+### Fixes
+- auto-link agent-created PRs to work items (#1904)
+-  Playbook 'fix' / 'review' gates items forever when pr_branch is unresolved (closes #1899) (#1901)
+
 ## 0.1.1637 (2026-04-30)
 
 ### Other

package/dashboard/js/render-prs.js

@@ -20,11 +20,15 @@ function prRow(pr) {
   const statusLabel = pr.status || 'active';
   const url = pr.url || '#';
   const prId = pr.id || '—';
+  const pendingReason = pr._pendingReason ? String(pr._pendingReason) : '';
+  const pendingReasonHtml = pendingReason
+    ? '<div style="font-size:9px;color:var(--muted);margin-top:2px" title="Pending reason: ' + escapeHtml(pendingReason) + '">' + escapeHtml(pendingReason.replace(/_/g, ' ')) + '</div>'
+    : '';
   return '<tr>' +
     '<td><span class="pr-id">' + escapeHtml(String(prId)) + '</span></td>' +
     '<td><a class="pr-title" href="' + escapeHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escapeHtml(pr.title || 'Untitled') + '</a>' + (pr.description ? '<div class="pr-desc">' + escapeHtml(pr.description.length > 120 ? pr.description.slice(0, 120) + '...' : pr.description) + '</div>' : '') + '</td>' +
     '<td><span class="pr-agent">' + escapeHtml(pr.agent || '—') + '</span></td>' +
-    '<td><span class="pr-branch">' + escapeHtml(pr.branch || '—') + '</span></td>' +
+    '<td><span class="pr-branch">' + escapeHtml(pr.branch || '—') + '</span>' + pendingReasonHtml + '</td>' +
     '<td><span class="pr-badge ' + reviewClass + '"' + (reviewTitle ? ' title="' + escapeHtml(reviewTitle) + '"' : '') + '>' + escapeHtml(reviewLabel) + '</span></td>' +
     '<td>' + (sq.reviewer && sq.status !== 'waiting' ? '<span class="pr-agent" title="' + escapeHtml(sq.note || '') + '">' + escapeHtml(sq.reviewer) + '</span>' : sq.reviewer && sq.status === 'waiting' ? '<span class="pr-agent" style="color:var(--muted)" title="Vote pending confirmation">' + escapeHtml(sq.reviewer) + '…</span>' : pr.reviewedBy && pr.reviewedBy.length ? '<span class="pr-agent">' + escapeHtml(pr.reviewedBy.join(', ')) + '</span>' : '<span style="color:var(--muted);font-size:11px">—</span>') + '</td>' +
     '<td><span class="pr-badge ' + buildClass + '">' + escapeHtml(buildLabel) + '</span></td>' +

package/dashboard.js

@@ -5838,9 +5838,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // /api/prd/regenerate removed — use /api/plans/approve which does diff-aware update
 
     // Agents
-    { method: 'POST', path: '/api/pull-requests/link', desc: 'Manually link an external PR for tracking', params: 'url, title?, project?, autoObserve?, context?', handler: async (req, res) => {
+    { method: 'POST', path: '/api/pull-requests/link', desc: 'Manually link an external PR for tracking', params: 'url, title?, project?, autoObserve?, context?, workItemId?', handler: async (req, res) => {
       const body = await readBody(req);
-      const { url, title, project: projectName, autoObserve, context } = body;
+      const { url, title, project: projectName, autoObserve, context, workItemId } = body;
       if (!url) return jsonReply(res, 400, { error: 'url required' });
 
       // Determine project
@@ -5853,6 +5853,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const prNumMatch = url.match(/\/pull\/(\d+)|pullrequest\/(\d+)/);
       const prNum = prNumMatch ? (prNumMatch[1] || prNumMatch[2]) : Date.now().toString().slice(-6);
       const prId = shared.getCanonicalPrId(targetProject, prNum, url);
+      const contextText = typeof context === 'string' ? context : (context == null ? '' : JSON.stringify(context));
+
+      // Resolve a work-item association from either the top-level workItemId
+      // field (preferred) or context.workItemId (legacy CC payload shape).
+      // Without this, manually-linked PRs end up with prdItems=[] and the
+      // Work Items page renders no PR even though _context records the ID.
+      const linkedItemId = (typeof workItemId === 'string' && workItemId.trim())
+        || (context && typeof context === 'object' && typeof context.workItemId === 'string' && context.workItemId.trim())
+        || '';
 
       // Atomic check-and-insert to prevent duplicates and races with polling loops
       let duplicate = false;
@@ -5870,15 +5879,25 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           status: 'active',
           created: new Date().toISOString(),
           url,
-          prdItems: [],
+          prdItems: linkedItemId ? [linkedItemId] : [],
           _manual: true,
           _contextOnly: !autoObserve,
           _autoObserve: !!autoObserve,
-          _context: context || '',
+          _context: contextText,
         });
         return prs;
       }, { defaultValue: [] });
       if (duplicate) return jsonReply(res, 400, { error: 'PR already tracked' });
+      // Persist the work-item ↔ PR association in pr-links.json so
+      // queries.getWorkItems() can render item._pr / item._prUrl. addPrLink
+      // is idempotent and handles the central / project-scoped split.
+      if (linkedItemId) {
+        try {
+          shared.addPrLink(prId, linkedItemId, { project: targetProject, prNumber: parseInt(prNum, 10) || null, url });
+        } catch (e) {
+          shared.log('warn', `PR link addPrLink failed for ${prId} → ${linkedItemId}: ${e.message}`);
+        }
+      }
       invalidateStatusCache();
       jsonReply(res, 200, { ok: true, id: prId });
 
@@ -5906,7 +5925,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             // Remote title always wins — any user-supplied title is a placeholder (closes #1283)
             if (prData.title) pr.title = prData.title.slice(0, 120);
             if (prData.description) pr.description = prData.description.slice(0, 500);
-            if (!pr.branch && prData.branch) pr.branch = prData.branch;
+            if (!pr.branch && prData.branch) {
+              pr.branch = prData.branch;
+              if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+            }
             if (pr.agent === 'human' && prData.author) pr.agent = prData.author;
             return prs;
           }, { defaultValue: [] });

package/engine/ado.js

@@ -405,6 +405,12 @@ async function pollPrStatus(config) {
       pr._adoSourceCommit = sourceCommit;
       updated = true;
     }
+    const sourceBranch = stripRefsHeads(prData.sourceRefName);
+    if (!pr.branch && sourceBranch) {
+      pr.branch = sourceBranch;
+      if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+      updated = true;
+    }
 
     const reviewers = prData.reviewers || [];
     const votes = reviewers.map(r => r.vote).filter(v => v !== undefined);
@@ -759,6 +765,7 @@ async function reconcilePrs(config) {
     shared.normalizePrRecords(existingPrs, project);
     const existingIds = new Set(existingPrs.map(p => p.id));
     let projectAdded = 0;
+    let metadataUpdated = 0;
 
     // Load work items to match branches to work item IDs
     const wiPath = shared.projectWorkItemsPath(project);
@@ -786,6 +793,11 @@ async function reconcilePrs(config) {
         if (existing && existing.prNumber == null) {
           existing.prNumber = adoPr.pullRequestId;
         }
+        if (existing && !existing.branch && branch) {
+          existing.branch = branch;
+          if (existing._pendingReason === 'missing_pr_branch') delete existing._pendingReason;
+          metadataUpdated++;
+        }
         // PR already tracked — write link to pr-links.json if we can extract an ID
         if (confirmedItemId) {
           addPrLink(prId, confirmedItemId, { project, prNumber: adoPr.pullRequestId, url: prUrl });
@@ -832,7 +844,7 @@ async function reconcilePrs(config) {
     // Backfill prdItems from pr-links for any PR with empty array
     const backfilled = shared.backfillPrPrdItems(existingPrs, shared.getPrLinks());
 
-    if (projectAdded > 0 || projectUpdated > 0 || backfilled > 0) {
+    if (projectAdded > 0 || projectUpdated > 0 || backfilled > 0 || metadataUpdated > 0) {
       mutateJsonFileLocked(prPath, (currentPrs) => {
         // Merge reconciled PRs into the locked copy by ID
         for (const pr of existingPrs) {

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-04-30T15:02:24.638Z"
+  "cachedAt": "2026-04-30T16:35:01.979Z"
 }

package/engine/github.js

@@ -282,7 +282,10 @@ async function forEachActiveGhPr(config, callback) {
             }
             if (pr.description === undefined) pr.description = (prData.body || '').slice(0, 500);
             if (pr.agent === 'human' && prData.user?.login) pr.agent = prData.user.login;
-            if (!pr.branch && prData.head?.ref) pr.branch = prData.head.ref;
+            if (!pr.branch && prData.head?.ref) {
+              pr.branch = prData.head.ref;
+              if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+            }
           }
         }
         centralUpdated++;
@@ -673,6 +676,7 @@ async function reconcilePrs(config) {
     const currentPrs = safeJson(prPath) || [];
     shared.normalizePrRecords(currentPrs, project);
     const existingIds = new Set(currentPrs.map(p => p.id));
+    let metadataUpdated = 0;
     let projectAdded = 0;
 
     // Load work items to match branches
@@ -697,6 +701,11 @@ async function reconcilePrs(config) {
         if (existing && existing.prNumber == null) {
           existing.prNumber = ghPr.number;
         }
+        if (existing && !existing.branch && branch) {
+          existing.branch = branch;
+          if (existing._pendingReason === 'missing_pr_branch') delete existing._pendingReason;
+          metadataUpdated++;
+        }
         if (confirmedItemId) {
           addPrLink(prId, confirmedItemId, { project, prNumber: ghPr.number, url: prUrl });
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
@@ -743,7 +752,7 @@ async function reconcilePrs(config) {
     // Backfill prdItems from pr-links for any PR with empty array
     const backfilled = backfillPrPrdItems(currentPrs, getPrLinks());
 
-    if (projectAdded > 0 || backfilled > 0) {
+    if (projectAdded > 0 || backfilled > 0 || metadataUpdated > 0) {
       mutateJsonFileLocked(prPath, (lockedPrs) => {
         for (const pr of currentPrs) {
           const idx = lockedPrs.findIndex(p => p.id === pr.id);

package/engine/lifecycle.js

@@ -744,13 +744,33 @@ function syncPrsFromOutput(output, agentId, meta, config) {
     }
   } catch {}
 
+  // prId → URL captured from inbox notes. Populated alongside prMatches so
+  // extractPrUrl below has a fallback when the agent's stdout doesn't contain
+  // the URL (the W-moljyu60wuzr / #1902 case — gh pr create ran in a sibling
+  // dispatch and only the inbox note carries the link).
+  const inboxUrls = new Map();
   const today = dateStamp();
   const inboxFiles = getInboxFiles().filter(f => f.includes(agentId) && f.includes(today));
   for (const f of inboxFiles) {
     const content = safeRead(path.join(INBOX_DIR, f));
     if (!content) continue;
-    const prHeaderPattern = /\*\*PR[:\*]*\*?\s*[#-]*\s*(?:(?:visualstudio\.com|dev\.azure\.com)[^\s"]*?pullrequest\/(\d+)|github\.com\/[^\s"]*?\/pull\/(\d+))/gi;
-    while ((match = prHeaderPattern.exec(content)) !== null) prMatches.add(match[1] || match[2]);
+    // Match a PR declaration line in the agent's findings note: optional bold,
+    // optional "Pull Request" spelling, line-anchored so "see PR https://..."
+    // mid-paragraph mentions don't trigger a false-positive. The protocol
+    // and host prefix is optional so "PR: https://github.com/..." ,
+    // "**PR:** github.com/...", etc. all match.
+    const prHeaderPattern = /(?:^|\n)\s*\*{0,2}(?:PR|Pull\s+Request)[:\*]*\*?\s*[#-]*\s*(?:https?:\/\/)?[^\s"]*?(?:(?:visualstudio\.com|dev\.azure\.com)[^\s"]*?pullrequest\/(\d+)|github\.com\/[^\s"]*?\/pull\/(\d+))/gi;
+    while ((match = prHeaderPattern.exec(content)) !== null) {
+      const prId = match[1] || match[2];
+      prMatches.add(prId);
+      // Pull the URL substring out of the matched chunk so we can hand it to
+      // extractPrUrl as a fallback. Prefer the first inbox URL we see for a
+      // given prId — later notes don't override the canonical record.
+      if (!inboxUrls.has(prId)) {
+        const urlMatch = match[0].match(/https?:\/\/[^\s"\\)]+/);
+        if (urlMatch) inboxUrls.set(prId, urlMatch[0].replace(/[.,;:]+$/, ''));
+      }
+    }
   }
 
   if (prMatches.size === 0) return 0;
@@ -773,7 +793,10 @@ function syncPrsFromOutput(output, agentId, meta, config) {
     return defaultProject;
   }
 
-  // Extract PR URL directly from agent output — no manual construction
+  // Extract PR URL directly from agent output — no manual construction.
+  // Falls back to the URL captured from the inbox note when the agent stdout
+  // doesn't contain the link (gh pr create may have run in a sibling dispatch
+  // whose stdout was rotated; the inbox note is the durable artifact).
   function extractPrUrl(prId) {
     // Stop at backslash in addition to whitespace/quotes — raw JSONL encodes newlines as \n (literal
     // backslash-n), so without this the regex would capture e.g. "pull/1804\n/usr/bin/bash".
@@ -781,7 +804,7 @@ function syncPrsFromOutput(output, agentId, meta, config) {
     if (ghMatch) return ghMatch[0].replace(/[.,;:]+$/, '');
     const adoMatch = output.match(new RegExp(`https?://(?:dev\\.azure\\.com|[^/]+\\.visualstudio\\.com)[^\\s"'\\)\\]\\\\]*?pullrequest/${prId}(?:[^\\s"'\\)\\]\\\\]*)`, 'i'));
     if (adoMatch) return adoMatch[0].replace(/[.,;:]+$/, '');
-    return '';
+    return inboxUrls.get(prId) || '';
   }
 
   const agentName = config.agents?.[agentId]?.name || agentId;

package/engine.js

@@ -1980,6 +1980,58 @@ function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   } catch (e) { log('warn', 'clear pending human feedback flag: ' + e.message); }
 }
 
+const PR_PENDING_MISSING_BRANCH = 'missing_pr_branch';
+
+function getPrDispatchBranch(pr) {
+  return typeof pr?.branch === 'string' ? pr.branch.trim() : '';
+}
+
+function mutatePrPendingReason(project, pr, mutator) {
+  const prPath = projectPrPath(project);
+  let changed = false;
+  mutatePullRequests(prPath, prs => {
+    const target = shared.findPrRecord(prs, pr, project);
+    if (!target) return prs;
+    changed = mutator(target) === true;
+    return prs;
+  });
+  return changed;
+}
+
+function markPrMissingBranch(project, pr, action) {
+  if (pr._pendingReason === PR_PENDING_MISSING_BRANCH) return false;
+  const changed = mutatePrPendingReason(project, pr, target => {
+    if (target._pendingReason === PR_PENDING_MISSING_BRANCH) return false;
+    target._pendingReason = PR_PENDING_MISSING_BRANCH;
+    return true;
+  });
+  if (changed) {
+    pr._pendingReason = PR_PENDING_MISSING_BRANCH;
+    log('warn', `PR ${pr.id}: cannot dispatch ${action} — missing pr_branch; waiting for PR metadata enrichment`);
+  }
+  return changed;
+}
+
+function clearPrMissingBranch(project, pr) {
+  if (pr._pendingReason !== PR_PENDING_MISSING_BRANCH) return false;
+  const changed = mutatePrPendingReason(project, pr, target => {
+    if (target._pendingReason !== PR_PENDING_MISSING_BRANCH) return false;
+    delete target._pendingReason;
+    return true;
+  });
+  if (changed) delete pr._pendingReason;
+  return changed;
+}
+
+function canDispatchPrBranch(project, pr, action) {
+  if (getPrDispatchBranch(pr)) {
+    clearPrMissingBranch(project, pr);
+    return true;
+  }
+  markPrMissingBranch(project, pr, action);
+  return false;
+}
+
 /**
  * Scan pull-requests.json for PRs needing review or fixes
  */
@@ -2021,6 +2073,7 @@ async function discoverFromPrs(config, project) {
     const prDisplayId = shared.getPrDisplayId(pr);
     const prCanonicalId = shared.getCanonicalPrId(project, pr, pr.url || '');
     if (activePrIds.has(prCanonicalId)) continue; // Skip PRs with active dispatch (prevent race)
+    if (getPrDispatchBranch(pr)) clearPrMissingBranch(project, pr);
     // Branch mutex: skip if PR branch is locked by any active dispatch (cross-type collision)
     if (pr.branch && isBranchActive(pr.branch)) {
       log('info', `Branch mutex: skipping PR ${pr.id} dispatch — branch ${pr.branch} locked by another agent`);
@@ -2061,6 +2114,7 @@ async function discoverFromPrs(config, project) {
     if (needsReview) {
       const key = `review-${project?.name || 'default'}-${prDisplayId}`;
       if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
+      if (!canDispatchPrBranch(project, pr, 'review')) continue;
 
       // Pre-dispatch live vote check — cached reviewStatus may be stale (poll lag ~6 min)
       try {
@@ -2104,6 +2158,7 @@ async function discoverFromPrs(config, project) {
       // Skip isAlreadyDispatched — fixedAfterReview/lastReviewedAt already dedupe; the 1hr
       // completed-dispatch window would block legitimate re-reviews within the hour after a fix
       if (isOnCooldown(key, cooldownMs)) continue;
+      if (!canDispatchPrBranch(project, pr, 're-review')) continue;
 
       // Pre-dispatch live vote check — cached 'waiting' may be stale if reviewer already acted
       try {
@@ -2140,6 +2195,7 @@ async function discoverFromPrs(config, project) {
     if (evalLoopEnabled && reviewStatus === 'changes-requested' && !awaitingReReview && !evalEscalated) {
       const key = `fix-${project?.name || 'default'}-${prDisplayId}`;
       if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
+      if (!canDispatchPrBranch(project, pr, 'fix')) continue;
       const agentId = resolveAgent('fix', config, { authorAgent: pr.agent });
       if (!agentId) continue;
 
@@ -2179,6 +2235,7 @@ async function discoverFromPrs(config, project) {
         }
         continue;
       }
+      if (!canDispatchPrBranch(project, pr, 'human-feedback fix')) continue;
       const agentId = resolveAgent('fix', config, { authorAgent: pr.agent });
       if (!agentId) continue;
 
@@ -2226,6 +2283,7 @@ async function discoverFromPrs(config, project) {
 
       const key = `build-fix-${project?.name || 'default'}-${prDisplayId}`;
       if (fixThrottled || isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
+      if (!canDispatchPrBranch(project, pr, 'build fix')) continue;
 
       // Pre-dispatch live build check — cached buildStatus may be stale: ADO can
       // recompute the merge commit when master moves and pollPrStatus deliberately
@@ -2310,6 +2368,7 @@ async function discoverFromPrs(config, project) {
       const conflictFixedAt = pr._conflictFixedAt;
       const withinLag = conflictFixedAt && Date.now() - new Date(conflictFixedAt).getTime() < 10 * 60 * 1000;
       if (!withinLag && !fixThrottled && !isAlreadyDispatched(key) && !isOnCooldown(key, cooldownMs)) {
+        if (!canDispatchPrBranch(project, pr, 'conflict fix')) continue;
         // Pre-dispatch live conflict check — cached `_mergeConflict` may be
         // stale: ADO/GitHub recompute mergeStatus asynchronously (1–5 min lag),
         // so a successful upstream merge can leave the flag set even after the

package/package.json

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