pr-shepherd 0.53.0 → 0.53.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/cli/api-usage-formatter.mjs

@@ -9,7 +9,7 @@ export function formatQuotaWarning(warning) {
     if (warning === undefined)
         return null;
     const used = warning.used === undefined ? "" : ` · used ${warning.used}`;
-    return [
+    const lines = [
         "## GitHub API quota warning",
         "",
         `- Resource: \`${warning.resource}\``,
@@ -18,8 +18,22 @@ export function formatQuotaWarning(warning) {
         `- Reset: ${resetTime(warning.resetAt)}`,
         `- Recommended poll interval: ${warning.pollIntervalMinutes} minutes`,
         `- Recommended bounded CLI timeout: ${warning.pollTimeoutMinutes} minutes`,
-        "- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR operations prefer REST `gh` (`gh pr view`, `gh pr review`, `gh api`); do not substitute `gh pr checks`/`gh pr watch`",
-    ].join("\n");
+        recommendation(warning),
+    ];
+    for (const budget of warning.budgets ?? []) {
+        const budgetUsed = budget.used === undefined ? "" : ` · used ${budget.used}`;
+        lines.push(`- Budget \`${budget.resource}\`: ${budget.remaining}/${budget.limit} remaining${budgetUsed} · crossed ${budget.thresholdPercent}% · resets ${resetTime(budget.resetAt)}`);
+    }
+    return lines.join("\n");
+}
+function recommendation(warning) {
+    if (warning.resource === "combined") {
+        return "- Recommendation: keep polling pr-shepherd at the cadence above; both GraphQL and REST core are below their warning thresholds, so do not shift work between them. Do not substitute `gh pr checks` or `gh pr watch`";
+    }
+    if (warning.resource === "core") {
+        return "- Recommendation: keep polling pr-shepherd at the cadence above; do not add incidental REST `gh` calls (`gh pr view`, `gh pr review`, `gh api`) while REST core is low. Do not substitute `gh pr checks` or `gh pr watch`";
+    }
+    return "- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR operations prefer REST `gh` (`gh pr view`, `gh pr review`, `gh api`); do not substitute `gh pr checks` or `gh pr watch`";
 }
 export function formatApiUsage(usage) {
     if (usage === undefined)

package/bin/commands/iterate/api-usage.mjs

@@ -1,6 +1,6 @@
 import { loadConfig } from "../../config/load.mjs";
-import { summarizeApiTelemetry, withGraphqlCredentialFingerprint, } from "../../github/api-telemetry.mjs";
-import { evaluateWorktreeGraphqlQuotaWarning } from "../../state/graphql-quota-warnings.mjs";
+import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
+import { selectQuotaWarning } from "../quota-selection.mjs";
 import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 function shouldWarn(result) {
     return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
@@ -10,14 +10,15 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
     if (apiUsage === undefined)
         return result;
     let quotaWarning = preservePersistedWarning ? result.quotaWarning : undefined;
-    if (quotaWarning === undefined && apiUsage.graphql !== undefined && shouldWarn(result)) {
+    const core = apiUsage.rest?.find((item) => item.resource === "core");
+    if (quotaWarning === undefined && shouldWarn(result) && (apiUsage.graphql || core)) {
         const [owner, repo] = result.repo.split("/");
         if (owner && repo) {
             const bands = loadConfig().watch.graphqlQuotaWarnings.map((band) => ({
                 ...band,
                 pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
             }));
-            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, withGraphqlCredentialFingerprint(apiUsage.graphql), persistWarning);
+            quotaWarning = await selectQuotaWarning({ owner, repo }, bands, apiUsage, persistWarning);
         }
     }
     const { quotaWarning: _deferredWarning, ...baseResult } = result;

package/bin/commands/poll-quota.d.mts

@@ -1,10 +1,22 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
-import type { GraphqlApiUsage, PollSummaryResult } from "../types.mts";
-/** Sleep at least `--interval`, and at least the active crossed quota band. */
-export declare function graphqlQuotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: Pick<GraphqlApiUsage, "remaining" | "limit"> | undefined, fallbackMs: number, maxMs: number): number;
+import type { ApiResourceUsage, GraphqlApiUsage, PollSummaryResult } from "../types.mts";
+/** Slow the poll for whichever of GraphQL or REST core is in a tighter band. */
+export declare function quotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: {
+    graphql?: Pick<GraphqlApiUsage, "remaining" | "limit">;
+    rest?: Pick<ApiResourceUsage, "resource" | "remaining" | "limit">[];
+} | undefined, fallbackMs: number, maxMs: number): number;
+export interface RateLimitRetry {
+    ms: number;
+    resource: string;
+    remaining?: number;
+    limit?: number;
+    resetAt?: number;
+}
 /**
- * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
- * limit. `null` means the error is not a retryable rate limit.
+ * Retry delay for `--until-terminal` when GitHub exhausts a primary quota or
+ * returns a secondary limit. `null` means the error is not a retryable rate limit.
  */
-export declare function pollGraphQlRetryAfterMs(err: unknown): number | null;
+export declare function pollRateLimitRetryAfterMs(err: unknown): RateLimitRetry | null;
+/** Stderr line naming the exhausted budget and when the sleep ends. */
+export declare function formatRateLimitRetryLine(tickLabel: string, elapsedSeconds: number, retry: RateLimitRetry): string;
 export declare function aggregateQuotaWarning(result: PollSummaryResult, bands: GraphqlQuotaWarningBand[], intervalSeconds: number): Promise<PollSummaryResult["quotaWarning"]>;

package/bin/commands/poll-quota.mjs

@@ -1,10 +1,10 @@
-import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
-import { summarizeApiTelemetry, withGraphqlCredentialFingerprint, } from "../github/api-telemetry.mjs";
+import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { GitHubRequestError } from "../github/errors.mjs";
 import { isRateLimitMessage } from "../comments/rate-limit.mjs";
+import { selectQuotaWarning } from "./quota-selection.mjs";
 const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
 /** Sleep at least `--interval`, and at least the active crossed quota band. */
-export function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
+function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
     if (usage === undefined || usage.limit <= 0 || bands.length === 0) {
         return Math.min(fallbackMs, maxMs);
     }
@@ -15,34 +15,72 @@ export function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
     const bandMs = active.pollIntervalMinutes * 60_000;
     return Math.min(Math.max(fallbackMs, bandMs), maxMs);
 }
