@yemi33/minions 0.1.143 → 0.1.145

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.145 (2026-04-01)
+
+### Engine
+- engine.js
+- engine/ado.js
+- engine/cleanup.js
+- engine/cooldown.js
+- engine/github.js
+- engine/lifecycle.js
+- engine/meeting.js
+- engine/playbook.js
+- engine/routing.js
+- engine/timeout.js
+
+### Dashboard
+- dashboard/js/render-other.js
+- dashboard/pages/engine.html
+
+### Other
+- test/unit.test.js
+
 ## 0.1.143 (2026-04-01)
 
 ### Engine

package/dashboard/js/render-other.js

@@ -44,6 +44,7 @@ function renderMetrics(metrics) {
   if (agents.length === 0) {
     el.innerHTML = '<p class="empty">No metrics yet. Metrics appear after agents complete tasks.</p>';
     renderTokenUsage(metrics);
+    renderContextPressure(metrics);
     return;
   }
   let html = '<table class="pr-table"><thead><tr><th>Agent</th><th>Done</th><th>Errors</th><th>PRs</th><th>Approved</th><th>Rejected</th><th>Rate</th><th>Reviews</th></tr></thead><tbody>';
@@ -64,6 +65,7 @@ function renderMetrics(metrics) {
   html += '</tbody></table>';
   el.innerHTML = html;
   renderTokenUsage(metrics);
+  renderContextPressure(metrics);
 }
 
 function renderTokenUsage(metrics) {
@@ -183,4 +185,25 @@ function renderTokenUsage(metrics) {
   el.innerHTML = html;
 }
 
-window.MinionsOther = { renderProjects, renderMcpServers, renderMetrics, renderTokenUsage };
+function renderContextPressure(metrics) {
+  const el = document.getElementById('context-pressure-content');
+  if (!el) return;
+  const cp = metrics._contextPressure;
+  if (!cp || !cp.dispatches) {
+    el.innerHTML = '<p class="empty">No context pressure data yet. Data appears after agents complete tasks.</p>';
+    return;
+  }
+  const avgTurns = (cp.totalTurns / cp.dispatches).toFixed(1);
+  const turnLimitPct = ((cp.turnLimitHits / cp.dispatches) * 100).toFixed(1);
+  const pctColor = parseFloat(turnLimitPct) > 20 ? 'var(--red)' : parseFloat(turnLimitPct) > 5 ? 'var(--yellow, orange)' : 'var(--green)';
+
+  let html = '<div class="token-tiles">';
+  html += '<div class="token-tile"><div class="token-tile-label">Avg Turns</div><div class="token-tile-value">' + avgTurns + '</div><div class="token-tile-sub">per dispatch</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Max Turns</div><div class="token-tile-value">' + cp.maxTurns + '</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Hit Turn Limit</div><div class="token-tile-value" style="color:' + pctColor + '">' + turnLimitPct + '%</div><div class="token-tile-sub">' + cp.turnLimitHits + ' of ' + cp.dispatches + ' dispatches</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Total Dispatches</div><div class="token-tile-value">' + cp.dispatches + '</div></div>';
+  html += '</div>';
+  el.innerHTML = html;
+}
+
+window.MinionsOther = { renderProjects, renderMcpServers, renderMetrics, renderTokenUsage, renderContextPressure };

package/dashboard/pages/engine.html

@@ -10,3 +10,7 @@
         <h2>Token Usage</h2>
         <div id="token-usage-content"><p class="empty">No usage data yet.</p></div>
       </section>
+      <section>
+        <h2>Context Pressure</h2>
+        <div id="context-pressure-content"><p class="empty">No context pressure data yet. Data appears after agents complete tasks.</p></div>
+      </section>

package/engine/ado.js

@@ -5,10 +5,10 @@
 
 const path = require('path');
 const shared = require('./shared');
-const { exec, getAdoOrgBase, addPrLink } = shared;
+const { exec, getAdoOrgBase, addPrLink, log, dateStamp } = shared;
 const { getPrs } = require('./queries');
 
-// Lazy require to avoid circular dependency
+// Lazy require to avoid circular dependency — only needed for engine().handlePostMerge
 let _engine = null;
 function engine() {
   if (!_engine) _engine = require('../engine');
@@ -37,7 +37,7 @@ function getAdoToken() {
       return token;
     }
   } catch (e) {
-    engine().log('warn', `Failed to get ADO token: ${e.message}`);
+    log('warn', `Failed to get ADO token: ${e.message}`);
   }
   // Back off for 10 minutes to avoid spamming browser auth popups
   _adoTokenFailedUntil = Date.now() + 10 * 60 * 1000;
@@ -57,7 +57,7 @@ async function adoFetch(url, token, _retryCount = 0) {
     if (_retryCount < MAX_RETRIES) {
       const freshToken = getAdoToken();
       if (freshToken) {
-        engine().log('info', 'ADO token expired mid-session — refreshed and retrying');
+        log('info', 'ADO token expired mid-session — refreshed and retrying');
         return adoFetch(url, freshToken, _retryCount + 1);
       }
     }
@@ -94,7 +94,7 @@ async function forEachActivePr(config, token, callback) {
         const updated = await callback(project, pr, prNum, orgBase);
         if (updated) projectUpdated++;
       } catch (err) {
-        try { engine().log('warn', `Failed to poll status for ${pr.id}: ${err.message}`); } catch { /* engine not available */ }
+        log('warn', `Failed to poll status for ${pr.id}: ${err.message}`);
       }
     }
 
@@ -110,10 +110,9 @@ async function forEachActivePr(config, token, callback) {
 // ─── PR Status Polling ───────────────────────────────────────────────────────
 
 async function pollPrStatus(config) {
-  const e = engine();
   const token = getAdoToken();
   if (!token) {
-    e.log('warn', 'Skipping PR status poll — no ADO token available');
+    log('warn', 'Skipping PR status poll — no ADO token available');
     return;
   }
 
@@ -129,14 +128,14 @@ async function pollPrStatus(config) {
     else if (prData.status === 'active') newStatus = 'active';
 
     if (pr.status !== newStatus) {
-      e.log('info', `PR ${pr.id} status: ${pr.status} → ${newStatus}`);
+      log('info', `PR ${pr.id} status: ${pr.status} → ${newStatus}`);
       pr.status = newStatus;
       updated = true;
 
       if (newStatus === 'merged' || newStatus === 'abandoned') {
         if (pr.reviewStatus === 'waiting') {
           pr.reviewStatus = newStatus === 'merged' ? 'approved' : 'pending';
-          e.log('info', `PR ${pr.id} reviewStatus: waiting → ${pr.reviewStatus} (${newStatus})`);
+          log('info', `PR ${pr.id} reviewStatus: waiting → ${pr.reviewStatus} (${newStatus})`);
         }
         await engine().handlePostMerge(pr, project, config, newStatus);
       }
@@ -153,7 +152,7 @@ async function pollPrStatus(config) {
     }
 
     if (pr.reviewStatus !== newReviewStatus) {
-      e.log('info', `PR ${pr.id} reviewStatus: ${pr.reviewStatus} → ${newReviewStatus}`);
+      log('info', `PR ${pr.id} reviewStatus: ${pr.reviewStatus} → ${newReviewStatus}`);
       pr.reviewStatus = newReviewStatus;
       updated = true;
       // Update author metrics when verdict changes to approved/rejected
@@ -167,7 +166,7 @@ async function pollPrStatus(config) {
             if (newReviewStatus === 'approved') metrics[authorId].prsApproved = (metrics[authorId].prsApproved || 0) + 1;
             else metrics[authorId].prsRejected = (metrics[authorId].prsRejected || 0) + 1;
             shared.safeWrite(metricsPath, metrics);
-          } catch (err) { try { engine().log('warn', `Metrics update: ${err.message}`); } catch { /* engine not available */ } }
+          } catch (err) { log('warn', `Metrics update: ${err.message}`); }
         }
       }
     }
@@ -209,7 +208,7 @@ async function pollPrStatus(config) {
     }
 
     if (pr.buildStatus !== buildStatus) {
-      e.log('info', `PR ${pr.id} build: ${pr.buildStatus || 'none'} → ${buildStatus}${buildFailReason ? ' (' + buildFailReason + ')' : ''}`);
+      log('info', `PR ${pr.id} build: ${pr.buildStatus || 'none'} → ${buildStatus}${buildFailReason ? ' (' + buildFailReason + ')' : ''}`);
       pr.buildStatus = buildStatus;
       if (buildFailReason) pr.buildFailReason = buildFailReason;
       else delete pr.buildFailReason;
@@ -221,14 +220,13 @@ async function pollPrStatus(config) {
   });
 
   if (totalUpdated > 0) {
-    e.log('info', `PR status poll: updated ${totalUpdated} PR(s)`);
+    log('info', `PR status poll: updated ${totalUpdated} PR(s)`);
   }
 }
 
 // ─── Poll Human Comments on PRs ──────────────────────────────────────────────
 
 async function pollPrHumanComments(config) {
-  const e = engine();
   const token = getAdoToken();
   if (!token) return;
 
@@ -285,12 +283,12 @@ async function pollPrHumanComments(config) {
       feedbackContent
     };
 
-    e.log('info', `PR ${pr.id}: ${newHumanComments.length} new comment(s), ${allHumanComments.length} total — full thread context provided`);
+    log('info', `PR ${pr.id}: ${newHumanComments.length} new comment(s), ${allHumanComments.length} total — full thread context provided`);
     return true;
   });
 
   if (totalUpdated > 0) {
-    e.log('info', `PR comment poll: found human feedback on ${totalUpdated} PR(s)`);
+    log('info', `PR comment poll: found human feedback on ${totalUpdated} PR(s)`);
   }
 }
 
