pi-subagents 0.25.0 → 0.27.0

package/src/runs/shared/acceptance-contract.ts

@@ -0,0 +1,291 @@
+import type {
+	AcceptanceConfig,
+	AcceptanceEvidenceKind,
+	AcceptanceInput,
+	AcceptanceProvenanceLevel,
+	ResolvedAcceptanceConfig,
+	ResolvedAcceptanceGate,
+	SubagentRunMode,
+} from "../../shared/types.ts";
+
+const DEFAULT_FINALIZATION_MAX_TURNS = 3;
+const MAX_FINALIZATION_TURNS = 10;
+
+const VALID_EVIDENCE = new Set<AcceptanceEvidenceKind>([
+	"changed-files",
+	"tests-added",
+	"commands-run",
+	"validation-output",
+	"residual-risks",
+	"no-staged-files",
+	"diff-summary",
+	"review-findings",
+	"manual-notes",
+]);
+
+const ACCEPTANCE_KEYS = new Set([
+	"criteria",
+	"evidence",
+	"verify",
+	"review",
+	"stopRules",
+	"maxFinalizationTurns",
+]);
+
+const REMOVED_ACCEPTANCE_KEYS = new Set(["level", "finalization", "reason"]);
+
+function hasArrayItems(value: unknown): boolean {
+	return Array.isArray(value) && value.length > 0;
+}
+
+export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"): string[] {
+	const errors: string[] = [];
+	if (input === undefined) return errors;
+	if (input === false || typeof input === "string") {
+		errors.push(`${pathLabel} must be an object. Public acceptance levels and false disables are no longer supported.`);
+		return errors;
+	}
+	if (!input || typeof input !== "object" || Array.isArray(input)) {
+		errors.push(`${pathLabel} must be an object.`);
+		return errors;
+	}
+
+	const value = input as Record<string, unknown>;
+	if (Object.hasOwn(value, "level")) {
+		errors.push(`${pathLabel}.level is no longer supported; configure criteria, evidence, verify, and review directly.`);
+	}
+	if (Object.hasOwn(value, "finalization")) {
+		errors.push(`${pathLabel}.finalization is not supported; acceptance contracts always run the self-review loop.`);
+	}
+	if (Object.hasOwn(value, "reason")) {
+		errors.push(`${pathLabel}.reason is not supported because acceptance is disabled by omitting the field.`);
+	}
+	for (const key of Object.keys(value)) {
+		if (!ACCEPTANCE_KEYS.has(key) && !REMOVED_ACCEPTANCE_KEYS.has(key)) errors.push(`${pathLabel}.${key} is not supported.`);
+	}
+
+	if (value.criteria !== undefined) {
+		if (!Array.isArray(value.criteria)) {
+			errors.push(`${pathLabel}.criteria must be an array.`);
+		} else {
+			for (const [index, criterion] of value.criteria.entries()) {
+				if (typeof criterion === "string") {
+					if (!criterion.trim()) errors.push(`${pathLabel}.criteria[${index}] must not be empty.`);
+					continue;
+				}
+				if (!criterion || typeof criterion !== "object" || Array.isArray(criterion)) {
+					errors.push(`${pathLabel}.criteria[${index}] must be a string or object.`);
+					continue;
+				}
+				const item = criterion as Record<string, unknown>;
+				if (typeof item.id !== "string" || !item.id.trim()) errors.push(`${pathLabel}.criteria[${index}].id is required.`);
+				if (typeof item.must !== "string" || !item.must.trim()) errors.push(`${pathLabel}.criteria[${index}].must is required.`);
+				if (item.evidence !== undefined && !Array.isArray(item.evidence)) errors.push(`${pathLabel}.criteria[${index}].evidence must be an array.`);
+				if (Array.isArray(item.evidence)) {
+					for (const [evidenceIndex, evidence] of item.evidence.entries()) {
+						if (typeof evidence !== "string" || !VALID_EVIDENCE.has(evidence as AcceptanceEvidenceKind)) {
+							errors.push(`${pathLabel}.criteria[${index}].evidence[${evidenceIndex}] is not a supported evidence kind.`);
+						}
+					}
+				}
+				if (item.severity !== undefined && item.severity !== "required" && item.severity !== "recommended") {
+					errors.push(`${pathLabel}.criteria[${index}].severity must be required or recommended.`);
+				}
+			}
+		}
+	}
+
+	if (Array.isArray(value.evidence)) {
+		for (const [index, item] of value.evidence.entries()) {
+			if (typeof item !== "string" || !VALID_EVIDENCE.has(item as AcceptanceEvidenceKind)) {
+				errors.push(`${pathLabel}.evidence[${index}] is not a supported evidence kind.`);
+			}
+		}
+	} else if (value.evidence !== undefined) {
+		errors.push(`${pathLabel}.evidence must be an array.`);
+	}
+
+	if (value.verify !== undefined && !Array.isArray(value.verify)) errors.push(`${pathLabel}.verify must be an array.`);
+	if (Array.isArray(value.verify)) {
+		for (const [index, command] of value.verify.entries()) {
+			if (!command || typeof command !== "object" || Array.isArray(command)) {
+				errors.push(`${pathLabel}.verify[${index}] must be an object.`);
+				continue;
+			}
+			const cmd = command as Record<string, unknown>;
+			if (typeof cmd.id !== "string" || !cmd.id.trim()) errors.push(`${pathLabel}.verify[${index}].id is required.`);
+			if (typeof cmd.command !== "string" || !cmd.command.trim()) errors.push(`${pathLabel}.verify[${index}].command is required.`);
+			if (cmd.timeoutMs !== undefined && (!Number.isInteger(cmd.timeoutMs) || Number(cmd.timeoutMs) <= 0)) {
+				errors.push(`${pathLabel}.verify[${index}].timeoutMs must be a positive integer.`);
+			}
+			if (cmd.cwd !== undefined && typeof cmd.cwd !== "string") errors.push(`${pathLabel}.verify[${index}].cwd must be a string.`);
+			if (cmd.env !== undefined) {
+				if (!cmd.env || typeof cmd.env !== "object" || Array.isArray(cmd.env)) {
+					errors.push(`${pathLabel}.verify[${index}].env must be an object with string values.`);
+				} else {
+					for (const [key, envValue] of Object.entries(cmd.env as Record<string, unknown>)) {
+						if (typeof envValue !== "string") errors.push(`${pathLabel}.verify[${index}].env.${key} must be a string.`);
+					}
+				}
+			}
+			if (cmd.allowFailure !== undefined && typeof cmd.allowFailure !== "boolean") errors.push(`${pathLabel}.verify[${index}].allowFailure must be a boolean.`);
+		}
+	}
+
+	if (value.review !== undefined) {
+		if (!value.review || typeof value.review !== "object" || Array.isArray(value.review)) {
+			errors.push(`${pathLabel}.review must be an object.`);
+		} else {
+			const review = value.review as Record<string, unknown>;
+			if (review.agent !== undefined && typeof review.agent !== "string") errors.push(`${pathLabel}.review.agent must be a string.`);
+			if (review.focus !== undefined && typeof review.focus !== "string") errors.push(`${pathLabel}.review.focus must be a string.`);
+			if (review.required !== undefined && typeof review.required !== "boolean") errors.push(`${pathLabel}.review.required must be a boolean.`);
+		}
+	}
+
+	if (value.stopRules !== undefined) {
+		if (!Array.isArray(value.stopRules)) {
+			errors.push(`${pathLabel}.stopRules must be an array.`);
+		} else {
+			for (const [index, rule] of value.stopRules.entries()) {
+				if (typeof rule !== "string" || !rule.trim()) errors.push(`${pathLabel}.stopRules[${index}] must be a non-empty string.`);
+			}
+		}
+	}
+
+	if (value.maxFinalizationTurns !== undefined) {
+		if (!Number.isInteger(value.maxFinalizationTurns) || Number(value.maxFinalizationTurns) < 1 || Number(value.maxFinalizationTurns) > MAX_FINALIZATION_TURNS) {
+			errors.push(`${pathLabel}.maxFinalizationTurns must be an integer from 1 to ${MAX_FINALIZATION_TURNS}.`);
+		}
+	}
+
+	const hasContract = hasArrayItems(value.criteria)
+		|| hasArrayItems(value.evidence)
+		|| hasArrayItems(value.verify)
+		|| value.review !== undefined
+		|| hasArrayItems(value.stopRules);
+	if (!hasContract) {
+		errors.push(`${pathLabel} must include at least one of criteria, evidence, verify, review, or stopRules.`);
+	}
+
+	return errors;
+}
+
+function normalizeCriteria(criteria: AcceptanceConfig["criteria"], evidence: AcceptanceEvidenceKind[]): ResolvedAcceptanceGate[] {
+	return (criteria ?? []).map((criterion, index) => {
+		if (typeof criterion === "string") {
+			return { id: `criterion-${index + 1}`, must: criterion, evidence, severity: "required" as const };
+		}
+		return {
+			id: criterion.id.trim(),
+			must: criterion.must,
+			evidence: criterion.evidence?.filter((item) => VALID_EVIDENCE.has(item)) ?? evidence,
+			severity: criterion.severity ?? "required",
+		};
+	}).filter((criterion) => criterion.must.trim());
+}
+
+function deriveAcceptanceLevel(config: AcceptanceConfig): AcceptanceProvenanceLevel {
+	if (config.review) return "reviewed";
+	if ((config.verify?.length ?? 0) > 0) return "verified";
+	return "checked";
+}
+
+export function resolveEffectiveAcceptance(input: {
+	explicit?: AcceptanceInput;
+	agentName: string;
+	task?: string;
+	mode?: SubagentRunMode;
+	async?: boolean;
+	dynamic?: boolean;
+	dynamicGroup?: boolean;
+}): ResolvedAcceptanceConfig {
+	if (input.explicit === undefined) {
+		return {
+			level: "none",
+			explicit: false,
+			inferredReason: ["acceptance not configured"],
+			criteria: [],
+			evidence: [],
+			verify: [],
+			stopRules: [],
+			finalization: { mode: "none", maxTurns: 0 },
+		};
+	}
+
+	const validationErrors = validateAcceptanceInput(input.explicit);
+	if (validationErrors.length > 0) throw new Error(validationErrors.join(" "));
+	const explicit = input.explicit;
+	const evidence = [...new Set(explicit.evidence ?? [])];
+	const criteria = normalizeCriteria(explicit.criteria, evidence);
+	const verify = explicit.verify ?? [];
+	const stopRules = explicit.stopRules ?? [];
+	return {
+		level: deriveAcceptanceLevel(explicit),
+		explicit: true,
+		inferredReason: ["explicit acceptance contract"],
+		criteria,
+		evidence,
+		verify,
+		...(explicit.review ? { review: explicit.review } : {}),
+		stopRules,
+		finalization: { mode: "self-review-loop", maxTurns: explicit.maxFinalizationTurns ?? DEFAULT_FINALIZATION_MAX_TURNS },
+	};
+}
+
+export function shouldRunAcceptanceFinalization(acceptance: ResolvedAcceptanceConfig): boolean {
+	return acceptance.explicit && acceptance.finalization.mode === "self-review-loop" && acceptance.finalization.maxTurns > 0;
+}
+
+export function acceptanceSelfReviewConfig(acceptance: ResolvedAcceptanceConfig): ResolvedAcceptanceConfig {
+	if (!acceptance.review && acceptance.verify.length === 0) return acceptance;
+	const { review: _review, verify: _verify, ...selfReview } = acceptance;
+	return {
+		...selfReview,
+		level: "checked",
+		verify: [],
+	};
+}
+
+export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig): string {
+	if (acceptance.level === "none") return "";
+	const lines = [
+		"",
+		"## Acceptance Contract",
+		"Completion is not accepted from prose alone. End the initial response with a structured acceptance report.",
+		"After the initial response, the runtime will continue this same session for a bounded self-review/repair loop before accepting the run.",
+		"",
+		"Criteria:",
+		...(acceptance.criteria.length ? acceptance.criteria.map((criterion) => `- ${criterion.id}: ${criterion.must}`) : ["- No explicit criteria were configured; satisfy the requested task and the required evidence/checks below."]),
+		"",
+		`Required evidence: ${acceptance.evidence.join(", ") || "none explicitly requested"}`,
+	];
+	if (acceptance.verify.length > 0) {
+		lines.push("", "Runtime verification commands configured by parent:");
+		for (const command of acceptance.verify) lines.push(`- ${command.id}: ${command.command}`);
+	}
+	if (acceptance.review) {
+		lines.push("", `Independent review gate: ${acceptance.review.required === false ? "optional" : "required"}${acceptance.review.agent ? ` by ${acceptance.review.agent}` : ""}.`);
+		if (acceptance.review.focus) lines.push(`Review focus: ${acceptance.review.focus}`);
+	}
+	if (acceptance.stopRules.length > 0) {
+		lines.push("", "Stop rules:", ...acceptance.stopRules.map((rule) => `- ${rule}`));
+	}
+	lines.push(
+		"",
+		"Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
+		"```acceptance-report",
+		JSON.stringify({
+			criteriaSatisfied: [{ id: "criterion-1", status: "satisfied", evidence: "specific proof" }],
+			changedFiles: [],
+			testsAddedOrUpdated: [],
+			commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
+			validationOutput: [],
+			residualRisks: [],
+			noStagedFiles: true,
+			notes: "anything else the parent should know",
+		}, null, 2),
+		"```",
+	);
+	return lines.join("\n");
+}

