create-principles-disciple 1.0.0 → 1.74.0

package/plugin/templates/langs/zh/skills/ai-sprint-orchestration/scripts/run.mjs

@@ -0,0 +1,3455 @@
+// Packaged AI sprint orchestrator entrypoint.
+// Canonical repo copy lives at packages/openclaw-plugin/templates/langs/zh/skills/ai-sprint-orchestration/scripts/run.mjs.
+// Keep this package-local copy in sync only for package CLI, validation, and runtime-layout changes.
+
+import { spawnSync, spawn } from 'child_process';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { decideStage, buildStageMetrics, buildHandoff } from './lib/decision.mjs';
+import { ensureDir, appendText, fileExists, readJson, writeJson, writeText } from './lib/state-store.mjs';
+import { buildRolePrompt, buildStageBrief, getTaskSpec, getActiveWorkUnit } from './lib/task-specs.mjs';
+import { archiveRunById } from './lib/archive.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const referencesRoot = path.join(packageRoot, 'references');
+const defaultRuntimeRoot = path.join(packageRoot, 'runtime');
+let runtimeRoot = process.env.AI_SPRINT_RUNTIME_ROOT
+  ? path.resolve(process.env.AI_SPRINT_RUNTIME_ROOT)
+  : defaultRuntimeRoot;
+let sprintRoot = path.join(runtimeRoot, 'runs');
+let tempRoot = path.join(runtimeRoot, 'tmp');
+// Resolve acpx binary path and node executable — spawn directly via node to avoid
+// shebang/env resolution issues when cron/nohup has a minimal PATH.
+const acpxBin = (() => {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  const r = spawnSync(cmd, ['acpx'], { encoding: 'utf8' });
+  if (r.status === 0) {
+    const lines = r.stdout.trim().split(/\r?\n/);
+    // On Windows, prefer .cmd file over the Unix shell script (no extension)
+    if (process.platform === 'win32') {
+      const cmdFile = lines.find(l => l.trim().toLowerCase().endsWith('.cmd'));
+      if (cmdFile) return cmdFile.trim();
+    }
+    const symlink = lines[0].trim();
+    try {
+      return fs.realpathSync(symlink);
+    } catch {
+      return symlink;
+    }
+  }
+  return 'acpx';
+})();
+const nodeBin = process.execPath; // e.g. /usr/bin/node — reliable, no PATH search needed
+// Extended env for detached child processes.
+// Linux: includes /usr/bin so the Node.js shebang (#!/usr/bin/env node) resolves
+// correctly even when cron/nohup has a minimal PATH.
+// Windows: inherit PATH as-is — nodeBin is absolute, no PATH search needed.
+const acpxEnv = process.platform === 'win32'
+  ? { ...process.env }
+  : {
+      ...process.env,
+      PATH: `${process.env.PATH ?? ''}:/usr/local/bin:/usr/bin:/bin`,
+    };
+
+// On Linux, ignore SIGHUP so SSH disconnect doesn't kill the orchestrator.
+// Skip in test environments to avoid interfering with test signal handling.
+if (process.platform !== 'win32' && !process.env.VITEST && process.env.NODE_ENV !== 'test') {
+  process.on('SIGHUP', () => { /* ignored — survive SSH disconnect */ });
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function configureRuntimeRoots(rootPath) {
+  runtimeRoot = path.resolve(rootPath);
+  sprintRoot = path.join(runtimeRoot, 'runs');
+  tempRoot = path.join(runtimeRoot, 'tmp');
+  process.env.AI_SPRINT_RUNTIME_ROOT = runtimeRoot;
+}
+
+function checkAcpxAvailable() {
+  return process.platform === 'win32'
+    ? spawnSync(process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', `"${acpxBin}" --version`], {
+        encoding: 'utf8',
+        shell: false,
+        timeout: 10_000,
+      })
+    : spawnSync(nodeBin, [acpxBin, '--version'], {
+        encoding: 'utf8',
+        shell: false,
+        timeout: 10_000,
+      });
+}
+
+function runSelfCheck() {
+  ensureDir(runtimeRoot);
+  ensureDir(sprintRoot);
+  ensureDir(tempRoot);
+
+  const checks = [];
+  const record = (name, ok, details) => {
+    checks.push({ name, ok, details });
+  };
+
+  record('package_root_exists', fileExists(packageRoot), packageRoot);
+  record('references_root_exists', fileExists(referencesRoot), referencesRoot);
+  record('runtime_root_exists', fileExists(runtimeRoot), runtimeRoot);
+  record('agent_registry_exists', fileExists(path.join(referencesRoot, 'agent-registry.json')), path.join(referencesRoot, 'agent-registry.json'));
+
+  const builtInSpecs = [
+    'workflow-validation-minimal',
+    'workflow-validation-minimal-verify',
+  ];
+  for (const specId of builtInSpecs) {
+    try {
+      const spec = getTaskSpec(specId, null);
+      record(`spec:${specId}`, true, spec.title);
+    } catch (err) {
+      record(`spec:${specId}`, false, err.message);
+    }
+  }
+
+  const acpxCheck = checkAcpxAvailable();
+  record('acpx_available', acpxCheck.status === 0, (acpxCheck.stdout || acpxCheck.stderr || '').trim() || `status=${acpxCheck.status}`);
+
+  // Check which agents are available by running a quick version check
+  try {
+    const registry = readJson(path.join(referencesRoot, 'agent-registry.json'));
+    const agentNames = Object.keys(registry.agents || {});
+    for (const agentName of agentNames) {
+      try {
+        const agentCheck = process.platform === 'win32'
+          ? spawnSync(process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', `"${acpxBin}" --format quiet --timeout 30 ${agentName} exec "echo available"`], { encoding: 'utf8', shell: false, timeout: 45_000 })
+          : spawnSync(nodeBin, [acpxBin, '--format', 'quiet', '--timeout', '30', agentName, 'exec', 'echo available'], { encoding: 'utf8', shell: false, timeout: 45_000 });
+        record(`agent:${agentName}`, agentCheck.status === 0, agentCheck.status === 0 ? 'available' : `status=${agentCheck.status}`);
+      } catch (agentErr) {
+        record(`agent:${agentName}`, false, agentErr.message);
+      }
+    }
+  } catch (registryErr) {
+    record('agent_registry_read', false, registryErr.message);
+  }
+
+  const probePath = path.join(runtimeRoot, '.self-check-write-probe.tmp');
+  try {
+    fs.writeFileSync(probePath, 'ok', 'utf8');
+    fs.rmSync(probePath, { force: true });
+    record('runtime_root_writable', true, runtimeRoot);
+  } catch (err) {
+    record('runtime_root_writable', false, err.message);
+  }
+
+  const failed = checks.filter((check) => !check.ok);
+  const lines = [
+    'AI Sprint Orchestrator Self Check',
+    '',
+    `Package root: ${packageRoot}`,
+    `Runtime root: ${runtimeRoot}`,
+    '',
+    ...checks.map((check) => `${check.ok ? '[OK]' : '[FAIL]'} ${check.name}: ${check.details}`),
+  ];
+  console.log(lines.join('\n'));
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
+function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+}
+
+function makeRunId(taskId) {
+  const stamp = nowIso().replace(/[:.]/g, '-');
+  return `${stamp}-${slugify(taskId)}`;
+}
+
+function createSprintState(spec, runId, specPath) {
+  return {
+    runId,
+    taskId: spec.id,
+    title: spec.title,
+    specPath: specPath || null,
+    status: 'running',
+    currentStageIndex: 0,
+    currentStage: spec.stages[0],
+    currentWorkUnitIndex: 0,
+    currentRound: 1,
+    maxRoundsPerStage: spec.maxRoundsPerStage,
+    maxRuntimeMinutes: spec.maxRuntimeMinutes,
+    staleAfterMs: spec.staleAfterMs ?? 5 * 60 * 1000,
+    orchestratorPid: process.pid,
+    lastHeartbeatAt: nowIso(),
+    currentRole: null,
+    haltReason: null,
+    mergePending: null,
+    worktree: null,  // { worktreePath, branchName, headSha, baseBranch } — set by ensureWorktree
+    consecutiveTimeouts: {}, // { stageName: count } — tracks consecutive timeouts per stage
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+}
+
+function loadOrInitState(args) {
+  ensureDir(sprintRoot);
+
+  if (args.resume) {
+    const runDir = path.join(sprintRoot, args.resume);
+    const sprintFile = path.join(runDir, 'sprint.json');
+    if (!fileExists(sprintFile)) {
+      throw new Error(`Run not found: ${args.resume}`);
+    }
+    const state = reconcileRunState(runDir, readJson(sprintFile));
+    if (state.status === 'halted' || state.status === 'aborted') {
+      // Validate: if halted mid-stage, the previous stage must have advanced
+      // Special case: implement-pass-1 revise → implement-pass-2 is valid routing
+      if (state.currentStageIndex > 0) {
+        const prevStageName = loadSpec(state, args).stages[state.currentStageIndex - 1];
+        const prevDecisionPath = path.join(runDir, 'stages', `${String(state.currentStageIndex).padStart(2, '0')}-${prevStageName}`, 'decision.md');
+        if (fileExists(prevDecisionPath)) {
+          const prevDecisionText = fs.readFileSync(prevDecisionPath, 'utf8');
+          const outcomeMatch = prevDecisionText.match(/Outcome:\s*(\w+)/);
+          if (outcomeMatch && outcomeMatch[1] !== 'advance') {
+            // Check for special routing: implement-pass-1 revise → implement-pass-2
+            const isSpecialRoute = state.currentStage === 'implement-pass-2' && prevStageName === 'implement-pass-1' && outcomeMatch[1] === 'revise';
+            if (!isSpecialRoute) {
+              throw new Error(`Cannot resume: previous stage "${prevStageName}" outcome was "${outcomeMatch[1]}" (expected "advance"). Fix the previous stage first.`);
+            }
+          }
+        }
+      }
+      const previousStatus = state.status;
+      state.status = 'running';
+      state.haltReason = null;
+      state.orchestratorPid = process.pid;
+      state.lastHeartbeatAt = nowIso();
+      state.updatedAt = nowIso();
+      // Refresh maxRoundsPerStage from spec in case spec was updated since the sprint started
+      const spec = loadSpec(state, args);
+      if (spec.maxRoundsPerStage !== undefined && spec.maxRoundsPerStage !== state.maxRoundsPerStage) {
+        appendTimeline(runDir, `maxRoundsPerStage updated from spec: ${state.maxRoundsPerStage} → ${spec.maxRoundsPerStage}`);
+        state.maxRoundsPerStage = spec.maxRoundsPerStage;
+      }
+      writeJson(sprintFile, state);
+      appendTimeline(runDir, `Sprint resumed from ${previousStatus} by operator`);
+    }
+    return { runDir, state, resumed: true };
+  }
+
+  if (!args.task) {
+    throw new Error('Missing required --task <task-id>');
+  }
+
+  const spec = getTaskSpec(args.task, args.taskSpec);
+  const runId = makeRunId(spec.id);
+  const runDir = path.join(sprintRoot, runId);
+  const state = createSprintState(spec, runId, args.taskSpec);
+  ensureDir(runDir);
+  writeJson(path.join(runDir, 'sprint.json'), state);
+  writeText(path.join(runDir, 'timeline.md'), `# Timeline\n\n- ${nowIso()} Created sprint ${runId}\n`);
+  writeText(path.join(runDir, 'latest-summary.md'), `# Latest Summary\n\n- Status: ${state.status}\n- Stage: ${state.currentStage}\n- Round: ${state.currentRound}\n`);
+  return { runDir, state, resumed: false };
+}
+
+function saveState(runDir, state) {
+  state.updatedAt = nowIso();
+  writeJson(path.join(runDir, 'sprint.json'), state);
+}
+
+function heartbeatState(runDir, state, patch = {}) {
+  Object.assign(state, patch, {
+    orchestratorPid: process.pid,
+    lastHeartbeatAt: nowIso(),
+  });
+  saveState(runDir, state);
+}
+
+function updateSummary(runDir, lines) {
+  writeText(path.join(runDir, 'latest-summary.md'), `# Latest Summary\n\n${lines.map((line) => `- ${line}`).join('\n')}\n`);
+}
+
+function inferFailureClassification({ summary = '', blockers = [], reviewerTimeouts = null, reviewerViolations = null }) {
+  const combined = [summary, ...(blockers ?? [])].join(' ').toLowerCase();
+
+  if (/acpx|path|enoent|eacces|eprem|permission|writable|runtime root|command not found|not available|failed to spawn|spawn.*enoent|exit status|status 1|status 130|taskkill|comspec/.test(combined)) {
+    return {
+      failureClassification: 'environment issue',
+      failureSource: 'runtime environment',
+      recommendedNextAction: 'Repair the environment or required binaries, then rerun self-check and validation.',
+    };
+  }
+
+  if (/sample-spec|product-side|sample-side|openclaw-plugin|d:\\code\\openclaw|integrationphase|branchworkspace/.test(combined)) {
+    return {
+      failureClassification: 'sample-spec issue',
+      failureSource: 'sample/spec contract',
+      recommendedNextAction: 'Classify and stop. Do not reopen product-side closure work in this workflow milestone.',
+    };
+  }
+
+  if ((reviewerTimeouts?.length ?? 0) > 0 || (reviewerViolations?.length ?? 0) > 0 || /missing reports|schema violation|report invalidated|timed out|verdict|dimensions/.test(combined)) {
+    return {
+      failureClassification: 'agent behavior issue',
+      failureSource: 'role execution or report quality',
+      recommendedNextAction: 'Adjust agent profile, fallback, or prompt discipline; do not treat this as a product-side bug.',
+    };
+  }
+
+  if (/agent .*failed/.test(combined)) {
+    return {
+      failureClassification: 'environment issue',
+      failureSource: 'agent runtime',
+      recommendedNextAction: 'Check agent availability and environment setup before retrying.',
+    };
+  }
+
+  return {
+    failureClassification: 'workflow bug',
+    failureSource: 'orchestrator runtime',
+    recommendedNextAction: 'Fix the workflow plumbing, persistence, or artifact layout before retrying.',
+  };
+}
+
+function updateSummaryWithClassification(runDir, lines, classification = null) {
+  const enriched = [...lines];
+  if (classification?.failureClassification) {
+    enriched.push(`Failure classification: ${classification.failureClassification}`);
+    enriched.push(`Failure source: ${classification.failureSource}`);
+    enriched.push(`Recommended next action: ${classification.recommendedNextAction}`);
+  }
+  updateSummary(runDir, enriched);
+}
+
+function readStageFailureClassification(runDir, state) {
+  try {
+    const stageDirName = `${String(state.currentStageIndex + 1).padStart(2, '0')}-${state.currentStage}`;
+    const scorecardPath = path.join(runDir, 'stages', stageDirName, 'scorecard.json');
+    if (!fileExists(scorecardPath)) return null;
+    const scorecard = readJson(scorecardPath);
+    if (!scorecard?.failureClassification) return null;
+    return {
+      failureClassification: scorecard.failureClassification,
+      failureSource: scorecard.failureSource ?? 'n/a',
+      recommendedNextAction: scorecard.recommendedNextAction ?? 'n/a',
+    };
+  } catch {
+    return null;
+  }
+}
+
+function extractEvidenceFiles(reportText) {
+  if (!reportText) return [];
+  const matches = [
+    ...reportText.matchAll(/files_(?:checked|verified):\s*([^\n]+)/gi),
+  ];
+  return matches
+    .flatMap((match) => match[1].split(','))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function writeCheckpointSummary(stageDir, { decision, handoff = null, producer = '', reviewerA = '', reviewerB = '', globalReviewer = '' }) {
+  const verifiedFiles = Array.from(new Set([
+    ...extractEvidenceFiles(producer),
+    ...extractEvidenceFiles(reviewerA),
+    ...extractEvidenceFiles(reviewerB),
+    ...extractEvidenceFiles(globalReviewer),
+  ]));
+  const accomplished = handoff?.contractItems?.filter((item) => item.status === 'DONE').map((item) => item.deliverable) ?? [];
+  const blockers = decision.blockers?.length ? decision.blockers : ['None.'];
+  const nextFocus = handoff?.focusForNextRound
+    ?? decision.nextRunRecommendation?.reasons?.[0]
+    ?? decision.summary;
+  const lines = [
+    '## Accomplished',
+    ...(accomplished.length ? accomplished.map((item) => `- ${item}`) : ['- No contract deliverables were marked DONE in this round.']),
+    '',
+    '## Blockers',
+    ...blockers.map((item) => `- ${item}`),
+    '',
+    '## Next Focus',
+    nextFocus,
+    '',
+    '## Verified Files',
+    ...(verifiedFiles.length ? verifiedFiles.map((item) => `- ${item}`) : ['- None recorded.']),
+  ];
+  writeText(path.join(stageDir, 'checkpoint-summary.md'), `${lines.join('\n')}\n`);
+}
+
+function writeStageFailureArtifacts({ runDir, state, stageName, stageDir, decisionPath, scorecardPath, summary, blockers = [] }) {
+  const failure = inferFailureClassification({ summary, blockers });
+  writeText(decisionPath, [
+    '# Decision',
+    '',
+    `- Stage: ${stageName}`,
+    `- Round: ${state.currentRound}`,
+    '- Outcome: error',
+    '',
+    '## Summary',
+    summary,
+    '',
+    '## Blockers',
+    ...(blockers.length ? blockers.map((item) => `- ${item}`) : ['- None.']),
+    '',
+    '## Failure Classification',
+    `- Type: ${failure.failureClassification}`,
+    `- Source: ${failure.failureSource}`,
+    `- Recommended Next Action: ${failure.recommendedNextAction}`,
+    '',
+  ].join('\n'));
+  writeJson(scorecardPath, {
+    stage: stageName,
+    round: state.currentRound,
+    outcome: 'error',
+    summary,
+    blockers,
+    failureClassification: failure.failureClassification,
+    failureSource: failure.failureSource,
+    recommendedNextAction: failure.recommendedNextAction,
+    updatedAt: nowIso(),
+  });
+  updateSummaryWithClassification(runDir, [
+    `Status: ${state.status}`,
+    `Stage: ${stageName}`,
+    `Round: ${state.currentRound}`,
+    `Halt reason: ${summary}`,
+  ], failure);
+}
+
+const MAX_TIMELINE_LINES = 500;
+
+function appendTimeline(runDir, line) {
+  const tlPath = path.join(runDir, 'timeline.md');
+  appendText(tlPath, `- ${nowIso()} ${line}\n`);
+
+  // Rotate if too long
+  if (fileExists(tlPath)) {
+    const content = fs.readFileSync(tlPath, 'utf8');
+    const lineCount = content.split('\n').filter((l) => l.startsWith('- ')).length;
+    if (lineCount > MAX_TIMELINE_LINES) {
+      const archivePath = path.join(runDir, 'timeline-archive.md');
+      appendText(archivePath, content);
+      const lines = content.split('\n').filter((l) => l.startsWith('- '));
+      const kept = lines.slice(-300);
+      writeText(tlPath, `# Timeline (archived ${lineCount - 300} older entries)\n\n${kept.join('\n')}\n`);
+    }
+  }
+}
+
+function runAgent({ cwd, agent, model, prompt, timeoutSeconds = 1800, failLogPath = null, promptDir = cwd, runDir = null, roleLabel = agent }) {
+  // promptDir (default=cwd) is where we write the prompt file; must exist and be writable.
+  // On Windows, avoid os.tmpdir() (short ~ paths) and non-existent branchWorkspace dirs.
+  const promptFile = path.join(promptDir, `.ai-sprint-prompt-${Date.now()}-${Math.random().toString(16).slice(2)}.txt`);
+  fs.writeFileSync(promptFile, prompt, 'utf8');
+
+  let result;
+  try {
+    if (process.platform === 'win32') {
+      const comspec = process.env.COMSPEC || 'cmd.exe';
+      result = spawnSync(
+        comspec,
+        [
+          '/d', '/s', '/c',
+          `"${acpxBin}" --cwd "%AI_SPRINT_CWD%" --approve-all --model "%AI_SPRINT_MODEL%" --timeout "%AI_SPRINT_TIMEOUT%" ${agent} exec -f "%AI_SPRINT_PROMPT%"`,
+        ],
+        {
+          cwd,
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: (timeoutSeconds + 60) * 1000,
+          shell: false,
+          env: {
+            ...process.env,
+            AI_SPRINT_CWD: cwd,
+            AI_SPRINT_MODEL: model,
+            AI_SPRINT_TIMEOUT: String(timeoutSeconds),
+            AI_SPRINT_PROMPT: promptFile,
+          },
+        },
+      );
+    } else {
+      result = spawnSync(
+        nodeBin,
+        [acpxBin, '--cwd', cwd, '--approve-all', '--model', model, '--timeout', String(timeoutSeconds), '--prompt-retries', '2', '--suppress-reads', agent, 'exec', '-f', promptFile],
+        {
+          cwd,
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: (timeoutSeconds + 60) * 1000,
+          shell: false,
+          // Detach child process into its own session group so SIGHUP
+          // from SSH disconnect doesn't propagate to agent processes.
+          detached: true,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: acpxEnv,
+        },
+      );
+      // Fallback if resolved path is stale (e.g., npm package updated between module load and spawn)
+      if (result.error && result.error.code === 'ENOENT') {
+        result = spawnSync(
+          nodeBin,
+          [acpxBin, '--cwd', cwd, '--approve-all', '--model', model, '--timeout', String(timeoutSeconds), '--prompt-retries', '2', '--suppress-reads', agent, 'exec', '-f', promptFile],
+          {
+            cwd,
+            encoding: 'utf8',
+            maxBuffer: 10 * 1024 * 1024,
+            timeout: (timeoutSeconds + 60) * 1000,
+            shell: false,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: acpxEnv,
+          },
+        );
+      }
+    }
+  } finally {
+    fs.rmSync(promptFile, { force: true });
+  }
+
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  if (result.error || result.status !== 0) {
+    // Map acpx exit codes to semantic error types for better error classification:
+    //   0  = success
+    //   1  = runtime error (agent crash, ACP failure)
+    //   2  = usage error (bad flags, missing prompt)
+    //   3  = timeout (acpx --timeout exceeded)
+    //   4  = no session (session lost/closed)
+    //   5  = permission denied (agent approval rejected)
+    //   130 = interrupted (SIGINT/SIGHUP — SSH disconnect)
+    const exitCode = result.status ?? 1;
+    const errorType = exitCode === 3 ? 'timeout'
+      : exitCode === 4 ? 'no_session'
+        : exitCode === 5 ? 'permission_denied'
+          : exitCode === 130 ? 'interrupted'
+            : exitCode === 2 ? 'usage_error'
+              : 'runtime_error';
+
+    if ((result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') && result.pid) {
+      terminateProcessTree(result.pid, { runDir, label: roleLabel });
+    }
+    if (failLogPath) {
+      ensureDir(path.dirname(failLogPath));
+      writeText(failLogPath, `# Agent Failure Log\n\n- agent: ${agent}\n- model: ${model}\n- exitStatus: ${result.status ?? 'N/A'}\n- exitCode: ${exitCode}\n- errorType: ${errorType}\n- error: ${result.error?.message ?? 'none'}\n\n## stdout\n\n${stdout}\n\n## stderr\n\n${stderr}\n`);
+    }
+    if (result.error) throw result.error;
+    throw Object.assign(new Error(`Agent ${agent} failed with status ${result.status} (${errorType})\n${stdout.slice(0, 2000)}\n${stderr.slice(0, 2000)}`), {
+      acpxExitCode: exitCode,
+      acpxErrorType: errorType,
+    });
+  }
+
+  return stdout.trim();
+}
+
+/**
+ * Async agent runner using spawn (non-blocking) — used for parallel reviewer execution.
+ * Returns a Promise that resolves with { stdout, stderr, status } or rejects on error.
+ */
+function runAgentAsync({ cwd, agent, model, prompt, timeoutSeconds = 1800, promptDir = cwd, runDir = null, roleLabel = agent, onSpawn = null }) {
+  return new Promise((resolve, reject) => {
+    const promptFile = path.join(promptDir, `.ai-sprint-prompt-${process.pid}-${crypto.randomUUID()}.txt`);
+
+    const cleanup = () => {
+      try { fs.rmSync(promptFile, { force: true }); } catch {}
+    };
+
+    try {
+      fs.writeFileSync(promptFile, prompt, 'utf8');
+    } catch (writeErr) {
+      reject(new Error(`Failed to write prompt file: ${writeErr.message}`));
+      return;
+    }
+
+    const timeoutMs = (timeoutSeconds + 60) * 1000;
+    let settled = false;
+    let stdout = '';
+    let stderr = '';
+    let proc;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        cleanup();
+        terminateProcessTree(proc?.pid, { runDir, label: roleLabel });
+        reject(new Error(`Agent ${agent} timed out after ${timeoutSeconds}s`));
+      }
+    }, timeoutMs);
+
+    try {
+      if (process.platform === 'win32') {
+        const comspec = process.env.COMSPEC || 'cmd.exe';
+        proc = spawn(comspec, [
+          '/d', '/s', '/c',
+          `"${acpxBin}" --cwd "%AI_SPRINT_CWD%" --approve-all --model "%AI_SPRINT_MODEL%" --timeout "%AI_SPRINT_TIMEOUT%" ${agent} exec -f "%AI_SPRINT_PROMPT%"`,
+        ], {
+          cwd,
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+          shell: false,
+          env: {
+            ...process.env,
+            AI_SPRINT_CWD: cwd,
+            AI_SPRINT_MODEL: model,
+            AI_SPRINT_TIMEOUT: String(timeoutSeconds),
+            AI_SPRINT_PROMPT: promptFile,
+          },
+        });
+      } else {
+        try {
+          proc = spawn(nodeBin, [acpxBin,
+            '--cwd', cwd, '--approve-all', '--model', model,
+            '--timeout', String(timeoutSeconds), '--prompt-retries', '2', '--suppress-reads', agent, 'exec', '-f', promptFile,
+          ], {
+            cwd,
+            encoding: 'utf8',
+            maxBuffer: 10 * 1024 * 1024,
+            shell: false,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: acpxEnv,
+          });
+        } catch (enoentErr) {
+          // Fallback if resolved path is stale
+          if (enoentErr.code === 'ENOENT') {
+            proc = spawn(nodeBin, [acpxBin,
+              '--cwd', cwd, '--approve-all', '--model', model,
+              '--timeout', String(timeoutSeconds), '--prompt-retries', '2', '--suppress-reads', agent, 'exec', '-f', promptFile,
+            ], {
+              cwd,
+              encoding: 'utf8',
+              maxBuffer: 10 * 1024 * 1024,
+              shell: false,
+              detached: true,
+              stdio: ['pipe', 'pipe', 'pipe'],
+              env: acpxEnv,
+            });
+          } else {
+            throw enoentErr;
+          }
+        }
+      }
+      if (proc?.pid && onSpawn) onSpawn(proc.pid);
+    } catch (spawnErr) {
+      settled = true;
+      clearTimeout(timer);
+      cleanup();
+      reject(new Error(`Failed to spawn agent ${agent}: ${spawnErr.message}`));
+      return;
+    }
+
+    proc.stdout.on('data', (data) => { stdout += data; });
+    proc.stderr.on('data', (data) => { stderr += data; });
+    // Use 'exit' instead of 'close' — on Windows, powershell.exe child process chains
+    // may keep stdio pipes open after exit, causing 'close' to never fire.
+    // 'exit' fires when the process exits regardless of stdio pipe state.
+    proc.on('exit', (code) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        // Read any remaining buffered stdout/stderr before resolving
+        resolve({ stdout: stdout.trim(), stderr: stderr.trim(), status: code });
+      }
+    });
+    // Cleanup prompt file on close (stdio fully drained) — separate from resolve
+    proc.on('close', () => {
+      cleanup();
+    });
+    proc.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        cleanup();
+        reject(err);
+      }
+    });
+  });
+}
+
+/**
+ * Check if there's progress evidence in the last N seconds.
+ * Progress signals:
+ * 1. Worklog file updated recently
+ * 2. Target directory has file modifications
+ * 3. Stdout has new content (tracked externally)
+ */
+function checkProgressEvidence({ worktreePath, worklogPath, lastStdoutLength, currentStdout, lookbackSeconds = 120 }) {
+  const now = Date.now();
+  const lookbackMs = lookbackSeconds * 1000;
+  const signals = [];
+
+  // Check worklog file mtime
+  if (worklogPath && fileExists(worklogPath)) {
+    try {
+      const stat = fs.statSync(worklogPath);
+      if (now - stat.mtimeMs < lookbackMs) {
+        signals.push({ type: 'worklog_updated', age: Math.round((now - stat.mtimeMs) / 1000) });
+      }
+    } catch {}
+  }
+
+  // Check for new stdout content
+  if (lastStdoutLength !== undefined && currentStdout !== undefined) {
+    if (currentStdout.length > lastStdoutLength) {
+      signals.push({ type: 'stdout_grew', delta: currentStdout.length - lastStdoutLength });
+    }
+  }
+
+  // Check target directory for recent modifications
+  if (worktreePath && fileExists(worktreePath)) {
+    try {
+      const result = spawnSync('git', ['diff', '--name-only', '--since', `${lookbackSeconds}.seconds.ago`], {
+        cwd: worktreePath,
+        encoding: 'utf8',
+        timeout: 10_000,
+      });
+      const changedFiles = (result.stdout ?? '').trim().split('\n').filter(Boolean);
+      if (changedFiles.length > 0) {
+        signals.push({ type: 'files_changed', count: changedFiles.length, files: changedFiles.slice(0, 3) });
+      }
+    } catch {}
+  }
+
+  return {
+    hasProgress: signals.length > 0,
+    signals,
+  };
+}
+
+/**
+ * Async agent runner with progress-based timeout extension.
+ * 
+ * Implements soft/hard timeout model:
+ * - softTimeout: check for progress, extend if evidence found
+ * - hardTimeout: force terminate regardless of progress
+ * - maxExtensions: limit total extensions to prevent infinite loops
+ */
+function runAgentWithProgressCheck({
+  cwd,
+  agent,
+  model,
+  prompt,
+  timeoutSeconds = 1800,
+  promptDir = cwd,
+  runDir = null,
+  roleLabel = agent,
+  worktreePath = null,
+  worklogPath = null,
+  softTimeoutRatio = 0.67,  // soft timeout at 67% of hard timeout
+  extensionSeconds = null,  // defaults to a timeout-scaled extension window
+  maxExtensions = 2,        // max 2 extensions unless caller overrides
+  progressCheckIntervalSeconds = 60,
+}) {
+  return new Promise((resolve, reject) => {
+    const scaledExtensionSeconds = extensionSeconds ?? Math.max(30, Math.min(300, Math.floor(timeoutSeconds / 2)));
+    const hardTimeoutSeconds = timeoutSeconds + (scaledExtensionSeconds * maxExtensions);
+    const softTimeoutSeconds = Math.floor(timeoutSeconds * softTimeoutRatio);
+    
+    let extensionsUsed = 0;
+    let lastStdoutLength = 0;
+    let lastProgressCheck = Date.now();
+    let settled = false;
+    let proc = null;
+    let stdout = '';
+    let stderr = '';
+
+    const promptFile = path.join(promptDir, `.ai-sprint-prompt-${process.pid}-${crypto.randomUUID()}.txt`);
+
+    const cleanup = () => {
+      try { fs.rmSync(promptFile, { force: true }); } catch {}
+    };
+
+    try {
+      fs.writeFileSync(promptFile, prompt, 'utf8');
+    } catch (writeErr) {
+      reject(new Error(`Failed to write prompt file: ${writeErr.message}`));
+      return;
+    }
+
+    // Hard timeout - absolute maximum
+    const hardTimer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(softTimer);
+        clearTimeout(progressTimer);
+        cleanup();
+        terminateProcessTree(proc?.pid, { runDir, label: roleLabel });
+        reject(new Error(`Agent ${agent} hard timeout after ${hardTimeoutSeconds}s (extended ${extensionsUsed} times)`));
+      }
+    }, hardTimeoutSeconds * 1000);
+
+    // Soft timeout - check progress and maybe extend
+    let softTimer;
+    const setupSoftTimeout = (seconds) => {
+      clearTimeout(softTimer);
+      softTimer = setTimeout(() => {
+        if (settled) return;
+        
+        const progress = checkProgressEvidence({
+          worktreePath,
+          worklogPath,
+          lastStdoutLength,
+          currentStdout: stdout,
+          lookbackSeconds: 120,
+        });
+
+        if (progress.hasProgress && extensionsUsed < maxExtensions) {
+          extensionsUsed++;
+          lastStdoutLength = stdout.length;
+          if (runDir) {
+            appendTimeline(runDir, `Soft timeout: progress detected for ${roleLabel}, extending by ${scaledExtensionSeconds}s (${progress.signals.map(s => s.type).join(', ')})`);
+          }
+          setupSoftTimeout(scaledExtensionSeconds);
+        } else {
+          // No progress or max extensions reached - this becomes effective timeout
+          // But don't terminate yet - let hard timeout handle it
+          if (runDir && extensionsUsed >= maxExtensions) {
+            appendTimeline(runDir, `Soft timeout: max extensions (${maxExtensions}) reached for ${roleLabel}, waiting for hard timeout`);
+          } else if (runDir) {
+            appendTimeline(runDir, `Soft timeout: no progress detected for ${roleLabel}, waiting for hard timeout`);
+          }
+        }
+      }, seconds * 1000);
+    };
+
+    // Progress monitoring timer
+    let progressTimer;
+    const setupProgressMonitor = () => {
+      clearTimeout(progressTimer);
+      progressTimer = setTimeout(() => {
+        if (settled) return;
+        
+        const progress = checkProgressEvidence({
+          worktreePath,
+          worklogPath,
+          lastStdoutLength,
+          currentStdout: stdout,
+          lookbackSeconds: 60,
+        });
+        
+        if (progress.hasProgress) {
+          lastStdoutLength = stdout.length;
+        }
+        
+        if (!settled) setupProgressMonitor();
+      }, progressCheckIntervalSeconds * 1000);
+    };
+
+    // Spawn the agent process
+    try {
+      if (process.platform === 'win32') {
+        const comspec = process.env.COMSPEC || 'cmd.exe';
+        proc = spawn(comspec, [
+          '/d', '/s', '/c',
+          `"${acpxBin}" --cwd "%AI_SPRINT_CWD%" --approve-all --model "%AI_SPRINT_MODEL%" --timeout "%AI_SPRINT_TIMEOUT%" ${agent} exec -f "%AI_SPRINT_PROMPT%"`,
+        ], {
+          cwd,
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+          shell: false,
+          env: {
+            ...process.env,
+            AI_SPRINT_CWD: cwd,
+            AI_SPRINT_MODEL: model,
+            AI_SPRINT_TIMEOUT: String(hardTimeoutSeconds),
+            AI_SPRINT_PROMPT: promptFile,
+          },
+        });
+      } else {
+        try {
+          proc = spawn(nodeBin, [acpxBin,
+            '--cwd', cwd, '--approve-all', '--model', model,
+            '--timeout', String(hardTimeoutSeconds), '--prompt-retries', '2', '--suppress-reads', agent, 'exec', '-f', promptFile,
+          ], {
+            cwd,
+            encoding: 'utf8',
+            maxBuffer: 10 * 1024 * 1024,
+            shell: false,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: acpxEnv,
+          });
+        } catch (enoentErr) {
+          if (enoentErr.code === 'ENOENT') {
+            proc = spawn(nodeBin, [acpxBin,
+              '--cwd', cwd, '--approve-all', '--model', model,
+              '--timeout', String(hardTimeoutSeconds), '--prompt-retries', '2', '--suppress-reads', agent, 'exec', '-f', promptFile,
+            ], {
+              cwd,
+              encoding: 'utf8',
+              maxBuffer: 10 * 1024 * 1024,
+              shell: false,
+              detached: true,
+              stdio: ['pipe', 'pipe', 'pipe'],
+              env: acpxEnv,
+            });
+          } else {
+            throw enoentErr;
+          }
+        }
+      }
+    } catch (spawnErr) {
+      settled = true;
+      clearTimeout(hardTimer);
+      clearTimeout(softTimer);
+      clearTimeout(progressTimer);
+      cleanup();
+      reject(new Error(`Failed to spawn agent ${agent}: ${spawnErr.message}`));
+      return;
+    }
+
+    proc.stdout.on('data', (data) => { stdout += data; });
+    proc.stderr.on('data', (data) => { stderr += data; });
+
+    proc.on('exit', (code) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(hardTimer);
+        clearTimeout(softTimer);
+        clearTimeout(progressTimer);
+        resolve({ stdout: stdout.trim(), stderr: stderr.trim(), status: code, extensionsUsed });
+      }
+    });
+
+    proc.on('close', () => { cleanup(); });
+
+    proc.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(hardTimer);
+        clearTimeout(softTimer);
+        clearTimeout(progressTimer);
+        cleanup();
+        reject(err);
+      }
+    });
+
+    // Start timers
+    setupSoftTimeout(softTimeoutSeconds);
+    setupProgressMonitor();
+  });
+}
+
+function roleConfig(spec, role) {
+  if (role === 'producer') return spec.producer;
+  if (role === 'reviewer_a') return spec.reviewerA;
+  if (role === 'reviewer_b') return spec.reviewerB;
+  if (role === 'global_reviewer') return spec.escalationReviewer ?? null;
+  throw new Error(`Unknown role: ${role}`);
+}
+
+function roleAttemptConfigs(config) {
+  if (!config) return [];
+  const primary = { ...config, fallback: undefined, attemptLabel: 'primary' };
+  const attempts = [primary];
+
+  if (config.fallback?.agent && config.fallback?.model) {
+    attempts.push({
+      ...config,
+      ...config.fallback,
+      fallback: undefined,
+      attemptLabel: 'fallback',
+    });
+  } else if (config.retryOnce === true) {
+    attempts.push({
+      ...config,
+      fallback: undefined,
+      attemptLabel: 'retry',
+    });
+  }
+
+  return attempts;
+}
+
+function loadSpec(state, args) {
+  const specPath = (args && args.taskSpec) || (state && state.specPath) || null;
+  return getTaskSpec(state.taskId, specPath);
+}
+
+/**
+ * Resolve per-role timeout for a given stage.
+ * Priority: spec.stageRoleTimeouts[stage][role] > config.timeoutSeconds > 600
+ */
+function stageRoleTimeout(spec, stage, role) {
+  if (spec.stageRoleTimeouts?.[stage]?.[role] != null) {
+    return spec.stageRoleTimeouts[stage][role];
+  }
+  const config = roleConfig(spec, role);
+  return config?.timeoutSeconds ?? 600;
+}
+
+function ensureStagePaths(runDir, stageIndex, stageName) {
+  const stageDir = path.join(runDir, 'stages', `${String(stageIndex + 1).padStart(2, '0')}-${stageName}`);
+  ensureDir(stageDir);
+  const paths = {
+    stageDir,
+    briefPath: path.join(stageDir, 'brief.md'),
+    producerPath: path.join(stageDir, 'producer.md'),
+    reviewerAPath: path.join(stageDir, 'reviewer-a.md'),
+    reviewerBPath: path.join(stageDir, 'reviewer-b.md'),
+    globalReviewerPath: path.join(stageDir, 'global-reviewer.md'),
+    decisionPath: path.join(stageDir, 'decision.md'),
+    scorecardPath: path.join(stageDir, 'scorecard.json'),
+    producerStdoutPath: path.join(stageDir, 'producer-stdout.log'),
+    reviewerAStdoutPath: path.join(stageDir, 'reviewer-a-stdout.log'),
+    reviewerBStdoutPath: path.join(stageDir, 'reviewer-b-stdout.log'),
+    globalReviewerStdoutPath: path.join(stageDir, 'global-reviewer-stdout.log'),
+    producerWorklogPath: path.join(stageDir, 'producer-worklog.md'),
+    reviewerAWorklogPath: path.join(stageDir, 'reviewer-a-worklog.md'),
+    reviewerBWorklogPath: path.join(stageDir, 'reviewer-b-worklog.md'),
+    globalReviewerWorklogPath: path.join(stageDir, 'global-reviewer-worklog.md'),
+    producerStatePath: path.join(stageDir, 'producer-state.json'),
+    reviewerAStatePath: path.join(stageDir, 'reviewer-a-state.json'),
+    reviewerBStatePath: path.join(stageDir, 'reviewer-b-state.json'),
+    globalReviewerStatePath: path.join(stageDir, 'global-reviewer-state.json'),
+  };
+
+  const placeholderFiles = [
+    paths.producerWorklogPath,
+    paths.reviewerAWorklogPath,
+    paths.reviewerBWorklogPath,
+    paths.globalReviewerWorklogPath,
+  ];
+  for (const file of placeholderFiles) {
+    if (!fileExists(file)) {
+      writeText(file, '# Worklog\n\n');
+    }
+  }
+
+  const placeholderStates = [
+    [paths.producerStatePath, 'producer'],
+    [paths.reviewerAStatePath, 'reviewer_a'],
+    [paths.reviewerBStatePath, 'reviewer_b'],
+    [paths.globalReviewerStatePath, 'global_reviewer'],
+  ];
+  for (const [file, role] of placeholderStates) {
+    if (!fileExists(file)) {
+      writeJson(file, {
+        role,
+        stage: stageName,
+        round: 0,
+        status: 'idle',
+        lastPid: null,
+        startedAt: null,
+        finishedAt: null,
+        terminatedAt: null,
+        timeoutSeconds: null,
+        lastError: null,
+        checklist: [],
+        updatedAt: nowIso(),
+      });
+    }
+  }
+
+  return paths;
+}
+
+function roleArtifactPaths(paths, role) {
+  if (role === 'producer') {
+    return { reportPath: paths.producerPath, stdoutPath: paths.producerStdoutPath };
+  }
+  if (role === 'reviewer_a') {
+    return { reportPath: paths.reviewerAPath, stdoutPath: paths.reviewerAStdoutPath };
+  }
+  if (role === 'reviewer_b') {
+    return { reportPath: paths.reviewerBPath, stdoutPath: paths.reviewerBStdoutPath };
+  }
+  if (role === 'global_reviewer') {
+    return { reportPath: paths.globalReviewerPath, stdoutPath: paths.globalReviewerStdoutPath };
+  }
+  throw new Error(`Unknown role: ${role}`);
+}
+
+function roleStatePath(paths, role) {
+  if (role === 'producer') return paths.producerStatePath;
+  if (role === 'reviewer_a') return paths.reviewerAStatePath;
+  if (role === 'reviewer_b') return paths.reviewerBStatePath;
+  if (role === 'global_reviewer') return paths.globalReviewerStatePath;
+  throw new Error(`Unknown role: ${role}`);
+}
+
+function updateRoleState(paths, role, patch) {
+  const statePath = roleStatePath(paths, role);
+  const previous = fileExists(statePath) ? readJson(statePath) : { role };
+  writeJson(statePath, {
+    ...previous,
+    ...patch,
+    role,
+    updatedAt: nowIso(),
+  });
+}
+
+function terminateProcessTree(pid, { runDir = null, label = 'process' } = {}) {
+  if (!pid) return false;
+  try {
+    if (process.platform === 'win32') {
+      const result = spawnSync('taskkill', ['/T', '/F', '/PID', String(pid)], {
+        encoding: 'utf8',
+        timeout: 30_000,
+        shell: false,
+      });
+      const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+      const success = result.status === 0 || /not found|no running instance|not found/i.test(output);
+      if (runDir) appendTimeline(runDir, `${success ? 'Terminated' : 'Failed to terminate'} ${label} process tree pid=${pid}${output ? ` (${output})` : ''}`);
+      return success;
+    }
+    // Kill entire process group — negative pid sends signal to all processes
+    // in the same process group. Fallback to direct pid kill if group kill
+    // fails (e.g., process group already destroyed).
+    try {
+      process.kill(-pid, 'SIGKILL');
+      if (runDir) appendTimeline(runDir, `Terminated ${label} process group pgid=${pid}`);
+    } catch (groupErr) {
+      if (groupErr.code === 'ESRCH') {
+        // Process already dead — expected during normal cleanup
+        if (runDir) appendTimeline(runDir, `${label} process already exited pid=${pid}`);
+        return true;
+      }
+      process.kill(pid, 'SIGKILL');
+      if (runDir) appendTimeline(runDir, `Terminated ${label} pid=${pid} (group kill failed: ${groupErr.message})`);
+    }
+    return true;
+  } catch (err) {
+    if (err.code === 'ESRCH') {
+      // Process already dead — expected during normal cleanup
+      if (runDir) appendTimeline(runDir, `${label} process already exited pid=${pid}`);
+      return true;
+    }
+    if (runDir) appendTimeline(runDir, `Failed to terminate ${label} pid=${pid}: ${err.message}`);
+    return false;
+  }
+}
+
+function cleanupRecordedRoleProcesses(paths, runDir) {
+  const roles = ['producer', 'reviewer_a', 'reviewer_b', 'global_reviewer'];
+  for (const role of roles) {
+    const statePath = roleStatePath(paths, role);
+    if (!fileExists(statePath)) continue;
+    const roleState = readJson(statePath);
+    if (roleState.lastPid) {
+      const terminated = terminateProcessTree(roleState.lastPid, { runDir, label: role });
+      if (terminated) {
+        updateRoleState(paths, role, {
+          status: roleState.status === 'completed' ? roleState.status : 'terminated',
+          terminatedAt: nowIso(),
+          lastPid: null,
+        });
+      } else {
+        updateRoleState(paths, role, {
+          lastError: roleState.lastError ?? `Failed to terminate recorded ${role} pid ${roleState.lastPid}`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * ISOLATION ARTIFACT ALLOWLIST
+ * Only these files can be collected from isolation directory to stage directory.
+ * This prevents accidental collection of logs, temp files, or other runtime artifacts.
+ */
+export const ISOLATION_COLLECT_ALLOWLIST = [
+  // Report files - the primary artifacts we want to collect
+  'report.md',
+  // Stage-specific report filenames
+  'producer.md',
+  'reviewer-a.md',
+  'reviewer-b.md',
+  'global-reviewer.md',
+];
+
+/**
+ * Check if a filename is allowed to be collected from isolation directory.
+ * @param {string} filename - The filename to check (basename only, no path)
+ * @returns {boolean} True if the file is in the allowlist
+ */
+export function isIsolationCollectAllowed(filename) {
+  return ISOLATION_COLLECT_ALLOWLIST.includes(filename);
+}
+
+/**
+ * Get the isolation directory path for a specific run/stage/role.
+ * This is the canonical isolation directory format: runtime/tmp/sprint-agent/{runId}/{stage}-{role}/
+ *
+ * @param {string} runId - The unique run identifier (e.g., "2026-04-02T14-24-34-009Z-task-name")
+ * @param {string} stageName - The stage name (e.g., "implement", "verify")
+ * @param {string} role - The role name (e.g., "producer", "reviewer_a")
+ * @returns {string} The isolation directory path
+ */
+export function getIsolationDir(runId, stageName, role) {
+  const roleDir = `${stageName}-${role}`;
+  return path.join(tempRoot, 'sprint-agent', runId, roleDir);
+}
+
+/**
+ * Find report in agent isolation directory.
+ * Agent writes to runtime/tmp/sprint-agent/{runId}/{stage}-{role}/{report}.md
+ *
+ * IMPORTANT: Uses runId directly for isolation lookup, not fragile timestamp extraction.
+ * This ensures different runs have unique isolation directories and prevents cross-contamination.
+ *
+ * @param {object} options
+ * @param {string} options.runId - The unique run identifier
+ * @param {string} options.stageName - The stage name
+ * @param {string} options.role - The role name
+ * @param {string} options.reportFilename - The report filename to look for
+ * @returns {string|null} The isolation report path if found and valid, null otherwise
+ */
+export function findIsolationReport({ runId, stageName, role, reportFilename }) {
+  if (!runId) return null;
+
+  const isolationDir = getIsolationDir(runId, stageName, role);
+  const isolationReportPath = path.join(isolationDir, reportFilename);
+
+  if (fileExists(isolationReportPath)) {
+    const content = fs.readFileSync(isolationReportPath, 'utf8').trim();
+    // Only return if it contains actual report content (not just session log)
+    if (content && (content.includes('## VERDICT') || content.includes('## SUMMARY'))) {
+      return isolationReportPath;
+    }
+  }
+  return null;
+}
+
+/**
+ * Collect allowed artifacts from isolation directory to stage directory.
+ * Only files in ISOLATION_COLLECT_ALLOWLIST will be collected.
+ *
+ * @param {object} options
+ * @param {string} options.runId - The unique run identifier
+ * @param {string} options.stageName - The stage name
+ * @param {string} options.role - The role name
+ * @param {string} options.stageDir - The stage directory to collect to
+ * @param {string} options.reportFilename - The expected report filename
+ * @param {string} options.runDir - The run directory (for timeline logging)
+ * @returns {{collected: string[], skipped: string[], isolationReportPath: string|null}} Lists of collected and skipped files, plus the isolation report path if valid
+ */
+export function collectIsolationArtifacts({ runId, stageName, role, stageDir, reportFilename, runDir }) {
+  const result = { collected: [], skipped: [], isolationReportPath: null };
+
+  if (!runId) return result;
+
+  const isolationDir = getIsolationDir(runId, stageName, role);
+  if (!fileExists(isolationDir)) return result;
+
+  // Only collect the specific report file if it's in the allowlist
+  if (!isIsolationCollectAllowed(reportFilename)) {
+    result.skipped.push(reportFilename);
+    return result;
+  }
+
+  const isolationReportPath = path.join(isolationDir, reportFilename);
+  const stageReportPath = path.join(stageDir, reportFilename);
+
+  if (!fileExists(isolationReportPath)) return result;
+
+  const isolationContent = fs.readFileSync(isolationReportPath, 'utf8').trim();
+  const stageContent = fileExists(stageReportPath) ? fs.readFileSync(stageReportPath, 'utf8').trim() : '';
+
+  // Only collect if isolation report has actual content and stage report is missing or empty
+  const isolationHasReport = isolationContent && (isolationContent.includes('## VERDICT') || isolationContent.includes('## SUMMARY'));
+  const stageHasReport = stageContent && (stageContent.includes('## VERDICT') || stageContent.includes('## SUMMARY'));
+
+  if (isolationHasReport) {
+    result.isolationReportPath = isolationReportPath; // Always return path when valid content exists
+    if (!stageHasReport) {
+      writeText(stageReportPath, `${isolationContent}\n`);
+      appendTimeline(runDir, `Collected isolation artifact: ${reportFilename}`);
+      result.collected.push(reportFilename);
+    } else {
+      result.skipped.push(reportFilename);
+    }
+  } else {
+    result.skipped.push(reportFilename);
+  }
+
+  return result;
+}
+
+function readRoleOutput({ reportPath, stdout, isolationReportPath = null }) {
+  // First try the expected report path
+  if (fileExists(reportPath)) {
+    const report = fs.readFileSync(reportPath, 'utf8').trim();
+    if (report) {
+      return report;
+    }
+  }
+  // Fallback to isolation directory if provided
+  if (isolationReportPath && fileExists(isolationReportPath)) {
+    const report = fs.readFileSync(isolationReportPath, 'utf8').trim();
+    if (report) {
+      return report;
+    }
+  }
+  return String(stdout ?? '').trim();
+}
+
+function reportExistsAndNonEmpty(reportPath) {
+  return fileExists(reportPath) && Boolean(fs.readFileSync(reportPath, 'utf8').trim());
+}
+
+const PROTECTED_CRITICAL = ['sprint.json', 'timeline.md', 'latest-summary.md'];
+const PROTECTED_STAGE_CRITICAL = ['decision.md', 'scorecard.json'];
+
+function protectedArtifacts(runDir, paths) {
+  // Roles must not modify stage-level truth sources that are written only after role execution.
+  // Do not include run-level timeline/latest-summary here: the orchestrator itself updates those
+  // while roles are still running (timeouts, progress signals, state transitions), which would
+  // create false protected-file violations.
+  return [
+    path.join(runDir, 'sprint.json'),
+    paths.decisionPath,
+    paths.scorecardPath,
+  ];
+}
+
+function classifyProtectedFile(filePath, runDir) {
+  const basename = path.basename(filePath);
+  if (!runDir) {
+    if (PROTECTED_CRITICAL.includes(basename) || PROTECTED_STAGE_CRITICAL.includes(basename)) {
+      return 'critical';
+    }
+    return 'warn';
+  }
+  const stageDir = path.join(runDir, 'stages');
+  if (filePath.startsWith(stageDir)) {
+    return PROTECTED_STAGE_CRITICAL.includes(basename) ? 'critical' : 'warn';
+  }
+  return PROTECTED_CRITICAL.includes(basename) ? 'critical' : 'warn';
+}
+
+function snapshotProtectedFiles(files) {
+  const snapshot = {};
+  for (const file of files) {
+    snapshot[file] = fileExists(file) ? fs.statSync(file).mtimeMs : null;
+  }
+  return snapshot;
+}
+
+function detectProtectedWriteViolation(files, snapshot, runDir) {
+  for (const file of files) {
+    const previous = snapshot[file] ?? null;
+    const current = fileExists(file) ? fs.statSync(file).mtimeMs : null;
+    if (previous !== current) {
+      return { file, severity: classifyProtectedFile(file, runDir) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Format a role-level validation result for decision.md.
+ * @param {string} roleName - Display name (e.g., "Producer", "Reviewer A")
+ * @param {{valid: boolean, missingSections?: string[], invalidFields?: string[], errorSummary?: string|null}} roleResult
+ * @returns {string[]} Lines for decision.md
+ */
+export function formatRoleValidation(roleName, roleResult) {
+  if (!roleResult) return [];
+  const lines = [];
+  const status = roleResult.valid ? '[OK]' : '[FAIL]';
+  const mainLine = `- ${roleName}: ${status}`;
+  
+  if (roleResult.valid) {
+    lines.push(mainLine);
+  } else {
+    // Show error summary if available
+    const details = [];
+    if (roleResult.missingSections?.length) {
+      details.push(`missing: ${roleResult.missingSections.join(', ')}`);
+    }
+    if (roleResult.invalidFields?.length) {
+      details.push(`invalid: ${roleResult.invalidFields.join(', ')}`);
+    }
+    lines.push(`${mainLine} ${details.join('; ')}`);
+  }
+  return lines;
+}
+
+/**
+ * Validate that a report contains the minimum required markdown section headings.
+ * Returns an array of missing section descriptions (empty = pass).
+ *
+ * WF-003 fix: reviewer report format enforcement — prevents stage_error from
+ * reports that exist on disk but lack required sections.
+ * WF-004 fix: producer report format enforcement — prevents max_rounds_exceeded
+ * by giving explicit feedback about which sections are missing.
+ */
+function validateReportSections(text, requiredSections, reportLabel) {
+  const missing = [];
+  for (const section of requiredSections) {
+    // Match ## or ### heading level, case-insensitive, word boundary after section name
+    const safeSection = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^#{2,3}\\s+${safeSection}\\b`, 'im');
+    if (!re.test(text)) {
+      missing.push(`${reportLabel}: missing required section "${section}"`);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Core reviewer-report minimum schema. Without these sections, the decision
+ * engine cannot produce valid verdicts or blockers, and the stage will fail
+ * with an opaque stage_error.
+ */
+const REQUIRED_REVIEWER_SECTIONS = ['VERDICT', 'FINDINGS', 'BLOCKERS', 'NEXT_FOCUS', 'CHECKS'];
+
+export function decideAndPersist({ runDir, stageName, stageDir, decisionPath, scorecardPath, producerPath, reviewerAPath, reviewerBPath, globalReviewerPath, state, reviewerTimeouts = null, reviewerViolations = null, reviewerFailures = null }) {
+  const spec = loadSpec(state);
+  const workUnit = getActiveWorkUnit(spec, stageName, {
+    workUnitIndex: state.currentWorkUnitIndex ?? 0,
+  });
+  // Build lookup maps for reviewer timeout/error state
+  const timeoutMap = new Map((reviewerTimeouts ?? []).map((r) => [r.role, r]));
+  const failureMap = new Map((reviewerFailures ?? []).map((r) => [r.role, r]));
+  const missingFiles = [];
+  if (!reportExistsAndNonEmpty(producerPath)) missingFiles.push(`producer: ${producerPath}${fileExists(producerPath) ? ' (empty)' : ''}`);
+  if (!reportExistsAndNonEmpty(reviewerAPath)) {
+    const info = timeoutMap.get('reviewer_a');
+    const failure = failureMap.get('reviewer_a');
+    if (info?.timedOut) missingFiles.push(`reviewer_a: ${reviewerAPath} (timed out, no report${failure?.summary ? `; ${failure.summary}` : ''})`);
+    else if (info || failure) missingFiles.push(`reviewer_a: ${reviewerAPath} (error, no report${failure?.summary ? `; ${failure.summary}` : ''})`);
+    else missingFiles.push(`reviewer_a: ${reviewerAPath}${fileExists(reviewerAPath) ? ' (empty)' : ' (missing)'}`);
+  }
+  if (!reportExistsAndNonEmpty(reviewerBPath)) {
+    const info = timeoutMap.get('reviewer_b');
+    const failure = failureMap.get('reviewer_b');
+    if (info?.timedOut) missingFiles.push(`reviewer_b: ${reviewerBPath} (timed out, no report${failure?.summary ? `; ${failure.summary}` : ''})`);
+    else if (info || failure) missingFiles.push(`reviewer_b: ${reviewerBPath} (error, no report${failure?.summary ? `; ${failure.summary}` : ''})`);
+    else missingFiles.push(`reviewer_b: ${reviewerBPath}${fileExists(reviewerBPath) ? ' (empty)' : ' (missing)'}`);
+  }
+
+  const stageCriteria = spec.stageCriteria?.[stageName] ?? {};
+  const globalReviewerRequired = stageCriteria.globalReviewerRequired === true;
+  if (globalReviewerRequired && globalReviewerPath && !reportExistsAndNonEmpty(globalReviewerPath)) {
+    missingFiles.push(`global_reviewer: ${globalReviewerPath}${fileExists(globalReviewerPath) ? ' (empty — required for this stage)' : ' (missing — required for this stage)'}`);
+  }
+
+  if (missingFiles.length > 0) {
+    const failure = inferFailureClassification({
+      summary: `Missing reports: ${missingFiles.join('; ')}`,
+      blockers: missingFiles,
+      reviewerTimeouts,
+      reviewerViolations,
+    });
+    writeText(decisionPath, [
+      `# Decision`,
+      '',
+      `- Stage: ${stageName}`,
+      `- Round: ${state.currentRound}`,
+      `- Outcome: error`,
+      '',
+      `## Missing reports`,
+      ...missingFiles.map((f) => `- ${f}`),
+      '',
+      `Cannot render stage decision because required role reports are missing.`,
+      '',
+    ].join('\n'));
+    writeJson(scorecardPath, {
+      stage: stageName,
+      round: state.currentRound,
+      outcome: 'error',
+      summary: `Missing reports: ${missingFiles.join('; ')}`,
+      missingReports: missingFiles,
+      failureClassification: failure.failureClassification,
+      failureSource: failure.failureSource,
+      recommendedNextAction: failure.recommendedNextAction,
+      reviewerTimeouts: reviewerTimeouts ?? null,
+      reviewerFailures: reviewerFailures ?? null,
+      updatedAt: nowIso(),
+    });
+    appendTimeline(runDir, `Stage ${stageName} round ${state.currentRound} decision: error (missing reports)`);
+    updateSummaryWithClassification(runDir, [
+      `Status: ${state.status}`,
+      `Stage: ${stageName}`,
+      `Round: ${state.currentRound}`,
+      `Outcome: error`,
+      `Missing: ${missingFiles.join('; ')}`,
+    ], failure);
+    return { outcome: 'error', summary: `Missing reports: ${missingFiles.join('; ')}`, blockers: missingFiles, metrics: {} };
+  }
+
+  const producer = fs.readFileSync(producerPath, 'utf8');
+  const reviewerA = fs.readFileSync(reviewerAPath, 'utf8');
+  const reviewerB = fs.readFileSync(reviewerBPath, 'utf8');
+  const globalReviewer = (globalReviewerRequired && globalReviewerPath && reportExistsAndNonEmpty(globalReviewerPath))
+    ? fs.readFileSync(globalReviewerPath, 'utf8')
+    : null;
+
+  // Read reviewer state JSON for dimensions fallback (agent may write dimensions to state but not report text)
+  const reviewerAStatePath = path.join(stageDir, 'reviewer-a-state.json');
+  const reviewerBStatePath = path.join(stageDir, 'reviewer-b-state.json');
+  let reviewerADimensionsFallback = null;
+  let reviewerBDimensionsFallback = null;
+  try {
+    if (fileExists(reviewerAStatePath)) {
+      const aState = readJson(reviewerAStatePath);
+      if (aState.dimensions && typeof aState.dimensions === 'object') reviewerADimensionsFallback = aState.dimensions;
+    }
+  } catch {}
+  try {
+    if (fileExists(reviewerBStatePath)) {
+      const bState = readJson(reviewerBStatePath);
+      if (bState.dimensions && typeof bState.dimensions === 'object') reviewerBDimensionsFallback = bState.dimensions;
+    }
+  } catch {}
+
+  // WF-003/WF-004 fix: validate report schema before entering decision engine.
+  // Reports that exist on disk but lack required sections cause opaque stage_error
+  // or silent max_rounds_exceeded. By validating here, we get explicit error
+  // messages that tell the agent exactly which sections are missing.
+  //
+  // Return 'error' outcome (which advanceState() maps to stage_error → halt).
+  // This is intentional: if both reviewers fail schema validation simultaneously,
+  // the stage cannot proceed. The explicit blockers tell the Executor exactly
+  // what to fix in the next sprint.
+  const schemaErrors = [];
+  const missingReviewerA = validateReportSections(reviewerA, REQUIRED_REVIEWER_SECTIONS, 'reviewer_a');
+  const missingReviewerB = validateReportSections(reviewerB, REQUIRED_REVIEWER_SECTIONS, 'reviewer_b');
+  if (missingReviewerA.length) schemaErrors.push(...missingReviewerA);
+  if (missingReviewerB.length) schemaErrors.push(...missingReviewerB);
+
+  if (schemaErrors.length > 0) {
+    const errorSummary = `Report schema violation: ${schemaErrors.join('; ')}`;
+    const failure = inferFailureClassification({
+      summary: errorSummary,
+      blockers: schemaErrors,
+      reviewerTimeouts,
+      reviewerViolations,
+    });
+    writeText(decisionPath, [
+      `# Decision`,
+      '',
+      `- Stage: ${stageName}`,
+      `- Round: ${state.currentRound}`,
+      `- Outcome: error`,
+      '',
+      `## Report Schema Violation`,
+      ...schemaErrors.map((e) => `- ${e}`),
+      '',
+      `Cannot render stage decision because role reports are missing required sections.`,
+      '',
+    ].join('\n'));
+    writeJson(scorecardPath, {
+      stage: stageName,
+      round: state.currentRound,
+      outcome: 'error',
+      summary: errorSummary,
+      missingReports: schemaErrors,
+      failureClassification: failure.failureClassification,
+      failureSource: failure.failureSource,
+      recommendedNextAction: failure.recommendedNextAction,
+      reviewerTimeouts: reviewerTimeouts ?? null,
+      updatedAt: nowIso(),
+      schemaValidation: {
+        reviewerA_sections: REQUIRED_REVIEWER_SECTIONS,
+        reviewerA_missing: missingReviewerA,
+        reviewerB_sections: REQUIRED_REVIEWER_SECTIONS,
+        reviewerB_missing: missingReviewerB,
+      },
+    });
+    appendTimeline(runDir, `Stage ${stageName} round ${state.currentRound} decision: error (report schema violation)`);
+    updateSummaryWithClassification(runDir, [
+      `Status: ${state.status}`,
+      `Stage: ${stageName}`,
+      `Round: ${state.currentRound}`,
+      `Outcome: error`,
+      `Schema violations: ${schemaErrors.join('; ')}`,
+    ], failure);
+    return { outcome: 'error', summary: errorSummary, blockers: schemaErrors, metrics: {} };
+  }
+
+  const decision = decideStage({
+    stageCriteria: spec.stageCriteria?.[stageName],
+    producer,
+    reviewerA,
+    reviewerB,
+    globalReviewer: globalReviewerRequired ? globalReviewer : null,
+    currentRound: state.currentRound,
+    maxRoundsPerStage: state.maxRoundsPerStage,
+    reviewerViolations,
+    reviewerADimensionsFallback,
+    reviewerBDimensionsFallback,
+  });
+
+  const content = [
+    `# Decision`,
+    '',
+    `- Stage: ${stageName}`,
+    `- Round: ${state.currentRound}`,
+    `- Outcome: ${decision.outcome}`,
+    `- Output Quality: ${decision.outputQuality}`,
+    ...(workUnit
+      ? [
+          `- Work Unit: ${workUnit.workUnitId}`,
+          `- Work Unit Goal: ${workUnit.workUnitGoal}`,
+        ]
+      : []),
+    '',
+    `## Summary`,
+    decision.summary,
+    '',
+    ...(decision.qualityReasons?.length
+      ? [
+        `## Quality Reasons`,
+        ...decision.qualityReasons.map((r) => `- ${r}`),
+        '',
+      ]
+      : []),
+    ...(decision.nextRunRecommendation
+      ? [
+        `## Next Run Recommendation`,
+        `- Type: ${decision.nextRunRecommendation.type}`,
+        ...(decision.nextRunRecommendation.spec
+          ? [`- Spec: ${decision.nextRunRecommendation.spec}`]
+          : []),
+        ...(decision.nextRunRecommendation.reasons?.length
+          ? ['', 'Reasons:', ...decision.nextRunRecommendation.reasons.map((r) => `- ${r}`)]
+          : []),
+        '',
+      ]
+      : []),
+    `## Validation`,
+    `- Contract Valid: ${decision.validation?.valid ?? 'n/a'}`,
+    ...(decision.validation?.producer
+      ? formatRoleValidation('Producer', decision.validation.producer)
+      : []),
+    ...(decision.validation?.reviewerA
+      ? formatRoleValidation('Reviewer A', decision.validation.reviewerA)
+      : []),
+    ...(decision.validation?.reviewerB
+      ? formatRoleValidation('Reviewer B', decision.validation.reviewerB)
+      : []),
+    ...(decision.validation?.globalReviewer
+      ? formatRoleValidation('Global Reviewer', decision.validation.globalReviewer)
+      : []),
+    ...(decision.validation?.errorSummary
+      ? ['', `### Error Summary`, decision.validation.errorSummary]
+      : []),
+    '',
+    `## Blockers`,
+    ...(decision.blockers.length ? decision.blockers.map((b) => `- ${b}`) : ['- None.']),
+    '',
+    `## Metrics`,
+    `- approvalCount: ${decision.metrics.approvalCount}`,
+    `- blockerCount: ${decision.metrics.blockerCount}`,
+    `- reviewerAVerdict: ${decision.metrics.reviewerAVerdict}`,
+    `- reviewerBVerdict: ${decision.metrics.reviewerBVerdict}`,
+    `- producerSectionChecks: ${JSON.stringify(decision.metrics.producerSectionChecks)}`,
+    `- reviewerSectionChecks: ${JSON.stringify(decision.metrics.reviewerSectionChecks)}`,
+    `- producerChecks: ${decision.metrics.producerChecks ?? 'n/a'}`,
+    `- reviewerAChecks: ${decision.metrics.reviewerAChecks ?? 'n/a'}`,
+    `- reviewerBChecks: ${decision.metrics.reviewerBChecks ?? 'n/a'}`,
+    ...(decision.metrics.globalReviewerVerdict
+      ? [
+        `- globalReviewerVerdict: ${decision.metrics.globalReviewerVerdict}`,
+        `- globalReviewerRequired: true`,
+        `- globalReviewerChecks: ${decision.metrics.globalReviewerChecks ?? 'n/a'}`,
+        `- macroAnswersSatisfied: ${decision.metrics.macroAnswersSatisfied ?? false}`,
+      ]
+      : []),
+    ...(decision.metrics.scoringDimensions?.length
+      ? [
+        `- scoringDimensions: ${decision.metrics.scoringDimensions.join(', ')}`,
+        `- reviewerADimensions: ${JSON.stringify(decision.metrics.reviewerADimensions)}`,
+        `- reviewerBDimensions: ${JSON.stringify(decision.metrics.reviewerBDimensions)}`,
+        `- dimensionFailures: ${decision.metrics.dimensionFailures.length}`,
+      ]
+      : []),
+    ...(decision.metrics.contractItems?.length
+      ? [
+        `- contractDoneItems: ${decision.metrics.contractCheck.doneItems}/${decision.metrics.contractCheck.totalItems}`,
+      ]
+      : []),
+    '',
+    `## Files`,
+    `- Producer: ${producerPath}`,
+    `- Reviewer A: ${reviewerAPath}`,
+    `- Reviewer B: ${reviewerBPath}`,
+    ...(globalReviewerRequired ? [`- Global Reviewer: ${globalReviewerPath}`] : []),
+  ].join('\n');
+
+  writeText(decisionPath, `${content}\n`);
+
+  const failure = decision.outcome === 'error'
+    ? inferFailureClassification({
+        summary: decision.summary,
+        blockers: decision.blockers,
+        reviewerTimeouts,
+        reviewerViolations,
+      })
+    : null;
+
+  const scorecard = {
+    stage: stageName,
+    round: state.currentRound,
+    workUnitId: workUnit?.workUnitId ?? null,
+    workUnitGoal: workUnit?.workUnitGoal ?? null,
+    outcome: decision.outcome,
+    outputQuality: decision.outputQuality,
+    qualityReasons: decision.qualityReasons ?? [],
+    nextRunRecommendation: decision.nextRunRecommendation ?? null,
+    validation: {
+      valid: decision.validation?.valid ?? true,
+      errorSummary: decision.validation?.errorSummary ?? null,
+      producer: decision.validation?.producer ?? null,
+      reviewerA: decision.validation?.reviewerA ?? null,
+      reviewerB: decision.validation?.reviewerB ?? null,
+      globalReviewer: decision.validation?.globalReviewer ?? null,
+    },
+    summary: decision.summary,
+    failureClassification: failure?.failureClassification ?? null,
+    failureSource: failure?.failureSource ?? null,
+    recommendedNextAction: failure?.recommendedNextAction ?? null,
+    approvalCount: decision.metrics.approvalCount,
+    blockerCount: decision.metrics.blockerCount,
+    reviewerAVerdict: decision.metrics.reviewerAVerdict,
+    reviewerBVerdict: decision.metrics.reviewerBVerdict,
+    producerSectionChecks: decision.metrics.producerSectionChecks,
+    reviewerSectionChecks: decision.metrics.reviewerSectionChecks,
+    producerChecks: decision.metrics.producerChecks,
+    reviewerAChecks: decision.metrics.reviewerAChecks,
+    reviewerBChecks: decision.metrics.reviewerBChecks,
+    ...(decision.metrics.globalReviewerVerdict
+      ? {
+        globalReviewerVerdict: decision.metrics.globalReviewerVerdict,
+        globalReviewerRequired: true,
+        globalReviewerChecks: decision.metrics.globalReviewerChecks,
+        macroAnswersSatisfied: decision.metrics.macroAnswersSatisfied,
+        macroAnswersRequired: decision.metrics.macroAnswersRequired ?? [],
+        macroAnswersFound: decision.metrics.macroAnswersFound ?? [],
+      }
+      : {}),
+    blockers: decision.blockers,
+    ...(decision.metrics.scoringDimensions?.length
+      ? {
+        scoringDimensions: decision.metrics.scoringDimensions,
+        reviewerADimensions: decision.metrics.reviewerADimensions,
+        reviewerBDimensions: decision.metrics.reviewerBDimensions,
+        dimensionFailures: decision.metrics.dimensionFailures,
+      }
+      : {}),
+    ...(decision.metrics.contractItems?.length
+      ? {
+        contractItems: decision.metrics.contractItems,
+        contractCheck: decision.metrics.contractCheck,
+      }
+      : {}),
+    ...(reviewerTimeouts
+      ? { reviewerTimeouts }
+      : {}),
+    ...(reviewerFailures
+      ? { reviewerFailures }
+      : {}),
+    updatedAt: nowIso(),
+  };
+  writeJson(scorecardPath, scorecard);
+
+  // Build and write handoff for next round
+  if (decision.outcome === 'revise') {
+    const handoff = buildHandoff({
+      reviewerA,
+      reviewerB,
+      globalReviewer,
+      producer,
+      metrics: decision.metrics,
+      stageName,
+      round: state.currentRound,
+      workUnit,
+    });
+    const handoffPath = path.join(stageDir, 'handoff.json');
+    writeJson(handoffPath, handoff);
+    writeCheckpointSummary(stageDir, {
+      decision,
+      handoff,
+      producer,
+      reviewerA,
+      reviewerB,
+      globalReviewer: globalReviewer ?? '',
+    });
+  } else {
+    writeCheckpointSummary(stageDir, {
+      decision,
+      handoff: null,
+      producer,
+      reviewerA,
+      reviewerB,
+      globalReviewer: globalReviewer ?? '',
+    });
+  }
+  appendTimeline(runDir, `Stage ${stageName} round ${state.currentRound} decision: ${decision.outcome}`);
+  updateSummaryWithClassification(runDir, [
+    `Status: ${state.status}`,
+    `Stage: ${stageName}`,
+    `Round: ${state.currentRound}`,
+    `Outcome: ${decision.outcome}`,
+    `Approval count: ${decision.metrics.approvalCount}/2${decision.metrics.globalReviewerVerdict ? ` + global_reviewer: ${decision.metrics.globalReviewerVerdict}` : ''}`,
+    `Blocker count: ${decision.metrics.blockerCount}`,
+    ...(decision.blockers.length ? [`Top blocker: ${decision.blockers[0]}`] : ['Top blocker: none']),
+  ], failure);
+  return decision;
+}
+
+/**
+ * Run merge gate: fetch origin and compare local vs remote PR/target branch HEAD SHA.
+ *
+ * IMPORTANT — targetBranch vs worktree.branchName:
+ *   - targetBranch = spec.branch ?? 'main'   ← the REAL PR branch on remote (e.g. 'feat/my-feature')
+ *   - worktree.branchName = sprint/<runId>/<stage>  ← internal temp branch, NEVER on remote
+ *
+ * Merge gate must NEVER use worktree.branchName — it does not exist on the remote.
+ * If spec.branch is not set, merge gate compares against 'main' (safe default).
+ *
+ * Returns { localHeadSha, remoteHeadSha, shaMatch, targetBranch }.
+ * Writes result to stages/<stage>/merge-gate.json.
+ */
+function runMergeGateCheck({ runDir, state, spec, mergeGatePath }) {
+  const workspace = state.worktree?.worktreePath ?? spec.workspace;
+  const remote = 'origin';
+
+  // targetBranch is the REAL PR branch on remote — NEVER the internal sprint worktree branch
+  const targetBranch = spec.branch ?? 'main';
+  const remoteRef = `refs/remotes/${remote}/${targetBranch}`;
+
+  try {
+    // Fetch the specific remote branch via targeted refspec
+    const fetchResult = spawnSync('git', ['fetch', remote, `refs/heads/${targetBranch}:refs/remotes/${remote}/${targetBranch}`], {
+      cwd: workspace,
+      encoding: 'utf8',
+      timeout: 60_000,
+    });
+
+    // If fetch fails (branch doesn't exist on remote), record clearly
+    if (fetchResult.status !== 0) {
+      const fetchErr = fetchResult.stderr?.trim() || fetchResult.stdout?.trim() || 'unknown';
+      appendTimeline(runDir, `Merge gate: target branch '${targetBranch}' does not exist on remote: ${fetchErr}`);
+      const result = { localHeadSha: null, remoteHeadSha: null, shaMatch: false, targetBranch, error: `Branch '${targetBranch}' not found on remote. Has it been pushed?`, fetchFailed: true };
+      writeJson(mergeGatePath, result);
+      return result;
+    }
+
+    const localShaResult = spawnSync('git', ['rev-parse', 'HEAD'], {
+      cwd: workspace, encoding: 'utf8', timeout: 10_000,
+    });
+    if (localShaResult.status !== 0) {
+      const errMsg = localShaResult.stderr?.trim() || localShaResult.stdout?.trim() || 'unknown';
+      appendTimeline(runDir, `Merge gate: git rev-parse HEAD failed with status ${localShaResult.status}: ${errMsg}`);
+      return { localHeadSha: null, remoteHeadSha: null, shaMatch: false, targetBranch, error: `git rev-parse HEAD failed: ${errMsg}` };
+    }
+    const localSha = (localShaResult.stdout ?? '').trim();
+
+    const remoteShaResult = spawnSync('git', ['rev-parse', remoteRef], {
+      cwd: workspace, encoding: 'utf8', timeout: 10_000,
+    });
+    if (remoteShaResult.status !== 0) {
+      appendTimeline(runDir, `Merge gate: remote ref ${remoteRef} not found after fetch (git status ${remoteShaResult.status})`);
+      return { localHeadSha: localSha, remoteHeadSha: null, shaMatch: false, targetBranch, error: `Remote ref '${remoteRef}' not found after fetch` };
+    }
+    const remoteSha = (remoteShaResult.stdout ?? '').trim();
+
+    const shaMatch = localSha === remoteSha;
+
+    const result = { localHeadSha: localSha, remoteHeadSha: remoteSha, shaMatch, targetBranch };
+
+    writeJson(mergeGatePath, result);
+    appendTimeline(runDir, `Merge gate: targetBranch=${targetBranch} local=${localSha.slice(0, 7)} remote=${remoteSha.slice(0, 7)} match=${shaMatch}`);
+
+    return result;
+  } catch (gateErr) {
+    appendTimeline(runDir, `Merge gate check failed: ${gateErr.message}`);
+    return { localHeadSha: null, remoteHeadSha: null, shaMatch: false, targetBranch, error: gateErr.message };
+  }
+}
+
+function advanceState(state, spec, decision, { runDir } = {}) {
+  if (decision.outcome === 'advance') {
+    if (state.currentStageIndex >= spec.stages.length - 1) {
+      // Merge gate check before completing final stage
+      if (runDir) {
+        const finalStageDir = `${String(state.currentStageIndex + 1).padStart(2, '0')}-${state.currentStage}`;
+        const mergeGatePath = path.join(runDir, 'stages', finalStageDir, 'merge-gate.json');
+        const mergeGate = runMergeGateCheck({ runDir, state, spec, mergeGatePath });
+        if (!mergeGate.shaMatch) {
+          const fetchFailed = Boolean(mergeGate.fetchFailed);
+          if (fetchFailed) {
+            state.status = 'completed';
+            state.mergePending = {
+              targetBranch: mergeGate.targetBranch,
+              reason: mergeGate.error,
+              mergeGate,
+              updatedAt: nowIso(),
+            };
+            state.haltReason = null;
+            return;
+          }
+          state.status = 'halted';
+          state.haltReason = {
+            type: 'merge_gate_sha_mismatch',
+            stage: state.currentStage,
+            round: state.currentRound,
+            targetBranch: mergeGate.targetBranch,
+            details: `Merge gate failed: local SHA ${mergeGate.localHeadSha?.slice(0, 7) ?? '?'} != remote/${mergeGate.targetBranch} SHA ${mergeGate.remoteHeadSha?.slice(0, 7) ?? '?'}. Push or rebase before completing.`,
+            blockers: ['Local SHA does not match remote target branch head. Push or rebase before completing.'],
+            mergeGate,
+          };
+          return;
+        }
+      }
+      state.mergePending = null;
+      state.status = 'completed';
+      return;
+    }
+    state.currentStageIndex += 1;
+    state.currentStage = spec.stages[state.currentStageIndex];
+    state.currentWorkUnitIndex = 0;
+    state.currentRound = 1;
+    return;
+  }
+
+  if (decision.outcome === 'revise') {
+    // Route implement-pass-1 revise → implement-pass-2 automatically
+    if (state.currentStage === 'implement-pass-1') {
+      state.currentStage = 'implement-pass-2';
+      state.currentStageIndex = spec.stages.indexOf('implement-pass-2');
+      state.currentWorkUnitIndex = 0;
+      state.currentRound = 1;
+      return;
+    }
+    state.currentRound += 1;
+    return;
+  }
+
+  // Both 'halt' and 'error' outcomes halt the sprint
+  // WF-003 fix: schema violations have already been retried in execStage via
+  // the 'revise' outcome path. If we reach here with 'error', it means retries
+  // were exhausted or the error is from the standard decision engine.
+  // Schema violation errors are now returned with a special flag to trigger retry
+  // instead of halt. See the schema validation block in decideAndPersist().
+  state.status = 'halted';
+  state.haltReason = {
+    type: decision.outcome === 'error' ? 'stage_error' : 'max_rounds_exceeded',
+    stage: state.currentStage,
+    round: state.currentRound,
+    details: decision.summary,
+    blockers: decision.blockers,
+  };
+}
+
+function maybeAbort(runDir, state) {
+  const fresh = readJson(path.join(runDir, 'sprint.json'));
+  if (fresh.status === 'aborted' || fresh.status === 'paused') {
+    Object.assign(state, fresh);
+    throw new Error(`Sprint ${fresh.status} by operator.`);
+  }
+  Object.assign(state, fresh);
+}
+
+function pidExists(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function reconcileRunState(runDir, state) {
+  if (state.status !== 'running') return state;
+  if (pidExists(state.orchestratorPid)) return state;
+
+  // Clean up any orphaned acpx queue-owner daemons and agent processes
+  // from the previous orchestrator run. acpx queue-owners are detached
+  // processes that may outlive their parent acpx invocation.
+  cleanupAcpxOrphans(runDir, state);
+
+  // Detect which artifacts already exist on disk for the current stage/round
+  const stageDirName = `${String(state.currentStageIndex + 1).padStart(2, '0')}-${state.currentStage}`;
+  const stageDir = path.join(runDir, 'stages', stageDirName);
+  const artifacts = {
+    producer: reportExistsAndNonEmpty(path.join(stageDir, 'producer.md')),
+    reviewerA: reportExistsAndNonEmpty(path.join(stageDir, 'reviewer-a.md')),
+    reviewerB: reportExistsAndNonEmpty(path.join(stageDir, 'reviewer-b.md')),
+    globalReviewer: reportExistsAndNonEmpty(path.join(stageDir, 'global-reviewer.md')),
+    decision: reportExistsAndNonEmpty(path.join(stageDir, 'decision.md')),
+  };
+
+  const roleLabel = state.currentRole ?? 'unknown';
+  const diskSummary = Object.entries(artifacts)
+    .filter(([, v]) => v)
+    .map(([k]) => k)
+    .join(', ') || 'none';
+
+  state.status = 'halted';
+  state.haltReason = {
+    type: 'stale_orchestrator',
+    stage: state.currentStage,
+    round: state.currentRound,
+    details: `Orchestrator pid ${state.orchestratorPid ?? 'unknown'} is no longer alive (was: ${roleLabel}). Artifacts on disk: ${diskSummary}.`,
+    blockers: ['The sprint process ended before stage completion. Resume to continue.'],
+    artifacts,
+  };
+  saveState(runDir, state);
+  updateSummary(runDir, [
+    `Status: ${state.status}`,
+    `Stage: ${state.currentStage}`,
+    `Round: ${state.currentRound}`,
+    `Halt reason: ${state.haltReason.details}`,
+    `Disk artifacts: ${diskSummary}`,
+  ]);
+  appendTimeline(runDir, `Sprint reconciled to halted: ${state.haltReason.details}`);
+  const paths = ensureStagePaths(runDir, state.currentStageIndex, state.currentStage);
+  cleanupRecordedRoleProcesses(paths, runDir);
+  cleanupWorktree({ state, runDir });
+  return state;
+}
+
+/**
+ * Clean up orphaned acpx queue-owner daemons and agent processes.
+ * acpx spawns detached queue-owner processes that may outlive the acpx CLI
+ * that created them. On stale-run reconciliation, these should be cleaned up.
+ */
+function cleanupAcpxOrphans(runDir, state) {
+  // Derive workspace from known-good sources only:
+  // 1. worktree (most reliable — we created it)
+  // 2. spec.workspace (loaded fresh, has clear semantic meaning)
+  const spec = state.taskId ? (() => {
+    try { return getTaskSpec(state.taskId, state.specPath); } catch { return null; }
+  })() : null;
+
+  const workspace = state.worktree?.worktreePath
+    ?? (spec?.workspace && spec.workspace !== state.specPath ? spec.workspace : null);
+
+  if (!workspace) {
+    appendTimeline(runDir, 'acpx session cleanup skipped: no trusted workspace available');
+    return;
+  }
+
+  // Try to close any active acpx sessions for the workspace+agent combo
+  const agent = spec?.producer?.agent ?? null;
+
+  if (agent) {
+    try {
+      // acpx <agent> sessions close — this removes the queue-owner lease
+      // Use nodeBin + [acpxBin, ...] for consistency with runAgent spawn pattern
+      const closeResult = spawnSync(nodeBin, [acpxBin, agent, 'sessions', 'close'],
+        { cwd: workspace, encoding: 'utf8', timeout: 10_000, env: acpxEnv, shell: false });
+      if (closeResult.status === 0) {
+        appendTimeline(runDir, `Cleaned up acpx ${agent} sessions for stale run recovery`);
+      }
+    } catch (closeErr) {
+      // Non-fatal — queue-owner may already be gone
+      appendTimeline(runDir, `acpx session cleanup skipped: ${closeErr.message}`);
+    }
+  }
+}
+
+/**
+ * Execute a single reviewer role asynchronously with independent timeout tracking.
+ * Returns a result object: { role, output, timedOut, reportExisted, violatedFile }
+ */
+async function runReviewerRole({ runDir, state, spec, paths, role, worktreeInfo }) {
+  const stageName = state.currentStage;
+  const workUnit = getActiveWorkUnit(spec, stageName, {
+    workUnitIndex: state.currentWorkUnitIndex ?? 0,
+  });
+  const config = roleConfig(spec, role);
+  const { reportPath, stdoutPath } = roleArtifactPaths(paths, role);
+  const failLogBase = path.join(paths.stageDir, `${role.replace('_', '-')}-failure`);
+
+  // Skip if report already exists
+  if (fileExists(reportPath) && fs.readFileSync(reportPath, 'utf8').trim()) {
+    updateRoleState(paths, role, {
+      stage: stageName,
+      round: state.currentRound,
+      status: 'completed',
+      lastPid: null,
+      finishedAt: nowIso(),
+      timeoutSeconds: stageRoleTimeout(spec, stageName, role),
+      lastError: null,
+    });
+    return { role, output: fs.readFileSync(reportPath, 'utf8').trim(), timedOut: false, reportExisted: true, violatedFile: null };
+  }
+
+  const protectedFiles = protectedArtifacts(runDir, paths);
+  const protectedSnapshot = snapshotProtectedFiles(protectedFiles);
+  const prompt = buildRolePrompt({
+    spec,
+    stage: stageName,
+    round: state.currentRound,
+    role,
+    runDir,
+    stageDir: paths.stageDir,
+    briefPath: paths.briefPath,
+    producerPath: paths.producerPath,
+    reviewerAPath: paths.reviewerAPath,
+    reviewerBPath: paths.reviewerBPath,
+    globalReviewerPath: paths.globalReviewerPath,
+    workUnit,
+  });
+  const timeoutSeconds = stageRoleTimeout(spec, stageName, role);
+  // Reviewers must verify code in the same workspace where producer made changes
+  // branchWorkspace may not exist — fall back to spec.workspace (always valid)
+  const cwd = worktreeInfo?.worktreePath ?? (fileExists(spec.branchWorkspace) ? spec.branchWorkspace : spec.workspace);
+
+  let output = null;
+  let timedOut = false;
+  let violatedFile = null;
+  let reportExisted = false;
+  const attemptErrors = [];
+  const attempts = roleAttemptConfigs(config);
+
+  for (let index = 0; index < attempts.length; index += 1) {
+    const attemptConfig = attempts[index];
+    const attemptLabel = attemptConfig.attemptLabel ?? `attempt_${index + 1}`;
+    const attemptTimeoutSeconds = stageRoleTimeout(
+      {
+        ...spec,
+        reviewerA: role === 'reviewer_a' ? attemptConfig : spec.reviewerA,
+        reviewerB: role === 'reviewer_b' ? attemptConfig : spec.reviewerB,
+      },
+      stageName,
+      role
+    );
+    const failLog = `${failLogBase}-${attemptLabel}.log`;
+
+    updateRoleState(paths, role, {
+      stage: stageName,
+      round: state.currentRound,
+      status: index === 0 ? 'running' : 'retrying',
+      startedAt: nowIso(),
+      finishedAt: null,
+      terminatedAt: null,
+      lastPid: null,
+      timeoutSeconds: attemptTimeoutSeconds,
+      lastError: null,
+    });
+
+    if (index > 0) {
+      appendTimeline(
+        runDir,
+        `${role} retrying with ${attemptConfig.agent}/${attemptConfig.model} (${attemptLabel})`
+      );
+    }
+
+    try {
+      const result = await runAgentAsync({
+        cwd,
+        agent: attemptConfig.agent,
+        model: attemptConfig.model,
+        prompt,
+        timeoutSeconds: attemptTimeoutSeconds,
+        promptDir: runDir,
+        runDir,
+        roleLabel: role,
+        onSpawn: (pid) => updateRoleState(paths, role, { lastPid: pid }),
+      });
+      const stdout = result.stdout ?? '';
+      const stderr = result.stderr ?? '';
+
+      if (result.status !== 0) {
+        ensureDir(path.dirname(failLog));
+        writeText(
+          failLog,
+          `# Agent Failure Log\n\n- attempt: ${attemptLabel}\n- agent: ${attemptConfig.agent}\n- model: ${attemptConfig.model}\n- exitStatus: ${result.status}\n\n## stdout\n\n${stdout.slice(0, 2000)}\n\n## stderr\n\n${stderr.slice(0, 2000)}\n`
+        );
+        throw new Error(`Agent ${attemptConfig.agent} failed with status ${result.status}`);
+      }
+
+      output = stdout.trim();
+      if (output) writeText(stdoutPath, `${output}\n`);
+      updateRoleState(paths, role, {
+        status: 'completed',
+        lastPid: null,
+        finishedAt: nowIso(),
+        lastError: null,
+      });
+      break;
+    } catch (err) {
+      const errorMessage = err.message ?? String(err);
+      const hasReport = fileExists(reportPath) && fs.readFileSync(reportPath, 'utf8').trim();
+
+      if (hasReport) {
+        output = null;
+        timedOut = errorMessage.includes('timed out');
+        reportExisted = true;
+        updateRoleState(paths, role, {
+          status: 'completed_after_timeout',
+          lastPid: null,
+          finishedAt: nowIso(),
+          lastError: errorMessage,
+        });
+        break;
+      }
+
+      const isTimedOut = errorMessage.includes('timed out');
+      attemptErrors.push({
+        label: attemptLabel,
+        agent: attemptConfig.agent,
+        model: attemptConfig.model,
+        error: errorMessage,
+        timedOut: isTimedOut,
+      });
+
+      ensureDir(path.dirname(failLog));
+      if (isTimedOut) {
+        timedOut = true;
+        writeText(
+          failLog,
+          `# Agent Timeout Log\n\n- attempt: ${attemptLabel}\n- agent: ${attemptConfig.agent}\n- model: ${attemptConfig.model}\n- timeout: ${attemptTimeoutSeconds}s\n- error: ${errorMessage}\n`
+        );
+        updateRoleState(paths, role, {
+          status: 'timed_out',
+          lastPid: null,
+          finishedAt: nowIso(),
+          terminatedAt: nowIso(),
+          lastError: errorMessage,
+        });
+      } else {
+        writeText(
+          failLog,
+          `# Agent Failure Log\n\n- attempt: ${attemptLabel}\n- agent: ${attemptConfig.agent}\n- model: ${attemptConfig.model}\n- error: ${errorMessage}\n`
+        );
+        updateRoleState(paths, role, {
+          status: 'error',
+          lastPid: null,
+          finishedAt: nowIso(),
+          lastError: errorMessage,
+        });
+      }
+
+      if (index < attempts.length - 1) {
+        continue;
+      }
+
+      if (!isTimedOut) {
+        throw new Error(
+          `${role} failed after ${attemptErrors.length} attempt(s): ${attemptErrors.map((item) => `${item.label}=${item.agent}/${item.model}: ${item.error}`).join(' | ')}`
+        );
+      }
+    }
+  }
+
+  // Collect isolation artifacts using runId for unique isolation directory
+  const reportFilename = path.basename(reportPath);
+  const { collected, isolationReportPath } = collectIsolationArtifacts({
+    runId: state.runId,
+    stageName,
+    role,
+    stageDir: paths.stageDir,
+    reportFilename,
+    runDir,
+  });
+
+  const text = readRoleOutput({ reportPath, stdout: output ?? '', isolationReportPath });
+  if (!text && output) {
+    writeText(reportPath, `${output}\n`);
+  } else if (text) {
+    if (!fileExists(reportPath)) writeText(reportPath, `${text}\n`);
+  }
+
+  const violated = detectProtectedWriteViolation(protectedFiles, protectedSnapshot, runDir);
+  if (violated) {
+    violatedFile = violated.file;
+  }
+
+  return { role, output: text || output || null, timedOut, reportExisted, violatedFile, attemptErrors };
+}
+
+const MUTATING_STAGES = ['implement-pass-1', 'implement-pass-2'];
+
+/**
+ * Ensure a git worktree exists for the given mutating stage.
+ * Reuses existing worktree if already present. Returns null if not applicable.
+ *
+ * Uses a legal git worktree add: git worktree add -b <newBranch> <worktreePath> <baseRef>
+ * where baseRef is a real git ref (branch/tag/SHA), not a filesystem path.
+ */
+function ensureWorktree({ spec, runDir, state, stageName }) {
+  if (!MUTATING_STAGES.includes(stageName)) return null;
+
+  const baseWorkspace = spec.workspace;
+  const baseBranch = spec.branch ?? 'main';
+  const branchName = `sprint/${state.runId.slice(0, 25)}/${stageName}`;
+  const worktreePath = path.join(runDir, 'worktrees', stageName);
+  
+  // Resolve baseRef with robust fallback chain:
+  // 1. spec.branch (local branch)
+  // 2. origin/{spec.branch} (remote branch)
+  // 3. HEAD (current checkout)
+  // 4. main (default branch)
+  const resolveBaseRef = () => {
+    const candidates = [
+      { ref: baseBranch, label: `spec.branch '${baseBranch}'` },
+      { ref: `origin/${baseBranch}`, label: `remote branch 'origin/${baseBranch}'` },
+      { ref: 'HEAD', label: 'current HEAD' },
+      { ref: 'main', label: 'default branch main' },
+    ];
+    
+    for (const candidate of candidates) {
+      const result = spawnSync('git', ['rev-parse', '--verify', candidate.ref], {
+        cwd: baseWorkspace,
+        encoding: 'utf8',
+        timeout: 10_000,
+      });
+      if (result.status === 0 && result.stdout?.trim()) {
+        if (candidate.ref !== baseBranch) {
+          appendTimeline(runDir, `Base ref resolved to ${candidate.label}`);
+        }
+        return candidate.ref;
+      }
+    }
+    // Last resort: return 'main' even if verification failed
+    appendTimeline(runDir, `Warning: Could not verify any base ref, using 'main'`);
+    return 'main';
+  };
+  
+  const baseRef = resolveBaseRef();
+
+  // Reuse existing worktree if already created for this stage
+  if (state.worktree?.worktreePath && fileExists(state.worktree.worktreePath)) {
+    appendTimeline(runDir, `Reusing existing worktree at ${state.worktree.worktreePath}`);
+    return state.worktree;
+  }
+  
+  // Also check if worktree directory exists on disk (state may have been lost)
+  // This handles resume scenarios where sprint.json lost worktree state
+  if (fileExists(worktreePath)) {
+    // Verify it's a valid worktree by checking for .git file
+    const gitFile = path.join(worktreePath, '.git');
+    if (fileExists(gitFile)) {
+      const headSha = (spawnSync('git', ['rev-parse', 'HEAD'], {
+        cwd: worktreePath,
+        encoding: 'utf8',
+        timeout: 10_000,
+      }).stdout ?? '').trim();
+      
+      if (headSha) {
+        const recoveredWorktree = {
+          worktreePath,
+          branchName,
+          headSha,
+          baseBranch,
+          baseWorkspace,
+          dirtyFiles: [],
+        };
+        state.worktree = recoveredWorktree;
+        appendTimeline(runDir, `Recovered existing worktree at ${worktreePath} (branch: ${branchName}, sha: ${headSha})`);
+        return recoveredWorktree;
+      }
+    }
+    // Invalid worktree directory - remove it
+    appendTimeline(runDir, `Removing invalid worktree directory at ${worktreePath}`);
+    try { fs.rmSync(worktreePath, { recursive: true, force: true }); } catch {}
+  }
+
+  try {
+    ensureDir(path.dirname(worktreePath));
+
+    // Create a new worktree with a new branch based on baseRef (a real git ref)
+    // Syntax: git worktree add -b <newBranch> <path> <startPoint>
+    // where <startPoint> is baseRef (e.g., 'main' or 'origin/main')
+    const result = spawnSync('git', ['worktree', 'add', '-b', branchName, worktreePath, baseRef], {
+      cwd: baseWorkspace,
+      encoding: 'utf8',
+      timeout: 30_000,
+    });
+
+    if (result.status !== 0) {
+      const errMsg = result.stderr?.trim() || result.stdout?.trim() || 'unknown error';
+      appendTimeline(runDir, `Worktree creation failed: ${errMsg} — falling back to base workspace`);
+      return null;
+    }
+
+    const headSha = (spawnSync('git', ['rev-parse', 'HEAD'], {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      timeout: 10_000,
+    }).stdout ?? '').trim();
+
+    const worktreeInfo = {
+      worktreePath,
+      branchName,
+      headSha,
+      baseBranch,
+      baseWorkspace, // Store for cleanup cwd
+      dirtyFiles: [],
+    };
+
+    state.worktree = worktreeInfo;
+    appendTimeline(runDir, `Created worktree at ${worktreePath} (branch: ${branchName}, baseRef: ${baseRef}, sha: ${headSha})`);
+    return worktreeInfo;
+  } catch (wtErr) {
+    appendTimeline(runDir, `Worktree creation failed: ${wtErr.message} — falling back to base workspace`);
+    return null;
+  }
+}
+
+/**
+ * Capture git status for the worktree and write git-status.json to stageDir.
+ */
+function captureGitStatus({ worktreePath, runDir, stageDir, state }) {
+  if (!worktreePath || !fileExists(worktreePath)) return null;
+  try {
+    const statusResult = spawnSync('git', ['status', '--short'], {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      timeout: 10_000,
+    });
+    const branchResult = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      timeout: 10_000,
+    });
+    const shaResult = spawnSync('git', ['rev-parse', 'HEAD'], {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      timeout: 10_000,
+    });
+    const dirtyFiles = ((statusResult.stdout ?? '').trim().split('\n').filter(Boolean) || []);
+
+    const gitStatus = {
+      branch: (branchResult.stdout ?? '').trim(),
+      headSha: (shaResult.stdout ?? '').trim(),
+      worktreePath,
+      dirtyFiles,
+      baseBranch: state.worktree?.baseBranch ?? null,
+      remoteBranch: state.worktree?.branchName ? `origin/${state.worktree.branchName}` : null,
+    };
+
+    const gitStatusPath = path.join(stageDir, 'git-status.json');
+    writeJson(gitStatusPath, gitStatus);
+    appendTimeline(runDir, `Git status: ${dirtyFiles.length} dirty files, sha: ${gitStatus.headSha}`);
+    return gitStatus;
+  } catch (err) {
+    appendTimeline(runDir, `Git status capture failed: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Remove the worktree from the filesystem (on halt).
+ * Uses the stored baseWorkspace as cwd (the git repo root), not the worktree's parent dir.
+ */
+function cleanupWorktree({ state, runDir }) {
+  if (!state.worktree?.worktreePath) return;
+  const { worktreePath, baseWorkspace } = state.worktree;
+  // Use the git repo root (baseWorkspace) as cwd, not the worktree's parent dir
+  const gitCwd = baseWorkspace ?? runDir;
+  try {
+    const result = spawnSync('git', ['worktree', 'remove', '--force', worktreePath], {
+      cwd: gitCwd,
+      encoding: 'utf8',
+      timeout: 30_000,
+    });
+    if (result.status === 0) {
+      appendTimeline(runDir, `Cleaned up worktree at ${worktreePath}`);
+      state.worktree = null;
+      return;
+    }
+    const errMsg = result.stderr?.trim() || result.stdout?.trim() || `git exited ${result.status}`;
+    appendTimeline(runDir, `Worktree cleanup failed for ${worktreePath}: ${errMsg} — manual cleanup may be required`);
+  } catch (cleanupErr) {
+    appendTimeline(runDir, `Worktree cleanup failed for ${worktreePath}: ${cleanupErr.message} — manual cleanup may be required`);
+  }
+}
+
+async function executeStage(runDir, state, spec) {
+  const stageName = state.currentStage;
+  const workUnit = getActiveWorkUnit(spec, stageName, {
+    workUnitIndex: state.currentWorkUnitIndex ?? 0,
+  });
+  const previousDecisionPath = path.join(
+    runDir,
+    'stages',
+    `${String(state.currentStageIndex + 1).padStart(2, '0')}-${stageName}`,
+    'decision.md',
+  );
+  const previousDecision = fileExists(previousDecisionPath)
+    ? fs.readFileSync(previousDecisionPath, 'utf8')
+    : '';
+
+  const paths = ensureStagePaths(
+    runDir,
+    state.currentStageIndex,
+    stageName,
+  );
+  const { stageDir, briefPath, producerPath, reviewerAPath, reviewerBPath, globalReviewerPath, decisionPath, scorecardPath } = paths;
+  const protectedFiles = protectedArtifacts(runDir, paths);
+
+  // Read handoff data for structured carry forward
+  const handoffPath = path.join(stageDir, 'handoff.json');
+  const handoff = fileExists(handoffPath) ? readJson(handoffPath) : null;
+  const checkpointSummaryPath = path.join(stageDir, 'checkpoint-summary.md');
+  const checkpointSummary = fileExists(checkpointSummaryPath)
+    ? fs.readFileSync(checkpointSummaryPath, 'utf8')
+    : null;
+
+  writeText(briefPath, `${buildStageBrief(spec, stageName, state.currentRound, previousDecision, handoff, checkpointSummary, {
+    workUnitIndex: state.currentWorkUnitIndex ?? 0,
+    runDir,
+    stageDir,
+  })}\n`);
+
+  // On round > 1, clear previous round's role reports so agents must regenerate them
+  if (state.currentRound > 1) {
+    const staleReports = [producerPath, reviewerAPath, reviewerBPath, globalReviewerPath];
+    for (const fp of staleReports) {
+      if (fileExists(fp)) {
+        fs.unlinkSync(fp);
+      }
+    }
+    appendTimeline(runDir, `Cleared previous round reports for stage ${stageName} round ${state.currentRound}`);
+  }
+
+  const outputs = {};
+  const stageStartedAt = Date.now();
+  const stageTimeoutMs = (spec.stageTimeoutMinutes ?? 30) * 60_000;
+
+  // ── Phase 1: Producer (sequential) ────────────────────────────────────────
+  appendTimeline(runDir, `Stage ${stageName} round ${state.currentRound} started (producer)`);
+  updateSummary(runDir, [
+    `Status: ${state.status}`,
+    `Stage: ${stageName}`,
+    `Round: ${state.currentRound}`,
+    'Producer is running.',
+  ]);
+
+  maybeAbort(runDir, state);
+  heartbeatState(runDir, state, { currentRole: 'producer' });
+
+  // Per-stage runtime check before producer
+  const stageElapsedProducer = Date.now() - stageStartedAt;
+  if (stageElapsedProducer > stageTimeoutMs) {
+    state.status = 'halted';
+    state.haltReason = {
+      type: 'stage_timeout',
+      stage: stageName,
+      round: state.currentRound,
+      details: `Stage ${stageName} exceeded ${(stageTimeoutMs / 60_000).toFixed(0)} minutes before producer`,
+      blockers: [`Stage timeout before producer started after ${(stageElapsedProducer / 60_000).toFixed(1)} minutes`],
+    };
+    saveState(runDir, state);
+    appendTimeline(runDir, `Sprint halted: ${state.haltReason.details}`);
+    writeStageFailureArtifacts({
+      runDir,
+      state,
+      stageName,
+      stageDir,
+      decisionPath,
+      scorecardPath,
+      summary: state.haltReason.details,
+      blockers: state.haltReason.blockers,
+    });
+    cleanupRecordedRoleProcesses(paths, runDir);
+    return { outcome: 'halt', summary: state.haltReason.details, blockers: state.haltReason.blockers, metrics: {} };
+  }
+
+  const producerConfig = roleConfig(spec, 'producer');
+  const producerTimeoutSeconds = stageRoleTimeout(spec, stageName, 'producer');
+  const producerPrompt = buildRolePrompt({
+    spec,
+    stage: stageName,
+    round: state.currentRound,
+    role: 'producer',
+    runDir,
+    stageDir,
+    briefPath,
+    producerPath,
+    reviewerAPath,
+    reviewerBPath,
+    workUnit,
+  });
+  const { reportPath: producerReportPath, stdoutPath: producerStdoutPath } = roleArtifactPaths(paths, 'producer');
+
+  // Worktree setup for mutating stages
+  const worktreeInfo = ensureWorktree({ spec, runDir, state, stageName });
+  // branchWorkspace may not exist — fall back to spec.workspace (always valid)
+  const producerWorkspace = worktreeInfo?.worktreePath ?? (fileExists(spec.branchWorkspace) ? spec.branchWorkspace : spec.workspace);
+
+  if (fileExists(producerReportPath) && fs.readFileSync(producerReportPath, 'utf8').trim()) {
+    outputs.producer = fs.readFileSync(producerReportPath, 'utf8').trim();
+    updateRoleState(paths, 'producer', {
+      stage: stageName,
+      round: state.currentRound,
+      status: 'completed',
+      lastPid: null,
+      finishedAt: nowIso(),
+      timeoutSeconds: producerTimeoutSeconds,
+      lastError: null,
+    });
+    appendTimeline(runDir, `producer skipped (report already exists) stage ${stageName} round ${state.currentRound}`);
+    // Capture git status even for skipped producer (worktree may have changed)
+    if (worktreeInfo?.worktreePath) {
+      captureGitStatus({ worktreePath: worktreeInfo.worktreePath, runDir, stageDir, state });
+    }
+  } else {
+    updateRoleState(paths, 'producer', {
+      stage: stageName,
+      round: state.currentRound,
+      status: 'running',
+      startedAt: nowIso(),
+      finishedAt: null,
+      terminatedAt: null,
+      lastPid: null,
+      timeoutSeconds: producerTimeoutSeconds,
+      lastError: null,
+    });
+    const protectedSnapshot = snapshotProtectedFiles(protectedFiles);
+    const producerFailLog = path.join(stageDir, 'producer-failure.log');
+    const producerWorklogPath = paths.producerWorklogPath;
+    let producerOutput;
+    let producerTimedOut = false;
+    let extensionsUsed = 0;
+    try {
+      const result = await runAgentWithProgressCheck({
+        cwd: producerWorkspace,
+        agent: producerConfig.agent,
+        model: producerConfig.model,
+        prompt: producerPrompt,
+        timeoutSeconds: producerTimeoutSeconds,
+        promptDir: runDir,
+        runDir,
+        roleLabel: 'producer',
+        worktreePath: worktreeInfo?.worktreePath,
+        worklogPath: producerWorklogPath,
+      });
+      if (result.status !== 0) {
+        throw new Error(`Agent exited with status ${result.status}: ${result.stderr || 'no stderr'}`);
+      }
+      producerOutput = result.stdout;
+      extensionsUsed = result.extensionsUsed ?? 0;
+      if (extensionsUsed > 0) {
+        appendTimeline(runDir, `Producer used ${extensionsUsed} timeout extensions`);
+      }
+    } catch (agentErr) {
+      // Track consecutive timeouts for fuse mechanism
+      const isTimeout = agentErr.message?.includes('timed out') || agentErr.message?.includes('ETIMEDOUT');
+      if (isTimeout) {
+        // Initialize consecutiveTimeouts if not present (resume from old state)
+        if (!state.consecutiveTimeouts) state.consecutiveTimeouts = {};
+        state.consecutiveTimeouts[stageName] = (state.consecutiveTimeouts[stageName] || 0) + 1;
+        appendTimeline(runDir, `Producer timeout #${state.consecutiveTimeouts[stageName]} for stage ${stageName}`);
+        
+        // Fuse: halt after 2 consecutive timeouts on same stage
+        if (state.consecutiveTimeouts[stageName] >= 2) {
+          state.status = 'halted';
+          state.haltReason = {
+            type: 'repeated_timeout',
+            stage: stageName,
+            round: state.currentRound,
+            details: `Producer timed out ${state.consecutiveTimeouts[stageName]} times on stage ${stageName}. Timeout may be too short or task too complex.`,
+            blockers: [
+              'Repeated timeout suggests insufficient timeout or overly complex task.',
+              'Consider: 1) Increase timeout in stageRoleTimeouts, 2) Simplify task scope, 3) Check for infinite loops in agent.',
+            ],
+          };
+          saveState(runDir, state);
+          appendTimeline(runDir, `Sprint halted: repeated timeout on stage ${stageName}`);
+          writeStageFailureArtifacts({
+            runDir,
+            state,
+            stageName,
+            stageDir,
+            decisionPath,
+            scorecardPath,
+            summary: state.haltReason.details,
+            blockers: state.haltReason.blockers,
+          });
+          cleanupRecordedRoleProcesses(paths, runDir);
+          cleanupWorktree({ state, runDir });
+          throw new Error(state.haltReason.details);
+        }
+      } else {
+        // Reset counter on non-timeout error
+        if (!state.consecutiveTimeouts) state.consecutiveTimeouts = {};
+        state.consecutiveTimeouts[stageName] = 0;
+      }
+      
+      // Write failure log
+      if (producerFailLog) {
+        ensureDir(path.dirname(producerFailLog));
+        writeText(producerFailLog, `# Agent Failure Log\n\n- agent: ${producerConfig.agent}\n- model: ${producerConfig.model}\n- error: ${agentErr.message ?? String(agentErr)}\n- extensionsUsed: ${extensionsUsed}\n\n`);
+      }
+      
+      if (fileExists(producerReportPath) && fs.readFileSync(producerReportPath, 'utf8').trim()) {
+        appendTimeline(runDir, `producer spawnSync timed out but report exists — recovering stage ${stageName} round ${state.currentRound}`);
+        producerOutput = null;
+        producerTimedOut = true;
+        updateRoleState(paths, 'producer', {
+          status: 'completed_after_timeout',
+          lastPid: null,
+          finishedAt: nowIso(),
+          terminatedAt: nowIso(),
+          lastError: agentErr.message ?? String(agentErr),
+        });
+      } else {
+        updateRoleState(paths, 'producer', {
+          status: isTimeout ? 'timed_out' : 'error',
+          lastPid: null,
+          finishedAt: nowIso(),
+          terminatedAt: isTimeout ? nowIso() : null,
+          lastError: agentErr.message ?? String(agentErr),
+        });
+        throw agentErr;
+      }
+    }
+    if (producerOutput) writeText(producerStdoutPath, `${producerOutput}\n`);
+    outputs.producer = readRoleOutput({ reportPath: producerReportPath, stdout: producerOutput ?? '' });
+    if (!fileExists(producerReportPath) || !fs.readFileSync(producerReportPath, 'utf8').trim()) {
+      writeText(producerReportPath, `${outputs.producer}\n`);
+    }
+    updateRoleState(paths, 'producer', {
+      status: producerTimedOut ? 'completed_after_timeout' : 'completed',
+      lastPid: null,
+      finishedAt: nowIso(),
+      lastError: producerTimedOut ? 'Recovered after timeout because report existed on disk.' : null,
+    });
+    // Skip mtime-based violation check during timeout recovery — the producer may have
+    // been mid-write when interrupted, causing spurious mtime changes on protected files.
+    const producerViolated = producerTimedOut ? null : detectProtectedWriteViolation(protectedFiles, protectedSnapshot, runDir);
+    if (producerViolated) {
+      state.status = 'halted';
+      state.haltReason = {
+        type: 'protected_file_modified',
+        stage: stageName,
+        round: state.currentRound,
+        details: `producer modified orchestrator-owned file ${producerViolated.file}`,
+        blockers: [`Protected file modified: ${producerViolated.file}`],
+      };
+      saveState(runDir, state);
+      appendTimeline(runDir, `Sprint halted: producer modified protected file ${producerViolated.file}`);
+      writeStageFailureArtifacts({
+        runDir,
+        state,
+        stageName,
+        stageDir,
+        decisionPath,
+        scorecardPath,
+        summary: state.haltReason.details,
+        blockers: state.haltReason.blockers,
+      });
+      cleanupRecordedRoleProcesses(paths, runDir);
+      cleanupWorktree({ state, runDir });
+      throw new Error(state.haltReason.details);
+    }
+    appendTimeline(runDir, `producer completed stage ${stageName} round ${state.currentRound}`);
+    // Reset consecutive timeout counter on successful completion
+    if (!state.consecutiveTimeouts) state.consecutiveTimeouts = {};
+    if (state.consecutiveTimeouts[stageName]) {
+      state.consecutiveTimeouts[stageName] = 0;
+    }
+    // Capture git status after producer completes for reviewers to reference
+    if (worktreeInfo?.worktreePath) {
+      captureGitStatus({ worktreePath: worktreeInfo.worktreePath, runDir, stageDir, state });
+    }
+  }
+  heartbeatState(runDir, state, { currentRole: null });
+
+  // ── Phase 2: Reviewers in parallel ────────────────────────────────────────
+  maybeAbort(runDir, state);
+  heartbeatState(runDir, state, { currentRole: 'reviewer_a || reviewer_b' });
+
+  // Per-stage runtime check before launching reviewers
+  const stageElapsedReviewers = Date.now() - stageStartedAt;
+  if (stageElapsedReviewers > stageTimeoutMs) {
+    state.status = 'halted';
+    state.haltReason = {
+      type: 'stage_timeout',
+      stage: stageName,
+      round: state.currentRound,
+      details: `Stage ${stageName} exceeded ${(stageTimeoutMs / 60_000).toFixed(0)} minutes before reviewers`,
+      blockers: [`Stage timeout before reviewers after ${(stageElapsedReviewers / 60_000).toFixed(1)} minutes`],
+    };
+    saveState(runDir, state);
+    appendTimeline(runDir, `Sprint halted: ${state.haltReason.details}`);
+    writeStageFailureArtifacts({
+      runDir,
+      state,
+      stageName,
+      stageDir,
+      decisionPath,
+      scorecardPath,
+      summary: state.haltReason.details,
+      blockers: state.haltReason.blockers,
+    });
+    cleanupRecordedRoleProcesses(paths, runDir);
+    cleanupWorktree({ state, runDir });
+    return { outcome: 'halt', summary: state.haltReason.details, blockers: state.haltReason.blockers, metrics: {} };
+  }
+
+  appendTimeline(runDir, `Stage ${stageName} round ${state.currentRound} reviewers launching in parallel`);
+  updateSummary(runDir, [
+    `Status: ${state.status}`,
+    `Stage: ${stageName}`,
+    `Round: ${state.currentRound}`,
+    'Reviewers are running in parallel.',
+  ]);
+
+  // Run both reviewers in parallel — each wrapped in try/catch so one failure doesn't cancel the other
+  const reviewerResults = [];
+  const [resultA, resultB] = await Promise.all([
+    runReviewerRole({ runDir, state, spec, paths, role: 'reviewer_a', worktreeInfo }).catch((err) => {
+      appendTimeline(runDir, `reviewer_a threw unhandled error: ${err.message}`);
+      return { role: 'reviewer_a', output: null, timedOut: false, reportExisted: false, violatedFile: null, error: String(err) };
+    }),
+    runReviewerRole({ runDir, state, spec, paths, role: 'reviewer_b', worktreeInfo }).catch((err) => {
+      appendTimeline(runDir, `reviewer_b threw unhandled error: ${err.message}`);
+      return { role: 'reviewer_b', output: null, timedOut: false, reportExisted: false, violatedFile: null, error: String(err) };
+    }),
+  ]);
+  reviewerResults.push(resultA, resultB);
+
+  // Collect outputs and timeout flags
+  const reviewerTimeouts = [];
+  const reviewerFailures = [];
+  const reviewerViolations = [];
+  for (const result of reviewerResults) {
+    if (result.error) {
+      appendTimeline(runDir, `${result.role} error: ${result.error}`);
+    }
+    outputs[result.role] = result.output;
+    if (result.attemptErrors?.length) {
+      reviewerFailures.push({
+        role: result.role,
+        summary: result.attemptErrors.map((item) => `${item.label}=${item.agent}/${item.model}: ${item.error}`).join(' | '),
+        attempts: result.attemptErrors,
+      });
+      appendTimeline(runDir, `${result.role} failed attempts: ${result.attemptErrors.map((item) => `${item.label}=${item.agent}/${item.model}`).join(', ')}`);
+    }
+    if (result.timedOut) {
+      appendTimeline(runDir, `${result.role} timed out stage ${stageName} round ${state.currentRound}`);
+      reviewerTimeouts.push({ role: result.role, timedOut: true, hadReport: result.reportExisted });
+    }
+    if (result.violatedFile) {
+      appendTimeline(runDir, `${result.role} modified protected file ${result.violatedFile} — report invalidated`);
+      reviewerViolations.push({ role: result.role, violatedFile: result.violatedFile });
+    }
+  }
+  heartbeatState(runDir, state, { currentRole: null });
+
+  // ── Phase 3: Global reviewer (sequential, only if required) ──────────────
+  const stageCriteria = spec.stageCriteria?.[stageName] ?? {};
+  const globalReviewerRequired = stageCriteria.globalReviewerRequired === true;
+  let globalReviewerOutput = null;
+  let globalReviewerTimedOut = false;
+
+  if (globalReviewerRequired) {
+    maybeAbort(runDir, state);
+    heartbeatState(runDir, state, { currentRole: 'global_reviewer' });
+    appendTimeline(runDir, `Stage ${stageName} round ${state.currentRound} global_reviewer is required — running sequentially after A/B`);
+
+    const globalReviewerConfig = roleConfig(spec, 'global_reviewer');
+    if (!globalReviewerConfig) {
+      appendTimeline(runDir, `global_reviewer config not found in spec — skipping`);
+    } else {
+      const globalReviewerPrompt = buildRolePrompt({
+        spec,
+        stage: stageName,
+        round: state.currentRound,
+        role: 'global_reviewer',
+        runDir,
+        stageDir,
+        briefPath,
+        producerPath,
+        reviewerAPath,
+        reviewerBPath,
+        globalReviewerPath: paths.globalReviewerPath,
+        workUnit,
+      });
+      const { reportPath: grReportPath, stdoutPath: grStdoutPath } = roleArtifactPaths(paths, 'global_reviewer');
+
+      if (fileExists(grReportPath) && fs.readFileSync(grReportPath, 'utf8').trim()) {
+        globalReviewerOutput = fs.readFileSync(grReportPath, 'utf8').trim();
+        updateRoleState(paths, 'global_reviewer', {
+          stage: stageName,
+          round: state.currentRound,
+          status: 'completed',
+          lastPid: null,
+          finishedAt: nowIso(),
+          timeoutSeconds: stageRoleTimeout(spec, stageName, 'global_reviewer'),
+          lastError: null,
+        });
+        appendTimeline(runDir, `global_reviewer skipped (report already exists) stage ${stageName} round ${state.currentRound}`);
+      } else {
+        updateRoleState(paths, 'global_reviewer', {
+          stage: stageName,
+          round: state.currentRound,
+          status: 'running',
+          startedAt: nowIso(),
+          finishedAt: null,
+          terminatedAt: null,
+          lastPid: null,
+          timeoutSeconds: stageRoleTimeout(spec, stageName, 'global_reviewer'),
+          lastError: null,
+        });
+        const protectedSnapshot = snapshotProtectedFiles(protectedFiles);
+        const grFailLog = path.join(stageDir, 'global-reviewer-failure.log');
+        let grOutput;
+        try {
+          grOutput = runAgent({
+            cwd: worktreeInfo?.worktreePath ?? (fileExists(spec.branchWorkspace) ? spec.branchWorkspace : spec.workspace),
+            agent: globalReviewerConfig.agent,
+            model: globalReviewerConfig.model,
+            prompt: globalReviewerPrompt,
+            timeoutSeconds: stageRoleTimeout(spec, stageName, 'global_reviewer'),
+            failLogPath: grFailLog,
+            promptDir: runDir,
+            runDir,
+            roleLabel: 'global_reviewer',
+          });
+        } catch (grErr) {
+          appendTimeline(runDir, `global_reviewer error: ${grErr.message}`);
+          grOutput = null;
+          updateRoleState(paths, 'global_reviewer', {
+            status: grErr.message?.includes('timed out') ? 'timed_out' : 'error',
+            lastPid: null,
+            finishedAt: nowIso(),
+            terminatedAt: grErr.message?.includes('timed out') ? nowIso() : null,
+            lastError: grErr.message ?? String(grErr),
+          });
+        }
+        if (grOutput) writeText(grStdoutPath, `${grOutput}\n`);
+        globalReviewerOutput = readRoleOutput({ reportPath: grReportPath, stdout: grOutput ?? '' });
+        if (globalReviewerOutput && !reportExistsAndNonEmpty(grReportPath)) {
+          writeText(grReportPath, `${globalReviewerOutput}\n`);
+        }
+        if (reportExistsAndNonEmpty(grReportPath)) {
+          updateRoleState(paths, 'global_reviewer', {
+            status: 'completed',
+            lastPid: null,
+            finishedAt: nowIso(),
+            lastError: null,
+          });
+        }
+        const grViolated = detectProtectedWriteViolation(protectedFiles, protectedSnapshot, runDir);
+        if (grViolated) {
+          appendTimeline(runDir, `global_reviewer modified protected file ${grViolated.file} — report invalidated`);
+          reviewerViolations.push({ role: 'global_reviewer', violatedFile: grViolated.file });
+        }
+        if (reportExistsAndNonEmpty(grReportPath)) {
+          appendTimeline(runDir, `global_reviewer completed stage ${stageName} round ${state.currentRound}`);
+        } else {
+          appendTimeline(runDir, `global_reviewer produced no report for stage ${stageName} round ${state.currentRound}`);
+        }
+      }
+    }
+    heartbeatState(runDir, state, { currentRole: null });
+  }
+
+  return decideAndPersist({
+    runDir,
+    stageName,
+    stageDir,
+    decisionPath,
+    scorecardPath,
+    producerPath,
+    reviewerAPath,
+    reviewerBPath,
+    globalReviewerPath,
+    state,
+    reviewerTimeouts: reviewerTimeouts.length > 0 ? reviewerTimeouts : null,
+    reviewerViolations: reviewerViolations.length > 0 ? reviewerViolations : null,
+    reviewerFailures: reviewerFailures.length > 0 ? reviewerFailures : null,
+  });
+}
+
+function abortRun(runId) {
+  const runDir = path.join(sprintRoot, runId);
+  const sprintFile = path.join(runDir, 'sprint.json');
+  if (!fileExists(sprintFile)) {
+    throw new Error(`Run not found: ${runId}`);
+  }
+  const state = readJson(sprintFile);
+  state.status = 'aborted';
+  state.haltReason = {
+    type: 'operator_abort',
+    stage: state.currentStage,
+    round: state.currentRound,
+    details: 'Aborted by operator',
+    blockers: [],
+  };
+  saveState(runDir, state);
+  updateSummary(runDir, [
+    `Status: ${state.status}`,
+    `Stage: ${state.currentStage}`,
+    `Round: ${state.currentRound}`,
+    'Operator aborted this sprint.',
+  ]);
+  const paths = ensureStagePaths(runDir, state.currentStageIndex, state.currentStage);
+  cleanupRecordedRoleProcesses(paths, runDir);
+  terminateProcessTree(state.orchestratorPid, { runDir, label: 'orchestrator' });
+  cleanupWorktree({ state, runDir });
+}
+
+function pauseRun(runId) {
+  const runDir = path.join(sprintRoot, runId);
+  const sprintFile = path.join(runDir, 'sprint.json');
+  if (!fileExists(sprintFile)) {
+    throw new Error(`Run not found: ${runId}`);
+  }
+  const state = readJson(sprintFile);
+  state.status = 'paused';
+  state.haltReason = {
+    type: 'operator_pause',
+    stage: state.currentStage,
+    round: state.currentRound,
+    details: 'Paused by operator',
+    blockers: [],
+  };
+  saveState(runDir, state);
+  updateSummary(runDir, [
+    `Status: ${state.status}`,
+    `Stage: ${state.currentStage}`,
+    `Round: ${state.currentRound}`,
+    'Operator paused this sprint.',
+  ]);
+  const paths = ensureStagePaths(runDir, state.currentStageIndex, state.currentStage);
+  cleanupRecordedRoleProcesses(paths, runDir);
+}
+
+function listRuns() {
+  ensureDir(sprintRoot);
+  const entries = [];
+  for (const entry of fs.readdirSync(sprintRoot)) {
+    const sprintFile = path.join(sprintRoot, entry, 'sprint.json');
+    if (!fileExists(sprintFile)) continue;
+    try {
+      const state = readJson(sprintFile);
+      const elapsedMin = ((Date.now() - (Date.parse(state.createdAt) || Date.now())) / 60_000).toFixed(0);
+      entries.push({
+        runId: entry,
+        task: state.taskId ?? '?',
+        title: (state.title ?? '').slice(0, 40),
+        status: state.status ?? '?',
+        stage: `${state.currentStage ?? '?'} (${(state.currentStageIndex ?? 0) + 1})`,
+        round: state.currentRound ?? '?',
+        elapsed: `${elapsedMin}m`,
+      });
+    } catch {}
+  }
+
+  if (entries.length === 0) {
+    console.log('No sprint runs found.');
+    return;
+  }
+
+  // Sort by createdAt descending (newest first)
+  entries.reverse();
+
+  const statusIcon = (s) => s === 'completed' ? '[OK]' : s === 'running' ? '>>>' : s === 'halted' ? '[!!]' : s === 'paused' ? '[||]' : '[??]';
+
+  const lines = [
+    '=== Sprint Runs ===',
+    '',
+  ];
+
+  for (const e of entries) {
+    lines.push(`  ${statusIcon(e.status)} ${e.status.padEnd(10)} ${e.runId.slice(0, 50)}`);
+    lines.push(`     ${e.task} | stage ${e.stage} | round ${e.round} | ${e.elapsed}`);
+  }
+
+  lines.push('');
+  lines.push(`  Total: ${entries.length} runs`);
+  console.log(lines.join('\n'));
+}
+
+function showStatus(runId) {
+  const runDir = path.join(sprintRoot, runId);
+  const sprintFile = path.join(runDir, 'sprint.json');
+  if (!fileExists(sprintFile)) {
+    throw new Error(`Run not found: ${runId}`);
+  }
+  const state = reconcileRunState(runDir, readJson(sprintFile));
+  const spec = loadSpec(state);
+  const now = Date.now();
+  const createdMs = Date.parse(state.createdAt) || now;
+  const heartbeatMs = Date.parse(state.lastHeartbeatAt) || now;
+  const elapsedMin = ((now - createdMs) / 60_000).toFixed(1);
+  const heartbeatAgeSec = ((now - heartbeatMs) / 1000).toFixed(0);
+  const maxRuntime = spec.maxRuntimeMinutes ?? 90;
+  const maxRounds = state.maxRoundsPerStage ?? 3;
+
+  // Find latest scorecard
+  const stageDirName = `${String(state.currentStageIndex + 1).padStart(2, '0')}-${state.currentStage}`;
+  const scorecardFile = path.join(runDir, 'stages', stageDirName, 'scorecard.json');
+  const scorecard = fileExists(scorecardFile) ? readJson(scorecardFile) : null;
+
+  // Count completed stages by scanning decision files
+  const stagesDir = path.join(runDir, 'stages');
+  const completedStages = [];
+  if (fileExists(stagesDir)) {
+    for (const entry of fs.readdirSync(stagesDir)) {
+      const decFile = path.join(stagesDir, entry, 'decision.md');
+      if (fileExists(decFile)) {
+        const text = fs.readFileSync(decFile, 'utf8');
+        const outcomeMatch = text.match(/Outcome:\s*(\w+)/);
+        completedStages.push({ dir: entry, outcome: outcomeMatch?.[1] ?? 'unknown' });
+      }
+    }
+  }
+
+  // Latest timeline entries (last 8)
+  const timelineFile = path.join(runDir, 'timeline.md');
+  let recentEvents = [];
+  if (fileExists(timelineFile)) {
+    recentEvents = fs.readFileSync(timelineFile, 'utf8')
+      .split('\n')
+      .filter((l) => l.startsWith('- '))
+      .slice(-8)
+      .map((l) => l.replace(/^- (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})\d{3}Z\s*/, ''));
+  }
+
+  // Build driver dashboard
+  const statusIcon = state.status === 'running' ? '>>>' : state.status === 'completed' ? '[OK]' : '[!!]';
+  const aliveHint = state.status === 'running'
+    ? (parseInt(heartbeatAgeSec, 10) > 120 ? `WARNING: heartbeat ${heartbeatAgeSec}s ago` : `heartbeat ${heartbeatAgeSec}s ago`)
+    : '';
+
+  const lines = [
+    `=== Sprint Dashboard ===`,
+    '',
+    `  ${statusIcon} ${state.status.toUpperCase()}`,
+    `  Task:     ${state.title}`,
+    `  Run:      ${runId}`,
+    '',
+    `  Stage:    ${state.currentStage}  (${state.currentStageIndex + 1}/${spec.stages.length})`,
+    `  Round:    ${state.currentRound} / ${maxRounds}`,
+    `  Role:     ${state.currentRole ?? 'idle'}`,
+    '',
+    `  Elapsed:  ${elapsedMin} min / ${maxRuntime} min max`,
+    `  ${aliveHint}`,
+    '',
+  ];
+
+  // Stage progress bar
+  if (spec.stages.length > 0) {
+    lines.push('  Stages:');
+    for (const stage of spec.stages) {
+      const done = completedStages.find((s) => s.dir.includes(stage));
+      const isCurrent = stage === state.currentStage;
+      const marker = done ? (done.outcome === 'advance' ? ' [PASS]' : ` [${done.outcome}]`) : (isCurrent ? ' >>' : ' --');
+      lines.push(`    ${stage}${marker}`);
+    }
+    lines.push('');
+  }
+
+  // Latest scorecard
+  if (scorecard) {
+    lines.push('  Latest round verdict:');
+    lines.push(`    reviewer_a: ${scorecard.reviewerAVerdict ?? '?'}`);
+    lines.push(`    reviewer_b: ${scorecard.reviewerBVerdict ?? '?'}`);
+    lines.push(`    approvals:  ${scorecard.approvalCount ?? 0} / 2 required`);
+    if (scorecard.failureClassification) {
+      lines.push(`    failure:    ${scorecard.failureClassification}`);
+      lines.push(`    source:     ${scorecard.failureSource ?? 'n/a'}`);
+    }
+    if (scorecard.blockerCount > 0) {
+      lines.push(`    blockers:   ${scorecard.blockerCount}`);
+      for (const b of (scorecard.blockers ?? []).slice(0, 3)) {
+        lines.push(`      - ${b.slice(0, 120)}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Recent events
+  if (recentEvents.length > 0) {
+    lines.push('  Recent events:');
+    for (const evt of recentEvents) {
+      lines.push(`    ${evt}`);
+    }
+    lines.push('');
+  }
+
+  // Controls reminder
+  lines.push('  Controls:');
+  lines.push(`    npm run ai-sprint -- --status ${runId}`);
+  lines.push(`    npm run ai-sprint -- --pause  ${runId}`);
+  lines.push(`    npm run ai-sprint -- --abort  ${runId}`);
+  lines.push(`    npm run ai-sprint -- --resume ${runId}`);
+  lines.push('');
+
+  console.log(lines.join('\n'));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log([
+      'AI Sprint Orchestrator',
+      '',
+      'Usage:',
+      '  node run.mjs --self-check                            Validate package-local environment',
+      '  node run.mjs --task <task-id> [--task-spec <path>]   Start a new sprint',
+      '  node run.mjs --resume <run-id>                        Resume a halted/aborted sprint',
+      '  node run.mjs --status <run-id>                        Show sprint dashboard',
+      '  node run.mjs --list                                   List all sprint runs',
+      '  node run.mjs --pause <run-id>                         Pause a running sprint',
+      '  node run.mjs --abort <run-id>                         Abort a sprint',
+      '  node run.mjs --archive <run-id>                       Archive a completed/halted sprint',
+      '  node run.mjs --task <task-id> --runtime-root <path>  Override runtime output root',
+      '',
+      'Sprints auto-archive on completion or halt.',
+      `Task specs are loaded from ${path.relative(packageRoot, path.join(referencesRoot, 'specs'))}/<task-id>.json`,
+      `Runtime output defaults to ${defaultRuntimeRoot}`,
+      'Override with --task-spec <path> to use a custom spec file.',
+    ].join('\n'));
+    return;
+  }
+
+  if (args['self-check']) {
+    if (args.runtimeRoot) {
+      configureRuntimeRoots(args.runtimeRoot);
+    } else {
+      configureRuntimeRoots(runtimeRoot);
+    }
+    runSelfCheck();
+    return;
+  }
+
+  if (args.list) {
+    listRuns();
+    return;
+  }
+
+  if (args.archive) {
+    try {
+      const archiveDir = archiveRunById(args.archive);
+      console.log(`Archived: ${archiveDir}`);
+    } catch (err) {
+      console.error(`Archive failed: ${err.message}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (args.abort) {
+    abortRun(args.abort);
+    console.log(`Aborted sprint ${args.abort}`);
+    return;
+  }
+
+  if (args.pause) {
+    pauseRun(args.pause);
+    console.log(`Paused sprint ${args.pause}`);
+    return;
+  }
+
+  if (args.status) {
+    showStatus(args.status);
+    return;
+  }
+
+  if (args.runtimeRoot) {
+    configureRuntimeRoots(args.runtimeRoot);
+  } else {
+    configureRuntimeRoots(runtimeRoot);
+  }
+
+  const { runDir, state } = loadOrInitState(args);
+  const spec = loadSpec(state, args);
+
+  // Register graceful shutdown handlers now that state and runDir are available.
+  // This ensures uncaught exceptions during the sprint loop write the halted state
+  // to disk instead of leaving it stuck at 'running'.
+  const gracefulHalt = (signal, detail) => {
+    if (state.status === 'running') {
+      state.status = 'halted';
+      state.haltReason = {
+        type: 'uncaught_exception',
+        stage: state.currentStage,
+        round: state.currentRound,
+        details: String(detail),
+        blockers: [String(detail)],
+      };
+      try {
+        saveState(runDir, state);
+        appendTimeline(runDir, `Sprint halted by uncaught ${signal}: ${String(detail)}`);
+      } catch (saveErr) {
+        console.error(`Failed to write halted state: ${saveErr.message}`);
+      }
+    }
+    console.error(`Fatal ${signal}: ${detail}`);
+    process.exitCode = 1;
+  };
+  process.on('uncaughtException', (err) => {
+    gracefulHalt('uncaughtException', err.stack ?? err.message);
+  });
+  process.on('unhandledRejection', (reason) => {
+    gracefulHalt('unhandledRejection', String(reason));
+  });
+
+  // Pre-flight check: verify acpx is available (the actual execution entry point).
+  // We do NOT check agent names with 'which' because acpx resolves agents via its
+  // own registry (npx, built-in commands, etc.). Checking agent binaries directly
+  // would cause false positives and is Linux-only.
+  if (!args.status && !args.list && !args.archive && !args.abort && !args.pause) {
+    const acpxCheck = checkAcpxAvailable();
+    if (acpxCheck.status !== 0) {
+      appendTimeline(runDir, `Pre-flight check FAILED: acpx not available`);
+      throw new Error(`acpx not available. Install it first: npm install -g acpx`);
+    }
+    appendTimeline(runDir, `Pre-flight check OK: acpx available`);
+  }
+
+  const sprintStartedAt = Date.parse(state.createdAt) || Date.now();
+
+  // Acquire exclusive lock to prevent concurrent orchestrators
+  const lockPath = path.join(runDir, 'orchestrator.lock');
+  if (fileExists(lockPath)) {
+    const lockData = readJson(lockPath);
+    const lockAge = Date.now() - Date.parse(lockData.acquiredAt || 0);
+    if (lockData.pid && pidExists(lockData.pid) && lockData.pid !== process.pid) {
+      if (lockAge < 30 * 60 * 1000) { // lock valid for 30 min
+        throw new Error(`Another orchestrator (PID ${lockData.pid}) is running. Acquired at ${lockData.acquiredAt}. Aborting.`);
+      }
+    }
+    // Clean up expired or stale lock
+    if (lockAge >= 30 * 60 * 1000 || !pidExists(lockData.pid)) {
+      try { fs.unlinkSync(lockPath); } catch {}
+    }
+  }
+  writeJson(lockPath, { pid: process.pid, acquiredAt: nowIso() });
+
+  appendTimeline(runDir, state.currentRound === 1 && state.currentStageIndex === 0 ? 'Sprint execution started' : 'Sprint resumed');
+
+  try {
+    while (state.status === 'running') {
+      heartbeatState(runDir, state);
+
+      // Global runtime check
+      const elapsedMinutes = (Date.now() - sprintStartedAt) / 60_000;
+      const maxRuntime = state.maxRuntimeMinutes ?? spec.maxRuntimeMinutes ?? 90;
+      if (elapsedMinutes > maxRuntime) {
+        state.status = 'halted';
+        state.haltReason = {
+          type: 'max_runtime_exceeded',
+          stage: state.currentStage,
+          round: state.currentRound,
+          details: `Sprint exceeded ${maxRuntime} minutes (elapsed: ${elapsedMinutes.toFixed(1)}min)`,
+          blockers: ['Runtime limit exceeded.'],
+        };
+        saveState(runDir, state);
+        appendTimeline(runDir, `Sprint halted: ${state.haltReason.details}`);
+        updateSummaryWithClassification(runDir, [
+          `Status: ${state.status}`,
+          `Stage: ${state.currentStage}`,
+          `Round: ${state.currentRound}`,
+          `Halt reason: ${state.haltReason.details}`,
+        ], readStageFailureClassification(runDir, state));
+        const paths = ensureStagePaths(runDir, state.currentStageIndex, state.currentStage);
+        cleanupRecordedRoleProcesses(paths, runDir);
+        break;
+      }
+
+      const decision = await executeStage(runDir, state, spec);
+      advanceState(state, spec, decision, { runDir });
+      saveState(runDir, state);
+      if (state.status === 'completed') {
+        cleanupWorktree({ state, runDir });
+        appendTimeline(runDir, 'Sprint completed');
+        updateSummary(runDir, [
+          `Status: ${state.status}`,
+          `Stage: ${state.currentStage}`,
+          `Round: ${state.currentRound}`,
+          ...(state.mergePending
+            ? [`Merge pending: push branch '${state.mergePending.targetBranch}' before merge.`]
+            : ['All stages finished.']),
+        ]);
+      }
+      if (state.status === 'halted') {
+        const paths = ensureStagePaths(runDir, state.currentStageIndex, state.currentStage);
+        cleanupRecordedRoleProcesses(paths, runDir);
+        cleanupWorktree({ state, runDir });
+        appendTimeline(runDir, `Sprint halted: ${state.haltReason?.details ?? 'unknown reason'}`);
+        updateSummaryWithClassification(runDir, [
+          `Status: ${state.status}`,
+          `Stage: ${state.currentStage}`,
+          `Round: ${state.currentRound}`,
+          `Halt reason: ${state.haltReason?.details ?? 'unknown reason'}`,
+        ], readStageFailureClassification(runDir, state));
+      }
+    }
+  } catch (error) {
+    if (state.status !== 'halted') {
+      state.status = 'halted';
+      state.haltReason = {
+        type: 'orchestrator_error',
+        stage: state.currentStage,
+        round: state.currentRound,
+        details: String(error),
+        blockers: [String(error)],
+      };
+      const paths = ensureStagePaths(runDir, state.currentStageIndex, state.currentStage);
+      cleanupRecordedRoleProcesses(paths, runDir);
+      cleanupWorktree({ state, runDir });
+      saveState(runDir, state);
+      appendTimeline(runDir, `Sprint halted by orchestrator error: ${String(error)}`);
+      updateSummaryWithClassification(runDir, [
+        `Status: ${state.status}`,
+        `Stage: ${state.currentStage}`,
+        `Round: ${state.currentRound}`,
+        `Halt reason: ${String(error)}`,
+      ], readStageFailureClassification(runDir, state) ?? inferFailureClassification({
+        summary: String(error),
+        blockers: [String(error)],
+      }));
+    }
+  }
+
+  // Auto-archive if sprint reached a terminal state
+  if (state.status === 'completed' || state.status === 'halted') {
+    try {
+      const archiveDir = archiveRunById(args.resume || path.basename(runDir));
+      appendTimeline(runDir, `Auto-archived to ${path.relative(runtimeRoot, archiveDir)}`);
+      console.log(`Archived: ${archiveDir}`);
+    } catch (archiveErr) {
+      // Archive failure must not block orchestrator exit
+      console.error(`Auto-archive failed: ${archiveErr.message}`);
+    }
+  }
+
+  // Release lock
+  try { fs.unlinkSync(lockPath); } catch {}
+
+  console.log(runDir);
+}
+
+// Only run main() when executed directly, not when imported for testing
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((err) => {
+    // main() is async and may throw. The try/catch inside main() handles
+    // errors within its body, but rejections from the Promise itself land here.
+    console.error('Fatal error:', err.message, err.stack);
+    process.exit(1);
+  });
+}