pr-shepherd 0.55.2 → 0.56.0

package/bin/commands/check-fingerprint.mjs

@@ -31,20 +31,26 @@ export async function tryReuseFingerprintReport(prNumber, repo, stateKey, config
     }
     if (!reportAllowsFingerprintSkip(cached.report))
         return null;
-    const live = await fetchPrFingerprint(prNumber, repo);
-    if (live.isInMergeQueue || cached.fingerprint.isInMergeQueue)
+    if (cached.fingerprint.isInMergeQueue)
+        return null;
+    if (!cached.fingerprint.checkSuitesComplete)
+        return null;
+    if (cached.fingerprint.commentCount > 100)
         return null;
-    if (!live.checkSuitesComplete || !cached.fingerprint.checkSuitesComplete)
+    if (cached.fingerprint.reviewCount > 100)
         return null;
-    if (live.commentCount > 100 || cached.fingerprint.commentCount > 100)
+    if (cached.fingerprint.threadCount > 20)
         return null;
-    if (live.reviewCount > 100 || cached.fingerprint.reviewCount > 100)
+    if (cached.fingerprint.hasMultiCommentThreads)
         return null;
-    if (live.threadCount > 20 || cached.fingerprint.threadCount > 20)
+    if (!cached.fingerprint.rulesComplete)
+        return null;
+    const live = await fetchPrFingerprint(prNumber, repo);
+    if (live.isInMergeQueue || !live.checkSuitesComplete)
         return null;
-    if (live.hasMultiCommentThreads || cached.fingerprint.hasMultiCommentThreads)
+    if (live.commentCount > 100 || live.reviewCount > 100 || live.threadCount > 20)
         return null;
-    if (!live.rulesComplete || !cached.fingerprint.rulesComplete)
+    if (live.hasMultiCommentThreads || !live.rulesComplete)
         return null;
     if (!fingerprintsEqual(cached.fingerprint, live))
         return null;

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

@@ -1,6 +1,7 @@
 import { type WorkflowSuiteSnapshot } from "../checks/unreported-required.mts";
 import type { BatchPrData, CheckRun, ShepherdReport } from "../types.mts";
 import type { RepoInfo } from "../github/client.mts";
+import type { CheckExecutionContext } from "./check-execution-context.mts";
 export interface UnreportedRequiredFields {
     unreportedRequiredChecks?: string[];
     trunkBehindBy?: number;
@@ -20,9 +21,9 @@ export declare function collectUnreportedRequired(input: {
     name: string;
     pr: number;
     relevantEvents: readonly string[];
-}): Promise<UnreportedRequiredFields>;
+}, context?: CheckExecutionContext): Promise<UnreportedRequiredFields>;
 /**
  * A fingerprint hit can keep a stale trunk `behindBy`. Refresh the trunk compare
  * and the required-context diff without refetching the whole batch.
  */
-export declare function refreshCachedUnreported(report: ShepherdReport, repo: RepoInfo): Promise<ShepherdReport>;
+export declare function refreshCachedUnreported(report: ShepherdReport, repo: RepoInfo, context?: CheckExecutionContext): Promise<ShepherdReport>;

package/bin/commands/check-unreported.mjs

@@ -1,7 +1,7 @@
 import { actionsWorkflowInProgress, reportedCheckNames, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
 import { loadBaseBehindBy, loadMergeTargetStatus } from "../github/merge-target-rules.mjs";
 /** Load trunk rules for a stack and diff them against the head's check names. */
-export async function collectUnreportedRequired(input) {
+export async function collectUnreportedRequired(input, context) {
     const localContexts = input.batchData.branchRules?.requiredStatusCheckContexts ??
         input.batchData.branchProtection?.requiredStatusCheckContexts ??
         [];
@@ -13,7 +13,7 @@ export async function collectUnreportedRequired(input) {
         headRefName: input.batchData.headRefName,
         localContexts,
         stack: input.batchData.stack,
-    });
+    }, context);
     const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(input.checks));
     const actionsRunning = actionsWorkflowInProgress(input.suites, new Set(input.relevantEvents));
     const baseBehindBy = unreported.length > 0 && !input.batchData.stack