@@ -301,10 +299,9 @@ async function pollPrHumanComments(config) {
  * in pull-requests.json, and add them. Matches PRs to work items by branch name.
  */
 async function reconcilePrs(config) {
-  const e = engine();
   const token = getAdoToken();
   if (!token) {
-    e.log('warn', 'Skipping PR reconciliation — no ADO token available');
+    log('warn', 'Skipping PR reconciliation — no ADO token available');
     return;
   }
 
@@ -322,7 +319,7 @@ async function reconcilePrs(config) {
     try {
       prData = await adoFetch(url, token);
     } catch (err) {
-      e.log('warn', `PR reconciliation failed for ${project.name}: ${err.message}`);
+      log('warn', `PR reconciliation failed for ${project.name}: ${err.message}`);
       continue;
     }
 
@@ -379,14 +376,14 @@ async function reconcilePrs(config) {
         branch,
         reviewStatus: 'pending',
         status: 'active',
-        created: (adoPr.creationDate || '').slice(0, 10) || e.dateStamp(),
+        created: (adoPr.creationDate || '').slice(0, 10) || dateStamp(),
         url: prUrl,
         prdItems: confirmedItemId ? [confirmedItemId] : [],
       });
       if (confirmedItemId) addPrLink(prId, confirmedItemId);
       existingIds.add(prId);
       projectAdded++;
-      e.log('info', `PR reconciliation: added ${prId} (branch: ${branch}${confirmedItemId ? ', linked to ' + confirmedItemId : ''}) to ${project.name}`);
+      log('info', `PR reconciliation: added ${prId} (branch: ${branch}${confirmedItemId ? ', linked to ' + confirmedItemId : ''}) to ${project.name}`);
     }
 
     // Backfill prdItems from pr-links for any PR with empty array
@@ -404,12 +401,12 @@ async function reconcilePrs(config) {
     if (projectAdded > 0 || projectUpdated > 0 || backfilled > 0) {
       shared.safeWrite(prPath, existingPrs);
       totalAdded += projectAdded;
-      if (projectUpdated > 0) e.log('info', `PR reconciliation: linked ${projectUpdated} existing PR(s) to PRD items in ${project.name}`);
+      if (projectUpdated > 0) log('info', `PR reconciliation: linked ${projectUpdated} existing PR(s) to PRD items in ${project.name}`);
     }
   }
 
   if (totalAdded > 0) {
-    e.log('info', `PR reconciliation: added ${totalAdded} missing PR(s) across projects`);
+    log('info', `PR reconciliation: added ${totalAdded} missing PR(s) across projects`);
   }
 }
 

