pr-shepherd 0.44.1 → 0.46.0

package/bin/comments/rate-limit.mjs

@@ -26,15 +26,21 @@ function buildRateLimitStop(message, meta) {
     const retryAfterSeconds = finiteNumber(meta.retryAfterSeconds);
     const remaining = finiteNumber(meta.rateLimit?.remaining);
     const limit = finiteNumber(meta.rateLimit?.limit);
+    const used = finiteNumber(meta.rateLimit?.used);
     const resetAt = finiteNumber(meta.rateLimit?.resetAt);
+    const resource = typeof meta.rateLimit?.resource === "string" ? meta.rateLimit.resource : undefined;
     if (retryAfterSeconds !== undefined)
         stop.retryAfterSeconds = retryAfterSeconds;
     if (limit !== undefined)
         stop.limit = limit;
+    if (used !== undefined)
+        stop.used = used;
     if (remaining !== undefined)
         stop.remaining = remaining;
     if (resetAt !== undefined)
         stop.resetAt = resetAt;
+    if (resource !== undefined)
+        stop.resource = resource;
     return stop;
 }
 function finiteNumber(value) {

package/bin/comments/review-visibility.d.mts

@@ -24,5 +24,5 @@ export declare function classifyReviewsForDisplay(reviews: Review[], seenMap: Ma
  *
  * Human-authored CR reviews continue to flow through the standard seen-gate.
  */
-export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames): ReviewVisibility;
+export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames, repeatBotReviews?: boolean): ReviewVisibility;
 export {};

package/bin/comments/review-visibility.mjs

@@ -31,7 +31,7 @@ export function classifyReviewsForDisplay(reviews, seenMap) {
  *
  * Human-authored CR reviews continue to flow through the standard seen-gate.
  */
-export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames) {
+export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames, repeatBotReviews = true) {
     const visible = [];
     const toMarkSeen = [];
     for (const review of reviews) {
@@ -39,7 +39,8 @@ export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botU
         const cls = classifyItem(review.id, review.body, seenMap);
         if (isBot) {
             if (cls === "unchanged") {
-                visible.push({ ...review, staleBotCr: true });
+                if (repeatBotReviews)
+                    visible.push({ ...review, staleBotCr: true });
             }
             else if (cls === "edited") {
                 visible.push({ ...review, edited: true });

package/bin/comments/thread-visibility.d.mts

@@ -7,5 +7,5 @@ interface ThreadVisibility {
     firstLookThreads: FirstLookThread[];
     toMarkSeen: ReviewThread[];
 }
-export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames): ThreadVisibility;
+export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames, repeatableThreadIds?: ReadonlySet<string>): ThreadVisibility;
 export {};

package/bin/comments/thread-visibility.mjs

@@ -19,14 +19,15 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
         return null;
     return { ...visible, firstLookStatus };
 }
-export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set()) {
+export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds) {
+    const shouldRepeat = (thread) => repeatableThreadIds?.has(thread.id) ?? true;
     const unresolvedThreads = threads.filter((t) => !t.isResolved);
     const activeThreads = unresolvedThreads
         .filter((t) => !t.isOutdated && !t.isMinimized)
         .flatMap((t) => {
         if (threadEndedByShepherd(t))
             return [];
-        if (isConfiguredBotAuthor(t, botUsernames))
+        if (isConfiguredBotAuthor(t, botUsernames) && shouldRepeat(t))
             return [t];
         const visible = classifyVisibleThread(t, seenMap);
         return visible ? [visible] : [];
@@ -40,7 +41,12 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
         }
         return t.isOutdated || t.isMinimized;
     })
