@yemi33/minions 0.1.955 → 0.1.957

package/CHANGELOG.md

@@ -1,8 +1,9 @@
 # Changelog
 
-## 0.1.955 (2026-04-14)
+## 0.1.957 (2026-04-14)
 
 ### Features
+- wire agentBusyReassignMs into settings UI and persist
 -  ADO throttle detection, poll guards, and dashboard banner (#1051)
 - gate auto-fix conflict dispatch behind autoFixConflicts flag
 - add PR/build status CLI shim and agent guidance
@@ -22,9 +23,9 @@
 - fix dashboard plan-pause nested lock violation (#968)
 - add missing branch_name to central dispatch vars (#967)
 - fix dispatch.js mutator fallback to use nullish coalescing (#966)
-- fix stall recovery nested lock violation (#965)
 
 ### Fixes
+- suppress warn for optional template variables (#1061)
 - fix ENGINE_DEFAULTS ref and derive boolean settings from defaults
 - add autoFixConflicts to boolean settings persist list
 - tighten build query guard to require mergeCommitId
@@ -44,7 +45,6 @@
 -  qaAbort race + skip kill on completed doc-chat
 -  doc-chat Stop button actually works — release server guard on disconnect
 -  CC streaming auto-retries fresh session when resume fails
--  429 retry on abort race applies to all sends, not just queued
 
 ### Other
 - test(engine): add regression tests for autoFixConflicts flag and DEFAULTS alias

package/dashboard/js/settings.js

@@ -61,6 +61,7 @@ async function openSettings() {
       settingsField('Eval Max Iterations', 'set-evalMaxIterations', e.evalMaxIterations || 3, '', 'Max review→fix cycles before escalating (1-10)') +
       settingsField('Eval Max Cost', 'set-evalMaxCost', e.evalMaxCost === null || e.evalMaxCost === undefined ? '' : e.evalMaxCost, '$', 'USD ceiling per work item across all eval iterations (blank = no limit)') +
       settingsField('Max Build Fix Attempts', 'set-maxBuildFixAttempts', e.maxBuildFixAttempts || 3, '', 'Max auto-fix dispatches per PR before escalating to human (1-10)') +
+      settingsField('Agent Busy Reassign', 'set-agentBusyReassignMs', e.agentBusyReassignMs || 600000, 'ms', 'Reassign work to another agent after it waits this long on a busy agent') +
       settingsField('Version Check Interval', 'set-versionCheckInterval', e.versionCheckInterval || 3600000, 'ms', 'How often to check npm for updates (default: 1 hour)') +
       settingsField('Ignored Comment Authors', 'set-ignoredCommentAuthors', (e.ignoredCommentAuthors || []).join(', '), '', 'Comma-separated usernames — comments auto-closed, never trigger fixes') +
     '</div>' +
@@ -246,6 +247,7 @@ async function saveSettings() {
       evalMaxIterations: document.getElementById('set-evalMaxIterations').value,
       evalMaxCost: document.getElementById('set-evalMaxCost').value || null,
       maxBuildFixAttempts: document.getElementById('set-maxBuildFixAttempts').value,
+      agentBusyReassignMs: document.getElementById('set-agentBusyReassignMs').value,
       ignoredCommentAuthors: document.getElementById('set-ignoredCommentAuthors').value,
       versionCheckInterval: document.getElementById('set-versionCheckInterval').value,
       ccModel: document.getElementById('set-ccModel').value,

package/dashboard.js

@@ -3754,6 +3754,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           versionCheckInterval: [60000],
           maxBuildFixAttempts: [1, 10],
           adoPollStatusEvery: [1], adoPollCommentsEvery: [1],
+          agentBusyReassignMs: [60000],
         };
         for (const [key, [min, max]] of Object.entries(numericFields)) {
           if (e[key] !== undefined) {

package/engine/playbook.js

@@ -214,6 +214,22 @@ function resolveTaskContext(item, config) {
 // are optional by design. Only variables that make the playbook non-functional
 // when absent are listed here.
 
+// ─── Optional Template Variables ────────────────────────────────────────────
+// Variables that legitimately resolve to empty string for ad-hoc work items.
+// These are silently filtered out of the empty-string warning to avoid
+// masking real warnings. Add new optional vars here when they are contextual
+// (plan-linked, checkpoint-dependent, etc.) and not required for the playbook
+// to function.
+
+const PLAYBOOK_OPTIONAL_VARS = new Set([
+  'source_plan',          // only set when work item is linked to a plan
+  'plan_slug',            // derived from source_plan
+  'additional_context',   // only set when item has a prompt
+  'references',           // only set when item.references has entries
+  'acceptance_criteria',  // only set when item.acceptanceCriteria has entries
+  'checkpoint_context',   // only set when resuming from a prior timeout
+]);
+
 const PLAYBOOK_REQUIRED_VARS = {
   'implement':            ['item_id', 'item_name', 'branch_name', 'project_path'],
   'implement-shared':     ['item_id', 'item_name', 'branch_name', 'worktree_path'],
@@ -364,9 +380,9 @@ function renderPlaybook(type, vars) {
     log('warn', `Playbook "${type}": substituted values contain unresolved {{...}} patterns (potential self-reference): ${selfRefVars.join(', ')}`);
   }
 
-  // Warn on variables that resolved to empty string
+  // Warn on variables that resolved to empty string (skip known-optional vars)
   const emptyVars = Object.entries(allVars)
-    .filter(([, val]) => String(val) === '')
+    .filter(([key, val]) => String(val) === '' && !PLAYBOOK_OPTIONAL_VARS.has(key))
     .map(([key]) => key);
   if (emptyVars.length > 0) {
     log('warn', `Playbook "${type}": template variables resolved to empty string: ${emptyVars.join(', ')}`);
@@ -551,6 +567,7 @@ module.exports = {
   renderPlaybook,
   validatePlaybookVars,
   PLAYBOOK_REQUIRED_VARS,
+  PLAYBOOK_OPTIONAL_VARS,
   buildSystemPrompt,
   buildAgentContext,
   selectPlaybook,

package/engine/shared.js

@@ -555,6 +555,7 @@ const ENGINE_DEFAULTS = {
   autoCompletePrs: false, // auto-merge PRs when builds green + review approved (opt-in)
   prMergeMethod: 'squash', // merge method: squash, merge, rebase
   ignoredCommentAuthors: [], // comments from these authors are auto-closed and never trigger fixes
+  agentBusyReassignMs: 600000, // 10min — reassign work item to another agent if preferred agent is busy beyond this threshold
   ccModel: 'sonnet', // model for Command Center and doc-chat (sonnet, haiku, opus)
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
   heartbeatTimeouts: {}, // populated after WORK_TYPE is defined (below)

package/engine.js

@@ -1300,6 +1300,7 @@ async function spawnAgent(dispatchItem, config) {
     const item = dispatch.pending.splice(idx, 1)[0];
     item.started_at = startedAt;
     delete item.skipReason;
+    delete item._agentBusySince;
     if (!dispatch.active.some(d => d.id === id)) {
       dispatch.active.push(item);
     }
@@ -3324,7 +3325,46 @@ async function tickInner() {
       log('warn', `Duplicate dispatch ID ${item.id} in pending queue — skipping`);
       continue;
     }
-    if (busyAgents.has(item.agent)) continue;
+    if (busyAgents.has(item.agent)) {
+      // 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;
+      if (!isExplicitReassign && 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);
+          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;
+            // 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;
+            });
+            // Fall through to branch mutex / concurrency checks below
+          } else {
+            continue; // No alternative agent available — keep waiting
+          }
+        } else {
+          continue; // Below threshold — keep waiting
+        }
+      } else {
+        continue; // No _agentBusySince set yet or explicitly assigned — skip
+      }
+    }
     // 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;
@@ -3412,6 +3452,18 @@ async function tickInner() {
         reason = 'branch_locked';
       }
     }
+    // Track when item first became blocked on a busy agent for reassignment threshold
+    if (reason === 'agent_busy') {
+      if (!item._agentBusySince) {
+        item._agentBusySince = ts();
+        skipReasonChanged = true;
+      }
+    } else {
+      if (item._agentBusySince) {
+        delete item._agentBusySince;
+        skipReasonChanged = true;
+      }
+    }
     if (item.skipReason !== reason) {
       item.skipReason = reason;
       skipReasonChanged = true;

package/package.json

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