@gitkraken/core-gitlens 0.5.114 → 0.5.115

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

@@ -12,7 +12,12 @@ import { toTokenWithInfo } from '../authentication/models.js';
 import { toCollectionScopeFailure } from '../collectionMetadata.js';
 import { IssuesCloudHostIntegrationId } from '../constants.js';
 import { IntegrationReadUnavailableError } from '../errors.js';
-import type { AccountWideIssuesResult, IssuesForProjectOptions, SearchMyIssuesOptions } from '../models/issueReads.js';
+import type {
+	AccountWideIssuesResult,
+	IssuesForProjectOptions,
+	ProjectIssuesDrain,
+	SearchMyIssuesOptions,
+} from '../models/issueReads.js';
 import { IssuesIntegration } from '../models/issuesIntegration.js';
 import type { ProviderApiCollectionResult, ProviderIssue } from './models.js';
 import { fromProviderIssue, providersMetadata, toIssueShape } from './models.js';
@@ -219,7 +224,7 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
 		options?: IssuesForProjectOptions,
-	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
+	): Promise<ProjectIssuesDrain | undefined> {
 		if (!isIssueResourceDescriptor(project)) return undefined;
 
 		const api = await this.getProvidersApi();
@@ -256,6 +261,8 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 			requestCount += 1;
 			hasMore = result.paging?.more ?? false;
 			const nextCursor = result.paging?.cursor;
+			truncated ||= result.paging?.truncated === true;
+			collectionMetadata = mergeCollectionMetadata(collectionMetadata, result.metadata);
 			for (const issue of result.values) {
 				const shape = toIssueShape(issue, this);
 				if (shape != null) {
@@ -270,7 +277,6 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 			}
 
 			cursor = nextCursor;
-			// More pages remain but we've hit the backstop: the drain is incomplete.
 			if (hasMore && requestCount >= maxPagesPerRequest) {
 				truncated = true;
 			}
@@ -294,14 +300,16 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 					'could not resolve the current user to scope issues to',
 				);
 			}
-			return {
-				values: issues.filter(issue => issue.assignees?.some(a => a.id === viewerId)),
-				truncated: truncated,
-				metadata: collectionMetadata,
-			};
+
+			const values = issues.filter(issue => issue.assignees?.some(a => a.id === viewerId));
+			return truncated
+				? { values: values, truncated: true, recovery: 'none', metadata: collectionMetadata }
+				: { values: values, truncated: false, metadata: collectionMetadata };
 		}
 
-		return { values: issues, truncated: truncated, metadata: collectionMetadata };
+		return truncated
+			? { values: issues, truncated: true, recovery: 'none', metadata: collectionMetadata }
+			: { values: issues, truncated: false, metadata: collectionMetadata };
 	}
 
 	override get id(): IssuesCloudHostIntegrationId.Linear {
@@ -433,30 +441,35 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		return result && fromProviderIssue(result, this);
 	}
 
