agentxchain 2.22.0 → 2.24.1

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);

package/src/lib/dispatch-bundle.js

@@ -14,7 +14,7 @@
  * orchestrator turn loop call it after assignGovernedTurn().
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { getActiveTurn, getActiveTurns } from './governed-state.js';
 import {
@@ -31,6 +31,7 @@ import {
 const HISTORY_PATH = '.agentxchain/history.jsonl';
 const FILE_PREVIEW_MAX_FILES = 5;
 const FILE_PREVIEW_MAX_LINES = 120;
+const PROPOSAL_SUMMARY_MAX_LINES = 80;
 const GATE_FILE_PREVIEW_MAX_LINES = 60;
 const DISPATCH_LOG_MAX_LINES = 50;
 const DISPATCH_LOG_MAX_LINE_BYTES = 8192;
@@ -229,6 +230,21 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
     lines.push('- You may propose changes as patches but cannot directly commit.');
     lines.push('- Your artifact type should be `patch`.');
+    if (runtimeType === 'api_proxy') {
+      lines.push('- **This runtime cannot write repo files directly.** When doing work, you MUST return proposed changes as structured JSON.');
+      lines.push('- Include a `proposed_changes` array in your turn result with each file change (omit or set to `[]` on completion-only turns):');
+      lines.push('  ```json');
+      lines.push('  "proposed_changes": [');
+      lines.push('    { "path": "src/lib/foo.js", "action": "create", "content": "// full file..." },');
+      lines.push('    { "path": "src/lib/bar.js", "action": "modify", "content": "// full new content..." },');
+      lines.push('    { "path": "src/old.js", "action": "delete" }');
+      lines.push('  ]');
+      lines.push('  ```');
+      lines.push('- Valid actions: `create` (new file), `modify` (replace content), `delete` (remove file).');
+      lines.push('- `content` is required for `create` and `modify` actions.');
+      lines.push('- The orchestrator will materialize your proposal to `.agentxchain/proposed/<turn_id>/` for review.');
+      lines.push('- List all proposed file paths in `files_changed`.');
+    }
     lines.push('');
   }
 
@@ -366,6 +382,22 @@ function renderPrompt(role, roleId, turn, state, config, root) {
       lines.push(`- **You are in the \`${currentPhase}\` phase (final phase).** When ready to ship, set \`run_completion_request: true\` and \`phase_transition_request: null\`.`);
     }
   }
+  // Phase-specific guidance for proposed roles
+  if (role.write_authority === 'proposed' && phaseNames.length > 0) {
+    const currentPhase = state?.phase;
+    const phaseIdx = currentPhase ? phaseNames.indexOf(currentPhase) : -1;
+    if (phaseIdx >= 0 && phaseIdx < phaseNames.length - 1) {
+      const nextPhase = phaseNames[phaseIdx + 1];
+      const currentGate = config.routing?.[currentPhase]?.exit_gate;
+      const gateClause = currentGate ? ` and the exit gate (\`${currentGate}\`) is satisfied` : '';
+      lines.push(`- **You are in the \`${currentPhase}\` phase (not final phase).** When your work is complete${gateClause}, set \`phase_transition_request: "${nextPhase}"\`.`);
+    } else if (phaseIdx >= 0 && phaseIdx === phaseNames.length - 1) {
+      lines.push(`- **You are in the \`${currentPhase}\` phase (final phase).** When ready to ship, set \`run_completion_request: true\` and \`phase_transition_request: null\`.`);
+      if (runtimeType === 'api_proxy') {
+        lines.push('- **Completion turns must be no-op:** set `proposed_changes` to `[]` or omit it, set `files_changed` to `[]`, and set `artifact.type` to `"review"`. Do NOT propose file changes on a completion turn.');
+      }
+    }
+  }
   // Phase-specific guidance for review_only roles (terminal phase ship readiness)
   if (role.write_authority === 'review_only' && phaseNames.length > 0) {
     const currentPhase = state?.phase;
@@ -467,6 +499,42 @@ function renderContext(state, config, root, turn, role) {
         }
       }
 
