@henryqw/pi-pr 6.2.13 → 9.0.2

package/extensions/pr-publish-work.ts

@@ -1,11 +1,16 @@
+import type { PrRun } from "./pr-run.ts";
 import { spawnBounded, type Exec } from "@henryqw/pi-process";
 import { cloneCurrentPullRequest, loadCurrentPullRequest, readValidatedRemoteAuthority, samePullRequestSnapshot, type CurrentPullRequest } from "./pr-github.ts";
 import { extensionExecApi, inspectWorktree, inspectWorktreeState, isAncestor, parseNulPaths, parseStatusSnapshot, readHead, readRemoteOid, requiredText, runChecked, validatePaths, withWorktreeLock } from "./pr-execution.ts";
 
 type Check = { command: string; args: string[] };
-type Options = { cwd: string; authority: CurrentPullRequest; signal?: AbortSignal; agentDir?: string; exec?: Exec; loadCurrentPullRequest?: typeof loadCurrentPullRequest };
+type Options = { run?: PrRun; cwd: string; authority: CurrentPullRequest; signal?: AbortSignal; agentDir?: string; exec?: Exec; loadCurrentPullRequest?: typeof loadCurrentPullRequest };
 
-/** One local publication attempt. An uncertain push consumes the run, even when a later read recovers. */
+/**
+ * One local publication attempt. An uncertain push consumes the run, even when a later read recovers.
+ * A dirty branch that diverged from the PR head may inspect and commit; validation and publication
+ * still require a descendant HEAD, so the active /pr syncs the committed branch first.
+ */
 export class PullRequestWorkPublisher {
 	private readonly authority: CurrentPullRequest;
 	private readonly exec: Exec;
@@ -20,8 +25,8 @@ export class PullRequestWorkPublisher {
 		if (options.authority.lifecycle !== "open" || options.authority.target.provenance !== "configured") {
 			throw new Error("Local publication requires a configured open pull request");
 		}
-		if (options.authority.local.head === "behind" || options.authority.local.head === "diverged") {
-			throw new Error("Local publication requires a branch descended from the published PR head");
+		if (options.authority.local.head === "behind") {
+			throw new Error("Local publication requires a branch that is not behind the published PR head");
 		}
 		this.options = options;
 		this.authority = cloneCurrentPullRequest(options.authority);
@@ -49,24 +54,25 @@ export class PullRequestWorkPublisher {
 		if (branch !== this.authority.target.branch) throw new Error("Local publication cancelled: branch changed");
 	}
 
-	async inspect(): Promise<{ paths: string[]; head: string }> {
-		if (this.initialHead) throw new Error("Pending changes already inspected");
+	async inspect(): Promise<{ paths: string[]; head: string; originalHead: string; diverged: boolean }> {
+		if (this.consumed) throw new Error("Commit or publication run is consumed; inspect its outcome in a fresh /pr");
+		if (this.status !== undefined) throw new Error("Pending changes already inspected");
 		return await withWorktreeLock(this.options.cwd, async () => {
 			await this.authorityCheck();
 			if (await inspectWorktreeState(this.exec, this.execOptions()) === "operation") throw new Error("Git operation in progress");
 			const head = await readHead(this.exec, this.execOptions());
-			if (!(await isAncestor(this.exec, this.execOptions(), this.authority.head.oid, head))) {
-				throw new Error("Local HEAD is not a descendant of the published PR head");
-			}
+			const diverged = !(await isAncestor(this.exec, this.execOptions(), this.authority.head.oid, head));
 			const status = (await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.execOptions())).stdout;
 			const paths = validatePaths([...parseStatusSnapshot(status).keys()], "Pending paths");
+			// Clean divergence belongs to local sync; only pending work justifies committing on a diverged HEAD.
+			if (diverged && !paths.length) throw new Error("Local HEAD is not a descendant of the published PR head");
 			this.initialHead = head;
 			this.status = status;
-			return { paths, head };
+			return { paths, head, originalHead: this.authority.head.oid, diverged };
 		}, { agentDir: this.options.agentDir, signal: this.options.signal });
 	}
 
-	async commit(pathsInput: string[], message: string): Promise<{ head: string }> {
+	async commit(pathsInput: string[], message: string): Promise<{ head: string; diverged: boolean }> {
 		if (!this.initialHead || this.status === undefined || this.consumed) throw new Error("Pending changes must be inspected first");
 		const paths = validatePaths(pathsInput, "Commit paths");
 		if (!paths.length || paths.some((path) => !parseStatusSnapshot(this.status!).has(path))) {
@@ -86,12 +92,17 @@ export class PullRequestWorkPublisher {
 			this.consumed = true;
 			await runChecked(this.exec, "git", ["--literal-pathspecs", "add", "-A", "--", ...paths], this.execOptions());
 			await runChecked(this.exec, "git", ["commit", "-m", message], this.execOptions());
-			return { head: await readHead(this.exec, this.execOptions()) };
+			const head = await readHead(this.exec, this.execOptions());
+			this.initialHead = head;
+			this.status = undefined;
+			this.validatedHead = undefined;
+			this.consumed = false;
+			return { head, diverged: !(await isAncestor(this.exec, this.execOptions(), this.authority.head.oid, head)) };
 		}, { agentDir: this.options.agentDir, signal: this.options.signal });
 	}
 
 	async validate(checks: Check[]): Promise<{ head: string; checks: number }> {
-		if (!this.initialHead || this.validatedHead) throw new Error("Local publication validation is unavailable");
+		if (!this.initialHead || this.validatedHead || this.consumed) throw new Error("Local publication validation is unavailable");
 		return await withWorktreeLock(this.options.cwd, async () => {
 			await this.authorityCheck();
 			if (await inspectWorktree(this.exec, this.execOptions()) !== "clean") throw new Error("Unrelated pending changes remain; ask about ownership before publishing");
@@ -99,10 +110,16 @@ export class PullRequestWorkPublisher {
 			if (!(await isAncestor(this.exec, this.execOptions(), this.authority.head.oid, head))) {
 				throw new Error("Local HEAD is not a descendant of the published PR head");
 			}
-			await runChecked(this.exec, "git", ["diff", "--check", this.authority.head.oid, head], this.execOptions());
-			for (const check of checks) await runChecked(this.exec, check.command, check.args, this.execOptions());
-			if (await readHead(this.exec, this.execOptions()) !== head || await inspectWorktree(this.exec, this.execOptions()) !== "clean") {
-				throw new Error("Validation changed local HEAD or worktree");
+			this.options.run?.beginChecks("publish-work", head, checks);
+			try {
+				await runChecked(this.exec, "git", ["diff", "--check", this.authority.head.oid, head], this.execOptions());
+				for (const check of checks) await runChecked(this.exec, check.command, check.args, this.execOptions());
+				await this.authorityCheck();
+				if (await readHead(this.exec, this.execOptions()) !== head || await inspectWorktree(this.exec, this.execOptions()) !== "clean") throw new Error("Validation changed local HEAD or worktree");
+			} catch (error) {
+				this.status = undefined;
+				this.options.run?.checksFailed();
+				throw error;
 			}
 			this.validatedHead = head;
 			return { head, checks: checks.length + 1 };
@@ -120,6 +137,8 @@ export class PullRequestWorkPublisher {
 			}
 			const original = this.authority.head.oid;
 			if (head === original) return { kind: "published", head };
+			this.options.run?.beforePush(original, head);
+			this.consumed = true; // An uncertain push cannot reopen inspect, commit, or validation.
 			let error: unknown;
 			try {
 				await runChecked(this.exec, "git", ["push", "--porcelain", `--force-with-lease=refs/heads/${this.authority.target.ref}:${original}`,
@@ -129,7 +148,7 @@ export class PullRequestWorkPublisher {
 			let remote: string | null;
 			try { remote = await readRemoteOid(this.exec, this.execOptions(), this.authority.target.fetchSource, this.authority.target.ref); }
 			catch { throw new Error("Local publication outcome unknown; do not retry"); }
-			if (remote === head) return { kind: "published", head };
+			if (remote === head) { this.options.run?.observeRemote(head); return { kind: "published", head }; }
 			if (remote === original) throw new Error(`Local publication not applied${error ? `: ${String(error)}` : ""}`);
 			throw new Error("Local publication outcome unknown; do not retry");
 		}, { agentDir: this.options.agentDir, signal: this.options.signal });

package/extensions/pr-routing.ts

@@ -2,6 +2,8 @@ export type PullRequestLifecycle = "open" | "merged" | "closed";
 export type CiStatus = "none" | "running" | "success" | "failure" | "failure-blocked";
 export type ReviewReadiness = "ready" | "pending";
 type PolicyReadiness = "ready" | "pending";
+/** GitHub computes mergeability asynchronously; `pending` is transient, not a blocker. */
+type Mergeability = "known" | "pending";
 type LocalWorktree = "clean" | "dirty";
 type LocalHeadRelation = "equal" | "behind" | "ahead" | "diverged";
 
@@ -14,6 +16,7 @@ export type PullRequestConditions = {
 	ci: CiStatus;
 	review: ReviewReadiness;
 	policy: PolicyReadiness;
+	mergeability: Mergeability;
 };
 
 export type LocalMergeSafety = {
@@ -60,34 +63,29 @@ export type PullRequestDiscovery<T extends PullRequest = PullRequest> =
 	| { kind: "blocked"; issue: DiscoveryIssue }
 	| { kind: "inactive" };
 
-export type NextStep = "create" | "link-branch" | "blocked" | "none" | "publish-work" | "update-branch" | "sweep" | "fix-ci" | "merge";
-function localMutationSafe(local: LocalMergeSafety): boolean {
-	return local.worktree === "clean" && local.head === "equal";
-}
-
-function localMergeSafe(local: LocalMergeSafety): boolean {
-	return local.worktree === "clean" && (local.head === "equal" || local.head === "behind");
-}
+export type NextStep =
+	| "create" | "link-branch" | "blocked" | "none"
+	| "sync-local" | "publish-work" | "refresh" | "update-branch" | "sweep" | "fix-ci" | "wait-ci" | "merge";
 
+/**
+ * Priority ladder for an open pull request. Local state is normalized first
+ * (sync, then publish), so every later route sees a clean HEAD equal to the PR head.
+ */
 export function derivePullRequestNextStep(pullRequest: PullRequest): Exclude<NextStep, "create" | "link-branch" | "blocked"> {
 	const { lifecycle, conditions, local } = pullRequest;
 	if (lifecycle !== "open" || conditions.draft) return "none";
-	if (local.worktree === "dirty" && (local.head === "behind" || local.head === "diverged")) return "none";
+	if (local.head === "behind") return "sync-local";
+	// Dirty diverged work is committed by publish-work first; the committed branch then syncs.
+	if (local.head === "diverged") return local.worktree === "clean" ? "sync-local" : "publish-work";
 	if (local.worktree === "dirty" || local.head === "ahead") return "publish-work";
-	if (conditions.conflict) {
-		return localMutationSafe(local) ? "update-branch" : "none";
-	}
-	if (conditions.ci === "failure") return localMutationSafe(local) ? "fix-ci" : "none";
+	if (conditions.mergeability === "pending") return "refresh";
+	if (conditions.conflict || conditions.baseUpdateRequired) return "update-branch";
+	if (conditions.ci === "failure") return "fix-ci";
 	if (conditions.ci === "failure-blocked") return "none";
-	if (conditions.changesRequested || conditions.unresolvedThreads > 0) {
-		return localMutationSafe(local) ? "sweep" : "none";
-	}
-	if (
-		conditions.review === "pending" ||
-		conditions.policy === "pending" ||
-		!localMergeSafe(local) ||
-		conditions.ci === "running"
-	) return "none";
+	if (conditions.changesRequested || conditions.unresolvedThreads > 0) return "sweep";
+	// Running checks usually leave merge policy BLOCKED, so the wait decision comes before the policy gate.
+	if (conditions.ci === "running") return conditions.review === "pending" ? "none" : "wait-ci";
+	if (conditions.review === "pending" || conditions.policy === "pending") return "none";
 	return "merge";
 }
 

package/extensions/pr-run.ts

@@ -0,0 +1,107 @@
+import { isDeepStrictEqual } from "node:util";
+import { createConfigStore } from "@henryqw/pi-config-store";
+import { isRecord } from "./pr-execution.ts";
+
+export type PrCheck = { command: string; args: string[] };
+export type MergeMethod = "squash" | "merge" | "rebase";
+export const MERGE_METHODS: readonly MergeMethod[] = ["squash", "merge", "rebase"];
+export type PrPolicy = { maxPublicationCycles: number; maxRepairAttempts: number; ciPollSeconds: number; ciWaitMinutes: number; mergeMethod: MergeMethod };
+export const DEFAULT_PR_POLICY: PrPolicy = { maxPublicationCycles: 3, maxRepairAttempts: 3, ciPollSeconds: 30, ciWaitMinutes: 10, mergeMethod: "squash" };
+type NumericPolicyKey = Exclude<keyof PrPolicy, "mergeMethod">;
+const NUMERIC_KEYS: readonly NumericPolicyKey[] = ["maxPublicationCycles", "maxRepairAttempts", "ciPollSeconds", "ciWaitMinutes"];
+/** `ciWaitMinutes: 0` disables waiting for running CI; every other limit must be positive. */
+const ZERO_ALLOWED: ReadonlySet<NumericPolicyKey> = new Set(["ciWaitMinutes"]);
+/** Node replaces a timer delay above 2^31-1 ms with 1 ms, which would turn a long poll into a tight loop. */
+const MAX_CI_POLL_SECONDS = 2_147_483;
+
+export function loadPrPolicy(agentDir?: string): PrPolicy {
+	const config = createConfigStore({
+		extensionId: "pi-pr", agentDir, defaults: () => ({ ...DEFAULT_PR_POLICY }),
+		parse(value: unknown): PrPolicy {
+			if (!isRecord(value) || Object.keys(value).some((key) => !Object.hasOwn(DEFAULT_PR_POLICY, key))) throw new Error(`Expected only ${Object.keys(DEFAULT_PR_POLICY).join(", ")}`);
+			const policy = { ...DEFAULT_PR_POLICY };
+			if (value.mergeMethod !== undefined) {
+				if (!MERGE_METHODS.includes(value.mergeMethod as MergeMethod)) throw new Error(`mergeMethod must be one of ${MERGE_METHODS.join(", ")}`);
+				policy.mergeMethod = value.mergeMethod as MergeMethod;
+			}
+			for (const key of NUMERIC_KEYS) {
+				if (value[key] !== undefined) {
+					const minimum = ZERO_ALLOWED.has(key) ? 0 : 1;
+					if (!Number.isSafeInteger(value[key]) || (value[key] as number) < minimum) throw new Error(`${key} must be an integer of at least ${minimum}`);
+					if (key === "ciPollSeconds" && (value[key] as number) > MAX_CI_POLL_SECONDS) throw new Error(`ciPollSeconds must be at most ${MAX_CI_POLL_SECONDS}`);
+					policy[key] = value[key] as number;
+				}
+			}
+			return policy;
+		},
+	});
+	try { return config.loadSync().value; }
+	catch (error) { throw new Error(`PR configuration is preserved at ${config.path}: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+/** One explicit /pr invocation; helper resumes never replenish these limits. */
+export class PrRun {
+	private readonly completed = new Map<string, Set<string | null>>();
+	private readonly checks = new Map<string, PrCheck[]>();
+	private readonly executed = new Map<string, PrCheck[][]>();
+	private lastRemote: string | null | undefined;
+	private publications = 0;
+	private repairs = 0;
+	private ciWaitedMs = 0;
+
+	readonly policy: PrPolicy;
+
+	constructor(policy: Partial<PrPolicy> = {}) {
+		this.policy = { ...DEFAULT_PR_POLICY, ...policy };
+	}
+
+	/** Reserve one CI poll interval from the invocation's wait budget; null once the budget is spent. */
+	consumeCiWait(): number | null {
+		const remaining = this.policy.ciWaitMinutes * 60_000 - this.ciWaitedMs;
+		if (remaining <= 0) return null;
+		const interval = Math.min(this.policy.ciPollSeconds * 1_000, remaining);
+		this.ciWaitedMs += interval;
+		return interval;
+	}
+
+	observeRemote(head: string | null): void {
+		if (this.lastRemote !== undefined && this.lastRemote !== head) this.publications += 1;
+		this.lastRemote = head;
+	}
+
+	beforePush(original: string | null, head: string): void {
+		this.observeRemote(original);
+		if (original !== head && this.publications >= this.policy.maxPublicationCycles) throw new Error(`Publication budget stop: limit ${this.policy.maxPublicationCycles} reached; run /pr again`);
+	}
+
+	complete(route: string, entryHead: string | null): void {
+		const heads = this.completed.get(route) ?? new Set<string | null>();
+		heads.add(entryHead);
+		this.completed.set(route, heads);
+	}
+
+	hasCompleted(route: string, head: string | null): boolean {
+		return this.completed.get(route)?.has(head) ?? false;
+	}
+
+	requireFreshChecks(route: string, head: string, checks: PrCheck[]): void {
+		if (this.repairs >= this.policy.maxRepairAttempts) throw new Error(`Repair budget stop: limit ${this.policy.maxRepairAttempts} reached; run /pr again`);
+		const frozen = this.checks.get(route);
+		if (frozen && !isDeepStrictEqual(frozen, checks)) throw new Error("Validation checks are frozen for this /pr; failing checks cannot be dropped");
+		if (this.hasExecuted(head, checks)) throw new Error("No progress: checks already executed on this HEAD in this /pr; repair the code or run /pr again");
+	}
+
+	beginChecks(route: string, head: string, checks: PrCheck[]): void {
+		this.requireFreshChecks(route, head, checks);
+		this.checks.set(route, structuredClone(checks));
+		const sets = this.executed.get(head) ?? [];
+		sets.push(structuredClone(checks));
+		this.executed.set(head, sets);
+	}
+
+	hasExecuted(head: string, checks: PrCheck[]): boolean {
+		return this.executed.get(head)?.some((set) => isDeepStrictEqual(set, checks)) ?? false;
+	}
+
+	checksFailed(): void { this.repairs += 1; }
+}

package/extensions/pr-sync.ts

@@ -0,0 +1,92 @@
+import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
+import { cloneCurrentPullRequest, loadCurrentPullRequest, samePullRequestSnapshot, type CurrentPullRequest } from "./pr-github.ts";
+import {
+	extensionExecApi,
+	inspectWorktreeState,
+	isAncestor,
+	parseSingleOutputLine,
+	readHead,
+	requiredOid,
+	runChecked,
+	withWorktreeLock,
+} from "./pr-execution.ts";
+
+export type SyncLocalHeadOptions = {
+	cwd: string;
+	authority: CurrentPullRequest;
+	signal?: AbortSignal;
+	agentDir?: string;
+	exec?: Exec;
+	loadCurrentPullRequest?: typeof loadCurrentPullRequest;
+};
+
+export type SyncLocalHeadResult = { kind: "fast-forwarded" | "rebased" | "unchanged"; head: string };
+
+/**
+ * Bring the local branch up to the published PR head without pushing.
+ * Behind: fast-forward (Git refuses when local changes overlap). Diverged and
+ * clean: rebase local commits onto the PR head; a conflict aborts back to the
+ * original HEAD. Never stashes, resets, or rewrites the remote.
+ */
+export async function syncLocalHead(options: SyncLocalHeadOptions): Promise<SyncLocalHeadResult> {
+	const authority = cloneCurrentPullRequest(options.authority);
+	if (authority.lifecycle !== "open" || authority.target.provenance !== "configured") {
+		throw new Error("Local sync requires a configured open pull request");
+	}
+	const exec = options.exec ?? spawnBounded;
+	const load = options.loadCurrentPullRequest ?? loadCurrentPullRequest;
+	const execOptions: ExecOptions = { cwd: options.cwd, signal: options.signal };
+	const target = authority.head.oid;
+	return await withWorktreeLock(options.cwd, async () => {
+		const discovery = await load(extensionExecApi(exec, options.cwd, options.signal), { cwd: options.cwd, signal: options.signal });
+		if (discovery.kind !== "current" || !samePullRequestSnapshot(authority, discovery.pullRequest)) {
+			throw new Error("Local sync cancelled: PR identity or remote head changed");
+		}
+		const assertLocalContext = async (expectedHead?: string): Promise<string> => {
+			const branch = parseSingleOutputLine((await runChecked(exec, "git", ["branch", "--show-current"], execOptions)).stdout, "current branch");
+			if (branch !== authority.target.branch) throw new Error("Local sync cancelled: current branch changed");
+			const head = await readHead(exec, execOptions);
+			if (expectedHead !== undefined && head !== expectedHead) throw new Error("Local sync cancelled: local HEAD moved during the fetch");
+			return head;
+		};
+		const head = await assertLocalContext();
+		if (await inspectWorktreeState(exec, execOptions) === "operation") throw new Error("Local sync cancelled: a Git operation is in progress");
+		await runChecked(exec, "git", [
+			"fetch", "--no-write-fetch-head", "--no-tags", "--no-recurse-submodules", authority.headFetchSource, target,
+		], execOptions);
+		await runChecked(exec, "git", ["cat-file", "-e", `${target}^{commit}`], execOptions);
+		// The fetch is the only slow step; branch, HEAD, and worktree are re-read right before any mutation.
+		await assertLocalContext(head);
+		const worktree = await inspectWorktreeState(exec, execOptions);
+		if (worktree === "operation") throw new Error("Local sync cancelled: a Git operation is in progress");
+		if (head === target || await isAncestor(exec, execOptions, target, head)) return { kind: "unchanged", head };
+		if (await isAncestor(exec, execOptions, head, target)) {
+			const merge = await exec("git", ["merge", "--ff-only", "--no-autostash", target], execOptions);
+			if (merge.killed) throw new Error("git merge --ff-only was killed; its outcome is unknown");
+			if (merge.code !== 0) {
+				throw new Error(`Local changes overlap the PR head update; commit or move them, then run /pr: ${merge.stderr.trim() || merge.stdout.trim()}`);
+			}
+			return { kind: "fast-forwarded", head: await verifySynced(exec, execOptions, target) };
+		}
+		if (worktree !== "clean") throw new Error("Local sync cancelled: diverged local commits need a clean worktree");
+		const mergeBase = requiredOid(parseSingleOutputLine((await runChecked(exec, "git", ["merge-base", target, head], execOptions)).stdout, "sync fork point"), "sync fork point");
+		const mergeCommits = (await runChecked(exec, "git", ["rev-list", "--max-count=1", "--min-parents=2", `${mergeBase}..${head}`], execOptions)).stdout.trim();
+		if (mergeCommits) throw new Error("Local sync cannot rebase local merge commits onto the PR head; rebase manually");
+		const rebase = await exec("git", ["-c", "core.editor=true", "-c", "rebase.updateRefs=false", "rebase", "--no-autostash", target], execOptions);
+		if (rebase.killed) throw new Error("git rebase was killed; its outcome is unknown");
+		if (rebase.code !== 0) {
+			await runChecked(exec, "git", ["rebase", "--abort"], execOptions);
+			if (await readHead(exec, execOptions) !== head) throw new Error("Local sync aborted a conflicting rebase but HEAD did not return to the original commit");
+			throw new Error(`Local commits conflict with the PR head; rebase manually: ${rebase.stderr.trim() || rebase.stdout.trim()}`);
+		}
+		return { kind: "rebased", head: await verifySynced(exec, execOptions, target) };
+	}, { agentDir: options.agentDir, signal: options.signal });
+}
+
+async function verifySynced(exec: Exec, execOptions: ExecOptions, target: string): Promise<string> {
+	const head = await readHead(exec, execOptions);
+	if (!(await isAncestor(exec, execOptions, target, head)) || await inspectWorktreeState(exec, execOptions) === "operation") {
+		throw new Error("Local sync did not leave a branch descended from the PR head");
+	}
+	return head;
+}

package/extensions/pr-ui.ts

@@ -87,6 +87,8 @@ function footerStatus(input: PrDisplayInput): Pick<PrFooter, "text" | "color"> {
 	if (conditions.unresolvedThreads > 0) return { text: `${conditions.unresolvedThreads} unresolved`, color: "warning" };
 	if (conditions.changesRequested) return { text: "changes requested", color: "error" };
 	if (conditions.ci === "running") return { text: "CI running", color: "warning" };
+	if (conditions.mergeability === "pending") return { text: "mergeability pending", color: "warning" };
+	if (input.local.head === "behind" || input.local.head === "diverged") return { text: `local ${input.local.head}`, color: "warning" };
 	if (derivePullRequestNextStep(input) === "merge") return { text: "merge-ready", color: "success" };
 	if (input.approved) return { text: "approved", color: "success" };
 	return { text: "open", color: "accent" };
@@ -94,14 +96,20 @@ function footerStatus(input: PrDisplayInput): Pick<PrFooter, "text" | "color"> {
 
 function widgetText(nextStep: NextStep): string | undefined {
 	switch (nextStep) {
+		case "sync-local":
+			return "Run /pr to sync the local branch with the PR head";
 		case "publish-work":
 			return "Run /pr to publish local work";
+		case "refresh":
+			return "Run /pr to re-read GitHub mergeability";
 		case "update-branch":
-			return "Run /pr to resolve merge conflict";
+			return "Run /pr to update the branch";
 		case "sweep":
 			return "Run /pr to address review feedback";
 		case "fix-ci":
 			return "Run /pr to fix CI";
+		case "wait-ci":
+			return "Run /pr to wait for CI, then continue";
 		case "merge":
 			return "Run /pr to merge pull request";
 		case "link-branch":

package/extensions/pr-update-branch.ts

@@ -1,3 +1,4 @@
+import type { PrRun } from "./pr-run.ts";
 import { readFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { join, resolve } from "node:path";
@@ -39,11 +40,22 @@ type UpdateBranchState = {
 type UpdateBranchResult =
 	| { kind: "verified"; head: string; fastForward: boolean }
 	| { kind: "conflict"; paths: string[] }
-	| { kind: "published"; head: string };
+	| { kind: "published"; head: string }
+	| { kind: "stale"; reason: string; authority: CurrentPullRequest };
+
+// Only pre-mutation preflight can authorize a fresh routing snapshot, never a replay.
+class StaleRebaseRoute extends Error {
+	readonly authority: CurrentPullRequest;
+	constructor(reason: string, authority: CurrentPullRequest) {
+		super(reason);
+		this.authority = authority;
+	}
+}
 
 type Load = typeof loadCurrentPullRequest;
 
 export type UpdateBranchOptions = {
+	run?: PrRun;
 	cwd: string;
 	authority: CurrentPullRequest;
 	signal?: AbortSignal;
@@ -54,7 +66,7 @@ export type UpdateBranchOptions = {
 
 function sameAuthority(frozen: CurrentPullRequest, fresh: CurrentPullRequest): boolean {
 	return samePullRequestSnapshot(frozen, fresh) && frozen.base.oid === fresh.base.oid &&
-		fresh.lifecycle === "open" && fresh.conditions.conflict;
+		fresh.lifecycle === "open" && (fresh.conditions.conflict || fresh.conditions.baseUpdateRequired);
 }
 
 type RebaseRecovery = { version: 1; phase: "pending" | "verified" | "published"; identity: string;
@@ -112,6 +124,7 @@ export async function inspectVerifiedRebaseRecovery(pr: CurrentPullRequest, opti
 export class PullRequestBranchUpdater {
 	readonly state: UpdateBranchState = { phase: "ready" };
 
+	private readonly run?: PrRun;
 	private readonly cwd: string;
 	private readonly authority: CurrentPullRequest;
 	private readonly signal?: AbortSignal;
@@ -126,6 +139,7 @@ export class PullRequestBranchUpdater {
 			throw new TypeError("Branch update requires a configured open pull request");
 		}
 		this.cwd = options.cwd;
+		this.run = options.run;
 		this.authority = cloneCurrentPullRequest(options.authority);
 		this.signal = options.signal;
 		this.agentDir = options.agentDir;
@@ -145,18 +159,18 @@ export class PullRequestBranchUpdater {
 		return { cwd: this.cwd, signal: this.signal };
 	}
 
-	private async freshAuthority(expectedHead: string, requireClean: boolean, published = false): Promise<CurrentPullRequest> {
+	private async freshAuthority(expectedHead: string, requireClean: boolean, published = false, beforeRebase = false): Promise<CurrentPullRequest> {
 		const discovery = await this.load(this.pi(), this.context());
-		const comparison = published ? {
+		if (discovery.kind !== "current") throw new Error("Branch update cancelled: pull request is no longer current");
+		const fresh = discovery.pullRequest;
+		const comparison = beforeRebase || published ? {
 			...this.authority,
-			head: { ...this.authority.head, oid: expectedHead },
-			target: { ...this.authority.target, remoteOid: expectedHead },
+			head: { ...this.authority.head, oid: beforeRebase ? fresh.head.oid : expectedHead },
+			target: { ...this.authority.target, remoteOid: beforeRebase ? fresh.target.remoteOid : expectedHead },
 		} : this.authority;
-		if (discovery.kind !== "current" || (published
-			? !samePullRequestSnapshot(comparison, discovery.pullRequest) ||
-				this.authority.base.oid !== discovery.pullRequest.base.oid || discovery.pullRequest.lifecycle !== "open"
-			: !sameAuthority(this.authority, discovery.pullRequest))) {
-			throw new Error("Branch update cancelled: frozen pull request authority changed");
+		if (!samePullRequestSnapshot(comparison, fresh) || fresh.lifecycle !== "open" ||
+			(!beforeRebase && (this.authority.base.oid !== fresh.base.oid || !published && !(fresh.conditions.conflict || fresh.conditions.baseUpdateRequired)))) {
+			throw new Error("Branch update cancelled: frozen pull request authority changed (identity, lifecycle, destination, or post-rebase authority)");
 		}
 		const branch = parseSingleOutputLine((await runChecked(this.exec, "git", ["branch", "--show-current"], this.execOptions())).stdout, "current branch");
 		if (branch !== this.authority.target.branch) throw new Error("Branch update cancelled: current branch changed");
@@ -164,8 +178,39 @@ export class PullRequestBranchUpdater {
 			throw new Error("Branch update cancelled: worktree is dirty or a Git operation is in progress");
 		}
 		const head = await readHead(this.exec, this.execOptions());
-		if (head !== expectedHead) throw new Error("Branch update cancelled: local HEAD changed");
-		return discovery.pullRequest;
+		const reasons: string[] = [];
+		if (beforeRebase) {
+			if (fresh.target.remoteOid !== this.authority.target.remoteOid || fresh.head.oid !== expectedHead) {
+				if (this.authority.target.remoteOid !== expectedHead || fresh.target.remoteOid !== fresh.head.oid ||
+					head !== fresh.head.oid || !(await isAncestor(this.exec, this.execOptions(), expectedHead, head))) {
+					throw new Error("Branch update cancelled: frozen pull request authority changed; head/remote drift is not a clean, already-published fast-forward");
+				}
+				reasons.push("Published PR head advanced by fast-forward");
+			} else if (head !== expectedHead && await isAncestor(this.exec, this.execOptions(), expectedHead, head)) {
+				reasons.push("Local HEAD is ahead of the frozen PR head");
+			} else if (head !== expectedHead) {
+				throw new Error("Branch update cancelled: local HEAD does not match the expected head");
+			}
+			if (fresh.base.oid !== this.authority.base.oid) reasons.push("Base OID changed");
+			if (!fresh.conditions.conflict && !fresh.conditions.baseUpdateRequired) {
+				reasons.push(this.authority.conditions.conflict ? "PR conflict cleared" : "Required base update cleared");
+			}
+		} else if (head !== expectedHead) {
+			throw new Error("Branch update cancelled: local HEAD does not match the expected head");
+		}
+		if (reasons.length) {
+			if (fresh.target.remoteOid !== fresh.head.oid) {
+				throw new Error("Branch update cancelled: PR head and remote lease disagree");
+			}
+			const path = recoveryPath(this.cwd, this.authority, this.agentDir);
+			const recovery = await readRecovery(path, this.signal);
+			if (recovery && recovery.phase !== "published") {
+				throw new Error(`Branch update recovery requires reconciliation; record preserved at ${path}; do not replan or replay`);
+			}
+			this.signal?.throwIfAborted();
+			throw new StaleRebaseRoute(`${reasons.join("; ")}; cancelled before rebase or publication`, cloneCurrentPullRequest(fresh));
+		}
+		return fresh;
 	}
 
 	private async writeRecovery(phase: RebaseRecovery["phase"], verified: string | null): Promise<void> {
@@ -234,7 +279,7 @@ export class PullRequestBranchUpdater {
 		}
 		if (this.state.phase !== "ready") throw new Error("Branch conflict rebase action was already consumed");
 		return await withWorktreeLock(this.cwd, async () => {
-			await this.freshAuthority(this.authority.head.oid, true);
+			await this.freshAuthority(this.authority.head.oid, true, false, true);
 			const source = await resolveRepositoryFetchSource(this.exec, this.execOptions(), {
 				host: this.authority.host,
 				repository: this.authority.base.repository,
@@ -244,7 +289,7 @@ export class PullRequestBranchUpdater {
 				"fetch", "--no-write-fetch-head", "--no-tags", "--no-recurse-submodules", source, this.authority.base.oid,
 			], this.execOptions());
 			await runChecked(this.exec, "git", ["cat-file", "-e", `${this.authority.base.oid}^{commit}`], this.execOptions());
-			await this.freshAuthority(this.authority.head.oid, true);
+			await this.freshAuthority(this.authority.head.oid, true, false, true);
 			if (await isAncestor(this.exec, this.execOptions(), this.authority.base.oid, this.authority.head.oid)) {
 				return await this.verifyRebase();
 			}
@@ -255,7 +300,7 @@ export class PullRequestBranchUpdater {
 				"rev-list", "--max-count=1", "--min-parents=2", `${mergeBase}..${this.authority.head.oid}`,
 			], this.execOptions())).stdout.trim();
 			if (mergeCommits) throw new Error("Branch update cannot rebase a branch with merge commits; preserve its resolutions manually");
-			await this.freshAuthority(this.authority.head.oid, true);
+			await this.freshAuthority(this.authority.head.oid, true, false, true);
 			await this.writeRecovery("pending", null);
 			const result = await this.exec("git", ["-c", "core.editor=true", "-c", "rebase.backend=merge", "-c", "rebase.updateRefs=false", "rebase", "--no-autostash", "--onto", this.authority.base.oid, mergeBase], this.execOptions());
 			if (result.killed) throw new Error("git rebase was killed; its outcome is unknown");
@@ -265,7 +310,12 @@ export class PullRequestBranchUpdater {
 			} catch (error) {
 				throw new Error(`git rebase failed: ${result.stderr.trim() || result.stdout.trim() || `exit code ${result.code}`}; ${error instanceof Error ? error.message : String(error)}`);
 			}
-		}, { agentDir: this.agentDir, signal: this.signal });
+		}, { agentDir: this.agentDir, signal: this.signal }).catch((error: unknown) => {
+			if (!(error instanceof StaleRebaseRoute)) throw error;
+			this.signal?.throwIfAborted();
+			this.state.phase = "blocked";
+			return { kind: "stale" as const, reason: error.message, authority: error.authority };
+		});
 	}
 
 	async continue(resolvedPaths: readonly string[]): Promise<UpdateBranchResult> {
@@ -277,17 +327,25 @@ export class PullRequestBranchUpdater {
 			throw new Error("Resolved paths must include every original conflict path");
 		}
 		return await withWorktreeLock(this.cwd, async () => {
-			const discovery = await this.load(this.pi(), this.context());
+			const assertContext = async () => {
+				const path = parseSingleOutputLine((await runChecked(this.exec, "git", ["rev-parse", "--git-path", "rebase-merge/head-name"], this.execOptions())).stdout, "rebase branch marker");
+				const marker = await readFile(resolve(this.cwd, path), "utf8").catch((error) => {
+					if (error.code === "ENOENT") throw new Error("Branch rebase context changed", { cause: error });
+					throw error;
+				});
+				if (marker.trim() !== `refs/heads/${this.authority.target.branch}` ||
+					await readHead(this.exec, this.execOptions()) !== this.state.conflict!.head) {
+					throw new Error("Branch rebase context changed");
+				}
+			};
+			await assertContext();
+			const discovery = await this.load(this.pi(), { ...this.context(), rebaseBranch: this.authority.target.branch });
 			if (discovery.kind !== "current" || !sameAuthority(this.authority, discovery.pullRequest)) {
 				throw new Error("Branch rebase authority changed");
 			}
-			const path = parseSingleOutputLine((await runChecked(this.exec, "git", ["rev-parse", "--git-path", "rebase-merge/head-name"], this.execOptions())).stdout, "rebase branch marker");
-			if ((await readFile(resolve(this.cwd, path), "utf8")).trim() !== `refs/heads/${this.authority.target.branch}` ||
-				await readHead(this.exec, this.execOptions()) !== this.state.conflict!.head) {
-				throw new Error("Branch rebase context changed");
-			}
 			const status = await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.execOptions());
 			assertOnlyDeclaredStatusChanged(this.state.conflict!.statusBaseline, status.stdout, paths);
+			await assertContext();
 			this.state.phase = "blocked";
 			await runChecked(this.exec, "git", ["--literal-pathspecs", "add", "--", ...paths], this.execOptions());
 			const unmerged = parseNulPaths((await runChecked(this.exec, "git", ["diff", "--name-only", "-z", "--diff-filter=U"], this.execOptions())).stdout, "Unmerged paths");
@@ -314,11 +372,13 @@ export class PullRequestBranchUpdater {
 				throw new Error("Verified branch no longer contains the frozen base");
 			}
 			if (remoteBefore === head) {
+				this.run?.observeRemote(head);
 				await this.writeRecovery("published", head);
 				this.state.phase = "published";
 				return { kind: "published", head };
 			}
 			await this.freshAuthority(head, true);
+			this.run?.beforePush(original, head);
 			this.state.phase = "blocked";
 			let pushError: unknown;
 			try {
@@ -337,6 +397,7 @@ export class PullRequestBranchUpdater {
 				throw new Error("Rebase push outcome is unknown; do not retry");
 			}
 			if (remote === head) {
+				this.run?.observeRemote(head);
 				await this.writeRecovery("published", head);
 				this.state.phase = "published";
 				return { kind: "published", head };