@yemi33/minions 0.1.1639 → 0.1.1641

package/CHANGELOG.md

@@ -1,9 +1,18 @@
 # Changelog
 
-## 0.1.1639 (2026-04-30)
+## 0.1.1641 (2026-04-30)
+
+### Features
+- harden PR attachment contract (#1908)
+
+## 0.1.1640 (2026-04-30)
+
+### Fixes
+- surface unresolved pr branches
+
+## 0.1.1638 (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)

package/dashboard/js/render-prs.js

@@ -18,6 +18,9 @@ function prRow(pr) {
   const buildLabel = pr.buildFixEscalated ? 'escalated (' + (pr.buildFixAttempts || '?') + ' fixes)' : (pr.buildStatus || 'none') + (pr._buildStatusStale ? ' (stale)' : '');
   const statusClass = pr.status === 'merged' ? 'merged' : pr.status === 'abandoned' ? 'rejected' : pr.status === 'active' ? 'active' : 'draft';
   const statusLabel = pr.status || 'active';
+  const branchError = pr._branchResolutionError?.reason || '';
+  const branchLabel = pr.branch || (branchError ? 'missing branch' : '—');
+  const branchClass = 'pr-branch' + (branchError ? ' branch-missing' : '');
   const url = pr.url || '#';
   const prId = pr.id || '—';
   const pendingReason = pr._pendingReason ? String(pr._pendingReason) : '';
@@ -28,7 +31,7 @@ function prRow(pr) {
     '<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>' + pendingReasonHtml + '</td>' +
+    '<td><span class="' + branchClass + '"' + (branchError ? ' title="' + escapeHtml(branchError) + '"' : '') + '>' + escapeHtml(branchLabel) + '</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/styles.css

@@ -262,6 +262,7 @@
   .pr-id { color: var(--muted); font-family: Consolas, monospace; font-size: var(--text-base); }
   .pr-agent { font-size: var(--text-base); color: var(--text); }
   .pr-branch { font-family: Consolas, monospace; font-size: var(--text-sm); color: var(--muted); background: var(--bg); padding: var(--space-1) var(--space-3); border-radius: 3px; border: 1px solid var(--border); }
+  .pr-branch.branch-missing { color: var(--red); border-color: var(--red); background: rgba(248,81,73,0.12); }
   .pr-badge { font-size: var(--text-sm); font-weight: 600; padding: var(--space-1) var(--space-4); border-radius: var(--radius-xl); text-transform: uppercase; letter-spacing: 0.5px; white-space: nowrap; }
   .pr-badge.draft { background: rgba(139,148,158,0.15); color: var(--muted); border: 1px solid var(--border); }
   .pr-badge.active { background: rgba(88,166,255,0.15); color: var(--blue); border: 1px solid var(--blue); }

package/dashboard.js

@@ -63,6 +63,55 @@ function reloadConfig() {
   PROJECTS = _getProjects(CONFIG);
 }
 
+function getWorkItemIdFromPrLinkContext(context, workItemId) {
+  if (typeof workItemId === 'string' && workItemId.trim()) return workItemId.trim();
+  if (!context) return null;
+  if (typeof context === 'object' && typeof context.workItemId === 'string' && context.workItemId.trim()) return context.workItemId.trim();
+  if (typeof context === 'string') {
+    const match = context.match(/\b(P-[a-z0-9]{6,}|W-[a-z0-9]{6,}|PL-[a-z0-9]{6,})\b/i);
+    return match ? match[1] : null;
+  }
+  return null;
+}
+
+function linkPullRequestForTracking({ url, title, project: projectName, autoObserve, context, workItemId }, config = CONFIG) {
+  if (!url) {
+    const err = new Error('url required');
+    err.statusCode = 400;
+    throw err;
+  }
+  const projects = shared.getProjects(config);
+  const targetProject = projectName ? projects.find(p => p.name?.toLowerCase() === projectName.toLowerCase()) : (projects[0] || null);
+  const prPath = targetProject ? shared.projectPrPath(targetProject) : path.join(MINIONS_DIR, 'pull-requests.json');
+
+  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 linkedWorkItemId = getWorkItemIdFromPrLinkContext(context, workItemId);
+  const contextText = typeof context === 'string' ? context : (context == null ? '' : JSON.stringify(context));
+  const result = shared.upsertPullRequestRecord(prPath, {
+    id: prId,
+    prNumber: parseInt(prNum, 10) || null,
+    title: (title || 'PR #' + prNum + ' (polling...)').slice(0, 120),
+    description: '',
+    agent: 'human',
+    branch: '',
+    reviewStatus: 'pending',
+    status: 'active',
+    created: new Date().toISOString(),
+    url,
+    prdItems: linkedWorkItemId ? [linkedWorkItemId] : [],
+    _manual: true,
+    _contextOnly: !autoObserve,
+    _autoObserve: !!autoObserve,
+    _context: contextText,
+  }, {
+    project: targetProject,
+    itemId: linkedWorkItemId,
+  });
+  return { ...result, prPath, targetProject, prNum };
+}
+
 function _normalizeSkillDirForCompare(dir) {
   const resolved = path.resolve(String(dir || '').replace(/\//g, path.sep));
   return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
@@ -5840,66 +5889,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // Agents
     { 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, workItemId } = body;
+      const { url } = body;
       if (!url) return jsonReply(res, 400, { error: 'url required' });
 
-      // Determine project
       reloadConfig();
-      const projects = shared.getProjects(CONFIG);
-      const targetProject = projectName ? projects.find(p => p.name?.toLowerCase() === projectName.toLowerCase()) : (projects[0] || null);
-      const prPath = targetProject ? shared.projectPrPath(targetProject) : path.join(MINIONS_DIR, 'pull-requests.json');
-
-      // Extract PR number from URL
-      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;
-      mutateJsonFileLocked(prPath, (prs) => {
-        if (!Array.isArray(prs)) prs = [];
-        if (prs.some(p => p.id === prId || p.url === url)) { duplicate = true; return prs; }
-        prs.push({
-          id: prId,
-          prNumber: parseInt(prNum, 10) || null,
-          title: (title || 'PR #' + prNum + ' (polling...)').slice(0, 120),
-          description: '',
-          agent: 'human',
-          branch: '',
-          reviewStatus: 'pending',
-          status: 'active',
-          created: new Date().toISOString(),
-          url,
-          prdItems: linkedItemId ? [linkedItemId] : [],
-          _manual: true,
-          _contextOnly: !autoObserve,
-          _autoObserve: !!autoObserve,
-          _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}`);
-        }
-      }
+      const { id: prId, prPath, targetProject, prNum, created, linked } = linkPullRequestForTracking(body, CONFIG);
       invalidateStatusCache();
-      jsonReply(res, 200, { ok: true, id: prId });
+      jsonReply(res, 200, { ok: true, id: prId, created, linked });
 
       // Async-enrich: fetch title, description, branch, author from GitHub/ADO API
       (async () => {
@@ -5927,6 +5923,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             if (prData.description) pr.description = prData.description.slice(0, 500);
             if (!pr.branch && prData.branch) {
               pr.branch = prData.branch;
+              if (pr._branchResolutionError) delete pr._branchResolutionError;
               if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
             }
             if (pr.agent === 'human' && prData.author) pr.agent = prData.author;
@@ -6425,6 +6422,7 @@ module.exports = {
   _parseDocChatResultText,
   _messageRequestsOrchestration,
   _formatDocChatContext,
+  _linkPullRequestForTracking: linkPullRequestForTracking,
   _resolveSkillReadPath,
   DOC_CHAT_DOCUMENT_DELIMITER,
 };

package/engine/ado.js

@@ -5,7 +5,7 @@
 
 const path = require('path');
 const shared = require('./shared');
-const { exec, execAsync, getAdoOrgBase, addPrLink, log, ts, dateStamp, PR_STATUS, createThrottleTracker } = shared;
+const { exec, execAsync, getAdoOrgBase, log, ts, dateStamp, PR_STATUS, createThrottleTracker } = shared;
 const { getPrs } = require('./queries');
 const { mutateJsonFileLocked } = shared;
 
@@ -357,6 +357,14 @@ async function pollPrStatus(config) {
 
     const prData = await adoFetch(`${repoBase}?api-version=7.1`, token);
 
+    const sourceBranch = stripRefsHeads(prData.sourceRefName);
+    if (sourceBranch && pr.branch !== sourceBranch) {
+      pr.branch = sourceBranch;
+      if (pr._branchResolutionError) delete pr._branchResolutionError;
+      if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+      updated = true;
+    }
+
     let newStatus = pr.status;
     if (prData.status === 'completed') newStatus = PR_STATUS.MERGED;
     else if (prData.status === 'abandoned') newStatus = PR_STATUS.ABANDONED;
@@ -405,12 +413,6 @@ 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);
@@ -795,12 +797,24 @@ async function reconcilePrs(config) {
         }
         if (existing && !existing.branch && branch) {
           existing.branch = branch;
+          if (existing._branchResolutionError) delete existing._branchResolutionError;
           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 });
+          shared.upsertPullRequestRecord(prPath, existing || {
+            id: prId,
+            prNumber: adoPr.pullRequestId,
+            title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
+            agent: (linkedItem?.dispatched_to || adoPr.createdBy?.displayName || 'unknown').toLowerCase(),
+            branch,
+            reviewStatus: 'pending',
+            status: 'active',
+            created: adoPr.creationDate || ts(),
+            url: prUrl,
+            prdItems: [],
+          }, { project, itemId: confirmedItemId });
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
             existing.prdItems.push(confirmedItemId);
@@ -815,7 +829,7 @@ async function reconcilePrs(config) {
       // are human-authored and should not be auto-tracked or auto-reviewed.
       if (!confirmedItemId) continue;
 
-      existingPrs.push({
+      const entry = {
         id: prId,
         prNumber: adoPr.pullRequestId,
         title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
@@ -826,8 +840,9 @@ async function reconcilePrs(config) {
         created: adoPr.creationDate || ts(),
         url: prUrl,
         prdItems: [confirmedItemId],
-      });
-      addPrLink(prId, confirmedItemId, { project, prNumber: adoPr.pullRequestId, url: prUrl });
+      };
+      const upserted = shared.upsertPullRequestRecord(prPath, entry, { project, itemId: confirmedItemId });
+      existingPrs.push(upserted.record || entry);
       existingIds.add(prId);
       projectAdded++;
       log('info', `PR reconciliation: added ${prId} (branch: ${branch}, linked to ${confirmedItemId}) to ${project.name}`);

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-04-30T16:35:01.979Z"
+  "cachedAt": "2026-04-30T17:23:35.113Z"
 }

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, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, createThrottleTracker } = shared;
+const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, mutateJsonFileLocked, MINIONS_DIR, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, createThrottleTracker } = shared;
 const { getPrs } = require('./queries');
 const path = require('path');
 
@@ -284,6 +284,7 @@ async function forEachActiveGhPr(config, callback) {
             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._branchResolutionError) delete pr._branchResolutionError;
               if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
             }
           }
@@ -327,6 +328,14 @@ async function pollPrStatus(config) {
 
     let updated = false;
 
+    const headBranch = prData.head?.ref ? String(prData.head.ref).trim() : '';
+    if (headBranch && pr.branch !== headBranch) {
+      pr.branch = headBranch;
+      if (pr._branchResolutionError) delete pr._branchResolutionError;
+      if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+      updated = true;
+    }
+
     // Map GitHub PR state to minions status
     let newStatus = pr.status;
     if (prData.merged) newStatus = PR_STATUS.MERGED;
@@ -703,11 +712,23 @@ async function reconcilePrs(config) {
         }
         if (existing && !existing.branch && branch) {
           existing.branch = branch;
+          if (existing._branchResolutionError) delete existing._branchResolutionError;
           if (existing._pendingReason === 'missing_pr_branch') delete existing._pendingReason;
           metadataUpdated++;
         }
         if (confirmedItemId) {
-          addPrLink(prId, confirmedItemId, { project, prNumber: ghPr.number, url: prUrl });
+          shared.upsertPullRequestRecord(prPath, existing || {
+            id: prId,
+            prNumber: ghPr.number,
+            title: (ghPr.title || `PR #${ghPr.number}`).slice(0, 120),
+            agent: (linkedItem?.dispatched_to || ghPr.user?.login || 'unknown').toLowerCase(),
+            branch,
+            reviewStatus: 'pending',
+            status: 'active',
+            created: ghPr.created_at || ts(),
+            url: prUrl,
+            prdItems: [],
+          }, { project, itemId: confirmedItemId });
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
             existing.prdItems.push(confirmedItemId);
@@ -722,7 +743,7 @@ async function reconcilePrs(config) {
       // Only auto-track PRs linked to a minions work item — skip human-authored PRs
       if (!confirmedItemId && !isE2eBranch) continue;
 
-      currentPrs.push({
+      const entry = {
         id: prId,
         prNumber: ghPr.number,
         title: (ghPr.title || `PR #${ghPr.number}`).slice(0, 120),
@@ -733,8 +754,9 @@ async function reconcilePrs(config) {
         created: ghPr.created_at || ts(),
         url: prUrl,
         prdItems: [confirmedItemId],
-      });
-      addPrLink(prId, confirmedItemId, { project, prNumber: ghPr.number, url: prUrl });
+      };
+      const upserted = shared.upsertPullRequestRecord(prPath, entry, { project, itemId: confirmedItemId });
+      currentPrs.push(upserted.record || entry);
       existingIds.add(prId);
       projectAdded++;
 

package/engine/lifecycle.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, execSilent, execAsync, projectPrPath, getPrLinks, addPrLink,
+const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, execSilent, execAsync, projectPrPath, getPrLinks,
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PR_STATUS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
@@ -853,53 +853,172 @@ function syncPrsFromOutput(output, agentId, meta, config) {
   const entryBranch = meta?.branch || '';
 
   for (const [prPath, { name, project: targetProject, entries }] of newPrsByPath) {
-    const linksToPersist = [];
-    mutateJsonFileLocked(prPath, (data) => {
-      const prs = Array.isArray(data) ? data : [];
-      // Normalize legacy YYYY-MM-DD created dates to ISO
-      for (const p of prs) {
-        if (p.created && p.created.length === 10) p.created = p.created + 'T00:00:00.000Z';
-      }
-      for (const { prId, fullId, entry } of entries) {
-        if (prs.some(p => p.id === fullId || (p.url && p.url === entry.url))) continue;
-
-        // Branch-level dedup: skip if an active PR already exists on the same branch.
-        // This prevents duplicate PRs when an agent retries and calls `gh pr create` again
-        // on the same branch (GitHub allows multiple PRs from one branch).
-        // Only block when the existing PR is active — abandoned/merged PRs don't conflict.
-        const branch = entry.branch || entryBranch;
-        if (branch) {
-          const existingOnBranch = prs.find(p => p.branch === branch && p.status === PR_STATUS.ACTIVE && p.id !== fullId);
-          if (existingOnBranch) {
-            log('warn', `Duplicate PR detected: ${fullId} on branch ${branch} — already tracked as ${existingOnBranch.id}. Skipping.`);
-            // Best-effort close the duplicate on GitHub (non-blocking, fire-and-forget)
-            try {
-              const ghSlug = output.match(/github\.com\/([^/]+\/[^/]+)/)?.[1];
-              if (ghSlug) {
-                execAsync(`gh pr close ${prId} --repo ${ghSlug} --comment "Closing duplicate — ${existingOnBranch.id} already tracks this branch."`, { timeout: 15000 })
-                  .catch(() => {});
-              }
-            } catch { /* best-effort */ }
-            continue;
+    for (const { prId, fullId, entry } of entries) {
+      let duplicateOnBranch = null;
+      const result = shared.upsertPullRequestRecord(prPath, entry, {
+        project: targetProject,
+        itemId: meta?.item?.id || null,
+        beforeInsert: (prs, normalizedEntry) => {
+          // Normalize legacy YYYY-MM-DD created dates to ISO while the file is locked.
+          for (const p of prs) {
+            if (p.created && p.created.length === 10) p.created = p.created + 'T00:00:00.000Z';
           }
-        }
-
-        prs.push(entry);
-        if (meta?.item?.id) {
-          linksToPersist.push({ prId: fullId, itemId: meta.item.id, project: targetProject, prNumber: entry.prNumber, url: entry.url });
-        }
-        added++;
+          // Branch-level dedup: skip if an active PR already exists on the same branch.
+          // This prevents duplicate PRs when an agent retries and calls `gh pr create` again
+          // on the same branch (GitHub allows multiple PRs from one branch).
+          // Only block when the existing PR is active — abandoned/merged PRs don't conflict.
+          const branch = normalizedEntry.branch || entryBranch;
+          if (!branch) return true;
+          duplicateOnBranch = prs.find(p => p.branch === branch && p.status === PR_STATUS.ACTIVE && p.id !== normalizedEntry.id) || null;
+          return !duplicateOnBranch;
+        },
+      });
+      if (duplicateOnBranch) {
+        log('warn', `Duplicate PR detected: ${fullId} on branch ${entry.branch || entryBranch} — already tracked as ${duplicateOnBranch.id}. Skipping.`);
+        // Best-effort close the duplicate on GitHub (non-blocking, fire-and-forget)
+        try {
+          const ghSlug = output.match(/github\.com\/([^/]+\/[^/]+)/)?.[1];
+          if (ghSlug) {
+            execAsync(`gh pr close ${prId} --repo ${ghSlug} --comment "Closing duplicate — ${duplicateOnBranch.id} already tracks this branch."`, { timeout: 15000 })
+              .catch(() => {});
+          }
+        } catch { /* best-effort */ }
+        continue;
       }
-      return prs;
-    });
-    for (const { prId, itemId, project, prNumber, url } of linksToPersist) {
-      addPrLink(prId, itemId, { project, prNumber, url });
+      if (result.created || result.linked) added++;
     }
     log('info', `Synced PR(s) from ${agentName}'s output to ${name === '_central' ? 'central' : name}/pull-requests.json`);
   }
   return added;
 }
 
+function isPrAttachmentRequired(type, item, meta = {}) {
+  if (!item?.id || item.skipPr) return false;
+  const explicit = item.requiresPr === true
+    || item.prRequired === true
+    || item.requiresPullRequest === true
+    || item.itemType === 'pr';
+  if (meta.branchStrategy === 'shared-branch' && item.itemType !== 'pr' && !explicit) return false;
+  return explicit
+    || type === WORK_TYPE.IMPLEMENT
+    || type === WORK_TYPE.IMPLEMENT_LARGE
+    || type === WORK_TYPE.FIX
+    || type === WORK_TYPE.TEST;
+}
+
+function hasCanonicalPrAttachment(itemId, config) {
+  if (!itemId) return false;
+  if (Object.values(getPrLinks()).some(linkedIds => (linkedIds || []).includes(itemId))) return true;
+  const projects = shared.getProjects(config);
+  for (const p of projects) {
+    const prs = safeJson(shared.projectPrPath(p)) || [];
+    if (prs.some(pr => (pr.prdItems || []).includes(itemId))) return true;
+  }
+  const centralPrs = safeJson(path.join(MINIONS_DIR, 'pull-requests.json')) || [];
+  return centralPrs.some(pr => (pr.prdItems || []).includes(itemId));
+}
+
+async function findOpenPrForBranch(meta, config) {
+  if (!meta?.branch) return null;
+  const projectObj = shared.getProjects(config).find(p => p.name === meta?.project?.name);
+  if (!projectObj) return null;
+  const host = projectObj.repoHost || 'ado';
+  if (host === 'github') {
+    const ghSlug = projectObj.prUrlBase?.match(/github\.com\/([^/]+\/[^/]+)\/pull/)?.[1];
+    if (!ghSlug) return null;
+    for (let attempt = 0; attempt < 3; 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') {
+          return { project: projectObj, prNumber: hits[0].number, url: hits[0].url };
+        }
+        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}`);
+        }
+      }
+    }
+    return null;
+  }
+  if (host === 'ado') {
+    const found = await require('./ado').findOpenPrOnBranch(projectObj, meta.branch);
+    return found ? { project: projectObj, prNumber: found.prNumber, url: found.url } : null;
+  }
+  log('debug', `Skipping branch PR lookup for unsupported repo host "${host}" on ${projectObj.name}`);
+  return null;
+}
+
+function markMissingPrAttachment(meta, agentId, reason, resultSummary) {
+  const noPrWiPath = resolveWorkItemPath(meta);
+  if (noPrWiPath) {
+    mutateJsonFileLocked(noPrWiPath, data => {
+      if (!Array.isArray(data)) return data;
+      const w = data.find(i => i.id === meta.item.id);
+      if (!w) return data;
+      w.status = WI_STATUS.NEEDS_REVIEW;
+      w._missingPrAttachment = true;
+      w.failReason = reason;
+      w._lastReviewReason = reason;
+      delete w.completedAt;
+      delete w._noPr;
+      delete w._noPrReason;
+      return data;
+    }, { skipWriteIfUnchanged: true });
+  }
+  shared.writeToInbox('engine', `missing-pr-attachment-${meta.item.id}`,
+    `# PR attachment missing for ${meta.item.id}\n\n` +
+    `**Agent:** ${agentId}\n` +
+    `**Work item:** \`${meta.item.id}\` — ${meta.item.title || ''}\n` +
+    `**Type:** ${meta.item.type || 'unknown'}\n` +
+    `**Branch:** ${meta.branch || '(none)'}\n\n` +
+    `${reason}\n` +
+    (resultSummary ? `\n## Agent summary\n${resultSummary}\n` : ''),
+    null,
+    { sourceItem: meta.item.id, reason: 'missing-pr-attachment' });
+}
+
+async function enforcePrAttachmentContract(type, meta, agentId, config, resultSummary) {
+  if (!isPrAttachmentRequired(type, meta?.item, meta)) return null;
+  if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
+
+  const found = await findOpenPrForBranch(meta, config);
+  if (found) {
+    const entry = {
+      id: shared.getCanonicalPrId(found.project, found.prNumber, found.url),
+      prNumber: found.prNumber,
+      title: meta.item?.title || `PR #${found.prNumber}`,
+      agent: agentId,
+      branch: meta.branch || '',
+      reviewStatus: 'pending',
+      status: PR_STATUS.ACTIVE,
+      created: ts(),
+      url: found.url,
+      prdItems: [meta.item.id],
+      sourcePlan: meta.item?.sourcePlan || '',
+      itemType: meta.item?.itemType || '',
+    };
+    shared.upsertPullRequestRecord(shared.projectPrPath(found.project), entry, {
+      project: found.project,
+      itemId: meta.item.id,
+    });
+    log('info', `Auto-linked existing PR ${entry.id} on branch ${meta.branch} for ${meta.item.id}`);
+    if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
+  }
+
+  const reason = `PR-producing work item ${meta.item.id} completed without a canonically attached PR record. Successful completion requires PR.prdItems/pr-links.json to include the work item; branch names, note URLs, and _context.workItemId metadata are not sufficient.`;
+  markMissingPrAttachment(meta, agentId, reason, resultSummary);
+  log('warn', reason);
+  return { reason, itemId: meta.item.id };
+}
+
 // ─── Post-Completion Hooks ──────────────────────────────────────────────────
 
 /**
@@ -1688,8 +1807,8 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     log('info', `Structured completion reports PR (${structuredCompletion.pr}) but regex sync found none — PR may already be tracked`);
   }
 
-  // Auto-recover: if a failed implement/fix agent created PRs, it likely succeeded before the failure surfaced.
-  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX;
+  // Auto-recover: if a failed implement/fix/test agent created PRs, it likely succeeded before the failure surfaced.
+  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX || type === WORK_TYPE.TEST;
   const autoRecovered = !isSuccess && prsCreatedCount > 0 && prCreatingType && !!meta?.item?.id;
   if (autoRecovered) {
     log('info', `Auto-recovery: agent failed but created ${prsCreatedCount} PR(s) — upgrading ${meta.item.id} to done`);
@@ -1799,6 +1918,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
+  let completionContractFailure = null;
+  if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
+    completionContractFailure = await enforcePrAttachmentContract(type, meta, agentId, config, resultSummary);
+    if (completionContractFailure) skipDoneStatus = true;
+  }
+
   if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
     meta._agentId = agentId;
     updateWorkItemStatus(meta, WI_STATUS.DONE, '');
@@ -1898,131 +2023,6 @@ 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()).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);
-      for (const p of allProjects) {
-        const prs = safeJson(shared.projectPrPath(p)) || [];
-        if (prs.some(pr => (pr.prdItems || []).includes(meta.item.id) || (pr.branch && pr.branch.includes(meta.item.id)))) {
-          existingPrFound = true;
-          break;
-        }
-      }
-    }
-    // Last resort: query the platform directly for an open PR on this branch.
-    // Handles the case where a prior orphaned dispatch created a PR but the engine
-    // never processed its output — so the PR exists on the platform but not in pull-requests.json.
-    if (!existingPrFound && meta?.branch) {
-      const projectObj = shared.getProjects(config).find(p => p.name === meta?.project?.name);
-      if (projectObj) {
-        try {
-          let found = null;
-          const host = projectObj.repoHost || 'ado';
-          if (host === 'github') {
-            const ghSlug = projectObj.prUrlBase?.match(/github\.com\/([^/]+\/[^/]+)\/pull/)?.[1];
-            if (ghSlug) {
-              // 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 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 = shared.getCanonicalPrId(projectObj, found.prNumber, found.url);
-            const prPath = shared.projectPrPath(projectObj);
-            mutateJsonFileLocked(prPath, prs => {
-              if (!Array.isArray(prs)) 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',
-                status: PR_STATUS.ACTIVE, created: ts(), url: found.url,
-                prdItems: meta.item?.id ? [meta.item.id] : [],
-                sourcePlan: meta.item?.sourcePlan || '', itemType: meta.item?.itemType || '',
-              });
-              return prs;
-            });
-            log('info', `Auto-linked existing PR ${fullId} on branch ${meta.branch} for ${meta.item?.id}`);
-            existingPrFound = true;
-          }
-        } catch (e) { log('warn', `PR lookup for branch ${meta.branch}: ${e.message}`); }
-      }
-    }
-    if (!existingPrFound) {
-      const noPrWiPath = resolveWorkItemPath(meta);
-      if (noPrWiPath) {
-        const hasOutput = stdout && stdout.length > 500;
-        let action = null;
-        mutateJsonFileLocked(noPrWiPath, data => {
-          if (!Array.isArray(data)) return data;
-          const w = data.find(i => i.id === meta.item.id);
-          if (!w) return data;
-          const retries = w._retryCount || 0;
-          if (!hasOutput && retries < ENGINE_DEFAULTS.maxRetries) {
-            w.status = WI_STATUS.PENDING;
-            w._retryCount = retries + 1;
-            delete w.dispatched_at;
-            delete w.dispatched_to;
-            delete w.failReason;
-            delete w.noPr;
-            action = { type: 'retry', retries: retries + 1 };
-          } else if (hasOutput) {
-            w.status = WI_STATUS.DONE;
-            w.completedAt = ts();
-            w._noPr = true;
-            w._noPrReason = 'Agent completed without creating a PR (changes may already exist or not be needed)';
-            delete w.failReason;
-            action = { type: 'done' };
-          } else {
-            w.status = WI_STATUS.NEEDS_REVIEW;
-            w._noPr = true;
-            w.failReason = 'Completed without output or PR after ' + ENGINE_DEFAULTS.maxRetries + ' attempts';
-            action = { type: 'needs-review' };
-          }
-          return data;
-        }, { skipWriteIfUnchanged: true });
-        if (action?.type === 'retry') {
-          log('info', `Auto-retry ${action.retries}/${ENGINE_DEFAULTS.maxRetries} for ${meta.item.id} (no output, no PR)`);
-        } else if (action?.type === 'done') {
-          log('info', `${meta.item.id} completed without PR — marking done (agent produced output)`);
-        } else if (action?.type === 'needs-review') {
-          log('warn', `${meta.item.id} needs review — no output after ${ENGINE_DEFAULTS.maxRetries} retries`);
-        }
-      }
-    }
-  }
-
   // Old plan-to-prd PRD check removed — moved before updateWorkItemStatus(DONE) to fix #893
   // (retryCount was being deleted by done-marking before the check could read it)
   // Review verdict check similarly moved before updateWorkItemStatus(DONE) — same root cause.
@@ -2046,7 +2046,8 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
   checkForLearnings(agentId, config.agents[agentId], dispatchItem.task);
-  if (effectiveSuccess) {
+  const finalResult = completionContractFailure ? DISPATCH_RESULT.ERROR : (effectiveSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
+  if (finalResult === DISPATCH_RESULT.SUCCESS) {
     extractSkillsFromOutput(stdout, agentId, dispatchItem, config);
     // Also scan inbox notes for skill blocks — agents often write skills to inbox, not stdout
     try {
@@ -2061,7 +2062,6 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       }
     } catch {}
   }
-  const finalResult = effectiveSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR;
   updateAgentHistory(agentId, dispatchItem, finalResult);
   // Don't count auto-retries as errors in metrics — only count final outcomes
   const isAutoRetry = !effectiveSuccess && meta?.item?.id && (meta.item._retryCount || 0) < ENGINE_DEFAULTS.maxRetries;
@@ -2074,7 +2074,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     teams.teamsNotifyCompletion(dispatchItem, finalResult, agentId).catch(() => {});
   } catch {}
 
-  return { resultSummary, taskUsage, autoRecovered, structuredCompletion };
+  return { resultSummary, taskUsage, autoRecovered, structuredCompletion, completionContractFailure };
 }
 
 // ─── PR → PRD Status Sync ─────────────────────────────────────────────────────

package/engine/shared.js

@@ -1896,6 +1896,80 @@ function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } =
   });
 }
 
+/**
+ * Canonical PR-producing work contract helper.
+ *
+ * Dashboard rendering derives work-item PR columns from PR.prdItems (with
+ * engine/pr-links.json as a compatibility fallback). Any path that discovers or
+ * manually records a PR for a work item must use this helper so the PR record
+ * and the canonical work-item attachment are created together and idempotently.
+ */
+function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null, itemIds = null, beforeInsert = null } = {}) {
+  if (!prPath) throw new Error('prPath required');
+  if (!entry || typeof entry !== 'object') throw new Error('entry required');
+
+  const linkedItemIds = normalizePrLinkItems([
+    ...(Array.isArray(entry.prdItems) ? entry.prdItems : []),
+    ...(Array.isArray(itemIds) ? itemIds : [itemId]),
+  ]);
+  const prNumber = getPrNumber(entry.prNumber ?? entry.id ?? entry.url);
+  const canonicalId = getCanonicalPrId(project, entry.prNumber ?? entry.id ?? entry.url ?? prNumber, entry.url || '');
+  if (!canonicalId) throw new Error('PR id required');
+  const normalizedEntry = {
+    ...entry,
+    id: canonicalId,
+    prNumber: prNumber ?? entry.prNumber ?? null,
+    prdItems: linkedItemIds,
+  };
+
+  let created = false;
+  let linked = false;
+  let skipped = false;
+  let record = null;
+
+  mutatePullRequests(prPath, (prs) => {
+    normalizePrRecords(prs, project);
+    let target = findPrRecord(prs, normalizedEntry, project);
+    if (!target && typeof beforeInsert === 'function' && beforeInsert(prs, normalizedEntry) === false) {
+      skipped = true;
+      return prs;
+    }
+    if (!target) {
+      target = normalizedEntry;
+      prs.push(target);
+      created = true;
+    } else {
+      target.id = canonicalId;
+      if (prNumber != null) target.prNumber = prNumber;
+      for (const key of ['url', 'title', 'description', 'agent', 'branch', 'reviewStatus', 'status', 'created', 'sourcePlan', 'itemType']) {
+        if (normalizedEntry[key] != null && normalizedEntry[key] !== '' && (target[key] == null || target[key] === '')) {
+          target[key] = normalizedEntry[key];
+        }
+      }
+      for (const key of ['_manual', '_contextOnly', '_autoObserve', '_context']) {
+        if (normalizedEntry[key] != null) target[key] = normalizedEntry[key];
+      }
+    }
+    target.prdItems = normalizePrLinkItems(target.prdItems || []);
+    for (const linkedItemId of linkedItemIds) {
+      if (!target.prdItems.includes(linkedItemId)) {
+        target.prdItems.push(linkedItemId);
+        linked = true;
+      }
+    }
+    record = { ...target, prdItems: [...target.prdItems] };
+    return prs;
+  });
+
+  if (!skipped) {
+    for (const linkedItemId of linkedItemIds) {
+      addPrLink(canonicalId, linkedItemId, { project, prNumber, url: normalizedEntry.url || '' });
+    }
+  }
+
+  return { id: canonicalId, prNumber, created, linked, skipped, record };
+}
+
 // ─── Cross-Platform Process Kill Helpers ─────────────────────────────────────
 
 function killGracefully(proc, graceMs = 5000) {
@@ -2203,6 +2277,7 @@ module.exports = {
   findPrRecord,
   normalizePrRecord,
   normalizePrRecords,
+  upsertPullRequestRecord,
   nextWorkItemId,
   getAdoOrgBase,
   sanitizePath,

package/engine.js

@@ -1268,15 +1268,19 @@ async function spawnAgent(dispatchItem, config) {
     }
 
     // Parse output and run all post-completion hooks
-    const { resultSummary, autoRecovered } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config);
+    const { resultSummary, autoRecovered, completionContractFailure } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config);
 
     // Move from active to completed in dispatch (single source of truth for agent status)
     // autoRecovered: agent failed after creating PRs — treat as success
-    const effectiveResult = (code === 0 || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR;
-    const completeOpts = effectiveResult === DISPATCH_RESULT.ERROR && failureClass ? { failureClass } : {};
+    const effectiveResult = completionContractFailure ? DISPATCH_RESULT.ERROR : ((code === 0 || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
+    const completeOpts = completionContractFailure
+      ? { processWorkItemFailure: false }
+      : (effectiveResult === DISPATCH_RESULT.ERROR && failureClass ? { failureClass } : {});
     // Extract last 5 non-empty stderr lines as error context when exit code is non-zero
     let errorReason = '';
-    if (effectiveResult === DISPATCH_RESULT.ERROR) {
+    if (completionContractFailure) {
+      errorReason = completionContractFailure.reason || 'PR attachment contract failed';
+    } else if (effectiveResult === DISPATCH_RESULT.ERROR) {
       errorReason = stderr.split('\n').filter(l => l.trim()).slice(-5).join(' | ').trim().slice(0, 300);
       // W-mo3zul9pirjb — when claude CLI exits in <3s with code 1 and no output (the
       // "silent crash" pattern seen during scheduled tasks when the box went to sleep
@@ -1982,56 +1986,99 @@ function clearPendingHumanFeedbackFlag(projectMeta, prId) {
 
 const PR_PENDING_MISSING_BRANCH = 'missing_pr_branch';
 
-function getPrDispatchBranch(pr) {
-  return typeof pr?.branch === 'string' ? pr.branch.trim() : '';
+function normalizePrBranch(value) {
+  const raw = value == null ? '' : String(value).trim();
+  if (!raw) return '';
+  return raw.replace(/^refs\/heads\//i, '');
 }
 
-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 resolvePrBranch(pr) {
+  if (!pr || typeof pr !== 'object') return '';
+  const candidates = [
+    pr.branch,
+    pr.pr_branch,
+    pr.prBranch,
+    pr.sourceRefName,
+    pr.sourceBranch,
+    pr.sourceRef,
+    pr.headRefName,
+    pr.head?.ref,
+  ];
+  for (const candidate of candidates) {
+    const branch = normalizePrBranch(candidate);
+    if (branch) return branch;
+  }
+  return '';
 }
 
-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) {
+// Unified branch-resolution state writer: when branch is found, persist it and
+// clear BOTH the structured _branchResolutionError (red-badge UI) and the
+// _pendingReason marker (dashboard pending-reason vocabulary). When branch is
+// missing, set BOTH fields so the dashboard can surface the gate via either
+// rendering path.
+function updatePrBranchResolutionState(project, pr, { branch = '', reason = '' } = {}) {
+  let changed = false;
+  try {
+    mutatePullRequests(projectPrPath(project), prs => {
+      const target = shared.findPrRecord(prs, pr, project);
+      if (!target) return;
+      if (branch) {
+        if (target.branch !== branch) {
+          target.branch = branch;
+          changed = true;
+        }
+        if (target._branchResolutionError) {
+          delete target._branchResolutionError;
+          changed = true;
+        }
+        if (target._pendingReason === PR_PENDING_MISSING_BRANCH) {
+          delete target._pendingReason;
+          changed = true;
+        }
+        return;
+      }
+      if (reason) {
+        const currentReason = target._branchResolutionError?.reason || '';
+        if (currentReason !== reason) {
+          target._branchResolutionError = { reason, at: ts() };
+          changed = true;
+        }
+        if (target._pendingReason !== PR_PENDING_MISSING_BRANCH) {
+          target._pendingReason = PR_PENDING_MISSING_BRANCH;
+          changed = true;
+        }
+      }
+    });
+  } catch (e) {
+    log('warn', `mark PR branch resolution state for ${pr?.id || 'unknown PR'}: ${e.message}`);
+  }
+  if (branch) {
+    pr.branch = branch;
+    if (pr._branchResolutionError) delete pr._branchResolutionError;
+    if (pr._pendingReason === PR_PENDING_MISSING_BRANCH) delete pr._pendingReason;
+  } else if (reason && changed) {
+    pr._branchResolutionError = { reason, at: ts() };
     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;
+function ensurePrBranchForDispatch(project, pr, automationType) {
+  const branch = resolvePrBranch(pr);
+  if (branch) {
+    if (pr.branch !== branch || pr._branchResolutionError || pr._pendingReason === PR_PENDING_MISSING_BRANCH) {
+      updatePrBranchResolutionState(project, pr, { branch });
+    }
+    return branch;
+  }
+  const reason = `Cannot dispatch ${automationType} for ${shared.getPrDisplayId(pr)}: missing pr_branch/source branch metadata. Link or refresh the PR so the source branch is known.`;
+  if (updatePrBranchResolutionState(project, pr, { reason })) {
+    log('warn', `PR ${pr.id}: ${reason}`);
   }
-  markPrMissingBranch(project, pr, action);
-  return false;
+  return '';
 }
 
+
 /**
  * Scan pull-requests.json for PRs needing review or fixes
  */
@@ -2073,10 +2120,10 @@ 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);
+    const prBranchForMutex = resolvePrBranch(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`);
+    if (prBranchForMutex && isBranchActive(prBranchForMutex)) {
+      log('info', `Branch mutex: skipping PR ${pr.id} dispatch — branch ${prBranchForMutex} locked by another agent`);
       continue;
     }
     // Skip human-authored PRs not linked to any work item — only auto-manage agent PRs
@@ -2114,7 +2161,6 @@ 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 {
@@ -2139,11 +2185,13 @@ async function discoverFromPrs(config, project) {
 
       const agentId = resolveAgent('review', config);
       if (!agentId) continue;
+      const prBranch = ensurePrBranchForDispatch(project, pr, 'review');
+      if (!prBranch) continue;
 
       const item = buildPrDispatch(agentId, config, project, pr, 'review', {
-        pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: pr.branch || '',
+        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, source: 'pr', pr, branch: pr.branch, project: projMeta });
+      }, `Review ${pr.id}: ${pr.title}`, { dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta });
       if (item) { newWork.push(item); }
     }
 
@@ -2158,7 +2206,6 @@ 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 {
@@ -2181,11 +2228,13 @@ async function discoverFromPrs(config, project) {
 
       const agentId = resolveAgent('review', config);
       if (!agentId) continue;
+      const prBranch = ensurePrBranchForDispatch(project, pr, 're-review');
+      if (!prBranch) continue;
 
       const item = buildPrDispatch(agentId, config, project, pr, 'review', {
-        pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: pr.branch || '',
+        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, source: 'pr', pr, branch: pr.branch, project: projMeta });
+      }, `Review ${pr.id}: ${pr.title}`, { dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta });
       if (item) { newWork.push(item); }
     }
 
@@ -2195,14 +2244,15 @@ 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;
+      const prBranch = ensurePrBranchForDispatch(project, pr, 'fix');
+      if (!prBranch) continue;
 
       const item = buildPrDispatch(agentId, config, project, pr, 'fix', {
-        pr_id: pr.id, pr_branch: pr.branch || '',
+        pr_id: pr.id, pr_branch: prBranch,
         review_note: pr.minionsReview?.note || pr.reviewNote || 'See PR thread comments',
-      }, `Fix ${pr.id}: ${pr.title || ''} — review feedback`, { dispatchKey: key, source: 'pr', pr, branch: pr.branch, project: projMeta });
+      }, `Fix ${pr.id}: ${pr.title || ''} — review feedback`, { dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta });
       if (item) {
         newWork.push(item); setCooldown(key); fixDispatched = true;
         // Increment review→fix cycle counter
@@ -2235,9 +2285,10 @@ 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;
+      const prBranch = ensurePrBranchForDispatch(project, pr, 'human-feedback fix');
+      if (!prBranch) continue;
 
       const coalesced = [...staleCoalesced, ...getCoalescedContexts(key)];
       let reviewNote = pr.humanFeedback.feedbackContent || 'See PR thread comments';
@@ -2247,10 +2298,10 @@ async function discoverFromPrs(config, project) {
       }
 
       const item = buildPrDispatch(agentId, config, project, pr, 'fix', {
-        pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: pr.branch || '',
+        pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: prBranch,
         reviewer: 'Human Reviewer',
         review_note: reviewNote,
-      }, `Fix ${pr.id}: ${pr.title || ''} — human feedback`, { dispatchKey: key, source: 'pr-human-feedback', pr, branch: pr.branch, project: projMeta });
+      }, `Fix ${pr.id}: ${pr.title || ''} — human feedback`, { dispatchKey: key, source: 'pr-human-feedback', pr, branch: prBranch, project: projMeta });
       if (item) { newWork.push(item); fixDispatched = true; }
     }
 
@@ -2283,7 +2334,6 @@ 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
@@ -2319,6 +2369,8 @@ async function discoverFromPrs(config, project) {
 
       const agentId = resolveAgent('fix', config, { authorAgent: pr.agent });
       if (!agentId) continue;
+      const prBranch = ensurePrBranchForDispatch(project, pr, 'build-fix');
+      if (!prBranch) continue;
 
       let reviewNote = `Build is failing: ${pr.buildFailReason || 'Check CI pipeline for details'}. Fix the build errors and push.`;
       if (pr.buildErrorLog) {
@@ -2326,9 +2378,9 @@ async function discoverFromPrs(config, project) {
       }
 
       const item = buildPrDispatch(agentId, config, project, pr, 'fix', {
-        pr_id: pr.id, pr_branch: pr.branch || '',
+        pr_id: pr.id, pr_branch: prBranch,
         review_note: reviewNote,
-      }, `Fix build failure on ${pr.id}: ${pr.title || ''}`, { dispatchKey: key, source: 'pr', pr, branch: pr.branch, project: projMeta });
+      }, `Fix build failure on ${pr.id}: ${pr.title || ''}`, { dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta });
       if (item) {
         newWork.push(item); setCooldown(key); fixDispatched = true;
         // Increment build fix attempts counter
@@ -2368,7 +2420,6 @@ 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
@@ -2395,10 +2446,12 @@ async function discoverFromPrs(config, project) {
         if (!liveSkip) {
           const agentId = resolveAgent('fix', config, { authorAgent: pr.agent });
           if (agentId) {
+            const prBranch = ensurePrBranchForDispatch(project, pr, 'conflict-fix');
+            if (!prBranch) continue;
             const item = buildPrDispatch(agentId, config, project, pr, 'fix', {
-              pr_id: pr.id, pr_branch: pr.branch || '',
+              pr_id: pr.id, pr_branch: prBranch,
               review_note: `This PR has merge conflicts with the target branch. Resolve the conflicts:\n\n1. Pull latest from main/master\n2. Resolve all conflicts (prefer PR branch changes unless main has critical fixes)\n3. Build and test after resolving\n4. Push the resolved branch`,
-            }, `Fix merge conflicts on ${pr.id}: ${pr.title || ''}`, { dispatchKey: key, source: 'pr', pr, branch: pr.branch, project: projMeta });
+            }, `Fix merge conflicts on ${pr.id}: ${pr.title || ''}`, { dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta });
             if (item) {
               newWork.push(item);
               setCooldown(key);

package/package.json

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