agentxchain 2.46.0 → 2.47.0

package/src/lib/report.js

@@ -1,4 +1,5 @@
 import { verifyExportArtifact } from './export-verifier.js';
+import { normalizeRunProvenance, summarizeRunProvenance } from './run-provenance.js';
 
 export const GOVERNANCE_REPORT_VERSION = '0.1';
 
@@ -78,6 +79,10 @@ function extractHistoryTimeline(artifact) {
       phase: e.phase || null,
       phase_transition: e.phase_transition_request || null,
       files_changed_count: Array.isArray(e.files_changed) ? e.files_changed.length : 0,
+      concurrent_with: Array.isArray(e.concurrent_with) && e.concurrent_with.length > 0 ? e.concurrent_with : undefined,
+      sibling_attributed_files: Array.isArray(e.observed_artifact?.attributed_to_concurrent_siblings) && e.observed_artifact.attributed_to_concurrent_siblings.length > 0
+        ? e.observed_artifact.attributed_to_concurrent_siblings
+        : undefined,
       decisions: Array.isArray(e.decisions) ? e.decisions.map((d) => d?.id || d).filter(Boolean) : [],
       objections: Array.isArray(e.objections) ? e.objections.map((o) => o?.id || o).filter(Boolean) : [],
       cost_usd: typeof e.cost?.total_usd === 'number' ? e.cost.total_usd : null,
@@ -99,6 +104,61 @@ function extractDecisionDigest(artifact) {
     }));
 }
 
+function extractApprovalPolicyDigest(artifact) {
+  const data = extractFileData(artifact, '.agentxchain/decision-ledger.jsonl');
+  if (!Array.isArray(data) || data.length === 0) return [];
+  return data
+    .filter((d) => d?.type === 'approval_policy')
+    .map((d) => ({
+      gate_type: d.gate_type || null,
+      action: d.action || null,
+      matched_rule: d.matched_rule || null,
+      from_phase: d.from_phase || null,
+      to_phase: d.to_phase || null,
+      reason: d.reason || '',
+      gate_id: d.gate_id || null,
+      timestamp: d.timestamp || null,
+    }));
+}
+
+function extractGateFailureDigest(artifact) {
+  const data = extractFileData(artifact, '.agentxchain/decision-ledger.jsonl');
+  if (!Array.isArray(data) || data.length === 0) return [];
+  return data
+    .filter((d) => d?.type === 'gate_failure')
+    .map((d) => ({
+      gate_type: d.gate_type || null,
+      gate_id: d.gate_id || null,
+      phase: d.phase || null,
+      from_phase: d.from_phase || null,
+      to_phase: d.to_phase || null,
+      requested_by_turn: d.requested_by_turn || null,
+      failed_at: d.failed_at || null,
+      queued_request: d.queued_request === true,
+      reasons: Array.isArray(d.reasons) ? d.reasons : [],
+      missing_files: Array.isArray(d.missing_files) ? d.missing_files : [],
+      missing_verification: d.missing_verification === true,
+    }));
+}
+
+function extractTimeoutEventDigest(artifact, relPath = '.agentxchain/decision-ledger.jsonl') {
+  const data = extractFileData(artifact, relPath);
+  if (!Array.isArray(data) || data.length === 0) return [];
+  return data
+    .filter((d) => typeof d?.type === 'string' && d.type.startsWith('timeout'))
+    .map((d) => ({
+      type: d.type,
+      scope: d.scope || null,
+      phase: d.phase || null,
+      turn_id: d.turn_id || null,
+      limit_minutes: typeof d.limit_minutes === 'number' ? d.limit_minutes : null,
+      elapsed_minutes: typeof d.elapsed_minutes === 'number' ? d.elapsed_minutes : null,
+      exceeded_by_minutes: typeof d.exceeded_by_minutes === 'number' ? d.exceeded_by_minutes : null,
+      action: d.action || null,
+      timestamp: d.timestamp || null,
+    }));
+}
+
 function extractHookSummary(artifact) {
   const data = extractFileData(artifact, '.agentxchain/hook-audit.jsonl');
   if (!Array.isArray(data) || data.length === 0) return null;
@@ -408,6 +468,23 @@ function extractCoordinatorDecisionDigest(artifact) {
     }));
 }
 
