agentxchain 2.80.0 → 2.81.0

package/README.md

@@ -167,6 +167,8 @@ agentxchain step
 | `approve-completion` | Approve a pending human-gated run completion |
 | `validate` | Validate governed kickoff wiring, a staged turn, or both |
 | `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
+| `verify turn` | Replay a staged turn's declared machine-evidence commands to confirm reproducibility before acceptance |
+| `replay turn` | Replay an accepted turn's machine-evidence commands from history for audit and drift detection |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
 | `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |

package/bin/agentxchain.js

@@ -60,6 +60,7 @@ import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
+import { replayTurnCommand } from '../src/commands/replay.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
@@ -388,6 +389,17 @@ verifyCmd
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyExportCommand);
 
+const replayCmd = program
+  .command('replay')
+  .description('Replay accepted governed evidence against the current workspace');
+
+replayCmd
+  .command('turn [turn_id]')
+  .description('Replay an accepted turn\'s declared machine-evidence commands from history')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Per-command replay timeout in milliseconds', '30000')
+  .action(replayTurnCommand);
+
 program
   .command('migrate')
   .description('Migrate a legacy v3 project to governed format')

package/package.json

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

package/src/commands/doctor.js

@@ -8,6 +8,7 @@ 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';
+import { PLUGIN_MANIFEST_FILE } from '../lib/plugins.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -74,6 +75,7 @@ function governedDoctor(root, rawConfig, opts) {
     const check = checkRuntimeReachable(rtId, rt);
     checks.push(check);
   }
+  const connectorProbe = getConnectorProbeRecommendation(runtimes);
 
   // 4. State directory
   const stateDir = join(root, '.agentxchain');
@@ -130,6 +132,90 @@ function governedDoctor(root, rawConfig, opts) {
     }
   }
 
+  // 8. Installed plugin health (only when plugins are installed)
+  const installedPlugins = rawConfig.plugins || {};
+  const pluginNames = Object.keys(installedPlugins);
+  if (pluginNames.length > 0) {
+    for (const pluginName of pluginNames) {
+      const meta = installedPlugins[pluginName];
+      const checkId = `plugin_${pluginName.replace(/[^a-z0-9_-]/gi, '_')}`;
+
+      // Check install path exists
+      if (!meta.install_path) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: 'No install_path recorded', plugin_name: pluginName });
+        continue;
+      }
+      const installAbsPath = join(root, meta.install_path);
+      if (!existsSync(installAbsPath)) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Install path missing: ${meta.install_path}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check manifest exists and is valid
+      const manifestPath = join(installAbsPath, PLUGIN_MANIFEST_FILE);
+      if (!existsSync(manifestPath)) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: 'Manifest file missing', plugin_name: pluginName });
+        continue;
+      }
+      let manifest;
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      } catch (err) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Manifest is corrupt JSON: ${err.message}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check hook files exist
+      const hookErrors = [];
+      if (manifest.hooks && typeof manifest.hooks === 'object') {
+        for (const [hookName, hookDef] of Object.entries(manifest.hooks)) {
+          if (!hookDef) continue;
+          const commands = Array.isArray(hookDef) ? hookDef : (hookDef.command ? [hookDef] : []);
+          for (const cmd of commands) {
+            const cmdArgs = cmd.command || cmd;
+            if (Array.isArray(cmdArgs) && cmdArgs.length > 0) {
+              const firstArg = cmdArgs[0];
+              if (typeof firstArg === 'string' && (firstArg.startsWith('./') || firstArg.startsWith('../'))) {
+                const hookFilePath = join(installAbsPath, firstArg);
+                if (!existsSync(hookFilePath)) {
+                  hookErrors.push(`${hookName}: ${firstArg}`);
+                }
+              }
+            }
+          }
+        }
+      }
+      if (hookErrors.length > 0) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Missing hook files: ${hookErrors.join(', ')}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check config env vars (warn only)
+      const envWarnings = [];
+      const pluginConfig = meta.config || {};
+      for (const [key, value] of Object.entries(pluginConfig)) {
+        if (typeof value === 'string' && value.startsWith('$')) {
+          const envVar = value.slice(1);
+          if (!process.env[envVar]) {
+            envWarnings.push(envVar);
+          }
+        }
+      }
+      // Also check webhook_env pattern from config
+      if (pluginConfig.webhook_env && !process.env[pluginConfig.webhook_env]) {
+        if (!envWarnings.includes(pluginConfig.webhook_env)) {
+          envWarnings.push(pluginConfig.webhook_env);
+        }
+      }
+
+      if (envWarnings.length > 0) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'warn', detail: `Env var(s) not set: ${envWarnings.join(', ')}`, plugin_name: pluginName });
+      } else {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'pass', detail: `v${manifest.version || '?'}, ${Object.keys(manifest.hooks || {}).length} hooks`, plugin_name: pluginName });
+      }
+    }
+  }
+
   // Compute summary
   const failCount = checks.filter(c => c.level === 'fail').length;
   const warnCount = checks.filter(c => c.level === 'warn').length;
