@yemi33/minions 0.1.1657 → 0.1.1659

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.1659 (2026-05-01)
+
+### Other
+- Harden runtime state writes
+
+## 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

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, mutateControl, mutateCooldowns, 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 || '';
 
@@ -2116,12 +2116,10 @@ const { cleanDispatchEntries } = require('./engine/dispatch');
 // ── Engine Restart Helpers (used by watchdog + API) ─────────────────────────
 
 function spawnEngine() {
-  const controlPath = path.join(ENGINE_DIR, 'control.json');
   // Don't pre-write 'stopped' — let the new engine process own its state transition.
   // The engine start code already handles state:'running' with a dead PID gracefully.
   // Only set restarted_at + clear stale pid so dashboard shows the restart timestamp.
-  const control = safeJson(controlPath) || {};
-  safeWrite(controlPath, { ...control, pid: null, restarted_at: new Date().toISOString() });
+  mutateControl(control => ({ ...control, pid: null, restarted_at: new Date().toISOString() }));
   const { spawn: cpSpawn } = require('child_process');
   const childEnv = { ...process.env };
   for (const key of Object.keys(childEnv)) {
@@ -2413,12 +2411,10 @@ const server = http.createServer(async (req, res) => {
           }, { defaultValue: { pending: [], active: [], completed: [] } });
         } catch (e) { console.error('dispatch cleanup:', e.message); }
         try {
-          const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-          const cooldowns = safeJsonObj(cooldownPath);
-          if (cooldowns[dispatchKey]) {
+          mutateCooldowns(cooldowns => {
             delete cooldowns[dispatchKey];
-            safeWrite(cooldownPath, cooldowns);
-          }
+            return cooldowns;
+          });
         } catch (e) { console.error('cooldown cleanup:', e.message); }
 
         return jsonReply(res, 200, { ok: true, id, rematerialized: true });
@@ -2463,12 +2459,10 @@ const server = http.createServer(async (req, res) => {
 
       // Clear cooldown so item isn't blocked by exponential backoff
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        if (cooldowns[dispatchKey]) {
+        mutateCooldowns(cooldowns => {
           delete cooldowns[dispatchKey];
-          safeWrite(cooldownPath, cooldowns);
-        }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup:', e.message); }
 
       return jsonReply(res, 200, { ok: true, id });
@@ -2514,13 +2508,12 @@ const server = http.createServer(async (req, res) => {
 
       // Clean cooldown entries so item can be re-created immediately
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        let cleaned = false;
-        for (const key of Object.keys(cooldowns)) {
-          if (key.includes(id)) { delete cooldowns[key]; cleaned = true; }
-        }
-        if (cleaned) safeWrite(cooldownPath, cooldowns);
+        mutateCooldowns(cooldowns => {
+          for (const key of Object.keys(cooldowns)) {
+            if (key.includes(id)) delete cooldowns[key];
+          }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup:', e.message); }
 
       // Reset PRD item status so it doesn't stay 'dispatched' with no work item (#779)
@@ -2579,13 +2572,12 @@ const server = http.createServer(async (req, res) => {
 
       // Clean cooldown entries
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        let cleaned = false;
-        for (const key of Object.keys(cooldowns)) {
-          if (key.includes(id)) { delete cooldowns[key]; cleaned = true; }
-        }
-        if (cleaned) safeWrite(cooldownPath, cooldowns);
+        mutateCooldowns(cooldowns => {
+          for (const key of Object.keys(cooldowns)) {
+            if (key.includes(id)) delete cooldowns[key];
+          }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup on cancel:', e.message); }
 
       invalidateStatusCache();
@@ -2704,12 +2696,10 @@ const server = http.createServer(async (req, res) => {
         }, { defaultValue: { pending: [], active: [], completed: [] } });
       } catch (e) { console.error('dispatch cleanup on reopen:', e.message); }
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        if (cooldowns[dispatchKey]) {
+        mutateCooldowns(cooldowns => {
           delete cooldowns[dispatchKey];
-          safeWrite(cooldownPath, cooldowns);
-        }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup on reopen:', e.message); }
 
       invalidateStatusCache();
@@ -2733,22 +2723,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;
@@ -6449,10 +6436,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Engine
     { method: 'POST', path: '/api/engine/wakeup', desc: 'Trigger immediate engine tick via control.json signal', handler: async (req, res) => {
-      const controlPath = path.join(MINIONS_DIR, 'engine', 'control.json');
-      const control = shared.safeJson(controlPath) || {};
-      control._wakeupAt = Date.now();
-      shared.safeWrite(controlPath, control);
+      shared.mutateControl(control => ({ ...control, _wakeupAt: Date.now() }));
       return jsonReply(res, 200, { ok: true, message: 'Wakeup signal sent' });
     }},
     { method: 'POST', path: '/api/engine/restart', desc: 'Force-kill engine and restart immediately', handler: handleEngineRestart },

package/engine/cleanup.js

@@ -9,7 +9,7 @@ const shared = require('./shared');
 const queries = require('./queries');
 
 const { exec, execSilent, log, ts, ENGINE_DEFAULTS } = shared;
-const { safeJson, safeWrite, safeReadDir, mutateWorkItems, mutateJsonFileLocked, getProjects, projectWorkItemsPath, projectPrPath,
+const { safeJson, safeWrite, safeReadDir, mutateCooldowns, mutateWorkItems, mutateJsonFileLocked, getProjects, projectWorkItemsPath, projectPrPath,
   sanitizeBranch, KB_CATEGORIES } = shared;
 const { getDispatch, getAgentStatus } = queries;
 
@@ -675,9 +675,9 @@ function runCleanup(config, verbose = false) {
         entries.sort((a, b) => (b[1].timestamp || 0) - (a[1].timestamp || 0));
         const keep = Object.fromEntries(entries.slice(0, COOLDOWN_CAP));
         cleaned.cooldowns = entries.length - COOLDOWN_CAP;
-        safeWrite(cooldownPath, keep);
+        mutateCooldowns(() => keep);
       } else if (dirty) {
-        safeWrite(cooldownPath, cooldowns);
+        mutateCooldowns(() => cooldowns);
       }
     }
   } catch (e) { log('warn', 'cap cooldowns: ' + e.message); }

package/engine/cli.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT } = shared;
+const { safeRead, safeJson, safeWrite, mutateControl, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT } = shared;
 const queries = require('./queries');
 const { getConfig, getControl, getDispatch, getAgentStatus,
   MINIONS_DIR, ENGINE_DIR, AGENTS_DIR, PLANS_DIR, PRD_DIR, CONTROL_PATH, DISPATCH_PATH } = queries;
@@ -312,7 +312,7 @@ const commands = {
     }
     let codeCommit = null;
     try { codeCommit = require('child_process').execSync('git rev-parse --short HEAD', { cwd: path.resolve(__dirname, '..'), encoding: 'utf8', timeout: 5000, windowsHide: true }).trim(); } catch {}
-    safeWrite(CONTROL_PATH, { state: 'running', pid: process.pid, started_at: e.ts(), codeVersion, codeCommit });
+    mutateControl(() => ({ state: 'running', pid: process.pid, started_at: e.ts(), codeVersion, codeCommit }));
     // Keep .minions-version in sync so `minions version` stays accurate after git pulls
     if (codeVersion) {
       try { fs.writeFileSync(path.join(shared.MINIONS_DIR, '.minions-version'), codeVersion); } catch {}
@@ -599,7 +599,10 @@ const commands = {
       const ctrl = getControl();
       if (ctrl._wakeupAt && Date.now() - ctrl._wakeupAt < 5000) {
         delete ctrl._wakeupAt;
-        safeWrite(CONTROL_PATH, ctrl);
+        mutateControl((control) => {
+          delete control._wakeupAt;
+          return control;
+        });
         e.tick();
       }
     }, 1000);
@@ -669,11 +672,11 @@ const commands = {
       clearInterval(fastPollTimer);
       if (teamsInboxTimer) clearInterval(teamsInboxTimer);
       for (const f of _watchedFiles) { try { fs.unwatchFile(f); } catch { /* cleanup */ } }
-      safeWrite(CONTROL_PATH, { state: 'stopping', pid: process.pid, stopping_at: e.ts() });
+      mutateControl(() => ({ state: 'stopping', pid: process.pid, stopping_at: e.ts() }));
       e.log('info', `Graceful shutdown initiated (${signal})`);
 
       if (e.activeProcesses.size === 0) {
-        safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+        mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
         e.log('info', 'Graceful shutdown complete (no active agents)');
         shared.flushLogs(); // drain buffered log entries before exit
         console.log('No active agents — stopped.');
@@ -687,7 +690,7 @@ const commands = {
       const poll = setInterval(() => {
         if (e.activeProcesses.size === 0) {
           clearInterval(poll);
-          safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+          mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
           e.log('info', 'Graceful shutdown complete (all agents finished)');
           shared.flushLogs(); // drain buffered log entries before exit
           console.log('All agents finished — stopped.');
@@ -695,7 +698,7 @@ const commands = {
         }
         if (Date.now() >= deadline) {
           clearInterval(poll);
-          safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+          mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
           e.log('warn', `Graceful shutdown timed out after ${timeout / 1000}s with ${e.activeProcesses.size} agent(s) still active`);
           shared.flushLogs(); // drain buffered log entries before exit
           console.log(`Shutdown timeout (${timeout / 1000}s) — force exiting with ${e.activeProcesses.size} agent(s) still running.`);
@@ -742,14 +745,14 @@ const commands = {
     if (control.pid && control.pid !== process.pid) {
       try { process.kill(control.pid); } catch { /* process may be dead */ }
     }
-    safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+    mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
     e.log('info', 'Engine stopped');
     console.log('Engine stopped.');
   },
 
   pause() {
     const e = engine();
-    safeWrite(CONTROL_PATH, { state: 'paused', paused_at: e.ts() });
+    mutateControl(() => ({ state: 'paused', paused_at: e.ts() }));
     e.log('info', 'Engine paused');
     console.log('Engine paused. Run `node .minions/engine.js resume` to resume.');
   },
@@ -761,7 +764,7 @@ const commands = {
       console.log('Engine is already running.');
       return;
     }
-    safeWrite(CONTROL_PATH, { state: 'running', resumed_at: e.ts() });
+    mutateControl(() => ({ state: 'running', resumed_at: e.ts() }));
     e.log('info', 'Engine resumed');
     console.log('Engine resumed.');
   },
@@ -932,7 +935,7 @@ const commands = {
   dispatch() {
     const control = getControl();
     if (control.state === 'running' && isEngineProcessAlive(control)) {
-      safeWrite(CONTROL_PATH, { ...control, _wakeupAt: Date.now() });
+      mutateControl((c) => ({ ...c, _wakeupAt: Date.now() }));
       console.log(`Dispatch wakeup requested from running engine (PID ${control.pid}).`);
       return;
     }

package/engine/cooldown.js

@@ -7,7 +7,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeJson, safeWrite, log, ENGINE_DEFAULTS } = shared;
+const { safeJson, mutateCooldowns, log, ENGINE_DEFAULTS } = shared;
 const { ENGINE_DIR } = queries;
 
 /**
@@ -37,6 +37,7 @@ function _truncateContextEntry(entry, maxBytes) {
 
 const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 const dispatchCooldowns = new Map(); // key → { timestamp, failures }
+let _lastDiskCooldownKeys = new Set();
 
 function loadCooldowns() {
   const saved = safeJson(COOLDOWN_PATH);
@@ -48,6 +49,7 @@ function loadCooldowns() {
       dispatchCooldowns.set(k, v);
     }
   }
+  _lastDiskCooldownKeys = new Set(dispatchCooldowns.keys());
   log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
 }
 
@@ -57,27 +59,35 @@ function saveCooldowns() {
   if (_cooldownWriteTimer) clearTimeout(_cooldownWriteTimer);
   _cooldownWriteTimer = setTimeout(() => {
     _cooldownWriteTimer = null;
-    // Prune expired entries (>24h) before saving
-    const now = Date.now();
-    for (const [k, v] of dispatchCooldowns) {
-      if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
-    }
-    // Trim pendingContexts arrays before writing to prevent bloat
-    const cap = ENGINE_DEFAULTS.maxPendingContexts;
-    const entryLimit = ENGINE_DEFAULTS.maxPendingContextEntryBytes;
-    for (const [, v] of dispatchCooldowns) {
-      if (Array.isArray(v.pendingContexts)) {
-        if (v.pendingContexts.length > cap) {
-          v.pendingContexts = v.pendingContexts.slice(-cap);
-        }
-        // Also truncate oversized individual entries — #1167 showed
-        // 20 entries × 25 MB each still produced a 500 MB cooldowns.json.
-        v.pendingContexts = v.pendingContexts.map(e => _truncateContextEntry(e, entryLimit));
-      }
-    }
-    const obj = Object.fromEntries(dispatchCooldowns);
     try {
-      safeWrite(COOLDOWN_PATH, obj);
+      mutateCooldowns((diskCooldowns) => {
+        for (const key of Array.from(dispatchCooldowns.keys())) {
+          if (_lastDiskCooldownKeys.has(key) && !Object.prototype.hasOwnProperty.call(diskCooldowns, key)) {
+            dispatchCooldowns.delete(key);
+          }
+        }
+        // Prune expired entries (>24h) before saving
+        const now = Date.now();
+        for (const [k, v] of dispatchCooldowns) {
+          if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
+        }
+        // Trim pendingContexts arrays before writing to prevent bloat
+        const cap = ENGINE_DEFAULTS.maxPendingContexts;
+        const entryLimit = ENGINE_DEFAULTS.maxPendingContextEntryBytes;
+        for (const [, v] of dispatchCooldowns) {
+          if (Array.isArray(v.pendingContexts)) {
+            if (v.pendingContexts.length > cap) {
+              v.pendingContexts = v.pendingContexts.slice(-cap);
+            }
+            // Also truncate oversized individual entries — #1167 showed
+            // 20 entries × 25 MB each still produced a 500 MB cooldowns.json.
+            v.pendingContexts = v.pendingContexts.map(e => _truncateContextEntry(e, entryLimit));
+          }
+        }
+        const obj = Object.fromEntries(dispatchCooldowns);
+        _lastDiskCooldownKeys = new Set(Object.keys(obj));
+        return obj;
+      });
     } catch (err) {
       log('warn', `saveCooldowns failed writing ${COOLDOWN_PATH}: ${err.message}`);
     }

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-01T04:46:00.686Z"
+  "cachedAt": "2026-05-01T05:34:43.680Z"
 }

package/engine/dispatch.js

@@ -81,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) {

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/queries.js

@@ -101,7 +101,21 @@ function timeSince(ms) {
 }
 
 function readJsonNoRestore(filePath) {
-  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    if (e && e.code !== 'ENOENT') {
+      console.warn(`[queries] failed to read ${_relativeStatePath(filePath)}: ${e.message}`);
+    }
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    console.warn(`[queries] corrupt JSON in ${_relativeStatePath(filePath)}: ${e.message}`);
+    return null;
+  }
 }
 
 // ── Core State Readers ──────────────────────────────────────────────────────

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)
@@ -230,8 +259,7 @@ function resolveAgent(workType, config, opts = {}) {
 
 function resolveAgentReservation(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 || {};
   const hintedAgents = normalizeAgentHints(agentHints, authorAgent, agents);
 
@@ -274,6 +302,9 @@ module.exports = {
   isAgentIdle,
   normalizeAgentHints,
   extractAgentHints,
+  isAgentHardPinned,
+  getHardPinnedAgent,
+  normalizeWorkType,
   _claimedAgents,
   resetClaimedAgents,
   resolveAgent,

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/shared.js

@@ -8,6 +8,9 @@ const path = require('path');
 const crypto = require('crypto');
 
 const MINIONS_DIR = process.env.MINIONS_TEST_DIR || path.resolve(__dirname, '..');
+const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
+const CONTROL_PATH = path.join(ENGINE_DIR, 'control.json');
+const COOLDOWNS_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 const PR_LINKS_PATH = path.join(MINIONS_DIR, 'engine', 'pr-links.json');
 const PINNED_ITEMS_PATH = path.join(MINIONS_DIR, 'engine', 'kb-pins.json');
 const LOG_PATH = path.join(MINIONS_DIR, 'engine', 'log.json');
@@ -428,6 +431,20 @@ function mutateJsonFileLocked(filePath, mutateFn, {
   }, { retries, retryBackoffMs });
 }
 
+function mutateControl(mutator) {
+  return mutateJsonFileLocked(CONTROL_PATH, (data) => {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+    return mutator(data) || data;
+  }, { defaultValue: { state: 'stopped', pid: null }, skipWriteIfUnchanged: true });
+}
+
+function mutateCooldowns(mutator) {
+  return mutateJsonFileLocked(COOLDOWNS_PATH, (data) => {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+    return mutator(data) || data;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+}
+
 /**
  * Generate a unique ID suffix: timestamp + 4 random chars.
  * Use for filenames that could collide (dispatch IDs, temp files, etc.)
@@ -2304,6 +2321,9 @@ function createThrottleTracker({ label, baseBackoffMs = 60000, maxBackoffMs = 32
 
 module.exports = {
   MINIONS_DIR,
+  ENGINE_DIR,
+  CONTROL_PATH,
+  COOLDOWNS_PATH,
   PR_LINKS_PATH,
   PINNED_ITEMS_PATH,
   LOG_PATH,
@@ -2325,6 +2345,8 @@ module.exports = {
   assertStateFileSize,
   withFileLock,
   mutateJsonFileLocked,
+  mutateControl,
+  mutateCooldowns,
   mutateWorkItems,
   reopenWorkItem,
   mutatePullRequests,

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

@@ -95,6 +95,7 @@ const safeRead = shared.safeRead;
 const safeWrite = shared.safeWrite;
 const safeUnlink = shared.safeUnlink;
 const mutateJsonFileLocked = shared.mutateJsonFileLocked;
+const mutateControl = shared.mutateControl;
 const mutateWorkItems = shared.mutateWorkItems;
 const mutatePullRequests = shared.mutatePullRequests;
 const withFileLock = shared.withFileLock;
@@ -2644,7 +2645,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,16 +2656,17 @@ function discoverFromWorkItems(config, project) {
       needsWrite = true;
     }
     const agentHints = routing.extractAgentHints(item);
-    const hasExplicitAgentHint = !!(item.agent || routing.normalizeAgentHints(agentHints, null, config.agents || {}).length);
-    let 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 && !hasExplicitAgentHint) {
-        agentId = resolveAgentReservation(workType, config);
+      if (!budgetBlocked && !hardPinRequested) {
+        agentId = resolveAgentReservation(workType, config, { agentHints });
       }
       if (agentId) {
         delete item._pendingReason;
@@ -3104,7 +3106,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) {
@@ -3185,10 +3187,10 @@ function discoverCentralWorkItems(config) {
     } else {
       // ─── Normal: single agent dispatch ──────────────────────────────
       const agentHints = routing.extractAgentHints(item);
-      const hasExplicitAgentHint = !!(item.agent || routing.normalizeAgentHints(agentHints, null, config.agents || {}).length);
-      const agentId = item.agent
-        || resolveAgent(workType, config, { agentHints })
-        || (!hasExplicitAgentHint ? resolveAgentReservation(workType, config) : null);
+      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;
@@ -3556,7 +3558,7 @@ async function tickInner() {
   }
 
   // Write heartbeat so dashboard can detect stale engine
-  try { safeWrite(CONTROL_PATH, { ...control, heartbeat: Date.now() }); } catch (e) { log('warn', 'write heartbeat: ' + e.message); }
+  try { mutateControl(c => ({ ...c, heartbeat: Date.now() })); } catch (e) { log('warn', 'write heartbeat: ' + e.message); }
 
   const config = getConfig();
   tickCount++;
@@ -3862,7 +3864,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;
@@ -3893,7 +3895,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;
@@ -3920,12 +3922,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;
@@ -3959,14 +3961,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.1657",
+  "version": "0.1.1659",
   "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"