pr-shepherd 0.59.3 → 0.60.1

package/bin/cli/iterate-lean.mjs

@@ -1,8 +1,10 @@
 import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
 import { projectRuleAutoResolve } from "../commands/rule-auto-resolve-format.mjs";
+import { projectEditedComments } from "./edited-comments-format.mjs";
 import { projectMergeRequirements } from "../merge-status/requirements-format.mjs";
 import { branchSegmentShowsBase } from "./iterate-branch-segment.mjs";
 import { isRedundantMergeQueue } from "./iterate-merge-formatter.mjs";
+import { capList } from "../util/cap-list.mjs";
 /**
  * Project an IterateResult to a lean JSON shape for the default (non-verbose) output.
  * Omits fields that are the trivial default (false, 0, empty) or state-gated fields
@@ -31,7 +33,7 @@ export function projectIterateLean(result, opts) {
             }),
         };
     }
-    const counts = Object.fromEntries(["passing", "skipped", "filtered", "inProgress", "superseded"]
+    const counts = Object.fromEntries(["passing", "skipped", "filtered", "inProgress", "queued", "superseded"]
         .filter((k) => result.summary[k] > 0)
         .map((k) => [k, result.summary[k]]));
     const summary = Object.keys(counts).length > 0 ? counts : null;
@@ -82,15 +84,9 @@ export function projectIterateLean(result, opts) {
                 }),
             },
         }),
-        ...((result.inProgressChecks?.length ?? 0) > 0 && {
-            inProgressChecks: result.inProgressChecks,
-        }),
-        ...((result.ignoredNames?.length ?? 0) > 0 && {
-            ignoredNames: result.ignoredNames,
-        }),
-        ...((result.supersededNames?.length ?? 0) > 0 && {
-            supersededNames: result.supersededNames,
-        }),
+        ...cappedList("inProgressChecks", result.inProgressChecks),
+        ...cappedList("ignoredNames", result.ignoredNames),
+        ...cappedList("supersededNames", result.supersededNames),
         ...((result.unreportedRequiredChecks?.length ?? 0) > 0 && {
             unreportedRequiredChecks: result.unreportedRequiredChecks,
         }),
@@ -104,6 +100,9 @@ export function projectIterateLean(result, opts) {
         ...(result.ruleAutoResolve && {
             ruleAutoResolve: projectRuleAutoResolve(result.ruleAutoResolve),
         }),
+        ...(result.editedComments?.length && {
+            editedComments: projectEditedComments(result.editedComments),
+        }),
     };
     switch (result.action) {
         case "ready":
@@ -144,7 +143,7 @@ export function projectIterateLean(result, opts) {
         case "fix_code":
             return {
                 ...base,
-                ...(result.checks.length > 0 && { checks: result.checks }),
+                // Passing checks stay summary counts and failures stay in `fix.checks`, as in lean text.
                 ...(result.cancelled.length > 0 && { cancelled: result.cancelled }),
                 fix: {
                     ...(result.fix.threads.length > 0 && { threads: result.fix.threads }),
@@ -190,6 +189,7 @@ export function projectIterateLean(result, opts) {
                     ...(result.fix.resolveOnlyCommand && {
                         resolveOnlyCommand: result.fix.resolveOnlyCommand,
                     }),
+                    ...(result.fix.reviewItems && { reviewItems: result.fix.reviewItems }),
                     ...(result.fix.instructions.length > 0 && {
                         instructions: result.fix.instructions,
                     }),
@@ -229,6 +229,7 @@ export function projectIterateLean(result, opts) {
                         result.escalate.thrashHistory.length > 0 && {
                         thrashHistory: result.escalate.thrashHistory,
                     }),
+                    ...(result.escalate.reviewItems && { reviewItems: result.escalate.reviewItems }),
                     ...(result.escalate.mergeQueueRemoval && {
                         mergeQueueRemoval: result.escalate.mergeQueueRemoval,
                     }),
@@ -246,4 +247,11 @@ export function projectIterateLean(result, opts) {
             };
     }
 }
+/** `{ [key]: first 5, [key + "More"]: hidden count }`, matching the capped Markdown lists. */
+function cappedList(key, items) {
+    if (!items || items.length === 0)
+        return {};
+    const { shown, hidden } = capList(items);
+    return { [key]: shown, ...(hidden > 0 && { [`${key}More`]: hidden }) };
+}
 export { projectIterateVerbose } from "./iterate-verbose.mjs";

