@henryqw/pi-pr 6.0.7 → 6.2.0

package/extensions/pr-create.ts

@@ -20,19 +20,20 @@ import {
 	type PullRequestTarget,
 } from "./pr-routing.ts";
 import {
-	assertOnlyDeclaredStatusChanged,
 	extensionExecApi,
 	inspectWorktree,
+	inspectWorktreeState,
+	parseNulPaths,
+	parseStatusSnapshot,
+	validateResolvedConflictPaths,
 	isAncestor,
 	isRecord,
-	parseNulPaths,
 	parseSingleOutputLine,
 	readHead,
 	readRemoteOid,
 	requiredOid,
 	requiredText,
 	runChecked,
-	validateResolvedConflictPaths,
 	withWorktreeLock,
 } from "./pr-execution.ts";
 
@@ -51,7 +52,7 @@ type CreateBaseAuthority = {
 	fetchSource: string;
 };
 
-type CreatePhase = "unprepared" | "prepared" | "conflict-awaiting-user" | "verified" | "pushed" | "published" | "blocked";
+type CreatePhase = "unprepared" | "prepared" | "verified" | "pushed" | "published" | "blocked";
 
 type CrossRepositoryCreateAuthority = {
 	baseRepositoryId: string;
@@ -63,14 +64,14 @@ type CreatePullRequestState = {
 	phase: CreatePhase;
 	base?: CreateBaseAuthority;
 	createAuthority?: CrossRepositoryCreateAuthority;
+	pending?: { head: string; status: string };
 	publicationHead?: string;
-	conflict?: { paths: string[]; statusBaseline: string; originalHead: string };
+	verifiedHead?: string;
 };
 
 type CreatePullRequestResult =
 	| { kind: "prepared"; base: CreateBaseAuthority; mergeBase: string }
 	| { kind: "verified"; head: string; fastForward: boolean }
-	| { kind: "conflict"; paths: string[] }
 	| { kind: "pushed"; head: string }
 	| { kind: "published"; url: string };
 
@@ -170,7 +171,6 @@ export class PullRequestCreator {
 	private readonly agentDir?: string;
 	private readonly exec: Exec;
 	private readonly load: Load;
-	private explicitBase?: string;
 
 	constructor(options: CreatePullRequestOptions) {
 		if (options.target.remoteOid !== null) requiredOid(options.target.remoteOid, "remote OID");
@@ -196,7 +196,7 @@ export class PullRequestCreator {
 	}
 
 	private async freshNone() {
-		const discovery = await this.load(this.pi(), this.context(), undefined, undefined, this.explicitBase);
+		const discovery = await this.load(this.pi(), this.context());
 		if (discovery.kind !== "none" || !sameTarget(this.target, discovery.creationTarget)) {
 			throw new Error("PR creation cancelled: fresh complete discovery is no longer none");
 		}
@@ -232,18 +232,16 @@ export class PullRequestCreator {
 		return await readHead(this.exec, this.options());
 	}
 
-	async prepare(explicitBase?: string): Promise<CreatePullRequestResult> {
+	async prepare(): Promise<CreatePullRequestResult> {
 		if (this.state.phase !== "unprepared") {
 			throw new Error("PR creation prepare action was already consumed");
 		}
 		return await withWorktreeLock(this.cwd, async () => {
-			this.explicitBase = explicitBase;
 			await this.freshNone();
 			const preflight = await preflightPullRequestCreation(
 				this.pi(),
 				this.context(),
 				this.target,
-				this.explicitBase,
 			);
 			if (preflight.worktree === "operation") {
 				throw new Error("PR creation cannot prepare while a Git operation is in progress");
@@ -277,83 +275,57 @@ export class PullRequestCreator {
 		}, { agentDir: this.agentDir, signal: this.signal });
 	}
 
-	private async verifyMerge(originalHead: string): Promise<{ head: string; fastForward: boolean }> {
-		const base = this.state.base!;
-		const head = await readHead(this.exec, this.options());
-		const commits = parseSingleOutputLine((await runChecked(this.exec, "git", ["rev-list", "--parents", "-n", "1", head], this.options())).stdout, "merge parents")
-			.split(" ").map((value, index) => requiredOid(value, index ? "merge parent" : "merged HEAD"));
-		if (commits[0] !== head) throw new Error("PR creation merge verification returned a different HEAD");
-		let fastForward = false;
-		if (head === base.oid && commits.length >= 2 && await isAncestor(this.exec, this.options(), originalHead, head)) fastForward = true;
-		else if (commits.length !== 3 || commits[1] !== originalHead || commits[2] !== base.oid) {
-			throw new Error("PR creation did not produce the exact configured fast-forward or two-parent merge");
-		}
-		await this.requireCleanHead();
-		this.state.phase = "verified";
-		delete this.state.conflict;
-		return { head, fastForward };
-	}
-
-	private async captureConflict(originalHead: string): Promise<string[]> {
-		const base = this.state.base!;
-		const mergeHead = requiredOid(parseSingleOutputLine((await runChecked(this.exec, "git", ["rev-parse", "--verify", "MERGE_HEAD^{commit}"], this.options())).stdout, "MERGE_HEAD"), "MERGE_HEAD");
-		if (mergeHead !== base.oid) throw new Error("Failed merge did not retain the frozen base");
-		const paths = parseNulPaths((await runChecked(this.exec, "git", ["diff", "--name-only", "-z", "--diff-filter=U"], this.options())).stdout, "Unmerged paths");
-		if (!paths.length) throw new Error("git merge failed without bounded unmerged paths");
-		const status = await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.options());
-		this.state.phase = "conflict-awaiting-user";
-		this.state.conflict = { paths, statusBaseline: status.stdout, originalHead };
-		return paths;
+	async inspect(): Promise<{ paths: string[]; head: string }> {
+		if (this.state.phase !== "prepared") throw new Error("PR creation must be prepared before inspecting pending work");
+		return await withWorktreeLock(this.cwd, async () => {
+			await this.freshNone();
+			if (await inspectWorktreeState(this.exec, this.options()) === "operation") throw new Error("Git operation in progress");
+			const head = await readHead(this.exec, this.options());
+			const status = (await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.options())).stdout;
+			const paths = [...parseStatusSnapshot(status).keys()];
+			parseNulPaths(paths.map((path) => `${path}\0`).join(""), "Pending paths");
+			this.state.pending = { head, status };
+			return { paths, head };
+		}, { agentDir: this.agentDir, signal: this.signal });
 	}
 
-	async merge(): Promise<CreatePullRequestResult> {
-		if (this.state.phase !== "prepared" || !this.state.base) {
-			throw new Error("PR creation is not prepared for merge");
+	async commit(pathsInput: string[], message: string): Promise<{ head: string }> {
+		if (this.state.phase !== "prepared" || !this.state.pending) throw new Error("PR creation has no inspected pending work");
+		const paths = validateResolvedConflictPaths(pathsInput, []);
+		if (!paths.length || paths.some((path) => !parseStatusSnapshot(this.state.pending!.status).has(path))) {
+			throw new Error("Commit paths must be reviewed pending paths");
 		}
+		requiredText(message, "commit message");
 		return await withWorktreeLock(this.cwd, async () => {
 			await this.freshNone();
-			if (await this.liveBase() !== this.state.base!.oid) throw new Error("PR creation cancelled: frozen base moved");
-			const originalHead = await this.requireCleanHead();
-			if (await isAncestor(this.exec, this.options(), this.state.base!.oid, originalHead)) {
-				this.state.phase = "verified";
-				return { kind: "verified", head: originalHead, fastForward: false };
-			}
-			this.state.phase = "blocked";
-			const result = await this.exec("git", ["merge", "--no-edit", this.state.base!.oid], this.options());
-			if (result.killed) throw new Error("git merge was killed; its outcome is unknown");
-			if (result.code === 0) {
-				const verified = await this.verifyMerge(originalHead);
-				return { kind: "verified", ...verified };
-			}
-			try {
-				const paths = await this.captureConflict(originalHead);
-				return { kind: "conflict", paths };
-			} catch (error) {
-				throw new Error(`git merge failed: ${result.stderr.trim() || result.stdout.trim() || `exit code ${result.code}`}; ${error instanceof Error ? error.message : String(error)}`);
+			if (await readHead(this.exec, this.options()) !== this.state.pending!.head ||
+				await inspectWorktreeState(this.exec, this.options()) === "operation" ||
+				(await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.options())).stdout !== this.state.pending!.status) {
+				throw new Error("Pending work changed after inspection");
 			}
+			const staged = parseNulPaths((await runChecked(this.exec, "git", ["diff", "--cached", "--no-renames", "--name-only", "-z"], this.options())).stdout, "Staged paths");
+			if (staged.some((path) => !paths.includes(path))) throw new Error("Unrelated staged changes require an ownership decision");
+			this.state.pending = undefined; // Commit outcome may be uncertain; never replay it.
+			await runChecked(this.exec, "git", ["--literal-pathspecs", "add", "-A", "--", ...paths], this.options());
+			await runChecked(this.exec, "git", ["commit", "-m", message], this.options());
+			return { head: await readHead(this.exec, this.options()) };
 		}, { agentDir: this.agentDir, signal: this.signal });
 	}
 
-	async continue(pathsInput: readonly string[]): Promise<CreatePullRequestResult> {
-		if (this.state.phase !== "conflict-awaiting-user" || !this.state.conflict || !this.state.base) {
-			throw new Error("PR creation has no conflict awaiting continuation");
+	async verify(): Promise<CreatePullRequestResult> {
+		if (this.state.phase !== "prepared" || !this.state.base) {
+			throw new Error("PR creation is not prepared for verification");
 		}
-		const paths = validateResolvedConflictPaths(pathsInput, this.state.conflict.paths);
 		return await withWorktreeLock(this.cwd, async () => {
 			await this.freshNone();
 			if (await this.liveBase() !== this.state.base!.oid) throw new Error("PR creation cancelled: frozen base moved");
-			if (await readHead(this.exec, this.options()) !== this.state.conflict!.originalHead) throw new Error("PR creation merge HEAD changed");
-			const mergeHead = requiredOid(parseSingleOutputLine((await runChecked(this.exec, "git", ["rev-parse", "--verify", "MERGE_HEAD^{commit}"], this.options())).stdout, "MERGE_HEAD"), "MERGE_HEAD");
-			if (mergeHead !== this.state.base!.oid) throw new Error("PR creation merge context changed");
-			const status = await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.options());
-			assertOnlyDeclaredStatusChanged(this.state.conflict!.statusBaseline, status.stdout, paths);
-			this.state.phase = "blocked";
-			await runChecked(this.exec, "git", ["add", "--", ...paths], this.options());
-			const unmerged = parseNulPaths((await runChecked(this.exec, "git", ["diff", "--name-only", "-z", "--diff-filter=U"], this.options())).stdout, "Unmerged paths");
-			if (unmerged.length) throw new Error(`Conflict paths remain unresolved: ${unmerged.join(", ")}`);
-			await runChecked(this.exec, "git", ["-c", "core.editor=true", "merge", "--continue"], this.options());
-			const verified = await this.verifyMerge(this.state.conflict!.originalHead);
-			return { kind: "verified", ...verified };
+			const head = await this.requireCleanHead();
+			if (!isPullRequestCreationEligible((await this.freshNone()).branch) || await readHead(this.exec, this.options()) !== head) {
+				throw new Error("PR creation changed during verification or no longer has a committed change");
+			}
+			this.state.verifiedHead = head;
+			this.state.phase = "verified";
+			return { kind: "verified", head, fastForward: false };
 		}, { agentDir: this.agentDir, signal: this.signal });
 	}
 
@@ -374,16 +346,14 @@ export class PullRequestCreator {
 	}
 
 	async push(): Promise<CreatePullRequestResult> {
-		if (this.state.phase !== "verified" || !this.state.base) {
+		if (this.state.phase !== "verified" || !this.state.base || !this.state.verifiedHead) {
 			throw new Error("PR creation is not ready to push");
 		}
 		return await withWorktreeLock(this.cwd, async () => {
 			await this.freshNone();
 			if (await this.liveBase() !== this.state.base!.oid) throw new Error("PR creation cancelled: frozen base moved");
 			const head = await this.requireCleanHead();
-			if (!(await isAncestor(this.exec, this.options(), this.state.base!.oid, head))) {
-				throw new Error("PR creation HEAD does not contain the frozen base");
-			}
+			if (head !== this.state.verifiedHead) throw new Error("PR creation verified HEAD changed");
 			const original = this.target.remoteOid;
 			if (original !== null && !(await isAncestor(this.exec, this.options(), original, head))) {
 				throw new Error("PR creation push would not fast-forward the frozen remote OID");
@@ -423,7 +393,7 @@ export class PullRequestCreator {
 			}
 			return;
 		}
-		const discovery = await this.load(this.pi(), this.context(), undefined, undefined, this.explicitBase);
+		const discovery = await this.load(this.pi(), this.context());
 		if (discovery.kind === "none") {
 			if (!sameTarget(this.target, discovery.creationTarget, head)) throw new Error("Published target authority changed");
 			return;

package/extensions/pr-feedback-attention.ts

@@ -0,0 +1,69 @@
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { extensionConfigDir, readTextFileBounded, writePrivateTextFileAtomically } from "@henryqw/pi-config-store";
+import { spawnBounded, type Exec } from "@henryqw/pi-process";
+import { collectPullRequestFeedback, feedbackAuthorityFromCurrent, feedbackEntries, type FeedbackSnapshot } from "./pr-feedback.ts";
+import { loadCurrentPullRequest, samePullRequestSnapshot, type CurrentPullRequest } from "./pr-github.ts";
+import { extensionExecApi, isRecord, parseSingleOutputLine, runChecked } from "./pr-execution.ts";
+
+function fingerprint(snapshot: FeedbackSnapshot, blockedIds: ReadonlySet<string> = new Set()): string {
+	const entries = feedbackEntries(snapshot).filter(({ id }) => !blockedIds.has(id)).map(({ id, kind, node }) => ({
+		id, kind, body: "body" in node ? node.body : null,
+	})).sort((a, b) => a.id.localeCompare(b.id));
+	return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+}
+
+async function markerPath(cwd: string, agentDir?: string, signal?: AbortSignal, exec: Exec = spawnBounded): Promise<string> {
+	const root = parseSingleOutputLine((await runChecked(exec, "git", ["rev-parse", "--show-toplevel"], { cwd, signal })).stdout, "worktree root");
+	const identity = createHash("sha256").update(await realpath(root)).digest("hex");
+	return join(extensionConfigDir("pi-pr", agentDir), "feedback", `${identity}.json`);
+}
+
+async function readMarker(path: string, signal?: AbortSignal): Promise<{ url: string; fingerprint: string } | null> {
+	let raw: string;
+	try {
+		raw = await readTextFileBounded(path, 2_048, { signal });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+	let marker: unknown;
+	try { marker = JSON.parse(raw); } catch { throw new Error(`Invalid feedback attention marker is preserved at ${path}`); }
+	if (!isRecord(marker) || Object.keys(marker).sort().join(",") !== "fingerprint,url,version" ||
+		marker.version !== 1 || typeof marker.url !== "string" || typeof marker.fingerprint !== "string" ||
+		!/^[0-9a-f]{64}$/.test(marker.fingerprint)) {
+		throw new Error(`Invalid feedback attention marker is preserved at ${path}`);
+	}
+	return { url: marker.url, fingerprint: marker.fingerprint };
+}
+
+export async function needsFeedbackAttention(
+	current: CurrentPullRequest,
+	options: { cwd: string; agentDir?: string; signal?: AbortSignal; exec?: Exec; load?: typeof loadCurrentPullRequest },
+): Promise<boolean> {
+	const { cwd, agentDir, signal } = options;
+	const exec = options.exec ?? spawnBounded;
+	const snapshot = await collectPullRequestFeedback(feedbackAuthorityFromCurrent(current), { exec, cwd, signal });
+	const discovery = await (options.load ?? loadCurrentPullRequest)(extensionExecApi(exec, cwd, signal),
+		{ cwd, signal: signal ?? new AbortController().signal });
+	if (discovery.kind !== "current" || !samePullRequestSnapshot(current, discovery.pullRequest) ||
+		current.base.oid !== discovery.pullRequest.base.oid) {
+		throw new Error("Feedback discovery cancelled: pull request authority changed");
+	}
+	const marker = await readMarker(await markerPath(cwd, agentDir, signal, exec), signal);
+	const entries = feedbackEntries(snapshot);
+	if (!entries.length) return false;
+	return !marker || marker.url !== current.url.href || marker.fingerprint !== fingerprint(snapshot);
+}
+
+export async function markFeedbackHandled(
+	snapshot: FeedbackSnapshot,
+	options: { cwd: string; agentDir?: string; signal?: AbortSignal; exec?: Exec; blockedIds?: readonly string[] },
+): Promise<void> {
+	const path = await markerPath(options.cwd, options.agentDir, options.signal, options.exec);
+	await readMarker(path, options.signal);
+	await writePrivateTextFileAtomically(path, `${JSON.stringify({ version: 1, url: snapshot.pullRequest.url, fingerprint: fingerprint(snapshot, new Set(options.blockedIds)) })}\n`, {
+		signal: options.signal,
+	});
+}

package/extensions/pr-feedback.ts

@@ -32,6 +32,8 @@ query ThreadReplies($threadId:ID!,$cursor:String){node(id:$threadId){... on Pull
 }}}`;
 const RESOLVE_THREAD_MUTATION = `
 mutation ResolveThread($threadId:ID!){resolveReviewThread(input:{threadId:$threadId}){thread{id isResolved}}}`;
+const REPLY_THREAD_MUTATION = `
+mutation ReplyThread($threadId:ID!,$body:String!){addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$threadId,body:$body}){comment{id body}}}`;
 
 type FeedbackAuthor = { login: string } | null;
 type FeedbackComment = {
@@ -377,7 +379,9 @@ class FeedbackClient {
 
 	private async request(query: string, variables: Record<string, string | number | null>, host: string, readOnly: boolean): Promise<Record<string, unknown>> {
 		const args = ["api", "graphql", "--hostname", requiredText(host, "GitHub host"), "-F", "query=@-"];
-		for (const [name, value] of Object.entries(variables)) if (value !== null) args.push("-F", `${name}=${value}`);
+		for (const [name, value] of Object.entries(variables)) {
+			if (value !== null) args.push(typeof value === "number" ? "-F" : "-f", `${name}=${value}`);
+		}
 		for (let attempt = 0; ; attempt += 1) {
 			try {
 				this.pages += 1;
@@ -499,6 +503,24 @@ export async function collectPullRequestFeedback(
 	});
 }
 
+export async function replyToPullRequestThread(
+	authorityInput: FeedbackAuthority,
+	threadIdInput: string,
+	bodyInput: string,
+	options: FeedbackClientOptions,
+): Promise<string> {
+	const authority = parseAuthority(authorityInput);
+	const threadId = requiredText(threadIdInput, "review thread ID");
+	const body = requiredText(bodyInput, "review thread reply");
+	const data = await new FeedbackClient(options).mutate(REPLY_THREAD_MUTATION, { threadId, body }, authority.host);
+	if (!isRecord(data.addPullRequestReviewThreadReply) || !isRecord(data.addPullRequestReviewThreadReply.comment) ||
+		data.addPullRequestReviewThreadReply.comment.body !== body ||
+		typeof data.addPullRequestReviewThreadReply.comment.id !== "string") {
+		throw new Error(`GitHub did not confirm reply to ${threadId}`);
+	}
+	return requiredText(data.addPullRequestReviewThreadReply.comment.id, "review reply ID");
+}
+
 export async function resolvePullRequestThread(
 	authorityInput: FeedbackAuthority,
 	threadIdInput: string,

package/extensions/pr-publish-work.ts

@@ -0,0 +1,143 @@
+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, validateResolvedConflictPaths, 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 };
+
+/** One local publication attempt. An uncertain push consumes the run, even when a later read recovers. */
+export class PullRequestWorkPublisher {
+	private readonly authority: CurrentPullRequest;
+	private readonly exec: Exec;
+	private readonly load: typeof loadCurrentPullRequest;
+	private readonly options: Options;
+	private initialHead?: string;
+	private status?: string;
+	private validatedHead?: string;
+	private consumed = false;
+
+	constructor(options: Options) {
+		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");
+		}
+		this.options = options;
+		this.authority = cloneCurrentPullRequest(options.authority);
+		this.exec = options.exec ?? spawnBounded;
+		this.load = options.loadCurrentPullRequest ?? loadCurrentPullRequest;
+	}
+
+	private execOptions() { return { cwd: this.options.cwd, signal: this.options.signal }; }
+
+	private async authorityCheck(): Promise<void> {
+		const { cwd, signal } = this.options;
+		const discovery = await this.load(extensionExecApi(this.exec, cwd, signal), { cwd, signal: signal ?? new AbortController().signal });
+		if (discovery.kind !== "current" || !samePullRequestSnapshot(this.authority, discovery.pullRequest)) {
+			throw new Error("Local publication cancelled: PR identity or remote head changed");
+		}
+		const remote = await readValidatedRemoteAuthority(extensionExecApi(this.exec, cwd, signal),
+			{ cwd, signal: signal ?? new AbortController().signal }, this.authority.target.remote);
+		if (remote.fetchSource !== this.authority.target.fetchSource || remote.host !== this.authority.target.host ||
+			remote.repository.toLowerCase() !== this.authority.target.repository.toLowerCase()) {
+			throw new Error("Local publication cancelled: push destination changed");
+		}
+		if (await readRemoteOid(this.exec, this.execOptions(), this.authority.target.fetchSource, this.authority.target.ref) !== this.authority.head.oid) {
+			throw new Error("Local publication cancelled: remote lease changed");
+		}
+		const branch = requiredText((await runChecked(this.exec, "git", ["branch", "--show-current"], this.execOptions())).stdout.trim(), "current branch");
+		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");
+		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 status = (await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.execOptions())).stdout;
+			const paths = [...parseStatusSnapshot(status).keys()];
+			parseNulPaths(paths.map((path) => `${path}\0`).join(""), "Pending paths");
+			this.initialHead = head;
+			this.status = status;
+			return { paths, head };
+		}, { agentDir: this.options.agentDir, signal: this.options.signal });
+	}
+
+	async commit(pathsInput: string[], message: string): Promise<{ head: string }> {
+		if (!this.initialHead || this.status === undefined || this.consumed) throw new Error("Pending changes must be inspected first");
+		const paths = validateResolvedConflictPaths(pathsInput, []);
+		if (!paths.length || paths.some((path) => !parseStatusSnapshot(this.status!).has(path))) {
+			throw new Error("Commit paths must be reviewed pending paths");
+		}
+		requiredText(message, "commit message");
+		return await withWorktreeLock(this.options.cwd, async () => {
+			await this.authorityCheck();
+			if (await readHead(this.exec, this.execOptions()) !== this.initialHead ||
+				await inspectWorktreeState(this.exec, this.execOptions()) === "operation" ||
+				(await runChecked(this.exec, "git", ["status", "--porcelain=v2", "-z", "--untracked-files=all"], this.execOptions())).stdout !== this.status) {
+				throw new Error("Pending changes moved after inspection; inspect again in a new /pr");
+			}
+			// Never let an already-staged unrelated path enter this commit.
+			const staged = parseNulPaths((await runChecked(this.exec, "git", ["diff", "--cached", "--no-renames", "--name-only", "-z"], this.execOptions())).stdout, "Staged paths");
+			if (staged.some((path) => !paths.includes(path))) throw new Error("Unrelated staged changes require an ownership decision");
+			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()) };
+		}, { 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 (!Array.isArray(checks) || checks.length > 32 || checks.some(({ command, args }) =>
+			typeof command !== "string" || !command || !Array.isArray(args) || args.some((arg) => typeof arg !== "string"))) {
+			throw new Error("Invalid validation commands");
+		}
+		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");
+			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");
+			}
+			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.validatedHead = head;
+			return { head, checks: checks.length + 1 };
+		}, { agentDir: this.options.agentDir, signal: this.options.signal });
+	}
+
+	async publish(): Promise<{ kind: "published"; head: string }> {
+		if (!this.validatedHead) throw new Error("Local work is not validated");
+		const head = this.validatedHead;
+		this.validatedHead = undefined; // A response loss must never allow a second push.
+		return await withWorktreeLock(this.options.cwd, async () => {
+			await this.authorityCheck();
+			if (await inspectWorktree(this.exec, this.execOptions()) !== "clean" || await readHead(this.exec, this.execOptions()) !== head) {
+				throw new Error("Validated local HEAD or worktree changed");
+			}
+			const original = this.authority.head.oid;
+			if (head === original) return { kind: "published", head };
+			let error: unknown;
+			try {
+				await runChecked(this.exec, "git", ["push", "--porcelain", `--force-with-lease=refs/heads/${this.authority.target.ref}:${original}`,
+					"--recurse-submodules=no", "--", this.authority.target.fetchSource,
+					`${head}:refs/heads/${this.authority.target.ref}`], this.execOptions());
+			} catch (failure) { error = failure; }
+			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 === 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

@@ -60,19 +60,7 @@ export type PullRequestDiscovery<T extends PullRequest = PullRequest> =
 	| { kind: "blocked"; issue: DiscoveryIssue }
 	| { kind: "inactive" };
 
-export type NextStep = "create" | "link-branch" | "blocked" | "none" | "update-branch" | "sweep" | "fix-ci" | "merge";
-export type RouteIntent = "automatic" | "feedback";
-export type FeedbackRouteBlocker =
-	| { kind: "discovery-blocked" }
-	| { kind: "pull-request-unavailable" }
-	| { kind: "pull-request-not-open" }
-	| { kind: "target-not-configured" }
-	| { kind: "worktree-dirty" }
-	| { kind: "head-not-equal"; relation: Exclude<LocalHeadRelation, "equal"> };
-type RouteDecision =
-	| { kind: "selected"; nextStep: NextStep }
-	| { kind: "feedback-blocked"; blocker: FeedbackRouteBlocker };
-
+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";
 }
@@ -84,7 +72,9 @@ function localMergeSafe(local: LocalMergeSafety): boolean {
 export function derivePullRequestNextStep(pullRequest: PullRequest): Exclude<NextStep, "create" | "link-branch" | "blocked"> {
 	const { lifecycle, conditions, local } = pullRequest;
 	if (lifecycle !== "open" || conditions.draft) return "none";
-	if (conditions.baseUpdateRequired || conditions.conflict) {
+	if (local.worktree === "dirty" && (local.head === "behind" || local.head === "diverged")) return "none";
+	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";
@@ -116,36 +106,6 @@ function deriveAutomaticNextStep(discovery: PullRequestDiscovery<PullRequest & {
 	return derivePullRequestNextStep(discovery.pullRequest);
 }
 
-export function deriveRouteDecision(
-	discovery: PullRequestDiscovery<PullRequest & { target: PullRequestTarget }>,
-	intent: RouteIntent = "automatic",
-): RouteDecision {
-	if (intent === "automatic") return { kind: "selected", nextStep: deriveAutomaticNextStep(discovery) };
-	if (discovery.kind === "blocked") {
-		return { kind: "feedback-blocked", blocker: { kind: "discovery-blocked" } };
-	}
-	if (discovery.kind !== "current") {
-		return { kind: "feedback-blocked", blocker: { kind: "pull-request-unavailable" } };
-	}
-	const pullRequest = discovery.pullRequest;
-	if (pullRequest.lifecycle !== "open") {
-		return { kind: "feedback-blocked", blocker: { kind: "pull-request-not-open" } };
-	}
-	if (pullRequest.target.provenance !== "configured") {
-		return { kind: "feedback-blocked", blocker: { kind: "target-not-configured" } };
-	}
-	if (pullRequest.local.worktree !== "clean") {
-		return { kind: "feedback-blocked", blocker: { kind: "worktree-dirty" } };
-	}
-	if (pullRequest.local.head !== "equal") {
-		return {
-			kind: "feedback-blocked",
-			blocker: { kind: "head-not-equal", relation: pullRequest.local.head },
-		};
-	}
-	return { kind: "selected", nextStep: "sweep" };
-}
-
 export function deriveNextStep(discovery: PullRequestDiscovery<PullRequest & { target: PullRequestTarget }>): NextStep {
 	return deriveAutomaticNextStep(discovery);
 }

package/extensions/pr-ui.ts

@@ -93,6 +93,8 @@ function footerStatus(input: PrDisplayInput): Pick<PrFooter, "text" | "color"> {
 
 function widgetText(input: PrDisplayInput, nextStep: NextStep): string | undefined {
 	switch (nextStep) {
+		case "publish-work":
+			return "Run /pr to publish local work";
 		case "update-branch":
 			return input.conditions.conflict
 				? "Run /pr to resolve merge conflict"