@yemi33/minions 0.1.1650 → 0.1.1652

package/engine/lifecycle.js

@@ -11,6 +11,7 @@ const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, ex
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PR_STATUS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
+const { resolveRuntime } = require('./runtimes');
 const queries = require('./queries');
 const { isBranchActive } = require('./cooldown');
 const { worktreeDirMatchesBranch } = require('./cleanup');
@@ -980,36 +981,72 @@ async function findOpenPrForBranch(meta, config) {
   return null;
 }
 
-function markMissingPrAttachment(meta, agentId, reason, resultSummary) {
+// Lightweight probe for "did the agent's output contain ANY PR URL?". Used by
+// the PR-attachment contract to distinguish silent-failure (no URL anywhere)
+// from auto-link-miss (URL present but engine couldn't canonically attach it).
+// Keep this regex roughly in sync with the gated detection in syncPrsFromOutput
+// — this is yes/no only; no capture groups required.
+function _outputContainsPrUrl(output) {
+  if (!output || typeof output !== 'string') return false;
+  const prUrlPattern = /https?:\/\/(?:github\.com\/[^\s"'\\)\]]+\/[^\s"'\\)\]]+\/pull\/\d+|(?:dev\.azure\.com|[^/\s"'\\)\]]+\.visualstudio\.com)[^\s"'\\)\]]*?pullrequest\/\d+)/i;
+  return prUrlPattern.test(output);
+}
+
+function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity) {
   const noPrWiPath = resolveWorkItemPath(meta);
+  const isHard = severity !== 'soft';
   if (noPrWiPath) {
     mutateJsonFileLocked(noPrWiPath, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === meta.item.id);
       if (!w) return data;
-      w.status = WI_STATUS.NEEDS_REVIEW;
-      w._missingPrAttachment = true;
-      w.failReason = reason;
-      w._lastReviewReason = reason;
-      delete w.completedAt;
-      delete w._noPr;
-      delete w._noPrReason;
+      if (isHard) {
+        w.status = WI_STATUS.NEEDS_REVIEW;
+        w._missingPrAttachment = true;
+        w.failReason = reason;
+        w._lastReviewReason = reason;
+        delete w.completedAt;
+        delete w._noPr;
+        delete w._noPrReason;
+      } else {
+        // Soft: don't change status or failReason — the agent did the work,
+        // we just couldn't auto-attach the PR. Surface a flag for the dashboard
+        // so the dispatch row can render a yellow "verify" badge.
+        w._unverifiedPrAttachment = true;
+        w._lastReviewReason = reason;
+      }
       return data;
     }, { skipWriteIfUnchanged: true });
   }
-  shared.writeToInbox('engine', `missing-pr-attachment-${meta.item.id}`,
-    `# PR attachment missing for ${meta.item.id}\n\n` +
-    `**Agent:** ${agentId}\n` +
-    `**Work item:** \`${meta.item.id}\` — ${meta.item.title || ''}\n` +
-    `**Type:** ${meta.item.type || 'unknown'}\n` +
-    `**Branch:** ${meta.branch || '(none)'}\n\n` +
-    `${reason}\n` +
-    (resultSummary ? `\n## Agent summary\n${resultSummary}\n` : ''),
-    null,
-    { sourceItem: meta.item.id, reason: 'missing-pr-attachment' });
+  if (isHard) {
+    shared.writeToInbox('engine', `missing-pr-attachment-${meta.item.id}`,
+      `# PR attachment missing for ${meta.item.id}\n\n` +
+      `**Agent:** ${agentId}\n` +
+      `**Work item:** \`${meta.item.id}\` — ${meta.item.title || ''}\n` +
+      `**Type:** ${meta.item.type || 'unknown'}\n` +
+      `**Branch:** ${meta.branch || '(none)'}\n\n` +
+      `${reason}\n` +
+      (resultSummary ? `\n## Agent summary\n${resultSummary}\n` : ''),
+      null,
+      { sourceItem: meta.item.id, reason: 'missing-pr-attachment' });
+  } else {
+    shared.writeToInbox('engine', `pr-auto-link-unverified-${meta.item.id}`,
+      `# PR auto-link unverified for ${meta.item.id}\n\n` +
+      `**Agent:** ${agentId}\n` +
+      `**Work item:** \`${meta.item.id}\` — ${meta.item.title || ''}\n` +
+      `**Type:** ${meta.item.type || 'unknown'}\n` +
+      `**Branch:** ${meta.branch || '(none)'}\n\n` +
+      `${reason}\n\n` +
+      `The agent's output mentioned a PR URL but the engine couldn't canonically attach it ` +
+      `(URL detection regex miss, branch lookup race, untrusted tool_use signature, etc.). ` +
+      `The work likely succeeded — verify against the project's PR list.\n` +
+      (resultSummary ? `\n## Agent summary\n${resultSummary}\n` : ''),
+      null,
+      { sourceItem: meta.item.id, reason: 'pr-auto-link-unverified' });
+  }
 }
 
