@yemi33/minions 0.1.956 → 0.1.957

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.1.956 (2026-04-14)
+## 0.1.957 (2026-04-14)
 
 ### Features
 - wire agentBusyReassignMs into settings UI and persist
@@ -25,6 +25,7 @@
 - fix dispatch.js mutator fallback to use nullish coalescing (#966)
 
 ### 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/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.956",
+  "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"