@yemi33/minions 0.1.1656 → 0.1.1658

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Changelog
 
-## 0.1.1656 (2026-05-01)
+## 0.1.1658 (2026-05-01)
+
+### Fixes
+- trust structured completion status, drop prose regex
+
+### Other
+- Fix soft routing hints
+
+## 0.1.1657 (2026-05-01)
+
+### Other
+- Fix dispatch dedupe and routing starvation
+
+## 0.1.1655 (2026-05-01)
 
 ### Features
 - ADO manual PR link metadata and branch race
-- gate non-terminal task completions
 
 ## 0.1.1654 (2026-05-01)
 

package/dashboard.js

@@ -31,7 +31,7 @@ const dispatchMod = require('./engine/dispatch');
 const steering = require('./engine/steering');
 const os = require('os');
 
-const { safeRead, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeUnlink, mutateJsonFileLocked, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, reopenWorkItem } = shared;
+const { safeRead, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeUnlink, mutateJsonFileLocked, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, reopenWorkItem } = shared;
 const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
   getSkills, getInbox, getNotesWithMeta, getPullRequests,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, timeSince,
@@ -1392,7 +1392,7 @@ async function executeCCActions(actions) {
     try {
       switch (action.type) {
         case 'dispatch': case 'fix': case 'implement': case 'explore': case 'review': case 'test': {
-          const workType = action.workType || (action.type !== 'dispatch' ? action.type : 'implement');
+          const workType = routing.normalizeWorkType(action.workType || (action.type !== 'dispatch' ? action.type : WORK_TYPE.IMPLEMENT), WORK_TYPE.IMPLEMENT);
           const id = 'W-' + shared.uid();
           const project = action.project || '';
 
@@ -2733,22 +2733,19 @@ const server = http.createServer(async (req, res) => {
       }
       const id = 'W-' + shared.uid();
       const item = {
-        id, title: body.title.trim(), type: body.type || 'implement',
+        id, title: body.title.trim(), type: routing.normalizeWorkType(body.type, WORK_TYPE.IMPLEMENT),
         priority: body.priority || 'medium', description: body.description || '',
         status: WI_STATUS.PENDING, created: new Date().toISOString(), createdBy: 'dashboard',
       };
       if (body.scope) item.scope = body.scope;
-      // Agent assignment normalization: when the caller (CC, dashboard form,
-      // direct API) supplies a single explicit agent — either via `agent`
-      // (singular) or a one-element `agents` array — treat it as a HARD pin
-      // by setting `item.agent`. The engine reads `item.agent || resolveAgent(…)`,
-      // so a hard-pinned item bypasses routing entirely and queues until that
-      // exact agent is free. Multi-agent arrays remain `item.agents` (hints
-      // for resolveAgent or fan-out scope).
+      // Agent assignment normalization: `agent` and `agents` are routing hints.
+      // Use agentLock/hardAgent only for the rare case where an item must wait
+      // for one exact agent instead of falling through to another idle agent.
       const _agentsArr = Array.isArray(body.agents) ? body.agents.filter(Boolean) : (typeof body.agents === 'string' && body.agents ? [body.agents] : []);
       if (body.agent) item.agent = String(body.agent);
       else if (_agentsArr.length === 1 && body.scope !== 'fan-out') item.agent = String(_agentsArr[0]);
       if (_agentsArr.length > 0) item.agents = _agentsArr;
+      if (body.agentLock === true || body.hardAgent === true) item.agentLock = true;
       if (body.references) item.references = body.references;
       if (body.acceptanceCriteria) item.acceptanceCriteria = body.acceptanceCriteria;
       if (body.skipPr) item.skipPr = true;

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-01T04:21:06.784Z"
+  "cachedAt": "2026-05-01T05:22:39.907Z"
 }

package/engine/dispatch.js

@@ -12,7 +12,7 @@ const { setCooldownFailure } = require('./cooldown');
 const { safeJson, safeWrite, safeReadDir, mutateJsonFileLocked, mutateWorkItems,
   mutatePullRequests, getProjects, projectWorkItemsPath, projectPrPath, log, ts, dateStamp,
   sidecarDispatchPrompt, deleteDispatchPromptSidecar,
-  WI_STATUS, DISPATCH_RESULT, ENGINE_DEFAULTS, AGENT_STATUS, FAILURE_CLASS, PR_STATUS } = shared;
+  WI_STATUS, WORK_TYPE, DISPATCH_RESULT, ENGINE_DEFAULTS, AGENT_STATUS, FAILURE_CLASS, PR_STATUS } = shared;
 const { getConfig, getDispatch, DISPATCH_PATH, INBOX_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -59,8 +59,20 @@ function mutateDispatch(mutator) {
 
 // ─── Add to Dispatch ─────────────────────────────────────────────────────────
 
+function getPrDispatchDedupeKey(entry) {
+  if (!entry?.meta?.pr || !entry?.meta?.project || !entry?.type) return null;
+  const type = entry.type === WORK_TYPE.FIX ? WORK_TYPE.FIX : entry.type;
+  const project = entry.meta.project;
+  const projectKey = project.name
+    || (project.localPath ? path.resolve(project.localPath).toLowerCase() : '');
+  if (!projectKey) return null;
+  const prKey = shared.getCanonicalPrId(project, entry.meta.pr, entry.meta.pr?.url || '');
+  if (!prKey) return null;
+  return `${projectKey}:${type}:${prKey}`;
+}
+
 function addToDispatch(item) {
-  item.id = item.id || `${item.agent}-${item.type}-${shared.uid()}`;
+  item.id = item.id || `${item.agent || 'unassigned'}-${item.type}-${shared.uid()}`;
   item.created_at = ts();
   item.meta = item.meta && typeof item.meta === 'object' ? item.meta : {};
   if (!item.meta.completionReportPath) {
@@ -69,7 +81,7 @@ function addToDispatch(item) {
   let added = false;
   mutateDispatch((dispatch) => {
     // Dedup: skip if same work item ID is already pending or active
-    const wiId = item.meta?.item?.id;
+    const wiId = item.meta?.source === 'central-work-item-fanout' ? null : item.meta?.item?.id;
     if (wiId) {
       const existing = [...dispatch.pending, ...(dispatch.active || [])].find(d => d.meta?.item?.id === wiId);
       if (existing) {
@@ -85,6 +97,15 @@ function addToDispatch(item) {
         return dispatch;
       }
     }
+    const prDedupeKey = getPrDispatchDedupeKey(item);
+    if (prDedupeKey) {
+      const existing = [...dispatch.pending, ...(dispatch.active || [])]
+        .find(d => getPrDispatchDedupeKey(d) === prDedupeKey);
+      if (existing) {
+        log('info', `Dedup: skipping ${item.id} — PR dispatch ${prDedupeKey} already in ${existing.id}`);
+        return dispatch;
+      }
+    }
     dispatch.pending.push(item);
     added = true;
     return dispatch;
@@ -568,6 +589,7 @@ function cancelPendingWorkItems(wiPath, matchFn, reason) {
 module.exports = {
   mutateDispatch,
   addToDispatch,
+  getPrDispatchDedupeKey,
   isRetryableFailureReason,
   completeDispatch,
   writeInboxAlert,

package/engine/lifecycle.js

@@ -1820,70 +1820,39 @@ function normalizeCompletionStatus(status) {
   return String(status || '').trim().toLowerCase().replace(/[\s_]+/g, '-');
 }
 
-function isTerminalPendingValue(value) {
-  const text = String(value || '').trim().toLowerCase();
-  if (!text) return true;
-  return /^(?:none|n\/a|na|no|nothing|not-applicable|not applicable|-)$/.test(text)
-    || /^no\s+(?:pending|remaining|outstanding)\b/.test(text)
-    || /^(?:all\s+)?(?:pending|remaining|outstanding)\s+(?:work|items?|tasks?)?\s*(?:resolved|complete|completed|done|closed)$/.test(text);
-}
-
-function isTerminalPendingLine(line) {
-  const text = String(line || '').trim().toLowerCase();
-  return /\bno\s+pending\b/.test(text)
-    || /\bpending\s*[:=-]\s*(?:none|n\/a|na|no|nothing|not applicable|-)\b/.test(text)
-    || /\bpending\s+(?:work|items?|tasks?)?\s*(?:resolved|complete|completed|done|closed)\b/.test(text);
-}
-
-function detectNonTerminalResultSummary(resultSummary, structuredCompletion) {
-  const completionStatus = normalizeCompletionStatus(structuredCompletion?.status);
-  if (completionStatus) {
-    if (/^(?:partial|partially-complete|in-progress|pending|deferred|blocked|incomplete|to-be-continued)/.test(completionStatus)) {
+// Trust the agent's explicit structured `status` field as the only signal that
+// a completion is non-terminal. Earlier versions also scanned the agent's
+// resultSummary prose with regex (looking for "pending", "in progress",
+// "partial", "wake up", etc.), but that produced false positives on benign
+// phrases like "I checked the pending PRs" or "build is in progress on CI"
+// 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.
+const NON_TERMINAL_COMPLETION_STATUSES = new Set([
+  'partial', 'partially-complete', 'in-progress', 'pending', 'deferred',
+  'blocked', 'incomplete', 'to-be-continued',
+  'failed', 'failure', 'error',
+]);
+
+function detectNonTerminalResultSummary(_resultSummary, structuredCompletion, completionReport) {
+  const candidates = [completionReport?.status, structuredCompletion?.status];
+  for (const status of candidates) {
+    const norm = normalizeCompletionStatus(status);
+    if (!norm) continue;
+    if (NON_TERMINAL_COMPLETION_STATUSES.has(norm)) {
+      const isFailure = norm === 'failed' || norm === 'failure' || norm === 'error';
       return {
-        phrase: `status:${structuredCompletion.status}`,
-        reason: `Nonterminal completion summary: structured status is '${structuredCompletion.status}'`,
+        phrase: `status:${status}`,
+        reason: isFailure
+          ? `Nonterminal completion summary: structured status is '${status}', not a successful terminal state`
+          : `Nonterminal completion summary: structured status is '${status}'`,
       };
     }
-    if (/^(?:fail|failed|failure|error)/.test(completionStatus)) {
-      return {
-        phrase: `status:${structuredCompletion.status}`,
-        reason: `Nonterminal completion summary: structured status is '${structuredCompletion.status}', not a successful terminal state`,
-      };
-    }
-  }
-
-  if (structuredCompletion?.pending && !isTerminalPendingValue(structuredCompletion.pending)) {
-    return {
-      phrase: 'pending',
-      reason: `Nonterminal completion summary: pending work remains (${String(structuredCompletion.pending).slice(0, 160)})`,
-    };
   }
-
-  const text = String(resultSummary || '').replace(/\r/g, '').trim();
-  if (!text) return null;
-
-  const patterns = [
-    { phrase: 'still running', re: /\b(?:still|currently|continues?\s+to\s+be)\s+(?:running|ongoing|in\s+progress)\b/i },
-    { phrase: 'will check later', re: /\b(?:i(?:'|’)ll|i\s+will|we(?:'|’)ll|we\s+will|will)\s+(?:check|verify|review|follow\s+up|revisit)\s+(?:again\s+)?(?:later|soon|in\b|after\b|when\b)/i },
-    { phrase: 'wake up', re: /\bwake(?:\s|-)?up\b|\bwake\b.*\b(?:check|verify|review)\b/i },
-    { phrase: 'not yet complete', re: /\b(?:not\s+yet|isn(?:'|’)t|not|incomplete|not\s+fully|not\s+completely)\s+(?:complete|completed|done|finished|validated|verified)\b/i },
-    { phrase: 'partial', re: /\bpartial(?:ly)?\b/i },
-    { phrase: 'to be continued', re: /\bto\s+be\s+continued\b|\btbc\b/i },
-    { phrase: 'in progress', re: /\bin\s+progress\b|\bongoing\b|\bincomplete\b/i },
-  ];
-  for (const { phrase, re } of patterns) {
-    if (re.test(text)) {
-      return { phrase, reason: `Nonterminal completion summary: matched '${phrase}'` };
-    }
-  }
-
-  const pendingLines = text.split('\n').filter(line => /\bpending\b/i.test(line));
-  for (const line of pendingLines) {
-    if (!isTerminalPendingLine(line)) {
-      return { phrase: 'pending', reason: `Nonterminal completion summary: matched 'pending'` };
-    }
-  }
-
   return null;
 }
 
@@ -2256,7 +2225,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 
   let completionContractFailure = null;
   if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
-    const nonTerminalCompletion = detectNonTerminalResultSummary(completionGateSummary, structuredCompletion);
+    const nonTerminalCompletion = detectNonTerminalResultSummary(completionGateSummary, structuredCompletion, reportCompletion);
     if (nonTerminalCompletion) {
       skipDoneStatus = true;
       const reason = deferNonTerminalCompletion(meta, nonTerminalCompletion);

package/engine/pipeline.js

@@ -9,6 +9,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 const { safeJson, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, ENGINE_DEFAULTS, MINIONS_DIR } = shared;
+const routing = require('./routing');
 const http = require('http');
 const { parseCronExpr, shouldRunNow } = require('./scheduler');
 
@@ -306,10 +307,11 @@ function executeTaskStage(stage, stageState, run, config) {
         id,
         title: item.title || stage.title,
         description: item.description || stage.description || '',
-        type: item.type || stage.taskType || 'explore',
+        type: routing.normalizeWorkType(item.type || stage.taskType, WORK_TYPE.EXPLORE),
         priority: item.priority || stage.priority || 'medium',
-        // Only set agent if explicitly specified — otherwise engine routing assigns any available agent
+        // Agent is a soft routing hint unless agentLock/hardAgent is set.
         ...(item.agent || stage.agent ? { agent: item.agent || stage.agent } : {}),
+        ...(item.agentLock === true || stage.agentLock === true || item.hardAgent === true || stage.hardAgent === true ? { agentLock: true } : {}),
         status: WI_STATUS.PENDING,
         created: ts(),
         createdBy: 'pipeline:' + run.pipelineId,
@@ -587,7 +589,7 @@ function executeMergePrsStage(stage, stageState, run, config) {
 
 function executeScheduleStage(stage, stageState, config) {
   // Create/update schedules in config
-  const schedules = stage.schedules || [{ id: stage.id + '-sched', cron: stage.cron, title: stage.title, type: stage.taskType || 'implement' }];
+  const schedules = stage.schedules || [{ id: stage.id + '-sched', cron: stage.cron, title: stage.title, type: routing.normalizeWorkType(stage.taskType, WORK_TYPE.IMPLEMENT) }];
   // Write to config via shared
   for (const sched of schedules) {
     const existing = (config.schedules || []).find(s => s.id === sched.id);

package/engine/routing.js

@@ -8,7 +8,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeJson, safeRead, log, ts } = shared;
+const { safeJson, safeRead, log, ts, WORK_TYPE } = shared;
 const { ENGINE_DIR, DISPATCH_PATH } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -116,12 +116,43 @@ function setTempBudget(n) {
 }
 function getTempBudget() { return _tempBudget; }
 
-// Centralizes the work-item shape used to derive routing hints. Engine code
-// previously inlined `item.preferred_agent || item.agents || null` at four
-// call sites; hoisting keeps the contract in one place.
+function normalizeWorkType(workType, fallback = WORK_TYPE.IMPLEMENT) {
+  const type = String(workType || fallback || '').trim();
+  if (!type) return fallback;
+  return type;
+}
+
+function routeForWorkType(workType) {
+  const routes = getRoutingTableCached();
+  return routes[normalizeWorkType(workType)] || routes[WORK_TYPE.IMPLEMENT] || { preferred: '_any_', fallback: '_any_' };
+}
+
+function isAgentHardPinned(item) {
+  return !!(item && (
+    item.agentLock === true ||
+    item.agent_locked === true ||
+    item.hardAgent === true ||
+    item.hard_agent === true
+  ));
+}
+
+function getHardPinnedAgent(item, agents = null) {
+  if (!isAgentHardPinned(item) || !item?.agent) return null;
+  const normalized = normalizeAgentHints(item.agent, null, agents);
+  return normalized[0] || null;
+}
+
+// Centralizes the work-item shape used to derive routing hints. `agent`,
+// `preferred_agent`, and `agents` are soft preferences unless an explicit
+// hard-pin flag is present (agentLock / hardAgent variants).
 function extractAgentHints(item) {
   if (!item || typeof item !== 'object') return null;
-  return item.preferred_agent || item.agents || null;
+  const hints = [];
+  if (!isAgentHardPinned(item) && item.agent) hints.push(item.agent);
+  if (item.preferred_agent) hints.push(item.preferred_agent);
+  if (Array.isArray(item.agents)) hints.push(...item.agents);
+  else if (item.agents) hints.push(item.agents);
+  return hints.length > 0 ? hints : null;
 }
 
 // Normalize a list of agent-hint inputs. Accepts:
@@ -158,8 +189,7 @@ function normalizeAgentHints(agentHints, authorAgent = null, agents = null) {
 
 function resolveAgent(workType, config, opts = {}) {
   const { authorAgent = null, agentHints = null } = opts || {};
-  const routes = getRoutingTableCached();
-  const route = routes[workType] || routes['implement'] || { preferred: '_any_', fallback: '_any_' };
+  const route = routeForWorkType(workType);
   const agents = config.agents || {};
 
   // Resolve _author_ token
@@ -191,7 +221,6 @@ function resolveAgent(workType, config, opts = {}) {
     for (const id of hintedAgents) {
       if (isAvailable(id)) { _claimedAgents.add(id); return id; }
     }
-    return null;
   }
 
   // Resolve _any_ token — pick any available agent (#480)
@@ -228,6 +257,41 @@ function resolveAgent(workType, config, opts = {}) {
   return null;
 }
 
+function resolveAgentReservation(workType, config, opts = {}) {
+  const { authorAgent = null, agentHints = null } = opts || {};
+  const route = routeForWorkType(workType);
+  const agents = config.agents || {};
+  const hintedAgents = normalizeAgentHints(agentHints, authorAgent, agents);
+
+  const hasBudget = (id) => {
+    if (!agents[id]) return false;
+    const budget = agents[id].monthlyBudgetUsd;
+    return !(budget && budget > 0 && getMonthlySpend(id) >= budget);
+  };
+  const eligible = (id) => (id && id !== '_any_' && hasBudget(id)) ? id : null;
+  const anyEligible = (exclude = []) => {
+    const excludeSet = new Set(exclude.filter(Boolean));
+    return Object.keys(agents)
+      .filter(id => !excludeSet.has(id) && hasBudget(id))
+      .sort((a, b) => getAgentErrorRate(a) - getAgentErrorRate(b))[0] || null;
+  };
+
+  if (hintedAgents.length > 0) return hintedAgents.find(hasBudget) || null;
+
+  const preferred = route.preferred === '_author_' ? authorAgent : route.preferred;
+  const fallback = route.fallback === '_author_' ? authorAgent : route.fallback;
+
+  if (preferred === '_any_') return anyEligible();
+  const preferredAgent = eligible(preferred);
+  if (preferredAgent) return preferredAgent;
+
+  if (fallback === '_any_') return anyEligible([preferred]);
+  const fallbackAgent = eligible(fallback);
+  if (fallbackAgent) return fallbackAgent;
+
+  return anyEligible([preferred, fallback]);
+}
+
 module.exports = {
   tempAgents,
   getRouting,
@@ -238,9 +302,13 @@ module.exports = {
   isAgentIdle,
   normalizeAgentHints,
   extractAgentHints,
+  isAgentHardPinned,
+  getHardPinnedAgent,
+  normalizeWorkType,
   _claimedAgents,
   resetClaimedAgents,
   resolveAgent,
+  resolveAgentReservation,
   setTempBudget,
   getTempBudget,
 };

package/engine/scheduler.js

@@ -24,7 +24,8 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, safeWrite, mutateJsonFileLocked, ts, dateStamp, WI_STATUS } = shared;
+const routing = require('./routing');
+const { safeJson, safeWrite, mutateJsonFileLocked, ts, dateStamp, WI_STATUS, WORK_TYPE } = shared;
 
 const SCHEDULE_RUNS_PATH = path.join(shared.MINIONS_DIR, 'engine', 'schedule-runs.json');
 
@@ -167,13 +168,14 @@ function discoverScheduledWork(config) {
       work.push({
         id: workItemId,
         title: resolveScheduleTemplateVars(sched.title),
-        type: sched.type || 'implement',
+        type: routing.normalizeWorkType(sched.type, WORK_TYPE.IMPLEMENT),
         priority: sched.priority || 'medium',
         description: resolveScheduleTemplateVars(sched.description || sched.title),
         status: WI_STATUS.PENDING,
         created: ts(),
         createdBy: 'scheduler',
         agent: sched.agent || null,
+        ...(sched.agentLock === true || sched.hardAgent === true ? { agentLock: true } : {}),
         project: sched.project || null,
         _scheduleId: sched.id,
       });

package/engine/timeout.js

@@ -147,7 +147,7 @@ function checkTimeouts(config) {
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
   const engineRestartGraceExempt = engine().engineRestartGraceExempt;
   const { completeDispatch } = dispatch();
-  const { runPostCompletionHooks, parseAgentOutput, parseStructuredCompletion, detectNonTerminalResultSummary } = require('./lifecycle');
+  const { runPostCompletionHooks, parseAgentOutput, parseStructuredCompletion, parseCompletionReportFile, detectNonTerminalResultSummary } = require('./lifecycle');
 
   const timeout = config.engine?.agentTimeout || ENGINE_DEFAULTS.agentTimeout;
   const defaultStaleOrphanTimeout = config.engine?.heartbeatTimeout || ENGINE_DEFAULTS.heartbeatTimeout;
@@ -265,7 +265,7 @@ function checkTimeouts(config) {
           outputResultSummary = parseAgentOutput(fullLogForHooks, runtimeName).resultSummary || '';
           const gateSummary = outputResultSummary || (!fullLogForHooks.includes('"type":') ? fullLogForHooks : '');
           completionDetection = isSuccess
-            ? detectNonTerminalResultSummary(gateSummary, parseStructuredCompletion(fullLogForHooks, runtimeName))
+            ? detectNonTerminalResultSummary(gateSummary, parseStructuredCompletion(fullLogForHooks, runtimeName), parseCompletionReportFile(item))
             : null;
         } catch (e) { log('warn', 'completion summary gate: ' + e.message); }
 

package/engine.js

@@ -125,7 +125,7 @@ const { getConfig, getControl, getDispatch, getNotes,
 const routing = require('./engine/routing');
 const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
   getAgentErrorRate, isAgentIdle, resolveAgent, resetClaimedAgents,
-  setTempBudget, tempAgents } = routing;
+  resolveAgentReservation, setTempBudget, tempAgents } = routing;
 
 // ─── Playbook, system prompt, agent context (extracted to engine/playbook.js) ─
 
@@ -2644,7 +2644,7 @@ function discoverFromWorkItems(config, project) {
       skipped.gated++; continue;
     }
 
-    let workType = item.type || 'implement';
+    let workType = routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT);
     if (workType === WORK_TYPE.IMPLEMENT && (item.complexity === 'large' || item.estimated_complexity === 'large')) {
       workType = WORK_TYPE.IMPLEMENT_LARGE;
     }
@@ -2655,14 +2655,24 @@ function discoverFromWorkItems(config, project) {
       needsWrite = true;
     }
     const agentHints = routing.extractAgentHints(item);
-    const agentId = item.agent || resolveAgent(workType, config, { agentHints });
+    const hardPinRequested = routing.isAgentHardPinned(item);
+    let agentId = routing.getHardPinnedAgent(item, config.agents || {})
+      || (!hardPinRequested ? resolveAgent(workType, config, { agentHints }) : null);
+    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 (agentId) {
+        delete item._pendingReason;
+        needsWrite = true;
+      }
+    }
     if (!agentId) {
-      // Check if reason is budget
-      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 (budgetBlocked) {
         if (item._pendingReason !== 'budget_exceeded') { item._pendingReason = 'budget_exceeded'; needsWrite = true; }
       } else {
@@ -3095,7 +3105,7 @@ function discoverCentralWorkItems(config) {
     }
     if (isOnCooldown(key, 0)) continue;
 
-    const workType = item.type || 'implement';
+    const workType = routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT);
     const isFanOut = item.scope === 'fan-out';
 
     if (isFanOut) {
@@ -3176,7 +3186,10 @@ function discoverCentralWorkItems(config) {
     } else {
       // ─── Normal: single agent dispatch ──────────────────────────────
       const agentHints = routing.extractAgentHints(item);
-      const agentId = item.agent || resolveAgent(workType, config, { agentHints });
+      const hardPinRequested = routing.isAgentHardPinned(item);
+      const agentId = routing.getHardPinnedAgent(item, config.agents || {})
+        || (!hardPinRequested ? resolveAgent(workType, config, { agentHints }) : null)
+        || (!hardPinRequested ? resolveAgentReservation(workType, config, { agentHints }) : null);
       if (!agentId) continue;
 
       const agentName = config.agents[agentId]?.name || agentId;
@@ -3837,6 +3850,7 @@ async function tickInner() {
   const seenPendingIds = new Set();
   const toDispatch = [];
   let generalSlots = slotsAvailable;
+  resetClaimedAgents(); // Pending agent resolution is a fresh allocation phase after discovery claims.
 
   for (const item of dispatch.pending) {
     if (seenPendingIds.has(item.id)) {
@@ -3849,7 +3863,7 @@ 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(item.type || WORK_TYPE.FIX, config, { agentHints: routing.extractAgentHints(item.meta?.item) });
+      const fallback = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config, { agentHints: routing.extractAgentHints(item.meta?.item) });
       if (!fallback) {
         log('warn', `Pending dispatch ${item.id} has no agent and routing returned no fallback — skipping`);
         continue;
@@ -3880,7 +3894,7 @@ 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(item.type, config);
+      const altAgent = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config);
       if (altAgent && altAgent !== item.agent) {
         const prevAgent = item.agent;
         item.agent = altAgent;
@@ -3907,12 +3921,12 @@ async function tickInner() {
       // Agent busy reassignment: if item has been waiting on a busy agent past the threshold,
       // try to find an alternative agent via routing. Skip explicitly assigned items.
       const reassignMs = config.engine?.agentBusyReassignMs ?? ENGINE_DEFAULTS.agentBusyReassignMs;
-      const isExplicitReassign = !!(item.meta?.item?.agent || routing.extractAgentHints(item.meta?.item));
-      if (!isExplicitReassign && reassignMs > 0 && item._agentBusySince) {
+      const isHardPinned = routing.isAgentHardPinned(item.meta?.item);
+      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(item.type, config);
+          const altAgent = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config, { agentHints: routing.extractAgentHints(item.meta?.item) });
           if (altAgent && altAgent !== originalAgent && !busyAgents.has(altAgent)) {
             log('info', `Reassigning ${item.id} from ${originalAgent} to ${altAgent} — agent busy > ${reassignMs}ms`);
             item.agent = altAgent;
@@ -3946,14 +3960,12 @@ async function tickInner() {
     // Branch mutex: skip items targeting a branch already locked by an active or newly-dispatched task
     const itemBranch = item.meta?.branch ? sanitizeBranch(item.meta.branch) : null;
     if (itemBranch && lockedBranches.has(itemBranch)) continue;
-    // Items explicitly assigned to an agent bypass concurrency cap — dispatch if agent is free
-    const isExplicitAssignment = !!item.meta?.item?.agent;
-    if (!isExplicitAssignment && generalSlots <= 0) continue;
+    if (generalSlots <= 0) continue;
     seenPendingIds.add(item.id);
     toDispatch.push(item);
     busyAgents.add(item.agent);
     if (itemBranch) lockedBranches.add(itemBranch);
-    if (!isExplicitAssignment) generalSlots--;
+    generalSlots--;
   }
 
   // Dispatch items — spawnAgent moves each from pending→active on disk.

package/package.json

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