agentxchain 2.20.0 → 2.22.0

package/package.json

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

package/scripts/release-preflight.sh

@@ -114,8 +114,31 @@ else
 fi
 TEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# pass / { print $3 }')"
 TEST_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# fail / { print $3 }')"
+if [ -z "${TEST_PASS:-}" ]; then
+  VITEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed/ { for (i = 1; i <= NF; i++) if ($i ~ /^[0-9]+$/) { print $i; exit } }')"
+  NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
+  if [ -n "${VITEST_PASS:-}" ] && [ -n "${NODE_PASS:-}" ]; then
+    TEST_PASS="$((VITEST_PASS + NODE_PASS))"
+  elif [ -n "${NODE_PASS:-}" ]; then
+    TEST_PASS="${NODE_PASS}"
+  elif [ -n "${VITEST_PASS:-}" ]; then
+    TEST_PASS="${VITEST_PASS}"
+  fi
+fi
+if [ -z "${TEST_FAIL:-}" ]; then
+  NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
+  if [ -n "${NODE_FAIL:-}" ]; then
+    TEST_FAIL="${NODE_FAIL}"
+  elif printf '%s\n' "$TEST_OUTPUT" | grep -Eq '^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed'; then
+    TEST_FAIL=0
+  fi
+fi
 if [ "$TEST_STATUS" -eq 0 ] && [ "${TEST_FAIL:-0}" = "0" ]; then
-  pass "${TEST_PASS} tests passed, 0 failures"
+  if [ -n "${TEST_PASS:-}" ]; then
+    pass "${TEST_PASS} tests passed, 0 failures"
+  else
+    pass "npm test passed, 0 failures"
+  fi
 else
   fail "npm test failed"
   printf '%s\n' "$TEST_OUTPUT" | tail -20

package/src/commands/demo.js

@@ -605,6 +605,7 @@ All acceptance criteria met. OBJ-002 (clock skew) noted for follow-up. OBJ-003 (
       console.log(chalk.dim('  ─'.repeat(26)));
       console.log('');
       console.log(`  ${chalk.bold('Try it for real:')}  agentxchain init --governed`);
+      console.log(`  ${chalk.bold('Step by step:')}    https://agentxchain.dev/docs/first-turn`);
       console.log(`  ${chalk.bold('Read more:')}       https://agentxchain.dev/docs/quickstart`);
       console.log('');
     }

package/src/commands/escalate.js

@@ -35,7 +35,7 @@ export async function escalateCommand(opts) {
     process.exit(1);
   }
 
-  const recovery = deriveRecoveryDescriptor(result.state);
+  const recovery = deriveRecoveryDescriptor(result.state, config);
 
   console.log('');
   console.log(chalk.yellow('  Run Escalated'));

package/src/commands/status.js

