pr-shepherd 0.52.1 → 0.53.1

package/bin/commands/poll.mjs

@@ -1,9 +1,8 @@
 import { runIterate } from "./iterate/index.mjs";
-import { heldByLowerLayer } from "./iterate/parent-first.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;
@@ -55,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;
@@ -98,12 +97,11 @@ async function runPollCore(opts) {
             }
             break;
         }
-        // A held draft waits on another layer's session, so hand it straight back.
-        if (lastResult.action === "wait" && !pastDebounce && !heldByLowerLayer(lastResult)) {
+        if (lastResult.action === "wait" && !pastDebounce) {
             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) {
@@ -128,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/commands/stack-drain.d.mts

@@ -8,17 +8,17 @@ export interface StackPlan {
     instructions: string[];
 }
 /**
- * Merge the ready bottom layer by PR number. `gh stack merge <n>` tries a stack
- * number first, but stack numbers come from the repository's issue and pull
- * request sequence, so a PR number never names a stack.
+ * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
+ * stack number first, but stack numbers come from the repository's issue and
+ * pull request sequence, so a PR number never names a stack.
  */
-export declare function planBottomDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
+export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
 /**
  * A merge-requested, fully ready stack whose bottom open layer still targets
  * the merged layer below it until GitHub retargets it onto the stack base.
  */
 export declare function retargetWaitPlan(first: PollSummaryItem): StackPlan;
-/** Every remaining layer only waits: on CI or merge state, or on a lower layer that does. */
+/** Every remaining layer only waits on CI or merge state. */
 export declare function idleWaitPlan(idle: PollSummaryItem[]): StackPlan;
 export declare function describeIdleLayers(idle: PollSummaryItem[]): string;
 export declare function appendAutonomousInstructions(instructions: string[], candidates: PollSummaryItem[]): void;

package/bin/commands/stack-drain.mjs

@@ -1,51 +1,63 @@
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
 import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
 /**
- * The lowest open layer when it can merge by itself: every layer below it
- * merged, GitHub retargeted it onto the stack base, it holds a current READY
- * receipt, and no layer is already in the merge queue.
+ * Highest open layer such that it and every open layer below it are ready to
+ * merge together. `gh stack merge <PR>` lands that PR and every unmerged layer
+ * below it. A merge queue accepts the same prefix and evaluates each layer
+ * from the bottom; a failure ejects that layer and those above it.
  */
-function drainableBottom(result) {
+function readyPrefixTop(result) {
     const layers = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
-    const bottom = layers.find((item) => item.state !== "MERGED");
-    if (!bottom || !isStackLayer(bottom) || bottom.state !== "OPEN")
+    if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
         return undefined;
-    if (bottom.action === "escalate" || !isStackLayerReady(bottom))
+    const open = layers.filter((item) => item.state === "OPEN");
+    const bottom = open[0];
+    if (!bottom || !isStackLayer(bottom) || bottom.state !== "OPEN")
         return undefined;
     if (bottom.baseRefName !== bottom.stack.baseRefName)
         return undefined;
-    if (result.stackAncestry?.some((gap) => gap.childPr === bottom.pr))
-        return undefined;
-    if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
-        return undefined;
-    return bottom;
+    const stale = new Set((result.stackAncestry ?? []).map((gap) => gap.childPr));
+    let top;
+    for (const item of open) {
+        if (!isStackLayer(item))
+            break;
+        if (item.action === "escalate" || !isStackLayerReady(item) || stale.has(item.pr))
+            break;
+        if (layers.some((layer) => layer.state === "CLOSED" && stackPosition(layer) < stackPosition(item)))
+            break;
+        top = item;
+    }
+    return top;
 }
 /**
- * Merge the ready bottom layer by PR number. `gh stack merge <n>` tries a stack
- * number first, but stack numbers come from the repository's issue and pull
- * request sequence, so a PR number never names a stack.
+ * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
+ * stack number first, but stack numbers come from the repository's issue and
+ * pull request sequence, so a PR number never names a stack.
  */
-export function planBottomDrain(result, mergeRequested) {
+export function planPrefixDrain(result, mergeRequested) {
     if (!mergeRequested)
         return undefined;
-    const bottom = drainableBottom(result);
-    if (!bottom)
+    const top = readyPrefixTop(result);
+    if (!top)
         return undefined;
     const gaps = result.stackAncestry ?? [];
     const staleChildren = new Set(gaps.map((gap) => gap.childPr));
-    const open = result.prs.filter((item) => item.state === "OPEN");
-    const uppers = splitStackWork(open.filter((item) => item.pr !== bottom.pr &&
+    const open = result.prs
+        .filter((item) => item.state === "OPEN")
+        .sort((left, right) => stackPosition(left) - stackPosition(right));
+    const above = splitStackWork(open.filter((item) => stackPosition(item) > stackPosition(top) &&
         item.action !== "escalate" &&
         (!isStackLayerReady(item) || staleChildren.has(item.pr))), staleChildren);
+    const span = open[0]?.pr === top.pr ? "that layer alone" : `PR #${top.pr} and every unmerged layer below it`;
     const instructions = [
-        `1. PR #${bottom.pr} is the bottom open layer of stack #${bottom.stack.number} in \`${result.repo}\` and is ready. Run \`GH_REPO=${result.repo} gh stack merge ${bottom.pr} --yes --squash\` to merge that layer alone, or to enqueue it when the base uses a merge queue. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
+        `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes --squash\` to merge ${span}. When the base uses a merge queue, the same command queues that prefix together and GitHub evaluates each layer from the bottom; a failure ejects that layer and the layers above it. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
     ];
-    appendAutonomousInstructions(instructions, uppers.sessions);
-    appendMarkReadyInstructions(instructions, uppers.markReady);
+    appendAutonomousInstructions(instructions, above.sessions);
+    appendMarkReadyInstructions(instructions, above.markReady);
     const handoffs = findHumanHandoffs(result);
     if (handoffs)
         appendHumanHandoffInstructions(instructions, handoffs, false);
-    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`--stack --merge\` selector; GitHub retargets the next layer onto \`${bottom.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
+    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`--stack --merge\` selector; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
     return {
         action: "merge",
         stackMergeable: gaps.length === 0 && open.every(isStackLayerReady),
@@ -66,7 +78,7 @@ export function retargetWaitPlan(first) {
         ],
     };
 }
-/** Every remaining layer only waits: on CI or merge state, or on a lower layer that does. */
+/** Every remaining layer only waits on CI or merge state. */
 export function idleWaitPlan(idle) {
     return {
         action: "wait",
@@ -79,9 +91,7 @@ export function idleWaitPlan(idle) {
     };
 }
 export function describeIdleLayers(idle) {
-    return idle
-        .map((item) => `PR #${item.pr} (${item.blockedByPr ? `stack-blocked by PR #${item.blockedByPr}` : item.reasons.join(", ")})`)
-        .join("; ");
+    return idle.map((item) => `PR #${item.pr} (${item.reasons.join(", ")})`).join("; ");
 }
 export function appendAutonomousInstructions(instructions, candidates) {
     if (candidates.length === 0)
@@ -89,10 +99,9 @@ export function appendAutonomousInstructions(instructions, candidates) {
     instructions.push(`${instructions.length + 1}. Start or delegate the relevant one-PR sessions below; review and CI work on separate layers can proceed concurrently.`);
     for (const item of candidates) {
         instructions.push(item.pollCommand
-            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.blockedByPr ? ` (stack-blocked by PR #${item.blockedByPr})` : ""}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
+            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
             : `${instructions.length + 1}. PR #${item.pr} needs a one-PR Shepherd session, but no command was available.`);
     }
-    instructions.push(`${instructions.length + 1}. Keep upper draft PRs in draft until every lower layer has completed Shepherd READY.`);
 }
 export function findHumanHandoffs(result) {
     const lastOpen = result.prs.filter((item) => item.state === "OPEN").at(-1);

package/bin/commands/stack-layer-readiness.d.mts

@@ -1,7 +1,6 @@
 import type { PollSummaryItem, StackLayerBlockReason } from "../types.mts";
 /**
- * Why a native stack layer does not yet let the layers above it advance, or undefined
- * when it does. The stack selector and an upper draft's parent-first mark-ready check
- * share this predicate so both always name the same blocking layer.
+ * Why a native stack layer is not ready to merge, or undefined when it is.
+ * A draft is marked ready by its own session; this predicate does not gate that.
  */
 export declare function stackLayerBlockReason(item: PollSummaryItem): StackLayerBlockReason | undefined;

package/bin/commands/stack-layer-readiness.mjs

@@ -1,7 +1,6 @@
 /**
- * Why a native stack layer does not yet let the layers above it advance, or undefined
- * when it does. The stack selector and an upper draft's parent-first mark-ready check
- * share this predicate so both always name the same blocking layer.
+ * Why a native stack layer is not ready to merge, or undefined when it is.
+ * A draft is marked ready by its own session; this predicate does not gate that.
  */
 export function stackLayerBlockReason(item) {
     if (item.state !== "OPEN")
@@ -13,7 +12,7 @@ export function stackLayerBlockReason(item) {
     // A receipt only establishes readiness after a merge-queue removal once
     // the one-PR session has observed and acknowledged that exact removal.
     // The aggregate projection preserves an unacknowledged removal here, so
-    // do not let its otherwise-current receipt promote a child draft.
+    // the layer is not ready to merge.
     if (item.queueRemoval)
         return "queue-removal";
     if ((item.checks?.failing ?? 0) > 0)
@@ -30,6 +29,6 @@ export function stackLayerBlockReason(item) {
             return "merge-state";
     }
     // A layer that looks ready but has not completed its own one-PR receipt
-    // is not sufficient evidence for the layers above it.
+    // is not ready to merge.
     return item.readyReceipt === true ? undefined : "no-ready-receipt";
 }

package/bin/commands/stack-stall.mjs

@@ -63,7 +63,6 @@ function stackStallFingerprint(result) {
             isDraft: item.isDraft,
             readyReceipt: item.readyReceipt,
             reasons: item.reasons,
-            blockedByPr: item.blockedByPr,
         })),
     });
 }

package/bin/commands/stack-work.d.mts

@@ -19,14 +19,14 @@ export interface StackWork {
 }
 /**
  * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A clean draft
- * that no lower layer blocks becomes an agent ready-for-review step instead. A stale-ancestry
- * child keeps its session, which returns the ancestry repair.
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
+ * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
 /**
  * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context and current lower layers.
+ * first because only the one-PR session reads the full review context.
  */
 export declare function appendMarkReadyInstructions(instructions: string[], layers: ProbedLayer[]): void;
 export {};

package/bin/commands/stack-work.mjs

@@ -5,9 +5,9 @@
 export const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
 /**
  * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A clean draft
- * that no lower layer blocks becomes an agent ready-for-review step instead. A stale-ancestry
- * child keeps its session, which returns the ancestry repair.
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
+ * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export function splitStackWork(candidates, staleChildren) {
     const work = { sessions: [], markReady: [], idle: [] };
@@ -15,8 +15,7 @@ export function splitStackWork(candidates, staleChildren) {
         if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
             work.sessions.push(item);
         }
-        else if (item.blockedByPr === undefined &&
-            item.reasons.includes("draft-auto-mark-ready-disabled")) {
+        else if (item.reasons.includes("draft-auto-mark-ready-disabled")) {
             work.markReady.push(item);
         }
         else {
@@ -27,7 +26,7 @@ export function splitStackWork(candidates, staleChildren) {
 }
 /**
  * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context and current lower layers.
+ * first because only the one-PR session reads the full review context.
  */
 export function appendMarkReadyInstructions(instructions, layers) {
     for (const item of layers) {

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

@@ -9,6 +9,7 @@ export interface TelemetryAggregate {
         unmeasuredRequestCount: number;
         nodeCount: number;
         rateLimit?: RateLimitInfo;
+        credentialFingerprint?: string;
     };
     rest: Map<string, {
         requestCount: number;

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

@@ -21,7 +21,7 @@ export function aggregateEvents(events) {
                 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);
+                adoptGraphqlRateLimit(aggregate.graphql, event.rateLimit, event.credentialFingerprint);
             }
             continue;
         }
@@ -48,7 +48,7 @@ export function mergeAggregate(target, source) {
     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);
+        adoptGraphqlRateLimit(target.graphql, source.graphql.rateLimit, source.graphql.credentialFingerprint);
     }
     for (const [resource, sourceGroup] of source.rest) {
         const targetGroup = target.rest.get(resource) ?? { requestCount: 0 };
@@ -65,6 +65,12 @@ export function aggregateStore(active) {
     mergeAggregate(all, aggregateEvents(active.events));
     return all;
 }
+function adoptGraphqlRateLimit(graphql, candidate, fingerprint) {
+    const next = selectAuthoritativeRateLimit(graphql.rateLimit, candidate);
+    if (next !== graphql.rateLimit)
+        graphql.credentialFingerprint = fingerprint;
+    graphql.rateLimit = next;
+}
 function selectAuthoritativeRateLimit(current, candidate) {
     if (current === undefined)
         return { ...candidate };

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

@@ -4,10 +4,14 @@ export interface ApiTelemetryEvent {
     kind: "GraphQL" | "REST";
     method: string;
     authSource: string;
+    /** Truncated SHA-256 of the credential that produced this request. */
+    credentialFingerprint?: 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;
+/** Attach the credential fingerprint without adding it when this command has none. */
+export declare function withGraphqlCredentialFingerprint<T extends object>(sample: T): T;
 export declare function summarizeApiTelemetry(): ApiUsage | undefined;

package/bin/github/api-telemetry.mjs

@@ -65,6 +65,18 @@ export function mergeGraphqlRateLimit(headerRateLimit, data) {
         ...(payload !== null && Number.isFinite(payload.nodeCount) && { nodeCount: payload.nodeCount }),
     };
 }
+/** Fingerprint of the credential that owns the authoritative GraphQL rate-limit sample. */
+function graphqlQuotaCredentialFingerprint() {
+    const active = store();
+    if (active === undefined)
+        return undefined;
+    return aggregateStore(active).graphql.credentialFingerprint;
+}
+/** Attach the credential fingerprint without adding it when this command has none. */
+export function withGraphqlCredentialFingerprint(sample) {
+    const credentialFingerprint = graphqlQuotaCredentialFingerprint();
+    return credentialFingerprint === undefined ? sample : { ...sample, credentialFingerprint };
+}
 export function summarizeApiTelemetry() {
     const active = store();
     if (active === undefined)

package/bin/github/graphql-http.mjs

@@ -22,9 +22,11 @@ async function graphqlInner(query, vars, opts) {
     }));
     const t0 = performance.now();
     let authSource = "unknown";
+    let credentialFingerprint;
     const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
         const auth = await makeAuthHeaders();
         authSource = auth.source;
+        credentialFingerprint = auth.fingerprint;
         return fetch(url, {
             method: "POST",
             headers: auth.headers,
@@ -38,6 +40,7 @@ async function graphqlInner(query, vars, opts) {
         response,
         durationMs,
         authSource,
+        credentialFingerprint,
     }));
     const durationMs = Math.round(performance.now() - retryT0);
     const headerRateLimit = parseRateLimit(res.headers);
@@ -61,6 +64,7 @@ async function graphqlInner(query, vars, opts) {
             kind: "GraphQL",
             method: "POST",
             authSource,
+            credentialFingerprint,
             rateLimit: headerRateLimit ?? undefined,
         });
         throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
@@ -93,6 +97,7 @@ async function graphqlInner(query, vars, opts) {
             kind: "GraphQL",
             method: "POST",
             authSource,
+            credentialFingerprint,
             rateLimit: headerRateLimit ?? undefined,
         });
         throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
@@ -123,6 +128,7 @@ async function graphqlInner(query, vars, opts) {
         kind: "GraphQL",
         method: "POST",
         authSource,
+        credentialFingerprint,
         rateLimit: rateLimit ?? undefined,
     });
     const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);

package/bin/github/http-auth.d.mts

@@ -2,6 +2,8 @@ export type AuthSource = "GH_TOKEN" | "GITHUB_TOKEN" | "gh auth token" | "GITHUB
 export declare function _resetTokenCache(): void;
 export declare function hasCachedToken(): boolean;
 export declare function clearTokenCache(): void;
+/** Truncated SHA-256. Callers persist this instead of the token or its full hash. */
+export declare function credentialFingerprint(token: string): string;
 /**
  * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
  * conditional REST requests) on top of the standard auth/version headers.
@@ -9,4 +11,5 @@ export declare function clearTokenCache(): void;
 export declare function makeAuthHeaders(extra?: Record<string, string>): Promise<{
     headers: Record<string, string>;
     source: AuthSource;
+    fingerprint: string;
 }>;

package/bin/github/http-auth.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -15,6 +16,10 @@ export function clearTokenCache() {
     _token = undefined;
     _tokenSource = undefined;
 }
+/** Truncated SHA-256. Callers persist this instead of the token or its full hash. */
+export function credentialFingerprint(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
 async function resolveToken() {
     if (_token && _tokenSource)
         return { token: _token, source: _tokenSource };
@@ -58,6 +63,7 @@ export async function makeAuthHeaders(extra) {
     const { token, source } = await resolveToken();
     return {
         source,
+        fingerprint: credentialFingerprint(token),
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: "application/vnd.github+json",

package/bin/github/http-intermediate.d.mts

@@ -6,4 +6,5 @@ export declare function recordIntermediateResponse(opts: {
     response: Response;
     durationMs: number;
     authSource: string;
+    credentialFingerprint?: string;
 }): void;

package/bin/github/http-intermediate.mjs

@@ -15,6 +15,9 @@ export function recordIntermediateResponse(opts) {
         kind: opts.kind === "GraphQL" ? "GraphQL" : "REST",
         method: opts.method,
         authSource: opts.authSource,
+        ...(opts.credentialFingerprint !== undefined && {
+            credentialFingerprint: opts.credentialFingerprint,
+        }),
         rateLimit,
     });
 }

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.d.mts

@@ -7,11 +7,17 @@ export interface GraphqlQuotaWarningState {
     lastRemaining: number;
     resetAt: number;
     warnedThresholds: number[];
+    /** Truncated SHA-256 of the credential. Absent in state written before fingerprints. */
+    credentialFingerprint?: string;
     rearmEpoch?: number;
 }
-export declare function evaluateGraphqlQuotaWarning(bands: GraphqlQuotaWarningBand[], sample: Pick<GraphqlApiUsage, "resource" | "limit" | "used" | "remaining" | "resetAt">, previous: GraphqlQuotaWarningState | null, observedAt?: number): {
+type GraphqlQuotaSample = Pick<GraphqlApiUsage, "resource" | "limit" | "used" | "remaining" | "resetAt"> & {
+    credentialFingerprint?: string;
+};
+export declare function evaluateGraphqlQuotaWarning(bands: GraphqlQuotaWarningBand[], sample: GraphqlQuotaSample, previous: GraphqlQuotaWarningState | null, observedAt?: number): {
     warning?: GraphqlQuotaWarning;
     state: GraphqlQuotaWarningState & {
         rearmEpoch: number;
     };
 };
+export {};