agentxchain 2.104.0 → 2.105.0

package/src/commands/role.js

@@ -1,5 +1,9 @@
 import chalk from 'chalk';
 import { loadProjectContext } from '../lib/config.js';
+import {
+  getRoleRuntimeCapabilityContract,
+  summarizeRuntimeCapabilityContract,
+} from '../lib/runtime-capabilities.js';
 
 export function roleCommand(subcommand, roleId, opts) {
   const context = loadProjectContext();
@@ -8,25 +12,26 @@ export function roleCommand(subcommand, roleId, opts) {
     process.exit(1);
   }
 
-  const { rawConfig, version } = context;
+  const { config, version } = context;
 
   if (version !== 4) {
     console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
     process.exit(1);
   }
 
-  const roles = rawConfig.roles || {};
+  const roles = config.roles || {};
+  const runtimes = config.runtimes || {};
   const roleIds = Object.keys(roles);
 
   if (subcommand === 'show') {
-    return showRole(roleId, roles, roleIds, opts);
+    return showRole(roleId, roles, runtimes, roleIds, opts);
   }
 
   // Default: list
-  return listRoles(roles, roleIds, opts);
+  return listRoles(roles, runtimes, roleIds, opts);
 }
 
-function listRoles(roles, roleIds, opts) {
+function listRoles(roles, runtimes, roleIds, opts) {
   if (roleIds.length === 0) {
     if (opts.json) {
       console.log('[]');
@@ -38,14 +43,17 @@ function listRoles(roles, roleIds, opts) {
 
   if (opts.json) {
     const output = roleIds.map((id) => {
+      const runtimeId = roles[id].runtime_id;
+      const runtime = runtimes[runtimeId];
       const entry = {
         id,
         title: roles[id].title,
         mandate: roles[id].mandate,
         write_authority: roles[id].write_authority,
-        runtime: roles[id].runtime,
+        runtime: runtimeId,
+        runtime_contract: runtime ? getRoleRuntimeCapabilityContract(id, roles[id], runtime).runtime_contract : null,
       };
-      if (typeof roles[id].decision_authority === 'number') {
+      if (typeof roles[id]?.decision_authority === 'number') {
         entry.decision_authority = roles[id].decision_authority;
       }
       return entry;
@@ -57,19 +65,22 @@ function listRoles(roles, roleIds, opts) {
   console.log(chalk.bold(`\n  Roles (${roleIds.length}):\n`));
   for (const id of roleIds) {
     const r = roles[id];
+    const runtime = runtimes[r.runtime_id];
+    const contract = runtime ? getRoleRuntimeCapabilityContract(id, r, runtime) : null;
     const authority = r.write_authority === 'authoritative'
       ? chalk.green(r.write_authority)
       : r.write_authority === 'proposed'
         ? chalk.yellow(r.write_authority)
         : chalk.dim(r.write_authority);
-    const decAuth = typeof r.decision_authority === 'number' ? chalk.dim(` dec:${r.decision_authority}`) : '';
-    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}${decAuth}] → ${chalk.dim(r.runtime)}`);
+    const decAuth = typeof r?.decision_authority === 'number' ? chalk.dim(` dec:${r.decision_authority}`) : '';
+    const capabilitySuffix = contract ? chalk.dim(` {${summarizeRuntimeCapabilityContract(contract.runtime_contract)}}`) : '';
+    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}${decAuth}] → ${chalk.dim(r.runtime_id)}${capabilitySuffix}`);
   }
   console.log('');
   console.log(chalk.dim('  Usage: agentxchain role show <role_id>\n'));
 }
 
-function showRole(roleId, roles, roleIds, opts) {
+function showRole(roleId, roles, runtimes, roleIds, opts) {
   if (!roleId) {
     console.log(chalk.red('  Missing role ID.'));
     console.log(chalk.dim(`  Usage: agentxchain role show <role_id>`));
@@ -86,6 +97,8 @@ function showRole(roleId, roles, roleIds, opts) {
   }
 
   const r = roles[roleId];
+  const runtime = runtimes[r.runtime_id];
+  const capability = runtime ? getRoleRuntimeCapabilityContract(roleId, r, runtime) : null;
 
   if (opts.json) {
     const entry = {
@@ -93,9 +106,19 @@ function showRole(roleId, roles, roleIds, opts) {
       title: r.title,
       mandate: r.mandate,
       write_authority: r.write_authority,
-      runtime: r.runtime,
+      runtime: r.runtime_id,
+      runtime_contract: capability?.runtime_contract || null,
+      effective_runtime_contract: capability
+        ? {
+            role_id: capability.role_id,
+            role_write_authority: capability.role_write_authority,
+            effective_write_path: capability.effective_write_path,
+            workflow_artifact_ownership: capability.workflow_artifact_ownership,
+            notes: capability.notes,
+          }
+        : null,
     };
-    if (typeof r.decision_authority === 'number') {
+    if (typeof r?.decision_authority === 'number') {
       entry.decision_authority = r.decision_authority;
     }
     console.log(JSON.stringify(entry, null, 2));
@@ -112,9 +135,23 @@ function showRole(roleId, roles, roleIds, opts) {
   console.log(`  Title:      ${r.title}`);
   console.log(`  Mandate:    ${r.mandate}`);
   console.log(`  Authority:  ${authority}`);
-  if (typeof r.decision_authority === 'number') {
+  if (typeof r?.decision_authority === 'number') {
     console.log(`  Decision:   ${r.decision_authority}`);
   }
-  console.log(`  Runtime:    ${chalk.dim(r.runtime)}`);
+  console.log(`  Runtime:    ${chalk.dim(r.runtime_id)}`);
+  if (capability) {
+    const base = capability.runtime_contract;
+    console.log(`  Transport:  ${base.transport}`);
+    console.log(`  Writes:     ${base.can_write_files}`);
+    console.log(`  Review:     ${base.review_only_behavior}`);
+    console.log(`  Proposals:  ${base.proposal_support}`);
+    console.log(`  Binary:     ${base.requires_local_binary ? 'yes' : 'no'}`);
+    console.log(`  owned_by:   ${base.workflow_artifact_ownership}`);
+    console.log(`  Effective:  ${capability.effective_write_path}`);
+    console.log(`  Ownership:  ${capability.workflow_artifact_ownership}`);
+    for (const note of capability.notes) {
+      console.log(`  Note:       ${note}`);
+    }
+  }
   console.log('');
 }

package/src/commands/run.js

@@ -35,6 +35,7 @@ import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import { resolveGovernedRole } from '../lib/role-resolution.js';
 import { buildInheritedContext } from '../lib/run-context-inheritance.js';
+import { shouldSuggestManualQaFallback } from '../lib/manual-qa-fallback.js';
 import {
   getDispatchAssignmentPath,
   getDispatchContextPath,
@@ -56,7 +57,7 @@ export async function runCommand(opts) {
 }
 
 export async function executeGovernedRun(context, opts = {}) {
-  const { root, config, rawConfig } = context;
+  const { root, config } = context;
   const log = opts.log || console.log;
 
   if (config.protocol_mode !== 'governed') {
@@ -315,11 +316,11 @@ export async function executeGovernedRun(context, opts = {}) {
 
       // Adapter failure
       if (!adapterResult.ok) {
-        if (shouldPrintManualQaFallback({
+        if (shouldSuggestManualQaFallback({
           roleId,
           runtimeId,
           classified: adapterResult.classified,
-          rawConfig,
+          config: cfg,
         })) {
           qaMissingCredentialsFallback = {
             roleId,
@@ -438,7 +439,7 @@ export async function executeGovernedRun(context, opts = {}) {
 
   // Recovery guidance for blocked/rejected states
   if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
-    const recovery = deriveRecoveryDescriptor(result.state);
+    const recovery = deriveRecoveryDescriptor(result.state, config);
     if (recovery) {
       log('');
       log(chalk.yellow(`  Recovery: ${recovery.typed_reason}`));
@@ -514,13 +515,6 @@ function promptUser(question) {
   });
 }
 
-function shouldPrintManualQaFallback({ roleId, runtimeId, classified, rawConfig }) {
-  return classified?.error_class === 'missing_credentials'
-    && roleId === 'qa'
-    && runtimeId === 'api-qa'
-    && rawConfig?.runtimes?.['manual-qa']?.type === 'manual';
-}
-
 function printManualQaFallback(log = console.log) {
   log('');
   log(chalk.dim('  No-key QA fallback:'));

package/src/commands/status.js

@@ -1,18 +1,26 @@
 import chalk from 'chalk';
+import { readFileSync } from 'fs';
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { loadConfig, loadLock, loadProjectContext, loadProjectState, loadState } from '../lib/config.js';
-import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { findProjectRoot, loadConfig, loadLock, loadProjectContext, loadProjectState, loadState } from '../lib/config.js';
+import {
+  deriveGovernedRunNextActions,
+  deriveRecoveryDescriptor,
+  deriveRuntimeBlockedGuidance,
+} from '../lib/blocked-state.js';
 import { getActiveTurn, getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
 import { getContinuityStatus } from '../lib/continuity-status.js';
 import { getConnectorHealth } from '../lib/connector-health.js';
+import { readRepoDecisions, summarizeRepoDecisions } from '../lib/repo-decisions.js';
 import { deriveWorkflowKitArtifacts } from '../lib/workflow-kit-artifacts.js';
 import { evaluateTimeouts } from '../lib/timeout-evaluator.js';
 import { summarizeRunProvenance } from '../lib/run-provenance.js';
+import { readRecentRunEventSummary } from '../lib/recent-event-summary.js';
+import { deriveConflictedTurnResolutionActions } from '../lib/conflict-actions.js';
 import { getDashboardPid, getDashboardSession } from './dashboard.js';
 
 export async function statusCommand(opts) {
-  const context = loadProjectContext();
+  const context = loadStatusContext();
   if (!context) {
     console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
     process.exit(1);
@@ -79,11 +87,42 @@ export async function statusCommand(opts) {
   console.log('');
 }
 
+function loadStatusContext(dir = process.cwd()) {
+  const context = loadProjectContext(dir);
+  if (context) return context;
+
+  const root = findProjectRoot(dir);
+  if (!root) return null;
+
+  let rawConfig;
+  try {
+    rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+
+  if (rawConfig?.protocol_mode !== 'governed') {
+    return null;
+  }
+
+  return {
+    root,
+    rawConfig,
+    config: rawConfig,
+    version: 4,
+  };
+}
+
 function renderGovernedStatus(context, opts) {
   const { root, config, version } = context;
   const state = loadProjectState(root, config);
   const continuity = getContinuityStatus(root, state);
   const connectorHealth = getConnectorHealth(root, config, state);
+  const recovery = deriveRecoveryDescriptor(state, config);
+  const runtimeGuidance = deriveRuntimeBlockedGuidance(state, config);
+  const nextActions = deriveGovernedRunNextActions(state, config);
+  const recentEventSummary = readRecentRunEventSummary(root);
+  const repoDecisionSummary = summarizeRepoDecisions(readRepoDecisions(root), config);
 
   const workflowKitArtifacts = deriveWorkflowKitArtifacts(root, config, state);
 
@@ -106,8 +145,13 @@ function renderGovernedStatus(context, opts) {
       provenance: state?.provenance || null,
       inherited_context: state?.inherited_context || null,
       repo_decisions: state?.repo_decisions || null,
+      repo_decision_summary: repoDecisionSummary,
       continuity,
+      recovery,
+      runtime_guidance: runtimeGuidance,
+      next_actions: nextActions,
       connector_health: connectorHealth,
+      recent_event_summary: recentEventSummary,
       workflow_kit_artifacts: workflowKitArtifacts,
       dashboard_session: dashboardSessionObj,
     }, null, 2));
@@ -134,8 +178,12 @@ function renderGovernedStatus(context, opts) {
   if (state?.inherited_context?.parent_run_id) {
     console.log(`  ${chalk.dim('Inherits:')} ${chalk.magenta(`parent ${state.inherited_context.parent_run_id} (${state.inherited_context.parent_status || 'unknown'})`)}`);
   }
-  if (state?.repo_decisions?.length > 0) {
-    console.log(`  ${chalk.dim('Repo decisions:')} ${chalk.yellow(`${state.repo_decisions.length} active`)}`);
+  if (repoDecisionSummary) {
+    console.log(`  ${chalk.dim('Repo decisions:')} ${chalk.yellow(formatRepoDecisionHeadline(repoDecisionSummary))}`);
+    const carryoverDetail = formatRepoDecisionCarryover(repoDecisionSummary);
+    if (carryoverDetail) {
+      console.log(`  ${chalk.dim('Carryover:')} ${carryoverDetail}`);
+    }
   }
   if (state?.accepted_integration_ref) {
     console.log(`  ${chalk.dim('Accepted:')} ${state.accepted_integration_ref}`);
@@ -144,6 +192,7 @@ function renderGovernedStatus(context, opts) {
 
   renderContinuityStatus(continuity, state);
   renderConnectorHealthStatus(connectorHealth);
+  renderRecentEventSummary(recentEventSummary);
 
   const activeTurnCount = getActiveTurnCount(state);
   const activeTurns = getActiveTurns(state);
@@ -171,14 +220,15 @@ function renderGovernedStatus(context, opts) {
         const cs = turn.conflict_state;
         const files = cs.conflict_error?.conflicting_files || [];
         const count = cs.detection_count || 1;
+        const [reassignAction, mergeAction] = deriveConflictedTurnResolutionActions(turn.turn_id);
         console.log(`      ${chalk.dim('Conflict:')}  ${files.length} file(s) — detection #${count}`);
         if (cs.conflict_error?.overlap_ratio != null) {
           console.log(`      ${chalk.dim('Overlap:')}   ${(cs.conflict_error.overlap_ratio * 100).toFixed(0)}%`);
         }
         const suggestion = cs.conflict_error?.suggested_resolution || 'reject_and_reassign';
         console.log(`      ${chalk.dim('Suggested:')} ${suggestion}`);
-        console.log(`      ${chalk.dim('Resolve:')}   ${chalk.cyan(`agentxchain reject-turn --turn ${turn.turn_id} --reassign`)}`);
-        console.log(`      ${chalk.dim('     or:')}   ${chalk.cyan(`agentxchain accept-turn --turn ${turn.turn_id} --resolution human_merge`)}`);
+        console.log(`      ${chalk.dim('Resolve:')}   ${chalk.cyan(reassignAction.command)}`);
+        console.log(`      ${chalk.dim('     or:')}   ${chalk.cyan(mergeAction.command)}`);
       }
     }
   } else if (singleActiveTurn) {
@@ -199,9 +249,10 @@ function renderGovernedStatus(context, opts) {
     if (singleActiveTurn.status === 'conflicted' && singleActiveTurn.conflict_state) {
       const cs = singleActiveTurn.conflict_state;
       const files = cs.conflict_error?.conflicting_files || [];
+      const [reassignAction, mergeAction] = deriveConflictedTurnResolutionActions(singleActiveTurn.turn_id);
       console.log(`  ${chalk.dim('Conflict:')} ${chalk.red(`${files.length} file(s) conflicting`)} — detection #${cs.detection_count || 1}`);
-      console.log(`  ${chalk.dim('Resolve:')}  ${chalk.cyan('agentxchain reject-turn --reassign')}`);
-      console.log(`  ${chalk.dim('     or:')}  ${chalk.cyan('agentxchain accept-turn --resolution human_merge')}`);
+      console.log(`  ${chalk.dim('Resolve:')}  ${chalk.cyan(reassignAction.command)}`);
+      console.log(`  ${chalk.dim('     or:')}  ${chalk.cyan(mergeAction.command)}`);
     }
   } else {
     console.log(`  ${chalk.dim('Turn:')}     ${chalk.yellow('No active turn')}`);
@@ -231,7 +282,6 @@ function renderGovernedStatus(context, opts) {
   if (state?.blocked_on) {
     console.log('');
     if (state.status === 'blocked') {
-      const recovery = deriveRecoveryDescriptor(state, config);
       const detail = recovery?.detail || state.blocked_on;
       console.log(`  ${chalk.dim('Blocked:')}  ${chalk.red.bold('BLOCKED')} — ${detail}`);
     } else if (state.blocked_on.startsWith('human_approval:')) {
@@ -246,7 +296,6 @@ function renderGovernedStatus(context, opts) {
     renderLastGateFailure(state.last_gate_failure, config);
   }
 
-  const recovery = deriveRecoveryDescriptor(state, config);
   if (recovery) {
     console.log('');
     console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);
@@ -258,18 +307,26 @@ function renderGovernedStatus(context, opts) {
     }
   }
 
+  if (runtimeGuidance.length > 0) {
+    console.log('');
+    console.log(`  ${chalk.dim('Runtime guidance:')}`);
+    for (const entry of runtimeGuidance) {
+      console.log(`    ${chalk.yellow('•')} ${entry.code} — ${chalk.cyan(entry.command)}`);
+      console.log(`      ${chalk.dim(`${entry.role_id} owns ${entry.artifact_path} at ${entry.phase}/${entry.gate_id}`)}`);
+      console.log(`      ${chalk.dim(entry.reason)}`);
+    }
+  }
+
   if (state?.pending_phase_transition) {
     const pt = state.pending_phase_transition;
     console.log(`  ${chalk.dim('Pending:')}  ${formatGovernedPhase(pt.from)} → ${formatGovernedPhase(pt.to)}`);
     console.log(`  ${chalk.dim('Gate:')}     ${pt.gate} (requires human approval)`);
-    console.log(`  ${chalk.dim('Action:')}   Run ${chalk.cyan('agentxchain approve-transition')} to advance`);
   }
 
   if (state?.pending_run_completion) {
     const pc = state.pending_run_completion;
     console.log(`  ${chalk.dim('Pending:')}  ${chalk.bold('Run Completion')}`);
     console.log(`  ${chalk.dim('Gate:')}     ${pc.gate} (requires human approval)`);
-    console.log(`  ${chalk.dim('Action:')}   Run ${chalk.cyan('agentxchain approve-completion')} to finalize`);
   }
 
   if (state?.status === 'completed') {
@@ -459,6 +516,81 @@ function renderWorkflowKitArtifactsSection(wkData) {
   }
 }
 
+function renderRecentEventSummary(summary) {
+  if (!summary) return;
+
+  const label = summary.freshness === 'recent'
+    ? chalk.green('recent')
+    : summary.freshness === 'quiet'
+      ? chalk.yellow('quiet')
+      : summary.freshness === 'unknown'
+        ? chalk.yellow('unknown timing')
+        : chalk.dim('none recorded');
+  const countLabel = summary.freshness === 'no_events'
+    ? null
+    : `${summary.recent_count || 0} in last ${summary.window_minutes || 15}m`;
+
+  console.log(`  ${chalk.dim('Recent events:')} ${label}${countLabel ? chalk.dim(` (${countLabel})`) : ''}`);
+  if (summary.latest_event) {
+    console.log(`  ${chalk.dim('Latest:')}   ${summary.latest_event.summary || summary.latest_event.event_type || 'unknown_event'}`);
+    console.log(`  ${chalk.dim('When:')}     ${summary.latest_event.timestamp || 'unknown'}`);
+  }
+  console.log('');
+}
+
+function formatRepoDecisionHeadline(summary) {
+  if (!summary) return 'none';
+  const parts = [`${summary.active_count} active`];
+  if (summary.overridden_count > 0) {
+    parts.push(`${summary.overridden_count} overridden`);
+  }
+  return parts.join(', ');
+}
+
+function formatRepoDecisionCarryover(summary) {
+  if (!summary?.operator_summary) {
+    return '';
+  }
+
+  const { operator_summary: operatorSummary, active_count: activeCount } = summary;
+  const parts = [];
+
+  if (activeCount === 0) {
+    parts.push('no active cross-run constraints remain');
+  } else if (Array.isArray(operatorSummary.active_categories) && operatorSummary.active_categories.length > 0) {
+    parts.push(`categories: ${operatorSummary.active_categories.join(', ')}`);
+  }
+
+  if (typeof operatorSummary.highest_active_authority_level === 'number') {
+    const roleLabel = operatorSummary.highest_active_authority_role
+      ? ` (${operatorSummary.highest_active_authority_role})`
+      : '';
+    parts.push(`highest authority: ${operatorSummary.highest_active_authority_level}${roleLabel}`);
+  }
+
+  if (operatorSummary.superseding_active_count > 0) {
+    parts.push(pluralizeRepoDecisionCount(
+      operatorSummary.superseding_active_count,
+      'active superseding earlier decision',
+      'active superseding earlier decisions',
+    ));
+  }
+
+  if (operatorSummary.overridden_with_successor_count > 0) {
+    parts.push(pluralizeRepoDecisionCount(
+      operatorSummary.overridden_with_successor_count,
+      'overridden with recorded successor',
+      'overridden with recorded successors',
+    ));
+  }
+
+  return parts.join('; ');
+}
+
+function pluralizeRepoDecisionCount(count, singular, plural) {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
 function renderLastGateFailure(failure, config) {
   const entryRole = config?.routing?.[failure.phase]?.entry_role || null;
   const suggestedCommand = entryRole ? `agentxchain step --role ${entryRole}` : 'agentxchain step --role <role>';

package/src/commands/step.js

@@ -62,9 +62,11 @@ import {
 } from '../lib/turn-paths.js';
 import { dispatchApiProxy } from '../lib/adapters/api-proxy-adapter.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { deriveConflictedTurnResolutionActions } from '../lib/conflict-actions.js';
 import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest, verifyDispatchManifest } from '../lib/dispatch-manifest.js';
 import { resolveGovernedRole } from '../lib/role-resolution.js';
+import { shouldSuggestManualQaFallback } from '../lib/manual-qa-fallback.js';
 
 export async function stepCommand(opts) {
   const context = loadProjectContext();
@@ -73,7 +75,7 @@ export async function stepCommand(opts) {
     process.exit(1);
   }
 
-  const { root, config, rawConfig } = context;
+  const { root, config } = context;
 
   if (config.protocol_mode !== 'governed') {
     console.log(chalk.red('The step command is only available for governed projects.'));
@@ -132,11 +134,12 @@ export async function stepCommand(opts) {
 
       // If the target turn is conflicted, print recovery paths instead of resuming
       if (targetTurn.status === 'conflicted') {
+        const [reassignAction, mergeAction] = deriveConflictedTurnResolutionActions(targetTurn.turn_id);
         console.log(chalk.yellow(`Turn ${targetTurn.turn_id} is conflicted. Resolve the conflict before resuming.`));
         console.log('');
         console.log(chalk.dim('Recovery options:'));
-        console.log(`  ${chalk.cyan(`agentxchain reject-turn --turn ${targetTurn.turn_id} --reassign`)}  — reject and re-dispatch with conflict context`);
-        console.log(`  ${chalk.cyan(`agentxchain accept-turn --turn ${targetTurn.turn_id} --resolution human_merge`)}  — manually merge and re-accept`);
+        console.log(`  ${chalk.cyan(reassignAction.command)}  — ${reassignAction.description}`);
+        console.log(`  ${chalk.cyan(mergeAction.command)}  — ${mergeAction.description}`);
         process.exit(1);
       }
 
@@ -166,13 +169,13 @@ export async function stepCommand(opts) {
 
   if (!skipAssignment) {
     if (state.pending_phase_transition || state.pending_run_completion) {
-      printRecoverySummary(state, 'This run is awaiting approval.');
+      printRecoverySummary(state, 'This run is awaiting approval.', config);
       process.exit(1);
     }
 
     if (state.status === 'blocked' && activeCount > 0) {
       if (!opts.resume) {
-        printRecoverySummary(state, 'This run is blocked on a retained turn.');
+        printRecoverySummary(state, 'This run is blocked on a retained turn.', config);
         process.exit(1);
       }
 
@@ -199,11 +202,12 @@ export async function stepCommand(opts) {
 
       // If the target turn is conflicted, print recovery paths
       if (targetTurn.status === 'conflicted') {
+        const [reassignAction, mergeAction] = deriveConflictedTurnResolutionActions(targetTurn.turn_id);
         console.log(chalk.yellow(`Turn ${targetTurn.turn_id} is conflicted. Resolve the conflict before resuming.`));
         console.log('');
         console.log(chalk.dim('Recovery options:'));
-        console.log(`  ${chalk.cyan(`agentxchain reject-turn --turn ${targetTurn.turn_id} --reassign`)}  — reject and re-dispatch with conflict context`);
-        console.log(`  ${chalk.cyan(`agentxchain accept-turn --turn ${targetTurn.turn_id} --resolution human_merge`)}  — manually merge and re-accept`);
+        console.log(`  ${chalk.cyan(reassignAction.command)}  — ${reassignAction.description}`);
+        console.log(`  ${chalk.cyan(mergeAction.command)}  — ${mergeAction.description}`);
         process.exit(1);
       }
 
@@ -291,7 +295,7 @@ export async function stepCommand(opts) {
       const assignResult = assignGovernedTurn(root, config, roleId);
       if (!assignResult.ok) {
         if (assignResult.error_code?.startsWith('hook_') || assignResult.error_code === 'hook_blocked') {
-          printAssignmentHookFailure(assignResult, roleId);
+          printAssignmentHookFailure(assignResult, roleId, config);
         }
         console.log(chalk.red(`Failed to assign turn: ${assignResult.error}`));
         process.exit(1);
@@ -357,6 +361,7 @@ export async function stepCommand(opts) {
         turnId: turn.turn_id,
         roleId,
         action: `Fix or reconfigure the hook, then rerun agentxchain step --resume${turn.turn_id ? ` --turn ${turn.turn_id}` : ''}`,
+        config,
       });
       process.exit(1);
     }
@@ -430,12 +435,12 @@ export async function stepCommand(opts) {
         console.log(chalk.dim(`  Retry trace: ${apiResult.retry_trace_path}`));
       }
 
-      if (
-        apiResult.classified?.error_class === 'missing_credentials'
-        && roleId === 'qa'
-        && config.roles?.qa?.runtime_id === 'api-qa'
-        && rawConfig?.runtimes?.['manual-qa']?.type === 'manual'
-      ) {
+      if (shouldSuggestManualQaFallback({
+        roleId,
+        runtimeId,
+        classified: apiResult.classified,
+        config,
+      })) {
         console.log(chalk.dim('  No-key QA fallback:'));
         console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
         console.log(chalk.dim('  - Then rerun: agentxchain step --resume'));
@@ -737,6 +742,7 @@ export async function stepCommand(opts) {
         turnId: turn.turn_id,
         roleId,
         action: `Fix or reconfigure the hook, then rerun agentxchain step --resume${turn.turn_id ? ` --turn ${turn.turn_id}` : ''}`,
+        config,
       });
       process.exit(1);
     }
@@ -769,6 +775,7 @@ export async function stepCommand(opts) {
         turnId: turn.turn_id,
         roleId,
         action: `Fix or reconfigure the hook, then rerun agentxchain step --resume${turn.turn_id ? ` --turn ${turn.turn_id}` : ''}`,
+        config,
       });
       process.exit(1);
     }
@@ -779,14 +786,14 @@ export async function stepCommand(opts) {
     const acceptResult = acceptGovernedTurn(root, config, { turnId: turn.turn_id });
     if (!acceptResult.ok) {
       if (acceptResult.accepted && acceptResult.error_code?.startsWith('hook_')) {
-        printAcceptedHookFailure(acceptResult);
+        printAcceptedHookFailure(acceptResult, config);
       } else {
         console.log(chalk.red(`Acceptance failed: ${acceptResult.error}`));
       }
       process.exit(1);
     }
 
-    printAcceptSummary(acceptResult);
+    printAcceptSummary(acceptResult, config);
   } else {
     // Reject and potentially retry
     console.log(chalk.yellow('Validation failed:'));
@@ -808,7 +815,7 @@ export async function stepCommand(opts) {
       }
 
       if (rejectResult.escalated) {
-        printEscalationSummary(rejectResult);
+        printEscalationSummary(rejectResult, config);
       } else {
         console.log(chalk.yellow('Turn rejected for retry.'));
         console.log(`  Attempt: ${rejectResult.state?.current_turn?.attempt}`);
@@ -887,8 +894,8 @@ function blockStepForHookIssue(root, state, turn, { hookResults, phase, defaultD
   };
 }
 
-function printLifecycleHookFailure(title, result, { turnId, roleId, action }) {
-  const recovery = deriveRecoveryDescriptor(result.state);
+function printLifecycleHookFailure(title, result, { turnId, roleId, action, config }) {
+  const recovery = deriveRecoveryDescriptor(result.state, config);
   const hookName = result.hookResults?.blocker?.hook_name
     || result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name
     || '(unknown)';
@@ -935,8 +942,8 @@ function resolveTargetRole(opts, state, config) {
   return resolved.roleId;
 }
 
-function printRecoverySummary(state, heading) {
-  const recovery = deriveRecoveryDescriptor(state);
+function printRecoverySummary(state, heading, config) {
+  const recovery = deriveRecoveryDescriptor(state, config);
   console.log(chalk.yellow(heading));
   if (!recovery) {
     return;
@@ -1007,8 +1014,8 @@ function printAssignmentWarnings(assignResult) {
   }
 }
 
-function printAssignmentHookFailure(result, roleId) {
-  const recovery = deriveRecoveryDescriptor(result.state);
+function printAssignmentHookFailure(result, roleId, config) {
+  const recovery = deriveRecoveryDescriptor(result.state, config);
   const hookName = result.hookResults?.blocker?.hook_name
     || result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name
     || '(unknown)';
@@ -1034,8 +1041,8 @@ function printAssignmentHookFailure(result, roleId) {
   console.log('');
 }
 
-function printAcceptedHookFailure(result) {
-  const recovery = deriveRecoveryDescriptor(result.state);
+function printAcceptedHookFailure(result, config) {
+  const recovery = deriveRecoveryDescriptor(result.state, config);
   const hookName = result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name || '(unknown)';
 
   console.log('');
@@ -1058,9 +1065,9 @@ function printAcceptedHookFailure(result) {
   console.log('');
 }
 
-function printAcceptSummary(result) {
+function printAcceptSummary(result, config) {
   const accepted = result.accepted;
-  const recovery = deriveRecoveryDescriptor(result.state);
+  const recovery = deriveRecoveryDescriptor(result.state, config);
   console.log('');
   console.log(chalk.green('  Turn Accepted'));
   console.log(chalk.dim('  ' + '-'.repeat(44)));
@@ -1104,8 +1111,8 @@ function printAcceptSummary(result) {
   console.log('');
 }
 
-function printEscalationSummary(result) {
-  const recovery = deriveRecoveryDescriptor(result.state);
+function printEscalationSummary(result, config) {
+  const recovery = deriveRecoveryDescriptor(result.state, config);
   console.log('');
   console.log(chalk.red('  Turn Escalated'));
   console.log(chalk.dim('  ' + '-'.repeat(44)));