@gitkraken/core-gitlens 0.4.101 → 0.5.101

package/src/git-cli/providers/pausedOperations.ts

@@ -509,7 +509,10 @@ export class PausedOperationsGitSubProvider implements GitPausedOperationsSubPro
 	}
 
 	@debug()
-	async continuePausedOperation(repoPath: string, options?: { skip?: boolean }): Promise<void> {
+	async continuePausedOperation(
+		repoPath: string,
+		options?: { skip?: boolean; messageEditor?: string },
+	): Promise<void> {
 		const scope = getScopedLogger();
 
 		const status = await this.getPausedOperationStatus(repoPath);
@@ -521,8 +524,32 @@ export class PausedOperationsGitSubProvider implements GitPausedOperationsSubPro
 
 		const args = [status.type, options?.skip ? '--skip' : '--continue'];
 
+		// Continuing after a conflicted step can open the commit-message editor (merge-backend rebases,
+		// cherry-picks, and reverts). `GIT_EDITOR` is what git honors for that step, so set it on the
+		// environment; also set `core.editor` config as a fallback.
+		const configs: string[] = [];
+		let env: Record<string, string | undefined> | undefined;
+		if (options?.messageEditor) {
+			configs.push('-c', `core.editor=${options.messageEditor}`);
+			env = { GIT_EDITOR: options.messageEditor };
+		}
+
 		try {
-			await this.git.run({ cwd: repoPath, errors: 'throw' }, ...args);
+			await this.git.run(
+				{
+					cwd: repoPath,
+					errors: 'throw',
+					configs: configs,
+					env: env,
+					// The runner dedups in-flight commands by args only — it ignores per-call `configs`/`env`.
+					// A headless continue (with `GIT_EDITOR`) and a plain `--continue` would therefore collapse
+					// into one execution, so the plain one could silently run headless (auto-accepting a commit
+					// message) or the headless one could ride a plain continue and open an editor that hangs the
+					// loop. Tag the headless variant so it can't share a pending command with the plain one.
+					correlationKey: options?.messageEditor ? 'paused-op-continue-headless' : undefined,
+				},
+				...args,
+			);
 			this.context.hooks?.cache?.onReset?.(repoPath, 'branches', 'status');
 			this.context.hooks?.repository?.onChanged?.(repoPath, ['head', 'heads', 'index']);
 		} catch (ex) {

package/src/git-cli/providers/staging.ts

@@ -58,7 +58,14 @@ export class StagingGitSubProvider implements GitStagingSubProvider {
 					if (gitDir == null) throw new Error(`Unable to determine git directory for ${repoPath}`);
 
 					const currentIndex = joinPaths(gitDir.uri.fsPath, 'index');
-					await fs.copyFile(currentIndex, tempIndex);
+					try {
+						await fs.copyFile(currentIndex, tempIndex);
+					} catch (ex) {
+						// A repo that has never staged anything has no index file yet; git reads a missing
+						// `GIT_INDEX_FILE` as an empty index, which is what 'current' means there. Any other
+						// failure is real — don't silently hand back an index claiming everything is deleted.
+						if ((ex as NodeJS.ErrnoException)?.code !== 'ENOENT') throw ex;
+					}
 					break;
 				}
 				case 'ref': {

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

@@ -3638,7 +3638,7 @@ export class GitHubApi {
 				endCursor?: string | null;
 				hasNextPage: boolean;
 			};
-			nodes: GitHubIssue[];
+			nodes: (GitHubIssue | null)[] | null;
 		};
 		interface SearchResult {
 			authored?: SearchCategory;
@@ -3777,16 +3777,26 @@ export class GitHubApi {
 				cancellation,
 			);
 
-			function toQueryResult(issue: GitHubIssue): IssueShape {
-				return fromGitHubIssue(issue, provider);
-			}
-
 			if (rsp == null) return { values: [], hasMore: false, page: page, truncated: false };
 
+			// Map node-by-node so one unmappable issue can't discard the whole result set
+			const issues: IssueShape[] = [];
+			for (const node of [
+				...(rsp.assigned?.nodes ?? []),
+				...(rsp.mentioned?.nodes ?? []),
+				...(rsp.authored?.nodes ?? []),
+			]) {
+				if (node?.id == null) continue;
+
+				try {
+					issues.push(fromGitHubIssue(node, provider));
+				} catch (ex) {
+					scope?.warn(`skipped unmappable issue; id=${node.id}, url=${node.url}, ex=${ex}`);
+				}
+			}
+
 			const results: IterableIterator<IssueShape> = uniqueBy(
-				[...(rsp.assigned?.nodes ?? []), ...(rsp.mentioned?.nodes ?? []), ...(rsp.authored?.nodes ?? [])].map(
-					toQueryResult,
-				),
+				issues,
 				r => r.url,
 				(original, _current) => original,
 			);
@@ -3910,7 +3920,7 @@ export class GitHubApi {
 					scope,
 					cancellation,
 				);
-				if (rsp == null) return [];
+				if (rsp == null) return results;
 
 				const pageResults = filterPullRequestsBySearchState(
 					rsp.search.nodes.map(pr => fromGitHubPullRequest(pr, provider)),

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 { PullRequestState } from '../../git/models/pullRequest.js';
+import type { PullRequestMember, PullRequestState } from '../../git/models/pullRequest.js';
 import {
 	PullRequest,
 	PullRequestMergeableState,
@@ -131,8 +131,9 @@ export type GitHubPullRequestState = 'OPEN' | 'CLOSED' | 'MERGED';
 export type GitHubIssueOrPullRequestState = GitHubIssueState | GitHubPullRequestState;
 
 export interface GitHubPullRequestLite extends Omit<GitHubIssueOrPullRequest, '__typename'> {
-	author: GitHubMember;
-	body: string;
+	/** `Actor` is nullable in GitHub's schema — `null` once the author's account is deleted */
+	author: GitHubMember | null;
+	body: string | null;
 
 	baseRefName: string;
 	baseRefOid: string;
@@ -167,7 +168,8 @@ export interface GitHubPullRequestLite extends Omit<GitHubIssueOrPullRequest, '_
 }
 
 export interface GitHubIssue extends Omit<GitHubIssueOrPullRequest, '__typename'> {
-	author: GitHubMember;
+	/** `Actor` is nullable in GitHub's schema — `null` once the author's account is deleted */
+	author: GitHubMember | null;
 	assignees: { nodes: GitHubMember[] };
 	comments?: {
 		totalCount: number;
@@ -203,7 +205,7 @@ export interface GitHubPullRequest extends GitHubPullRequestLite {
 	reviewDecision: GitHubPullRequestReviewDecision;
 	latestReviews: {
 		nodes: {
-			author: GitHubMember;
+			author: GitHubMember | null;
 			state: GitHubPullRequestReviewState;
 		}[];
 	};
@@ -234,15 +236,17 @@ export type GitHubViewerPermission =
 	| 'READ' // Can read and clone this repository. Can also open and comment on issues and pull requests
 	| 'NONE';
 
+/** `ghost` is how github.com renders an actor whose account was deleted */
+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 };
+}
+
 export function fromGitHubPullRequestLite(pr: GitHubPullRequestLite, provider: Provider): PullRequest {
 	return new PullRequest(
 		provider,
-		{
-			id: pr.author.login,
-			name: pr.author.login,
-			avatarUrl: pr.author.avatarUrl,
-			url: pr.author.url,
-		},
+		fromGitHubMemberOrGhost(pr.author),
 		String(pr.number),
 		pr.id,
 		pr.title,
@@ -296,7 +300,7 @@ export function fromGitHubPullRequestLite(pr: GitHubPullRequestLite, provider: P
 		undefined, // statusCheckRollupState
 		undefined, // project
 		undefined, // version
-		pr.body,
+		pr.body ?? undefined,
 	);
 }
 
@@ -399,12 +403,7 @@ export function fromGitHubPullRequestStatusCheckRollupState(
 export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider): PullRequest {
 	return new PullRequest(
 		provider,
-		{
-			id: pr.author.login,
-			name: pr.author.login,
-			avatarUrl: pr.author.avatarUrl,
-			url: pr.author.url,
-		},
+		fromGitHubMemberOrGhost(pr.author),
 		String(pr.number),
 		pr.id,
 		pr.title,
@@ -469,12 +468,7 @@ export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider)
 			)
 			.filter(<T>(r?: T): r is T => Boolean(r)),
 		pr.latestReviews.nodes.map(r => ({
-			reviewer: {
-				id: r.author.login,
-				name: r.author.login,
-				avatarUrl: r.author.avatarUrl,
-				url: r.author.url,
-			},
+			reviewer: fromGitHubMemberOrGhost(r.author),
 			state: fromGitHubPullRequestReviewState(r.state),
 		})),
 		pr.assignees.nodes.map(r => ({
@@ -486,7 +480,7 @@ export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider)
 		fromGitHubPullRequestStatusCheckRollupState(pr.commits.nodes?.[0]?.commit.statusCheckRollup?.state),
 		undefined, // project
 		undefined, // version
-		pr.body,
+		pr.body ?? undefined,
 	);
 }
 
@@ -506,12 +500,14 @@ export function fromGitHubIssue(value: GitHubIssue, provider: Provider): Issue {
 		new Date(value.updatedAt),
 		value.closed,
 		fromGitHubIssueOrPullRequestState(value.state),
-		{
-			id: value.author.login,
-			name: value.author.login,
-			avatarUrl: value.author.avatarUrl,
-			url: value.author.url,
-		},
+		value.author == null
+			? undefined
+			: {
+					id: value.author.login,
+					name: value.author.login,
+					avatarUrl: value.author.avatarUrl,
+					url: value.author.url,
+				},
 		value.assignees.nodes.map(assignee => ({
 			id: assignee.login,
 			name: assignee.login,

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

@@ -21,8 +21,6 @@ import type {
 	GitGraphSessionChangedChannels,
 	GitGraphSessionRefreshOptions,
 	GitGraphSessionRefreshResult,
-	GitGraphSessionSnapshot,
-	GraphSessionRestoreResult,
 } from '../../../../git/models/graphSession.js';
 import type { GitLog } from '../../../../git/models/log.js';
 import type { GitRemote } from '../../../../git/models/remote.js';
@@ -52,14 +50,12 @@ export class GraphGitSubProvider implements GitGraphSubProvider {
 			rev?: string;
 			limit?: number;
 			include?: { stats?: boolean };
-			restore?: GitGraphSessionSnapshot;
-			onRestore?: (result: GraphSessionRestoreResult) => void;
 		},
 		cancellation?: AbortSignal,
 	): Promise<GitGraphSession> {
 		// GitHub-backed graphs have no incremental machinery (and `getGraph` takes no row processor); the
-		// session is a thin window accumulator over full fetches. `rowProcessor` and `restore`/`onRestore`
-		// (there's no incremental restore path) are accepted for interface parity and ignored — always a full walk.
+		// session is a thin window accumulator over full fetches. `rowProcessor` is accepted for interface
+		// parity and ignored — always a full walk.
 		const session = new GraphSession(this, repoPath);
 		await session.initialize(options, cancellation);
 		return session;
@@ -295,10 +291,12 @@ export class GraphGitSubProvider implements GitGraphSubProvider {
 				date: commit.committer.date.getTime(),
 				commitDate: commit.committer.date.getTime(),
 				message: commit.message?.length ? commit.message : commit.summary,
-				type: commit.parents.length > 1 ? 'merge-node' : 'commit-node',
-				heads: refHeads,
-				remotes: refRemoteHeads,
-				tags: refTags,
+				kind: commit.parents.length > 1 ? 'merge' : 'commit',
+				// Omitted rather than empty: an empty array still counts as "present" to the splice
+				// fingerprint, which defeats its bare-row skip and makes every ref-less row look changeable.
+				heads: refHeads.length ? refHeads : undefined,
+				remotes: refRemoteHeads.length ? refRemoteHeads : undefined,
+				tags: refTags.length ? refTags : undefined,
 			});
 
 			if (commit.stats != null) {
@@ -623,11 +621,6 @@ class GraphSession implements GitGraphSession {
 		return true;
 	}
 
-	serialize(): GitGraphSessionSnapshot | undefined {
-		// No incremental restore path (no ref-tip gate / reachability table), so nothing worth persisting.
-		return undefined;
-	}
-
 	dispose(): void {
 		// No-op — the window lives entirely in memory.
 	}

package/src/plus/integrations/authentication/integrationAuthenticationProvider.ts

@@ -32,6 +32,38 @@ export interface IntegrationAuthenticationSessionDescriptor {
 	[key: string]: unknown;
 }
 
+/**
+ * Options for {@link IntegrationAuthenticationProvider.getSession}. The two variants keep `sync` exclusive
+ * with the interactive flags: a sync resolves whatever the cloud already has, so it must never open a connect
+ * window.
+ *
+ * `refreshRejectedToken` marks the stored token as known-refused by the provider (an `AuthenticationError` on
+ * a previous read), which forces a cloud `/refresh` even when the token's expiry still claims it is valid —
+ * the case a purely time-based refresh cannot see. The refresh token itself never reaches the client: the GK
+ * cloud performs the exchange server-side.
+ */
+export type GetSessionOptions =
+	| {
+			createIfNeeded?: boolean;
+			forceNewSession?: boolean;
+			sync?: never;
+			refreshRejectedToken?: boolean;
+			source?: Sources;
+	  }
+	| {
+			createIfNeeded?: never;
+			forceNewSession?: never;
+			sync: boolean;
+			refreshRejectedToken?: boolean;
+			source?: Sources;
+	  };
+
+/**
+ * What {@link IntegrationAuthenticationProviderBase.getSession} passes down once it has decided the stored
+ * session can't be served as-is. `refreshIfExpired` is its own conclusion, not a caller's option.
+ */
+type GetNewSessionOptions = GetSessionOptions & { refreshIfExpired?: boolean };
+
 export interface IntegrationAuthenticationProvider extends Disposable {
 	/**
 	 * Clears the stored secret for one connection only (never the whole provider). Unlike
@@ -46,11 +78,13 @@ export interface IntegrationAuthenticationProvider extends Disposable {
 		options?: { preserveConfigured?: boolean },
 	): Promise<void>;
 	deleteAllSessions(descriptor?: IntegrationAuthenticationSessionDescriptor): Promise<void>;
+	/**
+	 * Resolves the session for `descriptor`, from storage when it is still usable and from the cloud
+	 * otherwise. See {@link GetSessionOptions}.
+	 */
 	getSession(
 		descriptor: IntegrationAuthenticationSessionDescriptor,
-		options?:
-			| { createIfNeeded?: boolean; forceNewSession?: boolean; sync?: never; source?: Sources }
-			| { createIfNeeded?: never; forceNewSession?: never; sync: boolean; source?: Sources },
+		options?: GetSessionOptions,
 	): Promise<ProviderAuthenticationSession | undefined>;
 	get onDidChange(): Event<void>;
 }
@@ -120,9 +154,7 @@ abstract class IntegrationAuthenticationProviderBase<
 	@trace()
 	async getSession(
 		descriptor: IntegrationAuthenticationSessionDescriptor,
-		options?:
-			| { createIfNeeded?: boolean; forceNewSession?: boolean; sync?: never; source?: Sources }
-			| { createIfNeeded?: never; forceNewSession?: never; sync: boolean; source?: Sources },
+		options?: GetSessionOptions,
 	): Promise<ProviderAuthenticationSession | undefined> {
 		let session;
 		let previousToken;
@@ -143,10 +175,15 @@ abstract class IntegrationAuthenticationProviderBase<
 		}
 
 		const isExpiredSession = session?.expiresAt != null && new Date(session.expiresAt).getTime() < Date.now();
-		if (session == null || isExpiredSession) {
+		// A rejected token has to re-resolve even when the stored session looks perfectly healthy: that is
+		// the whole point — the provider refused it while its expiry still says valid. Without this the
+		// stored session short-circuits here and the refresh below is never reached.
+		const refreshRejectedToken = options?.refreshRejectedToken === true && session != null;
+		if (session == null || isExpiredSession || refreshRejectedToken) {
 			session = await this.getNewSession(descriptor, {
 				...options,
 				refreshIfExpired: isExpiredSession,
+				refreshRejectedToken: refreshRejectedToken,
 			});
 
 			if (session != null) {
@@ -163,21 +200,7 @@ abstract class IntegrationAuthenticationProviderBase<
 
 	protected abstract getNewSession(
 		descriptor: IntegrationAuthenticationSessionDescriptor,
-		options?:
-			| {
-					createIfNeeded?: boolean;
-					forceNewSession?: boolean;
-					sync?: never;
-					refreshIfExpired?: boolean;
-					source?: Sources;
-			  }
-			| {
-					createIfNeeded?: never;
-					forceNewSession?: never;
-					sync: boolean;
-					refreshIfExpired?: boolean;
-					source?: Sources;
-			  },
+		options?: GetNewSessionOptions,
 	): Promise<ProviderAuthenticationSession | undefined>;
 
 	protected fireChange(): void {
@@ -202,21 +225,7 @@ export class CloudIntegrationAuthenticationProvider<
 
 	protected override async getNewSession(
 		descriptor: IntegrationAuthenticationSessionDescriptor,
-		options?:
-			| {
-					createIfNeeded?: boolean;
-					forceNewSession?: boolean;
-					sync?: never;
-					refreshIfExpired?: boolean;
-					source?: Sources;
-			  }
-			| {
-					createIfNeeded?: never;
-					forceNewSession?: never;
-					sync: boolean;
-					refreshIfExpired?: boolean;
-					source?: Sources;
-			  },
+		options?: GetNewSessionOptions,
 	): Promise<ProviderAuthenticationSession | undefined> {
 		if (options?.forceNewSession) {
 			if ((await this.disconnectCloudSession()) === 'failure') {
@@ -230,9 +239,15 @@ export class CloudIntegrationAuthenticationProvider<
 		// TODO: This is a stopgap to make sure we're not hammering the api on automatic calls to get the session.
 		// Ultimately we want to timestamp calls to syncCloudIntegrations and use that to determine whether we should
 		// make the call or not.
+		// `refreshRejectedToken` joins the list for the same reason `refreshIfExpired` is on it: both mean the
+		// session in hand is known-unusable, so skipping the cloud round trip would just re-serve it.
 		let session =
-			options?.refreshIfExpired || options?.createIfNeeded || options?.forceNewSession || options?.sync
-				? await this.getCloudSession(descriptor)
+			options?.refreshIfExpired ||
+			options?.refreshRejectedToken ||
+			options?.createIfNeeded ||
+			options?.forceNewSession ||
+			options?.sync
+				? await this.getCloudSession(descriptor, { refreshRejectedToken: options?.refreshRejectedToken })
 				: undefined;
 
 		const shouldCreateSession = options?.createIfNeeded && session == null;
@@ -269,6 +284,7 @@ export class CloudIntegrationAuthenticationProvider<
 
 	private async getCloudSession(
 		descriptor: IntegrationAuthenticationSessionDescriptor,
+		options?: { refreshRejectedToken?: boolean },
 	): Promise<ProviderAuthenticationSession | undefined> {
 		const loggedIn = (await this.authenticationService.ctx.account.getAccount()) != null;
 		if (!loggedIn) return undefined;
@@ -304,7 +320,13 @@ export class CloudIntegrationAuthenticationProvider<
 			session.expiresIn = maxSmallIntegerV8; // maximum expiration length
 		}
 
-		if (session != null && session.expiresIn < 60) {
+		// `expiresIn < 60` is a PREDICTION that the token is about to lapse, and it is the only trigger the
+		// refresh used to have. It cannot see a token the provider has already refused while the backend
+		// still believes it is valid — a revoked grant, retired scopes, an app removed from the org — where
+		// `expiresIn` stays high and the doomed token is re-sent on every read. `refreshRejectedToken` is
+		// the observed counterpart: the caller saw the provider reject this exact token, so refresh it
+		// regardless of what its expiry claims.
+		if (session != null && (session.expiresIn < 60 || options?.refreshRejectedToken)) {
 			session = await cloudIntegrations.getConnectionSession(
 				this.authProviderId,
 				session.accessToken,

package/src/plus/integrations/authentication/rejectedTokenTracker.ts

@@ -0,0 +1,56 @@
+/**
+ * Per-connection recovery state for a cloud token the provider REFUSED — a revoked grant, retired scopes, an
+ * app removed from the org. A purely predictive refresh (`expiresIn < 60`) cannot see that case, because the
+ * backend still believes the token is valid, so without this the refused token is re-sent on every read and
+ * the failure only clears when the user reconnects by hand.
+ *
+ * One recovery refresh per connection, then the connection is the failure budget's problem:
+ * - {@link recordRejection} on an `AuthenticationError` — arms the refresh, or reports that the rejection is
+ *   not recoverable so the caller counts it as a real failure instead.
+ * - {@link claimRefresh} before the next read resolves its session — spends the rejection, so the refresh
+ *   fires once and no further read of that connection asks the cloud again.
+ *
+ * Deliberately NOT re-armed when the refresh hands back a different token. The GK cloud mints a new access
+ * token on every `/refresh`, so a credential the provider refuses for a reason a refresh cannot fix (retired
+ * scopes being the plain case) would look "rotated" on each attempt: re-arming on that would refresh on every
+ * read forever and the failure budget — the thing that disconnects and prompts a reconnect — would never
+ * advance. What resets this instead is {@link clear}, called by every path that replaces or removes the stored
+ * tokens; a connection that is simply working never reaches here at all.
+ */
+export class RejectedTokenTracker {
+	private readonly _rejections = new Map<string, 'armed' | 'spent'>();
+
+	/**
+	 * Whether a read of `connectionId` must force the cloud refresh of a token known to be refused, spending
+	 * the rejection so the refresh runs at most once. Spent here rather than after the read because a resolve
+	 * that throws must not leave the refresh armed and ask the cloud again on the next read.
+	 */
+	claimRefresh(connectionId: string): boolean {
+		if (this._rejections.get(connectionId) !== 'armed') return false;
+
+		this._rejections.set(connectionId, 'spent');
+		return true;
+	}
+
+	/**
+	 * Arms the recovery refresh for `connectionId`. Returns `false` once this connection has had its refresh
+	 * (or already has one pending), so the caller falls back to its own failure handling: a token still
+	 * refused after the refresh is not self-healing, and only the failure budget ends in a reconnect prompt.
+	 */
+	recordRejection(connectionId: string): boolean {
+		if (this._rejections.has(connectionId)) return false;
+
+		this._rejections.set(connectionId, 'armed');
+		return true;
+	}
+
+	/** Drops all state, for when the stored tokens a rejection could name are replaced or gone. */
+	clear(): void {
+		this._rejections.clear();
+	}
+
+	/** Whether any connection is holding a rejection. For assertions; the read path uses {@link claimRefresh}. */
+	get empty(): boolean {
+		return this._rejections.size === 0;
+	}
+}

package/src/plus/integrations/collectionMetadata.ts

@@ -1,4 +1,9 @@
-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';
@@ -68,8 +73,21 @@ function toCollectionFailureWarningKind(failure: CollectionScopeFailure): Provid
 	}
 }
 
-function collectionFailureMessage(failure: CollectionScopeFailure): string {
-	const scope = failure.scope;
+/**
+ * A scope's identity, as the stable string that keys it.
+ *
+ * The dedup keys in `providerPaging.ts` build on this, so failures and omissions can never disagree about
+ * what "the same scope" means. `providerId` is included: the same repository ID under two providers is two
+ * scopes.
+ */
+export function collectionScopeKey(scope: CollectionScope | undefined): string {
+	return [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(
+		' ',
+	);
+}
+
+/** ` (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 +99,64 @@ 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, so retrying the same request cannot recover them. That is why
+ * these never contribute to `fetchFailed`.
+ */
+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`;
+	}
+}
+
+/**
+ * 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 +182,25 @@ 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 succeeded, so a retry would return the same truncated set.
+	const omissions = metadata.omissions ?? [];
+	for (const omission of omissions) {
+		appendDedupedWarning(warnings, {
+			providerId: providerId,
+			domain: domain,
+			connectionId: connectionId,
+			message: collectionOmissionMessage(omission),
+			kind: 'other',
+			isAuth: false,
+		});
+	}
+
+	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.
+	if (incomplete && failures.length === 0 && omissions.length === 0) {
 		appendDedupedWarning(warnings, {
 			providerId: providerId,
 			domain: domain,