@gitkraken/core-gitlens 0.5.109 → 0.5.111

package/src/plus/git-github/api/github.ts

@@ -21,7 +21,7 @@ import type {
 	PullRequestState,
 	PullRequestStateFilter,
 } from '../../../git/models/pullRequest.js';
-import { PullRequestMergeMethod } from '../../../git/models/pullRequest.js';
+import { defaultPullRequestSort, PullRequestMergeMethod } from '../../../git/models/pullRequest.js';
 import type { Provider } from '../../../git/models/remoteProvider.js';
 import type { RepositoryMetadata } from '../../../git/models/repositoryMetadata.js';
 import type { GitRevisionRange } from '../../../git/models/revision.js';
@@ -29,6 +29,7 @@ import type { GitUser } from '../../../git/models/user.js';
 import type { RepositoryVisibility } from '../../../git/providers/types.js';
 import { getGitHubNoReplyAddressParts } from '../../../git/remotes/github.js';
 import { effectiveIssueSort, getIssueComparator } from '../../../git/utils/issue.utils.js';
+import { getPullRequestComparator } from '../../../git/utils/pullRequest.utils.js';
 import {
 	createRevisionRange,
 	getRevisionRangeParts,
@@ -37,7 +38,7 @@ import {
 } from '../../../git/utils/revision.utils.js';
 import { chunk } from '../../../utils/array.js';
 import { base64 } from '../../../utils/base64.js';
-import { CancellationError } from '../../../utils/cancellation.js';
+import { CancellationError, isCancellationError } from '../../../utils/cancellation.js';
 import { trace } from '../../../utils/decorators/log.js';
 import type { Event } from '../../../utils/event.js';
 import { Emitter } from '../../../utils/event.js';
@@ -110,10 +111,17 @@ const accountResolveBatchSize = 25;
 
 // Pull-request search selects the full PR fragment (reviews, requests, refs, commits, etc.),
 // which makes GitHub reject broad 100-node searches with `Resource limits for this query
-// exceeded` on large repositories. Thirty keeps the default within that GraphQL cost budget
-// while callers that know their scope is cheap can still opt into the supported 100-node max.
+// exceeded` on large repositories. Thirty keeps the default within that GraphQL cost budget;
+// the 100-node maximum the connection accepts is for the lite shape, whose per-node cost is a
+// fraction of it. The budget is per DOCUMENT, and one document holds every relationship × state
+// facet, so the worst case scales with the facet count (five relationships × four states = 20).
 const defaultPullRequestSearchPageSize = 30;
 const maxPullRequestSearchPageSize = 100;
+// Pages `searchMyPullRequests` drains for a caller that wants a whole list rather than a page.
+// Four reduced pages cover more than the single 100-node page this read served before it paged,
+// so the smaller page costs coverage nowhere; it bounds an unbounded drain on a read whose
+// consumers (Launchpad, the Graph pull-request panel) block on it.
+const maxMyPullRequestSearchPages = 4;
 
 function isRetryableTransientError(ex: unknown): ex is RequestError {
 	// An aborted request is rethrown as the original `AbortError` (not a `RequestError`), so it is
@@ -223,6 +231,85 @@ title
 updatedAt
 url
 `;
+/**
+ * Stacked-pull-request selections, appended to a pull request's selection set rather than baked into
+ * the fragments below: GitHub Enterprise Server schemas lag github.com, and selecting `stack` there
+ * fails the entire query with "Field 'stack' doesn't exist on type 'PullRequest'" — which would take
+ * every PR feature down with it, not just stacks. Always add these via `gqlPullRequestStackFragmentFor`.
+ */
+const gqlPullRequestStackFragment = `
+stack {
+	id
+	number
+	size
+	baseRefName
+}
+stackEntry {
+	position
+}
+`;
+
+function gqlPullRequestStackFragmentFor(options?: { baseUrl?: string }): string {
+	return isGitHubDotCom(options) ? gqlPullRequestStackFragment : '';
+}
+
+/** One layer of a stack, as returned by the stacks REST API. Ordered bottom to top. */
+export interface GitHubStackLayer {
+	number: number;
+	state: string;
+	draft?: boolean;
+	merged_at?: string | null;
+	head: { ref: string; sha: string };
+}
+
+export interface GitHubStackResource {
+	id: string;
+	number: number;
+	/** The stack's trunk — what the bottom member targets. */
+	base: { ref: string; sha?: string };
+	/** False once every member has merged; such a stack can no longer be extended. */
+	open?: boolean;
+	/** Members ordered bottom to top. */
+	pull_requests: GitHubStackLayer[];
+}
+
+/** Result of the asynchronous merge used for stacked pull requests. */
+interface GitHubAsyncMergeResult {
+	status: 'pending' | 'merged' | 'enqueued' | 'failed';
+	/** Everything but `status` is nested here — flattening it silently loses the poll ticket. */
+	details?: {
+		/** Always present; on `failed` it is the only explanation of why. */
+		message?: string;
+		/** Only while `pending` — the ticket to poll. */
+		uuid?: string;
+		/** Only once `merged`. */
+		sha?: string;
+		merge_method?: string;
+		merge_action?: string;
+		expected_head_sha?: string;
+	};
+}
+
+/**
+ * A 409 means a merge request is already in flight and carries its ticket, so it resumes rather than fails.
+ *
+ * The body has to be dug out of `original`: `requestCore` routes every 4xx through `handleRequestError`,
+ * which re-wraps octokit's `RequestError` in a `RequestClientError` carrying only `message` and `original`.
+ */
+function getAsyncMergeUuidFromConflict(ex: unknown): string | undefined {
+	const err = (RequestClientError.is(ex) ? ex.original : ex) as
+		| { status?: number; response?: { data?: GitHubAsyncMergeResult } }
+		| undefined;
+	if (err?.status !== 409) return undefined;
+
+	return err.response?.data?.details?.uuid;
+}
+
+const asyncMergePollIntervalMs = 2000;
+/** A stack merges one layer at a time and GitHub only promises "a few minutes", so the ceiling is
+ *  generous — giving up early would report a failure for a merge still in progress. */
+const maxAsyncMergePolls = 300;
+
 const gqlPullRequestLiteFragment = `
 ${gqlIssueOrPullRequestFragment}
 author {
@@ -259,6 +346,24 @@ repository {
 	viewerPermission
 }
 `;
+/**
+ * One review's fields, shared by `latestReviews` and `viewerLatestReview`. The two selections must stay
+ * identical: `fromGitHubPullRequest` merges the viewer's review into the capped `latestReviews` window and
+ * dedups by `id`, so a field present in only one of them would produce rows that differ by where they came
+ * from rather than by what they are.
+ */
+const gqlPullRequestReviewFragment = `
+id
+author {
+	login
+	avatarUrl(size: $avatarSize)
+	url
+}
+state
+commit {
+	oid
+}
+`;
 const gqlPullRequestFragment = `
 ${gqlPullRequestLiteFragment}
 additions
@@ -269,6 +374,7 @@ assignees(first: 25) {
 		url
 	}
 }
+changedFiles
 checksUrl
 deletions
 mergeable
@@ -278,14 +384,12 @@ mergedBy {
 reviewDecision
 latestReviews(first: 25) {
 	nodes {
-		author {
-			login
-			avatarUrl(size: $avatarSize)
-			url
-		}
-		state
+		${gqlPullRequestReviewFragment}
 	}
 }
+viewerLatestReview {
+	${gqlPullRequestReviewFragment}
+}
 reviewRequests(first: 25) {
 	nodes {
 		asCodeOwner
@@ -300,6 +404,7 @@ reviewRequests(first: 25) {
 	}
 }
 commits(last: 1) {
+	totalCount
 	nodes {
 		commit {
 			statusCheckRollup {
@@ -391,6 +496,7 @@ export class GitHubApi {
 
 		interface QueryResult {
 			viewer: {
+				databaseId: number | null;
 				name: string | null;
 				email: string | null;
 				login: string | null;
@@ -401,6 +507,7 @@ export class GitHubApi {
 		try {
 			const query = `query getCurrentAccount($avatarSize: Int) {
 	viewer {
+		databaseId
 		name
 		email
 		login
@@ -413,7 +520,10 @@ export class GitHubApi {
 
 			return {
 				provider: provider,
-				id: rsp.viewer.login,
+				// `id` is the provider's own id, as it is for every other provider, and `username` the handle
+				// filters and viewer matching key on. Falls back to the login only when GitHub omits the
+				// database id, which leaves the two equal rather than leaving `id` empty.
+				id: rsp.viewer.databaseId != null ? String(rsp.viewer.databaseId) : rsp.viewer.login,
 				name: rsp.viewer.name ?? undefined,
 				email: rsp.viewer.email ?? undefined,
 				// If we are GitHub Enterprise, we may need to convert the avatar URL since it might require authentication
@@ -973,6 +1083,7 @@ export class GitHubApi {
 	repository(name: $repo, owner: $owner) {
 		pullRequest(number: $number) {
 			${gqlPullRequestLiteFragment}
+			${gqlPullRequestStackFragmentFor(options)}
 		}
 	}
 }`;
@@ -1053,6 +1164,7 @@ export class GitHubApi {
 			associatedPullRequests(first: $limit, orderBy: {field: UPDATED_AT, direction: DESC}, states: $include) {
 				nodes {
 					${gqlPullRequestLiteFragment}
+					${gqlPullRequestStackFragmentFor(options)}
 				}
 			}
 		}
@@ -1146,6 +1258,7 @@ export class GitHubApi {
 				associatedPullRequests(first: 2, orderBy: {field: UPDATED_AT, direction: DESC}) {
 					nodes {
 						${gqlPullRequestLiteFragment}
+						${gqlPullRequestStackFragmentFor(options)}
 					}
 				}
 			}
@@ -3283,6 +3396,40 @@ export class GitHubApi {
 		scope: ScopedLogger | undefined,
 		cancellation?: AbortSignal | undefined,
 	): Promise<Endpoints[R]['response']> {
+		return (await this.requestCore(
+			provider,
+			token,
+			route,
+			options,
+			scope,
+			cancellation,
+		)) as Endpoints[R]['response'];
+	}
+
+	/**
+	 * REST call for routes `@octokit/types` doesn't describe yet — currently the stacked-pull-request
+	 * merge APIs, which are in public preview and absent from the generated endpoint map. Prefer
+	 * `request` for anything typed.
+	 */
+	private async requestPreview<T>(
+		provider: Provider | undefined,
+		token: GitHubTokenInfo,
+		route: string,
+		options: RequestParameters | undefined,
+		scope: ScopedLogger | undefined,
+		cancellation?: AbortSignal | undefined,
+	): Promise<T> {
+		return (await this.requestCore(provider, token, route, options, scope, cancellation)) as T;
+	}
+
+	private async requestCore(
+		provider: Provider | undefined,
+		token: GitHubTokenInfo,
+		route: string,
+		options: RequestParameters | undefined,
+		scope: ScopedLogger | undefined,
+		cancellation?: AbortSignal | undefined,
+	): Promise<unknown> {
 		const { accessToken } = token;
 		try {
 			let signal: AbortSignal | undefined;
@@ -3296,15 +3443,15 @@ export class GitHubApi {
 			// Retry transient gateway/network failures on idempotent reads only
 			const method = route.split(' ', 1)[0].toUpperCase();
 			const retryable = method === 'GET' || method === 'HEAD';
-			return (await this.requestWithRetries(
+			return await this.requestWithRetries(
 				() =>
 					this.config.wrapForForcedInsecureSSL(provider?.getIgnoreSSLErrors() ?? false, () =>
-						this.getDefaults(accessToken, request)(route as string, options),
+						this.getDefaults(accessToken, request)(route, options),
 					),
 				retryable,
 				signal,
 				scope,
-			)) as Endpoints[R]['response'];
+			);
 		} catch (ex) {
 			if (ex instanceof RequestError || ex.name === 'AbortError') {
 				this.handleRequestError(provider, token, ex, scope);
@@ -3526,8 +3673,10 @@ export class GitHubApi {
 	 * One page of the current user's pull requests, filtered by state and optionally by an explicit
 	 * relationship qualifier. Backs the PR sweeps, which drain it page by page.
 	 *
-	 * Ordering is part of the contract, not an option: always `sort:updated` (most recently updated first),
-	 * matching {@link searchPullRequestsPage}. A caller that stops before `hasMore` clears — every sweep with a
+	 * Ordering is part of the contract, not an option: always `sort:updated` (most recently updated first), which is
+	 * {@link searchPullRequestsPage}'s DEFAULT rather than its only order — that read takes a `criteria.sort`, this
+	 * one does not, because a sweep's recency window is what its page budget is defined against. A caller that stops
+	 * before `hasMore` clears — every sweep with a
 	 * page budget — therefore retains a well-defined recency window instead of an arbitrary slice of GitHub's
 	 * relevance ranking.
 	 */
@@ -3558,7 +3707,15 @@ export class GitHubApi {
 		cancellation?: AbortSignal,
 	): Promise<{ values: PullRequest[]; cursor?: string; hasMore: boolean; truncated: boolean }> {
 		const scope = getScopedLogger();
-		const limit = Math.min(100, this.config.getLaunchpadQueryLimit?.() ?? 100);
+		// The page follows the projection rather than being a separate decision: the full fragment is what GitHub
+		// rejects at 100 nodes (see `defaultPullRequestSearchPageSize`), so every read that selects it pages at the
+		// reduced size, and only the lite shape asks for the maximum. A caller that wants a whole list pages for it
+		// — see `searchMyPullRequests`.
+		const configuredLimit = this.config.getLaunchpadQueryLimit?.() ?? maxPullRequestSearchPageSize;
+		const limit = Math.min(
+			options?.summary === true ? maxPullRequestSearchPageSize : defaultPullRequestSearchPageSize,
+			configuredLimit,
+		);
 
 		try {
 			interface SearchResult {
@@ -3586,6 +3743,7 @@ export class GitHubApi {
 			nodes {
 				...on PullRequest {
 					${options?.summary ? gqlPullRequestLiteFragment : gqlPullRequestFragment}
+					${gqlPullRequestStackFragmentFor(options)}
 				}
 			}
 		}
@@ -3666,6 +3824,16 @@ export class GitHubApi {
 		}
 	}
 
+	/**
+	 * The whole list rather than a page: this read has no cursor to hand back (its `IntegrationResult<T[]>` return
+	 * has no paging channel at all), so it drains up to {@link maxMyPullRequestSearchPages} pages itself.
+	 *
+	 * Draining instead of taking one page is what lets the full projection page at the reduced size everywhere
+	 * (see the `limit` in {@link searchMyPullRequestsPage}): a single page would otherwise have to ask for 100
+	 * nodes of the selection GitHub rejects at that size, purely because this caller cannot resume. Ordering is
+	 * `sort:updated`, so the pages compose into a defined window rather than a shifting relevance ranking, and the
+	 * drain stops as soon as GitHub reports no next page.
+	 */
 	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
 	async searchMyPullRequests(
 		provider: Provider,
@@ -3681,7 +3849,33 @@ export class GitHubApi {
 		},
 		cancellation?: AbortSignal,
 	): Promise<PullRequest[]> {
-		return (await this.searchMyPullRequestsPage(provider, token, options, cancellation)).values;
+		const values: PullRequest[] = [];
+		// The searches behind one page can overlap (a PR can be authored by and review-requested from the same
+		// user), and a later page can repeat a row an earlier one already served if the PR was updated mid-drain.
+		const seen = new Set<string>();
+		let cursor: string | undefined;
+
+		for (let page = 0; page < maxMyPullRequestSearchPages; page++) {
+			const result = await this.searchMyPullRequestsPage(
+				provider,
+				token,
+				{ ...options, cursor: cursor },
+				cancellation,
+			);
+			for (const pr of result.values) {
+				if (seen.has(pr.url)) continue;
+
+				seen.add(pr.url);
+				values.push(pr);
+			}
+
+			// A missing or repeated cursor with `hasMore` would loop on the same page forever.
+			if (!result.hasMore || result.cursor == null || result.cursor === cursor) break;
+
+			cursor = result.cursor;
+		}
+
+		return values;
 	}
 
 	/**
@@ -3948,6 +4142,85 @@ export class GitHubApi {
 		}
 	}
 
+	/**
+	 * The PR twin of {@link countIssues}: counts pull requests for several scopes in ONE request via aliased
+	 * `search` fields selecting only `issueCount` with `first: 0`. Same positional/undefined contract as the issue
+	 * count.
+	 *
+	 * The one difference is states. {@link toGitHubPullRequestSearchFacets} fans a scope's states out into one
+	 * `search` each, so this reports the count the SAME way {@link searchPullRequestsPage} reports its total — the
+	 * LARGEST facet's `issueCount`, not their sum: the result ceiling applies per search, so the max is what
+	 * `exceedsProviderLimit` compares against, and summing would claim a total the read never surfaces. Relationships
+	 * are OR-ed and can't be a single count; the facade refuses a multi-relationship scope, so at most one is here.
+	 */
+	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
+	async countPullRequests(
+		provider: Provider,
+		token: GitHubTokenInfo,
+		scopes: readonly { repos?: string[]; org?: string; criteria?: PullRequestSearchCriteria }[],
+		options?: { baseUrl?: string },
+		cancellation?: AbortSignal,
+	): Promise<(number | undefined)[]> {
+		const scope = getScopedLogger();
+		if (scopes.length === 0) return [];
+
+		// Each scope expands to one query string per state facet (all sharing its single relationship, which the
+		// facade guarantees). A scope's count is the MAX across its facets — mirroring searchPullRequestsPage's
+		// totalCount — so the aliases stay grouped by scope and are reduced after the response.
+		const scopeQueries = scopes.map(s => {
+			const scopeQualifiers = toGitHubIssueSearchScopeQualifiers(s.org, s.repos);
+			return toGitHubPullRequestSearchFacets(s.criteria).map(f =>
+				[...scopeQualifiers, ...f.qualifiers].join(' '),
+			);
+		});
+
+		// Aliases are positional and generated (`s${scope}f${facet}`): a caller's key is arbitrary text and would
+		// break the document, so results are reduced back to one count per scope by index.
+		const aliased = scopeQueries.flatMap((queries, si) =>
+			queries.map((query, fi) => ({ alias: `s${si}f${fi}`, query: query })),
+		);
+		const params = aliased.map(a => `$${a.alias}: String!`).join('\n\t\t\t\t');
+		// `first: 0` is what makes this cheap — `issueCount` alone, no nodes over the wire.
+		const fields = aliased
+			.map(a => `${a.alias}: search(query: $${a.alias}, type: ISSUE, first: 0) { issueCount }`)
+			.join('\n\t\t\t\t');
+		const query = `query countPullRequests(
+				${params}
+			) {
+				${fields}
+			}`;
+
+		const variables: Record<string, unknown> = { baseUrl: options?.baseUrl };
+		for (const a of aliased) {
+			variables[a.alias] = a.query;
+		}
+
+		try {
+			const rsp = await this.graphql<Record<string, { issueCount?: number } | undefined>>(
+				provider,
+				token,
+				query,
+				variables,
+				scope,
+				cancellation,
+			);
+			if (rsp == null) return scopes.map(() => undefined);
+
+			return scopeQueries.map((queries, si) => {
+				let max: number | undefined;
+				for (let fi = 0; fi < queries.length; fi++) {
+					const count = rsp[`s${si}f${fi}`]?.issueCount;
+					if (count != null) {
+						max = max == null ? count : Math.max(max, count);
+					}
+				}
+				return max;
+			});
+		} catch (ex) {
+			throw this.handleException(ex, provider, scope);
+		}
+	}
+
 	/**
 	 * The aliased-search engine behind every GitHub issue search: one GraphQL request carrying N independently
 	 * cursored `search` fields, `@include`-gated so an exhausted or unrequested one costs nothing.
@@ -4234,8 +4507,11 @@ export class GitHubApi {
 	 * every active relationship × state facet, so one HTTP request serves one page even when the logical search is
 	 * a union. The cursor preserves each facet's continuation plus the positional page.
 	 *
-	 * Ordering is always most-recently-updated-first, and user text is sanitized before it reaches the provider
-	 * query. See {@link toGitHubPullRequestSearchFacets}.
+	 * Ordering is `criteria.sort`, defaulting to most-recently-updated-first — the order this read served before it
+	 * was expressible. It is requested of the provider AND re-applied to the merged page, because the page is a
+	 * union of facets and no per-facet server order describes it. The sort is part of the cursor fingerprint, so
+	 * changing it invalidates a threaded cursor exactly as changing the text or the scope does. User text is
+	 * sanitized before it reaches the provider query. See {@link toGitHubPullRequestSearchFacets}.
 	 */
 	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
 	async searchPullRequestsPage(
@@ -4351,6 +4627,7 @@ export class GitHubApi {
 				nodes {
 					... on PullRequest {
 						${gqlPullRequestFragment}
+						${gqlPullRequestStackFragmentFor(options)}
 					}
 				}
 			}`,
@@ -4395,7 +4672,15 @@ export class GitHubApi {
 					}
 				}
 			}
-			pullRequests.sort((a, b) => b.updatedDate.getTime() - a.updatedDate.getTime());
+			// The PR path re-sorts the merged page rather than trusting the per-facet server order — GitHub's
+			// server-side PR sort has been unreliable (the per-branch path re-sorts for the same reason), and the
+			// union of several facets is unordered regardless. The key was validated against
+			// `githubPullRequestSearchCapabilities.sorts` upstream, so its comparator is always defined for a PR
+			// shape; the guard only guards the unreachable case rather than inventing an order for it.
+			const comparator = getPullRequestComparator(options?.criteria?.sort ?? defaultPullRequestSort);
+			if (comparator != null) {
+				pullRequests.sort(comparator);
+			}
 			const values = [
 				...uniqueBy(
 					pullRequests,
@@ -4495,6 +4780,7 @@ export class GitHubApi {
 		nodes {
 			...on PullRequest {
 				${gqlPullRequestFragment}
+				${gqlPullRequestStackFragmentFor(options)}
 			}
 		}
 	}
@@ -4554,6 +4840,164 @@ export class GitHubApi {
 		}
 	}
 
+	/**
+	 * Every stack in the repository, each with its members bottom to top.
+	 *
+	 * One request regardless of how many pull requests are involved — which is what makes it the right
+	 * shape for list surfaces, whose pull requests arrive through the shared providers API and so carry no
+	 * stack membership of their own. Callers join the result by pull request number.
+	 *
+	 * A `404` means the repository isn't enrolled in the stacked-pull-requests preview; that's reported as
+	 * `undefined` rather than an error, since "no stacks" and "not available" both mean nothing to show.
+	 */
+	@trace({
+		args: (provider, token, owner, repo) => ({
+			provider: provider.name,
+			token: `<token:${token.microHash}>`,
+			owner: owner,
+			repo: repo,
+		}),
+	})
+	async getRepositoryStacks(
+		provider: Provider,
+		token: GitHubTokenInfo,
+		owner: string,
+		repo: string,
+		options?: { baseUrl?: string },
+		cancellation?: AbortSignal,
+	): Promise<GitHubStackResource[] | undefined> {
+		const scope = getScopedLogger();
+
+		try {
+			const rsp = await this.requestPreview<{ data: GitHubStackResource[] }>(
+				provider,
+				token,
+				'GET /repos/{owner}/{repo}/stacks',
+				{ owner: owner, repo: repo, baseUrl: options?.baseUrl },
+				scope,
+				cancellation,
+			);
+
+			return rsp.data;
+		} catch (ex) {
+			if (isCancellationError(ex)) throw ex;
+
+			Logger.warn(scope, `Unable to list stacks for ${owner}/${repo}: ${ex}`);
+			return undefined;
+		}
+	}
+
+	/**
+	 * Merges a stacked pull request, and with it every layer below it.
+	 *
+	 * Stacks cannot go through `mergePullRequest` — GitHub rejects stacked pull requests on the legacy
+	 * synchronous merge endpoints and mutations. The replacement is asynchronous: submit, then poll a
+	 * ticket until it reaches a terminal state.
+	 */
+	@trace({
+		args: (provider, token, owner, repo, pullNumber, expectedSourceSha) => ({
+			provider: provider.name,
+			token: `<token:${token.microHash}>`,
+			owner: owner,
+			repo: repo,
+			pullNumber: pullNumber,
+			expectedSourceSha: expectedSourceSha,
+		}),
+	})
+	async mergeStackedPullRequest(
+		provider: Provider,
+		token: GitHubTokenInfo,
+		owner: string,
+		repo: string,
+		pullNumber: number,
+		expectedSourceSha: string,
+		options?: { mergeMethod?: PullRequestMergeMethod; baseUrl?: string },
+		cancellation?: AbortSignal,
+	): Promise<boolean> {
+		const scope = getScopedLogger();
+
+		try {
+			let uuid: string | undefined;
+
+			try {
+				const submitted = await this.requestPreview<{ data: GitHubAsyncMergeResult }>(
+					provider,
+					token,
+					'PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge-async',
+					{
+						owner: owner,
+						repo: repo,
+						pull_number: pullNumber,
+						sha: expectedSourceSha,
+						merge_method: options?.mergeMethod,
+						baseUrl: options?.baseUrl,
+					},
+					scope,
+					cancellation,
+				);
+
+				// Already merged or rejected outright — nothing to poll for. `enqueued` lands via the merge
+				// queue, which can take several merge groups to settle, so it's transitional like `pending`.
+				if (submitted.data.status !== 'pending' && submitted.data.status !== 'enqueued') {
+					if (submitted.data.status === 'failed') {
+						Logger.warn(
+							scope,
+							`Stacked merge refused: ${submitted.data.details?.message ?? 'no reason given'}`,
+						);
+					}
+					return submitted.data.status === 'merged';
+				}
+
+				uuid = submitted.data.details?.uuid;
+			} catch (ex) {
+				// A merge request is already in flight (a retry, or a double-click) — adopt its ticket and
+				// poll that instead of reporting a failure for a merge that is actually running.
+				uuid = getAsyncMergeUuidFromConflict(ex);
+				if (uuid == null) throw ex;
+			}
+
+			if (uuid == null) return false;
+
+			// The stack merges server-side one layer at a time, so this can take a while. Poll on a
+			// fixed interval and give up rather than hang forever if the ticket never settles.
+			for (let attempt = 0; attempt < maxAsyncMergePolls; attempt++) {
+				if (cancellation?.aborted) throw new CancellationError();
+
+				await new Promise(resolve => setTimeout(resolve, asyncMergePollIntervalMs));
+
+				const polled = await this.requestPreview<{ data: GitHubAsyncMergeResult }>(
+					provider,
+					token,
+					'GET /repos/{owner}/{repo}/pulls/{pull_number}/merge-async/{uuid}',
+					{
+						owner: owner,
+						repo: repo,
+						pull_number: pullNumber,
+						uuid: uuid,
+						baseUrl: options?.baseUrl,
+					},
+					scope,
+					cancellation,
+				);
+
+				if (polled.data.status === 'pending' || polled.data.status === 'enqueued') continue;
+
+				if (polled.data.status === 'failed') {
+					Logger.warn(scope, `Stacked merge failed: ${polled.data.details?.message ?? 'no reason given'}`);
+				}
+				return polled.data.status === 'merged';
+			}
+
+			Logger.warn(scope, `Timed out waiting for stacked merge of ${owner}/${repo}#${pullNumber}`);
+			return false;
+		} catch (ex) {
+			if (isCancellationError(ex)) throw ex;
+
+			Logger.error(ex, scope);
+			throw this.handleException(ex, provider, scope);
+		}
+	}
+
 	@trace({
 		args: (provider, token, nodeId, expectedSourceSha) => ({
 			provider: provider.name,
@@ -4572,7 +5016,7 @@ export class GitHubApi {
 	): Promise<boolean> {
 		const scope = getScopedLogger();
 		interface QueryResult {
-			pullRequest: GitHubPullRequestLite | null | undefined;
+			mergePullRequest: { pullRequest: { id: string } | null | undefined } | null | undefined;
 		}
 
 		let githubMergeStrategy;
@@ -4620,7 +5064,7 @@ export class GitHubApi {
 				cancellation,
 			);
 
-			return rsp?.pullRequest?.id === nodeId;
+			return rsp?.mergePullRequest?.pullRequest?.id === nodeId;
 		} catch (ex) {
 			throw this.handleException(ex, provider, scope);
 		}