@yemi33/minions 0.1.726 → 0.1.728

package/CHANGELOG.md

@@ -1,8 +1,21 @@
 # Changelog
 
-## 0.1.726 (2026-04-09)
+## 0.1.728 (2026-04-09)
 
-### Fixes
+### Features
+- replace raw status strings with WI_STATUS constants in dashboard.js
+- Soften playbook CAPS emphasis and add context-awareness guidance
+-  Add structured completion protocol to PR-producing playbooks
+-  Create engine/recovery.js with recovery recipes
+-  Add FAILURE_CLASS enum and classifyFailure() function
+-  Add AGENT_STATUS enum and worker-state tracking
+-  Validate required template variables before dispatch
+- make post-verify plan archiving opt-in via autoArchive config
+
+### Fixes
+-  repair 3 pre-existing test failures in source-pattern tests
+-  merge master, sync dashboard-build jsFiles, bump HTML size limit
+-  resolve 4 pre-existing test failures breaking CI
 -  reject JSON/UUID fragments as PR titles, self-heal from platform
 
 ## 0.1.725 (2026-04-09)

package/dashboard/js/render-plans.js

@@ -183,7 +183,11 @@ function renderPlans(plans) {
     let prdJsonStatus = p.status || 'active';
     if (prdFile && p.format !== 'prd') {
       const linkedPrd = plans.find(pp => pp.file === prdFile && pp.format === 'prd');
-      if (linkedPrd) prdJsonStatus = linkedPrd.status || prdJsonStatus;
+      if (linkedPrd) {
+        prdJsonStatus = linkedPrd.status || prdJsonStatus;
+        // Propagate archiveReady from PRD to source .md plan card
+        if (linkedPrd.archiveReady) p.archiveReady = true;
+      }
       else if (!linkedPrd) {
         const archivedPrd = archivedPlans.find(pp => pp.file === prdFile && pp.format === 'prd');
         if (archivedPrd) prdJsonStatus = 'completed';
@@ -245,8 +249,12 @@ function renderPlans(plans) {
       'onclick="event.stopPropagation();triggerVerify(\'' + escHtml(prdFile) + '\',this)">Verify</button>' : '';
     const showArchive = !isArchived;
     const archiveFile = prdFile || p.file;
-    const archiveBtn = showArchive ? '<button class="pr-pager-btn" style="font-size:9px;padding:2px 8px" ' +
-      'onclick="event.stopPropagation();planArchive(\'' + escHtml(archiveFile) + '\',this)">Archive</button>' : '';
+    const archiveReady = p.archiveReady && !isArchived;
+    const archiveBtn = showArchive ? '<button class="pr-pager-btn" style="font-size:9px;padding:2px 8px' +
+      (archiveReady ? ';color:var(--green);font-weight:600;border:1px solid var(--green)' : '') + '" ' +
+      'onclick="event.stopPropagation();planArchive(\'' + escHtml(archiveFile) + '\',this)">' +
+      (archiveReady ? '✓ Archive' : 'Archive') + '</button>' : '';
+    const archiveReadyBadge = archiveReady ? '<span style="font-size:9px;font-weight:600;padding:1px 6px;border-radius:3px;background:rgba(63,185,80,0.15);color:var(--green);vertical-align:middle" title="Verification passed — ready to archive">Ready to archive</span>' : '';
     const deleteBtn = !isArchived ? '<button class="pr-pager-btn" style="font-size:9px;padding:2px 8px;color:var(--red)" ' +
       'onclick="event.stopPropagation();planDelete(\'' + escHtml(p.file) + '\')">Delete</button>' : '';
 
@@ -263,7 +271,7 @@ function renderPlans(plans) {
             (p.updatedAt ? '<span title="Last updated: ' + p.updatedAt + '">Updated ' + timeAgo(p.updatedAt) + '</span>' : '') +
             (p.completedAt ? '<span>' + p.completedAt.slice(0, 10) + '</span>' : '') +
             (p.generatedBy ? '<span>by ' + escHtml(p.generatedBy) + '</span>' : '') +
-            executeBtn + pauseBtn + resumeBtn + verifyBtn + (hasVerifyWi ? _renderVerifyBadge(verifyWi) : '') + archiveBtn + deleteBtn +
+            executeBtn + pauseBtn + resumeBtn + verifyBtn + (hasVerifyWi ? _renderVerifyBadge(verifyWi) : '') + archiveReadyBadge + archiveBtn + deleteBtn +
           '</div>' +
         '</div>' +
       '</div>' +

package/dashboard/js/render-work-items.js

@@ -40,7 +40,7 @@ function wiRow(item) {
     : (item.branchStrategy === 'shared-branch' && item.status === 'done')
       ? '<span style="font-size:9px;color:var(--muted)" title="Part of shared branch — aggregate PR created at verify stage">shared branch</span>'
       : '<span style="color:var(--muted)">—</span>';
-  return '<tr style="cursor:pointer" onclick="openWorkItemDetail(\'' + escHtml(item.id) + '\')">' +
+  return '<tr style="cursor:pointer" onclick="if(window.getSelection().toString().length>0)return;openWorkItemDetail(\'' + escHtml(item.id) + '\')">' +
     '<td><span class="pr-id">' + escHtml(item.id || '') + '</span></td>' +
     '<td style="max-width:220px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escHtml((item.title || '').slice(0, 200)) + '">' + escHtml(item.title || '') + '</td>' +
     '<td><span style="font-size:10px;color:var(--muted)">' + escHtml(item._source || '') + '</span>' +

package/dashboard/js/settings.js

@@ -47,6 +47,7 @@ async function openSettings() {
       settingsToggle('Eval Loop', 'set-evalLoop', e.evalLoop !== false, 'Auto-review implementations and iterate fix cycles until pass') +
       settingsToggle('Auto-decompose', 'set-autoDecompose', e.autoDecompose !== false, 'Large implement items are auto-split into sub-tasks') +
       settingsToggle('Allow Temp Agents', 'set-allowTempAgents', !!e.allowTempAgents, 'Spawn ephemeral agents when all permanent agents are busy') +
+      settingsToggle('Auto-archive Plans', 'set-autoArchive', !!e.autoArchive, 'Automatically archive plans after verify completes (off = manual archive via dashboard)') +
     '</div>' +
     '<div style="display:grid;grid-template-columns:1fr 1fr;gap:8px;margin-bottom:16px">' +
       settingsField('Eval Max Iterations', 'set-evalMaxIterations', e.evalMaxIterations || 3, '', 'Max review→fix cycles before escalating (1-10)') +
@@ -205,6 +206,7 @@ async function saveSettings() {
       evalLoop: document.getElementById('set-evalLoop').checked,
       autoDecompose: document.getElementById('set-autoDecompose').checked,
       allowTempAgents: document.getElementById('set-allowTempAgents').checked,
+      autoArchive: document.getElementById('set-autoArchive').checked,
       evalMaxIterations: document.getElementById('set-evalMaxIterations').value,
       evalMaxCost: document.getElementById('set-evalMaxCost').value || null,
       maxBuildFixAttempts: document.getElementById('set-maxBuildFixAttempts').value,

package/dashboard-build.js

@@ -32,7 +32,7 @@ function buildDashboardHtml() {
     'utils', 'state', 'detail-panel', 'live-stream',
     'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
     'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
-    'render-other', 'render-schedules', 'render-meetings', 'render-pinned',
+    'render-other', 'render-schedules', 'render-pipelines', 'render-meetings', 'render-pinned',
     'command-parser', 'command-input', 'command-center', 'command-history',
     'modal', 'modal-qa', 'settings', 'refresh'
   ];

package/dashboard.js

@@ -1055,12 +1055,12 @@ const server = http.createServer(async (req, res) => {
         const item = items.find(i => i.id === id);
         if (!item) return items;
         // Don't reset completed items unless explicitly forced
-        if ((item.status === 'done' || item.completedAt) && !body.force) {
+        if ((DONE_STATUSES.has(item.status) || item.completedAt) && !body.force) {
           found = 'already_done';
           return items;
         }
         found = true;
-        item.status = 'pending';
+        item.status = WI_STATUS.PENDING;
         item._retryCount = 0; // Reset retry counter on manual retry
         delete item.dispatched_at;
         delete item.dispatched_to;
@@ -1224,7 +1224,7 @@ const server = http.createServer(async (req, res) => {
       let wiPath;
       if (body.project) {
         // Write to project-specific queue
-        const targetProject = PROJECTS.find(p => p.name === body.project) || PROJECTS[0];
+        const targetProject = PROJECTS.find(p => p.name === body.project) || (PROJECTS.length > 0 ? PROJECTS[0] : null);
         if (!targetProject) return jsonReply(res, 400, { error: 'No projects configured' });
         wiPath = shared.projectWorkItemsPath(targetProject);
       } else {
@@ -1324,7 +1324,7 @@ const server = http.createServer(async (req, res) => {
       const item = {
         id, title: body.title, type: 'plan',
         priority: body.priority || 'high', description: body.description || '',
-        status: 'pending', created: new Date().toISOString(), createdBy: 'dashboard',
+        status: WI_STATUS.PENDING, created: new Date().toISOString(), createdBy: 'dashboard',
         branchStrategy: body.branch_strategy || 'parallel',
       };
       if (body.project) item.project = body.project;
@@ -1402,7 +1402,7 @@ const server = http.createServer(async (req, res) => {
         try {
           mutateWorkItems(wiPath, items => {
             const wi = items.find(w => w.sourcePlan === body.source && w.id === body.itemId);
-            if (wi && wi.status === 'pending') {
+            if (wi && wi.status === WI_STATUS.PENDING) {
               if (body.name !== undefined) wi.title = 'Implement: ' + body.name;
               if (body.description !== undefined) wi.description = body.description;
               if (body.priority !== undefined) wi.priority = body.priority;
@@ -1910,7 +1910,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
     // Load work items to check for completed plan-to-prd conversions
     const centralWi = safeJsonArr(path.join(MINIONS_DIR, 'work-items.json'));
     const completedPrdFiles = new Set(
-      centralWi.filter(w => w.type === 'plan-to-prd' && w.status === 'done' && w.planFile)
+      centralWi.filter(w => w.type === 'plan-to-prd' && DONE_STATUSES.has(w.status) && w.planFile)
         .map(w => w.planFile)
     );
     const plans = [];
@@ -1941,6 +1941,8 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
               requiresApproval: plan.requires_approval || false,
               revisionFeedback: plan.revision_feedback || null,
               sourcePlan: plan.source_plan || null,
+              archiveReady: plan._archiveReady || false,
+              archiveReadyAt: plan._archiveReadyAt || null,
             });
           } catch { /* JSON parse fallback */ }
         } else {
@@ -2237,14 +2239,14 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       mutateWorkItems(wiPath, items => {
         // Dedup: check if already queued
         const alreadyQueued = items.find(w =>
-          w.type === 'plan-to-prd' && w.planFile === plan.source_plan && (w.status === 'pending' || w.status === 'dispatched')
+          w.type === 'plan-to-prd' && w.planFile === plan.source_plan && (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.DISPATCHED)
         );
         if (alreadyQueued) { alreadyQueuedId = alreadyQueued.id; return; }
         items.push({
           id, title: `Regenerate PRD: ${plan.plan_summary || plan.source_plan}`,
           type: 'plan-to-prd', priority: 'high',
           description: `Plan file: plans/${plan.source_plan}\nTarget PRD filename: ${body.file}\nRegeneration requested by user after plan revision.${completedContext}`,
-          status: 'pending', created: new Date().toISOString(), createdBy: 'dashboard:regenerate',
+          status: WI_STATUS.PENDING, created: new Date().toISOString(), createdBy: 'dashboard:regenerate',
           project: plan.project || '', planFile: plan.source_plan,
           _targetPrdFile: body.file,
         });
@@ -2271,13 +2273,13 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       mutateJsonFileLocked(centralPath, (items) => {
         if (!Array.isArray(items)) items = [];
         // Only block if actively pending/dispatched — allow re-execute after completion
-        const existing = items.find(w => w.type === 'plan-to-prd' && w.planFile === body.file && (w.status === 'pending' || w.status === 'dispatched'));
+        const existing = items.find(w => w.type === 'plan-to-prd' && w.planFile === body.file && (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.DISPATCHED));
         if (existing) { existingId = existing.id; return items; }
         items.push({
           id, title: 'Convert plan to PRD: ' + body.file.replace('.md', ''),
           type: 'plan-to-prd', priority: 'high',
           description: 'Plan file: plans/' + body.file,
-          status: 'pending', created: new Date().toISOString(),
+          status: WI_STATUS.PENDING, created: new Date().toISOString(),
           createdBy: 'dashboard:execute', project: body.project || '',
           planFile: body.file,
         });
@@ -2332,7 +2334,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
             for (const w of items) {
               if (w.sourcePlan === body.source) {
                 materializedPlanItemIds.add(w.id);
-                if (w.status === 'pending' || w.status === 'failed') {
+                if (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.FAILED) {
                   // Delete — will re-materialize on next tick with updated plan data
                   reset++;
                   deletedItemIds.push(w.id);
@@ -2417,8 +2419,8 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
           const centralPath = path.join(MINIONS_DIR, 'work-items.json');
           mutateWorkItems(centralPath, items => {
             for (const w of items) {
-              if (w.type === 'plan-to-prd' && w.status === 'done' && w.planFile === prdSourcePlan) {
-                w.status = 'cancelled';
+              if (w.type === 'plan-to-prd' && DONE_STATUSES.has(w.status) && w.planFile === prdSourcePlan) {
+                w.status = WI_STATUS.CANCELLED;
                 w._cancelledBy = 'prd-deleted';
               }
             }
@@ -2530,7 +2532,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
           id, title: 'Revise plan: ' + (plan.plan_summary || body.file),
           type: 'plan-to-prd', priority: 'high',
           description: 'Revision requested on plan file: ' + (body.file.endsWith('.json') ? 'prd/' : 'plans/') + body.file + '\n\nFeedback:\n' + body.feedback + '\n\nRevise the plan to address this feedback. Read the existing plan, apply the feedback, and overwrite the file with the updated version. Set status back to "awaiting-approval".',
-          status: 'pending', created: new Date().toISOString(), createdBy: 'dashboard:revision',
+          status: WI_STATUS.PENDING, created: new Date().toISOString(), createdBy: 'dashboard:revision',
           project: plan.project || '',
           planFile: body.file,
         });
@@ -2629,7 +2631,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
             const filtered = [];
             for (const w of items) {
               if (w.sourcePlan === body.source) {
-                if (w.status === 'pending' || w.status === 'failed') {
+                if (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.FAILED) {
                   reset++;
                   deletedItemIds.push(w.id);
                 } else {
@@ -2660,7 +2662,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
           type: 'plan-to-prd',
           priority: 'high',
           description: `The source plan \`${sourcePlanFile}\` has been revised. Convert it into a fresh PRD JSON.\n\nRevision instruction: ${body.instruction}\n\nRead the revised plan, generate updated PRD items (missing_features), and write to \`prd/${body.source}\`. Set status to "approved". Include \`"source_plan": "${sourcePlanFile}"\` in the JSON root.\n\nPreserve items that are already done (status "implemented" or "complete"). Reset or replace items that were pending/failed.`,
-          status: 'pending',
+          status: WI_STATUS.PENDING,
           created: new Date().toISOString(),
           createdBy: 'dashboard:revise-and-regenerate',
           project: prd.project || '',
@@ -3555,7 +3557,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           config.engine.maxTurnsByType = mbt;
         }
         // Boolean fields
-        for (const key of ['autoApprovePlans', 'evalLoop', 'autoDecompose', 'allowTempAgents']) {
+        for (const key of ['autoApprovePlans', 'evalLoop', 'autoDecompose', 'allowTempAgents', 'autoArchive']) {
           if (e[key] !== undefined) config.engine[key] = !!e[key];
         }
         // Eval loop settings

package/engine/dispatch.js

@@ -11,7 +11,7 @@ const { setCooldownFailure } = require('./cooldown');
 
 const { safeJson, safeWrite, safeReadDir, mutateJsonFileLocked, mutateWorkItems,
   mutatePullRequests, getProjects, projectWorkItemsPath, projectPrPath, log, ts, dateStamp,
-  WI_STATUS, DISPATCH_RESULT, ENGINE_DEFAULTS } = shared;
+  WI_STATUS, DISPATCH_RESULT, ENGINE_DEFAULTS, AGENT_STATUS, FAILURE_CLASS } = shared;
 const { getConfig, getDispatch, DISPATCH_PATH, INBOX_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -19,6 +19,8 @@ const MINIONS_DIR = shared.MINIONS_DIR;
 // Lazy require to break circular dependency with engine.js
 let _lifecycle = null;
 function lifecycle() { if (!_lifecycle) _lifecycle = require('./lifecycle'); return _lifecycle; }
+let _recovery = null;
+function recovery() { if (!_recovery) _recovery = require('./recovery'); return _recovery; }
 
 // ─── Dispatch Mutation ───────────────────────────────────────────────────────
 
@@ -69,7 +71,12 @@ function addToDispatch(item) {
 
 // ─── Retryable Failure Classification ────────────────────────────────────────
 
-function isRetryableFailureReason(reason = '') {
+function isRetryableFailureReason(reason = '', failureClass = '') {
+  // FAILURE_CLASS-based classification takes precedence when available
+  if (failureClass) {
+    const neverRetry = new Set([FAILURE_CLASS.CONFIG_ERROR, FAILURE_CLASS.PERMISSION_BLOCKED]);
+    if (neverRetry.has(failureClass)) return false;
+  }
   const r = String(reason || '').toLowerCase();
   if (!r) return true; // unknown error from tool exit — keep retryable
   const nonRetryable = [
@@ -89,7 +96,7 @@ function isRetryableFailureReason(reason = '') {
 // ─── Complete Dispatch ───────────────────────────────────────────────────────
 
 function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', resultSummary = '', opts = {}) {
-  const { processWorkItemFailure = true } = opts;
+  const { processWorkItemFailure = true, failureClass } = opts;
   let item = null;
 
   mutateDispatch((dispatch) => {
@@ -108,6 +115,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     item.result = result;
     if (reason) item.reason = reason;
     if (resultSummary) item.resultSummary = resultSummary;
+    if (failureClass && result === DISPATCH_RESULT.ERROR) item.failureClass = failureClass;
     delete item.prompt;
     if (dispatch.completed.length >= 100) {
       dispatch.completed = dispatch.completed.slice(-100);
@@ -120,7 +128,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     log('info', `Completed dispatch: ${id} (${result}${reason ? ': ' + reason : ''})`);
 
     // Update source work item status on failure + auto-retry with backoff
-    const retryableFailure = isRetryableFailureReason(reason);
+    const retryableFailure = isRetryableFailureReason(reason, failureClass);
     if (result === DISPATCH_RESULT.ERROR && item.meta?.dispatchKey && retryableFailure) setCooldownFailure(item.meta.dispatchKey);
 
     if (processWorkItemFailure && result === DISPATCH_RESULT.ERROR && item.meta?.item?.id) {
@@ -130,8 +138,10 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
         if (wi) retries = wi._retryCount || 0;
       } catch (e) { log('warn', 'read retry count: ' + e.message); }
       const maxRetries = ENGINE_DEFAULTS.maxRetries;
-      if (retryableFailure && retries < maxRetries) {
-        log('info', `Dispatch error for ${item.meta.item.id} — auto-retry ${retries + 1}/${maxRetries}`);
+      // Use per-class retry limits from recovery.js when failureClass is available
+      const classAllowsRetry = failureClass ? recovery().shouldRetry(failureClass, retries) : (retries < maxRetries);
+      if (retryableFailure && classAllowsRetry) {
+        log('info', `Dispatch error for ${item.meta.item.id} — auto-retry ${retries + 1}/${maxRetries}${failureClass ? ' [' + failureClass + ']' : ''}`);
         lifecycle().updateWorkItemStatus(item.meta, WI_STATUS.PENDING, '');
         // Remove this dispatch key from completed so dedupe doesn't block immediate redispatch.
         if (item.meta?.dispatchKey) {
@@ -227,6 +237,29 @@ function writeInboxAlert(slug, content) {
   } catch (e) { log('warn', 'write inbox alert: ' + e.message); }
 }
 
+// ─── Agent Worker Status ────────────────────────────────────────────────────
+
+/**
+ * Update the worker-state fields on an active dispatch entry.
+ * Uses mutateDispatch() for atomic read-modify-write.
+ * @param {string} dispatchId — dispatch entry ID
+ * @param {string} status — one of AGENT_STATUS values
+ * @param {string} [detail] — optional human-readable detail string
+ */
+function updateAgentStatus(dispatchId, status, detail) {
+  if (!dispatchId || !status) return;
+  mutateDispatch((dispatch) => {
+    const entry = (dispatch.active || []).find(d => d.id === dispatchId)
+      || (dispatch.pending || []).find(d => d.id === dispatchId);
+    if (entry) {
+      entry.workerState = status;
+      entry.workerStateAt = ts();
+      if (detail !== undefined) entry.workerStateDetail = detail;
+    }
+    return dispatch;
+  });
+}
+
 // ─── Exports ─────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -235,4 +268,5 @@ module.exports = {
   isRetryableFailureReason,
   completeDispatch,
   writeInboxAlert,
+  updateAgentStatus,
 };

package/engine/lifecycle.js

@@ -9,7 +9,7 @@ const os = require('os');
 const shared = require('./shared');
 const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, execSilent, projectPrPath, getPrLinks, addPrLink,
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
-  ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS } = shared;
+  ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
 const queries = require('./queries');
 const { getConfig, getInboxFiles, getNotes, getPrs, getDispatch,
@@ -1101,6 +1101,49 @@ function parseAgentOutput(stdout) {
   return { resultSummary: text, taskUsage: usage, sessionId, model };
 }
 
+/**
+ * Parse structured completion block from agent output.
+ * Agents produce a ```completion fenced block with key: value pairs.
+ * Returns parsed object or null if not found / malformed.
+ * If multiple blocks exist, the last one wins (agent may retry).
+ */
+function parseStructuredCompletion(stdout) {
+  if (!stdout || typeof stdout !== 'string') return null;
+
+  // Extract text from stream-json output if needed
+  let text = stdout;
+  if (stdout.includes('"type":')) {
+    try {
+      const parsed = shared.parseStreamJsonOutput(stdout);
+      if (parsed.text) text = parsed.text;
+    } catch {}
+  }
+
+  // Find all ```completion blocks, take the last one
+  const blockPattern = /```completion\s*\n([\s\S]*?)```/g;
+  let lastMatch = null;
+  let m;
+  while ((m = blockPattern.exec(text)) !== null) {
+    lastMatch = m[1];
+  }
+  if (!lastMatch) return null;
+
+  // Parse key: value pairs
+  const result = {};
+  const lines = lastMatch.trim().split('\n');
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 1) continue;
+    const key = line.slice(0, colonIdx).trim().toLowerCase();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key && value) result[key] = value;
+  }
+
+  // Must have at least the status field to be valid
+  if (!result.status) return null;
+  return result;
+}
+
 /**
  * Handle decomposition result — parse sub-items from agent output and create child work items.
  * Called from runPostCompletionHooks when type === 'decompose'.
@@ -1191,6 +1234,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const result = isSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR;
   const { resultSummary, taskUsage, sessionId, model } = parseAgentOutput(stdout);
 
+  // Try structured completion protocol first (```completion block from agent output)
+  const structuredCompletion = parseStructuredCompletion(stdout);
+  if (structuredCompletion) {
+    log('info', `Structured completion from ${agentId}: status=${structuredCompletion.status}, pr=${structuredCompletion.pr || 'N/A'}`);
+  }
+
   // Save session for potential resume on next dispatch
   if (isSuccess && sessionId && agentId && !agentId.startsWith('temp-')) {
     try {
@@ -1207,6 +1256,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     prsCreatedCount = syncPrsFromOutput(stdout, agentId, meta, config) || 0;
   } catch (err) { log('warn', `PR sync from output: ${err.message}`); }
 
+  // Structured completion may report PR even when regex didn't find it
+  const scHasPr = structuredCompletion && structuredCompletion.pr && structuredCompletion.pr !== 'N/A';
+  if (scHasPr && prsCreatedCount === 0) {
+    log('info', `Structured completion reports PR (${structuredCompletion.pr}) but regex sync found none — PR may already be tracked`);
+  }
+
   // Auto-recover: if a failed implement/fix agent created PRs, it likely succeeded before being killed (e.g. heartbeat timeout)
   const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX;
   const autoRecovered = !isSuccess && prsCreatedCount > 0 && prCreatingType && !!meta?.item?.id;
@@ -1414,7 +1469,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const metricsResult = isAutoRetry ? 'retry' : finalResult;
   updateMetrics(agentId, dispatchItem, metricsResult, taskUsage, prsCreatedCount, model);
 
-  return { resultSummary, taskUsage, autoRecovered };
+  return { resultSummary, taskUsage, autoRecovered, structuredCompletion };
 }
 
 // ─── PR → PRD Status Sync ─────────────────────────────────────────────────────
@@ -1460,6 +1515,67 @@ function syncPrdFromPrs(config) {
   }
 }
 
+// ─── Failure Classification ─────────────────────────────────────────────────
+
+/**
+ * Classify an agent failure into a FAILURE_CLASS value based on exit code and output.
+ * @param {number} code — process exit code
+ * @param {string} stdout — agent stdout
+ * @param {string} stderr — agent stderr
+ * @returns {string} — one of FAILURE_CLASS values
+ */
+function classifyFailure(code, stdout = '', stderr = '') {
+  const out = String(stdout || '').toLowerCase();
+  const err = String(stderr || '').toLowerCase();
+  const combined = out + '\n' + err;
+
+  // Exit code 78 — configuration error (Claude CLI not found, bad setup)
+  if (code === 78) return FAILURE_CLASS.CONFIG_ERROR;
+
+  // Permission / trust / auth failures
+  if (/permission denied|access denied|unauthorized|403 forbidden|trust.*blocked|auth.*fail/i.test(combined)) {
+    return FAILURE_CLASS.PERMISSION_BLOCKED;
+  }
+
+  // Merge conflicts
+  if (/merge conflict|conflict.*merge|automatic merge failed|fix conflicts/i.test(combined)) {
+    return FAILURE_CLASS.MERGE_CONFLICT;
+  }
+
+  // Context window / max turns exhausted
+  if (/context window|max.*turns.*reached|token limit|conversation.*too long|context.*length.*exceeded/i.test(combined)) {
+    return FAILURE_CLASS.OUT_OF_CONTEXT;
+  }
+
+  // Network / API errors
+  if (/rate limit|429|econnrefused|enotfound|etimedout|dns.*resolution|api.*error.*5\d\d|overloaded/i.test(combined)) {
+    return FAILURE_CLASS.NETWORK_ERROR;
+  }
+
+  // Build / test / lint failures
+  if (/build failed|compilation error|test.*fail|lint.*error|type.*error|error ts\d+|syntax error|npm err/i.test(combined)) {
+    return FAILURE_CLASS.BUILD_FAILURE;
+  }
+
+  // Spawn errors — process crashed immediately or couldn't start
+  if (/spawn.*error|enoent|cannot find module|cannot find.*binary/i.test(combined)) {
+    return FAILURE_CLASS.SPAWN_ERROR;
+  }
+
+  // Empty output — agent produced nothing useful
+  if (!stdout || stdout.trim().length < 50) {
+    return FAILURE_CLASS.EMPTY_OUTPUT;
+  }
+
+  // Timeout is classified by the caller (timeout.js), not by output pattern
+  // but check for timeout markers in output as fallback
+  if (/timed.?out|timeout|heartbeat.*expired/i.test(combined)) {
+    return FAILURE_CLASS.TIMEOUT;
+  }
+
+  return FAILURE_CLASS.UNKNOWN;
+}
+
 module.exports = {
   checkPlanCompletion,
   archivePlan,
@@ -1476,9 +1592,11 @@ module.exports = {
   createReviewFeedbackForAuthor,
   updateMetrics,
   parseAgentOutput,
+  parseStructuredCompletion,
   runPostCompletionHooks,
   syncPrdFromPrs,
   resolveWorkItemPath,
   isItemCompleted,
+  classifyFailure,
 };
 

package/engine/playbook.js

@@ -206,6 +206,51 @@ function resolveTaskContext(item, config) {
   return resolved;
 }
 
+// ─── Required Template Variables ────────────────────────────────────────────
+// Defines which caller-provided variables are mandatory per playbook type.
+// Base vars (from buildBaseVars) and project vars (injected by renderPlaybook)
+// are always present and excluded. Variables in conditional blocks ({{#key}})
+// are optional by design. Only variables that make the playbook non-functional
+// when absent are listed here.
+
+const PLAYBOOK_REQUIRED_VARS = {
+  'implement':            ['item_id', 'item_name', 'branch_name', 'project_path'],
+  'implement-shared':     ['item_id', 'item_name', 'branch_name', 'worktree_path'],
+  'fix':                  ['pr_id', 'pr_branch'],
+  'review':               ['pr_id', 'pr_branch'],
+  'build-and-test':       ['pr_id', 'pr_branch', 'project_path'],
+  'explore':              ['task_description'],
+  'ask':                  ['question'],
+  'plan':                 ['task_description', 'project_path'],
+  'plan-to-prd':          ['plan_content', 'plan_file', 'prd_filename', 'project_path'],
+  'decompose':            ['item_id', 'item_description', 'project_path'],
+  'verify':               ['task_description'],
+  'test':                 ['item_name'],
+  'work-item':            ['item_id', 'item_name'],
+  'meeting-investigate':  ['meeting_title', 'agenda'],
+  'meeting-debate':       ['meeting_title', 'agenda'],
+  'meeting-conclude':     ['meeting_title', 'agenda'],
+};
+
+/**
+ * Validate that all required template variables for a playbook type are present
+ * and non-empty in the provided vars object.
+ * @param {string} playbookName - The playbook type name
+ * @param {object} vars - The template variables object
+ * @returns {{ valid: boolean, missing: string[] }}
+ */
+function validatePlaybookVars(playbookName, vars) {
+  const required = PLAYBOOK_REQUIRED_VARS[playbookName];
+  if (!required) return { valid: true, missing: [] };
+
+  const missing = required.filter(key => {
+    const val = vars[key];
+    return val === undefined || val === null || String(val).trim() === '';
+  });
+
+  return { valid: missing.length === 0, missing };
+}
+
 // ─── Playbook Renderer ──────────────────────────────────────────────────────
 
 function renderPlaybook(type, vars) {
@@ -292,6 +337,13 @@ function renderPlaybook(type, vars) {
   };
   const allVars = { ...projectVars, ...vars };
 
+  // Validate required template variables before substitution
+  const validation = validatePlaybookVars(type, allVars);
+  if (!validation.valid) {
+    log('error', `Playbook "${type}": missing required template variables: ${validation.missing.join(', ')} — skipping render`);
+    return null;
+  }
+
   // Process conditional blocks: {{#key}}...{{/key}} — include block only if key is truthy
   content = content.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (_, key, block) => {
     const val = allVars[key];
@@ -496,6 +548,8 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
 
 module.exports = {
   renderPlaybook,
+  validatePlaybookVars,
+  PLAYBOOK_REQUIRED_VARS,
   buildSystemPrompt,
   buildAgentContext,
   selectPlaybook,

package/engine/recovery.js

@@ -0,0 +1,112 @@
+/**
+ * engine/recovery.js — Recovery recipes for classified agent failures.
+ * Maps FAILURE_CLASS values to per-class retry limits and escalation policies.
+ * Zero external dependencies — uses only Node.js built-ins and imports from shared.js.
+ */
+
+const { FAILURE_CLASS, ESCALATION_POLICY, ENGINE_DEFAULTS } = require('./shared');
+
+// ─── Recovery Recipes ───────────────────────────────────────────────────────
+
+/**
+ * Each recipe defines:
+ *   maxAttempts  — max retries for this failure class (0 = never retry)
+ *   escalation   — ESCALATION_POLICY value
+ *   freshSession — whether to clear session.json before retry
+ *   description  — human-readable explanation for logs/dashboard
+ */
+const RECOVERY_RECIPES = new Map([
+  [FAILURE_CLASS.CONFIG_ERROR, {
+    maxAttempts: 0,
+    escalation: ESCALATION_POLICY.NO_RETRY,
+    freshSession: false,
+    description: 'Configuration error — fix config before retrying',
+  }],
+  [FAILURE_CLASS.PERMISSION_BLOCKED, {
+    maxAttempts: 0,
+    escalation: ESCALATION_POLICY.NO_RETRY,
+    freshSession: false,
+    description: 'Permission/trust gate blocked — requires human intervention',
+  }],
+  [FAILURE_CLASS.MERGE_CONFLICT, {
+    maxAttempts: 2,
+    escalation: ESCALATION_POLICY.RETRY_SAME,
+    freshSession: false,
+    description: 'Merge conflict — retry may succeed after dependency updates',
+  }],
+  [FAILURE_CLASS.BUILD_FAILURE, {
+    maxAttempts: 2,
+    escalation: ESCALATION_POLICY.RETRY_SAME,
+    freshSession: false,
+    description: 'Build/test failure — retry with same context for iterative fix',
+  }],
+  [FAILURE_CLASS.TIMEOUT, {
+    maxAttempts: 1,
+    escalation: ESCALATION_POLICY.RETRY_FRESH,
+    freshSession: true,
+    description: 'Timeout — retry with fresh session to avoid stuck state',
+  }],
+  [FAILURE_CLASS.EMPTY_OUTPUT, {
+    maxAttempts: 1,
+    escalation: ESCALATION_POLICY.HUMAN_REVIEW,
+    freshSession: true,
+    description: 'Empty output — agent produced nothing useful, flag for review',
+  }],
+  [FAILURE_CLASS.SPAWN_ERROR, {
+    maxAttempts: 2,
+    escalation: ESCALATION_POLICY.RETRY_FRESH,
+    freshSession: true,
+    description: 'Spawn error — retry with fresh session after transient failure',
+  }],
+  [FAILURE_CLASS.NETWORK_ERROR, {
+    maxAttempts: 3,
+    escalation: ESCALATION_POLICY.AUTO,
+    freshSession: false,
+    description: 'Network/API error — retry with exponential backoff',
+  }],
+  [FAILURE_CLASS.OUT_OF_CONTEXT, {
+    maxAttempts: 1,
+    escalation: ESCALATION_POLICY.HUMAN_REVIEW,
+    freshSession: true,
+    description: 'Context exhausted — retry with fresh session, flag if repeated',
+  }],
+  [FAILURE_CLASS.UNKNOWN, {
+    maxAttempts: null, // null = fall back to ENGINE_DEFAULTS.maxRetries
+    escalation: ESCALATION_POLICY.AUTO,
+    freshSession: false,
+    description: 'Unclassified failure — use default retry behavior',
+  }],
+]);
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Get the recovery recipe for a failure class.
+ * @param {string} failureClass — one of FAILURE_CLASS values
+ * @returns {object} recipe with maxAttempts, escalation, freshSession, description
+ */
+function getRecoveryRecipe(failureClass) {
+  return RECOVERY_RECIPES.get(failureClass) || RECOVERY_RECIPES.get(FAILURE_CLASS.UNKNOWN);
+}
+
+/**
+ * Determine whether a failed dispatch should be retried based on its failure class
+ * and current attempt count.
+ * @param {string} failureClass — one of FAILURE_CLASS values (or empty for unclassified)
+ * @param {number} attemptCount — how many times this item has already been retried
+ * @returns {boolean} true if another retry is allowed
+ */
+function shouldRetry(failureClass, attemptCount = 0) {
+  const recipe = getRecoveryRecipe(failureClass || FAILURE_CLASS.UNKNOWN);
+  // null maxAttempts = fall back to global ENGINE_DEFAULTS.maxRetries
+  const limit = recipe.maxAttempts !== null ? recipe.maxAttempts : ENGINE_DEFAULTS.maxRetries;
+  return attemptCount < limit;
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  RECOVERY_RECIPES,
+  getRecoveryRecipe,
+  shouldRetry,
+};

package/engine/shared.js

@@ -530,6 +530,7 @@ const ENGINE_DEFAULTS = {
   allowTempAgents: false, // opt-in: spawn ephemeral agents when all permanent agents are busy
   autoDecompose: true, // auto-decompose implement:large items into sub-tasks
   autoApprovePlans: false, // auto-approve PRDs without waiting for human approval
+  autoArchive: false, // opt-in: auto-archive plans after verify completes (false = mark ready, user archives manually)
   autoReview: true, // auto-dispatch review agents for new PRs (disable for manual review workflow)
   meetingRoundTimeout: 600000, // 10min per meeting round before auto-advance
   evalLoop: true, // enable review→fix loop after implementation completes
@@ -585,6 +586,33 @@ const MEETING_STATUS = {
   INVESTIGATING: 'investigating', DEBATING: 'debating', CONCLUDING: 'concluding',
   COMPLETED: 'completed', ARCHIVED: 'archived',
 };
+const AGENT_STATUS = {
+  SPAWNING: 'spawning', WORKTREE_SETUP: 'worktree-setup', READY: 'ready',
+  RUNNING: 'running', FINISHED: 'finished', FAILED: 'failed',
+  TRUST_BLOCKED: 'trust-blocked', TIMED_OUT: 'timed-out',
+};
+const FAILURE_CLASS = {
+  CONFIG_ERROR: 'config-error',           // Exit code 78, CLI not found, bad config
+  PERMISSION_BLOCKED: 'permission-blocked', // Trust gate, permission denied, auth failure
+  MERGE_CONFLICT: 'merge-conflict',       // Git merge conflict in worktree or dependency
+  BUILD_FAILURE: 'build-failure',         // Compilation, lint, or test failure
+  TIMEOUT: 'timeout',                     // Hard timeout or heartbeat timeout
+  EMPTY_OUTPUT: 'empty-output',           // Agent produced no meaningful output
+  SPAWN_ERROR: 'spawn-error',             // Process failed to start or crashed immediately
+  NETWORK_ERROR: 'network-error',         // API rate limit, DNS, connectivity
+  OUT_OF_CONTEXT: 'out-of-context',       // Context window exhausted, max turns reached
+  UNKNOWN: 'unknown',                     // Unclassified failure
+};
+const ESCALATION_POLICY = {
+  NO_RETRY: 'no-retry',         // CONFIG_ERROR, PERMISSION_BLOCKED — never retry
+  RETRY_SAME: 'retry-same',     // MERGE_CONFLICT, BUILD_FAILURE — retry same agent
+  RETRY_FRESH: 'retry-fresh',   // TIMEOUT, SPAWN_ERROR — retry with fresh session
+  HUMAN_REVIEW: 'human-review', // EMPTY_OUTPUT, OUT_OF_CONTEXT — flag for human
+  AUTO: 'auto',                 // UNKNOWN, NETWORK_ERROR — use default retry logic
+};
+
+// Structured completion protocol — fields agents must produce in ```completion blocks
+const COMPLETION_FIELDS = ['status', 'files_changed', 'tests', 'pr', 'pending', 'failure_class'];
 
 const DEFAULT_AGENT_METRICS = {
   tasksCompleted: 0, tasksErrored: 0,
@@ -911,7 +939,8 @@ module.exports = {
   classifyInboxItem,
   ENGINE_DEFAULTS,
   WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
-  PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS,
+  PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
+  FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
   DEFAULT_AGENT_METRICS,
   DEFAULT_AGENTS,
   DEFAULT_CLAUDE,

package/engine/timeout.js

@@ -9,7 +9,7 @@ const shared = require('./shared');
 const queries = require('./queries');
 
 const { safeRead, safeWrite, safeJson, mutateJsonFileLocked, getProjects, projectWorkItemsPath, log, ts,
-  ENGINE_DEFAULTS: DEFAULTS, WI_STATUS, DISPATCH_RESULT } = shared;
+  ENGINE_DEFAULTS: DEFAULTS, WI_STATUS, DISPATCH_RESULT, AGENT_STATUS } = shared;
 const { getDispatch, getAgentStatus } = queries;
 const AGENTS_DIR = queries.AGENTS_DIR;
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -138,6 +138,7 @@ function checkTimeouts(config) {
     const elapsed = Date.now() - new Date(info.startedAt).getTime();
     if (elapsed > itemTimeout) {
       log('warn', `Agent ${info.agentId} (${id}) hit hard timeout after ${Math.round(elapsed / 1000)}s — killing`);
+      dispatch().updateAgentStatus(id, AGENT_STATUS.TIMED_OUT, `Hard timeout after ${Math.round(elapsed / 1000)}s`);
       shared.killGracefully(info.proc, 5000);
     }
   }
@@ -267,12 +268,14 @@ function checkTimeouts(config) {
     if (!hasProcess && silentMs > effectiveTimeout && Date.now() > engineRestartGraceUntil) {
       // No tracked process AND no recent output past effective timeout AND grace period expired → orphaned
       log('warn', `Orphan detected: ${item.agent} (${item.id}) — no process tracked, silent for ${silentSec}s${isBlocking ? ' (blocking timeout exceeded)' : ''}`);
+      dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, `Orphaned — no process, silent for ${silentSec}s`);
       // Clear session so retry starts fresh
       try { shared.safeUnlink(path.join(AGENTS_DIR, item.agent, 'session.json')); } catch {}
       deadItems.push({ item, reason: `Orphaned — no process, silent for ${silentSec}s` });
     } else if (hasProcess && silentMs > effectiveTimeout) {
       // Has process but no output past effective timeout → hung
       log('warn', `Hung agent: ${item.agent} (${item.id}) — process exists but no output for ${silentSec}s${isBlocking ? ' (blocking timeout exceeded)' : ''}`);
+      dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, `Hung — no output for ${silentSec}s`);
       const procInfo = activeProcesses.get(item.id);
       if (procInfo) {
         shared.killGracefully(procInfo.proc, 5000);

package/engine.js

@@ -25,7 +25,7 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./engine/shared');
 const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS: DEFAULTS,
-  WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT } = shared;
+  WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT, AGENT_STATUS } = shared;
 const queries = require('./engine/queries');
 
 // ─── Paths ──────────────────────────────────────────────────────────────────
@@ -100,7 +100,7 @@ const withFileLock = shared.withFileLock;
 // ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
 
 const { mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch,
-  writeInboxAlert } = require('./engine/dispatch');
+  writeInboxAlert, updateAgentStatus } = require('./engine/dispatch');
 
 // ─── Timeout / Steering / Idle (extracted to engine/timeout.js) ──────────────
 
@@ -125,7 +125,8 @@ const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
 
 // ─── Playbook, system prompt, agent context (extracted to engine/playbook.js) ─
 
-const { renderPlaybook, buildSystemPrompt, buildAgentContext, selectPlaybook,
+const { renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS,
+  buildSystemPrompt, buildAgentContext, selectPlaybook,
   buildBaseVars, buildPrDispatch, resolveTaskContext,
   getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
 
@@ -136,7 +137,7 @@ const { renderPlaybook, buildSystemPrompt, buildAgentContext, selectPlaybook,
 const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, handlePostMerge, checkPlanCompletion,
   syncPrsFromOutput, updatePrAfterReview, updatePrAfterFix, checkForLearnings, extractSkillsFromOutput,
   updateAgentHistory, updateMetrics, createReviewFeedbackForAuthor, parseAgentOutput, syncPrdFromPrs,
-  isItemCompleted } = require('./engine/lifecycle');
+  isItemCompleted, classifyFailure } = require('./engine/lifecycle');
 
 // ─── Agent Spawner ──────────────────────────────────────────────────────────
 
@@ -278,6 +279,8 @@ async function spawnAgent(dispatchItem, config) {
   const engineConfig = config.engine || {};
   const startedAt = ts();
 
+  updateAgentStatus(id, AGENT_STATUS.SPAWNING, `Preparing ${type} task for ${agentId}`);
+
   // Resolve project context for this dispatch
   // meta.project has {name, localPath} — enrich with full config (mainBranch, repoHost, etc.)
   const metaProject = meta?.project || {};
@@ -311,6 +314,7 @@ async function spawnAgent(dispatchItem, config) {
   const _cleanupPromptFiles = () => { safeUnlink(promptPath); safeUnlink(sysPromptPath); };
 
   if (branchName) {
+    updateAgentStatus(id, AGENT_STATUS.WORKTREE_SETUP, `Setting up worktree for branch ${branchName}`);
     const wtSuffix = id ? id.split('-').pop() : shared.uid();
     const projectSlug = (project.name || 'default').replace(/[^a-zA-Z0-9_-]/g, '-');
     const wtDirName = `${projectSlug}-${branchName}-${wtSuffix}`;
@@ -491,6 +495,8 @@ async function spawnAgent(dispatchItem, config) {
     }
   }
 
+  updateAgentStatus(id, AGENT_STATUS.READY, 'Worktree ready, preparing to spawn process');
+
   // Safety check: warn if a write-capable task is running in the main repo without a worktree
   if (cwd === rootDir && ['implement', 'implement:large', 'fix', 'test', 'verify', 'plan-to-prd'].includes(type)) {
     log('warn', `Agent ${agentId} running ${type} task in main repo (no worktree) for ${id} — changes may land on master directly`);
@@ -558,6 +564,8 @@ async function spawnAgent(dispatchItem, config) {
   let stderr = '';
   let lastOutputAt = Date.now();
   let heartbeatTimer = null;
+  let _trustCheckDone = false;
+  const _spawnTime = Date.now();
 
   // Live output file — written as data arrives so dashboard can tail it
   const liveOutputPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
@@ -592,6 +600,25 @@ async function spawnAgent(dispatchItem, config) {
     if (stdout.length < MAX_OUTPUT) stdout += chunk.slice(0, MAX_OUTPUT - stdout.length);
     try { fs.appendFileSync(liveOutputPath, chunk); } catch { /* optional */ }
 
+    // Trust gate detection: check first 30s of output for trust/permission prompts
+    if (!_trustCheckDone && (Date.now() - _spawnTime) <= 30000) {
+      const lower = chunk.toLowerCase();
+      if (/\b(trust this|do you trust|allow access|grant permission|approve tools?|permission prompt)\b/.test(lower)) {
+        _trustCheckDone = true;
+        updateAgentStatus(id, AGENT_STATUS.TRUST_BLOCKED, 'Agent appears to be waiting for trust approval');
+        log('warn', `Trust gate detected for ${agentId} (${id}) — agent may be blocked on a permission prompt`);
+        writeInboxAlert(`trust-blocked-${id}`,
+          `# Trust Gate Blocked — \`${id}\`\n\n` +
+          `**Agent:** ${agentId}\n` +
+          `**Task:** ${dispatchItem.task || type}\n\n` +
+          `The agent appears to be blocked on a trust/permission prompt within 30s of spawn.\n` +
+          `Check the agent's live output and approve the trust gate manually.\n`
+        );
+      }
+    } else if (!_trustCheckDone) {
+      _trustCheckDone = true; // past 30s window
+    }
+
     // Capture sessionId early for mid-session steering
     const procInfo = activeProcesses.get(id);
     if (procInfo && !procInfo.sessionId && chunk.includes('session_id')) {
@@ -622,6 +649,10 @@ async function spawnAgent(dispatchItem, config) {
     if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
     log('info', `Agent ${agentId} (${id}) exited with code ${code}`);
 
+    // Emit worker-state transition: FINISHED or FAILED
+    updateAgentStatus(id, code === 0 ? AGENT_STATUS.FINISHED : AGENT_STATUS.FAILED,
+      code === 0 ? 'Agent completed successfully' : `Agent exited with code ${code}`);
+
     // Clear stale session if resume failed — prevents burning all retries on the same bad session
     if (code !== 0 && cachedSessionId && stderr.includes('No conversation found')) {
       log('warn', `Stale session ${cachedSessionId} for ${agentId} — clearing session.json`);
@@ -762,11 +793,14 @@ async function spawnAgent(dispatchItem, config) {
     safeWrite(archivePath, outputContent);
     safeWrite(latestPath, outputContent); // overwrite latest for dashboard compat
 
+    // Classify failure for non-zero exits
+    const failureClass = code !== 0 ? classifyFailure(code, stdout, stderr) : undefined;
+
     // Detect configuration errors (e.g. Claude CLI not found) — fail immediately with clear message
     if (code === 78) {
       const errMsg = stderr.includes('claude-code') ? stderr.trim() : 'Configuration error — Claude Code CLI not found. Install with: npm install -g @anthropic-ai/claude-code';
-      log('error', `Agent ${agentId} (${id}) failed: ${errMsg}`);
-      completeDispatch(id, DISPATCH_RESULT.ERROR, errMsg, '');
+      log('error', `Agent ${agentId} (${id}) failed: ${errMsg} [${failureClass}]`);
+      completeDispatch(id, DISPATCH_RESULT.ERROR, errMsg, '', { failureClass });
       try { fs.unlinkSync(sysPromptPath); } catch { /* cleanup */ }
       try { fs.unlinkSync(promptPath); } catch { /* cleanup */ }
       try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch { /* cleanup */ }
@@ -779,7 +813,8 @@ async function spawnAgent(dispatchItem, config) {
     // Move from active to completed in dispatch (single source of truth for agent status)
     // autoRecovered: agent failed (e.g. heartbeat timeout) but created PRs — treat as success
     const effectiveResult = (code === 0 || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR;
-    completeDispatch(id, effectiveResult, '', resultSummary);
+    const completeOpts = effectiveResult === DISPATCH_RESULT.ERROR && failureClass ? { failureClass } : {};
+    completeDispatch(id, effectiveResult, '', resultSummary, completeOpts);
 
     // Cleanup temp files (including PID file now that dispatch is complete)
     try { fs.unlinkSync(sysPromptPath); } catch { /* cleanup */ }
@@ -858,6 +893,8 @@ async function spawnAgent(dispatchItem, config) {
   // Track process — even if PID isn't available yet (async on Windows)
   activeProcesses.set(id, { proc, agentId, startedAt, sessionId: cachedSessionId });
 
+  updateAgentStatus(id, AGENT_STATUS.RUNNING, `Process spawned for ${agentId}`);
+
   // Log PID and persist to registry
   if (proc.pid) {
     log('info', `Agent process started: PID ${proc.pid}`);
@@ -2919,7 +2956,7 @@ module.exports = {
   validateConfig,
 
   // Dispatch management (re-exported from engine/dispatch.js)
-  mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch, writeInboxAlert,
+  mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch, writeInboxAlert, updateAgentStatus,
   activeProcesses, get engineRestartGraceUntil() { return engineRestartGraceUntil; },
   set engineRestartGraceUntil(v) { engineRestartGraceUntil = v; },
 
@@ -2934,7 +2971,7 @@ module.exports = {
   reconcileItemsWithPrs, detectDependencyCycles,
 
   // Playbooks
-  renderPlaybook, buildWorkItemDispatchVars,
+  renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS, buildWorkItemDispatchVars,
 
   // 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.726",
+  "version": "0.1.728",
   "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"

package/playbooks/build-and-test.md

@@ -143,9 +143,9 @@ Replace `<SHORT DESCRIPTION OF FAILURE>` and `<PASTE THE BUILD/TEST ERROR OUTPUT
 - Use the worktree path, NOT the main project path, for all commands
 - The worktree will persist after your process ends so the user can inspect it
 
-## IMPORTANT: Do NOT clean up the worktree
+## Do not clean up the worktree
 
-Leave the worktree in place at `{{project_path}}/../worktrees/bt-{{pr_number}}` — the user needs it to review the running app. The engine will clean it up after the PR is merged or closed.
+Leave the worktree in place at `{{project_path}}/../worktrees/bt-{{pr_number}}` — the user needs it to review the running app. The engine will clean it up automatically after the PR is merged or closed.
 
 
 ## When to Stop

package/playbooks/decompose.md

@@ -10,7 +10,7 @@ A work item has been flagged as too large for a single agent dispatch. Analyze t
 ## Work Item
 
 - **ID:** {{item_id}}
-- **Title:** {{item_title}}
+- **Title:** {{item_name}}
 - **Description:** {{item_description}}
 - **Complexity:** {{item_complexity}}
 - **Project:** {{project_name}} (`{{project_path}}`)

package/playbooks/fix.md

@@ -66,3 +66,18 @@ Do NOT remove the worktree — the engine handles cleanup automatically.
 
 Your task is complete once you have: (1) confirmed build and tests pass, (2) pushed the fix, and (3) commented on the PR. Do NOT continue exploring unrelated code or making additional improvements. Stop immediately.
 
+## Completion
+
+After finishing, output a structured completion block so the engine can parse your results:
+
+```completion
+status: done | partial | failed
+files_changed: <comma-separated list of key files changed>
+tests: pass | fail | skipped | N/A
+pr: PR-<number> or N/A
+failure_class: N/A
+pending: <any remaining work, or none>
+```
+
+Replace the values with your actual results. This block MUST appear in your final output.
+

package/playbooks/implement-shared.md

@@ -78,3 +78,18 @@ git push origin {{branch_name}}
 ## When to Stop
 
 Your task is complete once you have: (1) confirmed build and tests pass, and (2) pushed to the shared branch. Do NOT create a PR — the engine creates one when all plan items are done. Stop after pushing.
+
+## Completion
+
+After finishing, output a structured completion block so the engine can parse your results:
+
+```completion
+status: done | partial | failed
+files_changed: <comma-separated list of key files changed>
+tests: pass | fail | skipped | N/A
+pr: N/A
+failure_class: N/A
+pending: <any remaining work, or none>
+```
+
+Replace the values with your actual results. This block MUST appear in your final output.

package/playbooks/shared-rules.md

@@ -1,3 +1,7 @@
+## Context Window Awareness
+
+Your context window may be compacted or summarized mid-task by Claude's automatic context management. This is normal and expected for long-running tasks. Do NOT interpret compacted or truncated context as a signal to stop early, wrap up prematurely, or skip remaining work. Continue working toward your stated objective regardless of context window state — re-read key files if needed to recover context.
+
 ## Engine Rules (apply to all tasks)
 
 - Do NOT write to `agents/*/status.json` — the engine manages your status automatically.

package/playbooks/test.md

@@ -39,7 +39,7 @@ Use subagents only for genuinely parallel, independent tasks. For building, test
 - If a build or test fails, report the error clearly — don't try to fix it unless asked
 - If running a local server, report the URL (e.g., http://localhost:3000)
 
-## Run Command (IMPORTANT)
+## Run Command
 
 When the build succeeds and the task involves running a server or app, output a ready-to-paste run command using **absolute paths** so the user can launch it from any terminal. Format it exactly like this: