@gitkraken/core-gitlens 0.5.100 → 0.5.102

package/src/plus/integrations/collectionMetadata.ts

@@ -1,8 +1,13 @@
-import type { CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
+import type {
+	CollectionMetadata,
+	CollectionOmission,
+	CollectionScope,
+	CollectionScopeFailure,
+} from '@gitkraken/provider-apis';
 import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
 import type { IntegrationIds } from './constants.js';
 import { isRateLimitResponse } from './errors.js';
-import type { ProviderWarning } from './results.js';
+import type { ProviderWarning, ProviderWarningOmission } from './results.js';
 import { appendDedupedWarning } from './results.js';
 
 /**
@@ -68,8 +73,8 @@ function toCollectionFailureWarningKind(failure: CollectionScopeFailure): Provid
 	}
 }
 
-function collectionFailureMessage(failure: CollectionScopeFailure): string {
-	const scope = failure.scope;
+/** ` (resource r, project p, repository o/n)` for the scope IDs present; empty when the scope names none. */
+function collectionScopeText(scope: CollectionScope | undefined): string {
 	const parts: string[] = [];
 	if (scope?.resourceId != null) {
 		parts.push(`resource ${scope.resourceId}`);
@@ -81,9 +86,98 @@ function collectionFailureMessage(failure: CollectionScopeFailure): string {
 		parts.push(`repository ${scope.repositoryId}`);
 	}
 
-	const scopeText = parts.length ? ` (${parts.join(', ')})` : '';
+	return parts.length ? ` (${parts.join(', ')})` : '';
+}
+
+function collectionFailureMessage(failure: CollectionScopeFailure): string {
 	const detail = failure.message != null ? `: ${failure.message}` : '';
-	return `Failed to read ${failure.kind} scope${scopeText}${detail}`;
+	return `Failed to read ${failure.kind} scope${collectionScopeText(failure.scope)}${detail}`;
+}
+
+/**
+ * Explains one omission in the consumer's terms — what was left out and, where the SDK reports it, how much.
+ *
+ * An omission is a completeness fact, never a failure: the read succeeded, and the provider (or the SDK's own
+ * recovery budget) is what withheld results. That is why these never contribute to `fetchFailed`. Whether a
+ * retry would recover anything is a separate question this layer cannot answer — see the `recovery` note on
+ * {@link toProviderWarningOmission}.
+ */
+function collectionOmissionMessage(omission: CollectionOmission): string {
+	const scopeText = collectionScopeText(omission.scope);
+	switch (omission.kind) {
+		case 'provider-limit':
+			// `totalCount` is the only figure saying how much was withheld; both fields are optional, so degrade
+			// through the shapes the SDK can actually emit rather than printing `undefined`.
+			if (omission.totalCount != null && omission.limit != null) {
+				return `Search${scopeText} matched ${omission.totalCount} results, but the provider exposes at most ${omission.limit}`;
+			}
+			if (omission.limit != null) {
+				return `Search${scopeText} exceeded the provider limit of ${omission.limit} results`;
+			}
+			return `Search${scopeText} exceeded the provider's result limit`;
+		case 'recovery-budget':
+			return `Stopped recovering omitted results${scopeText} after reaching the request budget${
+				omission.limit != null ? ` of ${omission.limit} requests` : ''
+			}`;
+		case 'pagination-incomplete':
+			return `More results are available${scopeText} than this read returned`;
+		default:
+			// `CollectionOmissionKind` is a closed union, so this is unreachable today. Kept as a compile-time
+			// guard rather than a silent fallback: an SDK bump that adds a kind breaks the build here instead
+			// of quietly degrading it to a vague message.
+			omission.kind satisfies never;
+			return `Some results were omitted${scopeText}; the read is incomplete`;
+	}
+}
+
+/**
+ * Forwards an SDK omission as the structured signal consumers read instead of parsing {@link
+ * collectionOmissionMessage}'s prose.
+ *
+ * `results.ts` re-spells `CollectionOmissionKind` rather than importing it, so the published warning surface
+ * carries no `@gitkraken/provider-apis` types (see the export block in `index.ts`). The return type is what
+ * keeps the two unions honest: an SDK bump that adds a member fails to compile here, alongside
+ * `collectionOmissionMessage`'s `satisfies never`.
+ *
+ * `scope` is copied because the SDK's own object is retained and re-merged across drained pages
+ * (`providerPaging.ts`), and this one crosses the package boundary.
+ *
+ * `recovery` is always `'none'`, deliberately, and a scoped `pagination-incomplete` is why it looks wrong: the
+ * SDK emits that one shape from situations with opposite remedies and says so itself — "Either the read
+ * deliberately took one page per scope, or the provider advertised another page it gave no way to reach." Its
+ * `collectAcrossScopes` producers (Azure, Bitbucket, Bitbucket Server) are the first, its `drainAcrossScopes`
+ * producers (GitLab, Jira) the second, and those report an omission only when a cursor STALLED — so re-reading
+ * that scope stalls at the identical page. Nothing in `CollectionOmission` separates the two, so claiming
+ * recoverability would ship the dead-end button `recovery` exists to prevent. Making the recoverable case
+ * claimable needs provider-apis to say whether a scope was drained or merely sampled: a fact to forward, not
+ * to guess here.
+ */
+function toProviderWarningOmission(omission: CollectionOmission): ProviderWarningOmission {
+	return {
+		kind: omission.kind,
+		recovery: 'none',
+		...(omission.limit != null ? { limit: omission.limit } : {}),
+		// The SDK types this `number | null | undefined`; normalize to one absence for consumers.
+		...(omission.totalCount != null ? { totalCount: omission.totalCount } : {}),
+		...(omission.scope != null ? { scope: { ...omission.scope } } : {}),
+	};
+}
+
+/**
+ * Whether SDK metadata describes a read that may be missing results.
+ *
+ * A reported omission counts on its own rather than deferring to `completeness`. The SDK does couple the
+ * two — every site that emits an omission degrades completeness in the same call — so today the omission
+ * clause changes no outcome. It is defensive: the two facts arrive as independent fields, and a read that
+ * names what it left out must not be publishable as whole if a future producer sets only one of them.
+ *
+ * This is the single definition of "may be missing results", shared with `getPagedResult`, so one metadata
+ * object cannot be truncated at one layer and complete at another.
+ */
+export function isIncompleteCollection(metadata: CollectionMetadata | undefined): boolean {
+	if (metadata == null) return false;
+
+	return metadata.completeness !== 'complete' || (metadata.omissions?.length ?? 0) > 0;
 }
 
 /** Converts internal SDK collection metadata into neutral provider facade signals. */
@@ -109,8 +203,31 @@ export function assessCollectionMetadata(
 		});
 	}
 