@@ -143,6 +229,9 @@ function governedDoctor(root, rawConfig, opts) {
       ...versionSurface,
       config_version: versionSurface.config_generation,
       overall,
+      connector_probe_recommended: connectorProbe.recommended,
+      connector_probe_runtime_ids: connectorProbe.runtimeIds,
+      connector_probe_detail: connectorProbe.detail,
       checks,
       fail_count: failCount,
       warn_count: warnCount,
@@ -173,6 +262,9 @@ function governedDoctor(root, rawConfig, opts) {
     } else {
       console.log(chalk.red(`  Not ready: ${failCount} failure${failCount > 1 ? 's' : ''}, ${warnCount} warning${warnCount > 1 ? 's' : ''}.`));
     }
+    if (failCount === 0 && connectorProbe.recommended) {
+      console.log(chalk.dim(`  Next: ${connectorProbe.detail}`));
+    }
     console.log('');
   }
 
@@ -236,6 +328,35 @@ function checkRuntimeReachable(rtId, rt) {
   }
 }
 
+function getConnectorProbeRecommendation(runtimes) {
+  const runtimeIds = [];
+
+  for (const [rtId, rt] of Object.entries(runtimes || {})) {
+    if (!rt || typeof rt !== 'object') continue;
+    if (rt.type === 'api_proxy' || rt.type === 'remote_agent') {
+      runtimeIds.push(rtId);
+      continue;
+    }
+    if (rt.type === 'mcp' && (rt.transport || 'stdio') === 'streamable_http') {
+      runtimeIds.push(rtId);
+    }
+  }
+
+  if (runtimeIds.length === 0) {
+    return {
+      recommended: false,
+      runtimeIds: [],
+      detail: null,
+    };
+  }
+
+  return {
+    recommended: true,
+    runtimeIds,
+    detail: 'run `agentxchain connector check` to live-probe api / remote HTTP runtimes before the first governed turn.',
+  };
+}
+
 function getCurrentPhase(root) {
   const statePath = join(root, '.agentxchain', 'state.json');
   if (!existsSync(statePath)) return null;

package/src/commands/replay.js

@@ -0,0 +1,120 @@
+import chalk from 'chalk';
+
+import { loadProjectContext } from '../lib/config.js';
+import { normalizeVerification } from '../lib/repo-observer.js';
+import { resolveAcceptedTurnHistoryReference } from '../lib/accepted-turn-history.js';
+import {
+  DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS,
+  replayVerificationMachineEvidence,
+} from '../lib/verification-replay.js';
+
+export async function replayTurnCommand(turnId, opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(2);
+  }
+
+  if (context.config.protocol_mode !== 'governed' || context.version !== 4) {
+    console.log(chalk.red('replay turn is only available in governed v4 projects.'));
+    process.exit(2);
+  }
+
+  const timeoutMs = Number.parseInt(String(opts.timeout || String(DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS)), 10);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    console.log(chalk.red('replay turn requires a positive integer --timeout in milliseconds.'));
+    process.exit(2);
+  }
+
+  const { root, config } = context;
+  const resolved = resolveAcceptedTurnHistoryReference(root, turnId);
+  if (!resolved.ok) {
+    console.log(chalk.red(resolved.error));
+    process.exit(2);
+  }
+
+  const entry = resolved.entry;
+  const runtimeType = config.runtimes?.[entry.runtime_id]?.type || 'unknown';
+  const payload = {
+    source: 'history',
+    match_kind: resolved.match_kind,
+    turn_id: entry.turn_id,
+    resolved_turn_id: resolved.resolved_ref,
+    run_id: entry.run_id || null,
+    role: entry.role || null,
+    phase: entry.phase || null,
+    runtime_id: entry.runtime_id || null,
+    runtime_type: runtimeType,
+    accepted_at: entry.accepted_at || null,
+    declared_status: entry.verification?.status || 'skipped',
+    normalized_status: normalizeVerification(entry.verification, runtimeType).status,
+    timeout_ms: timeoutMs,
+    prior_verification_replay: entry.verification_replay || null,
+    ...replayVerificationMachineEvidence({
+      root,
+      verification: entry.verification,
+      timeoutMs,
+    }),
+  };
+
+  emitReplayTurn(payload, opts.json);
+  process.exit(payload.overall === 'match' ? 0 : 1);
+}
+
+function emitReplayTurn(payload, jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold(`  Replay Turn: ${chalk.cyan(payload.turn_id)}`));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Source:')}     accepted history (${payload.match_kind})`);
+  console.log(`  ${chalk.dim('Run:')}        ${payload.run_id || '—'}`);
+  console.log(`  ${chalk.dim('Role:')}       ${payload.role || '—'}`);
+  console.log(`  ${chalk.dim('Phase:')}      ${payload.phase || '—'}`);
+  console.log(`  ${chalk.dim('Runtime:')}    ${payload.runtime_id || '—'} (${payload.runtime_type})`);
+  console.log(`  ${chalk.dim('Accepted:')}   ${payload.accepted_at || '—'}`);
+  console.log(`  ${chalk.dim('Declared:')}   ${payload.declared_status}`);
+  console.log(`  ${chalk.dim('Normalized:')} ${payload.normalized_status}`);
+  if (payload.prior_verification_replay) {
+    const prior = payload.prior_verification_replay;
+    const verifiedAt = prior.verified_at ? ` at ${prior.verified_at}` : '';
+    console.log(`  ${chalk.dim('Prior replay:')} ${prior.overall} (${prior.matched_commands || 0}/${prior.replayed_commands || 0})${verifiedAt}`);
+  }
+  console.log(`  ${chalk.dim('Outcome:')}    ${formatOutcome(payload.overall)}`);
+
+  if (payload.reason) {
+    console.log(`  ${chalk.dim('Reason:')}     ${payload.reason}`);
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  for (const command of payload.commands || []) {
+    const marker = command.matched ? chalk.green('match') : chalk.red('mismatch');
+    console.log(`  [${marker}] ${command.command}`);
+    console.log(`    declared=${command.declared_exit_code} actual=${command.actual_exit_code == null ? 'null' : command.actual_exit_code}`);
+    if (command.signal) {
+      console.log(`    signal=${command.signal}`);
+    }
+    if (command.timed_out) {
+      console.log('    timed_out=true');
+    }
+    if (command.error) {
+      console.log(`    error=${command.error}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.dim('  Replay uses the current workspace and shell environment. It verifies declared exit-code reproducibility, not historical stdout/stderr identity.'));
+  console.log('');
+}
+
+function formatOutcome(outcome) {
+  if (outcome === 'match') return chalk.green('match');
+  if (outcome === 'mismatch') return chalk.red('mismatch');
+  return chalk.yellow('not_reproducible');
+}
+

package/src/lib/accepted-turn-history.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const HISTORY_PATH = '.agentxchain/history.jsonl';
+
+export function queryAcceptedTurnHistory(root) {
+  const filePath = join(root, HISTORY_PATH);
+  if (!existsSync(filePath)) return [];
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return [];
+  }
+
+  if (!content) return [];
+
+  return content
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry) => entry && typeof entry.turn_id === 'string')
+    .reverse();
+}
+
+export function resolveAcceptedTurnHistoryReference(root, ref) {
+  const entries = queryAcceptedTurnHistory(root);
+
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      error: 'No accepted turn history found. Accept at least one governed turn first.',
+    };
+  }
+
+  if (!ref) {
+    return {
+      ok: true,
+      entry: entries[0],
+      resolved_ref: entries[0].turn_id,
+      match_kind: 'latest',
+    };
+  }
+
+  const exact = entries.find((entry) => entry.turn_id === ref);
+  if (exact) {
+    return {
+      ok: true,
+      entry: exact,
+      resolved_ref: exact.turn_id,
+      match_kind: 'exact',
+    };
+  }
+
+  const prefixMatches = entries.filter((entry) => entry.turn_id.startsWith(ref));
+  if (prefixMatches.length === 1) {
+    return {
+      ok: true,
+      entry: prefixMatches[0],
+      resolved_ref: prefixMatches[0].turn_id,
+      match_kind: 'prefix',
+    };
+  }
+
+  if (prefixMatches.length > 1) {
+    return {
+      ok: false,
+      error: `Turn reference "${ref}" is ambiguous. Matches: ${prefixMatches.map((entry) => entry.turn_id).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Accepted turn ${ref} not found in history.`,
+  };
+}
+