agentxchain 2.22.0 → 2.23.0

package/README.md

@@ -214,7 +214,7 @@ The first-party governed workflow kit includes `.planning/SYSTEM_SPEC.md` alongs
 - `manual`: implemented
 - `local_cli`: implemented
 - `mcp`: implemented for stdio and streamable HTTP tool-contract dispatch
-- `api_proxy`: implemented for synchronous review-only turns and stages a provider-backed result during `step`
+- `api_proxy`: implemented for synchronous `review_only` and `proposed` write-authority turns; stages a provider-backed result during `step`
 
 ## Legacy IDE Mode
 

package/bin/agentxchain.js

@@ -68,6 +68,7 @@ import { resumeCommand } from '../src/commands/resume.js';
 import { escalateCommand } from '../src/commands/escalate.js';
 import { acceptTurnCommand } from '../src/commands/accept-turn.js';
 import { rejectTurnCommand } from '../src/commands/reject-turn.js';
+import { proposalListCommand, proposalDiffCommand, proposalApplyCommand, proposalRejectCommand } from '../src/commands/proposal.js';
 import { stepCommand } from '../src/commands/step.js';
 import { runCommand } from '../src/commands/run.js';
 import { approveTransitionCommand } from '../src/commands/approve-transition.js';
@@ -535,4 +536,35 @@ intakeCmd
   .option('-j, --json', 'Output as JSON')
   .action(intakeStatusCommand);
 
+// --- Proposal operations ----------------------------------------------------
+
+const proposalCmd = program
+  .command('proposal')
+  .description('Manage proposed changes from api_proxy agents');
+
+proposalCmd
+  .command('list')
+  .description('List all proposals and their status')
+  .action(proposalListCommand);
+
+proposalCmd
+  .command('diff <turn_id>')
+  .description('Show diff between proposed files and current workspace')
+  .option('--file <path>', 'Show diff for a single file only')
+  .action(proposalDiffCommand);
+
+proposalCmd
+  .command('apply <turn_id>')
+  .description('Apply proposed changes to the workspace')
+  .option('--file <path>', 'Apply only a specific file')
+  .option('--dry-run', 'Show what would change without writing')
+  .option('--force', 'Override proposal conflicts or unverifiable legacy proposals')
+  .action(proposalApplyCommand);
+
+proposalCmd
+  .command('reject <turn_id>')
+  .description('Reject a proposal without applying changes')
+  .option('--reason <reason>', 'Reason for rejection (required)')
+  .action(proposalRejectCommand);
+
 program.parse();

package/package.json

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

package/scripts/release-bump.sh

@@ -6,6 +6,7 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CLI_DIR="${SCRIPT_DIR}/.."
+REPO_ROOT="$(cd "${CLI_DIR}/.." && pwd)"
 cd "$CLI_DIR"
 
 TARGET_VERSION=""
@@ -46,13 +47,56 @@ fi
 echo "AgentXchain Release Identity: ${TARGET_VERSION}"
 echo "============================================="
 
