pr-shepherd 0.59.2 → 0.60.0

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([
@@ -350,10 +368,8 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         enabled: opts.autoMinimizeSuppressed === true,
         partition: authorizedPartition,
         batch: batchData,
-        prNumber,
-        repo,
     });
-    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)),
@@ -402,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/fix-loop-instruction.d.mts

@@ -1,9 +1,3 @@
 import type { InstructionStyle } from "../../config/load.mts";
-/**
- * The generic commit/push step and the journal step. Playbook style folds both into one pointer
- * only when the generic push applies: the "Fix-code loop" playbook tells the caller to push to the
- * PR head branch, which would conflict with a conflict or queue-recovery push step. Without the
- * generic push, the journal step stays inline with its citation clause. The rerun
- * step stays inline because it is the one step a halted loop cannot recover from.
- */
-export declare function buildPushJournalSteps(style: InstructionStyle, prReference: string | number, genericPush: boolean, wantsJournal: boolean): string[];
+/** The generic push stays separate from conflict and queue-recovery push instructions. */
+export declare function buildPushSteps(style: InstructionStyle, genericPush: boolean): string[];

package/bin/commands/iterate/fix-loop-instruction.mjs

@@ -1,35 +1,14 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { buildShepherdJournalCommand, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { playbookPointer } from "../playbook-pointer.mjs";
 const FIX_CODE_LOOP_PLAYBOOK = "Fix-code loop";
-/**
- * Playbook-style replacement for the invariant commit/push and journal steps. The
- * procedure text lives in the "Fix-code loop" playbook; only the trigger and the concrete
- * journal command stay in the per-tick output. `inline` style never calls this.
- */
-function buildFixLoopInstruction(prReference, journal) {
-    const parts = ["Commit and push any changes."];
-    if (journal)
-        parts.push(`Journal substantial decisions or rejections with \`${buildShepherdJournalCommand(prReference)}\`.`);
+/** The generic push stays separate from conflict and queue-recovery push instructions. */
+export function buildPushSteps(style, genericPush) {
+    if (!genericPush)
+        return [];
+    const push = "Commit and push any changes.";
+    if (style === "inline")
+        return [push];
     const cli = renderShellCommand([...loadConfig().cliCommand, "playbook", FIX_CODE_LOOP_PLAYBOOK]);
-    parts.push(`${playbookPointer(FIX_CODE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`);
-    return parts.join(" ");
-}
-/**
- * The generic commit/push step and the journal step. Playbook style folds both into one pointer
- * only when the generic push applies: the "Fix-code loop" playbook tells the caller to push to the
- * PR head branch, which would conflict with a conflict or queue-recovery push step. Without the
- * generic push, the journal step stays inline with its citation clause. The rerun
- * step stays inline because it is the one step a halted loop cannot recover from.
- */
-export function buildPushJournalSteps(style, prReference, genericPush, wantsJournal) {
-    if (style === "playbook" && genericPush)
-        return [buildFixLoopInstruction(prReference, wantsJournal)];
-    const steps = [];
-    if (genericPush)
-        steps.push("Commit and push any changes.");
-    if (wantsJournal)
-        steps.push(buildShepherdJournalInstruction(prReference));
-    return steps;
+    return [`${push} ${playbookPointer(FIX_CODE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`];
 }

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": {

package/bin/commands/iterate/index.mjs

@@ -9,12 +9,13 @@ import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
-import { isConfiguredBotAuthor, normalizeBotUsernames } from "../../comments/authors.mjs";
+import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
 import { hasCheckDrivenActionableWork } from "../check-annotations.mjs";
 import { buildReadyMergeOutcome, handleActiveMergeState } from "./merge-state.mjs";
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
+import { classifyItem, loadSeenMap } from "../../state/seen-comments.mjs";
 import { withIterateApiUsage } from "./run.mjs";
 import { fetchRawSummaryPr } from "../../github/poll-summary.mjs";
 import { summarizePollSummaryPr } from "../../github/poll-summary-projector.mjs";
@@ -29,10 +30,35 @@ import { buildUnreportedFixResult, planUnreportedRequired } from "./unreported-r
 import { createCheckExecutionContext } from "../check-execution-context.mjs";
 import { transportReadinessGaps } from "../../github/transport-evidence.mjs";
 import { buildEscalateHumanMessage } from "./escalate.mjs";
+import { markEditedCommentsSeen } from "./edited-comment-markers.mjs";
 export function runIterate(opts) {
-    return withIterateApiUsage(opts, () => runIterateCore(opts));
+    return withIterateApiUsage(opts, async () => {
+        const tick = {};
+        return attachEditedComments(await runIterateCore(opts, tick), tick, opts);
+    });
+}
+// Edited PR comments are not readiness work. Hold them while the PR waits or counts down, and show
+// each once on any other action (including MERGE after the ready delay), writing its marker then.
+// The poll loop defers the write to the result it returns, since it can discard or refresh a tick.
+// A replayed cached report can carry edits already shown, so re-check the current markers.
+async function attachEditedComments(result, tick, opts) {
+    const candidates = tick.report?.comments.edited ?? [];
+    if (candidates.length === 0 || result.action === "wait" || result.action === "ready")
+        return result;
+    if (result.action === "cancel" && (result.reason === "merged" || result.reason === "closed"))
+        return result;
+    const [owner, repo] = result.repo.split("/");
+    if (!owner || !repo)
+        return result;
+    const key = { owner, repo, pr: result.pr };
+    const seen = await loadSeenMap(key);
+    const edited = candidates.filter((c) => classifyItem(c.id, c.body, seen) === "edited");
+    if (edited.length === 0)
+        return result;
+    const withEdits = { ...result, editedComments: edited };
+    return opts.deferEditedCommentMarkers ? withEdits : markEditedCommentsSeen(withEdits);
 }
-async function runIterateCore(opts) {
+async function runIterateCore(opts, tick) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
@@ -51,7 +77,9 @@ async function runIterateCore(opts) {
         // compatibility key in the config loader.
         autoResolve: true,
         autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
+        reviewOutputMaxChars: config.iterate.reviewOutputMaxChars,
     }, checkContext);
+    tick.report = report;
     const [repoOwner, repoName] = report.repo.split("/");
     if (!repoOwner || !repoName) {
         throw new ShepherdError(`Unexpected repo format: "${report.repo}" (expected "owner/name")`, EXIT.DATAERR);
@@ -79,7 +107,11 @@ async function runIterateCore(opts) {
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
-    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [...report.threads.actionable, ...report.threads.resolutionOnly], report.ruleAutoResolveReviewSummaryIds);
+    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [
+        ...report.threads.actionable,
+        ...report.threads.resolutionOnly,
+        ...(report.heldThreadReviewIds ?? []).map((reviewId) => ({ reviewId })),
+    ], report.ruleAutoResolveReviewSummaryIds);
     // Minimize already-seen review summaries in-process so they never become agent-facing work.
     // GitHub can still return a null/error/rate-limit result per ID without
     // throwing (autoMinimizeComments reports this via `errors`, not a rejection);
@@ -94,20 +126,16 @@ async function runIterateCore(opts) {
         if (unminimized.length > 0)
             reviewSummaryIds = [...reviewSummaryIds, ...unminimized];
     }
-    // A first look at an already-minimized comment is only an acknowledgment.
-    // A non-bot edit that no longer matches a noise rule may carry new feedback;
-    // it must restart the ready delay and void an existing READY receipt. Bots
-    // regenerate minimized summaries on their own, so their edits surface for
-    // acknowledgment without restarting the countdown.
-    const editedMinimizedFeedback = report.comments.firstLook.some((comment) => comment.isMinimized === true &&
-        comment.edited === true &&
-        !isConfiguredBotAuthor(comment, botUsernames));
-    const hasReadinessWork = report.threads.actionable.length > 0 ||
+    // A first look at an already-minimized comment is only an acknowledgment. Edited PR comments
+    // (report.comments.edited) are neither: they never block readiness or restart the ready delay.
+    // Review items held back by iterate.reviewOutputMaxChars keep the PR out of ready/merge: a
+    // capped tick that shows only first-look comments still counts, since held work follows.
+    const hasReadinessWork = (report.reviewItems !== undefined && report.comments.firstLook.length > 0) ||
+        report.threads.actionable.length > 0 ||
         report.threads.resolutionOnly.length > 0 ||
         report.threads.firstLook.length > 0 ||
         (report.threads.ruleAutoResolveIds?.length ?? 0) > 0 ||
         report.comments.actionable.length > 0 ||
-        editedMinimizedFeedback ||
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.changesRequestedReviews.length > 0 ||
         hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status) ||
@@ -128,7 +156,7 @@ async function runIterateCore(opts) {
         !hasReadinessWork &&
         !activeMerge &&
         staleAncestry === null;
-    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork, editedMinimizedFeedback, checkContext);
+    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
@@ -400,7 +428,7 @@ async function recordReadyReceipt(key, report, context) {
     }
 }
 /** Clear a stale READY receipt; return whether a current receipt remains. */
