agentxchain 2.93.0 → 2.95.0

package/bin/agentxchain.js

@@ -61,6 +61,7 @@ import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
 import { replayTurnCommand } from '../src/commands/replay.js';
+import { replayExportCommand } from '../src/commands/replay-export.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
@@ -410,6 +411,14 @@ replayCmd
   .option('--timeout <ms>', 'Per-command replay timeout in milliseconds', '30000')
   .action(replayTurnCommand);
 
+replayCmd
+  .command('export <export-file>')
+  .description('Browse a completed export in the dashboard for offline post-mortem analysis')
+  .option('-j, --json', 'Output session info as JSON')
+  .option('--port <port>', 'Dashboard port', '3847')
+  .option('--no-open', 'Do not auto-open browser')
+  .action(replayExportCommand);
+
 program
   .command('migrate')
   .description('Migrate a legacy v3 project to governed format')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.93.0",
+  "version": "2.95.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/replay-export.js

@@ -0,0 +1,166 @@
+/**
+ * CLI command: agentxchain replay export <export-file>
+ *
+ * Starts the dashboard bridge-server serving a completed export's state
+ * for offline post-mortem analysis. The dashboard is fully read-only:
+ * no file watcher, no gate approval, no WebSocket push.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { tmpdir } from 'os';
+import { randomBytes } from 'crypto';
+import chalk from 'chalk';
+
+import { createBridgeServer } from '../lib/dashboard/bridge-server.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function replayExportCommand(exportFile, opts = {}) {
+  if (!exportFile) {
+    console.error(chalk.red('Usage: agentxchain replay export <export-file>'));
+    process.exit(2);
+  }
+
+  const exportPath = resolve(exportFile);
+  if (!existsSync(exportPath)) {
+    console.error(chalk.red(`Export file not found: ${exportPath}`));
+    process.exit(2);
+  }
+
+  let exportData;
+  try {
+    exportData = JSON.parse(readFileSync(exportPath, 'utf8'));
+  } catch (err) {
+    console.error(chalk.red(`Failed to parse export file: ${err.message}`));
+    process.exit(2);
+  }
+
+  if (!exportData.files || typeof exportData.files !== 'object') {
+    console.error(chalk.red('Export file missing "files" object. Not a valid agentxchain export.'));
+    process.exit(2);
+  }
+
+  // Create temp workspace with exported files
+  const tempId = randomBytes(8).toString('hex');
+  const tempRoot = join(tmpdir(), `agentxchain-replay-${tempId}`);
+  const tempAgentxchainDir = join(tempRoot, '.agentxchain');
+
+  try {
+    mkdirSync(tempRoot, { recursive: true });
+    mkdirSync(tempAgentxchainDir, { recursive: true });
+
+    // Write all embedded files from the export
+    let fileCount = 0;
+    for (const [relPath, content] of Object.entries(exportData.files)) {
+      const absPath = join(tempRoot, relPath);
+      mkdirSync(dirname(absPath), { recursive: true });
+      writeFileSync(absPath, typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+      fileCount++;
+    }
+
+    // Ensure agentxchain.json exists (needed by some dashboard endpoints)
+    const configPath = join(tempRoot, 'agentxchain.json');
+    if (!existsSync(configPath)) {
+      // Synthesize a minimal config from export summary
+      const minimalConfig = {
+        protocol_version: exportData.summary?.protocol_version || 6,
+        protocol_mode: 'governed',
+        version: 4,
+        project: { name: exportData.summary?.project_name || 'replay-export' },
+        roles: exportData.summary?.roles || {},
+        runtimes: {},
+        workflow: exportData.summary?.workflow || {},
+      };
+      writeFileSync(configPath, JSON.stringify(minimalConfig, null, 2));
+    }
+
+    const dashboardDir = join(__dirname, '..', '..', 'dashboard');
+    if (!existsSync(dashboardDir)) {
+      console.error(chalk.red('Dashboard assets not found.'));
+      cleanup(tempRoot);
+      process.exit(1);
+    }
+
+    const port = parseInt(opts.port, 10) || 3847;
+    const bridge = createBridgeServer({
+      agentxchainDir: tempAgentxchainDir,
+      dashboardDir,
+      port,
+      replayMode: true,
+    });
+
+    const { port: actualPort } = await bridge.start();
+    const url = `http://localhost:${actualPort}`;
+
+    const runId = exportData.summary?.run_id || null;
+    const schemaVersion = exportData.schema_version || null;
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        port: actualPort,
+        url,
+        export_file: exportPath,
+        run_id: runId,
+        export_schema_version: schemaVersion,
+        files_restored: fileCount,
+        temp_dir: tempRoot,
+      }, null, 2));
+    } else {
+      console.log('');
+      console.log(chalk.bold(`  Replay Export Dashboard`));
+      console.log(chalk.dim('  ' + '─'.repeat(40)));
+      console.log(`  ${chalk.dim('Export:')}   ${exportPath}`);
+      console.log(`  ${chalk.dim('Run ID:')}   ${runId || '—'}`);
+      console.log(`  ${chalk.dim('Schema:')}   ${schemaVersion || '—'}`);
+      console.log(`  ${chalk.dim('Files:')}    ${fileCount} restored`);
+      console.log(`  ${chalk.dim('URL:')}      ${chalk.cyan(url)}`);
+      console.log('');
+      console.log(chalk.dim('  Read-only mode — no live updates, no gate approval.'));
+      console.log(chalk.dim('  Press Ctrl+C to stop.'));
+      console.log('');
+    }
+
+    if (opts.open !== false && !opts.json) {
+      try {
+        const { exec } = await import('child_process');
+        const openCmd = process.platform === 'darwin' ? 'open'
+          : process.platform === 'win32' ? 'start'
+          : 'xdg-open';
+        exec(`${openCmd} ${url}`);
+      } catch {
+        // Browser open is best-effort
+      }
+    }
+
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      if (!opts.json) {
+        console.log('\nShutting down replay dashboard...');
+      }
+      await bridge.stop();
+      cleanup(tempRoot);
+      process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  } catch (err) {
+    cleanup(tempRoot);
+    if (err.code === 'EADDRINUSE') {
+      console.error(chalk.red(`Port ${opts.port || 3847} is already in use. Try --port <number>.`));
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+function cleanup(tempRoot) {
+  try {
+    rmSync(tempRoot, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup
+  }
+}

package/src/lib/dashboard/bridge-server.js

@@ -16,9 +16,11 @@ import { readFileSync, existsSync } from 'fs';
 import { join, extname, resolve, sep } from 'path';
 import { readResource } from './state-reader.js';
 import { FileWatcher } from './file-watcher.js';
+import { readRunEvents, RUN_EVENTS_PATH } from '../run-events.js';
 import { approvePendingDashboardGate } from './actions.js';
 import { readCoordinatorBlockerSnapshot } from './coordinator-blockers.js';
 import { readCoordinatorTimeoutStatus } from './coordinator-timeout-status.js';
+import { readAggregatedCoordinatorEvents, watchChildRepoEvents } from './coordinator-event-aggregation.js';
 import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
 import { readConnectorHealthSnapshot } from './connectors.js';
 import { readTimeoutStatus } from './timeout-status.js';
@@ -213,11 +215,22 @@ function resolveDashboardAssetPath(dashboardDir, pathname) {
 
 // ── Bridge Server ───────────────────────────────────────────────────────────
 
-export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }) {
+export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847, replayMode = false }) {
   const workspacePath = resolve(agentxchainDir, '..');
   const wsClients = new Set();
+  /** @type {Map<import('net').Socket, Set<string>|null>} null = all events */
+  const wsEventSubscriptions = new Map();
   const watcher = new FileWatcher(agentxchainDir);
   const mutationToken = randomBytes(24).toString('hex');
