agentxchain 2.103.0 → 2.105.0

package/src/commands/multi.js

@@ -11,7 +11,16 @@
  */
 
 import chalk from 'chalk';
+import { getCoordinatorBlockerDetails } from '../lib/coordinator-blocker-presentation.js';
+import {
+  normalizeCoordinatorGateApprovalFailure,
+  normalizeCoordinatorGateApprovalSuccess,
+} from '../lib/coordinator-gate-approval.js';
 import { loadCoordinatorConfig } from '../lib/coordinator-config.js';
+import { deriveCoordinatorNextActions } from '../lib/coordinator-next-actions.js';
+import { getCoordinatorPendingGateDetails } from '../lib/coordinator-pending-gate-presentation.js';
+import { buildCoordinatorRepoStatusRows } from '../lib/coordinator-repo-status-presentation.js';
+import { collectCoordinatorRepoSnapshots } from '../lib/coordinator-repo-snapshots.js';
 import {
   initializeCoordinatorRun,
   loadCoordinatorState,
@@ -99,9 +108,18 @@ export async function multiStatusCommand(options) {
 
   const status = getCoordinatorStatus(workspacePath);
   const barriers = readBarriers(workspacePath);
+  const configResult = loadCoordinatorConfig(workspacePath);
+  const repoRows = buildCoordinatorRepoStatusRows({
+    config: configResult.ok ? configResult.config : null,
+    coordinatorRepoRuns: status.repo_runs || {},
+  });
+  const nextActions = deriveCoordinatorCliNextActions(
+    status,
+    configResult.ok ? configResult.config : null,
+  );
 
   if (options.json) {
-    console.log(JSON.stringify({ ...status, barriers }, null, 2));
+    console.log(JSON.stringify({ ...status, barriers, next_actions: nextActions }, null, 2));
     return;
   }
 
@@ -129,14 +147,13 @@ export async function multiStatusCommand(options) {
     console.log(`Blocked:      ${chalk.red.bold('BLOCKED')} — ${reason}`);
   }
 
-  // Pending gate with phase transition direction
+  // Pending gate details
   if (status.pending_gate) {
-    const pg = status.pending_gate;
-    const fromTo = pg.from && pg.to ? ` ${pg.from} → ${pg.to}` : '';
-    console.log(`Pending Gate: ${pg.gate} (${pg.gate_type})${fromTo}`);
-    console.log(`Action:       Run ${chalk.cyan('agentxchain multi approve-gate')} to advance`);
+    printCoordinatorPendingGate(status.pending_gate);
   }
 
+  printCoordinatorNextActions(nextActions);
+
   // Completed state
   if (status.status === 'completed') {
     console.log('');
@@ -148,9 +165,13 @@ export async function multiStatusCommand(options) {
 
   console.log('');
   console.log('Repos:');
-  for (const [repoId, info] of Object.entries(status.repo_runs || {})) {
-    const phase = info.phase ? ` [${info.phase}]` : '';
-    console.log(`  ${repoId}: ${info.status || 'unknown'}${phase} (run: ${info.run_id})`);
+  for (const row of repoRows) {
+    const phase = row.phase ? ` [${row.phase}]` : '';
+    const details = [
+      `run: ${row.run_id || 'unknown'}`,
+      ...row.details.map((detail) => `${detail.label}: ${detail.value}`),
+    ];
+    console.log(`  ${row.repo_id}: ${row.status || 'unknown'}${phase} (${details.join('; ')})`);
   }
 
   // Phase gate status
@@ -183,6 +204,121 @@ function formatCoordinatorStatus(status) {
   }
 }
 
+function deriveCoordinatorCliNextActions(statusLike, config) {
+  const repos = config ? collectCoordinatorRepoSnapshots(config) : [];
+  return deriveCoordinatorNextActions({
+    status: statusLike?.status ?? null,
+    blockedReason: statusLike?.blocked_reason ?? null,
+    pendingGate: statusLike?.pending_gate ?? null,
+    repos,
+    coordinatorRepoRuns: statusLike?.repo_runs || {},
+  });
+}
+
+function printCoordinatorNextActions(nextActions, write = console.log) {
+  if (!Array.isArray(nextActions) || nextActions.length === 0) {
+    return;
+  }
+
+  write('');
+  write('Next Actions:');
+  for (const [index, action] of nextActions.entries()) {
+    write(`  ${index + 1}. ${action.command}`);
+    if (action.reason) {
+      write(`     ${action.reason}`);
+    }
+  }
+}
+
+function printCoordinatorPendingGate(pendingGate, write = console.log) {
+  const details = getCoordinatorPendingGateDetails({ pendingGate });
+  if (details.length === 0) {
+    return;
+  }
+
+  write('Pending Gate:');
+  for (const detail of details) {
+    write(`  ${detail.label}: ${detail.value}`);
+  }
+}
+
+function printCoordinatorGateApprovalFailure(failure, write = console.error) {
+  write('');
+  write('Coordinator Gate Approval Failed');
+  write('');
+  if (failure.gate_type) {
+    write(`  Gate Type: ${failure.gate_type}`);
+  }
+  if (failure.gate) {
+    write(`  Gate:      ${failure.gate}`);
+  }
+  if (failure.hook_name) {
+    write(`  Hook:      ${failure.hook_name}`);
+  } else if (failure.hook_phase) {
+    write(`  Hook:      ${failure.hook_phase}`);
+  }
+  write(`  Error:     ${failure.error || 'Coordinator gate approval failed'}`);
+  if (failure.recovery_summary?.typed_reason) {
+    write(`  Reason:    ${failure.recovery_summary.typed_reason}`);
+  }
+  if (failure.recovery_summary?.owner) {
+    write(`  Owner:     ${failure.recovery_summary.owner}`);
+  }
+  if (failure.recovery_summary?.recovery_action) {
+    write(`  Action:    ${failure.recovery_summary.recovery_action}`);
+  }
+  if (failure.recovery_summary?.detail) {
+    write(`  Detail:    ${failure.recovery_summary.detail}`);
+  }
+  printCoordinatorNextActions(failure.next_actions, write);
+}
+
+function normalizeCoordinatorBlockerForPresentation(blocker) {
+  if (!blocker || typeof blocker !== 'object' || Array.isArray(blocker)) {
+    return null;
+  }
+
+  if (blocker.code === 'repo_run_id_mismatch') {
+    return {
+      code: blocker.code,
+      repo_id: blocker.repo_id ?? null,
+      expected_run_id: blocker.expected_run_id ?? null,
+      actual_run_id: blocker.actual_run_id ?? null,
+      message: blocker.message || null,
+    };
+  }
+
+  if (blocker.type === 'run_id_mismatch') {
+    return {
+      code: 'repo_run_id_mismatch',
+      repo_id: blocker.repo_id ?? null,
+      expected_run_id: blocker.coordinator_run_id ?? blocker.expected_run_id ?? null,
+      actual_run_id: blocker.repo_run_id ?? blocker.actual_run_id ?? null,
+      message: blocker.detail || blocker.message || null,
+    };
+  }
+
+  return {
+    code: blocker.code || blocker.type || null,
+    message: blocker.message || blocker.detail || null,
+  };
+}
+
+function printCoordinatorBlockerDetails(blockers, write = console.error) {
+  for (const blocker of Array.isArray(blockers) ? blockers : []) {
+    const normalized = normalizeCoordinatorBlockerForPresentation(blocker);
+    if (!normalized?.message) {
+      continue;
+    }
+
+    const codeTag = normalized.code ? `[${normalized.code}] ` : '';
+    write(`  - ${codeTag}${normalized.message}`);
+    for (const detail of getCoordinatorBlockerDetails(normalized)) {
+      write(`    ${detail.label}: ${detail.value}`);
+    }
+  }
+}
+
 // ── multi step ─────────────────────────────────────────────────────────────
 
 export async function multiStepCommand(options) {
@@ -214,14 +350,21 @@ export async function multiStepCommand(options) {
     // Fire on_escalation hook (advisory — cannot block, only notifies)
     fireEscalationHook(workspacePath, configResult.config, state, state.blocked_reason || 'unknown reason');
     console.error(`Coordinator is blocked: ${state.blocked_reason || 'unknown reason'}`);
-    console.error('Resolve the blocked state, then run `agentxchain multi resume` before stepping again.');
+    printCoordinatorNextActions(
+      deriveCoordinatorCliNextActions(state, configResult.config),
+      console.error,
+    );
     process.exitCode = 1;
     return;
   }
 
   if (state.pending_gate) {
-    console.error(`Coordinator has a pending gate: ${state.pending_gate.gate}`);
-    console.error('Approve the gate with `agentxchain multi approve-gate` before stepping.');
+    console.error('Coordinator has a pending gate.');
+    printCoordinatorPendingGate(state.pending_gate, console.error);
+    printCoordinatorNextActions(
+      deriveCoordinatorCliNextActions(state, configResult.config),
+      console.error,
+    );
     process.exitCode = 1;
     return;
   }
@@ -235,14 +378,7 @@ export async function multiStepCommand(options) {
       // Fire on_escalation for the blocked resync
       fireEscalationHook(workspacePath, configResult.config, state, resync.blocked_reason || 'resync failure');
       console.error(`Coordinator resync entered blocked state: ${resync.blocked_reason || 'unknown reason'}`);
-      for (const mismatch of resync.mismatch_details || []) {
-        const codeTag = mismatch.code ? `[${mismatch.code}] ` : '';
-        console.error(`  - ${codeTag}${mismatch.message}`);
-        if (mismatch.code === 'repo_run_id_mismatch') {
-          console.error(`    expected: ${mismatch.expected_run_id}`);
-          console.error(`    actual:   ${mismatch.actual_run_id}`);
-        }
-      }
+      printCoordinatorBlockerDetails(resync.mismatch_details, console.error);
       process.exitCode = 1;
       return;
     }
@@ -308,7 +444,10 @@ export async function multiStepCommand(options) {
       } else {
         console.log(`Completion gate requested: ${gate.payload.gate}`);
       }
-      console.log('Approve the gate with `agentxchain multi approve-gate` to continue.');
+      const updatedState = loadCoordinatorState(workspacePath) || state;
+      printCoordinatorNextActions(
+        deriveCoordinatorCliNextActions(updatedState, configResult.config),
+      );
       return;
     }
 
@@ -318,14 +457,7 @@ export async function multiStepCommand(options) {
     }
     if (gate.blockers.length > 0) {
       console.error(`Coordinator ${gate.type === 'phase_transition' ? 'phase' : 'completion'} gate is not ready:`);
-      for (const blocker of gate.blockers) {
-        const codeTag = blocker.code ? `[${blocker.code}] ` : '';
-        console.error(`  - ${codeTag}${blocker.message}`);
-        if (blocker.code === 'repo_run_id_mismatch') {
-          console.error(`    expected: ${blocker.expected_run_id}`);
-          console.error(`    actual:   ${blocker.actual_run_id}`);
-        }
-      }
+      printCoordinatorBlockerDetails(gate.blockers, console.error);
     }
     process.exitCode = 1;
     return;
@@ -465,6 +597,8 @@ export async function multiResumeCommand(options) {
     return;
   }
 
+  const nextActions = deriveCoordinatorCliNextActions(result.state, configResult.config);
+
   if (options.json) {
     console.log(JSON.stringify({
       ok: true,
@@ -472,6 +606,8 @@ export async function multiResumeCommand(options) {
       resumed_status: result.resumed_status,
       blocked_reason: result.blocked_reason,
       pending_gate: result.state?.pending_gate || null,
+      next_action: nextActions[0]?.command ?? null,
+      next_actions: nextActions,
       resync: result.resync,
     }, null, 2));
     return;
@@ -479,11 +615,10 @@ export async function multiResumeCommand(options) {
 
   console.log(`Coordinator resumed: ${result.resumed_status}`);
   console.log(`Previous block: ${result.blocked_reason}`);
-  if (result.resumed_status === 'paused' && result.state?.pending_gate) {
-    console.log(`Next action: agentxchain multi approve-gate (${result.state.pending_gate.gate})`);
-  } else {
-    console.log('Next action: agentxchain multi step');
+  if (result.state?.pending_gate) {
+    printCoordinatorPendingGate(result.state.pending_gate);
   }
+  printCoordinatorNextActions(nextActions);
 }
 
 // ── multi approve-gate ─────────────────────────────────────────────────────
@@ -523,22 +658,34 @@ export async function multiApproveGateCommand(options) {
   if (gateHook.blocked) {
     const blocker = gateHook.verdicts.find(v => v.verdict === 'block');
     const reason = blocker?.message || 'before_gate hook blocked approval';
-    console.error(`Gate approval blocked by hook: ${reason}`);
+    const failure = normalizeCoordinatorGateApprovalFailure({
+      state,
+      config: configResult.config,
+      code: 'hook_blocked',
+      error: reason,
+      hookName: blocker?.hook_name || null,
+      hookPhase: 'before_gate',
+    });
+    printCoordinatorGateApprovalFailure(failure);
     if (options.json) {
-      console.log(JSON.stringify({ blocked: true, hook_phase: 'before_gate', reason }, null, 2));
+      console.log(JSON.stringify(failure, null, 2));
     }
     process.exitCode = 1;
     return;
   }
 
   if (!gateHook.ok) {
-    console.error(`Gate hook failed: ${gateHook.error || 'unknown hook failure'}`);
+    const failure = normalizeCoordinatorGateApprovalFailure({
+      state,
+      config: configResult.config,
+      code: 'hook_failed',
+      error: gateHook.error || 'unknown hook failure',
+      hookName: gateHook.results?.find((entry) => entry?.hook_name)?.hook_name || null,
+      hookPhase: 'before_gate',
+    });
+    printCoordinatorGateApprovalFailure(failure);
     if (options.json) {
-      console.log(JSON.stringify({
-        blocked: true,
-        hook_phase: 'before_gate',
-        reason: gateHook.error || 'unknown hook failure',
-      }, null, 2));
+      console.log(JSON.stringify(failure, null, 2));
     }
     process.exitCode = 1;
     return;
@@ -558,21 +705,32 @@ export async function multiApproveGateCommand(options) {
   }
 
   if (!result.ok) {
-    console.error(`Gate approval failed: ${result.error}`);
+    const failure = normalizeCoordinatorGateApprovalFailure({
+      state,
+      config: configResult.config,
+      code: 'approval_failed',
+      error: result.error || 'Coordinator gate approval failed',
+    });
+    printCoordinatorGateApprovalFailure(failure);
+    if (options.json) {
+      console.log(JSON.stringify(failure, null, 2));
+    }
     process.exitCode = 1;
     return;
   }
 
+  const success = normalizeCoordinatorGateApprovalSuccess({
+    result: { ...result, config: configResult.config },
+    gateType,
+  });
+
   if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
+    console.log(JSON.stringify(success, null, 2));
     return;
   }
 
-  if (gateType === 'phase_transition') {
-    console.log(`Phase transition approved: ${result.transition?.from} → ${result.transition?.to}`);
-  } else {
-    console.log('Run completion approved. Coordinator run is now complete.');
-  }
+  console.log(success.message);
+  printCoordinatorNextActions(success.next_actions);
 }
 
 // ── multi resync ───────────────────────────────────────────────────────────
@@ -614,9 +772,7 @@ export async function multiResyncCommand(options) {
       console.log(JSON.stringify({ diverged: true, mismatches: divergence.mismatches }, null, 2));
     } else {
       console.log(`Divergence detected (${divergence.mismatches.length} mismatch(es)):`);
-      for (const m of divergence.mismatches) {
-        console.log(`  [${m.type}] ${m.detail}`);
-      }
+      printCoordinatorBlockerDetails(divergence.mismatches, console.log);
       console.log('');
       console.log('Run without --dry-run to resync.');
     }
@@ -625,9 +781,17 @@ export async function multiResyncCommand(options) {
 
   // Step 2: Resync
   const result = resyncFromRepoAuthority(workspacePath, state, configResult.config);
+  const updatedState = loadCoordinatorState(workspacePath) || state;
+  const nextActions = deriveCoordinatorCliNextActions(updatedState, configResult.config);
 
   if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
+    console.log(JSON.stringify({
+      ...result,
+      status: updatedState.status ?? null,
+      pending_gate: updatedState.pending_gate ?? null,
+      next_action: nextActions[0]?.command ?? null,
+      next_actions: nextActions,
+    }, null, 2));
     return;
   }
 
@@ -642,9 +806,14 @@ export async function multiResyncCommand(options) {
         console.log(`    ${bc.barrier_id}: ${bc.previous_status} → ${bc.new_status}`);
       }
     }
+    if (updatedState.pending_gate) {
+      printCoordinatorPendingGate(updatedState.pending_gate);
+    }
+    printCoordinatorNextActions(nextActions);
   } else {
-    console.error('Resync completed with blocked state:');
-    console.error(`  Reason: ${result.blocked_reason}`);
+    console.error(`Coordinator resync entered blocked state: ${result.blocked_reason || 'unknown reason'}`);
+    printCoordinatorBlockerDetails(result.mismatch_details, console.error);
+    printCoordinatorNextActions(nextActions, console.error);
     process.exitCode = 1;
   }
 }

package/src/commands/phase.js

@@ -12,7 +12,7 @@ export function phaseCommand(subcommand, phaseId, opts) {
     process.exit(1);
   }
 
-  const { root, config, rawConfig, version } = context;
+  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);
@@ -27,14 +27,14 @@ export function phaseCommand(subcommand, phaseId, opts) {
   const state = loadProjectState(root, config);
 
   if (subcommand === 'show') {
-    return showPhase(phaseId, { root, config, rawConfig, state, phaseIds, opts });
+    return showPhase(phaseId, { root, config, state, phaseIds, opts });
   }
 
-  return listPhases({ root, config, rawConfig, state, phaseIds, opts });
+  return listPhases({ root, config, state, phaseIds, opts });
 }
 
-function listPhases({ root, config, rawConfig, state, phaseIds, opts }) {
-  const phases = phaseIds.map((phaseId) => buildPhaseRecord(root, config, rawConfig, state, phaseId));
+function listPhases({ root, config, state, phaseIds, opts }) {
+  const phases = phaseIds.map((phaseId) => buildPhaseRecord(root, config, state, phaseId));
 
   if (opts.json) {
     console.log(JSON.stringify({
@@ -56,7 +56,7 @@ function listPhases({ root, config, rawConfig, state, phaseIds, opts }) {
   console.log(chalk.dim('  Usage: agentxchain phase show <phase>\n'));
 }
 
-function showPhase(requestedPhaseId, { root, config, rawConfig, state, phaseIds, opts }) {
+function showPhase(requestedPhaseId, { root, config, state, phaseIds, opts }) {
   const phaseId = requestedPhaseId || state?.phase || phaseIds[0];
   if (!config.routing?.[phaseId]) {
     console.log(chalk.red(`  Unknown phase: ${phaseId}`));
@@ -64,7 +64,7 @@ function showPhase(requestedPhaseId, { root, config, rawConfig, state, phaseIds,
     process.exit(1);
   }
 
-  const phase = buildPhaseRecord(root, config, rawConfig, state, phaseId);
+  const phase = buildPhaseRecord(root, config, state, phaseId);
 
   if (opts.json) {
     console.log(JSON.stringify(phase, null, 2));
@@ -112,16 +112,14 @@ function showPhase(requestedPhaseId, { root, config, rawConfig, state, phaseIds,
   console.log('');
 }
 
-function buildPhaseRecord(root, config, rawConfig, state, phaseId) {
+function buildPhaseRecord(root, config, 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 hasExplicitWorkflowKit = config.workflow_kit?._explicit === true;
 
   const workflowSource = !hasExplicitWorkflowKit
     ? 'default'
-    : rawPhaseKit
+    : normalizedPhaseKit
       ? 'explicit'
       : 'not_declared';
 
@@ -152,7 +150,7 @@ function buildPhaseRecord(root, config, rawConfig, state, phaseId) {
     max_concurrent_turns: getMaxConcurrentTurns(config, phaseId),
     workflow_kit: {
       source: workflowSource,
-      template: typeof rawPhaseKit?.template === 'string' ? rawPhaseKit.template : null,
+      template: typeof normalizedPhaseKit?.template === 'string' ? normalizedPhaseKit.template : null,
       artifacts,
     },
   };

package/src/commands/reject-turn.js

@@ -76,7 +76,7 @@ export async function rejectTurnCommand(opts) {
   console.log('');
 
   if (result.escalated) {
-    const recovery = deriveRecoveryDescriptor(result.state);
+    const recovery = deriveRecoveryDescriptor(result.state, config);
     if (recovery) {
       console.log(`  ${chalk.dim('Reason:')}       ${recovery.typed_reason}`);
       console.log(`  ${chalk.dim('Owner:')}        ${recovery.owner}`);

package/src/commands/restart.js

@@ -13,7 +13,7 @@
 import chalk from 'chalk';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
-import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { loadProjectContext } from '../lib/config.js';
 import {
   assignGovernedTurn,
   getActiveTurns,
@@ -23,6 +23,8 @@ import {
   HISTORY_PATH,
   LEDGER_PATH,
 } from '../lib/governed-state.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { deriveRecommendedContinuityAction } from '../lib/continuity-status.js';
 import { readSessionCheckpoint, writeSessionCheckpoint, captureBaselineRef, SESSION_PATH } from '../lib/session-checkpoint.js';
 
 /**
@@ -30,6 +32,7 @@ import { readSessionCheckpoint, writeSessionCheckpoint, captureBaselineRef, SESS
  * so a new agent session can orient quickly.
  */
 function generateRecoveryReport(root, state, checkpoint, driftWarnings = []) {
+  const continuityAction = deriveRecommendedContinuityAction(state);
   const lines = [
     '# Session Recovery Report',
     '',
@@ -112,7 +115,7 @@ function generateRecoveryReport(root, state, checkpoint, driftWarnings = []) {
       `- **To**: ${pt.to}`,
       `- **Gate**: ${pt.gate}`,
       `- **Requested by**: ${pt.requested_by_turn || 'unknown'}`,
-      `- **Action**: Run \`agentxchain approve-transition\` to approve`,
+      `- **Action**: Run \`${continuityAction.recommended_command}\` to continue`,
       '',
     );
   }
@@ -124,7 +127,7 @@ function generateRecoveryReport(root, state, checkpoint, driftWarnings = []) {
       '',
       `- **Gate**: ${pc.gate}`,
       `- **Requested by**: ${pc.requested_by_turn || 'unknown'}`,
-      `- **Action**: Run \`agentxchain approve-completion\` to approve`,
+      `- **Action**: Run \`${continuityAction.recommended_command}\` to continue`,
       '',
     );
   }
@@ -139,10 +142,9 @@ function generateRecoveryReport(root, state, checkpoint, driftWarnings = []) {
   }
 
   lines.push('## Next Steps', '');
-  if (state.pending_phase_transition) {
-    lines.push('A phase transition is pending approval. Run `agentxchain approve-transition` before assigning new turns.', '');
-  } else if (state.pending_run_completion) {
-    lines.push('A run completion is pending approval. Run `agentxchain approve-completion` to finalize.', '');
+  if (continuityAction.recommended_command && !continuityAction.restart_recommended) {
+    const detail = continuityAction.recommended_detail ? ` Detail: ${continuityAction.recommended_detail}.` : '';
+    lines.push(`Run \`${continuityAction.recommended_command}\` next.${detail}`, '');
   } else {
     lines.push('The next turn has been assigned. Check the dispatch bundle for context.', '');
   }
@@ -197,10 +199,17 @@ export async function restartCommand(opts) {
 
   if (state.status === 'blocked') {
     console.log(chalk.red('Run is blocked. Resolve the blocker first.'));
-    if (state.blocked_reason) {
+    const recovery = deriveRecoveryDescriptor(state, config);
+    if (recovery) {
+      console.log(chalk.dim(`Reason: ${recovery.typed_reason}`));
+      console.log(chalk.dim(`Owner: ${recovery.owner}`));
+      console.log(chalk.dim(`Action: ${recovery.recovery_action}`));
+      if (recovery.detail) {
+        console.log(chalk.dim(`Detail: ${recovery.detail}`));
+      }
+    } else if (state.blocked_reason) {
       console.log(chalk.dim(`Reason: ${typeof state.blocked_reason === 'string' ? state.blocked_reason : JSON.stringify(state.blocked_reason)}`));
     }
-    console.log(chalk.dim('Use `agentxchain step --resume` or resolve the blocker, then try again.'));
     process.exit(1);
   }
 
@@ -227,17 +236,25 @@ export async function restartCommand(opts) {
     }
   }
 
+  const continuityAction = deriveRecommendedContinuityAction(state);
+
   // ── Pending gate / completion check ────────────────────────────────────
   if (state.pending_phase_transition) {
     const pt = state.pending_phase_transition;
     console.log(chalk.yellow(`Pending phase transition: ${pt.from} → ${pt.to} (gate: ${pt.gate})`));
-    console.log(chalk.dim('Run `agentxchain approve-transition` to approve before assigning new turns.'));
+    console.log(chalk.dim(`Run \`${continuityAction.recommended_command}\` next.`));
+    if (continuityAction.recommended_detail) {
+      console.log(chalk.dim(`Detail: ${continuityAction.recommended_detail}`));
+    }
   }
 
   if (state.pending_run_completion) {
     const pc = state.pending_run_completion;
     console.log(chalk.yellow(`Pending run completion (gate: ${pc.gate})`));
-    console.log(chalk.dim('Run `agentxchain approve-completion` to finalize.'));
+    console.log(chalk.dim(`Run \`${continuityAction.recommended_command}\` next.`));
+    if (continuityAction.recommended_detail) {
+      console.log(chalk.dim(`Detail: ${continuityAction.recommended_detail}`));
+    }
   }
 
   // Handle abandoned active turns (assigned but never completed)

package/src/commands/resume.js

@@ -101,7 +101,7 @@ export async function resumeCommand(opts) {
   }
 
   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);
   }
 
@@ -267,7 +267,7 @@ export async function resumeCommand(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);
@@ -482,8 +482,8 @@ function printAssignmentWarnings(assignResult) {
   }
 }
 
-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;
@@ -495,8 +495,8 @@ function printRecoverySummary(state, heading) {
   }
 }
 
-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)';