agentxchain 2.76.0 → 2.77.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';
@@ -111,6 +112,7 @@ import { intakeStatusCommand } from '../src/commands/intake-status.js';
 import { demoCommand } from '../src/commands/demo.js';
 import { historyCommand } from '../src/commands/history.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 +151,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 +267,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)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.76.0",
+  "version": "2.77.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/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++) {