@yemi33/minions 0.1.1665 → 0.1.1667

package/CHANGELOG.md

@@ -1,15 +1,20 @@
 # Changelog
 
-## 0.1.1665 (2026-05-01)
+## 0.1.1667 (2026-05-01)
+
+### Other
+- Harden PR attachment completion handling
+
+## 0.1.1666 (2026-05-01)
+
+### Other
+- Fix soft routing for fix dispatches
+
+## 0.1.1664 (2026-05-01)
 
 ### Features
-- treat failed task_complete as dispatch failure (#1954)
 - prevent duplicate PR fix dispatch (#1953)
 
-### Fixes
-- pre-dispatch agent starvation when only one agent is idle (closes #1940) (#1956)
--  Engine clean-exit agent runs incorrectly marked Orphaned/silent (#1955)
-
 ## 0.1.1662 (2026-05-01)
 
 ### Other

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-01T19:30:38.180Z"
+  "cachedAt": "2026-05-01T21:02:29.699Z"
 }

package/engine/lifecycle.js

@@ -943,7 +943,8 @@ function isPrAttachmentRequired(type, item, meta = {}) {
     || item.prRequired === true
     || item.requiresPullRequest === true
     || item.itemType === 'pr';
-  if (meta.branchStrategy === 'shared-branch' && item.itemType !== 'pr' && !explicit) return false;
+  const branchStrategy = meta.branchStrategy || item.branchStrategy;
+  if (branchStrategy === 'shared-branch' && item.itemType !== 'pr' && !explicit) return false;
 
   // Fix/test work items dispatched against an existing PR don't produce a new
   // PR — the agent updates meta.pr in place. Only require fresh PR attachment
@@ -960,21 +961,144 @@ function isPrAttachmentRequired(type, item, meta = {}) {
     || type === WORK_TYPE.TEST;
 }
 
+function readOptionalJsonStrict(filePath, label, validate) {
+  if (!filePath) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw new Error(`Cannot read ${label} JSON at ${filePath}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Corrupt ${label} JSON at ${filePath}: ${err.message}`);
+  }
+  if (validate && !validate(parsed)) {
+    throw new Error(`Invalid ${label} JSON shape at ${filePath}`);
+  }
+  return parsed;
+}
+
 function hasCanonicalPrAttachment(itemId, config) {
   if (!itemId) return false;
+  // Cheapest probe first — getPrLinks() is in-process cached and merges canonical IDs.
   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)) || [];
+    const prs = readOptionalJsonStrict(shared.projectPrPath(p), 'project pull-requests', Array.isArray) || [];
     if (prs.some(pr => (pr.prdItems || []).includes(itemId))) return true;
   }
-  const centralPrs = safeJson(path.join(MINIONS_DIR, 'pull-requests.json')) || [];
+  const centralPrs = readOptionalJsonStrict(path.join(MINIONS_DIR, 'pull-requests.json'), 'central pull-requests', Array.isArray) || [];
   return centralPrs.some(pr => (pr.prdItems || []).includes(itemId));
 }
 
