agentxchain 2.63.0 → 2.65.0

package/bin/agentxchain.js

@@ -59,7 +59,7 @@ import { generateCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
-import { verifyExportCommand, verifyProtocolCommand } from '../src/commands/verify.js';
+import { verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
@@ -86,6 +86,8 @@ import {
 } from '../src/commands/plugin.js';
 import { templateSetCommand } from '../src/commands/template-set.js';
 import { templateListCommand } from '../src/commands/template-list.js';
+import { phaseCommand } from '../src/commands/phase.js';
+import { gateCommand } from '../src/commands/gate.js';
 import { roleCommand } from '../src/commands/role.js';
 import { turnShowCommand } from '../src/commands/turn.js';
 import { templateValidateCommand } from '../src/commands/template-validate.js';
@@ -330,7 +332,14 @@ program
 
 const verifyCmd = program
   .command('verify')
-  .description('Verify protocol conformance targets');
+  .description('Verify governed turns, export artifacts, and protocol conformance targets');
+
+verifyCmd
+  .command('turn [turn_id]')
+  .description('Replay a staged turn\'s declared machine-evidence commands and compare exit codes')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Per-command replay timeout in milliseconds', '30000')
+  .action(verifyTurnCommand);
 
 verifyCmd
   .command('protocol')
@@ -487,6 +496,39 @@ templateCmd
   .option('-j, --json', 'Output as JSON')
   .action(templateValidateCommand);
 
+const phaseCmd = program
+  .command('phase')
+  .description('Inspect governed workflow phases');
+
+phaseCmd
+  .command('list')
+  .description('List governed phases in routing order')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => phaseCommand('list', null, opts));
+
+phaseCmd
+  .command('show [phase]')
+  .description('Show one governed phase in detail')
+  .option('-j, --json', 'Output as JSON')
+  .action((phaseId, opts) => phaseCommand('show', phaseId, opts));
+
+const gateCmd = program
+  .command('gate')
+  .description('Inspect governed gate definitions');
+
+gateCmd
+  .command('list')
+  .description('List all defined gates with phase linkage and predicate summary')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => gateCommand('list', null, opts));
+
+gateCmd
+  .command('show <gate_id>')
+  .description('Show a single gate contract, predicates, and status')
+  .option('-j, --json', 'Output as JSON')
+  .option('--evaluate', 'Live-evaluate gate predicates against current filesystem')
+  .action((gateId, opts) => gateCommand('show', gateId, opts));
+
 const roleCmd = program
   .command('role')
   .description('Inspect governed role definitions');

package/package.json

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

package/src/commands/accept-turn.js