-async function enforcePrAttachmentContract(type, meta, agentId, config, resultSummary) {
+async function enforcePrAttachmentContract(type, meta, agentId, config, resultSummary, output) {
   if (!isPrAttachmentRequired(type, meta?.item, meta)) return null;
   if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
 
@@ -1037,10 +1074,16 @@ async function enforcePrAttachmentContract(type, meta, agentId, config, resultSu
     if (hasCanonicalPrAttachment(meta.item.id, config)) return null;
   }
 
-  const reason = `PR-producing work item ${meta.item.id} completed without a canonically attached PR record. Successful completion requires PR.prdItems/pr-links.json to include the work item; branch names, note URLs, and _context.workItemId metadata are not sufficient.`;
-  markMissingPrAttachment(meta, agentId, reason, resultSummary);
-  log('warn', reason);
-  return { reason, itemId: meta.item.id };
+  // Distinguish "agent never claimed a PR" (hard — silent failure the contract
+  // was designed to catch) from "agent claimed a PR but engine couldn't attach
+  // it canonically" (soft — verification gap, not a failure).
+  const severity = _outputContainsPrUrl(output) ? 'soft' : 'hard';
+  const reason = severity === 'hard'
+    ? `${meta.item.id} completed but no PR URL was detected in the agent's output. Expected a PR — verify the agent didn't fail silently. (Branch: ${meta.branch || '(none)'}, agent: ${agentId})`
+    : `${meta.item.id} completed and a PR URL was found in the agent's output, but it couldn't be canonically attached. The work likely succeeded — verify by checking the PR list. (Branch: ${meta.branch || '(none)'}, agent: ${agentId})`;
+  markMissingPrAttachment(meta, agentId, reason, resultSummary, severity);
+  log(severity === 'hard' ? 'warn' : 'info', reason);
+  return { reason, itemId: meta.item.id, severity };
 }
 
 // ─── Post-Completion Hooks ──────────────────────────────────────────────────
@@ -1059,9 +1102,7 @@ function parseReviewVerdict(text) {
   // Match "VERDICT: APPROVE" or "VERDICT: REQUEST_CHANGES" (case-insensitive, optional markdown bold)
   const verdictMatch = text.match(/VERDICT[:\s]+\*{0,2}(APPROVE|REQUEST[_\s-]?CHANGES)\*{0,2}/i);
   if (verdictMatch) {
-    const v = verdictMatch[1].toUpperCase().replace(/[\s-]/g, '_');
-    if (v === 'APPROVE') return 'approved';
-    if (v.includes('CHANGES')) return 'changes-requested';
+    return normalizeReviewVerdict(verdictMatch[1]);
   }
   return null;
 }
@@ -1083,7 +1124,7 @@ function isReviewBailout(text) {
   return /bail(ing)?\s+out/i.test(text) || /already\s+posted/i.test(text);
 }
 
-async function updatePrAfterReview(agentId, pr, project, config, resultSummary) {
+async function updatePrAfterReview(agentId, pr, project, config, resultSummary, structuredCompletion = null) {
 
   if (!pr?.id) return;
 
@@ -1108,12 +1149,12 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary)
     }
   } catch (e) { log('warn', `Post-review status check for ${pr.id}: ${e.message}`); }
 
-  // Fallback: if live check returned pending (e.g., GitHub self-approval blocked), parse verdict from agent output
+  // Fallback: if live check returned pending (e.g., GitHub self-approval blocked), use the agent's completion report.
   if (!postReviewStatus) {
-    const verdict = parseReviewVerdict(resultSummary);
+    const verdict = reviewVerdictFromCompletion(structuredCompletion) || parseReviewVerdict(resultSummary);
     if (verdict) {
       postReviewStatus = verdict;
-      log('info', `Parsed review verdict from agent output for ${pr.id}: ${verdict}`);
+      log('info', `Read review verdict from agent completion for ${pr.id}: ${verdict}`);
     }
   }
 
