agentxchain 2.122.0 → 2.124.0

package/bin/agentxchain.js

@@ -675,6 +675,7 @@ program
   .option('--vision <path>', 'Path to VISION.md (project-relative or absolute, default: .planning/VISION.md)')
   .option('--max-runs <n>', 'Maximum consecutive governed runs in continuous mode (default: 100)', parseInt)
   .option('--poll-seconds <n>', 'Seconds between idle-detection cycles in continuous mode (default: 30)', parseInt)
+  .option('--triage-approval <mode>', 'Triage policy for vision-derived intents: auto or human (default: config or auto)')
   .option('--max-idle-cycles <n>', 'Stop after N consecutive idle cycles with no derivable work (default: 3)', parseInt)
   .option('--session-budget <usd>', 'Cumulative session-level budget cap in USD for continuous mode', parseFloat)
   .action(runCommand);
@@ -917,6 +918,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.122.0",
+  "version": "2.124.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/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,9 @@ 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')}`);
+  }
   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/continuous-run.js

@@ -86,6 +86,13 @@ function describeContinuousTerminalStep(step, contOpts) {
   if (step.status === 'idle_exit') {
     return `All vision goals appear addressed (${contOpts.maxIdleCycles} consecutive idle cycles). Stopping.`;
   }
+  if (step.status === 'failed') {
+    const reason = step.stop_reason || step.action || 'unknown';
+    return `Continuous loop failed: ${reason}. Check "agentxchain status" for details.`;
+  }
+  if (step.status === 'blocked') {
+    return 'Continuous loop paused on blocker. Use "agentxchain unblock <id>" to resume.';
+  }
   return null;
 }
 
@@ -304,7 +311,7 @@ export function resolveContinuousOptions(opts, config) {
     maxRuns: opts.maxRuns ?? configCont.max_runs ?? 100,
     pollSeconds: opts.pollSeconds ?? configCont.poll_seconds ?? 30,
     maxIdleCycles: opts.maxIdleCycles ?? configCont.max_idle_cycles ?? 3,
-    triageApproval: configCont.triage_approval ?? 'auto',
+    triageApproval: opts.triageApproval ?? configCont.triage_approval ?? 'auto',
     cooldownSeconds: opts.cooldownSeconds ?? configCont.cooldown_seconds ?? 5,
     perSessionMaxUsd: opts.sessionBudget ?? configCont.per_session_max_usd ?? null,
   };

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. S3 does not reopen completed runs.',
+      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?');