agentxchain 2.123.0 → 2.125.0

package/bin/agentxchain.js

@@ -121,7 +121,7 @@ import { historyCommand } from '../src/commands/history.js';
 import { decisionsCommand } from '../src/commands/decisions.js';
 import { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
-import { connectorCheckCommand } from '../src/commands/connector.js';
+import { connectorCheckCommand, connectorValidateCommand } from '../src/commands/connector.js';
 import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
 import { chainLatestCommand, chainListCommand, chainShowCommand } from '../src/commands/chain.js';
 import { missionAttachChainCommand, missionListCommand, missionPlanApproveCommand, missionPlanAutopilotCommand, missionPlanCommand, missionPlanLaunchCommand, missionPlanListCommand, missionPlanShowCommand, missionShowCommand, missionStartCommand } from '../src/commands/mission.js';
@@ -297,6 +297,15 @@ connectorCmd
   .option('--timeout <ms>', 'Per-probe timeout in milliseconds', '8000')
   .action(connectorCheckCommand);
 
+connectorCmd
+  .command('validate <runtime_id>')
+  .description('Dispatch one synthetic governed turn through a runtime and validate the staged turn result')
+  .option('--role <role_id>', 'Validate a specific role binding for the runtime')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Synthetic dispatch timeout in milliseconds', '120000')
+  .option('--keep-artifacts', 'Keep the scratch validation workspace even on success')
+  .action(connectorValidateCommand);
+
 program
   .command('demo')
   .description('Run a complete governed lifecycle demo (no API keys required)')
@@ -918,6 +927,7 @@ intakeCmd
   .description('Start governed execution for a planned intent')
   .option('--intent <id>', 'Intent ID to start')
   .option('--role <role>', 'Override the default entry role for the governed phase')
+  .option('--restart-completed', 'Initialize a fresh governed run when state is already completed')
   .option('-j, --json', 'Output as JSON')
   .action(intakeStartCommand);
 

package/package.json

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

package/src/commands/approve-transition.js

@@ -2,6 +2,8 @@ import chalk from 'chalk';
 import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import { approvePhaseTransition } from '../lib/governed-state.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { resolveGovernedRole } from '../lib/role-resolution.js';
+import { checkCleanBaseline } from '../lib/repo-observer.js';
 
 export async function approveTransitionCommand(opts) {
   const context = loadProjectContext();
@@ -72,8 +74,21 @@ export async function approveTransitionCommand(opts) {
     console.log(`  ${chalk.dim('Gate actions:')} ${result.gateActionRun.actions.length} completed`);
   }
   console.log(chalk.dim(`  Run status: ${result.state.status}`));
+  const nextRole = resolveGovernedRole({ state: result.state, config });
+  const nextRoleConfig = nextRole.roleId ? config.roles?.[nextRole.roleId] : null;
+  const cleanBaseline = nextRoleConfig
+    ? checkCleanBaseline(root, nextRoleConfig.write_authority || 'review_only')
+    : { clean: true };
   console.log('');
-  console.log(chalk.dim(`  Next: agentxchain step  (to run the first turn in ${pt.to} phase)`));
+  if (!cleanBaseline.clean && nextRole.roleId) {
+    console.log(chalk.yellow('  Next turn blocked until the workspace is checkpointed.'));
+    console.log(`  ${chalk.dim('Role:')}  ${nextRole.roleId} (${nextRoleConfig?.write_authority || 'review_only'})`);
+    console.log(`  ${chalk.dim('Why:')}   ${cleanBaseline.reason}`);
+    console.log(chalk.dim('  Fix:   git add -A && git commit -m "checkpoint accepted artifacts"'));
+    console.log(chalk.dim(`  Then:  agentxchain step  (to run the first turn in ${pt.to} phase)`));
+  } else {
+    console.log(chalk.dim(`  Next: agentxchain step  (to run the first turn in ${pt.to} phase)`));
+  }
   console.log('');
 }
 

package/src/commands/connector.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 
 import { loadProjectContext } from '../lib/config.js';
+import { DEFAULT_VALIDATE_TIMEOUT_MS, validateConfiguredConnector } from '../lib/connector-validate.js';
 import { DEFAULT_TIMEOUT_MS, probeConfiguredConnectors } from '../lib/connector-probe.js';
 
 function printJson(result, exitCode) {
@@ -120,3 +121,95 @@ export async function connectorCheckCommand(runtimeId, options = {}) {
 
   printText(payload, result.exitCode);
 }
+
+function printValidateText(result, exitCode) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Connector Validate'));
+  console.log(chalk.dim('  ' + '─'.repeat(47)));
+  console.log(`  ${chalk.dim(`Runtime:`)} ${result.runtime_id} (${result.runtime_type})`);
+  console.log(`  ${chalk.dim(`Role:`)}    ${result.role_id}`);
+  console.log(`  ${chalk.dim(`Timeout:`)} ${result.timeout_ms}ms`);
+  console.log('');
+
+  const badge = result.overall === 'pass'
+    ? chalk.green('PASS')
+    : result.overall === 'error'
+      ? chalk.red('ERROR')
+      : chalk.red('FAIL');
+  const summary = result.overall === 'pass'
+    ? 'Synthetic governed dispatch produced a valid turn result'
+    : (result.error || result.dispatch?.error || result.validation?.errors?.[0] || 'Connector validation failed');
+  console.log(`  ${badge}  ${summary}`);
+
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    console.log('');
+    for (const warning of result.warnings) {
+      console.log(`  ${chalk.yellow('!')} ${warning}`);
+    }
+  }
+
+  if (result.dispatch) {
+    console.log('');
+    console.log(`  ${chalk.dim('Dispatch:')} ${result.dispatch.ok ? chalk.green('ok') : chalk.red('failed')}`);
+    if (result.dispatch.error) {
+      console.log(`  ${chalk.dim('Detail:')}   ${result.dispatch.error}`);
+    }
+  }
+
+  if (result.validation) {
+    console.log(`  ${chalk.dim('Validator:')} ${result.validation.ok ? chalk.green('ok') : chalk.red(result.validation.stage || 'failed')}`);
+    if (Array.isArray(result.validation.errors) && result.validation.errors.length > 0) {
+      console.log(`  ${chalk.dim('Errors:')}   ${result.validation.errors.join(' | ')}`);
+    }
+  }
+
+  if (typeof result.cost_usd === 'number') {
+    console.log(`  ${chalk.dim('Cost:')}     $${result.cost_usd.toFixed(3)}`);
+  }
+
+  if (result.scratch_root) {
+    console.log('');
+    console.log(`  ${chalk.dim('Scratch:')} ${result.scratch_root}`);
+  }
+
+  console.log('');
+  process.exit(exitCode);
+}
+
+export async function connectorValidateCommand(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);
+  }
+
+  const timeoutMs = Number.parseInt(options.timeout || DEFAULT_VALIDATE_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 validateConfiguredConnector(context.root, {
+    runtimeId,
+    roleId: options.role || null,
+    timeoutMs,
+    keepArtifacts: options.keepArtifacts === true,
+  });
+
+  if (options.json) {
+    printJson(result, result.exitCode ?? 1);
+    return;
+  }
+
+  printValidateText(result, result.exitCode ?? 1);
+}