+      const proposalPreview = role?.write_authority === 'review_only'
+        ? buildProposalArtifactPreview(root, lastTurn)
+        : null;
+      if (proposalPreview) {
+        lines.push('### Proposed Artifact');
+        lines.push('');
+        lines.push(`- **Artifact ref:** \`${proposalPreview.artifactRef}\``);
+        lines.push(`- **Proposed files:** ${proposalPreview.changeCount}`);
+        lines.push('');
+        lines.push('```');
+        lines.push(proposalPreview.summary);
+        lines.push('```');
+        if (proposalPreview.summaryTruncated) {
+          lines.push('');
+          lines.push(`_Preview truncated after ${PROPOSAL_SUMMARY_MAX_LINES} lines._`);
+        }
+        lines.push('');
+
+        if (proposalPreview.filePreviews.length > 0) {
+          lines.push('### Proposed File Previews');
+          lines.push('');
+          for (const preview of proposalPreview.filePreviews) {
+            lines.push(`#### \`${preview.path}\` (${preview.action})`);
+            lines.push('');
+            lines.push('```');
+            lines.push(preview.content);
+            lines.push('```');
+            if (preview.truncated) {
+              lines.push('');
+              lines.push(`_Preview truncated after ${FILE_PREVIEW_MAX_LINES} lines._`);
+            }
+            lines.push('');
+          }
+        }
+      }
+
       // Verification evidence from the previous turn
       // Use raw verification (has commands, machine_evidence, evidence_summary)
       // and supplement with normalized_verification status when available
@@ -683,6 +751,113 @@ function buildChangedFilePreviews(root, filesChanged) {
   return previews;
 }
 
