agentxchain 2.5.0 → 2.6.0

package/bin/agentxchain.js

@@ -59,7 +59,7 @@ import { generateCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
-import { verifyProtocolCommand } from '../src/commands/verify.js';
+import { verifyExportCommand, verifyProtocolCommand } from '../src/commands/verify.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
@@ -71,6 +71,7 @@ import { stepCommand } from '../src/commands/step.js';
 import { approveTransitionCommand } from '../src/commands/approve-transition.js';
 import { approveCompletionCommand } from '../src/commands/approve-completion.js';
 import { dashboardCommand } from '../src/commands/dashboard.js';
+import { exportCommand } from '../src/commands/export.js';
 import {
   pluginInstallCommand,
   pluginListCommand,
@@ -121,6 +122,13 @@ program
   .option('-j, --json', 'Output as JSON')
   .action(statusCommand);
 
+program
+  .command('export')
+  .description('Export the governed run audit surface as a single artifact')
+  .option('--format <format>', 'Export format (json)', 'json')
+  .option('--output <path>', 'Write the export artifact to a file instead of stdout')
+  .action(exportCommand);
+
 program
   .command('start')
   .description('Launch legacy v3 agents in your IDE')
@@ -231,6 +239,13 @@ verifyCmd
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyProtocolCommand);
 
+verifyCmd
+  .command('export')
+  .description('Verify an AgentXchain export artifact against its embedded file bytes and summaries')
+  .option('--input <path>', 'Export artifact path, or "-" for stdin', '-')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(verifyExportCommand);
+
 program
   .command('migrate')
   .description('Migrate a legacy v3 project to governed format')

package/package.json

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

package/src/commands/export.js

@@ -0,0 +1,63 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { buildRunExport, buildCoordinatorExport } from '../lib/export.js';
+import { COORDINATOR_CONFIG_FILE } from '../lib/coordinator-config.js';
+import { safeWriteJson } from '../lib/safe-write.js';
+
+function detectExportKind(cwd) {
+  // Governed project takes priority (agentxchain.json)
+  if (existsSync(join(cwd, 'agentxchain.json'))) {
+    return 'governed';
+  }
+  // Coordinator workspace (agentxchain-multi.json)
+  if (existsSync(join(cwd, COORDINATOR_CONFIG_FILE))) {
+    return 'coordinator';
+  }
+  return null;
+}
+
+export async function exportCommand(options) {
+  const format = options.format || 'json';
+  if (format !== 'json') {
+    console.error(`Unsupported export format "${format}". Only "json" is supported in this slice.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const cwd = process.cwd();
+  const kind = detectExportKind(cwd);
+
+  let result;
+  try {
+    if (kind === 'governed') {
+      result = buildRunExport(cwd);
+    } else if (kind === 'coordinator') {
+      result = buildCoordinatorExport(cwd);
+    } else {
+      result = {
+        ok: false,
+        error: 'No governed project or coordinator workspace found. Run this inside an AgentXchain governed project or coordinator workspace.',
+      };
+    }
+  } catch (error) {
+    console.error(error.message || String(error));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!result.ok) {
+    console.error(result.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.output) {
+    const outputPath = resolve(cwd, options.output);
+    safeWriteJson(outputPath, result.export);
+    console.log(`Exported ${kind === 'coordinator' ? 'coordinator workspace' : 'governed run'} audit to ${options.output}`);
+    return;
+  }
+
+  console.log(JSON.stringify(result.export, null, 2));
+}

package/src/commands/verify.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { resolve } from 'node:path';
+import { loadExportArtifact, verifyExportArtifact } from '../lib/export-verifier.js';
 import { verifyProtocolConformance } from '../lib/protocol-conformance.js';
 
 export async function verifyProtocolCommand(opts) {
@@ -35,6 +36,38 @@ export async function verifyProtocolCommand(opts) {
   process.exit(result.exitCode);
 }
 
+export async function verifyExportCommand(opts) {
+  const format = opts.format || 'text';
+  const loaded = loadExportArtifact(opts.input || '-', process.cwd());
+
+  if (!loaded.ok) {
+    if (format === 'json') {
+      console.log(JSON.stringify({
+        overall: 'error',
+        input: loaded.input,
+        message: loaded.error,
+      }, null, 2));
+    } else {
+      console.log(chalk.red(`Export verification failed: ${loaded.error}`));
+    }
+    process.exit(2);
+  }
+
+  const result = verifyExportArtifact(loaded.artifact);
+  const report = {
+    ...result.report,
+    input: loaded.input,
+  };
+
+  if (format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printExportReport(report);
+  }
+
+  process.exit(result.ok ? 0 : 1);
+}
+
 function printProtocolReport(report) {
   console.log('');
   console.log(chalk.bold('  AgentXchain Protocol Conformance'));
@@ -74,3 +107,30 @@ function printProtocolReport(report) {
 
   console.log('');
 }
+
+function printExportReport(report) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Export Verification'));
+  console.log(chalk.dim('  ' + '─'.repeat(43)));
+  console.log(chalk.dim(`  Input: ${report.input}`));
+  console.log(chalk.dim(`  Export kind: ${report.export_kind || 'unknown'}`));
+  console.log(chalk.dim(`  Schema: ${report.schema_version || 'unknown'}`));
+  console.log('');
+
+  const overallLabel = report.overall === 'pass'
+    ? chalk.green('PASS')
+    : report.overall === 'fail'
+      ? chalk.red('FAIL')
+      : chalk.red('ERROR');
+  console.log(`  Overall: ${overallLabel}`);
+  console.log(chalk.dim(`  Files verified: ${report.file_count}`));
+  if (report.repo_count) {
+    console.log(chalk.dim(`  Embedded repos: ${report.repo_count}`));
+  }
+
+  for (const error of report.errors || []) {
+    console.log(chalk.red(`    ✗ ${error}`));
+  }
+
+  console.log('');
+}

package/src/lib/export-verifier.js

@@ -0,0 +1,422 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+const SUPPORTED_EXPORT_SCHEMA_VERSION = '0.2';
+const VALID_FILE_FORMATS = new Set(['json', 'jsonl', 'text']);
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function parseJsonl(raw, relPath) {
+  if (!raw.trim()) {
+    return [];
+  }
+
+  return raw
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`${relPath}: invalid JSONL at line ${index + 1}: ${error.message}`);
+      }
+    });
+}
+
+function addError(errors, path, message) {
+  errors.push(`${path}: ${message}`);
+}
+
+function verifyFileEntry(relPath, entry, errors) {
+  const path = `files.${relPath}`;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    addError(errors, path, 'file entry must be an object');
+    return;
+  }
+
+  if (!VALID_FILE_FORMATS.has(entry.format)) {
+    addError(errors, path, `unsupported format "${entry.format}"`);
+    return;
+  }
+
+  if (!Number.isInteger(entry.bytes) || entry.bytes < 0) {
+    addError(errors, path, 'bytes must be a non-negative integer');
+  }
+
+  if (typeof entry.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(entry.sha256)) {
+    addError(errors, path, 'sha256 must be a 64-character lowercase hex digest');
+  }
+
+  if (typeof entry.content_base64 !== 'string' || entry.content_base64.length === 0) {
+    addError(errors, path, 'content_base64 must be a non-empty string');
+    return;
+  }
+
+  let buffer;
+  try {
+    buffer = Buffer.from(entry.content_base64, 'base64');
+  } catch (error) {
+    addError(errors, path, `content_base64 is not valid base64: ${error.message}`);
+    return;
+  }
+
+  if (buffer.byteLength !== entry.bytes) {
+    addError(errors, path, `bytes mismatch: expected ${entry.bytes}, got ${buffer.byteLength}`);
+  }
+
+  if (sha256(buffer) !== entry.sha256) {
+    addError(errors, path, 'sha256 does not match content_base64');
+  }
+
+  const raw = buffer.toString('utf8');
+
+  try {
+    if (entry.format === 'json') {
+      const parsed = JSON.parse(raw);
+      if (!isDeepStrictEqual(parsed, entry.data)) {
+        addError(errors, path, 'data does not match decoded JSON content');
+      }
+      return;
+    }
+
+    if (entry.format === 'jsonl') {
+      const parsed = parseJsonl(raw, relPath);
+      if (!isDeepStrictEqual(parsed, entry.data)) {
+        addError(errors, path, 'data does not match decoded JSONL content');
+      }
+      return;
+    }
+
+    if (raw !== entry.data) {
+      addError(errors, path, 'data does not match decoded text content');
+    }
+  } catch (error) {
+    addError(errors, path, error.message);
+  }
+}
+
+function verifyFilesMap(files, errors) {
+  if (!files || typeof files !== 'object' || Array.isArray(files)) {
+    addError(errors, 'files', 'must be an object keyed by relative path');
+    return;
+  }
+
+  for (const [relPath, entry] of Object.entries(files)) {
+    verifyFileEntry(relPath, entry, errors);
+  }
+}
+
+function countJsonl(files, relPath) {
+  return Array.isArray(files?.[relPath]?.data) ? files[relPath].data.length : 0;
+}
+
+function countDirectoryFiles(files, prefix) {
+  return Object.keys(files || {}).filter((path) => path.startsWith(`${prefix}/`)).length;
+}
+
+function verifyRunExport(artifact, errors) {
+  if (typeof artifact.project_root !== 'string' || artifact.project_root.length === 0) {
+    addError(errors, 'project_root', 'must be a non-empty string');
+  }
+
+  if (!artifact.project || typeof artifact.project !== 'object' || Array.isArray(artifact.project)) {
+    addError(errors, 'project', 'must be an object');
+  } else {
+    const expectedProtocolMode = artifact.config?.protocol_mode
+      || artifact.state?.protocol_mode
+      || 'governed';
+    if (artifact.project.id !== artifact.config?.project?.id) {
+      addError(errors, 'project.id', 'must match config.project.id');
+    }
+    if (artifact.project.name !== artifact.config?.project?.name) {
+      addError(errors, 'project.name', 'must match config.project.name');
+    }
+    if (artifact.project.template !== (artifact.config?.template || 'generic')) {
+      addError(errors, 'project.template', 'must match config.template or implicit generic');
+    }
+    if (artifact.project.protocol_mode !== expectedProtocolMode) {
+      addError(errors, 'project.protocol_mode', 'must match exported protocol mode');
+    }
+  }
+
+  if (!artifact.summary || typeof artifact.summary !== 'object' || Array.isArray(artifact.summary)) {
+    addError(errors, 'summary', 'must be an object');
+    return;
+  }
+
+  if (!artifact.state || typeof artifact.state !== 'object' || Array.isArray(artifact.state)) {
+    addError(errors, 'state', 'must be an object');
+    return;
+  }
+
+  if (!isDeepStrictEqual(artifact.config, artifact.files?.['agentxchain.json']?.data)) {
+    addError(errors, 'config', 'must match files.agentxchain.json.data');
+  }
+
+  if (!isDeepStrictEqual(artifact.state, artifact.files?.['.agentxchain/state.json']?.data)) {
+    addError(errors, 'state', 'must match files..agentxchain/state.json.data');
+  }
+
+  const activeTurnIds = Object.keys(artifact.state.active_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
+  const retainedTurnIds = Object.keys(artifact.state.retained_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
+
+  if (!isDeepStrictEqual(artifact.summary.active_turn_ids, activeTurnIds)) {
+    addError(errors, 'summary.active_turn_ids', 'must match sorted state.active_turns keys');
+  }
+
+  if (!isDeepStrictEqual(artifact.summary.retained_turn_ids, retainedTurnIds)) {
+    addError(errors, 'summary.retained_turn_ids', 'must match sorted state.retained_turns keys');
+  }
+
+  if (artifact.summary.run_id !== (artifact.state.run_id || null)) {
+    addError(errors, 'summary.run_id', 'must match state.run_id');
+  }
+
+  if (artifact.summary.status !== (artifact.state.status || null)) {
+    addError(errors, 'summary.status', 'must match state.status');
+  }
+
+  if (artifact.summary.phase !== (artifact.state.phase || null)) {
+    addError(errors, 'summary.phase', 'must match state.phase');
+  }
+
+  const expectedHistoryEntries = countJsonl(artifact.files, '.agentxchain/history.jsonl');
+  const expectedDecisionEntries = countJsonl(artifact.files, '.agentxchain/decision-ledger.jsonl');
+  const expectedHookAuditEntries = countJsonl(artifact.files, '.agentxchain/hook-audit.jsonl');
+  const expectedDispatchFiles = countDirectoryFiles(artifact.files, '.agentxchain/dispatch');
+  const expectedStagingFiles = countDirectoryFiles(artifact.files, '.agentxchain/staging');
+  const expectedIntakePresent = Object.keys(artifact.files).some((path) => path.startsWith('.agentxchain/intake/'));
+  const expectedCoordinatorPresent = Object.keys(artifact.files).some((path) => path.startsWith('.agentxchain/multirepo/'));
+
+  if (artifact.summary.history_entries !== expectedHistoryEntries) {
+    addError(errors, 'summary.history_entries', 'must match .agentxchain/history.jsonl entry count');
+  }
+  if (artifact.summary.decision_entries !== expectedDecisionEntries) {
+    addError(errors, 'summary.decision_entries', 'must match .agentxchain/decision-ledger.jsonl entry count');
+  }
+  if (artifact.summary.hook_audit_entries !== expectedHookAuditEntries) {
+    addError(errors, 'summary.hook_audit_entries', 'must match .agentxchain/hook-audit.jsonl entry count');
+  }
+  if (artifact.summary.dispatch_artifact_files !== expectedDispatchFiles) {
+    addError(errors, 'summary.dispatch_artifact_files', 'must match .agentxchain/dispatch file count');
+  }
+  if (artifact.summary.staging_artifact_files !== expectedStagingFiles) {
+    addError(errors, 'summary.staging_artifact_files', 'must match .agentxchain/staging file count');
+  }
+  if (artifact.summary.intake_present !== expectedIntakePresent) {
+    addError(errors, 'summary.intake_present', 'must match intake file presence');
+  }
+  if (artifact.summary.coordinator_present !== expectedCoordinatorPresent) {
+    addError(errors, 'summary.coordinator_present', 'must match multirepo file presence');
+  }
+}
+
+function verifyCoordinatorExport(artifact, errors) {
+  if (typeof artifact.workspace_root !== 'string' || artifact.workspace_root.length === 0) {
+    addError(errors, 'workspace_root', 'must be a non-empty string');
+  }
+
+  if (!artifact.coordinator || typeof artifact.coordinator !== 'object' || Array.isArray(artifact.coordinator)) {
+    addError(errors, 'coordinator', 'must be an object');
+  } else {
+    if (artifact.coordinator.project_id !== (artifact.config?.project?.id || null)) {
+      addError(errors, 'coordinator.project_id', 'must match config.project.id');
+    }
+    if (artifact.coordinator.project_name !== (artifact.config?.project?.name || null)) {
+      addError(errors, 'coordinator.project_name', 'must match config.project.name');
+    }
+
+    const expectedRepoCount = Object.keys(artifact.config?.repos || {}).length;
+    const expectedWorkstreamCount = Object.keys(artifact.config?.workstreams || {}).length;
+    if (artifact.coordinator.repo_count !== expectedRepoCount) {
+      addError(errors, 'coordinator.repo_count', 'must match config.repos size');
+    }
+    if (artifact.coordinator.workstream_count !== expectedWorkstreamCount) {
+      addError(errors, 'coordinator.workstream_count', 'must match config.workstreams size');
+    }
+  }
+
+  if (!artifact.summary || typeof artifact.summary !== 'object' || Array.isArray(artifact.summary)) {
+    addError(errors, 'summary', 'must be an object');
+  } else {
+    const coordinatorState = artifact.files?.['.agentxchain/multirepo/state.json']?.data || null;
+    const expectedStatuses = {};
+    if (coordinatorState?.repo_runs && typeof coordinatorState.repo_runs === 'object') {
+      for (const [repoId, repoRun] of Object.entries(coordinatorState.repo_runs)) {
+        expectedStatuses[repoId] = repoRun.status || 'unknown';
+      }
+    }
+
+    const barriers = artifact.files?.['.agentxchain/multirepo/barriers.json']?.data;
+    const expectedBarrierCount = barriers && typeof barriers === 'object' && !Array.isArray(barriers)
+      ? Object.keys(barriers).length
+      : 0;
+
+    if (artifact.summary.super_run_id !== (coordinatorState?.super_run_id || null)) {
+      addError(errors, 'summary.super_run_id', 'must match coordinator state super_run_id');
+    }
+    if (artifact.summary.status !== (coordinatorState?.status || null)) {
+      addError(errors, 'summary.status', 'must match coordinator state status');
+    }
+    if (artifact.summary.phase !== (coordinatorState?.phase || null)) {
+      addError(errors, 'summary.phase', 'must match coordinator state phase');
+    }
+    if (!isDeepStrictEqual(artifact.summary.repo_run_statuses, expectedStatuses)) {
+      addError(errors, 'summary.repo_run_statuses', 'must match coordinator state repo run statuses');
+    }
+    if (artifact.summary.barrier_count !== expectedBarrierCount) {
+      addError(errors, 'summary.barrier_count', 'must match barriers.json object size');
+    }
+    if (artifact.summary.history_entries !== countJsonl(artifact.files, '.agentxchain/multirepo/history.jsonl')) {
+      addError(errors, 'summary.history_entries', 'must match multirepo history entry count');
+    }
+    if (artifact.summary.decision_entries !== countJsonl(artifact.files, '.agentxchain/multirepo/decision-ledger.jsonl')) {
+      addError(errors, 'summary.decision_entries', 'must match multirepo decision entry count');
+    }
+  }
+
+  if (!isDeepStrictEqual(artifact.config, artifact.files?.['agentxchain-multi.json']?.data)) {
+    addError(errors, 'config', 'must match files.agentxchain-multi.json.data');
+  }
+
+  if (!artifact.repos || typeof artifact.repos !== 'object' || Array.isArray(artifact.repos)) {
+    addError(errors, 'repos', 'must be an object');
+    return;
+  }
+
+  for (const [repoId, repoEntry] of Object.entries(artifact.repos)) {
+    const repoPath = `repos.${repoId}`;
+    if (!repoEntry || typeof repoEntry !== 'object' || Array.isArray(repoEntry)) {
+      addError(errors, repoPath, 'must be an object');
+      continue;
+    }
+    if (typeof repoEntry.path !== 'string' || repoEntry.path.length === 0) {
+      addError(errors, `${repoPath}.path`, 'must be a non-empty string');
+    }
+    if (typeof repoEntry.ok !== 'boolean') {
+      addError(errors, `${repoPath}.ok`, 'must be a boolean');
+      continue;
+    }
+    if (!repoEntry.ok) {
+      if (typeof repoEntry.error !== 'string' || repoEntry.error.length === 0) {
+        addError(errors, `${repoPath}.error`, 'must be a non-empty string when ok is false');
+      }
+      continue;
+    }
+    if (!repoEntry.export || typeof repoEntry.export !== 'object' || Array.isArray(repoEntry.export)) {
+      addError(errors, `${repoPath}.export`, 'must be an object when ok is true');
+      continue;
+    }
+    const nested = verifyExportArtifact(repoEntry.export);
+    for (const nestedError of nested.errors) {
+      addError(errors, `${repoPath}.export`, nestedError);
+    }
+  }
+}
+
+export function verifyExportArtifact(artifact) {
+  const errors = [];
+
+  if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    addError(errors, 'artifact', 'must be a JSON object');
+    return {
+      ok: false,
+      errors,
+      report: {
+        overall: 'fail',
+        schema_version: null,
+        export_kind: null,
+        file_count: 0,
+        errors,
+      },
+    };
+  }
+
+  if (artifact.schema_version !== SUPPORTED_EXPORT_SCHEMA_VERSION) {
+    addError(errors, 'schema_version', `must be "${SUPPORTED_EXPORT_SCHEMA_VERSION}"`);
+  }
+
+  if (typeof artifact.export_kind !== 'string') {
+    addError(errors, 'export_kind', 'must be a string');
+  }
+
+  if (typeof artifact.exported_at !== 'string' || Number.isNaN(Date.parse(artifact.exported_at))) {
+    addError(errors, 'exported_at', 'must be a valid ISO timestamp');
+  }
+
+  if (!artifact.config || typeof artifact.config !== 'object' || Array.isArray(artifact.config)) {
+    addError(errors, 'config', 'must be an object');
+  }
+
+  verifyFilesMap(artifact.files, errors);
+
+  if (artifact.export_kind === 'agentxchain_run_export') {
+    verifyRunExport(artifact, errors);
+  } else if (artifact.export_kind === 'agentxchain_coordinator_export') {
+    verifyCoordinatorExport(artifact, errors);
+  } else {
+    addError(errors, 'export_kind', `unsupported export kind "${artifact.export_kind}"`);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    report: {
+      overall: errors.length === 0 ? 'pass' : 'fail',
+      schema_version: artifact.schema_version || null,
+      export_kind: artifact.export_kind || null,
+      file_count: artifact.files && typeof artifact.files === 'object' && !Array.isArray(artifact.files)
+        ? Object.keys(artifact.files).length
+        : 0,
+      repo_count: artifact.repos && typeof artifact.repos === 'object' && !Array.isArray(artifact.repos)
+        ? Object.keys(artifact.repos).length
+        : 0,
+      errors,
+    },
+  };
+}
+
+export function loadExportArtifact(input, cwd = process.cwd()) {
+  const source = input || '-';
+  let raw;
+
+  try {
+    if (source === '-') {
+      if (process.stdin.isTTY) {
+        return {
+          ok: false,
+          input: 'stdin',
+          error: 'No export input provided. Pass --input <path> or pipe JSON on stdin.',
+        };
+      }
+      raw = readFileSync(0, 'utf8');
+    } else {
+      const resolved = resolve(cwd, source);
+      raw = readFileSync(resolved, 'utf8');
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      input: source === '-' ? 'stdin' : resolve(cwd, source),
+      error: error.message,
+    };
+  }
+
+  try {
+    return {
+      ok: true,
+      input: source === '-' ? 'stdin' : resolve(cwd, source),
+      artifact: JSON.parse(raw),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      input: source === '-' ? 'stdin' : resolve(cwd, source),
+      error: `Invalid JSON export artifact: ${error.message}`,
+    };
+  }
+}

package/src/lib/export.js

@@ -0,0 +1,303 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+import { loadProjectContext, loadProjectState } from './config.js';
+import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-config.js';
+import { loadCoordinatorState } from './coordinator-state.js';
+
+const EXPORT_SCHEMA_VERSION = '0.2';
+
+const COORDINATOR_INCLUDED_ROOTS = [
+  'agentxchain-multi.json',
+  '.agentxchain/multirepo/state.json',
+  '.agentxchain/multirepo/history.jsonl',
+  '.agentxchain/multirepo/barriers.json',
+  '.agentxchain/multirepo/decision-ledger.jsonl',
+  '.agentxchain/multirepo/barrier-ledger.jsonl',
+];
+
+const INCLUDED_ROOTS = [
+  'agentxchain.json',
+  '.agentxchain/state.json',
+  '.agentxchain/history.jsonl',
+  '.agentxchain/decision-ledger.jsonl',
+  '.agentxchain/hook-audit.jsonl',
+  '.agentxchain/hook-annotations.jsonl',
+  '.agentxchain/dispatch',
+  '.agentxchain/staging',
+  '.agentxchain/transactions/accept',
+  '.agentxchain/intake',
+  '.agentxchain/multirepo',
+];
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function collectPaths(root, relPath) {
+  const absPath = join(root, relPath);
+  if (!existsSync(absPath)) {
+    return [];
+  }
+
+  const stats = statSync(absPath);
+  if (stats.isFile()) {
+    return [relPath];
+  }
+
+  if (!stats.isDirectory()) {
+    return [];
+  }
+
+  const entries = readdirSync(absPath, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name, 'en'));
+
+  const files = [];
+  for (const entry of entries) {
+    const childRelPath = `${relPath}/${entry.name}`;
+    if (entry.isDirectory()) {
+      files.push(...collectPaths(root, childRelPath));
+    } else if (entry.isFile()) {
+      files.push(childRelPath);
+    }
+  }
+  return files;
+}
+
+function parseJsonl(relPath, raw) {
+  if (!raw.trim()) {
+    return [];
+  }
+
+  return raw
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`${relPath}: invalid JSONL at line ${index + 1}: ${error.message}`);
+      }
+    });
+}
+
+function parseFile(root, relPath) {
+  const absPath = join(root, relPath);
+  const buffer = readFileSync(absPath);
+  const raw = buffer.toString('utf8');
+
+  let format = 'text';
+  let data = raw;
+
+  if (relPath.endsWith('.json')) {
+    try {
+      data = JSON.parse(raw);
+      format = 'json';
+    } catch (error) {
+      throw new Error(`${relPath}: invalid JSON: ${error.message}`);
+    }
+  } else if (relPath.endsWith('.jsonl')) {
+    data = parseJsonl(relPath, raw);
+    format = 'jsonl';
+  }
+
+  return {
+    format,
+    bytes: buffer.byteLength,
+    sha256: sha256(buffer),
+    content_base64: buffer.toString('base64'),
+    data,
+  };
+}
+
+function countJsonl(files, relPath) {
+  return Array.isArray(files[relPath]?.data) ? files[relPath].data.length : 0;
+}
+
+function countDirectoryFiles(files, prefix) {
+  return Object.keys(files).filter((path) => path.startsWith(`${prefix}/`)).length;
+}
+
+export function buildRunExport(startDir = process.cwd()) {
+  const context = loadProjectContext(startDir);
+  if (!context) {
+    return {
+      ok: false,
+      error: 'No governed project found. Run this inside an AgentXchain governed project.',
+    };
+  }
+
+  if (context.config.protocol_mode !== 'governed') {
+    return {
+      ok: false,
+      error: 'Run export only supports governed projects in this slice.',
+    };
+  }
+
+  const { root, rawConfig, config, version } = context;
+  const state = loadProjectState(root, config);
+
+  const collectedPaths = [...new Set(INCLUDED_ROOTS.flatMap((relPath) => collectPaths(root, relPath)))]
+    .sort((a, b) => a.localeCompare(b, 'en'));
+
+  const files = {};
+  for (const relPath of collectedPaths) {
+    files[relPath] = parseFile(root, relPath);
+  }
+
+  const activeTurns = Object.keys(state?.active_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
+  const retainedTurns = Object.keys(state?.retained_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
+
+  return {
+    ok: true,
+    export: {
+      schema_version: EXPORT_SCHEMA_VERSION,
+      export_kind: 'agentxchain_run_export',
+      exported_at: new Date().toISOString(),
+      project_root: relative(process.cwd(), root) || '.',
+      project: {
+        id: config.project.id,
+        name: config.project.name,
+        template: config.template || 'generic',
+        protocol_mode: config.protocol_mode,
+        schema_version: version,
+      },
+      summary: {
+        run_id: state?.run_id || null,
+        status: state?.status || null,
+        phase: state?.phase || null,
+        active_turn_ids: activeTurns,
+        retained_turn_ids: retainedTurns,
+        history_entries: countJsonl(files, '.agentxchain/history.jsonl'),
+        decision_entries: countJsonl(files, '.agentxchain/decision-ledger.jsonl'),
+        hook_audit_entries: countJsonl(files, '.agentxchain/hook-audit.jsonl'),
+        dispatch_artifact_files: countDirectoryFiles(files, '.agentxchain/dispatch'),
+        staging_artifact_files: countDirectoryFiles(files, '.agentxchain/staging'),
+        intake_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/intake/')),
+        coordinator_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/multirepo/')),
+      },
+      files,
+      config: rawConfig,
+      state,
+    },
+  };
+}
+
+export function buildCoordinatorExport(startDir = process.cwd()) {
+  const workspaceRoot = resolve(startDir);
+  const configPath = join(workspaceRoot, COORDINATOR_CONFIG_FILE);
+
+  if (!existsSync(configPath)) {
+    return {
+      ok: false,
+      error: `No ${COORDINATOR_CONFIG_FILE} found at ${workspaceRoot}.`,
+    };
+  }
+
+  let rawConfig;
+  try {
+    rawConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Invalid JSON in ${COORDINATOR_CONFIG_FILE}: ${err.message}`,
+    };
+  }
+
+  const configResult = loadCoordinatorConfig(workspaceRoot);
+  const normalizedConfig = configResult.ok ? configResult.config : null;
+
+  // Collect coordinator-level files
+  const collectedPaths = [...new Set(
+    COORDINATOR_INCLUDED_ROOTS.flatMap((relPath) => collectPaths(workspaceRoot, relPath)),
+  )].sort((a, b) => a.localeCompare(b, 'en'));
+
+  const files = {};
+  for (const relPath of collectedPaths) {
+    files[relPath] = parseFile(workspaceRoot, relPath);
+  }
+
+  // Load coordinator state for summary
+  const coordState = loadCoordinatorState(workspaceRoot);
+
+  // Build repo run statuses from coordinator state
+  const repoRunStatuses = {};
+  if (coordState?.repo_runs) {
+    for (const [repoId, repoRun] of Object.entries(coordState.repo_runs)) {
+      repoRunStatuses[repoId] = repoRun.status || 'unknown';
+    }
+  }
+
+  // Count barriers from barriers.json
+  let barrierCount = 0;
+  const barriersKey = '.agentxchain/multirepo/barriers.json';
+  if (files[barriersKey]?.format === 'json' && files[barriersKey]?.data) {
+    barrierCount = Object.keys(files[barriersKey].data).length;
+  }
+
+  // Determine repos from config
+  const repos = {};
+  const repoEntries = rawConfig.repos && typeof rawConfig.repos === 'object'
+    ? Object.entries(rawConfig.repos)
+    : [];
+
+  for (const [repoId, repoDef] of repoEntries) {
+    const repoPath = repoDef?.path || '';
+    const resolvedPath = resolve(workspaceRoot, repoPath);
+
+    try {
+      const childExport = buildRunExport(resolvedPath);
+      if (childExport.ok) {
+        repos[repoId] = {
+          ok: true,
+          path: repoPath,
+          export: childExport.export,
+        };
+      } else {
+        repos[repoId] = {
+          ok: false,
+          path: repoPath,
+          error: childExport.error,
+        };
+      }
+    } catch (err) {
+      repos[repoId] = {
+        ok: false,
+        path: repoPath,
+        error: err.message || String(err),
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    export: {
+      schema_version: EXPORT_SCHEMA_VERSION,
+      export_kind: 'agentxchain_coordinator_export',
+      exported_at: new Date().toISOString(),
+      workspace_root: relative(process.cwd(), workspaceRoot) || '.',
+      coordinator: {
+        project_id: rawConfig.project?.id || null,
+        project_name: rawConfig.project?.name || null,
+        schema_version: rawConfig.schema_version || null,
+        repo_count: repoEntries.length,
+        workstream_count: rawConfig.workstreams
+          ? Object.keys(rawConfig.workstreams).length
+          : 0,
+      },
+      summary: {
+        super_run_id: coordState?.super_run_id || null,
+        status: coordState?.status || null,
+        phase: coordState?.phase || null,
+        repo_run_statuses: repoRunStatuses,
+        barrier_count: barrierCount,
+        history_entries: countJsonl(files, '.agentxchain/multirepo/history.jsonl'),
+        decision_entries: countJsonl(files, '.agentxchain/multirepo/decision-ledger.jsonl'),
+      },
+      files,
+      config: rawConfig,
+      repos,
+    },
+  };
+}