pr-shepherd 0.56.5 → 0.57.0

package/bin/commands/check.mjs

@@ -2,7 +2,11 @@ import { fetchPrBatch } from "../github/batch.mjs";
 import { headArrivalUnix, queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
 import { readQueueRemovalAcknowledgment, matchesQueueRemovalAcknowledgment, isCiQueueRemovalReason, } from "../state/queue-removal-ack.mjs";
 import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
-import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
+import { storeRestSnapshotReport } from "../state/rest-snapshot-report.mjs";
+import { restSnapshotState, withRestConditionalScope } from "../github/rest-conditional-scope.mjs";
+import { fingerprintReuser, tryReuseRestSnapshotReport } from "./check-fingerprint.mjs";
+import { readWaitDetectors, recordWaitDetectors } from "./check-wait-detectors.mjs";
+import { withTrunkRequiredContexts } from "../merge-status/required-check-requirements.mjs";
 import { collectUnreportedRequired, refreshCachedUnreported } from "./check-unreported.mjs";
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
@@ -16,7 +20,10 @@ import { computeStatus } from "./check-status.mjs";
 import { annotationMarkerBody, attachAndMergeCheckAnnotations, hasCheckDrivenActionableWork, } from "./check-annotations.mjs";
 import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.mjs";
-import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
+import { loadSeenMap, markSeen, classifyItem, mutationWasDenied } from "../state/seen-comments.mjs";
+import { aliasThreadSeenMarkers } from "../github/rest-identities.mjs";
+import { transportReadinessGaps } from "../github/transport-evidence.mjs";
+import { canGenerateGithubMutation } from "../github/mutation-policy.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
@@ -24,10 +31,21 @@ import { applySuppressedRuleAutoResolve } from "./rule-auto-resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./iterate/thread-mutation-routing.mjs";
-import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
+import { loadClassifyRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
+function enforceTransportReadiness(status, data) {
+    if (status !== "READY" || data.transport !== "rest")
+        return status;
+    if (data.reviewThreads.some((thread) => thread.isResolved === undefined ||
+        thread.isOutdated === undefined ||
+        thread.comments === undefined))
+        return "UNKNOWN";
+    if (transportReadinessGaps(data, data.mergeStateStatus).length > 0)
+        return "UNKNOWN";
+    return status;
+}
 export async function runCheck(opts, context) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -35,20 +53,48 @@ export async function runCheck(opts, context) {
         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 };
+    // Named REST reads in this PR's check are conditional (ETag/304) and cached under its state dir.
+    return withRestConditionalScope(stateKey, () => runScopedCheck(opts, context, repo, prNumber, stateKey));
+}
+async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const config = loadConfig();
     const reuseFingerprint = opts.fingerprintCache === true;
-    if (reuseFingerprint) {
-        const cached = await tryReuseFingerprintReport(prNumber, repo, stateKey, config);
-        if (cached)
-            return refreshCachedUnreported(cached, repo, context);
-    }
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const includeReceiptSummary = (await context?.wantsReceiptSummary(prNumber, repo)) ?? false;
-    const result = await fetchPrBatch(prNumber, repo, {
+    // GraphQL transport: conditional REST change detectors can replay an idle report for free.
+    // Changed trunk rules invalidate a cached report; check again without reuse.
+    const refreshReused = async (cached, baseTipOid) => (await refreshCachedUnreported(cached, repo, context, baseTipOid)) ??
+        runScopedCheck({ ...opts, fingerprintCache: false }, context, repo, prNumber, stateKey);
+    const detectors = reuseFingerprint && !includeReceiptSummary
+        ? await readWaitDetectors(prNumber, repo, stateKey, config)
+        : undefined;
+    if (detectors && "reused" in detectors)
+        return refreshReused(detectors.reused, detectors.baseTipOid);
+    const reuse = reuseFingerprint
+        ? await fingerprintReuser(prNumber, repo, stateKey, config)
+        : undefined;
+    const batchOptions = {
         paginateApprovedReviews,
+        terminalShortCircuit: true,
         ...(includeReceiptSummary && { includeReceiptSummary: true }),
-    });
+    };
+    const fetched = reuse
+        ? await fetchPrBatch(prNumber, repo, batchOptions, reuse)
+        : await fetchPrBatch(prNumber, repo, batchOptions);
+    if (fetched.stackEvidence)
+        context?.seedStack(prNumber, repo, fetched.stackEvidence);
+    if ("reused" in fetched) {
+        await recordWaitDetectors(stateKey, config, detectors, undefined);
+        return refreshReused(fetched.reused, fetched.baseTipOid);
+    }
+    const result = fetched;
     context?.setReceiptSummary(result.receiptSummary ?? null);
+    const restSnapshot = result.data.transport === "rest" ? restSnapshotState() : undefined;
+    if (reuseFingerprint) {
+        const reused = await tryReuseRestSnapshotReport(stateKey, config, restSnapshot);
+        if (reused)
+            return refreshReused(reused);
+    }
     let batchData = result.data;
     const unknownRefresh = await refreshUnknownMergeability(prNumber, repo, batchData);
     batchData = unknownRefresh.batchData;
@@ -67,7 +113,18 @@ export async function runCheck(opts, context) {
         ? []
         : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber, stateKey, triageBudget);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
-    const classifiedPrChecks = classifyChecks(allChecks);
+    const unreported = await collectUnreportedRequired({
+        batchData,
+        checks: allChecks,
+        suites: result.headWorkflowSuites ?? [],
+        owner: repo.owner,
+        name: repo.name,
+        pr: prNumber,
+        relevantEvents: config.checks.ciTriggerEvents,
+    }, context);
+    const classifiedPrChecks = classifyChecks(allChecks, {
+        requiredContexts: unreported.requiredContexts,
+    });
     const latestRemoval = batchData.latestMergeQueueRemoval;
     // `timelineItems(last: 1, ...)` returns the single most recent removal regardless of age, so
     // a PR removed from the queue once, long ago, and never re-added keeps returning that same
@@ -114,6 +171,7 @@ export async function runCheck(opts, context) {
     // synthetic queue-commit source.
     const classifiedQueueChecks = classifyChecks(queueRawChecks, {
         additionalRelevantEvents: ["merge_group"],
+        requiredContexts: unreported.requiredContexts,
     });
     const classifiedChecks = [...classifiedPrChecks, ...classifiedQueueChecks];
     const verdict = getCiVerdict(classifiedChecks);
@@ -129,23 +187,32 @@ export async function runCheck(opts, context) {
     triageBudget.throwIfSecondary();
     triageBudget.reportOmissionIfNeeded();
     const seenMap = await loadSeenMap(stateKey);
+    await aliasThreadSeenMarkers(repo, prNumber, batchData.reviewThreads.map((thread) => thread.id), seenMap);
+    const canGenerateItemMutation = (id, body, capability, operation) => !mutationWasDenied(id, body, seenMap) && canGenerateGithubMutation(capability, operation);
     const botUsernames = normalizeBotUsernames(config.botUsernames);
-    const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
+    const ruleSet = await loadClassifyRules(getEffectiveCwd(), config.standardRules);
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
     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 deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => !canGenerateItemMutation(id, batchData.comments.find((comment) => comment.id === id)?.body ?? "", batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize, "minimize")));
+    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames, new Set(batchData.comments
+        .filter((comment) => mutationWasDenied(comment.id, comment.body, seenMap))
+        .map((comment) => comment.id)));
+    const deniedRuleAutoResolveThreadIds = new Set(partition.ruleAutoResolveThreadIds.filter((id) => {
+        const thread = batchData.reviewThreads.find((candidate) => candidate.id === id);
+        return (thread?.isResolved !== false ||
+            !canGenerateItemMutation(thread.id, threadTranscriptBody(thread), thread.viewerCanResolve, "resolve"));
+    }));
     const visibleThreadCandidates = batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id));
     const resolveOtherHumanThreads = config.iterate.resolveOtherHumanThreads ?? "none";
     const threadMutationRouting = buildThreadMutationRouting(visibleThreadCandidates, botUsernames, partition.ruleAutoResolveThreadIds, resolveOtherHumanThreads);
     const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
     const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
     const repeatableThreadIds = new Set(visibleThreadCandidates
-        .filter((thread) => threadHasAuthorizedMutation(thread, replyThreadIds, resolveThreadIds))
+        .filter((thread) => !mutationWasDenied(thread.id, threadTranscriptBody(thread), seenMap) &&
+        threadHasAuthorizedMutation(thread, replyThreadIds, resolveThreadIds))
         .map((thread) => thread.id));
     const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds, resolveOtherHumanThreads);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