package/src/runs/shared/acceptance-evaluation.ts

@@ -0,0 +1,221 @@
+import { spawn, spawnSync } from "node:child_process";
+import * as path from "node:path";
+import type {
+	AcceptanceEvidenceKind,
+	AcceptanceLedger,
+	AcceptanceProvenanceLevel,
+	AcceptanceReport,
+	AcceptanceRuntimeCheck,
+	AcceptanceReviewResult,
+	AcceptanceVerifyCommand,
+	AcceptanceVerifyResult,
+	ResolvedAcceptanceConfig,
+	ResolvedAcceptanceGate,
+} from "../../shared/types.ts";
+import { parseAcceptanceReport } from "./acceptance-reports.ts";
+
+const LEVEL_RANK: Record<AcceptanceProvenanceLevel, number> = {
+	none: 0,
+	attested: 1,
+	checked: 2,
+	verified: 3,
+	reviewed: 4,
+};
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function checkCriteriaSatisfied(criteria: ResolvedAcceptanceGate[], report: AcceptanceReport): AcceptanceRuntimeCheck[] {
+	const reports = new Map((report.criteriaSatisfied ?? []).filter((item) => item.id).map((item) => [item.id!, item]));
+	return criteria.filter((criterion) => criterion.severity !== "recommended").map((criterion) => {
+		const item = reports.get(criterion.id);
+		if (!item) return { id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was not reported.` };
+		if (item.status !== "satisfied") return { id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was reported as ${item.status}.` };
+		return { id: `criterion:${criterion.id}`, status: "passed", message: `Required criterion '${criterion.id}' satisfied.` };
+	});
+}
+
+function reportEvidencePresent(report: AcceptanceReport, kind: AcceptanceEvidenceKind): boolean {
+	switch (kind) {
+		case "changed-files": return isStringArray(report.changedFiles) && report.changedFiles.length > 0;
+		case "tests-added": return isStringArray(report.testsAddedOrUpdated) && report.testsAddedOrUpdated.length > 0;
+		case "commands-run": return Array.isArray(report.commandsRun) && report.commandsRun.length > 0;
+		case "validation-output": return isStringArray(report.validationOutput) && report.validationOutput.length > 0;
+		case "residual-risks": return isStringArray(report.residualRisks);
+		case "no-staged-files": return report.noStagedFiles === true;
+		case "diff-summary": return typeof report.diffSummary === "string" && report.diffSummary.trim().length > 0;
+		case "review-findings": return isStringArray(report.reviewFindings);
+		case "manual-notes": return Boolean((report.manualNotes ?? report.notes)?.trim());
+	}
+}
+
+function checkNoStagedFiles(cwd: string): AcceptanceRuntimeCheck {
+	const result = spawnSync("git", ["status", "--short"], { cwd, encoding: "utf-8" });
+	if (result.status !== 0) {
+		return { id: "no-staged-files", status: "not-applicable", message: "git status unavailable; no staged-files check skipped" };
+	}
+	const staged = result.stdout.split(/\r?\n/).filter((line) => line.length >= 2 && line[0] !== " " && line[0] !== "?");
+	return staged.length === 0
+		? { id: "no-staged-files", status: "passed", message: "No staged files detected." }
+		: { id: "no-staged-files", status: "failed", message: `Staged files present: ${staged.join(", ")}` };
+}
+
+function runStructuralChecks(acceptance: ResolvedAcceptanceConfig, report: AcceptanceReport, cwd: string): AcceptanceRuntimeCheck[] {
+	const checks: AcceptanceRuntimeCheck[] = [];
+	checks.push(...checkCriteriaSatisfied(acceptance.criteria, report));
+	for (const kind of acceptance.evidence) {
+		const present = reportEvidencePresent(report, kind);
+		checks.push({
+			id: `evidence:${kind}`,
+			status: present ? "passed" : "failed",
+			message: present ? `${kind} evidence present.` : `${kind} evidence missing from child report.`,
+		});
+	}
+	if (acceptance.evidence.includes("no-staged-files")) checks.push(checkNoStagedFiles(cwd));
+	return checks;
+}
+
+function trimOutput(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+	return trimmed.length > 12_000 ? `${trimmed.slice(0, 12_000)}\n...[truncated]` : trimmed;
+}
+
+function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string): Promise<AcceptanceVerifyResult> {
+	return new Promise((resolve) => {
+		const startedAt = Date.now();
+		const cwd = command.cwd ? path.resolve(defaultCwd, command.cwd) : defaultCwd;
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		const child = spawn(command.command, {
+			cwd,
+			env: { ...process.env, ...(command.env ?? {}) },
+			shell: true,
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+		});
+		const timeout = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+			setTimeout(() => child.kill("SIGKILL"), 1000).unref?.();
+		}, command.timeoutMs ?? 120_000);
+		timeout.unref?.();
+		child.stdout.on("data", (chunk: Buffer) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString();
+		});
+		child.on("close", (exitCode) => {
+			clearTimeout(timeout);
+			const durationMs = Date.now() - startedAt;
+			const passed = exitCode === 0 && !timedOut;
+			resolve({
+				id: command.id,
+				command: command.command,
+				cwd,
+				exitCode,
+				status: timedOut ? "timed-out" : passed ? "passed" : command.allowFailure ? "allowed-failure" : "failed",
+				stdout: trimOutput(stdout),
+				stderr: trimOutput(stderr),
+				durationMs,
+			});
+		});
+		child.on("error", (error) => {
+			clearTimeout(timeout);
+			resolve({
+				id: command.id,
+				command: command.command,
+				cwd,
+				exitCode: 1,
+				status: command.allowFailure ? "allowed-failure" : "failed",
+				stderr: error instanceof Error ? error.message : String(error),
+				durationMs: Date.now() - startedAt,
+			});
+		});
+	});
+}
+
+export async function evaluateAcceptance(input: {
+	acceptance: ResolvedAcceptanceConfig;
+	output: string;
+	cwd: string;
+	report?: AcceptanceReport;
+	reviewResult?: AcceptanceReviewResult;
+}): Promise<AcceptanceLedger> {
+	const acceptance = input.acceptance;
+	const ledger: AcceptanceLedger = {
+		status: acceptance.level === "none" ? "not-required" : "claimed",
+		explicit: acceptance.explicit,
+		effectiveAcceptance: acceptance,
+		inferredReason: acceptance.inferredReason,
+		criteria: acceptance.criteria,
+		runtimeChecks: [],
+		verifyRuns: [],
+	};
+	if (acceptance.level === "none") return ledger;
+
+	const parsed = input.report ? { report: input.report } : parseAcceptanceReport(input.output);
+	if (parsed.report) {
+		ledger.childReport = parsed.report;
+		ledger.status = "attested";
+	} else {
+		ledger.childReportParseError = parsed.error;
+		ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
+		ledger.status = "rejected";
+		return ledger;
+	}
+
+	if (LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked) {
+		ledger.runtimeChecks = runStructuralChecks(acceptance, parsed.report, input.cwd);
+		if (ledger.runtimeChecks.some((check) => check.status === "failed")) {
+			ledger.status = "rejected";
+			return ledger;
+		}
+		ledger.status = "checked";
+	}
+
+	if (acceptance.verify.length > 0) {
+		ledger.verifyRuns = [];
+		for (const command of acceptance.verify) ledger.verifyRuns.push(await runVerifyCommand(command, input.cwd));
+		if (ledger.verifyRuns.some((run) => run.status === "failed" || run.status === "timed-out")) {
+			ledger.status = "rejected";
+			return ledger;
+		}
+		ledger.status = "verified";
+	}
+
+	if (acceptance.review) {
+		if (input.reviewResult) {
+			ledger.reviewResult = input.reviewResult;
+			ledger.status = input.reviewResult.status === "no-blockers" ? "reviewed" : "rejected";
+		} else {
+			const optionalReview = acceptance.review.required === false;
+			ledger.reviewResult = {
+				status: "needs-parent-decision",
+				findings: [{
+					severity: optionalReview ? "non-blocking" : "blocker",
+					issue: "Reviewed acceptance requires an independent reviewer result.",
+					rationale: "The run cannot be marked reviewed from child self-review or evidence alone.",
+				}],
+			};
+			if (!optionalReview) ledger.status = "rejected";
+		}
+	}
+
+	return ledger;
+}
+
+
+export function acceptanceFailureMessage(ledger: AcceptanceLedger): string | undefined {
+	if (ledger.status !== "rejected") return undefined;
+	const failedCheck = ledger.runtimeChecks.find((check) => check.status === "failed");
+	if (failedCheck) return `Acceptance rejected: ${failedCheck.message}`;
+	const failedVerify = ledger.verifyRuns.find((run) => run.status === "failed" || run.status === "timed-out");
+	if (failedVerify) return `Acceptance verification '${failedVerify.id}' ${failedVerify.status}.`;
+	if (ledger.reviewResult?.status === "needs-parent-decision") return "Acceptance review required but no automatic reviewer result is available.";
+	if (ledger.reviewResult?.status === "blockers") return "Acceptance review found blockers.";
+	return "Acceptance rejected.";
+}