@@ -1700,6 +1741,24 @@ function parseStructuredCompletion(stdout, runtimeName) {
   return result;
 }
 
+function parseCompletionReportFile(dispatchItem) {
+  const reportPath = dispatchItem?.meta?.completionReportPath || shared.dispatchCompletionReportPath(dispatchItem?.id);
+  if (!reportPath || !fs.existsSync(reportPath)) return null;
+  const report = safeJson(reportPath);
+  if (!report || typeof report !== 'object' || Array.isArray(report)) {
+    log('warn', `Ignoring malformed completion report for ${dispatchItem?.id || 'unknown'}: ${reportPath}`);
+    return null;
+  }
+  if (!report.status && report.outcome) report.status = report.outcome;
+  if (!report.status) {
+    log('warn', `Ignoring completion report without status for ${dispatchItem?.id || 'unknown'}: ${reportPath}`);
+    return null;
+  }
+  report._source = 'report-file';
+  report._path = reportPath;
+  return report;
+}
+
 function normalizeCompletionStatus(status) {
   return String(status || '').trim().toLowerCase().replace(/[\s_]+/g, '-');
 }
@@ -1817,6 +1876,28 @@ function deferNonTerminalCompletion(meta, detection) {
   return reason;
 }
 
+function parseCompletionBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['true', 'yes', '1'].includes(normalized)) return true;
+    if (['false', 'no', '0'].includes(normalized)) return false;
+  }
+  return undefined;
+}
+
+function normalizeReviewVerdict(verdict) {
+  const value = String(verdict || '').trim().toLowerCase().replace(/[\s-]+/g, '_');
+  if (value === 'approve' || value === 'approved') return 'approved';
+  if (value === 'request_changes' || value === 'changes_requested' || value === 'changes-requested') return 'changes-requested';
+  return null;
+}
+
+function reviewVerdictFromCompletion(completion) {
+  if (!completion || typeof completion !== 'object') return null;
+  return normalizeReviewVerdict(completion.verdict || completion.review_verdict || completion.reviewVerdict);
+}
+
 function writeNonCleanAgentReport(dispatchItem, agentId, outcome, structuredCompletion, resultSummary, exitCode) {
   if (!dispatchItem?.id || !outcome) {
     log('warn', 'Cannot write non-clean agent report without dispatch id and outcome');
@@ -1952,22 +2033,31 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // and for the foundation-only state of this plan item; downstream items
   // (P-2a6d9c4f, P-9c4f2d6a) populate dispatchItem.meta.runtimeName at spawn time.
   const runtimeName = dispatchItem.meta?.runtimeName || dispatchItem.runtimeName || 'claude';
-  const { resultSummary, taskUsage, sessionId, model } = parseAgentOutput(stdout, runtimeName);
-  const completionGateSummary = resultSummary || (typeof stdout === 'string' && !stdout.includes('"type":') ? stdout : '');
+  let { resultSummary, taskUsage, sessionId, model } = parseAgentOutput(stdout, runtimeName);
 
-  // Try structured completion protocol first (```completion block from agent output)
-  const structuredCompletion = parseStructuredCompletion(stdout, runtimeName);
+  // Prefer the sidecar completion report; keep fenced output as a compatibility fallback.
+  const reportCompletion = parseCompletionReportFile(dispatchItem);
+  const structuredCompletion = reportCompletion || parseStructuredCompletion(stdout, runtimeName);
   if (structuredCompletion) {
-    log('info', `Structured completion from ${agentId}: status=${structuredCompletion.status}, pr=${structuredCompletion.pr || 'N/A'}`);
+    if (structuredCompletion.summary) resultSummary = String(structuredCompletion.summary);
+    log('info', `Structured completion from ${agentId}: status=${structuredCompletion.status}, pr=${structuredCompletion.pr || 'N/A'}${structuredCompletion._source ? ` (${structuredCompletion._source})` : ''}`);
   }
+  const completionGateSummary = resultSummary || (typeof stdout === 'string' && !stdout.includes('"type":') ? stdout : '');
 
   // Save session for potential resume on next dispatch
   if (isSuccess && sessionId && agentId && !agentId.startsWith('temp-')) {
     try {
-      shared.safeWrite(path.join(AGENTS_DIR, agentId, 'session.json'), {
-        sessionId, dispatchId: dispatchItem.id, savedAt: ts(),
-        branch: dispatchItem.meta?.branch || null,
-      });
+      const runtime = resolveRuntime(runtimeName);
+      if (runtime && typeof runtime.saveSession === 'function') {
+        runtime.saveSession({
+          agentId,
+          dispatchId: dispatchItem.id,
+          branch: dispatchItem.meta?.branch || null,
+          sessionId,
+          agentsDir: AGENTS_DIR,
+          logger: { warn: (msg) => log('warn', msg) },
+        });
+      }
     } catch (err) { log('warn', `Session save: ${err.message}`); }
   }
 
@@ -1983,15 +2073,19 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     log('info', `Structured completion reports PR (${structuredCompletion.pr}) but regex sync found none — PR may already be tracked`);
   }
 
+  const completionStatus = normalizeCompletionStatus(structuredCompletion?.status);
+  const agentNeedsRerun = parseCompletionBoolean(structuredCompletion?.needs_rerun ?? structuredCompletion?.needsRerun) === true;
+  const agentReportedFailure = completionStatus.startsWith('fail') || agentNeedsRerun;
+  const agentRetryable = parseCompletionBoolean(structuredCompletion?.retryable);
+
   // Auto-recover: if a failed implement/fix/test agent created PRs, it likely succeeded before the failure surfaced.
   const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX || type === WORK_TYPE.TEST;
-  const autoRecovered = !isSuccess && prsCreatedCount > 0 && prCreatingType && !!meta?.item?.id;
+  const autoRecovered = !agentReportedFailure && !isSuccess && prsCreatedCount > 0 && prCreatingType && !!meta?.item?.id;
   if (autoRecovered) {
     log('info', `Auto-recovery: agent failed but created ${prsCreatedCount} PR(s) — upgrading ${meta.item.id} to done`);
   }
-  const effectiveSuccess = isSuccess || autoRecovered;
+  const effectiveSuccess = (isSuccess && !agentReportedFailure) || autoRecovered;
 
-  const completionStatus = normalizeCompletionStatus(structuredCompletion?.status);
   let nonCleanReportWritten = false;
   if (completionStatus.startsWith('partial') || autoRecovered || (completionStatus.startsWith('fail') && isSuccess)) {
     const outcome = completionStatus.startsWith('fail') ? 'failure' : 'partial';
@@ -2019,7 +2113,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // and after 3 such bailouts the WI flips to status=failed even though the
   // original review was posted on the first run.
   if (effectiveSuccess && type === WORK_TYPE.REVIEW && meta?.item?.id) {
-    const verdict = parseReviewVerdict(resultSummary);
+    const verdict = reviewVerdictFromCompletion(structuredCompletion) || parseReviewVerdict(resultSummary);
     if (!verdict && isReviewBailout(resultSummary)) {
       log('info', `Review ${meta.item.id} bailed out (review already posted) — treating as DONE without retry`);
     } else if (!verdict) {
@@ -2116,8 +2210,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   }
 
   if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
-    completionContractFailure = await enforcePrAttachmentContract(type, meta, agentId, config, resultSummary);
-    if (completionContractFailure) skipDoneStatus = true;
+    completionContractFailure = await enforcePrAttachmentContract(type, meta, agentId, config, resultSummary, stdout);
+    if (completionContractFailure?.severity === 'hard' || completionContractFailure?.nonTerminal) {
+      skipDoneStatus = true;
+    }
   }
 
   if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
@@ -2223,7 +2319,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // (retryCount was being deleted by done-marking before the check could read it)
   // Review verdict check similarly moved before updateWorkItemStatus(DONE) — same root cause.
 
-  if (type === WORK_TYPE.REVIEW) await updatePrAfterReview(agentId, meta?.pr, meta?.project, config, resultSummary);
+  if (type === WORK_TYPE.REVIEW) await updatePrAfterReview(agentId, meta?.pr, meta?.project, config, resultSummary, structuredCompletion);
   if (type === WORK_TYPE.FIX) {
     updatePrAfterFix(meta?.pr, meta?.project, meta?.source);
     // (#984) Sync PRD status for PR-linked features: fix work items have a different ID
@@ -2242,7 +2338,9 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
   checkForLearnings(agentId, config.agents[agentId], dispatchItem.task);
-  const finalResult = completionContractFailure ? DISPATCH_RESULT.ERROR : (effectiveSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
+  const hardContractFail = completionContractFailure?.severity === 'hard'
+    || completionContractFailure?.nonTerminal === true;
+  const finalResult = hardContractFail ? DISPATCH_RESULT.ERROR : (effectiveSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
   if (finalResult === DISPATCH_RESULT.SUCCESS) {
     extractSkillsFromOutput(stdout, agentId, dispatchItem, config);
     // Also scan inbox notes for skill blocks — agents often write skills to inbox, not stdout
@@ -2270,7 +2368,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     teams.teamsNotifyCompletion(dispatchItem, finalResult, agentId).catch(() => {});
   } catch {}
 
-  return { resultSummary, taskUsage, autoRecovered, structuredCompletion, completionContractFailure };
+  return { resultSummary, taskUsage, autoRecovered, structuredCompletion, completionContractFailure, agentReportedFailure, agentRetryable };
 }
 
 // ─── PR → PRD Status Sync ─────────────────────────────────────────────────────
@@ -2451,6 +2549,7 @@ module.exports = {
   isReviewBailout,
   parseStructuredCompletion,
   detectNonTerminalResultSummary,
+  parseCompletionReportFile,
   runPostCompletionHooks,
   syncPrdFromPrs,
   resolveWorkItemPath,

package/engine/runtimes/claude.js

@@ -25,6 +25,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { FAILURE_CLASS, safeWrite, ts } = require('../shared');
 
 const ENGINE_DIR = __dirname.replace(/[\\/]runtimes$/, '');
 const MINIONS_DIR = path.resolve(ENGINE_DIR, '..');
@@ -229,6 +230,88 @@ function buildArgs(opts = {}) {
   return args;
 }
 
+function buildSpawnFlags(opts = {}) {
+  const flags = ['--runtime', 'claude'];
+  if (opts.maxTurns != null) flags.push('--max-turns', String(opts.maxTurns));
+  if (opts.model) flags.push('--model', String(opts.model));
+  if (opts.allowedTools) flags.push('--allowedTools', String(opts.allowedTools));
+  if (opts.effort) flags.push('--effort', String(opts.effort));
+  if (opts.sessionId) flags.push('--resume', String(opts.sessionId));
+  if (opts.maxBudget != null) flags.push('--max-budget-usd', String(opts.maxBudget));
+  if (opts.bare === true) flags.push('--bare');
+  if (opts.fallbackModel) flags.push('--fallback-model', String(opts.fallbackModel));
+  if (opts.stream != null && opts.stream !== '') flags.push('--stream', String(opts.stream));
+  if (opts.disableBuiltinMcps === true) flags.push('--disable-builtin-mcps');
+  if (opts.suppressAgentsMd === true) flags.push('--no-custom-instructions');
+  if (opts.reasoningSummaries === true) flags.push('--enable-reasoning-summaries');
+  return flags;
+}
+
+function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
+  if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
+  try {
+    const sessionPath = path.join(agentsDir, agentId, 'session.json');
+    const sessionFile = _safeJson(sessionPath);
+    if (!sessionFile?.sessionId || !sessionFile.savedAt) return null;
+    const sessionAge = Date.now() - new Date(sessionFile.savedAt).getTime();
+    const sameBranch = branchName && sessionFile.branch && sessionFile.branch === branchName;
+    if (sessionAge < maxAgeMs && sameBranch) {
+      if (logger && typeof logger.info === 'function') {
+        logger.info(`Resuming session ${sessionFile.sessionId} for ${agentId} on branch ${branchName} (age: ${Math.round(sessionAge / 60000)}min)`);
+      }
+      return sessionFile.sessionId;
+    }
+  } catch (e) {
+    if (logger && typeof logger.warn === 'function') logger.warn('session resume lookup: ' + e.message);
+  }
+  return null;
+}
+
+function saveSession({ agentId, dispatchId, branch, sessionId, agentsDir, now = ts, writeJson = safeWrite, logger = console } = {}) {
+  if (!sessionId || !agentId || agentId.startsWith('temp-') || !agentsDir) return false;
+  try {
+    writeJson(path.join(agentsDir, agentId, 'session.json'), {
+      sessionId,
+      dispatchId,
+      savedAt: typeof now === 'function' ? now() : new Date().toISOString(),
+      branch: branch || null,
+    });
+    return true;
+  } catch (err) {
+    if (logger && typeof logger.warn === 'function') logger.warn(`Session save: ${err.message}`);
+    return false;
+  }
+}
+
+function detectPermissionGate(outputChunk) {
+  const lower = String(outputChunk || '').toLowerCase();
+  return /\b(trust this|do you trust|allow access|grant permission|approve tools?|permission prompt)\b/.test(lower);
+}
+
+function getPromptDeliveryMode() {
+  return 'stdin';
+}
+
+function usesSystemPromptFile({ isResume } = {}) {
+  return !isResume;
+}
+
+function _runtimeFailureClass(code) {
+  if (code === 'auth-failure' || code === 'budget-exceeded') return FAILURE_CLASS.PERMISSION_BLOCKED;
+  if (code === 'context-limit') return FAILURE_CLASS.OUT_OF_CONTEXT;
+  if (code === 'crash') return FAILURE_CLASS.SPAWN_ERROR;
+  return null;
+}
+
+function classifyFailure({ code, stdout = '', stderr = '', fallback } = {}) {
+  if (code === 78) return { failureClass: FAILURE_CLASS.CONFIG_ERROR, retryable: false, message: 'Claude configuration error' };
+  const parsed = parseError(`${stdout || ''}\n${stderr || ''}`);
+  const runtimeClass = parsed.code ? _runtimeFailureClass(parsed.code) : null;
+  if (runtimeClass) return { failureClass: runtimeClass, retryable: parsed.retriable !== false, message: parsed.message || '' };
+  const fallbackClass = typeof fallback === 'function' ? fallback(code, stdout, stderr) : FAILURE_CLASS.UNKNOWN;
+  return { failureClass: fallbackClass, retryable: parsed.retriable !== false, message: parsed.message || '' };
+}
+
 /**
  * Build the final prompt text delivered to the Claude CLI. Claude takes the
  * system prompt via `--system-prompt-file` and the user prompt via stdin, so
@@ -536,8 +619,15 @@ module.exports = {
   modelsCache: MODELS_CACHE,
   spawnScript: path.join(ENGINE_DIR, 'spawn-agent.js'),
   installHint: INSTALL_HINT,
+  buildSpawnFlags,
   buildArgs,
   buildPrompt,
+  getResumeSessionId,
+  saveSession,
+  detectPermissionGate,
+  getPromptDeliveryMode,
+  usesSystemPromptFile,
+  classifyFailure,
   resolveModel,
   parseOutput,
   parseStreamChunk,

package/engine/runtimes/copilot.js

@@ -31,6 +31,7 @@ const fs = require('fs');
 const https = require('https');
 const path = require('path');
 const { execSync } = require('child_process');
+const { FAILURE_CLASS, safeWrite, ts } = require('../shared');
 
 const ENGINE_DIR = __dirname.replace(/[\\/]runtimes$/, '');
 const isWin = process.platform === 'win32';
@@ -254,6 +255,88 @@ function buildArgs(opts = {}) {
   return args;
 }
 
+function buildSpawnFlags(opts = {}) {
+  const flags = ['--runtime', 'copilot'];
+  if (opts.maxTurns != null) flags.push('--max-turns', String(opts.maxTurns));
+  if (opts.model) flags.push('--model', String(opts.model));
+  if (opts.allowedTools) flags.push('--allowedTools', String(opts.allowedTools));
+  if (module.exports.capabilities.effortLevels && opts.effort) flags.push('--effort', String(opts.effort));
+  if (module.exports.capabilities.sessionResume && opts.sessionId) flags.push('--resume', String(opts.sessionId));
+  if (module.exports.capabilities.budgetCap && opts.maxBudget != null) flags.push('--max-budget-usd', String(opts.maxBudget));
+  if (module.exports.capabilities.bareMode && opts.bare === true) flags.push('--bare');
+  if (module.exports.capabilities.fallbackModel && opts.fallbackModel) flags.push('--fallback-model', String(opts.fallbackModel));
+  if (opts.stream != null && opts.stream !== '') flags.push('--stream', String(opts.stream));
+  if (opts.disableBuiltinMcps === true) flags.push('--disable-builtin-mcps');
+  if (opts.suppressAgentsMd === true) flags.push('--no-custom-instructions');
+  if (opts.reasoningSummaries === true) flags.push('--enable-reasoning-summaries');
+  return flags;
+}
+
+function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
+  if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
+  try {
+    const sessionPath = path.join(agentsDir, agentId, 'session.json');
+    const sessionFile = _safeJson(sessionPath);
+    if (!sessionFile?.sessionId || !sessionFile.savedAt) return null;
+    const sessionAge = Date.now() - new Date(sessionFile.savedAt).getTime();
+    const sameBranch = branchName && sessionFile.branch && sessionFile.branch === branchName;
+    if (sessionAge < maxAgeMs && sameBranch) {
+      if (logger && typeof logger.info === 'function') {
+        logger.info(`Resuming session ${sessionFile.sessionId} for ${agentId} on branch ${branchName} (age: ${Math.round(sessionAge / 60000)}min)`);
+      }
+      return sessionFile.sessionId;
+    }
+  } catch (e) {
+    if (logger && typeof logger.warn === 'function') logger.warn('session resume lookup: ' + e.message);
+  }
+  return null;
+}
+
+function saveSession({ agentId, dispatchId, branch, sessionId, agentsDir, now = ts, writeJson = safeWrite, logger = console } = {}) {
+  if (!sessionId || !agentId || agentId.startsWith('temp-') || !agentsDir) return false;
+  try {
+    writeJson(path.join(agentsDir, agentId, 'session.json'), {
+      sessionId,
+      dispatchId,
+      savedAt: typeof now === 'function' ? now() : new Date().toISOString(),
+      branch: branch || null,
+    });
+    return true;
+  } catch (err) {
+    if (logger && typeof logger.warn === 'function') logger.warn(`Session save: ${err.message}`);
+    return false;
+  }
+}
+
+function detectPermissionGate() {
+  return false;
+}
+
+function getPromptDeliveryMode() {
+  return 'stdin';
+}
+
+function usesSystemPromptFile() {
+  return false;
+}
+
+function _runtimeFailureClass(code) {
+  if (code === 'auth-failure' || code === 'budget-exceeded') return FAILURE_CLASS.PERMISSION_BLOCKED;
+  if (code === 'unknown-model') return FAILURE_CLASS.CONFIG_ERROR;
+  if (code === 'rate-limit') return FAILURE_CLASS.NETWORK_ERROR;
+  if (code === 'crash') return FAILURE_CLASS.SPAWN_ERROR;
+  return null;
+}
+
+function classifyFailure({ code, stdout = '', stderr = '', fallback } = {}) {
+  if (code === 78) return { failureClass: FAILURE_CLASS.CONFIG_ERROR, retryable: false, message: 'Copilot configuration error' };
+  const parsed = parseError(`${stdout || ''}\n${stderr || ''}`);
+  const runtimeClass = parsed.code ? _runtimeFailureClass(parsed.code) : null;
+  if (runtimeClass) return { failureClass: runtimeClass, retryable: parsed.retriable !== false, message: parsed.message || '' };
+  const fallbackClass = typeof fallback === 'function' ? fallback(code, stdout, stderr) : FAILURE_CLASS.UNKNOWN;
+  return { failureClass: fallbackClass, retryable: parsed.retriable !== false, message: parsed.message || '' };
+}
+
 // ── Prompt Construction ─────────────────────────────────────────────────────
 //
 // Copilot has no --system-prompt-file flag, so we deliver the system prompt
@@ -681,8 +764,15 @@ module.exports = {
   // Use the same wrapper as Claude — spawn-agent.js is runtime-agnostic per P-9c4f2d6a
   spawnScript: path.join(ENGINE_DIR, 'spawn-agent.js'),
   installHint: INSTALL_HINT,
+  buildSpawnFlags,
   buildArgs,
   buildPrompt,
+  getResumeSessionId,
+  saveSession,
+  detectPermissionGate,
+  getPromptDeliveryMode,
+  usesSystemPromptFile,
+  classifyFailure,
   resolveModel,
   parseOutput,
   parseStreamChunk,

package/engine/shared.js

@@ -230,6 +230,12 @@ function dispatchPromptSidecarPath(dispatchId) {
   return path.join(_promptContextsDir(), `${safeId}.md`);
 }
 
+function dispatchCompletionReportPath(dispatchId) {
+  if (!dispatchId) return null;
+  const safeId = String(dispatchId).replace(/[^a-zA-Z0-9._-]/g, '-');
+  return path.join(MINIONS_DIR, 'engine', 'completions', `${safeId}.json`);
+}
+
 /**
  * If the dispatch item's prompt exceeds thresholdBytes, write the full prompt
  * to engine/contexts/<id>.md and replace `item.prompt` with a short stub
@@ -716,7 +722,7 @@ const ENGINE_DEFAULTS = {
   autoFixBuilds: true, // auto-dispatch fix agents when a PR build fails
   meetingRoundTimeout: 900000, // 15min per meeting round before auto-advance
   evalLoop: true, // enable review→fix loop after implementation completes
-  evalMaxIterations: 3, // max review→fix cycles before escalating to human
+  evalMaxIterations: 3, // legacy UI/config field; engine discovery no longer enforces review→fix cycle caps
   evalMaxCost: null, // USD ceiling per work item across all eval iterations; null = no limit (gather baseline data first)
   maxRetries: 3, // max dispatch retries before marking work item as failed
   minRetryGapMs: 120000, // 2min — minimum gap between retry dispatches for the same work item; prevents tight retry loops when an idempotent agent (e.g. review bailing out on a duplicate) cannot produce the expected output (#1770)
@@ -727,7 +733,7 @@ const ENGINE_DEFAULTS = {
   logBufferSize: 50, // flush immediately when buffer exceeds this many entries
   lockRetries: 0, // no retries — single 5s timeout window with 25ms polling (200 attempts) is sufficient; stale lock recovery at 60s handles crashes
   lockRetryBackoffMs: 500, // base backoff between lock retries (doubles each attempt: 500ms, 1s, 2s, ...)
-  maxBuildFixAttempts: 3, // max consecutive auto-fix dispatch cycles per PR before escalation to human
+  maxBuildFixAttempts: 3, // legacy UI/config field; engine discovery no longer enforces build-fix attempt caps
   buildFixGracePeriod: 600000, // 10min — wait for CI to run after build fix before re-dispatching
   adoPollEnabled: true, // poll ADO PR status, comments, and reconciliation on each tick cycle
   ghPollEnabled: true, // poll GitHub PR status, comments, and reconciliation on each tick cycle
@@ -1171,7 +1177,7 @@ const ESCALATION_POLICY = {
 };
 
 // Structured completion protocol — fields agents must produce in ```completion blocks
-const COMPLETION_FIELDS = ['status', 'files_changed', 'tests', 'pr', 'pending', 'failure_class'];
+const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'pending', 'failure_class', 'retryable', 'needs_rerun', 'verdict'];
 
 const DEFAULT_AGENT_METRICS = {
   tasksCompleted: 0, tasksErrored: 0,
@@ -1778,6 +1784,39 @@ function findPrRecord(prs, prRef, project = null) {
   return numberMatches.length === 1 ? numberMatches[0] : null;
 }
 
+function snapshotPrRecord(pr) {
+  if (pr === undefined) return undefined;
+  return JSON.parse(JSON.stringify(pr));
+}
+
+function _jsonEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function _isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function applyPrFieldDelta(target, before, after) {
+  if (!target || typeof target !== 'object' || !after || typeof after !== 'object') return target;
+  before = before && typeof before === 'object' ? before : {};
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  for (const key of keys) {
+    const beforeValue = before[key];
+    const afterHas = Object.prototype.hasOwnProperty.call(after, key);
+    const afterValue = after[key];
+    if (_jsonEqual(beforeValue, afterValue)) continue;
+    if (!afterHas) {
+      delete target[key];
+    } else if (_isPlainObject(beforeValue) && _isPlainObject(afterValue) && _isPlainObject(target[key])) {
+      applyPrFieldDelta(target[key], beforeValue, afterValue);
+    } else {
+      target[key] = snapshotPrRecord(afterValue);
+    }
+  }
+  return target;
+}
+
 function normalizePrRecord(pr, project = null) {
   if (!pr || typeof pr !== 'object') return false;
   let changed = false;
@@ -2271,6 +2310,7 @@ module.exports = {
   safeUnlink,
   PROMPT_CONTEXTS_DIR,
   dispatchPromptSidecarPath,
+  dispatchCompletionReportPath,
   sidecarDispatchPrompt,
   resolveDispatchPrompt,
   deleteDispatchPromptSidecar,
@@ -2325,6 +2365,8 @@ module.exports = {
   isPrCompatibleWithProject,
   getCanonicalPrId,
   findPrRecord,
+  snapshotPrRecord,
+  applyPrFieldDelta,
   normalizePrRecord,
   normalizePrRecords,
   upsertPullRequestRecord,