@@ -158,7 +225,7 @@ export async function runCheck(opts, context) {
     const firstLookSummaries = [];
     const editedSummaries = [];
     const seenSummaries = [];
-    const deniedRuleAutoResolveReviewSummaryIds = new Set(partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize !== true));
+    const deniedRuleAutoResolveReviewSummaryIds = new Set(partition.ruleAutoResolveReviewSummaryIds.filter((id) => !canGenerateItemMutation(id, batchData.reviewSummaries.find((review) => review.id === id)?.body ?? "", batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize, "minimize")));
     const unseenReviewSummaries = batchData.reviewSummaries.filter((r) => !partition.suppressedReviewSummaryIds.has(r.id) ||
         deniedRuleAutoResolveReviewSummaryIds.has(r.id));
     for (const r of unseenReviewSummaries) {
@@ -167,10 +234,12 @@ export async function runCheck(opts, context) {
             firstLookSummaries.push(r);
         else if (cls === "edited")
             editedSummaries.push(r);
-        else
+        else if (!mutationWasDenied(r.id, r.body, seenMap))
             seenSummaries.push(r);
     }
-    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames, batchData.viewerAuthorization?.viewerCanAdminister === true);
+    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames, canGenerateGithubMutation(batchData.viewerAuthorization?.viewerCanAdminister, "dismiss"), new Set(batchData.changesRequestedReviews
+        .filter((review) => mutationWasDenied(review.id, review.body, seenMap))
+        .map((review) => review.id)));
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
     const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