+/** Slow the poll for whichever of GraphQL or REST core is in a tighter band. */
+export function quotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
+    const core = usage?.rest?.find((item) => item.resource === "core");
+    return Math.max(graphqlQuotaPollIntervalMs(bands, usage?.graphql, fallbackMs, maxMs), graphqlQuotaPollIntervalMs(bands, core, fallbackMs, maxMs));
+}
 /**
- * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
- * limit. `null` means the error is not a retryable rate limit.
+ * Retry delay for `--until-terminal` when GitHub exhausts a primary quota or
+ * returns a secondary limit. `null` means the error is not a retryable rate limit.
  */
-export function pollGraphQlRetryAfterMs(err) {
+export function pollRateLimitRetryAfterMs(err) {
     if (!(err instanceof GitHubRequestError))
         return null;
-    const retryable = err.status === 429 ||
-        err.retryAfterSeconds !== undefined ||
-        isRateLimitMessage(err.message) ||
-        (err.graphqlErrors?.some((error) => isRateLimitMessage(error.message)) ?? false) ||
-        (err.rateLimit !== undefined && err.rateLimit.remaining <= 0);
+    const rateLimitMessage = isRateLimitMessage(err.message) ||
+        (err.graphqlErrors?.some((error) => isRateLimitMessage(error.message)) ?? false);
+    const exhausted = err.rateLimit !== undefined && err.rateLimit.remaining <= 0;
+    const retryable = err.status === 429 || err.retryAfterSeconds !== undefined || rateLimitMessage || exhausted;
     if (!retryable)
         return null;
-    if (err.retryAfterSeconds !== undefined)
-        return Math.max(err.retryAfterSeconds, 0) * 1000;
-    if (err.rateLimit !== undefined && err.rateLimit.remaining <= 0) {
-        return Math.max(err.rateLimit.resetAt * 1000 - Date.now(), 0);
+    const resource = retryResource(err);
+    const rateLimit = err.rateLimit;
+    const details = {
+        resource,
+        ...(rateLimit?.remaining !== undefined && { remaining: rateLimit.remaining }),
+        ...(rateLimit?.limit !== undefined && { limit: rateLimit.limit }),
+        ...(rateLimit?.resetAt !== undefined && { resetAt: rateLimit.resetAt }),
+    };
+    if (err.retryAfterSeconds !== undefined) {
+        return { ...details, ms: Math.max(err.retryAfterSeconds, 0) * 1000 };
     }
-    return GRAPHQL_RETRY_AFTER_DEFAULT_MS;
+    if (exhausted && rateLimit !== undefined) {
+        return { ...details, ms: Math.max(rateLimit.resetAt * 1000 - Date.now(), 0) };
+    }
+    return { ...details, ms: GRAPHQL_RETRY_AFTER_DEFAULT_MS };
+}
+function retryResource(err) {
+    if (err.rateLimit?.resource)
+        return err.rateLimit.resource;
+    const secondary = err.status === 429 ||
+        err.retryAfterSeconds !== undefined ||
+        /secondary/i.test(err.message) ||
+        (err.graphqlErrors?.some((error) => /secondary/i.test(error.message)) ?? false);
+    return secondary ? "secondary" : "graphql";
+}
+/** Stderr line naming the exhausted budget and when the sleep ends. */
+export function formatRateLimitRetryLine(tickLabel, elapsedSeconds, retry) {
+    const resetAt = retry.resetAt ?? Math.ceil((Date.now() + retry.ms) / 1000);
+    const clock = `${new Date(resetAt * 1000).toISOString().slice(11, 19)}Z`;
+    const label = retry.resource === "graphql"
+        ? "GitHub GraphQL rate limit"
+        : retry.resource === "secondary"
+            ? "GitHub secondary rate limit"
+            : `GitHub REST ${retry.resource} rate limit`;
+    const counts = retry.remaining !== undefined && retry.limit !== undefined
+        ? ` (${retry.remaining}/${retry.limit})`
+        : "";
+    return `[${tickLabel} / +${elapsedSeconds}s] ${label}${counts} — retrying at ${clock} (in ${Math.round(retry.ms / 1000)}s)\n`;
 }
 export async function aggregateQuotaWarning(result, bands, intervalSeconds) {
-    const usage = summarizeApiTelemetry()?.graphql;
+    const usage = summarizeApiTelemetry();
     const [owner, repo] = result.repo.split("/");
     if (!usage || !owner || !repo)
         return undefined;
-    return evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands.map((band) => ({
+    if (!usage.graphql && !usage.rest?.some((item) => item.resource === "core"))
+        return undefined;
+    return selectQuotaWarning({ owner, repo }, bands.map((band) => ({
         ...band,
         pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
-    })), withGraphqlCredentialFingerprint(usage), true);
+    })), usage, true);
 }

package/bin/commands/poll-summary.mjs

@@ -5,7 +5,7 @@ import { getRepoInfo } from "../github/client.mjs";
 import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { fetchPollSummary } from "../github/poll-summary.mjs";
 import { sleep } from "../util/sleep.mjs";
-import { aggregateQuotaWarning, graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs, } from "./poll-quota.mjs";
+import { aggregateQuotaWarning, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, quotaPollIntervalMs, } from "./poll-quota.mjs";
 import { planPollSummary, withPollSummaryInstructions } from "./poll-summary-instructions.mjs";
 import { summaryStatusSignature } from "./poll-summary-signature.mjs";
 import { applyStackStallGuard } from "./stack-stall.mjs";
@@ -83,12 +83,12 @@ async function runAggregatePollCore(opts) {
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
                 }, opts.merge);
             }