package/engine/cleanup.js

@@ -8,7 +8,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { exec, execSilent } = shared;
+const { exec, execSilent, log, ts } = shared;
 const { safeJson, safeWrite, safeReadDir, getProjects, projectWorkItemsPath, projectPrPath,
   sanitizeBranch, KB_CATEGORIES } = shared;
 const { getDispatch, getAgentStatus } = queries;
@@ -20,10 +20,9 @@ const PRD_DIR = queries.PRD_DIR;
 const PLANS_DIR = queries.PLANS_DIR;
 
 // Lazy require to break circular dependency with engine.js
+// Only needed for engine().activeProcesses — log/ts come from shared.js
 let _engine = null;
 function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
-function log(level, msg, meta) { return engine().log(level, msg, meta); }
-function ts() { return engine().ts(); }
 
 // Lazy require for dispatch module
 let _dispatch = null;

package/engine/cooldown.js

@@ -7,13 +7,9 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeJson, safeWrite } = shared;
+const { safeJson, safeWrite, log } = shared;
 const { ENGINE_DIR } = queries;
 
-// Lazy require to avoid circular dependency with engine.js
-let _engine = null;
-function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
-
 const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 const dispatchCooldowns = new Map(); // key → { timestamp, failures }
 
@@ -27,7 +23,7 @@ function loadCooldowns() {
       dispatchCooldowns.set(k, v);
     }
   }
-  engine().log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
+  log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
 }
 
 let _cooldownWriteTimer = null;
@@ -85,7 +81,7 @@ function setCooldownFailure(key) {
   const failures = (existing?.failures || 0) + 1;
   dispatchCooldowns.set(key, { timestamp: Date.now(), failures });
   if (failures >= 3) {
-    engine().log('warn', `${key} has failed ${failures} times — cooldown is now ${Math.min(Math.pow(2, failures), 8)}x`);
+    log('warn', `${key} has failed ${failures} times — cooldown is now ${Math.min(Math.pow(2, failures), 8)}x`);
   }
   saveCooldowns();
 }

package/engine/github.js

@@ -5,11 +5,11 @@
  */
 
 const shared = require('./shared');
-const { exec, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, MINIONS_DIR, addPrLink, getPrLinks } = shared;
+const { exec, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeWrite, MINIONS_DIR, addPrLink, getPrLinks, log, dateStamp } = shared;
 const { getPrs } = require('./queries');
 const path = require('path');
 
