agentxchain 2.6.0 → 2.8.0

package/src/lib/notification-runner.js

@@ -0,0 +1,330 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { interpolateHeaders } from './hook-runner.js';
+
+export const NOTIFICATION_AUDIT_PATH = '.agentxchain/notification-audit.jsonl';
+export const VALID_NOTIFICATION_EVENTS = [
+  'run_blocked',
+  'operator_escalation_raised',
+  'escalation_resolved',
+  'phase_transition_pending',
+  'run_completion_pending',
+  'run_completed',
+];
+
+const NOTIFICATION_NAME_RE = /^[a-z0-9_-]+$/;
+const MAX_NOTIFICATION_WEBHOOKS = 8;
+const HEADER_VAR_RE = /\$\{([^}]+)\}/g;
+const SIGKILL_GRACE_MS = 2000;
+const MAX_STDERR_CAPTURE = 4096;
+
+function collectMissingHeaderVars(headers, webhookEnv) {
+  if (!headers) return [];
+  const missing = [];
+  const mergedEnv = { ...process.env };
+
+  for (const [key, value] of Object.entries(webhookEnv || {})) {
+    if (typeof value === 'string') {
+      mergedEnv[key] = value;
+    }
+  }
+
+  for (const [headerName, value] of Object.entries(headers)) {
+    let match;
+    while ((match = HEADER_VAR_RE.exec(value)) !== null) {
+      if (mergedEnv[match[1]] === undefined) {
+        missing.push({ header: headerName, varName: match[1] });
+      }
+    }
+    HEADER_VAR_RE.lastIndex = 0;
+  }
+
+  return missing;
+}
+
+function appendAudit(root, entry) {
+  const filePath = join(root, NOTIFICATION_AUDIT_PATH);
+  if (!existsSync(dirname(filePath))) {
+    mkdirSync(dirname(filePath), { recursive: true });
+  }
+  appendFileSync(filePath, `${JSON.stringify(entry)}\n`);
+}
+
+function generateEventId() {
+  return `notif_${randomBytes(8).toString('hex')}`;
+}
+
+function executeWebhook(webhook, envelope) {
+  const startedAt = Date.now();
+  let headers;
+
+  try {
+    headers = interpolateHeaders(webhook.headers, webhook.env);
+  } catch (error) {
+    return {
+      delivered: false,
+      timed_out: false,
+      status_code: null,
+      duration_ms: Date.now() - startedAt,
+      message: String(error?.message || error),
+      stderr_excerpt: String(error?.message || error).slice(0, MAX_STDERR_CAPTURE),
+    };
+  }
+
+  headers['Content-Type'] = 'application/json';
+
+  const script = `
+const url = process.argv[1];
+const body = process.argv[2];
+const headers = JSON.parse(process.argv[3]);
+headers.Connection = 'close';
+(async () => {
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(${webhook.timeout_ms}),
+    });
+    const text = await response.text();
+    process.stdout.write(JSON.stringify({ status: response.status, body: text }));
+    process.exit(0);
+  } catch (error) {
+    if (error?.name === 'TimeoutError' || error?.name === 'AbortError') {
+      process.stderr.write('timeout');
+      process.exit(2);
+    }
+    process.stderr.write(error?.message || String(error));
+    process.exit(1);
+  }
+})();
+`;
+
+  const result = spawnSync(process.execPath, ['-e', script, webhook.url, JSON.stringify(envelope), JSON.stringify(headers)], {
+    timeout: webhook.timeout_ms + SIGKILL_GRACE_MS,
+    maxBuffer: 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, ...(webhook.env || {}) },
+  });
+
+  const durationMs = Date.now() - startedAt;
+  const timedOut = result.error?.code === 'ETIMEDOUT' || durationMs > webhook.timeout_ms;
+  const stdout = result.stdout ? result.stdout.toString('utf8') : '';
+  const stderr = result.stderr ? result.stderr.toString('utf8').slice(0, MAX_STDERR_CAPTURE) : '';
+
+  if (timedOut) {
+    return {
+      delivered: false,
+      timed_out: true,
+      status_code: null,
+      duration_ms: durationMs,
+      message: `Timed out after ${webhook.timeout_ms}ms`,
+      stderr_excerpt: stderr,
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      delivered: false,
+      timed_out: false,
+      status_code: null,
+      duration_ms: durationMs,
+      message: stderr || `Webhook delivery failed with exit code ${result.status}`,
+      stderr_excerpt: stderr,
+    };
+  }
+
+  try {
+    const bridge = JSON.parse(stdout || '{}');
+    const statusCode = Number.isInteger(bridge.status) ? bridge.status : null;
+    const delivered = statusCode >= 200 && statusCode < 300;
+    return {
+      delivered,
+      timed_out: false,
+      status_code: statusCode,
+      duration_ms: durationMs,
+      message: delivered ? 'Delivered' : `Webhook returned HTTP ${statusCode}`,
+      stderr_excerpt: stderr,
+    };
+  } catch {
+    return {
+      delivered: false,
+      timed_out: false,
+      status_code: null,
+      duration_ms: durationMs,
+      message: 'Failed to parse webhook bridge response',
+      stderr_excerpt: stderr || stdout.slice(0, MAX_STDERR_CAPTURE),
+    };
+  }
+}
+
+export function validateNotificationsConfig(notifications) {
+  const errors = [];
+
+  if (!notifications || typeof notifications !== 'object' || Array.isArray(notifications)) {
+    errors.push('notifications must be an object');
+    return { ok: false, errors };
+  }
+
+  const allowedKeys = new Set(['webhooks']);
+  for (const key of Object.keys(notifications)) {
+    if (!allowedKeys.has(key)) {
+      errors.push(`notifications contains unknown field "${key}"`);
+    }
+  }
+
+  if (!('webhooks' in notifications)) {
+    return { ok: errors.length === 0, errors };
+  }
+
+  if (!Array.isArray(notifications.webhooks)) {
+    errors.push('notifications.webhooks must be an array');
+    return { ok: false, errors };
+  }
+
+  if (notifications.webhooks.length > MAX_NOTIFICATION_WEBHOOKS) {
+    errors.push(`notifications.webhooks: maximum ${MAX_NOTIFICATION_WEBHOOKS} webhooks`);
+  }
+
+  const names = new Set();
+  notifications.webhooks.forEach((webhook, index) => {
+    const label = `notifications.webhooks[${index}]`;
+
+    if (!webhook || typeof webhook !== 'object' || Array.isArray(webhook)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+
+    if (typeof webhook.name !== 'string' || !webhook.name.trim()) {
+      errors.push(`${label}: name must be a non-empty string`);
+    } else if (!NOTIFICATION_NAME_RE.test(webhook.name)) {
+      errors.push(`${label}: name must match ^[a-z0-9_-]+$`);
+    } else if (names.has(webhook.name)) {
+      errors.push(`${label}: duplicate webhook name "${webhook.name}"`);
+    } else {
+      names.add(webhook.name);
+    }
+
+    if (typeof webhook.url !== 'string' || !webhook.url.trim()) {
+      errors.push(`${label}: url must be a non-empty string`);
+    } else if (!/^https?:\/\/.+/.test(webhook.url)) {
+      errors.push(`${label}: url must be a valid HTTP or HTTPS URL`);
+    }
+
+    if (!Array.isArray(webhook.events) || webhook.events.length === 0) {
+      errors.push(`${label}: events must be a non-empty array`);
+    } else {
+      for (const eventName of webhook.events) {
+        if (!VALID_NOTIFICATION_EVENTS.includes(eventName)) {
+          errors.push(
+            `${label}: events contains unknown event "${eventName}". Valid events: ${VALID_NOTIFICATION_EVENTS.join(', ')}`
+          );
+        }
+      }
+    }
+
+    if (!Number.isInteger(webhook.timeout_ms) || webhook.timeout_ms < 100 || webhook.timeout_ms > 30000) {
+      errors.push(`${label}: timeout_ms must be an integer between 100 and 30000`);
+    }
+
+    if ('headers' in webhook && webhook.headers !== undefined) {
+      if (!webhook.headers || typeof webhook.headers !== 'object' || Array.isArray(webhook.headers)) {
+        errors.push(`${label}: headers must be an object`);
+      } else {
+        for (const [key, value] of Object.entries(webhook.headers)) {
+          if (typeof value !== 'string') {
+            errors.push(`${label}: headers.${key} must be a string`);
+          }
+        }
+        const missingHeaderVars = collectMissingHeaderVars(webhook.headers, webhook.env);
+        if (missingHeaderVars.length > 0) {
+          errors.push(
+            `${label}: unresolved header env vars ${missingHeaderVars.map(({ header, varName }) => `${header}:${varName}`).join(', ')}`
+          );
+        }
+      }
+    }
+
+    if ('env' in webhook && webhook.env !== undefined) {
+      if (!webhook.env || typeof webhook.env !== 'object' || Array.isArray(webhook.env)) {
+        errors.push(`${label}: env must be an object`);
+      } else {
+        for (const [key, value] of Object.entries(webhook.env)) {
+          if (typeof value !== 'string') {
+            errors.push(`${label}: env.${key} must be a string`);
+          }
+        }
+      }
+    }
+  });
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function emitNotifications(root, config, state, eventType, payload = {}, turn = null) {
+  const webhooks = config?.notifications?.webhooks;
+  if (!Array.isArray(webhooks) || webhooks.length === 0) {
+    return { ok: true, results: [] };
+  }
+
+  if (!VALID_NOTIFICATION_EVENTS.includes(eventType)) {
+    return { ok: false, error: `Unknown notification event "${eventType}"`, results: [] };
+  }
+
+  const eventId = generateEventId();
+  const emittedAt = new Date().toISOString();
+  const envelope = {
+    schema_version: '0.1',
+    event_id: eventId,
+    event_type: eventType,
+    emitted_at: emittedAt,
+    project: {
+      id: config?.project?.id || 'unknown',
+      name: config?.project?.name || 'Unknown',
+      root,
+    },
+    run: {
+      run_id: state?.run_id || null,
+      status: state?.status || null,
+      phase: state?.phase || null,
+    },
+    turn: turn ? {
+      turn_id: turn.turn_id || null,
+      role_id: turn.assigned_role || turn.role_id || null,
+      attempt: Number.isInteger(turn.attempt) ? turn.attempt : null,
+      assigned_sequence: Number.isInteger(turn.assigned_sequence) ? turn.assigned_sequence : null,
+    } : null,
+    payload,
+  };
+
+  const results = [];
+  for (const webhook of webhooks) {
+    if (!webhook.events.includes(eventType)) {
+      continue;
+    }
+
+    const delivery = executeWebhook(webhook, envelope);
+    const auditEntry = {
+      event_id: eventId,
+      event_type: eventType,
+      notification_name: webhook.name,
+      transport: 'webhook',
+      delivered: delivery.delivered,
+      status_code: delivery.status_code,
+      timed_out: delivery.timed_out,
+      duration_ms: delivery.duration_ms,
+      message: delivery.message,
+      emitted_at: emittedAt,
+    };
+    if (delivery.stderr_excerpt) {
+      auditEntry.stderr_excerpt = delivery.stderr_excerpt;
+    }
+    appendAudit(root, auditEntry);
+    results.push(auditEntry);
+  }
+
+  return { ok: true, event_id: eventId, results };
+}

package/src/lib/report.js

@@ -0,0 +1,379 @@
+import { verifyExportArtifact } from './export-verifier.js';
+
+export const GOVERNANCE_REPORT_VERSION = '0.1';
+
+function yesNo(value) {
+  return value ? 'yes' : 'no';
+}
+
+function summarizeBlockedOn(blockedOn) {
+  if (!blockedOn) return 'none';
+  if (typeof blockedOn === 'string') return blockedOn;
+  if (typeof blockedOn !== 'object' || Array.isArray(blockedOn)) return 'present';
+  if (typeof blockedOn.typed_reason === 'string' && blockedOn.typed_reason.length > 0) {
+    return blockedOn.typed_reason;
+  }
+  if (typeof blockedOn.reason === 'string' && blockedOn.reason.length > 0) {
+    return blockedOn.reason;
+  }
+  return 'present';
+}
+
+function summarizeBlockedState(run) {
+  const blockedReason = run?.blocked_reason;
+  if (blockedReason && typeof blockedReason === 'object' && !Array.isArray(blockedReason)) {
+    if (typeof blockedReason.recovery?.typed_reason === 'string' && blockedReason.recovery.typed_reason.length > 0) {
+      return blockedReason.recovery.typed_reason;
+    }
+    if (typeof blockedReason.category === 'string' && blockedReason.category.length > 0) {
+      return blockedReason.category;
+    }
+  }
+  return summarizeBlockedOn(run?.blocked_on);
+}
+
+function normalizeBudgetStatus(budgetStatus) {
+  if (!budgetStatus || typeof budgetStatus !== 'object' || Array.isArray(budgetStatus)) {
+    return null;
+  }
+
+  const normalized = {};
+  if (Number.isFinite(budgetStatus.spent_usd)) {
+    normalized.spent_usd = budgetStatus.spent_usd;
+  }
+  if (Number.isFinite(budgetStatus.remaining_usd)) {
+    normalized.remaining_usd = budgetStatus.remaining_usd;
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+function formatUsd(value) {
+  return typeof value === 'number' ? `$${value.toFixed(2)}` : 'n/a';
+}
+
+function formatStatusCounts(statusCounts) {
+  const entries = Object.entries(statusCounts || {}).sort(([left], [right]) => left.localeCompare(right, 'en'));
+  if (entries.length === 0) return 'none';
+  return entries.map(([status, count]) => `${status}(${count})`).join(', ');
+}
+
+function deriveRepoStatusCounts(repoStatuses) {
+  const counts = {};
+  for (const status of Object.values(repoStatuses || {})) {
+    const key = status || 'unknown';
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+function buildRunSubject(artifact) {
+  const activeTurns = artifact.summary?.active_turn_ids || [];
+  const retainedTurns = artifact.summary?.retained_turn_ids || [];
+  const activeRoles = [...new Set(
+    Object.values(artifact.state?.active_turns || {})
+      .map((turn) => turn?.assigned_role)
+      .filter((role) => typeof role === 'string' && role.length > 0),
+  )].sort((a, b) => a.localeCompare(b, 'en'));
+
+  return {
+    kind: 'governed_run',
+    project: {
+      id: artifact.project?.id || null,
+      name: artifact.project?.name || null,
+      template: artifact.project?.template || 'generic',
+      protocol_mode: artifact.project?.protocol_mode || null,
+      schema_version: artifact.project?.schema_version || null,
+    },
+    run: {
+      run_id: artifact.summary?.run_id || null,
+      status: artifact.summary?.status || null,
+      phase: artifact.summary?.phase || null,
+      blocked_on: artifact.state?.blocked_on || null,
+      blocked_reason: artifact.state?.blocked_reason || null,
+      active_turn_count: activeTurns.length,
+      retained_turn_count: retainedTurns.length,
+      active_turn_ids: activeTurns,
+      retained_turn_ids: retainedTurns,
+      active_roles: activeRoles,
+      budget_status: normalizeBudgetStatus(artifact.state?.budget_status),
+    },
+    artifacts: {
+      history_entries: artifact.summary?.history_entries || 0,
+      decision_entries: artifact.summary?.decision_entries || 0,
+      hook_audit_entries: artifact.summary?.hook_audit_entries || 0,
+      notification_audit_entries: artifact.summary?.notification_audit_entries || 0,
+      dispatch_artifact_files: artifact.summary?.dispatch_artifact_files || 0,
+      staging_artifact_files: artifact.summary?.staging_artifact_files || 0,
+      intake_present: Boolean(artifact.summary?.intake_present),
+      coordinator_present: Boolean(artifact.summary?.coordinator_present),
+    },
+  };
+}
+
+function buildCoordinatorSubject(artifact) {
+  const repoStatuses = artifact.summary?.repo_run_statuses || {};
+  const repoStatusCounts = deriveRepoStatusCounts(repoStatuses);
+  const repos = Object.entries(artifact.repos || {})
+    .sort(([left], [right]) => left.localeCompare(right, 'en'))
+    .map(([repoId, repoEntry]) => ({
+      repo_id: repoId,
+      path: repoEntry?.path || null,
+      ok: Boolean(repoEntry?.ok),
+      status: repoEntry?.ok ? repoEntry.export?.summary?.status || null : null,
+      run_id: repoEntry?.ok ? repoEntry.export?.summary?.run_id || null : null,
+      phase: repoEntry?.ok ? repoEntry.export?.summary?.phase || null : null,
+      project_id: repoEntry?.ok ? repoEntry.export?.project?.id || null : null,
+      project_name: repoEntry?.ok ? repoEntry.export?.project?.name || null : null,
+      error: repoEntry?.ok ? null : repoEntry?.error || null,
+    }));
+
+  const repoErrorCount = repos.filter((repo) => !repo.ok).length;
+
+  return {
+    kind: 'coordinator_workspace',
+    coordinator: {
+      project_id: artifact.coordinator?.project_id || null,
+      project_name: artifact.coordinator?.project_name || null,
+      schema_version: artifact.coordinator?.schema_version || null,
+      repo_count: artifact.coordinator?.repo_count || 0,
+      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,
+      barrier_count: artifact.summary?.barrier_count || 0,
+      repo_status_counts: repoStatusCounts,
+      repo_ok_count: repos.length - repoErrorCount,
+      repo_error_count: repoErrorCount,
+    },
+    repos,
+    artifacts: {
+      history_entries: artifact.summary?.history_entries || 0,
+      decision_entries: artifact.summary?.decision_entries || 0,
+    },
+  };
+}
+
+export function buildGovernanceReport(artifact, { input = 'stdin', generatedAt = new Date().toISOString() } = {}) {
+  const verification = verifyExportArtifact(artifact);
+  if (!verification.ok) {
+    return {
+      ok: false,
+      exitCode: 1,
+      report: {
+        overall: 'fail',
+        input,
+        message: 'Cannot build governance report from invalid export artifact.',
+        verification: verification.report,
+      },
+    };
+  }
+
+  let subject;
+  if (artifact.export_kind === 'agentxchain_run_export') {
+    subject = buildRunSubject(artifact);
+  } else if (artifact.export_kind === 'agentxchain_coordinator_export') {
+    subject = buildCoordinatorSubject(artifact);
+  } else {
+    return {
+      ok: false,
+      exitCode: 1,
+      report: {
+        overall: 'fail',
+        input,
+        message: 'Cannot build governance report from invalid export artifact.',
+        verification: verification.report,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    exitCode: 0,
+    report: {
+      report_version: GOVERNANCE_REPORT_VERSION,
+      overall: 'pass',
+      generated_at: generatedAt,
+      input,
+      export_kind: artifact.export_kind,
+      verification: verification.report,
+      subject,
+    },
+  };
+}
+
+export function formatGovernanceReportText(report) {
+  if (report.overall === 'error') {
+    return [
+      'AgentXchain Governance Report',
+      `Input: ${report.input}`,
+      'Status: ERROR',
+      `Message: ${report.message}`,
+    ].join('\n');
+  }
+
+  if (report.overall === 'fail') {
+    return [
+      'AgentXchain Governance Report',
+      `Input: ${report.input}`,
+      'Verification: FAIL',
+      report.message,
+      'Errors:',
+      ...(report.verification?.errors || []).map((error) => `- ${error}`),
+    ].join('\n');
+  }
+
+  if (report.subject.kind === 'governed_run') {
+    const { project, run, artifacts } = report.subject;
+    const lines = [
+      'AgentXchain Governance Report',
+      `Input: ${report.input}`,
+      `Export kind: ${report.export_kind}`,
+      'Verification: PASS',
+      `Project: ${project.name || 'unknown'} (${project.id || 'unknown'})`,
+      `Template: ${project.template}`,
+      `Protocol: ${project.protocol_mode || 'unknown'} (config schema ${project.schema_version || 'unknown'})`,
+      `Run: ${run.run_id || 'none'}`,
+      `Status: ${run.status || 'unknown'}`,
+      `Phase: ${run.phase || 'unknown'}`,
+      `Blocked on: ${summarizeBlockedState(run)}`,
+      `Active turns: ${run.active_turn_count}${run.active_turn_ids.length ? ` (${run.active_turn_ids.join(', ')})` : ''}`,
+      `Retained turns: ${run.retained_turn_count}${run.retained_turn_ids.length ? ` (${run.retained_turn_ids.join(', ')})` : ''}`,
+      `Active roles: ${run.active_roles.length ? run.active_roles.join(', ') : 'none'}`,
+    ];
+
+    if (run.budget_status) {
+      lines.push(
+        `Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}`,
+      );
+    }
+
+    lines.push(
+      `History entries: ${artifacts.history_entries}`,
+      `Decision entries: ${artifacts.decision_entries}`,
+      `Hook audit entries: ${artifacts.hook_audit_entries}`,
+      `Notification audit entries: ${artifacts.notification_audit_entries}`,
+      `Dispatch files: ${artifacts.dispatch_artifact_files}`,
+      `Staging files: ${artifacts.staging_artifact_files}`,
+      `Intake artifacts: ${yesNo(artifacts.intake_present)}`,
+      `Coordinator artifacts: ${yesNo(artifacts.coordinator_present)}`,
+    );
+
+    return lines.join('\n');
+  }
+
+  const { coordinator, run, artifacts, repos } = report.subject;
+  return [
+    'AgentXchain Governance Report',
+    `Input: ${report.input}`,
+    `Export kind: ${report.export_kind}`,
+    'Verification: PASS',
+    `Workspace: ${coordinator.project_name || 'unknown'} (${coordinator.project_id || 'unknown'})`,
+    `Coordinator schema: ${coordinator.schema_version || 'unknown'}`,
+    `Super run: ${run.super_run_id || 'none'}`,
+    `Status: ${run.status || 'unknown'}`,
+    `Phase: ${run.phase || 'unknown'}`,
+    `Repos: ${coordinator.repo_count} total, ${run.repo_ok_count} exported cleanly, ${run.repo_error_count} failed`,
+    `Workstreams: ${coordinator.workstream_count}`,
+    `Barriers: ${run.barrier_count}`,
+    `Repo statuses: ${formatStatusCounts(run.repo_status_counts)}`,
+    `History entries: ${artifacts.history_entries}`,
+    `Decision entries: ${artifacts.decision_entries}`,
+    'Repo details:',
+    ...repos.map((repo) => repo.ok
+      ? `- ${repo.repo_id}: ok, status ${repo.status || 'unknown'}, run ${repo.run_id || 'none'}, path ${repo.path || 'unknown'}`
+      : `- ${repo.repo_id}: failed export, ${repo.error || 'unknown error'}, path ${repo.path || 'unknown'}`),
+  ].join('\n');
+}
+
+export function formatGovernanceReportMarkdown(report) {
+  if (report.overall === 'error') {
+    return [
+      '# AgentXchain Governance Report',
+      '',
+      `- Input: \`${report.input}\``,
+      '- Status: `error`',
+      `- Message: ${report.message}`,
+    ].join('\n');
+  }
+
+  if (report.overall === 'fail') {
+    return [
+      '# AgentXchain Governance Report',
+      '',
+      `- Input: \`${report.input}\``,
+      '- Verification: `fail`',
+      `- Message: ${report.message}`,
+      '',
+      '## Verification Errors',
+      '',
+      ...(report.verification?.errors || []).map((error) => `- ${error}`),
+    ].join('\n');
+  }
+
+  if (report.subject.kind === 'governed_run') {
+    const { project, run, artifacts } = report.subject;
+    const lines = [
+      '# AgentXchain Governance Report',
+      '',
+      `- Input: \`${report.input}\``,
+      `- Export kind: \`${report.export_kind}\``,
+      '- Verification: `pass`',
+      `- Project: ${project.name || 'unknown'} (\`${project.id || 'unknown'}\`)`,
+      `- Template: \`${project.template}\``,
+      `- Protocol: \`${project.protocol_mode || 'unknown'}\` (config schema \`${project.schema_version || 'unknown'}\`)`,
+      `- Run: \`${run.run_id || 'none'}\``,
+      `- Status: \`${run.status || 'unknown'}\``,
+      `- Phase: \`${run.phase || 'unknown'}\``,
+      `- Blocked on: \`${summarizeBlockedState(run)}\``,
+      `- Active turns: ${run.active_turn_count}${run.active_turn_ids.length ? ` (\`${run.active_turn_ids.join('`, `')}\`)` : ''}`,
+      `- Retained turns: ${run.retained_turn_count}${run.retained_turn_ids.length ? ` (\`${run.retained_turn_ids.join('`, `')}\`)` : ''}`,
+      `- Active roles: ${run.active_roles.length ? `\`${run.active_roles.join('`, `')}\`` : '`none`'}`,
+    ];
+
+    if (run.budget_status) {
+      lines.push(`- Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}`);
+    }
+
+    lines.push(
+      `- History entries: ${artifacts.history_entries}`,
+      `- Decision entries: ${artifacts.decision_entries}`,
+      `- Hook audit entries: ${artifacts.hook_audit_entries}`,
+      `- Notification audit entries: ${artifacts.notification_audit_entries}`,
+      `- Dispatch files: ${artifacts.dispatch_artifact_files}`,
+      `- Staging files: ${artifacts.staging_artifact_files}`,
+      `- Intake artifacts: \`${yesNo(artifacts.intake_present)}\``,
+      `- Coordinator artifacts: \`${yesNo(artifacts.coordinator_present)}\``,
+    );
+
+    return lines.join('\n');
+  }
+
+  const { coordinator, run, artifacts, repos } = report.subject;
+  return [
+    '# AgentXchain Governance Report',
+    '',
+    `- Input: \`${report.input}\``,
+    `- Export kind: \`${report.export_kind}\``,
+    '- Verification: `pass`',
+    `- Workspace: ${coordinator.project_name || 'unknown'} (\`${coordinator.project_id || 'unknown'}\`)`,
+    `- Coordinator schema: \`${coordinator.schema_version || 'unknown'}\``,
+    `- Super run: \`${run.super_run_id || 'none'}\``,
+    `- Status: \`${run.status || 'unknown'}\``,
+    `- Phase: \`${run.phase || 'unknown'}\``,
+    `- Repos: ${coordinator.repo_count} total, ${run.repo_ok_count} exported cleanly, ${run.repo_error_count} failed`,
+    `- Workstreams: ${coordinator.workstream_count}`,
+    `- Barriers: ${run.barrier_count}`,
+    `- Repo statuses: ${formatStatusCounts(run.repo_status_counts)}`,
+    `- History entries: ${artifacts.history_entries}`,
+    `- Decision entries: ${artifacts.decision_entries}`,
+    '',
+    '## Repo Details',
+    '',
+    ...repos.map((repo) => repo.ok
+      ? `- \`${repo.repo_id}\`: ok, status \`${repo.status || 'unknown'}\`, run \`${repo.run_id || 'none'}\`, path \`${repo.path || 'unknown'}\``
+      : `- \`${repo.repo_id}\`: failed export, ${repo.error || 'unknown error'}, path \`${repo.path || 'unknown'}\``),
+  ].join('\n');
+}