+  let lastEventsFileSize = 0;
+
+  // Initialize events file size tracking
+  try {
+    const eventsPath = join(agentxchainDir, 'events.jsonl');
+    if (existsSync(eventsPath)) {
+      lastEventsFileSize = readFileSync(eventsPath).length;
+    }
+  } catch {}
 
   // Broadcast invalidation events to all connected WebSocket clients
   watcher.on('invalidate', ({ resource }) => {
@@ -225,8 +238,53 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
     for (const socket of wsClients) {
       sendWsFrame(socket, msg);
     }
+
+    // For events.jsonl changes, also push actual event data
+    if (resource === '/api/events') {
+      try {
+        const eventsPath = join(agentxchainDir, 'events.jsonl');
+        if (!existsSync(eventsPath)) return;
+        const content = readFileSync(eventsPath, 'utf8');
+        if (content.length <= lastEventsFileSize) {
+          // File was truncated — reset and push all
+          if (content.length < lastEventsFileSize) lastEventsFileSize = 0;
+          else return;
+        }
+        const newContent = content.slice(lastEventsFileSize);
+        lastEventsFileSize = content.length;
+        const lines = newContent.split('\n').filter(Boolean);
+        for (const line of lines) {
+          try {
+            const evt = JSON.parse(line);
+            for (const socket of wsClients) {
+              const filter = wsEventSubscriptions.get(socket);
+              if (filter && !filter.has(evt.event_type)) continue;
+              sendWsFrame(socket, JSON.stringify({ type: 'event', event: evt }));
+            }
+          } catch {}
+        }
+      } catch {}
+    }
   });
 