+function resolvePrFallbackProject(meta, config) {
+  const projects = shared.getProjects(config);
+  if (meta?.project?.name) {
+    const match = projects.find(p => p.name === meta.project.name);
+    if (match) return match;
+  }
+  if (meta?.project?.localPath) {
+    const metaPath = path.resolve(meta.project.localPath);
+    const match = projects.find(p => p.localPath && path.resolve(p.localPath) === metaPath);
+    if (match) return match;
+  }
+  if (meta?.item?.project) {
+    const match = projects.find(p => p.name === meta.item.project);
+    if (match) return match;
+  }
+  return projects.length === 1 ? projects[0] : null;
+}
+
+function runFileCapture(file, args, opts = {}) {
+  const { timeout = 30000, ...spawnOpts } = opts;
+  const MAX_BUFFER = 4 * 1024 * 1024; // 4MB — generous for gh/git output
+  return new Promise((resolve, reject) => {
+    let child;
+    let settled = false;
+    let timedOut = false;
+    let killedForBuffer = false;
+    let stdout = '';
+    let stderr = '';
+    let hardKillTimer = null;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (hardKillTimer) clearTimeout(hardKillTimer);
+      fn(value);
+    };
+    const timer = timeout ? setTimeout(() => {
+      timedOut = true;
+      if (!child) return;
+      shared.killGracefully(child, 1000);
+      // Hard-kill fallback if the child ignores SIGTERM. Cleared on close.
+      hardKillTimer = setTimeout(() => {
+        try { shared.killImmediate(child); } catch {}
+      }, 2500);
+    }, timeout) : null;
+    try {
+      child = shared.runFile(file, args, { ...spawnOpts, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      finish(reject, err);
+      return;
+    }
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', chunk => {
+      if (stdout.length + chunk.length > MAX_BUFFER) {
+        if (!killedForBuffer) { killedForBuffer = true; try { shared.killImmediate(child); } catch {} }
+        return;
+      }
+      stdout += chunk;
+    });
+    child.stderr?.on('data', chunk => {
+      if (stderr.length + chunk.length > MAX_BUFFER) {
+        if (!killedForBuffer) { killedForBuffer = true; try { shared.killImmediate(child); } catch {} }
+        return;
+      }
+      stderr += chunk;
+    });
+    child.on('error', err => {
+      err.stdout = stdout;
+      err.stderr = stderr;
+      finish(reject, err);
+    });
+    child.once('close', () => {
+      if (hardKillTimer) { clearTimeout(hardKillTimer); hardKillTimer = null; }
+    });
+    child.on('close', code => {
+      if (code === 0 && !timedOut && !killedForBuffer) {
+        finish(resolve, stdout);
+        return;
+      }
+      let message;
+      let errCode;
+      if (timedOut) {
+        message = `${file} timed out after ${timeout}ms`;
+        errCode = 'ETIMEDOUT';
+      } else if (killedForBuffer) {
+        message = `${file} exceeded max buffer of ${MAX_BUFFER} bytes`;
+        errCode = 'ERR_OUT_OF_RANGE';
+      } else {
+        message = `${file} exited with code ${code}`;
+        errCode = code;
+      }
+      const err = new Error(message);
+      err.code = errCode;
+      err.stdout = stdout;
+      err.stderr = stderr;
+      finish(reject, err);
+    });
+  });
+}
+
 async function findOpenPrForBranch(meta, config) {
   if (!meta?.branch) return null;
-  const projectObj = shared.getProjects(config).find(p => p.name === meta?.project?.name);
+  const projectObj = resolvePrFallbackProject(meta, config);
   if (!projectObj) return null;
   const host = projectObj.repoHost || 'ado';
   if (host === 'github') {
@@ -984,7 +1108,7 @@ async function findOpenPrForBranch(meta, config) {
       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 });
+        raw = await runFileCapture('gh', ['pr', 'list', '--head', String(meta.branch), '--repo', ghSlug, '--json', 'number,url,state', '--limit', '1'], { timeout: 15000 });
         const parsed = JSON.parse(raw || '[]');
         const hits = Array.isArray(parsed) ? parsed : [];
         if (hits.length > 0 && hits[0].state === 'OPEN') {
@@ -1024,6 +1148,7 @@ function _outputContainsPrUrl(output) {
 function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity) {
   const noPrWiPath = resolveWorkItemPath(meta);
   const isHard = severity !== 'soft';
+  let syncNeedsReviewToPrd = false;
   if (noPrWiPath) {
     mutateJsonFileLocked(noPrWiPath, data => {
       if (!Array.isArray(data)) return data;
@@ -1034,6 +1159,7 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity)
         w._missingPrAttachment = true;
         w.failReason = reason;
         w._lastReviewReason = reason;
+        syncNeedsReviewToPrd = !!meta.item?.sourcePlan;
         delete w.completedAt;
         delete w._noPr;
         delete w._noPrReason;
@@ -1047,6 +1173,9 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity)
       return data;
     }, { skipWriteIfUnchanged: true });
   }
+  if (isHard && syncNeedsReviewToPrd) {
+    syncPrdItemStatus(meta.item.id, WI_STATUS.NEEDS_REVIEW, meta.item.sourcePlan);
+  }
   if (isHard) {
     shared.writeToInbox('engine', `missing-pr-attachment-${meta.item.id}`,
       `# PR attachment missing for ${meta.item.id}\n\n` +
@@ -1075,9 +1204,50 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity)
   }
 }
 