@@ -166,6 +166,9 @@ export async function acceptTurnCommand(opts = {}) {
   if (accepted?.cost?.usd != null) {
     console.log(`  ${chalk.dim('Cost:')}     $${formatUsd(accepted.cost.usd)}`);
   }
+  if (accepted?.verification_replay) {
+    console.log(`  ${chalk.dim('Replay:')}   ${accepted.verification_replay.overall} (${accepted.verification_replay.matched_commands}/${accepted.verification_replay.replayed_commands})`);
+  }
   if (result.budget_warning) {
     console.log(`  ${chalk.yellow('Budget warning:')} ${result.budget_warning}`);
   }

package/src/commands/gate.js

@@ -0,0 +1,315 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import {
+  evaluateArtifactSemantics,
+  evaluateWorkflowGateSemantics,
+  getSemanticIdForPath,
+} from '../lib/workflow-gate-semantics.js';
+import { getEffectiveGateArtifacts, hasRoleParticipationInPhase } from '../lib/gate-evaluator.js';
+
+export function gateCommand(subcommand, gateId, opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config, version } = context;
+  if (version !== 4 || config.protocol_mode !== 'governed') {
+    console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
+    process.exit(1);
+  }
+
+  const gateIds = Object.keys(config.gates || {});
+  if (gateIds.length === 0) {
+    console.log(chalk.red('  No gates defined in config.'));
+    process.exit(1);
+  }
+
+  const state = loadProjectState(root, config);
+
+  if (subcommand === 'show') {
+    return showGate(gateId, { root, config, state, gateIds, opts });
+  }
+
+  return listGates({ root, config, state, gateIds, opts });
+}
+
+function findLinkedPhase(gateId, routing) {
+  for (const [phaseId, route] of Object.entries(routing || {})) {
+    if (route.exit_gate === gateId) return phaseId;
+  }
+  return null;
+}
+
+function buildGateRecord(root, config, state, gateId, evaluate) {
+  const gateDef = config.gates[gateId] || {};
+  const linkedPhase = findLinkedPhase(gateId, config.routing);
+  const effectiveArtifacts = getEffectiveGateArtifacts(config, gateDef, linkedPhase);
+  const requiresFiles = Array.isArray(gateDef.requires_files) ? gateDef.requires_files : [];
+  const requiresVerification = gateDef.requires_verification_pass === true;
+  const requiresHumanApproval = gateDef.requires_human_approval === true;
+  const status = state?.phase_gate_status?.[gateId] || null;
+
+  const lastFailure = state?.last_gate_failure?.gate_id === gateId
+    ? state.last_gate_failure
+    : null;
+
+  const record = {
+    id: gateId,
+    linked_phase: linkedPhase,
+    requires_files: requiresFiles,
+    effective_artifacts: effectiveArtifacts.map(normalizeEffectiveArtifact),
+    requires_verification_pass: requiresVerification,
+    requires_human_approval: requiresHumanApproval,
+    status,
+    last_failure: lastFailure
+      ? {
+        gate_type: lastFailure.gate_type,
+        phase: lastFailure.phase,
+        failed_at: lastFailure.failed_at,
+        reasons: lastFailure.reasons || [],
+        missing_files: lastFailure.missing_files || [],
+      }
+      : null,
+  };
+
+  if (evaluate) {
+    record.evaluation = evaluateGateSnapshot({
+      root,
+      state,
+      linkedPhase,
+      requiresVerification,
+      effectiveArtifacts,
+    });
+  }
+
+  return record;
+}
+
+function normalizeEffectiveArtifact(artifact) {
+  return {
+    path: artifact.path,
+    required: artifact.required !== false,
+    owned_by: artifact.owned_by || null,
+    legacy_semantics: artifact.useLegacySemantics ? getSemanticIdForPath(artifact.path) : null,
+    semantic_checks: Array.isArray(artifact.semanticChecks) ? artifact.semanticChecks : [],
+  };
+}
+
+function getLatestAcceptedTurnForPhase(state, phase) {
+  if (!phase || !Array.isArray(state?.history)) {
+    return null;
+  }
+
+  for (let index = state.history.length - 1; index >= 0; index--) {
+    const entry = state.history[index];
+    if (entry?.phase === phase) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+function buildOwnershipFailure(artifact, linkedPhase) {
+  if (!artifact.owned_by) {
+    return null;
+  }
+
+  if (!linkedPhase) {
+    return `Gate is not linked to a routing phase, so ownership for "${artifact.path}" cannot be evaluated.`;
+  }
+
+  return `"${artifact.path}" requires participation from role "${artifact.owned_by}" in phase "${linkedPhase}", but no accepted turn from that role was found`;
+}
+
+function evaluateGateSnapshot({ root, state, linkedPhase, requiresVerification, effectiveArtifacts }) {
+  const missingFiles = [];
+  const semanticFailures = [];
+  const ownershipFailures = [];
+
+  const artifacts = effectiveArtifacts.map((artifact) => {
+    const exists = existsSync(join(root, artifact.path));
+    const failures = [];
+
+    if (!exists && artifact.required) {
+      const reason = `Required file missing: ${artifact.path}`;
+      missingFiles.push(artifact.path);
+      failures.push(reason);
+    }
+
+    if (exists && artifact.useLegacySemantics) {
+      const semanticCheck = evaluateWorkflowGateSemantics(root, artifact.path);
+      if (semanticCheck && !semanticCheck.ok) {
+        semanticFailures.push(semanticCheck.reason);
+        failures.push(semanticCheck.reason);
+      }
+    }
+
+    if (exists) {
+      for (const semantic of artifact.semanticChecks || []) {
+        const semanticCheck = evaluateArtifactSemantics(root, {
+          path: artifact.path,
+          semantics: semantic.semantics,
+          semantics_config: semantic.semantics_config,
+        });
+        if (semanticCheck && !semanticCheck.ok) {
+          semanticFailures.push(semanticCheck.reason);
+          failures.push(semanticCheck.reason);
+        }
+      }
+    }
+
+    const ownershipSatisfied = artifact.owned_by && linkedPhase
+      ? hasRoleParticipationInPhase(state, linkedPhase, artifact.owned_by)
+      : null;
+    if (artifact.owned_by && linkedPhase && ownershipSatisfied === false) {
+      const reason = buildOwnershipFailure(artifact, linkedPhase);
+      ownershipFailures.push(reason);
+      failures.push(reason);
+    }
+
+    return {
+      ...normalizeEffectiveArtifact(artifact),
+      exists,
+      ownership_satisfied: ownershipSatisfied,
+      failures,
+    };
+  });
+
+  const latestAcceptedTurn = getLatestAcceptedTurnForPhase(state, linkedPhase);
+  const verificationStatus = latestAcceptedTurn?.verification?.status || null;
+  const verificationPassed = verificationStatus === 'pass' || verificationStatus === 'attested_pass';
+  const reasons = [
+    ...artifacts.flatMap((artifact) => artifact.failures),
+  ];
+
+  if (requiresVerification && !verificationPassed) {
+    reasons.push(`Verification status is "${verificationStatus || 'missing'}", requires "pass" or "attested_pass"`);
+  }
+
+  return {
+    phase: linkedPhase,
+    passed: reasons.length === 0,
+    reasons,
+    missing_files: missingFiles,
+    semantic_failures: semanticFailures,
+    ownership_failures: ownershipFailures,
+    artifacts,
+    verification: {
+      required: requiresVerification,
+      source_turn_id: latestAcceptedTurn?.turn_id || null,
+      status: verificationStatus,
+      passed: requiresVerification ? verificationPassed : null,
+    },
+  };
+}
+
+function listGates({ root, config, state, gateIds, opts }) {
+  const gates = gateIds.map((id) => buildGateRecord(root, config, state, id, false));
+
+  if (opts.json) {
+    console.log(JSON.stringify({ gates }, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Gates (${gates.length}):\n`));
+  for (const gate of gates) {
+    const phase = gate.linked_phase || chalk.dim('orphaned');
+    const approval = gate.requires_human_approval ? chalk.yellow('human-approval') : 'auto';
+    const predicates = [];
+    if (gate.effective_artifacts.length > 0) predicates.push(`${gate.effective_artifacts.length} artifact${gate.effective_artifacts.length > 1 ? 's' : ''}`);
+    if (gate.requires_verification_pass) predicates.push('verification');
+    const predicateStr = predicates.length > 0 ? predicates.join(' + ') : 'none';
+    const statusStr = gate.status ? ` [${gate.status}]` : '';
+    console.log(`  ${chalk.cyan(gate.id)}${statusStr} — phase ${chalk.bold(phase)}, ${approval}, requires ${predicateStr}`);
+  }
+  console.log('');
+  console.log(chalk.dim('  Usage: agentxchain gate show <gate_id>\n'));
+}
+
+function showGate(requestedGateId, { root, config, state, gateIds, opts }) {
+  if (!requestedGateId) {
+    console.log(chalk.red('  Gate ID is required.'));
+    console.log(chalk.dim(`  Available: ${gateIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  if (!config.gates[requestedGateId]) {
+    console.log(chalk.red(`  Unknown gate: ${requestedGateId}`));
+    console.log(chalk.dim(`  Available: ${gateIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  const gate = buildGateRecord(root, config, state, requestedGateId, opts.evaluate);
+
+  if (opts.json) {
+    console.log(JSON.stringify(gate, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Gate: ${chalk.cyan(gate.id)}\n`));
+  console.log(`  Linked phase:       ${gate.linked_phase || chalk.dim('none (orphaned)')}`);
+  console.log(`  Human approval:     ${gate.requires_human_approval ? chalk.yellow('yes') : 'no'}`);
+  console.log(`  Verification:       ${gate.requires_verification_pass ? 'required' : 'not required'}`);
+  if (gate.status) {
+    const statusColor = gate.status === 'passed' ? chalk.green : gate.status === 'failed' ? chalk.red : chalk.yellow;
+    console.log(`  Status:             ${statusColor(gate.status)}`);
+  }
+  if (gate.evaluation) {
+    console.log(`  Evaluation:         ${gate.evaluation.passed ? chalk.green('pass') : chalk.red('fail')}`);
+  }
+  console.log('');
+
+  if (gate.effective_artifacts.length === 0) {
+    console.log(`  ${chalk.dim('Effective artifacts:')} none\n`);
+  } else {
+    console.log(`  ${chalk.dim('Effective artifacts:')}`);
+    const evaluatedArtifacts = gate.evaluation?.artifacts || [];
+    for (const artifact of gate.effective_artifacts) {
+      const artifactEval = evaluatedArtifacts.find((entry) => entry.path === artifact.path);
+      const icon = artifactEval
+        ? artifactEval.failures.length === 0
+          ? chalk.green('\u2713')
+          : chalk.red('\u2717')
+        : chalk.dim('-');
+      const owner = artifact.owned_by || 'none';
+      const semantics = [
+        artifact.legacy_semantics,
+        ...artifact.semantic_checks.map((entry) => entry.semantics),
+      ].filter(Boolean);
+      console.log(`    ${icon} ${artifact.path} [${artifact.required ? 'required' : 'optional'}] [owner: ${owner}] [semantics: ${semantics.length > 0 ? semantics.join(', ') : 'none'}]`);
+      if (artifactEval?.failures.length) {
+        for (const failure of artifactEval.failures) {
+          console.log(`      ${chalk.dim(`- ${failure}`)}`);
+        }
+      }
+    }
+    console.log('');
+  }
+
+  if (gate.evaluation && gate.requires_verification_pass) {
+    const vpIcon = gate.evaluation.verification.passed ? chalk.green('\u2713') : chalk.red('\u2717');
+    const source = gate.evaluation.verification.source_turn_id
+      ? ` (${gate.evaluation.verification.source_turn_id})`
+      : '';
+    console.log(`  Verification pass: ${vpIcon} ${gate.evaluation.verification.passed ? 'yes' : 'no'}${source}\n`);
+  }
+
+  if (gate.last_failure) {
+    console.log(chalk.dim('  Last failure:'));
+    console.log(`    Type:    ${gate.last_failure.gate_type}`);
+    console.log(`    Phase:   ${gate.last_failure.phase}`);
+    console.log(`    At:      ${gate.last_failure.failed_at}`);
+    if (gate.last_failure.reasons.length > 0) {
+      console.log(`    Reasons: ${gate.last_failure.reasons.join('; ')}`);
+    }
+    if (gate.last_failure.missing_files.length > 0) {
+      console.log(`    Missing: ${gate.last_failure.missing_files.join(', ')}`);
+    }
+    console.log('');
+  }
+}

package/src/commands/phase.js

@@ -0,0 +1,159 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { getNextPhase } from '../lib/gate-evaluator.js';
+import { getMaxConcurrentTurns } from '../lib/normalized-config.js';
+
+export function phaseCommand(subcommand, phaseId, opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config, rawConfig, version } = context;
+  if (version !== 4 || config.protocol_mode !== 'governed') {
+    console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
+    process.exit(1);
+  }
+
+  const phaseIds = Object.keys(config.routing || {});
+  if (phaseIds.length === 0) {
+    console.log(chalk.red('  No governed phases are defined in routing.'));
+    process.exit(1);
+  }
+
+  const state = loadProjectState(root, config);
+
+  if (subcommand === 'show') {
+    return showPhase(phaseId, { root, config, rawConfig, state, phaseIds, opts });
+  }
+
+  return listPhases({ root, config, rawConfig, state, phaseIds, opts });
+}
+
+function listPhases({ root, config, rawConfig, state, phaseIds, opts }) {
+  const phases = phaseIds.map((phaseId) => buildPhaseRecord(root, config, rawConfig, state, phaseId));
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      current_phase: state?.phase || null,
+      phases,
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Phases (${phases.length}):\n`));
+  for (const phase of phases) {
+    const current = phase.is_current ? chalk.green(' [current]') : '';
+    const entry = phase.entry_role || 'none';
+    const gate = phase.exit_gate || 'open';
+    const next = phase.next_phase || 'final';
+    console.log(`  ${chalk.cyan(phase.id)}${current} — entry ${chalk.bold(entry)}, gate ${gate}, next ${next}, artifacts ${phase.workflow_kit.artifacts.length}`);
+  }
+  console.log('');
+  console.log(chalk.dim('  Usage: agentxchain phase show <phase>\n'));
+}
+
+function showPhase(requestedPhaseId, { root, config, rawConfig, state, phaseIds, opts }) {
+  const phaseId = requestedPhaseId || state?.phase || phaseIds[0];
+  if (!config.routing?.[phaseId]) {
+    console.log(chalk.red(`  Unknown phase: ${phaseId}`));
+    console.log(chalk.dim(`  Available: ${phaseIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  const phase = buildPhaseRecord(root, config, rawConfig, state, phaseId);
+
+  if (opts.json) {
+    console.log(JSON.stringify(phase, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Phase: ${chalk.cyan(phase.id)}${phase.is_current ? chalk.green(' [current]') : ''}\n`));
+  console.log(`  Entry role:        ${phase.entry_role || chalk.dim('none')}`);
+  console.log(`  Exit gate:         ${phase.exit_gate || chalk.dim('open')}`);
+  if (phase.exit_gate_status) {
+    console.log(`  Gate status:       ${phase.exit_gate_status}`);
+  }
+  console.log(`  Next phase:        ${phase.next_phase || chalk.dim('final')}`);
+  console.log(`  Next roles:        ${phase.allowed_next_roles.length > 0 ? phase.allowed_next_roles.join(', ') : chalk.dim('none')}`);
+  console.log(`  Max turns:         ${phase.max_concurrent_turns}`);
+  if (phase.timeout_minutes != null || phase.timeout_action) {
+    console.log(`  Timeout override:  ${phase.timeout_minutes != null ? `${phase.timeout_minutes}m` : chalk.dim('default')} / ${phase.timeout_action || chalk.dim('default')}`);
+  }
+  console.log(`  Workflow source:   ${phase.workflow_kit.source}`);
+  if (phase.workflow_kit.template) {
+    console.log(`  Workflow template: ${phase.workflow_kit.template}`);
+  }
+  console.log('');
+
+  if (phase.workflow_kit.artifacts.length === 0) {
+    console.log(`  ${chalk.dim('Artifacts:')} none declared\n`);
+    return;
+  }
+
+  console.log(`  ${chalk.dim('Artifacts:')}`);
+  for (const artifact of phase.workflow_kit.artifacts) {
+    const icon = artifact.exists ? chalk.green('✓') : (artifact.required ? chalk.red('✗') : chalk.yellow('○'));
+    const ownerLabel = artifact.owner_resolution === 'explicit'
+      ? artifact.owned_by
+      : artifact.owner_resolution === 'entry_role'
+        ? `${chalk.dim(artifact.owned_by + ' (hint, not enforced)')}`
+        : 'none';
+    const semantics = artifact.semantics || 'none';
+    const required = artifact.required ? 'required' : 'optional';
+    console.log(`    ${icon} ${artifact.path} [${required}] [owner: ${ownerLabel}] [semantics: ${semantics}]`);
+  }
+  if (phase.workflow_kit.artifacts.some((artifact) => artifact.owner_resolution === 'entry_role')) {
+    console.log(`    ${chalk.dim('Hint: inferred ownership from entry_role is display-only. Only explicit owned_by is enforced at gate evaluation.')}`);
+  }
+  console.log('');
+}
+
+function buildPhaseRecord(root, config, rawConfig, state, phaseId) {
+  const route = config.routing?.[phaseId] || {};
+  const normalizedPhaseKit = config.workflow_kit?.phases?.[phaseId] || null;
+  const rawWorkflowKit = rawConfig.workflow_kit;
+  const rawPhaseKit = rawWorkflowKit?.phases?.[phaseId] || null;
+  const hasExplicitWorkflowKit = rawWorkflowKit !== undefined && rawWorkflowKit !== null;
+
+  const workflowSource = !hasExplicitWorkflowKit
+    ? 'default'
+    : rawPhaseKit
+      ? 'explicit'
+      : 'not_declared';
+
+  const artifacts = (normalizedPhaseKit?.artifacts || []).map((artifact) => {
+    const hasExplicitOwner = typeof artifact.owned_by === 'string' && artifact.owned_by.length > 0;
+    const ownedBy = hasExplicitOwner ? artifact.owned_by : (route.entry_role || null);
+    return {
+      path: artifact.path,
+      required: artifact.required !== false,
+      semantics: artifact.semantics || null,
+      owned_by: ownedBy,
+      owner_resolution: hasExplicitOwner ? 'explicit' : (ownedBy ? 'entry_role' : 'unowned'),
+      ownership_enforced: hasExplicitOwner,
+      exists: existsSync(join(root, artifact.path)),
+    };
+  });
+
+  return {
+    id: phaseId,
+    is_current: state?.phase === phaseId,
+    entry_role: route.entry_role || null,
+    exit_gate: route.exit_gate || null,
+    exit_gate_status: route.exit_gate ? (state?.phase_gate_status?.[route.exit_gate] || null) : null,
+    next_phase: getNextPhase(phaseId, config.routing || {}),
+    allowed_next_roles: Array.isArray(route.allowed_next_roles) ? route.allowed_next_roles : [],
+    timeout_minutes: typeof route.timeout_minutes === 'number' ? route.timeout_minutes : null,
+    timeout_action: typeof route.timeout_action === 'string' ? route.timeout_action : null,
+    max_concurrent_turns: getMaxConcurrentTurns(config, phaseId),
+    workflow_kit: {
+      source: workflowSource,
+      template: typeof rawPhaseKit?.template === 'string' ? rawPhaseKit.template : null,
+      artifacts,
+    },
+  };
+}

package/src/commands/step.js

@@ -1023,6 +1023,9 @@ function printAcceptSummary(result) {
   if (accepted?.cost?.usd != null) {
     console.log(`  ${chalk.dim('Cost:')}     $${(accepted.cost.usd || 0).toFixed(2)}`);
   }
+  if (accepted?.verification_replay) {
+    console.log(`  ${chalk.dim('Replay:')}   ${accepted.verification_replay.overall} (${accepted.verification_replay.matched_commands}/${accepted.verification_replay.replayed_commands})`);
+  }
   console.log('');
 
   if (result.state?.status === 'completed') {

package/src/commands/verify.js

@@ -1,7 +1,16 @@
 import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { getActiveTurns } from '../lib/governed-state.js';
+import { normalizeVerification } from '../lib/repo-observer.js';
+import { validateStagedTurnResult } from '../lib/turn-result-validator.js';
+import { getTurnStagingResultPath } from '../lib/turn-paths.js';
 import { resolve } from 'node:path';
 import { loadExportArtifact, verifyExportArtifact } from '../lib/export-verifier.js';
 import { verifyProtocolConformance } from '../lib/protocol-conformance.js';
+import {
+  DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS,
+  replayVerificationMachineEvidence,
+} from '../lib/verification-replay.js';
 
 export async function verifyProtocolCommand(opts, command) {
   const requestedTier = Number.parseInt(String(opts.tier || '1'), 10);
@@ -95,6 +104,71 @@ export async function verifyExportCommand(opts) {
   process.exit(result.ok ? 0 : 1);
 }
 
+export async function verifyTurnCommand(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('verify 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('verify turn requires a positive integer --timeout in milliseconds.'));
+    process.exit(2);
+  }
+
+  const { root, config } = context;
+  const state = loadProjectState(root, config);
+  const activeTurns = getActiveTurns(state);
+  const selectedTurnId = resolveTargetTurnId(turnId, activeTurns);
+  const selectedTurn = activeTurns[selectedTurnId];
+  const stagingPath = getTurnStagingResultPath(selectedTurnId);
+  const validationState = {
+    ...state,
+    active_turns: {
+      [selectedTurnId]: selectedTurn,
+    },
+  };
+  const validation = validateStagedTurnResult(root, validationState, config, { stagingPath });
+
+  if (!validation.ok) {
+    emitTurnValidationFailure(validation, opts.json);
+    process.exit(1);
+  }
+
+  const turnResult = validation.turnResult;
+  const runtimeType = config.runtimes?.[selectedTurn.runtime_id]?.type || 'manual';
+  const declaredStatus = turnResult.verification?.status || 'skipped';
+  const normalizedStatus = normalizeVerification(turnResult.verification, runtimeType).status;
+  const payload = {
+    turn_id: selectedTurnId,
+    role: selectedTurn.assigned_role,
+    runtime_id: selectedTurn.runtime_id,
+    runtime_type: runtimeType,
+    staging_path: stagingPath,
+    declared_status: declaredStatus,
+    normalized_status: normalizedStatus,
+    validation: {
+      ok: true,
+      warnings: validation.warnings || [],
+    },
+    timeout_ms: timeoutMs,
+    ...replayVerificationMachineEvidence({
+      root,
+      verification: turnResult.verification,
+      timeoutMs,
+    }),
+  };
+
+  emitTurnVerification(payload, opts.json);
+  process.exit(payload.overall === 'match' ? 0 : 1);
+}
+
 function printProtocolReport(report) {
   console.log('');
   console.log(chalk.bold('  AgentXchain Protocol Conformance'));
@@ -162,3 +236,118 @@ function printExportReport(report) {
 
   console.log('');
 }
+
+function resolveTargetTurnId(requestedTurnId, activeTurns) {
+  const turnIds = Object.keys(activeTurns);
+
+  if (requestedTurnId) {
+    if (!activeTurns[requestedTurnId]) {
+      console.log(chalk.red(`Unknown active turn: ${requestedTurnId}`));
+      if (turnIds.length > 0) {
+        console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+      }
+      process.exit(2);
+    }
+    return requestedTurnId;
+  }
+
+  if (turnIds.length === 0) {
+    console.log(chalk.red('No active turn found.'));
+    process.exit(2);
+  }
+
+  if (turnIds.length > 1) {
+    console.log(chalk.red('Multiple active turns are present. Re-run with `agentxchain verify turn <turn_id>`.'));
+    console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+    process.exit(2);
+  }
+
+  return turnIds[0];
+}
+
+function emitTurnValidationFailure(validation, jsonMode) {
+  const payload = {
+    overall: 'validation_failed',
+    validation: {
+      ok: false,
+      stage: validation.stage,
+      error_class: validation.error_class,
+      errors: validation.errors || [],
+      warnings: validation.warnings || [],
+    },
+  };
+
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.red('  Turn Verification Blocked By Validation'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Stage:')}    ${validation.stage || 'unknown'}`);
+  console.log(`  ${chalk.dim('Reason:')}   ${validation.error_class || 'validation_error'}`);
+  for (const error of validation.errors || []) {
+    console.log(`  ${chalk.dim('Error:')}    ${error}`);
+  }
+  if ((validation.warnings || []).length > 0) {
+    console.log('');
+    for (const warning of validation.warnings || []) {
+      console.log(`  ${chalk.dim('Warning:')}  ${warning}`);
+    }
+  }
+  console.log('');
+}
+
+function emitTurnVerification(payload, jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold(`  Verify Turn: ${chalk.cyan(payload.turn_id)}`));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Role:')}       ${payload.role}`);
+  console.log(`  ${chalk.dim('Runtime:')}    ${payload.runtime_id} (${payload.runtime_type})`);
+  console.log(`  ${chalk.dim('Staging:')}    ${payload.staging_path}`);
+  console.log(`  ${chalk.dim('Declared:')}   ${payload.declared_status}`);
+  console.log(`  ${chalk.dim('Normalized:')} ${payload.normalized_status}`);
+  console.log(`  ${chalk.dim('Outcome:')}    ${formatOutcome(payload.overall)}`);
+
+  for (const warning of payload.validation?.warnings || []) {
+    console.log(`  ${chalk.dim('Warning:')}    ${warning}`);
+  }
+
+  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/gate-evaluator.js

@@ -30,7 +30,7 @@ function getWorkflowArtifactsForPhase(config, phase) {
   return Array.isArray(artifacts) ? artifacts : [];
 }
 
-function buildEffectiveGateArtifacts(config, gateDef, phase) {
+export function getEffectiveGateArtifacts(config, gateDef, phase) {
   const byPath = new Map();
 
   if (Array.isArray(gateDef?.requires_files)) {
@@ -92,7 +92,7 @@ function prefixSemanticReason(filePath, reason) {
   return `${filePath}: ${reason}`;
 }
 
-function hasRoleParticipationInPhase(state, phase, roleId) {
+export function hasRoleParticipationInPhase(state, phase, roleId) {
   const history = state?.history;
   if (!Array.isArray(history)) {
     return false;
@@ -104,7 +104,7 @@ function hasRoleParticipationInPhase(state, phase, roleId) {
 
 function evaluateGateArtifacts({ root, config, gateDef, phase, result, state }) {
   const failures = [];
-  const artifacts = buildEffectiveGateArtifacts(config, gateDef, phase);
+  const artifacts = getEffectiveGateArtifacts(config, gateDef, phase);
 
   for (const artifact of artifacts) {
     const absPath = join(root, artifact.path);

package/src/lib/governed-state.js

@@ -44,6 +44,10 @@ import { emitRunEvent } from './run-events.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
 import { recordRunHistory } from './run-history.js';
 import { buildDefaultRunProvenance } from './run-provenance.js';
+import {
+  replayVerificationMachineEvidence,
+  summarizeVerificationReplay,
+} from './verification-replay.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -2367,6 +2371,9 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const normalizedVerification = normalizeVerification(turnResult.verification, runtimeType);
   const artifactType = turnResult.artifact?.type || 'review';
   const derivedRef = deriveAcceptedRef(observation, artifactType, state.accepted_integration_ref);
+  const verificationReplay = (config.policies || []).some((policy) => policy?.rule === 'require_reproducible_verification')
+    ? replayVerificationMachineEvidence({ root, verification: turnResult.verification })
+    : null;
 
   // Policy evaluation — declarative governance rules (spec: POLICY_ENGINE_SPEC.md)
   const policyResult = evaluatePolicies(config.policies || [], {
@@ -2375,6 +2382,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     turnStatus: turnResult.status,
     turnCostUsd: readTurnCostUsd(turnResult),
     history: historyEntries,
+    verificationReplay,
   });
 
   if (policyResult.blocks.length > 0) {
@@ -2572,6 +2580,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     artifacts_created: turnResult.artifacts_created || [],
     verification: turnResult.verification || {},
     normalized_verification: normalizedVerification,
+    ...(verificationReplay ? { verification_replay: summarizeVerificationReplay(verificationReplay) } : {}),
     artifact: turnResult.artifact || {},
     observed_artifact: observedArtifact,
     proposed_next_role: turnResult.proposed_next_role,
@@ -3176,6 +3185,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     hookResults,
     ...(budgetWarning ? { budget_warning: budgetWarning } : {}),
     ...(policyResult.warnings.length > 0 ? { policy_warnings: policyResult.warnings } : {}),
+    ...(verificationReplay ? { verification_replay: summarizeVerificationReplay(verificationReplay) } : {}),
   };
 }
 

package/src/lib/policy-evaluator.js

@@ -78,6 +78,32 @@ const RULE_EVALUATORS = {
     }
     return { triggered: false, message: '' };
   },
+
+  require_reproducible_verification: (_params, ctx) => {
+    const replay = ctx.verificationReplay;
+    if (!replay) {
+      return {
+        triggered: true,
+        message: 'verification replay context is missing at acceptance time',
+      };
+    }
+
+    if (replay.overall === 'match') {
+      return { triggered: false, message: '' };
+    }
+
+    if (replay.overall === 'not_reproducible') {
+      return {
+        triggered: true,
+        message: replay.reason || 'verification.machine_evidence did not provide executable proof',
+      };
+    }
+
+    return {
+      triggered: true,
+      message: `verification replay mismatch: ${replay.matched_commands || 0}/${replay.replayed_commands || 0} commands matched declared exit codes`,
+    };
+  },
 };
 
 export const VALID_POLICY_RULES = Object.keys(RULE_EVALUATORS);
@@ -185,6 +211,12 @@ function validatePolicyParams(rule, params, prefix) {
         }
       }
       break;
+
+    case 'require_reproducible_verification':
+      if (params != null && typeof params !== 'object') {
+        errors.push(`${prefix}: params must be an object when provided`);
+      }
+      break;
   }
 
   return errors;

package/src/lib/verification-replay.js

@@ -0,0 +1,68 @@
+import { spawnSync } from 'node:child_process';
+
+export const DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS = 30_000;
+
+export function replayVerificationMachineEvidence({ root, verification, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS }) {
+  const machineEvidence = Array.isArray(verification?.machine_evidence)
+    ? verification.machine_evidence
+    : [];
+
+  const payload = {
+    timeout_ms: timeoutMs,
+    overall: 'not_reproducible',
+    replayed_commands: 0,
+    matched_commands: 0,
+    commands: [],
+  };
+
+  if (machineEvidence.length === 0) {
+    payload.reason = 'No verification.machine_evidence commands were declared. commands/evidence_summary are not executable proof.';
+    return payload;
+  }
+
+  payload.commands = machineEvidence.map((entry, index) => replayEvidenceCommand(root, entry, index, timeoutMs));
+  payload.replayed_commands = payload.commands.length;
+  payload.matched_commands = payload.commands.filter((entry) => entry.matched).length;
+  payload.overall = payload.commands.every((entry) => entry.matched) ? 'match' : 'mismatch';
+
+  return payload;
+}
+
+export function replayEvidenceCommand(root, entry, index, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS) {
+  const result = spawnSync(entry.command, {
+    cwd: root,
+    encoding: 'utf8',
+    shell: true,
+    timeout: timeoutMs,
+    maxBuffer: 1024 * 1024,
+  });
+
+  const timedOut = result.error?.code === 'ETIMEDOUT';
+  const actualExitCode = Number.isInteger(result.status) ? result.status : null;
+  const errorMessage = result.error?.message || null;
+
+  return {
+    index,
+    command: entry.command,
+    declared_exit_code: entry.exit_code,
+    actual_exit_code: actualExitCode,
+    matched: actualExitCode === entry.exit_code,
+    timed_out: timedOut,
+    signal: result.signal || null,
+    error: errorMessage,
+  };
+}
+
+export function summarizeVerificationReplay(payload) {
+  if (!payload) {
+    return null;
+  }
+
+  return {
+    overall: payload.overall,
+    replayed_commands: payload.replayed_commands || 0,
+    matched_commands: payload.matched_commands || 0,
+    timeout_ms: payload.timeout_ms || DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS,
+    ...(payload.reason ? { reason: payload.reason } : {}),
+  };
+}