package/src/runs/shared/acceptance-finalization.ts

@@ -0,0 +1,161 @@
+import type {
+	AcceptanceFinalizationTurn,
+	AcceptanceLedger,
+	ResolvedAcceptanceConfig,
+} from "../../shared/types.ts";
+import { acceptanceFailureMessage } from "./acceptance-evaluation.ts";
+import { stripAcceptanceReport } from "./acceptance-reports.ts";
+
+const INITIAL_OUTPUT_LIMIT = 8_000;
+
+function truncateForPrompt(value: string): string {
+	const trimmed = stripAcceptanceReport(value).trim();
+	if (trimmed.length <= INITIAL_OUTPUT_LIMIT) return trimmed || "(initial output was empty after removing acceptance-report)";
+	return `${trimmed.slice(0, INITIAL_OUTPUT_LIMIT)}\n...[truncated]`;
+}
+
+function formatReportForPrompt(ledger: AcceptanceLedger): string {
+	if (ledger.childReport) return JSON.stringify(ledger.childReport, null, 2);
+	return `Missing or malformed acceptance report: ${ledger.childReportParseError ?? "no parse detail"}`;
+}
+
+export function formatAcceptanceFinalizationPrompt(input: {
+	acceptance: ResolvedAcceptanceConfig;
+	initialOutput: string;
+	initialLedger: AcceptanceLedger;
+	turn: number;
+	maxTurns: number;
+	previousFailure?: string;
+}): string {
+	const lines = [
+		"## Acceptance Finalization",
+		"You are continuing the same subagent session. Before this run can be accepted, compare the current work to the acceptance contract and the evidence below.",
+		`This is finalization turn ${input.turn} of ${input.maxTurns}. The run will be rejected if the contract is still not satisfied after turn ${input.maxTurns}.`,
+		"",
+		"If a criterion is incomplete and fixable in this session, keep working now before returning the final report.",
+		"If a criterion cannot be satisfied in this session, report it as not-satisfied, explain the blocker in residualRisks, and say what input would unblock progress.",
+		"Do not claim a criterion is satisfied unless the current work has concrete evidence from files, commands, validation output, or other inspectable artifacts.",
+		"",
+		"## Acceptance Contract",
+		"Criteria:",
+		...(input.acceptance.criteria.length ? input.acceptance.criteria.map((criterion) => `- ${criterion.id}: ${criterion.must}`) : ["- No explicit criteria were configured; satisfy the requested task and required evidence/checks."]),
+		"",
+		`Required evidence: ${input.acceptance.evidence.join(", ") || "none explicitly requested"}`,
+	];
+	if (input.acceptance.verify.length > 0) {
+		lines.push("", "Runtime verification commands that must pass:", ...input.acceptance.verify.map((command) => `- ${command.id}: ${command.command}`));
+	}
+	if (input.acceptance.review) {
+		lines.push("", `Independent review gate after self-review: ${input.acceptance.review.required === false ? "optional" : "required"}${input.acceptance.review.agent ? ` by ${input.acceptance.review.agent}` : ""}.`);
+	}
+	if (input.acceptance.stopRules.length > 0) {
+		lines.push("", "Stop rules are hard constraints while deciding whether to continue, stop as blocked, or report success:", ...input.acceptance.stopRules.map((rule) => `- ${rule}`));
+	}
+	lines.push(
+		"",
+		"Initial visible output:",
+		truncateForPrompt(input.initialOutput),
+		"",
+		"Initial acceptance report:",
+		formatReportForPrompt(input.initialLedger),
+	);
+	if (input.previousFailure) {
+		lines.push("", "Previous finalization failure to address:", input.previousFailure);
+	}
+	lines.push(
+		"",
+		"Now do the self-check. If work was missing and you repaired it, report the repaired final state. Finish with exactly one fenced JSON block tagged `acceptance-report`.",
+		"```acceptance-report",
+		JSON.stringify({
+			criteriaSatisfied: [{ id: "criterion-1", status: "satisfied", evidence: "specific proof from the final state" }],
+			changedFiles: [],
+			testsAddedOrUpdated: [],
+			commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
+			validationOutput: [],
+			residualRisks: [],
+			noStagedFiles: true,
+			notes: "final self-review summary",
+		}, null, 2),
+		"```",
+	);
+	return lines.join("\n");
+}
+
+export function createFinalizationTurn(input: {
+	turn: number;
+	prompt: string;
+	rawOutput: string;
+	ledger: AcceptanceLedger;
+}): AcceptanceFinalizationTurn {
+	const failureMessage = acceptanceFailureMessage(input.ledger);
+	return {
+		turn: input.turn,
+		prompt: input.prompt,
+		status: input.ledger.status,
+		rawOutput: input.rawOutput,
+		...(input.ledger.childReport ? { report: input.ledger.childReport } : {}),
+		...(input.ledger.childReportParseError ? { parseError: input.ledger.childReportParseError } : {}),
+		runtimeChecks: input.ledger.runtimeChecks,
+		verifyRuns: input.ledger.verifyRuns,
+		...(failureMessage ? { failureMessage } : {}),
+	};
+}
+
+export function createFinalizationProcessFailureTurn(input: {
+	turn: number;
+	prompt: string;
+	rawOutput?: string;
+	message: string;
+}): AcceptanceFinalizationTurn {
+	return {
+		turn: input.turn,
+		prompt: input.prompt,
+		status: "rejected",
+		...(input.rawOutput ? { rawOutput: input.rawOutput } : {}),
+		runtimeChecks: [{ id: "finalization-process", status: "failed", message: input.message }],
+		verifyRuns: [],
+		failureMessage: `Acceptance rejected: ${input.message}`,
+	};
+}
+
+export function attachFinalizationToLedger(input: {
+	initialLedger: AcceptanceLedger;
+	authoritativeLedger: AcceptanceLedger;
+	turns: AcceptanceFinalizationTurn[];
+	status: "completed" | "failed";
+	maxTurns: number;
+}): AcceptanceLedger {
+	return {
+		...input.authoritativeLedger,
+		...(input.initialLedger.childReport ? { initialChildReport: input.initialLedger.childReport } : {}),
+		...(input.initialLedger.childReportParseError ? { initialChildReportParseError: input.initialLedger.childReportParseError } : {}),
+		finalization: {
+			mode: "self-review-loop",
+			status: input.status,
+			maxTurns: input.maxTurns,
+			turns: input.turns,
+		},
+	};
+}
+
+export function buildFinalizationProcessFailureLedger(input: {
+	initialLedger: AcceptanceLedger;
+	turns: AcceptanceFinalizationTurn[];
+	maxTurns: number;
+	message: string;
+}): AcceptanceLedger {
+	return attachFinalizationToLedger({
+		initialLedger: input.initialLedger,
+		authoritativeLedger: {
+			...input.initialLedger,
+			status: "rejected",
+			runtimeChecks: [
+				...input.initialLedger.runtimeChecks,
+				{ id: "finalization-process", status: "failed", message: input.message },
+			],
+		},
+		turns: input.turns,
+		status: "failed",
+		maxTurns: input.maxTurns,
+	});
+}