@@ -34,7 +34,7 @@ export async function collectUnreportedRequired(input) {
  * A fingerprint hit can keep a stale trunk `behindBy`. Refresh the trunk compare
  * and the required-context diff without refetching the whole batch.
  */
-export async function refreshCachedUnreported(report, repo) {
+export async function refreshCachedUnreported(report, repo, context) {
     const stack = report.mergeStatus?.mergeRequirements?.stack;
     if (!report.headRefName)
         return report;
@@ -48,7 +48,7 @@ export async function refreshCachedUnreported(report, repo) {
         headRefName: report.headRefName,
         localContexts: report.mergeStatus.mergeRequirements?.requiredStatusChecks?.contexts ?? [],
         stack,
-    });
+    }, context);
     const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(reportChecks(report)));
     const next = { ...report };
     if (unreported.length > 0)

package/bin/commands/check.d.mts

@@ -1,3 +1,4 @@
+import type { CheckExecutionContext } from "./check-execution-context.mts";
 import type { GlobalOptions, ShepherdReport } from "../types.mts";
 export declare function runCheck(opts: GlobalOptions & {
     autoResolve?: boolean;
@@ -6,4 +7,4 @@ export declare function runCheck(opts: GlobalOptions & {
     persistSeen?: boolean;
     fingerprintCache?: boolean;
     merge?: boolean;
-}): Promise<ShepherdReport>;
+}, context?: CheckExecutionContext): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -7,6 +7,7 @@ import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { fetchStartupFailureChecks, triageFailingChecks } from "../checks/triage.mjs";
+import { TriageBudget } from "../checks/triage-budget.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
@@ -26,7 +27,7 @@ import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
-export async function runCheck(opts) {
+export async function runCheck(opts, context) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
@@ -38,10 +39,15 @@ export async function runCheck(opts) {
     if (reuseFingerprint) {
         const cached = await tryReuseFingerprintReport(prNumber, repo, stateKey, config);
         if (cached)
-            return refreshCachedUnreported(cached, repo);
+            return refreshCachedUnreported(cached, repo, context);
     }
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
-    const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
+    const includeReceiptSummary = (await context?.wantsReceiptSummary(prNumber, repo)) ?? false;
+    const result = await fetchPrBatch(prNumber, repo, {
+        paginateApprovedReviews,
+        ...(includeReceiptSummary && { includeReceiptSummary: true }),
+    });
+    context?.setReceiptSummary(result.receiptSummary ?? null);
     let batchData = result.data;
     const unknownRefresh = await refreshUnknownMergeability(prNumber, repo, batchData);
     batchData = unknownRefresh.batchData;
@@ -55,9 +61,10 @@ export async function runCheck(opts) {
         return terminal;
     }
     const startupFailuresNeedAttempt = batchData.checks.some((check) => check.source === "startup_failure" && check.runAttempt === undefined);
+    const triageBudget = new TriageBudget();
     const startupFailureChecks = result.checkSuitesComplete && !startupFailuresNeedAttempt
         ? []
-        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber, stateKey);
+        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber, stateKey, triageBudget);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedPrChecks = classifyChecks(allChecks);
     const latestRemoval = batchData.latestMergeQueueRemoval;
@@ -103,8 +110,10 @@ export async function runCheck(opts) {
     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, stateKey)
+        ? await triageFailingChecks(failing, repo, stateKey, triageBudget, classifiedChecks.filter((c) => c.category !== "failing"))
         : failing;
+    triageBudget.throwIfSecondary();
+    triageBudget.reportOmissionIfNeeded();
     const seenMap = await loadSeenMap(stateKey);
     const botUsernames = normalizeBotUsernames(config.botUsernames);
     const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
@@ -168,7 +177,7 @@ export async function runCheck(opts) {
         name: repo.name,
         pr: prNumber,
         relevantEvents: config.checks.ciTriggerEvents,
-    });
+    }, context);
     let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount, unreported.hasUnreportedRequired);
     // Resolve any pending mergeability refresh (and the resulting MERGED/CLOSED short-circuit)
     // before deciding what to persist below — deferWhileQueued must see the same final,
@@ -251,6 +260,12 @@ export async function runCheck(opts) {
         ruleAutoResolveCommentIds: partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize === true),
         ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
     };
