@henryqw/pi-pr 6.2.13 → 9.0.2

package/extensions/pr-ci.ts

@@ -1,4 +1,6 @@
+import type { PrRun } from "./pr-run.ts";
 import { createHash } from "node:crypto";
+import { stripVTControlCharacters } from "node:util";
 import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
 import {
 	cloneCurrentPullRequest,
@@ -43,6 +45,13 @@ const STATUSES = new Set(["completed", "in_progress", "pending", "queued", "requ
 
 type Load = typeof loadCurrentPullRequest;
 
+// Only initial preflight, before any CI evidence read, can authorize rediscovery.
+export class StaleCiCollect extends Error {}
+
+function sanitizeLog(text: string): string {
+	return stripVTControlCharacters(text).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "");
+}
+
 type StepIdentity = {
 	number: number;
 	name: string;
@@ -113,6 +122,7 @@ type CiFixPhase = "ready" | "collecting" | "collected" | "published" | "blocked"
 type CiFixState = { phase: CiFixPhase };
 
 export type PullRequestCiFixOptions = {
+	run?: PrRun;
 	cwd: string;
 	authority: CurrentPullRequest;
 	signal?: AbortSignal;
@@ -291,6 +301,7 @@ function errorMessage(error: unknown): string {
 export class PullRequestCiFixer {
 	readonly state: CiFixState = { phase: "ready" };
 
+	private readonly run?: PrRun;
 	private readonly cwd: string;
 	private readonly authority: CurrentPullRequest;
 	private readonly signal?: AbortSignal;
@@ -307,6 +318,7 @@ export class PullRequestCiFixer {
 			throw new TypeError("CI repair requires the pull request head to match the configured remote OID");
 		}
 		this.cwd = options.cwd;
+		this.run = options.run;
 		this.authority = cloneCurrentPullRequest(options.authority);
 		this.signal = options.signal;
 		this.agentDir = options.agentDir;
@@ -326,21 +338,22 @@ export class PullRequestCiFixer {
 		return { cwd: this.cwd, signal: this.signal };
 	}
 
-	private async freshAuthority(requireOriginalLocal: boolean): Promise<CurrentPullRequest> {
+	private async freshAuthority(requireOriginalLocal: boolean, initial = false): Promise<CurrentPullRequest> {
 		const discovery = await this.load(this.pi(), this.context());
 		if (discovery.kind !== "current" || !samePullRequestSnapshot(this.authority, discovery.pullRequest) ||
-			discovery.pullRequest.base.oid !== this.authority.base.oid ||
+			(!initial && discovery.pullRequest.base.oid !== this.authority.base.oid) ||
 			discovery.pullRequest.conditions.ci !== "failure" ||
 			discovery.pullRequest.target.remoteOid !== this.authority.head.oid) {
 			throw new Error("CI repair cancelled: frozen pull request, base, target, head, or failed-CI authority changed");
 		}
-		if (requireOriginalLocal && (discovery.pullRequest.local.worktree !== "clean" || discovery.pullRequest.local.head !== "equal")) {
+		if (requireOriginalLocal && (discovery.pullRequest.local.worktree !== "clean" ||
+			(discovery.pullRequest.local.head !== "equal" && !(initial && discovery.pullRequest.local.head === "ahead")))) {
 			throw new Error("CI repair evidence requires the original clean equal local HEAD");
 		}
 		return discovery.pullRequest;
 	}
 
-	private async requireOriginalLocal(): Promise<void> {
+	private async requireOriginalLocal(initial = false): Promise<string> {
 		const branch = requiredText(parseSingleOutputLine(
 			(await runChecked(this.exec, "git", ["branch", "--show-current"], this.options())).stdout,
 			"current branch",
@@ -349,9 +362,12 @@ export class PullRequestCiFixer {
 		if (await inspectWorktree(this.exec, this.options()) !== "clean") {
 			throw new Error("CI repair requires a clean worktree with no Git operation in progress");
 		}
-		if (await readHead(this.exec, this.options()) !== this.authority.head.oid) {
+		const head = await readHead(this.exec, this.options());
+		if (head !== this.authority.head.oid &&
+			!(initial && await isAncestor(this.exec, this.options(), this.authority.head.oid, head))) {
 			throw new Error("CI repair evidence requires local HEAD to equal the frozen pull request head");
 		}
+		return head;
 	}
 
 	private async api(endpoint: string, label: string, options: Partial<ExecOptions> = {}): Promise<string> {
@@ -545,9 +561,17 @@ export class PullRequestCiFixer {
 		return run;
 	}
 
-	private async readSnapshot(requireOriginalLocal: boolean): Promise<CiSnapshot> {
-		const fresh = await this.freshAuthority(requireOriginalLocal);
-		if (requireOriginalLocal) await this.requireOriginalLocal();
+	private async readSnapshot(requireOriginalLocal: boolean, initial = false): Promise<CiSnapshot> {
+		const fresh = await this.freshAuthority(requireOriginalLocal, initial);
+		const head = requireOriginalLocal ? await this.requireOriginalLocal(initial) : undefined;
+		if (initial && (head !== this.authority.head.oid || fresh.base.oid !== this.authority.base.oid)) {
+			await this.requireSavedDestination(this.authority.head.oid);
+			if (await this.requireOriginalLocal(true) !== head) throw new Error("CI repair HEAD changed during initial preflight");
+			this.signal?.throwIfAborted();
+			throw new StaleCiCollect(head !== this.authority.head.oid
+				? "Local HEAD is ahead of the frozen PR head; cancelled before CI evidence or publication"
+				: "Base tip changed on the same ref; cancelled before CI evidence or publication");
+		}
 		const pageBudget = { pages: 0, records: 0 };
 		const checks = await this.readCheckRuns(pageBudget);
 		const failed = checks.filter(({ conclusion: value }) => value !== null && FAILED_CONCLUSIONS.has(value));
@@ -600,13 +624,22 @@ export class PullRequestCiFixer {
 	}
 
 	private async readJobLog(jobId: number): Promise<{ text: string; truncated: boolean }> {
-		const result = await runChecked(this.exec, "gh", [
-			"api", "--hostname", this.authority.host, ...API_HEADERS,
+		// Sanitize before runChecked can include output in a failure diagnostic.
+		const exec: Exec = async (command, args, options) => {
+			const result = await this.exec(command, args, options);
+			if (Buffer.byteLength(result.stdout, "utf8") > LOG_TAIL_BYTES) {
+				throw new Error(`Read failed job ${jobId} log executor exceeded its retained tail limit`);
+			}
+			return {
+				...result,
+				stdout: sanitizeLog(result.stdout),
+				stderr: sanitizeLog(result.stderr),
+			};
+		};
+		const result = await runChecked(exec, "gh", [
+			"api", "--allow-escape-sequences", "--hostname", this.authority.host, ...API_HEADERS,
 			`repos/${this.authority.base.repository}/actions/jobs/${jobId}/logs`,
 		], this.options({ stdoutTailBytes: LOG_TAIL_BYTES, timeoutMs: LOG_TIMEOUT_MS }));
-		if (Buffer.byteLength(result.stdout, "utf8") > LOG_TAIL_BYTES) {
-			throw new Error(`Read failed job ${jobId} log executor exceeded its retained tail limit`);
-		}
 		return { text: result.stdout, truncated: result.stdoutTruncated === true };
 	}
 
@@ -614,7 +647,7 @@ export class PullRequestCiFixer {
 		if (this.state.phase !== "ready") throw new Error("CI evidence collect action was already consumed");
 		this.state.phase = "collecting";
 		try {
-			const before = await this.readSnapshot(true);
+			const before = await this.readSnapshot(true, true);
 			const metadata = before.failures.map((failure) => failureEvidence(this.authority, failure, { text: "", truncated: false }));
 			const metadataBytes = metadata.map(jsonBytes);
 			const metadataTotal = jsonBytes(metadata);
@@ -710,6 +743,7 @@ export class PullRequestCiFixer {
 				const repairHead = await this.validatePublishAuthority();
 				const original = this.authority.head.oid;
 				await this.finalPublishRevalidation(original, repairHead);
+				this.run?.beforePush(original, repairHead);
 				let pushError: unknown;
 				try {
 					await runChecked(this.exec, "git", [
@@ -733,6 +767,7 @@ export class PullRequestCiFixer {
 					throw new Error(`CI repair push outcome is unknown: ${errorMessage(error)}`);
 				}
 				if (postcondition === repairHead) {
+					this.run?.observeRemote(repairHead);
 					this.state.phase = "published";
 					return { kind: "published", head: repairHead, attempt: "applied" };
 				}

package/extensions/pr-command.ts

@@ -2,7 +2,10 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { setTimeout as delay } from "node:timers/promises";
 import { executeGitHubMerge } from "./pr-merge.ts";
+import type { MergeMethod, PrRun } from "./pr-run.ts";
+import { syncLocalHead } from "./pr-sync.ts";
 import { needsFeedbackAttention } from "./pr-feedback-attention.ts";
 import {
 	linkInferredPullRequest,
@@ -26,6 +29,9 @@ const WORKFLOWS: Record<WorkflowNextStep, string> = {
 	"fix-ci": "skill:pi-pr-fix-ci",
 };
 export const WORKFLOW_ROUTES: ReadonlySet<string> = new Set(Object.keys(WORKFLOWS));
+/** GitHub recomputes mergeability shortly after a push; re-read a few times before giving up. */
+const REFRESH_ATTEMPTS = 3;
+const REFRESH_DELAY_MS = 5_000;
 type WorkflowReservation =
 	| { route: "create"; target: PullRequestTarget }
 	| { route: Exclude<WorkflowNextStep, "create">; pullRequest: CurrentPullRequest };
@@ -36,7 +42,9 @@ type PrCommandPi = Pick<ExtensionAPI, "exec" | "getCommands" | "sendUserMessage"
 export type PrCommandInvocation = ((nextStep: NextStep) => void) & {
 	sessionGeneration: number;
 	assertCurrent(): void;
-	completedRoutes?: ReadonlySet<string>;
+	run?: PrRun;
+	staleRediscoveries?: number;
+	replanAuthority?: CurrentPullRequest;
 };
 export type PrCommandHandler = (
 	args: string,
@@ -47,6 +55,7 @@ export type PrCommandHandler = (
 export type WorkflowPromptIdentity = Readonly<{
 	route: WorkflowNextStep;
 	skill: string;
+	path: string;
 	runId: string;
 	action: WorkflowLaunchAction;
 }>;
@@ -57,6 +66,11 @@ export type PrCommandDependencies = {
 	linkInferredPullRequest?: typeof linkInferredPullRequest;
 	inspectSweepRecovery?: (pullRequest: CurrentPullRequest, ctx: ExtensionContext) => Promise<boolean>;
 	inspectBranchRecovery?: (pullRequest: CurrentPullRequest, ctx: ExtensionContext) => Promise<boolean>;
+	syncLocalHead?: typeof syncLocalHead;
+	refreshAttempts?: number;
+	refreshDelayMs?: number;
+	/** Test override for the CI poll sleep; the budget still follows the run policy. */
+	ciPollMs?: number;
 	reserveWorkflow?: (
 		reservation: WorkflowReservation,
 		ctx: ExtensionContext,
@@ -106,13 +120,11 @@ async function dispatchWorkflow(
 		runId = reserved.runId;
 		invocation?.assertCurrent();
 		const queued = !ctx.isIdle();
-		const identity = { route, skill: workflow.name, runId, action: reserved.action };
+		const identity = { route, skill: workflow.name, path: workflow.sourceInfo.path, runId, action: reserved.action };
 		markPromptQueued(identity, queued);
-		const options = queued
-			? { deliverAs: "followUp" as const, expandPromptTemplates: true }
-			: { expandPromptTemplates: true };
 		invocation?.assertCurrent();
-		pi.sendUserMessage(`/${identity.skill} runId=${identity.runId} action=${identity.action}`, options);
+		// Busy-session launches are consumed by agent_before_settle, not user input queues.
+		if (!queued) pi.sendUserMessage(`/${identity.skill} runId=${identity.runId} action=${identity.action}`, { expandPromptTemplates: true });
 	} catch (error) {
 		if (runId !== undefined) release(runId, invocation);
 		throw error;
@@ -129,15 +141,6 @@ function noActionNotification(pullRequest: CurrentPullRequest): { message: strin
 	if (pullRequest.conditions.ci === "failure-blocked") {
 		return { message: `PR #${pullRequest.number} has a failed CI check that cannot run the CI fix workflow`, type: "warning" };
 	}
-	const mutatingWorkflowSelected = pullRequest.conditions.conflict ||
-		pullRequest.conditions.changesRequested || pullRequest.conditions.unresolvedThreads > 0 ||
-		pullRequest.conditions.ci === "failure";
-	if (mutatingWorkflowSelected && pullRequest.local.worktree === "dirty") {
-		return { message: `PR #${pullRequest.number} is blocked by a dirty worktree`, type: "warning" };
-	}
-	if (mutatingWorkflowSelected && pullRequest.local.head !== "equal") {
-		return { message: `PR #${pullRequest.number} is blocked by local HEAD ${pullRequest.local.head}`, type: "warning" };
-	}
 	if (pullRequest.conditions.ci === "running") {
 		return { message: `PR #${pullRequest.number} is waiting for CI`, type: "warning" };
 	}
@@ -147,12 +150,6 @@ function noActionNotification(pullRequest: CurrentPullRequest): { message: strin
 	if (pullRequest.conditions.policy === "pending") {
 		return { message: `PR #${pullRequest.number} is blocked by merge policy`, type: "warning" };
 	}
-	if (pullRequest.local.worktree === "dirty") {
-		return { message: `PR #${pullRequest.number} is blocked by a dirty worktree`, type: "warning" };
-	}
-	if (pullRequest.local.head === "ahead" || pullRequest.local.head === "diverged") {
-		return { message: `PR #${pullRequest.number} is blocked by local HEAD ${pullRequest.local.head}`, type: "warning" };
-	}
 	return { message: `PR #${pullRequest.number} has no available action`, type: "warning" };
 }
 
@@ -171,8 +168,10 @@ async function mergePullRequest(
 	current: CurrentPullRequest,
 	load: typeof loadCurrentPullRequest,
 	needsFeedback: typeof needsFeedbackAttention,
+	mergeMethod: MergeMethod | undefined,
 ): Promise<void> {
 	await executeGitHubMerge({
+		mergeMethod,
 		exec: (command, args, options) => pi.exec(command, args, {
 			...options,
 			signal: ctx.signal,
@@ -228,6 +227,9 @@ export function createPrCommandHandler(
 	const link = dependencies.linkInferredPullRequest ?? linkInferredPullRequest;
 	const inspectSweepRecovery = dependencies.inspectSweepRecovery ?? (async () => false);
 	const inspectBranchRecovery = dependencies.inspectBranchRecovery ?? (async () => false);
+	const sync = dependencies.syncLocalHead ?? syncLocalHead;
+	const refreshAttempts = dependencies.refreshAttempts ?? REFRESH_ATTEMPTS;
+	const refreshDelayMs = dependencies.refreshDelayMs ?? REFRESH_DELAY_MS;
 	const reserve = dependencies.reserveWorkflow ?? (async () => {
 		throw new Error("/pr workflow tools are unavailable");
 	});
@@ -237,10 +239,17 @@ export function createPrCommandHandler(
 		args: string, ctx: ExtensionContext,
 		onRouteResolved?: PrCommandInvocation,
 		linkedAuthority?: CurrentPullRequest,
+		refreshes = 0,
+		ciWaits = 0,
 	): Promise<NextStep> => {
 		if (args.trim()) throw new Error("/pr does not accept arguments");
 		const discovery = await load(pi, ctx);
 		onRouteResolved?.assertCurrent();
+		if (discovery.kind === "current") onRouteResolved?.run?.observeRemote(discovery.pullRequest.head.oid);
+		if (onRouteResolved?.replanAuthority && (discovery.kind !== "current" ||
+			!samePullRequestSnapshot(onRouteResolved.replanAuthority, discovery.pullRequest))) {
+			throw new Error("PR stale-route rediscovery cancelled: frozen PR identity, destination, or remote head changed");
+		}
 		if (linkedAuthority && (discovery.kind !== "current" || discovery.pullRequest.target.provenance !== "configured" ||
 			!isSameConfirmedMerge(linkedAuthority, discovery.pullRequest))) {
 			throw new Error("Link branch continuation cancelled: configured pull request context changed");
@@ -258,7 +267,7 @@ export function createPrCommandHandler(
 			nextStep = "sweep";
 			onRouteResolved?.assertCurrent();
 		}
-		if (discovery.kind === "current" && (nextStep === "merge" || nextStep === "none") &&
+		if (discovery.kind === "current" && (nextStep === "merge" || nextStep === "none" || nextStep === "wait-ci") &&
 			discovery.pullRequest.lifecycle === "open" && !discovery.pullRequest.conditions.draft &&
 			discovery.pullRequest.target.provenance === "configured" &&
 			discovery.pullRequest.local.worktree === "clean" && discovery.pullRequest.local.head === "equal") {
@@ -283,15 +292,58 @@ export function createPrCommandHandler(
 			if (linked.target.provenance !== "configured") throw new Error("Link branch failed: target was not configured");
 			return await handle("", ctx, onRouteResolved, linked);
 		}
+		if (nextStep === "sync-local") {
+			if (discovery.kind !== "current") throw new Error("/pr sync failed: pull request is unavailable");
+			const current = discovery.pullRequest;
+			if (onRouteResolved?.run?.hasCompleted("sync-local", current.head.oid)) {
+				ctx.ui.notify("PR sync-local already ran; inspect fresh state before retrying", "warning");
+				return "none";
+			}
+			const synced = await sync({ cwd: ctx.cwd, authority: current, signal: ctx.signal, loadCurrentPullRequest: load });
+			onRouteResolved?.assertCurrent();
+			onRouteResolved?.run?.complete("sync-local", current.head.oid);
+			const verb = synced.kind === "fast-forwarded" ? "fast-forwarded to" : synced.kind === "rebased" ? "rebased onto" : "already at";
+			ctx.ui.notify(`PR #${current.number}: local branch ${verb} the PR head`, "info");
+			return await handle("", ctx, onRouteResolved);
+		}
+		if (nextStep === "refresh") {
+			if (discovery.kind !== "current") throw new Error("/pr refresh failed: pull request is unavailable");
+			if (refreshes >= refreshAttempts) {
+				ctx.ui.notify(`PR #${discovery.pullRequest.number} mergeability is still being computed by GitHub; run /pr again`, "warning");
+				return "none";
+			}
+			await delay(refreshDelayMs, undefined, { signal: ctx.signal });
+			onRouteResolved?.assertCurrent();
+			return await handle("", ctx, onRouteResolved, undefined, refreshes + 1);
+		}
+		if (nextStep === "wait-ci") {
+			if (discovery.kind !== "current") throw new Error("/pr wait failed: pull request is unavailable");
+			const current = discovery.pullRequest;
+			const run = onRouteResolved?.run;
+			const interval = run?.consumeCiWait() ?? null;
+			if (interval === null) {
+				const budget = run?.policy.ciWaitMinutes ?? 0;
+				ctx.ui.notify(budget > 0
+					? `PR #${current.number} is still waiting for CI after ${budget} min; run /pr again later`
+					: `PR #${current.number} is waiting for CI`, "warning");
+				return "none";
+			}
+			if (ciWaits === 0) {
+				ctx.ui.notify(`PR #${current.number}: CI is running; checking every ${run!.policy.ciPollSeconds} s for up to ${run!.policy.ciWaitMinutes} min`, "info");
+			}
+			await delay(dependencies.ciPollMs ?? interval, undefined, { signal: ctx.signal });
+			onRouteResolved?.assertCurrent();
+			return await handle("", ctx, onRouteResolved, undefined, 0, ciWaits + 1);
+		}
 		if (nextStep === "merge") {
 			if (discovery.kind !== "current") throw new Error("/pr merge failed: pull request is unavailable");
-			await mergePullRequest(pi, ctx, discovery.pullRequest, load, needsFeedback);
+			await mergePullRequest(pi, ctx, discovery.pullRequest, load, needsFeedback, onRouteResolved?.run?.policy.mergeMethod);
 			return "merge";
 		}
 
 		if (!(nextStep in WORKFLOWS)) throw new Error(`/pr cannot dispatch route ${nextStep}`);
 		const route = nextStep as WorkflowNextStep;
-		if (onRouteResolved?.completedRoutes?.has(route)) {
+		if (onRouteResolved?.run?.hasCompleted(route, discovery.kind === "current" ? discovery.pullRequest.head.oid : null)) {
 			ctx.ui.notify(`PR ${route} already ran; inspect fresh state before retrying`, "warning");
 			return "none";
 		}