-// Lazy require to avoid circular dependency
+// Lazy require to avoid circular dependency — only needed for engine().handlePostMerge
 let _engine = null;
 function engine() {
   if (!_engine) _engine = require('../engine');
@@ -37,7 +37,7 @@ function ghApi(endpoint, slug) {
     const result = exec(cmd, { timeout: 30000, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
     return JSON.parse(result);
   } catch (e) {
-    engine().log('warn', `GitHub API error (${endpoint}): ${e.message}`);
+    log('warn', `GitHub API error (${endpoint}): ${e.message}`);
     return null;
   }
 }
@@ -66,7 +66,7 @@ async function forEachActiveGhPr(config, callback) {
         const updated = await callback(project, pr, prNum, slug);
         if (updated) projectUpdated++;
       } catch (err) {
-        try { engine().log('warn', `GitHub: failed to poll PR ${pr.id}: ${err.message}`); } catch { /* engine not available */ }
+        log('warn', `GitHub: failed to poll PR ${pr.id}: ${err.message}`);
       }
     }
 
@@ -101,7 +101,7 @@ async function forEachActiveGhPr(config, callback) {
         centralUpdated++;
       }
     } catch (err) {
-      try { engine().log('warn', `GitHub: failed to poll central PR ${pr.id}: ${err.message}`); } catch { /* engine not available */ }
+      log('warn', `GitHub: failed to poll central PR ${pr.id}: ${err.message}`);
     }
   }
   if (centralUpdated > 0) {
@@ -115,8 +115,6 @@ async function forEachActiveGhPr(config, callback) {
 // ─── PR Status Polling ──────────────────────────────────────────────────────
 
 async function pollPrStatus(config) {
-  const e = engine();
-
   const totalUpdated = await forEachActiveGhPr(config, async (project, pr, prNum, slug) => {
     const prData = ghApi(`/pulls/${prNum}`, slug);
     if (!prData) return false;
@@ -130,7 +128,7 @@ async function pollPrStatus(config) {
     else if (prData.state === 'open') newStatus = 'active';
 
     if (pr.status !== newStatus) {
-      e.log('info', `PR ${pr.id} status: ${pr.status} → ${newStatus}`);
+      log('info', `PR ${pr.id} status: ${pr.status} → ${newStatus}`);
       pr.status = newStatus;
       updated = true;
 
@@ -138,7 +136,7 @@ async function pollPrStatus(config) {
         // Resolve stale 'waiting' review status — won't be polled again after this
         if (pr.reviewStatus === 'waiting') {
           pr.reviewStatus = newStatus === 'merged' ? 'approved' : 'pending';
-          e.log('info', `PR ${pr.id} reviewStatus: waiting → ${pr.reviewStatus} (${newStatus})`);
+          log('info', `PR ${pr.id} reviewStatus: waiting → ${pr.reviewStatus} (${newStatus})`);
         }
         await engine().handlePostMerge(pr, project, config, newStatus);
       }
@@ -162,7 +160,7 @@ async function pollPrStatus(config) {
       else if (states.length > 0) newReviewStatus = 'pending';
 
       if (pr.reviewStatus !== newReviewStatus) {
-        e.log('info', `PR ${pr.id} reviewStatus: ${pr.reviewStatus} → ${newReviewStatus}`);
+        log('info', `PR ${pr.id} reviewStatus: ${pr.reviewStatus} → ${newReviewStatus}`);
         pr.reviewStatus = newReviewStatus;
         updated = true;
         // Update author metrics when verdict changes to approved/rejected
@@ -176,7 +174,7 @@ async function pollPrStatus(config) {
               if (newReviewStatus === 'approved') metrics[authorId].prsApproved = (metrics[authorId].prsApproved || 0) + 1;
               else metrics[authorId].prsRejected = (metrics[authorId].prsRejected || 0) + 1;
               shared.safeWrite(metricsPath, metrics);
-            } catch (err) { try { engine().log('warn', `Metrics update: ${err.message}`); } catch { /* engine not available */ } }
+            } catch (err) { log('warn', `Metrics update: ${err.message}`); }
           }
         }
       }
@@ -207,7 +205,7 @@ async function pollPrStatus(config) {
         }
 
         if (pr.buildStatus !== buildStatus) {
-          e.log('info', `PR ${pr.id} build: ${pr.buildStatus || 'none'} → ${buildStatus}${buildFailReason ? ' (' + buildFailReason + ')' : ''}`);
+          log('info', `PR ${pr.id} build: ${pr.buildStatus || 'none'} → ${buildStatus}${buildFailReason ? ' (' + buildFailReason + ')' : ''}`);
           pr.buildStatus = buildStatus;
           if (buildFailReason) pr.buildFailReason = buildFailReason;
           else delete pr.buildFailReason;
@@ -221,15 +219,13 @@ async function pollPrStatus(config) {
   });
 
   if (totalUpdated > 0) {
-    e.log('info', `GitHub PR status poll: updated ${totalUpdated} PR(s)`);
+    log('info', `GitHub PR status poll: updated ${totalUpdated} PR(s)`);
   }
 }
 
 // ─── Poll Human Comments on PRs ─────────────────────────────────────────────
 
 async function pollPrHumanComments(config) {
-  const e = engine();
-
   const totalUpdated = await forEachActiveGhPr(config, async (project, pr, prNum, slug) => {
     // Get issue comments (general PR comments)
     const comments = ghApi(`/issues/${prNum}/comments`, slug);
@@ -292,19 +288,18 @@ async function pollPrHumanComments(config) {
       feedbackContent
     };
 
-    e.log('info', `PR ${pr.id}: ${newComments.length} new comment(s), ${allCommentEntries.length} total — full thread context provided`);
+    log('info', `PR ${pr.id}: ${newComments.length} new comment(s), ${allCommentEntries.length} total — full thread context provided`);
     return true;
   });
 
   if (totalUpdated > 0) {
-    e.log('info', `GitHub PR comment poll: found human feedback on ${totalUpdated} PR(s)`);
+    log('info', `GitHub PR comment poll: found human feedback on ${totalUpdated} PR(s)`);
   }
 }
 
 // ─── PR Reconciliation ──────────────────────────────────────────────────────
 
 async function reconcilePrs(config) {
-  const e = engine();
   const projects = getProjects(config).filter(isGitHub);
   const branchPatterns = [/^work\//i, /^feat\//i, /^user\/yemishin\//i];
   let totalAdded = 0;
@@ -365,7 +360,7 @@ async function reconcilePrs(config) {
         branch,
         reviewStatus: 'pending',
         status: 'active',
-        created: (ghPr.created_at || '').slice(0, 10) || e.dateStamp(),
+        created: (ghPr.created_at || '').slice(0, 10) || dateStamp(),
         url: prUrl,
         prdItems: confirmedItemId ? [confirmedItemId] : [],
       });
@@ -373,7 +368,7 @@ async function reconcilePrs(config) {
       existingIds.add(prId);
       projectAdded++;
 
-      e.log('info', `GitHub PR reconciliation: added ${prId} (branch: ${branch}${confirmedItemId ? ', linked to ' + confirmedItemId : ''}) to ${project.name}`);
+      log('info', `GitHub PR reconciliation: added ${prId} (branch: ${branch}${confirmedItemId ? ', linked to ' + confirmedItemId : ''}) to ${project.name}`);
     }
 
     // Backfill prdItems from pr-links for any PR with empty array
@@ -395,7 +390,7 @@ async function reconcilePrs(config) {
   }
 
   if (totalAdded > 0) {
-    e.log('info', `GitHub PR reconciliation: added ${totalAdded} missing PR(s)`);
+    log('info', `GitHub PR reconciliation: added ${totalAdded} missing PR(s)`);
   }
 }
 

package/engine/lifecycle.js

@@ -932,6 +932,30 @@ function createReviewFeedbackForAuthor(reviewerAgentId, pr, config) {
   if (wrote) log('info', `Created review feedback for ${authorAgentId} from ${reviewerAgentId} on ${pr.id}`);
 }
 
+function recordContextPressureOnWorkItem(meta, turnCount, outputLogSizeBytes, hitTurnLimit) {
+  const itemId = meta.item?.id;
+  if (!itemId) return;
+
+  let wiPath;
+  if (meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout') {
+    wiPath = path.join(MINIONS_DIR, 'work-items.json');
+  } else if (meta.source === 'work-item' && meta.project?.name) {
+    wiPath = path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json');
+  }
+  if (!wiPath) return;
+
+  shared.mutateJsonFileLocked(wiPath, (items) => {
+    if (!Array.isArray(items)) return items;
+    const target = items.find(i => i.id === itemId);
+    if (target) {
+      target._turnCount = turnCount;
+      target._outputLogSizeBytes = outputLogSizeBytes;
+      target._hitTurnLimit = hitTurnLimit;
+    }
+    return items;
+  }, { defaultValue: [] });
+}
+
 function updateMetrics(agentId, dispatchItem, result, taskUsage, prsCreatedCount, model) {
 
   const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
@@ -977,6 +1001,20 @@ function updateMetrics(agentId, dispatchItem, result, taskUsage, prsCreatedCount
   for (const day of Object.keys(metrics._daily)) {
     if (day < cutoffStr) delete metrics._daily[day];
   }
+
+  // Update contextPressure aggregate
+  if (taskUsage && taskUsage.numTurns > 0) {
+    if (!metrics._contextPressure) metrics._contextPressure = { totalTurns: 0, dispatches: 0, maxTurns: 0, turnLimitHits: 0 };
+    const cp = metrics._contextPressure;
+    cp.totalTurns += taskUsage.numTurns;
+    cp.dispatches++;
+    if (taskUsage.numTurns > cp.maxTurns) cp.maxTurns = taskUsage.numTurns;
+    // Check if this dispatch hit the turn limit
+    const engineConfig = require('./queries').getConfig()?.engine || {};
+    const turnLimit = engineConfig.maxTurns || 100;
+    if (taskUsage.numTurns >= turnLimit) cp.turnLimitHits++;
+  }
+
   shared.safeWrite(metricsPath, metrics);
 }
 
@@ -1089,6 +1127,23 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
     // If decomposition produced nothing, fall through to mark parent as done
   }
 
+  // Record context utilization metrics on the work item
+  if (meta?.item?.id) {
+    try {
+      const engineConfig = (config.engine || {});
+      const turnLimit = engineConfig.maxTurns || 100;
+      const turnCount = taskUsage?.numTurns || 0;
+      const hitTurnLimit = turnCount >= turnLimit;
+      let outputLogSizeBytes = 0;
+      try {
+        const liveLogPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
+        const stat = fs.statSync(liveLogPath);
+        outputLogSizeBytes = stat.size;
+      } catch { /* file may not exist */ }
+      recordContextPressureOnWorkItem(meta, turnCount, outputLogSizeBytes, hitTurnLimit);
+    } catch (err) { log('warn', `Context pressure record: ${err.message}`); }
+  }
+
   if (isSuccess && meta?.item?.id && !skipDoneStatus) updateWorkItemStatus(meta, 'done', '');
   if (!isSuccess && meta?.item?.id) {
     // Auto-retry: read fresh _retryCount from file (not stale dispatch-time snapshot)
@@ -1289,6 +1344,7 @@ module.exports = {
   updateAgentHistory,
   createReviewFeedbackForAuthor,
   updateMetrics,
+  recordContextPressureOnWorkItem,
   parseAgentOutput,
   runPostCompletionHooks,
   syncPrdFromPrs,

package/engine/meeting.js

@@ -14,8 +14,7 @@ const { renderPlaybook } = require('./playbook');
 /** Patterns that indicate an agent returned no meaningful output */
 const EMPTY_OUTPUT_PATTERNS = ['(no output)', '(no findings)', '(no response)'];
 
-let _engine = null;
-function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
+// No lazy require needed — log comes from shared.js, no engine-specific APIs used
 
 const MEETINGS_DIR = path.join(__dirname, '..', 'meetings');
 
@@ -79,8 +78,12 @@ function discoverMeetingWork(config) {
     const agents = config.agents || {};
 
     if (roundName === 'concluding') {
-      // Only one agent concludes (first participant)
-      const concluder = meeting.participants[0];
+      // Pick the first non-busy participant as concluder (fallback to any participant)
+      const busyAgents = new Set(
+        (dispatch.active || []).map(d => d.agent).filter(Boolean)
+      );
+      const concluder = meeting.participants.find(p => !busyAgents.has(p))
+        || meeting.participants[0];
       if (!concluder) continue;
       const key = `meeting-${meeting.id}-r${round}-${concluder}`;
       if (activeKeys.has(key)) continue;
@@ -179,7 +182,6 @@ function discoverMeetingWork(config) {
  * Called from runPostCompletionHooks when type === 'meeting'.
  */
 function collectMeetingFindings(meetingId, agentId, roundName, output) {
-  const e = engine();
   const meeting = getMeeting(meetingId);
   if (!meeting) return;
 
@@ -188,7 +190,7 @@ function collectMeetingFindings(meetingId, agentId, roundName, output) {
 
   // Validate output — reject empty or placeholder responses
   if (!rawContent || EMPTY_OUTPUT_PATTERNS.includes(rawContent)) {
-    e.log('warn', `Meeting ${meetingId}: agent ${agentId} returned empty output for ${roundName} — rejecting`);
+    log('warn', `Meeting ${meetingId}: agent ${agentId} returned empty output for ${roundName} — rejecting`);
     // Don't record it — agent will be re-dispatched on next tick
     saveMeeting(meeting);
     return;
@@ -304,7 +306,6 @@ function deleteMeeting(id) {
  * Called from engine.js tick cycle.
  */
 function checkMeetingTimeouts(config) {
-  const e = engine();
   const meetings = getMeetings();
   const timeout = (config.engine || {}).meetingRoundTimeout
     || ENGINE_DEFAULTS.meetingRoundTimeout;
@@ -324,21 +325,21 @@ function checkMeetingTimeouts(config) {
     const totalCount = meeting.participants.length;
 
     if (meeting.status === 'investigating') {
-      e.log('warn', `Meeting ${meeting.id}: round 1 timed out after ${Math.round(elapsed / 60000)}min — ${respondedCount}/${totalCount} responded, advancing to debate`);
+      log('warn', `Meeting ${meeting.id}: round 1 timed out after ${Math.round(elapsed / 60000)}min — ${respondedCount}/${totalCount} responded, advancing to debate`);
       meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round 1 timed out — ${respondedCount}/${totalCount} findings received`, at: new Date().toISOString() });
       meeting.status = 'debating';
       meeting.round = 2;
       meeting.roundStartedAt = new Date().toISOString();
       saveMeeting(meeting);
     } else if (meeting.status === 'debating') {
-      e.log('warn', `Meeting ${meeting.id}: round 2 timed out after ${Math.round(elapsed / 60000)}min — ${respondedCount}/${totalCount} responded, advancing to conclusion`);
+      log('warn', `Meeting ${meeting.id}: round 2 timed out after ${Math.round(elapsed / 60000)}min — ${respondedCount}/${totalCount} responded, advancing to conclusion`);
       meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round 2 timed out — ${respondedCount}/${totalCount} debate responses received`, at: new Date().toISOString() });
       meeting.status = 'concluding';
       meeting.round = 3;
       meeting.roundStartedAt = new Date().toISOString();
       saveMeeting(meeting);
     } else if (meeting.status === 'concluding') {
-      e.log('warn', `Meeting ${meeting.id}: conclusion round timed out after ${Math.round(elapsed / 60000)}min — ending meeting without conclusion`);
+      log('warn', `Meeting ${meeting.id}: conclusion round timed out after ${Math.round(elapsed / 60000)}min — ending meeting without conclusion`);
       meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: 'Conclusion round timed out — meeting ended without conclusion', at: new Date().toISOString() });
       meeting.status = 'completed';
       meeting.completedAt = new Date().toISOString();

package/engine/playbook.js

@@ -206,9 +206,25 @@ function resolveTaskContext(item, config) {
   return resolved;
 }
 
+// ─── Critical Variable Definitions ─────────────────────────────────────────
+// Variables that MUST resolve to non-empty values for dispatch to proceed.
+// If any critical variable is empty or unresolved, renderPlaybook returns null.
+const CRITICAL_VARS = {
+  'implement': ['task_description', 'branch_name'],
+  'implement-shared': ['task_description', 'branch_name'],
+  'fix': ['task_description', 'branch_name'],
+  'work-item': ['task_description'],
+};
+
+// Module-level error state — callers check via getLastRenderError() after null return
+let _lastRenderError = null;
+
+function getLastRenderError() { return _lastRenderError; }
+
 // ─── Playbook Renderer ──────────────────────────────────────────────────────
 
 function renderPlaybook(type, vars) {
+  _lastRenderError = null;
   const pbPath = path.join(PLAYBOOKS_DIR, `${type}.md`);
   let content;
   try { content = fs.readFileSync(pbPath, 'utf8'); } catch {
@@ -290,15 +306,27 @@ function renderPlaybook(type, vars) {
     .filter(([, val]) => String(val) === '')
     .map(([key]) => key);
   if (emptyVars.length > 0) {
-    const msg = `Playbook "${type}": template variables resolved to empty string: ${emptyVars.join(', ')}`;
-    try { engine().log('warn', msg); } catch { /* engine not ready */ }
+    log('warn', `Playbook "${type}": template variables resolved to empty string: ${emptyVars.join(', ')}`);
   }
 
   // Warn on any remaining unresolved {{variable}} placeholders
   const unresolved = [...new Set((content.match(/\{\{(\w+)\}\}/g) || []).map(m => m.slice(2, -2)))];
   if (unresolved.length > 0) {
-    const msg = `Playbook "${type}": unresolved template variables: ${unresolved.join(', ')}`;
-    try { engine().log('warn', msg); } catch { /* engine not ready */ }
+    log('warn', `Playbook "${type}": unresolved template variables: ${unresolved.join(', ')}`);
+  }
+
+  // Block dispatch if critical variables are empty or unresolved
+  const criticalVars = CRITICAL_VARS[type] || [];
+  if (criticalVars.length > 0) {
+    const emptySet = new Set(emptyVars);
+    const unresolvedSet = new Set(unresolved);
+    const criticalMissing = criticalVars.filter(v => emptySet.has(v) || unresolvedSet.has(v));
+    if (criticalMissing.length > 0) {
+      const msg = `Playbook "${type}": critical variables empty or unresolved: ${criticalMissing.join(', ')} — blocking dispatch`;
+      log('warn', msg);
+      _lastRenderError = { reason: 'critical_vars_missing', vars: criticalMissing, message: msg };
+      return null;
+    }
   }
 
   return content;
@@ -472,6 +500,8 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
 
 module.exports = {
   renderPlaybook,
+  getLastRenderError,
+  CRITICAL_VARS,
   buildSystemPrompt,
   buildAgentContext,
   selectPlaybook,

package/engine/routing.js

@@ -8,16 +8,12 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeJson, safeRead } = shared;
+const { safeJson, safeRead, log, ts } = shared;
 const { ENGINE_DIR, DISPATCH_PATH } = queries;
 
 const MINIONS_DIR = path.resolve(__dirname, '..');
 const ROUTING_PATH = path.join(MINIONS_DIR, 'routing.md');
 
-// Lazy require to avoid circular dependency with engine.js
-let _engine = null;
-function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
-
 // ─── Temp Agents ─────────────────────────────────────────────────────────────
 
 const tempAgents = new Map(); // tempAgentId → { name, role, createdAt }
@@ -140,8 +136,8 @@ function resolveAgent(workType, config, authorAgent = null) {
   if (config.engine?.allowTempAgents) {
     const tempId = `temp-${shared.uid()}`;
     _claimedAgents.add(tempId);
-    tempAgents.set(tempId, { name: `Temp-${tempId.slice(5, 9)}`, role: 'Temporary Agent', createdAt: engine().ts() });
-    engine().log('info', `Spawning temp agent ${tempId} — all permanent agents busy`);
+    tempAgents.set(tempId, { name: `Temp-${tempId.slice(5, 9)}`, role: 'Temporary Agent', createdAt: ts() });
+    log('info', `Spawning temp agent ${tempId} — all permanent agents busy`);
     return tempId;
   }
 

package/engine/timeout.js

@@ -8,16 +8,15 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeRead, safeWrite, safeJson, getProjects, projectWorkItemsPath, ENGINE_DEFAULTS: DEFAULTS } = shared;
+const { safeRead, safeWrite, safeJson, getProjects, projectWorkItemsPath, log, ts, ENGINE_DEFAULTS: DEFAULTS } = shared;
 const { getDispatch, getAgentStatus } = queries;
 const AGENTS_DIR = queries.AGENTS_DIR;
 const MINIONS_DIR = shared.MINIONS_DIR;
 
 // Lazy require to break circular dependency with engine.js
+// Only needed for engine().activeProcesses and engine().engineRestartGraceUntil — log/ts come from shared.js
 let _engine = null;
 function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
-function log(level, msg, meta) { return engine().log(level, msg, meta); }
-function ts() { return engine().ts(); }
 
 // Lazy require for dispatch module (also circular via engine)
 let _dispatch = null;

package/engine.js

@@ -120,7 +120,7 @@ const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
 
 // ─── Playbook, system prompt, agent context (extracted to engine/playbook.js) ─
 
-const { renderPlaybook, buildSystemPrompt, buildAgentContext, selectPlaybook,
+const { renderPlaybook, getLastRenderError, buildSystemPrompt, buildAgentContext, selectPlaybook,
   buildBaseVars, buildPrDispatch, resolveTaskContext,
   getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
 
@@ -1493,9 +1493,17 @@ function discoverFromWorkItems(config, project) {
     if (playbookName === 'work-item' && workType === '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 rendered = renderPlaybook(playbookName, vars);
+    const renderError = getLastRenderError();
+    // If critical vars are missing, block dispatch entirely — don't fall through to work-item playbook
+    const prompt = item.prompt || rendered || (renderError ? null : (renderPlaybook('work-item', vars) || item.description));
     if (!prompt) {
-      log('warn', `No playbook rendered for ${item.id} (type: ${workType}, playbook: ${playbookName}) — skipping`);
+      if (renderError) {
+        log('warn', `Skipping ${item.id}: ${renderError.message}`);
+        if (item._pendingReason !== 'critical_vars_missing') { item._pendingReason = 'critical_vars_missing'; needsWrite = true; }
+      } else {
+        log('warn', `No playbook rendered for ${item.id} (type: ${workType}, playbook: ${playbookName}) — skipping`);
+      }
       continue;
     }
 
@@ -1782,9 +1790,16 @@ function discoverCentralWorkItems(config) {
         }
 
         const playbookName = selectPlaybook(workType, item);
-        const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
+        const rendered = renderPlaybook(playbookName, vars);
+        const renderError = getLastRenderError();
+        const prompt = rendered || (renderError ? null : renderPlaybook('work-item', vars));
         if (!prompt) {
-          log('warn', `Fan-out: playbook '${playbookName}' failed to render for ${item.id} → ${agent.id}, skipping`);
+          if (renderError) {
+            log('warn', `Fan-out: ${item.id} → ${agent.id}: ${renderError.message}`);
+            if (item._pendingReason !== 'critical_vars_missing') { item._pendingReason = 'critical_vars_missing'; }
+          } else {
+            log('warn', `Fan-out: playbook '${playbookName}' failed to render for ${item.id} → ${agent.id}, skipping`);
+          }
           continue;
         }
 
@@ -1894,9 +1909,16 @@ function discoverCentralWorkItems(config) {
       }
 
       const playbookName = selectPlaybook(workType, item);
-      const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
+      const rendered = renderPlaybook(playbookName, vars);
+      const renderError = getLastRenderError();
+      const prompt = rendered || (renderError ? null : renderPlaybook('work-item', vars));
       if (!prompt) {
-        log('warn', `Dispatch: playbook '${playbookName}' failed to render for ${item.id}, resetting to pending`);
+        if (renderError) {
+          log('warn', `Dispatch: ${item.id}: ${renderError.message}`);
+          item._pendingReason = 'critical_vars_missing';
+        } else {
+          log('warn', `Dispatch: playbook '${playbookName}' failed to render for ${item.id}, resetting to pending`);
+        }
         item.status = 'pending';
         continue;
       }
@@ -2378,6 +2400,7 @@ module.exports = {
 
   // Playbooks
   renderPlaybook,
+  getLastRenderError,
 
   // Timeout / Steering / Idle (re-exported from engine/timeout.js)
   checkTimeouts, checkSteering, checkIdleThreshold,

package/package.json

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