pr-shepherd 0.44.1 → 0.45.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -69,12 +69,12 @@ Conversations Resolved: No [Not Required]
 1. Review each item under `## Review threads` and `## Failing checks` and decide whether it needs a code change.
 2. Apply every warranted review fix in each file referenced above.
 3. Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.
-4. 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 review mutations or iterate until the remote PR head changes. If you did not change code, do not commit and continue.
+4. If you changed code, commit any remaining changes and push to the PR head branch, then run 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.
 5. Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an earlier Shepherd reply: a marked viewer-authored human thread is emitted resolve-only when authorized, while a marked other-human thread is already acknowledged and has no further mutation.
-6. If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. After changed code, wait for an authorized push and use its SHA.
+6. 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.
 7. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
 8. Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.
-9. `[FIX_CODE]` is conditional: after changed code, stop until an authorized push changes the remote PR head; without code changes, complete the authorized review mutations and iterate again.
+9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate again with the same options; without code changes, complete the authorized review mutations and iterate again.
 ```
 
 See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
@@ -88,7 +88,7 @@ This system is opinionated and works best with PRs that use required status chec
 - Shepherd identifies its own latest reply only when that comment begins `<!-- pr-shepherd -->`, not from author equality. A marked viewer-authored thread can be resolved without another reply as a retry.
 - Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
-- The CLI never performs git mutations. It may emit local commit guidance, but it does not recommend a push because GitHub viewer fields cannot verify the local Git credential.
+- The CLI never performs git mutations itself — it only emits commit/push instructions for the agent to run. It recommends pushing autonomously (own-repo PRs, and fork PRs where the viewer has push access to the fork) unless GitHub's viewer fields affirmatively report no head-branch push access, in which case it hands the push off to a human instead.
 - Every GitHub mutation is permission-aware. Shepherd uses raw viewer capability fields, omits unauthorized commands, and repeats authorization checks in direct `apply` commands. Missing capability data fails closed.
 - `build_suggestion_patches` turns one or more ordered GitHub suggestion threads into checked patches and commit metadata, but never edits the working tree or git history. Local HEAD may be ahead when the live PR head is its ancestor.
 

package/bin/checks/conclusions.d.mts

@@ -1,4 +1,27 @@
-import type { CheckConclusion } from "../types.mts";
+import type { CheckConclusion, ViewerAuthorization } from "../types.mts";
+/**
+ * True when the viewer's base-repo role grants GitHub's Actions rerun capability
+ * (`actions: write`, which rides with push access). The rerun runs against the base
+ * repo where the run lives, so `repositoryPermission` — not `headRepositoryPermission`,
+ * which covers fork push access — is the right field to gate on.
+ */
+export declare function canRerunWorkflows(auth: ViewerAuthorization | undefined): boolean;
+/**
+ * True when the viewer can push commits to the PR head branch — the fork, for a fork PR
+ * (own-fork PRs report `headRepositoryPermission: "ADMIN"`), or the base repo otherwise.
+ * `viewerCanEditFiles` is GitHub's direct "can the viewer commit to this PR" signal (true
+ * for fork authors and for maintainers with "allow edits from maintainers" enabled) and
+ * takes priority when present.
+ *
+ * pr-shepherd's premise is that the caller has push access to the PR it's iterating, so
+ * this defaults to pushable: it withholds the autonomous push only when GitHub
+ * affirmatively reports no head-branch access (`viewerCanEditFiles === false` and
+ * `headRepositoryPermission` in `NONE`/`READ`/`TRIAGE`). An unverifiable/unknown signal —
+ * matching the residual risk already accepted for CI reruns (see `canRerunWorkflows`) —
+ * is treated as pushable rather than pre-emptively handed off; a push without access
+ * simply fails when attempted.
+ */
+export declare function canPushToHead(auth: ViewerAuthorization | undefined): boolean;
 /** Failing-check rows for formatter/instructions — excludes annotation-only carriers. */
 export declare function isFailingAgentCheck(check: {
     conclusion: CheckConclusion;

package/bin/checks/conclusions.mjs

@@ -1,4 +1,43 @@
 const NON_FAILING_CONCLUSIONS = new Set(["SUCCESS", "SKIPPED", "NEUTRAL"]);
+/** Repository roles GitHub grants `actions: write` to — the exact capability a workflow-run rerun needs. */
+const RERUN_CAPABLE_PERMISSIONS = new Set(["WRITE", "MAINTAIN", "ADMIN"]);
+/**
+ * True when the viewer's base-repo role grants GitHub's Actions rerun capability
+ * (`actions: write`, which rides with push access). The rerun runs against the base
+ * repo where the run lives, so `repositoryPermission` — not `headRepositoryPermission`,
+ * which covers fork push access — is the right field to gate on.
+ */
+export function canRerunWorkflows(auth) {
+    const permission = auth?.repositoryPermission;
+    return permission != null && RERUN_CAPABLE_PERMISSIONS.has(permission);
+}
+/** Repository roles that carry push access to the head branch. */
+const PUSH_CAPABLE_PERMISSIONS = new Set(["WRITE", "MAINTAIN", "ADMIN"]);
+/**
+ * True when the viewer can push commits to the PR head branch — the fork, for a fork PR
+ * (own-fork PRs report `headRepositoryPermission: "ADMIN"`), or the base repo otherwise.
+ * `viewerCanEditFiles` is GitHub's direct "can the viewer commit to this PR" signal (true
+ * for fork authors and for maintainers with "allow edits from maintainers" enabled) and
+ * takes priority when present.
+ *
+ * pr-shepherd's premise is that the caller has push access to the PR it's iterating, so
+ * this defaults to pushable: it withholds the autonomous push only when GitHub
+ * affirmatively reports no head-branch access (`viewerCanEditFiles === false` and
+ * `headRepositoryPermission` in `NONE`/`READ`/`TRIAGE`). An unverifiable/unknown signal —
+ * matching the residual risk already accepted for CI reruns (see `canRerunWorkflows`) —
+ * is treated as pushable rather than pre-emptively handed off; a push without access
+ * simply fails when attempted.
+ */
+export function canPushToHead(auth) {
+    if (auth === undefined)
+        return true;
+    if (auth.viewerCanEditFiles === true)
+        return true;
+    const permission = auth.headRepositoryPermission;
+    if (permission != null && !PUSH_CAPABLE_PERMISSIONS.has(permission))
+        return false;
+    return true;
+}
 /** True for conclusions that belong under `## Failing checks` (not success/skipped/neutral). */
 function isFailingCheckConclusion(conclusion) {
     return conclusion == null || !NON_FAILING_CONCLUSIONS.has(conclusion);

package/bin/checks/triage.d.mts

@@ -1,4 +1,5 @@
 import type { CheckRun, ClassifiedCheck, TriagedCheck } from "../types.mts";
 import type { RepoInfo } from "../github/client.mts";
-export declare function triageFailingChecks(failingChecks: ClassifiedCheck[], repo: RepoInfo): Promise<TriagedCheck[]>;
-export declare function fetchStartupFailureChecks(repo: RepoInfo, headSha: string, prNumber: number): Promise<CheckRun[]>;
+import { type StateKey } from "../state/rest-cache.mts";
+export declare function triageFailingChecks(failingChecks: ClassifiedCheck[], repo: RepoInfo, stateKey?: StateKey): Promise<TriagedCheck[]>;
+export declare function fetchStartupFailureChecks(repo: RepoInfo, headSha: string, prNumber: number, stateKey?: StateKey): Promise<CheckRun[]>;

package/bin/checks/triage.mjs

@@ -1,24 +1,27 @@
 /* eslint-disable max-lines */
 import { restWithRateLimit, restText } from "../github/http.mjs";
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
 const STARTUP_FAILURE_STATUS = "startup_failure";
 const LOG_EXCERPT_CONTEXT_LINES = 16;
 const LOG_EXCERPT_TAIL_LINES = 28;
 const LOG_EXCERPT_MAX_CHARS = 4_000;
 const TRUNCATED_SUFFIX = "\n[truncated]";
 const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
-export function triageFailingChecks(failingChecks, repo) {
+export function triageFailingChecks(failingChecks, repo, stateKey) {
     const jobsCache = new Map();
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, stateKey)));
 }
