@yemi33/minions 0.1.144 → 0.1.145

package/CHANGELOG.md

@@ -1,17 +1,23 @@
 # Changelog
 
-## 0.1.144 (2026-04-01)
+## 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
 

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/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

@@ -78,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;

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 {
@@ -299,6 +315,20 @@ function renderPlaybook(type, vars) {
     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;
 }
 
@@ -470,6 +500,8 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
 
 module.exports = {
   renderPlaybook,
+  getLastRenderError,
+  CRITICAL_VARS,
   buildSystemPrompt,
   buildAgentContext,
   selectPlaybook,

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.144",
+  "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"