-            const retryMs = opts.untilTerminal ? pollGraphQlRetryAfterMs(error) : null;
-            if (retryMs === null || rateLimitRetries >= 1)
+            const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(error) : null;
+            if (retry === null || rateLimitRetries >= 1)
                 throw error;
             rateLimitRetries += 1;
-            process.stderr.write(`[aggregate poll tick ${tick} / +${Math.round((Date.now() - start) / 1000)}s] GraphQL rate limit — retrying in ${Math.round(retryMs / 1000)}s\n`);
-            await sleep(retryMs);
+            process.stderr.write(formatRateLimitRetryLine(`aggregate poll tick ${tick}`, Math.round((Date.now() - start) / 1000), retry));
+            await sleep(retry.ms);
             continue;
         }
         const allTerminal = last.selection.kind === "stack"
@@ -142,7 +142,7 @@ async function runAggregatePollCore(opts) {
         const elapsedMs = Date.now() - start;
         const sleepMs = debounceUntil
             ? Math.min(intervalMs, Math.max(debounceUntil - Date.now(), 0))
-            : graphqlQuotaPollIntervalMs(quotaBands, summarizeApiTelemetry()?.graphql, intervalMs, MAX_TIMER_MS);
+            : quotaPollIntervalMs(quotaBands, summarizeApiTelemetry(), intervalMs, MAX_TIMER_MS);
         if (!opts.untilTerminal && debounceUntil === null) {
             const remainingMs = timeoutMs - elapsedMs;
             if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {

package/bin/commands/poll.mjs

@@ -2,7 +2,7 @@ import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
 import { loadConfig } from "../config/load.mjs";
-import { graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs } from "./poll-quota.mjs";
+import { formatRateLimitRetryLine, pollRateLimitRetryAfterMs, quotaPollIntervalMs, } from "./poll-quota.mjs";
 import { writeDebounceProgress, writeWaitProgress } from "./poll-progress.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 const MAX_TIMER_MS = 2 ** 31 - 1;
@@ -54,12 +54,12 @@ async function runPollCore(opts) {
                 return result;
             }
             catch (err) {
-                const retryMs = untilTerminal ? pollGraphQlRetryAfterMs(err) : null;
-                if (retryMs === null || rateLimitRetries >= 1)
+                const retry = untilTerminal ? pollRateLimitRetryAfterMs(err) : null;
+                if (retry === null || rateLimitRetries >= 1)
                     throw err;
                 rateLimitRetries += 1;
-                process.stderr.write(`[poll tick ${tick} / +${Math.round((Date.now() - start) / 1000)}s] GraphQL rate limit — retrying in ${Math.round(retryMs / 1000)}s\n`);
-                await sleep(retryMs);
+                process.stderr.write(formatRateLimitRetryLine(`poll tick ${tick}`, Math.round((Date.now() - start) / 1000), retry));
+                await sleep(retry.ms);
                 const result = await iterateTick(fingerprintCache);
                 rateLimitRetries = 0;
                 return result;
@@ -101,7 +101,7 @@ async function runPollCore(opts) {
             if (pendingQuotaWarning === undefined)
                 debounceUntil = null;
             const elapsedMs = Date.now() - start;
-            const sleepMs = graphqlQuotaPollIntervalMs(quotaBands, lastResult.apiUsage?.graphql, intervalMs, MAX_TIMER_MS);
+            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS);
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
                 if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
@@ -126,7 +126,7 @@ async function runPollCore(opts) {
             !pastDebounce) {
             debounceUntil = null;
             const elapsedMs = Date.now() - start;
-            const sleepMs = graphqlQuotaPollIntervalMs(quotaBands, lastResult.apiUsage?.graphql, intervalMs, MAX_TIMER_MS);
+            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS);
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
                 if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {

package/bin/commands/quota-selection.d.mts

@@ -0,0 +1,7 @@
+import type { GraphqlQuotaWarningBand } from "../config/load.mts";
+import type { ApiUsage, GraphqlQuotaWarning } from "../types.mts";
+/** Claim GraphQL and REST core warnings separately, then present one result. */
+export declare function selectQuotaWarning(key: {
+    owner: string;
+    repo: string;
+}, bands: GraphqlQuotaWarningBand[], usage: ApiUsage, persist: boolean): Promise<GraphqlQuotaWarning | undefined>;

package/bin/commands/quota-selection.mjs

@@ -0,0 +1,20 @@
+import { withGraphqlCredentialFingerprint } from "../github/api-telemetry.mjs";
+import { composeQuotaWarning } from "../quota-budgets.mjs";
+import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
+/** Claim GraphQL and REST core warnings separately, then present one result. */
+export async function selectQuotaWarning(key, bands, usage, persist) {
+    const core = usage.rest?.find((item) => item.resource === "core");
+    const graphqlWarning = usage.graphql
+        ? await evaluateWorktreeGraphqlQuotaWarning(key, bands, withGraphqlCredentialFingerprint(usage.graphql), persist)
+        : undefined;
+    const coreWarning = core
+        ? await evaluateWorktreeGraphqlQuotaWarning(key, bands, withGraphqlCredentialFingerprint(core), persist)
+        : undefined;
+    return composeQuotaWarning({
+        graphqlWarning,
+        coreWarning,
+        graphql: usage.graphql,
+        core,
+        bands,
+    });
+}

package/bin/quota-budgets.d.mts

@@ -0,0 +1,16 @@
+import type { GraphqlQuotaWarningBand } from "./config/load.mts";
+import type { ApiResourceUsage, GraphqlQuotaWarning } from "./types.mts";
+type Usage = Pick<ApiResourceUsage, "resource" | "remaining" | "limit" | "used" | "resetAt">;
+/**
+ * One warning for the budgets that are low on this tick. A GraphQL warning
+ * recommends REST only when REST core is still above its bands. When both are
+ * low, the result uses the later reset and does not recommend a switch.
+ */
+export declare function composeQuotaWarning(input: {
+    graphqlWarning?: GraphqlQuotaWarning;
+    coreWarning?: GraphqlQuotaWarning;
+    graphql?: Usage;
+    core?: Usage;
+    bands: GraphqlQuotaWarningBand[];
+}): GraphqlQuotaWarning | undefined;
+export {};

package/bin/quota-budgets.mjs

@@ -0,0 +1,65 @@
+/** True when this sample is at or below a configured remaining-percent band. */
+function budgetBelowBand(usage, bands) {
+    if (usage === undefined || usage.limit <= 0 || bands.length === 0)
+        return false;
+    return bands.some((band) => usage.remaining * 100 <= usage.limit * band.remainingPercent);
+}
+/**
+ * One warning for the budgets that are low on this tick. A GraphQL warning
+ * recommends REST only when REST core is still above its bands. When both are
+ * low, the result uses the later reset and does not recommend a switch.
+ */
+export function composeQuotaWarning(input) {
+    const graphqlBelow = budgetBelowBand(input.graphql, input.bands);
+    const coreBelow = budgetBelowBand(input.core, input.bands);
+    const graphql = input.graphqlWarning;
+    const core = input.coreWarning;
+    if (graphql && core)
+        return combineWarnings(graphql, core);
+    if (graphql && coreBelow && input.core)
+        return combineWarnings(graphql, describeBudget(input.core, input.bands));
+    if (core && graphqlBelow && input.graphql) {
+        return combineWarnings(core, describeBudget(input.graphql, input.bands));
+    }
+    return graphql ?? core;
+}
+function describeBudget(usage, bands) {
+    const active = bands
+        .filter((band) => usage.remaining * 100 <= usage.limit * band.remainingPercent)
+        .reduce((lowest, band) => (band.remainingPercent < lowest.remainingPercent ? band : lowest));
+    return {
+        resource: usage.resource === "core" ? "core" : "graphql",
+        thresholdPercent: active.remainingPercent,
+        remaining: usage.remaining,
+        limit: usage.limit,
+        ...(usage.used !== undefined && { used: usage.used }),
+        resetAt: usage.resetAt,
+        pollIntervalMinutes: active.pollIntervalMinutes,
+        pollTimeoutMinutes: active.pollIntervalMinutes * 2,
+    };
+}
+function combineWarnings(left, right) {
+    const later = left.resetAt >= right.resetAt ? left : right;
+    const interval = Math.max(left.pollIntervalMinutes, right.pollIntervalMinutes);
+    return {
+        resource: "combined",
+        thresholdPercent: Math.min(left.thresholdPercent, right.thresholdPercent),
+        remaining: later.remaining,
+        limit: later.limit,
+        ...(later.used !== undefined && { used: later.used }),
+        resetAt: later.resetAt,
+        pollIntervalMinutes: interval,
+        pollTimeoutMinutes: interval * 2,
+        budgets: [toBudget(left), toBudget(right)].sort((a, b) => a.resource.localeCompare(b.resource)),
+    };
+}
+function toBudget(warning) {
+    return {
+        resource: warning.resource === "core" ? "core" : "graphql",
+        thresholdPercent: warning.thresholdPercent,
+        remaining: warning.remaining,
+        limit: warning.limit,
+        ...(warning.used !== undefined && { used: warning.used }),
+        resetAt: warning.resetAt,
+    };
+}

package/bin/quota-warning.mjs

@@ -2,5 +2,15 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const interval = `${warning.pollIntervalMinutes}m`;
     const timeout = `${warning.pollTimeoutMinutes}m`;
     const resetTime = new Date(warning.resetAt * 1000).toISOString();
-    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, raise any shorter interval and timeout flags to at least \`--interval ${interval} --timeout ${timeout}\`, keep any longer cadence, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
+    const opening = warning.resource === "combined"
+        ? "GitHub's GraphQL and REST core quotas are both low. Keep using pr-shepherd at the cadence below. Do not shift incidental calls between GraphQL and REST."
+        : warning.resource === "core"
+            ? `GitHub's REST core quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below. Do not add incidental REST \`gh\` calls (\`gh pr view\`, \`gh pr review\`, \`gh api\`) while REST core is below its warning threshold.`
+            : `GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool.`;
+    const resetLabel = warning.resource === "combined"
+        ? "both quotas have reset"
+        : warning.resource === "core"
+            ? "the REST core quota resets"
+            : "the GraphQL quota resets";
+    return `${prefix} ${opening} Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after ${resetLabel} at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, raise any shorter interval and timeout flags to at least \`--interval ${interval} --timeout ${timeout}\`, keep any longer cadence, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
 }

package/bin/state/graphql-quota-policy.mjs

@@ -32,7 +32,7 @@ export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt
         return { state };
     return {
         warning: {
-            resource: "graphql",
+            resource: sample.resource === "core" ? "core" : "graphql",
             thresholdPercent: active.remainingPercent,
             remaining: effective.remaining,
             limit: effective.limit,

package/bin/state/graphql-quota-warnings.d.mts

@@ -1,6 +1,6 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
-import type { GraphqlQuotaWarning, GraphqlApiUsage } from "../types.mts";
+import type { ApiResourceUsage, GraphqlQuotaWarning } from "../types.mts";
 export declare function evaluateWorktreeGraphqlQuotaWarning(key: {
     owner: string;
     repo: string;
-}, bands: GraphqlQuotaWarningBand[], sample: GraphqlApiUsage, persist: boolean, now?: number): Promise<GraphqlQuotaWarning | undefined>;
+}, bands: GraphqlQuotaWarningBand[], sample: ApiResourceUsage, persist: boolean, now?: number): Promise<GraphqlQuotaWarning | undefined>;

package/bin/state/graphql-quota-warnings.mjs

@@ -10,9 +10,10 @@ const sessionStates = new Map();
 export async function evaluateWorktreeGraphqlQuotaWarning(key, bands, sample, persist, now = Date.now() / 1000) {
     if (bands.length === 0)
         return undefined;
-    const path = await warningStatePath(key);
+    const quotaResource = sample.resource === "core" ? "core" : "graphql";
+    const path = await warningStatePath(key, quotaResource);
     if (path === undefined) {
-        const sessionKey = `${key.owner}/${key.repo}`;
+        const sessionKey = `${key.owner}/${key.repo}/${quotaResource}`;
         if (!persist) {
             return evaluateGraphqlQuotaWarning(bands, sample, sessionStates.get(sessionKey) ?? null, now)
                 .warning;
@@ -50,7 +51,7 @@ async function serializeStateUpdate(key, update) {
     });
     return result;
 }
-async function warningStatePath(key) {
+async function warningStatePath(key, resource) {
     let worktreeKey;
     try {
         worktreeKey = await getWorktreeKey();
@@ -58,7 +59,7 @@ async function warningStatePath(key) {
     catch {
         return undefined;
     }
-    return join(resolveRepoStateDir(key), "worktrees", `${worktreeKey}-graphql-quota-warnings.json`);
+    return join(resolveRepoStateDir(key), "worktrees", `${worktreeKey}-${resource}-quota-warnings.json`);
 }
 async function readState(path) {
     try {

package/bin/types/api-usage.d.mts

@@ -5,6 +5,8 @@ export interface ApiResourceUsage {
     used?: number;
     remaining: number;
     resetAt: number;
+    /** Truncated SHA-256 of the credential. Quota state only; summarized usage omits it. */
+    credentialFingerprint?: string;
 }
 export interface GraphqlApiUsage extends ApiResourceUsage {
     /** Exact sum reported by rateLimit.cost for GraphQL queries in this command. */
@@ -13,8 +15,15 @@ export interface GraphqlApiUsage extends ApiResourceUsage {
     unmeasuredRequestCount: number;
     /** Exact sum reported by rateLimit.nodeCount for measured GraphQL queries. */
     nodeCount: number;
-    /** Truncated SHA-256 of the credential. Quota state only; summarized usage omits it. */
-    credentialFingerprint?: string;
+}
+/** One budget inside a combined GraphQL and REST core warning. */
+export interface QuotaWarningBudget {
+    resource: "graphql" | "core";
+    thresholdPercent: number;
+    remaining: number;
+    limit: number;
+    used?: number;
+    resetAt: number;
 }
 export interface ApiUsage {
     credentialSources: string[];
@@ -22,7 +31,7 @@ export interface ApiUsage {
     rest?: ApiResourceUsage[];
 }
 export interface GraphqlQuotaWarning {
-    resource: "graphql";
+    resource: "graphql" | "core" | "combined";
     thresholdPercent: number;
     remaining: number;
     limit: number;
@@ -30,4 +39,6 @@ export interface GraphqlQuotaWarning {
     resetAt: number;
     pollIntervalMinutes: number;
     pollTimeoutMinutes: number;
+    /** Both budgets when GraphQL and REST core are low together. */
+    budgets?: QuotaWarningBudget[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.53.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.53.1", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.53.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.53.1", "pr-shepherd-mcp"]
   }
 }