agentxchain 2.103.0 → 2.105.0

package/src/lib/report.js

@@ -1,6 +1,16 @@
 import { verifyExportArtifact } from './export-verifier.js';
 import { buildDelegationSummary } from './export.js';
 import { normalizeRunProvenance, summarizeRunProvenance } from './run-provenance.js';
+import { deriveGovernedRunNextActions, deriveRuntimeBlockedGuidance } from './blocked-state.js';
+import {
+  buildRecentEventSummary,
+  formatRecentEventSummaryLine,
+} from './recent-event-summary.js';
+import {
+  deriveCoordinatorNextActions,
+} from './coordinator-next-actions.js';
+import { buildCoordinatorRepoStatusEntries } from './coordinator-repo-status-presentation.js';
+import { summarizeCoordinatorEvent } from './coordinator-event-narrative.js';
 
 export const GOVERNANCE_REPORT_VERSION = '0.1';
 
@@ -77,6 +87,18 @@ function extractDashboardSessionSummary(artifact) {
   return normalizeDashboardSessionSummary(artifact.summary?.dashboard_session);
 }
 
+function extractRunEventTimeline(artifact) {
+  const data = extractFileData(artifact, '.agentxchain/events.jsonl');
+  if (!Array.isArray(data)) return [];
+  return data.filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry));
+}
+
+function formatRecentEventDetail(summary) {
+  if (!summary?.latest_event) return 'No event recorded';
+  const latest = summary.latest_event;
+  return `${latest.summary || latest.event_type || 'unknown_event'} at ${latest.timestamp || 'unknown'}`;
+}
+
 function formatDashboardSessionLine(session) {
   if (!session) return null;
   switch (session.status) {
@@ -244,6 +266,35 @@ function formatTokenCount(value) {
   return value.toLocaleString('en-US');
 }
 
+function formatRepoDecisionAuthority(level, role, source) {
+  if (typeof level !== 'number') return null;
+  const roleLabel = role || 'unknown';
+  if (source === 'human_default') return `${level} (${roleLabel}, human default)`;
+  if (source === 'unknown_role') return `${level} (${roleLabel}, role missing from config)`;
+  return `${level} (${roleLabel})`;
+}
+
+function buildRepoDecisionSummaryLines(summary) {
+  if (!summary) return [];
+  const operatorSummary = summary.operator_summary || {};
+  const categories = Array.isArray(operatorSummary.active_categories) && operatorSummary.active_categories.length > 0
+    ? operatorSummary.active_categories.join(', ')
+    : 'none active';
+  const authority = formatRepoDecisionAuthority(
+    operatorSummary.highest_active_authority_level,
+    operatorSummary.highest_active_authority_role,
+    operatorSummary.highest_active_authority_source,
+  ) || '—';
+  const superseding = operatorSummary.superseding_active_count || 0;
+  const overridden = operatorSummary.overridden_with_successor_count || 0;
+
+  return [
+    `Categories: ${categories}`,
+    `Highest authority: ${authority}`,
+    `Lineage: ${superseding} active superseding earlier decision${superseding === 1 ? '' : 's'} | ${overridden} overridden with recorded successor${overridden === 1 ? '' : 's'}`,
+  ];
+}
+
 export function computeCostSummary(turns) {
   if (!Array.isArray(turns) || turns.length === 0) return null;
 
@@ -554,6 +605,7 @@ function extractRecoverySummary(artifact) {
   if (!blockedReason || typeof blockedReason !== 'object' || Array.isArray(blockedReason)) return null;
   const recovery = blockedReason.recovery;
   if (!recovery || typeof recovery !== 'object' || Array.isArray(recovery)) return null;
+  const runtimeGuidance = deriveRuntimeBlockedGuidance(artifact.state, artifact.config);
   return {
     category: blockedReason.category || null,
     typed_reason: recovery.typed_reason || null,
@@ -563,48 +615,10 @@ function extractRecoverySummary(artifact) {
     turn_retained: typeof recovery.turn_retained === 'boolean' ? recovery.turn_retained : null,
     blocked_at: blockedReason.blocked_at || null,
     turn_id: blockedReason.turn_id || null,
+    runtime_guidance: runtimeGuidance,
   };
 }
 
-function summarizeCoordinatorEvent(entry) {
-  const type = entry?.type || 'unknown';
-  const ts = entry?.timestamp || '';
-  switch (type) {
-    case 'run_initialized': {
-      const repoCount = entry.repo_runs ? Object.keys(entry.repo_runs).length : 0;
-      return `Coordinator run initialized with ${repoCount} repo${repoCount !== 1 ? 's' : ''}`;
-    }
-    case 'turn_dispatched':
-      return `Dispatched turn to ${entry.repo_id || 'unknown'} (${entry.role || '?'}) in workstream ${entry.workstream_id || 'unknown'}`;
-    case 'acceptance_projection': {
-      const turnRef = entry.repo_turn_id ? ` (turn ${entry.repo_turn_id})` : '';
-      const summaryText = entry.summary ? ` — ${entry.summary}` : '';
-      return `Projected acceptance from ${entry.repo_id || 'unknown'}${turnRef}${summaryText}`;
-    }
-    case 'context_generated': {
-      const upstreamCount = Array.isArray(entry.upstream_repo_ids) ? entry.upstream_repo_ids.length : 0;
-      return `Generated cross-repo context for ${entry.target_repo_id || 'unknown'} from ${upstreamCount} upstream repo${upstreamCount !== 1 ? 's' : ''}`;
-    }
-    case 'phase_transition_requested':
-      return `Requested phase transition: ${entry.from || '?'} → ${entry.to || '?'}`;
-    case 'phase_transition_approved':
-      return `Phase transition approved: ${entry.from || '?'} → ${entry.to || '?'}`;
-    case 'run_completion_requested':
-      return `Requested run completion (gate: ${entry.gate || 'unknown'})`;
-    case 'run_completed':
-      return 'Coordinator run completed';
-    case 'state_resynced': {
-      const resynced = Array.isArray(entry.resynced_repos) ? entry.resynced_repos.length : 0;
-      const barrierChanges = Array.isArray(entry.barrier_changes) ? entry.barrier_changes.length : 0;
-      return `Resynced state for ${resynced} repo${resynced !== 1 ? 's' : ''}, ${barrierChanges} barrier change${barrierChanges !== 1 ? 's' : ''}`;
-    }
-    case 'blocked_resolved':
-      return `Blocked state resolved: ${entry.from || '?'} → ${entry.to || '?'}`;
-    default:
-      return `${type} event${ts ? ` at ${ts}` : ''}`;
-  }
-}
-
 function extractCoordinatorTimeline(artifact) {
   const data = extractFileData(artifact, '.agentxchain/multirepo/history.jsonl');
   if (!Array.isArray(data) || data.length === 0) return [];
@@ -683,23 +697,6 @@ function normalizeCoordinatorBlockedReason(blockedReason) {
   return null;
 }
 
-function detectRunIdMismatches(repos, coordinatorRepoRuns) {
-  const mismatches = [];
-  for (const repo of repos) {
-    if (!repo.ok || !repo.run_id) continue;
-    const expected = coordinatorRepoRuns[repo.repo_id]?.run_id;
-    if (!expected) continue;
-    if (expected !== repo.run_id) {
-      mismatches.push({
-        repo_id: repo.repo_id,
-        expected_run_id: expected,
-        actual_run_id: repo.run_id,
-      });
-    }
-  }
-  return mismatches;
-}
-
 function normalizePendingGate(pendingGate) {
   if (!pendingGate || typeof pendingGate !== 'object' || Array.isArray(pendingGate)) return null;
   if (typeof pendingGate.gate !== 'string' || pendingGate.gate.length === 0) return null;
@@ -718,65 +715,6 @@ function normalizePendingGate(pendingGate) {
   return normalized;
 }
 
-function deriveCoordinatorNextActions({ status, blockedReason, pendingGate, repos, coordinatorRepoRuns, runIdMismatches }) {
-  const nextActions = [];
-
-  if (status === 'blocked') {
-    nextActions.push({
-      command: 'agentxchain multi resume',
-      reason: `Coordinator is blocked${blockedReason ? `: ${blockedReason}` : ''}. Resume after fixing the underlying issue.`,
-    });
-    if (runIdMismatches && runIdMismatches.length > 0) {
-      for (const m of runIdMismatches) {
-        nextActions.push({
-          command: `# repo_run_id_mismatch: ${m.repo_id}`,
-          reason: `Repo "${m.repo_id}" run identity drifted: coordinator expects "${m.expected_run_id}" but repo has "${m.actual_run_id}". Re-initialize the child repo with the correct run or use multi resume after investigation.`,
-        });
-      }
-    }
-    if (pendingGate) {
-      nextActions.push({
-        command: 'agentxchain multi approve-gate',
-        reason: `After resume, approve pending gate "${pendingGate.gate}" (${pendingGate.gate_type}).`,
-      });
-    }
-    return nextActions;
-  }
-
-  const driftedRepos = repos
-    .filter((repo) => repo.ok)
-    .filter((repo) => {
-      const coordinatorStatus = coordinatorRepoRuns?.[repo.repo_id]?.status || null;
-      return coordinatorStatus && repo.status && coordinatorStatus !== repo.status;
-    })
-    .map((repo) => repo.repo_id);
-
-  if (driftedRepos.length > 0) {
-    nextActions.push({
-      command: 'agentxchain multi resync',
-      reason: `Coordinator state disagrees with child repo status for: ${driftedRepos.join(', ')}.`,
-    });
-    return nextActions;
-  }
-
-  if (pendingGate) {
-    nextActions.push({
-      command: 'agentxchain multi approve-gate',
-      reason: `Coordinator is waiting on pending gate "${pendingGate.gate}" (${pendingGate.gate_type}).`,
-    });
-    return nextActions;
-  }
-
-  if (status === 'active' || status === 'paused') {
-    nextActions.push({
-      command: 'agentxchain multi step',
-      reason: 'Coordinator has no blocked state or pending gate and can continue.',
-    });
-  }
-
-  return nextActions;
-}
-
 function extractCoordinatorDecisionDigest(artifact) {
   const data = extractFileData(artifact, '.agentxchain/multirepo/decision-ledger.jsonl');
   if (!Array.isArray(data) || data.length === 0) return [];
@@ -879,13 +817,37 @@ function extractBarrierLedgerTimeline(artifact) {
 
 function deriveRepoStatusCounts(repoStatuses) {
   const counts = {};
-  for (const status of Object.values(repoStatuses || {})) {
+  const statuses = Array.isArray(repoStatuses)
+    ? repoStatuses
+    : Object.values(repoStatuses || {});
+  for (const status of statuses) {
     const key = status || 'unknown';
     counts[key] = (counts[key] || 0) + 1;
   }
   return counts;
 }
 
+function deriveCoordinatorStatusDrifts(repoStatusEntries) {
+  return repoStatusEntries
+    .filter((entry) => entry?.status_drift)
+    .map((entry) => entry.status_drift);
+}
+
+function deriveCoordinatorTerminalObservabilityNote(status, runIdMismatches, repoStatusDrifts) {
+  if (status !== 'completed') return null;
+  const driftKinds = [];
+  if (Array.isArray(runIdMismatches) && runIdMismatches.length > 0) {
+    driftKinds.push('run-id drift');
+  }
+  if (Array.isArray(repoStatusDrifts) && repoStatusDrifts.length > 0) {
+    driftKinds.push('status drift');
+  }
+  if (driftKinds.length === 0) return null;
+
+  const verb = driftKinds.length > 1 ? 'remain' : 'remains';
+  return `Child repo ${driftKinds.join(' and ')} ${verb} visible for audit, but this coordinator is already completed, so no recovery command is emitted.`;
+}
+
 export function extractWorkflowKitArtifacts(artifact) {
   const config = artifact.config;
   if (!config || typeof config !== 'object' || !config.workflow_kit) return null;
@@ -961,10 +923,12 @@ function buildRunSubject(artifact) {
   const gateSummary = extractGateSummary(artifact);
   const intakeLinks = extractIntakeLinks(artifact);
   const recoverySummary = extractRecoverySummary(artifact);
+  const nextActions = deriveGovernedRunNextActions(artifact.state, artifact.config);
   const continuity = extractContinuityMetadata(artifact);
   const governanceEvents = extractGovernanceEventDigest(artifact);
   const delegationSummary = extractDelegationSummary(artifact);
   const dashboardSession = extractDashboardSessionSummary(artifact);
+  const recentEventSummary = buildRecentEventSummary(extractRunEventTimeline(artifact));
 
   return {
     kind: 'governed_run',
@@ -992,6 +956,7 @@ function buildRunSubject(artifact) {
       budget_status: normalizeBudgetStatus(artifact.state?.budget_status),
       cost_summary: computeCostSummary(turns),
       dashboard_session: dashboardSession,
+      recent_event_summary: recentEventSummary,
       created_at: timing.created_at,
       completed_at: timing.completed_at,
       duration_seconds: timing.duration_seconds,
@@ -1006,6 +971,7 @@ function buildRunSubject(artifact) {
       gate_summary: gateSummary,
       intake_links: intakeLinks,
       recovery_summary: recoverySummary,
+      next_actions: nextActions,
       continuity,
       workflow_kit_artifacts: extractWorkflowKitArtifacts(artifact),
       repo_decisions: artifact.summary?.repo_decisions || null,
@@ -1055,8 +1021,8 @@ function extractRecoveryReportSummary(artifact) {
 
 function buildCoordinatorSubject(artifact) {
   const coordinatorState = extractFileData(artifact, '.agentxchain/multirepo/state.json') || {};
-  const repoStatuses = artifact.summary?.repo_run_statuses || {};
-  const repoStatusCounts = deriveRepoStatusCounts(repoStatuses);
+  const coordinatorStatus = coordinatorState?.status || artifact.summary?.status || null;
+  const coordinatorPhase = coordinatorState?.phase || artifact.summary?.phase || null;
   const repos = Object.entries(artifact.repos || {})
     .sort(([left], [right]) => left.localeCompare(right, 'en'))
     .map(([repoId, repoEntry]) => {
@@ -1098,15 +1064,31 @@ function buildCoordinatorSubject(artifact) {
   const timing = computeCoordinatorTiming(artifact, coordinatorTimeline);
   const blockedReason = normalizeCoordinatorBlockedReason(coordinatorState.blocked_reason);
   const pendingGate = normalizePendingGate(coordinatorState.pending_gate);
-  const runIdMismatches = detectRunIdMismatches(repos, coordinatorState.repo_runs || {});
+  const repoStatusEntries = buildCoordinatorRepoStatusEntries({
+    config: artifact.config,
+    coordinatorRepoRuns: coordinatorState.repo_runs || {},
+    repoSnapshots: repos,
+  });
+  const repoStatusCounts = deriveRepoStatusCounts(repoStatusEntries.map((entry) => entry.status));
+  const runIdMismatches = repoStatusEntries
+    .filter((entry) => entry?.run_id_mismatch)
+    .map((entry) => entry.run_id_mismatch);
+  const repoStatusDrifts = deriveCoordinatorStatusDrifts(repoStatusEntries);
+  const recentCoordinatorEvents = buildRecentEventSummary(coordinatorTimeline);
+  const recentChildRepoEvents = buildRecentEventSummary(extractAggregatedEventTimeline(artifact));
   const nextActions = deriveCoordinatorNextActions({
-    status: artifact.summary?.status || null,
+    status: coordinatorStatus,
     blockedReason,
     pendingGate,
     repos,
     coordinatorRepoRuns: coordinatorState.repo_runs || {},
     runIdMismatches,
   });
+  const terminalObservabilityNote = deriveCoordinatorTerminalObservabilityNote(
+    coordinatorStatus,
+    runIdMismatches,
+    repoStatusDrifts,
+  );
 
   return {
     kind: 'coordinator_workspace',
@@ -1118,12 +1100,16 @@ function buildCoordinatorSubject(artifact) {
       workstream_count: artifact.coordinator?.workstream_count || 0,
     },
     run: {
-      super_run_id: artifact.summary?.super_run_id || null,
-      status: artifact.summary?.status || null,
-      phase: artifact.summary?.phase || null,
+      super_run_id: coordinatorState?.super_run_id || artifact.summary?.super_run_id || null,
+      status: coordinatorStatus,
+      phase: coordinatorPhase,
       blocked_reason: blockedReason,
       pending_gate: pendingGate,
       run_id_mismatches: runIdMismatches,
+      repo_status_drifts: repoStatusDrifts,
+      terminal_observability_note: terminalObservabilityNote,
+      recent_coordinator_events: recentCoordinatorEvents,
+      recent_child_repo_events: recentChildRepoEvents,
       next_actions: nextActions,
       created_at: timing.created_at,
       completed_at: timing.completed_at,
@@ -1264,6 +1250,10 @@ export function formatGovernanceReportText(report) {
     if (run.dashboard_session) {
       lines.push(`Dashboard session: ${formatDashboardSessionLine(run.dashboard_session)}`);
     }
+    if (run.recent_event_summary) {
+      lines.push(`Recent events: ${formatRecentEventSummaryLine(run.recent_event_summary)}`);
+      lines.push(`Latest event: ${formatRecentEventDetail(run.recent_event_summary)}`);
+    }
 
     lines.push(
       `History entries: ${artifacts.history_entries}`,
@@ -1316,9 +1306,12 @@ export function formatGovernanceReportText(report) {
       }
     }
 
-    if (run.repo_decisions?.active?.length > 0) {
+    if (run.repo_decisions) {
       lines.push('', 'Repo Decisions:');
       lines.push(`  Active: ${run.repo_decisions.active_count}  Overridden: ${run.repo_decisions.overridden_count}`);
+      for (const summaryLine of buildRepoDecisionSummaryLines(run.repo_decisions)) {
+        lines.push(`  ${summaryLine}`);
+      }
       for (const d of run.repo_decisions.active) {
         const supersedes = d.overrides ? ` | supersedes ${d.overrides}` : '';
         const authority = d.authority_level == null ? '' : ` | authority ${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
@@ -1425,6 +1418,20 @@ export function formatGovernanceReportText(report) {
       lines.push(`  Action: ${run.recovery_summary.recovery_action || 'n/a'}`);
       lines.push(`  Detail: ${run.recovery_summary.detail || 'n/a'}`);
       lines.push(`  Turn retained: ${run.recovery_summary.turn_retained == null ? 'n/a' : yesNo(run.recovery_summary.turn_retained)}`);
+      if (Array.isArray(run.recovery_summary.runtime_guidance) && run.recovery_summary.runtime_guidance.length > 0) {
+        lines.push('  Runtime guidance:');
+        for (const entry of run.recovery_summary.runtime_guidance) {
+          lines.push(`    - ${entry.code} | ${entry.command} | ${entry.reason}`);
+        }
+      }
+    }
+
+    if (run.next_actions && run.next_actions.length > 0) {
+      lines.push('', 'Next Actions:');
+      for (let i = 0; i < run.next_actions.length; i++) {
+        const action = run.next_actions[i];
+        lines.push(`  ${i + 1}. ${action.command} | ${action.reason}`);
+      }
     }
 
     if (run.continuity) {
@@ -1486,6 +1493,12 @@ export function formatGovernanceReportText(report) {
       lines.push(`  - ${m.repo_id}: expected ${m.expected_run_id}, actual ${m.actual_run_id}`);
     }
   }
+  if (run.repo_status_drifts && run.repo_status_drifts.length > 0) {
+    lines.push(`Repo status drift: ${run.repo_status_drifts.length}`);
+    for (const drift of run.repo_status_drifts) {
+      lines.push(`  - ${drift.repo_id}: coordinator ${drift.coordinator_status || 'unknown'}, repo ${drift.repo_status || 'unknown'}`);
+    }
+  }
 
   lines.push(
     `Started: ${run.created_at || 'n/a'}`,
@@ -1506,6 +1519,17 @@ export function formatGovernanceReportText(report) {
   if (run.pending_gate) {
     lines.push(`Pending gate: ${run.pending_gate.gate} (${run.pending_gate.gate_type})`);
   }
+  if (run.recent_coordinator_events) {
+    lines.push(`Recent coordinator events: ${formatRecentEventSummaryLine(run.recent_coordinator_events)}`);
+    lines.push(`Latest coordinator event: ${formatRecentEventDetail(run.recent_coordinator_events)}`);
+  }
+  if (run.recent_child_repo_events) {
+    lines.push(`Recent child repo events: ${formatRecentEventSummaryLine(run.recent_child_repo_events)}`);
+    lines.push(`Latest child repo event: ${formatRecentEventDetail(run.recent_child_repo_events)}`);
+  }
+  if (run.terminal_observability_note) {
+    lines.push(`Terminal drift note: ${run.terminal_observability_note}`);
+  }
 
   if (run.next_actions && run.next_actions.length > 0) {
     lines.push('', 'Next Actions:');
@@ -1776,6 +1800,10 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.dashboard_session) {
       lines.push(`- Dashboard session: \`${formatDashboardSessionLine(run.dashboard_session)}\``);
     }
+    if (run.recent_event_summary) {
+      lines.push(`- Recent events: \`${formatRecentEventSummaryLine(run.recent_event_summary)}\``);
+      lines.push(`- Latest event: ${formatRecentEventDetail(run.recent_event_summary)}`);
+    }
 
     lines.push(
       `- History entries: ${artifacts.history_entries}`,
@@ -1828,14 +1856,19 @@ export function formatGovernanceReportMarkdown(report) {
       }
     }
 
-    if (run.repo_decisions?.active?.length > 0) {
+    if (run.repo_decisions) {
       lines.push('', '## Repo Decisions', '');
       lines.push(`Active: ${run.repo_decisions.active_count} | Overridden: ${run.repo_decisions.overridden_count}`, '');
-      lines.push('| ID | Category | Statement | Role | Authority | Run | Supersedes |', '|----|----------|-----------|------|-----------|-----|------------|');
-      for (const d of run.repo_decisions.active) {
-        const stmt = (d.statement || '').replace(/\|/g, '\\|');
-        const authority = d.authority_level == null ? '—' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
-        lines.push(`| ${d.id} | ${d.category} | ${stmt} | ${d.role || '—'} | ${authority} | \`${(d.run_id || '').slice(0, 12)}\` | ${d.overrides || '—'} |`);
+      for (const summaryLine of buildRepoDecisionSummaryLines(run.repo_decisions)) {
+        lines.push(`${summaryLine}`, '');
+      }
+      if (run.repo_decisions.active.length > 0) {
+        lines.push('| ID | Category | Statement | Role | Authority | Run | Supersedes |', '|----|----------|-----------|------|-----------|-----|------------|');
+        for (const d of run.repo_decisions.active) {
+          const stmt = (d.statement || '').replace(/\|/g, '\\|');
+          const authority = d.authority_level == null ? '—' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+          lines.push(`| ${d.id} | ${d.category} | ${stmt} | ${d.role || '—'} | ${authority} | \`${(d.run_id || '').slice(0, 12)}\` | ${d.overrides || '—'} |`);
+        }
       }
       if (run.repo_decisions.overridden?.length > 0) {
         lines.push('', 'Overridden decisions:', '');
@@ -1944,6 +1977,20 @@ export function formatGovernanceReportMarkdown(report) {
       lines.push(`- Action: \`${run.recovery_summary.recovery_action || 'n/a'}\``);
       lines.push(`- Detail: ${run.recovery_summary.detail || 'n/a'}`);
       lines.push(`- Turn retained: \`${run.recovery_summary.turn_retained == null ? 'n/a' : yesNo(run.recovery_summary.turn_retained)}\``);
+      if (Array.isArray(run.recovery_summary.runtime_guidance) && run.recovery_summary.runtime_guidance.length > 0) {
+        lines.push('- Runtime guidance:');
+        for (const entry of run.recovery_summary.runtime_guidance) {
+          lines.push(`  - \`${entry.code}\` — \`${entry.command}\`: ${entry.reason}`);
+        }
+      }
+    }
+
+    if (run.next_actions && run.next_actions.length > 0) {
+      lines.push('', '## Next Actions', '');
+      for (let i = 0; i < run.next_actions.length; i++) {
+        const action = run.next_actions[i];
+        lines.push(`${i + 1}. \`${action.command}\`: ${action.reason}`);
+      }
     }
 
     if (run.continuity) {
@@ -2008,6 +2055,12 @@ export function formatGovernanceReportMarkdown(report) {
       mdLines.push(`  - \`${m.repo_id}\`: expected \`${m.expected_run_id}\`, actual \`${m.actual_run_id}\``);
     }
   }
+  if (run.repo_status_drifts && run.repo_status_drifts.length > 0) {
+    mdLines.push(`- **Repo status drift: ${run.repo_status_drifts.length}**`);
+    for (const drift of run.repo_status_drifts) {
+      mdLines.push(`  - \`${drift.repo_id}\`: coordinator \`${drift.coordinator_status || 'unknown'}\`, repo \`${drift.repo_status || 'unknown'}\``);
+    }
+  }
 
   mdLines.push(
     `- Started: \`${run.created_at || 'n/a'}\``,
@@ -2028,6 +2081,17 @@ export function formatGovernanceReportMarkdown(report) {
   if (run.pending_gate) {
     mdLines.push(`- Pending gate: \`${run.pending_gate.gate}\` (\`${run.pending_gate.gate_type}\`)`);
   }
+  if (run.recent_coordinator_events) {
+    mdLines.push(`- Recent coordinator events: \`${formatRecentEventSummaryLine(run.recent_coordinator_events)}\``);
+    mdLines.push(`- Latest coordinator event: ${formatRecentEventDetail(run.recent_coordinator_events)}`);
+  }
+  if (run.recent_child_repo_events) {
+    mdLines.push(`- Recent child repo events: \`${formatRecentEventSummaryLine(run.recent_child_repo_events)}\``);
+    mdLines.push(`- Latest child repo event: ${formatRecentEventDetail(run.recent_child_repo_events)}`);
+  }
+  if (run.terminal_observability_note) {
+    mdLines.push(`- Terminal drift note: ${run.terminal_observability_note}`);
+  }
 
   if (run.next_actions && run.next_actions.length > 0) {
     mdLines.push('', '## Next Actions', '');
@@ -2403,6 +2467,10 @@ function renderRunHtml(report) {
   if (summarizeRunProvenance(run.provenance)) metaPairs.push(['Provenance', `<code>${esc(summarizeRunProvenance(run.provenance))}</code>`]);
   if (run.inherited_context?.parent_run_id) metaPairs.push(['Inherited from', `<code>${esc(run.inherited_context.parent_run_id)}</code> (${esc(run.inherited_context.parent_status || 'unknown')})`]);
   if (run.dashboard_session) metaPairs.push(['Dashboard', `<code>${esc(formatDashboardSessionLine(run.dashboard_session))}</code>`]);
+  if (run.recent_event_summary) {
+    metaPairs.push(['Recent events', esc(formatRecentEventSummaryLine(run.recent_event_summary))]);
+    metaPairs.push(['Latest event', esc(formatRecentEventDetail(run.recent_event_summary))]);
+  }
 
   metaPairs.push(
     ['History entries', String(artifacts.history_entries)],
@@ -2466,20 +2534,25 @@ function renderRunHtml(report) {
   }
 
   // Repo Decisions
-  if (run.repo_decisions?.active?.length > 0) {
+  if (run.repo_decisions) {
     let rdHtml = `<p>Active: ${run.repo_decisions.active_count} | Overridden: ${run.repo_decisions.overridden_count}</p>`;
-    rdHtml += htmlTable(
-      ['ID', 'Category', 'Statement', 'Role', 'Authority', 'Run', 'Supersedes'],
-      run.repo_decisions.active.map((d) => [
-        esc(d.id),
-        esc(d.category),
-        esc(d.statement || ''),
-        esc(d.role || '\u2014'),
-        esc(d.authority_level == null ? '\u2014' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`),
-        `<code>${esc((d.run_id || '').slice(0, 12))}</code>`,
-        esc(d.overrides || '\u2014'),
-      ]),
-    );
+    rdHtml += buildRepoDecisionSummaryLines(run.repo_decisions)
+      .map((line) => `<p>${esc(line)}</p>`)
+      .join('');
+    if (run.repo_decisions.active.length > 0) {
+      rdHtml += htmlTable(
+        ['ID', 'Category', 'Statement', 'Role', 'Authority', 'Run', 'Supersedes'],
+        run.repo_decisions.active.map((d) => [
+          esc(d.id),
+          esc(d.category),
+          esc(d.statement || ''),
+          esc(d.role || '\u2014'),
+          esc(d.authority_level == null ? '\u2014' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`),
+          `<code>${esc((d.run_id || '').slice(0, 12))}</code>`,
+          esc(d.overrides || '\u2014'),
+        ]),
+      );
+    }
     if (run.repo_decisions.overridden?.length > 0) {
       rdHtml += htmlTable(
         ['ID', 'Statement', 'Authority', 'Overridden By'],
@@ -2595,14 +2668,28 @@ function renderRunHtml(report) {
   // Recovery
   if (run.recovery_summary) {
     const rs = run.recovery_summary;
-    sections.push(`<div class="section">${htmlSection('Recovery', htmlDl([
+    let recoveryHtml = htmlDl([
       ['Category', `<code>${esc(rs.category || 'unknown')}</code>`],
       ['Typed reason', `<code>${esc(rs.typed_reason || 'unknown')}</code>`],
       ['Owner', `<code>${esc(rs.owner || 'unknown')}</code>`],
       ['Action', `<code>${esc(rs.recovery_action || 'n/a')}</code>`],
       ['Detail', esc(rs.detail || 'n/a')],
       ['Turn retained', rs.turn_retained == null ? 'n/a' : (rs.turn_retained ? 'yes' : 'no')],
-    ]))}</div>`);
+    ]);
+    if (Array.isArray(rs.runtime_guidance) && rs.runtime_guidance.length > 0) {
+      const items = '<ul>' + rs.runtime_guidance.map((entry) =>
+        `<li><code>${esc(entry.code)}</code> — <code>${esc(entry.command)}</code>: ${esc(entry.reason)}</li>`
+      ).join('') + '</ul>';
+      recoveryHtml += htmlSection('Runtime Guidance', items);
+    }
+    sections.push(`<div class="section">${htmlSection('Recovery', recoveryHtml)}</div>`);
+  }
+
+  if (run.next_actions?.length > 0) {
+    const nextHtml = '<ol>' + run.next_actions.map((action) =>
+      `<li><code>${esc(action.command)}</code>: ${esc(action.reason)}</li>`
+    ).join('') + '</ol>';
+    sections.push(`<div class="section">${htmlSection('Next Actions', nextHtml)}</div>`);
   }
 
   // Continuity
@@ -2659,6 +2746,9 @@ function renderCoordinatorHtml(report) {
   if (run.run_id_mismatches?.length > 0) {
     metaPairs.push(['Run ID mismatches', `<strong class="warn">${run.run_id_mismatches.length}</strong>`]);
   }
+  if (run.repo_status_drifts?.length > 0) {
+    metaPairs.push(['Repo status drift', `<strong class="warn">${run.repo_status_drifts.length}</strong>`]);
+  }
 
   metaPairs.push(
     ['Started', `<code>${esc(run.created_at || 'n/a')}</code>`],
@@ -2672,6 +2762,17 @@ function renderCoordinatorHtml(report) {
   if (run.completed_at) metaPairs.push(['Completed', `<code>${esc(run.completed_at)}</code>`]);
   if (run.duration_seconds != null) metaPairs.push(['Duration', `<code>${run.duration_seconds}s</code>`]);
   if (run.pending_gate) metaPairs.push(['Pending gate', `<code>${esc(run.pending_gate.gate)}</code> (<code>${esc(run.pending_gate.gate_type)}</code>)`]);
+  if (run.recent_coordinator_events) {
+    metaPairs.push(['Recent coordinator events', esc(formatRecentEventSummaryLine(run.recent_coordinator_events))]);
+    metaPairs.push(['Latest coordinator event', esc(formatRecentEventDetail(run.recent_coordinator_events))]);
+  }
+  if (run.recent_child_repo_events) {
+    metaPairs.push(['Recent child repo events', esc(formatRecentEventSummaryLine(run.recent_child_repo_events))]);
+    metaPairs.push(['Latest child repo event', esc(formatRecentEventDetail(run.recent_child_repo_events))]);
+  }
+  if (run.terminal_observability_note) {
+    metaPairs.push(['Terminal drift note', esc(run.terminal_observability_note)]);
+  }
 
   sections.push(`<div class="meta">${htmlDl(metaPairs)}</div>`);
 
@@ -2681,6 +2782,17 @@ function renderCoordinatorHtml(report) {
     sections.push(`<div class="section">${htmlSection('Next Actions', naHtml)}</div>`);
   }
 
+  if (run.repo_status_drifts?.length > 0) {
+    const driftRows = run.repo_status_drifts.map((drift) => [
+      `<code>${esc(drift.repo_id)}</code>`,
+      `<code>${esc(drift.coordinator_status || 'unknown')}</code>`,
+      `<code>${esc(drift.repo_status || 'unknown')}</code>`,
+    ]);
+    sections.push(
+      `<div class="section">${htmlSection('Repo Status Drift', htmlTable(['Repo', 'Coordinator', 'Repo Authority'], driftRows))}</div>`,
+    );
+  }
+
   // Coordinator Timeline
   if (coordinator_timeline?.length > 0) {
     const tlRows = coordinator_timeline.map((ev, i) => [String(i + 1), `<code>${esc(ev.type)}</code>`, `<code>${esc(ev.timestamp || 'n/a')}</code>`, esc(ev.summary)]);
@@ -2805,6 +2917,102 @@ function renderCoordinatorHtml(report) {
       if (repo.gate_summary?.length > 0) {
         repoHtml += htmlSection('Gate Outcomes', '<ul>' + repo.gate_summary.map((g) => `<li><code>${esc(g.gate_id)}</code>: ${badge(g.status)}</li>`).join('') + '</ul>', 4);
       }
+      if (repo.gate_failures?.length > 0) {
+        let gateFailureHtml = '<ul>';
+        for (const failure of repo.gate_failures) {
+          const request = failure.gate_type === 'run_completion'
+            ? 'run completion'
+            : `${esc(failure.from_phase || '?')} &rarr; ${esc(failure.to_phase || '?')}`;
+          gateFailureHtml += `<li><code>${esc(failure.gate_id || 'unknown')}</code> (<code>${esc(failure.gate_type || 'unknown')}</code>) at <code>${esc(failure.failed_at || 'n/a')}</code> via ${failure.queued_request ? 'queued drain' : 'direct'} request: ${request}`;
+          if (failure.reasons?.length > 0) {
+            gateFailureHtml += '<ul>' + failure.reasons.map((reason) => `<li>${esc(reason)}</li>`).join('') + '</ul>';
+          }
+          gateFailureHtml += '</li>';
+        }
+        gateFailureHtml += '</ul>';
+        repoHtml += htmlSection('Gate Failures', gateFailureHtml, 4);
+      }
+      if (repo.approval_policy_events?.length > 0) {
+        let approvalHtml = '<ul>';
+        for (const evt of repo.approval_policy_events) {
+          const transition = evt.gate_type === 'run_completion'
+            ? 'run completion'
+            : `${esc(evt.from_phase || '?')} &rarr; ${esc(evt.to_phase || '?')}`;
+          const rule = evt.matched_rule
+            ? ` — rule: <code>${esc(typeof evt.matched_rule === 'object' ? JSON.stringify(evt.matched_rule) : evt.matched_rule)}</code>`
+            : '';
+          approvalHtml += `<li><strong>${esc(evt.action || 'unknown')}</strong> (${esc(evt.gate_type || 'unknown')}) ${transition}${rule} at <code>${esc(evt.timestamp || 'n/a')}</code>`;
+          if (evt.reason) approvalHtml += `<br>${esc(evt.reason)}`;
+          approvalHtml += '</li>';
+        }
+        approvalHtml += '</ul>';
+        repoHtml += htmlSection('Approval Policy', approvalHtml, 4);
+      }
+      if (repo.governance_events?.length > 0) {
+        let governanceHtml = '<ul>';
+        for (const evt of repo.governance_events) {
+          governanceHtml += `<li><strong>${esc(evt.type)}</strong> (<code>${esc(evt.role || '?')}</code>, <code>${esc(evt.phase || '?')}</code> phase) at <code>${esc(evt.timestamp || 'n/a')}</code>${renderHtmlGovEventDetail(evt)}</li>`;
+        }
+        governanceHtml += '</ul>';
+        repoHtml += htmlSection('Governance Events', governanceHtml, 4);
+      }
+      if (repo.timeout_events?.length > 0) {
+        let timeoutHtml = '<ul>';
+        for (const evt of repo.timeout_events) {
+          const label = evt.type === 'timeout_warning' ? 'Warning'
+            : evt.type === 'timeout_skip' ? 'Skip'
+            : evt.type === 'timeout_skip_failed' ? 'Skip Failed'
+            : 'Escalation';
+          const elapsed = evt.elapsed_minutes != null ? `${evt.elapsed_minutes}m` : '?';
+          const limit = evt.limit_minutes != null ? `${evt.limit_minutes}m` : '?';
+          const exceeded = evt.exceeded_by_minutes != null ? ` (+${evt.exceeded_by_minutes}m)` : '';
+          timeoutHtml += `<li><strong>${label}</strong> (<code>${esc(evt.scope || '?')}</code> scope) — ${elapsed}/${limit}${exceeded}, action: <code>${esc(evt.action || 'n/a')}</code>, phase: <code>${esc(evt.phase || 'n/a')}</code> at <code>${esc(evt.timestamp || 'n/a')}</code></li>`;
+        }
+        timeoutHtml += '</ul>';
+        repoHtml += htmlSection('Timeout Events', timeoutHtml, 4);
+      }
+      if (repo.hook_summary) {
+        const eventList = Object.entries(repo.hook_summary.events)
+          .sort(([left], [right]) => left.localeCompare(right, 'en'))
+          .map(([event, count]) => `${esc(event)}(${count})`)
+          .join(', ');
+        const hookHtml = htmlDl([
+          ['Total executions', String(repo.hook_summary.total)],
+          ['Blocked', String(repo.hook_summary.blocked)],
+          ...(eventList ? [['Events', eventList]] : []),
+        ]);
+        repoHtml += htmlSection('Hook Activity', hookHtml, 4);
+      }
+      if (repo.recovery_summary) {
+        const recovery = repo.recovery_summary;
+        let recoveryHtml = htmlDl([
+          ['Category', `<code>${esc(recovery.category || 'unknown')}</code>`],
+          ['Typed reason', `<code>${esc(recovery.typed_reason || 'unknown')}</code>`],
+          ['Owner', `<code>${esc(recovery.owner || 'unknown')}</code>`],
+          ['Action', `<code>${esc(recovery.recovery_action || 'n/a')}</code>`],
+          ['Detail', esc(recovery.detail || 'n/a')],
+          ['Turn retained', recovery.turn_retained == null ? 'n/a' : (recovery.turn_retained ? 'yes' : 'no')],
+        ]);
+        if (Array.isArray(recovery.runtime_guidance) && recovery.runtime_guidance.length > 0) {
+          recoveryHtml += htmlSection('Runtime Guidance', '<ul>' + recovery.runtime_guidance.map((entry) =>
+            `<li><code>${esc(entry.code)}</code> — <code>${esc(entry.command)}</code>: ${esc(entry.reason)}</li>`
+          ).join('') + '</ul>', 5);
+        }
+        repoHtml += htmlSection('Recovery', recoveryHtml, 4);
+      }
+      if (repo.continuity) {
+        const continuityPairs = [
+          ['Session', `<code>${esc(repo.continuity.session_id || 'unknown')}</code>`],
+          ['Checkpoint', `<code>${esc(repo.continuity.checkpoint_reason || 'unknown')}</code> at <code>${esc(repo.continuity.last_checkpoint_at || 'n/a')}</code>`],
+          ['Last turn', `<code>${esc(repo.continuity.last_turn_id || 'none')}</code>`],
+          ['Last role', `<code>${esc(repo.continuity.last_role || 'unknown')}</code>`],
+          ['Last phase', `<code>${esc(repo.continuity.last_phase || 'unknown')}</code>`],
+        ];
+        if (repo.continuity.stale_checkpoint) {
+          continuityPairs.push(['Warning', `<span class="warn">checkpoint tracks run <code>${esc(repo.continuity.run_id)}</code>, but repo export tracks <code>${esc(repo.run_id)}</code></span>`]);
+        }
+        repoHtml += htmlSection('Continuity', htmlDl(continuityPairs), 4);
+      }
     }
     sections.push(`<div class="section">${htmlSection('Repo Details', repoHtml)}</div>`);
   }