-async function revalidateReadyReceipt(key, report, hasReadinessWork, editedMinimizedFeedback, context) {
+async function revalidateReadyReceipt(key, report, hasReadinessWork, context) {
     const receipt = await readReadyReceipt(key);
     if (!receipt)
         return false;
@@ -413,7 +441,6 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork, editedMinim
         !report.headSha ||
         !report.baseRefOid ||
         transportReadinessGaps(report, report.mergeStatus.mergeStateStatus).length > 0 ||
-        editedMinimizedFeedback ||
         (!retainQueuedReceipt && (report.status !== "READY" || hasReadinessWork))) {
         await clearReadyReceipt(key);
         return false;

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

@@ -8,6 +8,6 @@ import type { InstructionStyle } from "../../config/load.mts";
  */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, _cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], _inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
+isBehind?: boolean, _viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection?: QueueEjectionRecovery, // current merge-queue removal with failing queue checks
 instructionStyle?: InstructionStyle): string[];

package/bin/commands/iterate/render.mjs

@@ -1,12 +1,11 @@
-import { renderShellCommand } from "../../cli/runner.mjs";
+import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildRepeatedWorkflowBranchRecoveryInstructions, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
-import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 import { partitionFixThreads } from "./fix-instruction-threads.mjs";
 import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
 import { queueEjectionSteps } from "./queue-recovery-instructions.mjs";