+function markPrAttachmentVerificationError(meta, agentId, reason, resultSummary) {
+  const wiPath = resolveWorkItemPath(meta);
+  let syncNeedsReviewToPrd = false;
+  if (wiPath) {
+    mutateJsonFileLocked(wiPath, 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._prAttachmentStateError = true;
+      w.failReason = reason;
+      w._lastReviewReason = reason;
+      syncNeedsReviewToPrd = !!meta.item?.sourcePlan;
+      delete w.completedAt;
+      delete w._missingPrAttachment;
+      delete w._unverifiedPrAttachment;
+      return data;
+    }, { skipWriteIfUnchanged: true });
+  }
+  if (syncNeedsReviewToPrd) {
+    syncPrdItemStatus(meta.item.id, WI_STATUS.NEEDS_REVIEW, meta.item.sourcePlan);
+  }
+  shared.writeToInbox('engine', `pr-attachment-state-error-${meta.item.id}`,
+    `# PR attachment verification blocked 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: 'pr-attachment-state-error' });
+}
+
 async function enforcePrAttachmentContract(type, meta, agentId, config, resultSummary, output) {
   if (!isPrAttachmentRequired(type, meta?.item, meta)) return null;
-  if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
+  try {
+    if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
+  } catch (err) {
+    const reason = `${meta.item.id} completed but PR attachment verification could not read PR tracking state: ${err.message}`;
+    markPrAttachmentVerificationError(meta, agentId, reason, resultSummary);
+    log('warn', reason);
+    return { reason, itemId: meta.item.id, severity: 'hard', stateError: true };
+  }
 
   const found = await findOpenPrForBranch(meta, config);
   if (found) {
@@ -1100,7 +1270,14 @@ async function enforcePrAttachmentContract(type, meta, agentId, config, resultSu
       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;
+    try {
+      if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
+    } catch (err) {
+      const reason = `${meta.item.id} auto-linked a PR but PR attachment verification could not read PR tracking state: ${err.message}`;
+      markPrAttachmentVerificationError(meta, agentId, reason, resultSummary);
+      log('warn', reason);
+      return { reason, itemId: meta.item.id, severity: 'hard', stateError: true };
+    }
   }
 
   // Distinguish "agent never claimed a PR" (hard — silent failure the contract
@@ -1737,13 +1914,7 @@ function parseStructuredCompletion(stdout, runtimeName) {
   if (!stdout || typeof stdout !== 'string') return null;
 
   // Extract text from stream-json output if needed
-  let text = stdout;
-  if (stdout.includes('"type":')) {
-    try {
-      const parsed = shared.parseStreamJsonOutput(stdout, runtimeName);
-      if (parsed.text) text = parsed.text;
-    } catch {}
-  }
+  const text = extractCompletionText(stdout, runtimeName);
 
   // Find all ```completion blocks, take the last one
   const blockPattern = /```completion\s*\n([\s\S]*?)```/g;
@@ -1760,6 +1931,22 @@ function parseStructuredCompletion(stdout, runtimeName) {
   return parseCompletionKeyValues(lastMatch);
 }
 
+function extractCompletionText(stdout, runtimeName) {
+  let text = stdout;
+  if (typeof stdout === 'string' && stdout.includes('"type":')) {
+    try {
+      const parsed = shared.parseStreamJsonOutput(stdout, runtimeName);
+      if (parsed.text) text = parsed.text;
+    } catch {}
+  }
+  return text;
+}
+
+function hasCompletionFence(stdout, runtimeName) {
+  const text = extractCompletionText(stdout, runtimeName);
+  return /```completion\s*\n[\s\S]*?```/.test(text);
+}
+
 function extractTaskCompleteSummary(stdout) {
   if (!stdout || typeof stdout !== 'string') return '';
   let summary = '';
@@ -1817,6 +2004,29 @@ function parseCompletionKeyValues(text) {
   return result;
 }
 
+function parseCompletionFieldSummary(text) {
+  if (!text || typeof text !== 'string') return null;
+
+  const allowedFields = new Set(shared.COMPLETION_FIELDS || []);
+  const result = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim().replace(/^[-*]\s+/, '');
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 1) continue;
+    const key = line.slice(0, colonIdx).trim().toLowerCase().replace(/[\s-]+/g, '_');
+    if (!allowedFields.has(key)) continue;
+    const value = line.slice(colonIdx + 1).trim().replace(/^["'`]+|["'`]+$/g, '');
+    if (value) result[key] = value;
+  }
+
+  if (!result.status) return null;
+  const fieldCount = Object.keys(result).length;
+  const status = normalizeCompletionStatus(result.status);
+  const explicitlyFailed = status.startsWith('fail') || status === 'error';
+  if (fieldCount < 2 && !explicitlyFailed) return null;
+  return result;
+}
+
 function parseCompletionReportFile(dispatchItem, opts = {}) {
   const reportPath = dispatchItem?.meta?.completionReportPath || shared.dispatchCompletionReportPath(dispatchItem?.id);
   if (!reportPath || !fs.existsSync(reportPath)) {
@@ -1875,10 +2085,11 @@ function normalizeCompletionStatus(status) {
 // and burned 3-9 minutes of agent time per false-positive retry.
 //
 // Both structured signals (the JSON completion report at MINIONS_COMPLETION_REPORT
-// and the fenced ```completion block in stdout) carry a `status` field. If the
-// agent explicitly says they're not done, honor it; otherwise accept the
-// dispatch. The PR attachment contract still catches silent-failure cases
-// for PR-producing work.
+// and the fenced ```completion block in stdout) carry a `status` field. A plain
+// task_complete summary made only of completion fields is accepted as a narrow
+// compatibility fallback. If the agent explicitly says they're not done, honor
+// it; otherwise accept the dispatch. The PR attachment contract still catches
+// silent-failure cases for PR-producing work.
 const NON_TERMINAL_COMPLETION_STATUSES = new Set([
   'partial', 'partially-complete', 'in-progress', 'pending', 'deferred',
   'blocked', 'incomplete', 'to-be-continued',
@@ -2110,8 +2321,11 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 
   // Prefer the sidecar completion report; keep fenced output as a compatibility fallback.
   const reportCompletion = parseCompletionReportFile(dispatchItem, { warnIfMissing: true });
-  const fallbackCompletion = reportCompletion ? null : parseStructuredCompletion(stdout, runtimeName);
-  const structuredCompletion = reportCompletion || persistCompletionReport(dispatchItem, fallbackCompletion, 'fenced-completion');
+  const fencedCompletion = reportCompletion ? null : parseStructuredCompletion(stdout, runtimeName);
+  const summaryCompletion = reportCompletion || fencedCompletion ? null : parseCompletionFieldSummary(resultSummary);
+  const fallbackCompletion = fencedCompletion || summaryCompletion;
+  const fallbackSource = fencedCompletion && hasCompletionFence(stdout, runtimeName) ? 'fenced-completion' : 'summary-completion';
+  const structuredCompletion = reportCompletion || persistCompletionReport(dispatchItem, fallbackCompletion, fallbackSource);
   if (structuredCompletion) {
     if (structuredCompletion.summary) resultSummary = String(structuredCompletion.summary);
     log('info', `Structured completion from ${agentId}: status=${structuredCompletion.status}, pr=${structuredCompletion.pr || 'N/A'}${structuredCompletion._source ? ` (${structuredCompletion._source})` : ''}`);
@@ -2625,6 +2839,7 @@ module.exports = {
   parseReviewVerdict,
   isReviewBailout,
   parseStructuredCompletion,
+  parseCompletionFieldSummary,
   detectNonTerminalResultSummary,
   parseCompletionReportFile,
   persistCompletionReport,

package/engine.js

@@ -1365,13 +1365,15 @@ async function spawnAgent(dispatchItem, config) {
     let errorReason = '';
     if (hardContractFail) {
       errorReason = completionContractFailure.reason || 'PR attachment contract failed';
-    } else if (agentReportedFailure && structuredCompletion) {
-      errorReason = String(
-        structuredCompletion.summary
-        || structuredCompletion.pending
-        || structuredCompletion.failure_class
-        || `Agent reported ${structuredCompletion.status || 'failure'}`
-      ).slice(0, 300);
+    } else if (agentReportedFailure) {
+      errorReason = structuredCompletion
+        ? String(
+            structuredCompletion.summary
+            || structuredCompletion.pending
+            || structuredCompletion.failure_class
+            || `Agent reported ${structuredCompletion.status || 'failure'}`
+          ).slice(0, 300)
+        : 'Agent reported failure';
     } 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
@@ -2753,7 +2755,7 @@ function discoverFromWorkItems(config, project) {
       return b && b > 0 && getMonthlySpend(id) >= b && isAgentIdle(id);
     });
     if (!agentId) {
-      if (!budgetBlocked && !hardPinRequested) {
+      if (!budgetBlocked && !hardPinRequested && workType !== WORK_TYPE.FIX) {
         reservedAgentId = resolveAgentReservation(workType, config, { agentHints });
         agentId = reservedAgentId && !hasAgentHints ? routing.ANY_AGENT : reservedAgentId;
       }
@@ -3253,7 +3255,7 @@ function discoverCentralWorkItems(config) {
       const hardPinRequested = routing.isAgentHardPinned(item);
       const agentId = routing.getHardPinnedAgent(item, config.agents || {})
         || (!hardPinRequested ? resolveAgent(workType, config, { agentHints }) : null)
-        || (!hardPinRequested ? resolveAgentReservation(workType, config, { agentHints }) : null);
+        || (!hardPinRequested && workType !== WORK_TYPE.FIX ? resolveAgentReservation(workType, config, { agentHints }) : null);
       if (!agentId) continue;
 
       const agentName = config.agents[agentId]?.name || agentId;
@@ -3561,6 +3563,62 @@ async function discoverWork(config) {
   return allWork.length;
 }
 
+function getPendingDispatchRoutingOpts(item) {
+  const opts = { agentHints: routing.extractAgentHints(item?.meta?.item) };
+  const authorAgent = item?.meta?.pr?.agent;
+  if (authorAgent) opts.authorAgent = authorAgent;
+  return opts;
+}
+
+function resolvePendingDispatchAgent(item, config) {
+  return resolveAgent(
+    routing.normalizeWorkType(item?.type, WORK_TYPE.IMPLEMENT),
+    config,
+    getPendingDispatchRoutingOpts(item)
+  );
+}
+
+function assignPendingDispatchAgent(item, agentId, config) {
+  const agents = config.agents || {};
+  item.agent = agentId;
+  item.agentName = agents[agentId]?.name || tempAgents.get(agentId)?.name || agentId;
+  item.agentRole = agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent';
+  delete item._agentBusySince;
+  delete item.skipReason;
+}
+
+function clearPendingDispatchAgent(item) {
+  delete item.agent;
+  delete item.agentName;
+  delete item.agentRole;
+  delete item._agentBusySince;
+  delete item.skipReason;
+}
+
+function persistPendingDispatchAgent(item) {
+  mutateDispatch((dp) => {
+    const p = (dp.pending || []).find(d => d.id === item.id);
+    if (p) {
+      if (item.agent) {
+        p.agent = item.agent;
+        p.agentName = item.agentName;
+        p.agentRole = item.agentRole;
+      } else {
+        delete p.agent;
+        delete p.agentName;
+        delete p.agentRole;
+      }
+      delete p._agentBusySince;
+      delete p.skipReason;
+    }
+    return dp;
+  });
+}
+
+function isSoftFixDispatch(item) {
+  return item?.type === WORK_TYPE.FIX && !routing.isAgentHardPinned(item.meta?.item);
+}
+
 // ─── Main Tick ──────────────────────────────────────────────────────────────
 
 let tickCount = 0;
@@ -3955,27 +4013,17 @@ async function tickInner() {
     // be of type string. Received undefined` and re-queues — every tick. Try to
     // resolve a fallback via routing; if none is available, skip this tick.
     if (!item.agent || typeof item.agent !== 'string') {
-      const fallback = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config, { agentHints: routing.extractAgentHints(item.meta?.item) });
+      const fallback = resolvePendingDispatchAgent(item, config);
       if (!fallback) {
         log('warn', `Pending dispatch ${item.id} has no agent and routing returned no fallback — skipping`);
         continue;
       }
       log('info', `Pending dispatch ${item.id} missing agent; routed → ${fallback} (#1206 guard)`);
-      item.agent = fallback;
-      item.agentName = config.agents[fallback]?.name || tempAgents.get(fallback)?.name || fallback;
-      item.agentRole = config.agents[fallback]?.role || tempAgents.get(fallback)?.role || 'Agent';
+      assignPendingDispatchAgent(item, fallback, config);
       // Persist so the fix survives across ticks even if this dispatch is skipped
       // later in the loop (branch lock, concurrency cap, agent busy, etc.).
       try {
-        mutateDispatch((dp) => {
-          const p = (dp.pending || []).find(d => d.id === item.id);
-          if (p) {
-            p.agent = item.agent;
-            p.agentName = item.agentName;
-            p.agentRole = item.agentRole;
-          }
-          return dp;
-        });
+        persistPendingDispatchAgent(item);
       } catch (e) { log('warn', `Persist agent resolution for ${item.id} failed: ${e.message}`); }
     }
     // #1204: Pre-assigned unspawned temp agents never unblock naturally.
@@ -3986,27 +4034,13 @@ async function tickInner() {
     // them eagerly before the busy check so an idle named agent can pick up.
     const isUnspawnedTemp = item.agent?.startsWith('temp-') && !busyAgents.has(item.agent);
     if (isUnspawnedTemp) {
-      const altAgent = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config);
+      const altAgent = resolvePendingDispatchAgent(item, config);
       if (altAgent && altAgent !== item.agent) {
         const prevAgent = item.agent;
-        item.agent = altAgent;
-        item.agentName = config.agents[altAgent]?.name || tempAgents.get(altAgent)?.name || altAgent;
-        item.agentRole = config.agents[altAgent]?.role || tempAgents.get(altAgent)?.role || 'Agent';
-        delete item._agentBusySince;
-        delete item.skipReason;
+        assignPendingDispatchAgent(item, altAgent, config);
         log('info', `Reassigning ${item.id} from unspawned temp ${prevAgent} to ${altAgent} — temp agent never spawned`);
         // Persist reassignment to dispatch.json so it survives restarts/ticks
-        mutateDispatch((dp) => {
-          const p = (dp.pending || []).find(d => d.id === item.id);
-          if (p) {
-            p.agent = altAgent;
-            p.agentName = item.agentName;
-            p.agentRole = item.agentRole;
-            delete p._agentBusySince;
-            delete p.skipReason;
-          }
-          return dp;
-        });
+        persistPendingDispatchAgent(item);
       }
     }
     if (busyAgents.has(item.agent)) {
@@ -4014,30 +4048,30 @@ async function tickInner() {
       // try to find an alternative agent via routing. Skip explicitly assigned items.
       const reassignMs = config.engine?.agentBusyReassignMs ?? ENGINE_DEFAULTS.agentBusyReassignMs;
       const isHardPinned = routing.isAgentHardPinned(item.meta?.item);
-      if (!isHardPinned && reassignMs > 0 && item._agentBusySince) {
+      if (isSoftFixDispatch(item)) {
+        const originalAgent = item.agent;
+        const altAgent = resolvePendingDispatchAgent(item, config);
+        if (altAgent && altAgent !== originalAgent && !busyAgents.has(altAgent)) {
+          log('info', `Reassigning ${item.id} from ${originalAgent} to ${altAgent} — soft fix suggestion unavailable`);
+          assignPendingDispatchAgent(item, altAgent, config);
+          persistPendingDispatchAgent(item);
+          // Fall through to branch mutex / concurrency checks below.
+        } else {
+          log('info', `Clearing busy soft fix agent on ${item.id} (${originalAgent}) — waiting for any available agent`);
+          clearPendingDispatchAgent(item);
+          persistPendingDispatchAgent(item);
+          continue;
+        }
+      } else if (!isHardPinned && reassignMs > 0 && item._agentBusySince) {
         const busySinceMs = new Date(item._agentBusySince).getTime();
         if (Date.now() - busySinceMs > reassignMs) {
           const originalAgent = item.agent;
-          const altAgent = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config, { agentHints: routing.extractAgentHints(item.meta?.item) });
+          const altAgent = resolvePendingDispatchAgent(item, config);
           if (altAgent && altAgent !== originalAgent && !busyAgents.has(altAgent)) {
             log('info', `Reassigning ${item.id} from ${originalAgent} to ${altAgent} — agent busy > ${reassignMs}ms`);
-            item.agent = altAgent;
-            item.agentName = config.agents[altAgent]?.name || tempAgents.get(altAgent)?.name || altAgent;
-            item.agentRole = config.agents[altAgent]?.role || tempAgents.get(altAgent)?.role || 'Agent';
-            delete item._agentBusySince;
-            delete item.skipReason;
+            assignPendingDispatchAgent(item, altAgent, config);
             // Persist reassignment to dispatch.json
-            mutateDispatch((dp) => {
-              const p = (dp.pending || []).find(d => d.id === item.id);
-              if (p) {
-                p.agent = altAgent;
-                p.agentName = item.agentName;
-                p.agentRole = item.agentRole;
-                delete p._agentBusySince;
-                delete p.skipReason;
-              }
-              return dp;
-            });
+            persistPendingDispatchAgent(item);
             // Fall through to branch mutex / concurrency checks below
           } else {
             continue; // No alternative agent available — keep waiting

package/package.json

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