@gitkraken/core-gitlens 0.5.101 → 0.5.102

package/dist/plus/integrations/results.js

@@ -48,11 +48,86 @@ export function toProviderWarning(providerId, domain, connectionId, ex) {
         isAuth: kind === 'auth',
     };
 }
-/** A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes. */
+/**
+ * A scope's identity, as the stable string that keys it.
+ *
+ * The single definition of what "the same scope" means, shared by the failure and omission dedup keys in
+ * `providerPaging.ts` and by {@link providerWarningKey} below, so a scope gaining a field is one edit rather
+ * than three. `providerId` is included: the same repository ID under two providers is two scopes.
+ *
+ * The parameter is structural rather than the SDK's `CollectionScope` so this module keeps naming no
+ * `@gitkraken/provider-apis` types (see the export block in `index.ts`) while still serving its SDK-facing
+ * callers, which pass that type in unchanged.
+ */
+export function collectionScopeKey(scope) {
+    return [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(' ');
+}
+/**
+ * The omission's contribution to a warning's identity — empty when there is none, so a warning without an
+ * omission keeps deduping exactly as it did before the field existed.
+ *
+ * Two omissions of different kinds do produce different `message` values today, so message alone would still
+ * separate them. That is incidental: the premise of `omission` is that consumers must not depend on prose
+ * carrying the distinguishing fact, and this key must not either.
+ */
+function providerWarningOmissionKey(omission) {
+    if (omission == null)
+        return '';
+    return [
+        omission.kind,
+        omission.recovery,
+        omission.limit ?? '',
+        omission.totalCount ?? '',
+        collectionScopeKey(omission.scope),
+    ].join(' ');
+}
+/**
+ * Strips the omission from every warning in `warnings` when the read as a whole failed.
+ *
+ * An omission asserts the request SUCCEEDED, and a drain only learns it failed AFTER it may have emitted one:
+ * an early page can report its own truncation and then a later page can die. Deciding per warning, at the
+ * moment each is built, cannot see that future — so the aggregate is reconciled once, here, where
+ * `fetchFailed` is final. Call it at the point a read returns its `fetchFailed`.
+ *
+ * Re-dedupes as it goes: the omission is part of a warning's identity, so two warnings that differed only
+ * there become identical once it is gone, and the array's contract is that no two entries are equal.
+ *
+ * Mutates in place: the warning array is the one being returned, and callers accumulate into it across pages.
+ */
+export function reconcileOmissionsWithFailure(warnings, fetchFailed) {
+    if (!fetchFailed || !warnings.some(w => w.omission != null))
+        return;
+    const reconciled = [];
+    for (const warning of warnings) {
+        if (warning.omission == null) {
+            appendDedupedWarning(reconciled, warning);
+            continue;
+        }
+        const { omission: _omission, ...rest } = warning;
+        appendDedupedWarning(reconciled, rest);
+    }
+    warnings.splice(0, warnings.length, ...reconciled);
+}
+/**
+ * A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes.
+ *
+ * `message` stays LAST. It is the only free-form segment — provider prose, spaces and all — so anything
+ * appended after it could be impersonated by a message that happens to end in the same text.
+ */
 function providerWarningKey(warning) {
-    return [warning.providerId, warning.connectionId ?? '', warning.domain ?? '', warning.kind, warning.message].join(' ');
+    return [
+        warning.providerId,
+        warning.connectionId ?? '',
+        warning.domain ?? '',
+        warning.kind,
+        providerWarningOmissionKey(warning.omission),
+        warning.message,
+    ].join(' ');
 }
-/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+/**
+ * Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message, plus the
+ * structured omission when one is present) is absent.
+ */
 export function appendDedupedWarning(into, warning) {
     const key = providerWarningKey(warning);
     if (into.some(existing => providerWarningKey(existing) === key))

package/dist/plus/integrations/results.js.map

@@ -1 +1 @@
-{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AA8K1G,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAE5C,SAAS,sBAAsB,CAAC,EAAW;IAC1C,MAAM,GAAG,GAAG,CAAC,EAAE,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,MAAM,OAAO,GAAG,EAA8E,CAAC;IAC/F,MAAM,MAAM,GACX,OAAO,OAAO,EAAE,MAAM,KAAK,QAAQ;QAClC,CAAC,CAAC,OAAO,CAAC,MAAM;QAChB,CAAC,CAAC,OAAO,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,QAAQ;YAC9C,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM;YACzB,CAAC,CAAC,SAAS,CAAC;IAEf,4GAA4G;IAC5G,6GAA6G;IAC7G,IAAI,wCAAwC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,uCAAuC,MAAM,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvG,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,uCAAuC,MAAM,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvG,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,GAAG,+BAA+B;QAClD,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,+BAA+B,GAAG,CAAC,CAAC,KAAK;QAC3D,CAAC,CAAC,GAAG,CAAC;AACR,CAAC;AA+BD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAChC,UAA0B,EAC1B,MAA0B,EAC1B,YAAgC,EAChC,EAAW;IAEX,IAAI,IAA6B,CAAC;IAClC,IAAI,EAAE,YAAY,mBAAmB,EAAE,CAAC;QACvC,IAAI,GAAG,MAAM,CAAC;IACf,CAAC;SAAM,IAAI,EAAE,YAAY,qBAAqB,EAAE,CAAC;QAChD,IAAI,GAAG,YAAY,CAAC;IACrB,CAAC;SAAM,IAAI,EAAE,YAAY,oBAAoB,EAAE,CAAC;QAC/C,IAAI,GAAG,WAAW,CAAC;IACpB,CAAC;SAAM,CAAC;QACP,IAAI,GAAG,OAAO,CAAC;IAChB,CAAC;IAED,OAAO;QACN,UAAU,EAAE,UAAU;QACtB,MAAM,EAAE,MAAM;QACd,YAAY,EAAE,YAAY;QAC1B,OAAO,EAAE,sBAAsB,CAAC,EAAE,CAAC;QACnC,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,IAAI,KAAK,MAAM;KACvB,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,SAAS,kBAAkB,CAAC,OAAwB;IACnD,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAChH,GAAG,CACH,CAAC;AACH,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,oBAAoB,CAAC,IAAuB,EAAE,OAAwB;IACrF,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC;QAAE,OAAO;IAExE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACpB,CAAC"}
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"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"}

package/docs/integrations.md

@@ -177,13 +177,13 @@ result** instead of rejecting the call. One provider's expired token never blank
 `ProviderWarning.kind` (also exported as `ProviderWarningKind`) carries the classifications the facade can
 prove from structured errors:
 
-| `kind`          | Meaning                                                                                       | Reasonable response                                                                         |
-| --------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `auth`          | Token rejected (401/403 that isn't a throttle).                                               | Prompt to reconnect that connection.                                                        |
-| `rate-limit`    | Throttled (429, or a 403 whose body says so).                                                 | Back off and retry; keep the last snapshot.                                                 |
-| `not-found`     | 404/410/422 on the requested scope.                                                           | Drop that scope; don't reconnect.                                                           |
-| `no-connection` | The requested `connectionId`/`domain` doesn't resolve.                                        | Re-resolve the target or re-authenticate.                                                   |
-| `other`         | Catch-all: unsupported input, truncation, upstream/network failure, or an unclassified error. | Preserve the warning and use the result flags; do not assume it is benign or non-retryable. |
+| `kind`          | Meaning                                                                                                                                         | Reasonable response                                                                         |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                 | Prompt to reconnect that connection.                                                        |
+| `rate-limit`    | Throttled (429, or a 403 whose body says so).                                                                                                   | Back off and retry; keep the last snapshot.                                                 |
+| `not-found`     | 404/410/422 on the requested scope.                                                                                                             | Drop that scope; don't reconnect.                                                           |
+| `no-connection` | The requested `connectionId`/`domain` doesn't resolve.                                                                                          | Re-resolve the target or re-authenticate.                                                   |
+| `other`         | Catch-all: unsupported input, truncation, upstream/network failure, or an unclassified error. Read `omission` before treating one as a failure. | Preserve the warning and use the result flags; do not assume it is benign or non-retryable. |
 
 `isAuth` is a convenience mirror of `kind === 'auth'`. **Collapsing `kind` into that boolean loses the
 rate-limit and not-found distinctions**, which then have to be re-derived from raw provider prose.
@@ -191,6 +191,70 @@ Conversely, `other` is intentionally not a complete failure taxonomy. Treat `mes
 text rather than a stable protocol; use `fetchFailed`, `page.truncated`, and `page.allPages` for completeness
 and keep unknown failures conservative.
 
+### `omission` — succeeded, but withheld results
+
+`other` covers two facts with **opposite remedies**: a request that failed, and a request that succeeded while
+part of the answer was withheld. `ProviderWarning.omission` is set only for the second, so a consumer can act
+on it without parsing `message`:
+
+```ts
+if (warning.omission != null) {
+	// The read SUCCEEDED — message it as incompleteness, not failure.
+	// Whether anything would fetch the rest is a separate question; see `recovery` below.
+	if (warning.omission.recovery !== 'none') offerLoadMore(warning.omission);
+}
+```
+
+`kind` stays `'other'` for these on purpose: it is the discriminant derived from a caught exception's type, and
+adding a member would silently change what `'other'` means for every existing build.
+
+**Its absence proves nothing.** It is never set on a failure — an exception or a structured scope failure —
+where it would be a lie. But it is also absent whenever incompleteness was reported without naming what was
+left out, so treat a bare `kind: 'other'` warning as unclassified rather than as a proven failure.
+
+The line that matters is whether the request **succeeded**, not whether a tail was left unread. A drain that
+stopped on its own accounting succeeded and is capped, so it carries the omission; a drain that was interrupted
+mid-read left an unread tail too, but a retry may complete it — that one carries no omission and sets
+`fetchFailed`.
+
+`kind` says **why** results are missing:
+
+| `omission.kind`         | What happened                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `provider-limit`        | The provider refuses to serve past a cap (GitHub search's 1,000, Trello's `cards_limit`).                                          |
+| `recovery-budget`       | The internal partitioned recovery stopped before visiting every partition.                                                         |
+| `pagination-incomplete` | Pages were left unread: an undrained sub-scope, a page budget, or a provider that advertised another page without a usable cursor. |
+
+#### `recovery` — what, if anything, would fetch the rest
+
+**`kind` does not answer that**, and `pagination-incomplete` is why: a drain that stopped at a page budget and
+a provider that gave no usable cursor are the same kind, but only the first can be fetched. Gate a "load more"
+affordance on `recovery`, never on `kind`:
+
+| `omission.recovery` | Means                                                          | What a consumer does                                                       |
+| ------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `none`              | Nothing you can call returns the missing items.                | Say the results are capped. Do not offer to fetch more.                    |
+| `page-budget`       | Re-run the same read with a higher `maxPages` (sweep options). | Offer it — but note it re-reads from the start, so make it user-initiated. |
+
+`recovery` is **required** — unlike `limit`, `totalCount` and `scope`, it is never absent. An absent value
+would be indistinguishable from `none` while actually meaning "this producer didn't say", which is the
+ambiguity `omission` exists to remove.
+
+It is also **conservative**: it names only what a producer can prove, so `none` means "not known to be
+recoverable", not "proven unrecoverable". Today only a sweep that spent its own page budget reports
+`page-budget`; everything else — every provider cap, every exhausted internal budget, and every omission
+derived from SDK metadata — is `none`. A `scope` does not change that. It attributes where results were
+withheld, and the SDK reports the same scoped shape both for a scope it merely sampled and for one whose
+cursor stalled, so re-reading it is not something this layer can promise.
+
+`limit`, `totalCount` and `scope` are forwarded only when reported; **most omissions carry none of the three**,
+so render correctly without them. Two traps: `totalCount` is `number | undefined` and never `null` (the SDK's
+`null` is normalized to absent at the boundary), and `limit` on `recovery-budget` is a **request** budget — do
+not show it to a user as a number of results.
+
+Warnings dedup on their structure, `omission` included, so two omissions that differ only in kind, recovery or
+scope stay two warnings even if their messages ever converge.
+
 | Flag                    | Says                                                                                                                                          |
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `fetchFailed`           | `items` is incomplete because a scope failed, or because a flat hierarchy read was truncated. Distinguishes this from a genuine empty result. |
@@ -199,6 +263,16 @@ and keep unknown failures conservative.
 | `failedProviderIds`     | Sweeps/broadens: providers whose requested scopes produced no usable result.                                                                  |
 | `incompleteProviderIds` | Sweeps/broadens: providers with a usable result plus a failed, partial, or truncated sibling scope.                                           |
 
+An omission pairs with `page.truncated: true` — results are missing — and typically with `fetchFailed: false`,
+since nothing failed. But the flags are **per result** and `omission` is **per warning**, so the two can differ
+on a fan-out: a sweep where provider A was capped and provider B failed outright reports `fetchFailed: true`
+while A's omission stays true for A. Read `omission` on the warning that carries it — its `providerId`,
+`domain` and `connectionId` say who it is about — rather than inferring it from the aggregate.
+
+What is guaranteed is the narrower thing: a warning never claims its own read succeeded when it didn't. A drain
+that dies mid-read publishes its unread tail with no omission, even if an earlier page had already reported
+one.
+
 `resolveRepository` reports through `resolution.status` instead: `resolved` · `not-found` · `unauthorized` ·
 `unsupported-provider` · `invalid-remote-url` · `host-mismatch` · `undetermined`. A `resolved` identity
 carries the provider's **canonical** owner/name plus `renamed: true` when the local remote is stale.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gitkraken/core-gitlens",
   "description": "GitLens core — shared Git / AI / GitHub primitives for internal GitKraken consumption",
-  "version": "0.5.101",
+  "version": "0.5.102",
   "license": "SEE LICENSE IN LICENSE",
   "author": {
     "name": "GitKraken",

package/src/plus/integrations/collectionMetadata.ts

@@ -7,7 +7,7 @@ import type {
 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';
 
 /**
@@ -73,19 +73,6 @@ function toCollectionFailureWarningKind(failure: CollectionScopeFailure): Provid
 	}
 }
 
-/**
- * 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[] = [];
@@ -110,9 +97,10 @@ function collectionFailureMessage(failure: CollectionScopeFailure): string {
 /**
  * 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`.
+ * 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);
@@ -142,6 +130,39 @@ function collectionOmissionMessage(omission: CollectionOmission): string {
 	}
 }
 
+/**
+ * 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.
  *
@@ -184,7 +205,8 @@ export function assessCollectionMetadata(
 
 	// 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.
+	// `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, {
@@ -194,12 +216,17 @@ export function assessCollectionMetadata(
 			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,

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/providers/utils/providerPaging.ts

@@ -6,7 +6,8 @@ import type {
 } from '@gitkraken/provider-apis';
 import { isCancellationError } from '../../../../utils/cancellation.js';
 import { uniqueBy } from '../../../../utils/iterable.js';
-import { collectionScopeKey, toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { collectionScopeKey } from '../../results.js';
 import type { ProviderApiPagedResult, ProviderHierarchyResult } from '../models.js';
 
 /**

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 };
 		}
 

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

@@ -9,12 +9,13 @@ import { isIssuesIntegration } from '../models/issuesIntegration.js';
 import { IssueFilter, providersMetadata } from '../providers/models.js';
 import { mergeCollectionMetadata, parsePageCursor } from '../providers/utils/providerPaging.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
+import { reconcileOmissionsWithFailure } from '../results.js';
 import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
 import type { ProviderReadContext } from './context.js';
 import { parseIssueTrackerPageCursor, toIssueTrackerPageCursor } from './cursors.js';
 import { runCaptured } from './drains.js';
 import { projectKey, resourceIdForProject, resourceLabel, resourceMatchesOrg } from './hierarchy.utils.js';
-import { issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
+import { incompleteReadWarning, issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
 
 export async function listIssueTrackerIssuesPage(
 	ctx: ProviderReadContext,
@@ -431,14 +432,19 @@ export async function listIssueTrackerIssuesPage(
 	// the caller sees the truncation, but only when no warning already explains it (avoid duplicate noise).
 	if (projectTruncated && warnings.length === 0) {
 		warnings.push(
-			otherWarning(
+			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',
 			),
 		);
 	}
+	// A metadata omission from an earlier project asserts the read succeeded; a later one may since have failed.
+	reconcileOmissionsWithFailure(warnings, fetchFailed);
 
 	const retryPages = retryWindowPages();
 	const cursor = toIssueTrackerPageCursor({

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

@@ -6,7 +6,7 @@ import type { IssueFilter, ProviderReposInput } from '../providers/models.js';
 import { PagingMode, providersMetadata } from '../providers/models.js';
 import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
-import { appendDedupedWarning } from '../results.js';
+import { appendDedupedWarning, reconcileOmissionsWithFailure } from '../results.js';
 import {
 	isGitHostIntegration,
 	isIssuesHostIntegrationId,
@@ -269,14 +269,19 @@ export async function listIssuesPage(
 		const truncated = continuation.truncated || assessment.truncated;
 		if (truncated && warnings.length === 0) {
 			warnings.push(
-				otherWarning(
+				truncationWarning(
 					options.providerId,
 					domain,
 					options.connectionId,
-					`Account-wide issue search for '${options.providerId}' was truncated; results may be incomplete.`,
+					'Account-wide issue search',
+					// `exhausted`: this composite read exposes no budget the caller can raise, so nothing it
+					// could call would return the withheld items.
+					assessment.fetchFailed || pageFetchFailed ? 'interrupted' : 'exhausted',
 				),
 			);
 		}
+		// A metadata omission from an earlier page asserts the read succeeded; a later page may since have failed.
+		reconcileOmissionsWithFailure(warnings, assessment.fetchFailed || pageFetchFailed);
 		return {
 			items: items,
 			warnings: warnings,
@@ -385,8 +390,20 @@ export async function listIssuesPage(
 	// page isn't published as complete. Metadata incompleteness is an independent source of the same signal.
 	const truncated = continuation.truncated || assessment.truncated;
 	if (truncated && warnings.length === 0) {
-		warnings.push(truncationWarning(options.providerId, domain, options.connectionId, 'Issue'));
+		warnings.push(
+			truncationWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				'Issue',
+				// `exhausted`, never `page-budget`: a paged read has no budget the caller can raise, and
+				// ordinary continuation is already expressed by `hasMore`/`cursor`.
+				assessment.fetchFailed || pageFetchFailed ? 'interrupted' : 'exhausted',
+			),
+		);
 	}
+	// A metadata omission from an earlier page asserts the read succeeded; a later page may since have failed.
+	reconcileOmissionsWithFailure(warnings, assessment.fetchFailed || pageFetchFailed);
 	return {
 		items: items,
 		warnings: warnings,