@yemi33/minions 0.1.1664 → 0.1.1666

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1666 (2026-05-01)
+
+### Other
+- Fix soft routing for fix dispatches
+
 ## 0.1.1664 (2026-05-01)
 
 ### Features

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-01T19:29:49.074Z"
+  "cachedAt": "2026-05-01T20:53:59.616Z"
 }

package/engine/lifecycle.js

@@ -1752,20 +1752,67 @@ function parseStructuredCompletion(stdout, runtimeName) {
   while ((m = blockPattern.exec(text)) !== null) {
     lastMatch = m[1];
   }
-  if (!lastMatch) return null;
+  if (!lastMatch) {
+    const taskCompleteSummary = extractTaskCompleteSummary(stdout);
+    return taskCompleteSummary ? parseCompletionKeyValues(taskCompleteSummary) : null;
+  }
+
+  return parseCompletionKeyValues(lastMatch);
+}
+
+function extractTaskCompleteSummary(stdout) {
+  if (!stdout || typeof stdout !== 'string') return '';
+  let summary = '';
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || !line.startsWith('{')) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    if (!obj || typeof obj !== 'object') continue;
+    if (obj.type === 'session.task_complete') {
+      const value = obj.data?.summary;
+      if (typeof value === 'string' && value.trim()) summary = value;
+      continue;
+    }
+    if (obj.type === 'tool.execution_start' && obj.data?.toolName === 'task_complete') {
+      const value = obj.data?.arguments?.summary;
+      if (typeof value === 'string' && value.trim()) summary = value;
+      continue;
+    }
+    if (obj.type === 'assistant.message' && Array.isArray(obj.data?.toolRequests)) {
+      for (const tr of obj.data.toolRequests) {
+        if (tr?.name !== 'task_complete') continue;
+        const value = tr.arguments?.summary || tr.intentionSummary;
+        if (typeof value === 'string' && value.trim()) summary = value;
+      }
+    }
+  }
+  return summary;
+}
+
+function hasActionableFailureClass(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return false;
+  return !['n/a', 'na', 'none', 'null', 'no', 'false', 'not-applicable'].includes(normalized);
+}
 
-  // Parse key: value pairs
+function parseCompletionKeyValues(text) {
+  if (!text || typeof text !== 'string') return null;
   const result = {};
-  const lines = lastMatch.trim().split('\n');
+  const allowedFields = new Set(shared.COMPLETION_FIELDS || []);
+  const lines = text.trim().split('\n');
   for (const line of lines) {
-    const colonIdx = line.indexOf(':');
+    const normalizedLine = line.trim().replace(/^[-*]\s+/, '');
+    const colonIdx = normalizedLine.indexOf(':');
     if (colonIdx < 1) continue;
-    const key = line.slice(0, colonIdx).trim().toLowerCase();
-    const value = line.slice(colonIdx + 1).trim();
+    const key = normalizedLine.slice(0, colonIdx).trim().toLowerCase();
+    if (allowedFields.size > 0 && !allowedFields.has(key)) continue;
+    const value = normalizedLine.slice(colonIdx + 1).trim();
     if (key && value) result[key] = value;
   }
 
-  // Must have at least the status field to be valid
+  // Must have at least status, or an actionable failure_class that implies failure.
+  if (!result.status && hasActionableFailureClass(result.failure_class)) result.status = 'failed';
   if (!result.status) return null;
   return result;
 }
@@ -2102,7 +2149,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 
   const completionStatus = normalizeCompletionStatus(structuredCompletion?.status);
   const agentNeedsRerun = parseCompletionBoolean(structuredCompletion?.needs_rerun ?? structuredCompletion?.needsRerun) === true;
-  const agentReportedFailure = completionStatus.startsWith('fail') || agentNeedsRerun;
+  const agentReportedFailure = completionStatus.startsWith('fail')
+    || completionStatus === 'error'
+    || hasActionableFailureClass(structuredCompletion?.failure_class)
+    || agentNeedsRerun;
   const agentRetryable = parseCompletionBoolean(structuredCompletion?.retryable);
 
   // Auto-recover: if a failed implement/fix/test agent created PRs, it likely succeeded before the failure surfaced.
@@ -2114,8 +2164,8 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const effectiveSuccess = (isSuccess && !agentReportedFailure) || autoRecovered;
 
   let nonCleanReportWritten = false;