+	protected override async getProviderIssueByResourceId(
+		session: ProviderAuthenticationSession,
+		resourceId: string,
+		id: string,
+		_resourceUrl: string | undefined,
+	): Promise<Issue | undefined> {
+		const api = await this.getProvidersApi();
+		const result = await api.getIssue(toTokenWithInfo(this.id, session), {
+			resourceId: resourceId,
+			number: id,
+		});
+		return result && fromProviderIssue(result, this);
+	}
+
 	private async getRawProviderIssue(
 		session: ProviderAuthenticationSession,
 		resource: ResourceDescriptor,
 		id: string,
 	): Promise<ProviderIssue | undefined> {
 		const api = await this.getProvidersApi();
-		try {
-			if (!isIssueResourceDescriptor(resource)) {
-				Logger.error(undefined, 'getProviderIssue: resource is not an IssueResourceDescriptor');
-				return undefined;
-			}
-
-			const result = await api.getIssue(toTokenWithInfo(this.id, session), {
-				resourceId: resource.id,
-				number: id,
-			});
-
-			if (result == null) return undefined;
-
-			return result;
-		} catch (ex) {
-			Logger.error(ex, 'getProviderIssue');
+		if (!isIssueResourceDescriptor(resource)) {
+			Logger.error(undefined, 'getProviderIssue: resource is not an IssueResourceDescriptor');
 			return undefined;
 		}
+
+		return api.getIssue(toTokenWithInfo(this.id, session), {
+			resourceId: resource.id,
+			number: id,
+		});
 	}
 	private getIssueAutolinkLikeUrl(issue: ProviderIssue): string | null {
 		const url = issue.url;

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

@@ -1229,13 +1229,24 @@ function toIssueIdentifier(value: string | number): string {
 	return String(value);
 }
 
-export function toIssueShape(issue: ProviderIssue, provider: ProviderReference): IssueShape | undefined {
+export function toIssueShape(
+	issue: ProviderIssue,
+	provider: ProviderReference,
+	options?: { reliableStateCategory?: boolean },
+): IssueShape | undefined {
 	// TODO: Add some protections/baselines rather than killing the transformation here
 	// `author` is intentionally not required: some providers have no per-item creator (e.g. Trello cards,
 	// which the SDK maps with `author: null`), and dropping every such item would discard the whole board.
 	// Fall back to an empty author instead so these issues still surface.
 	if (issue.updatedDate == null || issue.url == null) return undefined;
 
+	// Jira SDK results derive this category from a localized display name and default unknown names to DONE.
+	// Only the direct point read opts in because it maps Jira's stable status-category key itself.
+	const closed =
+		issue.closedDate != null ||
+		(issue.state?.category === 'DONE' &&
+			(provider.id !== IssuesCloudHostIntegrationId.Jira || options?.reliableStateCategory === true));
+
 	return {
 		type: 'issue',
 		provider: provider,
@@ -1254,8 +1265,8 @@ export function toIssueShape(issue: ProviderIssue, provider: ProviderReference):
 		createdDate: issue.createdDate,
 		updatedDate: issue.updatedDate,
 		closedDate: issue.closedDate ?? undefined,
-		closed: issue.closedDate != null,
-		state: issue.closedDate != null ? 'closed' : 'opened',
+		closed: closed,
+		state: closed ? 'closed' : 'opened',
 		author: {
 			id: issue.author?.id ?? '',
 			// An absent name stays absent, matching {@link fromProviderAccount}; see `IssueMember.name`.
@@ -1688,6 +1699,7 @@ export function fromProviderIssue(
 	options?: { project?: IssueProject },
 ): Issue {
 	const identifier = toIssueIdentifier(issue.number);
+	const closed = issue.closedDate != null || issue.state?.category === 'DONE';
 	return new Issue(
 		integration,
 		identifier,
@@ -1696,8 +1708,8 @@ export function fromProviderIssue(
 		issue.url ?? '',
 		issue.createdDate,
 		issue.updatedDate ?? issue.closedDate ?? issue.createdDate,
-		issue.closedDate != null,
-		issue.closedDate != null ? 'closed' : 'opened',
+		closed,
+		closed ? 'closed' : 'opened',
 		fromProviderAccount(issue.author),
 		issue.assignees?.map(fromProviderAccount) ?? undefined,
 		issue.repository != null

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

@@ -0,0 +1,115 @@
+import type { TokenWithInfo } from '../authentication/models.js';
+import type { IntegrationIds } from '../constants.js';
+import { IssuesCloudHostIntegrationId } from '../constants.js';
+import {
+	AuthenticationError,
+	AuthenticationErrorReason,
+	isRateLimitResponse,
+	RequestClientError,
+	RequestNotFoundError,
+	toError,
+	toRateLimitError,
+} from '../errors.js';
+
+const linearIssueNotFoundMessage = /^Linear issue not found: .+$/i;
+const maxProviderErrorBodyLength = 500;
+
+type ProviderGraphQLError = {
+	message?: unknown;
+	extensions?: { code?: unknown };
+};
+
+function getProviderGraphQLErrors(body: unknown): ProviderGraphQLError[] {
+	if (body == null || typeof body !== 'object') return [];
+
+	const errors = (body as { errors?: unknown }).errors;
+	return Array.isArray(errors)
+		? errors.filter((error): error is ProviderGraphQLError => error != null && typeof error === 'object')
+		: [];
+}
+
+function isLinearRateLimitError(providerId: IntegrationIds, ex: unknown): boolean {
+	if (providerId !== IssuesCloudHostIntegrationId.Linear) return false;
+
+	const body = (ex as { response?: { body?: unknown } }).response?.body;
+	return getProviderGraphQLErrors(body).some(error => error.extensions?.code === 'RATELIMITED');
+}
+
+export function isProviderIssueNotFoundError(providerId: IntegrationIds, ex: unknown): boolean {
+	if (providerId === IssuesCloudHostIntegrationId.Linear) {
+		return ex instanceof Error && linearIssueNotFoundMessage.test(ex.message);
+	}
+
+	const status = (ex as { response?: { status?: unknown } }).response?.status;
+	return status === 404 || status === 410 || status === 422;
+}
+
+export function throwProviderError(tokenWithInfo: TokenWithInfo, error: unknown): never {
+	const { accessToken: token, ...tokenInfo } = tokenWithInfo;
+	const providerId = tokenWithInfo.providerId;
+	const normalizedError = toError(error);
+	// Linear reports GraphQL throttling as HTTP 400, so its structured code must win over generic 4xx handling.
+	if (isLinearRateLimitError(providerId, error)) {
+		throw toRateLimitError(normalizedError, token);
+	}
+
+	const status = (error as { response?: { status?: unknown } }).response?.status;
+	if (typeof status === 'number') {
+		switch (status) {
+			case 404:
+			case 410:
+			case 422:
+				throw new RequestNotFoundError(normalizedError);
+			case 429:
+				throw toRateLimitError(normalizedError, token);
+			case 401:
+			case 403:
+				// Some hosts overload 403 for throttling; classify that before asking the user to reconnect.
+				if (isRateLimitResponse({ status: status, message: normalizedError.message })) {
+					throw toRateLimitError(normalizedError, token);
+				}
+				throw new AuthenticationError(
+					tokenInfo,
+					status === 401 ? AuthenticationErrorReason.Unauthorized : AuthenticationErrorReason.Forbidden,
+					normalizedError,
+				);
+			default:
+				if (status >= 400 && status < 500) {
+					throw new RequestClientError(normalizedError);
+				}
+		}
+	}
+
+	throw error;
+}
+
+/** Extracts the useful provider prose from an already-parsed SDK response body. */
+export function getProviderResponseBodyMessage(body: unknown): string | undefined {
+	let message: string | undefined;
+	if (typeof body === 'string') {
+		message = body;
+	} else if (body != null && typeof body === 'object') {
+		const { message: direct, error } = body as { message?: unknown; error?: unknown };
+		if (typeof direct === 'string') {
+			message = direct;
+		} else if (typeof error === 'string') {
+			message = error;
+		} else if (error != null && typeof error === 'object') {
+			const nested = (error as { message?: unknown }).message;
+			if (typeof nested === 'string') {
+				message = nested;
+			}
+		}
+		if (message == null) {
+			const graphQLError = getProviderGraphQLErrors(body)[0];
+			if (typeof graphQLError?.message === 'string') {
+				message = graphQLError.message;
+			} else if (typeof graphQLError?.extensions?.code === 'string') {
+				message = graphQLError.extensions.code;
+			}
+		}
+	}
+
+	message = message?.trim();
+	return message ? message.slice(0, maxProviderErrorBodyLength) : undefined;
+}

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

@@ -20,15 +20,8 @@ import {
 	GitSelfManagedHostIntegrationId,
 	IssuesCloudHostIntegrationId,
 } from '../constants.js';
-import {
-	AuthenticationError,
-	AuthenticationErrorReason,
-	isRateLimitResponse,
-	RequestClientError,
-	RequestNotFoundError,
-	toError,
-	toRateLimitError,
-} from '../errors.js';
+import { RequestNotFoundError, toError } from '../errors.js';
+import { requestJiraIssueByKey } from './jiraIssueByKey.js';
 import type {
 	GetIssueFn,
 	GetIssuesForReposFn,
@@ -69,6 +62,7 @@ import type {
 	PullRequestFilter,
 } from './models.js';
 import { isRepoIdsInput, providersMetadata } from './models.js';
+import { getProviderResponseBodyMessage, isProviderIssueNotFoundError, throwProviderError } from './providerErrors.js';
 import {
 	collectProviderPagedResult,
 	mergeCollectionMetadata,
@@ -88,7 +82,6 @@ const createProviderApis: ProviderApisFactory =
 // `Repository <x> not found`. Anchoring to that shape (rather than a loose `not found` substring) keeps
 // the message fallbacks from misclassifying unrelated GraphQL/transport failures as a confident negative.
 const repoNotFoundMessage = /^Repository .+ not found$/i;
-
 // Duck-typed rather than `ex instanceof GraphQLErrors`, because importing the class as a value makes this
 // module unloadable from plain Node ESM consumers: `@gitkraken/provider-apis` is CommonJS and declares its
 // exports through getters, which Node's `cjs-module-lexer` cannot see, so the only named exports it can
@@ -562,43 +555,13 @@ export class ProvidersApi {
 	}
 
 	private handleProviderError<T>(tokenWithInfo: TokenWithInfo, error: any): T {
-		const { accessToken: token, ...tokenInfo } = tokenWithInfo;
 		const providerId = tokenWithInfo.providerId;
 		const provider = this.providers[providerId];
 		if (provider == null) {
 			throw new Error(`Provider with id ${providerId} not registered`);
 		}
 
-		if (error?.response?.status != null) {
-			const status: number = error.response.status;
-			switch (status) {
-				case 404: // Not found
-				case 410: // Gone
-				case 422: // Unprocessable Entity
-					throw new RequestNotFoundError(error);
-				case 429: // Too Many Requests
-					throw toRateLimitError(error, token);
-				case 401: // Unauthorized
-				case 403: // Forbidden
-					// A throttled request arrives on both statuses depending on the host (see
-					// `isRateLimitResponse`); 403 previously skipped the check, so every provider going through the
-					// SDK reported a rate limit as `auth` and asked the user to reconnect a healthy account.
-					if (isRateLimitResponse({ status: status, message: error.message })) {
-						throw toRateLimitError(error, token);
-					}
-					throw new AuthenticationError(
-						tokenInfo,
-						status === 401 ? AuthenticationErrorReason.Unauthorized : AuthenticationErrorReason.Forbidden,
-						error,
-					);
-				default:
-					if (status >= 400 && status < 500) {
-						throw new RequestClientError(error);
-					}
-			}
-		}
-
-		throw error;
+		return throwProviderError(tokenWithInfo, error);
 	}
 
 	async getPagedResult<T>(
@@ -878,7 +841,7 @@ export class ProvidersApi {
 			/** See {@link GetIssuesOptions.sort}. Linear expresses `created`/`updated`, descending only. */
 			sort?: IssueSorting;
 		},
-	): Promise<PagedResult<ProviderIssue>> {
+	): Promise<ProviderApiPagedResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
 			'getLinearIssuesFn',
@@ -1522,7 +1485,7 @@ export class ProvidersApi {
 		tokenOptInfo: TokenOptInfo,
 		reposOrIds: ProviderReposInput,
 		options?: GetIssuesOptions & { isPAT?: boolean; baseUrl?: string },
-	): Promise<PagedResult<ProviderIssue>> {
+	): Promise<ProviderApiPagedResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
 			'getIssuesForReposFn',
@@ -1837,6 +1800,24 @@ export class ProvidersApi {
 		);
 	}
 
+	async getJiraIssueByKey(
+		tokenOptInfo: TokenWithInfo<IssuesCloudHostIntegrationId.Jira>,
+		resourceId: string,
+		resourceUrl: string,
+		key: string,
+	): Promise<ProviderIssue | undefined> {
+		const { tokenWithInfo } = await this.ensureProviderToken(tokenOptInfo);
+
+		try {
+			return await requestJiraIssueByKey(this.request, tokenWithInfo.accessToken, resourceId, resourceUrl, key);
+		} catch (e) {
+			const status = (e as { response?: { status?: unknown } }).response?.status;
+			if (status === 404) return undefined;
+
+			return this.handleProviderError<ProviderIssue | undefined>(tokenWithInfo, e);
+		}
+	}
+
 	async getIssue(
 		tokenOptInfo: TokenWithInfo,
 		input: { resourceId: string; number: string } | { namespace: string; name: string; number: string },
@@ -1854,6 +1835,8 @@ export class ProvidersApi {
 
 			return result?.data;
 		} catch (e) {
+			if (isProviderIssueNotFoundError(tokenWithInfo.providerId, e)) return undefined;
+
 			return this.handleProviderError<ProviderIssue | undefined>(tokenWithInfo, e);
 		}
 	}
@@ -1896,28 +1879,3 @@ async function parseFetchResponseForApi<T>(response: Response): Promise<Provider
 
 	return result;
 }
-
-const maxProviderErrorBodyLength = 500;
-
-/** Extracts the useful provider prose from an already-parsed SDK response body. */
-function getProviderResponseBodyMessage(body: unknown): string | undefined {
-	let message: string | undefined;
-	if (typeof body === 'string') {
-		message = body;
-	} else if (body != null && typeof body === 'object') {
-		const { message: direct, error } = body as { message?: unknown; error?: unknown };
-		if (typeof direct === 'string') {
-			message = direct;
-		} else if (typeof error === 'string') {
-			message = error;
-		} else if (error != null && typeof error === 'object') {
-			const nested = (error as { message?: unknown }).message;
-			if (typeof nested === 'string') {
-				message = nested;
-			}
-		}
-	}
-
-	message = message?.trim();
-	return message ? message.slice(0, maxProviderErrorBodyLength) : undefined;
-}

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

@@ -1,4 +1,3 @@
-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';
@@ -9,7 +8,7 @@ import type { ProviderAuthenticationSession } from '../authentication/models.js'
 import { toTokenWithInfo } from '../authentication/models.js';
 import { IssuesCloudHostIntegrationId } from '../constants.js';
 import { IntegrationReadUnavailableError } from '../errors.js';
-import type { IssuesForProjectOptions } from '../models/issueReads.js';
+import type { IssuesForProjectOptions, ProjectIssuesDrain } from '../models/issueReads.js';
 import { IssuesIntegration } from '../models/issuesIntegration.js';
 import { fromProviderIssue, providersMetadata, toIssueShape } from './models.js';
 
@@ -104,7 +103,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
 		options?: IssuesForProjectOptions,
-	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
+	): Promise<ProjectIssuesDrain | 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;
 
@@ -141,7 +140,9 @@ 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, metadata: result.metadata };
+		return truncated
+			? { values: values, truncated: true, recovery: 'none', metadata: result.metadata }
+			: { values: values, truncated: false, metadata: result.metadata };
 	}
 
 	protected override searchProviderMyIssues(

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

@@ -32,17 +32,24 @@ export function parsePageCursor(cursor: string | undefined): number | undefined
 }
 
 /** Preserves successful sibling scopes, but doesn't turn an all-scope provider failure into an empty success. */
-export async function flatSettledOrThrow<T>(promises: Promise<T[]>[]): Promise<T[]> {
-	const results = await Promise.allSettled(promises);
-	const fulfilled = results.filter((result): result is PromiseFulfilledResult<T[]> => result.status === 'fulfilled');
-	if (fulfilled.length === 0) {
-		const rejected = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');
-		if (rejected != null) throw rejected.reason;
-	}
+export function throwIfAllSettledFailed<T>(results: PromiseSettledResult<T>[]): void {
+	if (results.some(result => result.status === 'fulfilled')) return;
+
+	const rejected = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');
+	if (rejected != null) throw rejected.reason;
+}
 
+export function flatSettledResultsOrThrow<T>(results: PromiseSettledResult<T[]>[]): T[] {
+	throwIfAllSettledFailed(results);
+
+	const fulfilled = results.filter((result): result is PromiseFulfilledResult<T[]> => result.status === 'fulfilled');
 	return fulfilled.flatMap(result => result.value);
 }
 
+export async function flatSettledOrThrow<T>(promises: Promise<T[]>[]): Promise<T[]> {
+	return flatSettledResultsOrThrow(await Promise.allSettled(promises));
+}
+
 /** Precedence for merged completeness: any known omission (`partial`) wins, then inability to confirm
  * (`unknown`), and only an all-`complete` set of pages stays `complete`. */
 const completenessRank: Record<CollectionCompleteness, number> = { partial: 2, unknown: 1, complete: 0 };

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

@@ -2,7 +2,7 @@ import type { CollectionMetadata } from '@gitkraken/provider-apis';
 import type { IssueShape, IssueSorting } from '../../../git/models/issue.js';
 import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
 import { mapBounded } from '../../../utils/promise.js';
-import { mergeAssessmentInto } from '../collectionMetadata.js';
+import { assessCollectionMetadata, mergeAssessmentInto } from '../collectionMetadata.js';
 import type { IntegrationIds } from '../constants.js';
 import { providerFanOutConcurrency } from '../constants.js';
 import { isIssuesIntegration } from '../models/issuesIntegration.js';
@@ -452,10 +452,7 @@ export async function listIssueTrackerIssuesPage(
 	// Partial project discovery means some projects' issues are missing from this page; propagate it so the
 	// page reports fetchFailed even when every discovered project's own read succeeded.
 	let fetchFailed = projectDiscoveryFailed || accountLookupFailed;
-	// A project whose internal page-drain hit its backstop (Jira/Linear cap at maxPagesPerRequest) reports
-	// `truncated`; surface it as `page.truncated` so a windowed read isn't published as having drained each
-	// project completely.
-	let projectTruncated = projectDiscoveryTruncated;
+	let truncationRecovery: 'narrow-scope' | 'none' | undefined = projectDiscoveryTruncated ? 'none' : undefined;
 	let drainMetadata: CollectionMetadata | undefined;
 	for (const { project, value: result, warning } of perProject) {
 		const key = projectKey(project);
@@ -465,7 +462,7 @@ export async function listIssueTrackerIssuesPage(
 			// single failing token repeats verbatim once per project in the window.
 			appendDedupedWarning(warnings, warning);
 			fetchFailed = true;
-			projectTruncated = true;
+			truncationRecovery = 'none';
 		}
 		// A thrown/unsupported read (e.g. Linear not-implemented) surfaces as a warning with no value;
 		// mark the aggregate as fetchFailed so an empty result isn't mistaken for "no issues".
@@ -475,7 +472,8 @@ export async function listIssueTrackerIssuesPage(
 		if (result != null) {
 			items.push(...result.values);
 			if (result.truncated) {
-				projectTruncated = true;
+				const recovery = result.recovery;
+				truncationRecovery = truncationRecovery == null || truncationRecovery === recovery ? recovery : 'none';
 			}
 			if (result.metadata != null) {
 				drainMetadata = mergeCollectionMetadata(drainMetadata, result.metadata);
@@ -497,29 +495,33 @@ export async function listIssueTrackerIssuesPage(
 	// publishes. A no-op when nothing merged, since the tracker already ordered that single run.
 	const orderedItems = ordering.order(items);
 
-	const drainAssessment = mergeAssessmentInto(
-		warnings,
-		options.providerId,
-		domain,
-		options.connectionId,
-		drainMetadata,
-	);
+	const projectReadReportedTruncation = truncationRecovery != null;
+	const drainAssessment = assessCollectionMetadata(options.providerId, domain, options.connectionId, drainMetadata);
+	for (const warning of drainAssessment.warnings) {
+		// A project result already supplies the recovery semantics. Replace metadata's unstructured fallback with
+		// the structured warning below, while retaining specific failures and omissions.
+		if (projectReadReportedTruncation && !drainAssessment.fetchFailed && warning.omission == null) continue;
+
+		appendDedupedWarning(warnings, warning);
+	}
 	fetchFailed = fetchFailed || drainAssessment.fetchFailed;
-	projectTruncated = projectTruncated || drainAssessment.truncated;
+	if (drainAssessment.truncated) {
+		truncationRecovery = 'none';
+	}
 
-	// A per-project read that returned data but couldn't confirm completeness (e.g. Trello's provider-native
-	// cap) sets `truncated` without a structured failure. Add one provider-neutral incompleteness warning so
-	// the caller sees the truncation, but only when no warning already explains it (avoid duplicate noise).
-	if (projectTruncated && warnings.length === 0) {
-		warnings.push(
+	const projectTruncated = truncationRecovery != null;
+	const scopeTooLarge = !fetchFailed && truncationRecovery === 'narrow-scope';
+	if (scopeTooLarge || (!fetchFailed && projectTruncated && !warnings.some(warning => warning.omission != null))) {
+		appendDedupedWarning(
+			warnings,
 			incompleteReadWarning(
 				options.providerId,
 				domain,
 				options.connectionId,
-				'Some issues were omitted; the provider returned an incomplete result.',
-				// `exhausted`, not `page-budget`: the per-project drain's backstop is an internal constant
-				// (`maxPagesPerRequest`), not an option this read exposes, so no caller can raise it.
-				fetchFailed ? 'interrupted' : 'exhausted',
+				scopeTooLarge
+					? 'Some projects hold more issues than one read can return; narrow the scope to read the rest.'
+					: 'Some issues were omitted; the provider returned an incomplete result.',
+				scopeTooLarge ? 'scope-too-large' : 'exhausted',
 			),
 		);
 	}