@gitkraken/core-gitlens 0.5.109 → 0.5.111

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

@@ -1,6 +1,10 @@
-import type { PullRequestSearchCriteria, PullRequestStateFilter } from '../../../git/models/pullRequest.js';
-import { PullRequestFilter } from '../../../git/models/pullRequest.js';
-import { sanitizeGitHubSearchText } from './issueSearchQuery.js';
+import type {
+	PullRequestSearchCriteria,
+	PullRequestSorting,
+	PullRequestStateFilter,
+} from '../../../git/models/pullRequest.js';
+import { defaultPullRequestSort, PullRequestFilter } from '../../../git/models/pullRequest.js';
+import { sanitizeGitHubQualifierValue, sanitizeGitHubSearchText } from './issueSearchQuery.js';
 
 export type GitHubPullRequestSearchFacet = {
 	/** Stable GraphQL alias and composite-cursor key. */
@@ -8,10 +12,20 @@ export type GitHubPullRequestSearchFacet = {
 	qualifiers: string[];
 };
 
-const relationshipQualifier: Record<PullRequestFilter, string> = {
+/**
+ * The GitHub search qualifier each relationship translates to. Exhaustive over `PullRequestFilter` so a new
+ * member can't be silently unmapped.
+ *
+ * Exported because the account-wide read builds its own facets from the same vocabulary (see
+ * `GitHubIntegrationBase.getProviderMyPullRequestsForUser`). Kept as ONE declaration rather than a copy per
+ * caller: the exhaustive `Record` makes a missing key a compile error, but nothing would catch two copies
+ * disagreeing on a qualifier STRING, and a wrong qualifier is a read that quietly answers a different question.
+ */
+export const gitHubPullRequestRelationshipQualifiers: Record<PullRequestFilter, string> = {
 	[PullRequestFilter.Author]: 'author:@me',
 	[PullRequestFilter.Assignee]: 'assignee:@me',
 	[PullRequestFilter.ReviewRequested]: 'review-requested:@me',
+	[PullRequestFilter.Reviewed]: 'reviewed-by:@me',
 	[PullRequestFilter.Mention]: 'mentions:@me',
 };
 
@@ -19,6 +33,7 @@ const relationshipAlias: Record<PullRequestFilter, string> = {
 	[PullRequestFilter.Author]: 'author',
 	[PullRequestFilter.Assignee]: 'assignee',
 	[PullRequestFilter.ReviewRequested]: 'reviewRequested',
+	[PullRequestFilter.Reviewed]: 'reviewed',
 	[PullRequestFilter.Mention]: 'mention',
 };
 
@@ -29,6 +44,30 @@ const stateAlias: Record<PullRequestStateFilter, string> = {
 	all: 'All',
 };
 
+/**
+ * How each orderable key becomes a GitHub `sort:` qualifier.
+ *
+ * A literal `Record` over the union rather than a derived transform, for the same reason the relationship tables
+ * are: adding a sort field without deciding its qualifier fails the build instead of quietly emitting a search
+ * with no ordering constraint — the one failure mode the ordering contract exists to prevent, and the one a
+ * caller cannot detect from the result.
+ *
+ * `updated:desc` maps to the bare `sort:updated`, not `sort:updated-desc`. The two are the same query to GitHub,
+ * but the bare form is what this read has always emitted, so keeping it makes the default byte-identical to
+ * today's query — matching `toGitHubIssueSortQualifier`. Do not "normalize" it.
+ */
+export const gitHubPullRequestSortQualifiers: Partial<Record<PullRequestSorting, string>> = {
+	'created:asc': 'sort:created-asc',
+	'created:desc': 'sort:created-desc',
+	'updated:asc': 'sort:updated-asc',
+	'updated:desc': 'sort:updated',
+};
+
+/** The `sort:` qualifier for a key, or `undefined` when there is no key or GitHub can't express it. */
+export function toGitHubPullRequestSortQualifier(sort: PullRequestSorting | undefined): string | undefined {
+	return sort != null ? gitHubPullRequestSortQualifiers[sort] : undefined;
+}
+
 function stateQualifiers(state: PullRequestStateFilter): string[] {
 	switch (state) {
 		case 'closed':
@@ -62,18 +101,53 @@ export function toGitHubPullRequestSearchFacets(
 		: ['open'];
 	const states: PullRequestStateFilter[] = requestedStates.includes('all') ? ['all'] : requestedStates;
 	const text = criteria?.text != null ? sanitizeGitHubSearchText(criteria.text) : '';
+	// Ordering is part of the contract, not an option: without an explicit `sort:` GitHub answers in relevance
+	// order, so which rows land inside the result ceiling would shift with its ranking even when nothing changed
+	// upstream. A key GitHub can't express is REFUSED here, not approximated with a fallback order — a silent
+	// `sort:updated` substitute would emit one order in the query while the merged-page comparator applied another
+	// (or none for an unknown field), which is exactly the "the N most recent are what you get" promise the ceiling
+	// contract cannot keep under a guessed order. Unreachable through the facade — every key is validated against
+	// `githubPullRequestSearchCapabilities.sorts` first — so this guards the direct callers of this exported builder
+	// and of `GitHubApi.searchPullRequestsPage`.
+	//
+	// Deliberately STRICTER than the issue path, which drops an inexpressible qualifier and searches on
+	// (`toGitHubIssueSearchQualifiers` pushes `toGitHubIssueSortQualifier`'s result only when it is non-null). The
+	// two reads differ in what that costs: an issue search is served by whichever facets the provider ordered, while
+	// this one hands its merged page to `getPullRequestComparator`, so a dropped qualifier here means the query and
+	// the comparator disagree about the order the ceiling was applied under. Refusing is the only answer that
+	// cannot lie about which rows were reachable.
+	const sort = criteria?.sort ?? defaultPullRequestSort;
+	const sortQualifier = toGitHubPullRequestSortQualifier(sort);
+	if (sortQualifier == null) {
+		throw new Error(`GitHub cannot order a pull request search by '${sort}'`);
+	}
+
+	// Facet-independent, unlike the relationship/state qualifiers below — build once and share.
+	const dateQualifiers: string[] = [];
+	const pushDate = (value: string | undefined, toQualifier: (sanitized: string) => string): void => {
+		if (value == null) return;
+
+		const sanitized = sanitizeGitHubQualifierValue(value);
+		if (sanitized.length > 0) {
+			dateQualifiers.push(toQualifier(sanitized));
+		}
+	};
+	pushDate(criteria?.updatedAfter, v => `updated:>=${v}`);
+	pushDate(criteria?.createdAfter, v => `created:>=${v}`);
 
 	return relationships.flatMap(relationship =>
 		states.map(state => ({
 			alias: `${relationship != null ? relationshipAlias[relationship] : 'scope'}${stateAlias[state]}`,
 			qualifiers: [
 				'is:pr',
-				...(relationship != null ? [relationshipQualifier[relationship]] : []),
+				...(relationship != null ? [gitHubPullRequestRelationshipQualifiers[relationship]] : []),
 				...stateQualifiers(state),
+				// `!= null`, not truthy: `draft:false` narrows to ready-for-review PRs just as `draft:true` narrows to drafts.
+				...(criteria?.draft != null ? [`draft:${criteria.draft}`] : []),
 				...(criteria?.includeArchived === true ? [] : ['archived:false']),
 				...(text.length > 0 ? [text] : []),
-				// Contract, not an option: a capped result is the N most recently updated only under this order.
-				'sort:updated',
+				...dateQualifiers,
+				sortQualifier,
 			],
 		})),
 	);

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

@@ -2,7 +2,7 @@ import type { Endpoints } from '@octokit/types';
 import { GitFileIndexStatus } from '../../git/models/fileStatus.js';
 import type { IssueLabel } from '../../git/models/issue.js';
 import { Issue, RepositoryAccessLevel } from '../../git/models/issue.js';
-import type { PullRequestMember, PullRequestState } from '../../git/models/pullRequest.js';
+import type { PullRequestMember, PullRequestStackInfo, PullRequestState } from '../../git/models/pullRequest.js';
 import {
 	PullRequest,
 	PullRequestMergeableState,
@@ -165,6 +165,20 @@ export interface GitHubPullRequestLite extends Omit<GitHubIssueOrPullRequest, '_
 		url: string;
 		viewerPermission: GitHubViewerPermission;
 	};
+
+	/** Only selected against github.com — GitHub Enterprise Server schemas lag and reject the field. */
+	stack?: GitHubPullRequestStack | null;
+	/** Only selected against github.com — see `stack`. */
+	stackEntry?: { position: number } | null;
+}
+
+/** GitHub's stacked-pull-request object. Read-only; all stack mutations are REST-only. */
+export interface GitHubPullRequestStack {
+	id: string;
+	number: number;
+	size: number;
+	/** The branch the bottom of the stack targets — the stack's trunk. */
+	baseRefName: string;
 }
 
 export interface GitHubIssue extends Omit<GitHubIssueOrPullRequest, '__typename'> {
@@ -194,21 +208,32 @@ export type GitHubPullRequestMergeableState = 'MERGEABLE' | 'CONFLICTING' | 'UNK
 export type GitHubPullRequestStatusCheckRollupState = 'SUCCESS' | 'FAILURE' | 'PENDING' | 'EXPECTED' | 'ERROR';
 export type GitHubPullRequestReviewState = 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED' | 'PENDING';
 
+type GitHubPullRequestReview = {
+	id: string;
+	author: GitHubMember | null;
+	state: GitHubPullRequestReviewState;
+	commit?: { oid: string } | null;
+};
+
 export interface GitHubPullRequest extends GitHubPullRequestLite {
 	additions: number;
 	assignees: {
 		nodes: GitHubMember[];
 	};
+	changedFiles: number;
 	checksUrl: string;
 	deletions: number;
 	mergeable: GitHubPullRequestMergeableState;
 	reviewDecision: GitHubPullRequestReviewDecision;
 	latestReviews: {
-		nodes: {
-			author: GitHubMember | null;
-			state: GitHubPullRequestReviewState;
-		}[];
+		nodes: GitHubPullRequestReview[];
 	};
+	/**
+	 * The current user's own latest review. `latestReviews` is capped, so on a heavily-reviewed pull request
+	 * the viewer's own review can fall outside that window — which is exactly the row a "needs my review"
+	 * surface is asking about.
+	 */
+	viewerLatestReview: GitHubPullRequestReview | null;
 	reviewRequests: {
 		nodes: {
 			asCodeOwner: boolean;
@@ -216,6 +241,7 @@ export interface GitHubPullRequest extends GitHubPullRequestLite {
 		}[];
 	};
 	commits: {
+		totalCount: number;
 		nodes: {
 			commit: {
 				statusCheckRollup: {
@@ -240,7 +266,13 @@ export type GitHubViewerPermission =
 function fromGitHubMemberOrGhost(member: GitHubMember | null | undefined): PullRequestMember {
 	if (member == null) return { id: 'ghost', name: 'ghost' };
 
-	return { id: member.login, name: member.login, avatarUrl: member.avatarUrl, url: member.url };
+	return {
+		id: member.login,
+		name: member.login,
+		username: member.login,
+		avatarUrl: member.avatarUrl,
+		url: member.url,
+	};
 }
 
 export function fromGitHubPullRequestLite(pr: GitHubPullRequestLite, provider: Provider): PullRequest {
@@ -289,6 +321,7 @@ export function fromGitHubPullRequestLite(pr: GitHubPullRequestLite, provider: P
 			isCrossRepository: pr.isCrossRepository,
 		},
 		pr.isDraft,
+		// The lite fragment selects nothing between `isDraft` and `stack`.
 		undefined, // additions
 		undefined, // deletions
 		undefined, // commentsCount
@@ -300,10 +333,26 @@ export function fromGitHubPullRequestLite(pr: GitHubPullRequestLite, provider: P
 		undefined, // statusCheckRollupState
 		undefined, // project
 		undefined, // version
+		undefined, // commitCount
+		fromGitHubPullRequestStack(pr),
+		undefined, // filesChanged
 		pr.body ?? undefined,
 	);
 }
 
+/** Both fields are absent on GitHub Enterprise Server (never selected) and `null` when unstacked. */
+function fromGitHubPullRequestStack(pr: GitHubPullRequestLite): PullRequestStackInfo | undefined {
+	if (pr.stack == null || pr.stackEntry == null) return undefined;
+
+	return {
+		id: pr.stack.id,
+		number: pr.stack.number,
+		size: pr.stack.size,
+		position: pr.stackEntry.position,
+		baseRef: pr.stack.baseRefName,
+	};
+}
+
 export function fromGitHubIssueOrPullRequestState(state: GitHubPullRequestState): PullRequestState {
 	return state === 'MERGED' ? 'merged' : state === 'CLOSED' ? 'closed' : 'opened';
 }
@@ -401,6 +450,19 @@ export function fromGitHubPullRequestStatusCheckRollupState(
 }
 
 export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider): PullRequest {
+	// `latestReviews` is capped, so keep the viewer's own review even when it falls outside that window, deduped
+	// by review id since the two selections overlap. Unsubmitted drafts are dropped from the union rather than
+	// from the viewer's side alone: `PENDING` is in GitHub's review-state enum on both selections, and the field
+	// this feeds is documented as reviews already SUBMITTED — a draft there tells a "needs my review" consumer
+	// the review is done, and a reviewer with a submitted review plus a draft would get two conflicting rows.
+	const viewerLatestReview = pr.viewerLatestReview;
+	const latestReviews = [
+		...pr.latestReviews.nodes,
+		...(viewerLatestReview != null && !pr.latestReviews.nodes.some(r => r.id === viewerLatestReview.id)
+			? [viewerLatestReview]
+			: []),
+	].filter(review => review.state !== 'PENDING');
+
 	return new PullRequest(
 		provider,
 		fromGitHubMemberOrGhost(pr.author),
@@ -459,6 +521,7 @@ export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider)
 							reviewer: {
 								id: r.requestedReviewer.login,
 								name: r.requestedReviewer.login,
+								username: r.requestedReviewer.login,
 								avatarUrl: r.requestedReviewer.avatarUrl,
 								url: r.requestedReviewer.url,
 							},
@@ -467,19 +530,24 @@ export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider)
 					: undefined,
 			)
 			.filter(<T>(r?: T): r is T => Boolean(r)),
-		pr.latestReviews.nodes.map(r => ({
+		latestReviews.map(r => ({
 			reviewer: fromGitHubMemberOrGhost(r.author),
 			state: fromGitHubPullRequestReviewState(r.state),
+			commitOid: r.commit?.oid,
 		})),
 		pr.assignees.nodes.map(r => ({
 			id: r.login,
 			name: r.login,
+			username: r.login,
 			avatarUrl: r.avatarUrl,
 			url: r.url,
 		})),
 		fromGitHubPullRequestStatusCheckRollupState(pr.commits.nodes?.[0]?.commit.statusCheckRollup?.state),
 		undefined, // project
 		undefined, // version
+		pr.commits.totalCount,
+		fromGitHubPullRequestStack(pr),
+		pr.changedFiles,
 		pr.body ?? undefined,
 	);
 }
@@ -505,12 +573,14 @@ export function fromGitHubIssue(value: GitHubIssue, provider: Provider): Issue {
 			: {
 					id: value.author.login,
 					name: value.author.login,
+					username: value.author.login,
 					avatarUrl: value.author.avatarUrl,
 					url: value.author.url,
 				},
 		value.assignees.nodes.map(assignee => ({
 			id: assignee.login,
 			name: assignee.login,
+			username: assignee.login,
 			avatarUrl: assignee.avatarUrl,
 			url: assignee.url,
 		})),

package/src/plus/git-github/providers/github/status.ts

@@ -44,6 +44,7 @@ export class StatusGitSubProvider implements GitStatusSubProvider {
 			unstaged?: boolean;
 			untracked?: boolean;
 			throwOnError?: boolean;
+			priority?: GitCommandPriority;
 		},
 		_cancellation?: AbortSignal,
 	): Promise<boolean> {

package/src/plus/integrations/context.ts

@@ -155,6 +155,10 @@ export interface IntegrationCacheProvider {
 		cacheable: Cacheable<Account>,
 		options?: CacheExpiryOptions & { connectionId?: string; etag?: string },
 	): CacheResult<Account>;
+	/** Evicts every cached pull request. A merge invalidates more than the merged pull request alone —
+	 *  a stacked merge lands every layer below it and retargets every layer above — and no caller can
+	 *  name that full set. */
+	deletePullRequests(): void;
 }
 
 /**

package/src/plus/integrations/index.ts

@@ -73,6 +73,8 @@ const uncachedIntegrationCacheProvider: IntegrationCacheProvider = {
 	getIssueOrPullRequest: (_id, _type, _resource, _integration, loader) => loadUncached(loader),
 	getIssue: (_id, _resource, _integration, loader) => loadUncached(loader),
 	getCurrentAccount: (_integration, loader) => loadUncached(loader),
+	// Nothing is cached, so there is nothing to evict.
+	deletePullRequests: () => {},
 };
 
 function toIntegrationCacheProvider(cache: IntegrationManagerCacheProvider | undefined): IntegrationCacheProvider {

package/src/plus/integrations/integrationService.ts

@@ -77,8 +77,13 @@ import { providersMetadata } from './providers/models.js';
 import type { ProvidersApi } from './providers/providersApi.js';
 import { broadenIssues } from './reads/broaden.js';
 import type { RepositoryResolutionContext } from './reads/context.js';
-import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
-import { countIssues } from './reads/counts.js';
+import type {
+	IssueCountResult,
+	IssueCountScope,
+	PullRequestCountResult,
+	PullRequestCountScope,
+} from './reads/counts.js';
+import { countIssues, countPullRequests } from './reads/counts.js';
 import type { SupportedFilters } from './reads/filters.js';
 import { getSupportedFilters } from './reads/filters.js';
 import { listOrgs, listProjects, listRepos } from './reads/hierarchy.js';
@@ -1147,6 +1152,24 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		return countIssues(this, options);
 	}
 
+	/**
+	 * How many pull requests match each scope, without fetching any — the PR twin of {@link countIssues}. See
+	 * {@link IntegrationManager.countPullRequests} for the cost model, the per-scope isolation rules, and why
+	 * `count: undefined` must not be rendered as zero.
+	 */
+	async countPullRequests(options: {
+		providerId: IntegrationIds;
+		scopes: readonly PullRequestCountScope[];
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	}): Promise<ProviderResult<PullRequestCountResult>> {
+		return countPullRequests(this, options);
+	}
+
 	/**
 	 * Reads the user's issues from an issue-tracker provider (Jira/Linear/Trello), whose issues live under
 	 * resource → project (not repos), so they can't go through {@link listIssuesPage} (git-host, repo-scoped).

package/src/plus/integrations/manager.ts

@@ -9,7 +9,12 @@ import type { ConfiguredIntegrationsChangeEvent } from './authentication/configu
 import type { ConfiguredIntegrationDescriptor } from './authentication/models.js';
 import type { IntegrationIds } from './constants.js';
 import type { IssueFilter, IssueSorting, PullRequestFilter } from './providerFilters.js';
-import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
+import type {
+	IssueCountResult,
+	IssueCountScope,
+	PullRequestCountResult,
+	PullRequestCountScope,
+} from './reads/counts.js';
 import type { SupportedFilters } from './reads/filters.js';
 import type {
 	ConnectionStateChangeEvent,
@@ -156,6 +161,22 @@ type PullRequestSweepCommonOptions = {
 	 * This extends the provider-native result; it is not a narrowing filter.
 	 */
 	includeReviewRequested?: boolean;
+	/**
+	 * Account-wide only: fetch the full PR projection (review decision, review requests, latest reviews)
+	 * instead of the default summary/lite one. Opt-in because it enlarges every account-wide page; callers
+	 * that classify by review state (e.g. a "needs my review" surface) set it, others keep the lean read.
+	 *
+	 * GitHub/GHE only today — no other provider's account-wide read has a projection switch, so they return
+	 * their native shape regardless. A cross-provider sweep therefore gets reviews from GitHub targets and
+	 * whatever the others natively carry; it is a breadth request, not a guarantee, so it does not refuse
+	 * (unlike `filters`, where dropping a member would change the requested set).
+	 *
+	 * Projection only: it cannot change which pull requests come back. Every GitHub account-wide read goes through
+	 * the same search whether or not it is set, so the Launchpad ignored-repository and organization qualifiers
+	 * (and the per-facet result ceiling) apply the same either way. What it costs is the reduced page size, and a
+	 * document whose weight scales with the number of relationship × state facets in flight.
+	 */
+	includeReviews?: boolean;
 	forceSync?: boolean;
 	maxPages?: number;
 	/**
@@ -355,10 +376,17 @@ export interface IntegrationManager {
 	 * GitHub's mismatched `involves:@me`. Omit relationships only with a repository/organization scope to search
 	 * every PR there.
 	 *
-	 * Results are always ordered most-recently-updated-first. If the provider's result ceiling is reached, the
-	 * request still succeeds and carries a warning omission with `totalCount`, `limit`, and `recovery: 'none'`.
-	 * `totalCount` is the largest provider-reported pre-ceiling facet count, not the reachable or returned row
-	 * count; this mirrors the per-search ceiling's own unit.
+	 * **Ordering is `criteria.sort`**, most-recently-updated-first when omitted. It is validated like every other
+	 * criterion — a key not in `getSupportedFilters().pullRequestSearch.sorts` refuses the whole read rather than
+	 * falling back, because at a bounded result window another order reaches another subset. The page is a union of
+	 * the provider's relationship × state facets, so it is re-ordered as a whole rather than served as concatenated
+	 * per-facet runs. Changing the sort invalidates a threaded cursor (it is part of the cursor's fingerprint,
+	 * alongside the text and the scope); drop the cursor when you change the order.
+	 *
+	 * If the provider's result ceiling is reached, the request still succeeds and carries a warning omission with
+	 * `totalCount`, `limit`, `sort`, and `recovery: 'none'`. `totalCount` is the largest provider-reported
+	 * pre-ceiling facet count, not the reachable or returned row count; this mirrors the per-search ceiling's own
+	 * unit.
 	 *
 	 * Check `getSupportedFilters().pullRequestSearch` before calling. A provider that reports no relationships
 	 * refuses the read rather than returning a page that never honored the criteria or scope.
@@ -518,6 +546,23 @@ export interface IntegrationManager {
 		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
 		domain?: string;
 	}): Promise<ProviderResult<IssueCountResult>>;
+	/**
+	 * How many pull requests match each scope, fetching none of them — the PR twin of {@link countIssues}, behind a
+	 * "this will fetch ~N pull requests" preview and a live count next to an unapplied filter. Same cost model,
+	 * per-scope isolation, `key`-echo, and `count: undefined` ≠ zero rule as the issue count; GitHub/GHE only.
+	 *
+	 * The one PR-specific difference: a scope's `states` are counted as independent searches, so the reported count
+	 * is the LARGEST of them (the same total {@link searchPullRequestsPage} surfaces), not their sum. Several states
+	 * in one scope are therefore fine; only several relationships are refused — one relationship per scope, see
+	 * {@link PullRequestCountScope}.
+	 */
+	countPullRequests(options: {
+		providerId: IntegrationIds;
+		scopes: readonly PullRequestCountScope[];
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderResult<PullRequestCountResult>>;
 	/** Issue trackers are cloud-only, so this read takes no `domain`. */
 	listIssueTrackerIssuesPage(options: {
 		providerId: IntegrationIds;

package/src/plus/integrations/models/gitHostIntegration.ts

@@ -7,11 +7,13 @@ import type {
 	PullRequest,
 	PullRequestMergeMethod,
 	PullRequestSearchCriteria,
+	PullRequestStackInfo,
 	PullRequestStateFilter,
 } from '../../../git/models/pullRequest.js';
 import type { RepositoryMetadata } from '../../../git/models/repositoryMetadata.js';
 import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
 import type { PullRequestUrlIdentity } from '../../../git/utils/pullRequest.utils.js';
+import { isCancellationError } from '../../../utils/cancellation.js';
 import { gate } from '../../../utils/decorators/gate.js';
 import { trace } from '../../../utils/decorators/log.js';
 import { first } from '../../../utils/iterable.js';
@@ -267,6 +269,14 @@ export abstract class GitHostIntegration<
 		connectionId?: string;
 	}): Promise<ProviderRepository | undefined>;
 
+	/** Stack membership for every stacked pull request in the repository, keyed by pull request number.
+	 *  Only hosts with a stacks concept implement this (currently GitHub). */
+	getStacksByPullRequestNumber?(
+		owner: string,
+		repo: string,
+		cancellation?: AbortSignal,
+	): Promise<Map<number, PullRequestStackInfo> | undefined>;
+
 	protected abstract getProviderDefaultBranch(
 		{ accessToken }: ProviderAuthenticationSession,
 		repo: T,
@@ -514,7 +524,11 @@ export abstract class GitHostIntegration<
 		options?: { cursor?: string },
 	): Promise<ProviderHierarchyResult<ProviderRepository> | undefined>;
 
-	async mergePullRequest(pr: PullRequest, options?: { mergeMethod?: PullRequestMergeMethod }): Promise<boolean> {
+	async mergePullRequest(
+		pr: PullRequest,
+		options?: { mergeMethod?: PullRequestMergeMethod },
+		cancellation?: AbortSignal,
+	): Promise<boolean> {
 		const scope = getScopedLogger();
 
 		const connected = this.maybeConnected ?? (await this.isConnected());
@@ -523,12 +537,20 @@ export abstract class GitHostIntegration<
 		await this.refreshSessionIfExpired(scope);
 
 		try {
-			const result = await this.mergeProviderPullRequest(this._session!, pr, options);
+			const result = await this.mergeProviderPullRequest(this._session!, pr, options, cancellation);
 			this.resetRequestExceptionCount('mergePullRequest');
 			return result;
 		} catch (ex) {
+			if (isCancellationError(ex)) return false;
+
 			this.handleProviderException('mergePullRequest', ex, { scope: scope });
 			return false;
+		} finally {
+			// A merge attempt just changed the state of more than this pull request on the server (a
+			// stacked merge lands every layer below and retargets every layer above) whether it succeeded
+			// or failed partway through — so cached pull requests can't be trusted either way. Without
+			// this, ref pills and branch enrichment keep serving the pre-merge object until its expiry.
+			this.ctx.cache.deletePullRequests();
 		}
 	}
 
@@ -536,6 +558,7 @@ export abstract class GitHostIntegration<
 		session: ProviderAuthenticationSession,
 		pr: PullRequest,
 		options?: { mergeMethod?: PullRequestMergeMethod },
+		cancellation?: AbortSignal,
 	): Promise<boolean>;
 
 	@trace()
@@ -1755,6 +1778,35 @@ export abstract class GitHostIntegration<
 		cancellation?: AbortSignal,
 	): Promise<(number | undefined)[] | undefined>;
 
+	/** The PR twin of {@link countIssuesResult}: counts each scope's pull requests, transferring none. */
+	async countPullRequestsResult(
+		scopes: readonly { repos?: ProviderRepoInput[]; org?: string; criteria?: PullRequestSearchCriteria }[],
+		cancellation?: AbortSignal,
+		connectionId?: string,
+	): Promise<IntegrationResult<(number | undefined)[] | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		const start = performance.now();
+		try {
+			const counts = await this.countProviderPullRequests?.(session, scopes, cancellation);
+			this.resetRequestExceptionCount('countPullRequests');
+			return { value: counts, duration: performance.now() - start };
+		} catch (ex) {
+			this.handleProviderException('countPullRequests', ex, { scope: scope, connectionId: connectionId });
+			return { error: toError(ex), duration: performance.now() - start };
+		}
+	}
+
+	/** OPTIONAL, like {@link countProviderIssues}: only a provider that can count without fetching implements it. */
+	protected countProviderPullRequests?(
+		session: ProviderAuthenticationSession,
+		scopes: readonly { repos?: ProviderRepoInput[]; org?: string; criteria?: PullRequestSearchCriteria }[],
+		cancellation?: AbortSignal,
+	): Promise<(number | undefined)[] | undefined>;
+
 	getPullRequestIdentityFromMaybeUrl(search: string): PullRequestUrlIdentity | undefined {
 		return this.getProviderPullRequestIdentityFromMaybeUrl?.(search);
 	}

package/src/plus/integrations/models/integration.ts

@@ -81,6 +81,7 @@ type SyncReqUsecase = Exclude<
 	| 'getResourcesForUser'
 	| 'getSshSigningKeysForEmails'
 	| 'countIssues'
+	| 'countPullRequests'
 	| 'mergePullRequest'
 	| 'searchIssuesPage'
 	| 'searchPullRequestsPage'
@@ -928,7 +929,11 @@ export abstract class IntegrationBase<
 	}
 
 	@trace()
-	async getPullRequest(resource: T, id: string): Promise<PullRequest | undefined> {
+	async getPullRequest(
+		resource: T,
+		id: string,
+		options?: { expiryOverride?: boolean | number },
+	): Promise<PullRequest | undefined> {
 		const scope = getScopedLogger();
 
 		const connected = this.maybeConnected ?? (await this.isConnected());
@@ -936,18 +941,24 @@ export abstract class IntegrationBase<
 
 		await this.refreshSessionIfExpired(scope);
 
-		const pr = await this.ctx.cache.getPullRequest(id, resource, this, () => ({
-			value: (async () => {
-				try {
-					const result = await this.getProviderPullRequest?.(this._session!, resource, id);
-					this.resetRequestExceptionCount('getPullRequest');
-					return result;
-				} catch (ex) {
-					this.handleProviderException('getPullRequest', ex, { scope: scope });
-					return undefined;
-				}
-			})(),
-		}));
+		const pr = await this.ctx.cache.getPullRequest(
+			id,
+			resource,
+			this,
+			() => ({
+				value: (async () => {
+					try {
+						const result = await this.getProviderPullRequest?.(this._session!, resource, id);
+						this.resetRequestExceptionCount('getPullRequest');
+						return result;
+					} catch (ex) {
+						this.handleProviderException('getPullRequest', ex, { scope: scope });
+						return undefined;
+					}
+				})(),
+			}),
+			{ expiryOverride: options?.expiryOverride },
+		);
 		return pr;
 	}
 

package/src/plus/integrations/providerFilters.ts

@@ -28,4 +28,9 @@ export type {
  * same dependency-direction reason as the issue-search model above: provider API clients translate them below
  * this package and cannot import this facade.
  */
-export type { PullRequestSearchCapabilities, PullRequestSearchCriteria } from '../../git/models/pullRequest.js';
+export type {
+	PullRequestSearchCapabilities,
+	PullRequestSearchCriteria,
+	PullRequestSortField,
+	PullRequestSorting,
+} from '../../git/models/pullRequest.js';