@gitkraken/core-gitlens 0.5.108 → 0.5.110

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

@@ -11,7 +11,8 @@ import {
 } from '../../../git/errors.js';
 import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js';
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
-import type { Issue, IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
+import type { Issue, IssueSearchCriteria, IssueShape, IssueSorting } from '../../../git/models/issue.js';
+import { defaultIssueSort } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest } from '../../../git/models/issueOrPullRequest.js';
 import type {
 	PullRequest,
@@ -20,13 +21,15 @@ 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';
 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,
@@ -77,11 +80,21 @@ import {
 	gitHubIssueSearchRelationships,
 	toGitHubIssueSearchQualifiers,
 	toGitHubIssueSearchScopeQualifiers,
+	toGitHubIssueSortQualifier,
 } from './issueSearchQuery.js';
 import { toGitHubPullRequestSearchFacets } from './pullRequestSearchQuery.js';
 import type { GitHubTokenInfo } from './token.js';
 
 const emptyPagedResult: PagedResult<any> = Object.freeze({ values: [] });
+/**
+ * What an issue-search cursor records when the caller asked for no ordering at all.
+ *
+ * A sentinel rather than an omitted field, because omitted already means something else and more important: a
+ * cursor persisted before ordering existed. Distinguishing the two is what lets an old cursor keep resuming while
+ * a genuine change from unordered to ordered is still refused. Not an `IssueSorting`, so it can never collide
+ * with one.
+ */
+const unsortedCursorSort = 'unsorted' as const;
 const emptyBlameResult: GitHubBlame = Object.freeze({ ranges: [] });
 
 // Transient gateway/network failures (e.g. an upstream `502 Bad Gateway`) are worth a few quick
@@ -98,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
@@ -247,6 +267,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
@@ -266,14 +304,12 @@ mergedBy {
 reviewDecision
 latestReviews(first: 25) {
 	nodes {
-		author {
-			login
-			avatarUrl(size: $avatarSize)
-			url
-		}
-		state
+		${gqlPullRequestReviewFragment}
 	}
 }
+viewerLatestReview {
+	${gqlPullRequestReviewFragment}
+}
 reviewRequests(first: 25) {
 	nodes {
 		asCodeOwner
@@ -3514,8 +3550,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.
 	 */
@@ -3546,7 +3584,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 {
@@ -3654,6 +3700,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,
@@ -3669,9 +3725,45 @@ 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;
 	}
 
+	/**
+	 * The current user's issues: authored ∪ assigned ∪ mentioned, each its own aliased search behind one composite
+	 * cursor. Bound to `@me` by construction, unlike {@link searchIssuesPage}.
+	 *
+	 * Ordering is OPT-IN here, and that asymmetry with {@link searchIssuesPage} is deliberate: this read has never
+	 * requested a sort, so GitHub has always answered it in relevance order. Emitting a default would change which
+	 * issues its already-shipped consumers see, so an omitted `sort` still emits no `sort:` qualifier at all and
+	 * keeps today's result. Pass one to get a defined order — which is also what makes a page budget meaningful,
+	 * since relevance ranking can shift under an unchanged upstream.
+	 */
 	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
 	async searchMyIssues(
 		provider: Provider,
@@ -3685,6 +3777,8 @@ export class GitHubApi {
 			includeBody?: boolean;
 			includeAllAssignees?: boolean;
 			cursor?: string;
+			/** Requested order. Omitted leaves GitHub's relevance order, which is what this read has always served. */
+			sort?: IssueSorting;
 			/**
 			 * Which of the three "my issues" searches to run. Omitted runs all three (GitHub's own definition of
 			 * "mine": authored ∪ assigned ∪ mentioned). Supplied, only the `true` ones run — so a caller wanting
@@ -3710,7 +3804,10 @@ export class GitHubApi {
 			search += `${repo}${options.repos.join(repo)}`;
 		}
 
-		const baseFilters = 'type:issue is:open archived:false';
+		// A requested sort goes through the same table `searchIssuesPage` uses, so the two GitHub issue reads can't
+		// diverge the first time a key is added. Omitted appends nothing — see this method's contract above.
+		const sortQualifier = toGitHubIssueSortQualifier(options?.sort);
+		const baseFilters = ['type:issue is:open archived:false', sortQualifier].filter(Boolean).join(' ');
 		// `includeAllAssignees` broadens the assigned category from "assigned to me" to "assigned to anyone"
 		// (`assignee:*` is GitHub's has-any-assignee qualifier). Authored/mentioned stay bound to `@me` — they're
 		// user-relative by definition, so an all-assignees read still only surfaces the current user's authored
@@ -3748,7 +3845,24 @@ export class GitHubApi {
 			searches.push({ alias: 'authored', query: `${search} ${baseFilters} author:@me`.trim() });
 		}
 
-		return this.searchIssuesByAlias(provider, token, searches, options, cancellation);
+		// Field by field, like `searchIssuesPage`: `options` also carries `repos`/`includeAllAssignees`/`categories`,
+		// already folded into `searches[].query` above and undeclared by the callee.
+		return this.searchIssuesByAlias(
+			provider,
+			token,
+			searches,
+			{
+				baseUrl: options?.baseUrl,
+				avatarSize: options?.avatarSize,
+				includeBody: options?.includeBody,
+				cursor: options?.cursor,
+				sort: options?.sort,
+				// This read emitted no `sort:` qualifier at all before ordering existed, so a cursor with no
+				// recorded key came out of a relevance-ordered walk.
+				legacySort: unsortedCursorSort,
+			},
+			cancellation,
+		);
 	}
 
 	/**
@@ -3756,9 +3870,15 @@ export class GitHubApi {
 	 * relationship to the current user. The issue counterpart of {@link searchMyPullRequestsPage}, and distinct
 	 * from {@link searchMyIssues}, which is permanently bound to `@me`.
 	 *
-	 * Ordering is part of the contract, not an option: always `sort:updated` (most recently updated first). A
-	 * consumer's "show the N most recent" policy at GitHub's result ceiling is only correct under a guaranteed
-	 * order, and an option would let a caller pick relevance order and then truncate to an arbitrary subset.
+	 * Ordering is `criteria.sort`, defaulting to most-recently-updated-first — the order this read served before
+	 * ordering was an option, so an omitted `sort` emits the identical query. What is NOT optional is that SOME
+	 * order is always requested: without one GitHub answers in relevance order, and at the result ceiling that
+	 * makes which rows are reachable a function of GitHub's ranking rather than of the request. A key GitHub can't
+	 * express (`closed`, `priority`, …) is refused by the facade before the request, not silently downgraded.
+	 *
+	 * With more than one relationship the page is a UNION of several searches, each ordered by the provider; the
+	 * merged page is re-sorted here so the whole page honors the requested key. Across pages the order is still
+	 * per-alias — see {@link searchIssuesByAlias}.
 	 *
 	 * Each requested relationship becomes its own aliased search, unioned and deduped by url; with none, a single
 	 * search runs over the scope alone. `criteria.text` and the other free-form values are sanitized so user input
@@ -3780,9 +3900,12 @@ export class GitHubApi {
 		},
 		cancellation?: AbortSignal,
 	): Promise<AliasedIssueSearchResult | undefined> {
+		// Resolved once: the emitted qualifier, the merged page's comparator and the cursor's fingerprint must all
+		// be the same key, which is what `effectiveIssueSort` exists to guarantee.
+		const sort = effectiveIssueSort(options?.criteria?.sort);
 		const base = [
 			...toGitHubIssueSearchScopeQualifiers(options?.org, options?.repos),
-			...toGitHubIssueSearchQualifiers(options?.criteria),
+			...toGitHubIssueSearchQualifiers(options?.criteria, sort),
 		].join(' ');
 
 		// One aliased search per relationship, OR-ed by union. They can't be one query: GitHub AND-s qualifiers,
@@ -3796,7 +3919,27 @@ export class GitHubApi {
 				}))
 			: [{ alias: 'matched', query: base }];
 
-		return this.searchIssuesByAlias(provider, token, searches, options, cancellation);
+		// Forwarded field by field rather than spread: `options` also carries `repos`/`org`/`criteria`, which are
+		// already baked into `searches[].query` above and which the callee declares nothing about. `sort` is the
+		// EFFECTIVE key, since the merged page and the cursor's fingerprint must both use the one the query used.
+		return this.searchIssuesByAlias(
+			provider,
+			token,
+			searches,
+			{
+				baseUrl: options?.baseUrl,
+				avatarSize: options?.avatarSize,
+				includeBody: options?.includeBody,
+				cursor: options?.cursor,
+				pageSize: options?.pageSize,
+				sort: sort,
+				// This read has always emitted `sort:updated`, which is `defaultIssueSort` — so a cursor with no
+				// recorded key came out of a walk under exactly that key, and only a caller asking for a
+				// different one has to restart.
+				legacySort: defaultIssueSort,
+			},
+			cancellation,
+		);
 	}
 
 	/**
@@ -3823,9 +3966,12 @@ export class GitHubApi {
 		if (scopes.length === 0) return [];
 
 		const queries = scopes.map(s => {
+			// The same resolved key the search would use, so the count previews the query it previews. Ordering
+			// cannot change a total, but emitting a DIFFERENT qualifier string than the search does would break the
+			// parity this probe is for.
 			const qualifiers = [
 				...toGitHubIssueSearchScopeQualifiers(s.org, s.repos),
-				...toGitHubIssueSearchQualifiers(s.criteria),
+				...toGitHubIssueSearchQualifiers(s.criteria, effectiveIssueSort(s.criteria?.sort)),
 			];
 
 			// A relationship set is OR-ed across searches, which a single count can't express — the facade splits
@@ -3872,6 +4018,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.
@@ -3886,14 +4111,31 @@ export class GitHubApi {
 	 * {@link searchMyIssues} is one configuration of it (its three `@me` categories), and its alias names are
 	 * that read's published cursor keys.
 	 *
-	 * `searches` must have unique aliases, each a valid GraphQL name that is neither `page` nor `truncated` —
-	 * the composite cursor keys aliases at its top level, alongside those two reserved fields.
+	 * `searches` must have unique aliases, each a valid GraphQL name that is none of `page`, `truncated` or
+	 * `sort` — the composite cursor keys aliases at its top level, alongside those three reserved fields.
+	 *
+	 * `sort` is the order the caller asked for, which this does two things with. Each alias comes back ordered by
+	 * it (the qualifier is already in `searches[].query`), but the UNION of several aliases is not, so the merged
+	 * page is re-sorted here; and the key is recorded in the cursor, so a continuation that changed it THROWS
+	 * rather than serving a sequence with gaps and repeats. Omitted means the caller asked for no order at all
+	 * ({@link searchMyIssues}'s default), which re-sorts nothing and pins nothing.
+	 *
+	 * `legacySort` is the order the calling read produced BEFORE this field existed, and is what a cursor with no
+	 * recorded key is compared against — such a cursor is not of unknown order, it is of that read's old one.
 	 */
 	private async searchIssuesByAlias(
 		provider: Provider,
 		token: GitHubTokenInfo,
 		searches: readonly AliasedIssueSearch[],
-		options?: { baseUrl?: string; avatarSize?: number; includeBody?: boolean; cursor?: string; pageSize?: number },
+		options: {
+			baseUrl?: string;
+			avatarSize?: number;
+			includeBody?: boolean;
+			cursor?: string;
+			pageSize?: number;
+			sort?: IssueSorting;
+			legacySort: IssueSorting | typeof unsortedCursorSort;
+		},
 		cancellation?: AbortSignal,
 	): Promise<AliasedIssueSearchResult | undefined> {
 		const scope = getScopedLogger();
@@ -3914,6 +4156,16 @@ export class GitHubApi {
 		interface SearchCursor {
 			page?: number;
 			truncated?: boolean;
+			/**
+			 * The order this cursor's pages were produced under: an `IssueSorting`, or `unsortedCursorSort` when
+			 * the caller asked for none. Written as a value rather than left absent in the no-order case
+			 * specifically so that ABSENT keeps meaning "cursor from before ordering existed", which is accepted
+			 * and sealed instead of refused — a consumer's persisted cursor has to keep working across this change.
+			 *
+			 * Those three cases are the whole domain, so it is typed as them rather than as `string`: a foreign
+			 * cursor carrying something else is caught by the mismatch check either way.
+			 */
+			sort?: IssueSorting | typeof unsortedCursorSort;
 			[alias: string]: string | number | boolean | null | undefined;
 		}
 
@@ -3922,19 +4174,54 @@ export class GitHubApi {
 		// by a cursor string that reads back as page 1, restarting the walk with no error and no truncation flag.
 		// Cheap to check, and it fails at the one call that introduced the collision rather than in a consumer's
 		// persisted cursor.
-		const reserved = searches.filter(s => s.alias === 'page' || s.alias === 'truncated');
+		const reserved = searches.filter(s => s.alias === 'page' || s.alias === 'truncated' || s.alias === 'sort');
 		if (reserved.length > 0) {
 			throw new Error(
 				`Issue search alias(es) ${reserved.map(s => `'${s.alias}'`).join(', ')} collide with the composite cursor's reserved keys`,
 			);
 		}
 
+		// A key GitHub cannot express emits no `sort:` qualifier, so each alias would come back in RELEVANCE order
+		// while the union below is sorted by that key and the cursor sealed under it: an arbitrary subset,
+		// presented as ordered, resumable only into more of the same. Refused here rather than downgraded, which
+		// is the rule the whole feature is built on. Unreachable through the facade — no `supportedIssueSorts`
+		// table declares a key without a qualifier — so this guards the direct callers of the two public reads,
+		// where `title` is expressible enough to have a comparator and not enough to be a GitHub search qualifier.
+		if (options.sort != null && toGitHubIssueSortQualifier(options.sort) == null) {
+			throw new Error(`GitHub cannot order an issue search by '${options.sort}'`);
+		}
+
 		let cursor: SearchCursor | undefined;
 		if (options?.cursor != null) {
 			try {
 				cursor = JSON.parse(options.cursor) as SearchCursor;
 			} catch {}
 		}
+		// The order this request is being made under, as the cursor records it.
+		const requestedSort = options.sort ?? unsortedCursorSort;
+		// A cursor produced under a DIFFERENT order can't be resumed: every alias would continue from a position in
+		// a differently-ordered result set, so the continuation re-emits rows already seen and skips rows never
+		// seen. REFUSED rather than silently restarted from page 1, because a restart cannot be reported honestly
+		// from here: this read is cursor-only, so `resolveCurrentPage` has no page of its own to trust and echoes
+		// the `page` the caller supplied alongside the cursor — page 1's rows would be published as page N, which
+		// is the very confusion the fingerprint exists to prevent. Refusing surfaces a warning + `fetchFailed`, and
+		// the remedy ("drop the cursor") is the caller's to apply.
+		//
+		// A cursor with NO recorded sort predates this field — which is not the same as being of unknown order.
+		// Each read produced exactly one order before ordering was an option (`sort:updated` for the filtered
+		// search, relevance for `searchMyIssues`), so an absent key reads as THAT one, `legacySort`. Compared
+		// rather than waved through: the facade now resolves an omitted key to `defaultIssueSort`, so the
+		// account-wide read's query gained a `sort:updated` qualifier it did not have, and resuming a
+		// relevance-ordered cursor inside it advances each alias through a re-ordered result set — the gaps and
+		// repeats this check exists to prevent, arriving through the very case meant to keep working. A cursor
+		// whose implied key matches the request still resumes, and is sealed with the current one.
+		const cursorSort = cursor?.sort ?? options.legacySort;
+		if (cursor != null && cursorSort !== requestedSort) {
+			throw new Error(
+				`Issue search cursor was produced under sort '${cursorSort}' but '${requestedSort}' was requested; restart the read without a cursor`,
+			);
+		}
+
 		const page = Math.max(1, Math.trunc(cursor?.page ?? 1));
 		// A slot is a continuation string, `null` (exhausted), or absent. Anything else came from a malformed or
 		// foreign cursor, and is read as absent rather than threaded back into the request as a continuation.
@@ -4023,16 +4310,38 @@ export class GitHubApi {
 
 			// Dedupe by `url`, not `IssueShape.id`: for some providers `id` is a per-repository number, so an
 			// id-keyed map would collapse distinct issues across repositories.
-			const results: IterableIterator<IssueShape> = uniqueBy(
-				issues,
-				r => r.url,
-				(original, _current) => original,
-			);
+			const deduped = [
+				...uniqueBy(
+					issues,
+					r => r.url,
+					(original, _current) => original,
+				),
+			];
+
+			// Each alias arrived ordered by the server; their concatenation is not, so the merged page is ordered
+			// here. AFTER the dedupe, not before, and that ordering is load-bearing: the alias order is also the
+			// dedupe's precedence (an issue both assigned to and authored by the user surfaces as the assigned one,
+			// per `searchMyIssues`), and sorting first would hand `uniqueBy` a different first occurrence and
+			// silently change which copy wins. The pull-request path sorts BEFORE its dedupe because its facets
+			// carry no such precedence — the difference is deliberate, not an inconsistency to tidy up.
+			//
+			// A comparator is always available for a key GitHub declares (`created`/`updated`/`comments`/
+			// `reactions` are all on `IssueShape`), so `undefined` here means the capability table has outrun this
+			// read; leave the provider's per-alias order rather than inventing one.
+			//
+			// Counted over `active`, not `searches`: continuations exhaust aliases one at a time, so a later page of
+			// a three-category walk can come from ONE surviving search — already ordered by the server. Re-sorting
+			// it could only reproduce that order, while hiding a provider that ignored the qualifier.
+			const comparator = options?.sort != null ? getIssueComparator(options.sort) : undefined;
+			if (comparator != null && active.length > 1) {
+				deduped.sort(comparator);
+			}
 
 			// Every alias gets a slot, so an inactive one keeps its `null` and stays out of the next request. A
 			// missing slot would be read as "never requested", which for a `searches` set that still lists it
 			// would restart it from its first page.
-			const next: SearchCursor = { page: page + 1 };
+			// The order is pinned on the way out too, so the next round can refuse a changed key (see above).
+			const next: SearchCursor = { page: page + 1, sort: requestedSort };
 			let hasMore = false;
 			let continuationMissing = false;
 			let maxIssueCount = 0;
@@ -4057,7 +4366,7 @@ export class GitHubApi {
 				cursor?.truncated === true || maxIssueCount > githubSearchResultLimit || continuationMissing;
 			next.truncated = truncated || undefined;
 			return {
-				values: [...results],
+				values: deduped,
 				cursor: hasMore ? JSON.stringify(next) : undefined,
 				hasMore: hasMore,
 				page: page,
@@ -4074,8 +4383,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(
@@ -4235,7 +4547,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,