-# 1. Assert clean tree
-echo "[1/7] Checking git tree cleanliness..."
-if ! git diff --quiet HEAD 2>/dev/null || [ -n "$(git ls-files --others --exclude-standard 2>/dev/null)" ]; then
-  echo "FAIL: Working tree is not clean. Commit or stash changes before creating release identity." >&2
+TARGET_RELEASE_DOC="website-v2/docs/releases/v${TARGET_VERSION//./-}.mdx"
+ALLOWED_RELEASE_PATHS=(
+  "cli/CHANGELOG.md"
+  "${TARGET_RELEASE_DOC}"
+  "website-v2/sidebars.ts"
+  "website-v2/src/pages/index.tsx"
+  ".agentxchain-conformance/capabilities.json"
+  "website-v2/docs/protocol-implementor-guide.mdx"
+  ".planning/LAUNCH_EVIDENCE_REPORT.md"
+)
+
+is_allowed_release_path() {
+  local candidate="$1"
+  local allowed
+  for allowed in "${ALLOWED_RELEASE_PATHS[@]}"; do
+    if [[ "$candidate" == "$allowed" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+stage_if_present() {
+  local rel_path="$1"
+  if [[ -e "${REPO_ROOT}/${rel_path}" ]]; then
+    git -C "$REPO_ROOT" add -- "$rel_path"
+    return 0
+  fi
+  if git -C "$REPO_ROOT" ls-files --error-unmatch "$rel_path" >/dev/null 2>&1; then
+    git -C "$REPO_ROOT" add -- "$rel_path"
+  fi
+}
+
+# 1. Assert only allowed release-surface dirt is present
+echo "[1/7] Checking release-prep tree state..."
+DISALLOWED_DIRTY=()
+while IFS= read -r status_line; do
+  [[ -z "$status_line" ]] && continue
+  path="${status_line#?? }"
+  if ! is_allowed_release_path "$path"; then
+    DISALLOWED_DIRTY+=("$path")
+  fi
+done < <(git -C "$REPO_ROOT" status --porcelain)
+
+if [[ "${#DISALLOWED_DIRTY[@]}" -gt 0 ]]; then
+  echo "FAIL: Working tree contains changes outside the allowed release surfaces:" >&2
+  printf '  - %s\n' "${DISALLOWED_DIRTY[@]}" >&2
   exit 1
 fi
-echo "  OK: tree is clean"
+echo "  OK: tree contains only allowed release-prep changes"
 
 # 2. Assert not already at target version
 echo "[2/7] Checking current version..."
@@ -78,11 +122,14 @@ echo "  OK: package.json updated to ${TARGET_VERSION}"
 
 # 5. Stage version files
 echo "[5/7] Staging version files..."
-git add package.json
+git add -- package.json
 if [[ -f package-lock.json ]]; then
-  git add package-lock.json
+  git add -- package-lock.json
 fi
-echo "  OK: version files staged"
+for rel_path in "${ALLOWED_RELEASE_PATHS[@]}"; do
+  stage_if_present "$rel_path"
+done
+echo "  OK: version files and allowed release surfaces staged"
 
 # 6. Create release commit
 echo "[6/7] Creating release commit..."

package/src/commands/proposal.js

@@ -0,0 +1,144 @@
+import chalk from 'chalk';
+import { loadProjectContext } from '../lib/config.js';
+import { listProposals, diffProposal, applyProposal, rejectProposal } from '../lib/proposal-ops.js';
+
+export async function proposalListCommand() {
+  const context = requireGovernedContext();
+  const result = listProposals(context.root);
+  if (!result.ok) {
+    console.log(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  if (result.proposals.length === 0) {
+    console.log(chalk.dim('  No proposals found.'));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold('  Proposals'));
+  console.log(chalk.dim('  ' + '─'.repeat(60)));
+  for (const p of result.proposals) {
+    const statusColor = p.status === 'applied' ? chalk.green : p.status === 'rejected' ? chalk.red : chalk.yellow;
+    console.log(`  ${chalk.dim(p.turn_id)}  ${p.role}  ${p.file_count} files  ${statusColor(p.status)}`);
+  }
+  console.log('');
+}
+
+export async function proposalDiffCommand(turnId, opts) {
+  const context = requireGovernedContext();
+  if (!turnId) {
+    console.log(chalk.red('Usage: agentxchain proposal diff <turn_id>'));
+    process.exit(1);
+  }
+
+  const result = diffProposal(context.root, turnId, opts.file);
+  if (!result.ok) {
+    console.log(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  for (const d of result.diffs) {
+    console.log('');
+    console.log(chalk.bold(`  ${d.path}`) + chalk.dim(` (${d.action})`));
+    console.log(chalk.dim('  ' + '─'.repeat(50)));
+    for (const line of d.preview.split('\n')) {
+      if (line.startsWith('+')) console.log(chalk.green(`  ${line}`));
+      else if (line.startsWith('-')) console.log(chalk.red(`  ${line}`));
+      else console.log(chalk.dim(`  ${line}`));
+    }
+  }
+  console.log('');
+}
+
+export async function proposalApplyCommand(turnId, opts) {
+  const context = requireGovernedContext();
+  if (!turnId) {
+    console.log(chalk.red('Usage: agentxchain proposal apply <turn_id>'));
+    process.exit(1);
+  }
+
+  const result = applyProposal(context.root, turnId, {
+    file: opts.file,
+    dryRun: opts.dryRun,
+    force: opts.force,
+  });
+
+  if (!result.ok) {
+    if (Array.isArray(result.conflicts) && result.conflicts.length > 0) {
+      console.log(chalk.red(`  ${result.error}`));
+      console.log(chalk.dim('  ' + '─'.repeat(44)));
+      for (const conflict of result.conflicts) {
+        console.log(`  ${chalk.red('•')} ${conflict.path} ${chalk.dim(`(${conflict.reason})`)}`);
+      }
+      console.log('');
+      process.exit(1);
+    }
+    console.log(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  console.log('');
+  if (result.dry_run) {
+    console.log(chalk.yellow('  Dry Run — No Changes Written'));
+  } else if (result.forced) {
+    console.log(chalk.yellow('  Proposal Applied With Force'));
+  } else {
+    console.log(chalk.green('  Proposal Applied'));
+  }
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Turn:')}    ${turnId}`);
+  console.log(`  ${chalk.dim('Applied:')} ${result.applied_files.length} files`);
+  if (result.applied_files.length > 0) {
+    for (const f of result.applied_files) {
+      console.log(`           ${chalk.dim('•')} ${f}`);
+    }
+  }
+  if (result.skipped_files.length > 0) {
+    console.log(`  ${chalk.dim('Skipped:')} ${result.skipped_files.length} files`);
+    for (const f of result.skipped_files) {
+      console.log(`           ${chalk.dim('•')} ${f}`);
+    }
+  }
+  if (result.forced && result.overridden_conflicts?.length > 0) {
+    console.log(`  ${chalk.dim('Forced:')}  ${result.overridden_conflicts.length} conflicts overridden`);
+    for (const conflict of result.overridden_conflicts) {
+      console.log(`           ${chalk.dim('•')} ${conflict.path}`);
+    }
+  }
+  console.log('');
+}
+
+export async function proposalRejectCommand(turnId, opts) {
+  const context = requireGovernedContext();
+  if (!turnId) {
+    console.log(chalk.red('Usage: agentxchain proposal reject <turn_id> --reason "..."'));
+    process.exit(1);
+  }
+
+  const result = rejectProposal(context.root, turnId, opts.reason);
+  if (!result.ok) {
+    console.log(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.yellow('  Proposal Rejected'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Turn:')}   ${turnId}`);
+  console.log(`  ${chalk.dim('Reason:')} ${opts.reason}`);
+  console.log('');
+}
+
+function requireGovernedContext() {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+  if (context.config.protocol_mode !== 'governed') {
+    console.log(chalk.red('The proposal command is only available for governed projects.'));
+    process.exit(1);
+  }
+  return context;
+}

package/src/commands/resume.js

@@ -21,6 +21,7 @@ import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import {
   initializeGovernedRun,
   assignGovernedTurn,
+  deriveAfterDispatchHookRecoveryAction,
   markRunBlocked,
   getActiveTurns,
   getActiveTurnCount,
@@ -358,13 +359,17 @@ function runAfterDispatchHooks(root, hooksConfig, state, turn, config) {
       || `after_dispatch hook blocked dispatch for turn ${turnId}`;
     const errorCode = afterDispatchHooks.tamper?.error_code || 'hook_blocked';
 
+    const recoveryAction = deriveAfterDispatchHookRecoveryAction(state, config, {
+      turnRetained: true,
+      turnId,
+    });
     markRunBlocked(root, {
       blockedOn: `hook:after_dispatch:${hookName}`,
       category: 'dispatch_error',
       recovery: {
         typed_reason: afterDispatchHooks.tamper ? 'hook_tamper' : 'hook_block',
         owner: 'human',
-        recovery_action: `Fix or reconfigure the hook, then rerun agentxchain resume`,
+        recovery_action: recoveryAction,
         turn_retained: true,
         detail,
       },
@@ -378,6 +383,7 @@ function runAfterDispatchHooks(root, hooksConfig, state, turn, config) {
       hookName,
       error: detail,
       errorCode,
+      recoveryAction,
       hookResults: afterDispatchHooks,
     });
 
@@ -387,7 +393,7 @@ function runAfterDispatchHooks(root, hooksConfig, state, turn, config) {
   return { ok: true };
 }
 
-function printDispatchHookFailure({ turnId, roleId, hookName, error, hookResults }) {
+function printDispatchHookFailure({ turnId, roleId, hookName, error, hookResults, recoveryAction }) {
   const isTamper = hookResults?.tamper;
   console.log('');
   console.log(chalk.yellow('  Dispatch Blocked By Hook'));
@@ -399,7 +405,7 @@ function printDispatchHookFailure({ turnId, roleId, hookName, error, hookResults
   console.log(`  ${chalk.dim('Error:')}    ${error}`);
   console.log(`  ${chalk.dim('Reason:')}   ${isTamper ? 'hook_tamper' : 'hook_block'}`);
   console.log(`  ${chalk.dim('Owner:')}    human`);
-  console.log(`  ${chalk.dim('Action:')}   Fix or reconfigure the hook, then rerun agentxchain resume`);
+  console.log(`  ${chalk.dim('Action:')}   ${recoveryAction}`);
   console.log('');
 }
 

package/src/commands/step.js

@@ -28,6 +28,7 @@ import {
   initializeGovernedRun,
   assignGovernedTurn,
   acceptGovernedTurn,
+  deriveAfterDispatchHookRecoveryAction,
   rejectGovernedTurn,
   markRunBlocked,
   getActiveTurnCount,
@@ -338,7 +339,7 @@ export async function stepCommand(opts) {
     });
 
     if (!afterDispatchHooks.ok) {
-      const blocked = blockStepForHookIssue(root, turn, {
+      const blocked = blockStepForHookIssue(root, state, turn, {
         hookResults: afterDispatchHooks,
         phase: 'after_dispatch',
         defaultDetail: `after_dispatch hook blocked dispatch for turn ${turn.turn_id}`,
@@ -654,7 +655,7 @@ export async function stepCommand(opts) {
     });
 
     if (!beforeValidationHooks.ok) {
-      const blocked = blockStepForHookIssue(root, turn, {
+      const blocked = blockStepForHookIssue(root, state, turn, {
         hookResults: beforeValidationHooks,
         phase: 'before_validation',
         defaultDetail: `before_validation hook blocked validation for turn ${turn.turn_id}`,
@@ -686,7 +687,7 @@ export async function stepCommand(opts) {
     });
 
     if (!afterValidationHooks.ok) {
-      const blocked = blockStepForHookIssue(root, turn, {
+      const blocked = blockStepForHookIssue(root, state, turn, {
         hookResults: afterValidationHooks,
         phase: 'after_validation',
         defaultDetail: `after_validation hook blocked acceptance for turn ${turn.turn_id}`,
@@ -775,7 +776,7 @@ function loadHookStagedTurn(root, stagingRel) {
   }
 }
 
-function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail, config }) {
+function blockStepForHookIssue(root, state, turn, { hookResults, phase, defaultDetail, config }) {
   const hookName = hookResults.blocker?.hook_name
     || hookResults.results?.find((entry) => entry.hook_name)?.hook_name
     || 'unknown';
@@ -783,13 +784,17 @@ function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail,
     || hookResults.tamper?.message
     || defaultDetail;
   const errorCode = hookResults.tamper?.error_code || 'hook_blocked';
+  const recoveryAction = deriveAfterDispatchHookRecoveryAction(state, config, {
+    turnRetained: true,
+    turnId: turn.turn_id,
+  });
   const blocked = markRunBlocked(root, {
     blockedOn: `hook:${phase}:${hookName}`,
     category: phase === 'after_dispatch' ? 'dispatch_error' : 'validation_error',
     recovery: {
       typed_reason: hookResults.tamper ? 'hook_tamper' : 'hook_block',
       owner: 'human',
-      recovery_action: 'Fix or reconfigure the hook, then run agentxchain step --resume',
+      recovery_action: recoveryAction,
       turn_retained: true,
       detail,
     },

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

@@ -1,10 +1,14 @@
 /**
- * API proxy adapter — review-only synchronous provider calls.
+ * API proxy adapter — synchronous provider calls for review and proposed authoring.
  *
- * v1 scope (Session #19 freeze):
- *   - review_only roles only
+ * Supported write authorities:
+ *   - review_only: single request/response, structured review JSON
+ *   - proposed: single request/response, structured JSON with proposed_changes[]
+ *     (orchestrator materializes proposals to .agentxchain/proposed/<turn_id>/)
+ *
+ * Constraints:
  *   - single request / single response (synchronous within `step`)
- *   - no tool use, no patch application, no repo writes
+ *   - no tool use, no direct repo writes
  *   - turn result must arrive as structured JSON
  *   - provider telemetry is authoritative for cost
  *
@@ -46,13 +50,15 @@ const PROVIDER_ENDPOINTS = {
   openai: 'https://api.openai.com/v1/chat/completions',
 };
 
-// Cost rates per million tokens (USD)
-const COST_RATES = {
-  // Anthropic
+// Bundled cost rates per million tokens (USD).
+// These are convenience defaults — operators can override via budget.cost_rates in agentxchain.json.
+// Verified: 2026-04-07 (Anthropic via docs.anthropic.com; OpenAI from training knowledge)
+const BUNDLED_COST_RATES = {
+  // Anthropic — verified 2026-04-07
   '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
+  'claude-opus-4-6': { input_per_1m: 5.00, output_per_1m: 25.00 },
+  'claude-haiku-4-5-20251001': { input_per_1m: 1.00, output_per_1m: 5.00 },
+  // OpenAI — verified 2026-04-07 (training knowledge, could not live-verify openai.com)
   '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 },
@@ -63,6 +69,18 @@ const COST_RATES = {
   'o4-mini': { input_per_1m: 1.10, output_per_1m: 4.40 },
 };
 
+// Resolve cost rates: operator-supplied cost_rates override bundled defaults
+function getCostRates(model, config) {
+  const operatorRates = config?.budget?.cost_rates;
+  if (operatorRates && typeof operatorRates === 'object' && operatorRates[model]) {
+    const r = operatorRates[model];
+    if (Number.isFinite(r.input_per_1m) && Number.isFinite(r.output_per_1m)) {
+      return r;
+    }
+  }
+  return BUNDLED_COST_RATES[model] || null;
+}
+
 const RETRYABLE_ERROR_CLASSES = [
   'rate_limited',
   'network_failure',
@@ -415,7 +433,7 @@ function emptyUsageTotals() {
   };
 }
 
-function usageFromTelemetry(provider, model, usage) {
+function usageFromTelemetry(provider, model, usage, config) {
   if (!usage || typeof usage !== 'object') return null;
 
   let inputTokens = 0;
@@ -429,7 +447,7 @@ function usageFromTelemetry(provider, model, usage) {
     outputTokens = Number.isFinite(usage.output_tokens) ? usage.output_tokens : 0;
   }
 
-  const rates = COST_RATES[model];
+  const rates = getCostRates(model, config);
   const usd = rates
     ? (inputTokens / 1_000_000) * rates.input_per_1m + (outputTokens / 1_000_000) * rates.output_per_1m
     : 0;
@@ -576,6 +594,7 @@ async function executeApiCall({
   requestBody,
   timeoutSeconds,
   signal,
+  config,
 }) {
   const timeoutMs = timeoutSeconds * 1000;
   const controller = new AbortController();
@@ -672,7 +691,7 @@ async function executeApiCall({
     };
   }
 
-  const usage = usageFromTelemetry(provider, model, responseData.usage);
+  const usage = usageFromTelemetry(provider, model, responseData.usage, config);
   const extraction = extractTurnResult(responseData, provider);
 
   if (!extraction.ok) {
@@ -740,9 +759,9 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
     return { ok: false, error: `Runtime "${runtimeId}" is not an api_proxy runtime` };
   }
 
-  // Enforce v1 restriction: review_only only
-  if (role?.write_authority !== 'review_only') {
-    return { ok: false, error: `v1 api_proxy only supports review_only roles (got "${role?.write_authority}")` };
+  // Enforce api_proxy restriction: review_only or proposed only
+  if (role?.write_authority !== 'review_only' && role?.write_authority !== 'proposed') {
+    return { ok: false, error: `api_proxy only supports review_only and proposed roles (got "${role?.write_authority}")` };
   }
 
   // Read dispatch bundle
@@ -879,6 +898,7 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
       requestBody,
       timeoutSeconds,
       signal,
+      config,
     });
 
     const attemptCompletedAt = new Date().toISOString();
@@ -1180,5 +1200,7 @@ export {
   buildOpenAiRequest,
   classifyError,
   classifyHttpError,
-  COST_RATES,
+  BUNDLED_COST_RATES,
+  BUNDLED_COST_RATES as COST_RATES, // backward compat alias
+  getCostRates,
 };

package/src/lib/blocked-state.js

@@ -1,27 +1,63 @@
-import { deriveEscalationRecoveryAction, getActiveTurnCount } from './governed-state.js';
+import {
+  deriveConflictLoopRecoveryAction,
+  deriveDispatchRecoveryAction,
+  deriveEscalationRecoveryAction,
+  deriveHookTamperRecoveryAction,
+  deriveNeedsHumanRecoveryAction,
+  getActiveTurnCount,
+} from './governed-state.js';
 
 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) {
+function isLegacyNeedsHumanRecoveryAction(action) {
+  return action === 'Resolve the stated issue, then run agentxchain step --resume';
+}
+
+function isLegacyHookTamperRecoveryAction(action) {
+  return action === 'Disable or fix the hook, verify protected files, then run agentxchain step --resume';
+}
+
+function isLegacyConflictLoopRecoveryAction(action) {
+  return typeof action === 'string' && action.startsWith('Serialize the conflicting work, then run agentxchain step --resume');
+}
+
+function maybeRefreshRecoveryAction(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;
+  const turnId = state?.blocked_reason?.turn_id ?? state?.escalation?.from_turn_id ?? null;
+  if (typedReason === 'retries_exhausted' || ((typedReason === 'operator_escalation') && isLegacyEscalationRecoveryAction(currentAction))) {
+    return deriveEscalationRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+    });
+  }
+
+  if (typedReason === 'needs_human' && isLegacyNeedsHumanRecoveryAction(currentAction)) {
+    return deriveNeedsHumanRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+    });
+  }
+
+  if (typedReason === 'hook_tamper' && isLegacyHookTamperRecoveryAction(currentAction)) {
+    return deriveHookTamperRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+    });
+  }
+
+  if (typedReason === 'conflict_loop' && isLegacyConflictLoopRecoveryAction(currentAction)) {
+    return deriveConflictLoopRecoveryAction(turnId);
   }
 
-  return deriveEscalationRecoveryAction(state, config, {
-    turnRetained,
-    turnId: state?.blocked_reason?.turn_id ?? state?.escalation?.from_turn_id ?? null,
-  });
+  return null;
 }
 
 export function deriveRecoveryDescriptor(state, config = null) {
@@ -53,11 +89,11 @@ export function deriveRecoveryDescriptor(state, config = null) {
 
   const persistedRecovery = state.blocked_reason?.recovery;
   if (persistedRecovery && typeof persistedRecovery === 'object') {
-    const refreshedEscalationAction = maybeRefreshEscalationAction(state, config, persistedRecovery, turnRetained);
+    const refreshedRecoveryAction = maybeRefreshRecoveryAction(state, config, persistedRecovery, turnRetained);
     return {
       typed_reason: persistedRecovery.typed_reason || 'unknown_block',
       owner: persistedRecovery.owner || 'human',
-      recovery_action: refreshedEscalationAction
+      recovery_action: refreshedRecoveryAction
         || persistedRecovery.recovery_action
         || 'Inspect state.json and resolve manually before rerunning agentxchain step',
       turn_retained: typeof persistedRecovery.turn_retained === 'boolean'
@@ -75,7 +111,10 @@ export function deriveRecoveryDescriptor(state, config = null) {
     return {
       typed_reason: 'needs_human',
       owner: 'human',
-      recovery_action: 'Resolve the stated issue, then run agentxchain step --resume',
+      recovery_action: deriveNeedsHumanRecoveryAction(state, config, {
+        turnRetained,
+        turnId: state.blocked_reason?.turn_id ?? null,
+      }),
       turn_retained: turnRetained,
       detail: state.blocked_on.slice('human:'.length) || null,
     };
@@ -110,7 +149,10 @@ export function deriveRecoveryDescriptor(state, config = null) {
     return {
       typed_reason: 'dispatch_error',
       owner: 'human',
-      recovery_action: 'Resolve the dispatch issue, then run agentxchain step --resume',
+      recovery_action: deriveDispatchRecoveryAction(state, config, {
+        turnRetained,
+        turnId: state.blocked_reason?.turn_id ?? null,
+      }),
       turn_retained: turnRetained,
       detail: state.blocked_on.slice('dispatch:'.length) || state.blocked_on,
     };

package/src/lib/config.js

@@ -7,7 +7,7 @@ import {
   normalizeGovernedStateShape,
   getActiveTurn,
   reconcileBudgetStatusWithConfig,
-  reconcileEscalationRecoveryWithConfig,
+  reconcileRecoveryActionsWithConfig,
 } from './governed-state.js';
 
 function attachLegacyCurrentTurnAlias(state) {
@@ -155,7 +155,7 @@ export function loadProjectState(root, config) {
     stateData = normalized.state;
     const reconciledBudget = reconcileBudgetStatusWithConfig(stateData, config);
     stateData = reconciledBudget.state;
-    const reconciledRecovery = reconcileEscalationRecoveryWithConfig(stateData, config);
+    const reconciledRecovery = reconcileRecoveryActionsWithConfig(stateData, config);
     stateData = reconciledRecovery.state;
     if (normalized.changed || reconciledBudget.changed || reconciledRecovery.changed) {
       safeWriteJson(filePath, stateData);