pr-shepherd 0.44.1 → 0.45.0

package/bin/github/http-auth.mjs

@@ -3,29 +3,40 @@ import { promisify } from "node:util";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const execFile = promisify(execFileCb);
 let _token;
+let _tokenSource;
 export function _resetTokenCache() {
     _token = undefined;
+    _tokenSource = undefined;
 }
 export function hasCachedToken() {
     return _token !== undefined;
 }
 export function clearTokenCache() {
     _token = undefined;
+    _tokenSource = undefined;
 }
 async function resolveToken() {
-    if (_token)
-        return _token;
-    const envToken = process.env["GH_TOKEN"] ?? process.env["GITHUB_TOKEN"];
-    if (envToken) {
-        _token = envToken;
-        return _token;
+    if (_token && _tokenSource)
+        return { token: _token, source: _tokenSource };
+    const ghToken = process.env["GH_TOKEN"];
+    if (ghToken) {
+        _token = ghToken;
+        _tokenSource = "GH_TOKEN";
+        return { token: _token, source: _tokenSource };
+    }
+    const githubToken = process.env["GITHUB_TOKEN"];
+    if (githubToken) {
+        _token = githubToken;
+        _tokenSource = "GITHUB_TOKEN";
+        return { token: _token, source: _tokenSource };
     }
     try {
         const { stdout } = await execFile("gh", ["auth", "token"]);
         const token = stdout.trim();
         if (token) {
             _token = token;
-            return _token;
+            _tokenSource = "gh auth token";
+            return { token: _token, source: _tokenSource };
         }
     }
     catch {
@@ -34,16 +45,26 @@ async function resolveToken() {
     const codexToken = process.env["GITHUB_PERSONAL_ACCESS_TOKEN"];
     if (codexToken) {
         _token = codexToken;
-        return _token;
+        _tokenSource = "GITHUB_PERSONAL_ACCESS_TOKEN";
+        return { token: _token, source: _tokenSource };
     }
     throw new ShepherdError("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.", EXIT.NOPERM);
 }
-export async function makeHeaders() {
+/**
+ * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
+ * conditional REST requests) on top of the standard auth/version headers.
+ */
+export async function makeAuthHeaders(extra) {
+    const { token, source } = await resolveToken();
     return {
-        Authorization: `Bearer ${await resolveToken()}`,
-        Accept: "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2022-11-28",
-        "User-Agent": "pr-shepherd",
-        "Content-Type": "application/json",
+        source,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "pr-shepherd",
+            "Content-Type": "application/json",
+            ...extra,
+        },
     };
 }

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

@@ -0,0 +1,9 @@
+export declare function recordIntermediateResponse(opts: {
+    n: number;
+    kind: "GraphQL" | "REST" | "restText";
+    method: string;
+    url: string;
+    response: Response;
+    durationMs: number;
+    authSource: string;
+}): void;

package/bin/github/http-intermediate.mjs

@@ -0,0 +1,20 @@
+import { appendEntry } from "../log/log-file.mjs";
+import { formatResponseEntry } from "../log/session.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { parseRateLimit, parseRetryAfter } from "./http-utils.mjs";
+export function recordIntermediateResponse(opts) {
+    const rateLimit = parseRateLimit(opts.response.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(opts.response.headers);
+    appendEntry(formatResponseEntry({
+        ...opts,
+        status: opts.response.status,
+        rateLimit,
+        retryAfterSeconds,
+    }));
+    recordApiTelemetry({
+        kind: opts.kind === "GraphQL" ? "GraphQL" : "REST",
+        method: opts.method,
+        authSource: opts.authSource,
+        rateLimit,
+    });
+}

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

@@ -1,4 +1,4 @@
-type RetryLogFn = (status: number, durationMs: number) => void;
+type RetryLogFn = (response: Response, durationMs: number) => void;
 export declare function requestWithTokenRetry(fn: () => Promise<Response>, t0: number, onIntermediate?: RetryLogFn): Promise<{
     res: Response;
     attempt: number;

package/bin/github/http-request.mjs

@@ -23,7 +23,7 @@ async function fetchWithTransportRetry(fn) {
 export async function requestWithTokenRetry(fn, t0, onIntermediate) {
     const res = await fetchWithTransportRetry(fn);
     if (res.status === 401 && hasCachedToken()) {
-        onIntermediate?.(401, Math.round(performance.now() - t0));
+        onIntermediate?.(res, Math.round(performance.now() - t0));
         try {
             await res.arrayBuffer();
         }

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

@@ -3,6 +3,12 @@ export interface RateLimitInfo {
     remaining: number;
     limit: number;
     resetAt: number;
+    used?: number;
+    resource?: string;
+    /** Exact GraphQL query cost when the operation selected rateLimit.cost. */
+    cost?: number;
+    /** Exact GraphQL node count when the operation selected rateLimit.nodeCount. */
+    nodeCount?: number;
 }
 export declare function sanitizeBody(body: string): string;
 export declare function redactToken(body: string): string;

package/bin/github/http-utils.mjs

@@ -45,7 +45,16 @@ export function parseRateLimit(headers) {
     const limit = Number(lRaw);
     const resetAt = Number(tRaw);
     if (Number.isFinite(remaining) && Number.isFinite(limit) && Number.isFinite(resetAt)) {
-        return { remaining, limit, resetAt };
+        const usedRaw = headers.get("x-ratelimit-used");
+        const used = usedRaw === null ? undefined : Number(usedRaw);
+        const resource = headers.get("x-ratelimit-resource") ?? undefined;
+        return {
+            remaining,
+            limit,
+            resetAt,
+            ...(Number.isFinite(used) && { used }),
+            ...(resource !== undefined && resource !== "" && { resource }),
+        };
     }
     return null;
 }

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

@@ -1,7 +1,22 @@
+import { type StateKey } from "../state/rest-cache.mts";
 import { type RateLimitInfo } from "./http-utils.mts";
 export interface RestResult<T = unknown> {
     data: T;
     rateLimit?: RateLimitInfo;
 }
+/**
+ * Enables `If-None-Match` conditional requests for a REST call, backed by a
+ * per-PR on-disk cache (see `src/state/rest-cache.mts`). A 304 response
+ * returns the cached body and — unlike a normal request — does not consume
+ * the primary REST rate-limit quota.
+ */
+export interface RestRequestOptions {
+    conditional?: {
+        key: StateKey;
+        /** Logical cache name; must be unique per distinct resource + page. */
+        name: string;
+        headSha?: string;
+    };
+}
 export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
-export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown): Promise<RestResult<T>>;
+export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown, opts?: RestRequestOptions): Promise<RestResult<T>>;

package/bin/github/rest-http.mjs

@@ -1,9 +1,13 @@
+/* eslint-disable max-lines */
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { loadEtagEntry, storeEtagEntry } from "../state/rest-cache.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 const SAFE_GITHUB_REST_PATH = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]*$/;
 function githubApiUrl(path) {
@@ -24,19 +28,55 @@ export async function rest(method, path, body) {
     const { data } = await restWithRateLimit(method, path, body);
     return data;
 }
-export async function restWithRateLimit(method, path, body) {
+export async function restWithRateLimit(method, path, body, opts) {
     const url = githubApiUrl(path);
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "REST", method, url, body }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
+    let authSource = "unknown";
+    const cached = opts?.conditional
+        ? await loadEtagEntry(opts.conditional.key, opts.conditional.name)
+        : null;
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders(cached ? { "If-None-Match": cached.etag } : undefined);
+        authSource = auth.source;
+        return fetch(url, {
+            method,
+            headers: auth.headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "REST",
         method,
-        headers: await makeHeaders(),
-        body: body !== undefined ? JSON.stringify(body) : undefined,
-    }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "REST", method, url, status, durationMs })));
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
-    const ct = res.headers.get("content-type") ?? "";
     const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(res.headers);
+    // A 304 is not `res.ok` but is not an error either — and critically, does
+    // not consume the primary REST request quota — so it must be handled
+    // before the !res.ok branch below.
+    if (res.status === 304 && cached) {
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "REST",
+            method,
+            url,
+            status: res.status,
+            durationMs,
+            attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
+        }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
+        return { data: cached.body, rateLimit };
+    }
+    const ct = res.headers.get("content-type") ?? "";
     if (!res.ok) {
         const text = await res.text();
         appendEntry(formatResponseEntry({
@@ -48,11 +88,16 @@ export async function restWithRateLimit(method, path, body) {
             durationMs,
             textBody: redactToken(text),
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
         throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
             rateLimit,
-            retryAfterSeconds: parseRetryAfter(res.headers),
+            retryAfterSeconds,
+            authSource,
         });
     }
     if (ct.includes("application/json")) {
@@ -67,7 +112,21 @@ export async function restWithRateLimit(method, path, body) {
             contentType: ct,
             body: json,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
+        if (opts?.conditional) {
+            const etag = res.headers.get("etag");
+            if (etag) {
+                await storeEtagEntry(opts.conditional.key, opts.conditional.name, {
+                    etag,
+                    body: json,
+                    ...(opts.conditional.headSha !== undefined && { headSha: opts.conditional.headSha }),
+                });
+            }
+        }
         return { data: json, rateLimit };
     }
     appendEntry(formatResponseEntry({
@@ -79,6 +138,10 @@ export async function restWithRateLimit(method, path, body) {
         durationMs,
         contentType: ct || undefined,
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit,
+        retryAfterSeconds,
     }));
+    recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
     return { data: undefined, rateLimit };
 }

package/bin/github/rest-text.mjs

@@ -1,19 +1,45 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 export async function restText(path) {
     const url = `${BASE_URL}${path}`;
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, { method: "GET", headers: await makeHeaders(), redirect: "manual" }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "restText", method: "GET", url, status, durationMs })));
+    let authSource = "unknown";
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders();
+        authSource = auth.source;
+        return fetch(url, { method: "GET", headers: auth.headers, redirect: "manual" });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "restText",
+        method: "GET",
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
+    const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(res.headers);
+    recordApiTelemetry({ kind: "REST", method: "GET", authSource, rateLimit });
     if ([301, 302, 307, 308].includes(res.status)) {
-        const redirected = await followRestTextRedirect(res, { n, url, durationMs, attempt });
+        const redirected = await followRestTextRedirect(res, {
+            n,
+            url,
+            durationMs,
+            attempt,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
+        });
         if (redirected !== null)
             return redirected;
     }
@@ -27,11 +53,15 @@ export async function restText(path) {
             status: res.status,
             durationMs,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
         throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
-            rateLimit: parseRateLimit(res.headers) ?? undefined,
-            retryAfterSeconds: parseRetryAfter(res.headers),
+            rateLimit,
+            retryAfterSeconds,
+            authSource,
         });
     }
     appendEntry(formatResponseEntry({
@@ -43,6 +73,9 @@ export async function restText(path) {
         durationMs,
         contentLength: parseContentLength(res.headers),
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit,
+        retryAfterSeconds,
     }));
     return res.text();
 }
@@ -55,6 +88,9 @@ async function followRestTextRedirect(res, entry) {
         status: res.status,
         durationMs: entry.durationMs,
         attempt: entry.attempt > 1 ? entry.attempt : undefined,
+        authSource: entry.authSource,
+        rateLimit: entry.rateLimit,
+        retryAfterSeconds: entry.retryAfterSeconds,
     }));
     const location = res.headers.get("location");
     if (!location)