+function buildProposalArtifactPreview(root, lastTurn) {
+  const artifactRef = lastTurn?.artifact?.ref;
+  if (typeof artifactRef !== 'string' || !artifactRef.startsWith('.agentxchain/proposed/')) {
+    return null;
+  }
+
+  const absProposalDir = join(root, artifactRef);
+  const summaryPath = join(absProposalDir, 'PROPOSAL.md');
+
+  let summary = '';
+  let summaryTruncated = false;
+
+  if (existsSync(summaryPath)) {
+    try {
+      const raw = readFileSync(summaryPath, 'utf8');
+      const lines = raw.replace(/\r\n/g, '\n').split('\n');
+      summaryTruncated = lines.length > PROPOSAL_SUMMARY_MAX_LINES;
+      summary = (summaryTruncated ? lines.slice(0, PROPOSAL_SUMMARY_MAX_LINES) : lines)
+        .join('\n')
+        .trimEnd();
+    } catch {
+      summary = '';
+    }
+  }
+
+  const changeActions = extractProposalActions(summary);
+  const materializedFiles = collectProposalFiles(absProposalDir);
+
+  if (!summary) {
+    const fallbackLines = [
+      `# Proposed Changes — ${lastTurn.turn_id || '(unknown)'}`,
+      '',
+      lastTurn.summary || '(no summary)',
+      '',
+    ];
+    for (const filePath of materializedFiles) {
+      fallbackLines.push(`- \`${filePath}\` — ${changeActions.get(filePath) || 'create'}`);
+    }
+    summary = fallbackLines.join('\n');
+  }
+
+  const filePreviews = [];
+  for (const relPath of materializedFiles.slice(0, FILE_PREVIEW_MAX_FILES)) {
+    const absPath = join(absProposalDir, relPath);
+
+    let raw;
+    try {
+      raw = readFileSync(absPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = raw.replace(/\r\n/g, '\n').split('\n');
+    const truncated = lines.length > FILE_PREVIEW_MAX_LINES;
+    const previewLines = truncated ? lines.slice(0, FILE_PREVIEW_MAX_LINES) : lines;
+    filePreviews.push({
+      path: relPath,
+      action: changeActions.get(relPath) || 'create',
+      content: previewLines.join('\n').trimEnd(),
+      truncated,
+    });
+  }
+
+  return {
+    artifactRef,
+    summary,
+    summaryTruncated,
+    filePreviews,
+    changeCount: changeActions.size || materializedFiles.length,
+  };
+}
+
+function extractProposalActions(summary) {
+  const actions = new Map();
+  if (!summary) {
+    return actions;
+  }
+
+  const matches = summary.matchAll(/^- `([^`]+)` — ([a-z]+)/gm);
+  for (const match of matches) {
+    actions.set(match[1], match[2]);
+  }
+  return actions;
+}
+
+function collectProposalFiles(absProposalDir, relPrefix = '') {
+  if (!existsSync(absProposalDir)) {
+    return [];
+  }
+
+  const files = [];
+  for (const entry of readdirSync(absProposalDir, { withFileTypes: true })) {
+    if (entry.name === 'PROPOSAL.md') {
+      continue;
+    }
+
+    const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+    const absPath = join(absProposalDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectProposalFiles(absPath, relPath));
+    } else if (entry.isFile()) {
+      files.push(relPath);
+    }
+  }
+  return files.sort();
+}
+
 function buildDispatchLogExcerpt(root, turnId) {
   const logPath = join(root, getDispatchLogPath(turnId));
   if (!existsSync(logPath)) {

package/src/lib/governed-state.js

@@ -17,7 +17,7 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync, readdirSync, rmSync } from 'fs';
 import { join, dirname } from 'path';
-import { randomBytes } from 'crypto';
+import { randomBytes, createHash } from 'crypto';
 import { safeWriteJson } from './safe-write.js';
 import { validateStagedTurnResult } from './turn-result-validator.js';
 import { evaluatePhaseExit, evaluateRunCompletion } from './gate-evaluator.js';
@@ -155,6 +155,87 @@ function materializeDerivedReviewArtifact(root, turnResult, state, runtimeType,
   return reviewPath;
 }
 
+function materializeDerivedProposalArtifact(root, turnResult, state, runtimeType) {
+  if (turnResult?.artifact?.type !== 'patch' || runtimeType !== 'api_proxy') {
+    return null;
+  }
+  if (!Array.isArray(turnResult.proposed_changes) || turnResult.proposed_changes.length === 0) {
+    return null;
+  }
+
+  const proposalDir = `.agentxchain/proposed/${turnResult.turn_id}`;
+  const absProposalDir = join(root, proposalDir);
+  mkdirSync(absProposalDir, { recursive: true });
+
+  // Write PROPOSAL.md summary
+  const summaryLines = [
+    `# Proposed Changes — ${turnResult.turn_id}`,
+    '',
+    `**Role:** ${turnResult.role}`,
+    `**Runtime:** ${turnResult.runtime_id}`,
+    `**Status:** ${turnResult.status}`,
+    '',
+    `## Summary`,
+    '',
+    turnResult.summary || '(no summary)',
+    '',
+    `## Files`,
+    '',
+  ];
+  for (const change of turnResult.proposed_changes) {
+    summaryLines.push(`- \`${change.path}\` — ${change.action}`);
+  }
+  if (turnResult.decisions?.length > 0) {
+    summaryLines.push('', '## Decisions', '');
+    for (const dec of turnResult.decisions) {
+      summaryLines.push(`- **${dec.id}** (${dec.category}): ${dec.statement}`);
+    }
+  }
+  summaryLines.push('');
+  writeFileSync(join(absProposalDir, 'PROPOSAL.md'), summaryLines.join('\n'));
+  writeFileSync(
+    join(absProposalDir, 'SOURCE_SNAPSHOT.json'),
+    JSON.stringify(captureProposalSourceSnapshot(root, turnResult.proposed_changes), null, 2) + '\n',
+  );
+
+  // Materialize each proposed file (create/modify only; delete just listed)
+  for (const change of turnResult.proposed_changes) {
+    if (change.action === 'delete') continue;
+    if (typeof change.content !== 'string') continue;
+    const absFilePath = join(absProposalDir, change.path);
+    mkdirSync(dirname(absFilePath), { recursive: true });
+    writeFileSync(absFilePath, change.content);
+  }
+
+  turnResult.artifact = { ...(turnResult.artifact || {}), ref: proposalDir };
+  return proposalDir;
+}
+
+function captureProposalSourceSnapshot(root, proposedChanges) {
+  return {
+    captured_at: new Date().toISOString(),
+    files: proposedChanges.map((change) => {
+      const absFilePath = join(root, change.path);
+      if (!existsSync(absFilePath)) {
+        return {
+          path: change.path,
+          action: change.action,
+          existed: false,
+          sha256: null,
+        };
+      }
+
+      const content = readFileSync(absFilePath);
+      return {
+        path: change.path,
+        action: change.action,
+        existed: true,
+        sha256: `sha256:${createHash('sha256').update(content).digest('hex')}`,
+      };
+    }),
+  };
+}
+
 function normalizeActiveTurns(activeTurns) {
   if (!activeTurns || typeof activeTurns !== 'object' || Array.isArray(activeTurns)) {
     return {};
@@ -229,6 +310,60 @@ export function deriveRetainedTurnRecoveryCommand(state, config, options = {}) {
   return command;
 }
 
+export function deriveBlockedRecoveryCommand(state, config, options = {}) {
+  const turnRetained = typeof options.turnRetained === 'boolean'
+    ? options.turnRetained
+    : getActiveTurnCount(state) > 0;
+  if (!turnRetained) {
+    return options.clearedCommand || 'agentxchain resume';
+  }
+
+  return deriveRetainedTurnRecoveryCommand(state, config, {
+    turnId: options.turnId,
+    fallbackCommand: options.fallbackCommand || 'agentxchain step --resume',
+    manualCommand: options.manualCommand || 'agentxchain resume',
+    automatedCommand: options.automatedCommand || 'agentxchain step --resume',
+  });
+}
+
+export function deriveNeedsHumanRecoveryAction(state, config, options = {}) {
+  const command = deriveBlockedRecoveryCommand(state, config, {
+    turnRetained: options.turnRetained,
+    turnId: options.turnId,
+  });
+  return `Resolve the stated issue, then run ${command}`;
+}
+
+export function deriveDispatchRecoveryAction(state, config, options = {}) {
+  const command = deriveBlockedRecoveryCommand(state, config, {
+    turnRetained: options.turnRetained,
+    turnId: options.turnId,
+  });
+  return `Resolve the dispatch issue, then run ${command}`;
+}
+
+export function deriveHookTamperRecoveryAction(state, config, options = {}) {
+  const command = deriveBlockedRecoveryCommand(state, config, {
+    turnRetained: options.turnRetained,
+    turnId: options.turnId,
+  });
+  return `Disable or fix the hook, verify protected files, then run ${command}`;
+}
+
+export function deriveAfterDispatchHookRecoveryAction(state, config, options = {}) {
+  const command = deriveBlockedRecoveryCommand(state, config, {
+    turnRetained: options.turnRetained,
+    turnId: options.turnId,
+  });
+  return `Fix or reconfigure the hook, then rerun ${command}`;
+}
+
+export function deriveConflictLoopRecoveryAction(turnId) {
+  return turnId
+    ? `Serialize the conflicting work, then run agentxchain reject-turn --turn ${turnId} --reassign`
+    : 'Serialize the conflicting work, then run agentxchain reject-turn --reassign';
+}
+
 function isLegacyEscalationRecoveryAction(action) {
   return action === 'Resolve the escalation, then run agentxchain step --resume'
     || action === 'Resolve the escalation, then run agentxchain step';
@@ -857,7 +992,7 @@ function deriveHookRecovery(state, { phase, hookName, detail, errorCode, turnId,
     typed_reason: isTamper ? 'hook_tamper' : 'hook_block',
     owner: 'human',
     recovery_action: isTamper
-      ? 'Disable or fix the hook, verify protected files, then run agentxchain step --resume'
+      ? deriveHookTamperRecoveryAction(state, null, { turnRetained, turnId })
       : `Fix or reconfigure hook "${hookName}", then rerun agentxchain accept-turn${turnId ? ` --turn ${turnId}` : ''}`,
     turn_retained: Boolean(turnRetained),
     detail: detail || hookName || phase,
@@ -936,30 +1071,80 @@ function normalizeRecoveryDescriptor(recovery, turnRetained, detail) {
   };
 }
 
-export function reconcileEscalationRecoveryWithConfig(state, config) {
+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 isLegacyAfterDispatchHookBlockRecoveryAction(action) {
+  return action === 'Fix or reconfigure the hook, then rerun agentxchain resume';
+}
+
+function isLegacyConflictLoopRecoveryAction(action) {
+  return typeof action === 'string' && action.startsWith('Serialize the conflicting work, then run agentxchain step --resume');
+}
+
+export function reconcileRecoveryActionsWithConfig(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,
-  });
+  const turnId = state.blocked_reason?.turn_id ?? state.escalation?.from_turn_id ?? null;
+
+  let shouldRefresh = false;
+  let nextAction = null;
+
+  if (typedReason === 'operator_escalation' || typedReason === 'retries_exhausted') {
+    shouldRefresh = typedReason === 'retries_exhausted' || isLegacyEscalationRecoveryAction(currentAction);
+    if (shouldRefresh) {
+      nextAction = deriveEscalationRecoveryAction(state, config, {
+        turnRetained,
+        turnId,
+      });
+    }
+  } else if (typedReason === 'needs_human') {
+    shouldRefresh = isLegacyNeedsHumanRecoveryAction(currentAction);
+    if (shouldRefresh) {
+      nextAction = deriveNeedsHumanRecoveryAction(state, config, {
+        turnRetained,
+        turnId,
+      });
+    }
+  } else if (typedReason === 'hook_tamper') {
+    shouldRefresh = isLegacyHookTamperRecoveryAction(currentAction);
+    if (shouldRefresh) {
+      nextAction = deriveHookTamperRecoveryAction(state, config, {
+        turnRetained,
+        turnId,
+      });
+    }
+  } else if (typedReason === 'hook_block') {
+    shouldRefresh = isLegacyAfterDispatchHookBlockRecoveryAction(currentAction);
+    if (shouldRefresh) {
+      nextAction = deriveAfterDispatchHookRecoveryAction(state, config, {
+        turnRetained,
+        turnId,
+      });
+    }
+  } else if (typedReason === 'conflict_loop') {
+    shouldRefresh = isLegacyConflictLoopRecoveryAction(currentAction);
+    if (shouldRefresh) {
+      nextAction = deriveConflictLoopRecoveryAction(turnId);
+    }
+  }
+
+  if (!shouldRefresh || !nextAction) {
+    return { state, changed: false };
+  }
 
   let nextState = state;
   let changed = false;
@@ -1015,7 +1200,10 @@ function inferBlockedReasonFromState(state) {
       recovery: {
         typed_reason: 'needs_human',
         owner: 'human',
-        recovery_action: 'Resolve the stated issue, then run agentxchain step --resume',
+        recovery_action: deriveNeedsHumanRecoveryAction(state, null, {
+          turnRetained,
+          turnId: activeTurn?.turn_id ?? state.blocked_reason?.turn_id ?? null,
+        }),
         turn_retained: turnRetained,
         detail,
       },
@@ -1049,7 +1237,10 @@ function inferBlockedReasonFromState(state) {
       recovery: {
         typed_reason: 'dispatch_error',
         owner: 'human',
-        recovery_action: 'Resolve the dispatch issue, then run agentxchain step --resume',
+        recovery_action: deriveDispatchRecoveryAction(state, null, {
+          turnRetained,
+          turnId: activeTurn?.turn_id ?? state.blocked_reason?.turn_id ?? null,
+        }),
         turn_retained: turnRetained,
         detail,
       },
@@ -1802,6 +1993,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const runtime = config.runtimes?.[runtimeId];
   const runtimeType = runtime?.type || 'manual';
   materializeDerivedReviewArtifact(root, turnResult, state, runtimeType, baseline);
+  materializeDerivedProposalArtifact(root, turnResult, state, runtimeType);
   const writeAuthority = role?.write_authority || 'review_only';
   const diffComparison = compareDeclaredVsObserved(
     turnResult.files_changed || [],
@@ -1859,7 +2051,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         recovery: {
           typed_reason: 'conflict_loop',
           owner: 'human',
-          recovery_action: `Serialize the conflicting work, then run agentxchain step --resume --turn ${currentTurn.turn_id}`,
+          recovery_action: deriveConflictLoopRecoveryAction(currentTurn.turn_id),
           turn_retained: true,
           detail: buildConflictDetail(conflict),
         },
@@ -2018,7 +2210,10 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       recovery: {
         typed_reason: 'needs_human',
         owner: 'human',
-        recovery_action: 'Resolve the stated issue, then run agentxchain step --resume',
+        recovery_action: deriveNeedsHumanRecoveryAction(updatedState, config, {
+          turnRetained: false,
+          turnId: turnResult.turn_id,
+        }),
         turn_retained: false,
         detail: turnResult.needs_human_reason || 'unspecified',
       },

package/src/lib/normalized-config.js

@@ -389,11 +389,11 @@ export function validateV4Config(data, projectRoot) {
           errors.push(`Role "${id}" is review_only but uses local_cli runtime "${role.runtime}" — review_only roles should not have authoritative write access`);
         }
       }
-      // v1 api_proxy restriction: only review_only roles may bind to api_proxy runtimes (Session #19 freeze)
+      // api_proxy restriction: only review_only and proposed roles may bind to api_proxy runtimes
       if (role.runtime && data.runtimes[role.runtime]) {
         const rt = data.runtimes[role.runtime];
-        if (rt.type === 'api_proxy' && role.write_authority !== 'review_only') {
-          errors.push(`Role "${id}" has write_authority "${role.write_authority}" but uses api_proxy runtime "${role.runtime}" — v1 api_proxy only supports review_only roles`);
+        if (rt.type === 'api_proxy' && role.write_authority !== 'review_only' && role.write_authority !== 'proposed') {
+          errors.push(`Role "${id}" has write_authority "${role.write_authority}" but uses api_proxy runtime "${role.runtime}" — api_proxy only supports review_only and proposed roles`);
         }
       }
     }