-import { buildPushJournalSteps } from "./fix-loop-instruction.mjs";
+import { buildPushSteps } from "./fix-loop-instruction.mjs";
 /**
  * Render a resolve command as a shell snippet. Appends `--require-sha HEAD` when set: run after
  * the push step, the local HEAD is the pushed PR head, and `apply review` rejects the mutations
@@ -18,7 +17,7 @@ export function renderResolveCommand(rc) {
 }
 const REQUIRE_HEAD_SHA = "--require-sha HEAD";
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, _cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], _inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
+isBehind = false, _viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection, // current merge-queue removal with failing queue checks
 instructionStyle = "inline") {
     const instructions = [];
@@ -48,12 +47,9 @@ instructionStyle = "inline") {
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0)
         instructions.push("Review every item under `## First-look items` before acting.");
-    if (firstLookSummaries.length > 0 && viewerCanUpdate)
-        instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
-    const editedTotal = editedSummaries.length +
-        actionableComments.filter((c) => c.edited).length +
-        firstLookThreads.filter((t) => t.edited).length +
-        firstLookComments.filter((c) => c.edited).length;
+    if (firstLookSummaries.length > 0)
+        instructions.push("Read each body under `## Review summaries (first look)` before acting.");
+    const editedTotal = editedSummaries.length + firstLookThreads.filter((t) => t.edited).length;
     if (editedTotal > 0)
         instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
     if (unlocatedThreads.length > 0)
@@ -72,19 +68,24 @@ instructionStyle = "inline") {
         instructions.push(staleClause);
     if (!hintWithConflictStep)
         instructions.push(...branchUpdateHint);
+    const hasReviewFeedback = threads.length > 0 ||
+        resolutionOnlyThreads.length > 0 ||
+        firstLookThreads.length > 0 ||
+        changesRequestedReviews.length > 0 ||
+        actionableComments.length > 0 ||
+        firstLookSummaries.length > 0 ||
+        editedSummaries.length > 0;
+    if (hasReviewFeedback) {
+        const journalCommand = buildPrShepherdCommand(["apply", "journal", String(prReference)]).text;
+        instructions.push(`Optional: If you reject a code review suggestion, journal why: \`${journalCommand} '- <reason>'\`.`);
+    }
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     const genericPush = !(branchRecovery || queueEjection) && hasNonConflictHints;
-    const wantsJournal = viewerCanUpdate &&
-        (hasReviewMutations ||
-            hasNonConflictHints ||
-            firstLookTotal > 0 ||
-            firstLookSummaries.length > 0 ||
-            editedTotal > 0);
     if (branchRecovery || queueEjection) {
         instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, !branchRecovery));
     }
-    instructions.push(...buildPushJournalSteps(instructionStyle, prReference, genericPush, wantsJournal));
+    instructions.push(...buildPushSteps(instructionStyle, genericPush));
     if (resolveOnlyCommand?.hasMutations)
         instructions.push(`Run: \`${renderResolveCommand(resolveOnlyCommand)}\``);
     instructions.push(...buildResolveCommandInstruction(resolveCommand, renderResolveCommand(resolveCommand)), buildFixCompletionInstruction());

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

@@ -27,7 +27,7 @@ export function onePrCancelFromPulls(explicit, repoSlug, pulls) {
         isDraft: pull.draft,
         shouldCancel: true,
         remainingSeconds: 0,
-        summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 0, superseded: 0 },
+        summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 0, queued: 0, superseded: 0 },
         baseBranch: pull.baseRefName,
         branchProtection: null,
         checks: [],

package/bin/commands/poll-seen-options.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Seen-state options for one poll tick. The loop can discard or refresh a tick's result, so
+ * edited-comment markers are written only for the result it returns.
+ */
+export declare function pollTickSeenOptions(debounceSeconds: number, pastDebounce: boolean): {
+    persistSeen: boolean;
+    deferEditedCommentMarkers: boolean;
+};

