pr-shepherd 0.44.0 → 0.45.0

package/bin/commands/check.mjs

@@ -27,6 +27,7 @@ export async function runCheck(opts) {
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
+    const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const config = loadConfig();
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
@@ -40,7 +41,7 @@ export async function runCheck(opts) {
     }
     const startupFailureChecks = result.checkSuitesComplete
         ? []
-        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
+        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber, stateKey);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedPrChecks = classifyChecks(allChecks);
     const latestRemoval = batchData.latestMergeQueueRemoval;
@@ -65,14 +66,15 @@ export async function runCheck(opts) {
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
     const ignored = classifiedChecks.filter((c) => c.category === "ignored");
-    const triagedBase = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
-    const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
+    const triagedBase = failing.length > 0 && !opts.skipTriage
+        ? await triageFailingChecks(failing, repo, stateKey)
+        : failing;
     const seenMap = await loadSeenMap(stateKey);
     const botUsernames = normalizeBotUsernames(config.botUsernames);
     const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
-    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber);
+    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber, { stateKey, headSha: batchData.headRefOid });
     const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
     const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize !== true));

package/bin/commands/iterate/api-usage.d.mts

@@ -0,0 +1,2 @@
+import type { IterateResult } from "../../types.mts";
+export declare function attachApiUsage(result: IterateResult, persistWarning: boolean, preservePersistedWarning?: boolean): Promise<IterateResult>;

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

@@ -0,0 +1,42 @@
+import { loadConfig } from "../../config/load.mjs";
+import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
+import { evaluateWorktreeGraphqlQuotaWarning } from "../../state/graphql-quota-warnings.mjs";
+import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
+function shouldWarn(result) {
+    if (["wait", "mark_ready", "merge"].includes(result.action))
+        return true;
+    if (result.action !== "fix_code")
+        return false;
+    return !result.fix.instructions.some((instruction) => /stop polling|human direction/i.test(instruction));
+}
+export async function attachApiUsage(result, persistWarning, preservePersistedWarning = false) {
+    const apiUsage = summarizeApiTelemetry();
+    if (apiUsage === undefined)
+        return result;
+    let quotaWarning = preservePersistedWarning ? result.quotaWarning : undefined;
+    if (quotaWarning === undefined && apiUsage.graphql !== undefined && shouldWarn(result)) {
+        const [owner, repo] = result.repo.split("/");
+        if (owner && repo) {
+            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, loadConfig().watch.graphqlQuotaWarnings, apiUsage.graphql, persistWarning);
+        }
+    }
+    const { quotaWarning: _deferredWarning, ...baseResult } = result;
+    const withWarning = {
+        ...baseResult,
+        apiUsage,
+        ...(quotaWarning !== undefined && { quotaWarning }),
+    };
+    if (quotaWarning === undefined || withWarning.action !== "fix_code")
+        return withWarning;
+    const instructions = [...withWarning.fix.instructions];
+    const completion = instructions.at(-1);
+    if (completion !== undefined) {
+        if (/\[FIX_CODE\].*non-terminal/i.test(completion)) {
+            instructions[instructions.length - 1] = buildQuotaAwareContinuation(quotaWarning, "`[FIX_CODE]` is non-terminal. After completing these steps,");
+        }
+        else if (/\[FIX_CODE\].*is conditional:.*if you did not change code,/i.test(completion)) {
+            instructions[instructions.length - 1] = completion.replace(/if you did not change code,(.*?)\s+and iterate again with the same options\./i, (_, before) => `if you did not change code,${before.trimEnd()}. ${buildQuotaAwareContinuation(quotaWarning, "").trimStart()}`);
+        }
+    }
+    return { ...withWarning, fix: { ...withWarning.fix, instructions } };
+}

package/bin/commands/iterate/check-instructions.d.mts

@@ -27,7 +27,7 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
  * command run unmodified is already correct for them. The pointer below is load-bearing:
  * without it, nothing in CLI output tells the agent that playbook exists.
  */
