pr-shepherd 0.44.1 → 0.46.0

package/bin/cli/iterate-formatter.mjs

@@ -1,34 +1,11 @@
 import { formatFixCodeResult } from "./fix-formatter.mjs";
+import { formatRelevantChecks } from "./iterate-checks-formatter.mjs";
 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.
  *
@@ -50,7 +27,8 @@ export function formatIterateResult(result, opts) {
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
         : "";
-    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\``;
+    const baseBranchSeg = verbose && result.baseBranch ? ` · **baseBranch** \`${result.baseBranch}\`` : "";
+    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\`${baseBranchSeg}`;
     let summaryLine;
     if (verbose) {
         let verboseBranch = "";
@@ -132,21 +110,27 @@ 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 verboseChecks = verbose ? formatRelevantChecks(result.checks) : null;
+    const telemetrySections = [quotaWarning, apiUsage, verboseChecks];
     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 +151,8 @@ export function formatIterateResult(result, opts) {
                 cancelHeaderLines.push(activityLine);
             return joinSections([
                 cancelHeaderLines.join("\n"),
+                ...(apiUsage ? [apiUsage] : []),
+                ...(verboseChecks ? [verboseChecks] : []),
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
@@ -174,10 +160,12 @@ export function formatIterateResult(result, opts) {
         case "escalate":
             return joinSections([
                 header,
+                ...(apiUsage ? [apiUsage] : []),
+                ...(verboseChecks ? [verboseChecks] : []),
                 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":
@@ -157,6 +158,10 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.escalate.changesRequestedReviews,
                     }),
+                    ...(result.escalate.checks &&
+                        result.escalate.checks.length > 0 && {
+                        checks: result.escalate.checks,
+                    }),
                     ...(result.escalate.stalledChecks &&
                         result.escalate.stalledChecks.length > 0 && {
                         stalledChecks: result.escalate.stalledChecks,

package/bin/cli/journal-extract-handler.d.mts

@@ -0,0 +1,2 @@
+/** Extracts a checked Shepherd Journal from a local PR-body file without external I/O. */
+export declare function handleJournalExtract(args: string[]): Promise<void>;

package/bin/cli/journal-extract-handler.mjs

@@ -0,0 +1,48 @@
+import { extractShepherdJournal } from "../journal/index.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { USAGE, maybePrintHelp } from "./help.mjs";
+import { readSafeBodyFile } from "./safe-body-file.mjs";
+/** Extracts a checked Shepherd Journal from a local PR-body file without external I/O. */
+export async function handleJournalExtract(args) {
+    if (maybePrintHelp(args, "journal extract"))
+        return;
+    const bodyFile = parseBodyFile(args);
+    if (bodyFile === null)
+        return;
+    try {
+        const body = await readSafeBodyFile(bodyFile);
+        process.stdout.write(`${JSON.stringify(extractShepherdJournal(body))}\n`);
+    }
+    catch (error) {
+        process.stderr.write(`pr-shepherd: journal extract: ${String(error)}\n`);
+        process.exitCode = error instanceof ShepherdError ? error.exitCode : EXIT.NOINPUT;
+    }
+}
+function parseBodyFile(args) {
+    let bodyFile;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--body-file") {
+            const value = args[++index];
+            if (value === undefined || bodyFile !== undefined) {
+                return printUsage();
+            }
+            bodyFile = value;
+            continue;
+        }
+        if (arg.startsWith("--body-file=")) {
+            const value = arg.slice("--body-file=".length);
+            if (value === "" || bodyFile !== undefined)
+                return printUsage();
+            bodyFile = value;
+            continue;
+        }
+        return printUsage();
+    }
+    return bodyFile ?? printUsage();
+}
+function printUsage() {
+    process.stderr.write(`${USAGE["journal extract"]}\n`);
+    process.exitCode = EXIT.USAGE;
+    return null;
+}

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/cli/safe-body-file.d.mts

@@ -0,0 +1,14 @@
+import { open } from "node:fs/promises";
+type FileHandle = Awaited<ReturnType<typeof open>>;
+export interface SafeBodyFileReaderDependencies {
+    platform: NodeJS.Platform;
+    noFollow: number | undefined;
+    nonBlock: number | undefined;
+    open: (filePath: string, flags: number) => Promise<FileHandle>;
+}
+/**
+ * Reads a regular file after rejecting unsafe final path entries without exposing its contents.
+ * Callers must trust parent directories: O_NOFOLLOW only protects the final path entry.
+ */
+export declare function readSafeBodyFile(filePath: string, dependencies?: SafeBodyFileReaderDependencies): Promise<string>;
+export {};

package/bin/cli/safe-body-file.mjs

@@ -0,0 +1,42 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+const DEFAULT_DEPENDENCIES = {
+    platform: process.platform,
+    noFollow: constants.O_NOFOLLOW,
+    nonBlock: constants.O_NONBLOCK,
+    open,
+};
+/**
+ * Reads a regular file after rejecting unsafe final path entries without exposing its contents.
+ * Callers must trust parent directories: O_NOFOLLOW only protects the final path entry.
+ */
+export async function readSafeBodyFile(filePath, dependencies = DEFAULT_DEPENDENCIES) {
+    const flags = safeOpenFlags(dependencies);
+    if (flags === null)
+        throw noInput();
+    let handle;
+    try {
+        handle = await dependencies.open(filePath, flags);
+        if (!(await handle.stat()).isFile())
+            throw new Error("not a regular file");
+        return await handle.readFile({ encoding: "utf8" });
+    }
+    catch {
+        throw noInput();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function safeOpenFlags(dependencies) {
+    if (dependencies.platform === "win32" ||
+        dependencies.noFollow === undefined ||
+        dependencies.nonBlock === undefined) {
+        return null;
+    }
+    return constants.O_RDONLY | dependencies.noFollow | dependencies.nonBlock;
+}
+function noInput() {
+    return new ShepherdError("body file could not be read safely", EXIT.NOINPUT);
+}

package/bin/cli-parser.mjs

@@ -10,6 +10,7 @@ import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
+import { handleJournalExtract } from "./cli/journal-extract-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { setupLog } from "./log/setup.mjs";
@@ -32,6 +33,12 @@ export async function main(argv) {
         await handleLogFile(args.slice(1));
         return;
     }
+    // Extraction deliberately precedes legacy warnings and logging: it is a local,
+    // GitHub/config/log-free read path for automation that already has a PR body.
+    if (subcommand === "journal" && args[1] === "extract") {
+        await handleJournalExtract(args.slice(2));
+        return;
+    }
     // The public command groups keep admin diagnostics out of the normal
     // command namespace. Keep this before setupLog because log-file reads the
     // log path and must not initialize/tee the log it is reporting.

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);

package/bin/commands/check-status.mjs

@@ -9,15 +9,15 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
         return "FAILING";
     if (verdict.anyInProgress)
         return "IN_PROGRESS";
-    // BLOCKED with no remaining shepherd work — hand off via ready-delay regardless of why GitHub
+    // BLOCKED with no remaining shepherd work — enter ready-delay regardless of why GitHub
     // is BLOCKED (review pending, insufficient approvals, branch-protection rule, etc.).
     // Requires hasChecks so that a PR with zero relevant checks (CI never started, or all
     // filtered/skipped) doesn't prematurely trigger READY before any check has reported.
     // Exception: UNSTABLE with ignored checks — UNSTABLE means only non-required checks are
-    // pending/failing, and if those are all ignored the handoff is safe even with no other checks.
+    // pending/failing, and if those are all ignored the ready state is safe even with no other checks.
     // BLOCKED is excluded from the ignoredNames extension: BLOCKED can mean required checks haven't
-    // started, and handing off prematurely there risks a broken merge attempt.
-    // blockingBotReviewInProgress is still excluded — a bot review is shepherd's problem, not a hand-off.
+    // started, and entering READY prematurely there risks a broken merge attempt.
+    // blockingBotReviewInProgress is still excluded — a bot review is Shepherd work, not a READY state.
     const hasRelevantPassingChecks = verdict.hasChecks || (mergeStatus.status === "UNSTABLE" && verdict.ignoredNames.length > 0);
     if (verdict.allPassed &&
         hasRelevantPassingChecks &&

package/bin/commands/check.mjs

@@ -16,7 +16,8 @@ import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
-import { normalizeBotUsernames } from "../comments/authors.mjs";
+import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
+import { buildThreadMutationRouting } from "./iterate/thread-mutation-routing.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -27,6 +28,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 +42,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,20 +67,31 @@ 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));
     const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
     const deniedRuleAutoResolveThreadIds = new Set(partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve !== true));
-    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id)), seenMap, botUsernames);
+    const visibleThreadCandidates = batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id));
+    const threadMutationRouting = buildThreadMutationRouting(visibleThreadCandidates, botUsernames, partition.ruleAutoResolveThreadIds);
+    const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
+    const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
+    const repeatableThreadIds = new Set(visibleThreadCandidates
+        .filter((thread) => thread.path !== null &&
+        thread.line !== null &&
+        (!replyThreadIds.has(thread.id) || thread.viewerCanReply === true) &&
+        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true))
+        .map((thread) => thread.id));
+    const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -101,7 +114,7 @@ export async function runCheck(opts) {
         else
             seenSummaries.push(r);
     }
-    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
+    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames, batchData.viewerAuthorization?.viewerCanAdminister === true);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     if (opts.persistSeen !== false) {
         const successfulAnnotations = [
@@ -143,12 +156,21 @@ export async function runCheck(opts) {
         ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
     };
     const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(authorizedPartition, opts.autoMinimizeSuppressed);
+    const visibleMutationThreadIds = new Set([...threadVisibility.activeThreads, ...threadVisibility.resolutionOnlyThreads].map((thread) => thread.id));
     const ruleAutoResolveThreadIds = [
         ...authorizedRuleAutoResolveThreadIds,
-        ...deniedRuleAutoResolveThreadIds,
+        ...[...deniedRuleAutoResolveThreadIds].filter((id) => visibleMutationThreadIds.has(id)),
     ];
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
-    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
+    const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
+    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((review) => {
+        if (partition.suppressedChangesRequestedIds.has(review.id))
+            return false;
+        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
+        return (!isBot ||
+            batchData.viewerAuthorization?.viewerCanAdminister === true ||
+            visibleChangesRequestedIds.has(review.id));
+    }).length;
     const approvedReviews = approvedReviewVisibility.visible;
     let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
     if (status === "READY" && !didRefreshMergeability) {

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,35 @@
+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) {
+    return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
+}
+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,");
+        }
+    }
+    return { ...withWarning, fix: { ...withWarning.fix, instructions } };
+}

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