-async function triageCheck(check, repo, jobsCache) {
+async function triageCheck(check, repo, jobsCache, stateKey) {
     if (check.runId === null ||
         check.conclusion === "CANCELLED" ||
         check.conclusion === "STARTUP_FAILURE") {
         return { ...check };
     }
-    const jobs = await fetchJobs(check.runId, repo, jobsCache);
+    const jobs = await fetchJobs(check.runId, repo, jobsCache, stateKey);
     const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
-    const logExcerpt = jobInfo?.jobId ? await fetchJobLogExcerpt(jobInfo.jobId, repo) : undefined;
+    const logExcerpt = jobInfo?.jobId
+        ? await fetchJobLogExcerpt(jobInfo.jobId, repo, stateKey, jobInfo.jobConclusion != null)
+        : undefined;
     return {
         ...check,
         ...(jobInfo?.workflowName !== undefined && { workflowName: jobInfo.workflowName }),
@@ -27,9 +30,9 @@ async function triageCheck(check, repo, jobsCache) {
         ...(logExcerpt !== undefined && { logExcerpt }),
     };
 }
-export async function fetchStartupFailureChecks(repo, headSha, prNumber) {
+export async function fetchStartupFailureChecks(repo, headSha, prNumber, stateKey) {
     try {
-        return await fetchStartupFailureChecksUncached(repo, headSha, prNumber);
+        return await fetchStartupFailureChecksUncached(repo, headSha, prNumber, stateKey);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -37,13 +40,21 @@ export async function fetchStartupFailureChecks(repo, headSha, prNumber) {
         return [];
     }
 }
-async function fetchStartupFailureChecksUncached(repo, headSha, prNumber) {
+async function fetchStartupFailureChecksUncached(repo, headSha, prNumber, stateKey) {
     const { owner, name } = repo;
     const perPage = 100;
     const MAX_RUN_PAGES = 10;
     const checks = [];
     for (let page = 1; page <= MAX_RUN_PAGES; page++) {
-        const { data, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`);
+        const { data, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`, undefined, stateKey
+            ? {
+                conditional: {
+                    key: stateKey,
+                    name: `runs-startupfailure-${headSha}-p${page}`,
+                    headSha,
+                },
+            }
+            : undefined);
         checks.push(...data.workflow_runs
             .filter((run) => runBelongsToPr(run, prNumber, headSha))
             .map(workflowRunToCheckRun));
@@ -75,15 +86,15 @@ function workflowRunToCheckRun(run) {
 function runBelongsToPr(run, prNumber, headSha) {
     return (run.pull_requests ?? []).some((pr) => pr.number === prNumber && (pr.head?.sha ?? headSha) === headSha);
 }
-function fetchJobs(runId, repo, cache) {
+function fetchJobs(runId, repo, cache, stateKey) {
     const cached = cache.get(runId);
     if (cached)
         return cached;
-    const promise = fetchJobsUncached(runId, repo);
+    const promise = fetchJobsUncached(runId, repo, stateKey);
     cache.set(runId, promise);
     return promise;
 }
-async function fetchJobsUncached(runId, repo) {
+async function fetchJobsUncached(runId, repo, stateKey) {
     const { owner, name } = repo;
     const perPage = 100;
     const MAX_JOB_PAGES = 20; // 2000 jobs max
@@ -95,7 +106,9 @@ async function fetchJobsUncached(runId, repo) {
                 process.stderr.write(`pr-shepherd: job pagination cap (${MAX_JOB_PAGES * 100} jobs) reached for run ${runId} — triage may be incomplete\n`);
                 break;
             }
-            const { data, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`);
+            const { data, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`, undefined, stateKey
+                ? { conditional: { key: stateKey, name: `jobs-run-${runId}-p${page}` } }
+                : undefined);
             allJobs.push(...data.jobs);
             if (rateLimit?.remaining === 0) {
                 process.stderr.write(`pr-shepherd: REST rate limit remaining is 0 while listing jobs for run ${runId} — triage may be incomplete\n`);
@@ -127,12 +140,28 @@ function pickJobInfo(jobs, checkName) {
         workflowName: job.workflow_name,
         jobName: job.name,
         failedStep,
+        jobConclusion: job.conclusion,
     };
 }
-async function fetchJobLogExcerpt(jobId, repo) {
+/**
+ * `cacheable` gates the cross-tick cache — only set once the matched job has
+ * a terminal conclusion, so an in-progress job's (possibly partial) log
+ * never gets frozen into the cache.
+ */
+async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false) {
+    const cacheName = `joblog-${jobId}`;
+    if (stateKey && cacheable) {
+        const cached = await loadDerived(stateKey, cacheName);
+        if (cached)
+            return cached.value ?? undefined;
+    }
     const { owner, name } = repo;
     try {
-        return buildLogExcerpt(await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`));
+        const excerpt = buildLogExcerpt(await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`));
+        if (stateKey && cacheable) {
+            await storeDerived(stateKey, cacheName, excerpt ?? null);
+        }
+        return excerpt;
     }
     catch {
         return undefined;

package/bin/cli/api-usage-formatter.d.mts

@@ -0,0 +1,3 @@
+import type { ApiUsage, GraphqlQuotaWarning } from "../types.mts";
+export declare function formatQuotaWarning(warning: GraphqlQuotaWarning | undefined): string | null;
+export declare function formatApiUsage(usage: ApiUsage | undefined): string | null;

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

@@ -0,0 +1,36 @@
+function resetTime(resetAt) {
+    return new Date(resetAt * 1000).toISOString();
+}
+function formatResource(resource) {
+    const used = resource.used === undefined ? "" : ` · used ${resource.used}`;
+    return `- \`${resource.resource}\`: ${resource.remaining}/${resource.limit} remaining${used} · ${resource.requestCount} requests · resets ${resetTime(resource.resetAt)}`;
+}
+export function formatQuotaWarning(warning) {
+    if (warning === undefined)
+        return null;
+    const used = warning.used === undefined ? "" : ` · used ${warning.used}`;
+    return [
+        "## GitHub API quota warning",
+        "",
+        `- Resource: \`${warning.resource}\``,
+        `- Remaining: ${warning.remaining}/${warning.limit}${used}`,
+        `- Crossed threshold: ${warning.thresholdPercent}% remaining`,
+        `- Reset: ${resetTime(warning.resetAt)}`,
+        `- Recommended poll interval: ${warning.pollIntervalMinutes} minutes`,
+        `- Recommended bounded CLI timeout: ${warning.pollTimeoutMinutes} minutes`,
+        "- Recommendation: prefer non-GraphQL `gh` CLI commands for PR operations until the reset above, then resume pr-shepherd",
+    ].join("\n");
+}
+export function formatApiUsage(usage) {
+    if (usage === undefined)
+        return null;
+    const lines = ["## GitHub API usage", ""];
+    lines.push(`- Credential source: ${usage.credentialSources.map((source) => `\`${source}\``).join(", ")}`);
+    if (usage.graphql !== undefined) {
+        lines.push(formatResource(usage.graphql));
+        lines.push(`- GraphQL measured cost: ${usage.graphql.measuredQueryCost} · unmeasured requests: ${usage.graphql.unmeasuredRequestCount} · nodes: ${usage.graphql.nodeCount}`);
+    }
+    for (const resource of usage.rest ?? [])
+        lines.push(formatResource(resource));
+    return lines.join("\n");
+}

package/bin/cli/error-format.d.mts

@@ -0,0 +1,13 @@
+/** Safe GitHub transport metadata suitable for user-facing structured error output. */
+export declare function serializeGitHubRequestErrorDetails(err: unknown): {
+    rateLimit?: {
+        resource: string;
+        limit: number;
+        remaining: number;
+        used?: number | undefined;
+        resetAt: number;
+    } | undefined;
+    retryAfterSeconds?: number | undefined;
+    credential?: string | undefined;
+} | undefined;
+export declare function formatCliError(err: unknown): string;

package/bin/cli/error-format.mjs

@@ -0,0 +1,41 @@
+import { GitHubRequestError } from "../github/errors.mjs";
+/** Safe GitHub transport metadata suitable for user-facing structured error output. */
+export function serializeGitHubRequestErrorDetails(err) {
+    if (!(err instanceof GitHubRequestError))
+        return undefined;
+    return {
+        ...(err.rateLimit !== undefined && {
+            rateLimit: {
+                resource: err.rateLimit.resource ?? "unknown",
+                limit: err.rateLimit.limit,
+                remaining: err.rateLimit.remaining,
+                ...(err.rateLimit.used !== undefined && { used: err.rateLimit.used }),
+                resetAt: err.rateLimit.resetAt,
+            },
+        }),
+        ...(err.retryAfterSeconds !== undefined && { retryAfterSeconds: err.retryAfterSeconds }),
+        ...(err.authSource !== undefined && { credential: err.authSource }),
+    };
+}
+export function formatCliError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const githubDetails = serializeGitHubRequestErrorDetails(err);
+    if (githubDetails === undefined)
+        return message;
+    const details = [];
+    if (githubDetails.rateLimit !== undefined) {
+        details.push(`resource ${githubDetails.rateLimit.resource}`);
+        details.push(`remaining ${githubDetails.rateLimit.remaining}/${githubDetails.rateLimit.limit}`);
+        if (githubDetails.rateLimit.used !== undefined) {
+            details.push(`used ${githubDetails.rateLimit.used}`);
+        }
+        details.push(`reset ${new Date(githubDetails.rateLimit.resetAt * 1000).toISOString()}`);
+    }
+    if (githubDetails.retryAfterSeconds !== undefined) {
+        details.push(`retry after ${githubDetails.retryAfterSeconds}s`);
+    }
+    if (githubDetails.credential !== undefined) {
+        details.push(`credential ${githubDetails.credential}`);
+    }
+    return details.length === 0 ? message : `${message} (${details.join("; ")})`;
+}

package/bin/cli/fix-formatter.mjs

@@ -44,6 +44,10 @@ export function formatFixCodeResult(header, result) {
     const failingChecks = result.fix.checks.filter((ch) => isFailingAgentCheck(ch));
     if (failingChecks.length > 0) {
         sections.push("## Failing checks");
+        // Multiple failing CheckRuns (matrix jobs, etc.) can share one runId; the rerun command is
+        // identical for all of them, so print it once — after the first bullet for that runId —
+        // instead of repeating the same shell command on every row.
+        const seenRerunRunIds = new Set();
         const bullets = failingChecks.map((ch) => {
             const workflowPrefix = ch.workflowName ? `${ch.workflowName} › ` : "";
             const jobLabel = ch.jobName ? ch.jobName : ch.name;
@@ -56,7 +60,10 @@ export function formatFixCodeResult(header, result) {
             const scopeTag = ch.scope
                 ? ` [scope: ${ch.scope}${ch.commitOid ? `, commit: ${ch.commitOid}` : ""}]`
                 : "";
-            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${scopeTag}`];
+            const rerunTag = ch.rerunCommand ? " [rerun authorized]" : "";
+            const lines = [
+                `- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${scopeTag}${rerunTag}`,
+            ];
             if (ch.conclusion !== "CANCELLED") {
                 if (ch.failedStep)
                     lines.push(`  > ${ch.failedStep}`);
@@ -65,6 +72,10 @@ export function formatFixCodeResult(header, result) {
                 if (ch.logExcerpt)
                     lines.push(indentBlockquote(ch.logExcerpt, "  "));
             }
+            if (ch.rerunCommand && ch.runId && !seenRerunRunIds.has(ch.runId)) {
+                seenRerunRunIds.add(ch.runId);
+                lines.push(`  rerun: \`${ch.rerunCommand}\``);
+            }
             return lines.join("\n");
         });
         sections.push(bullets.join("\n\n"));

package/bin/cli/iterate-activity-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { IterateResult } from "../types.mts";
+export declare function formatActivityLine(result: IterateResult): string | null;

package/bin/cli/iterate-activity-formatter.mjs

@@ -0,0 +1,26 @@
+export function formatActivityLine(result) {
+    const activity = result.activity ?? {
+        commitCount: 0,
+        reviewRoundCount: 0,
+        latestCommitCommittedAtUnix: null,
+        reviewItemsSinceLatestCommit: [],
+    };
+    const hasActiveChecks = (result.inProgressChecks?.length ?? 0) > 0;
+    if (activity.commitCount === 0 &&
+        activity.reviewRoundCount === 0 &&
+        activity.reviewItemsSinceLatestCommit.length === 0 &&
+        !hasActiveChecks) {
+        return null;
+    }
+    const parts = [`${activity.commitCount} commits`, `${activity.reviewRoundCount} review rounds`];
+    if (activity.reviewItemsSinceLatestCommit.length > 0) {
+        parts.push(`${activity.reviewItemsSinceLatestCommit.length} review items since latest commit`);
+    }
+    if (hasActiveChecks) {
+        parts.push(`active: ${result
+            .inProgressChecks.slice(0, 5)
+            .map((check) => `\`${check.name}\``)
+            .join(", ")}`);
+    }
+    return `**activity** ${parts.join(" · ")}`;
+}

package/bin/cli/iterate-formatter.mjs

@@ -3,32 +3,8 @@ import { joinSections } from "../util/markdown.mjs";
 import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, } from "./iterate-instructions.mjs";
 import { formatMergeRequirementLines } from "../merge-status/requirements-format.mjs";
 import { appendMergeQueueHeader, formatMergeAction } from "./iterate-merge-formatter.mjs";
-function formatActivityLine(result) {
-    const activity = result.activity ?? {
-        commitCount: 0,
-        reviewRoundCount: 0,
-        latestCommitCommittedAtUnix: null,
-        reviewItemsSinceLatestCommit: [],
-    };
-    const hasActiveChecks = (result.inProgressChecks?.length ?? 0) > 0;
-    if (activity.commitCount === 0 &&
-        activity.reviewRoundCount === 0 &&
-        activity.reviewItemsSinceLatestCommit.length === 0 &&
-        !hasActiveChecks) {
-        return null;
-    }
-    const parts = [`${activity.commitCount} commits`, `${activity.reviewRoundCount} review rounds`];
-    if (activity.reviewItemsSinceLatestCommit.length > 0) {
-        parts.push(`${activity.reviewItemsSinceLatestCommit.length} review items since latest commit`);
-    }
-    if (hasActiveChecks) {
-        parts.push(`active: ${result
-            .inProgressChecks.slice(0, 5)
-            .map((c) => `\`${c.name}\``)
-            .join(", ")}`);
-    }
-    return `**activity** ${parts.join(" · ")}`;
-}
+import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
+import { formatActivityLine } from "./iterate-activity-formatter.mjs";
 /**
  * Format an IterateResult as human-readable Markdown.
  *
@@ -132,21 +108,26 @@ export function formatIterateResult(result, opts) {
     if (activityLine)
         headerLines.push(activityLine);
     const header = headerLines.join("\n");
+    const quotaWarning = formatQuotaWarning(result.quotaWarning);
+    const apiUsage = verbose ? formatApiUsage(result.apiUsage) : null;
+    const telemetrySections = [quotaWarning, apiUsage];
     switch (result.action) {
         case "wait":
             return joinSections([
                 header,
+                ...telemetrySections,
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
+                ...telemetrySections,
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
         case "merge":
-            return formatMergeAction(header, result);
+            return formatMergeAction(joinSections([header, ...telemetrySections]), result);
         case "cancel": {
             const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
             if (result.mergeRequirements) {
@@ -167,6 +148,7 @@ export function formatIterateResult(result, opts) {
                 cancelHeaderLines.push(activityLine);
             return joinSections([
                 cancelHeaderLines.join("\n"),
+                ...(apiUsage ? [apiUsage] : []),
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
@@ -174,10 +156,11 @@ export function formatIterateResult(result, opts) {
         case "escalate":
             return joinSections([
                 header,
+                ...(apiUsage ? [apiUsage] : []),
                 result.escalate.humanMessage,
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
         case "fix_code":
-            return formatFixCodeResult(header, result);
+            return formatFixCodeResult(joinSections([header, ...telemetrySections]), result);
     }
 }

package/bin/cli/iterate-instructions.mjs

@@ -1,12 +1,23 @@
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 import { inlineCode } from "../util/markdown.mjs";
+import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
+            if (result.quotaWarning) {
+                return [
+                    buildQuotaAwareContinuation(result.quotaWarning, "Non-terminal — no action needed this tick."),
+                ];
+            }
             return [
                 "Non-terminal — no action needed this tick. Iterate again with the same options to continue.",
             ];
         case "mark_ready":
+            if (result.quotaWarning) {
+                return [
+                    buildQuotaAwareContinuation(result.quotaWarning, "The CLI marked the PR ready for review."),
+                ];
+            }
             return [
                 "The CLI marked the PR ready for review. Iterate again with the same options to continue.",
             ];
@@ -20,7 +31,9 @@ export function buildSimpleIterateInstructions(result) {
             else if (result.merge.fallbackCommand) {
                 instructions.push(`Only if GitHub reports that auto-merge is unavailable, run the \`plain merge fallback\` command: ${inlineCode(renderMergeCommand(result.merge.fallbackCommand))}.`);
             }
-            instructions.push("Then iterate again with the same options to monitor until the PR merges or needs work.");
+            instructions.push(result.quotaWarning
+                ? buildQuotaAwareContinuation(result.quotaWarning, "After running the merge command.")
+                : "Then iterate again with the same options to monitor until the PR merges or needs work.");
             return instructions;
         }
         case "cancel":

package/bin/cli/iterate-lean.mjs

@@ -64,6 +64,7 @@ export function projectIterateLean(result, opts) {
         ...((result.supersededNames?.length ?? 0) > 0 && {
             supersededNames: result.supersededNames,
         }),
+        ...(result.quotaWarning && { quotaWarning: result.quotaWarning }),
     };
     switch (result.action) {
         case "wait":

package/bin/cli/mutate-formatter.mjs

@@ -6,12 +6,14 @@ function formatRateLimit(result) {
     const rateLimit = result.rateLimit;
     if (rateLimit) {
         const details = [
+            typeof rateLimit.resource === "string" ? `resource ${rateLimit.resource}` : null,
             typeof rateLimit.retryAfterSeconds === "number"
                 ? `retry after ${rateLimit.retryAfterSeconds}s`
                 : null,
             typeof rateLimit.remaining === "number" && typeof rateLimit.limit === "number"
                 ? `remaining ${rateLimit.remaining}/${rateLimit.limit}`
                 : null,
+            typeof rateLimit.used === "number" ? `used ${rateLimit.used}` : null,
             typeof rateLimit.resetAt === "number"
                 ? `reset at ${new Date(rateLimit.resetAt * 1000).toISOString()}`
                 : null,

package/bin/commands/check-annotations.d.mts

@@ -1,3 +1,4 @@
+import { type AnnotationCacheOptions } from "../github/check-annotations.mts";
 import type { CheckAnnotation, ClassifiedCheck, ShepherdReport, TriagedCheck } from "../types.mts";
 export declare function checksWithActionableAnnotations(report: ShepherdReport): TriagedCheck[];
 export declare function attachAndMergeCheckAnnotations(buckets: {
@@ -8,7 +9,7 @@ export declare function attachAndMergeCheckAnnotations(buckets: {
     ignored: ClassifiedCheck[];
 }, seenMap: Map<string, {
     seenAt: number;
-}>, prNumber: number): Promise<{
+}>, prNumber: number, cacheOpts?: AnnotationCacheOptions): Promise<{
     passing: ClassifiedCheck[];
     failing: TriagedCheck[];
     skipped: ClassifiedCheck[];

package/bin/commands/check-annotations.mjs

@@ -1,4 +1,4 @@
-import { fetchCheckRunAnnotations } from "../github/check-annotations.mjs";
+import { fetchCheckRunAnnotations, } from "../github/check-annotations.mjs";
 function shouldFetchCheckAnnotations(check) {
     return check.id != null && check.status === "COMPLETED" && check.hasAnnotations === true;
 }
@@ -11,7 +11,7 @@ export function checksWithActionableAnnotations(report) {
         ...(report.checks.ignored ?? []),
     ].filter((c) => c.conclusion !== "SUCCESS" && (c.annotations?.length ?? 0) > 0);
 }
-export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber) {
+export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber, cacheOpts) {
     const candidates = [
         ...buckets.failing,
         ...buckets.passing,
@@ -19,7 +19,7 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber)
         ...buckets.filtered,
         ...buckets.ignored,
     ].filter(shouldFetchCheckAnnotations);
-    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber);
+    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts);
     const byId = new Map(annotated.flatMap((c) => (c.id != null ? [[c.id, c]] : [])));
     const apply = (list) => list.map((c) => {
         if (c.id == null)
@@ -35,20 +35,20 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber)
         ignored: apply(buckets.ignored),
     };
 }
-async function attachUnseenCheckAnnotations(checks, seenMap, prNumber) {
+async function attachUnseenCheckAnnotations(checks, seenMap, prNumber, cacheOpts) {
     const checksWithAnnotations = [];
     for (const check of checks) {
         // eslint-disable-next-line no-await-in-loop
-        checksWithAnnotations.push(await attachForCheck(check, seenMap, prNumber));
+        checksWithAnnotations.push(await attachForCheck(check, seenMap, prNumber, cacheOpts));
     }
     return checksWithAnnotations;
 }
-async function attachForCheck(check, seenMap, prNumber) {
+async function attachForCheck(check, seenMap, prNumber, cacheOpts) {
     if (check.id == null)
         return check;
     let annotations;
     try {
-        annotations = await fetchCheckRunAnnotations(check.id);
+        annotations = await fetchCheckRunAnnotations(check.id, cacheOpts);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);