@resolveio/server-lib 22.3.149 → 22.3.150

package/src/util/ai-runner-manager-policy.ts

@@ -0,0 +1,2733 @@
+export type ResolveIOAIManagerAction =
+	| 'continue'
+	| 'retry_infra'
+	| 'reset_loop_budget'
+	| 'park_repeated_failure'
+	| 'park_ping_pong'
+	| 'manual_handoff';
+
+export interface ResolveIOAIManagerFailureRecord {
+	outcome?: string;
+	lane?: string;
+	stepType?: string;
+	failureClass?: string;
+	blocker?: string;
+	blockerFingerprint?: string;
+	evidenceHash?: string;
+	changedFiles?: string[];
+	artifactPaths?: string[];
+	summary?: string;
+	recordedAt?: Date | string;
+}
+
+export type ResolveIOAIManagerEvidenceStrength = 'none' | 'weak' | 'material' | 'proof';
+
+export interface ResolveIOAIManagerEvidenceAssessment {
+	changed: boolean;
+	material: boolean;
+	strength: ResolveIOAIManagerEvidenceStrength;
+	signals: string[];
+	evidenceHash: string;
+	blockerFingerprint: string;
+}
+
+export type ResolveIOAIManagerRecoveryClass =
+	| 'advance_after_proof'
+	| 'diagnosis_only'
+	| 'diagnosis_revision'
+	| 'infra_repair'
+	| 'compile_repair'
+	| 'journey_contract_repair'
+	| 'business_proof_repair'
+	| 'release_repair'
+	| 'product_code_repair'
+	| 'blocked_until_new_evidence'
+	| 'manual_handoff'
+	| 'continue';
+
+export interface ResolveIOAIManagerRecoveryPlan {
+	recoveryClass: ResolveIOAIManagerRecoveryClass;
+	lane: string;
+	stepType: string;
+	nextActionLabel: string;
+	objective: string;
+	allowedAction: string;
+	productRepairAllowed: boolean;
+	expensiveModelAllowed: boolean;
+	maxAttemptsBeforePark: number;
+	finiteSteps: string[];
+	requiredEvidence: string[];
+	loopResetEvidence: string[];
+	forbiddenActions: string[];
+	notes: string[];
+}
+
+export type ResolveIOAIManagerRecoveryCheckpointStatus =
+	| 'active'
+	| 'parked'
+	| 'manual_handoff'
+	| 'complete';
+
+export interface ResolveIOAIManagerRecoveryCheckpoint {
+	checkpointId: string;
+	recoveryClass: ResolveIOAIManagerRecoveryClass;
+	status: ResolveIOAIManagerRecoveryCheckpointStatus;
+	lane: string;
+	stepType: string;
+	allowedAction: string;
+	productRepairAllowed: boolean;
+	expensiveModelAllowed: boolean;
+	attempts: number;
+	maxAttemptsBeforePark: number;
+	blockerFingerprint: string;
+	evidenceHash: string;
+	changedFiles: string[];
+	artifactPaths: string[];
+	requiredEvidence: string[];
+	loopResetEvidence: string[];
+	forbiddenActions: string[];
+	objective: string;
+	nextActionLabel: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export type ResolveIOAIManagerRecoveryEvidenceProbeStepKind =
+	| 'read_only_diagnosis'
+	| 'rerun_same_gate'
+	| 'infra_preflight'
+	| 'compile_check'
+	| 'route_probe'
+	| 'business_assertion'
+	| 'journey_validation'
+	| 'release_status'
+	| 'diff_scope_check'
+	| 'operator_review';
+
+export interface ResolveIOAIManagerRecoveryEvidenceProbeStep {
+	id: string;
+	kind: ResolveIOAIManagerRecoveryEvidenceProbeStepKind;
+	label: string;
+	objective: string;
+	required: boolean;
+	commandHint?: string;
+	artifactExpectation: string;
+	successSignal: string;
+}
+
+export interface ResolveIOAIManagerRecoveryEvidenceProbe {
+	probeId: string;
+	checkpointId: string;
+	recoveryClass: ResolveIOAIManagerRecoveryClass;
+	lane: string;
+	stepType: string;
+	objective: string;
+	evidenceOnly: boolean;
+	productRepairAllowed: boolean;
+	expensiveModelAllowed: boolean;
+	evidenceHashBefore: string;
+	blockerFingerprint: string;
+	steps: ResolveIOAIManagerRecoveryEvidenceProbeStep[];
+	requiredArtifacts: string[];
+	acceptanceEvidence: string[];
+	stopConditions: string[];
+	loopResetEvidence: string[];
+	createdAt: string;
+}
+
+export type ResolveIOAIManagerRecoveryAutomationMode =
+	| 'advance'
+	| 'collect_evidence'
+	| 'read_only_diagnosis'
+	| 'repair_infra'
+	| 'repair_compile'
+	| 'repair_journey_contract'
+	| 'repair_business_assertion'
+	| 'repair_release'
+	| 'targeted_product_repair'
+	| 'manual_review'
+	| 'continue_gate';
+
+export interface ResolveIOAIManagerRecoveryActionRetryPolicy {
+	allowImmediateRetry: boolean;
+	requireNewEvidence: boolean;
+	resetLoopWhen: string[];
+	stopWhen: string[];
+}
+
+export type ResolveIOAIManagerHotfixFirstReleaseAction =
+	| 'wait_for_active_deploy'
+	| 'block_duplicate_deploy'
+	| 'block_duplicate_publish'
+	| 'review_force_deploy'
+	| 'hotfix_release_artifact'
+	| 'deploy_new_artifact_after_release_gate'
+	| 'build_artifact_first';
+
+export type ResolveIOAIManagerHotfixChannel =
+	| 'static_ui'
+	| 'backend_js'
+	| 'config'
+	| 'seed_data'
+	| 'cache_invalidation'
+	| 'service_restart'
+	| 'release_artifact'
+	| 'force_deploy_review'
+	| 'new_artifact_deploy'
+	| 'artifact_build';
+
+export interface ResolveIOAIManagerHotfixPlanStep {
+	id: string;
+	label: string;
+	channel: ResolveIOAIManagerHotfixChannel;
+	safeToAutoRun: boolean;
+	requiresFullDeploy: boolean;
+	requiredEvidence: string[];
+	successEvidence: string[];
+	blockedBy: string[];
+}
+
+export interface ResolveIOAIManagerHotfixPlan {
+	planId: string;
+	label: string;
+	recommendedChannel: ResolveIOAIManagerHotfixChannel;
+	reason: string;
+	fullDeployAvoided: boolean;
+	steps: ResolveIOAIManagerHotfixPlanStep[];
+	acceptanceEvidence: string[];
+	escalationTriggers: string[];
+}
+
+export interface ResolveIOAIManagerHotfixFirstReleasePolicyInput {
+	surface?: string;
+	activeDeploy?: boolean;
+	deployFingerprint?: string;
+	lastDeployFingerprint?: string;
+	publishFingerprint?: string;
+	lastPublishFingerprint?: string;
+	deployStatus?: string;
+	publishStatus?: string;
+	sampleDataStatus?: string;
+	forceDeploy?: boolean;
+	forcePublish?: boolean;
+	hasNewArtifact?: boolean;
+}
+
+export interface ResolveIOAIManagerHotfixFirstReleasePolicy {
+	policy: 'hotfix_first';
+	surface: string;
+	recommendedAction: ResolveIOAIManagerHotfixFirstReleaseAction;
+	label: string;
+	reason: string;
+	hotfixPreferred: boolean;
+	fullDeployAllowed: boolean;
+	duplicateDeployBlocked: boolean;
+	duplicatePublishBlocked: boolean;
+	forceDeployRequiredToRepeat: boolean;
+	forcePublishRequiredToRepeat: boolean;
+	statuses: {
+		deploy: string;
+		publish: string;
+		sampleData: string;
+	};
+	fingerprints: {
+		current: string;
+		last: string;
+		matchesLast: boolean;
+		publishCurrent: string;
+		publishLast: string;
+		publishMatchesLast: boolean;
+	};
+	hotfixPlan: ResolveIOAIManagerHotfixPlan;
+	allowedActions: string[];
+	forbiddenActions: string[];
+	requiredEvidence: string[];
+}
+
+export interface ResolveIOAIManagerRecoveryActionPacket {
+	actionId: string;
+	checkpointId: string;
+	probeId: string;
+	recoveryClass: ResolveIOAIManagerRecoveryClass;
+	mode: ResolveIOAIManagerRecoveryAutomationMode;
+	label: string;
+	lane: string;
+	stepType: string;
+	primaryStepKind: ResolveIOAIManagerRecoveryEvidenceProbeStepKind | 'none';
+	objective: string;
+	evidenceOnly: boolean;
+	autoRunnable: boolean;
+	productRepairAllowed: boolean;
+	expensiveModelAllowed: boolean;
+	canResetLoopAfterEvidence: boolean;
+	maxAttemptsBeforePark: number;
+	requiredArtifacts: string[];
+	nextCommands: string[];
+	successCriteria: string[];
+	retryPolicy: ResolveIOAIManagerRecoveryActionRetryPolicy;
+	releasePolicy?: ResolveIOAIManagerHotfixFirstReleasePolicy;
+	blockedReason?: string;
+	createdAt: string;
+}
+
+export type ResolveIOAIManagerRecoveryActionDispatchAction =
+	| 'run_evidence_probe'
+	| 'run_read_only_diagnosis'
+	| 'run_infra_repair'
+	| 'run_compile_repair'
+	| 'run_journey_contract_repair'
+	| 'run_business_assertion_repair'
+	| 'run_release_repair'
+	| 'run_targeted_product_repair'
+	| 'advance'
+	| 'continue_gate'
+	| 'park_manual';
+
+export interface ResolveIOAIManagerAutoDispatchPolicyInput {
+	dispatchAction?: ResolveIOAIManagerRecoveryActionDispatchAction | string;
+	directive?: Partial<ResolveIOAIManagerRecoveryExecutionDirective>;
+	action?: Partial<ResolveIOAIManagerRecoveryActionPacket>;
+	includeJourneyContractRepair?: boolean;
+	includeReleaseRepair?: boolean;
+	includeBusinessProofRepair?: boolean;
+	includeProductRepair?: boolean;
+}
+
+export type ResolveIOAIManagerRecoveryActionDispatchStatus =
+	| 'queued'
+	| 'started'
+	| 'completed'
+	| 'failed'
+	| 'parked';
+
+export interface ResolveIOAIManagerRecoveryActionDispatchRecord {
+	dispatchId: string;
+	actionId: string;
+	checkpointId: string;
+	probeId: string;
+	mode: ResolveIOAIManagerRecoveryAutomationMode;
+	dispatchAction: ResolveIOAIManagerRecoveryActionDispatchAction;
+	status: ResolveIOAIManagerRecoveryActionDispatchStatus;
+	evidenceHash: string;
+	blockerFingerprint: string;
+	productRepairAllowed: boolean;
+	expensiveModelAllowed: boolean;
+	reason: string;
+	artifactPaths: string[];
+	startedAt?: string;
+	completedAt?: string;
+	createdAt: string;
+}
+
+export interface ResolveIOAIManagerRecoveryActionDispatchInput {
+	action?: ResolveIOAIManagerRecoveryActionPacket;
+	history?: ResolveIOAIManagerRecoveryActionDispatchRecord[];
+	current?: ResolveIOAIManagerFailureRecord;
+	operatorApproved?: boolean;
+	now?: Date | string;
+}
+
+export interface ResolveIOAIManagerRecoveryActionDispatchDecision {
+	dispatchAction: ResolveIOAIManagerRecoveryActionDispatchAction;
+	allowed: boolean;
+	reason: string;
+	status: ResolveIOAIManagerRecoveryActionDispatchStatus;
+	canRunProductRepair: boolean;
+	canRunExpensiveModel: boolean;
+	shouldRecordDispatch: boolean;
+	requiresNewEvidence: boolean;
+	newEvidence: boolean;
+	dispatchRecord?: ResolveIOAIManagerRecoveryActionDispatchRecord;
+}
+
+export type ResolveIOAIManagerRecoveryExecutionPhase =
+	| 'evidence'
+	| 'diagnosis'
+	| 'infra'
+	| 'compile'
+	| 'journey'
+	| 'business_proof'
+	| 'release'
+	| 'product_repair'
+	| 'advance'
+	| 'manual';
+
+export interface ResolveIOAIManagerRecoveryExecutionDirectiveInput {
+	action?: ResolveIOAIManagerRecoveryActionPacket;
+	dispatchDecision?: ResolveIOAIManagerRecoveryActionDispatchDecision;
+	current?: ResolveIOAIManagerFailureRecord;
+	surface?: string;
+	now?: Date | string;
+}
+
+export interface ResolveIOAIManagerRecoveryExecutionDirective {
+	directiveId: string;
+	surface: string;
+	dispatchAction: ResolveIOAIManagerRecoveryActionDispatchAction;
+	phase: ResolveIOAIManagerRecoveryExecutionPhase;
+	allowed: boolean;
+	status: ResolveIOAIManagerRecoveryActionDispatchStatus;
+	reason: string;
+	lane: string;
+	stepType: string;
+	nextActionLabel: string;
+	rerunReason: string;
+	evidenceOnly: boolean;
+	autoRunnable: boolean;
+	productRepairAllowed: boolean;
+	expensiveModelAllowed: boolean;
+	canRunProductRepair: boolean;
+	canRunExpensiveModel: boolean;
+	canResetLoopAfterEvidence: boolean;
+	requiresNewEvidence: boolean;
+	newEvidence: boolean;
+	maxAttemptsBeforePark: number;
+	requiredArtifacts: string[];
+	nextCommands: string[];
+	successCriteria: string[];
+	forbiddenActions: string[];
+	dispatchRecord?: ResolveIOAIManagerRecoveryActionDispatchRecord;
+	releasePolicy?: ResolveIOAIManagerHotfixFirstReleasePolicy;
+	createdAt: string;
+}
+
+export interface ResolveIOAIManagerRecoveryCheckpointInput {
+	plan: ResolveIOAIManagerRecoveryPlan;
+	current?: ResolveIOAIManagerFailureRecord;
+	previousCheckpoint?: ResolveIOAIManagerRecoveryCheckpoint;
+	now?: Date | string;
+}
+
+export type ResolveIOAIManagerRecoveryGateAction =
+	| 'allow'
+	| 'collect_new_evidence'
+	| 'reject_action'
+	| 'manual_handoff'
+	| 'complete';
+
+export interface ResolveIOAIManagerRecoveryGateInput {
+	checkpoint: ResolveIOAIManagerRecoveryCheckpoint;
+	current?: ResolveIOAIManagerFailureRecord;
+	proposedAction?: string;
+	operatorApproved?: boolean;
+	now?: Date | string;
+}
+
+export interface ResolveIOAIManagerRecoveryGateDecision {
+	action: ResolveIOAIManagerRecoveryGateAction;
+	reason: string;
+	canRunProductRepair: boolean;
+	canRunExpensiveModel: boolean;
+	shouldResetLoopBudget: boolean;
+	shouldIncrementAttempt: boolean;
+	newEvidence: boolean;
+	materialEvidence: boolean;
+	evidenceStrength: ResolveIOAIManagerEvidenceStrength;
+	evidenceSignals: string[];
+	blockerFingerprint: string;
+	evidenceHash: string;
+	missingEvidence: string[];
+	checkpoint: ResolveIOAIManagerRecoveryCheckpoint;
+}
+
+export interface ResolveIOAIManagerRecoveryEvidenceProbeInput {
+	checkpoint: ResolveIOAIManagerRecoveryCheckpoint;
+	current?: ResolveIOAIManagerFailureRecord;
+	now?: Date | string;
+}
+
+export interface ResolveIOAIManagerRecoveryActionPacketInput {
+	plan?: ResolveIOAIManagerRecoveryPlan;
+	checkpoint: ResolveIOAIManagerRecoveryCheckpoint;
+	probe?: ResolveIOAIManagerRecoveryEvidenceProbe;
+	current?: ResolveIOAIManagerFailureRecord;
+	now?: Date | string;
+}
+
+export interface ResolveIOAIManagerRecoveryPlanInput {
+	action?: ResolveIOAIManagerAction | string;
+	reason?: string;
+	failureClass?: string;
+	lane?: string;
+	stepType?: string;
+	blocker?: string;
+	sameFailureCount?: number;
+	pingPongCount?: number;
+	newEvidence?: boolean;
+	productRepairFailure?: boolean;
+	changedFiles?: string[];
+	artifactPaths?: string[];
+	maxSameFailureRepeats?: number;
+}
+
+export interface ResolveIOAIManagerPolicyInput {
+	history?: ResolveIOAIManagerFailureRecord[];
+	current?: ResolveIOAIManagerFailureRecord;
+	maxSameFailureRepeats?: number;
+	maxPingPongTransitions?: number;
+	infraFailureClasses?: string[];
+	ignoredFailureClasses?: string[];
+}
+
+export interface ResolveIOAIManagerPolicyDecision {
+	action: ResolveIOAIManagerAction;
+	reason: string;
+	failureClass: string;
+	blockerFingerprint: string;
+	evidenceHash: string;
+	sameFailureCount: number;
+	pingPongCount: number;
+	newEvidence: boolean;
+	materialEvidence: boolean;
+	evidenceStrength: ResolveIOAIManagerEvidenceStrength;
+	evidenceSignals: string[];
+	loopBudgetShouldReset: boolean;
+	productRepairFailure: boolean;
+	recoveryPlan: ResolveIOAIManagerRecoveryPlan;
+	recoveryCheckpoint: ResolveIOAIManagerRecoveryCheckpoint;
+	recoveryEvidenceProbe: ResolveIOAIManagerRecoveryEvidenceProbe;
+	recoveryAction: ResolveIOAIManagerRecoveryActionPacket;
+}
+
+export interface ResolveIOAIManagerRecoveryReplayMatrixInput {
+	surface?: string;
+	includeJourneyContractRepair?: boolean;
+	includeReleaseRepair?: boolean;
+	includeProductRepair?: boolean;
+	maxSameFailureRepeats?: number;
+}
+
+export interface ResolveIOAIManagerRecoveryReplayCase {
+	caseId: string;
+	surface: string;
+	pass: boolean;
+	action: string;
+	reason: string;
+	recoveryClass: string;
+	dispatchAction: string;
+	safeAutoDispatch: boolean;
+	expectedSafeAutoDispatch: boolean;
+	productRepairAllowed: boolean;
+	loopBudgetShouldReset: boolean;
+	materialEvidence: boolean;
+	evidenceStrength: ResolveIOAIManagerEvidenceStrength;
+	hotfixFirst?: boolean;
+	fullDeployAllowed?: boolean;
+	details?: Record<string, any>;
+}
+
+function cleanText(value: any, max = 2000): string {
+	return String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+function cleanList(values: any, limit = 40, max = 500): string[] {
+	if (!Array.isArray(values)) {
+		return [];
+	}
+	const result: string[] = [];
+	for (const value of values) {
+		const normalized = cleanText(value, max);
+		if (normalized && !result.includes(normalized)) {
+			result.push(normalized);
+		}
+		if (result.length >= limit) {
+			break;
+		}
+	}
+	return result;
+}
+
+function releaseStatusIsBlocked(value: string): boolean {
+	return /fail|error|blocked|missing|empty|not ready|not_ready|denied|invalid|timeout|stale/i.test(value);
+}
+
+function releaseStatusIsTerminalDeploy(value: string): boolean {
+	return /requested|queued|in.?progress|completed|complete|success|succeeded|pass|passed|published|deployed|failed|error|blocked/i.test(value);
+}
+
+function buildReleaseAllowedActions(action: ResolveIOAIManagerHotfixFirstReleaseAction): string[] {
+	if (action === 'wait_for_active_deploy') {
+		return ['wait_for_current_deploy_result', 'collect_current_deploy_log', 'refresh_release_snapshot'];
+	}
+	if (action === 'block_duplicate_deploy') {
+		return ['collect_existing_deploy_evidence', 'hotfix_release_artifact', 'request_force_deploy_with_reason'];
+	}
+	if (action === 'block_duplicate_publish') {
+		return ['collect_existing_publish_evidence', 'hotfix_release_artifact', 'request_force_publish_with_reason'];
+	}
+	if (action === 'review_force_deploy') {
+		return ['verify_force_deploy_reason', 'rerun_failed_release_gate_once', 'record_force_deploy_evidence'];
+	}
+	if (action === 'deploy_new_artifact_after_release_gate') {
+		return ['verify_new_artifact_fingerprint', 'run_release_gate_once', 'record_publish_deploy_evidence'];
+	}
+	if (action === 'build_artifact_first') {
+		return ['build_missing_release_artifact', 'record_artifact_fingerprint', 'run_release_gate_once'];
+	}
+	return ['hotfix_live_runner_or_release_artifact', 'rerun_failed_release_gate_only', 'record_release_evidence'];
+}
+
+function hotfixStep(
+	id: string,
+	label: string,
+	channel: ResolveIOAIManagerHotfixChannel,
+	options: {
+		safeToAutoRun?: boolean;
+		requiresFullDeploy?: boolean;
+		requiredEvidence?: string[];
+		successEvidence?: string[];
+		blockedBy?: string[];
+	} = {}
+): ResolveIOAIManagerHotfixPlanStep {
+	return {
+		id,
+		label,
+		channel,
+		safeToAutoRun: options.safeToAutoRun === true,
+		requiresFullDeploy: options.requiresFullDeploy === true,
+		requiredEvidence: options.requiredEvidence || [],
+		successEvidence: options.successEvidence || [],
+		blockedBy: options.blockedBy || []
+	};
+}
+
+function buildHotfixFirstReleasePlan(input: {
+	action: ResolveIOAIManagerHotfixFirstReleaseAction;
+	surface: string;
+	reason: string;
+	releaseBlocked: boolean;
+}): ResolveIOAIManagerHotfixPlan {
+	const surface = cleanText(input.surface || 'runner', 80)
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '_')
+		.replace(/^_+|_+$/g, '') || 'runner';
+	const commonAcceptance = [
+		'failed release gate is rerun once and passes',
+		'artifact fingerprint or hotfix evidence is recorded',
+		'operator console shows no active duplicate deploy blocker'
+	];
+	if (input.action === 'wait_for_active_deploy') {
+		return {
+			planId: `${surface}:wait_for_active_deploy`,
+			label: 'Wait For Active Deploy',
+			recommendedChannel: 'release_artifact',
+			reason: input.reason,
+			fullDeployAvoided: true,
+			steps: [
+				hotfixStep('collect_active_deploy_log', 'Collect active deploy log', 'release_artifact', {
+					safeToAutoRun: true,
+					requiredEvidence: ['active deploy id or release operation id'],
+					successEvidence: ['terminal deploy status and release log captured']
+				})
+			],
+			acceptanceEvidence: commonAcceptance,
+			escalationTriggers: ['active deploy exceeds timeout', 'active deploy fails without a release log']
+		};
+	}
+	if (input.action === 'deploy_new_artifact_after_release_gate') {
+		return {
+			planId: `${surface}:deploy_new_artifact_after_release_gate`,
+			label: 'Deploy New Artifact After Release Gate',
+			recommendedChannel: 'new_artifact_deploy',
+			reason: input.reason,
+			fullDeployAvoided: false,
+			steps: [
+				hotfixStep('verify_new_artifact_fingerprint', 'Verify new artifact fingerprint', 'new_artifact_deploy', {
+					safeToAutoRun: true,
+					requiresFullDeploy: true,
+					requiredEvidence: ['current artifact fingerprint differs from last deployed fingerprint'],
+					successEvidence: ['release gate permits one full deploy']
+				})
+			],
+			acceptanceEvidence: [
+				'new artifact fingerprint recorded',
+				'release gate passed before full deploy',
+				'deploy/publish result recorded'
+			],
+			escalationTriggers: ['artifact fingerprint matches last deploy', 'release gate fails']
+		};
+	}
+	if (input.action === 'build_artifact_first') {
+		return {
+			planId: `${surface}:build_artifact_first`,
+			label: 'Build Artifact First',
+			recommendedChannel: 'artifact_build',
+			reason: input.reason,
+			fullDeployAvoided: true,
+			steps: [
+				hotfixStep('build_once_record_fingerprint', 'Build once and record fingerprint', 'artifact_build', {
+					safeToAutoRun: false,
+					requiredEvidence: ['missing artifact fingerprint', 'release gate reason for building'],
+					successEvidence: ['artifact fingerprint recorded before any deploy']
+				})
+			],
+			acceptanceEvidence: ['artifact fingerprint exists', 'no deploy queued before release gate'],
+			escalationTriggers: ['build repeats without a new fingerprint', 'build failure lacks compile log']
+		};
+	}
+	if (input.action === 'review_force_deploy') {
+		return {
+			planId: `${surface}:review_force_deploy`,
+			label: 'Review Force Deploy',
+			recommendedChannel: 'force_deploy_review',
+			reason: input.reason,
+			fullDeployAvoided: false,
+			steps: [
+				hotfixStep('verify_force_deploy_reason', 'Verify force deploy reason', 'force_deploy_review', {
+					requiredEvidence: ['explicit force_deploy reason', 'why hotfix cannot resolve the release blocker'],
+					successEvidence: ['one allowed deploy attempt is recorded with reason']
+				})
+			],
+			acceptanceEvidence: ['force deploy evidence recorded', 'duplicate fingerprint exception is auditable'],
+			escalationTriggers: ['force deploy reason is empty', 'same force deploy fails twice']
+		};
+	}
+	return {
+		planId: `${surface}:${input.action}`,
+		label: input.action === 'block_duplicate_deploy'
+			? 'Hotfix Or Force Deploy'
+			: input.action === 'block_duplicate_publish'
+				? 'Hotfix Or Force Publish'
+				: 'Hotfix Release Artifact',
+		recommendedChannel: input.action === 'block_duplicate_publish'
+			? 'release_artifact'
+			: input.releaseBlocked ? 'release_artifact' : 'static_ui',
+		reason: input.reason,
+		fullDeployAvoided: true,
+		steps: [
+			hotfixStep('static_ui_hotfix', 'Static UI hotfix', 'static_ui', {
+				safeToAutoRun: true,
+				requiredEvidence: ['built dist path', 'target S3 bucket and CloudFront distribution', 'changed frontend bundle or asset list'],
+				successEvidence: ['S3 upload result', 'CloudFront invalidation id', 'public bundle contains expected hotfix marker']
+			}),
+			hotfixStep('backend_js_hotfix', 'Backend JS hotfix', 'backend_js', {
+				requiredEvidence: ['compiled JS artifact path', 'target backend host', 'diff limited to runner/operator code'],
+				successEvidence: ['remote file checksum', 'service restart or process reload evidence', 'self-test passes']
+			}),
+			hotfixStep('config_seed_cache_restart', 'Config, seed, cache, or restart repair', 'config', {
+				safeToAutoRun: true,
+				requiredEvidence: ['exact config/seed/cache key or process name', 'why no product artifact changed'],
+				successEvidence: ['release gate rerun result', 'operator console release snapshot refreshed']
+			})
+		],
+		acceptanceEvidence: commonAcceptance,
+		escalationTriggers: [
+			'hotfix changes customer-facing product code outside the release artifact',
+			'same release gate fails twice after hotfix evidence',
+			'same publish fingerprint is retried without force_publish evidence',
+			'force deploy is requested without a reason'
+		]
+	};
+}
+
+export function buildResolveIOAIManagerHotfixFirstReleasePolicy(
+	input: ResolveIOAIManagerHotfixFirstReleasePolicyInput = {}
+): ResolveIOAIManagerHotfixFirstReleasePolicy {
+	const surface = cleanText(input.surface || 'runner', 120);
+	const deployStatus = cleanText(input.deployStatus, 160);
+	const publishStatus = cleanText(input.publishStatus, 160);
+	const sampleDataStatus = cleanText(input.sampleDataStatus, 160);
+	const deployFingerprint = cleanText(input.deployFingerprint, 240);
+	const lastDeployFingerprint = cleanText(input.lastDeployFingerprint, 240);
+	const publishFingerprint = cleanText(input.publishFingerprint, 240);
+	const lastPublishFingerprint = cleanText(input.lastPublishFingerprint, 240);
+	const fingerprintMatchesLast = !!deployFingerprint && !!lastDeployFingerprint && deployFingerprint === lastDeployFingerprint;
+	const publishFingerprintMatchesLast = !!publishFingerprint && !!lastPublishFingerprint && publishFingerprint === lastPublishFingerprint;
+	const releaseBlocked = [deployStatus, publishStatus, sampleDataStatus].some(releaseStatusIsBlocked);
+	const duplicateDeployBlocked = fingerprintMatchesLast
+		&& input.forceDeploy !== true
+		&& releaseStatusIsTerminalDeploy([deployStatus, publishStatus].filter(Boolean).join(' '));
+	const duplicatePublishBlocked = publishFingerprintMatchesLast
+		&& input.forcePublish !== true
+		&& releaseStatusIsBlocked(publishStatus)
+		&& releaseStatusIsTerminalDeploy(publishStatus);
+	let recommendedAction: ResolveIOAIManagerHotfixFirstReleaseAction = 'hotfix_release_artifact';
+	let label = 'Hotfix Release Artifact';
+	let reason = 'Repair the live runner/operator code, release config, domain, seed-data, or release artifact and rerun only the failed release gate.';
+	let fullDeployAllowed = false;
+	if (input.activeDeploy === true) {
+		recommendedAction = 'wait_for_active_deploy';
+		label = 'Wait For Active Deploy';
+		reason = 'A deploy is already queued or running; collect that result before spending another deploy cycle.';
+	}
+	else if (duplicateDeployBlocked) {
+		recommendedAction = 'block_duplicate_deploy';
+		label = 'Block Duplicate Deploy';
+		reason = 'The same artifact fingerprint already has release status; hotfix or provide explicit force_deploy evidence before rerunning it.';
+	}
+	else if (duplicatePublishBlocked) {
+		recommendedAction = 'block_duplicate_publish';
+		label = 'Block Duplicate Publish';
+		reason = 'The same publish fingerprint already has release status; hotfix the release artifact or provide explicit force_publish evidence before rerunning publish.';
+	}
+	else if ((fingerprintMatchesLast && input.forceDeploy === true) || (publishFingerprintMatchesLast && input.forcePublish === true)) {
+		recommendedAction = 'review_force_deploy';
+		label = 'Review Force Deploy';
+		reason = input.forcePublish === true
+			? 'force_publish was explicitly requested for a repeated publish artifact; require a reason and rerun only the failed release gate.'
+			: 'force_deploy was explicitly requested for a repeated artifact; require a reason and rerun only the failed release gate.';
+		fullDeployAllowed = true;
+	}
+	else if (input.hasNewArtifact === false && !releaseBlocked) {
+		recommendedAction = 'build_artifact_first';
+		label = 'Build Artifact First';
+		reason = 'No release artifact fingerprint is available yet; build once, record the fingerprint, and avoid repeated deploys.';
+	}
+	else if (input.hasNewArtifact === true && !releaseBlocked) {
+		recommendedAction = 'deploy_new_artifact_after_release_gate';
+		label = 'Deploy New Artifact After Release Gate';
+		reason = 'A new artifact can be deployed after the release gate proves the artifact is new and ready.';
+		fullDeployAllowed = true;
+	}
+	const allowedActions = buildReleaseAllowedActions(recommendedAction);
+	const hotfixPlan = buildHotfixFirstReleasePlan({
+		action: recommendedAction,
+		surface,
+		reason,
+		releaseBlocked
+	});
+	return {
+		policy: 'hotfix_first',
+		surface,
+		recommendedAction,
+		label,
+		reason,
+		hotfixPreferred: recommendedAction !== 'deploy_new_artifact_after_release_gate' && recommendedAction !== 'review_force_deploy',
+		fullDeployAllowed,
+		duplicateDeployBlocked,
+		duplicatePublishBlocked,
+		forceDeployRequiredToRepeat: true,
+		forcePublishRequiredToRepeat: true,
+		statuses: {
+			deploy: deployStatus,
+			publish: publishStatus,
+			sampleData: sampleDataStatus
+		},
+		fingerprints: {
+			current: deployFingerprint,
+			last: lastDeployFingerprint,
+			matchesLast: fingerprintMatchesLast,
+			publishCurrent: publishFingerprint,
+			publishLast: lastPublishFingerprint,
+			publishMatchesLast: publishFingerprintMatchesLast
+		},
+		hotfixPlan,
+		allowedActions,
+		forbiddenActions: [
+			'rerun full builder loop for a release-only blocker',
+			'queue duplicate deploy without force_deploy evidence',
+			'queue duplicate publish without force_publish evidence',
+			'publish/deploy again before reading the failed release log',
+			'change core workflow after business proof passed unless release evidence proves it is required'
+		],
+		requiredEvidence: [
+			'failed release gate log or active deploy result',
+			'deploy artifact fingerprint comparison',
+			'publish artifact fingerprint comparison when publish is the failed gate',
+			'hotfix/config/seed/domain change evidence when no new product artifact is needed',
+			'force_deploy or force_publish reason when repeating the same fingerprint'
+		]
+	};
+}
+
+export function isResolveIOAIManagerSafeAutoDispatch(
+	input: ResolveIOAIManagerAutoDispatchPolicyInput | ResolveIOAIManagerRecoveryActionDispatchAction | string | undefined
+): boolean {
+	const normalizedInput = typeof input === 'string'
+		? { dispatchAction: input }
+		: (input || {});
+	const dispatchAction = cleanText(normalizedInput.dispatchAction || normalizedInput.directive?.dispatchAction, 120);
+	const directiveAllowed = normalizedInput.directive?.allowed;
+	const actionAutoRunnable = normalizedInput.action?.autoRunnable;
+	const productRepairAllowed = normalizedInput.directive?.canRunProductRepair === true
+		|| normalizedInput.directive?.productRepairAllowed === true
+		|| normalizedInput.action?.productRepairAllowed === true;
+	const expensiveModelAllowed = normalizedInput.directive?.canRunExpensiveModel === true
+		|| normalizedInput.directive?.expensiveModelAllowed === true
+		|| normalizedInput.action?.expensiveModelAllowed === true;
+	if (!dispatchAction || dispatchAction === 'park_manual') {
+		return false;
+	}
+	if (directiveAllowed === false || actionAutoRunnable === false) {
+		return false;
+	}
+	if ([
+		'run_evidence_probe',
+		'run_read_only_diagnosis',
+		'run_infra_repair',
+		'run_compile_repair'
+	].includes(dispatchAction)) {
+		return true;
+	}
+	if (dispatchAction === 'run_release_repair') {
+		return normalizedInput.includeReleaseRepair !== false;
+	}
+	if (dispatchAction === 'run_journey_contract_repair') {
+		return normalizedInput.includeJourneyContractRepair !== false && productRepairAllowed !== true;
+	}
+	if (dispatchAction === 'run_business_assertion_repair') {
+		return normalizedInput.includeBusinessProofRepair === true
+			&& productRepairAllowed !== true
+			&& expensiveModelAllowed !== true;
+	}
+	if (dispatchAction === 'run_targeted_product_repair') {
+		return normalizedInput.includeProductRepair === true
+			&& productRepairAllowed === true
+			&& expensiveModelAllowed !== true;
+	}
+	return dispatchAction === 'advance' || dispatchAction === 'continue_gate';
+}
+
+function isoNow(value?: Date | string): string {
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+	const parsed = value ? new Date(value) : new Date();
+	if (Number.isFinite(parsed.getTime())) {
+		return parsed.toISOString();
+	}
+	return new Date().toISOString();
+}
+
+function stableHash(prefix: string, value: any): string {
+	const normalized = typeof value === 'string'
+		? cleanText(value, 12000)
+		: JSON.stringify(value || {});
+	let hash = 0;
+	for (let index = 0; index < normalized.length; index += 1) {
+		hash = ((hash << 5) - hash + normalized.charCodeAt(index)) | 0;
+	}
+	return `${prefix}-${Math.abs(hash).toString(36) || '0'}`;
+}
+
+export function normalizeResolveIOAIManagerFailureClass(value: any): string {
+	const normalized = cleanText(value, 80)
+		.toLowerCase()
+		.replace(/[\s-]+/g, '_');
+	if (!normalized) {
+		return 'unknown';
+	}
+	if (/^(qa_infra|infrastructure|harness|puppeteer|chrome|mongo|port|startup)$/.test(normalized)) {
+		return 'infra';
+	}
+	if (/^(build|compile|typescript|tsc|angular_build|ng_build)$/.test(normalized)) {
+		return 'compile';
+	}
+	if (/^(false_pass|route_only|missing_business_proof)$/.test(normalized)) {
+		return 'business';
+	}
+	return normalized.slice(0, 80);
+}
+
+export function fingerprintResolveIOAIManagerBlocker(value: any): string {
+	const normalized = cleanText(value, 4000)
+		.toLowerCase()
+		.replace(/[a-f0-9]{16,}/g, '<id>')
+		.replace(/\b\d{2,}\b/g, '<n>')
+		.replace(/\bline\s+<n>\b/g, 'line <n>')
+		.replace(/https?:\/\/\S+/g, '<url>')
+		.replace(/\s+/g, ' ')
+		.trim();
+	return stableHash('mgr-blocker', normalized);
+}
+
+function resolveResolveIOAIManagerBlockerFingerprint(
+	record: ResolveIOAIManagerFailureRecord | undefined,
+	fallback?: any
+): string {
+	const blockerText = cleanText(record?.blocker || record?.summary, 4000);
+	if (blockerText) {
+		return fingerprintResolveIOAIManagerBlocker(blockerText);
+	}
+	const explicit = cleanText(record?.blockerFingerprint, 120);
+	if (explicit) {
+		return explicit;
+	}
+	return fingerprintResolveIOAIManagerBlocker(fallback || '');
+}
+
+export function hashResolveIOAIManagerEvidence(record: ResolveIOAIManagerFailureRecord | undefined): string {
+	if (!record) {
+		return stableHash('mgr-evidence', '');
+	}
+	const explicit = cleanText(record.evidenceHash, 120);
+	if (explicit) {
+		return explicit;
+	}
+	return stableHash('mgr-evidence', {
+		failureClass: normalizeResolveIOAIManagerFailureClass(record.failureClass),
+		blocker: cleanText(record.blocker || record.summary, 2000),
+		changedFiles: cleanList(record.changedFiles, 80, 500).sort(),
+		artifactPaths: cleanList(record.artifactPaths, 80, 500).sort()
+	});
+}
+
+export function buildResolveIOAIManagerRecoveryCheckpoint(
+	input: ResolveIOAIManagerRecoveryCheckpointInput
+): ResolveIOAIManagerRecoveryCheckpoint {
+	const plan = input.plan;
+	const current = input.current || {};
+	const blockerFingerprint = resolveResolveIOAIManagerBlockerFingerprint(current, plan.objective);
+	const evidenceHash = hashResolveIOAIManagerEvidence(current);
+	const changedFiles = cleanList(current.changedFiles, 80, 500);
+	const artifactPaths = cleanList(current.artifactPaths, 80, 500);
+	const previous = input.previousCheckpoint;
+	const sameCheckpointBase = previous
+		&& previous.recoveryClass === plan.recoveryClass
+		&& previous.lane === plan.lane
+		&& previous.stepType === plan.stepType
+		&& previous.blockerFingerprint === blockerFingerprint
+		&& previous.evidenceHash === evidenceHash;
+	const attempts = sameCheckpointBase ? Math.max(0, Number(previous.attempts || 0)) + 1 : 1;
+	const status: ResolveIOAIManagerRecoveryCheckpointStatus = plan.recoveryClass === 'manual_handoff'
+		? 'manual_handoff'
+		: plan.recoveryClass === 'blocked_until_new_evidence'
+			? 'parked'
+			: plan.recoveryClass === 'advance_after_proof'
+				? 'complete'
+				: 'active';
+	const now = isoNow(input.now);
+	const checkpointId = stableHash('mgr-recovery', {
+		recoveryClass: plan.recoveryClass,
+		lane: plan.lane,
+		stepType: plan.stepType,
+		allowedAction: plan.allowedAction,
+		blockerFingerprint,
+		evidenceHash
+	});
+	return {
+		checkpointId,
+		recoveryClass: plan.recoveryClass,
+		status,
+		lane: plan.lane,
+		stepType: plan.stepType,
+		allowedAction: plan.allowedAction,
+		productRepairAllowed: plan.productRepairAllowed,
+		expensiveModelAllowed: plan.expensiveModelAllowed,
+		attempts,
+		maxAttemptsBeforePark: plan.maxAttemptsBeforePark,
+		blockerFingerprint,
+		evidenceHash,
+		changedFiles,
+		artifactPaths,
+		requiredEvidence: cleanList(plan.requiredEvidence, 40, 500),
+		loopResetEvidence: cleanList(plan.loopResetEvidence, 40, 500),
+		forbiddenActions: cleanList(plan.forbiddenActions, 40, 500),
+		objective: cleanText(plan.objective, 1000),
+		nextActionLabel: cleanText(plan.nextActionLabel, 160),
+		createdAt: sameCheckpointBase && previous?.createdAt ? previous.createdAt : now,
+		updatedAt: now
+	};
+}
+
+function makeRecoveryEvidenceProbeStep(
+	id: string,
+	kind: ResolveIOAIManagerRecoveryEvidenceProbeStepKind,
+	label: string,
+	objective: string,
+	artifactExpectation: string,
+	successSignal: string,
+	options: Partial<Pick<ResolveIOAIManagerRecoveryEvidenceProbeStep, 'required' | 'commandHint'>> = {}
+): ResolveIOAIManagerRecoveryEvidenceProbeStep {
+	return {
+		id,
+		kind,
+		label,
+		objective: cleanText(objective, 1000),
+		required: options.required !== false,
+		...(options.commandHint ? { commandHint: cleanText(options.commandHint, 500) } : {}),
+		artifactExpectation: cleanText(artifactExpectation, 500),
+		successSignal: cleanText(successSignal, 500)
+	};
+}
+
+function recoveryEvidenceProbeStepsFor(
+	checkpoint: ResolveIOAIManagerRecoveryCheckpoint
+): ResolveIOAIManagerRecoveryEvidenceProbeStep[] {
+	const base = [
+		makeRecoveryEvidenceProbeStep(
+			'snapshot_current_blocker',
+			'rerun_same_gate',
+			'Snapshot Current Blocker',
+			'Capture the current blocker, failure class, evidence hash, changed files, and artifact paths before any new repair.',
+			'runner-evidence/current-blocker.json',
+			'Snapshot includes the same checkpointId, blockerFingerprint, and evidenceHashBefore.'
+		)
+	];
+	if (checkpoint.recoveryClass === 'diagnosis_only' || checkpoint.recoveryClass === 'diagnosis_revision') {
+		return [
+			...base,
+			makeRecoveryEvidenceProbeStep(
+				'collect_read_only_root_cause_evidence',
+				'read_only_diagnosis',
+				'Collect Read-Only Root-Cause Evidence',
+				checkpoint.recoveryClass === 'diagnosis_revision'
+					? 'Collect new evidence that proves the current owner_files or failing_path is wrong before broadening scope.'
+					: 'Reproduce or classify the issue and record the exact customer complaint, expected result, observed result, route/module, and account context.',
+				'runner-evidence/diagnosis-readonly.md',
+				'Evidence supports one falsifiable accepted hypothesis and at least one rejected alternative.'
+			),
+			makeRecoveryEvidenceProbeStep(
+				'validate_diagnosis_gate',
+				'read_only_diagnosis',
+				'Validate Diagnosis Gate',
+				'Validate issue_case, accepted_hypothesis, rejected_alternatives, failing_path, owner_files, and before/action/after proof_plan.',
+				'runner-evidence/diagnosis-gate.json',
+				'Diagnosis gate validates before product-code repair is allowed.'
+			)
+		];
+	}
+	if (checkpoint.recoveryClass === 'infra_repair') {
+		return [
+			...base,
+			makeRecoveryEvidenceProbeStep(
+				'run_infra_preflight',
+				'infra_preflight',
+				'Run Infra Preflight',
+				'Check Puppeteer/Chrome, ports, Mongo/settings, cache state, startup commands, and server/client process health.',
+				'runner-evidence/infra-preflight.log',
+				'The same infra gate either passes or returns a new infra blocker hash.',
+				{ commandHint: 'runner preflight: puppeteer/chrome/mongo/ports/startup' }
+			)
+		];
+	}
+	if (checkpoint.recoveryClass === 'compile_repair') {
+		return [
+			...base,
+			makeRecoveryEvidenceProbeStep(
+				'rerun_compile_gate',
+				'compile_check',
+				'Rerun Compile Gate',
+				'Rerun the same deterministic compile/build command and capture the first actionable error.',
+				'runner-evidence/compile.log',
+				'Compile passes or the first failing error changes.',
+				{ commandHint: 'same finite build/compile command from the failed gate' }
+			)
+		];
+	}
+	if (checkpoint.recoveryClass === 'journey_contract_repair') {
+		return [
+			...base,
+			makeRecoveryEvidenceProbeStep(
+				'validate_journey_contract',
+				'journey_validation',
+				'Validate Journey Contract',
+				'Validate docs/APP_JOURNEY_CONTRACT.md has first/next/last workflow, route/action/method mapping, seeded data story, completion states, and QA assertions.',
+				'runner-evidence/journey-contract-validation.json',
+				'Journey contract validates before build tasks continue.'
+			),
+			makeRecoveryEvidenceProbeStep(
+				'verify_hub_workflow_mapping',
+				'journey_validation',
+				'Verify Hub Workflow Mapping',
+				'Confirm the hub CTA and screen sequence implement the journey contract instead of link-only navigation.',
+				'runner-evidence/hub-workflow-map.json',
+				'Primary hub action maps to a real route/action/method/calculation and next state.'
+			)
+		];
+	}
+	if (checkpoint.recoveryClass === 'business_proof_repair' || checkpoint.recoveryClass === 'product_code_repair') {
+		return [
+			...base,
+			makeRecoveryEvidenceProbeStep(
+				'rerun_business_assertion',
+				'business_assertion',
+				'Rerun Business Assertion',
+				'Run the exact issue/app promise proof and capture before/action/after DOM/data evidence.',
+				'runner-evidence/business-assertion.json',
+				'Business assertion passes, or the observed failure changes with a new artifact path.'
+			),
+			makeRecoveryEvidenceProbeStep(
+				'check_diff_scope',
+				'diff_scope_check',
+				'Check Diff Scope',
+				'Compare changed files against the current diagnosis/journey owner scope before another code repair.',
+				'runner-evidence/diff-scope.json',
+				'Changed files are in scope, or diagnosis/journey scope is revised with evidence.'
+			)
+		];
+	}
+	if (checkpoint.recoveryClass === 'release_repair') {
+		return [
+			...base,
+			makeRecoveryEvidenceProbeStep(
+				'collect_release_status',
+				'release_status',
+				'Collect Release Status',
+				'Collect publish/deploy/build-instance/domain/CloudFront status and the last actionable deploy error.',
+				'runner-evidence/release-status.json',
+				'Release gate passes or returns a new release blocker hash without product-code repair.'
+			)
+		];
+	}
+	if (checkpoint.recoveryClass === 'manual_handoff') {
+		return [
+			...base,
+			makeRecoveryEvidenceProbeStep(
+				'operator_review_checkpoint',
+				'operator_review',
+				'Operator Review Checkpoint',
+				'Expose budget, blocker, evidence hash, and the minimum policy/scope change needed before another expensive loop.',
+				'runner-evidence/operator-review.json',
+				'Operator approves a new scope/policy or provides new external evidence.'
+			)
+		];
+	}
+	return [
+		...base,
+		makeRecoveryEvidenceProbeStep(
+			'rerun_same_deterministic_gate',
+			'rerun_same_gate',
+			'Rerun Same Deterministic Gate',
+			'Rerun the exact failed check and capture new logs/artifacts without changing product code first.',
+			'runner-evidence/retry-gate.log',
+			'Gate passes, or evidenceHash/blockerFingerprint/artifactPaths change.'
+		)
+	];
+}
+
+export function buildResolveIOAIManagerRecoveryEvidenceProbe(
+	input: ResolveIOAIManagerRecoveryEvidenceProbeInput
+): ResolveIOAIManagerRecoveryEvidenceProbe {
+	const checkpoint = input.checkpoint;
+	const now = isoNow(input.now);
+	const steps = recoveryEvidenceProbeStepsFor(checkpoint);
+	const requiredArtifacts = Array.from(new Set(steps
+		.filter((step) => step.required)
+		.map((step) => step.artifactExpectation)
+		.filter(Boolean)));
+	return {
+		probeId: stableHash('mgr-probe', {
+			checkpointId: checkpoint.checkpointId,
+			recoveryClass: checkpoint.recoveryClass,
+			evidenceHash: checkpoint.evidenceHash,
+			blockerFingerprint: checkpoint.blockerFingerprint
+		}),
+		checkpointId: checkpoint.checkpointId,
+		recoveryClass: checkpoint.recoveryClass,
+		lane: checkpoint.lane,
+		stepType: checkpoint.stepType,
+		objective: checkpoint.status === 'parked'
+			? 'Collect new evidence before any additional expensive model/code repair.'
+			: cleanText(checkpoint.objective, 1000),
+		evidenceOnly: checkpoint.status === 'parked'
+			|| checkpoint.recoveryClass === 'diagnosis_only'
+			|| checkpoint.recoveryClass === 'diagnosis_revision'
+			|| checkpoint.recoveryClass === 'infra_repair'
+			|| checkpoint.recoveryClass === 'compile_repair'
+			|| checkpoint.recoveryClass === 'release_repair',
+		productRepairAllowed: checkpoint.productRepairAllowed && checkpoint.status !== 'parked',
+		expensiveModelAllowed: checkpoint.expensiveModelAllowed && checkpoint.status !== 'parked',
+		evidenceHashBefore: checkpoint.evidenceHash,
+		blockerFingerprint: checkpoint.blockerFingerprint,
+		steps,
+		requiredArtifacts,
+		acceptanceEvidence: Array.from(new Set([
+			...checkpoint.requiredEvidence,
+			...checkpoint.loopResetEvidence,
+			...steps.map((step) => step.successSignal)
+		].map((entry) => cleanText(entry, 500)).filter(Boolean))).slice(0, 30),
+		stopConditions: Array.from(new Set([
+			...checkpoint.forbiddenActions,
+			'no new evidence hash',
+			'no new artifact path',
+			'product-code repair requested while evidenceOnly is true'
+		].map((entry) => cleanText(entry, 500)).filter(Boolean))).slice(0, 30),
+		loopResetEvidence: checkpoint.loopResetEvidence,
+		createdAt: now
+	};
+}
+
+function recoveryAutomationModeFor(
+	checkpoint: ResolveIOAIManagerRecoveryCheckpoint
+): ResolveIOAIManagerRecoveryAutomationMode {
+	if (checkpoint.status === 'manual_handoff' || checkpoint.recoveryClass === 'manual_handoff') {
+		return 'manual_review';
+	}
+	if (checkpoint.status === 'complete' || checkpoint.recoveryClass === 'advance_after_proof') {
+		return 'advance';
+	}
+	if (checkpoint.status === 'parked' || checkpoint.recoveryClass === 'blocked_until_new_evidence') {
+		return 'collect_evidence';
+	}
+	if (checkpoint.recoveryClass === 'diagnosis_only' || checkpoint.recoveryClass === 'diagnosis_revision') {
+		return 'read_only_diagnosis';
+	}
+	if (checkpoint.recoveryClass === 'infra_repair') {
+		return 'repair_infra';
+	}
+	if (checkpoint.recoveryClass === 'compile_repair') {
+		return 'repair_compile';
+	}
+	if (checkpoint.recoveryClass === 'journey_contract_repair') {
+		return 'repair_journey_contract';
+	}
+	if (checkpoint.recoveryClass === 'business_proof_repair') {
+		return 'repair_business_assertion';
+	}
+	if (checkpoint.recoveryClass === 'release_repair') {
+		return 'repair_release';
+	}
+	if (checkpoint.recoveryClass === 'product_code_repair') {
+		return 'targeted_product_repair';
+	}
+	return 'continue_gate';
+}
+
+function recoveryActionLabelFor(mode: ResolveIOAIManagerRecoveryAutomationMode, checkpoint: ResolveIOAIManagerRecoveryCheckpoint): string {
+	const explicit = cleanText(checkpoint.nextActionLabel, 120);
+	if (explicit && mode !== 'collect_evidence') {
+		return explicit;
+	}
+	const labels: Record<ResolveIOAIManagerRecoveryAutomationMode, string> = {
+		advance: 'Advance To Next Gate',
+		collect_evidence: 'Collect New Evidence',
+		read_only_diagnosis: 'Run Diagnosis Evidence Pass',
+		repair_infra: 'Repair Infra Gate',
+		repair_compile: 'Repair Compile Gate',
+		repair_journey_contract: 'Repair Journey Contract',
+		repair_business_assertion: 'Repair Business Proof',
+		repair_release: 'Repair Release Gate',
+		targeted_product_repair: 'Run Targeted Repair',
+		manual_review: 'Manual Review',
+		continue_gate: 'Continue Current Gate'
+	};
+	return labels[mode];
+}
+
+function recoveryActionAutoRunnable(
+	mode: ResolveIOAIManagerRecoveryAutomationMode,
+	probe: ResolveIOAIManagerRecoveryEvidenceProbe
+): boolean {
+	if (mode === 'manual_review') {
+		return false;
+	}
+	if (mode === 'advance' || mode === 'continue_gate') {
+		return true;
+	}
+	if (mode === 'targeted_product_repair' || mode === 'read_only_diagnosis' || mode === 'repair_journey_contract' || mode === 'repair_business_assertion') {
+		return true;
+	}
+	return probe.steps.some((step) => step.commandHint || step.kind === 'rerun_same_gate' || step.kind === 'release_status' || step.kind === 'diff_scope_check');
+}
+
+export function buildResolveIOAIManagerRecoveryActionPacket(
+	input: ResolveIOAIManagerRecoveryActionPacketInput
+): ResolveIOAIManagerRecoveryActionPacket {
+	const checkpoint = input.checkpoint;
+	const probe = input.probe || buildResolveIOAIManagerRecoveryEvidenceProbe({
+		checkpoint,
+		current: input.current,
+		now: input.now
+	});
+	const mode = recoveryAutomationModeFor(checkpoint);
+	const primaryStep = probe.steps.find((step) => step.required && step.id !== 'snapshot_current_blocker')
+		|| probe.steps.find((step) => step.required)
+		|| probe.steps[0];
+	const evidenceOnly = probe.evidenceOnly || mode === 'collect_evidence' || mode === 'repair_infra' || mode === 'repair_compile' || mode === 'repair_release';
+	const requireNewEvidence = mode === 'collect_evidence'
+		|| checkpoint.status === 'parked'
+		|| checkpoint.attempts >= checkpoint.maxAttemptsBeforePark;
+	const stopWhen = Array.from(new Set([
+		...probe.stopConditions,
+		...(requireNewEvidence ? ['same blocker fingerprint and same evidence hash after probe'] : [])
+	].map((entry) => cleanText(entry, 500)).filter(Boolean))).slice(0, 30);
+	const resetLoopWhen = Array.from(new Set([
+		...checkpoint.loopResetEvidence,
+		...probe.loopResetEvidence,
+		...(requireNewEvidence ? [
+			'new material evidence: changed blocker, validated diagnosis/journey, business proof, compile/infra/release proof, or new actionable trace',
+			'weak hash-only evidence does not reset the loop'
+		] : [])
+	].map((entry) => cleanText(entry, 500)).filter(Boolean))).slice(0, 30);
+	const nextCommands = probe.steps
+		.map((step) => cleanText(step.commandHint || `${step.kind}:${step.id}`, 500))
+		.filter(Boolean)
+		.slice(0, 12);
+	const releasePolicy = mode === 'repair_release'
+		? buildResolveIOAIManagerHotfixFirstReleasePolicy({
+			surface: 'manager_recovery',
+			deployStatus: checkpoint.stepType,
+			publishStatus: checkpoint.lane
+		})
+		: undefined;
+	const now = isoNow(input.now);
+	return {
+		actionId: stableHash('mgr-action', {
+			checkpointId: checkpoint.checkpointId,
+			probeId: probe.probeId,
+			mode,
+			evidenceHash: checkpoint.evidenceHash,
+			blockerFingerprint: checkpoint.blockerFingerprint
+		}),
+		checkpointId: checkpoint.checkpointId,
+		probeId: probe.probeId,
+		recoveryClass: checkpoint.recoveryClass,
+		mode,
+		label: recoveryActionLabelFor(mode, checkpoint),
+		lane: checkpoint.lane,
+		stepType: checkpoint.stepType,
+		primaryStepKind: primaryStep?.kind || 'none',
+		objective: mode === 'collect_evidence'
+			? probe.objective
+			: cleanText(checkpoint.objective || probe.objective, 1000),
+		evidenceOnly,
+		autoRunnable: recoveryActionAutoRunnable(mode, probe),
+		productRepairAllowed: checkpoint.productRepairAllowed && !evidenceOnly && checkpoint.status !== 'parked',
+		expensiveModelAllowed: checkpoint.expensiveModelAllowed && checkpoint.status !== 'parked',
+		canResetLoopAfterEvidence: resetLoopWhen.length > 0,
+		maxAttemptsBeforePark: checkpoint.maxAttemptsBeforePark,
+		requiredArtifacts: probe.requiredArtifacts.slice(0, 20),
+		nextCommands: releasePolicy
+			? Array.from(new Set([...nextCommands, ...releasePolicy.allowedActions])).slice(0, 12)
+			: nextCommands,
+		successCriteria: releasePolicy
+			? Array.from(new Set([...probe.acceptanceEvidence, ...releasePolicy.requiredEvidence])).slice(0, 20)
+			: probe.acceptanceEvidence.slice(0, 20),
+		retryPolicy: {
+			allowImmediateRetry: checkpoint.status !== 'parked' && mode !== 'manual_review',
+			requireNewEvidence,
+			resetLoopWhen,
+			stopWhen
+		},
+		...(releasePolicy ? { releasePolicy } : {}),
+		...(mode === 'collect_evidence' ? { blockedReason: 'Manager parked this loop until the recovery action records new evidence.' } : {}),
+		createdAt: now
+	};
+}
+
+function dispatchActionForMode(mode: ResolveIOAIManagerRecoveryAutomationMode): ResolveIOAIManagerRecoveryActionDispatchAction {
+	const map: Record<ResolveIOAIManagerRecoveryAutomationMode, ResolveIOAIManagerRecoveryActionDispatchAction> = {
+		advance: 'advance',
+		collect_evidence: 'run_evidence_probe',
+		read_only_diagnosis: 'run_read_only_diagnosis',
+		repair_infra: 'run_infra_repair',
+		repair_compile: 'run_compile_repair',
+		repair_journey_contract: 'run_journey_contract_repair',
+		repair_business_assertion: 'run_business_assertion_repair',
+		repair_release: 'run_release_repair',
+		targeted_product_repair: 'run_targeted_product_repair',
+		manual_review: 'park_manual',
+		continue_gate: 'continue_gate'
+	};
+	return map[mode] || 'park_manual';
+}
+
+function buildRecoveryDispatchRecord(
+	action: ResolveIOAIManagerRecoveryActionPacket,
+	dispatchAction: ResolveIOAIManagerRecoveryActionDispatchAction,
+	status: ResolveIOAIManagerRecoveryActionDispatchStatus,
+	reason: string,
+	current?: ResolveIOAIManagerFailureRecord,
+	now?: Date | string
+): ResolveIOAIManagerRecoveryActionDispatchRecord {
+	const evidenceHash = current?.evidenceHash || action.checkpointId || action.actionId;
+	const blockerFingerprint = resolveResolveIOAIManagerBlockerFingerprint(current, action.objective);
+	const artifactPaths = cleanList(current?.artifactPaths, 20, 500);
+	const createdAt = isoNow(now);
+	return {
+		dispatchId: stableHash('mgr-dispatch', {
+			actionId: action.actionId,
+			dispatchAction,
+			evidenceHash,
+			blockerFingerprint,
+			status
+		}),
+		actionId: action.actionId,
+		checkpointId: action.checkpointId,
+		probeId: action.probeId,
+		mode: action.mode,
+		dispatchAction,
+		status,
+		evidenceHash,
+		blockerFingerprint,
+		productRepairAllowed: action.productRepairAllowed && dispatchAction === 'run_targeted_product_repair',
+		expensiveModelAllowed: action.expensiveModelAllowed && dispatchAction !== 'run_evidence_probe',
+		reason,
+		artifactPaths,
+		...(status === 'started' ? { startedAt: createdAt } : {}),
+		...(status === 'completed' ? { completedAt: createdAt } : {}),
+		createdAt
+	};
+}
+
+export function decideResolveIOAIManagerRecoveryActionDispatch(
+	input: ResolveIOAIManagerRecoveryActionDispatchInput
+): ResolveIOAIManagerRecoveryActionDispatchDecision {
+	const action = input.action;
+	const history = Array.isArray(input.history) ? input.history.filter(Boolean).slice(-50) : [];
+	const current = input.current || {};
+	if (!action) {
+		return {
+			dispatchAction: 'park_manual',
+			allowed: false,
+			reason: 'recovery_dispatch_missing_action',
+			status: 'parked',
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldRecordDispatch: false,
+			requiresNewEvidence: true,
+			newEvidence: false
+		};
+	}
+	const dispatchAction = dispatchActionForMode(action.mode);
+	const evidenceHash = current.evidenceHash || action.checkpointId || action.actionId;
+	const blockerFingerprint = resolveResolveIOAIManagerBlockerFingerprint(current, action.objective);
+	const sameActionHistory = history.filter((entry) => entry.actionId === action.actionId);
+	const sameEvidenceHistory = sameActionHistory.filter((entry) => entry.evidenceHash === evidenceHash
+		&& entry.blockerFingerprint === blockerFingerprint);
+	const activeDispatch = sameEvidenceHistory.find((entry) => entry.status === 'queued' || entry.status === 'started');
+	const completedDispatch = sameEvidenceHistory.find((entry) => entry.status === 'completed' || entry.status === 'failed');
+	const newEvidence = sameActionHistory.length > 0 && sameEvidenceHistory.length === 0;
+	const requiresNewEvidence = action.retryPolicy.requireNewEvidence === true;
+	const manualOnly = action.mode === 'manual_review' || !action.autoRunnable;
+	const productDispatch = dispatchAction === 'run_targeted_product_repair';
+	const expensiveDispatch = !['run_evidence_probe', 'advance', 'continue_gate', 'park_manual'].includes(dispatchAction);
+	if (manualOnly && input.operatorApproved !== true) {
+		const record = buildRecoveryDispatchRecord(action, 'park_manual', 'parked', 'recovery_dispatch_requires_manual_review', current, input.now);
+		return {
+			dispatchAction: 'park_manual',
+			allowed: false,
+			reason: record.reason,
+			status: 'parked',
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldRecordDispatch: true,
+			requiresNewEvidence,
+			newEvidence,
+			dispatchRecord: record
+		};
+	}
+	if (productDispatch && action.productRepairAllowed !== true) {
+		const record = buildRecoveryDispatchRecord(action, 'park_manual', 'parked', 'recovery_dispatch_product_repair_not_allowed', current, input.now);
+		return {
+			dispatchAction: 'park_manual',
+			allowed: false,
+			reason: record.reason,
+			status: 'parked',
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldRecordDispatch: true,
+			requiresNewEvidence: true,
+			newEvidence,
+			dispatchRecord: record
+		};
+	}
+	if (activeDispatch) {
+		return {
+			dispatchAction: 'park_manual',
+			allowed: false,
+			reason: 'recovery_dispatch_already_running_for_same_evidence',
+			status: 'parked',
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldRecordDispatch: false,
+			requiresNewEvidence: true,
+			newEvidence: false
+		};
+	}
+	if (completedDispatch && requiresNewEvidence && !newEvidence) {
+		const record = buildRecoveryDispatchRecord(action, 'park_manual', 'parked', 'recovery_dispatch_same_evidence_already_attempted', current, input.now);
+		return {
+			dispatchAction: 'park_manual',
+			allowed: false,
+			reason: record.reason,
+			status: 'parked',
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldRecordDispatch: true,
+			requiresNewEvidence: true,
+			newEvidence: false,
+			dispatchRecord: record
+		};
+	}
+	const status: ResolveIOAIManagerRecoveryActionDispatchStatus = dispatchAction === 'advance' || dispatchAction === 'continue_gate'
+		? 'completed'
+		: 'started';
+	const record = buildRecoveryDispatchRecord(action, dispatchAction, status, 'recovery_dispatch_allowed', current, input.now);
+	return {
+		dispatchAction,
+		allowed: true,
+		reason: 'recovery_dispatch_allowed',
+		status,
+		canRunProductRepair: productDispatch && action.productRepairAllowed === true,
+		canRunExpensiveModel: expensiveDispatch && action.expensiveModelAllowed === true,
+		shouldRecordDispatch: true,
+		requiresNewEvidence,
+		newEvidence,
+		dispatchRecord: record
+	};
+}
+
+export function appendResolveIOAIManagerRecoveryActionDispatch(
+	history: ResolveIOAIManagerRecoveryActionDispatchRecord[] | undefined,
+	record: ResolveIOAIManagerRecoveryActionDispatchRecord | undefined,
+	limit = 50
+): ResolveIOAIManagerRecoveryActionDispatchRecord[] {
+	const existing = Array.isArray(history) ? history.filter(Boolean) : [];
+	if (!record) {
+		return existing.slice(-limit);
+	}
+	const deduped = existing.filter((entry) => entry.dispatchId !== record.dispatchId);
+	return [...deduped, record].slice(-limit);
+}
+
+function recoveryExecutionPhaseForDispatch(
+	dispatchAction: ResolveIOAIManagerRecoveryActionDispatchAction
+): ResolveIOAIManagerRecoveryExecutionPhase {
+	const map: Record<ResolveIOAIManagerRecoveryActionDispatchAction, ResolveIOAIManagerRecoveryExecutionPhase> = {
+		run_evidence_probe: 'evidence',
+		run_read_only_diagnosis: 'diagnosis',
+		run_infra_repair: 'infra',
+		run_compile_repair: 'compile',
+		run_journey_contract_repair: 'journey',
+		run_business_assertion_repair: 'business_proof',
+		run_release_repair: 'release',
+		run_targeted_product_repair: 'product_repair',
+		advance: 'advance',
+		continue_gate: 'advance',
+		park_manual: 'manual'
+	};
+	return map[dispatchAction] || 'manual';
+}
+
+function recoveryDirectiveReason(
+	action: ResolveIOAIManagerRecoveryActionPacket | undefined,
+	decision: ResolveIOAIManagerRecoveryActionDispatchDecision,
+	current?: ResolveIOAIManagerFailureRecord
+): string {
+	const blocker = cleanText(current?.blocker || current?.summary || '', 260);
+	const label = cleanText(action?.label, 120) || decision.dispatchAction;
+	const objective = cleanText(action?.objective, 260);
+	return [
+		`MANAGER_RECOVERY:${decision.dispatchAction}`,
+		`label=${label}`,
+		decision.reason ? `reason=${decision.reason}` : '',
+		blocker ? `blocker=${blocker}` : '',
+		objective ? `objective=${objective}` : ''
+	].filter(Boolean).join(' | ');
+}
+
+export function buildResolveIOAIManagerRecoveryExecutionDirective(
+	input: ResolveIOAIManagerRecoveryExecutionDirectiveInput
+): ResolveIOAIManagerRecoveryExecutionDirective {
+	const action = input.action;
+	const dispatchDecision = input.dispatchDecision || decideResolveIOAIManagerRecoveryActionDispatch({
+		action,
+		current: input.current,
+		now: input.now
+	});
+	const dispatchAction = dispatchDecision.dispatchAction;
+	const now = isoNow(input.now);
+	const phase = recoveryExecutionPhaseForDispatch(dispatchAction);
+	const lane = cleanText(action?.lane || input.current?.lane || '', 120);
+	const stepType = cleanText(action?.stepType || input.current?.stepType || '', 120);
+	const rerunReason = recoveryDirectiveReason(action, dispatchDecision, input.current);
+	const surface = cleanText(input.surface || 'runner', 120);
+	return {
+		directiveId: stableHash('mgr-directive', {
+			surface,
+			actionId: action?.actionId || '',
+			dispatchAction,
+			reason: dispatchDecision.reason,
+			evidenceHash: dispatchDecision.dispatchRecord?.evidenceHash || input.current?.evidenceHash || ''
+		}),
+		surface,
+		dispatchAction,
+		phase,
+		allowed: dispatchDecision.allowed,
+		status: dispatchDecision.status,
+		reason: dispatchDecision.reason,
+		lane,
+		stepType,
+		nextActionLabel: cleanText(action?.label, 160) || dispatchAction,
+		rerunReason,
+		evidenceOnly: action?.evidenceOnly !== false || dispatchAction === 'run_evidence_probe',
+		autoRunnable: action?.autoRunnable === true,
+		productRepairAllowed: action?.productRepairAllowed === true,
+		expensiveModelAllowed: action?.expensiveModelAllowed === true,
+		canRunProductRepair: dispatchDecision.canRunProductRepair,
+		canRunExpensiveModel: dispatchDecision.canRunExpensiveModel,
+		canResetLoopAfterEvidence: action?.canResetLoopAfterEvidence === true,
+		requiresNewEvidence: dispatchDecision.requiresNewEvidence,
+		newEvidence: dispatchDecision.newEvidence,
+		maxAttemptsBeforePark: Math.max(1, Number(action?.maxAttemptsBeforePark || 1) || 1),
+		requiredArtifacts: cleanList(action?.requiredArtifacts, 20, 500),
+		nextCommands: cleanList(action?.nextCommands, 20, 500),
+		successCriteria: cleanList(action?.successCriteria, 20, 500),
+		forbiddenActions: action?.productRepairAllowed === true
+			? []
+			: Array.from(new Set([
+				'Do not run product-code repair from this directive unless canRunProductRepair is true.',
+				...(action?.releasePolicy?.forbiddenActions || [])
+			])).slice(0, 20),
+		...(dispatchDecision.dispatchRecord ? { dispatchRecord: dispatchDecision.dispatchRecord } : {}),
+		...(action?.releasePolicy ? { releasePolicy: action.releasePolicy } : {}),
+		createdAt: now
+	};
+}
+
+function newListEntries(current: string[], previous: string[]): string[] {
+	const existing = new Set(previous.map((entry) => cleanText(entry, 500)).filter(Boolean));
+	return current
+		.map((entry) => cleanText(entry, 500))
+		.filter((entry) => entry && !existing.has(entry));
+}
+
+function recordLane(value: any): string {
+	return cleanText(value?.lane, 80);
+}
+
+function recordStepType(value: any): string {
+	return cleanText(value?.stepType, 80);
+}
+
+function recordFailureClass(value: any): string {
+	const valueText = cleanText(value?.failureClass, 80);
+	return valueText ? normalizeResolveIOAIManagerFailureClass(valueText) : '';
+}
+
+function materialEvidenceText(record: ResolveIOAIManagerFailureRecord | undefined, paths: string[] = []): string {
+	return [
+		cleanText(record?.blocker, 1200),
+		cleanText(record?.summary, 1200),
+		...paths.map((path) => cleanText(path, 500))
+	].filter(Boolean).join(' ').toLowerCase();
+}
+
+function hasMaterialEvidenceLanguage(text: string): boolean {
+	return /(business|assertion|proof|before|after|dom|trace|stack|network|mongo|query|diff|scope|diagnosis|journey|contract|workflow|compile|build|preflight|infra|chrome|puppeteer|release|publish|deploy|sample|seed|route|auth|hydration|performance|slow|owner|root.?cause|repro|pdf|export|upload|import|filter|invoice|saved|calculated|comparison|report)/i.test(text);
+}
+
+export function assessResolveIOAIManagerEvidenceChange(
+	previous: (ResolveIOAIManagerFailureRecord | ResolveIOAIManagerRecoveryCheckpoint | undefined),
+	current: ResolveIOAIManagerFailureRecord | undefined,
+	fallbackObjective?: string
+): ResolveIOAIManagerEvidenceAssessment {
+	const currentRecord = current || {};
+	const previousRecord = previous as any;
+	const previousEvidenceHash = previousRecord ? cleanText(previousRecord.evidenceHash, 160) || hashResolveIOAIManagerEvidence(previousRecord) : '';
+	const currentEvidenceHash = hashResolveIOAIManagerEvidence(currentRecord);
+	const previousBlockerFingerprint = previousRecord
+		? cleanText(previousRecord.blockerFingerprint, 160) || resolveResolveIOAIManagerBlockerFingerprint(previousRecord, fallbackObjective)
+		: '';
+	const currentBlockerFingerprint = resolveResolveIOAIManagerBlockerFingerprint(currentRecord, fallbackObjective);
+	const previousChangedFiles = cleanList(previousRecord?.changedFiles, 80, 500);
+	const currentChangedFiles = cleanList(currentRecord.changedFiles, 80, 500);
+	const previousArtifactPaths = cleanList(previousRecord?.artifactPaths, 80, 500);
+	const currentArtifactPaths = cleanList(currentRecord.artifactPaths, 80, 500);
+	const addedChangedFiles = newListEntries(currentChangedFiles, previousChangedFiles);
+	const addedArtifactPaths = newListEntries(currentArtifactPaths, previousArtifactPaths);
+	const signals: string[] = [];
+	if (previousEvidenceHash && currentEvidenceHash !== previousEvidenceHash) {
+		signals.push('evidence_hash_changed');
+	}
+	if (previousBlockerFingerprint && currentBlockerFingerprint !== previousBlockerFingerprint) {
+		signals.push('blocker_fingerprint_changed');
+	}
+	if (recordLane(previousRecord) && recordLane(previousRecord) !== recordLane(currentRecord)) {
+		signals.push('lane_changed');
+	}
+	if (recordStepType(previousRecord) && recordStepType(previousRecord) !== recordStepType(currentRecord)) {
+		signals.push('step_type_changed');
+	}
+	if (recordFailureClass(previousRecord) && recordFailureClass(previousRecord) !== recordFailureClass(currentRecord)) {
+		signals.push('failure_class_changed');
+	}
+	if (addedChangedFiles.length) {
+		signals.push('changed_files_added');
+	}
+	if (addedArtifactPaths.length) {
+		signals.push('artifact_paths_added');
+	}
+	if (isPassingOutcome(currentRecord)) {
+		signals.push('passing_outcome');
+	}
+	const changed = signals.length > 0;
+	const evidenceText = materialEvidenceText(currentRecord, addedArtifactPaths);
+	const pathOrSummaryHasMaterialSignal = hasMaterialEvidenceLanguage(evidenceText);
+	const proof = signals.includes('passing_outcome');
+	const structuralChange = signals.some((signal) => /blocker_fingerprint_changed|lane_changed|step_type_changed|failure_class_changed/.test(signal));
+	const materialArtifact = addedArtifactPaths.length > 0 && pathOrSummaryHasMaterialSignal;
+	const materialChangedFiles = addedChangedFiles.length > 0
+		&& /diagnosis|owner|scope|diff|root.?cause|failing path|stack|trace|business|proof|compile|release|deploy|workflow|journey/i.test(evidenceText);
+	const material = proof || structuralChange || materialArtifact || materialChangedFiles;
+	const strength: ResolveIOAIManagerEvidenceStrength = proof
+		? 'proof'
+		: material
+			? 'material'
+			: changed
+				? 'weak'
+				: 'none';
+	return {
+		changed,
+		material,
+		strength,
+		signals,
+		evidenceHash: currentEvidenceHash,
+		blockerFingerprint: currentBlockerFingerprint
+	};
+}
+
+function proposedActionIsProductRepair(value: any): boolean {
+	const normalized = cleanText(value, 120);
+	return /product|code|repair|build|business|journey|workflow/i.test(normalized)
+		&& !/infra|compile|diagnosis|manual|evidence|release|publish/i.test(normalized);
+}
+
+export function decideResolveIOAIManagerRecoveryGate(
+	input: ResolveIOAIManagerRecoveryGateInput
+): ResolveIOAIManagerRecoveryGateDecision {
+	const checkpoint = input.checkpoint;
+	const hasCurrent = !!input.current;
+	const current = input.current || {};
+	const assessment = hasCurrent
+		? assessResolveIOAIManagerEvidenceChange(checkpoint, current, checkpoint.objective)
+		: {
+			changed: false,
+			material: false,
+			strength: 'none' as ResolveIOAIManagerEvidenceStrength,
+			signals: [],
+			evidenceHash: checkpoint.evidenceHash,
+			blockerFingerprint: checkpoint.blockerFingerprint
+		};
+	const blockerFingerprint = assessment.blockerFingerprint;
+	const evidenceHash = assessment.evidenceHash;
+	const changedFiles = hasCurrent ? cleanList(current.changedFiles, 80, 500) : checkpoint.changedFiles;
+	const artifactPaths = hasCurrent ? cleanList(current.artifactPaths, 80, 500) : checkpoint.artifactPaths;
+	const evidenceChanged = assessment.changed;
+	const proposedAction = cleanText(input.proposedAction || checkpoint.allowedAction, 120);
+	const productRepairRequested = proposedActionIsProductRepair(proposedAction);
+	const missingEvidence = checkpoint.requiredEvidence.filter((required) => {
+		const normalized = cleanText(required, 120).toLowerCase();
+		if (!normalized) {
+			return false;
+		}
+		if (/artifact|log|proof|gate|evidence/.test(normalized)) {
+			return !artifactPaths.length && !current.evidenceHash;
+		}
+		if (/diff|changed files|owner|scope|file/.test(normalized)) {
+			return !changedFiles.length;
+		}
+		return false;
+	});
+	const makeDecision = (
+		action: ResolveIOAIManagerRecoveryGateAction,
+		reason: string,
+		overrides: Partial<ResolveIOAIManagerRecoveryGateDecision> = {}
+	): ResolveIOAIManagerRecoveryGateDecision => ({
+		action,
+		reason,
+		canRunProductRepair: checkpoint.productRepairAllowed,
+		canRunExpensiveModel: checkpoint.expensiveModelAllowed,
+		shouldResetLoopBudget: false,
+		shouldIncrementAttempt: action === 'allow',
+		newEvidence: evidenceChanged,
+		materialEvidence: assessment.material,
+		evidenceStrength: assessment.strength,
+		evidenceSignals: assessment.signals,
+		blockerFingerprint,
+		evidenceHash,
+		missingEvidence,
+		checkpoint: {
+			...checkpoint,
+			updatedAt: isoNow(input.now)
+		},
+		...overrides
+	});
+
+	if (checkpoint.status === 'complete') {
+		return makeDecision('complete', 'recovery_gate_checkpoint_already_complete', {
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldIncrementAttempt: false
+		});
+	}
+	if (checkpoint.status === 'manual_handoff' && input.operatorApproved !== true) {
+		return makeDecision('manual_handoff', 'recovery_gate_manual_handoff_requires_operator_approval', {
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldIncrementAttempt: false
+		});
+	}
+	if (productRepairRequested && !checkpoint.productRepairAllowed) {
+		return makeDecision('reject_action', 'recovery_gate_product_repair_not_allowed_for_checkpoint', {
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldIncrementAttempt: false
+		});
+	}
+	if (checkpoint.status === 'parked' && !evidenceChanged) {
+		return makeDecision('collect_new_evidence', 'recovery_gate_parked_until_new_evidence', {
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldIncrementAttempt: false
+		});
+	}
+	if (checkpoint.status === 'parked' && evidenceChanged && !assessment.material) {
+		return makeDecision('collect_new_evidence', 'recovery_gate_weak_evidence_requires_material_signal', {
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldIncrementAttempt: false
+		});
+	}
+	if (checkpoint.attempts >= checkpoint.maxAttemptsBeforePark && !evidenceChanged) {
+		return makeDecision('collect_new_evidence', 'recovery_gate_attempt_limit_requires_new_evidence', {
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldIncrementAttempt: false
+		});
+	}
+	if (checkpoint.attempts >= checkpoint.maxAttemptsBeforePark && evidenceChanged && !assessment.material) {
+		return makeDecision('collect_new_evidence', 'recovery_gate_attempt_limit_requires_material_evidence', {
+			canRunProductRepair: false,
+			canRunExpensiveModel: false,
+			shouldIncrementAttempt: false
+		});
+	}
+	if (evidenceChanged) {
+		const currentFailureClass = normalizeResolveIOAIManagerFailureClass(current.failureClass);
+		const currentCanRunProductRepair = checkpoint.productRepairAllowed
+			|| !/^(infra|compile|diagnosis|release)$/i.test(currentFailureClass);
+		return makeDecision('allow', 'recovery_gate_new_material_evidence_unblocks_retry', {
+			canRunProductRepair: currentCanRunProductRepair,
+			canRunExpensiveModel: checkpoint.expensiveModelAllowed || currentCanRunProductRepair,
+			shouldResetLoopBudget: true
+		});
+	}
+	return makeDecision('allow', 'recovery_gate_action_allowed');
+}
+
+function failureKey(record: ResolveIOAIManagerFailureRecord | undefined): string {
+	if (!record) {
+		return '';
+	}
+	const failureClass = normalizeResolveIOAIManagerFailureClass(record.failureClass);
+	const blockerFingerprint = resolveResolveIOAIManagerBlockerFingerprint(record);
+	return `${cleanText(record.lane, 80)}:${cleanText(record.stepType, 80)}:${failureClass}:${blockerFingerprint}`;
+}
+
+function failureEvidenceKey(record: ResolveIOAIManagerFailureRecord | undefined): string {
+	return `${failureKey(record)}:${hashResolveIOAIManagerEvidence(record)}`;
+}
+
+function isPassingOutcome(record: ResolveIOAIManagerFailureRecord | undefined): boolean {
+	return /^(pass|accepted|ready_to_publish|published|ready_for_merge|complete|completed)$/i.test(cleanText(record?.outcome, 80));
+}
+
+function isManualOutcome(record: ResolveIOAIManagerFailureRecord | undefined): boolean {
+	return /^(manual_handoff|park_manual|stopped)$/i.test(cleanText(record?.outcome, 80));
+}
+
+export function buildResolveIOAIManagerRecoveryPlan(input: ResolveIOAIManagerRecoveryPlanInput = {}): ResolveIOAIManagerRecoveryPlan {
+	const action = cleanText(input.action, 80) || 'continue';
+	const reason = cleanText(input.reason, 240);
+	const failureClass = normalizeResolveIOAIManagerFailureClass(input.failureClass);
+	const lane = cleanText(input.lane, 80) || 'supervisor';
+	const stepType = cleanText(input.stepType, 80) || 'unknown';
+	const blocker = cleanText(input.blocker, 700);
+	const changedFiles = cleanList(input.changedFiles, 12, 240);
+	const artifactPaths = cleanList(input.artifactPaths, 12, 240);
+	const maxAttemptsBeforePark = Math.max(1, Number(input.maxSameFailureRepeats || 3) || 3);
+	const commonNotes = [
+		reason ? `policy_reason=${reason}` : '',
+		blocker ? `blocker=${blocker}` : '',
+		changedFiles.length ? `changed_files=${changedFiles.join(', ')}` : '',
+		artifactPaths.length ? `artifacts=${artifactPaths.join(', ')}` : ''
+	].filter(Boolean);
+	const base: Omit<ResolveIOAIManagerRecoveryPlan, 'recoveryClass' | 'nextActionLabel' | 'objective' | 'allowedAction' | 'productRepairAllowed' | 'expensiveModelAllowed' | 'finiteSteps' | 'requiredEvidence' | 'loopResetEvidence' | 'forbiddenActions'> = {
+		lane,
+		stepType,
+		maxAttemptsBeforePark,
+		notes: commonNotes
+	};
+	const makePlan = (
+		recoveryClass: ResolveIOAIManagerRecoveryClass,
+		nextActionLabel: string,
+		objective: string,
+		allowedAction: string,
+		productRepairAllowed: boolean,
+		expensiveModelAllowed: boolean,
+		finiteSteps: string[],
+		requiredEvidence: string[],
+		loopResetEvidence: string[],
+		forbiddenActions: string[]
+	): ResolveIOAIManagerRecoveryPlan => ({
+		...base,
+		recoveryClass,
+		nextActionLabel,
+		objective,
+		allowedAction,
+		productRepairAllowed,
+		expensiveModelAllowed,
+		finiteSteps,
+		requiredEvidence,
+		loopResetEvidence,
+		forbiddenActions
+	});
+	if (action === 'reset_loop_budget') {
+		return makePlan(
+			'advance_after_proof',
+			'Advance After Proof',
+			'Checkpoint the passing evidence and move to the next required gate.',
+			'advance_to_next_gate',
+			false,
+			false,
+			[
+				'Record the passing artifact, changed files, and gate result.',
+				'Reset the loop counter because a real gate passed.',
+				'Select the next unmet deterministic gate instead of repeating the previous repair.'
+			],
+			['passing gate record', 'artifact or log proving the passed check'],
+			['new passing gate result', 'new business proof artifact'],
+			['rerun the same repair after a pass', 'mark accepted without the required downstream gate']
+		);
+	}
+	if (action === 'manual_handoff') {
+		return makePlan(
+			'manual_handoff',
+			'Manual Review',
+			'Stop autonomous repair and expose the blocker, evidence, and last safe state.',
+			'manual_review_only',
+			false,
+			false,
+			[
+				'Freeze further product-code edits.',
+				'Show the blocker fingerprint, evidence hash, and prior attempts.',
+				'Require a human edit to classification, scope, or retry policy before another model/code loop.'
+			],
+			['blocker fingerprint', 'evidence hash', 'attempt history'],
+			['manual policy change', 'new external evidence'],
+			['start another automatic model repair', 'hide the failed evidence']
+		);
+	}
+	if (action === 'budget_stop') {
+		return makePlan(
+			'manual_handoff',
+			'Budget Stop Review',
+			'Stop autonomous model/code loops until a cheaper scoped next action is selected.',
+			'budget_review_only',
+			false,
+			false,
+			[
+				'Freeze further model repair loops.',
+				'Show the prompt/token/runtime budget that tripped the guard.',
+				'Select a cheaper deterministic gate, infra repair, diagnosis revision, or manual scope edit before resuming.'
+			],
+			['budget guard reason', 'latest prompt estimate', 'last blocker/evidence hash'],
+			['manual scope reduction', 'new deterministic evidence', 'approved budget policy change'],
+			['start another broad model prompt', 'reset budget without new evidence', 'hide cost context']
+		);
+	}
+	if (failureClass === 'diagnosis' || stepType === 'diagnosis_gate') {
+		return makePlan(
+			'diagnosis_only',
+			'Run Diagnosis Gate',
+			'Produce a falsifiable root-cause diagnosis before any repair.',
+			'read_only_diagnosis',
+			false,
+			true,
+			[
+				'Reproduce or explicitly classify the customer issue.',
+				'Accept one falsifiable hypothesis and record rejected alternatives.',
+				'Identify the frontend/backend/shared failing path.',
+				'Select a small owner_files set.',
+				'Define exact before/action/after business proof.'
+			],
+			['issue_case', 'accepted_hypothesis', 'rejected_alternatives', 'failing_path', 'owner_files', 'proof_plan'],
+			['new reproduction artifact', 'new query/log/code evidence', 'validated diagnosis gate'],
+			['edit product code', 'run broad repo repair', 'accept route-load evidence as success']
+		);
+	}
+	if (failureClass === 'owner_scope' || failureClass === 'out_of_scope' || /out.?of.?scope|owner_files/i.test(reason)) {
+		return makePlan(
+			'diagnosis_revision',
+			'Revise Diagnosis Scope',
+			'Revise owner_files only when new evidence proves the current scope is wrong.',
+			'diagnosis_revision_only',
+			false,
+			true,
+			[
+				'Compare changed files against the diagnosis owner_files.',
+				'Collect evidence proving why the new file is in the failing path.',
+				'Update accepted_hypothesis, failing_path, owner_files, and proof_plan together.',
+				'Resume repair only after the revised gate validates.'
+			],
+			['out-of-scope file list', 'new failing-path evidence', 'revalidated diagnosis gate'],
+			['revised owner_files with evidence', 'new business proof requirement'],
+			['keep broad edits without diagnosis', 'add convenience refactors', 'continue repair outside owner_files']
+		);
+	}
+	if (action === 'retry_infra') {
+		const isCompile = failureClass === 'compile';
+		return makePlan(
+			isCompile ? 'compile_repair' : 'infra_repair',
+			isCompile ? 'Repair Compile Gate' : 'Repair Infra Gate',
+			isCompile
+				? 'Fix the deterministic compile/build blocker before spending another product repair loop.'
+				: 'Fix the deterministic harness/browser/server/Mongo blocker before product repair.',
+			isCompile ? 'compile_repair_only' : 'infra_repair_only',
+			false,
+			false,
+			isCompile
+				? [
+					'Read the exact compile/build log and identify the first actionable error.',
+					'Fix missing dependency, stale artifact, command, cache, or type wiring required by the compile gate.',
+					'Rerun the same finite compile command.',
+					'Return the compile log artifact and status.'
+				]
+				: [
+					'Run preflight for Puppeteer, Chrome executable, ports, Mongo/settings, and startup command.',
+					'Repair only the failing harness/environment item.',
+					'Rerun the same infra check.',
+					'Return the infra log and pass/fail status.'
+				],
+			isCompile
+				? ['compile command', 'compile log artifact', 'first failing error fixed or still failing']
+				: ['preflight command', 'infra log artifact', 'specific repaired environment item'],
+			['same check now passes', 'new infra/compile blocker hash'],
+			['run product-code model repair', 'count this as product failure', 'accept route/business success without the compile/infra gate']
+		);
+	}
+	if (action === 'park_repeated_failure' || action === 'park_ping_pong') {
+		return makePlan(
+			'blocked_until_new_evidence',
+			action === 'park_ping_pong' ? 'Park Ping-Pong Loop' : 'Park Repeated Failure',
+			'Stop the current loop until new evidence changes the diagnosis, route, or repair target.',
+			'collect_new_evidence_only',
+			false,
+			false,
+			[
+				'Do not rerun the same prompt or same repair.',
+				'Show the repeated blocker and evidence hash.',
+				'Collect a new artifact: failing DOM state, stack trace, network response, Mongo delta, compile log, or revised diagnosis.',
+				'Reset the loop only after material evidence changes the blocker, proof, diagnosis, journey, or actionable trace.'
+			],
+			['same failure count', 'blocker fingerprint', 'evidence hash'],
+			['changed blocker fingerprint', 'changed evidence hash', 'business/compile/infra/release proof artifact', 'revised diagnosis or journey contract', 'new actionable trace or data delta'],
+			['alternate between two failed patches', 'increase loop budget without evidence', 'hide the park reason']
+		);
+	}
+	if (failureClass === 'journey') {
+		return makePlan(
+			'journey_contract_repair',
+			'Repair Journey Contract',
+			'Fix the first/next/last workflow contract before app code work continues.',
+			'journey_contract_repair',
+			false,
+			true,
+			[
+				'Open docs/APP_JOURNEY_CONTRACT.md.',
+				'Define first_screen, north_star_workflow, screen_sequence, data_story, completion_states, and qa_assertions.',
+				'Ensure each CTA maps to an action, route, method, calculation, or state transition.',
+				'Validate that sample data can drive the promised workflow.'
+			],
+			['validated journey_contract JSON', 'CTA-to-action mapping', 'workflow QA assertions'],
+			['journey validation passes', 'new workflow QA rows generated'],
+			['build empty routes', 'add link-only dashboard actions', 'defer workflow design to wow pass']
+		);
+	}
+	if (failureClass === 'release') {
+		return makePlan(
+			'release_repair',
+			'Repair Release Gate',
+			'Repair deploy/publish/sample-data release evidence with a hotfix-first path before any repeated full deploy.',
+			'release_repair_only',
+			false,
+			false,
+			[
+				'Read the deploy/publish/sample-data log.',
+				'Identify whether the blocker is domain, asset, seed data, route, permission, or CDN.',
+				'Prefer backend hotfix, release config, domain, cache, or seed-data repair when the product artifact already has business proof.',
+				'Rerun only the failed release gate.'
+			],
+			['deploy or publish log', 'sample-data status', 'failed release gate rerun'],
+			['release gate passes', 'new release blocker hash'],
+			['change core workflow after business QA passed', 'mark accepted from scorecard only', 'rerun full builder loop', 'repeat deploy of same artifact without force_deploy evidence']
+		);
+	}
+	if (failureClass === 'business' || failureClass === 'qa_evidence' || failureClass === 'route') {
+		return makePlan(
+			'business_proof_repair',
+			'Repair Business Proof',
+			'Fix the exact failing workflow assertion and prove before/action/after behavior.',
+			'business_repair',
+			true,
+			true,
+			[
+				'Open the failing QA row or proof_plan.',
+				'Trace the UI action to method/publication/query/calculation.',
+				'Patch the smallest owner or workflow files.',
+				'Rerun only the failed business assertion.',
+				'Record DOM/data/Mongo/artifact proof.'
+			],
+			['failing assertion', 'action trace', 'business proof artifact'],
+			['business assertion passes', 'new failed assertion with new evidence'],
+			['treat route load as success', 'rerun unrelated QA rows first', 'accept scorecard-only evidence']
+		);
+	}
+	if (input.productRepairFailure !== false || failureClass === 'product_code') {
+		return makePlan(
+			'product_code_repair',
+			'Run Targeted Product Repair',
+			'Repair the current product-code blocker with the smallest scoped edit and immediate proof.',
+			'targeted_product_repair',
+			true,
+			true,
+			[
+				'Inspect the current blocker, artifacts, changed files, and owner/workflow scope.',
+				'Form one small repair hypothesis.',
+				'Patch only files justified by the active diagnosis or journey contract.',
+				'Rerun the smallest failed gate.',
+				'Record new evidence before any additional loop.'
+			],
+			['owner/workflow scope', 'repair diff', 'failed gate rerun artifact'],
+			['new evidence hash', 'same gate passes'],
+			['broad repo search-and-edit', 'rerun the same prompt without inspecting artifacts', 'change unrelated UI polish']
+		);
+	}
+	return makePlan(
+		'continue',
+		'Continue Current Gate',
+		'Continue the current lane because no blocking loop or infra condition was detected.',
+		'continue',
+		false,
+		false,
+		[
+			'Use the active lane memory.',
+			'Run the next finite gate.',
+			'Record artifacts and evidence hash.'
+		],
+		['active lane memory', 'finite gate artifact'],
+		['new gate result', 'new artifact path'],
+		['spawn duplicate runners', 'advance without evidence']
+	);
+}
+
+function collectOpenTail(records: ResolveIOAIManagerFailureRecord[]): ResolveIOAIManagerFailureRecord[] {
+	const tail: ResolveIOAIManagerFailureRecord[] = [];
+	for (let index = records.length - 1; index >= 0; index -= 1) {
+		const record = records[index];
+		if (isPassingOutcome(record)) {
+			break;
+		}
+		tail.unshift(record);
+	}
+	return tail;
+}
+
+function countSameFailure(records: ResolveIOAIManagerFailureRecord[], current: ResolveIOAIManagerFailureRecord): number {
+	const currentKey = failureKey(current);
+	let count = 0;
+	for (let index = records.length - 1; index >= 0; index -= 1) {
+		const record = records[index];
+		if (isPassingOutcome(record)) {
+			break;
+		}
+		if (failureKey(record) !== currentKey) {
+			break;
+		}
+		count += 1;
+	}
+	return count;
+}
+
+function previousRecordForPolicy(
+	history: ResolveIOAIManagerFailureRecord[],
+	current: ResolveIOAIManagerFailureRecord,
+	currentWasExplicit: boolean
+): ResolveIOAIManagerFailureRecord | undefined {
+	if (!history.length) {
+		return undefined;
+	}
+	if (!currentWasExplicit) {
+		return history.length > 1 ? history[history.length - 2] : undefined;
+	}
+	const last = history[history.length - 1];
+	if (failureEvidenceKey(last) === failureEvidenceKey(current)) {
+		return history.length > 1 ? history[history.length - 2] : undefined;
+	}
+	return last;
+}
+
+function countPingPong(records: ResolveIOAIManagerFailureRecord[], current: ResolveIOAIManagerFailureRecord): number {
+	const tail = collectOpenTail(records).filter((record) => {
+		return cleanText(record.lane, 80) === cleanText(current.lane, 80)
+			&& cleanText(record.stepType, 80) === cleanText(current.stepType, 80);
+	});
+	if (tail.length < 4) {
+		return 0;
+	}
+	const keys = tail.map(failureKey).filter(Boolean);
+	const last = keys.slice(-6);
+	if (last.length < 4) {
+		return 0;
+	}
+	const distinct = Array.from(new Set(last));
+	if (distinct.length !== 2) {
+		return 0;
+	}
+	for (let index = 2; index < last.length; index += 1) {
+		if (last[index] !== last[index - 2]) {
+			return 0;
+		}
+	}
+	return last.length - 1;
+}
+
+export function decideResolveIOAIManagerPolicy(input: ResolveIOAIManagerPolicyInput): ResolveIOAIManagerPolicyDecision {
+	const history = Array.isArray(input.history) ? input.history : [];
+	const currentWasExplicit = !!input.current;
+	const current = input.current || history[history.length - 1] || {};
+	const failureClass = normalizeResolveIOAIManagerFailureClass(current.failureClass);
+	const blockerFingerprint = resolveResolveIOAIManagerBlockerFingerprint(current);
+	const evidenceHash = hashResolveIOAIManagerEvidence(current);
+	const previous = previousRecordForPolicy(history, current, currentWasExplicit);
+	const previousSameFailure = previous && failureKey(previous) === failureKey(current);
+	const evidenceAssessment = previousSameFailure
+		? assessResolveIOAIManagerEvidenceChange(previous, current)
+		: {
+			changed: false,
+			material: false,
+			strength: 'none' as ResolveIOAIManagerEvidenceStrength,
+			signals: [],
+			evidenceHash,
+			blockerFingerprint
+		};
+	const newEvidence = !!previousSameFailure && evidenceAssessment.changed;
+	const sameFailureCount = countSameFailure(history, current);
+	const pingPongCount = countPingPong(history, current);
+	const maxSameFailureRepeats = Math.max(1, Number(input.maxSameFailureRepeats || 3) || 3);
+	const maxPingPongTransitions = Math.max(3, Number(input.maxPingPongTransitions || 3) || 3);
+	const infraClasses = new Set((input.infraFailureClasses || ['infra', 'compile']).map(normalizeResolveIOAIManagerFailureClass));
+	const ignoredClasses = new Set((input.ignoredFailureClasses || []).map(normalizeResolveIOAIManagerFailureClass));
+	const base = {
+		failureClass,
+		blockerFingerprint,
+		evidenceHash,
+		sameFailureCount,
+		pingPongCount,
+		newEvidence,
+		materialEvidence: evidenceAssessment.material,
+		evidenceStrength: evidenceAssessment.strength,
+		evidenceSignals: evidenceAssessment.signals,
+		loopBudgetShouldReset: false,
+		productRepairFailure: !infraClasses.has(failureClass) && !ignoredClasses.has(failureClass)
+	};
+	const withPlan = (
+		action: ResolveIOAIManagerAction,
+		reason: string,
+		overrides: Partial<Omit<ResolveIOAIManagerPolicyDecision, 'action' | 'reason' | 'recoveryPlan' | 'recoveryCheckpoint'>> = {}
+	): ResolveIOAIManagerPolicyDecision => {
+		const merged = {
+			...base,
+			...overrides
+		};
+		const recoveryPlan = buildResolveIOAIManagerRecoveryPlan({
+			action,
+			reason,
+			failureClass: merged.failureClass,
+			lane: current.lane,
+			stepType: current.stepType,
+			blocker: current.blocker || current.summary,
+			sameFailureCount: merged.sameFailureCount,
+			pingPongCount: merged.pingPongCount,
+			newEvidence: merged.newEvidence,
+			productRepairFailure: merged.productRepairFailure,
+			changedFiles: current.changedFiles,
+			artifactPaths: current.artifactPaths,
+			maxSameFailureRepeats
+		});
+		const recoveryCheckpoint = buildResolveIOAIManagerRecoveryCheckpoint({
+			plan: recoveryPlan,
+			current
+		});
+		const recoveryEvidenceProbe = buildResolveIOAIManagerRecoveryEvidenceProbe({
+			checkpoint: recoveryCheckpoint,
+			current
+		});
+		return {
+			...merged,
+			action,
+			reason,
+			recoveryPlan,
+			recoveryCheckpoint,
+			recoveryEvidenceProbe,
+			recoveryAction: buildResolveIOAIManagerRecoveryActionPacket({
+				plan: recoveryPlan,
+				checkpoint: recoveryCheckpoint,
+				probe: recoveryEvidenceProbe,
+				current
+			})
+		};
+	};
+	if (isPassingOutcome(current)) {
+		return withPlan('reset_loop_budget', 'manager_policy_progress_passed', {
+			loopBudgetShouldReset: true,
+			productRepairFailure: false
+		});
+	}
+	if (isManualOutcome(current)) {
+		return withPlan('manual_handoff', 'manager_policy_manual_or_stopped');
+	}
+	if (pingPongCount >= maxPingPongTransitions) {
+		return withPlan('park_ping_pong', 'manager_policy_ping_pong_failure_loop');
+	}
+	if (sameFailureCount >= maxSameFailureRepeats && !evidenceAssessment.material) {
+		return withPlan('park_repeated_failure', newEvidence
+			? 'manager_policy_same_failure_with_weak_evidence'
+			: 'manager_policy_same_failure_without_new_evidence');
+	}
+	if (infraClasses.has(failureClass)) {
+		return withPlan('retry_infra', 'manager_policy_infra_failure_routes_to_infra_repair', {
+			productRepairFailure: false
+		});
+	}
+	if (newEvidence || !previousSameFailure) {
+		if (newEvidence && !evidenceAssessment.material) {
+			return withPlan('continue', 'manager_policy_weak_evidence_does_not_reset_loop_budget');
+		}
+		return withPlan('continue', newEvidence
+				? 'manager_policy_new_material_evidence_resets_loop_budget'
+				: 'manager_policy_new_failure_or_lane', {
+			loopBudgetShouldReset: true,
+			materialEvidence: newEvidence ? true : base.materialEvidence,
+			evidenceStrength: newEvidence ? evidenceAssessment.strength : base.evidenceStrength
+		});
+	}
+	return withPlan('continue', 'manager_policy_retry_below_repeat_limit');
+}
+
+function buildReplayDirectiveFromPlan(input: {
+	surface: string;
+	plan: ResolveIOAIManagerRecoveryPlan;
+	current: ResolveIOAIManagerFailureRecord;
+	now?: Date | string;
+}): ResolveIOAIManagerRecoveryExecutionDirective {
+	const checkpoint = buildResolveIOAIManagerRecoveryCheckpoint({
+		plan: input.plan,
+		current: input.current,
+		now: input.now
+	});
+	const probe = buildResolveIOAIManagerRecoveryEvidenceProbe({
+		checkpoint,
+		current: input.current,
+		now: input.now
+	});
+	const action = buildResolveIOAIManagerRecoveryActionPacket({
+		plan: input.plan,
+		checkpoint,
+		probe,
+		current: input.current,
+		now: input.now
+	});
+	const dispatch = decideResolveIOAIManagerRecoveryActionDispatch({
+		action,
+		current: input.current,
+		now: input.now
+	});
+	return buildResolveIOAIManagerRecoveryExecutionDirective({
+		action,
+		dispatchDecision: dispatch,
+		current: input.current,
+		surface: input.surface,
+		now: input.now
+	});
+}
+
+function replayCaseFromDirective(input: {
+	caseId: string;
+	surface: string;
+	action: string;
+	reason: string;
+	directive: ResolveIOAIManagerRecoveryExecutionDirective;
+	expectedSafeAutoDispatch: boolean;
+	pass: boolean;
+	loopBudgetShouldReset?: boolean;
+	materialEvidence?: boolean;
+	evidenceStrength?: ResolveIOAIManagerEvidenceStrength;
+	details?: Record<string, any>;
+}): ResolveIOAIManagerRecoveryReplayCase {
+	const directive = input.directive;
+	const safeAutoDispatch = isResolveIOAIManagerSafeAutoDispatch({
+		dispatchAction: directive.dispatchAction,
+		directive,
+		includeJourneyContractRepair: input.expectedSafeAutoDispatch && directive.dispatchAction === 'run_journey_contract_repair',
+		includeReleaseRepair: input.expectedSafeAutoDispatch && directive.dispatchAction === 'run_release_repair',
+		includeProductRepair: false
+	});
+	return {
+		caseId: input.caseId,
+		surface: input.surface,
+		pass: input.pass && safeAutoDispatch === input.expectedSafeAutoDispatch,
+		action: input.action,
+		reason: input.reason,
+		recoveryClass: cleanText(directive.dispatchRecord?.mode || directive.phase, 120),
+		dispatchAction: directive.dispatchAction,
+		safeAutoDispatch,
+		expectedSafeAutoDispatch: input.expectedSafeAutoDispatch,
+		productRepairAllowed: directive.canRunProductRepair === true,
+		loopBudgetShouldReset: input.loopBudgetShouldReset === true,
+		materialEvidence: input.materialEvidence === true,
+		evidenceStrength: input.evidenceStrength || 'none',
+		...(directive.releasePolicy ? {
+			hotfixFirst: directive.releasePolicy.policy === 'hotfix_first',
+			fullDeployAllowed: directive.releasePolicy.fullDeployAllowed
+		} : {}),
+		details: {
+			phase: directive.phase,
+			allowed: directive.allowed,
+			reason: directive.reason,
+			releasePolicy: directive.releasePolicy,
+			...(input.details || {})
+		}
+	};
+}
+
+export function buildResolveIOAIManagerRecoveryReplayMatrix(
+	input: ResolveIOAIManagerRecoveryReplayMatrixInput = {}
+): ResolveIOAIManagerRecoveryReplayCase[] {
+	const surface = cleanText(input.surface || 'runner', 120);
+	const maxSameFailureRepeats = Math.max(1, Number(input.maxSameFailureRepeats || 2) || 2);
+	const includeReleaseRepair = input.includeReleaseRepair !== false;
+	const includeJourneyContractRepair = input.includeJourneyContractRepair !== false;
+	const cases: ResolveIOAIManagerRecoveryReplayCase[] = [];
+	const infraPolicy = decideResolveIOAIManagerPolicy({
+		history: [
+			{ lane: 'qa', stepType: 'workflow_qa', outcome: 'needs_repair', failureClass: 'infra', blocker: 'Chrome executable missing.', evidenceHash: 'chrome-missing' }
+		],
+		current: { lane: 'qa', stepType: 'workflow_qa', outcome: 'needs_repair', failureClass: 'infra', blocker: 'Chrome executable missing.', evidenceHash: 'chrome-missing' },
+		maxSameFailureRepeats
+	});
+	const infraDirective = buildResolveIOAIManagerRecoveryExecutionDirective({
+		action: infraPolicy.recoveryAction,
+		current: { lane: 'qa', stepType: 'workflow_qa', outcome: 'needs_repair', failureClass: 'infra', blocker: 'Chrome executable missing.', evidenceHash: 'chrome-missing' },
+		surface
+	});
+	cases.push(replayCaseFromDirective({
+		caseId: 'infra_routes_to_infra_repair',
+		surface,
+		action: infraPolicy.action,
+		reason: infraPolicy.reason,
+		directive: infraDirective,
+		expectedSafeAutoDispatch: true,
+		pass: infraPolicy.action === 'retry_infra'
+			&& infraPolicy.recoveryPlan.recoveryClass === 'infra_repair'
+			&& infraDirective.dispatchAction === 'run_infra_repair'
+			&& infraDirective.canRunProductRepair === false,
+		details: { recoveryClass: infraPolicy.recoveryPlan.recoveryClass }
+	}));
+	const releasePlan = buildResolveIOAIManagerRecoveryPlan({
+		action: 'continue',
+		reason: 'publish failed after business proof',
+		failureClass: 'release',
+		lane: 'publish',
+		stepType: 'test_deploy',
+		blocker: 'Domain publish failed for the current artifact.'
+	});
+	const releaseCurrent = {
+		lane: 'publish',
+		stepType: 'test_deploy',
+		outcome: 'needs_repair',
+		failureClass: 'release',
+		blocker: 'Domain publish failed for the current artifact.',
+		evidenceHash: 'release-domain-publish-failed',
+		artifactPaths: ['runner-evidence/release-status.json']
+	};
+	const releaseDirective = buildReplayDirectiveFromPlan({
+		surface,
+		plan: releasePlan,
+		current: releaseCurrent
+	});
+	cases.push(replayCaseFromDirective({
+		caseId: 'release_uses_hotfix_first_repair',
+		surface,
+		action: 'continue',
+		reason: 'publish failed after business proof',
+		directive: releaseDirective,
+		expectedSafeAutoDispatch: includeReleaseRepair,
+		pass: releasePlan.recoveryClass === 'release_repair'
+			&& releaseDirective.dispatchAction === 'run_release_repair'
+			&& releaseDirective.releasePolicy?.policy === 'hotfix_first'
+			&& releaseDirective.releasePolicy?.fullDeployAllowed === false
+			&& releaseDirective.canRunProductRepair === false,
+		details: { recoveryClass: releasePlan.recoveryClass }
+	}));
+	const journeyPlan = buildResolveIOAIManagerRecoveryPlan({
+		action: 'continue',
+		reason: 'journey contract missing first next last',
+		failureClass: 'journey',
+		lane: 'plan',
+		stepType: 'journey_contract',
+		blocker: 'Journey contract does not map the hub CTA to an action.'
+	});
+	const journeyDirective = buildReplayDirectiveFromPlan({
+		surface,
+		plan: journeyPlan,
+		current: {
+			lane: 'plan',
+			stepType: 'journey_contract',
+			outcome: 'needs_repair',
+			failureClass: 'journey',
+			blocker: 'Journey contract does not map the hub CTA to an action.',
+			evidenceHash: 'journey-contract-invalid'
+		}
+	});
+	cases.push(replayCaseFromDirective({
+		caseId: 'journey_repair_is_safe_only_for_aicoder_surfaces',
+		surface,
+		action: 'continue',
+		reason: 'journey contract missing first next last',
+		directive: journeyDirective,
+		expectedSafeAutoDispatch: includeJourneyContractRepair,
+		pass: journeyPlan.recoveryClass === 'journey_contract_repair'
+			&& journeyDirective.dispatchAction === 'run_journey_contract_repair'
+			&& journeyDirective.canRunProductRepair === false,
+		details: { recoveryClass: journeyPlan.recoveryClass }
+	}));
+	const weakPolicy = decideResolveIOAIManagerPolicy({
+		history: [
+			{ lane: 'repair', stepType: 'repair', outcome: 'needs_repair', failureClass: 'product_code', blocker: 'Save action still throws TypeError.', evidenceHash: 'save-before' },
+			{ lane: 'repair', stepType: 'repair', outcome: 'needs_repair', failureClass: 'product_code', blocker: 'Save action still throws TypeError.', evidenceHash: 'renamed-hash-only' }
+		],
+		current: { lane: 'repair', stepType: 'repair', outcome: 'needs_repair', failureClass: 'product_code', blocker: 'Save action still throws TypeError.', evidenceHash: 'renamed-hash-only' },
+		maxSameFailureRepeats
+	});
+	const weakDirective = buildResolveIOAIManagerRecoveryExecutionDirective({
+		action: weakPolicy.recoveryAction,
+		current: { lane: 'repair', stepType: 'repair', outcome: 'needs_repair', failureClass: 'product_code', blocker: 'Save action still throws TypeError.', evidenceHash: 'renamed-hash-only' },
+		surface
+	});
+	cases.push(replayCaseFromDirective({
+		caseId: 'weak_hash_only_evidence_stays_parked',
+		surface,
+		action: weakPolicy.action,
+		reason: weakPolicy.reason,
+		directive: weakDirective,
+		expectedSafeAutoDispatch: true,
+		pass: weakPolicy.action === 'park_repeated_failure'
+			&& weakPolicy.materialEvidence === false
+			&& weakPolicy.loopBudgetShouldReset === false
+			&& weakDirective.dispatchAction === 'run_evidence_probe',
+		loopBudgetShouldReset: weakPolicy.loopBudgetShouldReset,
+		materialEvidence: weakPolicy.materialEvidence,
+		evidenceStrength: weakPolicy.evidenceStrength,
+		details: { evidenceSignals: weakPolicy.evidenceSignals }
+	}));
+	const materialPolicy = decideResolveIOAIManagerPolicy({
+		history: [
+			{ lane: 'repair', stepType: 'repair', outcome: 'needs_repair', failureClass: 'product_code', blocker: 'Save action still throws TypeError.', evidenceHash: 'save-before', artifactPaths: ['qa/save-before.log'] },
+			{
+				lane: 'repair',
+				stepType: 'repair',
+				outcome: 'needs_repair',
+				failureClass: 'product_code',
+				blocker: 'Save action still throws TypeError.',
+				summary: 'New DOM trace proves the click reaches the method with an undefined id.',
+				evidenceHash: 'save-dom-trace',
+				artifactPaths: ['qa/save-before.log', 'qa/save-dom-trace.json']
+			}
+		],
+		current: {
+			lane: 'repair',
+			stepType: 'repair',
+			outcome: 'needs_repair',
+			failureClass: 'product_code',
+			blocker: 'Save action still throws TypeError.',
+			summary: 'New DOM trace proves the click reaches the method with an undefined id.',
+			evidenceHash: 'save-dom-trace',
+			artifactPaths: ['qa/save-before.log', 'qa/save-dom-trace.json']
+		},
+		maxSameFailureRepeats
+	});
+	cases.push({
+		caseId: 'material_evidence_resets_loop_budget',
+		surface,
+		pass: materialPolicy.action === 'continue'
+			&& materialPolicy.materialEvidence === true
+			&& materialPolicy.loopBudgetShouldReset === true,
+		action: materialPolicy.action,
+		reason: materialPolicy.reason,
+		recoveryClass: materialPolicy.recoveryPlan.recoveryClass,
+		dispatchAction: materialPolicy.recoveryAction.mode,
+		safeAutoDispatch: false,
+		expectedSafeAutoDispatch: false,
+		productRepairAllowed: materialPolicy.recoveryAction.productRepairAllowed,
+		loopBudgetShouldReset: materialPolicy.loopBudgetShouldReset,
+		materialEvidence: materialPolicy.materialEvidence,
+		evidenceStrength: materialPolicy.evidenceStrength,
+		details: { evidenceSignals: materialPolicy.evidenceSignals }
+	});
+	const productPlan = buildResolveIOAIManagerRecoveryPlan({
+		action: 'continue',
+		reason: 'business proof still failing',
+		failureClass: 'product_code',
+		lane: 'repair',
+		stepType: 'repair',
+		blocker: 'Save action still throws TypeError.',
+		productRepairFailure: true
+	});
+	const productDirective = buildReplayDirectiveFromPlan({
+		surface,
+		plan: productPlan,
+		current: {
+			lane: 'repair',
+			stepType: 'repair',
+			outcome: 'needs_repair',
+			failureClass: 'product_code',
+			blocker: 'Save action still throws TypeError.',
+			evidenceHash: 'save-product-repair'
+		}
+	});
+	const productSafe = isResolveIOAIManagerSafeAutoDispatch({
+		dispatchAction: productDirective.dispatchAction,
+		directive: productDirective,
+		includeProductRepair: input.includeProductRepair === true
+	});
+	cases.push({
+		caseId: 'product_repair_requires_explicit_operator_policy',
+		surface,
+		pass: productPlan.recoveryClass === 'product_code_repair'
+			&& productDirective.dispatchAction === 'run_targeted_product_repair'
+			&& productSafe === false,
+		action: 'continue',
+		reason: 'business proof still failing',
+		recoveryClass: productPlan.recoveryClass,
+		dispatchAction: productDirective.dispatchAction,
+		safeAutoDispatch: productSafe,
+		expectedSafeAutoDispatch: false,
+		productRepairAllowed: productDirective.canRunProductRepair,
+		loopBudgetShouldReset: false,
+		materialEvidence: false,
+		evidenceStrength: 'none',
+		details: { phase: productDirective.phase, allowed: productDirective.allowed }
+	});
+	const duplicateReleasePolicy = buildResolveIOAIManagerHotfixFirstReleasePolicy({
+		surface,
+		deployFingerprint: `${surface}-artifact-sha`,
+		lastDeployFingerprint: `${surface}-artifact-sha`,
+		deployStatus: 'completed',
+		publishStatus: 'published'
+	});
+	cases.push({
+		caseId: 'duplicate_release_fingerprint_blocks_full_deploy',
+		surface,
+		pass: duplicateReleasePolicy.recommendedAction === 'block_duplicate_deploy'
+			&& duplicateReleasePolicy.duplicateDeployBlocked === true
+			&& duplicateReleasePolicy.fullDeployAllowed === false,
+		action: duplicateReleasePolicy.recommendedAction,
+		reason: duplicateReleasePolicy.reason,
+		recoveryClass: 'release_repair',
+		dispatchAction: 'run_release_repair',
+		safeAutoDispatch: includeReleaseRepair,
+		expectedSafeAutoDispatch: includeReleaseRepair,
+		productRepairAllowed: false,
+		loopBudgetShouldReset: false,
+		materialEvidence: false,
+		evidenceStrength: 'none',
+		hotfixFirst: true,
+		fullDeployAllowed: duplicateReleasePolicy.fullDeployAllowed,
+		details: { releasePolicy: duplicateReleasePolicy }
+	});
+	return cases;
+}