+    if (opts.autoMinimizeSuppressed === true &&
+        (authorizedPartition.ruleAutoResolveThreadIds.length > 0 ||
+            authorizedPartition.ruleAutoResolveCommentIds.length > 0 ||
+            authorizedPartition.ruleAutoResolveReviewSummaryIds.length > 0)) {
+        context?.invalidateReceiptSummary();
+    }
     const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, autoResolved, autoMinimized, autoResolveErrors, errorReasons, } = await applySuppressedRuleAutoResolve({
         enabled: opts.autoMinimizeSuppressed === true,
         partition: authorizedPartition,

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

@@ -2,15 +2,18 @@ import type { AgentCheck, ResolveCommand, Review } from "../../types.mts";
 /** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
 export declare function buildCrStaleClause(reviews: Review[]): string;
 /**
- * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
- * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
+ * base and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
  * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
  * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or
  * discarding the rest of the user's config.
  */
-export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, isBehind: boolean): string[];
+export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, branch: {
+    isBehind: boolean;
+    hasConflicts: boolean;
+}): string[];
 /**
  * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.
  * The fetched PR base branch is raw context; the caller still owns repository-specific git

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

@@ -8,19 +8,20 @@ export function buildCrStaleClause(reviews) {
     return human;
 }
 /**
- * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
- * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
+ * base and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
  * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
  * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or
  * discarding the rest of the user's config.
  */
