fix: merge stacked PRs via GitHub's async merge endpoint

The synchronous merge endpoint rejects stacked PRs. Route stacked PRs
through the async merge endpoint and poll until the background merge
completes, so the merge status updates reliably (even for slow merges).

Author: glehmann

src/api/types.ts

@@ -4,6 +4,14 @@ import { components } from "@octokit/openapi-types";
 // Extended types include body_html from GitHub's HTML media type (application/vnd.github.html+json)
 export type PullRequest = components["schemas"]["pull-request"] & {
   body_html?: string;
+  // Stacked PRs (newer than openapi-types@27; null for non-stacked PRs)
+  stack?: {
+    id: number;
+    number: number;
+    size: number;
+    position: number;
+    base: { ref: string; sha: string };
+  } | null;
 };
 export type PullRequestFile = components["schemas"]["diff-entry"];
 export type ReviewComment =

src/browser/contexts/github.tsx

@@ -74,6 +74,19 @@ export type UserProfile = components["schemas"]["public-user"];
 // Types
 // ============================================================================
 
+/**
+ * Result of an asynchronous merge (POST /pulls/{pull_number}/merge-async).
+ * While pending, `details.uuid` can be polled until a terminal status.
+ */
+export interface AsyncMergeResult {
+  status: "pending" | "merged" | "enqueued" | "failed";
+  details: {
+    message: string;
+    uuid?: string;
+    sha?: string;
+  };
+}
+
 export interface PRSearchResult {
   id: number;
   number: number;
@@ -1120,6 +1133,117 @@ function createGitHubStore() {
     return data;
   }
 
+  /**
+   * Merge a PR asynchronously (required for stacked PRs). Submits the merge
+   * request and polls the returned UUID until the merge reaches a terminal
+   * state. Throws if the merge fails or times out.
+   */
+  async function mergePRAsync(
+    owner: string,
+    repo: string,
+    number: number,
+    options?: {
+      merge_method?: "merge" | "squash" | "rebase";
+      sha?: string;
+    }
+  ): Promise<AsyncMergeResult> {
+    if (!octokit) throw new Error("Not initialized");
+
+    let result: AsyncMergeResult;
+    try {
+      const { data } = await octokit.request<AsyncMergeResult>({
+        method: "PUT",
+        url: "/repos/{owner}/{repo}/pulls/{pull_number}/merge-async",
+        owner,
+        repo,
+        pull_number: number,
+        merge_method: options?.merge_method ?? "squash",
+        merge_action: "direct_merge",
+        sha: options?.sha,
+      });
+      result = data;
+    } catch (error) {
+      // 409: an async merge is already in flight for this PR — the response
+      // carries that request's UUID, which we can poll instead.
+      const err = error as {
+        status?: number;
+        response?: { data?: AsyncMergeResult };
+      };
+      if (err.status === 409 && err.response?.data) {
+        result = err.response.data;
+      } else {
+        throw error;
+      }
+    }
+
+    const { uuid } = result.details ?? {};
+    if (!uuid) return result; // already terminal (merged/enqueued/failed)
+
+    // The merge runs as a background job on GitHub (stacked merges can take
+    // several minutes), so poll patiently instead of giving up quickly.
+    const startedAt = Date.now();
+    const MAX_POLL_MS = 15 * 60_000;
+    let intervalMs = 2000;
+    let attempt = 0;
+    while (
+      result.status === "pending" &&
+      Date.now() - startedAt < MAX_POLL_MS
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      if (Date.now() - startedAt > 2 * 60_000) {
+        intervalMs = Math.min(intervalMs + 2000, 10_000);
+      }
+      attempt++;
+
+      try {
+        const { data } = await octokit.request<AsyncMergeResult>({
+          method: "GET",
+          url: "/repos/{owner}/{repo}/pulls/{pull_number}/merge-async/{uuid}",
+          owner,
+          repo,
+          pull_number: number,
+          uuid,
+        });
+        result = data;
+        if (result.status !== "pending") break;
+      } catch {
+        // Transient error — keep polling; the PR-state check below still runs.
+      }
+
+      // Accelerator: if the PR itself has flipped to merged, we're done even
+      // if the UUID endpoint misbehaves.
+      if (attempt % 5 === 0) {
+        try {
+          const pr = await queryClient.fetchQuery({
+            ...queries.pullRequest(owner, repo, number),
+            staleTime: 0,
+          });
+          if (pr.merged) {
+            return {
+              status: "merged",
+              details: {
+                message: "Merged",
+                sha: pr.merge_commit_sha ?? undefined,
+              },
+            };
+          }
+        } catch {
+          // Ignore — rely on UUID polling
+        }
+      }
+    }
+
+    if (result.status === "pending") {
+      throw new Error(
+        "Merge is still running in the background on GitHub. It will complete there and the PR status will update."
+      );
+    }
+    if (result.status === "failed") {
+      throw new Error(result.details?.message ?? "Failed to merge");
+    }
+    return result;
+  }
+
   async function dequeuePullRequest(
     owner: string,
     repo: string,
@@ -2462,6 +2586,7 @@ function createGitHubStore() {
     getWorkflowRuns: getWorkflowRunsForSha,
     approveWorkflowRun,
     mergePR,
+    mergePRAsync,
     dequeuePullRequest,
     enqueuePullRequest,
     getPRCommits,

src/browser/contexts/pr-review/index.test.ts

@@ -42,6 +42,10 @@ function createMockGitHubStore(): GitHubStore {
     invalidatePR: () => {},
     getPR: async () => createMockPR(),
     mergePR: async () => ({ merged: true }),
+    mergePRAsync: async () => ({
+      status: "merged",
+      details: { message: "merged" },
+    }),
     closePR: async () => {},
     reopenPR: async () => {},
     deleteBranch: async () => {},
@@ -763,6 +767,10 @@ function createMockGitHubStoreWithVersions(
     invalidatePR: () => {},
     getPR: async () => createMockPR(),
     mergePR: async () => ({ merged: true }),
+    mergePRAsync: async () => ({
+      status: "merged",
+      details: { message: "merged" },
+    }),
     closePR: async () => {},
     reopenPR: async () => {},
     deleteBranch: async () => {},
@@ -987,6 +995,108 @@ test("mergePR sets mergeError and clears merging on failure", async () => {
   expect(state.pr.merged).toBe(false);
 });
 
+// ============================================================================
+// mergePR (stacked PRs - async merge endpoint)
+// ============================================================================
+
+function createStackedMockPR(): PullRequest {
+  return createMockPR({
+    stack: {
+      id: 1,
+      number: 2,
+      size: 2,
+      position: 1,
+      base: { ref: "main", sha: "def456" },
+    },
+  });
+}
+
+test("mergePR uses async merge endpoint for stacked PRs and sets merged=true", async () => {
+  let syncCalled = false;
+  let asyncCalled = false;
+  const github = {
+    ...createMockGitHubStore(),
+    mergePR: async () => {
+      syncCalled = true;
+      return { merged: true };
+    },
+    mergePRAsync: async () => {
+      asyncCalled = true;
+      return { status: "merged", details: { message: "merged" } };
+    },
+  } as unknown as GitHubStore;
+  const store = new PRReviewStore(github, {
+    pr: createStackedMockPR(),
+    files: [],
+    comments: [],
+    owner: "test",
+    repo: "repo",
+    viewerPermission: "WRITE",
+  });
+
+  const result = await store.mergePR();
+
+  expect(result).toBe(true);
+  expect(asyncCalled).toBe(true);
+  expect(syncCalled).toBe(false);
+  const state = store.getSnapshot();
+  expect(state.pr.merged).toBe(true);
+  expect(state.pr.state).toBe("closed");
+  expect(state.merging).toBe(false);
+});
+
+test("mergePR sets prInMergeQueue when async merge is enqueued", async () => {
+  const github = {
+    ...createMockGitHubStore(),
+    mergePRAsync: async () => ({
+      status: "enqueued",
+      details: { message: "enqueued" },
+    }),
+  } as unknown as GitHubStore;
+  const store = new PRReviewStore(github, {
+    pr: createStackedMockPR(),
+    files: [],
+    comments: [],
+    owner: "test",
+    repo: "repo",
+    viewerPermission: "WRITE",
+  });
+
+  const result = await store.mergePR();
+
+  expect(result).toBe(true);
+  const state = store.getSnapshot();
+  expect(state.prInMergeQueue).toBe(true);
+  expect(state.pr.merged).toBe(false);
+  expect(state.merging).toBe(false);
+});
+
+test("mergePR sets mergeError when async merge fails", async () => {
+  const github = {
+    ...createMockGitHubStore(),
+    mergePRAsync: async () => {
+      throw new Error("Merge failed");
+    },
+  } as unknown as GitHubStore;
+  const store = new PRReviewStore(github, {
+    pr: createStackedMockPR(),
+    files: [],
+    comments: [],
+    owner: "test",
+    repo: "repo",
+    viewerPermission: "WRITE",
+  });
+
+  const result = await store.mergePR();
+
+  expect(result).toBe(false);
+  const state = store.getSnapshot();
+  expect(state.merging).toBe(false);
+  expect(state.mergeError).toBe("Merge failed");
+  expect(state.pr.merged).toBe(false);
+  expect(state.prInMergeQueue).toBe(false);
+});
+
 // ============================================================================
 // Conversation / Timeline events
 // ============================================================================

src/browser/contexts/pr-review/index.tsx

@@ -3769,6 +3769,25 @@ export class PRReviewStore {
         this.invalidatePRCaches(owner, repo, pr.number);
 
         this.set({ prInMergeQueue: true, merging: false });
+      } else if (pr.stack) {
+        // Stacked PRs must be merged via the asynchronous merge endpoint.
+        const result = await this.github.mergePRAsync(owner, repo, pr.number, {
+          merge_method: mergeMethod,
+          sha: pr.head.sha,
+        });
+
+        this.invalidatePRCaches(owner, repo, pr.number);
+
+        if (result.status === "merged") {
+          this.set({
+            pr: { ...this.state.pr, merged: true, state: "closed" as const },
+            merging: false,
+          });
+        } else if (result.status === "enqueued") {
+          this.set({ prInMergeQueue: true, merging: false });
+        } else {
+          throw new Error(result.details?.message ?? "Failed to merge");
+        }
       } else {
         await this.github.mergePR(owner, repo, pr.number, {
           merge_method: mergeMethod,