agentxchain 2.76.0 → 2.78.0

package/README.md

@@ -2,6 +2,8 @@
 
 CLI for governed multi-agent software delivery.
 
+AgentXchain coordinates multiple AI agents — PM, developer, QA, architect, and any custom roles — to work together on a codebase with built-in governance: structured turns, mandatory challenge between agents, phase gates, human approvals, and an append-only audit trail. Think of it as the operating system for AI software teams.
+
 The canonical mode is governed delivery: orchestrator-owned state, structured turn results, phase gates, mandatory challenge, and explicit human approvals where required.
 
 Legacy IDE-window coordination is still shipped as a compatibility mode for teams that want lock-based handoff in Cursor, VS Code, or Claude Code.
@@ -36,6 +38,13 @@ npm install -g agentxchain
 agentxchain --version
 ```
 
+Or via Homebrew (macOS/Linux):
+
+```bash
+brew tap shivamtiwari93/tap
+brew install agentxchain
+```
+
 For a zero-install one-off command, use the package-bound form:
 
 ```bash

package/bin/agentxchain.js

@@ -75,6 +75,7 @@ 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 { auditCommand } from '../src/commands/audit.js';
 import { restoreCommand } from '../src/commands/restore.js';
 import { restartCommand } from '../src/commands/restart.js';
 import { reportCommand } from '../src/commands/report.js';
@@ -110,7 +111,9 @@ import { intakeResolveCommand } from '../src/commands/intake-resolve.js';
 import { intakeStatusCommand } from '../src/commands/intake-status.js';
 import { demoCommand } from '../src/commands/demo.js';
 import { historyCommand } from '../src/commands/history.js';