+function extractCoordinatorApprovalPolicyDigest(artifact) {
+  const data = extractFileData(artifact, '.agentxchain/multirepo/decision-ledger.jsonl');
+  if (!Array.isArray(data) || data.length === 0) return [];
+  return data
+    .filter((d) => d?.type === 'approval_policy')
+    .map((d) => ({
+      gate_type: d.gate_type || null,
+      action: d.action || null,
+      matched_rule: d.matched_rule || null,
+      from_phase: d.from_phase || null,
+      to_phase: d.to_phase || null,
+      reason: d.reason || '',
+      gate_id: d.gate_id || null,
+      timestamp: d.timestamp || null,
+    }));
+}
+
 function extractBarrierSummary(artifact) {
   const data = extractFileData(artifact, '.agentxchain/multirepo/barriers.json');
   if (!data || typeof data !== 'object' || Array.isArray(data)) return [];
@@ -538,6 +615,9 @@ function buildRunSubject(artifact) {
 
   const turns = extractHistoryTimeline(artifact);
   const decisions = extractDecisionDigest(artifact);
+  const approvalPolicyEvents = extractApprovalPolicyDigest(artifact);
+  const gateFailures = extractGateFailureDigest(artifact);
+  const timeoutEvents = extractTimeoutEventDigest(artifact);
   const hookSummary = extractHookSummary(artifact);
   const timing = computeTiming(artifact, turns);
   const gateSummary = extractGateSummary(artifact);
@@ -560,6 +640,7 @@ function buildRunSubject(artifact) {
       phase: artifact.summary?.phase || null,
       blocked_on: artifact.state?.blocked_on || null,
       blocked_reason: artifact.state?.blocked_reason || null,
+      provenance: normalizeRunProvenance(artifact.summary?.provenance || artifact.state?.provenance),
       active_turn_count: activeTurns.length,
       retained_turn_count: retainedTurns.length,
       active_turn_ids: activeTurns,
@@ -571,6 +652,9 @@ function buildRunSubject(artifact) {
       duration_seconds: timing.duration_seconds,
       turns,
       decisions,
+      approval_policy_events: approvalPolicyEvents,
+      gate_failures: gateFailures,
+      timeout_events: timeoutEvents,
       hook_summary: hookSummary,
       gate_summary: gateSummary,
       intake_links: intakeLinks,
@@ -643,6 +727,9 @@ function buildCoordinatorSubject(artifact) {
       const childExport = repoEntry.export;
       base.turns = extractHistoryTimeline(childExport);
       base.decisions = extractDecisionDigest(childExport);
+      base.approval_policy_events = extractApprovalPolicyDigest(childExport);
+      base.gate_failures = extractGateFailureDigest(childExport);
+      base.timeout_events = extractTimeoutEventDigest(childExport);
       base.hook_summary = extractHookSummary(childExport);
       base.gate_summary = extractGateSummary(childExport);
       base.recovery_summary = extractRecoverySummary(childExport);
@@ -656,6 +743,8 @@ function buildCoordinatorSubject(artifact) {
   const barrierSummary = extractBarrierSummary(artifact);
   const barrierLedgerTimeline = extractBarrierLedgerTimeline(artifact);
   const decisionDigest = extractCoordinatorDecisionDigest(artifact);
+  const coordinatorApprovalPolicyEvents = extractCoordinatorApprovalPolicyDigest(artifact);
+  const coordinatorTimeoutEvents = extractTimeoutEventDigest(artifact, '.agentxchain/multirepo/decision-ledger.jsonl');
   const timing = computeCoordinatorTiming(artifact, coordinatorTimeline);
   const blockedReason = normalizeCoordinatorBlockedReason(coordinatorState.blocked_reason);
   const pendingGate = normalizePendingGate(coordinatorState.pending_gate);
@@ -698,6 +787,8 @@ function buildCoordinatorSubject(artifact) {
     barrier_summary: barrierSummary,
     barrier_ledger_timeline: barrierLedgerTimeline,
     decision_digest: decisionDigest,
+    approval_policy_events: coordinatorApprovalPolicyEvents,
+    timeout_events: coordinatorTimeoutEvents,
     recovery_report: extractRecoveryReportSummary(artifact),
     repos,
     artifacts: {
@@ -810,6 +901,9 @@ export function formatGovernanceReportText(report) {
     if (run.duration_seconds != null) {
       lines.push(`Duration: ${run.duration_seconds}s`);
     }
+    if (summarizeRunProvenance(run.provenance)) {
+      lines.push(`Provenance: ${summarizeRunProvenance(run.provenance)}`);
+    }
 
     lines.push(
       `History entries: ${artifacts.history_entries}`,
@@ -828,7 +922,8 @@ export function formatGovernanceReportText(report) {
         const t = run.turns[i];
         const cost = t.cost_usd != null ? formatUsd(t.cost_usd) : 'n/a';
         const phase = t.phase_transition ? `${t.phase || '?'} -> ${t.phase_transition}` : (t.phase || '?');
-        lines.push(`  ${i + 1}. [${t.role}] ${t.summary || '(no summary)'} | phase: ${phase} | files: ${t.files_changed_count} | cost: ${cost} | ${t.accepted_at || 'n/a'}`);
+        const siblingNote = Array.isArray(t.sibling_attributed_files) ? ` (${t.sibling_attributed_files.length} sibling-attributed)` : '';
+        lines.push(`  ${i + 1}. [${t.role}] ${t.summary || '(no summary)'} | phase: ${phase} | files: ${t.files_changed_count}${siblingNote} | cost: ${cost} | ${t.accepted_at || 'n/a'}`);
       }
     }
 
@@ -846,6 +941,46 @@ export function formatGovernanceReportText(report) {
       }
     }
 
+    if (run.gate_failures && run.gate_failures.length > 0) {
+      lines.push('', 'Gate Failures:');
+      for (const failure of run.gate_failures) {
+        const request = failure.gate_type === 'run_completion'
+          ? 'run completion'
+          : `${failure.from_phase || failure.phase || '?'} -> ${failure.to_phase || '?'}`;
+        const source = failure.queued_request ? 'queued drain' : 'direct';
+        lines.push(`  - ${failure.gate_id || 'unknown'} | ${failure.gate_type || 'unknown'} | request: ${request} | source: ${source} | at: ${failure.failed_at || 'n/a'}`);
+        for (const reason of failure.reasons || []) {
+          lines.push(`      reason: ${reason}`);
+        }
+      }
+    }
+
+    if (run.approval_policy_events && run.approval_policy_events.length > 0) {
+      lines.push('', 'Approval Policy:');
+      for (const evt of run.approval_policy_events) {
+        const transition = evt.gate_type === 'run_completion'
+          ? 'run completion'
+          : `${evt.from_phase || '?'} -> ${evt.to_phase || '?'}`;
+        const rule = evt.matched_rule ? ` | rule: ${typeof evt.matched_rule === 'object' ? JSON.stringify(evt.matched_rule) : evt.matched_rule}` : '';
+        lines.push(`  - ${evt.action || 'unknown'} | ${evt.gate_type || 'unknown'} | ${transition}${rule} | at: ${evt.timestamp || 'n/a'}`);
+        if (evt.reason) lines.push(`      reason: ${evt.reason}`);
+      }
+    }
+
+    if (run.timeout_events && run.timeout_events.length > 0) {
+      lines.push('', 'Timeout Events:');
+      for (const evt of run.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` : '';
+        lines.push(`  - ${label} | ${evt.scope || '?'} scope | ${elapsed}/${limit}${exceeded ? ` (${exceeded})` : ''} | action: ${evt.action || 'n/a'} | phase: ${evt.phase || 'n/a'} | at: ${evt.timestamp || 'n/a'}`);
+      }
+    }
+
     if (run.intake_links && run.intake_links.length > 0) {
       lines.push('', 'Intake Linkage:');
       for (const intake of run.intake_links) {
@@ -896,7 +1031,19 @@ export function formatGovernanceReportText(report) {
     return lines.join('\n');
   }
 
-  const { coordinator, run, artifacts, repos, coordinator_timeline, barrier_summary, barrier_ledger_timeline, decision_digest, recovery_report } = report.subject;
+  const {
+    coordinator,
+    run,
+    artifacts,
+    repos,
+    coordinator_timeline,
+    barrier_summary,
+    barrier_ledger_timeline,
+    decision_digest,
+    approval_policy_events,
+    timeout_events,
+    recovery_report,
+  } = report.subject;
   const lines = [
     'AgentXchain Governance Report',
     `Input: ${report.input}`,
@@ -979,6 +1126,32 @@ export function formatGovernanceReportText(report) {
     }
   }
 
+  if (approval_policy_events && approval_policy_events.length > 0) {
+    lines.push('', 'Approval Policy:');
+    for (const evt of approval_policy_events) {
+      const transition = evt.gate_type === 'run_completion'
+        ? 'run completion'
+        : `${evt.from_phase || '?'} -> ${evt.to_phase || '?'}`;
+      const rule = evt.matched_rule ? ` | rule: ${typeof evt.matched_rule === 'object' ? JSON.stringify(evt.matched_rule) : evt.matched_rule}` : '';
+      lines.push(`  - ${evt.action || 'unknown'} | ${evt.gate_type || 'unknown'} | ${transition}${rule} | at: ${evt.timestamp || 'n/a'}`);
+      if (evt.reason) lines.push(`      reason: ${evt.reason}`);
+    }
+  }
+
+  if (timeout_events && timeout_events.length > 0) {
+    lines.push('', 'Timeout Events:');
+    for (const evt of 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` : '';
+      lines.push(`  - ${label} | ${evt.scope || '?'} scope | ${elapsed}/${limit}${exceeded ? ` (${exceeded})` : ''} | action: ${evt.action || 'n/a'} | phase: ${evt.phase || 'n/a'} | at: ${evt.timestamp || 'n/a'}`);
+    }
+  }
+
   if (recovery_report) {
     lines.push('', 'Recovery Report:');
     lines.push(`  Trigger: ${recovery_report.trigger || 'n/a'}`);
@@ -1003,7 +1176,8 @@ export function formatGovernanceReportText(report) {
           const t = repo.turns[i];
           const cost = t.cost_usd != null ? formatUsd(t.cost_usd) : 'n/a';
           const phase = t.phase_transition ? `${t.phase || '?'} -> ${t.phase_transition}` : (t.phase || '?');
-          repoLines.push(`    ${i + 1}. [${t.role}] ${t.summary || '(no summary)'} | phase: ${phase} | files: ${t.files_changed_count} | cost: ${cost} | ${t.accepted_at || 'n/a'}`);
+          const siblingNote = Array.isArray(t.sibling_attributed_files) ? ` (${t.sibling_attributed_files.length} sibling-attributed)` : '';
+          repoLines.push(`    ${i + 1}. [${t.role}] ${t.summary || '(no summary)'} | phase: ${phase} | files: ${t.files_changed_count}${siblingNote} | cost: ${cost} | ${t.accepted_at || 'n/a'}`);
         }
       }
       if (repo.decisions && repo.decisions.length > 0) {
@@ -1018,6 +1192,39 @@ export function formatGovernanceReportText(report) {
           repoLines.push(`    - ${gate.gate_id}: ${gate.status}`);
         }
       }
+      if (repo.gate_failures && repo.gate_failures.length > 0) {
+        repoLines.push('  Gate Failures:');
+        for (const failure of repo.gate_failures) {
+          const request = failure.gate_type === 'run_completion'
+            ? 'run completion'
+            : `${failure.from_phase || failure.phase || '?'} -> ${failure.to_phase || '?'}`;
+          repoLines.push(`    - ${failure.gate_id || 'unknown'}: ${failure.gate_type || 'unknown'} | ${request} | ${failure.queued_request ? 'queued drain' : 'direct'} | ${failure.failed_at || 'n/a'}`);
+          for (const reason of failure.reasons || []) {
+            repoLines.push(`      reason: ${reason}`);
+          }
+        }
+      }
+      if (repo.approval_policy_events && repo.approval_policy_events.length > 0) {
+        repoLines.push('  Approval Policy:');
+        for (const evt of repo.approval_policy_events) {
+          const transition = evt.gate_type === 'run_completion'
+            ? 'run completion'
+            : `${evt.from_phase || '?'} -> ${evt.to_phase || '?'}`;
+          repoLines.push(`    - ${evt.action || 'unknown'}: ${evt.gate_type || 'unknown'} | ${transition} | ${evt.timestamp || 'n/a'}`);
+        }
+      }
+      if (repo.timeout_events && repo.timeout_events.length > 0) {
+        repoLines.push('  Timeout Events:');
+        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` : '?';
+          repoLines.push(`    - ${label}: ${evt.scope || '?'} scope | ${elapsed}/${limit} | action: ${evt.action || 'n/a'} | ${evt.timestamp || 'n/a'}`);
+        }
+      }
       if (repo.hook_summary) {
         repoLines.push(`  Hook Activity: ${repo.hook_summary.total} total, ${repo.hook_summary.blocked} blocked`);
       }
@@ -1098,6 +1305,9 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.duration_seconds != null) {
       lines.push(`- Duration: \`${run.duration_seconds}s\``);
     }
+    if (summarizeRunProvenance(run.provenance)) {
+      lines.push(`- Provenance: \`${summarizeRunProvenance(run.provenance)}\``);
+    }
 
     lines.push(
       `- History entries: ${artifacts.history_entries}`,
@@ -1117,7 +1327,8 @@ export function formatGovernanceReportMarkdown(report) {
         const cost = t.cost_usd != null ? formatUsd(t.cost_usd) : 'n/a';
         const phase = t.phase_transition ? `${t.phase || '?'} → ${t.phase_transition}` : (t.phase || '?');
         const summary = (t.summary || '(no summary)').replace(/\|/g, '\\|');
-        lines.push(`| ${i + 1} | ${t.role} | ${phase} | ${summary} | ${t.files_changed_count} | ${cost} | ${t.accepted_at || 'n/a'} |`);
+        const siblingNote = Array.isArray(t.sibling_attributed_files) ? ` (${t.sibling_attributed_files.length} sibling)` : '';
+        lines.push(`| ${i + 1} | ${t.role} | ${phase} | ${summary} | ${t.files_changed_count}${siblingNote} | ${cost} | ${t.accepted_at || 'n/a'} |`);
       }
     }
 
@@ -1135,6 +1346,45 @@ export function formatGovernanceReportMarkdown(report) {
       }
     }
 
+    if (run.gate_failures && run.gate_failures.length > 0) {
+      lines.push('', '## Gate Failures', '');
+      for (const failure of run.gate_failures) {
+        const request = failure.gate_type === 'run_completion'
+          ? 'run completion'
+          : `${failure.from_phase || failure.phase || '?'} → ${failure.to_phase || '?'}`;
+        lines.push(`- \`${failure.gate_id || 'unknown'}\` (${failure.gate_type || 'unknown'}) at \`${failure.failed_at || 'n/a'}\` via ${failure.queued_request ? 'queued drain' : 'direct'} request: ${request}`);
+        for (const reason of failure.reasons || []) {
+          lines.push(`  - ${reason}`);
+        }
+      }
+    }
+
+    if (run.approval_policy_events && run.approval_policy_events.length > 0) {
+      lines.push('', '## Approval Policy', '');
+      for (const evt of run.approval_policy_events) {
+        const transition = evt.gate_type === 'run_completion'
+          ? 'run completion'
+          : `${evt.from_phase || '?'} → ${evt.to_phase || '?'}`;
+        const rule = evt.matched_rule ? ` — rule: \`${typeof evt.matched_rule === 'object' ? JSON.stringify(evt.matched_rule) : evt.matched_rule}\`` : '';
+        lines.push(`- **${evt.action || 'unknown'}** (${evt.gate_type || 'unknown'}) ${transition}${rule} at \`${evt.timestamp || 'n/a'}\``);
+        if (evt.reason) lines.push(`  - ${evt.reason}`);
+      }
+    }
+
+    if (run.timeout_events && run.timeout_events.length > 0) {
+      lines.push('', '## Timeout Events', '');
+      for (const evt of run.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)` : '';
+        lines.push(`- **${label}** (\`${evt.scope || '?'}\` scope) — ${elapsed}/${limit}${exceeded}, action: \`${evt.action || 'n/a'}\`, phase: \`${evt.phase || 'n/a'}\` at \`${evt.timestamp || 'n/a'}\``);
+      }
+    }
+
     if (run.intake_links && run.intake_links.length > 0) {
       lines.push('', '## Intake Linkage', '');
       for (const intake of run.intake_links) {
@@ -1188,7 +1438,19 @@ export function formatGovernanceReportMarkdown(report) {
     return lines.join('\n');
   }
 
-  const { coordinator, run, artifacts, repos, coordinator_timeline, barrier_summary, barrier_ledger_timeline, decision_digest, recovery_report: coordRecoveryReport } = report.subject;
+  const {
+    coordinator,
+    run,
+    artifacts,
+    repos,
+    coordinator_timeline,
+    barrier_summary,
+    barrier_ledger_timeline,
+    decision_digest,
+    approval_policy_events,
+    timeout_events,
+    recovery_report: coordRecoveryReport,
+  } = report.subject;
   const mdLines = [
     '# AgentXchain Governance Report',
     '',
@@ -1272,6 +1534,32 @@ export function formatGovernanceReportMarkdown(report) {
     }
   }
 
+  if (approval_policy_events && approval_policy_events.length > 0) {
+    mdLines.push('', '## Approval Policy', '');
+    for (const evt of approval_policy_events) {
+      const transition = evt.gate_type === 'run_completion'
+        ? 'run completion'
+        : `${evt.from_phase || '?'} → ${evt.to_phase || '?'}`;
+      const rule = evt.matched_rule ? ` — rule: \`${typeof evt.matched_rule === 'object' ? JSON.stringify(evt.matched_rule) : evt.matched_rule}\`` : '';
+      mdLines.push(`- **${evt.action || 'unknown'}** (${evt.gate_type || 'unknown'}) ${transition}${rule} at \`${evt.timestamp || 'n/a'}\``);
+      if (evt.reason) mdLines.push(`  - ${evt.reason}`);
+    }
+  }
+
+  if (timeout_events && timeout_events.length > 0) {
+    mdLines.push('', '## Timeout Events', '');
+    for (const evt of 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)` : '';
+      mdLines.push(`- **${label}** (\`${evt.scope || '?'}\` scope) — ${elapsed}/${limit}${exceeded}, action: \`${evt.action || 'n/a'}\`, phase: \`${evt.phase || 'n/a'}\` at \`${evt.timestamp || 'n/a'}\``);
+    }
+  }
+
   if (coordRecoveryReport) {
     mdLines.push('', '## Recovery Report', '');
     mdLines.push(`- **Trigger:** ${coordRecoveryReport.trigger || 'n/a'}`);
@@ -1297,7 +1585,8 @@ export function formatGovernanceReportMarkdown(report) {
         const cost = t.cost_usd != null ? formatUsd(t.cost_usd) : 'n/a';
         const phase = t.phase_transition ? `${t.phase || '?'} → ${t.phase_transition}` : (t.phase || '?');
         const summary = (t.summary || '(no summary)').replace(/\|/g, '\\|');
-        repoLines.push(`| ${i + 1} | ${t.role} | ${phase} | ${summary} | ${t.files_changed_count} | ${cost} | ${t.accepted_at || 'n/a'} |`);
+        const siblingNote = Array.isArray(t.sibling_attributed_files) ? ` (${t.sibling_attributed_files.length} sibling)` : '';
+        repoLines.push(`| ${i + 1} | ${t.role} | ${phase} | ${summary} | ${t.files_changed_count}${siblingNote} | ${cost} | ${t.accepted_at || 'n/a'} |`);
       }
     }
     if (repo.decisions && repo.decisions.length > 0) {
@@ -1312,6 +1601,42 @@ export function formatGovernanceReportMarkdown(report) {
         repoLines.push(`- \`${gate.gate_id}\`: \`${gate.status}\``);
       }
     }
+    if (repo.gate_failures && repo.gate_failures.length > 0) {
+      repoLines.push('', '#### Gate Failures', '');
+      for (const failure of repo.gate_failures) {
+        const request = failure.gate_type === 'run_completion'
+          ? 'run completion'
+          : `${failure.from_phase || failure.phase || '?'} → ${failure.to_phase || '?'}`;
+        repoLines.push(`- \`${failure.gate_id || 'unknown'}\` (${failure.gate_type || 'unknown'}) at \`${failure.failed_at || 'n/a'}\` via ${failure.queued_request ? 'queued drain' : 'direct'} request: ${request}`);
+        for (const reason of failure.reasons || []) {
+          repoLines.push(`  - ${reason}`);
+        }
+      }
+    }
+    if (repo.approval_policy_events && repo.approval_policy_events.length > 0) {
+      repoLines.push('', '#### Approval Policy', '');
+      for (const evt of repo.approval_policy_events) {
+        const transition = evt.gate_type === 'run_completion'
+          ? 'run completion'
+          : `${evt.from_phase || '?'} → ${evt.to_phase || '?'}`;
+        const rule = evt.matched_rule ? ` — rule: \`${typeof evt.matched_rule === 'object' ? JSON.stringify(evt.matched_rule) : evt.matched_rule}\`` : '';
+        repoLines.push(`- **${evt.action || 'unknown'}** (${evt.gate_type || 'unknown'}) ${transition}${rule} at \`${evt.timestamp || 'n/a'}\``);
+        if (evt.reason) repoLines.push(`  - ${evt.reason}`);
+      }
+    }
+    if (repo.timeout_events && repo.timeout_events.length > 0) {
+      repoLines.push('', '#### Timeout Events', '');
+      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)` : '';
+        repoLines.push(`- **${label}** (\`${evt.scope || '?'}\` scope) — ${elapsed}/${limit}${exceeded}, action: \`${evt.action || 'n/a'}\`, phase: \`${evt.phase || 'n/a'}\` at \`${evt.timestamp || 'n/a'}\``);
+      }
+    }
     if (repo.hook_summary) {
       repoLines.push('', '#### Hook Activity', '', `- Total: ${repo.hook_summary.total}`, `- Blocked: ${repo.hook_summary.blocked}`);
       const eventList = Object.entries(repo.hook_summary.events).sort(([a], [b]) => a.localeCompare(b, 'en')).map(([e, c]) => `${e}(${c})`).join(', ');

package/src/lib/run-history.js

@@ -9,6 +9,7 @@
 
 import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
+import { normalizeRunProvenance } from './run-provenance.js';
 
 const RUN_HISTORY_PATH = '.agentxchain/run-history.jsonl';
 const HISTORY_PATH = '.agentxchain/history.jsonl';
@@ -79,6 +80,7 @@ export function recordRunHistory(root, state, config, status) {
       gate_results: state?.phase_gate_status || {},
       connector_used: connectorUsed,
       model_used: modelUsed,
+      provenance: normalizeRunProvenance(state?.provenance),
       recorded_at: new Date().toISOString(),
     };
 
@@ -132,6 +134,115 @@ export function queryRunHistory(root, opts = {}) {
   return entries;
 }
 
+/**
+ * Walk run lineage backwards from a given run_id via parent_run_id links.
+ *
+ * Returns an ordered array (oldest ancestor first) of history entries
+ * forming the lineage chain. If a parent_run_id references a run not
+ * found in history, the chain terminates with a broken_link sentinel.
+ *
+ * @param {string} root - project root directory
+ * @param {string} runId - the run to trace lineage for
+ * @returns {{ ok: boolean, chain?: Array<object>, error?: string }}
+ */
+export function queryRunLineage(root, runId) {
+  const filePath = join(root, RUN_HISTORY_PATH);
+  if (!existsSync(filePath)) {
+    return { ok: false, error: 'No run history found. Run at least one governed run first.' };
+  }
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return { ok: false, error: 'Failed to read run history file.' };
+  }
+  if (!content) {
+    return { ok: false, error: 'No run history found. Run at least one governed run first.' };
+  }
+
+  const entries = content
+    .split('\n')
+    .filter(Boolean)
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+
+  // Build lookup by run_id
+  const byId = new Map();
+  for (const entry of entries) {
+    if (entry.run_id) byId.set(entry.run_id, entry);
+  }
+
+  // Find the target entry
+  const target = byId.get(runId);
+  if (!target) {
+    return { ok: false, error: `Run ${runId} not found in run history.` };
+  }
+
+  // Walk backwards collecting ancestors
+  const chain = [target];
+  let current = target;
+  const visited = new Set([runId]);
+
+  while (current.provenance?.parent_run_id) {
+    const parentId = current.provenance.parent_run_id;
+    if (visited.has(parentId)) break; // safety: prevent cycles
+    visited.add(parentId);
+
+    const parent = byId.get(parentId);
+    if (!parent) {
+      chain.unshift({ broken_link: true, missing_run_id: parentId });
+      break;
+    }
+    chain.unshift(parent);
+    current = parent;
+  }
+
+  return { ok: true, chain };
+}
+
+/**
+ * Validate that a run_id exists in history and is in a terminal state.
+ * Used by --continue-from and --recover-from flag validation.
+ *
+ * @param {string} root - project root directory
+ * @param {string} runId - the run_id to validate
+ * @returns {{ ok: boolean, entry?: object, error?: string }}
+ */
+export function validateParentRun(root, runId) {
+  const filePath = join(root, RUN_HISTORY_PATH);
+  if (!existsSync(filePath)) {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+  if (!content) {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+
+  const entries = content
+    .split('\n')
+    .filter(Boolean)
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+
+  const entry = entries.find(e => e.run_id === runId);
+  if (!entry) {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+
+  if (!WRITABLE_TERMINAL_STATUSES.has(entry.status)) {
+    return { ok: false, error: `Run ${runId} is still active (status: ${entry.status}). Cannot chain from a non-terminal run.` };
+  }
+
+  return { ok: true, entry };
+}
+
 /**
  * Get the path to the run-history file.
  */

package/src/lib/run-loop.js

@@ -38,7 +38,7 @@ const DEFAULT_MAX_TURNS = 50;
  * @param {string} root - project root directory
  * @param {object} config - normalized governed config
  * @param {object} callbacks - { selectRole, dispatch, approveGate, onEvent? }
- * @param {object} [options] - { maxTurns?: number }
+ * @param {object} [options] - { maxTurns?: number, provenance?: object, startNewRunFromCompleted?: boolean, startNewRunFromBlocked?: boolean }
  * @returns {Promise<RunLoopResult>}
  */
 export async function runLoop(root, config, callbacks, options = {}) {
@@ -58,8 +58,14 @@ export async function runLoop(root, config, callbacks, options = {}) {
 
   // ── Initialize if idle ──────────────────────────────────────────────────
   let state = loadState(root, config);
-  if (!state || state.status === 'idle') {
-    const initResult = initRun(root, config);
+  const shouldRestartCompleted = state?.status === 'completed' && options.startNewRunFromCompleted === true;
+  const shouldRestartBlocked = state?.status === 'blocked' && options.startNewRunFromBlocked === true;
+  if (!state || state.status === 'idle' || shouldRestartCompleted || shouldRestartBlocked) {
+    const initOpts = options.provenance ? { provenance: options.provenance } : {};
+    if (shouldRestartCompleted || shouldRestartBlocked) {
+      initOpts.allow_terminal_restart = true;
+    }
+    const initResult = initRun(root, config, initOpts);
     if (!initResult.ok) {
       return makeResult(false, 'init_failed', loadState(root, config), turnsExecuted, turnHistory, gatesApproved, [initResult.error]);
     }