-  if (completionStatus.startsWith('partial') || autoRecovered || (completionStatus.startsWith('fail') && isSuccess)) {
-    const outcome = completionStatus.startsWith('fail') ? 'failure' : 'partial';
+  if (completionStatus.startsWith('partial') || autoRecovered || (agentReportedFailure && isSuccess)) {
+    const outcome = agentReportedFailure ? 'failure' : 'partial';
     writeNonCleanAgentReport(dispatchItem, agentId, outcome, structuredCompletion, completionGateSummary, code);
     nonCleanReportWritten = true;
   }
@@ -2347,7 +2397,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // Review verdict check similarly moved before updateWorkItemStatus(DONE) — same root cause.
 
   if (type === WORK_TYPE.REVIEW) await updatePrAfterReview(agentId, meta?.pr, meta?.project, config, resultSummary, structuredCompletion);
-  if (type === WORK_TYPE.FIX) {
+  if (type === WORK_TYPE.FIX && effectiveSuccess) {
     updatePrAfterFix(meta?.pr, meta?.project, meta?.source);
     // (#984) Sync PRD status for PR-linked features: fix work items have a different ID
     // than the original PRD feature, so syncPrdItemStatus(fixWiId, ...) finds nothing.

package/engine/routing.js

@@ -13,6 +13,7 @@ const { ENGINE_DIR, DISPATCH_PATH } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
 const ROUTING_PATH = path.join(MINIONS_DIR, 'routing.md');
+const ANY_AGENT = '_any_';
 
 // ─── Temp Agents ─────────────────────────────────────────────────────────────
 
@@ -124,7 +125,7 @@ function normalizeWorkType(workType, fallback = WORK_TYPE.IMPLEMENT) {
 
 function routeForWorkType(workType) {
   const routes = getRoutingTableCached();
-  return routes[normalizeWorkType(workType)] || routes[WORK_TYPE.IMPLEMENT] || { preferred: '_any_', fallback: '_any_' };
+  return routes[normalizeWorkType(workType)] || routes[WORK_TYPE.IMPLEMENT] || { preferred: ANY_AGENT, fallback: ANY_AGENT };
 }
 
 function isAgentHardPinned(item) {
@@ -224,10 +225,10 @@ function resolveAgent(workType, config, opts = {}) {
   }
 
   // Resolve _any_ token — pick any available agent (#480)
-  if (preferred === '_any_') { const pick = pickAnyIdle(); if (pick) return pick; }
+  if (preferred === ANY_AGENT) { const pick = pickAnyIdle(); if (pick) return pick; }
   else if (preferred && isAvailable(preferred)) { _claimedAgents.add(preferred); return preferred; }
 
-  if (fallback === '_any_') { const pick = pickAnyIdle([preferred]); if (pick) return pick; }
+  if (fallback === ANY_AGENT) { const pick = pickAnyIdle([preferred]); if (pick) return pick; }
   else if (fallback && isAvailable(fallback)) { _claimedAgents.add(fallback); return fallback; }
 
   // Fall back to any idle agent, preferring lower error rates
@@ -268,7 +269,7 @@ function resolveAgentReservation(workType, config, opts = {}) {
     const budget = agents[id].monthlyBudgetUsd;
     return !(budget && budget > 0 && getMonthlySpend(id) >= budget);
   };
-  const eligible = (id) => (id && id !== '_any_' && hasBudget(id)) ? id : null;
+  const eligible = (id) => (id && id !== ANY_AGENT && hasBudget(id)) ? id : null;
   const anyEligible = (exclude = []) => {
     const excludeSet = new Set(exclude.filter(Boolean));
     return Object.keys(agents)
@@ -281,11 +282,11 @@ function resolveAgentReservation(workType, config, opts = {}) {
   const preferred = route.preferred === '_author_' ? authorAgent : route.preferred;
   const fallback = route.fallback === '_author_' ? authorAgent : route.fallback;
 
-  if (preferred === '_any_') return anyEligible();
+  if (preferred === ANY_AGENT) return anyEligible();
   const preferredAgent = eligible(preferred);
   if (preferredAgent) return preferredAgent;
 
-  if (fallback === '_any_') return anyEligible([preferred]);
+  if (fallback === ANY_AGENT) return anyEligible([preferred]);
   const fallbackAgent = eligible(fallback);
   if (fallbackAgent) return fallbackAgent;
 
@@ -305,6 +306,7 @@ module.exports = {
   isAgentHardPinned,
   getHardPinnedAgent,
   normalizeWorkType,
+  ANY_AGENT,
   _claimedAgents,
   resetClaimedAgents,
   resolveAgent,

package/engine/timeout.js

@@ -194,6 +194,29 @@ function isOsPidAliveForDispatch(itemId) {
   catch { return false; }
 }
 
+function readFileTail(filePath, maxBytes) {
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const stat = fs.fstatSync(fd);
+    const tailSize = Math.min(stat.size, maxBytes);
+    const buf = Buffer.alloc(tailSize);
+    fs.readSync(fd, buf, 0, tailSize, Math.max(0, stat.size - tailSize));
+    return buf.toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function parseProcessExitCode(logText) {
+  if (!logText) return null;
+  const exitPattern = /(?:^|\n)\[process-exit\]\s+(?:code=)?(-?\d+|spawn-failed)(?=\s|$)/g;
+  let lastMatch = null;
+  let m;
+  while ((m = exitPattern.exec(logText)) !== null) lastMatch = m;
+  if (!lastMatch) return null;
+  return lastMatch[1] === 'spawn-failed' ? -1 : parseInt(lastMatch[1], 10);
+}
+
 function checkTimeouts(config) {
   const activeProcesses = engine().activeProcesses;
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
@@ -225,6 +248,45 @@ function checkTimeouts(config) {
   const deadItems = [];
   const legacyAnnotationClears = new Set();
 
+  function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess) {
+    const isSuccess = processExitCode === 0;
+    log('info', `Agent ${item.agent} (${item.id}) completed via output detection (exit code ${processExitCode}, ${isSuccess ? 'success' : 'error'})`);
+
+    // Extract output text for the output.log — read full file for complete parsing
+    const outputLogPath = path.join(AGENTS_DIR, item.agent, 'output.log');
+    try {
+      const fullLog = safeRead(liveLogPath) || detectedLogText;
+      const { text } = shared.parseStreamJsonOutput(fullLog);
+      safeWrite(outputLogPath, `# Output for dispatch ${item.id}\n# Exit code: ${processExitCode}\n# Completed: ${ts()}\n# Detected via output scan\n\n## Result\n${text || '(no text)'}\n`);
+    } catch (e) { log('warn', 'parse output result: ' + e.message); }
+
+    const fullLogForHooks = safeRead(liveLogPath) || detectedLogText;
+    let completionDetection = null;
+    let outputResultSummary = '';
+    try {
+      const runtimeName = item.meta?.runtimeName || item.runtimeName || 'claude';
+      outputResultSummary = parseAgentOutput(fullLogForHooks, runtimeName).resultSummary || '';
+      const gateSummary = outputResultSummary || (!fullLogForHooks.includes('"type":') ? fullLogForHooks : '');
+      completionDetection = isSuccess
+        ? detectNonTerminalResultSummary(gateSummary, parseStructuredCompletion(fullLogForHooks, runtimeName), parseCompletionReportFile(item))
+        : null;
+    } catch (e) { log('warn', 'completion summary gate: ' + e.message); }
+
+    completeDispatch(item.id, completionDetection ? DISPATCH_RESULT.ERROR : (isSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR),
+      completionDetection ? completionDetection.reason : (isSuccess ? 'Completed (detected from output)' : `Exited with code ${processExitCode} (detected from output)`),
+      outputResultSummary,
+      completionDetection ? { processWorkItemFailure: false } : {});
+
+    // Run post-completion hooks via shared helper (async — fire and forget in timeout context).
+    // Pass the actual exit code so autoRecovery (PR-created-but-failed) still works correctly.
+    runPostCompletionHooks(item, item.agent, processExitCode, fullLogForHooks, config).catch(e => log('warn', 'post-completion hooks: ' + e.message));
+
+    if (hasProcess) {
+      shared.killImmediate(activeProcesses.get(item.id)?.proc);
+      activeProcesses.delete(item.id);
+    }
+  }
+
   for (const item of (dispatchData.active || [])) {
     if (!item.agent) continue;
 
@@ -265,75 +327,21 @@ function checkTimeouts(config) {
     //
     // We tail 64KB — process-exit is always the last non-empty line of the file.
     // No time cap: a stuck dispatch whose process has exited must always be detected (#716).
-    let completedViaOutput = false;
+    // completedViaOutput detection is gated on a [process-exit] code=N sentinel;
+    // a "type":"result" event alone can race engine.js's close handler (#1792).
     try {
       let liveLogTail;
       try {
-        const fd = fs.openSync(liveLogPath, 'r');
-        try {
-          const stat = fs.fstatSync(fd);
-          const TAIL_SIZE = 65536; // 64KB
-          const tailSize = Math.min(stat.size, TAIL_SIZE);
-          const buf = Buffer.alloc(tailSize);
-          fs.readSync(fd, buf, 0, tailSize, Math.max(0, stat.size - tailSize));
-          liveLogTail = buf.toString('utf8');
-        } finally { fs.closeSync(fd); }
+        liveLogTail = readFileTail(liveLogPath, 65536); // 64KB
       } catch { /* ENOENT or read failure — liveLogTail stays undefined */ }
 
       // Parse the LAST [process-exit] sentinel — code=N or "spawn-failed".
       // Use the global regex with a manual loop so we always pick up the latest occurrence,
       // not the first (defends against logs that somehow contain stale sentinel lines).
-      let processExited = false;
-      let processExitCode = null;
-      if (liveLogTail) {
-        const exitPattern = /\n\[process-exit\]\s+(?:code=)?(-?\d+|spawn-failed)/g;
-        let lastMatch = null;
-        let m;
-        while ((m = exitPattern.exec(liveLogTail)) !== null) lastMatch = m;
-        if (lastMatch) {
-          processExited = true;
-          processExitCode = lastMatch[1] === 'spawn-failed' ? -1 : parseInt(lastMatch[1], 10);
-        }
-      }
-
-      if (processExited) {
-        completedViaOutput = true;
-        const isSuccess = processExitCode === 0;
-        log('info', `Agent ${item.agent} (${item.id}) completed via output detection (exit code ${processExitCode}, ${isSuccess ? 'success' : 'error'})`);
+      const processExitCode = parseProcessExitCode(liveLogTail);
 
-        // Extract output text for the output.log — read full file for complete parsing
-        const outputLogPath = path.join(AGENTS_DIR, item.agent, 'output.log');
-        try {
-          const fullLog = safeRead(liveLogPath) || liveLogTail;
-          const { text } = shared.parseStreamJsonOutput(fullLog);
-          safeWrite(outputLogPath, `# Output for dispatch ${item.id}\n# Exit code: ${processExitCode}\n# Completed: ${ts()}\n# Detected via output scan\n\n## Result\n${text || '(no text)'}\n`);
-        } catch (e) { log('warn', 'parse output result: ' + e.message); }
-
-        const fullLogForHooks = safeRead(liveLogPath) || liveLogTail;
-        let completionDetection = null;
-        let outputResultSummary = '';
-        try {
-          const runtimeName = item.meta?.runtimeName || item.runtimeName || 'claude';
-          outputResultSummary = parseAgentOutput(fullLogForHooks, runtimeName).resultSummary || '';
-          const gateSummary = outputResultSummary || (!fullLogForHooks.includes('"type":') ? fullLogForHooks : '');
-          completionDetection = isSuccess
-            ? detectNonTerminalResultSummary(gateSummary, parseStructuredCompletion(fullLogForHooks, runtimeName), parseCompletionReportFile(item))
-            : null;
-        } catch (e) { log('warn', 'completion summary gate: ' + e.message); }
-
-        completeDispatch(item.id, completionDetection ? DISPATCH_RESULT.ERROR : (isSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR),
-          completionDetection ? completionDetection.reason : (isSuccess ? 'Completed (detected from output)' : `Exited with code ${processExitCode} (detected from output)`),
-          outputResultSummary,
-          completionDetection ? { processWorkItemFailure: false } : {});
-
-        // Run post-completion hooks via shared helper (async — fire and forget in timeout context).
-        // Pass the actual exit code so autoRecovery (PR-created-but-failed) still works correctly.
-        runPostCompletionHooks(item, item.agent, processExitCode, fullLogForHooks, config).catch(e => log('warn', 'post-completion hooks: ' + e.message));
-
-        if (hasProcess) {
-          shared.killImmediate(activeProcesses.get(item.id)?.proc);
-          activeProcesses.delete(item.id);
-        }
+      if (processExitCode !== null) {
+        completeFromOutput(item, liveLogPath, processExitCode, liveLogTail, hasProcess);
         continue; // Skip orphan/hung detection — we handled it
       }
       // Note: we DO NOT trigger on `"type":"result"` alone. There is a ~1s race between
@@ -392,8 +400,21 @@ function checkTimeouts(config) {
         log('info', `Orphan check: ${item.agent} (${item.id}) silent ${silentSec}s but OS PID is alive — keeping [${_logState}]`);
         continue;
       }
+      // Final safety scan: the normal 64KB tail scan can miss a clean exit if
+      // later runtime payloads or diagnostics push the sentinel outside the tail.
+      // Before declaring an orphan, inspect the full log and route terminal exits
+      // through the same completion path.
+      try {
+        const fullLog = safeRead(liveLogPath);
+        const processExitCode = parseProcessExitCode(fullLog);
+        if (processExitCode !== null) {
+          completeFromOutput(item, liveLogPath, processExitCode, fullLog, hasProcess);
+          continue;
+        }
+      } catch (e) { log('warn', 'orphan final output completion scan: ' + e.message); }
+
       // No tracked process AND no recent output past stale-orphan timeout AND (grace period expired OR confirmed-dead at restart) → orphaned
-      log('warn', `Orphan detected: ${item.agent} (${item.id}) — no live process tracked, silent for ${silentSec}s [${_logState}]`);
+      log('warn', `Orphan detected: ${item.agent} (${item.id}) — no live process tracked, silent for ${silentSec}s [logExists/logSize=${_logState}]`);
       dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, `Orphaned — no process, silent for ${silentSec}s`);
       // Clear session so retry starts fresh
       try { shared.safeUnlink(path.join(AGENTS_DIR, item.agent, 'session.json')); } catch {}

package/engine.js

@@ -1365,8 +1365,13 @@ async function spawnAgent(dispatchItem, config) {
     let errorReason = '';
     if (hardContractFail) {
       errorReason = completionContractFailure.reason || 'PR attachment contract failed';
-    } else if (agentReportedFailure && structuredCompletion?.summary) {
-      errorReason = String(structuredCompletion.summary).slice(0, 300);
+    } else if (agentReportedFailure && structuredCompletion) {
+      errorReason = String(
+        structuredCompletion.summary
+        || structuredCompletion.pending
+        || structuredCompletion.failure_class
+        || `Agent reported ${structuredCompletion.status || 'failure'}`
+      ).slice(0, 300);
     } 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
@@ -2563,6 +2568,73 @@ async function discoverFromPrs(config, project) {
 /**
  * Scan work-items.json for manually queued tasks
  */
+function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, project, root, branchName) {
+  const vars = {
+    ...buildBaseVars(agentId, config, project),
+    item_id: item.id,
+    item_name: item.title || item.id,
+    item_priority: item.priority || 'medium',
+    item_description: item.description || '',
+    item_complexity: item.complexity || item.estimated_complexity || 'medium',
+    task_description: item.title + (item.description ? '\n\n' + item.description : ''),
+    task_id: item.id,
+    work_type: workType,
+    source_plan: item.sourcePlan || '',
+    plan_slug: (item.sourcePlan || '').replace('.json', ''),
+    additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
+    scope_section: `## Scope: Project — ${project?.name || 'default'}\n\nThis task is scoped to a single project.`,
+    branch_name: branchName,
+    project_path: root,
+    worktree_path: path.resolve(root, config.engine?.worktreeRoot || '../worktrees', `${branchName}`),
+    commit_message: item.commitMessage || `feat: ${item.title || item.id}`,
+    notes_content: '',
+  };
+  const cpResult = buildWorkItemDispatchVars(item, vars, config, {
+    worktreePath: vars.worktree_path || root,
+    workType,
+  });
+  if (cpResult.needsReview) {
+    return { needsReview: true, checkpointCount: cpResult.checkpointCount, prompt: null };
+  }
+
+  const playbookName = selectPlaybook(workType, item);
+  if (playbookName === 'work-item' && workType === WORK_TYPE.REVIEW) {
+    log('info', `Work item ${item.id} is type "review" but has no PR — using work-item playbook`);
+  }
+  return {
+    needsReview: false,
+    checkpointCount: cpResult.checkpointCount,
+    prompt: item.prompt || renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars) || item.description,
+  };
+}
+
+function projectFromDispatchMeta(metaProject, config) {
+  if (!metaProject) return null;
+  const projects = getProjects(config);
+  if (metaProject.name) {
+    const byName = projects.find(p => p.name === metaProject.name);
+    if (byName) return byName;
+  }
+  if (metaProject.localPath) {
+    const refPath = path.resolve(metaProject.localPath);
+    const byPath = projects.find(p => p.localPath && path.resolve(p.localPath) === refPath);
+    if (byPath) return byPath;
+  }
+  return metaProject;
+}
+
+function refreshDeferredWorkItemPrompt(item, config) {
+  if (!item?.meta?.deferAgentResolution || item.meta.source !== 'work-item' || !item.meta.item) return;
+  if (!item.agent || item.agent === routing.ANY_AGENT) return;
+  const project = projectFromDispatchMeta(item.meta.project, config);
+  const root = project?.localPath ? path.resolve(project.localPath) : path.resolve(MINIONS_DIR, '..');
+  const workType = routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT);
+  const branchName = item.meta.branch || item.meta.item.branch || `work/${item.meta.item.id}`;
+  const rendered = renderProjectWorkItemPromptForAgent(item.meta.item, workType, item.agent, config, project, root, branchName);
+  if (rendered.prompt) item.prompt = rendered.prompt;
+  item.meta.deferAgentResolution = false;
+}
+
 function discoverFromWorkItems(config, project) {
   const src = project?.workSources?.workItems || config.workSources?.workItems;
   if (!src?.enabled) return [];
@@ -2670,17 +2742,20 @@ function discoverFromWorkItems(config, project) {
       needsWrite = true;
     }
     const agentHints = routing.extractAgentHints(item);
+    const hasAgentHints = Array.isArray(agentHints) && agentHints.length > 0;
     const hardPinRequested = routing.isAgentHardPinned(item);
     let agentId = routing.getHardPinnedAgent(item, config.agents || {})
       || (!hardPinRequested ? resolveAgent(workType, config, { agentHints }) : null);
+    let reservedAgentId = agentId;
     const cfgAgents = config.agents || {};
     const budgetBlocked = Object.keys(cfgAgents).some(id => {
       const b = cfgAgents[id].monthlyBudgetUsd;
       return b && b > 0 && getMonthlySpend(id) >= b && isAgentIdle(id);
     });
     if (!agentId) {
-      if (!budgetBlocked && !hardPinRequested) {
-        agentId = resolveAgentReservation(workType, config, { agentHints });
+      if (!budgetBlocked && !hardPinRequested && workType !== WORK_TYPE.FIX) {
+        reservedAgentId = resolveAgentReservation(workType, config, { agentHints });
+        agentId = reservedAgentId && !hasAgentHints ? routing.ANY_AGENT : reservedAgentId;
       }
       if (agentId) {
         delete item._pendingReason;
@@ -2698,6 +2773,7 @@ function discoverFromWorkItems(config, project) {
 
     const isShared = item.branchStrategy === 'shared-branch' && item.featureBranch;
     const branchName = isShared ? item.featureBranch : (item.branch || `work/${item.id}`);
+    const deferredAgentResolution = agentId === routing.ANY_AGENT;
 
     // Branch mutex: skip if target branch is locked by an active dispatch
     const branchConflict = isBranchActive(branchName);
@@ -2708,50 +2784,23 @@ function discoverFromWorkItems(config, project) {
       continue;
     }
 
-    const vars = {
-      ...buildBaseVars(agentId, config, project),
-      item_id: item.id,
-      item_name: item.title || item.id,
-      item_priority: item.priority || 'medium',
-      item_description: item.description || '',
-      item_complexity: item.complexity || item.estimated_complexity || 'medium',
-      task_description: item.title + (item.description ? '\n\n' + item.description : ''),
-      task_id: item.id,
-      work_type: workType,
-      source_plan: item.sourcePlan || '',
-      plan_slug: (item.sourcePlan || '').replace('.json', ''),
-      additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
-      scope_section: `## Scope: Project — ${project?.name || 'default'}\n\nThis task is scoped to a single project.`,
-      branch_name: branchName,
-      project_path: root,
-      worktree_path: path.resolve(root, config.engine?.worktreeRoot || '../worktrees', `${branchName}`),
-      commit_message: item.commitMessage || `feat: ${item.title || item.id}`,
-      notes_content: '',
-    };
-    // Build common vars: references, acceptance criteria, checkpoint, notes, task context
-    const cpResult = buildWorkItemDispatchVars(item, vars, config, {
-      worktreePath: vars.worktree_path || root,
-      workType,
-    });
-    if (cpResult.needsReview) {
+    const promptAgentId = deferredAgentResolution ? reservedAgentId : agentId;
+    const promptResult = renderProjectWorkItemPromptForAgent(item, workType, promptAgentId, config, project, root, branchName);
+    if (promptResult.needsReview) {
       log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
       item.status = WI_STATUS.NEEDS_REVIEW;
-      item._checkpointCount = cpResult.checkpointCount;
+      item._checkpointCount = promptResult.checkpointCount;
       needsWrite = true;
       continue;
     }
-    if (cpResult.checkpointCount !== null) {
-      item._checkpointCount = cpResult.checkpointCount;
+    if (promptResult.checkpointCount !== null) {
+      item._checkpointCount = promptResult.checkpointCount;
       needsWrite = true;
     }
 
-    const playbookName = selectPlaybook(workType, item);
-    if (playbookName === 'work-item' && workType === WORK_TYPE.REVIEW) {
-      log('info', `Work item ${item.id} is type "review" but has no PR — using work-item playbook`);
-    }
-    const prompt = item.prompt || renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars) || item.description;
+    const prompt = promptResult.prompt;
     if (!prompt) {
-      log('warn', `No playbook rendered for ${item.id} (type: ${workType}, playbook: ${playbookName}) — skipping`);
+      log('warn', `No playbook rendered for ${item.id} (type: ${workType}) — skipping`);
       continue;
     }
 
@@ -2768,7 +2817,7 @@ function discoverFromWorkItems(config, project) {
       agentRole: config.agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent',
       task: `[${project?.name || 'project'}] ${item.title || item.description?.slice(0, 80) || item.id}`,
       prompt,
-      meta: { dispatchKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(item.branchStrategy === 'shared-branch' && item.featureBranch), item, project: { name: project?.name, localPath: project?.localPath } }
+      meta: { dispatchKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(item.branchStrategy === 'shared-branch' && item.featureBranch), item, project: { name: project?.name, localPath: project?.localPath }, deferAgentResolution: deferredAgentResolution }
     });
 
     setCooldown(key);
@@ -3204,7 +3253,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;
@@ -3512,6 +3561,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;
@@ -3872,33 +3977,51 @@ async function tickInner() {
       log('warn', `Duplicate dispatch ID ${item.id} in pending queue — skipping`);
       continue;
     }
+    if (item.agent === routing.ANY_AGENT) {
+      const routedAgent = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config, { agentHints: routing.extractAgentHints(item.meta?.item) });
+      if (!routedAgent) {
+        log('debug', `Pending dispatch ${item.id} is waiting for any available agent`);
+        continue;
+      }
+      item.agent = routedAgent;
+      item.agentName = config.agents[routedAgent]?.name || tempAgents.get(routedAgent)?.name || routedAgent;
+      item.agentRole = config.agents[routedAgent]?.role || tempAgents.get(routedAgent)?.role || 'Agent';
+      delete item._agentBusySince;
+      delete item.skipReason;
+      refreshDeferredWorkItemPrompt(item, config);
+      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;
+            p.prompt = item.prompt;
+            if (item.meta) p.meta = item.meta;
+            delete p._agentBusySince;
+            delete p.skipReason;
+          }
+          return dp;
+        });
+      } catch (e) { log('warn', `Persist any-agent resolution for ${item.id} failed: ${e.message}`); }
+    }
     // #1206: Guard against undefined/non-string item.agent. A corrupted dispatch
     // entry (manual edit, serialization round-trip, cleared field) would otherwise
     // be handed to spawnAgent, which crashes with `TypeError: "path" argument must
     // 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.
@@ -3909,27 +4032,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)) {
@@ -3937,30 +4046,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.1664",
+  "version": "0.1.1666",
   "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"