+import { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
+import { connectorCheckCommand } from '../src/commands/connector.js';
 import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -149,6 +152,12 @@ program
   .option('--output <path>', 'Write the export artifact to a file instead of stdout')
   .action(exportCommand);
 
+program
+  .command('audit')
+  .description('Render a governance audit directly from the current governed project or coordinator workspace')
+  .option('--format <format>', 'Output format: text, json, or markdown', 'text')
+  .action(auditCommand);
+
 program
   .command('restore')
   .description('Restore governed continuity roots from a run export artifact')
@@ -259,6 +268,17 @@ program
   .option('-j, --json', 'Output as JSON')
   .action(doctorCommand);
 
+const connectorCmd = program
+  .command('connector')
+  .description('Probe governed runtime connectors directly');
+
+connectorCmd
+  .command('check [runtime_id]')
+  .description('Run live connector probes for all non-manual runtimes or one named runtime')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Per-probe timeout in milliseconds', '8000')
+  .action(connectorCheckCommand);
+
 program
   .command('demo')
   .description('Run a complete governed lifecycle demo (no API keys required)')
@@ -311,6 +331,13 @@ program
   .option('-d, --dir <path>', 'Project directory')
   .action(historyCommand);
 
+program
+  .command('diff <left_run_id> <right_run_id>')
+  .description('Compare two recorded governed runs from run-history')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(diffCommand);
+
 program
   .command('events')
   .description('Show repo-local run lifecycle events')

package/package.json

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

package/src/commands/audit.js

@@ -0,0 +1,75 @@
+import chalk from 'chalk';
+
+import { buildCoordinatorExport, buildRunExport } from '../lib/export.js';
+import {
+  buildGovernanceReport,
+  formatGovernanceReportMarkdown,
+  formatGovernanceReportText,
+} from '../lib/report.js';
+
+function detectAuditKind(cwd) {
+  const runResult = buildRunExport(cwd);
+  if (runResult.ok) {
+    return {
+      ok: true,
+      input: cwd,
+      artifact: runResult.export,
+    };
+  }
+
+  const coordinatorResult = buildCoordinatorExport(cwd);
+  if (coordinatorResult.ok) {
+    return {
+      ok: true,
+      input: cwd,
+      artifact: coordinatorResult.export,
+    };
+  }
+
+  return {
+    ok: false,
+    error: runResult.error || coordinatorResult.error || 'No governed project or coordinator workspace found.',
+  };
+}
+
+function printAndExit(report, format, exitCode) {
+  if (format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(exitCode);
+  }
+
+  if (format === 'markdown') {
+    console.log(formatGovernanceReportMarkdown(report));
+    process.exit(exitCode);
+  }
+
+  if (format === 'text') {
+    if (report.overall === 'error' || report.overall === 'fail') {
+      console.log(chalk.red(formatGovernanceReportText(report)));
+    } else {
+      console.log(formatGovernanceReportText(report));
+    }
+    process.exit(exitCode);
+  }
+
+  console.error(`Unsupported audit format "${format}". Use "text", "json", or "markdown".`);
+  process.exit(2);
+}
+
+export async function auditCommand(options) {
+  const format = options.format || 'text';
+  const cwd = process.cwd();
+  const resolved = detectAuditKind(cwd);
+
+  if (!resolved.ok) {
+    printAndExit({
+      overall: 'error',
+      input: cwd,
+      message: resolved.error,
+    }, format, 2);
+    return;
+  }
+
+  const result = buildGovernanceReport(resolved.artifact, { input: resolved.input });
+  printAndExit(result.report, format, result.exitCode);
+}

package/src/commands/connector.js

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+
+import { loadProjectContext } from '../lib/config.js';
+import { DEFAULT_TIMEOUT_MS, probeConfiguredConnectors } from '../lib/connector-probe.js';
+
+function printJson(result, exitCode) {
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(exitCode);
+}
+
+function printText(result, exitCode) {
+  if (result.connectors.length === 0) {
+    console.log('');
+    console.log(chalk.bold('  AgentXchain Connector Check'));
+    console.log(chalk.dim('  ' + '─'.repeat(44)));
+    console.log('');
+    console.log(`  ${chalk.green('PASS')}  No non-manual runtimes are configured`);
+    console.log('');
+    process.exit(exitCode);
+  }
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Connector Check'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim(`Timeout: ${result.timeout_ms}ms per connector`)}`);
+  console.log('');
+
+  for (const connector of result.connectors) {
+    const badge = connector.level === 'pass' ? chalk.green('PASS') : chalk.red('FAIL');
+    console.log(`  ${badge}  ${connector.runtime_id} (${connector.type})`);
+    console.log(`        ${chalk.dim('Target:')} ${connector.target}`);
+    console.log(`        ${chalk.dim('Probe:')}  ${connector.probe_kind}`);
+    if (connector.endpoint) {
+      console.log(`        ${chalk.dim('URL:')}    ${connector.endpoint}`);
+    }
+    if (connector.status_code != null) {
+      console.log(`        ${chalk.dim('HTTP:')}   ${connector.status_code}`);
+    }
+    if (connector.auth_env) {
+      console.log(`        ${chalk.dim('Auth:')}   ${connector.auth_env}`);
+    }
+    if (connector.latency_ms != null) {
+      console.log(`        ${chalk.dim('Time:')}   ${connector.latency_ms}ms`);
+    }
+    console.log(`        ${chalk.dim('Detail:')} ${connector.detail}`);
+  }
+
+  console.log('');
+  const summary = result.overall === 'pass'
+    ? chalk.green(`  ✓ ${result.pass_count}/${result.connectors.length} connectors passed`)
+    : chalk.red(`  ${result.fail_count} connector failure(s), ${result.pass_count} passed`);
+  console.log(summary);
+  console.log('');
+  process.exit(exitCode);
+}
+
+export async function connectorCheckCommand(runtimeId, options = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    const payload = { overall: 'error', error: 'No governed agentxchain.json found.' };
+    if (options.json) {
+      printJson(payload, 2);
+      return;
+    }
+    console.error(chalk.red('No governed agentxchain.json found. Run this inside a governed project.'));
+    process.exit(2);
+  }
+
+  if (context.config.protocol_mode !== 'governed') {
+    const payload = { overall: 'error', error: 'connector check only supports governed projects.' };
+    if (options.json) {
+      printJson(payload, 2);
+      return;
+    }
+    console.error(chalk.red('connector check only supports governed projects.'));
+    process.exit(2);
+  }
+
+  const timeoutMs = Number.parseInt(options.timeout || DEFAULT_TIMEOUT_MS, 10);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    const payload = { overall: 'error', error: 'Timeout must be a positive integer.' };
+    if (options.json) {
+      printJson(payload, 2);
+      return;
+    }
+    console.error(chalk.red('Timeout must be a positive integer.'));
+    process.exit(2);
+  }
+
+  const result = await probeConfiguredConnectors(context.config, {
+    runtimeId: runtimeId || null,
+    timeoutMs,
+    onProbeStart: options.json ? null : (probeRuntimeId, runtime) => {
+      console.log(`  ${chalk.dim('…')} Probing ${chalk.bold(probeRuntimeId)} ${chalk.dim(`(${runtime.type})`)}`);
+    },
+  });
+
+  if (!result.ok && result.error) {
+    const payload = { overall: 'error', error: result.error };
+    if (options.json) {
+      printJson(payload, result.exitCode || 2);
+      return;
+    }
+    console.error(chalk.red(result.error));
+    process.exit(result.exitCode || 2);
+  }
+
+  const payload = {
+    overall: result.overall,
+    timeout_ms: result.timeout_ms,
+    pass_count: result.pass_count,
+    fail_count: result.fail_count,
+    connectors: result.connectors,
+  };
+
+  if (options.json) {
+    printJson(payload, result.exitCode);
+    return;
+  }
+
+  printText(payload, result.exitCode);
+}

package/src/commands/demo.js