-        .map((t) => classifyVisibleThread(t, seenMap) ?? t);
+        .flatMap((t) => {
+        const visible = classifyVisibleThread(t, seenMap);
+        if (visible)
+            return [visible];
+        return shouldRepeat(t) ? [t] : [];
+    });
     const firstLookThreads = [
         ...threads.flatMap((t) => {
             if (!t.isOutdated)

package/bin/config/load.d.mts

@@ -1,6 +1,10 @@
 declare const MINIMIZE_COMMENTS_POLICIES: readonly ["all", "bots", "users", "none"];
 export type MinimizeCommentsPolicy = (typeof MINIMIZE_COMMENTS_POLICIES)[number];
-interface PrShepherdConfig {
+export interface GraphqlQuotaWarningBand {
+    remainingPercent: number;
+    pollIntervalMinutes: number;
+}
+export interface PrShepherdConfig {
     /** Optional user classification configuration; preserved for rule consumers. */
     classify?: unknown;
     /** GitHub logins that should be treated as bots even when GitHub reports User/Unknown. */
@@ -30,6 +34,7 @@ interface PrShepherdConfig {
     };
     watch: {
         readyDelayMinutes: number;
+        graphqlQuotaWarnings: GraphqlQuotaWarningBand[];
     };
     resolve: {
         shaPoll: {

package/bin/config/load.mjs

@@ -115,6 +115,37 @@ function parseMergeCommandArgs(value) {
     }
     return strategies.length === 0 ? [...value, "--merge"] : [...value];
 }
+function parseGraphqlQuotaWarnings(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("Invalid config: watch.graphqlQuotaWarnings must be an array");
+    }
+    const seen = new Set();
+    const parsed = value.map((item, index) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] must be an object`);
+        }
+        const record = item;
+        const remainingPercent = record["remainingPercent"];
+        const pollIntervalMinutes = record["pollIntervalMinutes"];
+        if (typeof remainingPercent !== "number" ||
+            !Number.isInteger(remainingPercent) ||
+            remainingPercent < 1 ||
+            remainingPercent > 100) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].remainingPercent must be an integer from 1 to 100`);
+        }
+        if (typeof pollIntervalMinutes !== "number" ||
+            !Number.isFinite(pollIntervalMinutes) ||
+            pollIntervalMinutes <= 0) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].pollIntervalMinutes must be a positive number`);
+        }
+        if (seen.has(remainingPercent)) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings has duplicate remainingPercent ${remainingPercent}`);
+        }
+        seen.add(remainingPercent);
+        return { remainingPercent, pollIntervalMinutes };
+    });
+    return parsed.sort((left, right) => right.remainingPercent - left.remainingPercent);
+}
 const KNOWN_CONFIG_KEYS = new Set([
     "classify",
     "botUsernames",
@@ -135,7 +166,7 @@ const KNOWN_NESTED_KEYS = {
         "minimizeComments",
         "behindBaseHint",
     ]),
-    watch: new Set(["readyDelayMinutes"]),
+    watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents"]),
     mergeStatus: new Set(["blockingReviewerLogins"]),
@@ -228,6 +259,7 @@ export function loadConfig() {
         config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
         if (config.merge)
             config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
+        config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;

package/bin/config.json

@@ -22,7 +22,12 @@
     "behindBaseHint": ""
   },
   "watch": {
-    "readyDelayMinutes": 10
+    "readyDelayMinutes": 10,
+    "graphqlQuotaWarnings": [
+      { "remainingPercent": 30, "pollIntervalMinutes": 2 },
+      { "remainingPercent": 20, "pollIntervalMinutes": 5 },
+      { "remainingPercent": 10, "pollIntervalMinutes": 10 }
+    ]
   },
   "resolve": {
     "shaPoll": {

package/bin/github/api-telemetry-aggregate.d.mts

@@ -0,0 +1,32 @@
+import type { ApiTelemetryEvent } from "./api-telemetry.mts";
+import type { RateLimitInfo } from "./http-utils.mts";
+export interface TelemetryAggregate {
+    eventCount: number;
+    credentialSources: Map<string, number>;
+    graphql: {
+        requestCount: number;
+        measuredQueryCost: number;
+        unmeasuredRequestCount: number;
+        nodeCount: number;
+        rateLimit?: RateLimitInfo;
+    };
+    rest: Map<string, {
+        requestCount: number;
+        rateLimit?: RateLimitInfo;
+    }>;
+}
+export interface SequencedApiTelemetryEvent extends ApiTelemetryEvent {
+    sequence: number;
+}
+export interface TelemetryStore {
+    events: SequencedApiTelemetryEvent[];
+    compacted: TelemetryAggregate;
+    eventCount: number;
+    clock: {
+        next: number;
+    };
+}
+export declare function emptyAggregate(): TelemetryAggregate;
+export declare function aggregateEvents(events: SequencedApiTelemetryEvent[]): TelemetryAggregate;
+export declare function mergeAggregate(target: TelemetryAggregate, source: TelemetryAggregate): void;
+export declare function aggregateStore(active: TelemetryStore): TelemetryAggregate;

package/bin/github/api-telemetry-aggregate.mjs

@@ -0,0 +1,84 @@
+export function emptyAggregate() {
+    return {
+        eventCount: 0,
+        credentialSources: new Map(),
+        graphql: { requestCount: 0, measuredQueryCost: 0, unmeasuredRequestCount: 0, nodeCount: 0 },
+        rest: new Map(),
+    };
+}
+export function aggregateEvents(events) {
+    const aggregate = emptyAggregate();
+    for (const event of events) {
+        aggregate.eventCount += 1;
+        if (!aggregate.credentialSources.has(event.authSource)) {
+            aggregate.credentialSources.set(event.authSource, event.sequence);
+        }
+        if (event.kind === "GraphQL") {
+            aggregate.graphql.requestCount += 1;
+            if (event.rateLimit?.cost === undefined)
+                aggregate.graphql.unmeasuredRequestCount += 1;
+            else
+                aggregate.graphql.measuredQueryCost += event.rateLimit.cost;
+            aggregate.graphql.nodeCount += event.rateLimit?.nodeCount ?? 0;
+            if (event.rateLimit !== undefined) {
+                aggregate.graphql.rateLimit = selectAuthoritativeRateLimit(aggregate.graphql.rateLimit, event.rateLimit);
+            }
+            continue;
+        }
+        const resource = event.rateLimit?.resource ?? "unknown";
+        const group = aggregate.rest.get(resource) ?? { requestCount: 0 };
+        group.requestCount += 1;
+        if (event.rateLimit !== undefined) {
+            group.rateLimit = selectAuthoritativeRateLimit(group.rateLimit, event.rateLimit);
+        }
+        aggregate.rest.set(resource, group);
+    }
+    return aggregate;
+}
+export function mergeAggregate(target, source) {
+    target.eventCount += source.eventCount;
+    for (const [credentialSource, sequence] of source.credentialSources) {
+        const current = target.credentialSources.get(credentialSource);
+        if (current === undefined || sequence < current) {
+            target.credentialSources.set(credentialSource, sequence);
+        }
+    }
+    target.graphql.requestCount += source.graphql.requestCount;
+    target.graphql.measuredQueryCost += source.graphql.measuredQueryCost;
+    target.graphql.unmeasuredRequestCount += source.graphql.unmeasuredRequestCount;
+    target.graphql.nodeCount += source.graphql.nodeCount;
+    if (source.graphql.rateLimit !== undefined) {
+        target.graphql.rateLimit = selectAuthoritativeRateLimit(target.graphql.rateLimit, source.graphql.rateLimit);
+    }
+    for (const [resource, sourceGroup] of source.rest) {
+        const targetGroup = target.rest.get(resource) ?? { requestCount: 0 };
+        targetGroup.requestCount += sourceGroup.requestCount;
+        if (sourceGroup.rateLimit !== undefined) {
+            targetGroup.rateLimit = selectAuthoritativeRateLimit(targetGroup.rateLimit, sourceGroup.rateLimit);
+        }
+        target.rest.set(resource, targetGroup);
+    }
+}
+export function aggregateStore(active) {
+    const all = emptyAggregate();
+    mergeAggregate(all, active.compacted);
+    mergeAggregate(all, aggregateEvents(active.events));
+    return all;
+}
+function selectAuthoritativeRateLimit(current, candidate) {
+    if (current === undefined)
+        return { ...candidate };
+    if (candidate.resetAt !== current.resetAt) {
+        return candidate.resetAt > current.resetAt ? { ...candidate } : current;
+    }
+    if (candidate.remaining !== current.remaining) {
+        return candidate.remaining < current.remaining ? { ...candidate } : current;
+    }
+    if (candidate.used !== current.used) {
+        if (candidate.used === undefined)
+            return current;
+        if (current.used === undefined || candidate.used > current.used)
+            return { ...candidate };
+    }
+    return current;
+}

package/bin/github/api-telemetry.d.mts

@@ -0,0 +1,13 @@
+import type { ApiUsage } from "../types.mts";
+import type { RateLimitInfo } from "./http-utils.mts";
+export interface ApiTelemetryEvent {
+    kind: "GraphQL" | "REST";
+    method: string;
+    authSource: string;
+    rateLimit?: RateLimitInfo;
+}
+/** Isolates a top-level CLI/MCP command while allowing nested iterate ticks to aggregate. */
+export declare function withApiTelemetryScope<T>(fn: () => Promise<T>): Promise<T>;
+export declare function recordApiTelemetry(event: ApiTelemetryEvent): void;
+export declare function mergeGraphqlRateLimit(headerRateLimit: RateLimitInfo | null, data: unknown): RateLimitInfo | null;
+export declare function summarizeApiTelemetry(): ApiUsage | undefined;

package/bin/github/api-telemetry.mjs

@@ -0,0 +1,128 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { aggregateEvents, aggregateStore, emptyAggregate, mergeAggregate, } from "./api-telemetry-aggregate.mjs";
+const GRAPHQL_RATE_LIMIT_ALIAS = "_shepherdRateLimit";
+const eventStorage = new AsyncLocalStorage();
+function store() {
+    return eventStorage.getStore();
+}
+/** Isolates a top-level CLI/MCP command while allowing nested iterate ticks to aggregate. */
+export function withApiTelemetryScope(fn) {
+    const parent = store();
+    const child = {
+        events: [],
+        compacted: emptyAggregate(),
+        eventCount: 0,
+        clock: parent?.clock ?? { next: 0 },
+    };
+    return eventStorage.run(child, async () => {
+        try {
+            return await fn();
+        }
+        finally {
+            mergeAggregate(child.compacted, aggregateEvents(child.events));
+            child.events = [];
+            if (parent !== undefined) {
+                mergeAggregate(parent.compacted, aggregateEvents(parent.events));
+                parent.events = [];
+                mergeAggregate(parent.compacted, child.compacted);
+                parent.eventCount += child.eventCount;
+            }
+        }
+    });
+}
+export function recordApiTelemetry(event) {
+    const active = store();
+    if (active === undefined)
+        return;
+    active.events.push({
+        ...event,
+        rateLimit: event.rateLimit ? { ...event.rateLimit } : undefined,
+        sequence: active.clock.next++,
+    });
+    active.eventCount += 1;
+}
+export function mergeGraphqlRateLimit(headerRateLimit, data) {
+    const payload = extractGraphqlRateLimit(data);
+    if (headerRateLimit === null && payload === null)
+        return null;
+    const resetAt = payload === null ? undefined : Date.parse(payload.resetAt) / 1000;
+    const fallback = payload !== null && Number.isFinite(resetAt)
+        ? {
+            limit: payload.limit,
+            used: payload.used,
+            remaining: payload.remaining,
+            resetAt: resetAt,
+            resource: "graphql",
+        }
+        : null;
+    const base = headerRateLimit ?? fallback;
+    if (base === null)
+        return null;
+    return {
+        ...base,
+        resource: base.resource ?? "graphql",
+        ...(payload !== null && Number.isFinite(payload.cost) && { cost: payload.cost }),
+        ...(payload !== null && Number.isFinite(payload.nodeCount) && { nodeCount: payload.nodeCount }),
+    };
+}
+export function summarizeApiTelemetry() {
+    const active = store();
+    if (active === undefined)
+        return undefined;
+    const selected = aggregateStore(active);
+    if (selected.eventCount === 0)
+        return undefined;
+    const credentialSources = [...selected.credentialSources.entries()]
+        .sort((left, right) => left[1] - right[1])
+        .map(([source]) => source);
+    const graphql = summarizeGraphql(selected.graphql);
+    const rest = summarizeRest(selected.rest);
+    return {
+        credentialSources,
+        ...(graphql !== undefined && { graphql }),
+        ...(rest.length > 0 && { rest }),
+    };
+}
+function summarizeGraphql(selected) {
+    const rateLimit = selected.rateLimit;
+    if (rateLimit === undefined)
+        return undefined;
+    return {
+        ...resourceUsage(rateLimit, selected.requestCount, "graphql"),
+        measuredQueryCost: selected.measuredQueryCost,
+        unmeasuredRequestCount: selected.unmeasuredRequestCount,
+        nodeCount: selected.nodeCount,
+    };
+}
+function summarizeRest(selected) {
+    return [...selected.entries()].flatMap(([resource, group]) => {
+        return group.rateLimit ? [resourceUsage(group.rateLimit, group.requestCount, resource)] : [];
+    });
+}
+function resourceUsage(rateLimit, requestCount, fallbackResource) {
+    return {
+        resource: rateLimit.resource ?? fallbackResource,
+        requestCount,
+        limit: rateLimit.limit,
+        ...(rateLimit.used !== undefined && { used: rateLimit.used }),
+        remaining: rateLimit.remaining,
+        resetAt: rateLimit.resetAt,
+    };
+}
+function extractGraphqlRateLimit(data) {
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return null;
+    const value = data[GRAPHQL_RATE_LIMIT_ALIAS];
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!Number.isFinite(record["cost"]) ||
+        !Number.isFinite(record["limit"]) ||
+        !Number.isFinite(record["nodeCount"]) ||
+        !Number.isFinite(record["remaining"]) ||
+        typeof record["resetAt"] !== "string" ||
+        !Number.isFinite(record["used"])) {
+        return null;
+    }
+    return record;
+}

package/bin/github/check-annotations.d.mts

@@ -1,2 +1,15 @@
+import { type StateKey } from "../state/rest-cache.mts";
 import type { CheckAnnotation } from "../types.mts";
-export declare function fetchCheckRunAnnotations(checkRunId: string): Promise<CheckAnnotation[]>;
+export interface AnnotationCacheOptions {
+    stateKey: StateKey;
+    headSha?: string;
+}
+/**
+ * Fetches all inline annotations for a check run.
+ *
+ * When `cacheOpts` is provided, the result is cached by `checkRunId` — safe
+ * because callers only pass `cacheOpts` for COMPLETED check runs (a re-run
+ * mints a new check-run node id, so a COMPLETED run's annotations are
+ * immutable once fetched).
+ */
+export declare function fetchCheckRunAnnotations(checkRunId: string, cacheOpts?: AnnotationCacheOptions): Promise<CheckAnnotation[]>;

package/bin/github/check-annotations.mjs

@@ -1,11 +1,34 @@
 import { createHash } from "node:crypto";
 import { graphql } from "./client.mjs";
 import { CHECK_RUN_ANNOTATIONS_QUERY } from "./queries.mjs";
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
 const ANNOTATIONS_PER_PAGE = 100;
 const MAX_ANNOTATION_PAGES = 10;
 const ANNOTATION_TEXT_MAX_CHARS = 4_000;
 const TRUNCATED_SUFFIX = "\n[truncated]";
-export async function fetchCheckRunAnnotations(checkRunId) {
+/**
+ * Some Checks-API publishers (e.g. SonarCloud) PATCH additional annotations
+ * onto an already-COMPLETED check run without minting a new check-run node
+ * ID, so "COMPLETED" is not a reliable immutability signal on its own. Bound
+ * the cache instead of trusting it forever, so a long-running poll session
+ * eventually revalidates.
+ */
+const ANNOTATION_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
+/**
+ * Fetches all inline annotations for a check run.
+ *
+ * When `cacheOpts` is provided, the result is cached by `checkRunId` — safe
+ * because callers only pass `cacheOpts` for COMPLETED check runs (a re-run
+ * mints a new check-run node id, so a COMPLETED run's annotations are
+ * immutable once fetched).
+ */
+export async function fetchCheckRunAnnotations(checkRunId, cacheOpts) {
+    const cacheName = `annotations-${checkRunId}`;
+    if (cacheOpts) {
+        const cached = await loadDerived(cacheOpts.stateKey, cacheName);
+        if (cached && Date.now() - cached.storedAt < ANNOTATION_CACHE_MAX_AGE_MS)
+            return cached.value;
+    }
     let cursor = null;
     const nodes = [];
     for (let page = 1; page <= MAX_ANNOTATION_PAGES; page++) {
@@ -20,7 +43,11 @@ export async function fetchCheckRunAnnotations(checkRunId) {
         }
         cursor = result.pageInfo.endCursor;
     }
-    return nodes.map((node) => toCheckAnnotation(checkRunId, node));
+    const annotations = nodes.map((node) => toCheckAnnotation(checkRunId, node));
+    if (cacheOpts) {
+        await storeDerived(cacheOpts.stateKey, cacheName, annotations, cacheOpts.headSha);
+    }
+    return annotations;
 }
 async function fetchAnnotationPage(checkRunId, cursor) {
     const res = await graphql(CHECK_RUN_ANNOTATIONS_QUERY, {

package/bin/github/client.d.mts

@@ -38,7 +38,7 @@ export declare function updatePullRequestBody(pullRequestId: string, body: strin
  * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
  * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
- * READY handoff. The same response carries state so a concurrent merge or
+ * READY state. The same response carries state so a concurrent merge or
  * close can supersede the earlier GraphQL snapshot without another request.
  */
 export declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{

package/bin/github/client.mjs

@@ -93,7 +93,7 @@ export async function updatePullRequestBody(pullRequestId, body) {
  * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
  * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
- * READY handoff. The same response carries state so a concurrent merge or
+ * READY state. The same response carries state so a concurrent merge or
  * close can supersede the earlier GraphQL snapshot without another request.
  */
 export async function getMergeableState(pr, owner, repo) {

package/bin/github/errors.d.mts

@@ -15,11 +15,13 @@ export declare class GitHubRequestError extends ShepherdError {
     readonly rateLimit?: RateLimitInfo;
     readonly retryAfterSeconds?: number;
     readonly graphqlErrors?: GitHubGraphQlError[];
+    readonly authSource?: string;
     constructor(message: string, opts: {
         status: number;
         rateLimit?: RateLimitInfo;
         retryAfterSeconds?: number;
         graphqlErrors?: GitHubGraphQlError[];
+        authSource?: string;
         /**
          * Bypasses status-based classification entirely — for callers that already
          * know the failure kind better than the HTTP status can express (e.g. a

package/bin/github/errors.mjs

@@ -52,6 +52,7 @@ export class GitHubRequestError extends ShepherdError {
     rateLimit;
     retryAfterSeconds;
     graphqlErrors;
+    authSource;
     constructor(message, opts) {
         super(message, opts.exitCodeOverride ??
             classifyStatus(opts.status, opts.rateLimit, opts.retryAfterSeconds, opts.graphqlErrors));
@@ -60,5 +61,6 @@ export class GitHubRequestError extends ShepherdError {
         this.rateLimit = opts.rateLimit;
         this.retryAfterSeconds = opts.retryAfterSeconds;
         this.graphqlErrors = opts.graphqlErrors;
+        this.authSource = opts.authSource;
     }
 }

package/bin/github/gql/batch-pr-page.gql

@@ -18,6 +18,14 @@ query BatchPrPage(
   $includeChecks: Boolean!
   $checksCursor: String
 ) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       reviewThreads(last: 100, before: $threadsCursor) @include(if: $includeThreads) {

package/bin/github/gql/batch-pr.gql

@@ -1,6 +1,14 @@
 # First page only. Extra pages use batch-pr-page.gql so follow-ups do not
 # re-select every connection (GraphQL points scale with possible nodes).
 query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     viewerPermission
     viewerCanAdminister

package/bin/github/gql/check-run-annotations.gql

@@ -1,4 +1,12 @@
 query CheckRunAnnotations($id: ID!, $cursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   node(id: $id) {
     __typename
     ... on CheckRun {

package/bin/github/gql/commit-check-contexts.gql

@@ -1,4 +1,12 @@
 query CommitCheckContexts($owner: String!, $repo: String!, $oid: String!, $cursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     object(expression: $oid) {
       __typename

package/bin/github/gql/get-pr-body.gql

@@ -1,4 +1,12 @@
 query GetPrBody($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       id

package/bin/github/gql/get-pr-head-sha.gql

@@ -1,4 +1,12 @@
 query GetPrHeadSha($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       headRefOid

package/bin/github/gql/pr-number-by-branch.gql

@@ -1,4 +1,12 @@
 query PrNumberByBranch($owner: String!, $repo: String!, $branch: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequests(headRefName: $branch, states: OPEN, first: 1) {
       nodes {