@@ -168,7 +168,7 @@ function renderGovernedStatus(context, opts) {
   if (state?.blocked_on) {
     console.log('');
     if (state.status === 'blocked') {
-      const recovery = deriveRecoveryDescriptor(state);
+      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:')) {
@@ -179,7 +179,7 @@ function renderGovernedStatus(context, opts) {
     }
   }
 
-  const recovery = deriveRecoveryDescriptor(state);
+  const recovery = deriveRecoveryDescriptor(state, config);
   if (recovery) {
     console.log('');
     console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);

package/src/lib/adapters/api-proxy-adapter.js

@@ -48,9 +48,19 @@ const PROVIDER_ENDPOINTS = {
 
 // Cost rates per million tokens (USD)
 const COST_RATES = {
+  // Anthropic
   'claude-sonnet-4-6': { input_per_1m: 3.00, output_per_1m: 15.00 },
   'claude-opus-4-6': { input_per_1m: 15.00, output_per_1m: 75.00 },
   'claude-haiku-4-5-20251001': { input_per_1m: 0.80, output_per_1m: 4.00 },
+  // OpenAI
+  'gpt-4o': { input_per_1m: 2.50, output_per_1m: 10.00 },
+  'gpt-4o-mini': { input_per_1m: 0.15, output_per_1m: 0.60 },
+  'gpt-4.1': { input_per_1m: 2.00, output_per_1m: 8.00 },
+  'gpt-4.1-mini': { input_per_1m: 0.40, output_per_1m: 1.60 },
+  'gpt-4.1-nano': { input_per_1m: 0.10, output_per_1m: 0.40 },
+  'o3': { input_per_1m: 2.00, output_per_1m: 8.00 },
+  'o3-mini': { input_per_1m: 1.10, output_per_1m: 4.40 },
+  'o4-mini': { input_per_1m: 1.10, output_per_1m: 4.40 },
 };
 
 const RETRYABLE_ERROR_CLASSES = [

package/src/lib/blocked-state.js

@@ -1,6 +1,30 @@
-import { getActiveTurnCount } from './governed-state.js';
+import { deriveEscalationRecoveryAction, getActiveTurnCount } from './governed-state.js';
 
-export function deriveRecoveryDescriptor(state) {
+function isLegacyEscalationRecoveryAction(action) {
+  return action === 'Resolve the escalation, then run agentxchain step --resume'
+    || action === 'Resolve the escalation, then run agentxchain step';
+}
+
+function maybeRefreshEscalationAction(state, config, persistedRecovery, turnRetained) {
+  if (!config || !persistedRecovery || typeof persistedRecovery !== 'object') {
+    return null;
+  }
+
+  const typedReason = persistedRecovery.typed_reason;
+  const currentAction = persistedRecovery.recovery_action || null;
+  const shouldRefresh = typedReason === 'retries_exhausted'
+    || ((typedReason === 'operator_escalation') && isLegacyEscalationRecoveryAction(currentAction));
+  if (!shouldRefresh) {
+    return null;
+  }
+
+  return deriveEscalationRecoveryAction(state, config, {
+    turnRetained,
+    turnId: state?.blocked_reason?.turn_id ?? state?.escalation?.from_turn_id ?? null,
+  });
+}
+
+export function deriveRecoveryDescriptor(state, config = null) {
   if (!state || typeof state !== 'object') {
     return null;
   }
@@ -29,10 +53,13 @@ export function deriveRecoveryDescriptor(state) {
 
   const persistedRecovery = state.blocked_reason?.recovery;
   if (persistedRecovery && typeof persistedRecovery === 'object') {
+    const refreshedEscalationAction = maybeRefreshEscalationAction(state, config, persistedRecovery, turnRetained);
     return {
       typed_reason: persistedRecovery.typed_reason || 'unknown_block',
       owner: persistedRecovery.owner || 'human',
-      recovery_action: persistedRecovery.recovery_action || 'Inspect state.json and resolve manually before rerunning agentxchain step',
+      recovery_action: refreshedEscalationAction
+        || persistedRecovery.recovery_action
+        || 'Inspect state.json and resolve manually before rerunning agentxchain step',
       turn_retained: typeof persistedRecovery.turn_retained === 'boolean'
         ? persistedRecovery.turn_retained
         : turnRetained,
@@ -66,9 +93,10 @@ export function deriveRecoveryDescriptor(state) {
 
   if (state.blocked_on.startsWith('escalation:')) {
     const isOperatorEscalation = state.blocked_on.startsWith('escalation:operator:') || state.escalation?.source === 'operator';
-    const recoveryAction = turnRetained
-      ? 'Resolve the escalation, then run agentxchain step --resume'
-      : 'Resolve the escalation, then run agentxchain step';
+    const recoveryAction = deriveEscalationRecoveryAction(state, config, {
+      turnRetained,
+      turnId: state.blocked_reason?.turn_id ?? state.escalation?.from_turn_id ?? null,
+    });
     return {
       typed_reason: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
       owner: 'human',

package/src/lib/config.js

@@ -3,7 +3,12 @@ import { join, parse as pathParse, resolve } from 'path';
 import { safeParseJson, validateConfigSchema, validateLockSchema, validateProjectStateSchema, validateStateSchema } from './schema.js';
 import { loadNormalizedConfig } from './normalized-config.js';
 import { safeWriteJson } from './safe-write.js';
-import { normalizeGovernedStateShape, getActiveTurn } from './governed-state.js';
+import {
+  normalizeGovernedStateShape,
+  getActiveTurn,
+  reconcileBudgetStatusWithConfig,
+  reconcileEscalationRecoveryWithConfig,
+} from './governed-state.js';
 
 function attachLegacyCurrentTurnAlias(state) {
   if (!state || typeof state !== 'object') {
@@ -148,7 +153,11 @@ export function loadProjectState(root, config) {
   if (config?.protocol_mode === 'governed') {
     const normalized = normalizeGovernedStateShape(stateData);
     stateData = normalized.state;
-    if (normalized.changed) {
+    const reconciledBudget = reconcileBudgetStatusWithConfig(stateData, config);
+    stateData = reconciledBudget.state;
+    const reconciledRecovery = reconcileEscalationRecoveryWithConfig(stateData, config);
+    stateData = reconciledRecovery.state;
+    if (normalized.changed || reconciledBudget.changed || reconciledRecovery.changed) {
       safeWriteJson(filePath, stateData);
     }
   }

package/src/lib/governed-state.js

@@ -190,6 +190,68 @@ export function getActiveTurn(state) {
   return turns.length === 1 ? turns[0] : null;
 }
 
+function resolveRecoveryTurnId(state, preferredTurnId = null) {
+  const activeTurns = getActiveTurns(state);
+  if (preferredTurnId && activeTurns[preferredTurnId]) {
+    return preferredTurnId;
+  }
+
+  const blockedTurnId = state?.blocked_reason?.turn_id;
+  if (blockedTurnId && activeTurns[blockedTurnId]) {
+    return blockedTurnId;
+  }
+
+  const escalationTurnId = state?.escalation?.from_turn_id;
+  if (escalationTurnId && activeTurns[escalationTurnId]) {
+    return escalationTurnId;
+  }
+
+  const turnIds = Object.keys(activeTurns);
+  return turnIds.length === 1 ? turnIds[0] : null;
+}
+
+export function deriveRetainedTurnRecoveryCommand(state, config, options = {}) {
+  const turnId = resolveRecoveryTurnId(state, options.turnId);
+  if (!turnId) {
+    return options.fallbackCommand || 'agentxchain step --resume';
+  }
+
+  const turn = getActiveTurns(state)[turnId];
+  const runtimeType = config?.runtimes?.[turn?.runtime_id]?.type || 'manual';
+  let command = runtimeType === 'manual'
+    ? (options.manualCommand || 'agentxchain resume')
+    : (options.automatedCommand || 'agentxchain step --resume');
+
+  if (getActiveTurnCount(state) > 1) {
+    command += ` --turn ${turnId}`;
+  }
+
+  return command;
+}
+
+function isLegacyEscalationRecoveryAction(action) {
+  return action === 'Resolve the escalation, then run agentxchain step --resume'
+    || action === 'Resolve the escalation, then run agentxchain step';
+}
+
+export function deriveEscalationRecoveryAction(state, config, options = {}) {
+  if (typeof options.overrideAction === 'string' && options.overrideAction.trim()) {
+    return options.overrideAction.trim();
+  }
+
+  const turnRetained = typeof options.turnRetained === 'boolean'
+    ? options.turnRetained
+    : getActiveTurnCount(state) > 0;
+  const command = turnRetained
+    ? deriveRetainedTurnRecoveryCommand(state, config, {
+      turnId: options.turnId,
+      fallbackCommand: 'agentxchain step --resume',
+    })
+    : 'agentxchain resume';
+
+  return `Resolve the escalation, then run ${command}`;
+}
+
 export function getActiveTurnOrThrow(state) {
   const turns = Object.values(getActiveTurns(state));
   if (turns.length === 0) {
@@ -222,6 +284,91 @@ function attachLegacyCurrentTurnAlias(state) {
   return state;
 }
 
+function formatBudgetRecoveryAction(isReadyToResume) {
+  return isReadyToResume
+    ? 'Run agentxchain resume to assign the next turn'
+    : 'Increase per_run_max_usd in agentxchain.json, then run agentxchain resume';
+}
+
+function formatBudgetRecoveryDetail(spentUsd, limitUsd, remainingUsd, isReadyToResume) {
+  if (limitUsd == null) {
+    return isReadyToResume
+      ? `Budget recovery ready: spent $${spentUsd.toFixed(2)} with per_run_max_usd disabled`
+      : `Run budget exhausted: spent $${spentUsd.toFixed(2)} with no configured per_run_max_usd limit`;
+  }
+
+  if (isReadyToResume) {
+    return `Budget recovery ready: spent $${spentUsd.toFixed(2)} of $${limitUsd.toFixed(2)} limit ($${remainingUsd.toFixed(2)} remaining)`;
+  }
+
+  return `Run budget exhausted: spent $${spentUsd.toFixed(2)} of $${limitUsd.toFixed(2)} limit ($${Math.abs(remainingUsd).toFixed(2)} over)`;
+}
+
+export function reconcileBudgetStatusWithConfig(state, config) {
+  if (!state || typeof state !== 'object') {
+    return { state, changed: false };
+  }
+
+  const baseState = stripLegacyCurrentTurn(state);
+  const budgetStatus = baseState.budget_status && typeof baseState.budget_status === 'object' && !Array.isArray(baseState.budget_status)
+    ? baseState.budget_status
+    : {};
+  const spentUsd = Number.isFinite(budgetStatus.spent_usd) ? budgetStatus.spent_usd : 0;
+  const limitUsd = Number.isFinite(config?.budget?.per_run_max_usd) ? config.budget.per_run_max_usd : null;
+  const remainingUsd = limitUsd != null ? limitUsd - spentUsd : null;
+  const nextBudgetStatus = {
+    ...budgetStatus,
+    spent_usd: spentUsd,
+    remaining_usd: remainingUsd,
+  };
+
+  if (remainingUsd != null && remainingUsd <= 0) {
+    nextBudgetStatus.exhausted = true;
+    if (budgetStatus.exhausted_at) {
+      nextBudgetStatus.exhausted_at = budgetStatus.exhausted_at;
+    }
+    if (budgetStatus.exhausted_after_turn) {
+      nextBudgetStatus.exhausted_after_turn = budgetStatus.exhausted_after_turn;
+    }
+  } else {
+    delete nextBudgetStatus.exhausted;
+    delete nextBudgetStatus.exhausted_at;
+    delete nextBudgetStatus.exhausted_after_turn;
+  }
+
+  let nextState = {
+    ...baseState,
+    budget_status: nextBudgetStatus,
+  };
+
+  const isBudgetBlocked = nextState.blocked_on === 'budget:exhausted' || nextState.blocked_reason?.category === 'budget_exhausted';
+  if (isBudgetBlocked) {
+    const isReadyToResume = remainingUsd == null || remainingUsd > 0;
+    nextState = {
+      ...nextState,
+      blocked_on: 'budget:exhausted',
+      blocked_reason: buildBlockedReason({
+        category: 'budget_exhausted',
+        recovery: {
+          typed_reason: 'budget_exhausted',
+          owner: 'human',
+          recovery_action: formatBudgetRecoveryAction(isReadyToResume),
+          turn_retained: false,
+          detail: formatBudgetRecoveryDetail(spentUsd, limitUsd, remainingUsd, isReadyToResume),
+        },
+        turnId: nextState.blocked_reason?.turn_id ?? nextState.last_completed_turn_id ?? null,
+        blockedAt: nextState.blocked_reason?.blocked_at,
+      }),
+    };
+  }
+
+  const changed = JSON.stringify(baseState) !== JSON.stringify(nextState);
+  return {
+    state: changed ? nextState : baseState,
+    changed,
+  };
+}
+
 function normalizeV1toV1_1(state) {
   const hadLegacyCurrentTurn = Object.prototype.hasOwnProperty.call(state, 'current_turn');
   const activeTurns = normalizeActiveTurns(state.active_turns);
@@ -789,6 +936,66 @@ function normalizeRecoveryDescriptor(recovery, turnRetained, detail) {
   };
 }
 
+export function reconcileEscalationRecoveryWithConfig(state, config) {
+  if (!state || typeof state !== 'object' || state.status !== 'blocked' || !config) {
+    return { state, changed: false };
+  }
+
+  const recovery = state.blocked_reason?.recovery;
+  const typedReason = recovery?.typed_reason;
+  if (typedReason !== 'operator_escalation' && typedReason !== 'retries_exhausted') {
+    return { state, changed: false };
+  }
+
+  const currentAction = recovery?.recovery_action || null;
+  const shouldRefresh = typedReason === 'retries_exhausted' || isLegacyEscalationRecoveryAction(currentAction);
+  if (!shouldRefresh) {
+    return { state, changed: false };
+  }
+
+  const turnRetained = typeof recovery?.turn_retained === 'boolean'
+    ? recovery.turn_retained
+    : getActiveTurnCount(state) > 0;
+  const nextAction = deriveEscalationRecoveryAction(state, config, {
+    turnRetained,
+    turnId: state.blocked_reason?.turn_id ?? state.escalation?.from_turn_id ?? null,
+  });
+
+  let nextState = state;
+  let changed = false;
+
+  if (recovery && currentAction !== nextAction) {
+    nextState = {
+      ...nextState,
+      blocked_reason: {
+        ...nextState.blocked_reason,
+        recovery: {
+          ...recovery,
+          recovery_action: nextAction,
+        },
+      },
+    };
+    changed = true;
+  }
+
+  if (
+    nextState.escalation?.source === 'operator'
+    && isLegacyEscalationRecoveryAction(nextState.escalation.recovery_action)
+    && nextState.escalation.recovery_action !== nextAction
+  ) {
+    nextState = {
+      ...nextState,
+      escalation: {
+        ...nextState.escalation,
+        recovery_action: nextAction,
+      },
+    };
+    changed = true;
+  }
+
+  return { state: nextState, changed };
+}
+
 function inferBlockedReasonFromState(state) {
   if (!state || typeof state !== 'object') {
     return null;
@@ -818,9 +1025,10 @@ function inferBlockedReasonFromState(state) {
 
   if (state.blocked_on.startsWith('escalation:')) {
     const isOperatorEscalation = isOperatorEscalationBlockedOn(state.blocked_on) || state.escalation?.source === 'operator';
-    const recoveryAction = turnRetained
-      ? 'Resolve the escalation, then run agentxchain step --resume'
-      : 'Resolve the escalation, then run agentxchain step';
+    const recoveryAction = deriveEscalationRecoveryAction(state, null, {
+      turnRetained,
+      turnId: activeTurn?.turn_id ?? state.escalation?.from_turn_id ?? null,
+    });
     return buildBlockedReason({
       category: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
       recovery: {
@@ -1001,10 +1209,11 @@ export function raiseOperatorEscalation(root, config, details) {
   }
 
   const turnRetained = Boolean(targetTurn);
-  const recoveryAction = details.action
-    || (turnRetained
-      ? 'Resolve the escalation, then run agentxchain step --resume'
-      : 'Resolve the escalation, then run agentxchain step');
+  const recoveryAction = deriveEscalationRecoveryAction(state, config, {
+    turnRetained,
+    turnId: targetTurn?.turn_id || null,
+    overrideAction: details.action,
+  });
   const detail = typeof details.detail === 'string' && details.detail.trim()
     ? details.detail.trim()
     : reason;
@@ -1161,11 +1370,17 @@ export function initializeGovernedRun(root, config) {
  * @returns {{ ok: boolean, error?: string, warnings?: string[], state?: object }}
  */
 export function assignGovernedTurn(root, config, roleId) {
-  const state = readState(root);
+  let state = readState(root);
   if (!state) {
     return { ok: false, error: 'No governed state.json found' };
   }
 
+  const reconciledBudget = reconcileBudgetStatusWithConfig(state, config);
+  if (reconciledBudget.changed) {
+    state = reconciledBudget.state;
+    writeState(root, state);
+  }
+
   // DEC-PARALLEL-007: No new assignment while run is blocked
   if (state.status === 'blocked') {
     return { ok: false, error: 'Cannot assign turn: run is blocked. Resolve the blocked state before assigning new turns.' };
@@ -1206,6 +1421,11 @@ export function assignGovernedTurn(root, config, roleId) {
     return { ok: false, error: `Cannot assign turn: ${activeCount} active turn(s) already at capacity (max_concurrent_turns = ${maxConcurrent})` };
   }
 
+  // DEC-BUDGET-ENFORCE-001: Pre-assignment budget exhaustion guard
+  if (state.budget_status?.remaining_usd != null && state.budget_status.remaining_usd <= 0) {
+    return { ok: false, error: `Cannot assign turn: run budget exhausted (spent $${(state.budget_status.spent_usd || 0).toFixed(2)} of $${((state.budget_status.spent_usd || 0) + state.budget_status.remaining_usd).toFixed(2)} limit). Increase per_run_max_usd in agentxchain.json, then run agentxchain resume` };
+  }
+
   // DEC-PARALLEL-011: Budget reservation
   const warnings = [];
   const reservations = { ...(state.budget_reservations || {}) };
@@ -1807,6 +2027,44 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     });
   }
 
+  // DEC-BUDGET-ENFORCE-001: Post-acceptance budget exhaustion check
+  // Per-turn overrun warning (advisory only)
+  let budgetWarning = null;
+  const turnReservation = state.budget_reservations?.[currentTurn.turn_id];
+  if (turnReservation && costUsd > turnReservation.reserved_usd) {
+    budgetWarning = `Actual cost $${costUsd.toFixed(2)} exceeded reservation $${turnReservation.reserved_usd.toFixed(2)} for this turn`;
+  }
+  // Budget exhaustion enforcement
+  if (
+    updatedState.budget_status.remaining_usd != null &&
+    updatedState.budget_status.remaining_usd <= 0 &&
+    updatedState.status !== 'blocked' &&
+    updatedState.status !== 'completed'
+  ) {
+    const onExceed = config.budget?.on_exceed || 'pause_and_escalate';
+    if (onExceed === 'pause_and_escalate') {
+      const limit = (updatedState.budget_status.spent_usd + updatedState.budget_status.remaining_usd);
+      const overBy = Math.abs(updatedState.budget_status.remaining_usd);
+      updatedState.status = 'blocked';
+      updatedState.blocked_on = 'budget:exhausted';
+      updatedState.blocked_reason = buildBlockedReason({
+        category: 'budget_exhausted',
+        recovery: {
+          typed_reason: 'budget_exhausted',
+          owner: 'human',
+          recovery_action: 'Increase per_run_max_usd in agentxchain.json, then run agentxchain resume',
+          turn_retained: false,
+          detail: `Run budget exhausted: spent $${updatedState.budget_status.spent_usd.toFixed(2)} of $${limit.toFixed(2)} limit ($${overBy.toFixed(2)} over)`,
+        },
+        turnId: currentTurn.turn_id,
+        blockedAt: now,
+      });
+      updatedState.budget_status.exhausted = true;
+      updatedState.budget_status.exhausted_at = now;
+      updatedState.budget_status.exhausted_after_turn = currentTurn.turn_id;
+    }
+  }
+
   let gateResult = null;
   let completionResult = null;
   const hasRemainingTurns = Object.keys(remainingTurns).length > 0;
@@ -2030,6 +2288,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     gateResult,
     completionResult,
     hookResults,
+    ...(budgetWarning ? { budget_warning: budgetWarning } : {}),
   };
 }
 
@@ -2171,7 +2430,7 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
   }
 
   // Retries exhausted — escalate
-  const updatedState = {
+  const exhaustedEscalationState = {
     ...state,
     status: 'blocked',
     active_turns: {
@@ -2185,12 +2444,19 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
       },
     },
     blocked_on: `escalation:retries-exhausted:${currentTurn.assigned_role}`,
+  };
+
+  const updatedState = {
+    ...exhaustedEscalationState,
     blocked_reason: buildBlockedReason({
       category: 'retries_exhausted',
       recovery: {
         typed_reason: 'retries_exhausted',
         owner: 'human',
-        recovery_action: 'Resolve the escalation, then run agentxchain step --resume',
+        recovery_action: deriveEscalationRecoveryAction(exhaustedEscalationState, config, {
+          turnRetained: true,
+          turnId: currentTurn.turn_id,
+        }),
         turn_retained: true,
         detail: `escalation:retries-exhausted:${currentTurn.assigned_role}`,
       },
@@ -2218,7 +2484,10 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
   if (hooksConfig.on_escalation?.length > 0) {
     _fireOnEscalationHooks(root, hooksConfig, {
       blocked_reason: 'retries_exhausted',
-      recovery_action: 'Resolve the escalation, then run agentxchain step --resume',
+      recovery_action: deriveEscalationRecoveryAction(updatedState, config, {
+        turnRetained: true,
+        turnId: currentTurn.turn_id,
+      }),
       failed_turn_id: currentTurn.turn_id,
       failed_role: currentTurn.assigned_role,
       attempt_count: currentAttempt,