-	const incomplete = metadata.completeness !== 'complete';
-	if (incomplete && failures.length === 0) {
+	// Omissions explain WHY a read is incomplete when nothing failed — a provider cap, an exhausted recovery
+	// budget, an undrained scope. They classify as `other`, never `auth`, and are deliberately excluded from
+	// `fetchFailed` below: the request itself succeeded. `omission` carries that same fact structurally, so a
+	// consumer can act on it without parsing the message.
+	const omissions = metadata.omissions ?? [];
+	for (const omission of omissions) {
+		appendDedupedWarning(warnings, {
+			providerId: providerId,
+			domain: domain,
+			connectionId: connectionId,
+			message: collectionOmissionMessage(omission),
+			kind: 'other',
+			isAuth: false,
+			omission: toProviderWarningOmission(omission),
+		});
+	}
+
+	const incomplete = isIncompleteCollection(metadata);
+	// Only fall back to the generic message when nothing more specific was reported; an omission already
+	// explains the incompleteness in the consumer's terms, so adding this on top would be noise.
+	//
+	// This one deliberately carries no `omission`: it fires precisely when the SDK reported incompleteness
+	// WITHOUT saying what was left out, so there is no structured fact to forward and synthesizing one would
+	// assert a specificity this layer does not have.
+	if (incomplete && failures.length === 0 && omissions.length === 0) {
 		appendDedupedWarning(warnings, {
 			providerId: providerId,
 			domain: domain,

package/src/plus/integrations/index.ts

@@ -202,6 +202,10 @@ export type {
 	ProviderSweepResult,
 	ProviderWarning,
 	ProviderWarningKind,
+	ProviderWarningOmission,
+	ProviderWarningOmissionKind,
+	ProviderWarningOmissionRecovery,
+	ProviderWarningOmissionScope,
 	ProviderOrganization,
 	ProviderRepositoryShape,
 	RepositoryIdentity,

package/src/plus/integrations/integrationService.ts

@@ -555,7 +555,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 	async getMyIssues(
 		integrationIds?: (GitCloudHostIntegrationId | IssuesCloudHostIntegrationId | GitSelfManagedHostIntegrationId)[],
 		options?: { openRepositoriesOnly?: boolean; cancellation?: AbortSignal },
-	): Promise<IssueShape[] | undefined> {
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
 		const integrations: Map<Integration, ResourceDescriptor[] | undefined> = new Map();
 		const hostingIntegrationIds = integrationIds?.filter(
 			id => id in GitCloudHostIntegrationId || id in GitSelfManagedHostIntegrationId,
@@ -623,26 +623,54 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 	private async getMyIssuesCore(
 		integrations: Map<Integration, ResourceDescriptor[] | undefined>,
 		cancellation?: AbortSignal,
-	): Promise<IssueShape[] | undefined> {
-		const promises: Promise<IssueShape[] | undefined>[] = [];
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
+		const start = performance.now();
+
+		const promises: Promise<IntegrationResult<IssueShape[] | undefined>>[] = [];
 		for (const [integration, repos] of integrations) {
 			if (integration == null) continue;
 
-			promises.push(integration.searchMyIssues(repos, cancellation));
+			promises.push(integration.searchMyIssuesResult(repos, cancellation));
 		}
 
 		const results = await Promise.allSettled(promises);
-		return [...flatten(filterMap(results, r => (r.status === 'fulfilled' ? r.value : undefined)))];
+		const successfulResults = [
+			...flatten(
+				filterMap(results, r =>
+					r.status === 'fulfilled' && r.value?.value != null ? r.value.value : undefined,
+				),
+			),
+		];
+		const errors = [
+			...filterMap(results, r =>
+				r.status === 'fulfilled' && r.value?.error != null ? r.value.error : undefined,
+			),
+		];
+
+		const error =
+			errors.length === 0
+				? undefined
+				: errors.length === 1
+					? errors[0]
+					: new AggregateError(errors, 'Failed to get some issues');
+
+		return {
+			value: successfulResults,
+			error: error,
+			duration: performance.now() - start,
+		};
 	}
 
-	async getMyIssuesForRemotes(remote: GitRemote): Promise<IssueShape[] | undefined>;
-	async getMyIssuesForRemotes(remotes: GitRemote[]): Promise<IssueShape[] | undefined>;
+	async getMyIssuesForRemotes(remote: GitRemote): Promise<IntegrationResult<IssueShape[] | undefined>>;
+	async getMyIssuesForRemotes(remotes: GitRemote[]): Promise<IntegrationResult<IssueShape[] | undefined>>;
 	@trace({
 		args: (remoteOrRemotes: GitRemote | GitRemote[]) => ({
 			remoteOrRemotes: Array.isArray(remoteOrRemotes) ? remoteOrRemotes.map(rp => rp.name) : remoteOrRemotes.name,
 		}),
 	})
-	async getMyIssuesForRemotes(remoteOrRemotes: GitRemote | GitRemote[]): Promise<IssueShape[] | undefined> {
+	async getMyIssuesForRemotes(
+		remoteOrRemotes: GitRemote | GitRemote[],
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
 		if (!Array.isArray(remoteOrRemotes)) {
 			remoteOrRemotes = [remoteOrRemotes];
 		}
@@ -653,7 +681,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 			if (remote?.provider == null) return undefined;
 
 			const integration = await this.getByRemote(remote);
-			return integration?.searchMyIssues(remote.provider.repoDesc);
+			return integration?.searchMyIssuesResult(remote.provider.repoDesc);
 		}
 
 		const integrations = new Map<GitHostIntegration, ResourceDescriptor[]>();

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

@@ -737,6 +737,7 @@ export abstract class IntegrationBase<
 		const session = await this.resolveReadSession(connectionId, scope);
 		if (session == null) return undefined;
 
+		const start = performance.now();
 		try {
 			const issues = await this.searchProviderMyIssues(
 				session,
@@ -744,10 +745,10 @@ export abstract class IntegrationBase<
 				cancellation,
 			);
 			this.resetRequestExceptionCount('searchMyIssues');
-			return { value: issues };
+			return { value: issues, duration: performance.now() - start };
 		} catch (ex) {
 			this.handleProviderException('searchMyIssues', ex, { scope: scope, connectionId: connectionId });
-			return { error: toError(ex) };
+			return { error: toError(ex), duration: performance.now() - start };
 		}
 	}
 

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

@@ -470,7 +470,10 @@ export type GetIssueFn = (
 export type GetIssuesForReposFn = (
 	input: (GetIssuesForReposInput | GetIssuesForRepoIdsInput) & PagingInput,
 	options?: EnterpriseOptions,
-) => Promise<{ data: ProviderIssue[]; pageInfo?: PageInfo }>;
+	// GitHub's multi-repo issue search reports its 1,000-result cap — and, when it recovers past it by
+	// partitioning, what that recovery could not reach — through `metadata`. Documented on the contract for
+	// the reader; `getPagedResult` accepts and forwards `metadata` from any provider fn regardless.
+) => Promise<{ data: ProviderIssue[]; pageInfo?: PageInfo; metadata?: CollectionMetadata }>;
 
 export type GetIssuesForCurrentUserInput = PagingInput & {
 	// GitLab's account-wide REST read (`GET /issues`): `scope` controls breadth ('assigned_to_me' vs 'all') and

package/src/plus/integrations/providers/providersApi.ts

@@ -13,6 +13,7 @@ import type { PagedResult } from '../../../utils/paging.js';
 import type { IntegrationAuthenticationService } from '../authentication/integrationAuthenticationService.js';
 import type { TokenOptInfo, TokenWithInfo } from '../authentication/models.js';
 import { toTokenWithInfo } from '../authentication/models.js';
+import { isIncompleteCollection } from '../collectionMetadata.js';
 import type { IntegrationIds } from '../constants.js';
 import {
 	GitCloudHostIntegrationId,
@@ -32,7 +33,6 @@ import type {
 	GetIssueFn,
 	GetIssuesForReposFn,
 	GetIssuesOptions,
-	GetPullRequestsForRepoFn,
 	GetPullRequestsForReposFn,
 	GetPullRequestsForUserFn,
 	GetPullRequestsForUserOptions,
@@ -275,9 +275,7 @@ export class ProvidersApi {
 				getPullRequestsForReposFn: providerApis.gitlab.getPullRequestsForRepos.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForReposFn,
-				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(
-					providerApis.gitlab,
-				) as GetPullRequestsForRepoFn,
+				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(providerApis.gitlab),
 				getPullRequestsForUserFn: providerApis.gitlab.getPullRequestsAssociatedWithUser.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForUserFn,
@@ -302,9 +300,7 @@ export class ProvidersApi {
 				getPullRequestsForReposFn: providerApis.gitlab.getPullRequestsForRepos.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForReposFn,
-				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(
-					providerApis.gitlab,
-				) as GetPullRequestsForRepoFn,
+				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(providerApis.gitlab),
 				getPullRequestsForUserFn: providerApis.gitlab.getPullRequestsAssociatedWithUser.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForUserFn,
@@ -681,9 +677,9 @@ export class ProvidersApi {
 			// SDK collection completeness is independent from provider-native pagination: a result can expose a
 			// real next page (`more`) and still have a failed sibling scope (`partial`/`unknown`). Surface the
 			// latter as `truncated` so consumers treat the page as incomplete. Absent metadata (old providers,
-			// test doubles) leaves `truncated` unset for backward compatibility.
-			const truncated =
-				normalizedMetadata != null && normalizedMetadata.completeness !== 'complete' ? true : undefined;
+			// test doubles) leaves `truncated` unset for backward compatibility. Shares the incompleteness
+			// predicate with the facade assessment so one metadata object can't be truncated there and whole here.
+			const truncated = isIncompleteCollection(normalizedMetadata) ? true : undefined;
 
 			return {
 				values: result.data,

package/src/plus/integrations/providers/trello.ts

@@ -1,3 +1,4 @@
+import type { CollectionMetadata } from '@gitkraken/provider-apis';
 import type { Account } from '../../../git/models/author.js';
 import type { Issue, IssueShape } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest, IssueOrPullRequestType } from '../../../git/models/issueOrPullRequest.js';
@@ -103,7 +104,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
 		options?: { user?: string; filters?: IssueFilter[] },
-	): Promise<{ values: IssueShape[]; truncated: boolean } | undefined> {
+	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
 		// A non-issue descriptor genuinely has nothing to read (empty), but a missing app key is a broken read.
 		if (!isIssueResourceDescriptor(project)) return undefined;
 
@@ -139,7 +140,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		// never a cursor. Surface that as terminal truncation; there is no next page to fetch, so retrying the
 		// same read cannot recover the omitted cards (D11).
 		const truncated = result.metadata != null && result.metadata.completeness !== 'complete';
-		return { values: values, truncated: truncated };
+		return { values: values, truncated: truncated, metadata: result.metadata };
 	}
 
 	protected override searchProviderMyIssues(

package/src/plus/integrations/providers/utils/providerPaging.ts

@@ -1,6 +1,13 @@
-import type { CollectionCompleteness, CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
+import type {
+	CollectionCompleteness,
+	CollectionMetadata,
+	CollectionOmission,
+	CollectionScopeFailure,
+} from '@gitkraken/provider-apis';
 import { isCancellationError } from '../../../../utils/cancellation.js';
+import { uniqueBy } from '../../../../utils/iterable.js';
 import { toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { collectionScopeKey } from '../../results.js';
 import type { ProviderApiPagedResult, ProviderHierarchyResult } from '../models.js';
 
 /**
@@ -42,21 +49,29 @@ const completenessRank: Record<CollectionCompleteness, number> = { partial: 2, u
 
 /** A stable key for deduplicating structurally-identical scope failures accumulated across drained pages. */
 function collectionFailureKey(failure: CollectionScopeFailure): string {
-	const scope = failure.scope;
-	return [
-		failure.kind,
-		scope?.providerId ?? '',
-		scope?.resourceId ?? '',
-		scope?.projectId ?? '',
-		scope?.repositoryId ?? '',
-		failure.message ?? '',
-	].join(' ');
+	return [failure.kind, collectionScopeKey(failure.scope), failure.message ?? ''].join(' ');
+}
+
+/**
+ * A stable key for collapsing omissions accumulated across drained pages, matching the SDK's own
+ * `dedupeOmissions`: kind plus scope IDs, deliberately WITHOUT `limit`/`totalCount`.
+ *
+ * Those counts are a re-measurement, not an identity. GitHub recomputes the match total on every request, so
+ * one repository drained over several pages reports the same cap with a drifting total; keying on the total
+ * would emit a near-identical warning per page ("matched 1393…", "matched 1402…") that
+ * `appendDedupedWarning` cannot collapse, since the messages genuinely differ. Independently-scoped omissions
+ * still stay distinct, which is the case that carries information.
+ */
+function collectionOmissionKey(omission: CollectionOmission): string {
+	return [omission.kind, collectionScopeKey(omission.scope)].join(' ');
 }
 
 /**
  * Merges SDK collection metadata across drained pages. Completeness follows {@link completenessRank};
- * failures are concatenated and deduplicated by kind, scope IDs, and message. Returns `undefined` when no
- * page supplied metadata, so metadata-free providers and test doubles keep behaving as before.
+ * failures are deduplicated by kind, scope IDs, and message, and omissions are collapsed per kind and scope
+ * keeping the highest reported total ({@link collectionOmissionKey}). Both preserve first-reported order.
+ * Returns `undefined` when no page supplied metadata, so metadata-free providers and test doubles keep
+ * behaving as before.
  */
 export function mergeCollectionMetadata(
 	base: CollectionMetadata | undefined,
@@ -70,17 +85,25 @@ export function mergeCollectionMetadata(
 			? next.completeness
 			: base.completeness;
 
-	const failures: CollectionScopeFailure[] = [];
-	const seen = new Set<string>();
-	for (const failure of [...(base.failures ?? []), ...(next.failures ?? [])]) {
-		const key = collectionFailureKey(failure);
-		if (seen.has(key)) continue;
-
-		seen.add(key);
-		failures.push(failure);
-	}
-
-	return { completeness: completeness, ...(failures.length ? { failures: failures } : {}) };
+	// First occurrence wins: a repeated failure carries no new information, since the message is part of its key.
+	const failures = [
+		...uniqueBy([...(base.failures ?? []), ...(next.failures ?? [])], collectionFailureKey, original => original),
+	];
+	// Highest total wins, so re-measuring one cap across pages collapses to a single omission holding the
+	// largest figure reported for it — the same rule the SDK applies in `createCollectionMetadata`.
+	const omissions = [
+		...uniqueBy(
+			[...(base.omissions ?? []), ...(next.omissions ?? [])],
+			collectionOmissionKey,
+			(original, current) => ((current.totalCount ?? -1) > (original.totalCount ?? -1) ? current : undefined),
+		),
+	];
+
+	return {
+		completeness: completeness,
+		...(failures.length ? { failures: failures } : {}),
+		...(omissions.length ? { omissions: omissions } : {}),
+	};
 }
 
 /**

package/src/plus/integrations/reads/drains.ts

@@ -9,7 +9,7 @@ import type { PullRequestFilter } from '../providerFilters.js';
 import type { ProviderPullRequest, ProviderReposInput, ProviderRepository } from '../providers/models.js';
 import { getProviderPullRequestIdentity } from '../providers/models.js';
 import type { ProviderWarning } from '../results.js';
-import { appendDedupedWarning, toProviderWarning } from '../results.js';
+import { appendDedupedWarning, reconcileOmissionsWithFailure, toProviderWarning } from '../results.js';
 import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
 import { noConnectionWarning, truncationWarning } from './warnings.js';
 
@@ -90,10 +90,18 @@ export async function drainPullRequests(
 	// this through the terminal returns instead of resetting it to false at the last page.
 	let fetchFailed = false;
 	let truncated = false;
+	// A page the provider capped or couldn't vouch for. Decides the CAUSE the terminal warning reports: a cap
+	// outranks a budget stop, because raising a budget cannot un-cap a page.
+	let providerTruncated = false;
+	// The subset of that which no other warning already explains — decides whether this drain raises one of
+	// its own on an otherwise clean exit.
+	let unexplainedTruncation = false;
 
 	// With no repos this is an account-wide "my PRs" sweep. The repo-scoped core rejects an empty `repos`
 	// input, so read the provider-native account-wide core instead.
 	const accountWide = repos.length === 0;
+	/** Every cursor already followed, so a provider that cycles them can't keep the drain walking in circles. */
+	const seenCursors = new Set<string>();
 
 	for (;;) {
 		page++;
@@ -130,10 +138,23 @@ export async function drainPullRequests(
 				appendDedupedWarning(warnings, noConnectionWarning(id, domain, connectionId));
 			}
 			// `warning` set → a hard read failure (incomplete items); otherwise not connected / no session.
+			const failed = fetchFailed || warning != null || unavailable;
+			// A cap seen on an earlier page still left results out, so it is still worth saying — but as part
+			// of a read that failed, never as an omission. (`failed` is always true here when anything was
+			// latched: reaching this exit past page 1 means a later page was lost.)
+			if (unexplainedTruncation) {
+				appendDedupedWarning(
+					warnings,
+					truncationWarning(id, domain, connectionId, 'Pull request', failed ? 'interrupted' : 'exhausted'),
+				);
+			}
+			// An earlier page may already have emitted an omission before this one died; it asserts the read
+			// succeeded, which is no longer true.
+			reconcileOmissionsWithFailure(warnings, failed);
 			return {
 				items: items,
 				warnings: warnings,
-				fetchFailed: fetchFailed || warning != null || unavailable,
+				fetchFailed: failed,
 				truncated: truncated || sessionLostAfterProgress,
 				// Only a top-level first-page rejection means the provider itself failed. A later-page or
 				// per-scope failure still yielded a usable provider slice and stays represented separately.
@@ -171,14 +192,31 @@ export async function drainPullRequests(
 			value.paging?.truncated === true ||
 			assessment.truncated;
 		truncated = truncated || pageTruncated;
-		if (pageTruncated && !assessment.truncated) {
-			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
-		}
+		// A page the provider itself capped, or one whose completeness it couldn't confirm. Latched from ANY
+		// source, SDK metadata included: no budget of ours un-caps a page, so a later `maxPages` hit must not
+		// claim raising it would help.
+		providerTruncated = providerTruncated || pageTruncated;
+		// Whether this drain owes its OWN warning for that is a separate question — `mergeAssessmentInto` has
+		// already appended one when the fact came from SDK metadata, and repeating it would be noise.
+		unexplainedTruncation = unexplainedTruncation || (pageTruncated && !assessment.truncated);
 
 		if (!(value.paging?.more ?? false)) {
 			// A read that can't confirm completeness (single-page provider reads with no `hasNextPage`)
 			// sets `paging.truncated`; propagate it (and any top-level `truncated` and SDK incompleteness)
 			// so the sweep doesn't claim an all-pages result.
+			if (unexplainedTruncation) {
+				appendDedupedWarning(
+					warnings,
+					truncationWarning(
+						id,
+						domain,
+						connectionId,
+						'Pull request',
+						fetchFailed ? 'interrupted' : 'exhausted',
+					),
+				);
+			}
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return {
 				items: items,
 				warnings: warnings,
@@ -187,21 +225,34 @@ export async function drainPullRequests(
 				failedProvider: false,
 			};
 		}
-		if (page >= maxPages) {
-			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
-			return {
-				items: items,
-				warnings: warnings,
-				fetchFailed: fetchFailed,
-				truncated: true,
-				failedProvider: false,
-			};
-		}
 
+		// Resolve the continuation BEFORE deciding why the drain stops. `page-budget` claims the missing items
+		// are reachable, which is only true with a usable cursor in hand — and a provider can report another
+		// page while handing back none (Bitbucket Server does, when it omits `nextPageStart`). Checking the
+		// budget first would label that unreachable tail as merely unfetched, so raising `maxPages` would
+		// return the identical set.
 		const nextCursor = value.paging?.cursor;
-		if (nextCursor == null || nextCursor === '{}') {
-			// Provider says there is more but didn't return a usable cursor; stop rather than refetch the same page.
-			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
+		// A cursor already used isn't a continuation either — following it refetches a page we have, and a
+		// provider that cycles (A→B→A) would otherwise burn the whole budget and then be reported as merely
+		// out of budget. Tracked as a SET rather than compared one-back, matching the SDK's own `followCursors`:
+		// `drainToRequestedPage` and `collectProviderPagedResult` compare only the previous cursor, which a
+		// cycle slips past. That is tolerable there and not here, because only this drain reports `page-budget`.
+		const continuable = nextCursor != null && nextCursor !== '{}' && !seenCursors.has(nextCursor);
+		if (!continuable || page >= maxPages) {
+			// `providerTruncated` outranks the budget: a page the provider capped stays capped however many
+			// pages we are allowed to read, so promising `page-budget` on top of it would be a load-more that
+			// cannot deliver the capped part.
+			appendDedupedWarning(
+				warnings,
+				truncationWarning(
+					id,
+					domain,
+					connectionId,
+					'Pull request',
+					fetchFailed ? 'interrupted' : continuable && !providerTruncated ? 'page-budget' : 'exhausted',
+				),
+			);
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return {
 				items: items,
 				warnings: warnings,
@@ -211,6 +262,7 @@ export async function drainPullRequests(
 			};
 		}
 
+		seenCursors.add(nextCursor);
 		cursor = nextCursor;
 	}
 }
@@ -262,12 +314,20 @@ export async function drainRepositories(
 		if (value == null) {
 			const interruptedAfterProgress = page > 1;
 			if (interruptedAfterProgress && warning == null) {
-				appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Repository'));
+				// Not a backstop: the read was cut short mid-drain, which is why it also sets `fetchFailed`
+				// below. A retry may complete it, so this must not claim the succeeded-but-capped omission.
+				appendDedupedWarning(
+					warnings,
+					truncationWarning(id, domain, connectionId, 'Repository', 'interrupted'),
+				);
 			}
+			const failed = fetchFailed || warning != null || interruptedAfterProgress;
+			// An SDK omission from an earlier page asserts the read succeeded; this one didn't.
+			reconcileOmissionsWithFailure(warnings, failed);
 			return {
 				repos: repos,
 				warnings: warnings,
-				fetchFailed: fetchFailed || warning != null || interruptedAfterProgress,
+				fetchFailed: failed,
 				truncated: truncated || interruptedAfterProgress,
 			};
 		}
@@ -277,6 +337,7 @@ export async function drainRepositories(
 		fetchFailed = fetchFailed || assessment.fetchFailed;
 		truncated = truncated || value.truncated === true || value.paging?.truncated === true || assessment.truncated;
 		if (!(value.paging?.more ?? false)) {
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return {
 				repos: repos,
 				warnings: warnings,
@@ -284,13 +345,16 @@ export async function drainRepositories(
 				truncated: truncated,
 			};
 		}
+
 		if (page >= maxPages) {
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return { repos: repos, warnings: warnings, fetchFailed: fetchFailed, truncated: true };
 		}
 
 		const nextCursor = value.paging?.cursor;
 		if (nextCursor == null || nextCursor === '{}') {
 			// Provider says there is more but didn't return a usable cursor; stop rather than refetch the same page.
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return { repos: repos, warnings: warnings, fetchFailed: fetchFailed, truncated: true };
 		}