pr-shepherd 0.44.1 → 0.45.0

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

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveStateBase } from "./base.mjs";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { getWorktreeKey } from "../util/worktree.mjs";
+import { claimWarning } from "./graphql-quota-claims.mjs";
+import { evaluateGraphqlQuotaWarning, } from "./graphql-quota-policy.mjs";
+const pendingStateUpdates = new Map();
+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);
+    if (path === undefined) {
+        const sessionKey = `${key.owner}/${key.repo}`;
+        if (!persist) {
+            return evaluateGraphqlQuotaWarning(bands, sample, sessionStates.get(sessionKey) ?? null, now)
+                .warning;
+        }
+        return serializeStateUpdate(`session:${sessionKey}`, async () => {
+            const evaluated = evaluateGraphqlQuotaWarning(bands, sample, sessionStates.get(sessionKey) ?? null, now);
+            sessionStates.set(sessionKey, evaluated.state);
+            return evaluated.warning;
+        });
+    }
+    if (!persist) {
+        const previous = await readState(path);
+        return evaluateGraphqlQuotaWarning(bands, sample, previous, now).warning;
+    }
+    return serializeStateUpdate(path, async () => {
+        const previous = await readState(path);
+        const evaluated = evaluateGraphqlQuotaWarning(bands, sample, previous, now);
+        const warning = evaluated.warning !== undefined &&
+            (await claimWarning(path, evaluated.warning, now, evaluated.state.rearmEpoch))
+            ? evaluated.warning
+            : undefined;
+        await writeState(path, evaluated.state);
+        return warning;
+    });
+}
+async function serializeStateUpdate(key, update) {
+    const previous = pendingStateUpdates.get(key) ?? Promise.resolve();
+    const result = previous.then(update);
+    const completion = result.then(() => undefined, () => undefined);
+    pendingStateUpdates.set(key, completion);
+    void completion.finally(() => {
+        if (pendingStateUpdates.get(key) === completion) {
+            pendingStateUpdates.delete(key);
+        }
+    });
+    return result;
+}
+async function warningStatePath(key) {
+    if (!SAFE_SEGMENT.test(key.owner) || !SAFE_SEGMENT.test(key.repo)) {
+        throw new Error(`Invalid repo key segments: ${key.owner}/${key.repo}`);
+    }
+    let worktreeKey;
+    try {
+        worktreeKey = await getWorktreeKey();
+    }
+    catch {
+        return undefined;
+    }
+    return join(resolveStateBase(), `${key.owner}-${key.repo}`, "worktrees", `${worktreeKey}-graphql-quota-warnings.json`);
+}
+async function readState(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (typeof parsed.resource !== "string" ||
+            !Number.isFinite(parsed.limit) ||
+            !Number.isFinite(parsed.lastRemaining) ||
+            !Number.isFinite(parsed.resetAt) ||
+            !Array.isArray(parsed.warnedThresholds)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeState(path, state) {
+    let tmp;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await writeFile(tmp, JSON.stringify(state), "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+    }
+    catch {
+        // Best-effort warning state must never fail the command.
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        }
+    }
+}

package/bin/state/rest-cache.d.mts

@@ -0,0 +1,48 @@
+/**
+ * Cross-tick GitHub API response cache — reduces redundant requests across
+ * `pr-shepherd` poll ticks.
+ *
+ * Two entry kinds, both keyed by a caller-chosen logical `name` (hashed to a
+ * filesystem-safe filename, mirroring seen-comments.mts):
+ *
+ * - "etag" entries back conditional REST requests (`If-None-Match`). A 200
+ *   response overwrites the entry; a 304 leaves it untouched. Used for list
+ *   endpoints whose content can change from tick to tick (job lists, run
+ *   lists).
+ * - "derived" entries cache a value computed from a response that is
+ *   immutable once identified by its key — job-log excerpts once a job is
+ *   terminal, check-run annotations once the check is COMPLETED. No ETag
+ *   applies; the cache is keyed on an immutable identity instead.
+ *
+ * Entries live under `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/rest-cache/`
+ * and are removed for free when `pr-shepherd clean` deletes the PR's state
+ * directory — there is no separate pruning routine.
+ */
+export interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export interface EtagCacheEntry {
+    kind: "etag";
+    name: string;
+    etag: string;
+    body: unknown;
+    storedAt: number;
+    headSha?: string;
+}
+export interface DerivedCacheEntry<T = unknown> {
+    kind: "derived";
+    name: string;
+    value: T;
+    storedAt: number;
+    headSha?: string;
+}
+export declare function loadEtagEntry(key: StateKey, name: string): Promise<EtagCacheEntry | null>;
+export declare function storeEtagEntry(key: StateKey, name: string, fields: {
+    etag: string;
+    body: unknown;
+    headSha?: string;
+}): Promise<void>;
+export declare function loadDerived<T = unknown>(key: StateKey, name: string): Promise<DerivedCacheEntry<T> | null>;
+export declare function storeDerived<T = unknown>(key: StateKey, name: string, value: T, headSha?: string): Promise<void>;

package/bin/state/rest-cache.mjs

@@ -0,0 +1,91 @@
+/**
+ * Cross-tick GitHub API response cache — reduces redundant requests across
+ * `pr-shepherd` poll ticks.
+ *
+ * Two entry kinds, both keyed by a caller-chosen logical `name` (hashed to a
+ * filesystem-safe filename, mirroring seen-comments.mts):
+ *
+ * - "etag" entries back conditional REST requests (`If-None-Match`). A 200
+ *   response overwrites the entry; a 304 leaves it untouched. Used for list
+ *   endpoints whose content can change from tick to tick (job lists, run
+ *   lists).
+ * - "derived" entries cache a value computed from a response that is
+ *   immutable once identified by its key — job-log excerpts once a job is
+ *   terminal, check-run annotations once the check is COMPLETED. No ETag
+ *   applies; the cache is keyed on an immutable identity instead.
+ *
+ * Entries live under `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/rest-cache/`
+ * and are removed for free when `pr-shepherd clean` deletes the PR's state
+ * directory — there is no separate pruning routine.
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { resolvePrStatePath } from "./base.mjs";
+export async function loadEtagEntry(key, name) {
+    const entry = await readEntry(key, name);
+    return entry?.kind === "etag" ? entry : null;
+}
+export async function storeEtagEntry(key, name, fields) {
+    await writeEntry(key, name, {
+        kind: "etag",
+        name,
+        etag: fields.etag,
+        body: fields.body,
+        storedAt: Date.now(),
+        ...(fields.headSha !== undefined && { headSha: fields.headSha }),
+    });
+}
+export async function loadDerived(key, name) {
+    const entry = await readEntry(key, name);
+    return entry?.kind === "derived" ? entry : null;
+}
+export async function storeDerived(key, name, value, headSha) {
+    await writeEntry(key, name, {
+        kind: "derived",
+        name,
+        value,
+        storedAt: Date.now(),
+        ...(headSha !== undefined && { headSha }),
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function readEntry(key, name) {
+    try {
+        const raw = await readFile(resolvePath(key, name), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeEntry(key, name, entry) {
+    let tmp;
+    try {
+        const path = resolvePath(key, name);
+        await mkdir(dirname(path), { recursive: true });
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await writeFile(tmp, JSON.stringify(entry), "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+    }
+    catch {
+        // best-effort — a failed cache write just means the next tick re-fetches
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function resolvePath(key, name) {
+    const hash = createHash("sha256").update(name, "utf8").digest("hex");
+    return resolvePrStatePath(key, "rest-cache", `${hash}.json`);
+}

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

@@ -0,0 +1,31 @@
+export interface ApiResourceUsage {
+    resource: string;
+    requestCount: number;
+    limit: number;
+    used?: number;
+    remaining: number;
+    resetAt: number;
+}
+export interface GraphqlApiUsage extends ApiResourceUsage {
+    /** Exact sum reported by rateLimit.cost for GraphQL queries in this command. */
+    measuredQueryCost: number;
+    /** Requests without an exact cost, principally GraphQL mutations. */
+    unmeasuredRequestCount: number;
+    /** Exact sum reported by rateLimit.nodeCount for measured GraphQL queries. */
+    nodeCount: number;
+}
+export interface ApiUsage {
+    credentialSources: string[];
+    graphql?: GraphqlApiUsage;
+    rest?: ApiResourceUsage[];
+}
+export interface GraphqlQuotaWarning {
+    resource: "graphql";
+    thresholdPercent: number;
+    remaining: number;
+    limit: number;
+    used?: number;
+    resetAt: number;
+    pollIntervalMinutes: number;
+    pollTimeoutMinutes: number;
+}

package/bin/types/api-usage.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/iterate.d.mts

@@ -5,6 +5,7 @@ import type { MergeRequirements } from "./merge-requirements.mts";
 import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
+import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
 export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
 export interface IterateResultSummary {
     passing: number;
@@ -41,6 +42,8 @@ export interface IterateResultBase {
     supersededNames?: string[];
     activity?: PrActivitySummary;
     mergeQueue?: import("./merge-queue.mts").MergeQueueReport;
+    apiUsage?: ApiUsage;
+    quotaWarning?: GraphqlQuotaWarning;
 }
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
@@ -129,12 +132,12 @@ export interface IterateCommandOptions extends GlobalOptions {
     noAutoMarkReady?: boolean;
     /** Legacy no-op retained for API compatibility; workflow runs are never cancelled. */
     noAutoCancelActionable?: boolean;
-    /** Override stall timeout seconds. Defaults to config.iterate.stallTimeoutMinutes * 60. */
     stallTimeoutSeconds?: number;
     /** Legacy per-invocation no-op retained for API compatibility. */
     neverCancelRuns?: string[];
     persistSeen?: boolean;
     /** Shepherd through readiness and emit the exact merge/queue command when ready. */
     merge?: boolean;
+    deferQuotaWarning?: boolean;
 }
 export {};

package/bin/types/report.d.mts

@@ -136,6 +136,8 @@ export interface AgentCheck {
     /** One-line status text shown in the GitHub UI (e.g. "67.68% of diff hit (target 85.00%)"). */
     summary?: string;
     logExcerpt?: string;
+    /** `gh run rerun` command, present only when the check has a runId and the viewer's repository role grants Actions rerun capability (WRITE+). */
+    rerunCommand?: string;
     annotations?: CheckAnnotation[];
     annotationOnly?: true;
     scope?: "merge_group";

package/bin/types.d.mts

@@ -12,3 +12,4 @@ export * from "./types/merge-requirements.mts";
 export * from "./types/merge-action.mts";
 export * from "./types/escalate.mts";
 export * from "./types/merge-queue.mts";
+export * from "./types/api-usage.mts";

package/bin/types.mjs

@@ -12,3 +12,4 @@ export * from "./types/merge-requirements.mjs";
 export * from "./types/merge-action.mjs";
 export * from "./types/escalate.mjs";
 export * from "./types/merge-queue.mjs";
+export * from "./types/api-usage.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.44.1",
+  "version": "0.45.0",
   "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.44.1",
+  "version": "0.45.0",
   "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.44.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.45.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -28,7 +28,7 @@ mechanics every tick. Apply the referenced playbook in full whenever a step poin
 ### Suggestion patches
 
 - Run one plural `build-suggestion-patches` command with a repeated `--thread-id … --message … [--description …]` group for every marked thread in displayed order.
-- The CLI only builds patches. Apply, stage, and commit the returned patches in order. Push only when authorization has been established outside Shepherd; GitHub viewer fields cannot verify the local Git credential.
+- The CLI only builds patches. Apply, stage, and commit the returned patches in order. This command does not itself check push authorization — follow the `iterate`/`fix_code` output's own commit/push instruction for whether to push now or hand off: it reflects whether GitHub confirms the viewer can push to the PR head branch.
 - The command builds from the fetched PR head and accepts a clean local descendant only when the complete ordered patch stream passes `git apply --check`.
 - If the command refuses because a suggestion is unsafe or no longer applies, inspect the current source, the displayed replacement block, and reviewer intent before editing manually. Do not apply a stale numeric range blindly or retry unchanged input.
 - A returned patch was checked against the then-current worktree. If it later fails, re-inspect the worktree because it changed after validation.
@@ -40,14 +40,19 @@ Match each failure's `[conclusion: …]` tag under `## Failing checks` to a rule
 
 More specific rows win over the general "GitHub Actions failure" row — check conclusion first.
 
-| Tag / kind                                                               | Do                                                                                                                                                                                                |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If it is missing or insufficient, hand off the displayed run ID/URL; Shepherd cannot verify authorization for another Actions read or mutation. |
-| Transient infrastructure failure                                         | Record the diagnosis. Shepherd does not recommend a rerun because GitHub exposes no exact viewer capability for that workflow-run action.                                                         |
-| Real test or build failure                                               | Apply a code fix — do not rerun.                                                                                                                                                                  |
-| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered. Hand off the displayed metadata; Shepherd cannot verify authorization for another Actions read or mutation.                                                           |
-| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered. Hand off the displayed metadata; Shepherd cannot verify authorization for another Actions read or mutation.                                                           |
-| `external` (no run ID, has a URL)                                        | Preserve the URL in the handoff. Shepherd does not recommend opening it because it cannot verify the current viewer's access to the external system.                                              |
+A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository role grants GitHub's Actions rerun capability (WRITE+) — Shepherd verified this from `repositoryPermission`. This confirms the account's role, not the granular scope of whatever credential actually runs `gh`; if the printed `rerun:` command still fails when run, do not retry it — hand off the displayed metadata instead, the same as an unauthorized check. No tag/command means Shepherd could not verify the account-level capability at all; hand off instead of guessing. A run still in progress, an `ACTION_REQUIRED` run (paused pending manual workflow approval — a rerun cannot grant that approval), or a check whose runId does not resolve to a GitHub Actions workflow never gets `[rerun authorized]`, regardless of role.
+
+When several bullets share one runId (matrix jobs from the same run), the `rerun:` command is printed once, on the first bullet; every bullet for that runId still carries `[rerun authorized]` and is covered by that single command — do not run it more than once.
+
+| Tag / kind                                                               | Do                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If it is missing or insufficient: run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes; otherwise hand off the displayed run ID/URL. |
+| Transient infrastructure failure                                         | Run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes. Otherwise record the diagnosis and hand off — Shepherd cannot verify rerun authorization.                                        |
+| Real test or build failure                                               | Apply a code fix — do not rerun, even if `[rerun authorized]` is shown.                                                                                                                                                  |
+| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered. Run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes; otherwise hand off the displayed metadata.                                                           |
+| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered. Run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes; otherwise hand off the displayed metadata.                                                           |
+| `[conclusion: ACTION_REQUIRED]`                                          | Never carries `[rerun authorized]`. Hand off — the run needs a maintainer's manual workflow approval on GitHub, which a rerun cannot grant.                                                                              |
+| `external` (no run ID, has a URL)                                        | Preserve the URL in the handoff. Shepherd does not recommend opening it because it cannot verify the current viewer's access to the external system.                                                                     |
 
 ### Review-mutation mechanics