@@ -608,7 +608,8 @@ All acceptance criteria met. OBJ-002 (clock skew) noted for follow-up. OBJ-003 (
       console.log('');
       console.log(`  ${chalk.dim('1.')} ${chalk.bold('Scaffold')}     agentxchain init --governed --goal "Your project mission"`);
       console.log(`  ${chalk.dim('2.')} ${chalk.bold('Verify')}       agentxchain doctor`);
-      console.log(`  ${chalk.dim('3.')} ${chalk.bold('First turn')}   agentxchain run`);
+      console.log(`  ${chalk.dim('3.')} ${chalk.bold('Probe')}        agentxchain connector check`);
+      console.log(`  ${chalk.dim('4.')} ${chalk.bold('First turn')}   agentxchain run`);
       console.log('');
       console.log(`  ${chalk.bold('Docs:')}           https://agentxchain.dev/docs/quickstart`);
       console.log('');

package/src/commands/diff.js

@@ -0,0 +1,121 @@
+import chalk from 'chalk';
+
+import { findProjectRoot } from '../lib/config.js';
+import { buildRunDiff, resolveRunHistoryReference } from '../lib/run-diff.js';
+
+export async function diffCommand(leftRef, rightRef, opts) {
+  const root = findProjectRoot(opts.dir || process.cwd());
+  if (!root) {
+    console.error(chalk.red('No AgentXchain project found. Run this inside a governed project.'));
+    process.exit(1);
+  }
+
+  const leftResult = resolveRunHistoryReference(root, leftRef);
+  if (!leftResult.ok) {
+    console.error(chalk.red(leftResult.error));
+    process.exit(1);
+  }
+
+  const rightResult = resolveRunHistoryReference(root, rightRef);
+  if (!rightResult.ok) {
+    console.error(chalk.red(rightResult.error));
+    process.exit(1);
+  }
+
+  const diff = buildRunDiff(leftResult.entry, rightResult.entry);
+  if (opts.json) {
+    console.log(JSON.stringify(diff, null, 2));
+    return;
+  }
+
+  console.log(formatRunDiffText(diff));
+}
+
+function formatRunDiffText(diff) {
+  const lines = [];
+  lines.push(chalk.bold('Run Diff'));
+  lines.push(`${chalk.dim('Left:')}  ${formatRunHeader(diff.left)}`);
+  lines.push(`${chalk.dim('Right:')} ${formatRunHeader(diff.right)}`);
+
+  if (!diff.changed) {
+    lines.push('');
+    lines.push(chalk.green('No differences.'));
+    return lines.join('\n');
+  }
+
+  appendChangedSection(lines, 'Changed fields', Object.values(diff.scalar_changes)
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.label}: ${formatValue(entry.left, entry.label)} -> ${formatValue(entry.right, entry.label)}`));
+
+  appendChangedSection(lines, 'Numeric deltas', Object.values(diff.numeric_changes)
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.label}: ${formatValue(entry.left, entry.label)} -> ${formatValue(entry.right, entry.label)}${formatDelta(entry.delta, entry.label)}`));
+
+  appendChangedSection(lines, 'List changes', Object.values(diff.list_changes)
+    .filter((entry) => entry.changed)
+    .flatMap((entry) => {
+      const items = [];
+      if (entry.added.length > 0) {
+        items.push(`${entry.label} added: ${entry.added.join(', ')}`);
+      }
+      if (entry.removed.length > 0) {
+        items.push(`${entry.label} removed: ${entry.removed.join(', ')}`);
+      }
+      return items;
+    }));
+
+  appendChangedSection(lines, 'Gate changes', diff.gate_changes
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.gate_id}: ${formatValue(entry.left)} -> ${formatValue(entry.right)}`));
+
+  return lines.join('\n');
+}
+
+function appendChangedSection(lines, heading, items) {
+  if (items.length === 0) return;
+  lines.push('');
+  lines.push(chalk.bold(heading));
+  for (const item of items) {
+    lines.push(`- ${item}`);
+  }
+}
+
+function formatRunHeader(entry) {
+  const status = entry.status || '—';
+  const trigger = entry.trigger || 'legacy';
+  const recordedAt = entry.recorded_at
+    ? new Date(entry.recorded_at).toLocaleString()
+    : 'unknown date';
+  return `${entry.run_id} (${status}, ${trigger}, ${recordedAt})`;
+}
+
+function formatValue(value, label = '') {
+  if (value == null) return '—';
+  if (typeof value === 'boolean') return value ? 'yes' : 'no';
+  if (label === 'Cost' || label === 'Budget') return `$${value.toFixed(4)}`;
+  if (label === 'Duration') return formatDuration(value);
+  return String(value);
+}
+
+function formatDelta(delta, label) {
+  if (delta == null || delta === 0) return '';
+  if (label === 'Cost' || label === 'Budget') {
+    return ` (${delta > 0 ? '+' : ''}$${delta.toFixed(4)})`;
+  }
+  if (label === 'Duration') {
+    return ` (${delta > 0 ? '+' : ''}${formatDuration(delta)})`;
+  }
+  return ` (${delta > 0 ? '+' : ''}${delta})`;
+}
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const secs = Math.floor(ms / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  const remainSecs = secs % 60;
+  if (mins < 60) return `${mins}m ${remainSecs}s`;
+  const hrs = Math.floor(mins / 60);
+  const remainMins = mins % 60;
+  return `${hrs}h ${remainMins}m`;
+}

package/src/commands/doctor.js

@@ -7,6 +7,7 @@ import { validateProject } from '../lib/validation.js';
 import { getWatchPid } from './watch.js';
 import { loadNormalizedConfig, detectConfigVersion } from '../lib/normalized-config.js';
 import { readDaemonState, evaluateDaemonStatus } from '../lib/run-schedule.js';
+import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -136,9 +137,11 @@ function governedDoctor(root, rawConfig, opts) {
 
   if (opts.json) {
     const projectId = rawConfig?.project?.id || rawConfig?.project?.name || 'unknown';
+    const versionSurface = getGovernedVersionSurface(rawConfig);
     console.log(JSON.stringify({
       project: projectId,
-      config_version: 4,
+      ...versionSurface,
+      config_version: versionSurface.config_generation,
       overall,
       checks,
       fail_count: failCount,
@@ -149,7 +152,8 @@ function governedDoctor(root, rawConfig, opts) {
     console.log('');
     console.log(chalk.bold('  AgentXchain Governed Doctor'));
     console.log(chalk.dim('  ' + '─'.repeat(44)));
-    console.log(chalk.dim(`  Project: ${projectId} (v4)`));
+    console.log(chalk.dim(`  Project: ${projectId}`));
+    console.log(chalk.dim(`  Versioning: ${formatGovernedVersionLabel(rawConfig)}`));
     console.log('');
 
     for (const c of checks) {

package/src/commands/init.js

@@ -971,6 +971,7 @@ async function initGoverned(opts) {
   }
   console.log(`    ${chalk.bold('agentxchain template validate')} ${chalk.dim('# prove the scaffold contract before the first turn')}`);
   console.log(`    ${chalk.bold('agentxchain doctor')} ${chalk.dim('# verify runtimes, config, and readiness')}`);
+  console.log(`    ${chalk.bold('agentxchain connector check')} ${chalk.dim('# live-probe configured runtimes before the first turn')}`);
   console.log(`    ${chalk.bold('git add -A')} ${chalk.dim('# stage the governed scaffold')}`);
   console.log(`    ${chalk.bold('git commit -m "initial governed scaffold"')} ${chalk.dim('# checkpoint the starting state')}`);
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);

package/src/commands/validate.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { loadConfig, loadProjectContext } from '../lib/config.js';
 import { validateGovernedProject, validateProject } from '../lib/validation.js';
+import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
 
 export async function validateCommand(opts) {
   const context = loadProjectContext();
@@ -21,9 +22,13 @@ export async function validateCommand(opts) {
       });
 
   if (opts.json) {
+    const governedVersionSurface = context.config.protocol_mode === 'governed'
+      ? getGovernedVersionSurface(context.rawConfig)
+      : {};
     console.log(JSON.stringify({
       ...validation,
       protocol_mode: context.config.protocol_mode,
+      ...governedVersionSurface,
       version: context.version,
     }, null, 2));
   } else {
@@ -31,7 +36,11 @@ export async function validateCommand(opts) {
     console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
     console.log(chalk.dim('  ' + '─'.repeat(44)));
     console.log(chalk.dim(`  Root: ${context.root}`));
-    console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (v${context.version})`));
+    if (context.config.protocol_mode === 'governed') {
+      console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (${formatGovernedVersionLabel(context.rawConfig)})`));
+    } else {
+      console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (v${context.version})`));
+    }
     console.log('');
 
     if (validation.ok) {

package/src/lib/connector-probe.js

@@ -0,0 +1,353 @@
+import { execFileSync } from 'node:child_process';
+
+import {
+  buildProviderHeaders,
+  buildProviderRequest,
+  PROVIDER_ENDPOINTS,
+} from './adapters/api-proxy-adapter.js';
+
+const PROBEABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
+const DEFAULT_TIMEOUT_MS = 8_000;
+
+function formatCommand(command, args = []) {
+  if (Array.isArray(command)) {
+    return command.join(' ');
+  }
+  if (typeof command === 'string' && command.length > 0) {
+    return [command, ...(Array.isArray(args) ? args : [])].join(' ');
+  }
+  return null;
+}
+
+function formatTarget(runtime) {
+  switch (runtime?.type) {
+    case 'api_proxy':
+      return [runtime.provider, runtime.model].filter(Boolean).join(' / ') || 'unknown target';
+    case 'remote_agent':
+      return runtime.url || 'unknown target';
+    case 'mcp':
+      return runtime.transport === 'streamable_http'
+        ? (runtime.url || 'unknown target')
+        : (formatCommand(runtime.command, runtime.args) || 'unknown target');
+    case 'local_cli':
+      return formatCommand(runtime.command, runtime.args) || 'unknown target';
+    default:
+      return 'unknown target';
+  }
+}
+
+function commandHead(runtime) {
+  if (Array.isArray(runtime?.command)) {
+    return runtime.command[0] || null;
+  }
+  if (typeof runtime?.command === 'string' && runtime.command.trim()) {
+    return runtime.command.trim().split(/\s+/)[0];
+  }
+  return null;
+}
+
+function resolveBinary(command) {
+  const resolver = process.platform === 'win32' ? 'where' : 'which';
+  execFileSync(resolver, [command], { stdio: 'ignore' });
+}
+
+function resolveProviderEndpoint(runtime) {
+  if (typeof runtime?.base_url === 'string' && runtime.base_url.trim()) {
+    return runtime.base_url.trim();
+  }
+
+  const provider = String(runtime?.provider || '').trim().toLowerCase();
+  const endpointTemplate = PROVIDER_ENDPOINTS[provider];
+  if (!endpointTemplate) return null;
+
+  if (endpointTemplate.includes('{model}')) {
+    return endpointTemplate.replace('{model}', encodeURIComponent(runtime.model || ''));
+  }
+  return endpointTemplate;
+}
+
+function classifyHttpFailure(status, bodyText, authEnv) {
+  if (status === 401 || status === 403) {
+    return {
+      level: 'fail',
+      detail: authEnv
+        ? `${authEnv} was rejected by the remote endpoint`
+        : 'Remote endpoint rejected the request as unauthorized',
+    };
+  }
+  if (status === 404) {
+    return {
+      level: 'fail',
+      detail: 'Configured endpoint or model was not found',
+    };
+  }
+  if (status === 429) {
+    return {
+      level: 'fail',
+      detail: 'Remote endpoint is reachable but currently rate limited',
+    };
+  }
+  return {
+    level: 'fail',
+    detail: bodyText
+      ? `Remote endpoint returned HTTP ${status}: ${bodyText.slice(0, 160)}`
+      : `Remote endpoint returned HTTP ${status}`,
+  };
+}
+
+async function probeHttp({ url, method = 'GET', headers = {}, body, timeoutMs }) {
+  const startedAt = Date.now();
+  try {
+    const response = await fetch(url, {
+      method,
+      headers,
+      body,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const latencyMs = Date.now() - startedAt;
+    const responseText = await response.text();
+    return {
+      ok: true,
+      statusCode: response.status,
+      latencyMs,
+      responseText,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - startedAt,
+      error,
+    };
+  }
+}
+
+async function probeLocalCommand(runtimeId, runtime, probeKindLabel) {
+  const head = commandHead(runtime);
+  const base = {
+    runtime_id: runtimeId,
+    type: runtime.type,
+    target: formatTarget(runtime),
+    probe_kind: probeKindLabel,
+  };
+
+  if (!head) {
+    return {
+      ...base,
+      level: 'fail',
+      detail: 'No command configured',
+    };
+  }
+
+  try {
+    resolveBinary(head);
+    return {
+      ...base,
+      level: 'pass',
+      command: head,
+      detail: `${head} is available on PATH`,
+    };
+  } catch {
+    return {
+      ...base,
+      level: 'fail',
+      command: head,
+      detail: `${head} was not found on PATH`,
+    };
+  }
+}
+
+async function probeApiProxy(runtimeId, runtime, timeoutMs) {
+  const base = {
+    runtime_id: runtimeId,
+    type: runtime.type,
+    target: formatTarget(runtime),
+    probe_kind: 'live_api_request',
+    auth_env: runtime.auth_env || null,
+  };
+
+  if (runtime.auth_env && !process.env[runtime.auth_env]) {
+    return {
+      ...base,
+      level: 'fail',
+      detail: `${runtime.auth_env} is not set`,
+    };
+  }
+
+  const endpoint = resolveProviderEndpoint(runtime);
+  if (!endpoint) {
+    return {
+      ...base,
+      level: 'fail',
+      detail: `No probe endpoint is defined for provider "${runtime.provider || 'unknown'}"`,
+    };
+  }
+
+  const provider = String(runtime.provider || '').trim().toLowerCase();
+  const apiKey = runtime.auth_env ? process.env[runtime.auth_env] : '';
+  const requestBody = JSON.stringify(buildProviderRequest(provider, 'ping', '', runtime.model, 1));
+  const headers = buildProviderHeaders(provider, apiKey);
+  const result = await probeHttp({
+    url: endpoint,
+    method: 'POST',
+    headers,
+    body: requestBody,
+    timeoutMs,
+  });
+
+  if (!result.ok) {
+    return {
+      ...base,
+      endpoint,
+      level: 'fail',
+      latency_ms: result.latencyMs,
+      detail: `Probe failed: ${result.error?.name === 'TimeoutError' ? 'timed out' : (result.error?.message || 'network error')}`,
+    };
+  }
+
+  if (result.statusCode >= 200 && result.statusCode < 300) {
+    return {
+      ...base,
+      endpoint,
+      status_code: result.statusCode,
+      latency_ms: result.latencyMs,
+      level: 'pass',
+      detail: `${runtime.provider} accepted the live probe request`,
+    };
+  }
+
+  const classified = classifyHttpFailure(result.statusCode, result.responseText, runtime.auth_env);
+  return {
+    ...base,
+    endpoint,
+    status_code: result.statusCode,
+    latency_ms: result.latencyMs,
+    ...classified,
+  };
+}
+
+async function probeHttpRuntime(runtimeId, runtime, timeoutMs) {
+  const endpoint = runtime.url;
+  const base = {
+    runtime_id: runtimeId,
+    type: runtime.type,
+    target: formatTarget(runtime),
+    probe_kind: 'live_http_ping',
+    endpoint,
+  };
+
+  const result = await probeHttp({
+    url: endpoint,
+    method: 'GET',
+    headers: runtime.headers || {},
+    timeoutMs,
+  });
+
+  if (!result.ok) {
+    return {
+      ...base,
+      level: 'fail',
+      latency_ms: result.latencyMs,
+      detail: `Probe failed: ${result.error?.name === 'TimeoutError' ? 'timed out' : (result.error?.message || 'network error')}`,
+    };
+  }
+
+  if ((result.statusCode >= 200 && result.statusCode < 300) || result.statusCode === 405) {
+    return {
+      ...base,
+      level: 'pass',
+      status_code: result.statusCode,
+      latency_ms: result.latencyMs,
+      detail: result.statusCode === 405
+        ? 'Endpoint is reachable but rejects GET (expected for some RPC transports)'
+        : 'Endpoint responded to the live probe',
+    };
+  }
+
+  const classified = classifyHttpFailure(result.statusCode, result.responseText, null);
+  return {
+    ...base,
+    status_code: result.statusCode,
+    latency_ms: result.latencyMs,
+    ...classified,
+  };
+}
+
+export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  if (!runtime || !PROBEABLE_RUNTIME_TYPES.has(runtime.type)) {
+    return {
+      runtime_id: runtimeId,
+      type: runtime?.type || 'unknown',
+      target: formatTarget(runtime),
+      probe_kind: 'unsupported',
+      level: 'fail',
+      detail: `Runtime type "${runtime?.type || 'unknown'}" cannot be probed`,
+    };
+  }
+
+  if (runtime.type === 'local_cli') {
+    return probeLocalCommand(runtimeId, runtime, 'command_presence');
+  }
+
+  if (runtime.type === 'api_proxy') {
+    return probeApiProxy(runtimeId, runtime, timeoutMs);
+  }
+
+  if (runtime.type === 'mcp') {
+    if (runtime.transport === 'streamable_http') {
+      return probeHttpRuntime(runtimeId, runtime, timeoutMs);
+    }
+    return probeLocalCommand(runtimeId, runtime, 'command_presence');
+  }
+
+  return probeHttpRuntime(runtimeId, runtime, timeoutMs);
+}
+
+export async function probeConfiguredConnectors(config, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const requestedRuntimeId = options.runtimeId || null;
+  const onProbeStart = typeof options.onProbeStart === 'function' ? options.onProbeStart : null;
+
+  const runtimeEntries = Object.entries(config?.runtimes || {})
+    .filter(([, runtime]) => PROBEABLE_RUNTIME_TYPES.has(runtime?.type))
+    .sort(([left], [right]) => left.localeCompare(right, 'en'));
+
+  if (requestedRuntimeId) {
+    const match = runtimeEntries.find(([runtimeId]) => runtimeId === requestedRuntimeId);
+    if (!match) {
+      return {
+        ok: false,
+        error: `Unknown connector runtime "${requestedRuntimeId}"`,
+        exitCode: 2,
+      };
+    }
+    const [runtimeId, runtime] = match;
+    onProbeStart?.(runtimeId, runtime);
+    const connector = await probeConnectorRuntime(runtimeId, runtime, { timeoutMs });
+    return summarizeResults([connector], timeoutMs);
+  }
+
+  const connectors = [];
+  for (const [runtimeId, runtime] of runtimeEntries) {
+    onProbeStart?.(runtimeId, runtime);
+    connectors.push(await probeConnectorRuntime(runtimeId, runtime, { timeoutMs }));
+  }
+  return summarizeResults(connectors, timeoutMs);
+}
+
+function summarizeResults(connectors, timeoutMs) {
+  const failCount = connectors.filter((item) => item.level === 'fail').length;
+  const passCount = connectors.filter((item) => item.level === 'pass').length;
+  return {
+    ok: failCount === 0,
+    exitCode: failCount === 0 ? 0 : 1,
+    overall: failCount === 0 ? 'pass' : 'fail',
+    timeout_ms: timeoutMs,
+    pass_count: passCount,
+    fail_count: failCount,
+    connectors,
+  };
+}
+
+export { DEFAULT_TIMEOUT_MS, PROBEABLE_RUNTIME_TYPES };

package/src/lib/protocol-version.js

@@ -0,0 +1,40 @@
+export const CURRENT_PROTOCOL_VERSION = 'v6';
+export const CURRENT_CONFIG_GENERATION = 4;
+
+export function getGovernedConfigSchemaVersion(rawConfig) {
+  if (!rawConfig || typeof rawConfig !== 'object') {
+    return null;
+  }
+
+  if (typeof rawConfig.schema_version === 'string' && rawConfig.schema_version.trim()) {
+    return rawConfig.schema_version.trim();
+  }
+
+  if (rawConfig.schema_version === 4) {
+    return '1.0';
+  }
+
+  return null;
+}
+
+export function getGovernedVersionSurface(rawConfig) {
+  return {
+    protocol_version: CURRENT_PROTOCOL_VERSION,
+    config_generation: CURRENT_CONFIG_GENERATION,
+    config_schema_version: getGovernedConfigSchemaVersion(rawConfig),
+  };
+}
+
+export function formatGovernedVersionLabel(rawConfig) {
+  const surface = getGovernedVersionSurface(rawConfig);
+  const parts = [
+    `protocol ${surface.protocol_version}`,
+    `config generation v${surface.config_generation}`,
+  ];
+
+  if (surface.config_schema_version) {
+    parts.push(`config schema ${surface.config_schema_version}`);
+  }
+
+  return parts.join(', ');
+}

package/src/lib/report.js

@@ -149,6 +149,67 @@ function formatDurationCompact(ms) {
   return `${hrs}h ${remainMins}m`;
 }
 
+function formatTokenCount(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 'n/a';
+  return value.toLocaleString('en-US');
+}
+
+export function computeCostSummary(turns) {
+  if (!Array.isArray(turns) || turns.length === 0) return null;
+
+  let totalUsd = 0;
+  let costedTurnCount = 0;
+  let hasAnyTokens = false;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  const roleMap = new Map();
+  const phaseMap = new Map();
+
+  for (const t of turns) {
+    const costUsd = typeof t.cost_usd === 'number' && Number.isFinite(t.cost_usd) ? t.cost_usd : 0;
+    const hasFiniteCost = typeof t.cost_usd === 'number' && Number.isFinite(t.cost_usd);
+    if (hasFiniteCost) {
+      totalUsd += costUsd;
+      costedTurnCount++;
+    }
+
+    const inTok = typeof t.input_tokens === 'number' && Number.isFinite(t.input_tokens) ? t.input_tokens : 0;
+    const outTok = typeof t.output_tokens === 'number' && Number.isFinite(t.output_tokens) ? t.output_tokens : 0;
+    if (t.input_tokens != null || t.output_tokens != null) hasAnyTokens = true;
+    totalInputTokens += inTok;
+    totalOutputTokens += outTok;
+
+    // Aggregate by role
+    const role = t.role || 'unknown';
+    if (!roleMap.has(role)) roleMap.set(role, { role, usd: 0, turns: 0, input_tokens: 0, output_tokens: 0 });
+    const roleEntry = roleMap.get(role);
+    roleEntry.usd += costUsd;
+    roleEntry.turns++;
+    roleEntry.input_tokens += inTok;
+    roleEntry.output_tokens += outTok;
+
+    // Aggregate by phase
+    const phase = t.phase || 'unknown';
+    if (!phaseMap.has(phase)) phaseMap.set(phase, { phase, usd: 0, turns: 0 });
+    const phaseEntry = phaseMap.get(phase);
+    phaseEntry.usd += costUsd;
+    phaseEntry.turns++;
+  }
+
+  const byRole = [...roleMap.values()].sort((a, b) => a.role.localeCompare(b.role, 'en'));
+  const byPhase = [...phaseMap.values()].sort((a, b) => a.phase.localeCompare(b.phase, 'en'));
+
+  return {
+    total_usd: totalUsd,
+    total_input_tokens: hasAnyTokens ? totalInputTokens : null,
+    total_output_tokens: hasAnyTokens ? totalOutputTokens : null,
+    turn_count: turns.length,
+    costed_turn_count: costedTurnCount,
+    by_role: byRole,
+    by_phase: byPhase,
+  };
+}
+
 function formatTurnTimelineTime(turn) {
   const acceptedAt = turn.accepted_at || 'n/a';
   const duration = formatDurationCompact(turn.duration_ms);
@@ -188,6 +249,8 @@ function extractHistoryTimeline(artifact) {
       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,
+      input_tokens: typeof e.cost?.input_tokens === 'number' && Number.isFinite(e.cost.input_tokens) ? e.cost.input_tokens : null,
+      output_tokens: typeof e.cost?.output_tokens === 'number' && Number.isFinite(e.cost.output_tokens) ? e.cost.output_tokens : null,
       started_at: e.started_at || null,
       duration_ms: typeof e.duration_ms === 'number' ? e.duration_ms : null,
       accepted_at: e.accepted_at || null,
@@ -808,6 +871,7 @@ function buildRunSubject(artifact) {
       retained_turn_ids: retainedTurns,
       active_roles: activeRoles,
       budget_status: normalizeBudgetStatus(artifact.state?.budget_status),
+      cost_summary: computeCostSummary(turns),
       created_at: timing.created_at,
       completed_at: timing.completed_at,
       duration_seconds: timing.duration_seconds,
@@ -1086,6 +1150,30 @@ export function formatGovernanceReportText(report) {
       `Coordinator artifacts: ${yesNo(artifacts.coordinator_present)}`,
     );
 
+    if (run.cost_summary) {
+      const cs = run.cost_summary;
+      lines.push('', 'Cost Summary:');
+      lines.push(`  Total: ${formatUsd(cs.total_usd)} across ${cs.turn_count} turn${cs.turn_count !== 1 ? 's' : ''} (${cs.costed_turn_count} with cost data)`);
+      if (cs.total_input_tokens != null || cs.total_output_tokens != null) {
+        lines.push(`  Tokens: ${formatTokenCount(cs.total_input_tokens)} input / ${formatTokenCount(cs.total_output_tokens)} output`);
+      }
+      if (cs.by_role.length > 0) {
+        lines.push('  By role:');
+        for (const r of cs.by_role) {
+          const tokens = r.input_tokens || r.output_tokens
+            ? `, ${formatTokenCount(r.input_tokens)} in / ${formatTokenCount(r.output_tokens)} out`
+            : '';
+          lines.push(`    ${r.role}: ${formatUsd(r.usd)} (${r.turns} turn${r.turns !== 1 ? 's' : ''}${tokens})`);
+        }
+      }
+      if (cs.by_phase.length > 0) {
+        lines.push('  By phase:');
+        for (const p of cs.by_phase) {
+          lines.push(`    ${p.phase}: ${formatUsd(p.usd)} (${p.turns} turn${p.turns !== 1 ? 's' : ''})`);
+        }
+      }
+    }
+
     if (run.turns && run.turns.length > 0) {
       lines.push('', 'Turn Timeline:');
       for (let i = 0; i < run.turns.length; i++) {
@@ -1519,6 +1607,27 @@ export function formatGovernanceReportMarkdown(report) {
       `- Coordinator artifacts: \`${yesNo(artifacts.coordinator_present)}\``,
     );
 
+    if (run.cost_summary) {
+      const cs = run.cost_summary;
+      lines.push('', '## Cost Summary', '');
+      lines.push(`**Total:** ${formatUsd(cs.total_usd)} across ${cs.turn_count} turn${cs.turn_count !== 1 ? 's' : ''} (${cs.costed_turn_count} with cost data)`);
+      if (cs.total_input_tokens != null || cs.total_output_tokens != null) {
+        lines.push(`**Tokens:** ${formatTokenCount(cs.total_input_tokens)} input / ${formatTokenCount(cs.total_output_tokens)} output`);
+      }
+      if (cs.by_role.length > 0) {
+        lines.push('', '| Role | Cost | Turns | Input Tokens | Output Tokens |', '|------|------|-------|--------------|---------------|');
+        for (const r of cs.by_role) {
+          lines.push(`| ${r.role} | ${formatUsd(r.usd)} | ${r.turns} | ${formatTokenCount(r.input_tokens)} | ${formatTokenCount(r.output_tokens)} |`);
+        }
+      }
+      if (cs.by_phase.length > 0) {
+        lines.push('', '| Phase | Cost | Turns |', '|-------|------|-------|');
+        for (const p of cs.by_phase) {
+          lines.push(`| ${p.phase} | ${formatUsd(p.usd)} | ${p.turns} |`);
+        }
+      }
+    }
+
     if (run.turns && run.turns.length > 0) {
       lines.push('', '## Turn Timeline', '', '| # | Role | Phase | Summary | Files | Cost | Time |', '|---|------|-------|---------|-------|------|------|');
       for (let i = 0; i < run.turns.length; i++) {

package/src/lib/run-diff.js

@@ -0,0 +1,194 @@
+import { isInheritable, queryRunHistory } from './run-history.js';
+import { getRunTriggerLabel } from './run-provenance.js';
+
+const SCALAR_FIELDS = [
+  ['status', 'Status'],
+  ['trigger', 'Trigger'],
+  ['template', 'Template'],
+  ['connector_used', 'Connector'],
+  ['model_used', 'Model'],
+  ['blocked_reason', 'Blocked reason'],
+  ['headline', 'Headline'],
+  ['inheritable', 'Inheritance snapshot'],
+];
+
+const NUMERIC_FIELDS = [
+  ['total_turns', 'Turns'],
+  ['decisions_count', 'Decisions'],
+  ['total_cost_usd', 'Cost'],
+  ['budget_limit_usd', 'Budget'],
+  ['duration_ms', 'Duration'],
+];
+
+export function resolveRunHistoryReference(root, ref) {
+  const entries = queryRunHistory(root, {});
+
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      error: 'No run history found. Run at least one governed run first.',
+    };
+  }
+
+  const exact = entries.find((entry) => entry.run_id === ref);
+  if (exact) {
+    return { ok: true, entry: exact, resolved_ref: exact.run_id, match_kind: 'exact' };
+  }
+
+  const prefixMatches = entries.filter((entry) => typeof entry.run_id === 'string' && entry.run_id.startsWith(ref));
+  if (prefixMatches.length === 1) {
+    return {
+      ok: true,
+      entry: prefixMatches[0],
+      resolved_ref: prefixMatches[0].run_id,
+      match_kind: 'prefix',
+    };
+  }
+
+  if (prefixMatches.length > 1) {
+    return {
+      ok: false,
+      error: `Run reference "${ref}" is ambiguous. Matches: ${prefixMatches.map((entry) => entry.run_id).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Run ${ref} not found in run history.`,
+  };
+}
+
+export function buildRunDiff(leftEntry, rightEntry) {
+  const left = normalizeRunEntry(leftEntry);
+  const right = normalizeRunEntry(rightEntry);
+
+  const scalar_changes = Object.fromEntries(
+    SCALAR_FIELDS.map(([field, label]) => {
+      const leftValue = left[field];
+      const rightValue = right[field];
+      return [field, {
+        label,
+        left: leftValue,
+        right: rightValue,
+        changed: !isEqual(leftValue, rightValue),
+      }];
+    }),
+  );
+
+  const numeric_changes = Object.fromEntries(
+    NUMERIC_FIELDS.map(([field, label]) => {
+      const leftValue = left[field];
+      const rightValue = right[field];
+      return [field, {
+        label,
+        left: leftValue,
+        right: rightValue,
+        changed: !isEqual(leftValue, rightValue),
+        delta: typeof leftValue === 'number' && typeof rightValue === 'number'
+          ? rightValue - leftValue
+          : null,
+      }];
+    }),
+  );
+
+  const list_changes = {
+    phases_completed: buildListChange('Phases', left.phases_completed, right.phases_completed),
+    roles_used: buildListChange('Roles', left.roles_used, right.roles_used),
+  };
+
+  const gate_changes = buildGateChanges(left.gate_results, right.gate_results);
+
+  const changed = [
+    ...Object.values(scalar_changes),
+    ...Object.values(numeric_changes),
+  ].some((entry) => entry.changed)
+    || Object.values(list_changes).some((entry) => entry.changed)
+    || gate_changes.some((entry) => entry.changed);
+
+  return {
+    changed,
+    left,
+    right,
+    scalar_changes,
+    numeric_changes,
+    list_changes,
+    gate_changes,
+  };
+}
+
+function normalizeRunEntry(entry) {
+  return {
+    run_id: entry.run_id || null,
+    status: entry.status || null,
+    trigger: getRunTriggerLabel(entry.provenance),
+    template: entry.template || null,
+    connector_used: entry.connector_used || null,
+    model_used: entry.model_used || null,
+    blocked_reason: entry.blocked_reason || null,
+    headline: entry.retrospective?.headline || null,
+    inheritable: isInheritable(entry),
+    total_turns: typeof entry.total_turns === 'number' ? entry.total_turns : null,
+    decisions_count: typeof entry.decisions_count === 'number' ? entry.decisions_count : null,
+    total_cost_usd: typeof entry.total_cost_usd === 'number' ? entry.total_cost_usd : null,
+    budget_limit_usd: typeof entry.budget_limit_usd === 'number' ? entry.budget_limit_usd : null,
+    duration_ms: typeof entry.duration_ms === 'number' ? entry.duration_ms : null,
+    phases_completed: normalizeStringArray(entry.phases_completed),
+    roles_used: normalizeStringArray(entry.roles_used),
+    gate_results: normalizeGateResults(entry.gate_results),
+    recorded_at: entry.recorded_at || null,
+  };
+}
+
+function buildListChange(label, left, right) {
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  const added = right.filter((value) => !leftSet.has(value));
+  const removed = left.filter((value) => !rightSet.has(value));
+  return {
+    label,
+    left,
+    right,
+    added,
+    removed,
+    changed: added.length > 0 || removed.length > 0,
+  };
+}
+
+function buildGateChanges(leftGateResults, rightGateResults) {
+  const gateIds = [...new Set([
+    ...Object.keys(leftGateResults),
+    ...Object.keys(rightGateResults),
+  ])].sort((a, b) => a.localeCompare(b, 'en'));
+
+  return gateIds.map((gateId) => {
+    const left = gateId in leftGateResults ? leftGateResults[gateId] : null;
+    const right = gateId in rightGateResults ? rightGateResults[gateId] : null;
+    return {
+      gate_id: gateId,
+      left,
+      right,
+      changed: !isEqual(left, right),
+    };
+  });
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value
+    .filter((item) => typeof item === 'string' && item.trim().length > 0)
+    .map((item) => item.trim()))]
+    .sort((a, b) => a.localeCompare(b, 'en'));
+}
+
+function normalizeGateResults(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([gateId]) => typeof gateId === 'string' && gateId.trim().length > 0)
+      .map(([gateId, result]) => [gateId.trim(), result ?? null]),
+  );
+}
+
+function isEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}