+  // Set up child-repo event watchers for coordinator event aggregation
+  let childRepoWatcher = null;
+  try {
+    const watchResult = watchChildRepoEvents(workspacePath, (_repoId, newEvents) => {
+      for (const evt of newEvents) {
+        const msg = JSON.stringify({ type: 'coordinator_event', repo_id: evt.repo_id, event: evt });
+        for (const socket of wsClients) {
+          const filter = wsEventSubscriptions.get(socket);
+          if (filter && !filter.has('coordinator_event')) continue;
+          sendWsFrame(socket, msg);
+        }
+      }
+    });
+    if (watchResult.ok) {
+      childRepoWatcher = watchResult;
+    }
+  } catch {}
+
   const server = createServer(async (req, res) => {
     const method = req.method || 'GET';
     const isApproveGateRequest = method === 'POST' && req.url && new URL(req.url, `http://${req.headers.host}`).pathname === '/api/actions/approve-gate';
@@ -247,15 +305,21 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
     if (pathname === '/api/session') {
       writeJson(res, 200, {
         session_version: '1',
-        mutation_token: mutationToken,
+        mutation_token: replayMode ? null : mutationToken,
+        replay_mode: replayMode,
         capabilities: {
-          approve_gate: true,
+          approve_gate: !replayMode,
         },
       });
       return;
     }
 
     if (pathname === '/api/actions/approve-gate') {
+      if (replayMode) {
+        writeJson(res, 403, { ok: false, code: 'replay_mode', error: 'Replay mode: gate approval is not available on exported snapshots.' });
+        return;
+      }
+
       if (method !== 'POST') {
         writeJson(res, 405, { ok: false, code: 'method_not_allowed', error: 'Use POST for dashboard actions.' }, { Allow: 'POST' });
         return;
@@ -290,6 +354,24 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/coordinator/events') {
+      const type = url.searchParams.get('type') || undefined;
+      const since = url.searchParams.get('since') || undefined;
+      const repoId = url.searchParams.get('repo_id') || undefined;
+      const limitParam = url.searchParams.get('limit');
+      const limit = limitParam != null ? parseInt(limitParam, 10) : 100;
+      const result = readAggregatedCoordinatorEvents(workspacePath, {
+        type, since, repo_id: repoId, limit: limit === 0 ? undefined : limit,
+      });
+      if (!result.ok) {
+        const isMissingConfig = typeof result.error === 'string' && result.error.includes('config_missing:');
+        writeJson(res, isMissingConfig ? 404 : 500, { error: result.error });
+        return;
+      }
+      writeJson(res, 200, result.events);
+      return;
+    }
+
     if (pathname === '/api/workflow-kit-artifacts') {
       const result = readWorkflowKitArtifacts(workspacePath);
       writeJson(res, result.status, result.body);
@@ -308,6 +390,20 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/events') {
+      const type = url.searchParams.get('type') || undefined;
+      const since = url.searchParams.get('since') || undefined;
+      const runId = url.searchParams.get('run_id') || undefined;
+      const limitParam = url.searchParams.get('limit');
+      const limit = limitParam != null ? parseInt(limitParam, 10) : 50;
+      let events = readRunEvents(workspacePath, { type, since, limit: limit === 0 ? undefined : limit });
+      if (runId) {
+        events = events.filter(e => e.run_id === runId);
+      }
+      writeJson(res, 200, events);
+      return;
+    }
+
     if (pathname === '/api/run-history') {
       const url = new URL(req.url, `http://${req.headers.host}`);
       const limit = url.searchParams.get('limit') ? parseInt(url.searchParams.get('limit'), 10) : undefined;
@@ -365,11 +461,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
     if (!ws) return;
 
     wsClients.add(ws);
+    wsEventSubscriptions.set(ws, null); // null = all events
 
-    ws.on('close', () => wsClients.delete(ws));
-    ws.on('error', () => wsClients.delete(ws));
+    ws.on('close', () => { wsClients.delete(ws); wsEventSubscriptions.delete(ws); });
+    ws.on('error', () => { wsClients.delete(ws); wsEventSubscriptions.delete(ws); });
 
-    // Handle incoming frames (for ping/pong and close detection)
+    // Handle incoming frames (for ping/pong, close detection, and subscribe)
     ws.on('data', (data) => {
       const frame = parseClientFrame(data);
       if (!frame) return;
@@ -377,15 +474,30 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       if (frame.opcode === 0x08) {
         // Close frame
         wsClients.delete(ws);
+        wsEventSubscriptions.delete(ws);
         sendWsControlFrame(ws, 0x08, frame.payload);
         try { ws.end(); } catch {}
       } else if (frame.opcode === 0x09) {
         // Ping → Pong
         sendWsControlFrame(ws, 0x0a, frame.payload);
       } else if (frame.opcode === 0x01) {
+        // Text frame — check for subscribe message
+        try {
+          const msg = JSON.parse(frame.payload.toString('utf8'));
+          if (msg.type === 'subscribe' && Array.isArray(msg.event_types)) {
+            wsEventSubscriptions.set(ws, new Set(msg.event_types));
+            sendWsFrame(ws, JSON.stringify({ type: 'subscribed', event_types: msg.event_types }));
+            return;
+          }
+          if (msg.type === 'subscribe' && !msg.event_types) {
+            wsEventSubscriptions.set(ws, null); // reset to all
+            sendWsFrame(ws, JSON.stringify({ type: 'subscribed', event_types: null }));
+            return;
+          }
+        } catch {}
         sendWsError(
           ws,
-          'Dashboard WebSocket is read-only. Use the authenticated HTTP approve-gate action instead.'
+          'Dashboard WebSocket is read-only except for event subscription. Use the authenticated HTTP approve-gate action for mutations.'
         );
       }
     });
@@ -404,6 +516,7 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
   function stop() {
     return new Promise((resolve) => {
       watcher.stop();
+      if (childRepoWatcher?.stop) childRepoWatcher.stop();
       for (const socket of wsClients) {
         try { socket.destroy(); } catch {}
       }

package/src/lib/dashboard/coordinator-event-aggregation.js

@@ -0,0 +1,169 @@
+/**
+ * Coordinator event aggregation — merges lifecycle events from all child
+ * repos in a multi-repo coordinator run into a single time-ordered stream.
+ *
+ * See: .planning/COORDINATOR_EVENT_AGGREGATION_SPEC.md
+ */
+
+import { existsSync, readFileSync, watchFile, unwatchFile, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { loadCoordinatorConfig } from '../coordinator-config.js';
+import { RUN_EVENTS_PATH } from '../run-events.js';
+
+/**
+ * Read and merge events from all child repos defined in the coordinator config.
+ *
+ * @param {string} workspacePath - Coordinator workspace root
+ * @param {object} [opts]        - Filter options
+ * @param {string} [opts.type]   - Comma-separated event types
+ * @param {string} [opts.since]  - ISO-8601 timestamp
+ * @param {number} [opts.limit]  - Max events (from end, default 100)
+ * @param {string} [opts.repo_id] - Filter to one repo
+ * @returns {{ ok: boolean, events?: object[], error?: string }}
+ */
+export function readAggregatedCoordinatorEvents(workspacePath, opts = {}) {
+  const configResult = loadCoordinatorConfig(workspacePath);
+  if (!configResult.ok) {
+    return { ok: false, error: configResult.errors.join('; ') };
+  }
+
+  const config = configResult.config;
+  let allEvents = [];
+
+  for (const [repoId, repo] of Object.entries(config.repos)) {
+    if (opts.repo_id && opts.repo_id !== repoId) continue;
+
+    const repoPath = resolve(workspacePath, repo.path);
+    const eventsPath = join(repoPath, RUN_EVENTS_PATH);
+
+    if (!existsSync(eventsPath)) continue;
+
+    let raw;
+    try {
+      raw = readFileSync(eventsPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = raw.split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const evt = JSON.parse(line);
+        evt.repo_id = repoId;
+        allEvents.push(evt);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  }
+
+  // Apply type filter
+  if (opts.type) {
+    const types = new Set(opts.type.split(',').map(t => t.trim()));
+    allEvents = allEvents.filter(e => types.has(e.event_type));
+  }
+
+  // Apply since filter
+  if (opts.since) {
+    const sinceMs = new Date(opts.since).getTime();
+    if (!Number.isNaN(sinceMs)) {
+      allEvents = allEvents.filter(e => new Date(e.timestamp).getTime() > sinceMs);
+    }
+  }
+
+  // Sort by timestamp ascending, ties broken by event_id
+  allEvents.sort((a, b) => {
+    const tDiff = new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime();
+    if (tDiff !== 0) return tDiff;
+    return (a.event_id || '').localeCompare(b.event_id || '');
+  });
+
+  // Apply limit (from end)
+  const limit = opts.limit ?? 100;
+  if (limit > 0 && allEvents.length > limit) {
+    allEvents = allEvents.slice(-limit);
+  }
+
+  return { ok: true, events: allEvents };
+}
+
+/**
+ * Set up file watchers on child repo events.jsonl files for real-time
+ * WebSocket push. Returns a controller with a stop() method.
+ *
+ * @param {string} workspacePath - Coordinator workspace root
+ * @param {function} onNewEvents - Callback: (repoId, events[]) => void
+ * @returns {{ ok: boolean, stop?: function, error?: string }}
+ */
+export function watchChildRepoEvents(workspacePath, onNewEvents) {
+  const configResult = loadCoordinatorConfig(workspacePath);
+  if (!configResult.ok) {
+    return { ok: false, error: configResult.errors.join('; ') };
+  }
+
+  const config = configResult.config;
+  const trackedFiles = new Map(); // eventsPath → { repoId, lastSize }
+  const watchedPaths = [];
+
+  for (const [repoId, repo] of Object.entries(config.repos)) {
+    const repoPath = resolve(workspacePath, repo.path);
+    const eventsPath = join(repoPath, RUN_EVENTS_PATH);
+
+    let initialSize = 0;
+    try {
+      if (existsSync(eventsPath)) {
+        initialSize = statSync(eventsPath).size;
+      }
+    } catch {}
+
+    trackedFiles.set(eventsPath, { repoId, lastSize: initialSize });
+
+    // Use fs.watchFile (polling) for reliability across platforms
+    try {
+      watchFile(eventsPath, { interval: 500 }, (curr) => {
+        const tracked = trackedFiles.get(eventsPath);
+        if (!tracked) return;
+
+        const currentSize = curr.size;
+        if (currentSize <= tracked.lastSize) {
+          // File truncated or unchanged
+          if (currentSize < tracked.lastSize) {
+            tracked.lastSize = 0;
+          } else {
+            return;
+          }
+        }
+
+        try {
+          const content = readFileSync(eventsPath, 'utf8');
+          const newContent = content.slice(tracked.lastSize);
+          tracked.lastSize = content.length;
+
+          const lines = newContent.split('\n').filter(Boolean);
+          const newEvents = [];
+          for (const line of lines) {
+            try {
+              const evt = JSON.parse(line);
+              evt.repo_id = tracked.repoId;
+              newEvents.push(evt);
+            } catch {}
+          }
+
+          if (newEvents.length > 0) {
+            onNewEvents(tracked.repoId, newEvents);
+          }
+        } catch {}
+      });
+      watchedPaths.push(eventsPath);
+    } catch {}
+  }
+
+  function stop() {
+    for (const path of watchedPaths) {
+      try { unwatchFile(path); } catch {}
+    }
+    trackedFiles.clear();
+  }
+
+  return { ok: true, stop };
+}

package/src/lib/dashboard/state-reader.js

@@ -17,6 +17,7 @@ const HISTORY_FILE = 'history.jsonl';
 const LEDGER_FILE = 'decision-ledger.jsonl';
 const HOOK_AUDIT_FILE = 'hook-audit.jsonl';
 const HOOK_ANNOTATIONS_FILE = 'hook-annotations.jsonl';
+const EVENTS_FILE = 'events.jsonl';
 const MULTIREPO_DIR = 'multirepo';
 const BARRIERS_FILE = 'barriers.json';
 const BARRIER_LEDGER_FILE = 'barrier-ledger.jsonl';
@@ -38,6 +39,7 @@ export const RESOURCE_MAP = {
   '/api/coordinator/barrier-ledger': join(MULTIREPO_DIR, BARRIER_LEDGER_FILE),
   '/api/coordinator/hooks/audit': join(MULTIREPO_DIR, HOOK_AUDIT_FILE),
   '/api/coordinator/hooks/annotations': join(MULTIREPO_DIR, HOOK_ANNOTATIONS_FILE),
+  '/api/events': EVENTS_FILE,
 };
 
 /**

package/src/lib/dispatch-bundle.js

@@ -575,6 +575,11 @@ function renderContext(state, config, root, turn, role) {
         lines.push(`  - ${req}`);
       }
     }
+    if (Array.isArray(dc.required_decision_ids) && dc.required_decision_ids.length > 0) {
+      lines.push(`- **Required decisions:** ${dc.required_decision_ids.join(', ')}`);
+      lines.push('');
+      lines.push('Your accepted turn must emit these decision IDs in `decisions[]` before the parent review may advance the phase or complete the run.');
+    }
     lines.push('');
     lines.push('Focus exclusively on the charter above. Do not expand scope beyond the delegation.');
     lines.push('');
@@ -599,9 +604,14 @@ function renderContext(state, config, root, turn, role) {
       if (result.verification?.status) {
         lines.push(`- **Verification:** ${result.verification.status}`);
       }
+      if (Array.isArray(result.required_decision_ids) && result.required_decision_ids.length > 0) {
+        lines.push(`- **Required decisions:** ${result.required_decision_ids.join(', ')}`);
+        lines.push(`- **Satisfied decisions:** ${(result.satisfied_decision_ids || []).join(', ') || 'none'}`);
+        lines.push(`- **Missing decisions:** ${(result.missing_decision_ids || []).join(', ') || 'none'}`);
+      }
       lines.push('');
     }
-    lines.push('Evaluate whether each delegation met its acceptance contract.');
+    lines.push('Evaluate whether each delegation met its acceptance contract and returned any required named decisions.');
     lines.push('Your turn result should assess the delegation outcomes and decide next steps.');
     lines.push('');
   }

package/src/lib/export-verifier.js

@@ -110,6 +110,100 @@ function verifyFilesMap(files, errors) {
   }
 }
 
+function compareEventOrder(a, b) {
+  const left = Date.parse(a?.timestamp || '');
+  const right = Date.parse(b?.timestamp || '');
+  const leftTime = Number.isNaN(left) ? Number.POSITIVE_INFINITY : left;
+  const rightTime = Number.isNaN(right) ? Number.POSITIVE_INFINITY : right;
+  if (leftTime !== rightTime) {
+    return leftTime - rightTime;
+  }
+  return String(a?.event_id || '').localeCompare(String(b?.event_id || ''));
+}
+
+function buildExpectedAggregatedEventsSummary(repos) {
+  const events = [];
+  const reposWithEvents = new Set();
+
+  for (const [repoId, repoEntry] of Object.entries(repos || {})) {
+    if (!repoEntry?.ok || !repoEntry.export || typeof repoEntry.export !== 'object' || Array.isArray(repoEntry.export)) {
+      continue;
+    }
+
+    const repoEvents = repoEntry.export.files?.['.agentxchain/events.jsonl']?.data;
+    if (!Array.isArray(repoEvents)) {
+      continue;
+    }
+
+    for (const event of repoEvents) {
+      if (!event || typeof event !== 'object' || Array.isArray(event)) {
+        continue;
+      }
+      events.push({
+        ...event,
+        repo_id: repoId,
+      });
+      reposWithEvents.add(repoId);
+    }
+  }
+
+  events.sort(compareEventOrder);
+
+  const eventTypeCounts = {};
+  for (const event of events) {
+    const type = event.event_type || event.type || 'unknown';
+    eventTypeCounts[type] = (eventTypeCounts[type] || 0) + 1;
+  }
+
+  return {
+    total_events: events.length,
+    repos_with_events: [...reposWithEvents].sort(),
+    event_type_counts: eventTypeCounts,
+    events,
+  };
+}
+
+function verifyAggregatedEventsSummary(artifact, errors) {
+  const summary = artifact.summary?.aggregated_events;
+  if (summary === undefined || summary === null) {
+    return;
+  }
+
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+    addError(errors, 'summary.aggregated_events', 'must be an object when present');
+    return;
+  }
+
+  const failedRepoIds = Object.entries(artifact.repos || {})
+    .filter(([, repoEntry]) => repoEntry && typeof repoEntry === 'object' && !Array.isArray(repoEntry) && repoEntry.ok === false)
+    .map(([repoId]) => repoId);
+
+  for (const repoId of failedRepoIds) {
+    if (summary.repos_with_events?.includes(repoId)) {
+      addError(
+        errors,
+        'summary.aggregated_events.repos_with_events',
+        `cannot include repo "${repoId}" when repos.${repoId}.ok is false because no nested export proof is available`,
+      );
+    }
+  }
+
+  const expected = buildExpectedAggregatedEventsSummary(artifact.repos);
+
+  if (summary.total_events !== expected.total_events) {
+    addError(errors, 'summary.aggregated_events.total_events', 'must match reconstructed aggregated event count');
+  }
+  if (!isDeepStrictEqual(summary.repos_with_events, expected.repos_with_events)) {
+    addError(errors, 'summary.aggregated_events.repos_with_events', 'must match reconstructed contributing repo ids');
+  }
+  if (!isDeepStrictEqual(summary.event_type_counts, expected.event_type_counts)) {
+    addError(errors, 'summary.aggregated_events.event_type_counts', 'must match reconstructed event type counts');
+  }
+  if (!isDeepStrictEqual(summary.events, expected.events)) {
+    addError(errors, 'summary.aggregated_events.events', 'must match reconstructed sorted aggregated event list');
+  }
+}
+
 function countJsonl(files, relPath) {
   return Array.isArray(files?.[relPath]?.data) ? files[relPath].data.length : 0;
 }
@@ -343,6 +437,8 @@ function verifyCoordinatorExport(artifact, errors) {
       addError(errors, `${repoPath}.export`, nestedError);
     }
   }
+
+  verifyAggregatedEventsSummary(artifact, errors);
 }
 
 export function verifyExportArtifact(artifact) {

package/src/lib/export.js

@@ -9,6 +9,7 @@ import { loadCoordinatorState } from './coordinator-state.js';
 import { normalizeRunProvenance } from './run-provenance.js';
 import { getDashboardPid, getDashboardSession } from '../commands/dashboard.js';
 import { readRepoDecisions } from './repo-decisions.js';
+import { RUN_EVENTS_PATH } from './run-events.js';
 
 const EXPORT_SCHEMA_VERSION = '0.3';
 
@@ -279,6 +280,9 @@ export function buildDelegationSummary(files) {
         delegation_id: del.id,
         to_role: del.to_role,
         charter: del.charter,
+        required_decision_ids: Array.isArray(del.required_decision_ids) ? del.required_decision_ids : [],
+        satisfied_decision_ids: Array.isArray(reviewResult?.satisfied_decision_ids) ? reviewResult.satisfied_decision_ids : [],
+        missing_decision_ids: Array.isArray(reviewResult?.missing_decision_ids) ? reviewResult.missing_decision_ids : [],
         status: reviewResult?.status || child?.status || 'pending',
         child_turn_id: child?.turn_id || null,
       };
@@ -474,6 +478,62 @@ export function buildRunExport(startDir = process.cwd()) {
   };
 }
 
+/**
+ * Build aggregated child-repo lifecycle events summary for coordinator exports.
+ * Reads events.jsonl from each child repo, tags with repo_id, merges, sorts.
+ */
+function buildAggregatedEventsSummary(workspaceRoot, repoEntries) {
+  let allEvents = [];
+  const reposWithEvents = new Set();
+
+  for (const [repoId, repoDef] of repoEntries) {
+    const repoPath = resolve(workspaceRoot, repoDef?.path || '');
+    const eventsPath = join(repoPath, RUN_EVENTS_PATH);
+
+    if (!existsSync(eventsPath)) continue;
+
+    let raw;
+    try {
+      raw = readFileSync(eventsPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = raw.split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const evt = JSON.parse(line);
+        evt.repo_id = repoId;
+        allEvents.push(evt);
+        reposWithEvents.add(repoId);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  }
+
+  // Sort by timestamp ascending, ties broken by event_id
+  allEvents.sort((a, b) => {
+    const tDiff = new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime();
+    if (tDiff !== 0) return tDiff;
+    return (a.event_id || '').localeCompare(b.event_id || '');
+  });
+
+  // Count event types
+  const eventTypeCounts = {};
+  for (const evt of allEvents) {
+    const t = evt.event_type || evt.type || 'unknown';
+    eventTypeCounts[t] = (eventTypeCounts[t] || 0) + 1;
+  }
+
+  return {
+    total_events: allEvents.length,
+    repos_with_events: [...reposWithEvents].sort(),
+    event_type_counts: eventTypeCounts,
+    events: allEvents,
+  };
+}
+
 export function buildCoordinatorExport(startDir = process.cwd()) {
   const workspaceRoot = resolve(startDir);
   const configPath = join(workspaceRoot, COORDINATOR_CONFIG_FILE);
@@ -584,6 +644,7 @@ export function buildCoordinatorExport(startDir = process.cwd()) {
         barrier_count: barrierCount,
         history_entries: countJsonl(files, '.agentxchain/multirepo/history.jsonl'),
         decision_entries: countJsonl(files, '.agentxchain/multirepo/decision-ledger.jsonl'),
+        aggregated_events: buildAggregatedEventsSummary(workspaceRoot, repoEntries),
       },
       files,
       config: rawConfig,

package/src/lib/governed-state.js

@@ -2152,6 +2152,7 @@ export function assignGovernedTurn(root, config, roleId) {
       parent_role: pendingDelegation.parent_role,
       charter: pendingDelegation.charter,
       acceptance_contract: pendingDelegation.acceptance_contract,
+      required_decision_ids: pendingDelegation.required_decision_ids || [],
     };
     // Mark the delegation as active
     pendingDelegation.status = 'active';
@@ -2742,6 +2743,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
             to_role: delegation.to_role,
             charter: delegation.charter,
             acceptance_contract: delegation.acceptance_contract,
+            required_decision_ids: delegation.required_decision_ids || [],
           })),
         }
       : {}),
@@ -2753,6 +2755,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
             parent_role: currentTurn.delegation_context.parent_role,
             charter: currentTurn.delegation_context.charter,
             acceptance_contract: currentTurn.delegation_context.acceptance_contract,
+            required_decision_ids: currentTurn.delegation_context.required_decision_ids || [],
           },
         }
       : {}),
@@ -2833,6 +2836,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         to_role: del.to_role,
         charter: del.charter,
         acceptance_contract: del.acceptance_contract,
+        required_decision_ids: del.required_decision_ids || [],
         status: 'pending',
         child_turn_id: null,
         created_at: now,
@@ -2859,12 +2863,23 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         // Build delegation review context
         const delegationResults = parentDelegations.map(d => {
           const childHistory = nextHistoryEntries.find(h => h.turn_id === d.child_turn_id);
+          const childDecisionIds = Array.isArray(childHistory?.decisions)
+            ? childHistory.decisions
+              .map((decision) => decision?.id)
+              .filter((id) => typeof id === 'string')
+            : [];
+          const requiredDecisionIds = Array.isArray(d.required_decision_ids) ? d.required_decision_ids : [];
+          const satisfiedDecisionIds = requiredDecisionIds.filter((id) => childDecisionIds.includes(id));
+          const missingDecisionIds = requiredDecisionIds.filter((id) => !childDecisionIds.includes(id));
           return {
             delegation_id: d.delegation_id,
             child_turn_id: d.child_turn_id,
             to_role: d.to_role,
             charter: d.charter,
             acceptance_contract: d.acceptance_contract,
+            required_decision_ids: requiredDecisionIds,
+            satisfied_decision_ids: satisfiedDecisionIds,
+            missing_decision_ids: missingDecisionIds,
             summary: childHistory?.summary || '(no summary)',
             status: d.status,
             files_changed: childHistory?.files_changed || [],

package/src/lib/report.js

@@ -33,6 +33,9 @@ function normalizeDelegationSummary(summary) {
         delegation_id: delegation.delegation_id,
         to_role: delegation.to_role,
         charter: delegation.charter,
+        required_decision_ids: Array.isArray(delegation.required_decision_ids) ? delegation.required_decision_ids : [],
+        satisfied_decision_ids: Array.isArray(delegation.satisfied_decision_ids) ? delegation.satisfied_decision_ids : [],
+        missing_decision_ids: Array.isArray(delegation.missing_decision_ids) ? delegation.missing_decision_ids : [],
         status: delegation.status,
         child_turn_id: delegation.child_turn_id,
       });
@@ -625,6 +628,19 @@ function extractCoordinatorTimeline(artifact) {
     });
 }
 
+function extractAggregatedEventTimeline(artifact) {
+  const aggEvents = artifact.summary?.aggregated_events;
+  if (!aggEvents || !Array.isArray(aggEvents.events) || aggEvents.events.length === 0) return [];
+  return aggEvents.events.map((evt) => ({
+    repo_id: evt.repo_id || null,
+    type: evt.event_type || evt.type || 'unknown',
+    timestamp: evt.timestamp || null,
+    run_id: evt.run_id || null,
+    event_id: evt.event_id || null,
+    summary: `[${evt.repo_id || '?'}] ${evt.event_type || evt.type || 'unknown'} at ${evt.timestamp || '?'}`,
+  }));
+}
+
 function computeCoordinatorTiming(artifact, coordinatorTimeline) {
   const coordinatorState = extractFileData(artifact, '.agentxchain/multirepo/state.json');
   const createdAtFromHistory = coordinatorTimeline
@@ -1118,6 +1134,7 @@ function buildCoordinatorSubject(artifact) {
       repo_error_count: repoErrorCount,
     },
     coordinator_timeline: coordinatorTimeline,
+    aggregated_event_timeline: extractAggregatedEventTimeline(artifact),
     barrier_summary: barrierSummary,
     barrier_ledger_timeline: barrierLedgerTimeline,
     decision_digest: decisionDigest,
@@ -1290,6 +1307,11 @@ export function formatGovernanceReportText(report) {
         lines.push(`  - ${chain.parent_role} (${chain.parent_turn_id}) | outcome: ${chain.outcome} | review: ${chain.review_turn_id || 'pending'}`);
         for (const delegation of chain.delegations) {
           lines.push(`      ${delegation.delegation_id} -> ${delegation.to_role} | ${delegation.status} | child: ${delegation.child_turn_id || 'pending'} | ${delegation.charter}`);
+          if (delegation.required_decision_ids?.length > 0) {
+            lines.push(`        required decisions: ${delegation.required_decision_ids.join(', ')}`);
+            lines.push(`        satisfied decisions: ${delegation.satisfied_decision_ids.join(', ') || 'none'}`);
+            lines.push(`        missing decisions: ${delegation.missing_decision_ids.join(', ') || 'none'}`);
+          }
         }
       }
     }
@@ -1496,6 +1518,17 @@ export function formatGovernanceReportText(report) {
     }
   }
 
+  const aggregated_event_timeline = report.subject.aggregated_event_timeline;
+  if (aggregated_event_timeline && aggregated_event_timeline.length > 0) {
+    lines.push('', 'Aggregated Child Repo Events:');
+    for (const evt of aggregated_event_timeline) {
+      const ts = evt.timestamp ? ` [${evt.timestamp}]` : '';
+      lines.push(`  [${evt.repo_id || '?'}] ${evt.type}${ts}`);
+    }
+  } else {
+    lines.push('', 'Aggregated Child Repo Events:', '  No child repo events.');
+  }
+
   if (barrier_summary && barrier_summary.length > 0) {
     lines.push('', 'Barrier Summary:');
     for (const b of barrier_summary) {
@@ -1773,7 +1806,7 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.delegation_summary?.delegation_chains?.length > 0) {
       lines.push('', '## Delegation Summary', '');
       lines.push(`- Total delegations issued: ${run.delegation_summary.total_delegations_issued}`, '');
-      lines.push('| Parent Role | Parent Turn | Outcome | Review Turn | Delegation | Child Turn | Status | Charter |', '|-------------|-------------|---------|-------------|------------|------------|--------|---------|');
+      lines.push('| Parent Role | Parent Turn | Outcome | Review Turn | Delegation | Child Turn | Status | Required Decisions | Missing Decisions | Charter |', '|-------------|-------------|---------|-------------|------------|------------|--------|--------------------|-------------------|---------|');
       for (const chain of run.delegation_summary.delegation_chains) {
         for (let i = 0; i < chain.delegations.length; i++) {
           const delegation = chain.delegations[i];
@@ -1782,7 +1815,9 @@ export function formatGovernanceReportMarkdown(report) {
           const outcome = i === 0 ? `\`${chain.outcome}\`` : '';
           const reviewTurn = i === 0 ? `\`${chain.review_turn_id || 'pending'}\`` : '';
           const charter = delegation.charter.replace(/\|/g, '\\|');
-          lines.push(`| ${parentRole} | ${parentTurn} | ${outcome} | ${reviewTurn} | \`${delegation.delegation_id}\` → \`${delegation.to_role}\` | \`${delegation.child_turn_id || 'pending'}\` | \`${delegation.status}\` | ${charter} |`);
+          const requiredDecisions = (delegation.required_decision_ids || []).join(', ').replace(/\|/g, '\\|') || '—';
+          const missingDecisions = (delegation.missing_decision_ids || []).join(', ').replace(/\|/g, '\\|') || '—';
+          lines.push(`| ${parentRole} | ${parentTurn} | ${outcome} | ${reviewTurn} | \`${delegation.delegation_id}\` → \`${delegation.to_role}\` | \`${delegation.child_turn_id || 'pending'}\` | \`${delegation.status}\` | ${requiredDecisions} | ${missingDecisions} | ${charter} |`);
         }
       }
     }
@@ -1996,6 +2031,18 @@ export function formatGovernanceReportMarkdown(report) {
     }
   }
 
+  const aggregated_event_timeline = report.subject.aggregated_event_timeline;
+  if (aggregated_event_timeline && aggregated_event_timeline.length > 0) {
+    mdLines.push('', '## Aggregated Child Repo Events', '', '| Timestamp | Repo | Event Type | Summary |', '|-----------|------|------------|---------|');
+    for (const evt of aggregated_event_timeline) {
+      const ts = evt.timestamp ? `\`${evt.timestamp}\`` : 'n/a';
+      const escapedSummary = evt.summary.replace(/\|/g, '\\|');
+      mdLines.push(`| ${ts} | \`${evt.repo_id || '?'}\` | \`${evt.type}\` | ${escapedSummary} |`);
+    }
+  } else {
+    mdLines.push('', '## Aggregated Child Repo Events', '', 'No child repo events.');
+  }
+
   if (barrier_summary && barrier_summary.length > 0) {
     mdLines.push('', '## Barrier Summary', '', '| Barrier | Workstream | Type | Status | Satisfied |', '|---------|------------|------|--------|-----------|');
     for (const b of barrier_summary) {
@@ -2392,11 +2439,13 @@ function renderRunHtml(report) {
           `<code>${esc(d.delegation_id)}</code> &rarr; <code>${esc(d.to_role)}</code>`,
           `<code>${esc(d.child_turn_id || 'pending')}</code>`,
           badge(d.status),
+          esc((d.required_decision_ids || []).join(', ') || '\u2014'),
+          esc((d.missing_decision_ids || []).join(', ') || '\u2014'),
           esc(d.charter),
         ]);
       }
     }
-    delHtml += htmlTable(['Parent Role', 'Parent Turn', 'Outcome', 'Review Turn', 'Delegation', 'Child Turn', 'Status', 'Charter'], rows);
+    delHtml += htmlTable(['Parent Role', 'Parent Turn', 'Outcome', 'Review Turn', 'Delegation', 'Child Turn', 'Status', 'Required Decisions', 'Missing Decisions', 'Charter'], rows);
     sections.push(`<div class="section">${htmlSection('Delegation Summary', delHtml)}</div>`);
   }
 
@@ -2603,6 +2652,22 @@ function renderCoordinatorHtml(report) {
     sections.push(`<div class="section">${htmlSection('Coordinator Timeline', htmlTable(['#', 'Type', 'Time', 'Summary'], tlRows))}</div>`);
   }
 
+  // Aggregated Child Repo Events
+  {
+    const aggTimeline = report.subject.aggregated_event_timeline;
+    if (aggTimeline?.length > 0) {
+      const aggRows = aggTimeline.map((evt) => [
+        `<code>${esc(evt.timestamp || 'n/a')}</code>`,
+        `<span class="badge" style="background:#4a90d9">${esc(evt.repo_id || '?')}</span>`,
+        `<code>${esc(evt.type)}</code>`,
+        esc(evt.summary),
+      ]);
+      sections.push(`<div class="section">${htmlSection('Aggregated Child Repo Events', htmlTable(['Timestamp', 'Repo', 'Event Type', 'Summary'], aggRows))}</div>`);
+    } else {
+      sections.push(`<div class="section">${htmlSection('Aggregated Child Repo Events', '<p>No child repo events.</p>')}</div>`);
+    }
+  }
+
   // Barrier Summary
   if (barrier_summary?.length > 0) {
     const bRows = barrier_summary.map((b) => [

package/src/lib/schemas/turn-result.schema.json

@@ -268,6 +268,16 @@
             "items": { "type": "string", "minLength": 1 },
             "minItems": 1,
             "description": "What the delegate must achieve for this delegation to be considered complete."
+          },
+          "required_decision_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^DEC-\\d+$"
+            },
+            "minItems": 1,
+            "uniqueItems": true,
+            "description": "Optional named decisions the delegated child must emit before the parent review turn may advance phase/run lifecycle."
           }
         }
       }

package/src/lib/turn-result-validator.js

@@ -263,6 +263,16 @@ function validateSchema(tr) {
     }
   }
 