-export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
+export function buildBehindBaseHintInstruction(baseBranch, hint, branch) {
     const trimmedHint = typeof hint === "string" ? hint.trim() : "";
-    if (!isBehind || trimmedHint === "")
+    if ((!branch.isBehind && !branch.hasConflicts) || trimmedHint === "")
         return [];
-    return [`The branch is behind PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
+    const state = branch.hasConflicts ? "conflicts with" : "is behind";
+    return [`The branch ${state} PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
 /**
  * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.

package/bin/commands/iterate/escalate.mjs

@@ -1,3 +1,5 @@
+/* eslint-disable max-lines */
+import { renderRelatedJobLines } from "../../cli/related-jobs-format.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { renderResolveCommand } from "./render.mjs";
 function renderEscalateAuthor(item) {
@@ -52,6 +54,7 @@ function renderEscalateCheck(check) {
         lines.push(`  > ${check.summary}`);
     if (check.logExcerpt)
         lines.push(...renderBlockquoteLines(check.logExcerpt, "  "));
+    lines.push(...renderRelatedJobLines(check.relatedJobs));
     if (check.rerunCommand)
         lines.push(`  rerun: \`${check.rerunCommand}\``);
     for (const annotation of check.annotations ?? []) {

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

@@ -19,6 +19,10 @@ import { canRerunWorkflows } from "../../checks/conclusions.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 const EMPTY_RELEASED = new Set();
+function hasLogEvidence(check) {
+    return (Boolean(check.logExcerpt?.trim()) ||
+        (check.relatedJobs ?? []).some((job) => Boolean(job.logExcerpt?.trim())));
+}
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
@@ -30,13 +34,13 @@ function checkRequiresHumanFollowUp(check) {
     // identify a code or configuration fix for the agent. Only a later failure with
     // no actionable evidence needs a human handoff.
     if (check.runAttempt !== undefined && check.runAttempt > 1)
-        return !check.logExcerpt?.trim();
+        return !hasLogEvidence(check);
     // An external check's direct URL is actionable evidence: the agent can inspect the
     // provider and/or reproduce the reported failure locally. Only a truly bare check
     // has no autonomous investigation path.
     if (check.runId === null)
         return !check.detailsUrl?.trim();
-    return !check.logExcerpt?.trim();
+    return !hasLogEvidence(check);
 }
 function nextFixAttempts(stored, threads, countAttempt) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};

package/bin/commands/iterate/helpers.mjs

@@ -80,6 +80,7 @@ export function buildRelevantChecks(report) {
                 ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
                 ...(c.summary !== undefined && { summary: c.summary }),
                 ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
+                ...(c.relatedJobs !== undefined && { relatedJobs: c.relatedJobs }),
                 ...(c.annotations !== undefined && { annotations: c.annotations }),
                 ...(c.scope !== undefined && { scope: c.scope }),
                 ...(c.commitOid !== undefined && { commitOid: c.commitOid }),

package/bin/commands/iterate/index.mjs

@@ -27,6 +27,7 @@ import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 import { annotateBlockedWait, resolveCheckBlockerGate } from "./check-blocker-gate.mjs";
 import { buildUnreportedFixResult, planUnreportedRequired } from "./unreported-required.mjs";
+import { createCheckExecutionContext } from "../check-execution-context.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -40,6 +41,7 @@ async function runIterateCore(opts) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const neverCancelRuns = opts.neverCancelRuns ?? config.actions.neverCancelRuns;
+    const checkContext = createCheckExecutionContext(readyDelaySeconds);
     const report = await runCheck({
         ...opts,
         prNumber,
@@ -48,7 +50,7 @@ async function runIterateCore(opts) {
         // compatibility key in the config loader.
         autoResolve: true,
         autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
-    });
+    }, checkContext);
     const [repoOwner, repoName] = report.repo.split("/");
     if (!repoOwner || !repoName) {
         throw new ShepherdError(`Unexpected repo format: "${report.repo}" (expected "owner/name")`, EXIT.DATAERR);
@@ -84,6 +86,7 @@ async function runIterateCore(opts) {
     // the apply command remains a working fallback instead of silently dropping it.
     let reviewSummaryIds = minimizeIds;
     if (selfMinimizeIds.length > 0) {
+        checkContext.invalidateReceiptSummary();
         const { minimized } = await autoMinimizeComments(selfMinimizeIds);
         const minimizedIds = new Set(minimized);
         const unminimized = selfMinimizeIds.filter((id) => !minimizedIds.has(id));
@@ -110,13 +113,13 @@ async function runIterateCore(opts) {
     const staleAncestry = await findStaleNativeStackAncestry(report, {
         owner: repoOwner,
         name: repoName,
-    });
+    }, checkContext);
     const isCleanReadyState = report.status === "READY" &&
         !report.mergeStatus.isDraft &&
         !hasReadinessWork &&
         !activeMerge &&
         staleAncestry === null;
-    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork);
+    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork, checkContext);
     const headSha = report.headSha ?? "unknown";
     // The elapsed marker survives a hidden-comment acknowledgement tick and is
     // consumed only when this tick cancels or merges. A receipt that is still
@@ -233,7 +236,7 @@ async function runIterateCore(opts) {
     if (markReadyResult)
         return markReadyResult;
     if (readyState.shouldCancel && !report.mergeStatus.isDraft) {
-        const receiptWritten = receiptCurrent || (await recordReadyReceipt(receiptKey, report));
+        const receiptWritten = receiptCurrent || (await recordReadyReceipt(receiptKey, report, checkContext));
         // Aggregate --stack routing trusts only a layer's receipt, so an unwritten
         // one keeps the elapsed marker and retries next tick. A one-PR receipt
         // only lets a rerun skip the wait, so its failure never changes the action.
@@ -279,7 +282,7 @@ async function runIterateCore(opts) {
     };
     return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, reportForWork, reviewSummaryIds), blockerGate);
 }
-async function recordReadyReceipt(key, report) {
+async function recordReadyReceipt(key, report, context) {
     if (report.status !== "READY" ||
         report.mergeStatus.state !== "OPEN" ||
         report.mergeStatus.isDraft ||
@@ -287,7 +290,7 @@ async function recordReadyReceipt(key, report) {
         !report.baseRefOid)
         return false;
     try {
-        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const raw = await receiptSummaryForReport(key, report, context);
         if (fingerprintRawSummaryPr(raw) === null ||
             raw.state !== "OPEN" ||
             raw.isDraft ||
@@ -327,7 +330,7 @@ async function recordReadyReceipt(key, report) {
     }
 }
 /** Clear a stale READY receipt; return whether a current receipt remains. */
-async function revalidateReadyReceipt(key, report, hasReadinessWork) {
+async function revalidateReadyReceipt(key, report, hasReadinessWork, context) {
     const receipt = await readReadyReceipt(key);
     if (!receipt)
         return false;
@@ -344,7 +347,7 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork) {
         return false;
     }
     try {
-        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const raw = await receiptSummaryForReport(key, report, context);
         const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
         if (annotationProbeUnavailable(raw)) {
             const sameHead = raw.headRefOid === report.headSha;
@@ -385,3 +388,12 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork) {
         return false;
     }
 }
+/** A mismatched or invalidated same-request hint falls back to the original fresh read. */
+async function receiptSummaryForReport(key, report, context) {
+    const candidate = context?.getReceiptSummary();
+    if (candidate?.number === report.pr &&
+        candidate.headRefOid === report.headSha &&
+        candidate.baseRefOid === report.baseRefOid)
+        return candidate;
+    return fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+}

package/bin/commands/iterate/render.mjs

@@ -38,8 +38,15 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
-    if (hasConflicts && !hasRepeatedWorkflowBranchRecovery) {
-        instructions.push(buildConflictInstruction(stackRebase));
+    // A conflicting native stack layer follows the printed gh-stack route, so it omits the hint.
+    const branchUpdateHint = buildBehindBaseHintInstruction(baseBranch, behindBaseHint, {
+        isBehind,
+        hasConflicts: hasConflicts && !stackRebase,
+    });
+    // The conflict hint belongs with the conflict step; otherwise it precedes the push step.
+    const hintWithConflictStep = hasConflicts && !hasRepeatedWorkflowBranchRecovery;
+    if (hintWithConflictStep) {
+        instructions.push(buildConflictInstruction(stackRebase), ...branchUpdateHint);
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
@@ -77,7 +84,8 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
         const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`Read every body under \`## Changes-requested reviews\` and apply any warranted change.${staleClause}`);
     }
-    instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
+    if (!hintWithConflictStep)
+        instructions.push(...branchUpdateHint);
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts || hasRepeatedWorkflowBranchRecovery) {

package/bin/commands/iterate/stale-ancestry.d.mts

@@ -1,6 +1,7 @@
 import type { RepoInfo } from "../../github/client.mts";
 import type { PollSummaryStackAncestry } from "../../types.mts";
 import type { ShepherdReport } from "../../types/report.mts";
+import type { CheckExecutionContext } from "../check-execution-context.mts";
 /**
  * A verified stale boundary for the PR being shepherded.
  *
@@ -19,4 +20,4 @@ export interface StaleNativeStackAncestry extends PollSummaryStackAncestry {
  * could not be verified. Callers must not emit a repair command from an
  * unverified snapshot.
  */
-export declare function findStaleNativeStackAncestry(report: Pick<ShepherdReport, "pr" | "mergeStatus">, repo: RepoInfo): Promise<StaleNativeStackAncestry | null>;
+export declare function findStaleNativeStackAncestry(report: Pick<ShepherdReport, "pr" | "mergeStatus">, repo: RepoInfo, context?: CheckExecutionContext): Promise<StaleNativeStackAncestry | null>;

package/bin/commands/iterate/stale-ancestry.mjs

@@ -8,12 +8,13 @@ import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
  * could not be verified. Callers must not emit a repair command from an
  * unverified snapshot.
  */
-export async function findStaleNativeStackAncestry(report, repo) {
+export async function findStaleNativeStackAncestry(report, repo, context) {
     const stack = report.mergeStatus.mergeRequirements?.stack;
     if (!stack || stack.position <= 1)
         return null;
     try {
-        const topology = await readStackTopology(report.pr, repo);
+        const topology = await (context?.readStackTopology(report.pr, repo) ??
+            readStackTopology(report.pr, repo));
         const ancestry = stackAncestryGaps(topology.ordered).find((gap) => gap.childPr === report.pr);
         if (!ancestry)
             return null;

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

@@ -1,4 +1,5 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
+import { type RateLimitKind } from "../github/rate-limit-kind.mts";
 import type { ApiResourceUsage, GraphqlApiUsage, PollSummaryResult } from "../types.mts";
 /** Slow the poll for whichever of GraphQL or REST core is in a tighter band. */
 export declare function quotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: {
@@ -8,6 +9,7 @@ export declare function quotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], us
 export interface RateLimitRetry {
     ms: number;
     resource: string;
+    kind: RateLimitKind;
     remaining?: number;
     limit?: number;
     resetAt?: number;

package/bin/commands/poll-quota.mjs

@@ -1,6 +1,6 @@
 import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { GitHubRequestError } from "../github/errors.mjs";
-import { isRateLimitMessage } from "../comments/rate-limit.mjs";
+import { rateLimitKind } from "../github/rate-limit-kind.mjs";
 import { exhaustedPrimaryLimitDelayMs } from "./poll-rate-limit-delay.mjs";
 import { selectQuotaWarning } from "./quota-selection.mjs";
 const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
@@ -28,36 +28,29 @@ export function quotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
 export function pollRateLimitRetryAfterMs(err) {
     if (!(err instanceof GitHubRequestError))
         return null;
-    const rateLimitMessage = isRateLimitMessage(err.message) ||
-        (err.graphqlErrors?.some((error) => isRateLimitMessage(error.message)) ?? false);
-    const exhausted = err.rateLimit !== undefined && err.rateLimit.remaining <= 0;
-    const retryable = err.status === 429 || err.retryAfterSeconds !== undefined || rateLimitMessage || exhausted;
-    if (!retryable)
+    const kind = rateLimitKind(err);
+    if (kind === null)
         return null;
-    const resource = retryResource(err);
+    const resource = kind === "secondary" ? "secondary" : (err.rateLimit?.resource ?? "graphql");
     const rateLimit = err.rateLimit;
     const details = {
+        kind,
         resource,
-        ...(rateLimit?.remaining !== undefined && { remaining: rateLimit.remaining }),
-        ...(rateLimit?.limit !== undefined && { limit: rateLimit.limit }),
-        ...(rateLimit?.resetAt !== undefined && { resetAt: rateLimit.resetAt }),
+        ...(kind === "primary" &&
+            rateLimit?.remaining !== undefined && { remaining: rateLimit.remaining }),
+        ...(kind === "primary" && rateLimit?.limit !== undefined && { limit: rateLimit.limit }),
+        ...(kind === "primary" && rateLimit?.resetAt !== undefined && { resetAt: rateLimit.resetAt }),
     };
-    if (err.retryAfterSeconds !== undefined) {
-        return { ...details, ms: Math.max(err.retryAfterSeconds, 0) * 1000 };
+    if (kind === "primary" && rateLimit !== undefined) {
+        return {
+            ...details,
+            ms: Math.max(exhaustedPrimaryLimitDelayMs(rateLimit.resetAt, Date.now()), Math.max(err.retryAfterSeconds ?? 0, 0) * 1000),
+        };
     }
-    if (exhausted && rateLimit !== undefined) {
-        return { ...details, ms: exhaustedPrimaryLimitDelayMs(rateLimit.resetAt, Date.now()) };
-    }
-    return { ...details, ms: GRAPHQL_RETRY_AFTER_DEFAULT_MS };
-}
-function retryResource(err) {
-    if (err.rateLimit?.resource)
-        return err.rateLimit.resource;
-    const secondary = err.status === 429 ||
-        err.retryAfterSeconds !== undefined ||
-        /secondary/i.test(err.message) ||
-        (err.graphqlErrors?.some((error) => /secondary/i.test(error.message)) ?? false);
-    return secondary ? "secondary" : "graphql";
+    return {
+        ...details,
+        ms: Math.max(GRAPHQL_RETRY_AFTER_DEFAULT_MS, Math.max(err.retryAfterSeconds ?? 0, 0) * 1000),
+    };
 }
 function rateLimitResourceLabel(resource) {
     if (resource === "graphql")

package/bin/commands/poll-rate-limit-wait.mjs

@@ -2,7 +2,8 @@ import { rest } from "../github/rest-http.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { formatRateLimitGiveUpLine, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, } from "./poll-quota.mjs";
 const MAX_NO_PROGRESS_ATTEMPTS = 5;
-const NO_PROGRESS_BACKOFF_MS = [15_000, 30_000, 60_000];
+const PRIMARY_NO_PROGRESS_BACKOFF_MS = [15_000, 30_000, 60_000];
+const SECONDARY_NO_PROGRESS_BACKOFF_MS = [60_000, 120_000, 240_000, 480_000, 960_000];
 const MERGE_STATES = new Set([
     "BEHIND",
     "BLOCKED",
@@ -26,8 +27,10 @@ export function createUntilTerminalRateLimitRetry() {
         },
     };
 }
-function backoffMs(attempt) {
-    return NO_PROGRESS_BACKOFF_MS[Math.min(attempt, NO_PROGRESS_BACKOFF_MS.length) - 1] ?? 60_000;
+function backoffMs(attempt, kind) {
+    const backoff = kind === "secondary" ? SECONDARY_NO_PROGRESS_BACKOFF_MS : PRIMARY_NO_PROGRESS_BACKOFF_MS;
+    const index = kind === "secondary" ? attempt : attempt - 1;
+    return backoff[Math.min(index, backoff.length - 1)] ?? backoff.at(-1);
 }
 async function waitForRateLimit(state, err, opts) {
     const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(err) : null;
@@ -35,14 +38,16 @@ async function waitForRateLimit(state, err, opts) {
         throw err;
     const elapsed = Math.round((Date.now() - opts.startedAt) / 1000);
     const progressed = state.armed &&
+        retry.kind === "primary" &&
         retry.resetAt !== undefined &&
         (state.lastResetAt === undefined || retry.resetAt > state.lastResetAt);
     let sleepMs = retry.ms;
     if (!state.armed || progressed) {
         state.armed = true;
         state.noProgress = 0;
-        if (retry.resetAt !== undefined)
+        if (retry.kind === "primary" && retry.resetAt !== undefined) {
             state.lastResetAt = retry.resetAt;
+        }
     }
     else {
         state.noProgress += 1;
@@ -52,13 +57,13 @@ async function waitForRateLimit(state, err, opts) {
         }
         // Never sleep less than GitHub asked for. A short no-progress backoff must
         // not undercut an explicit Retry-After or the secondary-limit default.
-        sleepMs = Math.max(retry.ms, backoffMs(state.noProgress));
+        sleepMs = Math.max(retry.ms, backoffMs(state.noProgress, retry.kind));
     }
     process.stderr.write(formatRateLimitRetryLine(opts.tickLabel, elapsed, { ...retry, ms: sleepMs }));
-    return sleepRateLimit(sleepMs, opts, retry.resource);
+    return sleepRateLimit(sleepMs, opts, retry.kind, retry.resource);
 }
-async function sleepRateLimit(ms, opts, resource) {
-    const canProbe = resource !== "core" && opts.targets.length > 0;
+async function sleepRateLimit(ms, opts, kind, resource) {
+    const canProbe = kind === "primary" && resource === "graphql" && opts.targets.length > 0;
     if (ms <= opts.intervalMs || opts.intervalMs <= 0) {
         await sleep(ms);
         return undefined;

package/bin/commands/ready-delay.d.mts

@@ -33,4 +33,6 @@ export declare function updateReadyDelay(prNumber: number, isReady: boolean, rea
 }): Promise<ReadyDelayState>;
 /** Delete the ready-delay marker once an elapsed delay has been consumed. */
 export declare function clearReadyDelay(prNumber: number, owner: string, repo: string): Promise<void>;
+/** Read-only hint for including compact receipt evidence in the next full PR snapshot. */
+export declare function readyDelayElapsed(prNumber: number, owner: string, repo: string, readyDelaySeconds: number): Promise<boolean>;
 export {};

package/bin/commands/ready-delay.mjs

@@ -54,6 +54,24 @@ export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, own
 export async function clearReadyDelay(prNumber, owner, repo) {
     await safeUnlink(readySincePath(prNumber, owner, repo));
 }
+/** Read-only hint for including compact receipt evidence in the next full PR snapshot. */
+export async function readyDelayElapsed(prNumber, owner, repo, readyDelaySeconds) {
+    const markerPath = readySincePath(prNumber, owner, repo);
+    let raw;
+    try {
+        raw = await readFile(markerPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const [since, head] = raw.trim().split(" ");
+    const readySince = Number(since);
+    const now = Math.floor(Date.now() / 1000);
+    return Boolean(head &&
+        Number.isSafeInteger(readySince) &&
+        readySince <= now &&
+        now - readySince >= readyDelaySeconds);
+}
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------