@resolveio/server-lib 22.3.125 → 22.3.126

package/src/util/support-runner-v5.ts

@@ -0,0 +1,897 @@
+export type ResolveIOSupportV5StepType =
+	| 'compile_check'
+	| 'startup_check'
+	| 'live_seed'
+	| 'auth_bootstrap'
+	| 'route_probe'
+	| 'qa_row'
+	| 'build_repair'
+	| 'qa_retest'
+	| 'pr_review'
+	| 'artifact_package'
+	| 'cleanup';
+
+export type ResolveIOSupportV5Outcome =
+	| 'pass'
+	| 'needs_repair'
+	| 'retry_same_step'
+	| 'park_manual'
+	| 'budget_stop'
+	| 'infra_retry'
+	| 'ready_for_merge';
+
+export type ResolveIOSupportV5Lane = 'build' | 'qa' | 'review' | 'supervisor';
+
+export type ResolveIOSupportV5MicrotaskStatus =
+	| 'pending'
+	| 'in_progress'
+	| 'pass'
+	| 'needs_repair'
+	| 'blocked'
+	| 'parked';
+
+export type ResolveIOSupportV5MicrotaskType =
+	| ResolveIOSupportV5StepType
+	| 'planning'
+	| 'scope_slice'
+	| 'product_repair'
+	| 'runner_repair';
+
+export interface ResolveIOSupportV5PromptBudget {
+	initialPlannerCap: number;
+	buildMicrotaskCap: number;
+	buildMicrotaskHardCap: number;
+	qaMicrotaskCap: number;
+	qaMicrotaskHardCap: number;
+	repairMicrotaskCap: number;
+	repairMicrotaskHardCap: number;
+}
+
+export interface ResolveIOSupportV5Microtask {
+	microtaskId: string;
+	lane: ResolveIOSupportV5Lane;
+	type: ResolveIOSupportV5MicrotaskType;
+	status: ResolveIOSupportV5MicrotaskStatus;
+	objective: string;
+	targetFiles: string[];
+	contextRefs: string[];
+	selfGate: string;
+	acceptanceProof: string;
+	threadKey: string;
+	promptTokenEstimate?: number;
+	attempts: number;
+	dependsOn: string[];
+	parentScopeId?: string;
+	blocker?: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface ResolveIOSupportV5UsageSection {
+	name: string;
+	tokenEstimate: number;
+}
+
+export interface ResolveIOSupportV5MicrotaskUsage {
+	microtaskId: string;
+	lane: ResolveIOSupportV5Lane;
+	model?: string;
+	threadKey?: string;
+	reuseThread: boolean;
+	freshReason?: string;
+	promptTokenEstimate: number;
+	promptSections: ResolveIOSupportV5UsageSection[];
+	actualInputTokens?: number;
+	actualCachedInputTokens?: number;
+	actualOutputTokens?: number;
+	durationMs?: number;
+	outcome?: ResolveIOSupportV5Outcome | ResolveIOSupportV5MicrotaskStatus;
+	recordedAt: string;
+}
+
+export interface ResolveIOSupportV5Budget {
+	maxPromptTokensPerNonInitialStep: number;
+	maxLoopsPerTicket: number;
+	maxRepeatedNoProgress: number;
+	maxRuntimeMinutesPerLoop: number;
+	totalPromptTokenEstimate: number;
+	totalRuntimeMs: number;
+	loopCount: number;
+}
+
+export interface ResolveIOSupportV5LaneMemory {
+	lane: ResolveIOSupportV5Lane;
+	model: string;
+	threadKey: string;
+	scopeSummary: string;
+	activeBlocker: string;
+	activeQaRow?: {
+		index?: number;
+		workflow?: string;
+		route?: string;
+		assertion?: string;
+		status?: string;
+	};
+	changedFiles: string[];
+	artifactPaths: string[];
+	latestPromptTokenEstimate?: number;
+	updatedAt: string;
+}
+
+export interface ResolveIOSupportV5SupervisorState {
+	version: 'v5';
+	status: 'active' | 'parked' | 'complete';
+	currentGoal: string;
+	approvedScope: string;
+	prBranch: string;
+	activeStep: ResolveIOSupportV5StepType;
+	activeBlocker: string;
+	lastGoodCheckpoint: string;
+	currentQaRow?: ResolveIOSupportV5LaneMemory['activeQaRow'];
+	processLease?: {
+		runId?: string;
+		token?: string;
+		generation?: number;
+		workspace?: string;
+		lane?: string;
+	};
+	artifactLinks: string[];
+	noEmailUnlessApproved: boolean;
+	updatedAt: string;
+}
+
+export interface ResolveIOSupportV5StepRecord {
+	microtaskId?: string;
+	stepType: ResolveIOSupportV5StepType;
+	outcome: ResolveIOSupportV5Outcome;
+	lane: ResolveIOSupportV5Lane;
+	model?: string;
+	threadKey?: string;
+	promptTokenEstimate?: number;
+	runtimeMs?: number;
+	summary: string;
+	blocker?: string;
+	changedFiles?: string[];
+	artifactPaths?: string[];
+	recordedAt: string;
+}
+
+export interface ResolveIOSupportV5RunnerIncident {
+	incidentClass: string;
+	summary: string;
+	stepType?: ResolveIOSupportV5StepType;
+	blockerFingerprint?: string;
+	artifactPaths?: string[];
+	recordedAt: string;
+}
+
+export interface ResolveIOSupportV5StateBundle {
+	supportWorkflowVersion: 'v5';
+	supportV5SupervisorState: ResolveIOSupportV5SupervisorState;
+	supportV5LaneMemory: {
+		build: ResolveIOSupportV5LaneMemory;
+		qa: ResolveIOSupportV5LaneMemory;
+	};
+	supportV5StepHistory: ResolveIOSupportV5StepRecord[];
+	supportV5Budget: ResolveIOSupportV5Budget;
+	supportV5RunnerIncidents: ResolveIOSupportV5RunnerIncident[];
+	supportV5MicrotaskLedger: ResolveIOSupportV5Microtask[];
+	supportV5ActiveMicrotaskId?: string;
+	supportV5ScopeDigest?: string;
+	supportV5MicrotaskUsageHistory: ResolveIOSupportV5MicrotaskUsage[];
+}
+
+export interface ResolveIOSupportV5InitializeInput {
+	jobId: string;
+	ticketId?: string;
+	ticketNumber?: string;
+	title?: string;
+	description?: string;
+	approvedScopeRequirements?: string[];
+	approvedScopeHours?: number | null;
+	prBranch?: string;
+	buildThreadKey?: string;
+	qaThreadKey?: string;
+	processLease?: ResolveIOSupportV5SupervisorState['processLease'];
+	now?: Date | string;
+	existing?: Partial<ResolveIOSupportV5StateBundle>;
+}
+
+export interface ResolveIOSupportV5StepInput {
+	microtaskId?: string;
+	stepType: ResolveIOSupportV5StepType;
+	outcome: ResolveIOSupportV5Outcome;
+	lane: ResolveIOSupportV5Lane;
+	model?: string;
+	threadKey?: string;
+	promptTokenEstimate?: number;
+	runtimeMs?: number;
+	summary?: string;
+	blocker?: string;
+	changedFiles?: string[];
+	artifactPaths?: string[];
+	activeQaRow?: ResolveIOSupportV5LaneMemory['activeQaRow'];
+	now?: Date | string;
+}
+
+export interface ResolveIOSupportV5ContinuationDecision {
+	action: 'continue' | 'park';
+	reason: string;
+	nextStep: ResolveIOSupportV5StepType;
+	repeatedNoProgressCount: number;
+	budgetExceeded: boolean;
+}
+
+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 cleanText(value: any, max = 2000): string {
+	return String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+function cleanList(values: any, limit = 20, 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 stableIdFromText(prefix: string, value: string): string {
+	const text = cleanText(value, 2000).toLowerCase();
+	let hash = 0;
+	for (let index = 0; index < text.length; index += 1) {
+		hash = ((hash << 5) - hash + text.charCodeAt(index)) | 0;
+	}
+	return `${prefix}-${Math.abs(hash).toString(36) || '0'}`;
+}
+
+function estimateTextTokens(value: string): number {
+	const text = String(value || '');
+	if (!text) {
+		return 0;
+	}
+	return Math.max(1, Math.ceil(text.length / 4));
+}
+
+export function fingerprintResolveIOSupportV5Blocker(value: any): string {
+	const text = 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>');
+	let hash = 0;
+	for (let index = 0; index < text.length; index += 1) {
+		hash = ((hash << 5) - hash + text.charCodeAt(index)) | 0;
+	}
+	return `v5-${Math.abs(hash).toString(36)}`;
+}
+
+export function buildResolveIOSupportV5Budget(existing?: Partial<ResolveIOSupportV5Budget>): ResolveIOSupportV5Budget {
+	return {
+		maxPromptTokensPerNonInitialStep: Number(existing?.maxPromptTokensPerNonInitialStep || 1800),
+		maxLoopsPerTicket: Number(existing?.maxLoopsPerTicket || 24),
+		maxRepeatedNoProgress: Number(existing?.maxRepeatedNoProgress || 2),
+		maxRuntimeMinutesPerLoop: Number(existing?.maxRuntimeMinutesPerLoop || 15),
+		totalPromptTokenEstimate: Number(existing?.totalPromptTokenEstimate || 0),
+		totalRuntimeMs: Number(existing?.totalRuntimeMs || 0),
+		loopCount: Number(existing?.loopCount || 0)
+	};
+}
+
+export function buildResolveIOSupportV5PromptBudget(existing?: Partial<ResolveIOSupportV5PromptBudget>): ResolveIOSupportV5PromptBudget {
+	return {
+		initialPlannerCap: Number(existing?.initialPlannerCap || 6000),
+		buildMicrotaskCap: Number(existing?.buildMicrotaskCap || 1800),
+		buildMicrotaskHardCap: Number(existing?.buildMicrotaskHardCap || 2500),
+		qaMicrotaskCap: Number(existing?.qaMicrotaskCap || 1500),
+		qaMicrotaskHardCap: Number(existing?.qaMicrotaskHardCap || 2200),
+		repairMicrotaskCap: Number(existing?.repairMicrotaskCap || 1200),
+		repairMicrotaskHardCap: Number(existing?.repairMicrotaskHardCap || 1800)
+	};
+}
+
+export function buildResolveIOSupportV5ScopeDigest(input: {
+	goal?: string;
+	approvedScope?: string | string[];
+	prBranch?: string;
+	maxTokens?: number;
+}): string {
+	const scope = Array.isArray(input.approvedScope)
+		? cleanList(input.approvedScope, 30, 220).join(' | ')
+		: cleanText(input.approvedScope, 4000);
+	const raw = [
+		input.goal ? `Goal: ${cleanText(input.goal, 300)}` : '',
+		scope ? `Approved scope: ${scope}` : '',
+		input.prBranch ? `PR branch: ${cleanText(input.prBranch, 160)}` : ''
+	].filter(Boolean).join('\n');
+	const maxChars = Math.max(400, Math.floor(Number(input.maxTokens || 1000) * 4));
+	return raw.slice(0, maxChars);
+}
+
+export function buildResolveIOSupportV5MicrotaskLedger(input: {
+	scopeDigest: string;
+	requirements?: string[];
+	buildThreadKey: string;
+	qaThreadKey: string;
+	now?: Date | string;
+	existing?: ResolveIOSupportV5Microtask[];
+}): ResolveIOSupportV5Microtask[] {
+	const existing = Array.isArray(input.existing) ? input.existing : [];
+	const completedByObjective = new Map<string, ResolveIOSupportV5Microtask>();
+	for (const task of existing) {
+		if (task && (task.status === 'pass' || task.status === 'parked')) {
+			completedByObjective.set(cleanText(task.objective, 500).toLowerCase(), task);
+		}
+	}
+	const now = isoNow(input.now);
+	const requirements = cleanList(input.requirements, 30, 240);
+	const sourceRequirements = requirements.length
+		? requirements
+		: cleanText(input.scopeDigest, 1000).split(/\s+\|\s+|\r?\n/g).map((line) => line.trim()).filter(Boolean).slice(0, 12);
+	const ledger: ResolveIOSupportV5Microtask[] = [];
+	sourceRequirements.forEach((requirement, index) => {
+		const objective = cleanText(requirement, 240);
+		if (!objective) {
+			return;
+		}
+		const existingCompleted = completedByObjective.get(objective.toLowerCase());
+		const buildId = stableIdFromText(`build-${index + 1}`, objective);
+		const qaId = stableIdFromText(`qa-${index + 1}`, objective);
+		ledger.push(existingCompleted && existingCompleted.lane === 'build' ? existingCompleted : {
+			microtaskId: buildId,
+			lane: 'build',
+			type: 'build_repair',
+			status: 'pending',
+			objective,
+			targetFiles: [],
+			contextRefs: ['scope_digest'],
+			selfGate: 'Run the smallest compile/type/unit check that proves this one behavior.',
+			acceptanceProof: 'Concrete code/data proof for this behavior, with changed files listed.',
+			threadKey: input.buildThreadKey,
+			attempts: 0,
+			dependsOn: [],
+			parentScopeId: stableIdFromText('scope', objective),
+			createdAt: now,
+			updatedAt: now
+		});
+		ledger.push({
+			microtaskId: qaId,
+			lane: 'qa',
+			type: 'qa_row',
+			status: 'pending',
+			objective: `QA proof for: ${objective}`,
+			targetFiles: [],
+			contextRefs: ['scope_digest', buildId],
+			selfGate: 'Drive this one customer-facing workflow row in browser/localhost and capture one captioned proof artifact.',
+			acceptanceProof: 'QA matrix row pass with route/data assertion, screenshot/caption artifact, and persisted before/after row/count/value proof for data-changing workflows.',
+			threadKey: input.qaThreadKey,
+			attempts: 0,
+			dependsOn: [buildId],
+			parentScopeId: stableIdFromText('scope', objective),
+			createdAt: now,
+			updatedAt: now
+		});
+	});
+	return ledger.length ? ledger : existing.slice(-80);
+}
+
+export function selectResolveIOSupportV5ActiveMicrotask(
+	ledger: ResolveIOSupportV5Microtask[] = [],
+	preferredId?: string
+): ResolveIOSupportV5Microtask | undefined {
+	const byPreferred = preferredId ? ledger.find((task) => task.microtaskId === preferredId && !['pass', 'parked'].includes(task.status)) : undefined;
+	if (byPreferred) {
+		return byPreferred;
+	}
+	return ledger.find((task) => task.status === 'needs_repair')
+		|| ledger.find((task) => task.status === 'in_progress')
+		|| ledger.find((task) => task.lane === 'build' && /repair/i.test(String(task.type || '')) && task.status === 'pending')
+		|| ledger.find((task) => task.status === 'pending')
+		|| ledger.find((task) => task.status === 'blocked');
+}
+
+export function initializeResolveIOSupportV5State(input: ResolveIOSupportV5InitializeInput): ResolveIOSupportV5StateBundle {
+	const now = isoNow(input.now);
+	const existing = input.existing || {};
+	const existingSupervisor = existing.supportV5SupervisorState;
+	const existingLaneMemory = existing.supportV5LaneMemory || {} as ResolveIOSupportV5StateBundle['supportV5LaneMemory'];
+	const scope = cleanList(input.approvedScopeRequirements, 24, 240).join(' | ')
+		|| cleanText(input.description, 1000)
+		|| cleanText(input.title, 300);
+	const ticketLabel = cleanText(input.ticketNumber || input.ticketId || input.jobId, 120);
+	const buildThreadKey = cleanText(input.buildThreadKey || existingLaneMemory.build?.threadKey || `support:${input.ticketId || input.jobId}:job:${input.jobId}:build`, 240);
+	const qaThreadKey = cleanText(input.qaThreadKey || existingLaneMemory.qa?.threadKey || `support:${input.ticketId || input.jobId}:job:${input.jobId}:qa`, 240);
+	const budget = buildResolveIOSupportV5Budget(existing.supportV5Budget);
+	const scopeDigest = cleanText((existing as any).supportV5ScopeDigest, 4000) || buildResolveIOSupportV5ScopeDigest({
+		goal: existingSupervisor?.currentGoal || `Resolve support ticket ${ticketLabel}`,
+		approvedScope: scope,
+		prBranch: input.prBranch || existingSupervisor?.prBranch || ''
+	});
+	const ledger = buildResolveIOSupportV5MicrotaskLedger({
+		scopeDigest,
+		requirements: cleanList(input.approvedScopeRequirements, 30, 240),
+		buildThreadKey,
+		qaThreadKey,
+		now,
+		existing: (existing as any).supportV5MicrotaskLedger
+	});
+	const activeMicrotask = selectResolveIOSupportV5ActiveMicrotask(ledger, (existing as any).supportV5ActiveMicrotaskId);
+	return {
+		supportWorkflowVersion: 'v5',
+		supportV5SupervisorState: {
+			version: 'v5',
+			status: existingSupervisor?.status || 'active',
+			currentGoal: existingSupervisor?.currentGoal || `Resolve support ticket ${ticketLabel}`,
+			approvedScope: existingSupervisor?.approvedScope || scope,
+			prBranch: cleanText(input.prBranch || existingSupervisor?.prBranch || '', 240),
+			activeStep: existingSupervisor?.activeStep || 'compile_check',
+			activeBlocker: existingSupervisor?.activeBlocker || '',
+			lastGoodCheckpoint: existingSupervisor?.lastGoodCheckpoint || 'v5_initialized',
+			currentQaRow: existingSupervisor?.currentQaRow,
+			processLease: input.processLease || existingSupervisor?.processLease,
+			artifactLinks: cleanList(existingSupervisor?.artifactLinks, 40, 500),
+			noEmailUnlessApproved: true,
+			updatedAt: now
+		},
+		supportV5LaneMemory: {
+			build: {
+				lane: 'build',
+				model: existingLaneMemory.build?.model || 'gpt-5.3-codex',
+				threadKey: buildThreadKey,
+				scopeSummary: existingLaneMemory.build?.scopeSummary || scope,
+				activeBlocker: existingLaneMemory.build?.activeBlocker || '',
+				activeQaRow: existingLaneMemory.build?.activeQaRow,
+				changedFiles: cleanList(existingLaneMemory.build?.changedFiles, 80, 500),
+				artifactPaths: cleanList(existingLaneMemory.build?.artifactPaths, 80, 500),
+				latestPromptTokenEstimate: Number(existingLaneMemory.build?.latestPromptTokenEstimate || 0) || undefined,
+				updatedAt: existingLaneMemory.build?.updatedAt || now
+			},
+			qa: {
+				lane: 'qa',
+				model: existingLaneMemory.qa?.model || 'gpt-5.4-mini',
+				threadKey: qaThreadKey,
+				scopeSummary: existingLaneMemory.qa?.scopeSummary || scope,
+				activeBlocker: existingLaneMemory.qa?.activeBlocker || '',
+				activeQaRow: existingLaneMemory.qa?.activeQaRow,
+				changedFiles: cleanList(existingLaneMemory.qa?.changedFiles, 80, 500),
+				artifactPaths: cleanList(existingLaneMemory.qa?.artifactPaths, 80, 500),
+				latestPromptTokenEstimate: Number(existingLaneMemory.qa?.latestPromptTokenEstimate || 0) || undefined,
+				updatedAt: existingLaneMemory.qa?.updatedAt || now
+			}
+		},
+		supportV5StepHistory: Array.isArray(existing.supportV5StepHistory)
+			? existing.supportV5StepHistory.slice(-80)
+			: [],
+		supportV5Budget: budget,
+		supportV5RunnerIncidents: Array.isArray(existing.supportV5RunnerIncidents)
+			? existing.supportV5RunnerIncidents.slice(-80)
+			: [],
+		supportV5MicrotaskLedger: ledger,
+		supportV5ActiveMicrotaskId: activeMicrotask?.microtaskId,
+		supportV5ScopeDigest: scopeDigest,
+		supportV5MicrotaskUsageHistory: Array.isArray((existing as any).supportV5MicrotaskUsageHistory)
+			? (existing as any).supportV5MicrotaskUsageHistory.slice(-200)
+			: []
+	};
+}
+
+export function recordResolveIOSupportV5Step(
+	bundle: ResolveIOSupportV5StateBundle,
+	step: ResolveIOSupportV5StepInput
+): ResolveIOSupportV5StateBundle {
+	const now = isoNow(step.now);
+	const promptTokens = Math.max(0, Number(step.promptTokenEstimate || 0) || 0);
+	const runtimeMs = Math.max(0, Number(step.runtimeMs || 0) || 0);
+	const microtaskId = cleanText(step.microtaskId || bundle.supportV5ActiveMicrotaskId, 160);
+	const record: ResolveIOSupportV5StepRecord = {
+		...(microtaskId ? { microtaskId } : {}),
+		stepType: step.stepType,
+		outcome: step.outcome,
+		lane: step.lane,
+		model: cleanText(step.model, 80),
+		threadKey: cleanText(step.threadKey, 240),
+		promptTokenEstimate: promptTokens || undefined,
+		runtimeMs: runtimeMs || undefined,
+		summary: cleanText(step.summary || step.blocker || step.outcome, 1200),
+		blocker: cleanText(step.blocker, 1200),
+		changedFiles: cleanList(step.changedFiles, 80, 500),
+		artifactPaths: cleanList(step.artifactPaths, 80, 500),
+		recordedAt: now
+	};
+	const laneMemory = { ...bundle.supportV5LaneMemory };
+	if (step.lane === 'build' || step.lane === 'qa') {
+		const previous = laneMemory[step.lane];
+		laneMemory[step.lane] = {
+			...previous,
+			activeBlocker: record.blocker || previous.activeBlocker || '',
+			activeQaRow: step.activeQaRow || previous.activeQaRow,
+			changedFiles: record.changedFiles?.length ? record.changedFiles : previous.changedFiles,
+			artifactPaths: record.artifactPaths?.length ? record.artifactPaths : previous.artifactPaths,
+			latestPromptTokenEstimate: promptTokens || previous.latestPromptTokenEstimate,
+			updatedAt: now
+		};
+	}
+	const supervisor = {
+		...bundle.supportV5SupervisorState,
+		status: step.outcome === 'ready_for_merge' ? 'complete' as const : (step.outcome === 'park_manual' || step.outcome === 'budget_stop' ? 'parked' as const : 'active' as const),
+		activeStep: step.stepType,
+		activeBlocker: record.blocker || '',
+		currentQaRow: step.activeQaRow || bundle.supportV5SupervisorState.currentQaRow,
+		lastGoodCheckpoint: step.outcome === 'pass' || step.outcome === 'ready_for_merge'
+			? step.stepType
+			: bundle.supportV5SupervisorState.lastGoodCheckpoint,
+		artifactLinks: Array.from(new Set([
+			...bundle.supportV5SupervisorState.artifactLinks,
+			...(record.artifactPaths || [])
+		])).slice(-80),
+		updatedAt: now
+	};
+	const ledger = (bundle.supportV5MicrotaskLedger || []).map((task) => {
+		if (task.microtaskId !== bundle.supportV5ActiveMicrotaskId) {
+			return task;
+		}
+		const status: ResolveIOSupportV5MicrotaskStatus = step.outcome === 'pass' || step.outcome === 'ready_for_merge'
+			? 'pass'
+			: step.outcome === 'park_manual' || step.outcome === 'budget_stop'
+				? 'parked'
+				: step.outcome === 'needs_repair' || step.outcome === 'retry_same_step'
+					? 'needs_repair'
+					: 'in_progress';
+		return {
+			...task,
+			status,
+			blocker: record.blocker || task.blocker,
+			promptTokenEstimate: promptTokens || task.promptTokenEstimate,
+			attempts: task.attempts + (step.outcome === 'pass' || step.outcome === 'ready_for_merge' ? 0 : 1),
+			updatedAt: now
+		};
+	});
+	const nextMicrotask = selectResolveIOSupportV5ActiveMicrotask(ledger, bundle.supportV5ActiveMicrotaskId);
+	return {
+		...bundle,
+		supportV5SupervisorState: supervisor,
+		supportV5LaneMemory: laneMemory,
+		supportV5StepHistory: [...bundle.supportV5StepHistory, record].slice(-100),
+		supportV5Budget: {
+			...bundle.supportV5Budget,
+			totalPromptTokenEstimate: bundle.supportV5Budget.totalPromptTokenEstimate + promptTokens,
+			totalRuntimeMs: bundle.supportV5Budget.totalRuntimeMs + runtimeMs,
+			loopCount: bundle.supportV5Budget.loopCount + 1
+		},
+		supportV5MicrotaskLedger: ledger,
+		supportV5ActiveMicrotaskId: nextMicrotask?.microtaskId,
+		supportV5MicrotaskUsageHistory: bundle.supportV5MicrotaskUsageHistory || []
+	};
+}
+
+export function recordResolveIOSupportV5MicrotaskUsage(
+	bundle: ResolveIOSupportV5StateBundle,
+	usage: Omit<ResolveIOSupportV5MicrotaskUsage, 'recordedAt'>
+): ResolveIOSupportV5StateBundle {
+	const record: ResolveIOSupportV5MicrotaskUsage = {
+		...usage,
+		microtaskId: cleanText(usage.microtaskId, 160),
+		threadKey: cleanText(usage.threadKey, 240),
+		model: cleanText(usage.model, 80),
+		promptTokenEstimate: Math.max(0, Number(usage.promptTokenEstimate || 0) || 0),
+		promptSections: Array.isArray(usage.promptSections)
+			? usage.promptSections.map((section) => ({
+				name: cleanText(section.name, 120),
+				tokenEstimate: Math.max(0, Number(section.tokenEstimate || 0) || 0)
+			})).filter((section) => section.name)
+			: [],
+		recordedAt: isoNow()
+	};
+	const ledger = (bundle.supportV5MicrotaskLedger || []).map((task) => task.microtaskId === record.microtaskId
+		? {
+			...task,
+			promptTokenEstimate: record.promptTokenEstimate,
+			updatedAt: record.recordedAt
+		}
+		: task);
+	return {
+		...bundle,
+		supportV5MicrotaskLedger: ledger,
+		supportV5MicrotaskUsageHistory: [
+			...(bundle.supportV5MicrotaskUsageHistory || []),
+			record
+		].slice(-200)
+	};
+}
+
+export function decideResolveIOSupportV5Continuation(bundle: ResolveIOSupportV5StateBundle): ResolveIOSupportV5ContinuationDecision {
+	const history = bundle.supportV5StepHistory || [];
+	const budget = buildResolveIOSupportV5Budget(bundle.supportV5Budget);
+	const last = history[history.length - 1];
+	const activeMicrotaskId = cleanText(bundle.supportV5ActiveMicrotaskId, 160);
+	const blockerFingerprint = fingerprintResolveIOSupportV5Blocker(last?.blocker || last?.summary || '');
+	let repeatedNoProgressCount = 0;
+	for (let index = history.length - 1; index >= 0; index -= 1) {
+		const item = history[index];
+		if (activeMicrotaskId && cleanText((item as any).microtaskId, 160) !== activeMicrotaskId) {
+			continue;
+		}
+		if (item.outcome === 'pass' || item.outcome === 'ready_for_merge') {
+			break;
+		}
+		if (item.stepType !== last?.stepType) {
+			break;
+		}
+		if (fingerprintResolveIOSupportV5Blocker(item.blocker || item.summary || '') === blockerFingerprint) {
+			repeatedNoProgressCount += 1;
+		}
+	}
+	const budgetExceeded = budget.loopCount >= budget.maxLoopsPerTicket
+		|| (last?.promptTokenEstimate || 0) > budget.maxPromptTokensPerNonInitialStep;
+	if (budgetExceeded) {
+		return {
+			action: 'park',
+			reason: 'support_v5_budget_guard',
+			nextStep: last?.stepType || 'cleanup',
+			repeatedNoProgressCount,
+			budgetExceeded
+		};
+	}
+	if (repeatedNoProgressCount > budget.maxRepeatedNoProgress) {
+		return {
+			action: 'park',
+			reason: 'support_v5_repeated_no_progress',
+			nextStep: last?.stepType || 'cleanup',
+			repeatedNoProgressCount,
+			budgetExceeded
+		};
+	}
+	return {
+		action: 'continue',
+		reason: 'support_v5_continue',
+		nextStep: last?.stepType || bundle.supportV5SupervisorState.activeStep,
+		repeatedNoProgressCount,
+		budgetExceeded: false
+	};
+}
+
+export function buildResolveIOSupportV5DiagnoseFirstPrompt(lines: {
+	goal?: string;
+	approvedScope?: string[];
+	activeStep?: ResolveIOSupportV5StepType;
+	activeBlocker?: string;
+	lane?: ResolveIOSupportV5Lane;
+	laneSummary?: string;
+	currentQaRow?: ResolveIOSupportV5LaneMemory['activeQaRow'];
+	artifactPaths?: string[];
+	changedFiles?: string[];
+}): string[] {
+	return [
+		'Support Runner V5 contract: act like a guarded autonomous engineer, not a gate checklist.',
+		'Start with Diagnose First: observed evidence, likely cause, smallest next action, and expected proof.',
+		'Use compact lane memory and current artifacts before asking for broad ticket context.',
+		'Do not send customer email. Do not write production data. Do not spawn duplicate build, QA, server, client, Mongo, browser, or Codex processes.',
+		'If repairing, inspect logs/artifacts/source/diff first; make the smallest code or localhost-data change, then run the smallest finite self-gate.',
+		'For build repairs, prefer `npm run build-prod -- --watch=false`, a targeted `tsc --noEmit`, or a focused unit test. `npm run build-dev` is forbidden for support microtasks because it is slow/watch-oriented and can leave heavy esbuild work. If no finite gate exists, return a blocked self-gate with the exact reason instead of running build-dev.',
+		'If QA fails, retest the failed row before advancing; if the same blocker repeats without new proof, park with the exact blocker.',
+		lines.goal ? `Goal: ${cleanText(lines.goal, 500)}` : '',
+		cleanList(lines.approvedScope, 12, 240).length ? `Approved scope: ${cleanList(lines.approvedScope, 12, 240).join(' | ')}` : '',
+		lines.activeStep ? `Active step: ${lines.activeStep}` : '',
+		lines.lane ? `Lane: ${lines.lane}` : '',
+		lines.laneSummary ? `Lane memory: ${cleanText(lines.laneSummary, 700)}` : '',
+		lines.activeBlocker ? `Active blocker: ${cleanText(lines.activeBlocker, 800)}` : '',
+		lines.currentQaRow?.workflow ? `Current QA row: ${cleanText(lines.currentQaRow.workflow, 300)}` : '',
+		lines.currentQaRow?.route ? `Current QA route: ${cleanText(lines.currentQaRow.route, 300)}` : '',
+		cleanList(lines.changedFiles, 12, 200).length ? `Changed files: ${cleanList(lines.changedFiles, 12, 200).join(', ')}` : '',
+		cleanList(lines.artifactPaths, 12, 240).length ? `Artifacts: ${cleanList(lines.artifactPaths, 12, 240).join(', ')}` : ''
+	].filter(Boolean);
+}
+
+export function buildResolveIOSupportV5MicrotaskPrompt(input: {
+	bundle: ResolveIOSupportV5StateBundle;
+	lane: 'build' | 'qa';
+	model?: string;
+	stage?: string;
+	failureText?: string;
+	changedFiles?: string[];
+	artifactPaths?: string[];
+	targetFiles?: string[];
+	contextSnippets?: string[];
+	activeQaRow?: ResolveIOSupportV5LaneMemory['activeQaRow'];
+}): {
+	prompt: string;
+	promptTokenEstimate: number;
+	promptSections: ResolveIOSupportV5UsageSection[];
+	activeMicrotask?: ResolveIOSupportV5Microtask;
+	withinCap: boolean;
+	withinHardCap: boolean;
+	cap: number;
+	hardCap: number;
+	reason?: string;
+} {
+	const activeMicrotask = selectResolveIOSupportV5ActiveMicrotask(
+		input.bundle.supportV5MicrotaskLedger || [],
+		input.bundle.supportV5ActiveMicrotaskId
+	);
+	const budget = buildResolveIOSupportV5PromptBudget();
+	const repairLike = Boolean(input.failureText || activeMicrotask?.status === 'needs_repair' || /repair/i.test(String(input.stage || activeMicrotask?.type || '')));
+	const cap = repairLike
+		? budget.repairMicrotaskCap
+		: input.lane === 'qa'
+			? budget.qaMicrotaskCap
+			: budget.buildMicrotaskCap;
+	const hardCap = repairLike
+		? budget.repairMicrotaskHardCap
+		: input.lane === 'qa'
+			? budget.qaMicrotaskHardCap
+			: budget.buildMicrotaskHardCap;
+	const laneMemory = input.bundle.supportV5LaneMemory[input.lane];
+	const taskThreadKey = activeMicrotask?.threadKey || laneMemory.threadKey;
+	const changedFiles = cleanList(input.changedFiles?.length ? input.changedFiles : laneMemory.changedFiles, 8, 160);
+	const artifactPaths = cleanList(input.artifactPaths?.length ? input.artifactPaths : laneMemory.artifactPaths, 8, 200);
+	const targetFiles = cleanList(input.targetFiles?.length ? input.targetFiles : activeMicrotask?.targetFiles, 5, 160);
+	const contextSnippets = cleanList(input.contextSnippets, 5, 360);
+	const qaRow = input.activeQaRow || activeMicrotask?.lane === 'qa' ? input.activeQaRow || laneMemory.activeQaRow || input.bundle.supportV5SupervisorState.currentQaRow : undefined;
+	const sections = [
+		{
+			name: 'microtask_contract',
+			text: [
+				'Support Runner V5 Microtask Contract.',
+				'Use the existing persistent lane thread. Do not start a fresh thread.',
+				'Do exactly one microtask and one proof gate. Do not replay ticket triage, prior plans, attachments, broad QA checklist, or unrelated scope.',
+				'If context is insufficient, request the smallest missing file/log/artifact by path and park this microtask; do not broaden the prompt.',
+				'Do not send customer email. Do not deploy. Do not spawn duplicate server/client/Mongo/browser/Codex processes.',
+				input.lane === 'qa'
+					? 'QA lane hard boundary: the platform preflight owns compile, dependency install, Mongo/server/client startup, and Angular startup. This lane owns only browser/data proof and QA artifacts unless the prompt explicitly says preflight was skipped.'
+					: 'Build lane hard boundary: do not run `npm run build-dev`, `ng build`, `npm run server`, `npm run client`, `ng serve`, `run-local-qa.sh`, browser automation, or any watch/long-lived command. If a broad compile gate is needed, run only `npm run build-prod -- --watch=false`; otherwise use a targeted finite check or return the precise blocker.'
+			].join('\n')
+		},
+		{
+			name: 'scope_digest',
+			text: cleanText(input.bundle.supportV5ScopeDigest || input.bundle.supportV5SupervisorState.approvedScope, 900)
+		},
+		{
+			name: 'active_microtask',
+			text: activeMicrotask ? [
+				`Microtask id: ${activeMicrotask.microtaskId}`,
+				`Lane: ${input.lane}`,
+				`Type: ${activeMicrotask.type}`,
+				`Status: ${activeMicrotask.status}`,
+				`Objective: ${cleanText(activeMicrotask.objective, 360)}`,
+				`Self-gate: ${cleanText(activeMicrotask.selfGate, 260)}`,
+				`Acceptance proof: ${cleanText(activeMicrotask.acceptanceProof, 260)}`,
+				`Attempts on this microtask: ${activeMicrotask.attempts}`,
+				`Thread key: ${taskThreadKey}`
+			].join('\n') : 'No active microtask found. Park and report support_v5_microtask_missing.'
+		},
+		{
+			name: 'failure_delta',
+			text: input.failureText ? `Latest blocker/failure delta: ${cleanText(input.failureText, 700)}` : ''
+		},
+		{
+			name: 'target_context',
+			text: [
+				targetFiles.length ? `Target files: ${targetFiles.join(', ')}` : '',
+				changedFiles.length ? `Changed files: ${changedFiles.join(', ')}` : '',
+				artifactPaths.length ? `Artifacts: ${artifactPaths.join(', ')}` : '',
+				qaRow?.workflow ? `QA row workflow: ${cleanText(qaRow.workflow, 220)}` : '',
+				qaRow?.route ? `QA row route: ${cleanText(qaRow.route, 220)}` : '',
+				qaRow?.assertion ? `QA row assertion: ${cleanText(qaRow.assertion, 260)}` : '',
+				contextSnippets.length ? `Relevant snippets:\n${contextSnippets.join('\n---\n')}` : ''
+			].filter(Boolean).join('\n')
+		},
+		input.lane === 'qa' ? {
+			name: 'qa_browser_evidence_contract',
+			text: [
+				'QA lane first action after preflight: collect fresh browser evidence for the active row, not a proof review of existing route/auth artifacts.',
+				'Use the already-running localhost harness and staged env. Before any shell command, run `source .resolveio-support-tools/env.sh 2>/dev/null || source ../.resolveio-support-tools/env.sh 2>/dev/null || true`; then use `$RESOLVEIO_SUPPORT_QA_CLIENT_URL`, `$RESOLVEIO_SUPPORT_QA_SERVER_URL`, `$PUPPETEER_EXECUTABLE_PATH`, and `$CHROME_BIN`.',
+				'Required auth replay helper inside every Puppeteer row script: `const storage=JSON.parse(fs.readFileSync("qa-artifacts/auth-bootstrap-storage-state.json","utf8")); const entries=[...(Array.isArray(storage.localStorageEntries)?storage.localStorageEntries:[]), ...(Array.isArray(storage.localStorage)?storage.localStorage:Object.entries(storage.localStorage||{}).map(([key,value])=>({key,value}))), ...((storage.origins||[]).flatMap(o=>o.localStorage||[]))].map(e=>({key:e.key||e.name,value:e.value})).filter(e=>e.key); const clientUrl=process.env.RESOLVEIO_SUPPORT_QA_CLIENT_URL||process.env.RESOLVEIO_RUNNER_QA_CLIENT_URL; const rowRoute="<ACTIVE_QA_ROUTE>"; await page.goto(clientUrl,{waitUntil:"domcontentloaded"}); await page.evaluate(items=>{localStorage.clear(); for(const item of items)localStorage.setItem(item.key,item.value);}, entries); await page.goto(new URL(rowRoute, clientUrl).href,{waitUntil:"domcontentloaded"});` Replace `<ACTIVE_QA_ROUTE>` with the active row route before running. A screenshot of `/home`, the login screen, or a shell route after this helper means the QA script navigated to the wrong route or storage is stale; rerun the same row with the active route before returning an app blocker.',
+				'Allowed first command shape: one bounded `node`/Puppeteer row script that reads `qa-artifacts/auth-bootstrap-storage-state.json`, opens `$RESOLVEIO_SUPPORT_QA_CLIENT_URL`, seeds localStorage, navigates to the active QA route with `new URL(activeRoute, clientUrl).href`, drives the visible workflow, captures screenshot/caption, and updates the active matrix row. A `/home` proof is invalid for a locked non-home route.',
+				'Forbidden in QA lane after preflight: `npm run build`, `npm run build-dev`, `npm run build-prod`, `ng build`, `npm install`, `npm ci`, `npm run server`, `npm run client`, `ng serve`, `gulp`, `mongod`, `run-local-qa.sh`, and broad source discovery. If a build/startup/dependency problem is suspected, return `blocked` or `needs-fix` with the existing qa-artifacts log paths instead of launching those commands.',
+					'Launch Puppeteer from `PUPPETEER_EXECUTABLE_PATH || CHROME_BIN`, seed localStorage from `qa-artifacts/auth-bootstrap-storage-state.json`, then navigate to the active QA route.',
+					'Before passing, confirm `qa-artifacts/auth-bootstrap-result.json` used the ticket reporter or named affected user when available. If it used generic admin/dev while `qa-live-data-seed-result.json.selected.qa_user_context` names a reporter/affected user, rerun auth as that user or return needs-fix.',
+					'Drive the visible customer workflow for this one row. Capture a new customer-facing screenshot/caption and update `qa-artifacts/qa-coverage-matrix.json` with workflow, route, data id/name, assertion, screenshot path, caption, and pass/failed/blocked status.',
+				'After selecting any From/To, source/target, dropdown, combobox, rio-select, filter, item, customer, yard, chemical, or treatment-plan value, read the visible control text back from the DOM. If it still contains placeholder text such as Select Chemical, Select Yard, Select Customer, Select Treatment Plan Type, Loading..., empty, null, or undefined, do not click the action button and do not mark pass. Capture the selected-state blocker screenshot/DOM text and return needs-fix.',
+				'If the row needs persisted data proof, create that proof yourself in the same bounded QA command by querying localhost QA Mongo through process.env.MONGO_URL after the visible UI action. Write the result under qa-artifacts/ as JSON and reference that path in the matrix. Do not ask for a missing post-action DB artifact while the local QA stack is running; either write it or return needs-fix with the exact query/script error. For update-interchangeables rows, the JSON must include concrete non-placeholder fromText and toText, before/after counts or sample documents for treatment plans and tank/interchangeable records, and must fail if either selected value is only an arrow/placeholder or if the persisted collections are empty.',
+					'If the row names multiple concrete entities such as assets, units, BOLs, invoices, chemicals, customers, yards, or numbered records, prove every named entity. Do not pass by proving only one representative record.',
+					'For customer-reported data bugs, use production-seeded localhost records from `qa-live-data-seed-result.json`. If the exact named record is missing from the seed, fail the row as a seed/query blocker instead of testing a substitute record.',
+					'Route-ready, auth-bootstrap, shell, header-only, and empty-list screenshots do not satisfy this microtask. If the row cannot be proven, capture the blocker screenshot/DOM state and return needs-fix with that exact blocker.',
+				'Do not run compile/startup/npm install, do not spawn another server/client/Mongo, and do not inspect broad source trees before the first browser evidence command.'
+			].join('\n')
+		} : {
+			name: 'non_qa_noop',
+			text: ''
+		},
+		{
+			name: 'return_contract',
+			text: input.lane === 'qa'
+				? 'Return strict JSON only: {"status":"pass"|"needs-fix"|"blocked","microtaskId":"","summary":"","evidence":[""],"artifacts":[""],"next_actions":[""]}.'
+				: 'Return concise Markdown with: Microtask Result, Root Cause, Changes, Self-Gate, Acceptance Proof, Residual Risk.'
+		}
+	].filter((section) => cleanText(section.text, 20));
+	const promptSections = sections.map((section) => ({
+		name: section.name,
+		tokenEstimate: estimateTextTokens(section.text)
+	}));
+	const prompt = sections.map((section) => section.text).join('\n\n');
+	const promptTokenEstimate = estimateTextTokens(prompt);
+	return {
+		prompt,
+		promptTokenEstimate,
+		promptSections,
+		activeMicrotask,
+		withinCap: promptTokenEstimate <= cap,
+		withinHardCap: promptTokenEstimate <= hardCap,
+		cap,
+		hardCap,
+		reason: promptTokenEstimate > hardCap
+			? 'support_v5_microtask_prompt_hard_cap'
+			: promptTokenEstimate > cap
+				? 'support_v5_microtask_prompt_soft_cap'
+				: undefined
+	};
+}
+
+export function summarizeResolveIOSupportV5MicrotaskUsage(bundle: ResolveIOSupportV5StateBundle): {
+	totalPromptTokenEstimate: number;
+	byMicrotask: Array<{ microtaskId: string; promptTokenEstimate: number; calls: number }>;
+	bySection: ResolveIOSupportV5UsageSection[];
+	broadPromptViolations: ResolveIOSupportV5MicrotaskUsage[];
+} {
+	const byMicrotask = new Map<string, { microtaskId: string; promptTokenEstimate: number; calls: number }>();
+	const bySection = new Map<string, number>();
+	let totalPromptTokenEstimate = 0;
+	const broadPromptViolations: ResolveIOSupportV5MicrotaskUsage[] = [];
+	const promptBudget = buildResolveIOSupportV5PromptBudget();
+	for (const usage of bundle.supportV5MicrotaskUsageHistory || []) {
+		totalPromptTokenEstimate += usage.promptTokenEstimate || 0;
+		const existing = byMicrotask.get(usage.microtaskId) || { microtaskId: usage.microtaskId, promptTokenEstimate: 0, calls: 0 };
+		existing.promptTokenEstimate += usage.promptTokenEstimate || 0;
+		existing.calls += 1;
+		byMicrotask.set(usage.microtaskId, existing);
+		for (const section of usage.promptSections || []) {
+			bySection.set(section.name, (bySection.get(section.name) || 0) + section.tokenEstimate);
+		}
+		const hardCap = usage.lane === 'qa' ? promptBudget.qaMicrotaskHardCap : promptBudget.buildMicrotaskHardCap;
+		if ((usage.promptTokenEstimate || 0) > hardCap) {
+			broadPromptViolations.push(usage);
+		}
+	}
+	return {
+		totalPromptTokenEstimate,
+		byMicrotask: Array.from(byMicrotask.values()),
+		bySection: Array.from(bySection.entries()).map(([name, tokenEstimate]) => ({ name, tokenEstimate })),
+		broadPromptViolations
+	};
+}
+
+export function buildResolveIOSupportV5Incident(input: {
+	incidentClass: string;
+	summary: string;
+	stepType?: ResolveIOSupportV5StepType;
+	blocker?: string;
+	artifactPaths?: string[];
+	now?: Date | string;
+}): ResolveIOSupportV5RunnerIncident {
+	return {
+		incidentClass: cleanText(input.incidentClass, 120) || 'support_v5_runner_incident',
+		summary: cleanText(input.summary, 1200),
+		stepType: input.stepType,
+		blockerFingerprint: input.blocker ? fingerprintResolveIOSupportV5Blocker(input.blocker) : undefined,
+		artifactPaths: cleanList(input.artifactPaths, 40, 500),
+		recordedAt: isoNow(input.now)
+	};
+}