@resolveio/server-lib 22.3.141 → 22.3.142

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

@@ -0,0 +1,1740 @@
+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 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 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;
+	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 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;
+	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;
+	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;
+	loopBudgetShouldReset: boolean;
+	productRepairFailure: boolean;
+	recoveryPlan: ResolveIOAIManagerRecoveryPlan;
+	recoveryCheckpoint: ResolveIOAIManagerRecoveryCheckpoint;
+	recoveryEvidenceProbe: ResolveIOAIManagerRecoveryEvidenceProbe;
+	recoveryAction: ResolveIOAIManagerRecoveryActionPacket;
+}
+
+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 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 ? ['changed evidence hash', 'new artifact path'] : [])
+	].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 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,
+		successCriteria: probe.acceptanceEvidence.slice(0, 20),
+		retryPolicy: {
+			allowImmediateRetry: checkpoint.status !== 'parked' && mode !== 'manual_review',
+			requireNewEvidence,
+			resetLoopWhen,
+			stopWhen
+		},
+		...(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
+			? []
+			: ['Do not run product-code repair from this directive unless canRunProductRepair is true.'],
+		...(dispatchDecision.dispatchRecord ? { dispatchRecord: dispatchDecision.dispatchRecord } : {}),
+		createdAt: now
+	};
+}
+
+function listHasNewEntry(current: string[], previous: string[]): boolean {
+	const existing = new Set(previous.map((entry) => cleanText(entry, 500)).filter(Boolean));
+	return current.some((entry) => {
+		const normalized = cleanText(entry, 500);
+		return !!normalized && !existing.has(normalized);
+	});
+}
+
+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 blockerFingerprint = hasCurrent
+		? resolveResolveIOAIManagerBlockerFingerprint(current, checkpoint.objective)
+		: checkpoint.blockerFingerprint;
+	const evidenceHash = hasCurrent ? hashResolveIOAIManagerEvidence(current) : checkpoint.evidenceHash;
+	const changedFiles = hasCurrent ? cleanList(current.changedFiles, 80, 500) : checkpoint.changedFiles;
+	const artifactPaths = hasCurrent ? cleanList(current.artifactPaths, 80, 500) : checkpoint.artifactPaths;
+	const evidenceChanged = evidenceHash !== checkpoint.evidenceHash
+		|| blockerFingerprint !== checkpoint.blockerFingerprint
+		|| listHasNewEntry(changedFiles, checkpoint.changedFiles)
+		|| listHasNewEntry(artifactPaths, checkpoint.artifactPaths);
+	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,
+		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.attempts >= checkpoint.maxAttemptsBeforePark && !evidenceChanged) {
+		return makeDecision('collect_new_evidence', 'recovery_gate_attempt_limit_requires_new_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_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 the new evidence hash changes.'
+			],
+			['same failure count', 'blocker fingerprint', 'evidence hash'],
+			['changed evidence hash', 'new artifact path', 'revised diagnosis or journey contract'],
+			['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 without rewriting working app flow.',
+			'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.',
+				'Repair the release artifact/config/seed issue.',
+				'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']
+		);
+	}
+	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 = failureEvidenceKey(current);
+	let count = 0;
+	for (let index = records.length - 1; index >= 0; index -= 1) {
+		const record = records[index];
+		if (isPassingOutcome(record)) {
+			break;
+		}
+		if (failureEvidenceKey(record) !== currentKey) {
+			break;
+		}
+		count += 1;
+	}
+	return count;
+}
+
+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 current = input.current || history[history.length - 1] || {};
+	const failureClass = normalizeResolveIOAIManagerFailureClass(current.failureClass);
+	const blockerFingerprint = resolveResolveIOAIManagerBlockerFingerprint(current);
+	const evidenceHash = hashResolveIOAIManagerEvidence(current);
+	const previous = history.length > 1 ? history[history.length - 2] : undefined;
+	const previousSameFailure = previous && failureKey(previous) === failureKey(current);
+	const previousEvidenceHash = previousSameFailure ? hashResolveIOAIManagerEvidence(previous) : '';
+	const newEvidence = !!previousSameFailure && !!previousEvidenceHash && previousEvidenceHash !== evidenceHash;
+	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,
+		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 && !newEvidence) {
+		return withPlan('park_repeated_failure', '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) {
+		return withPlan('continue', newEvidence
+				? 'manager_policy_new_evidence_resets_loop_budget'
+				: 'manager_policy_new_failure_or_lane', {
+			loopBudgetShouldReset: true
+		});
+	}
+	return withPlan('continue', 'manager_policy_retry_below_repeat_limit');
+}