package/bin/cli/iterate-verbose.mjs

@@ -1,11 +1,16 @@
 import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
+import { projectEditedComments } from "./edited-comments-format.mjs";
 export function projectIterateVerbose(result, opts) {
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const readyDelayOverride = readyDelaySuffix ? { readyDelayOverride: readyDelaySuffix } : {};
+    // Edited comments use the lean projection: their bookkeeping fields have no Markdown form.
+    const edited = result.editedComments && {
+        editedComments: projectEditedComments(result.editedComments),
+    };
     if (result.action === "fix_code")
-        return { ...result, ...readyDelayOverride };
+        return { ...result, ...readyDelayOverride, ...edited };
     const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
     // `cancel` has no instructions, so verbose JSON omits the field as verbose Markdown omits the section.
     const instructions = result.action === "cancel" ? {} : { instructions: buildSimpleIterateInstructions(result) };
-    return { ...result, ...log, ...readyDelayOverride, ...instructions };
+    return { ...result, ...log, ...readyDelayOverride, ...instructions, ...edited };
 }

package/bin/cli/list-formatters.d.mts

@@ -49,9 +49,6 @@ export declare function renderCommentBullet(c: {
 }, opts?: {
     statusTag?: string;
 }): string;
-export declare function renderEditedCommentTag(c: {
-    edited?: boolean;
-}): string | undefined;
 export declare function renderReviewBullet(r: {
     id: string;
     author: string;

package/bin/cli/list-formatters.mjs

@@ -101,9 +101,6 @@ export function renderCommentBullet(c, opts = {}) {
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
     return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
 }
-export function renderEditedCommentTag(c) {
-    return c.edited ? "[edited since first look]" : undefined;
-}
 export function renderReviewBullet(r, opts = {}) {
     const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`;
     const staleTag = r.staleReview
@@ -138,8 +135,7 @@ export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, first
         }));
     }
     for (const c of firstLookComments) {
-        const editedSuffix = c.edited ? ", edited" : "";
-        bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
+        bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
     }
     return bullets;
 }

package/bin/commands/check-review-budget.d.mts

@@ -0,0 +1,39 @@
+import { type ReviewItemRollup } from "../comments/review-output-budget.mts";
+import type { ActionableComment, EditedComment, FirstLookComment, FirstLookThread, Review, ReviewThread } from "../types.mts";
+/** Every check.mts list that renders a review item, generates a mutation for it, or marks it seen. */
+export interface ReviewOutputBuckets {
+    changesRequested: {
+        visible: Review[];
+        toMarkSeen: Review[];
+    };
+    threads: {
+        activeThreads: ReviewThread[];
+        resolutionOnlyThreads: ReviewThread[];
+        firstLookThreads: FirstLookThread[];
+        toMarkSeen: ReviewThread[];
+    };
+    comments: {
+        actionable: ActionableComment[];
+        minimizeIds: string[];
+        toMarkSeen: ActionableComment[];
+    };
+    firstLookComments: FirstLookComment[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    editedComments: EditedComment[];
+}
+/**
+ * Applies `iterate.reviewOutputMaxChars` to one tick's review buckets. Priority: changes-requested
+ * reviews, active threads and comments, first-look items, review summaries, edited comments.
+ * Approved reviews are opt-in minimize targets, not review work, and are never held.
+ * Held items leave every list — the report, the generated mutation IDs, and the seen-marker
+ * writes — so the next tick shows them. `rollup` is set only when something was held.
+ * Edited comments are held only alongside other held work: edits never block readiness, so a
+ * ready or terminal tick must not leave some of them unshown. `heldThreadReviewIds` names the
+ * parent reviews of held unresolved threads, which must not be minimized while those wait.
+ */
+export declare function applyReviewOutputBudget(buckets: ReviewOutputBuckets, maxChars: number): {
+    buckets: ReviewOutputBuckets;
+    rollup?: ReviewItemRollup;
+    heldThreadReviewIds?: string[];
+};

package/bin/commands/check-review-budget.mjs

@@ -0,0 +1,78 @@
+import { selectReviewOutput, } from "../comments/review-output-budget.mjs";
+import { threadTranscriptBody } from "../threads/transcript.mjs";
+const bodyItem = (item) => ({
+    id: item.id,
+    cost: item.body.length,
+    ...(item.createdAtUnix !== undefined && { createdAtUnix: item.createdAtUnix }),
+});
+const threadItem = (thread) => ({
+    ...bodyItem(thread),
+    cost: threadTranscriptBody(thread).length,
+});
+/**
+ * Applies `iterate.reviewOutputMaxChars` to one tick's review buckets. Priority: changes-requested
+ * reviews, active threads and comments, first-look items, review summaries, edited comments.
+ * Approved reviews are opt-in minimize targets, not review work, and are never held.
+ * Held items leave every list — the report, the generated mutation IDs, and the seen-marker
+ * writes — so the next tick shows them. `rollup` is set only when something was held.
+ * Edited comments are held only alongside other held work: edits never block readiness, so a
+ * ready or terminal tick must not leave some of them unshown. `heldThreadReviewIds` names the
+ * parent reviews of held unresolved threads, which must not be minimized while those wait.
+ */
+export function applyReviewOutputBudget(buckets, maxChars) {
+    const { changesRequested, threads, comments } = buckets;
+    const selection = selectReviewOutput([
+        changesRequested.visible.map(bodyItem),
+        [
+            ...threads.activeThreads.map(threadItem),
+            ...threads.resolutionOnlyThreads.map(threadItem),
+            ...comments.actionable.map(bodyItem),
+        ],
+        [...threads.firstLookThreads.map(threadItem), ...buckets.firstLookComments.map(bodyItem)],
+        [...buckets.firstLookSummaries.map(bodyItem), ...buckets.editedSummaries.map(bodyItem)],
+        buckets.editedComments.map(bodyItem),
+    ], maxChars);
+    if (selection.rollup === undefined)
+        return { buckets };
+    const nonEditedIds = [
+        ...changesRequested.visible,
+        ...threads.activeThreads,
+        ...threads.resolutionOnlyThreads,
+        ...comments.actionable,
+        ...threads.firstLookThreads,
+        ...buckets.firstLookComments,
+        ...buckets.firstLookSummaries,
+        ...buckets.editedSummaries,
+    ].map((item) => item.id);
+    if (nonEditedIds.every(selection.keep))
+        return { buckets };
+    const heldThreadReviewIds = [...threads.activeThreads, ...threads.resolutionOnlyThreads]
+        .filter((thread) => !selection.keep(thread.id))
+        .flatMap((thread) => (thread.reviewId !== undefined ? [thread.reviewId] : []));
+    const keep = (items) => items.filter((item) => selection.keep(item.id));
+    return {
+        buckets: {
+            changesRequested: {
+                visible: keep(changesRequested.visible),
+                toMarkSeen: keep(changesRequested.toMarkSeen),
+            },
+            threads: {
+                activeThreads: keep(threads.activeThreads),
+                resolutionOnlyThreads: keep(threads.resolutionOnlyThreads),
+                firstLookThreads: keep(threads.firstLookThreads),
+                toMarkSeen: keep(threads.toMarkSeen),
+            },
+            comments: {
+                actionable: keep(comments.actionable),
+                minimizeIds: comments.minimizeIds.filter(selection.keep),
+                toMarkSeen: keep(comments.toMarkSeen),
+            },
+            firstLookComments: keep(buckets.firstLookComments),
+            firstLookSummaries: keep(buckets.firstLookSummaries),
+            editedSummaries: keep(buckets.editedSummaries),
+            editedComments: keep(buckets.editedComments),
+        },
+        rollup: selection.rollup,
+        ...(heldThreadReviewIds.length > 0 && { heldThreadReviewIds }),
+    };
+}

package/bin/commands/check-wait-detectors.d.mts

@@ -10,7 +10,11 @@ type StateKey = {
 /**
  * Outcome of the GraphQL transport's REST change detectors. `reused` replays the stored report
  * without any GraphQL request. Otherwise `digest` is what the detectors read before this tick's
- * GraphQL snapshot, recorded beside the new report by `recordWaitDetectors`.
+ * GraphQL snapshot, recorded beside the new report by `recordWaitDetectors`. `changed` is set
+ * when this read differs from the digest stored beside the report, or no digest is stored yet
+ * (the seeding tick): the stored report may predate what the detectors saw, so the tick must
+ * not reuse it through the GraphQL fingerprint either. A same-digest read past
+ * `poll.reconcileSeconds` leaves `changed` unset.
  */
 export type WaitDetectorResult = {
     reused: ShepherdReport;
@@ -18,6 +22,7 @@ export type WaitDetectorResult = {
 } | {
     digest: string;
     readAt: number;
+    changed?: true;
 };
 /**
  * On the GraphQL transport, run the REST change detectors for an idle stored report. Returns

package/bin/commands/check-wait-detectors.mjs

@@ -83,7 +83,8 @@ export async function readWaitDetectors(prNumber, repo, stateKey, config, now =
             baseTipOid: observed.baseTipOid,
         };
     }
-    return { digest: state.digest, readAt: now };
+    const changed = previous?.digest !== state.digest;
+    return { digest: state.digest, readAt: now, ...(changed && { changed: true }) };
 }
 /**
  * After a GraphQL tick, store the digest its detectors read beside the report that tick built.

package/bin/commands/check.d.mts

@@ -7,6 +7,8 @@ type CheckOptions = GlobalOptions & {
     persistSeen?: boolean;
     fingerprintCache?: boolean;
     merge?: boolean;
+    /** Per-tick review-item body budget (`iterate.reviewOutputMaxChars`). Omitted or 0: no cap. */
+    reviewOutputMaxChars?: number;
 };
 export declare function runCheck(opts: CheckOptions, context?: CheckExecutionContext): Promise<ShepherdReport>;
 export {};

package/bin/commands/check.mjs

@@ -28,6 +28,7 @@ import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
 import { applySuppressedRuleAutoResolve } from "./rule-auto-resolve.mjs";
+import { applyReviewOutputBudget } from "./check-review-budget.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";
@@ -70,7 +71,11 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         : undefined;
     if (detectors && "reused" in detectors)
         return refreshReused(detectors.reused, detectors.baseTipOid);
-    const reuse = reuseFingerprint
+    // A detector change, or a first seeding read, means the stored report may predate what the
+    // detectors saw; an unchanged first-page fingerprint cannot vouch for it (it omits
+    // per-check-run fields), so take a full snapshot instead.
+    const detectorsChanged = detectors !== undefined && "changed" in detectors;
+    const reuse = reuseFingerprint && !detectorsChanged
         ? await fingerprintReuser(prNumber, repo, stateKey, config)
         : undefined;
     const batchOptions = {
@@ -215,13 +220,17 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         threadHasAuthorizedMutation(thread, replyThreadIds, resolveThreadIds))
         .map((thread) => thread.id));
     const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds, resolveOtherHumanThreads);
-    const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
-        const cls = classifyItem(c.id, c.body, seenMap);
-        if (cls === "unchanged")
-            return [];
-        const base = { ...c, firstLookStatus: "minimized" };
-        return cls === "edited" ? [{ ...base, edited: true }] : [base];
-    });
+    const firstLookComments = minimizedCommentCandidates
+        .filter((c) => classifyItem(c.id, c.body, seenMap) === "new")
+        .map((c) => ({ ...c, firstLookStatus: "minimized" }));
+    // Edited PR comments never block readiness. Iterate shows them on the next action that is not
+    // wait/ready and writes their markers then, so an edit is never marked seen while hidden.
+    const editedComments = [
+        ...minimizedCommentCandidates
+            .filter((c) => classifyItem(c.id, c.body, seenMap) === "edited")
+            .map((c) => ({ ...c, edited: true })),
+        ...visibleCommentClassification.edited,
+    ];
     const firstLookSummaries = [];
     const editedSummaries = [];
     const seenSummaries = [];
@@ -251,7 +260,6 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             canGenerateItemMutation(review.id, review.body, batchData.viewerAuthorization?.viewerCanAdminister, "dismiss") ||
             visibleChangesRequestedIds.has(review.id));
     }).length;
-    const approvedReviews = approvedReviewVisibility.visible;
     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)
@@ -292,6 +300,16 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             filtered: merged.filtered,
             ignored: merged.ignored,
         }, mergeStatus.status);
+    // A deferred tick shows no review items, so it is never capped; its seen markers stay unwritten.
+    const { buckets: budgeted, rollup: reviewItems, heldThreadReviewIds, } = applyReviewOutputBudget({
+        changesRequested: changesRequestedReviewVisibility,
+        threads: threadVisibility,
+        comments: visibleCommentClassification,
+        firstLookComments,
+        firstLookSummaries,
+        editedSummaries,
+        editedComments,
+    }, deferWhileQueued ? 0 : (opts.reviewOutputMaxChars ?? 0));
     if (opts.persistSeen !== false) {
         const successfulAnnotations = [
             ...merged.passing,
@@ -304,11 +322,11 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         const deferredMarkSeen = deferWhileQueued
             ? []
             : [
-                ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
-                ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-                ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
-                ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
-                ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+                ...budgeted.firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+                ...budgeted.threads.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
+                ...budgeted.comments.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
+                ...[...budgeted.firstLookSummaries, ...budgeted.editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
+                ...budgeted.changesRequested.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
                 ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
             ];
         await Promise.allSettled([
@@ -351,7 +369,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         partition: authorizedPartition,
         batch: batchData,
     });
-    const visibleMutationThreadIds = new Set([...threadVisibility.activeThreads, ...threadVisibility.resolutionOnlyThreads].map((thread) => thread.id));
+    const visibleMutationThreadIds = new Set([...budgeted.threads.activeThreads, ...budgeted.threads.resolutionOnlyThreads].map((thread) => thread.id));
     const ruleAutoResolveThreadIds = [
         ...authorizedRuleAutoResolveThreadIds,
         ...[...deniedRuleAutoResolveThreadIds].filter((id) => visibleMutationThreadIds.has(id)),
@@ -400,27 +418,30 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             }),
         },
         threads: {
-            actionable: threadVisibility.activeThreads,
-            resolutionOnly: threadVisibility.resolutionOnlyThreads,
+            actionable: budgeted.threads.activeThreads,
+            resolutionOnly: budgeted.threads.resolutionOnlyThreads,
             autoResolved,
             autoResolveErrors,
             ...(errorReasons.length > 0 && { autoResolveErrorReasons: errorReasons }),
-            firstLook: threadVisibility.firstLookThreads,
+            firstLook: budgeted.threads.firstLookThreads,
             ...(ruleAutoResolveThreadIds.length > 0
                 ? { ruleAutoResolveIds: ruleAutoResolveThreadIds }
                 : undefined),
         },
         comments: {
-            actionable: visibleCommentClassification.actionable,
-            minimizeIds: [...visibleCommentClassification.minimizeIds, ...ruleAutoResolveCommentIds],
-            firstLook: firstLookComments,
+            actionable: budgeted.comments.actionable,
+            minimizeIds: [...budgeted.comments.minimizeIds, ...ruleAutoResolveCommentIds],
+            firstLook: budgeted.firstLookComments,
+            ...(budgeted.editedComments.length > 0 && { edited: budgeted.editedComments }),
             ...(autoMinimized.length > 0 && { autoMinimized }),
         },
-        changesRequestedReviews,
+        changesRequestedReviews: budgeted.changesRequested.visible,
         reviewSummaries: seenSummaries,
-        firstLookSummaries,
-        editedSummaries,
-        approvedReviews,
+        firstLookSummaries: budgeted.firstLookSummaries,
+        editedSummaries: budgeted.editedSummaries,
+        approvedReviews: approvedReviewVisibility.visible,
+        ...(reviewItems && { reviewItems }),
+        ...(heldThreadReviewIds && { heldThreadReviewIds }),
         ...(ruleAutoResolveReviewSummaryIds.length > 0
             ? { ruleAutoResolveReviewSummaryIds }
             : undefined),

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

@@ -37,5 +37,10 @@ export declare function buildResolveCommandInstruction(resolveCommand: ResolveCo
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
 /** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
 export declare function buildReleasedBlockerInstruction(prNumber: number): string;
+/** `iterate.reviewOutputMaxChars` held review items back; the rerun step that follows shows them. */
+export declare function buildReviewSubsetInstruction(reviewItems: {
+    shown: number;
+    total: number;
+}): string;
 /** Recurrence only. Commit, push, rerun, and SHA steps are earlier instructions. */
 export declare function buildFixCompletionInstruction(): string;

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

@@ -74,6 +74,10 @@ export function buildReleasedBlockerInstruction(prNumber) {
         ? "Update this PR branch from its base using the repository's branch-update procedure. Do not rerun the job; a rerun retests the old merge ref."
         : `Update this PR branch from its base with \`gh pr update-branch ${prNumber} --rebase\`. Do not rerun the job; a rerun retests the old merge ref.`;
 }
+/** `iterate.reviewOutputMaxChars` held review items back; the rerun step that follows shows them. */
+export function buildReviewSubsetInstruction(reviewItems) {
+    return `This is a subset: ${reviewItems.shown} of ${reviewItems.total} review items are shown, and only their IDs are in the commands above. After handling these items, rerun Shepherd for the next batch; do not fetch the held items yourself.`;
+}
 /** Recurrence only. Commit, push, rerun, and SHA steps are earlier instructions. */
 export function buildFixCompletionInstruction() {
     return FIX_CODE_CONTINUATION;

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

@@ -5,7 +5,7 @@ export declare function classifyReviewSummaries(summaries: {
     firstLook: Review[];
     seen: Review[];
     edited: Review[];
-}, approvals: Review[], minimizeApprovals: boolean, minimizeComments?: MinimizeCommentsPolicy | undefined, botUsernames?: NormalizedBotUsernames, unresolvedThreads?: ReviewThread[], ruleAutoResolveIds?: string[]): {
+}, approvals: Review[], minimizeApprovals: boolean, minimizeComments?: MinimizeCommentsPolicy | undefined, botUsernames?: NormalizedBotUsernames, unresolvedThreads?: ReadonlyArray<Pick<ReviewThread, "reviewId">>, ruleAutoResolveIds?: string[]): {
     minimizeIds: string[];
     selfMinimizeIds: string[];
     firstLookSummaries: Review[];

package/bin/commands/iterate/edited-comment-markers.d.mts

@@ -0,0 +1,3 @@
+import type { IterateResult } from "../../types.mts";
+/** Records the edited comments a result shows, so each edit is shown once. Returns the result. */
+export declare function markEditedCommentsSeen(result: IterateResult): Promise<IterateResult>;

package/bin/commands/iterate/edited-comment-markers.mjs

@@ -0,0 +1,10 @@
+import { markSeen } from "../../state/seen-comments.mjs";
+/** Records the edited comments a result shows, so each edit is shown once. Returns the result. */
+export async function markEditedCommentsSeen(result) {
+    const [owner, repo] = result.repo.split("/");
+    if (!result.editedComments?.length || !owner || !repo)
+        return result;
+    const key = { owner, repo, pr: result.pr };
+    await Promise.allSettled(result.editedComments.map((c) => markSeen(key, c.id, c.body)));
+    return result;
+}

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

@@ -9,7 +9,7 @@ import { buildFixInstructions } from "./render.mjs";
 import { buildRemovedQueueRecovery, buildStackQueueRemovalAcknowledgment } from "./merge.mjs";
 import { hasLogEvidence } from "./check-evidence.mjs";
 import { currentEjectionCommit, } from "./queue-recovery-instructions.mjs";
-import { buildReleasedBlockerInstruction } from "./check-instructions.mjs";
+import { buildReleasedBlockerInstruction, buildReviewSubsetInstruction, } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
 import { lookupUpperLayerTrunkConflict } from "./stack-trunk-conflict.mjs";
 import { lookupMergedBasePullRequests } from "./merged-base-pull-requests.mjs";
@@ -78,6 +78,14 @@ function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 export async function handleFixCode(ctx) {
+    const result = await handleFixCodeTick(ctx);
+    // Every escalation from a capped tick carries the rollup: the reader sees a subset.
+    const { reviewItems } = ctx.report;
+    if (result.action !== "escalate" || reviewItems === undefined)
+        return result;
+    return { ...result, escalate: { ...result.escalate, reviewItems } };
+}
+async function handleFixCodeTick(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, releasedCheckNames = EMPTY_RELEASED, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
@@ -221,6 +229,7 @@ export async function handleFixCode(ctx) {
         editedSummaries.length > 0 ||
         report.threads.firstLook.length > 0 ||
         report.comments.firstLook.length > 0 ||
+        report.reviewItems !== undefined ||
         checks.some((check) => (check.annotations?.length ?? 0) > 0) ||
         failingAgentChecks.some((check) => releasedCheckNames.has(check.name) ||
             belongsToActiveWorkflowRun(check) ||
@@ -348,6 +357,12 @@ export async function handleFixCode(ctx) {
         if (completion !== undefined)
             instructions.push(completion);
     }
+    if (report.reviewItems) {
+        const completion = instructions.pop();
+        instructions.push(buildReviewSubsetInstruction(report.reviewItems));
+        if (completion !== undefined)
+            instructions.push(completion);
+    }
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }
@@ -396,6 +411,7 @@ export async function handleFixCode(ctx) {
             firstLookComments,
             inProgressRunIds,
             protectedRuns,
+            ...(report.reviewItems && { reviewItems: report.reviewItems }),
         },
         cancelled,
     };

package/bin/commands/iterate/helpers.mjs

@@ -1,10 +1,15 @@
 import { blockedReasonFromRequirements } from "../../merge-status/requirements-format.mjs";
+import { capList, moreSuffix } from "../../util/cap-list.mjs";
+/** GitHub statuses for a check that has not started running yet. */
+const QUEUED_STATUSES = new Set(["QUEUED", "WAITING", "PENDING", "REQUESTED"]);
 export function buildSummary(report) {
+    const queued = report.checks.inProgress.filter((c) => QUEUED_STATUSES.has(c.status)).length;
     return {
         passing: report.checks.passing.length,
         skipped: report.checks.skipped.length,
         filtered: report.checks.filtered.length,
-        inProgress: report.checks.inProgress.length,
+        inProgress: report.checks.inProgress.length - queued,
+        queued,
         superseded: report.checks.supersededNames?.length ?? 0,
     };
 }
@@ -111,13 +116,12 @@ export function buildWaitLog(base) {
     const counts = [
         ...(summary.passing > 0 ? [`${summary.passing} passing`] : []),
         ...(summary.inProgress > 0 ? [`${summary.inProgress} in-progress`] : []),
+        ...(summary.queued > 0 ? [`${summary.queued} queued`] : []),
     ];
     const parts = counts.length > 0 ? [counts.join(", ")] : [];
     if ((base.inProgressChecks?.length ?? 0) > 0) {
-        parts.push(`active checks: ${base
-            .inProgressChecks.slice(0, 5)
-            .map((c) => c.name)
-            .join(", ")}`);
+        const { shown, hidden } = capList(base.inProgressChecks);
+        parts.push(`active checks: ${shown.map((c) => c.name).join(", ")}${moreSuffix(hidden)}`);
     }
     switch (base.mergeStatus) {
         case "BLOCKED": {