+  if ('delegations' in tr) {
+    if (!Array.isArray(tr.delegations)) {
+      errors.push('delegations must be an array.');
+    } else {
+      for (let i = 0; i < tr.delegations.length; i++) {
+        errors.push(...validateDelegation(tr.delegations[i], i));
+      }
+    }
+  }
+
   errors.push(...collectUnfilledTemplatePlaceholderErrors(tr));
 
   return errors;
@@ -382,6 +392,54 @@ function validateObjection(obj, index) {
   return errors;
 }
 
+function validateDelegation(del, index) {
+  const errors = [];
+  const prefix = `delegations[${index}]`;
+
+  if (del === null || typeof del !== 'object' || Array.isArray(del)) {
+    return [`${prefix} must be an object.`];
+  }
+  if (typeof del.id !== 'string' || !/^del-\d{3}$/.test(del.id)) {
+    errors.push(`${prefix}.id must match pattern del-NNN.`);
+  }
+  if (typeof del.to_role !== 'string' || !/^[a-z0-9_-]+$/.test(del.to_role)) {
+    errors.push(`${prefix}.to_role must match pattern ^[a-z0-9_-]+$.`);
+  }
+  if (typeof del.charter !== 'string' || !del.charter.trim()) {
+    errors.push(`${prefix}.charter must be a non-empty string.`);
+  }
+  if (!Array.isArray(del.acceptance_contract) || del.acceptance_contract.length === 0) {
+    errors.push(`${prefix}.acceptance_contract must be a non-empty array.`);
+  } else {
+    for (let i = 0; i < del.acceptance_contract.length; i++) {
+      if (typeof del.acceptance_contract[i] !== 'string' || !del.acceptance_contract[i].trim()) {
+        errors.push(`${prefix}.acceptance_contract[${i}] must be a non-empty string.`);
+      }
+    }
+  }
+  if (del.required_decision_ids !== undefined) {
+    if (!Array.isArray(del.required_decision_ids) || del.required_decision_ids.length === 0) {
+      errors.push(`${prefix}.required_decision_ids must be a non-empty array when provided.`);
+    } else {
+      const seen = new Set();
+      for (let i = 0; i < del.required_decision_ids.length; i++) {
+        const id = del.required_decision_ids[i];
+        if (typeof id !== 'string' || !/^DEC-\d+$/.test(id)) {
+          errors.push(`${prefix}.required_decision_ids[${i}] must match pattern DEC-NNN.`);
+          continue;
+        }
+        if (seen.has(id)) {
+          errors.push(`${prefix}.required_decision_ids contains duplicate "${id}".`);
+          continue;
+        }
+        seen.add(id);
+      }
+    }
+  }
+
+  return errors;
+}
+
 // ── Stage B: Assignment Validation ───────────────────────────────────────────
 
 function validateAssignment(tr, state) {
@@ -563,6 +621,7 @@ function validateProtocol(tr, state, config) {
 
   const role = config.roles?.[tr.role];
   const writeAuthority = role?.write_authority;
+  const activeTurn = getActiveTurn(state) || state?.current_turn || null;
 
   // Challenge requirement: review_only roles MUST raise at least one objection
   if (config.rules?.challenge_required !== false) {
@@ -628,7 +687,6 @@ function validateProtocol(tr, state, config) {
     }
 
     // No recursive delegation: if this turn is a delegation review, it cannot delegate further
-    const activeTurn = state?.active_turns ? Object.values(state.active_turns)[0] : null;
     if (activeTurn?.delegation_context) {
       errors.push('Delegation review turns cannot contain further delegations.');
     }
@@ -663,6 +721,26 @@ function validateProtocol(tr, state, config) {
     }
   }
 
+  if (activeTurn?.delegation_review) {
+    const unmetDecisionContracts = (activeTurn.delegation_review.results || [])
+      .filter((result) => Array.isArray(result?.missing_decision_ids) && result.missing_decision_ids.length > 0);
+    if (unmetDecisionContracts.length > 0) {
+      const detail = unmetDecisionContracts
+        .map((result) => `${result.delegation_id}: ${result.missing_decision_ids.join(', ')}`)
+        .join('; ');
+      if (tr.phase_transition_request) {
+        errors.push(
+          `Delegation review cannot request phase transition while required child decisions are missing: ${detail}.`
+        );
+      }
+      if (tr.run_completion_request) {
+        errors.push(
+          `Delegation review cannot request run completion while required child decisions are missing: ${detail}.`
+        );
+      }
+    }
+  }
+
   return { errors, warnings };
 }