@henryqw/pi-pr 6.2.14 → 9.0.3

package/extensions/pr-comment-sweep.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
 import { markFeedbackHandled } from "./pr-feedback-attention.ts";
+import { PrRun } from "./pr-run.ts";
 import {
 	extensionConfigDir,
 	readTextFileBounded,
@@ -50,7 +51,7 @@ import {
 
 export const SWEEP_RECOVERY_MAX_BYTES = 1024 * 1024;
 
-const STATE_VERSION = 2;
+const STATE_VERSION = 3;
 const STATE_FILE = "state.json";
 const LEDGER_NOTE_MAX_BYTES = 2 * 1024;
 const REPLY_METADATA_RESERVE_BYTES = 8 * 1024;
@@ -73,12 +74,17 @@ type SweepRunGuard = {
 	fingerprint: string;
 };
 type SweepCheck = { command: string; args: string[] };
+type PendingScope = { head: string; exactOutsidePaths: string[] };
+type SweepValidation = { head: string; checks: SweepCheck[] };
 type SweepFinalProjection = {
 	generation: number;
 	contentFingerprint: string;
 	items: Array<{ id: string; kind: FeedbackKind }>;
 	threads: Array<{ id: string; isResolved: boolean }>;
 };
+// Only a fresh start before recovery is written may cancel for safe rerouting.
+export class StaleSweepStart extends Error {}
+
 export type SweepStatus = {
 	phase: SweepPhase;
 	guard: SweepRunGuard;
@@ -91,6 +97,9 @@ export type SweepStatus = {
 	plan: { ledger: SweepLedgerEntry[]; ownedPaths: string[] } | null;
 	approved: boolean;
 	legacyRecovery: boolean;
+	pendingScope: PendingScope | null;
+	validation: SweepValidation | null;
+	legacyChecks: SweepCheck[] | null;
 	projection: SweepFinalProjection | null;
 	attempts: {
 		commit: AttemptState;
@@ -119,7 +128,7 @@ type CommitAttempt = {
 	head: string | null;
 };
 type SweepState = {
-	version: 1 | 2;
+	version: 1 | 2 | 3;
 	workflow: "pi-pr-comment-sweep";
 	worktree: { id: string; root: string };
 	epoch: number;
@@ -137,6 +146,8 @@ type SweepState = {
 	approved: boolean;
 	approvalGeneration: number | null;
 	ownedPaths: string[];
+	pendingScope: PendingScope | null;
+	validation: SweepValidation | null;
 	publicationHead: string | null;
 	projection: SweepFinalProjection | null;
 	attempts: {
@@ -157,6 +168,8 @@ export type PullRequestCommentSweepOptions = {
 	loadCurrentPullRequest?: Load;
 	newRunId?: () => string;
 	pause?: (milliseconds: number) => Promise<void>;
+	run?: PrRun;
+	confirmLegacyChecks?: (head: string, checks: SweepCheck[]) => Promise<boolean>;
 };
 function exactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
 	const actual = Object.keys(value).sort();
@@ -248,8 +261,8 @@ function recoveryMatchesRouteAuthority(state: SweepState, suppliedAuthority: Swe
 		(state.attempts.push.state === "attempting" || state.attempts.push.state === "unknown" || state.attempts.push.state === "applied") &&
 		state.publicationHead
 	) permittedHeads.add(state.publicationHead);
-	return [...permittedHeads].some((head) => sameLinkage(state.authority, suppliedAuthority, head,
-		state.attempts.push.state === "applied"));
+	// The base tip belongs to frozen feedback, not recovery or publication identity.
+	return [...permittedHeads].some((head) => sameLinkage(state.authority, suppliedAuthority, head, true));
 }
 
 function feedbackMatchesAuthority(snapshot: FeedbackSnapshot, authority: SweepAuthority, head: string): boolean {
@@ -414,12 +427,13 @@ function parseState(value: unknown, expectedRoot: string, expectedId: string): S
 		!isRecord(value.attempts) || !isRecord(value.attempts.push) || !isRecord(value.attempts.finalize)) {
 		throw new Error("sweep recovery state is invalid");
 	}
+	if ((value.version !== 1 && value.version !== 2 && value.version !== STATE_VERSION) || value.workflow !== "pi-pr-comment-sweep") throw new Error("unsupported sweep recovery state version");
 	exactKeys(value, [
 		"version", "workflow", "worktree", "epoch", "runId", "phase", "authority", "original", "feedback",
 		"ledger", ...(value.version === 1 && !("approved" in value) ? [] : ["approved"]),
 		...("approvalGeneration" in value ? ["approvalGeneration"] : []), "ownedPaths", "publicationHead", "projection", "attempts",
+		...(value.version === STATE_VERSION ? ["pendingScope", "validation"] : []),
 	], "sweep recovery state");
-	if ((value.version !== 1 && value.version !== STATE_VERSION) || value.workflow !== "pi-pr-comment-sweep") throw new Error("unsupported sweep recovery state version");
 	if (!(["triage", "recorded", "published", "refresh-pending", "refreshed", "resolving", "resolved"] as unknown[]).includes(value.phase)) {
 		throw new Error("sweep recovery phase is invalid");
 	}
@@ -480,8 +494,26 @@ function parseState(value: unknown, expectedRoot: string, expectedId: string): S
 		state: attemptState(value.attempts.finalize.state, "finalize attempt state"),
 		checks: parseChecks(value.attempts.finalize.checks),
 	};
+	let pendingScope: PendingScope | null = null;
+	let validation: SweepValidation | null = null;
+	if (value.version === STATE_VERSION) {
+		if (value.pendingScope !== null) {
+			if (!isRecord(value.pendingScope)) throw new Error("pending scope is invalid");
+			exactKeys(value.pendingScope, ["head", "exactOutsidePaths"], "pending scope");
+			pendingScope = { head: requiredOid(value.pendingScope.head, "pending scope HEAD"), exactOutsidePaths: parseOwnedPaths(value.pendingScope.exactOutsidePaths) };
+			if (value.phase !== "recorded" || push.state !== "none" || !pendingScope.exactOutsidePaths.length || pendingScope.exactOutsidePaths.some((path) => ownedPaths.includes(path))) throw new Error("pending scope is inconsistent");
+		}
+		if (value.validation !== null) {
+			if (!isRecord(value.validation)) throw new Error("validation is invalid");
+			exactKeys(value.validation, ["head", "checks"], "validation");
+			validation = { head: requiredOid(value.validation.head, "validated HEAD"), checks: parseChecks(value.validation.checks) };
+			if (pendingScope || !ledger) throw new Error("validation is inconsistent");
+		}
+	}
 	const state: SweepState = {
-		version: value.version as 1 | 2,
+		version: value.version as 1 | 2 | 3,
+		pendingScope,
+		validation,
 		workflow: "pi-pr-comment-sweep",
 		worktree: { id, root },
 		epoch: integer(value.epoch, "sweep epoch"),
@@ -554,7 +586,10 @@ function status(state: SweepState): SweepStatus {
 		ledgerComplete: state.ledger !== null,
 		plan: state.ledger ? { ledger: structuredClone(state.ledger), ownedPaths: [...state.ownedPaths] } : null,
 		approved: state.approved,
-		legacyRecovery: state.version === 1,
+		legacyRecovery: state.version < STATE_VERSION,
+		pendingScope: structuredClone(state.pendingScope),
+		validation: structuredClone(state.validation),
+		legacyChecks: state.version < STATE_VERSION ? structuredClone(state.attempts.finalize.checks) : null,
 		projection: state.projection ? structuredClone(state.projection) : null,
 		attempts: {
 			commit: state.attempts.commit?.state ?? "none",
@@ -625,6 +660,8 @@ export class PullRequestCommentSweep {
 	private readonly load: Load;
 	private readonly newRunId: () => string;
 	private readonly pause?: (milliseconds: number) => Promise<void>;
+	private readonly run: PrRun;
+	private readonly confirmLegacyChecks?: PullRequestCommentSweepOptions["confirmLegacyChecks"];
 
 	constructor(options: PullRequestCommentSweepOptions) {
 		this.cwd = options.cwd;
@@ -635,6 +672,8 @@ export class PullRequestCommentSweep {
 		this.load = options.loadCurrentPullRequest ?? loadCurrentPullRequest;
 		this.newRunId = options.newRunId ?? randomUUID;
 		this.pause = options.pause;
+		this.run = options.run ?? new PrRun();
+		this.confirmLegacyChecks = options.confirmLegacyChecks;
 	}
 
 	private options(extra: Partial<ExecOptions> = {}): ExecOptions {
@@ -711,8 +750,10 @@ export class PullRequestCommentSweep {
 	}
 
 	private async save(location: Awaited<ReturnType<PullRequestCommentSweep["location"]>>, state: SweepState): Promise<void> {
-		const checked = parseState(state, location.root, location.id);
-		const contents = `${JSON.stringify(checked)}\n`;
+		const { pendingScope: _pending, validation: _validation, ...legacy } = state;
+		const checked = parseState(state.version === STATE_VERSION ? state : legacy, location.root, location.id);
+		const { pendingScope: _checkedPending, validation: _checkedValidation, ...checkedLegacy } = checked;
+		const contents = `${JSON.stringify(checked.version === STATE_VERSION ? checked : checkedLegacy)}\n`;
 		if (Buffer.byteLength(contents, "utf8") > SWEEP_RECOVERY_MAX_BYTES) {
 			throw new Error(`Comment sweep recovery exceeds ${SWEEP_RECOVERY_MAX_BYTES} bytes`);
 		}
@@ -760,6 +801,81 @@ export class PullRequestCommentSweep {
 		return head;
 	}
 
+	private requireRecorded(state: SweepState): void {
+		if (state.phase !== "recorded" || !state.ledger || !state.approved || state.attempts.push.state !== "none" ||
+			state.attempts.commit && state.attempts.commit.state !== "applied" || state.attempts.resolutions.length || state.attempts.finalize.state !== "none") {
+			throw new Error("Scope repair requires recorded unpublished recovery with no unresolved mutation");
+		}
+	}
+
+	/** Inspect scope only after reconciliation; never infer ownership from branch placement. */
+	private async planScope(state: SweepState): Promise<void> {
+		const head = await readHead(this.exec, this.options());
+		const dirty = await this.localPaths();
+		if (dirty.some((path) => !state.ownedPaths.includes(path))) throw new Error("Comment sweep found changes outside owned paths in the worktree");
+		const changed = parseNulPaths((await runChecked(this.exec, "git", ["diff", "--name-only", "--no-renames", "-z", `${state.original.head}..${head}`], this.options())).stdout, "Sweep committed paths");
+		const outside = changed.filter((path) => !state.ownedPaths.includes(path));
+		await this.requireOwnedLocalState({ ...state, ownedPaths: [...state.ownedPaths, ...outside] }, head);
+		if (outside.length) {
+			this.requireRecorded(state);
+			if (dirty.length) throw new Error("Scope review requires a clean worktree");
+			state.pendingScope = { head, exactOutsidePaths: validatePaths(outside, "Pending scope paths") };
+			state.validation = null;
+		} else state.pendingScope = null;
+		if (state.validation?.head !== head) state.validation = null;
+		await this.currentAuthority(state.authority, state.original.lease, true);
+		if (await readHead(this.exec, this.options()) !== head || !isDeepStrictEqual(await this.localPaths(), dirty)) throw new Error("Scope inspection local HEAD or worktree changed");
+	}
+
+	async adopt(guard: SweepRunGuard, headInput: string, outsideInput: string[]): Promise<SweepStatus> {
+		const head = requiredOid(headInput, "Reviewed scope HEAD");
+		const paths = parseOwnedPaths(outsideInput);
+		return await withWorktreeLock(this.cwd, async () => {
+			const location = await this.location();
+			const state = await this.loadState(location);
+			requireGuard(state, guard);
+			this.requireRecorded(state);
+			if (!state.pendingScope || state.pendingScope.head !== head || !isDeepStrictEqual([...state.pendingScope.exactOutsidePaths].sort(), [...paths].sort())) throw new Error("Adoption must match the exact pending scope HEAD and outside paths");
+			await this.planScope(state);
+			if (!state.pendingScope || state.pendingScope.head !== head || !isDeepStrictEqual([...state.pendingScope.exactOutsidePaths].sort(), [...paths].sort())) throw new Error("Reviewed committed scope changed before adoption");
+			state.ownedPaths = validatePaths([...state.ownedPaths, ...paths], "Sweep owned paths");
+			state.pendingScope = null;
+			state.validation = null;
+			await this.requireCleanPublication(state, head);
+			await this.currentAuthority(state.authority, state.original.lease, true);
+			await this.requireCleanPublication(state, head);
+			await this.save(location, state);
+			return status(state);
+		}, { agentDir: this.agentDir, signal: this.signal });
+	}
+
+	async validate(guard: SweepRunGuard, checksInput: SweepCheck[]): Promise<SweepStatus> {
+		const checks = parseChecks(checksInput);
+		return await withWorktreeLock(this.cwd, async () => {
+			const location = await this.location();
+			const state = await this.loadState(location);
+			requireGuard(state, guard);
+			this.requireRecorded(state);
+			if (state.pendingScope) throw new Error("Review and adopt pending scope before validation");
+			const head = await readHead(this.exec, this.options());
+			await this.requireCleanPublication(state, head);
+			await this.currentAuthority(state.authority, state.original.lease, true);
+			this.run.beginChecks("sweep", head, checks);
+			state.version = STATE_VERSION;
+			state.validation = null;
+			await this.save(location, state);
+			try {
+				await runChecked(this.exec, "git", ["diff", "--check", state.original.head, head], this.options());
+				for (const check of checks) await runChecked(this.exec, check.command, check.args, this.options());
+				await this.currentAuthority(state.authority, state.original.lease, true);
+				await this.requireCleanPublication(state, head);
+			} catch (error) { this.run.checksFailed(); throw error; }
+			state.validation = { head, checks };
+			await this.save(location, state);
+			return status(state);
+		}, { agentDir: this.agentDir, signal: this.signal });
+	}
+
 	private async requireCleanPublication(state: SweepState, expectedHead: string): Promise<void> {
 		if ((await this.localPaths()).length) throw new Error("Comment sweep requires a clean worktree");
 		await this.requireOwnedLocalState(state, expectedHead);
@@ -795,6 +911,17 @@ export class PullRequestCommentSweep {
 		};
 	}
 
+	private async requireStartHead(authority: SweepAuthority): Promise<void> {
+		if ((await this.localPaths()).length) throw new Error("Comment sweep start requires a clean worktree");
+		const head = await readHead(this.exec, this.options());
+		if (head === authority.head.oid) return;
+		await this.currentAuthority(authority, authority.head.oid);
+		if (await isAncestor(this.exec, this.options(), authority.head.oid, head)) {
+			throw new StaleSweepStart("Local HEAD is ahead of the frozen PR head; cancelled before sweep recovery or publication");
+		}
+		throw new Error("Comment sweep start requires local HEAD to descend from the frozen PR head");
+	}
+
 	async start(): Promise<SweepStatus> {
 		return await withWorktreeLock(this.cwd, async () => {
 			const location = await this.location();
@@ -802,17 +929,13 @@ export class PullRequestCommentSweep {
 			if (!this.suppliedAuthority) throw new Error("Comment sweep start requires route authority");
 			const authority = this.suppliedAuthority;
 			if (authority.head.oid !== authority.target.remoteOid) throw new Error("Comment sweep requires PR head and remote lease to match");
-			if ((await this.localPaths()).length || await readHead(this.exec, this.options()) !== authority.head.oid) {
-				throw new Error("Comment sweep start requires a clean worktree at the PR head");
-			}
+			await this.requireStartHead(authority);
 			await this.currentAuthority(authority, authority.head.oid);
 			const snapshot = await this.collect(authority, authority.head.oid);
 			await this.currentAuthority(authority, authority.head.oid);
-			if ((await this.localPaths()).length || await readHead(this.exec, this.options()) !== authority.head.oid) {
-				throw new Error("Comment sweep authority changed during feedback fetch");
-			}
+			await this.requireStartHead(authority);
 			const state: SweepState = {
-				version: 2,
+				version: STATE_VERSION,
 				workflow: "pi-pr-comment-sweep",
 				worktree: { id: location.id, root: location.root },
 				epoch: 1,
@@ -830,6 +953,8 @@ export class PullRequestCommentSweep {
 				approved: false,
 				approvalGeneration: null,
 				ownedPaths: [],
+				pendingScope: null,
+				validation: null,
 				publicationHead: null,
 				projection: null,
 				attempts: {
@@ -868,7 +993,7 @@ export class PullRequestCommentSweep {
 		if (state.attempts.push.state === "attempting" || state.attempts.push.state === "unknown") {
 			const attemptedHead = state.attempts.push.head;
 			if (!attemptedHead) throw new Error("Attempted push has no captured head");
-			await this.currentAuthority(state.authority, remote);
+			await this.currentAuthority(state.authority, remote, true);
 			if (remote === attemptedHead) {
 				state.attempts.push.state = "applied";
 				state.phase = "published";
@@ -883,7 +1008,7 @@ export class PullRequestCommentSweep {
 			: state.original.lease;
 		remote = await readRemoteOid(this.exec, this.options(), state.authority.target.fetchSource, state.authority.target.ref);
 		if (remote !== expectedRemote) throw new Error("Comment sweep remote authority cannot be reconciled");
-		await this.currentAuthority(state.authority, expectedRemote, state.attempts.push.state === "applied");
+		await this.currentAuthority(state.authority, expectedRemote, true);
 
 		const pending = state.attempts.resolutions.filter(({ state: attempt }) => attempt === "attempting" || attempt === "unknown");
 		if (pending.length > 1) throw new Error("Multiple unresolved mutation attempts cannot be reconciled");
@@ -944,16 +1069,16 @@ export class PullRequestCommentSweep {
 				state.attempts.push = { state: "none", head: null };
 				state.publicationHead = null;
 			}
-			if (state.attempts.finalize.state === "blocked") state.attempts.finalize = { state: "none", checks: [] };
 			const published = state.attempts.push.state === "applied";
-			if (published) state.version = 2;
+			if (!published) state.version = STATE_VERSION;
 			const expectedRemote = published ? state.publicationHead! : state.original.lease;
-			await this.currentAuthority(state.authority, expectedRemote, published);
-			await this.requireOwnedLocalState(state, published ? expectedRemote : undefined);
+			await this.currentAuthority(state.authority, expectedRemote, true);
 			if (state.ledger) {
 				state.approved = true;
 				state.approvalGeneration = state.feedback.generation;
 			}
+			if (published) await this.requireCleanPublication(state, expectedRemote);
+			else await this.planScope(state);
 			state.epoch += 1;
 			state.runId = safeRunId(this.newRunId());
 			await this.save(location, state);
@@ -978,7 +1103,7 @@ export class PullRequestCommentSweep {
 			if (state.phase === "triage" && state.ledger === null) {
 				if (ownedPathsInput === undefined) throw new Error("Initial comment sweep ledger requires ownedPaths");
 				await this.requireCleanPublication(state, state.original.head);
-				await this.currentAuthority(state.authority, state.original.lease);
+				await this.currentAuthority(state.authority, state.original.lease, true);
 				state.ledger = exactLedger(ledgerInput, state.feedback.snapshot);
 				state.approved = true;
 				state.approvalGeneration = state.feedback.generation;
@@ -1010,10 +1135,11 @@ export class PullRequestCommentSweep {
 			if (state.phase !== "recorded" || !state.ledger || !state.approved || state.attempts.push.state !== "none") {
 				throw new Error("Comment sweep is not ready to commit");
 			}
+			if (state.pendingScope) throw new Error("Review and adopt pending scope before committing");
 			if (state.attempts.commit && state.attempts.commit.state !== "applied") {
 				throw new Error("Comment sweep has an unreconciled commit; use resume");
 			}
-			await this.currentAuthority(state.authority, state.original.lease);
+			await this.currentAuthority(state.authority, state.original.lease, true);
 			const beforeHead = await this.requireOwnedLocalState(state);
 			const paths = await this.localPaths();
 			if (paths.some((path) => !state.ownedPaths.includes(path))) throw new Error("Comment sweep found changes outside owned paths before staging");
@@ -1023,9 +1149,10 @@ export class PullRequestCommentSweep {
 			const tree = requiredOid(parseSingleOutputLine((await runChecked(this.exec, "git", ["write-tree"], this.options())).stdout, "Commit tree"), "commit tree");
 			const attempt: CommitAttempt = { state: "attempting", beforeHead, tree, head: null };
 			state.attempts.commit = attempt;
+			state.validation = null;
 			await this.save(location, state);
 			try {
-				await this.currentAuthority(state.authority, state.original.lease);
+				await this.currentAuthority(state.authority, state.original.lease, true);
 				await this.requireOwnedLocalState(state, beforeHead);
 				if (parseSingleOutputLine((await runChecked(this.exec, "git", ["write-tree"], this.options())).stdout, "Commit tree") !== tree) {
 					throw new Error("Comment sweep index changed before commit");
@@ -1054,24 +1181,26 @@ export class PullRequestCommentSweep {
 			if (state.phase !== "recorded" || !state.ledger || state.attempts.push.state !== "none" || !state.approved) {
 				throw new Error("Comment sweep is not ready to publish");
 			}
+			if (state.pendingScope) throw new Error("Review and adopt pending scope before publication");
 			if (state.attempts.commit && state.attempts.commit.state !== "applied") {
 				throw new Error("Comment sweep has an unreconciled commit; use resume");
 			}
 			const head = await this.requireOwnedLocalState(state);
 			if ((await this.localPaths()).length) throw new Error("Comment sweep publish requires a clean worktree; use the commit action for owned fixes first");
-			await this.currentAuthority(state.authority, state.original.lease);
+			await this.currentAuthority(state.authority, state.original.lease, true);
 			if (head === state.original.head) {
 				state.publicationHead = head;
 				state.attempts.push = { state: "applied", head };
 				state.phase = "published";
-				state.version = 2;
 				await this.save(location, state);
 				return status(state);
 			}
+			if (!state.validation || state.validation.head !== head) throw new Error("Comment sweep requires validation on the exact clean HEAD before publication");
+			this.run.beforePush(state.original.lease, head);
 			if (!(await isAncestor(this.exec, this.options(), state.original.lease, head))) {
 				throw new Error("Comment sweep push would not fast-forward the original lease");
 			}
-			await this.currentAuthority(state.authority, state.original.lease);
+			await this.currentAuthority(state.authority, state.original.lease, true);
 			if (await readHead(this.exec, this.options()) !== head || (await this.localPaths()).length) {
 				throw new Error("Comment sweep local HEAD or worktree changed before push");
 			}
@@ -1087,10 +1216,10 @@ export class PullRequestCommentSweep {
 				if (await readRemoteOid(this.exec, this.options(), state.authority.target.fetchSource, state.authority.target.ref) !== head) {
 					throw new Error("Published remote ref did not match captured HEAD");
 				}
-				await this.currentAuthority(state.authority, head);
+				await this.currentAuthority(state.authority, head, true);
 				state.attempts.push.state = "applied";
 				state.phase = "published";
-				state.version = 2;
+				this.run.observeRemote(head);
 				await this.save(location, state);
 				return status(state);
 			} catch (error) {
@@ -1128,7 +1257,7 @@ export class PullRequestCommentSweep {
 			state.approved = ledger !== null;
 			state.approvalGeneration = ledger ? state.feedback.generation : null;
 			state.projection = ledger ? buildProjection(state.feedback.generation, snapshot, ledger) : null;
-			state.attempts.finalize = { state: "none", checks: [] };
+			if (state.version === STATE_VERSION) state.attempts.finalize = { state: "none", checks: [] };
 			state.phase = ledger ? "refreshed" : "refresh-pending";
 			await this.save(location, state);
 			return status(state);
@@ -1299,13 +1428,19 @@ export class PullRequestCommentSweep {
 			if (state.attempts.resolutions.some(({ state: attempt }) => attempt !== "applied")) {
 				throw new Error("Comment sweep has unresolved or unknown mutation attempts");
 			}
-			if (state.attempts.finalize.state !== "none" && state.attempts.finalize.state !== "applied") {
-				throw new Error("Comment sweep has an unreconciled finalization attempt; use resume");
+			const legacy = state.version < STATE_VERSION;
+			if (!legacy && state.attempts.finalize.state !== "none" && state.attempts.finalize.state !== "applied") throw new Error("Comment sweep has an unresolved finalization attempt");
+			if (!legacy && checks.length) throw new Error("Run checks with validate before publication; v3 finalization runs no new checks");
+			if (legacy && state.attempts.finalize.state !== "none" && !isDeepStrictEqual(state.attempts.finalize.checks, checks)) throw new Error("Legacy recovery requires exactly its saved checks");
+			if (state.attempts.finalize.state === "unknown" || state.attempts.finalize.state === "attempting") {
+				if (this.run.hasExecuted(state.publicationHead, checks) || !this.confirmLegacyChecks ||
+					!await this.confirmLegacyChecks(state.publicationHead, checks)) throw new Error("Legacy check outcome unknown; a later /pr requires explicit confirmation of safe repeatability");
 			}
 			await this.freshProjection(state);
 			const alreadyChecked = state.attempts.finalize.state === "applied" &&
 				isDeepStrictEqual(state.attempts.finalize.checks, checks);
-			if (!alreadyChecked) {
+			if (!alreadyChecked && legacy) {
+				this.run.beginChecks("sweep-legacy", state.publicationHead, checks);
 				state.attempts.finalize = { state: "attempting", checks };
 				await this.save(location, state);
 				for (const check of checks) {
@@ -1313,16 +1448,19 @@ export class PullRequestCommentSweep {
 					try {
 						result = await this.exec(check.command, check.args, this.options());
 					} catch (error) {
+						this.run.checksFailed();
 						state.attempts.finalize.state = "unknown";
 						await this.save(location, state);
 						throw error;
 					}
 					if (result.killed) {
+						this.run.checksFailed();
 						state.attempts.finalize.state = "unknown";
 						await this.save(location, state);
 						throw new Error(`Finalization check was killed: ${check.command}`);
 					}
 					if (result.code !== 0) {
+						this.run.checksFailed();
 						state.attempts.finalize.state = "blocked";
 						await this.save(location, state);
 						const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.code}`;

package/extensions/pr-create.ts

@@ -1,3 +1,4 @@
+import type { PrRun } from "./pr-run.ts";
 import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
 import {
 	branchTrackingRef,
@@ -75,6 +76,7 @@ type CreatePullRequestResult =
 	| { kind: "published"; url: string };
 
 export type CreatePullRequestOptions = {
+	run?: PrRun;
 	cwd: string;
 	target: PullRequestTarget;
 	signal?: AbortSignal;
@@ -162,6 +164,7 @@ function parseCreatedUrl(output: string, host: string, baseRepository: string):
 export class PullRequestCreator {
 	readonly state: CreatePullRequestState = { phase: "unprepared" };
 
+	private readonly run?: PrRun;
 	private readonly cwd: string;
 	private readonly target: PullRequestTarget;
 	private readonly noTarget: boolean;
@@ -173,6 +176,7 @@ export class PullRequestCreator {
 
 	constructor(options: CreatePullRequestOptions) {
 		this.cwd = options.cwd;
+		this.run = options.run;
 		this.target = { ...options.target };
 		this.noTarget = options.target.provenance === "inferred" && options.target.remoteOid === null;
 		this.signal = options.signal;
@@ -359,6 +363,7 @@ export class PullRequestCreator {
 			await this.freshNone();
 			if (await this.liveBase() !== this.state.base!.oid) throw new Error("PR creation cancelled: frozen base moved");
 			if (await this.requireCleanHead() !== head) throw new Error("PR creation cancelled: local HEAD changed before push");
+			this.run?.beforePush(original, head);
 			this.state.publicationHead = head;
 			this.state.phase = "blocked";
 			await runChecked(this.exec, "git", [
@@ -368,6 +373,7 @@ export class PullRequestCreator {
 			if (await readRemoteOid(this.exec, this.options(), this.target.fetchSource, this.target.ref) !== head) {
 				throw new Error("Published remote ref did not match captured HEAD");
 			}
+			this.run?.observeRemote(head);
 			this.state.phase = "pushed";
 			if (this.noTarget) {
 				await this.configureNoTargetUpstream(head);

package/extensions/pr-github.ts

@@ -116,7 +116,7 @@ export type PullRequestObservation = {
 	target: { repository: string; branch: string; remote: string; ref: string };
 };
 
-export type PullRequestLoadContext = { cwd: string; signal?: AbortSignal };
+export type PullRequestLoadContext = { cwd: string; signal?: AbortSignal; rebaseBranch?: string };
 
 type PullRequestCreationPreflight = {
 	head: string;
@@ -861,10 +861,11 @@ function conditions(
 		? "pending"
 		: "ready";
 	const behind = candidate.mergeStateStatus === "BEHIND";
+	const conflict = candidate.mergeable === "CONFLICTING" || candidate.mergeStateStatus === "DIRTY";
 	return {
 		draft: candidate.isDraft,
 		baseUpdateRequired: behind,
-		conflict: candidate.mergeable === "CONFLICTING" || candidate.mergeStateStatus === "DIRTY",
+		conflict,
 		changesRequested: candidate.reviewDecision === "CHANGES_REQUESTED",
 		unresolvedThreads,
 		ci: ciStatus(candidate.checkStates),
@@ -872,6 +873,10 @@ function conditions(
 		policy: candidate.mergeable === "MERGEABLE" && candidate.mergeStateStatus === "CLEAN"
 			? "ready"
 			: "pending",
+		// A confirmed conflict on either field is definitive; the other field's UNKNOWN is not worth waiting for.
+		mergeability: !conflict && (candidate.mergeable === "UNKNOWN" || candidate.mergeStateStatus === "UNKNOWN")
+			? "pending"
+			: "known",
 	};
 }
 
@@ -1365,7 +1370,9 @@ async function readPushTarget(
 	if (worktree.code !== 0) commandFailure("Check Git worktree", worktree);
 	if (worktreeOutput !== "true\n") fail("Check Git worktree", "invalid response");
 
-	const branchResult = await execute(pi, context, "Read current branch", "git", ["branch", "--show-current"]);
+	const branchResult = context.rebaseBranch === undefined
+		? await execute(pi, context, "Read current branch", "git", ["branch", "--show-current"])
+		: { stdout: `${context.rebaseBranch}\n` };
 	if (branchResult.stdout === "") return { kind: "blocked", issue: "detached" };
 	let branch: string;
 	try {

package/extensions/pr-merge.ts

@@ -6,6 +6,7 @@ import {
 	runChecked,
 } from "./pr-execution.ts";
 import type { LocalMergeSafety } from "./pr-routing.ts";
+import type { MergeMethod } from "./pr-run.ts";
 
 const MERGE_PULL_REQUEST_MUTATION = "mutation($pullRequestId:ID!,$expectedHeadOid:GitObjectID!,$mergeMethod:PullRequestMergeMethod!){mergePullRequest(input:{pullRequestId:$pullRequestId,expectedHeadOid:$expectedHeadOid,mergeMethod:$mergeMethod}){pullRequest{id state}}}";
 
@@ -23,6 +24,8 @@ type InspectedLocalMergeSafety = LocalMergeSafety & {
 type ExecuteGitHubMergeInput = InspectLocalMergeSafetyInput & {
 	pullRequestId: string;
 	hostname: string;
+	/** Configured merge method; GitHub rejects a method the repository does not allow. */
+	mergeMethod?: MergeMethod;
 	expectedBase: {
 		repository: string;
 		ref: string;
@@ -127,7 +130,7 @@ export async function executeGitHubMerge(input: ExecuteGitHubMergeInput): Promis
 		"-F",
 		`expectedHeadOid=${input.expectedHead}`,
 		"-F",
-		"mergeMethod=SQUASH",
+		`mergeMethod=${(input.mergeMethod ?? "squash").toUpperCase()}`,
 	], { cwd: input.cwd });
 	const output = merged.stdout.trim();
 	if (!output) throw new Error("GitHub merge returned no output");