fix(pr-header): surface gh errors, forward head SHA, dedupe disable-auto

Addresses PR review feedback on the write layer:

- write() now reads the server's { error } body on failure so toasts show the
  actionable gh stderr instead of a generic "POST … failed: 500".
- Forward expectedHeadOid through the enqueue/auto-merge path into
  gh pr merge --auto --match-head-commit, guarding auto-merge against a stale
  head (parity with the direct-merge path).
- The merge-queue off-toggle no longer fires both dequeue and disable-auto
  (which map to the same gh --disable-auto), avoiding a duplicate request.

Author: dastratakos

packages/cli/src/__tests__/pull-request-mutations.routes.test.ts

@@ -155,6 +155,18 @@ describe("pull-request mutation API", () => {
 		expect(await ghArgs()).toEqual(["pr merge 7 --auto --merge", "pr merge 7 --disable-auto"]);
 	});
 
+	it("forwards expectedHeadOid to gh as --match-head-commit when enabling auto-merge", async () => {
+		const runId = insertRun();
+		const res = await send(await start(), "POST", `/api/runs/${runId}/pull-request/auto-merge`, {
+			number: 7,
+			enabled: true,
+			mergeMethod: "SQUASH",
+			expectedHeadOid: SHA,
+		});
+		expect(res.status).toBe(200);
+		expect(await ghArgs()).toEqual([`pr merge 7 --auto --squash --match-head-commit ${SHA}`]);
+	});
+
 	it("adds and removes reviewers via gh pr edit", async () => {
 		const runId = insertRun();
 		const port = await start();

packages/cli/src/github/mutations.ts

@@ -70,10 +70,13 @@ export function setAutoMerge(
 	number: number,
 	enabled: boolean,
 	mergeMethod?: PullRequestMergeMethod,
+	expectedHeadOid?: string,
 ): Promise<void> {
 	if (!enabled) return ghWrite(["pr", "merge", String(number), "--disable-auto"], repoRoot);
 	const args = ["pr", "merge", String(number), "--auto"];
 	if (mergeMethod) args.push(MERGE_METHOD_FLAG[mergeMethod]);
+	// Guard against enabling auto-merge for a stale head the user hasn't seen.
+	if (expectedHeadOid) args.push("--match-head-commit", expectedHeadOid);
 	return ghWrite(args, repoRoot);
 }
 

packages/cli/src/routes/pull-request-mutations.ts

@@ -37,6 +37,7 @@ const autoMergeInput = z.object({
 	number: numberField,
 	enabled: z.boolean(),
 	mergeMethod: mergeMethod.optional(),
+	expectedHeadOid: z.string().optional(),
 });
 const reviewersInput = z.object({ number: numberField, reviewers: z.array(z.string()).min(1) });
 
@@ -127,7 +128,13 @@ export function pullRequestMutationRoutes(db: StageDb): Route[] {
 				const input = await parseBody(req, res, autoMergeInput);
 				if (!input) return;
 				await runMutation(res, () =>
-					setAutoMerge(run.repoRoot, input.number, input.enabled, input.mergeMethod),
+					setAutoMerge(
+						run.repoRoot,
+						input.number,
+						input.enabled,
+						input.mergeMethod,
+						input.expectedHeadOid,
+					),
 				);
 			},
 		},

packages/web/src/components/pull-request/merge-status.tsx

@@ -174,18 +174,18 @@ function MergeActions({
 							} else {
 								autoMergeMutation.mutate({ owner, repo, number, enabled: true, mergeMethod });
 							}
-						} else {
-							if (mergeInfo.isInMergeQueue && mergeInfo.entry) {
-								dequeueMutation.mutate({
-									owner,
-									repo,
-									number,
-									mergeQueueEntryId: mergeInfo.entry.id,
-								});
-							}
-							if (mergeInfo.autoMergeEnabled) {
-								autoMergeMutation.mutate({ owner, repo, number, enabled: false });
-							}
+						} else if (mergeInfo.isInMergeQueue && mergeInfo.entry) {
+							dequeueMutation.mutate({
+								owner,
+								repo,
+								number,
+								mergeQueueEntryId: mergeInfo.entry.id,
+							});
+						} else if (mergeInfo.autoMergeEnabled) {
+							// `else if`: both dequeue and disabling auto-merge map to the same
+							// `gh pr merge --disable-auto` here, so fire only one to avoid a
+							// duplicate request (and a spurious error toast on the second).
+							autoMergeMutation.mutate({ owner, repo, number, enabled: false });
 						}
 					}}
 				/>

packages/web/src/lib/pull-request-mutations.ts

@@ -1,22 +1,39 @@
 import type { PullRequestMergeMethod } from "@stagereview/types/pull-request";
 import { useQueryClient } from "@tanstack/react-query";
-import { jsonFetch } from "@/lib/use-view-state";
 
 function prPath(runId: string, suffix: string): string {
 	return `/api/runs/${encodeURIComponent(runId)}/pull-request${suffix}`;
 }
 
-function write(
+async function write(
 	runId: string,
 	suffix: string,
 	method: "POST" | "PATCH" | "DELETE",
 	body: Record<string, unknown>,
 ): Promise<unknown> {
-	return jsonFetch(prPath(runId, suffix), {
+	const path = prPath(runId, suffix);
+	const res = await fetch(path, {
 		method,
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify(body),
 	});
+	const text = await res.text();
+	if (!res.ok) {
+		// The server returns `{ error: <gh stderr> }` on failure — surface it so the
+		// toast shows the actionable gh message, not a generic "POST … failed: 500".
+		let message = `${method} ${path} failed: ${res.status}`;
+		try {
+			const parsed: unknown = text ? JSON.parse(text) : null;
+			if (parsed && typeof parsed === "object" && "error" in parsed) {
+				const { error } = parsed as { error: unknown };
+				if (typeof error === "string" && error) message = error;
+			}
+		} catch {
+			// non-JSON body — keep the generic message
+		}
+		throw new Error(message);
+	}
+	return text ? JSON.parse(text) : {};
 }
 
 /** Invalidate every PR-derived query for a run after a mutation. */
@@ -83,10 +100,15 @@ export function mergeMutationOptions(runId: string) {
 }
 
 // Merge-queue enqueue maps to "enable auto-merge" — gh enqueues when ready.
+// Forward the head SHA so the server can guard against a stale head (--match-head-commit).
 export function enqueueMutationOptions(runId: string) {
 	return {
 		mutationFn: (v: RepoVars & { number: number; expectedHeadOid?: string }) =>
-			write(runId, "/auto-merge", "POST", { number: v.number, enabled: true }),
+			write(runId, "/auto-merge", "POST", {
+				number: v.number,
+				enabled: true,
+				expectedHeadOid: v.expectedHeadOid,
+			}),
 	};
 }