package/src/commands/doctor.js

@@ -423,7 +423,7 @@ function getConnectorProbeRecommendation(runtimes) {
   return {
     recommended: true,
     runtimeIds,
-    detail: 'run `agentxchain connector check` to live-probe api / remote HTTP runtimes before the first governed turn.',
+    detail: 'run `agentxchain connector check` to live-probe api / remote HTTP runtimes, then `agentxchain connector validate <runtime_id>` to prove one binding produces valid governed turn results.',
   };
 }
 

package/src/commands/init.js

@@ -495,6 +495,18 @@ function formatGovernedRuntimeCommand(runtime) {
   return Array.isArray(runtime?.command) ? runtime.command.join(' ') : String(runtime?.command || '');
 }
 
+function formatRuntimeSummary(runtimeId, runtime) {
+  if (!runtimeId || !runtime) return 'unconfigured';
+  if (runtime.type === 'manual') return `${runtimeId} (manual)`;
+  const command = formatGovernedRuntimeCommand(runtime);
+  if (!command) return `${runtimeId} (${runtime.type})`;
+  return `${command} (${runtime.prompt_transport || runtime.type})`;
+}
+
+function hasTemplateDefinedRouting(template) {
+  return Boolean(template?.scaffold_blueprint?.routing && Object.keys(template.scaffold_blueprint.routing).length > 0);
+}
+
 function resolveInitDirOption(dirOption) {
   if (dirOption == null) return null;
   const value = String(dirOption).trim();
@@ -862,10 +874,8 @@ async function initGoverned(opts) {
   const dir = resolve(process.cwd(), folderName);
   const targetLabel = formatInitTarget(dir);
   const projectId = slugify(projectName);
-  let localDevRuntime;
-
   try {
-    ({ runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(opts));
+    resolveGovernedLocalDevRuntime(opts);
   } catch (err) {
     console.error(chalk.red(`  Error: ${err.message}`));
     process.exit(1);
@@ -906,6 +916,9 @@ async function initGoverned(opts) {
     ? { ...opts, goal: projectGoal }
     : { ...opts };
   const { config, scaffoldWorkflowKitConfig } = scaffoldGoverned(dir, projectName, projectId, templateId, scaffoldOptions, workflowKitConfig);
+  const devRuntimeId = config.roles?.dev?.runtime;
+  const devRuntime = devRuntimeId ? config.runtimes?.[devRuntimeId] : null;
+  const hasLiveConnectorProbe = Object.values(config.runtimes || {}).some((runtime) => runtime?.type && runtime.type !== 'manual');
 
   console.log('');
   console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(targetLabel)}/`));
@@ -928,12 +941,12 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.dim('└──')} TALK.md`);
   console.log('');
   console.log(`  ${chalk.dim('Roles:')} ${promptRoleIds.join(', ')}`);
-  console.log(`  ${chalk.dim('Phases:')} ${phaseNames.join(' → ')} ${chalk.dim(selectedTemplate.scaffold_blueprint ? '(template-defined; edit routing in agentxchain.json to customize)' : '(default; extend via routing in agentxchain.json)')}`);
+  console.log(`  ${chalk.dim('Phases:')} ${phaseNames.join(' → ')} ${chalk.dim(hasTemplateDefinedRouting(selectedTemplate) ? '(template-defined; edit routing in agentxchain.json to customize)' : '(default; extend via routing in agentxchain.json)')}`);
   console.log(`  ${chalk.dim('Template:')} ${templateId}`);
   if (config.project?.goal) {
     console.log(`  ${chalk.dim('Goal:')} ${config.project.goal}`);
   }
-  console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
+  console.log(`  ${chalk.dim('Dev runtime:')} ${formatRuntimeSummary(devRuntimeId, devRuntime)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);
   console.log('');
 
@@ -962,6 +975,7 @@ async function initGoverned(opts) {
     console.log('');
   } else if (Object.entries(config.roles).every(([, role]) => allRuntimes[role.runtime]?.type === 'manual')) {
     console.log(`  ${chalk.green('Ready:')} manual-only scaffold (${chalk.bold('no API keys')} and ${chalk.bold('no local coding CLI')} required).`);
+    console.log(`  ${chalk.green('  ')}Use ${chalk.bold('agentxchain step')} for the first governed turn; ${chalk.bold('run')} requires automatable runtimes.`);
     console.log('');
   }
 
@@ -974,7 +988,13 @@ 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')}`);
+  if (hasLiveConnectorProbe) {
+    console.log(`    ${chalk.bold('agentxchain connector check')} ${chalk.dim('# live-probe configured runtimes before the first turn')}`);
+    const firstNonManualRtId = Object.entries(config.runtimes || {}).find(([, rt]) => rt?.type && rt.type !== 'manual')?.[0];
+    if (firstNonManualRtId) {
+      console.log(`    ${chalk.bold(`agentxchain connector validate ${firstNonManualRtId}`)} ${chalk.dim('# prove the runtime produces valid governed turn results')}`);
+    }
+  }
   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/intake-start.js

@@ -17,6 +17,7 @@ export async function intakeStartCommand(opts) {
 
   const result = startIntent(root, opts.intent, {
     role: opts.role || undefined,
+    allowTerminalRestart: opts.restartCompleted === true,
   });
 
   if (opts.json) {

package/src/lib/adapters/manual-adapter.js

@@ -32,6 +32,10 @@ export function printManualDispatchInstructions(state, config, options = {}) {
   const stagingPath = getTurnStagingResultPath(turn.turn_id);
   const phase = state.phase || 'planning';
   const roleId = turn.assigned_role;
+  const artifactType = getDefaultArtifactType(role);
+  const verificationExample = getVerificationExample(phase, config, role);
+  const phaseTransitionExample = getDefaultPhaseTransitionRequest(phase, config);
+  const runCompletionExample = getDefaultRunCompletionRequest(phase, config);
 
   const lines = [];
   lines.push('');
@@ -64,6 +68,15 @@ export function printManualDispatchInstructions(state, config, options = {}) {
     lines.push('');
   }
 
+  const completionHints = getPhaseCompletionHints(phase, role, config);
+  if (completionHints.length > 0) {
+    lines.push('  To exit this phase cleanly:');
+    for (const hint of completionHints) {
+      lines.push(`    - ${hint}`);
+    }
+    lines.push('');
+  }
+
   // Minimal turn-result example
   lines.push('  Minimal turn-result.json:');
   lines.push('  {');
@@ -71,17 +84,17 @@ export function printManualDispatchInstructions(state, config, options = {}) {
   lines.push(`    "run_id": "${state.run_id || 'run_...'}",`);
   lines.push(`    "turn_id": "${turn.turn_id}",`);
   lines.push(`    "role": "${roleId}",`);
-  lines.push(`    "runtime_id": "${role?.runtime || 'manual'}",`);
+  lines.push(`    "runtime_id": "${turn.runtime_id || role?.runtime_id || role?.runtime || 'manual'}",`);
   lines.push('    "status": "completed",');
   lines.push('    "summary": "...",');
   lines.push('    "decisions": [{"id":"DEC-001","category":"scope","statement":"...","rationale":"..."}],');
   lines.push('    "objections": [{"id":"OBJ-001","severity":"medium","statement":"...","status":"raised"}],');
   lines.push('    "files_changed": [],');
-  lines.push('    "verification": {"status":"skipped","commands":[],"evidence_summary":"..."},');
-  lines.push('    "artifact": {"type":"review","ref":null},');
-  lines.push(`    "proposed_next_role": "${getDefaultNextRole(roleId, config)}",`);
-  lines.push('    "phase_transition_request": null,');
-  lines.push('    "run_completion_request": null');
+  lines.push(`    "verification": ${verificationExample},`);
+  lines.push(`    "artifact": {"type":"${artifactType}","ref":null},`);
+  lines.push(`    "proposed_next_role": "${getDefaultNextRole(roleId, config, phase)}",`);
+  lines.push(`    "phase_transition_request": ${phaseTransitionExample === null ? 'null' : `"${phaseTransitionExample}"`},`);
+  lines.push(`    "run_completion_request": ${runCompletionExample === null ? 'null' : runCompletionExample}`);
   lines.push('  }');
   lines.push('');
   lines.push('  Docs: https://agentxchain.dev/docs/getting-started');
@@ -112,11 +125,48 @@ function getPhaseGateHints(phase, roleId, config) {
   return hints;
 }
 
+function getPhaseCompletionHints(phase, role, config) {
+  const hints = [];
+  const writeAuthority = role?.write_authority || 'review_only';
+  const nextPhase = getNextPhase(phase, config);
+  const exitGate = config?.routing?.[phase]?.exit_gate;
+  const gateConfig = exitGate ? config?.gates?.[exitGate] : null;
+
+  if (gateConfig?.requires_verification_pass && writeAuthority !== 'review_only') {
+    hints.push('set `verification.status` to `pass` only when your listed checks actually passed');
+  }
+  if (writeAuthority === 'authoritative') {
+    hints.push('use `artifact.type: "workspace"` unless you created a real git commit during the turn');
+  } else if (writeAuthority === 'proposed') {
+    hints.push('use `artifact.type: "patch"` for non-completion turns');
+  } else {
+    hints.push('keep `artifact.type: "review"` because review-only roles cannot claim code-writing artifacts');
+  }
+  if (nextPhase) {
+    hints.push(`set \`phase_transition_request\` to \`${nextPhase}\` when this turn is ready to leave \`${phase}\``);
+  } else if (phase === 'qa') {
+    hints.push('set `run_completion_request` to `true` when QA evidence is complete and you are asking to end the run');
+  }
+
+  return hints;
+}
+
 /**
  * Suggest a reasonable next role based on current role.
  */
-function getDefaultNextRole(roleId, config) {
+function getDefaultNextRole(roleId, config, phase) {
   const routing = config.routing || {};
+  // Check phase-specific allowed_next first
+  const phaseAllowed = routing[phase]?.allowed_next_roles || routing[phase]?.allowed_next;
+  if (phase && phaseAllowed?.length > 0) {
+    const allowed = phaseAllowed;
+    // If the current role is in the allowlist, suggest it (another turn in same phase)
+    if (allowed.includes(roleId)) return roleId;
+    // Otherwise suggest the first non-human allowed role
+    const nonHuman = allowed.find(r => r !== 'human');
+    if (nonHuman) return nonHuman;
+    return allowed[0];
+  }
   if (routing[roleId]?.default_next) return routing[roleId].default_next;
   if (roleId === 'pm') return 'dev';
   if (roleId === 'dev') return 'qa';
@@ -124,6 +174,46 @@ function getDefaultNextRole(roleId, config) {
   return 'human';
 }
 
+function getDefaultArtifactType(role) {
+  const writeAuthority = role?.write_authority || 'review_only';
+  if (writeAuthority === 'authoritative') return 'workspace';
+  if (writeAuthority === 'proposed') return 'patch';
+  return 'review';
+}
+
+function getVerificationExample(phase, config, role) {
+  const writeAuthority = role?.write_authority || 'review_only';
+  const exitGate = config?.routing?.[phase]?.exit_gate;
+  const gateConfig = exitGate ? config?.gates?.[exitGate] : null;
+  if (gateConfig?.requires_verification_pass && writeAuthority !== 'review_only') {
+    return '{"status":"pass","commands":["..."],"evidence_summary":"..."}';
+  }
+  return '{"status":"skipped","commands":[],"evidence_summary":"..."}';
+}
+
+function getDefaultPhaseTransitionRequest(phase, config) {
+  return getNextPhase(phase, config);
+}
+
+function getDefaultRunCompletionRequest(phase, config) {
+  const nextPhase = getNextPhase(phase, config);
+  if (!nextPhase && phase === 'qa') {
+    return 'true';
+  }
+  return null;
+}
+
+function getNextPhase(phase, config) {
+  const orderedPhases = Array.isArray(config?.phases) && config.phases.length > 0
+    ? config.phases.map((entry) => typeof entry === 'string' ? entry : entry?.id).filter(Boolean)
+    : Object.keys(config?.routing || {});
+  const index = orderedPhases.indexOf(phase);
+  if (index === -1 || index === orderedPhases.length - 1) {
+    return null;
+  }
+  return orderedPhases[index + 1];
+}
+
 /**
  * Wait for the staged turn result file to appear.
  *

package/src/lib/connector-validate.js

@@ -0,0 +1,504 @@
+import { execFileSync } from 'node:child_process';
+import {
+  cpSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readlinkSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+import { loadProjectContext } from './config.js';
+import { writeDispatchBundle } from './dispatch-bundle.js';
+import { getActiveTurn, initializeGovernedRun, assignGovernedTurn, readTurnCostUsd } from './governed-state.js';
+import { dispatchApiProxy } from './adapters/api-proxy-adapter.js';
+import { dispatchLocalCli, saveDispatchLogs } from './adapters/local-cli-adapter.js';
+import { dispatchMcp } from './adapters/mcp-adapter.js';
+import { dispatchRemoteAgent } from './adapters/remote-agent-adapter.js';
+import { getDispatchPromptPath, getTurnStagingResultPath } from './turn-paths.js';
+import { validateStagedTurnResult } from './turn-result-validator.js';
+
+const VALIDATABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
+const DEFAULT_VALIDATE_TIMEOUT_MS = 120_000;
+
+export async function validateConfiguredConnector(sourceRoot, options = {}) {
+  const sourceContext = loadProjectContext(sourceRoot);
+  if (!sourceContext) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'No governed agentxchain.json found.',
+    };
+  }
+
+  if (sourceContext.config.protocol_mode !== 'governed') {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'connector validate only supports governed projects.',
+    };
+  }
+
+  const runtimeId = typeof options.runtimeId === 'string' ? options.runtimeId.trim() : '';
+  if (!runtimeId) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'Runtime id is required. Usage: agentxchain connector validate <runtime_id>',
+    };
+  }
+
+  const timeoutMs = Number.parseInt(options.timeoutMs ?? DEFAULT_VALIDATE_TIMEOUT_MS, 10);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'Timeout must be a positive integer.',
+    };
+  }
+
+  const runtime = sourceContext.config.runtimes?.[runtimeId];
+  if (!runtime) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: `Unknown connector runtime "${runtimeId}"`,
+    };
+  }
+  if (runtime.type === 'manual') {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: `Runtime "${runtimeId}" is manual. connector validate only supports automated runtimes.`,
+    };
+  }
+  if (!VALIDATABLE_RUNTIME_TYPES.has(runtime.type)) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: `Runtime "${runtimeId}" of type "${runtime.type}" cannot be validated by connector validate.`,
+    };
+  }
+
+  const roleSelection = resolveValidationRole(sourceContext.config, runtimeId, options.roleId);
+  if (!roleSelection.ok) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: roleSelection.error,
+    };
+  }
+
+  const tempBase = mkdtempSync(join(tmpdir(), 'axc-connector-validate-'));
+  const scratchRoot = join(tempBase, 'workspace');
+  const warnings = [...roleSelection.warnings];
+  let keepArtifacts = options.keepArtifacts === true;
+  let dispatch = null;
+  let validation = null;
+  let costUsd = null;
+
+  try {
+    copyRepoForValidation(sourceRoot, scratchRoot);
+    initializeScratchGit(scratchRoot);
+
+    const scratchContext = loadProjectContext(scratchRoot);
+    if (!scratchContext) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: 'Failed to load governed config inside scratch workspace.',
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const initResult = initializeGovernedRun(scratchRoot, scratchContext.config, {
+      provenance: {
+        trigger: 'connector_validate',
+        runtime_id: runtimeId,
+        role_id: roleSelection.roleId,
+      },
+    });
+    if (!initResult.ok) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: initResult.error,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const assignResult = assignGovernedTurn(scratchRoot, scratchContext.config, roleSelection.roleId);
+    if (!assignResult.ok) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: assignResult.error,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const state = assignResult.state;
+    const turn = getActiveTurn(state);
+    if (!turn) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: 'Synthetic validation turn was not assigned.',
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const bundleResult = writeDispatchBundle(scratchRoot, state, scratchContext.config, { turnId: turn.turn_id });
+    if (!bundleResult.ok) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: bundleResult.error,
+        scratch_root: scratchRoot,
+      };
+    }
+    if (Array.isArray(bundleResult.warnings)) {
+      warnings.push(...bundleResult.warnings);
+    }
+
+    appendValidationPrompt(scratchRoot, scratchContext.config, state, turn);
+    configureRuntimeValidationTimeout(scratchContext.config, runtimeId, timeoutMs);
+
+    const signal = AbortSignal.timeout(timeoutMs);
+    const adapterResult = await dispatchValidationTurn(
+      scratchRoot,
+      state,
+      scratchContext.config,
+      runtimeId,
+      { turnId: turn.turn_id, signal },
+    );
+
+    dispatch = {
+      ok: adapterResult.ok,
+      error: adapterResult.error || null,
+      timed_out: adapterResult.timedOut === true,
+      aborted: adapterResult.aborted === true,
+      log_count: Array.isArray(adapterResult.logs) ? adapterResult.logs.length : 0,
+    };
+
+    if (Array.isArray(adapterResult.logs) && adapterResult.logs.length > 0) {
+      saveDispatchLogs(scratchRoot, turn.turn_id, adapterResult.logs);
+    }
+
+    if (!adapterResult.ok) {
+      keepArtifacts = true;
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        dispatch,
+        validation: null,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    validation = validateStagedTurnResult(scratchRoot, state, scratchContext.config, {
+      stagingPath: getTurnStagingResultPath(turn.turn_id),
+    });
+    costUsd = validation?.turnResult ? readTurnCostUsd(validation.turnResult) : null;
+
+    if (!validation.ok) {
+      keepArtifacts = true;
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        dispatch,
+        validation: {
+          ok: false,
+          stage: validation.stage,
+          error_class: validation.error_class,
+          errors: validation.errors,
+          warnings: validation.warnings,
+        },
+        cost_usd: costUsd,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    return {
+      ok: true,
+      exitCode: 0,
+      overall: 'pass',
+      runtime_id: runtimeId,
+      runtime_type: runtime.type,
+      role_id: roleSelection.roleId,
+      timeout_ms: timeoutMs,
+      warnings,
+      dispatch,
+      validation: {
+        ok: true,
+        stage: null,
+        error_class: null,
+        errors: [],
+        warnings: validation.warnings,
+      },
+      cost_usd: costUsd,
+      scratch_root: keepArtifacts ? scratchRoot : null,
+    };
+  } catch (error) {
+    keepArtifacts = true;
+    return {
+      ok: false,
+      exitCode: 1,
+      overall: 'fail',
+      runtime_id: runtimeId,
+      runtime_type: runtime.type,
+      role_id: roleSelection.roleId,
+      timeout_ms: timeoutMs,
+      warnings,
+      dispatch,
+      validation,
+      error: error.message,
+      scratch_root: scratchRoot,
+    };
+  } finally {
+    if (!keepArtifacts) {
+      try {
+        rmSync(tempBase, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+}
+
+function resolveValidationRole(config, runtimeId, requestedRoleId) {
+  const matchingRoles = Object.entries(config.roles || {})
+    .filter(([, role]) => (role.runtime_id || role.runtime) === runtimeId)
+    .map(([roleId]) => roleId)
+    .sort((a, b) => a.localeCompare(b, 'en'));
+
+  if (matchingRoles.length === 0) {
+    return { ok: false, error: `No roles are bound to runtime "${runtimeId}".` };
+  }
+
+  if (requestedRoleId) {
+    if (!config.roles?.[requestedRoleId]) {
+      return { ok: false, error: `Unknown role "${requestedRoleId}".` };
+    }
+    const boundRuntimeId = config.roles[requestedRoleId].runtime_id || config.roles[requestedRoleId].runtime;
+    if (boundRuntimeId !== runtimeId) {
+      return {
+        ok: false,
+        error: `Role "${requestedRoleId}" is not bound to runtime "${runtimeId}".`,
+      };
+    }
+    return { ok: true, roleId: requestedRoleId, warnings: [] };
+  }
+
+  const warnings = [];
+  if (matchingRoles.length > 1) {
+    warnings.push(
+      `Runtime "${runtimeId}" is shared by multiple roles (${matchingRoles.join(', ')}). ` +
+      `Validated the first binding "${matchingRoles[0]}". Use --role to target another binding.`,
+    );
+  }
+
+  return {
+    ok: true,
+    roleId: matchingRoles[0],
+    warnings,
+  };
+}
+
+function copyRepoForValidation(sourceRoot, scratchRoot) {
+  mkdirSync(scratchRoot, { recursive: true });
+  copyTree(sourceRoot, scratchRoot);
+}
+
+function copyTree(sourcePath, destPath) {
+  mkdirSync(destPath, { recursive: true });
+  for (const entry of readdirSync(sourcePath, { withFileTypes: true })) {
+    if (entry.name === '.git' || entry.name === '.agentxchain') {
+      continue;
+    }
+
+    const sourceEntry = join(sourcePath, entry.name);
+    const destEntry = join(destPath, entry.name);
+    const stats = lstatSync(sourceEntry);
+
+    if (stats.isSymbolicLink()) {
+      symlinkSync(readlinkSync(sourceEntry), destEntry);
+      continue;
+    }
+
+    if (stats.isDirectory()) {
+      if (entry.name === 'node_modules') {
+        symlinkSync(sourceEntry, destEntry, 'dir');
+        continue;
+      }
+      copyTree(sourceEntry, destEntry);
+      continue;
+    }
+
+    mkdirSync(dirname(destEntry), { recursive: true });
+    cpSync(sourceEntry, destEntry, { force: true, preserveTimestamps: true });
+  }
+}
+
+function initializeScratchGit(root) {
+  execFileSync('git', ['init', '-q'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['checkout', '-q', '-b', 'main'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['add', '-A'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['commit', '-q', '-m', 'connector validation baseline'], {
+    cwd: root,
+    stdio: 'ignore',
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'AgentXchain Validator',
+      GIT_AUTHOR_EMAIL: 'noreply@agentxchain.dev',
+      GIT_COMMITTER_NAME: 'AgentXchain Validator',
+      GIT_COMMITTER_EMAIL: 'noreply@agentxchain.dev',
+    },
+  });
+}
+
+function appendValidationPrompt(root, config, state, turn) {
+  const promptPath = join(root, getDispatchPromptPath(turn.turn_id));
+  const role = config.roles?.[turn.assigned_role];
+  const reviewOnly = role?.write_authority === 'review_only';
+  const validationTurn = {
+    schema_version: '1.0',
+    run_id: state.run_id,
+    turn_id: turn.turn_id,
+    role: turn.assigned_role,
+    runtime_id: turn.runtime_id,
+    status: 'completed',
+    summary: 'Connector validation synthetic turn completed without modifying product files.',
+    decisions: [
+      {
+        id: 'DEC-900',
+        category: 'process',
+        statement: 'The runtime emitted a schema-valid connector validation result.',
+        rationale: 'Synthetic dispatch completed and staged a governed turn result.',
+      },
+    ],
+    objections: reviewOnly ? [
+      {
+        id: 'OBJ-900',
+        severity: 'low',
+        statement: 'Validation objection: this is a synthetic proof turn, not delivery work.',
+        status: 'acknowledged',
+      },
+    ] : [],
+    files_changed: [],
+    verification: {
+      status: 'skipped',
+      evidence_summary: 'Synthetic connector validation turn; no repo work requested.',
+    },
+    artifact: {
+      type: 'review',
+      ref: null,
+    },
+    proposed_next_role: 'human',
+  };
+
+  const lines = [
+    '',
+    '## Connector Validation Override',
+    '',
+    'This dispatch is a connector-validation proof turn, not real product work.',
+    '',
+    'You must follow these extra constraints:',
+    '',
+    '1. Do not edit any product files.',
+    '2. Write exactly one governed turn result to the staged result path already provided in ASSIGNMENT.json.',
+    '3. Use `files_changed: []` and `artifact.type: "review"`.',
+    '4. Do not request a phase transition or run completion.',
+    '5. Set `proposed_next_role: "human"`.',
+    reviewOnly ? '6. Include at least one objection because this role is review_only.' : '6. Objections may be empty because this role is not review_only.',
+    '',
+    'Use this JSON shape as your starting point and replace nothing except if you need equivalent wording:',
+    '',
+    '```json',
+    JSON.stringify(validationTurn, null, 2),
+    '```',
+    '',
+  ];
+
+  writeFileSync(promptPath, lines.join('\n'), { flag: 'a' });
+}
+
+function configureRuntimeValidationTimeout(config, runtimeId, timeoutMs) {
+  if (config?.runtimes?.[runtimeId] && config.runtimes[runtimeId].type === 'remote_agent') {
+    config.runtimes[runtimeId] = {
+      ...config.runtimes[runtimeId],
+      timeout_ms: timeoutMs,
+    };
+  }
+}
+
+async function dispatchValidationTurn(root, state, config, runtimeId, options = {}) {
+  const runtime = config.runtimes?.[runtimeId];
+  switch (runtime?.type) {
+    case 'local_cli':
+      return dispatchLocalCli(root, state, config, options);
+    case 'api_proxy':
+      return dispatchApiProxy(root, state, config, options);
+    case 'mcp':
+      return dispatchMcp(root, state, config, options);
+    case 'remote_agent':
+      return dispatchRemoteAgent(root, state, config, options);
+    default:
+      return { ok: false, error: `Unsupported runtime type "${runtime?.type || 'unknown'}"` };
+  }
+}
+
+export { DEFAULT_VALIDATE_TIMEOUT_MS, VALIDATABLE_RUNTIME_TYPES };

package/src/lib/intake.js

@@ -711,9 +711,10 @@ export function startIntent(root, intentId, options = {}) {
   }
 
   if (state.status === 'completed' && !allowCompletedRestart) {
+    const restartCmd = `agentxchain intake start --intent ${intent.intent_id} --restart-completed`;
     return {
       ok: false,
-      error: 'cannot start: governed run is already completed. Use "agentxchain init --force" to start a new run.',
+      error: `cannot start: governed run is already completed. Re-run with "${restartCmd}" to initialize a fresh governed run.`,
       exitCode: 1,
     };
   }

package/src/lib/turn-result-validator.js

@@ -513,6 +513,20 @@ function validateArtifact(tr, config) {
     }
   }
 
+  // Authoritative roles with product-file changes must not claim artifact.type "review".
+  // "review" signals observation-only, but non-empty product files_changed means the actor
+  // wrote to the repo.  Allowing the mismatch makes accepted_integration_ref look clean
+  // when the workspace is actually dirty — hiding state from the next authoritative turn.
+  if (writeAuthority === 'authoritative' && tr.artifact?.type === 'review') {
+    const productFiles = (tr.files_changed || []).filter(f => !isAllowedReviewPath(f));
+    if (productFiles.length > 0) {
+      errors.push(
+        `Role "${tr.role}" has authoritative write authority and changed product files (${productFiles.join(', ')}), but artifact type is "review". ` +
+        'Use "workspace" or "commit" when product files are modified.'
+      );
+    }
+  }
+
   // Warn if files_changed is empty for authoritative + completed turns
   if (writeAuthority === 'authoritative' && tr.status === 'completed' && (tr.files_changed || []).length === 0) {
     warnings.push('Authoritative role completed with no files_changed — is this intentional?');