@@ -179,20 +248,12 @@ export async function runCheck(opts, context) {
             return false;
         const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
         return (!isBot ||
-            batchData.viewerAuthorization?.viewerCanAdminister === true ||
+            canGenerateItemMutation(review.id, review.body, batchData.viewerAuthorization?.viewerCanAdminister, "dismiss") ||
             visibleChangesRequestedIds.has(review.id));
     }).length;
     const approvedReviews = approvedReviewVisibility.visible;
-    const unreported = await collectUnreportedRequired({
-        batchData,
-        checks: allChecks,
-        suites: result.headWorkflowSuites ?? [],
-        owner: repo.owner,
-        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);
+    status = enforceTransportReadiness(status, batchData);
     // Resolve any pending mergeability refresh (and the resulting MERGED/CLOSED short-circuit)
     // before deciding what to persist below — deferWhileQueued must see the same final,
     // possibly-refreshed mergeStatus that commands/iterate/index.mts acts on, not the pre-refresh
@@ -203,6 +264,7 @@ export async function runCheck(opts, context) {
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
+        status = enforceTransportReadiness(status, batchData);
         if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
             const terminal = buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
             if (result.fingerprint) {
@@ -270,9 +332,13 @@ export async function runCheck(opts, context) {
     }
     const authorizedPartition = {
         ...partition,
-        ruleAutoResolveThreadIds: partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve === true),
-        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),
+        ruleAutoResolveThreadIds: partition.ruleAutoResolveThreadIds.filter((id) => {
+            const thread = batchData.reviewThreads.find((candidate) => candidate.id === id);
+            return (thread?.isResolved === false &&
+                canGenerateItemMutation(id, threadTranscriptBody(thread), thread.viewerCanResolve, "resolve"));
+        }),
+        ruleAutoResolveCommentIds: partition.ruleAutoResolveCommentIds.filter((id) => canGenerateItemMutation(id, batchData.comments.find((comment) => comment.id === id)?.body ?? "", batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize, "minimize")),
+        ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => canGenerateItemMutation(id, batchData.reviewSummaries.find((review) => review.id === id)?.body ?? "", batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize, "minimize")),
     };
     if (opts.autoMinimizeSuppressed === true &&
         (authorizedPartition.ruleAutoResolveThreadIds.length > 0 ||
@@ -292,6 +358,7 @@ export async function runCheck(opts, context) {
         ...authorizedRuleAutoResolveThreadIds,
         ...[...deniedRuleAutoResolveThreadIds].filter((id) => visibleMutationThreadIds.has(id)),
     ];
+    mergeStatus = withTrunkRequiredContexts(mergeStatus, unreported.requiredContexts);
     const blockedByFilteredCheck = isBlockedByFilteredCheck(mergeStatus, verdict);
     const queueCommit = batchData.isInMergeQueue
         ? batchData.mergeQueueEntry?.headCommitOid
@@ -303,10 +370,16 @@ export async function runCheck(opts, context) {
     const report = {
         pr: prNumber,
         nodeId: batchData.nodeId,
+        ...(batchData.transport && { transport: batchData.transport }),
+        ...(batchData.transportUnavailable && {
+            transportUnavailable: batchData.transportUnavailable,
+        }),
         headSha: batchData.headRefOid,
         headRefName: unreported.headRefName,
         repo: `${repo.owner}/${repo.name}`,
-        ...(batchData.viewerAuthorization && { viewerAuthorization: batchData.viewerAuthorization }),
+        ...(batchData.viewerAuthorization && {
+            viewerAuthorization: batchData.viewerAuthorization,
+        }),
         status,
         baseBranch: batchData.baseRefName,
         ...(batchData.baseRefOid && { baseRefOid: batchData.baseRefOid }),
@@ -321,8 +394,12 @@ export async function runCheck(opts, context) {
             ...(ignoredAnnotated.length > 0 && { ignored: ignoredAnnotated }),
             filteredNames: verdict.filteredNames,
             blockedByFilteredCheck,
-            ...(verdict.ignoredNames.length > 0 && { ignoredNames: verdict.ignoredNames }),
-            ...(verdict.supersededNames.length > 0 && { supersededNames: verdict.supersededNames }),
+            ...(verdict.ignoredNames.length > 0 && {
+                ignoredNames: verdict.ignoredNames,
+            }),
+            ...(verdict.supersededNames.length > 0 && {
+                supersededNames: verdict.supersededNames,
+            }),
         },
         threads: {
             actionable: threadVisibility.activeThreads,
@@ -358,7 +435,9 @@ export async function runCheck(opts, context) {
             mergeQueue: {
                 enabled: Boolean(batchData.isMergeQueueEnabled),
                 inQueue: Boolean(batchData.isInMergeQueue),
-                ...(batchData.autoMergeRequest && { autoMergeRequest: batchData.autoMergeRequest }),
+                ...(batchData.autoMergeRequest && {
+                    autoMergeRequest: batchData.autoMergeRequest,
+                }),
                 ...(batchData.mergeQueueEntry && { entry: batchData.mergeQueueEntry }),
                 ...(batchData.latestMergeQueueRemoval && {
                     latestRemoval: batchData.latestMergeQueueRemoval,
@@ -369,7 +448,9 @@ export async function runCheck(opts, context) {
                     : batchData.removedMergeQueueChecksIncomplete) && {
                     checksIncomplete: true,
                 }),
-                ...(headUpdatedAfterRemoval && { headUpdatedAfterRemoval: true }),
+                ...(headUpdatedAfterRemoval && {
+                    headUpdatedAfterRemoval: true,
+                }),
                 ...(removalsOnHead > 1 && { removalsOnHead }),
                 ...(removalAcknowledged && { removalAcknowledged: true }),
             },
@@ -377,15 +458,24 @@ export async function runCheck(opts, context) {
         ...(unreported.unreportedRequiredChecks && {
             unreportedRequiredChecks: unreported.unreportedRequiredChecks,
         }),
-        ...(unreported.trunkBehindBy !== undefined && { trunkBehindBy: unreported.trunkBehindBy }),
-        ...(unreported.baseBehindBy !== undefined && { baseBehindBy: unreported.baseBehindBy }),
+        ...(unreported.trunkBehindBy !== undefined && {
+            trunkBehindBy: unreported.trunkBehindBy,
+        }),
+        ...(unreported.baseBehindBy !== undefined && {
+            baseBehindBy: unreported.baseBehindBy,
+        }),
         ...(unreported.actionsWorkflowInProgress && {
             actionsWorkflowInProgress: true,
         }),
-        ...(unreported.stackBottomPr !== undefined && { stackBottomPr: unreported.stackBottomPr }),
+        ...(unreported.stackBottomPr !== undefined && {
+            stackBottomPr: unreported.stackBottomPr,
+        }),
     };
     if (result.fingerprint) {
         await storePrFingerprint(stateKey, result.fingerprint, report, config);
+        await recordWaitDetectors(stateKey, config, detectors, result.fingerprint);
     }
+    if (restSnapshot)
+        await storeRestSnapshotReport(stateKey, restSnapshot.digest, report, config);
     return report;
 }

package/bin/commands/event-instructions.d.mts

@@ -0,0 +1,11 @@
+import type { NextCheck } from "../types/next-check.mts";
+/**
+ * Steps that replace "iterate immediately" when Shepherd ran in event mode and the PR is
+ * waiting: end the turn, keep one wake-up, and let the next tick come from a PR event or the
+ * wake-up. Always printed after any state-specific sentence.
+ */
+export declare function eventWaitSteps(next: NextCheck): string[];
+/** Replaces the `[FIX_CODE]` "iterate immediately" line when the tick ran in event mode. */
+export declare function eventFixContinuation(next: NextCheck): string;
+/** One aggregate step: sessions still run first, and only then does the turn end. */
+export declare function eventAggregateStep(next: NextCheck, waiting: boolean): string;

package/bin/commands/event-instructions.mjs

@@ -0,0 +1,27 @@
+import { playbookPointer } from "./playbook-pointer.mjs";
+function wakeUpClause(next) {
+    const kind = next.reason === "safety-net" ? "safety-net wake-up" : "wake-up";
+    return `Keep exactly one ${kind} at \`${next.at}\` (\`${next.reason}\`).`;
+}
+/**
+ * Steps that replace "iterate immediately" when Shepherd ran in event mode and the PR is
+ * waiting: end the turn, keep one wake-up, and let the next tick come from a PR event or the
+ * wake-up. Always printed after any state-specific sentence.
+ */
+export function eventWaitSteps(next) {
+    return [
+        `Event mode: end this turn now without sleeping or polling. ${playbookPointer("Cloud event loop")}`,
+        `${wakeUpClause(next)} When a PR event or that wake-up arrives, rerun this command with the same options and act only on Shepherd's output, never on the event payload.`,
+    ];
+}
+/** Replaces the `[FIX_CODE]` "iterate immediately" line when the tick ran in event mode. */
+export function eventFixContinuation(next) {
+    return `\`[FIX_CODE]\` is non-terminal. After the steps above, rerun this command once with the same options, then end the turn without sleeping. ${wakeUpClause(next)} ${playbookPointer("Cloud event loop")}`;
+}
+/** One aggregate step: sessions still run first, and only then does the turn end. */
+export function eventAggregateStep(next, waiting) {
+    const lead = waiting
+        ? "Event mode: end this turn now without sleeping or polling."
+        : "Event mode: once the steps above are done and the rerun still waits, end the turn without sleeping.";
+    return `${lead} ${wakeUpClause(next)} When a PR event or that wake-up arrives, rerun this selector with the same options and act only on Shepherd's output, never on the event payload. ${playbookPointer("Cloud event loop")}`;
+}

package/bin/commands/event-mode.d.mts

@@ -0,0 +1,14 @@
+import type { IterateCommandOptions, IterateResult, PollSummaryCommandOptions, PollSummaryResult } from "../types.mts";
+import { type PollCommandOptions } from "./poll.mts";
+import { type AggregatePollCommandOptions } from "./poll-summary.mts";
+/**
+ * One iterate tick. In event mode the tick runs exactly once with no settle window and no
+ * sleeping, persists seen markers immediately, and reports when to come back.
+ */
+export declare function runIterateForMode(opts: IterateCommandOptions): Promise<IterateResult>;
+/** One aggregate tick; event mode adds `pollMode` and `nextCheck`. */
+export declare function runPollSummaryForMode(opts: PollSummaryCommandOptions): Promise<PollSummaryResult>;
+/** The default poll command: the sleeping loop in poll mode, one tick in event mode. */
+export declare function runPollForMode(opts: PollCommandOptions): Promise<IterateResult>;
+/** The aggregate poll command: the sleeping loop in poll mode, one tick in event mode. */
+export declare function runAggregatePollForMode(opts: AggregatePollCommandOptions): Promise<PollSummaryResult>;

package/bin/commands/event-mode.mjs

@@ -0,0 +1,138 @@
+import { loadConfig } from "../config/load.mjs";
+import { readStallState } from "../state/iterate-stall.mjs";
+import { runWithDurableState } from "../state/durable-state.mjs";
+import { eventAggregateStep, eventFixContinuation } from "./event-instructions.mjs";
+import { earliestNextCheck, MERGE_QUEUE_RECHECK_SECONDS, nextCheckCandidates, SAFETY_NET_SECONDS, } from "./next-check.mjs";
+import { isFixCodeContinuation } from "./iterate/check-instructions.mjs";
+import { isHandedOffSelection } from "./poll-summary-explicit-instructions.mjs";
+import { runIterate } from "./iterate/index.mjs";
+import { resolvePollMode } from "./poll-mode.mjs";
+import { readStackStallDeadline } from "./stack-stall.mjs";
+import { runPoll } from "./poll.mjs";
+import { runAggregatePoll, runPollSummary, } from "./poll-summary.mjs";
+function isEventMode(requested) {
+    return resolvePollMode(requested, loadConfig().poll.mode) === "event";
+}
+/**
+ * One iterate tick. In event mode the tick runs exactly once with no settle window and no
+ * sleeping, persists seen markers immediately, and reports when to come back.
+ */
+export function runIterateForMode(opts) {
+    if (!isEventMode(opts.pollMode))
+        return runIterate(opts);
+    return runWithDurableState(() => runIterateEvent(opts));
+}
+/** One aggregate tick; event mode adds `pollMode` and `nextCheck`. */
+export function runPollSummaryForMode(opts) {
+    if (!isEventMode(opts.pollMode))
+        return runPollSummary(opts);
+    const eventOpts = { ...opts, pollMode: "event" };
+    return runWithDurableState(async () => withAggregateNextCheck(await runPollSummary(eventOpts), eventOpts));
+}
+/** The default poll command: the sleeping loop in poll mode, one tick in event mode. */
+export function runPollForMode(opts) {
+    if (!isEventMode(opts.pollMode))
+        return runPoll(opts);
+    const { intervalSeconds: _intervalSeconds, timeoutSeconds: _timeoutSeconds, debounceSeconds: _debounceSeconds, quietStatus: _quietStatus, untilTerminal: _untilTerminal, ...tick } = opts;
+    return runIterateForMode(tick);
+}
+/** The aggregate poll command: the sleeping loop in poll mode, one tick in event mode. */
+export function runAggregatePollForMode(opts) {
+    return isEventMode(opts.pollMode) ? runPollSummaryForMode(opts) : runAggregatePoll(opts);
+}
+async function runIterateEvent(opts) {
+    const { pollMode: _pollMode, ...iterateOpts } = opts;
+    const sink = {};
+    const result = await runIterate({
+        ...iterateOpts,
+        persistSeen: true,
+        fingerprintCache: false,
+        stallDeadlineSink: sink,
+    });
+    const nowMs = Date.now();
+    const stallDeadlineSeconds = earliestDeadline(await readStallDeadline(result, opts.stallTimeoutSeconds), result.action === "wait" ? sink.ciStartDeadlineSeconds : undefined);
+    const nextCheck = earliestNextCheck(nextCheckCandidates({
+        action: result.action,
+        remainingSeconds: result.remainingSeconds,
+        queued: result.mergeQueue?.inQueue === true,
+        restMerge: result.action === "merge" && result.merge.mode === "rest",
+        stackDraftHold: result.action === "wait" && result.stackDraftHold !== undefined,
+        stallDeadlineSeconds,
+    }, nowMs), nowMs);
+    const tagged = { ...result, pollMode: "event", ...(nextCheck && { nextCheck }) };
+    if (tagged.action !== "fix_code" || !nextCheck)
+        return tagged;
+    return {
+        ...tagged,
+        fix: {
+            ...tagged.fix,
+            instructions: tagged.fix.instructions.map((step) => isFixCodeContinuation(step) ? eventFixContinuation(nextCheck) : step),
+        },
+    };
+}
+function earliestDeadline(...deadlines) {
+    const known = deadlines.filter((d) => d !== undefined);
+    return known.length > 0 ? Math.min(...known) : undefined;
+}
+/** When an unchanged state would trip the stall timeout, or undefined when no timer is running. */
+async function readStallDeadline(result, stallTimeoutSeconds) {
+    if (!["wait", "fix_code"].includes(result.action))
+        return undefined;
+    const timeout = stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60;
+    const [owner, repo] = result.repo.split("/");
+    if (timeout <= 0 || !owner || !repo)
+        return undefined;
+    const read = await readStallState({ owner, repo, pr: result.pr });
+    return read.ok && read.state ? read.state.firstSeenAt + timeout : undefined;
+}
+async function withAggregateNextCheck(result, opts) {
+    const tagged = { ...result, pollMode: "event" };
+    const stallDeadlineSeconds = await readStackStallDeadline(result, opts.stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60);
+    const nextCheck = aggregateNextCheck(result, stallDeadlineSeconds);
+    if (!nextCheck)
+        return tagged;
+    const instructions = (result.instructions ?? []).map(withoutPollingCadence);
+    const waiting = result.reason === "waiting" || result.reason === "timeout";
+    return {
+        ...tagged,
+        nextCheck,
+        instructions: [
+            ...instructions,
+            `${instructions.length + 1}. ${eventAggregateStep(nextCheck, waiting)}`,
+        ],
+    };
+}
+/**
+ * Event mode replaces polling: the appended event step owns the next wake-up, so a stack
+ * step's "recheck at the configured polling cadence" would contradict it. A pending stack
+ * merge resumes on that wake-up instead.
+ */
+function withoutPollingCadence(step) {
+    return step
+        .replace(/ Recheck(?: them)? at the configured polling cadence\./g, "")
+        .replace("rerun that command at the configured cadence to resume its UUID", "rerun that command after the wake-up below to resume its UUID");
+}
+function aggregateNextCheck(result, stallDeadlineSeconds) {
+    if (isHandedOffSelection(result) ||
+        result.reason === "all_terminal" ||
+        result.nextAction === "cancel" ||
+        result.nextAction === "escalate") {
+        return undefined;
+    }
+    const candidates = result.prs
+        .filter((item) => (item.remainingSeconds ?? 0) > 0)
+        .map((item) => ({ reason: "ready-delay", seconds: item.remainingSeconds }));
+    // A printed stack merge can stay pending, so recheck it like a REST merge. A mergeable
+    // stack that is queued or waiting prints no merge command, so it gets no such wake-up.
+    if (result.nextAction === "merge") {
+        candidates.push({ reason: "merge-pending", seconds: MERGE_QUEUE_RECHECK_SECONDS });
+    }
+    candidates.push(result.prs.some((item) => item.isInMergeQueue)
+        ? { reason: "merge-queue", seconds: MERGE_QUEUE_RECHECK_SECONDS }
+        : { reason: "safety-net", seconds: SAFETY_NET_SECONDS });
+    const nowMs = Date.now();
+    if (stallDeadlineSeconds !== undefined) {
+        candidates.push({ reason: "stall-timeout", seconds: stallDeadlineSeconds - nowMs / 1000 });
+    }
+    return earliestNextCheck(candidates, nowMs);
+}

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

@@ -2,6 +2,8 @@ import { loadConfig } from "../../config/load.mjs";
 import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
 import { selectQuotaWarning } from "../quota-selection.mjs";
 import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
+import { getGithubTransport } from "../../github/transport.mjs";
+import { isFixCodeContinuation } from "./check-instructions.mjs";
 function shouldWarn(result) {
     return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
 }
@@ -18,7 +20,7 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
                 ...band,
                 pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
             }));
-            quotaWarning = await selectQuotaWarning({ owner, repo }, bands, apiUsage, persistWarning);
+            quotaWarning = await selectQuotaWarning({ owner, repo }, bands, apiUsage, persistWarning, getGithubTransport());
         }
     }
     const { quotaWarning: _deferredWarning, ...baseResult } = result;
@@ -32,7 +34,7 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
     const instructions = [...withWarning.fix.instructions];
     const completion = instructions.at(-1);
     if (completion !== undefined) {
-        if (/\[FIX_CODE\].*non-terminal/i.test(completion)) {
+        if (isFixCodeContinuation(completion)) {
             instructions[instructions.length - 1] = buildQuotaAwareContinuation(quotaWarning, "`[FIX_CODE]` is non-terminal. After completing these steps,");
         }
     }

package/bin/commands/iterate/base.mjs

@@ -5,6 +5,10 @@ export function buildIterateBase(report, readyState) {
     return {
         pr: report.pr,
         repo: report.repo,
+        ...(report.transport && { transport: report.transport }),
+        ...(report.transportUnavailable?.length && {
+            transportUnavailable: report.transportUnavailable,
+        }),
         status: report.status,
         state: report.mergeStatus.state,
         mergeStateStatus: report.mergeStatus.mergeStateStatus,

package/bin/commands/iterate/check-blocker-gate.mjs

@@ -1,6 +1,8 @@
 import { graphql } from "../../github/client.mjs";
 import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
 import { clearCheckBlocker, formatCheckBlockerRef, readCheckBlockers, } from "../../state/check-blockers.mjs";
+import { rest } from "../../github/http.mjs";
+import { githubOperation } from "../../github/transport.mjs";
 const RATE_LIMIT = "cost limit nodeCount remaining resetAt used";
 const PULL_QUERY = `query CheckBlockerPull($owner: String!, $name: String!, $number: Int!) {
   _shepherdRateLimit: rateLimit { ${RATE_LIMIT} }
@@ -78,7 +80,10 @@ async function lookupBlocker(blocker) {
     try {
         const vars = { owner: blocker.owner, name: blocker.name, number: blocker.number };
         if (blocker.kind === "issue") {
-            const { data } = await graphql(ISSUE_QUERY, vars);
+            const { data } = await githubOperation("CheckBlockerIssue", () => graphql(ISSUE_QUERY, vars), async () => {
+                const issue = await rest("GET", `/repos/${blocker.owner}/${blocker.name}/issues/${blocker.number}`);
+                return { data: { repository: { issue: { state: issue.state.toUpperCase() } } } };
+            });
             const issue = data.repository?.issue;
             if (!issue)
                 return ignore(blocker, "not found");
@@ -88,7 +93,14 @@ async function lookupBlocker(blocker) {
                 return "released";
             return ignore(blocker, `unexpected state ${issue.state}`);
         }
-        const { data } = await graphql(PULL_QUERY, vars);
+        const { data } = await githubOperation("CheckBlockerPull", () => graphql(PULL_QUERY, vars), async () => {
+            const pull = await rest("GET", `/repos/${blocker.owner}/${blocker.name}/pulls/${blocker.number}`);
+            return {
+                data: {
+                    repository: { pullRequest: { state: pull.state.toUpperCase(), merged: pull.merged } },
+                },
+            };
+        });
         const pull = data.repository?.pullRequest;
         if (!pull)
             return ignore(blocker, "not found");

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

@@ -1,5 +1,7 @@
 import type { AgentCheck, ResolveCommand, Review } from "../../types.mts";
-/** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
+/** The `[FIX_CODE]` recurrence step, whether plain or rewritten by the quota warning. */
+export declare function isFixCodeContinuation(step: string): boolean;
+/** Build the stale-CR step for `## Changes-requested reviews`. Empty when no human CR is stale. */
 export declare function buildCrStaleClause(reviews: Review[]): string;
 /**
  * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
@@ -24,16 +26,13 @@ export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBran
     hasConflicts: boolean;
 }, stackRebase?: string): string[];
 /**
- * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
- * whenever the *unmodified, as-printed* command is unsafe without them:
- *
- * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
- *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
- * dismiss-ID retention. The pointer below is load-bearing: without it, nothing in CLI output
- * tells the agent that playbook exists.
+ * Build the `apply review` step, with the rendered command inline. The step stays here (not in
+ * the skill) because the *as-printed* command is invalid without `$DISMISS_MESSAGE`: an empty
+ * `--message` makes `apply review` reject the mutation. `--require-sha` needs no substitution:
+ * the rendered command reads the pushed HEAD itself. "Even if you changed no code": the
+ * command records each item's disposition either way.
  */
-export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
+export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand, rendered: string): string[];
 /** One pointer. Conclusion, rerun, and bare-check rules live in the CI playbook. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
 /** Update the PR branch after an external blocker merges or closes. Never rerun that job. */