@resolveio/server-lib 22.3.219 → 22.3.221

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

@@ -0,0 +1,961 @@
+import {
+	assessResolveIOAIManagerEvidenceChange,
+	decideResolveIOAIManagerAutonomyPolicy,
+	ResolveIOAIManagerAutonomyPolicyDecision,
+	ResolveIOAIManagerAutonomyPolicyInput,
+	ResolveIOAIManagerFailureRecord,
+	ResolveIOAIManagerRecoveryActionDispatchRecord,
+	ResolveIOAIManagerRecoveryActionPacket,
+	ResolveIOAIManagerRecoveryCheckpoint,
+	ResolveIOAIManagerRecoveryExecutionDirective,
+	ResolveIOAIManagerRecoveryEvidenceProbe,
+	ResolveIOAIManagerRecoveryPlan
+} from './ai-runner-manager-policy';
+
+export type ResolveIOAIManagerAutopilotSafetyLevel = 'low' | 'medium' | 'high' | 'blocked';
+
+export interface ResolveIOAIManagerAutopilotRecommendedAction {
+	action: string;
+	label: string;
+	reason: string;
+	safety: ResolveIOAIManagerAutopilotSafetyLevel;
+	enabled: boolean;
+	autoRunnable: boolean;
+	expectedResult: string;
+	requiresNewEvidence: boolean;
+	canRunProductRepair: boolean;
+	canRunExpensiveModel: boolean;
+	canResetLoopAfterEvidence: boolean;
+	singleActionOnly: boolean;
+	allowedDispatchAction: string;
+	costCeilingUsd: number;
+	requiredStateTransition: string;
+	proofRequiredBeforeContinuation: boolean;
+	autonomyMode: string;
+	autonomyCanAutoDispatch: boolean;
+	autonomyBlocked: boolean;
+	expectedValueScore: number;
+	expectedValueSource: string;
+	expectedValuePositive: boolean;
+	evidenceBacked: boolean;
+	evidenceStrength: string;
+	dispatchAction?: string;
+}
+
+export interface ResolveIOAIManagerAutopilotControlAction {
+	action: string;
+	label: string;
+	group: 'primary' | 'policy' | 'evidence' | 'release' | 'danger';
+	enabled: boolean;
+	autoRunnable: boolean;
+	requiresConfirmation: boolean;
+	confirmationReason: string;
+	safety: ResolveIOAIManagerAutopilotSafetyLevel;
+	reason: string;
+	nextCommand: string;
+	expectedResult: string;
+	costCeilingUsd: number;
+}
+
+export interface ResolveIOAIManagerAutopilotControlGroup {
+	groupId: 'policy' | 'evidence' | 'release' | 'danger';
+	label: string;
+	actions: ResolveIOAIManagerAutopilotControlAction[];
+}
+
+export interface ResolveIOAIManagerAutopilotControlPolicy {
+	mode: string;
+	modeLabel: string;
+	modeDescription: string;
+	onePrimaryActionOnly: true;
+	blocked: boolean;
+	blockedReason: string;
+	canAutoDispatch: boolean;
+	requiresHumanDecision: boolean;
+	primaryAction: ResolveIOAIManagerAutopilotControlAction;
+	secondaryActionGroups: ResolveIOAIManagerAutopilotControlGroup[];
+	budget: {
+		currentRunUsd: number;
+		totalUsd: number;
+		projectedActionCostUsd: number;
+		projectedSpendUsd: number;
+		budgetSoftUsd: number;
+		budgetHardUsd: number;
+		softBudgetExceeded: boolean;
+		hardBudgetExceeded: boolean;
+		untrackedWarning: string;
+	};
+}
+
+export interface ResolveIOAIManagerHumanDecisionChoice {
+	choiceId: string;
+	label: string;
+	action: string;
+	description: string;
+	safety: ResolveIOAIManagerAutopilotSafetyLevel;
+	requiresConfirmation: boolean;
+	nextCommand: string;
+	expectedResult: string;
+}
+
+export interface ResolveIOAIManagerHumanDecisionRequest {
+	requestId: string;
+	required: boolean;
+	status: 'not_required' | 'waiting_for_operator';
+	reason: string;
+	question: string;
+	preferredChoiceId: string;
+	evidence: {
+		failureClass: string;
+		blocker: string;
+		blockerFingerprint: string;
+		evidenceHash: string;
+		checkpointId: string;
+		recoveryClass: string;
+		dispatchAction: string;
+		requiredArtifacts: string[];
+		forbiddenActions: string[];
+		recentArtifactPaths: string[];
+	};
+	choices: ResolveIOAIManagerHumanDecisionChoice[];
+	blockedUntil: string[];
+	createdAt: string;
+}
+
+export interface ResolveIOAIManagerAutopilotLoopGuard {
+	state: 'clear' | 'collecting_evidence' | 'parked' | 'manual_handoff' | 'complete';
+	blocked: boolean;
+	reason: string;
+	failureClass: string;
+	blocker: string;
+	blockerFingerprint: string;
+	evidenceHash: string;
+	materialEvidence: boolean;
+	evidenceStrength: string;
+	evidenceSignals: string[];
+	sameEvidenceDispatchCount: number;
+	sameEvidenceAlreadyAttempted: boolean;
+	loopCount: number;
+	maxLoopCount: number;
+	attempts: number;
+	maxAttemptsBeforePark: number;
+	canResetLoopAfterEvidence: boolean;
+	resetRequires: string[];
+}
+
+export interface ResolveIOAIManagerAutopilotRecentDispatch {
+	dispatchId: string;
+	actionId: string;
+	checkpointId: string;
+	probeId: string;
+	mode: string;
+	dispatchAction: string;
+	status: string;
+	reason: string;
+	evidenceHash: string;
+	blockerFingerprint: string;
+	artifactPaths: string[];
+	startedAt: string;
+	completedAt: string;
+	createdAt: string;
+}
+
+export interface ResolveIOAIManagerAutopilotSnapshot {
+	surface: string;
+	runId: string;
+	title: string;
+	status: string;
+	phase: string;
+	lane: string;
+	stepType: string;
+	runKind: string;
+	recommendedAction: ResolveIOAIManagerAutopilotRecommendedAction;
+	controlPolicy: ResolveIOAIManagerAutopilotControlPolicy;
+	loopGuard: ResolveIOAIManagerAutopilotLoopGuard;
+	recovery: {
+		checkpointId: string;
+		recoveryClass: string;
+		dispatchAction: string;
+		singleActionOnly: boolean;
+		allowedDispatchAction: string;
+		directiveAllowed: boolean;
+		evidenceOnly: boolean;
+		productRepairAllowed: boolean;
+		expensiveModelAllowed: boolean;
+		costCeilingUsd: number;
+		requiredStateTransition: string;
+		proofRequiredBeforeContinuation: boolean;
+		requiredArtifacts: string[];
+		nextCommands: string[];
+		successCriteria: string[];
+		exitCriteria: string[];
+		forbiddenActions: string[];
+	};
+	autonomyPolicy: ResolveIOAIManagerAutonomyPolicyDecision;
+	recentDispatches: ResolveIOAIManagerAutopilotRecentDispatch[];
+	humanDecision: ResolveIOAIManagerHumanDecisionRequest;
+	cost: {
+		currentRunUsd: number;
+		totalUsd: number;
+		currentRunTokens: number;
+		totalTokens: number;
+		untrackedWarning: string;
+	};
+	updatedAt: string;
+}
+
+export interface ResolveIOAIManagerAutopilotSnapshotInput {
+	surface: string;
+	runId?: string;
+	title?: string;
+	status?: string;
+	phase?: string;
+	lane?: string;
+	stepType?: string;
+	runKind?: string;
+	current?: ResolveIOAIManagerFailureRecord;
+	recoveryPlan?: ResolveIOAIManagerRecoveryPlan;
+	recoveryCheckpoint?: ResolveIOAIManagerRecoveryCheckpoint;
+	recoveryEvidenceProbe?: ResolveIOAIManagerRecoveryEvidenceProbe;
+	recoveryAction?: ResolveIOAIManagerRecoveryActionPacket;
+	recoveryDirective?: ResolveIOAIManagerRecoveryExecutionDirective;
+	recoveryDispatchHistory?: ResolveIOAIManagerRecoveryActionDispatchRecord[];
+	loopCount?: number;
+	maxLoopCount?: number;
+	currentRunUsd?: number;
+	totalUsd?: number;
+	currentRunTokens?: number;
+	totalTokens?: number;
+	untrackedCostWarning?: string;
+	autonomyPolicy?: ResolveIOAIManagerAutonomyPolicyInput;
+	updatedAt?: Date | string;
+}
+
+function cleanText(value: any, max = 1000): string {
+	return String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+function cleanList(value: any, limit = 20, max = 500): string[] {
+	const raw = Array.isArray(value) ? value : [];
+	const output: string[] = [];
+	for (const entry of raw) {
+		const cleaned = cleanText(entry, max);
+		if (cleaned && !output.includes(cleaned)) {
+			output.push(cleaned);
+		}
+		if (output.length >= limit) {
+			break;
+		}
+	}
+	return output;
+}
+
+function cleanNumber(value: any): number {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+function isoNow(value?: Date | string): string {
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+	const parsed = value ? new Date(value) : new Date();
+	return Number.isFinite(parsed.getTime()) ? parsed.toISOString() : 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'}`;
+}
+
+function defaultLabelForAction(action: string): string {
+	switch (action) {
+		case 'run_evidence_probe':
+			return 'Collect New Evidence';
+		case 'run_read_only_diagnosis':
+			return 'Run Diagnosis';
+		case 'run_infra_repair':
+			return 'Repair Infra';
+		case 'run_compile_repair':
+			return 'Repair Compile';
+		case 'run_journey_contract_repair':
+			return 'Repair Journey';
+		case 'run_business_assertion_repair':
+			return 'Repair Business Proof';
+		case 'run_release_repair':
+			return 'Repair Release';
+		case 'run_targeted_product_repair':
+			return 'Run Targeted Repair';
+		case 'advance':
+			return 'Advance';
+		case 'continue_gate':
+			return 'Continue Gate';
+		case 'park_manual':
+			return 'Attach New Evidence';
+		default:
+			return action ? cleanText(action.replace(/_/g, ' '), 120) : 'Review Manager State';
+	}
+}
+
+function expectedResultForAction(action: string, evidenceOnly: boolean): string {
+	if (action === 'park_manual') {
+		return 'Runner stays parked until new evidence, operator approval, or a changed blocker is recorded.';
+	}
+	if (evidenceOnly || action === 'run_evidence_probe' || action === 'run_read_only_diagnosis') {
+		return 'Runner records a new artifact path or changed evidence hash before any more product repair.';
+	}
+	if (action === 'run_infra_repair' || action === 'run_compile_repair' || action === 'run_release_repair') {
+		return 'Runner repairs only the named deterministic gate and reruns that gate.';
+	}
+	if (action === 'run_targeted_product_repair') {
+		return 'Runner performs one bounded owner-scope repair and then returns to deterministic proof.';
+	}
+	return 'Runner advances only after the current gate has proof.';
+}
+
+function autonomyModeLabel(mode: string): string {
+	switch (mode) {
+		case 'monitor_only':
+			return 'Monitor Only';
+		case 'auto_retry_within_budget':
+			return 'Auto Retry Within Budget';
+		case 'manual_only':
+		default:
+			return 'Manual Only';
+	}
+}
+
+function autonomyModeDescription(mode: string): string {
+	switch (mode) {
+		case 'monitor_only':
+			return 'Watch the runner and record evidence, but do not dispatch recovery, repair, QA, release, or customer actions.';
+		case 'auto_retry_within_budget':
+			return 'Auto-dispatch only evidence-backed actions with positive expected value inside the configured budget.';
+		case 'manual_only':
+		default:
+			return 'Show the safest next action, but require an operator to dispatch it.';
+	}
+}
+
+function controlAction(input: {
+	action: string;
+	label?: string;
+	group: ResolveIOAIManagerAutopilotControlAction['group'];
+	enabled?: boolean;
+	autoRunnable?: boolean;
+	requiresConfirmation?: boolean;
+	confirmationReason?: string;
+	safety?: ResolveIOAIManagerAutopilotSafetyLevel;
+	reason?: string;
+	nextCommand?: string;
+	expectedResult?: string;
+	costCeilingUsd?: number;
+}): ResolveIOAIManagerAutopilotControlAction {
+	const action = cleanText(input.action, 120) || 'review';
+	return {
+		action,
+		label: cleanText(input.label, 160) || defaultLabelForAction(action),
+		group: input.group,
+		enabled: input.enabled !== false,
+		autoRunnable: input.autoRunnable === true,
+		requiresConfirmation: input.requiresConfirmation === true,
+		confirmationReason: cleanText(input.confirmationReason, 500),
+		safety: input.safety || 'medium',
+		reason: cleanText(input.reason, 1000),
+		nextCommand: cleanText(input.nextCommand || action, 160),
+		expectedResult: cleanText(input.expectedResult || expectedResultForAction(action, false), 500),
+		costCeilingUsd: cleanNumber(input.costCeilingUsd)
+	};
+}
+
+function safetyFor(input: {
+	action: string;
+	enabled: boolean;
+	evidenceOnly: boolean;
+	productRepairAllowed: boolean;
+	expensiveModelAllowed: boolean;
+}): ResolveIOAIManagerAutopilotSafetyLevel {
+	if (!input.enabled || input.action === 'park_manual') {
+		return 'blocked';
+	}
+	if (input.evidenceOnly || input.action === 'run_evidence_probe' || input.action === 'run_read_only_diagnosis') {
+		return 'low';
+	}
+	if (input.expensiveModelAllowed || input.action === 'run_targeted_product_repair') {
+		return 'high';
+	}
+	if (input.productRepairAllowed) {
+		return 'medium';
+	}
+	return 'medium';
+}
+
+function buildControlPolicy(input: {
+	recommendedAction: ResolveIOAIManagerAutopilotRecommendedAction;
+	autonomyPolicy: ResolveIOAIManagerAutonomyPolicyDecision;
+	humanDecision: ResolveIOAIManagerHumanDecisionRequest;
+	recoveryRequiredArtifacts: string[];
+	recoveryForbiddenActions: string[];
+	currentRunUsd: number;
+	totalUsd: number;
+	untrackedWarning: string;
+}): ResolveIOAIManagerAutopilotControlPolicy {
+	const recommended = input.recommendedAction;
+	const autonomy = input.autonomyPolicy;
+	const blocked = recommended.enabled === false || autonomy.blocked === true || recommended.action === 'park_manual';
+	const primaryAction = controlAction({
+		action: recommended.action,
+		label: recommended.label,
+		group: 'primary',
+		enabled: recommended.enabled,
+		autoRunnable: recommended.autoRunnable,
+		requiresConfirmation: recommended.safety === 'high'
+			|| recommended.canRunExpensiveModel
+			|| recommended.action === 'run_targeted_product_repair'
+			|| recommended.action === 'run_release_repair',
+		confirmationReason: recommended.safety === 'high'
+			? 'This can spend model tokens or modify product code; confirm the diagnosis/proof gate is current.'
+			: recommended.action === 'run_release_repair'
+				? 'This can affect release state; confirm hotfix/release evidence first.'
+				: '',
+		safety: recommended.safety,
+		reason: recommended.reason,
+		nextCommand: recommended.allowedDispatchAction || recommended.dispatchAction || recommended.action,
+		expectedResult: recommended.expectedResult,
+		costCeilingUsd: recommended.costCeilingUsd
+	});
+	const policyActions = (['manual_only', 'monitor_only', 'auto_retry_within_budget'] as const).map((mode) => controlAction({
+		action: `set_mode:${mode}`,
+		label: autonomyModeLabel(mode),
+		group: 'policy',
+		enabled: autonomy.mode !== mode,
+		autoRunnable: false,
+		requiresConfirmation: mode === 'auto_retry_within_budget',
+		confirmationReason: mode === 'auto_retry_within_budget'
+			? 'Auto retry will dispatch only evidence-backed actions inside budget, but can still spend runner tokens.'
+			: '',
+		safety: mode === 'auto_retry_within_budget' ? 'medium' : 'low',
+		reason: mode === autonomy.mode ? 'Current manager mode.' : autonomyModeDescription(mode),
+		nextCommand: `set_manager_mode_${mode}`,
+		expectedResult: mode === autonomy.mode ? 'Mode is unchanged.' : `Manager switches to ${autonomyModeLabel(mode)}.`,
+		costCeilingUsd: 0
+	}));
+	const choiceActions = (input.humanDecision.choices || [])
+		.filter((choice) => choice.action !== recommended.action)
+		.map((choice) => controlAction({
+			action: choice.action,
+			label: choice.label,
+			group: choice.action === 'record_hotfix_evidence' ? 'release' : (choice.action === 'park_manual' ? 'danger' : 'evidence'),
+			enabled: true,
+			autoRunnable: false,
+			requiresConfirmation: choice.requiresConfirmation || choice.action === 'park_manual',
+			confirmationReason: choice.requiresConfirmation
+				? choice.description
+				: choice.action === 'park_manual'
+					? 'Parking stops automated progress until new evidence or operator policy changes.'
+					: '',
+			safety: choice.safety,
+			reason: choice.description,
+			nextCommand: choice.nextCommand,
+			expectedResult: choice.expectedResult,
+			costCeilingUsd: 0
+		}));
+	if (recommended.requiresNewEvidence && !choiceActions.some((action) => action.action === 'run_evidence_probe')) {
+		choiceActions.unshift(controlAction({
+			action: 'run_evidence_probe',
+			label: 'Collect New Evidence',
+			group: 'evidence',
+			enabled: true,
+			autoRunnable: false,
+			requiresConfirmation: false,
+			safety: 'low',
+			reason: 'Collect deterministic evidence before another repair loop.',
+			nextCommand: 'run_evidence_probe',
+			expectedResult: 'A new artifact path or changed evidence hash is recorded.',
+			costCeilingUsd: 0.25
+		}));
+	}
+	const grouped = ([
+		{ groupId: 'policy', label: 'Mode', actions: policyActions },
+		{ groupId: 'evidence', label: 'Evidence', actions: choiceActions.filter((action) => action.group === 'evidence') },
+		{ groupId: 'release', label: 'Release', actions: choiceActions.filter((action) => action.group === 'release') },
+		{ groupId: 'danger', label: 'Danger Zone', actions: choiceActions.filter((action) => action.group === 'danger') }
+	] as ResolveIOAIManagerAutopilotControlGroup[]).filter((group) => group.actions.length > 0);
+	return {
+		mode: autonomy.mode,
+		modeLabel: autonomyModeLabel(autonomy.mode),
+		modeDescription: autonomyModeDescription(autonomy.mode),
+		onePrimaryActionOnly: true,
+		blocked,
+		blockedReason: blocked ? cleanText(autonomy.reason || recommended.reason, 1000) : '',
+		canAutoDispatch: recommended.autoRunnable === true && autonomy.canAutoDispatch === true,
+		requiresHumanDecision: input.humanDecision.required === true || recommended.autoRunnable !== true,
+		primaryAction,
+		secondaryActionGroups: grouped,
+		budget: {
+			currentRunUsd: input.currentRunUsd,
+			totalUsd: input.totalUsd,
+			projectedActionCostUsd: autonomy.projectedActionCostUsd,
+			projectedSpendUsd: autonomy.projectedSpendUsd,
+			budgetSoftUsd: autonomy.budgetSoftUsd,
+			budgetHardUsd: autonomy.budgetHardUsd,
+			softBudgetExceeded: autonomy.softBudgetExceeded,
+			hardBudgetExceeded: autonomy.hardBudgetExceeded,
+			untrackedWarning: input.untrackedWarning
+		}
+	};
+}
+
+function resolveDispatchAction(input: ResolveIOAIManagerAutopilotSnapshotInput): string {
+	const directiveAction = cleanText(input.recoveryDirective?.dispatchAction, 120);
+	if (directiveAction) {
+		return directiveAction;
+	}
+	const actionMode = cleanText(input.recoveryAction?.mode, 120);
+	switch (actionMode) {
+		case 'collect_evidence':
+			return 'run_evidence_probe';
+		case 'read_only_diagnosis':
+			return 'run_read_only_diagnosis';
+		case 'repair_infra':
+			return 'run_infra_repair';
+		case 'repair_compile':
+			return 'run_compile_repair';
+		case 'repair_journey_contract':
+			return 'run_journey_contract_repair';
+		case 'repair_business_assertion':
+			return 'run_business_assertion_repair';
+		case 'repair_release':
+			return 'run_release_repair';
+		case 'targeted_product_repair':
+			return 'run_targeted_product_repair';
+		case 'advance':
+			return 'advance';
+		case 'continue_gate':
+			return 'continue_gate';
+		case 'manual_review':
+			return 'park_manual';
+		default:
+			return input.recoveryCheckpoint?.status === 'parked' ? 'run_evidence_probe' : 'continue_gate';
+	}
+}
+
+function countSameEvidenceDispatches(input: ResolveIOAIManagerAutopilotSnapshotInput, dispatchAction: string): number {
+	const checkpointId = cleanText(input.recoveryCheckpoint?.checkpointId || input.recoveryAction?.checkpointId, 160);
+	const actionId = cleanText(input.recoveryAction?.actionId, 160);
+	const evidenceHash = cleanText(input.current?.evidenceHash || input.recoveryCheckpoint?.evidenceHash, 160);
+	const blockerFingerprint = cleanText(input.current?.blockerFingerprint || input.recoveryCheckpoint?.blockerFingerprint, 160);
+	const history = Array.isArray(input.recoveryDispatchHistory) ? input.recoveryDispatchHistory : [];
+	return history.filter((entry) => {
+		const sameCheckpoint = checkpointId && cleanText(entry?.checkpointId, 160) === checkpointId;
+		const sameAction = actionId && cleanText(entry?.actionId, 160) === actionId;
+		const sameEvidence = !evidenceHash || cleanText(entry?.evidenceHash, 160) === evidenceHash;
+		const sameBlocker = !blockerFingerprint || cleanText(entry?.blockerFingerprint, 160) === blockerFingerprint;
+		const sameDispatchAction = !dispatchAction
+			|| dispatchAction === 'park_manual'
+			|| cleanText(entry?.dispatchAction, 120) === dispatchAction
+			|| cleanText(entry?.dispatchAction, 120) === 'park_manual';
+		return (sameCheckpoint || sameAction) && sameEvidence && sameBlocker && sameDispatchAction;
+	}).length;
+}
+
+function normalizeRecentDispatches(history: ResolveIOAIManagerRecoveryActionDispatchRecord[] | undefined): ResolveIOAIManagerAutopilotRecentDispatch[] {
+	const source = Array.isArray(history) ? history.filter(Boolean) : [];
+	return source.slice(-5).reverse().map((entry) => ({
+		dispatchId: cleanText(entry?.dispatchId, 160),
+		actionId: cleanText(entry?.actionId, 160),
+		checkpointId: cleanText(entry?.checkpointId, 160),
+		probeId: cleanText(entry?.probeId, 160),
+		mode: cleanText(entry?.mode, 120),
+		dispatchAction: cleanText(entry?.dispatchAction, 120),
+		status: cleanText(entry?.status, 80),
+		reason: cleanText(entry?.reason, 500),
+		evidenceHash: cleanText(entry?.evidenceHash, 160),
+		blockerFingerprint: cleanText(entry?.blockerFingerprint, 160),
+		artifactPaths: cleanList(entry?.artifactPaths, 8, 500),
+		startedAt: cleanText(entry?.startedAt, 80),
+		completedAt: cleanText(entry?.completedAt, 80),
+		createdAt: cleanText(entry?.createdAt, 80)
+	}));
+}
+
+function humanDecisionChoice(
+	choiceId: string,
+	label: string,
+	action: string,
+	description: string,
+	safety: ResolveIOAIManagerAutopilotSafetyLevel,
+	nextCommand: string,
+	expectedResult: string,
+	requiresConfirmation = false
+): ResolveIOAIManagerHumanDecisionChoice {
+	return {
+		choiceId,
+		label,
+		action,
+		description: cleanText(description, 500),
+		safety,
+		requiresConfirmation,
+		nextCommand,
+		expectedResult: cleanText(expectedResult, 500)
+	};
+}
+
+function buildHumanDecisionRequest(input: {
+	snapshot: ResolveIOAIManagerAutopilotSnapshotInput;
+	recommendedAction: ResolveIOAIManagerAutopilotRecommendedAction;
+	loopState: ResolveIOAIManagerAutopilotLoopGuard['state'];
+	reason: string;
+	dispatchAction: string;
+	sameEvidenceAlreadyAttempted: boolean;
+	requiresNewEvidence: boolean;
+	requiredArtifacts: string[];
+	forbiddenActions: string[];
+	recentDispatches: ResolveIOAIManagerAutopilotRecentDispatch[];
+	updatedAt?: Date | string;
+}): ResolveIOAIManagerHumanDecisionRequest {
+	const checkpoint = input.snapshot.recoveryCheckpoint;
+	const current = input.snapshot.current || {};
+	const recoveryClass = cleanText(checkpoint?.recoveryClass || input.snapshot.recoveryAction?.recoveryClass || input.snapshot.recoveryPlan?.recoveryClass, 120);
+	const failureClass = cleanText(current.failureClass, 120);
+	const blocker = cleanText(current.blocker || current.summary || input.reason, 1000);
+	const evidenceHash = cleanText(current.evidenceHash || checkpoint?.evidenceHash, 160);
+	const blockerFingerprint = cleanText(current.blockerFingerprint || checkpoint?.blockerFingerprint, 160);
+	const checkpointId = cleanText(checkpoint?.checkpointId || input.snapshot.recoveryAction?.checkpointId, 160);
+	const recentArtifactPaths = cleanList(
+		current.artifactPaths?.length
+			? current.artifactPaths
+			: input.recentDispatches.flatMap((entry) => entry.artifactPaths || []),
+		12,
+		500
+	);
+	const required = input.sameEvidenceAlreadyAttempted
+		|| input.loopState === 'parked'
+		|| input.loopState === 'manual_handoff'
+		|| input.recommendedAction.enabled === false
+		|| input.recommendedAction.action === 'park_manual';
+	const baseEvidence = {
+		failureClass,
+		blocker,
+		blockerFingerprint,
+		evidenceHash,
+		checkpointId,
+		recoveryClass,
+		dispatchAction: input.dispatchAction,
+		requiredArtifacts: input.requiredArtifacts,
+		forbiddenActions: input.forbiddenActions,
+		recentArtifactPaths
+	};
+	const blockedUntil = input.requiresNewEvidence
+		? Array.from(new Set([
+			'new material evidence changes the evidenceHash or blockerFingerprint',
+			'new artifact path is recorded from the failed deterministic gate',
+			'operator updates scope, diagnosis, budget, or retry policy'
+		]))
+		: [];
+	if (!required) {
+		return {
+			requestId: stableHash('mgr-human', {
+				checkpointId,
+				evidenceHash,
+				blockerFingerprint,
+				required: false
+			}),
+			required: false,
+			status: 'not_required',
+			reason: 'No human decision is required for the current bounded next action.',
+			question: '',
+			preferredChoiceId: '',
+			evidence: baseEvidence,
+			choices: [],
+			blockedUntil: [],
+			createdAt: isoNow(input.updatedAt)
+		};
+	}
+	const choices: ResolveIOAIManagerHumanDecisionChoice[] = [];
+	if (input.requiresNewEvidence || input.sameEvidenceAlreadyAttempted || input.loopState === 'parked') {
+		choices.push(humanDecisionChoice(
+			'attach_new_evidence',
+			'Attach New Evidence',
+			'run_evidence_probe',
+			'Collect a new deterministic artifact before allowing another model/code loop.',
+			'low',
+			'run_evidence_probe',
+			'The runner records a new artifact path or changed evidence hash, then re-evaluates the same gate.'
+		));
+	}
+	if (/diagnosis|owner|scope|product_code|business|unknown/i.test(`${recoveryClass} ${failureClass}`)) {
+		choices.push(humanDecisionChoice(
+			'revise_diagnosis',
+			'Revise Diagnosis',
+			'run_read_only_diagnosis',
+			'Run a read-only diagnosis revision to change owner files or proof plan with evidence.',
+			'low',
+			'run_read_only_diagnosis',
+			'The diagnosis gate is updated before any product-code repair is allowed.'
+		));
+	}
+	if (/infra|compile/i.test(`${recoveryClass} ${failureClass}`)) {
+		choices.push(humanDecisionChoice(
+			'repair_named_gate',
+			/compile/i.test(`${recoveryClass} ${failureClass}`) ? 'Repair Compile Gate' : 'Repair Infra Gate',
+			/compile/i.test(`${recoveryClass} ${failureClass}`) ? 'run_compile_repair' : 'run_infra_repair',
+			'Repair only the deterministic gate that failed; do not count this as product-code failure.',
+			'medium',
+			/compile/i.test(`${recoveryClass} ${failureClass}`) ? 'run_compile_repair' : 'run_infra_repair',
+			'The named infra/compile gate passes or returns a new blocker hash.',
+			true
+		));
+	}
+	if (/release/i.test(`${recoveryClass} ${failureClass}`)) {
+		choices.push(humanDecisionChoice(
+			'record_hotfix_evidence',
+			'Record Hotfix Evidence',
+			'record_hotfix_evidence',
+			'Record commit, checksum, restart, health, and self-test proof before continuing release repair.',
+			'low',
+			'record_hotfix_evidence',
+			'Hotfix evidence validates and the runner reruns the smallest release gate.'
+		));
+	}
+	choices.push(humanDecisionChoice(
+		'keep_parked',
+		'Keep Parked',
+		'park_manual',
+		'Leave the run parked until a human changes the evidence, scope, budget, or retry policy.',
+		'blocked',
+		'park_manual',
+		'No additional model, QA, repair, publish, or deploy work is queued.'
+	));
+	const dedupedChoices = choices.filter((choice, index, source) => {
+		return source.findIndex((candidate) => candidate.choiceId === choice.choiceId) === index;
+	}).slice(0, 4);
+	return {
+		requestId: stableHash('mgr-human', {
+			checkpointId,
+			evidenceHash,
+			blockerFingerprint,
+			choices: dedupedChoices.map((choice) => choice.choiceId)
+		}),
+		required: true,
+		status: 'waiting_for_operator',
+		reason: cleanText(input.reason || input.recommendedAction.reason, 1000),
+		question: 'Choose the one evidence-backed action that should unblock this runner.',
+		preferredChoiceId: dedupedChoices[0]?.choiceId || 'keep_parked',
+		evidence: baseEvidence,
+		choices: dedupedChoices,
+		blockedUntil,
+		createdAt: isoNow(input.updatedAt)
+	};
+}
+
+export function buildResolveIOAIManagerAutopilotSnapshot(
+	input: ResolveIOAIManagerAutopilotSnapshotInput
+): ResolveIOAIManagerAutopilotSnapshot {
+	const dispatchAction = resolveDispatchAction(input);
+	const directiveAllowed = input.recoveryDirective
+		? input.recoveryDirective.allowed === true
+		: input.recoveryAction?.autoRunnable === true;
+	const evidenceOnly = input.recoveryDirective?.evidenceOnly === true
+		|| input.recoveryAction?.evidenceOnly === true
+		|| input.recoveryEvidenceProbe?.evidenceOnly === true
+		|| input.recoveryCheckpoint?.status === 'parked';
+	const productRepairAllowed = (input.recoveryDirective?.canRunProductRepair ?? input.recoveryDirective?.productRepairAllowed ?? input.recoveryAction?.productRepairAllowed ?? input.recoveryCheckpoint?.productRepairAllowed) === true;
+	const expensiveModelAllowed = (input.recoveryDirective?.canRunExpensiveModel ?? input.recoveryDirective?.expensiveModelAllowed ?? input.recoveryAction?.expensiveModelAllowed ?? input.recoveryCheckpoint?.expensiveModelAllowed) === true;
+	const requiresNewEvidence = input.recoveryDirective?.requiresNewEvidence === true
+		|| input.recoveryAction?.retryPolicy?.requireNewEvidence === true
+		|| input.recoveryCheckpoint?.status === 'parked';
+	const sameEvidenceDispatchCount = countSameEvidenceDispatches(input, dispatchAction);
+	const sameEvidenceAlreadyAttempted = requiresNewEvidence && sameEvidenceDispatchCount > 0 && input.recoveryDirective?.newEvidence !== true;
+	const checkpointStatus = cleanText(input.recoveryCheckpoint?.status, 80);
+	const evidenceAssessment = input.recoveryCheckpoint && input.current
+		? assessResolveIOAIManagerEvidenceChange(input.recoveryCheckpoint, input.current, input.recoveryCheckpoint.objective)
+		: {
+			changed: false,
+			material: false,
+			strength: 'none',
+			signals: [] as string[]
+		};
+	const loopState = checkpointStatus === 'manual_handoff'
+		? 'manual_handoff'
+		: checkpointStatus === 'complete'
+			? 'complete'
+			: sameEvidenceAlreadyAttempted || input.recoveryDirective?.allowed === false
+				? 'parked'
+				: evidenceOnly && requiresNewEvidence
+					? 'collecting_evidence'
+					: 'clear';
+	const enabled = directiveAllowed && !sameEvidenceAlreadyAttempted && loopState !== 'manual_handoff';
+	const recommendedAction = sameEvidenceAlreadyAttempted || input.recoveryDirective?.allowed === false
+		? 'park_manual'
+		: dispatchAction;
+	const label = cleanText(
+		sameEvidenceAlreadyAttempted
+			? 'Attach New Evidence'
+			: input.recoveryDirective?.nextActionLabel || input.recoveryAction?.label || defaultLabelForAction(recommendedAction),
+		140
+	);
+	const reason = cleanText(
+		sameEvidenceAlreadyAttempted
+			? 'The same recovery action already ran against the same evidence; a new artifact path or changed evidence hash is required.'
+			: input.recoveryDirective?.reason || input.recoveryAction?.blockedReason || input.recoveryPlan?.objective || input.current?.blocker || 'Manager can continue the current gate.',
+		1000
+	);
+	const canResetLoopAfterEvidence = input.recoveryDirective?.canResetLoopAfterEvidence === true
+		|| input.recoveryAction?.canResetLoopAfterEvidence === true
+		|| cleanList(input.recoveryCheckpoint?.loopResetEvidence, 20, 500).length > 0;
+	const resetRequires = cleanList(
+		input.recoveryAction?.retryPolicy?.resetLoopWhen?.length
+			? input.recoveryAction.retryPolicy.resetLoopWhen
+			: input.recoveryCheckpoint?.loopResetEvidence,
+		20,
+		500
+	);
+	const recoveryRequiredArtifacts = cleanList(input.recoveryDirective?.requiredArtifacts?.length ? input.recoveryDirective.requiredArtifacts : input.recoveryAction?.requiredArtifacts, 20, 500);
+	const recoveryForbiddenActions = cleanList(input.recoveryDirective?.forbiddenActions?.length ? input.recoveryDirective.forbiddenActions : input.recoveryAction?.retryPolicy?.stopWhen, 20, 500);
+	const singleActionOnly = input.recoveryDirective?.singleActionOnly !== false && input.recoveryAction?.singleActionOnly !== false;
+	const allowedDispatchAction = cleanText(input.recoveryDirective?.allowedDispatchAction || input.recoveryAction?.allowedDispatchAction || dispatchAction, 120);
+	const costCeilingUsd = cleanNumber(input.recoveryDirective?.costCeilingUsd || input.recoveryAction?.costCeilingUsd);
+	const requiredStateTransition = cleanText(input.recoveryDirective?.requiredStateTransition || input.recoveryAction?.requiredStateTransition, 500);
+	const proofRequiredBeforeContinuation = input.recoveryDirective?.proofRequiredBeforeContinuation === true || input.recoveryAction?.proofRequiredBeforeContinuation === true;
+	const exitCriteria = cleanList(input.recoveryDirective?.exitCriteria?.length ? input.recoveryDirective.exitCriteria : input.recoveryAction?.exitCriteria, 30, 500);
+	const currentRunUsd = cleanNumber(input.currentRunUsd);
+	const totalUsd = cleanNumber(input.totalUsd);
+	const autonomyPolicy = decideResolveIOAIManagerAutonomyPolicy({
+		...(input.autonomyPolicy || {}),
+		currentSpendUsd: input.autonomyPolicy?.currentSpendUsd ?? totalUsd,
+		projectedActionCostUsd: input.autonomyPolicy?.projectedActionCostUsd ?? costCeilingUsd,
+		dispatchAction,
+		newEvidence: input.autonomyPolicy?.newEvidence ?? evidenceAssessment.changed,
+		materialEvidence: input.autonomyPolicy?.materialEvidence ?? evidenceAssessment.material,
+		evidenceStrength: input.autonomyPolicy?.evidenceStrength ?? evidenceAssessment.strength,
+		evidenceSignals: input.autonomyPolicy?.evidenceSignals ?? evidenceAssessment.signals,
+		sameEvidenceAlreadyAttempted: input.autonomyPolicy?.sameEvidenceAlreadyAttempted ?? sameEvidenceAlreadyAttempted
+	});
+	const recentDispatches = normalizeRecentDispatches(input.recoveryDispatchHistory);
+	const recommendedActionPacket: ResolveIOAIManagerAutopilotRecommendedAction = {
+		action: recommendedAction,
+		label,
+		reason,
+		safety: safetyFor({
+			action: recommendedAction,
+			enabled,
+			evidenceOnly,
+			productRepairAllowed,
+			expensiveModelAllowed
+		}),
+		enabled,
+		autoRunnable: enabled && input.recoveryAction?.autoRunnable !== false && autonomyPolicy.canAutoDispatch === true,
+		expectedResult: expectedResultForAction(recommendedAction, evidenceOnly),
+		requiresNewEvidence,
+		canRunProductRepair: enabled && productRepairAllowed,
+		canRunExpensiveModel: enabled && expensiveModelAllowed,
+		canResetLoopAfterEvidence,
+		singleActionOnly,
+		allowedDispatchAction,
+		costCeilingUsd,
+		requiredStateTransition,
+		proofRequiredBeforeContinuation,
+		autonomyMode: autonomyPolicy.mode,
+		autonomyCanAutoDispatch: autonomyPolicy.canAutoDispatch,
+		autonomyBlocked: autonomyPolicy.blocked,
+		expectedValueScore: autonomyPolicy.expectedValueScore,
+		expectedValueSource: autonomyPolicy.expectedValueSource,
+		expectedValuePositive: autonomyPolicy.expectedValuePositive,
+		evidenceBacked: autonomyPolicy.evidenceBacked,
+		evidenceStrength: autonomyPolicy.evidenceStrength,
+		dispatchAction
+	};
+	const humanDecision = buildHumanDecisionRequest({
+		snapshot: input,
+		recommendedAction: recommendedActionPacket,
+		loopState,
+		reason,
+		dispatchAction,
+		sameEvidenceAlreadyAttempted,
+		requiresNewEvidence,
+		requiredArtifacts: recoveryRequiredArtifacts,
+		forbiddenActions: recoveryForbiddenActions,
+		recentDispatches,
+		updatedAt: input.updatedAt
+	});
+	const untrackedWarning = cleanText(input.untrackedCostWarning || 'Manual Codex sessions outside this runner are not included unless recorded in the usage ledger.', 500);
+	const controlPolicy = buildControlPolicy({
+		recommendedAction: recommendedActionPacket,
+		autonomyPolicy,
+		humanDecision,
+		recoveryRequiredArtifacts,
+		recoveryForbiddenActions,
+		currentRunUsd,
+		totalUsd,
+		untrackedWarning
+	});
+	return {
+		surface: cleanText(input.surface || 'unknown', 120),
+		runId: cleanText(input.runId, 160),
+		title: cleanText(input.title, 240),
+		status: cleanText(input.status || input.recoveryCheckpoint?.status, 80),
+		phase: cleanText(input.phase || input.recoveryDirective?.phase, 80),
+		lane: cleanText(input.lane || input.recoveryDirective?.lane || input.recoveryCheckpoint?.lane || input.current?.lane, 120),
+		stepType: cleanText(input.stepType || input.recoveryDirective?.stepType || input.recoveryCheckpoint?.stepType || input.current?.stepType, 120),
+		runKind: cleanText(input.runKind, 120),
+		recommendedAction: recommendedActionPacket,
+		controlPolicy,
+		loopGuard: {
+			state: loopState,
+			blocked: loopState === 'parked' || loopState === 'manual_handoff',
+			reason,
+			failureClass: cleanText(input.current?.failureClass, 120),
+			blocker: cleanText(input.current?.blocker || input.current?.summary, 1000),
+			blockerFingerprint: cleanText(input.current?.blockerFingerprint || input.recoveryCheckpoint?.blockerFingerprint, 160),
+			evidenceHash: cleanText(input.current?.evidenceHash || input.recoveryCheckpoint?.evidenceHash, 160),
+			materialEvidence: evidenceAssessment.material === true,
+			evidenceStrength: cleanText(evidenceAssessment.strength, 40),
+			evidenceSignals: cleanList(evidenceAssessment.signals, 12, 120),
+			sameEvidenceDispatchCount,
+			sameEvidenceAlreadyAttempted,
+			loopCount: cleanNumber(input.loopCount),
+			maxLoopCount: cleanNumber(input.maxLoopCount),
+			attempts: cleanNumber(input.recoveryCheckpoint?.attempts),
+			maxAttemptsBeforePark: cleanNumber(input.recoveryCheckpoint?.maxAttemptsBeforePark),
+			canResetLoopAfterEvidence,
+			resetRequires
+		},
+		recovery: {
+			checkpointId: cleanText(input.recoveryCheckpoint?.checkpointId || input.recoveryAction?.checkpointId, 160),
+			recoveryClass: cleanText(input.recoveryCheckpoint?.recoveryClass || input.recoveryAction?.recoveryClass || input.recoveryPlan?.recoveryClass, 120),
+			dispatchAction,
+			singleActionOnly,
+			allowedDispatchAction,
+			directiveAllowed,
+			evidenceOnly,
+			productRepairAllowed,
+			expensiveModelAllowed,
+			costCeilingUsd,
+			requiredStateTransition,
+			proofRequiredBeforeContinuation,
+			requiredArtifacts: recoveryRequiredArtifacts,
+			nextCommands: cleanList(input.recoveryDirective?.nextCommands?.length ? input.recoveryDirective.nextCommands : input.recoveryAction?.nextCommands, 20, 500),
+			successCriteria: cleanList(input.recoveryDirective?.successCriteria?.length ? input.recoveryDirective.successCriteria : input.recoveryAction?.successCriteria, 20, 500),
+			exitCriteria,
+			forbiddenActions: recoveryForbiddenActions
+		},
+		autonomyPolicy,
+		recentDispatches,
+		humanDecision,
+		cost: {
+			currentRunUsd,
+			totalUsd,
+			currentRunTokens: cleanNumber(input.currentRunTokens),
+			totalTokens: cleanNumber(input.totalTokens),
+			untrackedWarning
+		},
+		updatedAt: isoNow(input.updatedAt)
+	};
+}