-export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
+export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand, pushAuthorized?: boolean): string[];
 /** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
-export declare function buildFixCompletionInstruction(checks: AgentCheck[], requiresRemoteUpdateAuthorization?: boolean, hasShaGatedReviewMutations?: boolean): string;
+export declare function buildFixCompletionInstruction(checks: AgentCheck[], requiresRemoteUpdateAuthorization?: boolean, hasShaGatedReviewMutations?: boolean, pushAuthorized?: boolean): string;

package/bin/commands/iterate/check-instructions.mjs

@@ -36,7 +36,7 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
  * command run unmodified is already correct for them. The pointer below is load-bearing:
  * without it, nothing in CLI output tells the agent that playbook exists.
  */
-export function buildResolveCommandInstruction(resolveCommand) {
+export function buildResolveCommandInstruction(resolveCommand, pushAuthorized = false) {
     if (!resolveCommand.hasMutations)
         return [];
     const instructions = [];
@@ -44,7 +44,9 @@ export function buildResolveCommandInstruction(resolveCommand) {
         instructions.push("Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an established Shepherd reply; a marked viewer-authored human thread is emitted resolve-only, not for another reply.");
     }
     if (resolveCommand.requiresHeadSha) {
-        instructions.push("If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, do not run this command until an authorized push updates the remote PR head; then replace `$HEAD_SHA` with that pushed commit SHA.");
+        instructions.push(pushAuthorized
+            ? "If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA."
+            : "If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, do not run this command until an authorized push updates the remote PR head; then replace `$HEAD_SHA` with that pushed commit SHA.");
     }
     if (resolveCommand.requiresDismissMessage) {
         instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
@@ -58,32 +60,49 @@ export function buildFailingCheckInstructions(checks) {
         return [];
     const hasBare = checks.some((c) => !c.runId && !c.detailsUrl);
     const hasTriageable = checks.some((c) => c.runId || c.detailsUrl);
+    const hasRerunAuthorized = checks.some((c) => c.rerunCommand);
     const instructions = [];
     if (hasTriageable) {
         instructions.push('Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.');
     }
+    if (hasRerunAuthorized) {
+        instructions.push('A `[rerun authorized]` check includes a `rerun:` command. See "CI failure triage" in the pr-shepherd skill for which conclusions warrant a rerun versus a code fix.');
+    }
     if (hasBare) {
         instructions.push("For each `(no runId)` failure, escalate to a human because no log or URL is available.");
     }
     return instructions;
 }
-export function buildFixCompletionInstruction(checks, requiresRemoteUpdateAuthorization = false, hasShaGatedReviewMutations = false) {
+export function buildFixCompletionInstruction(checks, requiresRemoteUpdateAuthorization = false, hasShaGatedReviewMutations = false, pushAuthorized = false) {
     if (requiresRemoteUpdateAuthorization) {
+        if (pushAuthorized) {
+            return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate again with the same options.";
+        }
         return "`[FIX_CODE]` requires a human handoff for an authorized push after conflict resolution. Shepherd cannot verify the Git credential's push authorization. Stop polling after committing, and resume only after the remote PR head changes.";
     }
     const hasUninspectableFailure = checks.some((check) => !check.runId && !check.detailsUrl);
-    const hasCiAuthorizationHandoff = checks.some((check) => check.conclusion === "CANCELLED" ||
-        check.conclusion === "STARTUP_FAILURE" ||
-        (check.runId === null && Boolean(check.detailsUrl)) ||
-        (check.runId !== null && !check.logExcerpt?.trim()));
     if (hasUninspectableFailure) {
         return "`[FIX_CODE]` requires a human handoff for an uninspectable failing check. Stop polling after escalating, and resume only after human direction.";
     }
-    if (hasCiAuthorizationHandoff) {
+    // Checks that would otherwise need a workflow-run mutation (rerun) to move forward.
+    // `rerunCommand` is only populated when the viewer's repository role grants Actions
+    // rerun capability (see canRerunWorkflows) — unauthorized checks stay a terminal handoff.
+    const ciHandoffChecks = checks.filter((check) => check.conclusion === "CANCELLED" ||
+        check.conclusion === "STARTUP_FAILURE" ||
+        (check.runId === null && Boolean(check.detailsUrl)) ||
+        (check.runId !== null && !check.logExcerpt?.trim()));
+    const hasUnauthorizedCiHandoff = ciHandoffChecks.some((check) => !check.rerunCommand);
+    if (hasUnauthorizedCiHandoff) {
         return "`[FIX_CODE]` requires a human handoff for a failing check with no authorized follow-up action. Stop polling after escalating, and resume only after human direction.";
     }
     if (hasShaGatedReviewMutations) {
+        if (pushAuthorized) {
+            return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate again with the same options; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
+        }
         return "`[FIX_CODE]` is conditional: if you changed code, stop after committing and resume only after an authorized push changes the remote PR head; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
     }
+    if (ciHandoffChecks.some((check) => check.rerunCommand)) {
+        return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate again with the same options to continue.";
+    }
     return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.";
 }

package/bin/commands/iterate/fix-code.mjs

@@ -11,6 +11,7 @@ import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
+import { canRerunWorkflows, canPushToHead } from "../../checks/conclusions.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 function nextFixAttempts(stored, headSha, threads) {
@@ -144,14 +145,39 @@ export async function handleFixCode(ctx) {
         };
     }
     await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
-    // GitHub does not expose a per-run viewer capability for cancellation. Fail closed:
-    // do not issue or recommend an Actions mutation based only on repository role.
+    // GitHub does not expose a per-run viewer capability for cancellation, so Shepherd never
+    // issues or recommends a cancellation regardless of repository role. A rerun is different:
+    // GitHub's Actions rerun API requires actions:write, which rides with WRITE+ repo access, so
+    // repositoryPermission is a proxy for account-level rerun capability (see canRerunWorkflows) —
+    // it does not confirm the credential executing `gh` has that scope; an unauthorized rerun
+    // simply fails when the agent runs it, the same residual risk as every other CLI-recommended
+    // git/gh mutation in this codebase.
     const cancelled = [];
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
     const resolutionOnlyThreads = report.threads.resolutionOnly;
     const actionableComments = report.comments.actionable.map(toAgentComment);
-    const failingAgentChecks = toAgentChecks(failingChecks);
+    const rerunAuthorized = canRerunWorkflows(report.viewerAuthorization);
+    // A workflow run can only be rerun once it has fully completed; a runId still present among
+    // in-progress checks (a sibling job from the same run) is not yet eligible.
+    const inProgressWorkflowRunIds = new Set(report.checks.inProgress.flatMap((c) => (c.runId !== null ? [c.runId] : [])));
+    // Confirmed GitHub Actions provenance for a runId: `source: "startup_failure"` checks are
+    // fetched directly from the Actions REST API (always genuine), while `source: "check_run"`
+    // checks need `workflowName` — derived from the same `checkSuite.workflowRun.workflow` GraphQL
+    // path as the run's numeric ID — because a third-party GitHub App's CheckRun can carry a
+    // details-URL-parsed runId that merely looks like an Actions run number.
+    const actionsRunIds = new Set(failingChecks.flatMap((c) => c.runId !== null && (c.source === "startup_failure" || c.workflowName !== undefined)
+        ? [c.runId]
+        : []));
+    const failingAgentChecks = toAgentChecks(failingChecks).map((c) => rerunAuthorized &&
+        c.runId &&
+        actionsRunIds.has(c.runId) &&
+        // ACTION_REQUIRED means the run is paused pending manual workflow approval; rerunning does
+        // not grant that approval, so no rerun command applies.
+        c.conclusion !== "ACTION_REQUIRED" &&
+        !inProgressWorkflowRunIds.has(c.runId)
+        ? { ...c, rerunCommand: `gh run rerun ${c.runId} -R ${report.repo}` }
+        : c);
     const checks = [
         ...failingAgentChecks,
         ...toAgentChecks(annotatedExtra).map((c) => ({ ...c, annotationOnly: true })),
@@ -160,16 +186,24 @@ export async function handleFixCode(ctx) {
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { behindBaseHint } = loadConfig().iterate;
+    // Whether GitHub reports the viewer can push to the PR head branch (own-repo write
+    // access, or a fork with viewerCanEditFiles/head-repo write for a fork PR). Drives
+    // whether the fix instructions push autonomously or hand off for an authorized push —
+    // see canPushToHead.
+    const pushAuthorized = canPushToHead(report.viewerAuthorization);
     // Only surface in-progress runs when a push is plausible — resolution-only and
     // summary-only iterations have no path to a push, so listing runs would prompt
     // unnecessary cancellation.
     const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    // Conflict resolution necessarily changes the branch head, but Shepherd cannot verify
-    // authorization for the local Git credential that would publish it. Defer review mutations
-    // until an authorized push updates the PR and a fresh iteration can rebuild SHA-safe commands.
-    const { resolveCommand, resolveOnlyCommand } = hasConflicts
+    // Conflict resolution necessarily changes the branch head. When the viewer cannot push,
+    // Shepherd cannot verify authorization for the local Git credential that would publish
+    // it, so review mutations are deferred until an authorized push updates the PR and a
+    // fresh iteration can rebuild SHA-safe commands. When the viewer can push, the agent
+    // pushes as part of this fix_code tick, so mutations can be built normally (SHA-gated
+    // like any other push-requiring tick).
+    const { resolveCommand, resolveOnlyCommand } = hasConflicts && !pushAuthorized
         ? buildResolveCommand([], [], [], [], [], prReference, botUsernames, [], undefined, [])
         : buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
@@ -202,7 +236,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, pushAuthorized);
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/index.mjs

@@ -14,7 +14,11 @@ import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { buildReadyMergeResult, handleActiveMergeState } from "./merge-state.mjs";
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
-export async function runIterate(opts) {
+import { withIterateApiUsage } from "./run.mjs";
+export function runIterate(opts) {
+    return withIterateApiUsage(opts, () => runIterateCore(opts));
+}
+async function runIterateCore(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
@@ -48,8 +52,7 @@ export async function runIterate(opts) {
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
     }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [...report.threads.actionable, ...report.threads.resolutionOnly], report.ruleAutoResolveReviewSummaryIds);
-    // Already-seen review summaries have no new content to surface — minimize them
-    // in-process so they never register as agent-facing actionable work (#313).
+    // Minimize already-seen review summaries in-process so they never become agent-facing work.
     // GitHub can still return a null/error/rate-limit result per ID without
     // throwing (autoMinimizeComments reports this via `errors`, not a rejection);
     // any ID it did not confirm minimized falls back into the agent-facing set so

package/bin/commands/iterate/merge-state.mjs

@@ -7,7 +7,10 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
         return null;
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
-    if (!queue && report.viewerAuthorization?.viewerCanEnableAutoMerge === true) {
+    // A merge queue is enrolled the same way auto-merge is granted: enabling
+    // auto-merge on a queue-required PR is what adds it to the queue, so
+    // viewerCanEnableAutoMerge authorizes both the plain-merge and enqueue paths.
+    if (report.viewerAuthorization?.viewerCanEnableAutoMerge === true) {
         return {
             ...base,
             action: "merge",
@@ -16,7 +19,7 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
                 repo: report.repo,
                 nodeId: report.nodeId,
                 headSha: report.headSha ?? "unknown",
-                queue: false,
+                queue,
             }),
         };
     }

package/bin/commands/iterate/render.d.mts

@@ -2,4 +2,4 @@ import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, Fir
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean): string[];
+isBehind?: boolean, viewerCanUpdate?: boolean, pushAuthorized?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -11,7 +11,7 @@ export function renderResolveCommand(rc) {
     return renderShellCommand(parts);
 }
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false) {
+isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     const instructions = [];
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
@@ -81,10 +81,14 @@ isBehind = false, viewerCanUpdate = false) {
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts) {
-        instructions.push(`Commit any remaining conflict-resolution changes${mutationSuffix}.`);
+        instructions.push(pushAuthorized
+            ? `Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`
+            : `Commit any remaining conflict-resolution changes${mutationSuffix}.`);
     }
     else if (hasNonConflictHints) {
-        instructions.push("If you changed code, commit any remaining changes, then stop and hand off for a push whose authorization is established outside Shepherd; do not run the remaining review mutations or iterate until the remote PR head changes. Shepherd cannot verify the Git credential's push authorization. If you did not change code, do not commit and continue with the remaining steps.");
+        instructions.push(pushAuthorized
+            ? "If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps."
+            : "If you changed code, commit any remaining changes, then stop and hand off for a push whose authorization is established outside Shepherd; do not run the remaining review mutations or iterate until the remote PR head changes. Shepherd cannot verify the Git credential's push authorization. If you did not change code, do not commit and continue with the remaining steps.");
     }
     if (viewerCanUpdate &&
         (hasReviewMutations ||
@@ -96,7 +100,7 @@ isBehind = false, viewerCanUpdate = false) {
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
-    instructions.push(...buildResolveCommandInstruction(resolveCommand));
-    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
+    instructions.push(...buildResolveCommandInstruction(resolveCommand, pushAuthorized));
+    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha, pushAuthorized));
     return instructions;
 }

package/bin/commands/iterate/run.d.mts

@@ -0,0 +1,2 @@
+import type { IterateCommandOptions, IterateResult } from "../../types.mts";
+export declare function withIterateApiUsage(opts: IterateCommandOptions, runCore: () => Promise<IterateResult>): Promise<IterateResult>;

package/bin/commands/iterate/run.mjs

@@ -0,0 +1,8 @@
+import { withApiTelemetryScope } from "../../github/api-telemetry.mjs";
+import { attachApiUsage } from "./api-usage.mjs";
+export function withIterateApiUsage(opts, runCore) {
+    return withApiTelemetryScope(async () => {
+        const result = await runCore();
+        return attachApiUsage(result, opts.deferQuotaWarning !== true);
+    });
+}

package/bin/commands/mark-files-as-viewed.mjs

@@ -3,6 +3,14 @@ import { graphql, getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
 import { paginateForward } from "../github/pagination.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr: Int!, $filesCursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       id

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

@@ -0,0 +1,2 @@
+import type { IterateResult } from "../types.mts";
+export declare function withPollApiUsage(runCore: () => Promise<IterateResult>, preservePersistedWarning: boolean): Promise<IterateResult>;

package/bin/commands/poll-run.mjs

@@ -0,0 +1,8 @@
+import { withApiTelemetryScope } from "../github/api-telemetry.mjs";
+import { attachApiUsage } from "./iterate/api-usage.mjs";
+export function withPollApiUsage(runCore, preservePersistedWarning) {
+    return withApiTelemetryScope(async () => {
+        const result = await runCore();
+        return attachApiUsage(result, true, preservePersistedWarning);
+    });
+}

package/bin/commands/poll.d.mts

@@ -1,5 +1,5 @@
 import type { IterateCommandOptions, IterateResult } from "../types.mts";
-interface PollCommandOptions extends IterateCommandOptions {
+export interface PollCommandOptions extends IterateCommandOptions {
     intervalSeconds: number;
     timeoutSeconds: number;
     /** Settle window after first FIX_CODE before returning. Default 60. 0 disables. */
@@ -9,4 +9,3 @@ interface PollCommandOptions extends IterateCommandOptions {
 }
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
 export declare function runPoll(opts: PollCommandOptions): Promise<IterateResult>;
-export {};

package/bin/commands/poll.mjs

@@ -1,5 +1,6 @@
 import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
+import { withPollApiUsage } from "./poll-run.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
     if (verbose) {
@@ -61,7 +62,10 @@ function writeDebounceProgress(tick, elapsedMs, remainingMs) {
     process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
 }
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
-export async function runPoll(opts) {
+export function runPoll(opts) {
+    return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true);
+}
+async function runPollCore(opts) {
     const { intervalSeconds, timeoutSeconds, debounceSeconds: debounceSecondsOpt, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
     const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
@@ -74,11 +78,8 @@ export async function runPoll(opts) {
     const quietStatus = quietStatusOpt === true;
     const untilTerminal = untilTerminalOpt === true;
     let lastWaitSignature = null;
-    // When prNumber is omitted, iterateOpts.prNumber starts undefined and each tick would otherwise
-    // re-infer the PR from the current branch. That inference query only matches OPEN PRs, so once
-    // the monitored PR merges it returns nothing and runIterate throws instead of reporting the
-    // terminal CANCEL/merged result. Pin the PR resolved by the first tick so later ticks target it
-    // directly and never re-run branch discovery.
+    let pendingQuotaWarning;
+    // Pin the PR resolved by the first tick; branch inference only matches OPEN PRs.
     let prNumber = opts.prNumber;
     let debounceUntil = null;
     while (true) {
@@ -88,10 +89,31 @@ export async function runPoll(opts) {
             ...iterateOpts,
             prNumber,
             persistSeen: debounceSeconds === 0 || pastDebounce,
+            // Until-terminal must persist before deciding to return.
+            deferQuotaWarning: !untilTerminal,
         });
         prNumber ??= lastResult.pr;
+        if (lastResult.quotaWarning !== undefined)
+            pendingQuotaWarning = lastResult.quotaWarning;
+        if (untilTerminal &&
+            pendingQuotaWarning !== undefined &&
+            !(lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) &&
+            !(debounceUntil !== null && !pastDebounce)) {
+            const terminalOrHandoff = ["cancel", "escalate"].includes(lastResult.action) ||
+                (lastResult.action === "fix_code" &&
+                    lastResult.fix.instructions.some((instruction) => /stop polling|human direction/i.test(instruction)));
+            if (terminalOrHandoff) {
+                const { quotaWarning: _quotaWarning, ...withoutQuotaWarning } = lastResult;
+                lastResult = withoutQuotaWarning;
+            }
+            else if (lastResult.quotaWarning === undefined) {
+                lastResult = { ...lastResult, quotaWarning: pendingQuotaWarning };
+            }
+            break;
+        }
         if (lastResult.action === "wait" && !pastDebounce) {
-            debounceUntil = null;
+            if (pendingQuotaWarning === undefined)
+                debounceUntil = null;
             const elapsedMs = Date.now() - start;
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
@@ -126,9 +148,6 @@ export async function runPoll(opts) {
                 writeDebounceProgress(tick, Date.now() - start, remainingMs);
                 await sleep(Math.min(intervalMs, remainingMs));
             }
-            // Always continue so a tick that *started* before debounceUntil but *finished*
-            // after it cannot return with persistSeen: false. The next loop iteration
-            // sees pastDebounce and persists.
             continue;
         }
         break;

package/bin/comments/rate-limit.d.mts

@@ -2,15 +2,19 @@ export interface ResolveRateLimitStop {
     message: string;
     retryAfterSeconds?: number;
     limit?: number;
+    used?: number;
     remaining?: number;
     resetAt?: number;
+    resource?: string;
 }
 export declare function rateLimitFromError(err: unknown, fallbackMessage: string): ResolveRateLimitStop | null;
 export declare function rateLimitFromGraphQlResult(messages: string[], meta: {
     rateLimit?: {
         remaining?: unknown;
         limit?: unknown;
+        used?: unknown;
         resetAt?: unknown;
+        resource?: unknown;
     };
     retryAfterSeconds?: unknown;
     stopOnZeroRemaining?: boolean;

package/bin/comments/rate-limit.mjs

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

package/bin/config/load.d.mts

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

package/bin/config/load.mjs

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

package/bin/config.json

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

package/bin/exit-codes.d.mts

@@ -35,7 +35,7 @@ export declare const EXIT: Readonly<{
     readonly UNAVAILABLE: 69;
     /** Unexpected/unclassified internal error — the fallback. */
     readonly SOFTWARE: 70;
-    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, `Retry-After` present. */
+    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, Retry-After, GraphQL INTERNAL. */
     readonly TEMPFAIL: 75;
     /** GitHub 401/403 — missing token or insufficient PAT scopes. */
     readonly NOPERM: 77;