@@ -30,4 +30,4 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): 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[], hasConflicts?: boolean, hasShaGatedReviewMutations?: boolean): string;

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

@@ -44,7 +44,7 @@ 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("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 (resolveCommand.requiresDismissMessage) {
         instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
@@ -58,32 +58,27 @@ 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.");
+        instructions.push("For each `(no runId)` failure, preserve the displayed metadata; Shepherd will escalate when no other autonomous work remains.");
     }
     return instructions;
 }
-export function buildFixCompletionInstruction(checks, requiresRemoteUpdateAuthorization = false, hasShaGatedReviewMutations = false) {
-    if (requiresRemoteUpdateAuthorization) {
-        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) {
-        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.";
-    }
+export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false) {
+    if (hasConflicts)
+        return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate again with the same options.";
     if (hasShaGatedReviewMutations) {
-        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.";
+        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.";
+    }
+    if (checks.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/classify.mjs

@@ -67,7 +67,8 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     const canResolve = new Set(authorizationThreads
         .filter((thread) => thread.viewerCanResolve === true)
         .map((thread) => thread.id));
-    const replyThreadIds = routed.replyThreadIds.filter((id) => canReply.has(id));
+    const pairedResolveIds = new Set(routed.pairedResolveThreadIds);
+    const replyThreadIds = routed.replyThreadIds.filter((id) => canReply.has(id) && (!pairedResolveIds.has(id) || canResolve.has(id)));
     // Viewer-authored human resolves stay paired with an authorized reply. Marker-ended
     // viewer-authored retries and bot/non-human resolves need only resolve authorization.
     const pairedResolveThreadIds = routed.pairedResolveThreadIds.filter((id) => canReply.has(id) && canResolve.has(id));