package/bin/index.mjs

@@ -9,6 +9,7 @@
  */
 import { main } from "./cli-parser.mjs";
 import { errorToExitCode } from "./exit-codes.mjs";
+import { formatCliError } from "./cli/error-format.mjs";
 function formatCause(cause, seen = new Set(), depth = 0) {
     if (depth > 5 || seen.has(cause))
         return "[circular or deep cause chain]";
@@ -21,7 +22,7 @@ function formatCause(cause, seen = new Set(), depth = 0) {
     return String(cause);
 }
 main(process.argv).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = formatCliError(err);
     const causeStr = err instanceof Error && err.cause != null ? formatCause(err.cause) : null;
     process.stderr.write(`pr-shepherd error: ${msg}${causeStr !== null ? ` (cause: ${causeStr})` : ""}\n`);
     process.exit(errorToExitCode(err));

package/bin/log/session.d.mts

@@ -24,6 +24,17 @@ interface HttpResponseEntry {
     contentLength?: number;
     /** Set on 401-retry invocations. */
     attempt?: number;
+    authSource?: string;
+    rateLimit?: {
+        resource?: string;
+        limit: number;
+        used?: number;
+        remaining: number;
+        resetAt: number;
+        cost?: number;
+        nodeCount?: number;
+    };
+    retryAfterSeconds?: number;
 }
 export declare function formatRequestEntry(entry: HttpRequestEntry): string;
 export declare function formatResponseEntry(entry: HttpResponseEntry): string;

package/bin/log/session.mjs

@@ -70,6 +70,28 @@ export function formatResponseEntry(entry) {
             ? `restText response — ${entry.status}${attempt} · ${entry.durationMs}ms`
             : `REST response — ${entry.status}${attempt} · ${entry.durationMs}ms`;
     let out = `### #${entry.n} ${label} · ${ts}\n\n`;
+    if (entry.authSource !== undefined)
+        out += `auth-source: \`${entry.authSource}\`\n`;
+    if (entry.rateLimit !== undefined) {
+        const used = entry.rateLimit.used !== undefined ? ` · used ${entry.rateLimit.used}` : "";
+        const resource = entry.rateLimit.resource ?? "unknown";
+        out += `rate-limit: \`${resource}\` · remaining ${entry.rateLimit.remaining}/${entry.rateLimit.limit}${used} · reset ${new Date(entry.rateLimit.resetAt * 1000).toISOString()}\n`;
+        if (entry.rateLimit.cost !== undefined || entry.rateLimit.nodeCount !== undefined) {
+            const parts = [
+                entry.rateLimit.cost !== undefined ? `cost ${entry.rateLimit.cost}` : null,
+                entry.rateLimit.nodeCount !== undefined ? `nodes ${entry.rateLimit.nodeCount}` : null,
+            ].filter(Boolean);
+            out += `graphql-query: ${parts.join(" · ")}\n`;
+        }
+    }
+    if (entry.retryAfterSeconds !== undefined) {
+        out += `retry-after: ${entry.retryAfterSeconds}s\n`;
+    }
+    if (entry.authSource !== undefined ||
+        entry.rateLimit !== undefined ||
+        entry.retryAfterSeconds !== undefined) {
+        out += "\n";
+    }
     if (entry.kind === "restText") {
         if (entry.contentLength !== undefined) {
             out += `content-length: ${entry.contentLength} bytes (body not logged)\n\n`;

package/bin/mcp/server.mjs

@@ -6,6 +6,7 @@ import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from
 import { isRepositoryQualifiedPrReference } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
 import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
+import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
 const pr = z
@@ -166,16 +167,29 @@ function toolError(error) {
         : error instanceof PartialApplyError
             ? errorToExitCode(error.cause)
             : errorToExitCode(error);
+    const cause = error instanceof PartialApplyError ? error.cause : error;
+    const githubDetails = serializeGitHubRequestErrorDetails(cause);
     const details = error instanceof PartialApplyError
         ? { failedIndex: error.failedIndex, completed: redactValue(error.completed) }
         : error instanceof PrShepherdValidationError
             ? { validation: true }
             : {};
-    const message = redactErrorMessage(error instanceof Error ? error.message : String(error));
+    const formattedCause = formatCliError(cause);
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    const message = redactErrorMessage(error instanceof PartialApplyError && formattedCause.startsWith(causeMessage)
+        ? `${error.message}${formattedCause.slice(causeMessage.length)}`
+        : formattedCause);
     return {
         isError: true,
         content: [{ type: "text", text: `pr-shepherd error (${code}): ${message}` }],
-        structuredContent: { code, message, details },
+        structuredContent: {
+            code,
+            message,
+            details: {
+                ...details,
+                ...(githubDetails !== undefined && { github: redactValue(githubDetails) }),
+            },
+        },
     };
 }
 function redactErrorMessage(message) {

package/bin/quota-warning.d.mts

@@ -0,0 +1,2 @@
+import type { GraphqlQuotaWarning } from "./types.mts";
+export declare function buildQuotaAwareContinuation(warning: GraphqlQuotaWarning, prefix: string): string;

package/bin/quota-warning.mjs

@@ -0,0 +1,6 @@
+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). For the time being, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr checks\`, \`gh pr review\`, \`gh api\` REST endpoints) for PR operations — they draw on the separate REST budget, not the depleted GraphQL pool. Resume 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, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, 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-claims.d.mts

@@ -0,0 +1,2 @@
+import type { GraphqlQuotaWarning } from "../types.mts";
+export declare function claimWarning(path: string, warning: GraphqlQuotaWarning, now: number, rearmEpoch: number): Promise<boolean>;

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

@@ -0,0 +1,61 @@
+import { mkdir, open, readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+export async function claimWarning(path, warning, now, rearmEpoch) {
+    const claimsDir = `${path}.claims`;
+    const claimPath = join(claimsDir, `${warning.resetAt}-${warning.limit}-${warning.thresholdPercent}-${rearmEpoch}.json`);
+    let handle;
+    try {
+        await mkdir(claimsDir, { recursive: true });
+        await sweepStaleClaims(claimsDir, now);
+        handle = await open(claimPath, "wx");
+        await handle.writeFile(JSON.stringify({
+            resource: warning.resource,
+            resetAt: warning.resetAt,
+            thresholdPercent: warning.thresholdPercent,
+            rearmEpoch,
+        }), "utf8");
+        return true;
+    }
+    catch (error) {
+        // When state storage is unavailable, surfacing the warning is safer than
+        // silently exhausting the credential. EEXIST alone means another process
+        // racing for this exact re-arm epoch already won the claim — a claim
+        // left over from an earlier epoch (e.g. before a credential switch) has
+        // a different filename and never collides here, so a re-armed warning
+        // is never suppressed by a stale epoch's claim.
+        return !isAlreadyExists(error);
+    }
+    finally {
+        try {
+            await handle?.close();
+        }
+        catch {
+            // Best-effort claim cleanup is unnecessary: existence is the claim.
+        }
+    }
+}
+async function sweepStaleClaims(claimsDir, now) {
+    try {
+        const entries = await readdir(claimsDir);
+        await Promise.all(entries.map(async (entry) => {
+            const resetAt = Number(entry.split("-")[0]);
+            if (!Number.isFinite(resetAt) || now < resetAt)
+                return;
+            try {
+                await unlink(join(claimsDir, entry));
+            }
+            catch {
+                // Best-effort sweep.
+            }
+        }));
+    }
+    catch {
+        // Best-effort sweep; a missing or unreadable directory is fine.
+    }
+}
+function isAlreadyExists(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "EEXIST");
+}

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

@@ -0,0 +1,17 @@
+import type { GraphqlQuotaWarningBand } from "../config/load.mts";
+import type { GraphqlApiUsage, GraphqlQuotaWarning } from "../types.mts";
+export interface GraphqlQuotaWarningState {
+    resource: string;
+    limit: number;
+    lastUsed?: number;
+    lastRemaining: number;
+    resetAt: number;
+    warnedThresholds: number[];
+    rearmEpoch?: number;
+}
+export declare function evaluateGraphqlQuotaWarning(bands: GraphqlQuotaWarningBand[], sample: Pick<GraphqlApiUsage, "resource" | "limit" | "used" | "remaining" | "resetAt">, previous: GraphqlQuotaWarningState | null, observedAt?: number): {
+    warning?: GraphqlQuotaWarning;
+    state: GraphqlQuotaWarningState & {
+        rearmEpoch: number;
+    };
+};

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

@@ -0,0 +1,43 @@
+export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt = Date.now() / 1000) {
+    const windowRolled = previous !== null && sample.resetAt > previous.resetAt && observedAt >= previous.resetAt;
+    const rearm = previous === null ||
+        previous.resource !== sample.resource ||
+        previous.limit !== sample.limit ||
+        windowRolled ||
+        (sample.used !== undefined && previous.lastUsed !== undefined
+            ? sample.used < previous.lastUsed
+            : sample.remaining > previous.lastRemaining);
+    const warned = new Set(rearm ? [] : previous.warnedThresholds);
+    const rearmEpoch = rearm ? (previous?.rearmEpoch ?? 0) + 1 : (previous?.rearmEpoch ?? 0);
+    const crossed = bands.filter((band) => sample.remaining * 100 <= sample.limit * band.remainingPercent);
+    const newCrossed = crossed.filter((band) => !warned.has(band.remainingPercent));
+    for (const band of crossed)
+        warned.add(band.remainingPercent);
+    const active = newCrossed.at(-1);
+    const state = {
+        resource: sample.resource,
+        limit: sample.limit,
+        ...(sample.used !== undefined && { lastUsed: sample.used }),
+        lastRemaining: sample.remaining,
+        resetAt: sample.resetAt,
+        warnedThresholds: bands
+            .map((band) => band.remainingPercent)
+            .filter((threshold) => warned.has(threshold)),
+        rearmEpoch,
+    };
+    if (active === undefined)
+        return { state };
+    return {
+        warning: {
+            resource: "graphql",
+            thresholdPercent: active.remainingPercent,
+            remaining: sample.remaining,
+            limit: sample.limit,
+            ...(sample.used !== undefined && { used: sample.used }),
+            resetAt: sample.resetAt,
+            pollIntervalMinutes: active.pollIntervalMinutes,
+            pollTimeoutMinutes: active.pollIntervalMinutes * 2,
+        },
+        state,
+    };
+}

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

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