package/bin/commands/poll-seen-options.mjs

@@ -0,0 +1,7 @@
+/**
+ * Seen-state options for one poll tick. The loop can discard or refresh a tick's result, so
+ * edited-comment markers are written only for the result it returns.
+ */
+export function pollTickSeenOptions(debounceSeconds, pastDebounce) {
+    return { persistSeen: debounceSeconds === 0 || pastDebounce, deferEditedCommentMarkers: true };
+}

package/bin/commands/poll.mjs

@@ -1,4 +1,6 @@
 import { runIterate } from "./iterate/index.mjs";
+import { pollTickSeenOptions } from "./poll-seen-options.mjs";
+import { markEditedCommentsSeen } from "./iterate/edited-comment-markers.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
 import { loadConfig } from "../config/load.mjs";
@@ -26,6 +28,7 @@ async function runPollCore(opts) {
     const verbose = opts.verbose === true;
     const quietStatus = quietStatusOpt === true;
     const untilTerminal = untilTerminalOpt === true;
+    const swallowsMarkReady = untilTerminal || iterateOpts.merge === true;
     let lastWaitSignature = null;
     let pendingQuotaWarning;
     let prNumber = opts.prNumber;
@@ -34,6 +37,7 @@ async function runPollCore(opts) {
     while (true) {
         tick += 1;
         const pastDebounce = debounceUntil !== null && Date.now() >= debounceUntil;
+        const seenOptions = pollTickSeenOptions(debounceSeconds, pastDebounce);
         const remainingBefore = untilTerminal
             ? Number.POSITIVE_INFINITY
             : timeoutMs - (Date.now() - start);
@@ -41,7 +45,7 @@ async function runPollCore(opts) {
         const iterateTick = (fingerprintCache) => runIterate({
             ...iterateOpts,
             prNumber,
-            persistSeen: debounceSeconds === 0 || pastDebounce,
+            ...seenOptions,
             fingerprintCache,
             deferQuotaWarning: !untilTerminal,
             quotaWarningMinimumPollIntervalMinutes: intervalSeconds / 60,
@@ -123,9 +127,7 @@ async function runPollCore(opts) {
             await sleep(sleepMs);
             continue;
         }
-        if ((untilTerminal || iterateOpts.merge) &&
-            lastResult.action === "mark_ready" &&
-            !pastDebounce) {
+        if (swallowsMarkReady && lastResult.action === "mark_ready" && !pastDebounce) {
             debounceUntil = null;
             const elapsedMs = Date.now() - start;
             const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS, getGithubTransport());
@@ -153,5 +155,5 @@ async function runPollCore(opts) {
         await refreshIfReturning();
         break;
     }
-    return lastResult;
+    return markEditedCommentsSeen(lastResult);
 }