pr-shepherd 0.46.4 → 0.46.6

package/bin/cli/list-formatters.mjs

@@ -1,5 +1,6 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
 import { threadComments } from "../threads/transcript.mjs";
+import { truncateBody, BODY_TRUNCATE_MAX_CHARS, NESTED_BODY_TRUNCATE_MAX_CHARS, } from "./body-truncate.mjs";
 const BODY_PREVIEW_MAX = 100;
 export function renderAuthor(author, authorType, authorAssociation, viewerDidAuthor) {
     return [`@${author}`, authorType, authorAssociation, viewerDidAuthor ? "viewer-authored" : null]
@@ -41,48 +42,54 @@ export function renderThreadBullet(t, opts = {}) {
     }
     const parts = [bulletLine];
     if (!opts.noBody) {
-        parts.push(renderThreadCommentBullets(t));
+        parts.push(renderThreadCommentBullets(t, opts.verbose));
     }
     if (t.suggestion && opts.renderSuggestion) {
         parts.push(renderSuggestionBlock(t.suggestion));
     }
     return parts.join("\n");
 }
-export function renderThreadConversation(t) {
-    if (!t.comments || t.comments.length === 0)
-        return blockquote(t.body);
+export function renderThreadConversation(t, verbose = false) {
+    const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
+    if (!t.comments || t.comments.length === 0) {
+        return blockquote(t.body, topCap, t.url);
+    }
+    const nestedCap = verbose ? undefined : NESTED_BODY_TRUNCATE_MAX_CHARS;
     return threadComments(t)
-        .map((c) => {
+        .map((c, i) => {
         const heading = c.id
             ? c.url
                 ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`
                 : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`
             : `#### (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`;
-        return `${heading}\n\n${blockquote(c.body)}`;
+        return `${heading}\n\n${blockquote(c.body, i === 0 ? topCap : nestedCap, c.url)}`;
     })
         .join("\n\n");
 }
-export function blockquote(body) {
-    return body
+export function blockquote(body, maxChars, url) {
+    const text = maxChars === undefined ? body : truncateBody(body, maxChars, url);
+    return text
         .replace(/\r\n/g, "\n")
         .split("\n")
         .map((line) => (line === "" ? ">" : `> ${line}`))
         .join("\n");
 }
-function renderThreadCommentBullets(t) {
+function renderThreadCommentBullets(t, verbose = false) {
+    const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
+    const nestedCap = verbose ? undefined : NESTED_BODY_TRUNCATE_MAX_CHARS;
     return threadComments(t)
-        .map((c) => {
+        .map((c, i) => {
         const link = c.url ? ` [↗](${c.url})` : "";
         const id = c.id ? `\`commentId=${c.id}\`` : "comment";
         return [
             `  - ${id}${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`,
-            indentBlockquote(c.body, "    "),
+            indentBlockquote(c.body, "    ", i === 0 ? topCap : nestedCap, c.url),
         ].join("\n");
     })
         .join("\n");
 }
-function indentBlockquote(body, indent) {
-    return blockquote(body)
+function indentBlockquote(body, indent, maxChars, url) {
+    return blockquote(body, maxChars, url)
         .split("\n")
         .map((line) => `${indent}${line}`)
         .join("\n");
@@ -118,13 +125,14 @@ export function renderReviewListSection(heading, items) {
  * Threads that also appear in resolutionOnlyIds have their body suppressed
  * (already shown in `## Review threads to resolve`).
  */
-export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, firstLookComments) {
+export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, firstLookComments, verbose = false) {
     const bullets = [];
     for (const t of firstLookThreads) {
         bullets.push(renderThreadBullet(t, {
             statusTag: renderFirstLookStatusTag(t),
             noBody: resolutionOnlyIds.has(t.id),
             suppressEditedMarker: true,
+            verbose,
         }));
     }
     for (const c of firstLookComments) {

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

@@ -1,6 +1,21 @@
 import { type AnnotationCacheOptions } from "../github/check-annotations.mts";
 import type { CheckAnnotation, ClassifiedCheck, ShepherdReport, TriagedCheck } from "../types.mts";
 export declare function checksWithActionableAnnotations(report: ShepherdReport): TriagedCheck[];
+/**
+ * True when GitHub itself is already acting on this PR regardless of Shepherd (a failing
+ * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
+ * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
+ * the seen-marker suppression gate there can't drift from the actual iterate dispatch
+ * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * seen markers must not be suppressed just because the PR happens to be queued).
+ */
+export declare function hasCheckDrivenActionableWork(checks: {
+    failing: TriagedCheck[];
+    passing: ClassifiedCheck[];
+    skipped: ClassifiedCheck[];
+    filtered: ClassifiedCheck[];
+    ignored?: TriagedCheck[];
+}, mergeStatusValue: string): boolean;
 export declare function attachAndMergeCheckAnnotations(buckets: {
     passing: ClassifiedCheck[];
     failing: TriagedCheck[];

package/bin/commands/check-annotations.mjs

@@ -2,6 +2,9 @@ import { fetchCheckRunAnnotations, } from "../github/check-annotations.mjs";
 function shouldFetchCheckAnnotations(check) {
     return check.id != null && check.status === "COMPLETED" && check.hasAnnotations === true;
 }
+function hasActionableAnnotation(check) {
+    return check.conclusion !== "SUCCESS" && (check.annotations?.length ?? 0) > 0;
+}
 export function checksWithActionableAnnotations(report) {
     return [
         ...report.checks.failing,
@@ -9,7 +12,26 @@ export function checksWithActionableAnnotations(report) {
         ...report.checks.skipped,
         ...report.checks.filtered,
         ...(report.checks.ignored ?? []),
-    ].filter((c) => c.conclusion !== "SUCCESS" && (c.annotations?.length ?? 0) > 0);
+    ].filter(hasActionableAnnotation);
+}
+/**
+ * True when GitHub itself is already acting on this PR regardless of Shepherd (a failing
+ * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
+ * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
+ * the seen-marker suppression gate there can't drift from the actual iterate dispatch
+ * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * seen markers must not be suppressed just because the PR happens to be queued).
+ */
+export function hasCheckDrivenActionableWork(checks, mergeStatusValue) {
+    return (checks.failing.length > 0 ||
+        [
+            ...checks.failing,
+            ...checks.passing,
+            ...checks.skipped,
+            ...checks.filtered,
+            ...(checks.ignored ?? []),
+        ].some(hasActionableAnnotation) ||
+        mergeStatusValue === "CONFLICTS");
 }
 export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber, cacheOpts) {
     const candidates = [

package/bin/commands/check.d.mts

@@ -4,4 +4,5 @@ export declare function runCheck(opts: GlobalOptions & {
     autoMinimizeSuppressed?: boolean;
     skipTriage?: boolean;
     persistSeen?: boolean;
+    merge?: boolean;
 }): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -7,7 +7,7 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { annotationMarkerBody, attachAndMergeCheckAnnotations } from "./check-annotations.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";
@@ -47,9 +47,16 @@ export async function runCheck(opts) {
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedPrChecks = classifyChecks(allChecks);
     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
+    // historical event forever. When GitHub omits the removed queue commit for that old event
+    // (e.g. after the synthetic commit is garbage collected), freshness is unverifiable — treat
+    // it as stale/updated rather than as still current, so Shepherd doesn't escalate
+    // `merge-queue-removed` permanently on data it can no longer check. The raw removal fields
+    // still render in the merge-queue header regardless of this flag.
     const headUpdatedAfterRemoval = Boolean(latestRemoval &&
-        latestRemoval.beforeCommitParentOids &&
-        !latestRemoval.beforeCommitParentOids.includes(batchData.headRefOid));
+        (!latestRemoval.beforeCommitParentOids ||
+            !latestRemoval.beforeCommitParentOids.includes(batchData.headRefOid)));
     const queueRawChecks = batchData.isInMergeQueue
         ? (batchData.mergeQueueChecks ?? [])
         : latestRemoval && !headUpdatedAfterRemoval
@@ -118,6 +125,51 @@ export async function runCheck(opts) {
     }
     const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames, batchData.viewerAuthorization?.viewerCanAdminister === true);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
+    const changesRequestedReviews = changesRequestedReviewVisibility.visible;
+    const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
+    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((review) => {
+        if (partition.suppressedChangesRequestedIds.has(review.id))
+            return false;
+        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
+        return (!isBot ||
+            batchData.viewerAuthorization?.viewerCanAdminister === true ||
+            visibleChangesRequestedIds.has(review.id));
+    }).length;
+    const approvedReviews = approvedReviewVisibility.visible;
+    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
+    // 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
+    // snapshot. A conflict newly discovered by this REST read is exactly the kind of check-driven
+    // signal that keeps a queued PR out of the deferral path.
+    if (status === "READY" && !didRefreshMergeability) {
+        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount);
+        batchData = refreshed.batchData;
+        mergeStatus = refreshed.mergeStatus;
+        status = refreshed.status;
+        if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
+            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        }
+    }
+    // Mirrors the deferral gate in commands/iterate/index.mts exactly (via the shared
+    // hasCheckDrivenActionableWork helper, so the two can't drift): when this tick's non-CI
+    // actionable work (threads/comments/review summaries/changes-requested) will be held back
+    // because the PR is queued, none of it was actually shown to the agent this tick —
+    // persisting seen markers for it now would make it silently vanish from every later tick
+    // once it's no longer "new" or "edited", even after the PR leaves the queue. A queued PR
+    // that also has check-driven work (failing checks, actionable annotations, conflicts) is
+    // NOT deferred — index.mts still renders these items via fix_code — so this must stay false
+    // in that case too, or their seen markers would be suppressed while actually being shown.
+    const deferWhileQueued = opts.merge === true &&
+        batchData.isInMergeQueue === true &&
+        config.actions.workWhileQueued !== true &&
+        !hasCheckDrivenActionableWork({
+            failing: merged.failing,
+            passing: merged.passing,
+            skipped: merged.skipped,
+            filtered: merged.filtered,
+            ignored: merged.ignored,
+        }, mergeStatus.status);
     if (opts.persistSeen !== false) {
         const successfulAnnotations = [
             ...merged.passing,
@@ -127,19 +179,24 @@ export async function runCheck(opts) {
         ]
             .filter((check) => check.conclusion === "SUCCESS")
             .flatMap((check) => check.annotations ?? []);
+        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)),
+                ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ];
         await Promise.allSettled([
             ...successfulAnnotations.map((a) => markSeen(stateKey, a.id, annotationMarkerBody(a))),
-            ...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)),
-            ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ...deferredMarkSeen,
             ...batchData.comments
-                .filter((c) => partition.suppressedCommentIds.has(c.id))
+                .filter((c) => partition.suppressedCommentIds.has(c.id) && !deniedRuleAutoResolveCommentIds.has(c.id))
                 .map((c) => markSeen(stateKey, c.id, c.body)),
             ...batchData.reviewThreads
-                .filter((t) => partition.suppressedThreadIds.has(t.id))
+                .filter((t) => partition.suppressedThreadIds.has(t.id) && !deniedRuleAutoResolveThreadIds.has(t.id))
                 .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
             ...batchData.reviewSummaries
                 .filter((r) => partition.suppressedReviewSummaryIds.has(r.id) &&
@@ -163,27 +220,6 @@ export async function runCheck(opts) {
         ...authorizedRuleAutoResolveThreadIds,
         ...[...deniedRuleAutoResolveThreadIds].filter((id) => visibleMutationThreadIds.has(id)),
     ];
-    const changesRequestedReviews = changesRequestedReviewVisibility.visible;
-    const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
-    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((review) => {
-        if (partition.suppressedChangesRequestedIds.has(review.id))
-            return false;
-        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
-        return (!isBot ||
-            batchData.viewerAuthorization?.viewerCanAdminister === true ||
-            visibleChangesRequestedIds.has(review.id));
-    }).length;
-    const approvedReviews = approvedReviewVisibility.visible;
-    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
-    if (status === "READY" && !didRefreshMergeability) {
-        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount);
-        batchData = refreshed.batchData;
-        mergeStatus = refreshed.mergeStatus;
-        status = refreshed.status;
-        if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
-            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
-        }
-    }
     const blockedByFilteredCheck = isBlockedByFilteredCheck(mergeStatus, verdict);
     const queueCommit = batchData.isInMergeQueue
         ? batchData.mergeQueueEntry?.headCommitOid

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

@@ -90,12 +90,12 @@ export function buildFailingCheckInstructions(checks) {
 }
 export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false) {
     if (hasConflicts)
-        return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate again with the same options.";
+        return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate immediately with the same options.";
     if (hasShaGatedReviewMutations) {
-        return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate again with the same options; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
+        return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate immediately with the same options; if you did not change code, complete the authorized review mutations and iterate immediately with the same options.";
     }
     if (checks.some((check) => check.rerunCommand)) {
-        return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate again with the same options to continue.";
+        return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate immediately with the same options to continue.";
     }
-    return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.";
+    return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate immediately with the same options to continue.";
 }

package/bin/commands/iterate/index.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { runCheck } from "../check.mjs";
 import { updateReadyDelay } from "../ready-delay.mjs";
 import { getCurrentPrNumber } from "../../github/client.mjs";
@@ -10,7 +11,7 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
-import { checksWithActionableAnnotations } from "../check-annotations.mjs";
+import { hasCheckDrivenActionableWork } from "../check-annotations.mjs";
 import { buildReadyMergeResult, handleActiveMergeState } from "./merge-state.mjs";
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
@@ -73,9 +74,7 @@ async function runIterateCore(opts) {
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.comments.firstLook.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
-        report.checks.failing.length > 0 ||
-        checksWithActionableAnnotations(report).length > 0 ||
-        report.mergeStatus.status === "CONFLICTS" ||
+        hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status) ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0 ||
@@ -85,7 +84,16 @@ async function runIterateCore(opts) {
     const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName);
     const base = buildIterateBase(report, readyState);
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
-    if (hasActionableWork) {
+    // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
+    // GitHub itself is already acting on — the queue will eject the PR for these regardless of
+    // what Shepherd does, so they always surface immediately. Only review threads/comments/
+    // changes-requested reviews/review summaries — the categories that would otherwise cause a
+    // Shepherd-initiated push while the PR sits safely in the queue — are eligible for deferral.
+    const checkDrivenActionableWork = hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status);
+    const deferWhileQueued = opts.merge === true &&
+        report.mergeQueue?.inQueue === true &&
+        config.actions.workWhileQueued !== true;
+    if (hasActionableWork && !(deferWhileQueued && !checkDrivenActionableWork)) {
         return handleFixCode({
             base,
             report,
@@ -110,6 +118,11 @@ async function runIterateCore(opts) {
         base,
         report,
         stallKey,
+        reviewSummaryIds,
+        firstLookSummaries,
+        editedSummaries,
+        surfacedApprovals,
+        minimizeApprovals: config.iterate.minimizeApprovals,
     });
     if (mergeStateResult)
         return mergeStateResult;

package/bin/commands/iterate/merge-state.d.mts

@@ -1,4 +1,4 @@
-import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+import type { IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
 type StallKey = {
     owner: string;
     repo: string;
@@ -11,5 +11,10 @@ export declare function handleActiveMergeState(input: {
     base: IterateResultBase;
     report: ShepherdReport;
     stallKey: StallKey;
+    reviewSummaryIds: string[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    surfacedApprovals: Review[];
+    minimizeApprovals: boolean;
 }): Promise<IterateResult | null>;
 export {};

package/bin/commands/iterate/merge-state.mjs

@@ -19,14 +19,55 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
         }),
     };
 }
+/** Raw counts of non-CI actionable work held back for one queued-PR wait tick. Omitted (all zero) when empty. */
+function buildDeferredWork(input) {
+    const { report, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, minimizeApprovals, } = input;
+    // These buckets are not disjoint (e.g. an unresolved outdated thread is both
+    // `resolutionOnly` and `firstLook`; an eligible-to-minimize comment/summary is both
+    // `actionable`/`firstLook` and queued in `minimizeIds`/`reviewSummaryIds`) — dedupe by ID.
+    const threadIds = new Set([
+        ...report.threads.actionable.map((t) => t.id),
+        ...report.threads.resolutionOnly.map((t) => t.id),
+        ...report.threads.firstLook.map((t) => t.id),
+        ...(report.threads.ruleAutoResolveIds ?? []),
+    ]);
+    const commentIds = new Set([
+        ...report.comments.actionable.map((c) => c.id),
+        ...(report.comments.minimizeIds ?? []),
+        ...report.comments.firstLook.map((c) => c.id),
+    ]);
+    const reviewSummaryIdSet = new Set([
+        ...reviewSummaryIds,
+        ...firstLookSummaries.map((r) => r.id),
+        ...editedSummaries.map((r) => r.id),
+        ...(minimizeApprovals ? surfacedApprovals.map((r) => r.id) : []),
+    ]);
+    const deferredWork = {
+        threads: threadIds.size,
+        comments: commentIds.size,
+        changesRequestedReviews: report.changesRequestedReviews.length,
+        reviewSummaries: reviewSummaryIdSet.size,
+    };
+    const total = deferredWork.threads +
+        deferredWork.comments +
+        deferredWork.changesRequestedReviews +
+        deferredWork.reviewSummaries;
+    return total > 0 ? deferredWork : undefined;
+}
 export async function handleActiveMergeState(input) {
     const { enabled, active, base, report, stallKey } = input;
+    const inQueue = report.mergeQueue?.inQueue === true;
     if (enabled && active) {
         await clearStallState(stallKey);
+        // Only the queued case ever holds back non-CI actionable work (see the `deferWhileQueued`
+        // gate in index.mts, which requires `inQueue === true`); an ordinary active auto-merge
+        // request with no queue membership never defers anything, so it never carries counts here.
+        const deferredWork = inQueue ? buildDeferredWork(input) : undefined;
         return {
             ...base,
             action: "wait",
-            log: report.mergeQueue?.inQueue
+            ...(deferredWork && { deferredWork }),
+            log: inQueue
                 ? `WAIT: PR #${report.pr} is in the merge queue`
                 : `WAIT: PR #${report.pr} has auto-merge enabled`,
         };

package/bin/commands/iterate/render.mjs

@@ -96,10 +96,10 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
         instructions.push(`Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`);
     }
     else if (hasRepeatedWorkflowBranchRecovery) {
-        instructions.push("Push the updated PR head branch before iterating again.");
+        instructions.push("Push the updated PR head branch before iterating immediately.");
     }
     else if (hasNonConflictHints) {
-        instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps.");
+        instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue with the remaining steps.");
     }
     if (viewerCanUpdate &&
         (hasReviewMutations ||

package/bin/config/load.d.mts

@@ -44,6 +44,8 @@ export interface PrShepherdConfig {
     };
     checks: {
         ciTriggerEvents: string[];
+        /** Regex patterns matched against each raw log line; matching lines are dropped from log excerpts. Empty by default — no lines are stripped unless configured. */
+        ignoreLogLines: string[];
     };
     mergeStatus: {
         blockingReviewerLogins: string[];
@@ -57,6 +59,14 @@ export interface PrShepherdConfig {
         autoMarkReady: boolean;
         /** Legacy-named patterns that keep matching Actions checks visible despite ignoreChecks. */
         neverCancelRuns: string[];
+        /**
+         * When `false` (default), `iterate --merge` defers non-CI actionable work
+         * (review threads, comments, changes-requested reviews, review summaries)
+         * while the PR sits in the merge queue, since a Shepherd-initiated push
+         * would eject it. When `true`, restores pre-existing behavior: actionable
+         * work is handled immediately regardless of queue membership.
+         */
+        workWhileQueued: boolean;
         /** @deprecated Accepted for compatibility, ignored by the loader. */
         autoResolveOutdated?: boolean;
         /** @deprecated Accepted for compatibility, ignored by the loader. */

package/bin/config/load.mjs

@@ -86,6 +86,20 @@ function parseNeverCancelRuns(value) {
     }
     return value;
 }
+function parseIgnoreLogLines(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid config: checks.ignoreLogLines must be an array of strings`);
+    }
+    for (const pattern of value) {
+        try {
+            new RegExp(pattern);
+        }
+        catch {
+            throw new Error(`Invalid config: checks.ignoreLogLines contains an invalid regular expression: ${pattern}`);
+        }
+    }
+    return value;
+}
 const SHEPHERD_OWNED_MERGE_FLAGS = [
     "--repo",
     "-R",
@@ -168,13 +182,14 @@ const KNOWN_NESTED_KEYS = {
     ]),
     watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
-    checks: new Set(["ciTriggerEvents"]),
+    checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),
     mergeStatus: new Set(["blockingReviewerLogins"]),
     merge: new Set(["commandArgs"]),
     actions: new Set([
         "autoMinimizeSuppressed",
         "autoMarkReady",
         "neverCancelRuns",
+        "workWhileQueued",
         "autoResolveOutdated",
         "commitSuggestions",
     ]),
@@ -261,6 +276,7 @@ export function loadConfig() {
             config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
         config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
+        config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
         configCache.set(cwd, config);
         return config;
     }

package/bin/config.json

@@ -36,7 +36,8 @@
     }
   },
   "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"]
+    "ciTriggerEvents": ["pull_request", "pull_request_target"],
+    "ignoreLogLines": []
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]
@@ -47,6 +48,7 @@
   "actions": {
     "autoMinimizeSuppressed": true,
     "autoMarkReady": true,
-    "neverCancelRuns": []
+    "neverCancelRuns": [],
+    "workWhileQueued": false
   }
 }

package/bin/mcp/server.mjs

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
 import { isRepositoryQualifiedPrReference } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
-import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
+import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
@@ -88,7 +88,13 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), formatIterateResult));
+    }, async (input) => {
+        // One options object feeds both channels so JSON and Markdown cannot drift.
+        const opts = {
+            readyDelaySuffix: input.readyDelaySeconds === undefined ? undefined : `${input.readyDelaySeconds}s`,
+        };
+        return runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), (result) => formatIterateResult(result, opts), (result) => projectIterateLean(result, opts));
+    });
     server.registerTool("apply", {
         description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
         inputSchema: applyInputSchema,
@@ -131,16 +137,22 @@ function readPackageVersion() {
     const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
     return packageJson.version;
 }
-function toolResult(result, text) {
+function toolResult(structured, text) {
     return {
         content: [{ type: "text", text }],
-        structuredContent: result,
+        structuredContent: structured,
     };
 }
-async function runTool(work, format) {
+/**
+ * `project` mirrors the CLI's `--format=json` treatment of the same result. Tools
+ * whose CLI JSON is the raw result object (apply, build_suggestion_patch(es) — see
+ * handlers.mts and cli-parser.mts, which JSON.stringify the result directly) omit
+ * `project` and return the result unchanged, matching their own CLI JSON output.
+ */
+async function runTool(work, format, project) {
     try {
         const result = await work();
-        return toolResult(result, format(result));
+        return toolResult(project ? project(result) : result, format(result));
     }
     catch (error) {
         return toolError(error);

package/bin/quota-warning.mjs

@@ -2,5 +2,5 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const interval = `${warning.pollIntervalMinutes}m`;
     const timeout = `${warning.pollTimeoutMinutes}m`;
     const resetTime = new Date(warning.resetAt * 1000).toISOString();
-    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). For the time being, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr checks\`, \`gh pr review\`, \`gh api\` REST endpoints) for PR operations — they draw on the separate REST budget, not the depleted GraphQL pool. Resume pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
+    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
 }

package/bin/types/iterate.d.mts

@@ -48,6 +48,7 @@ export interface IterateResultBase {
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
     log: string;
+    deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
 }
 export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
 interface IterateResultCancel extends IterateResultBase {
@@ -135,9 +136,18 @@ export interface IterateCommandOptions extends GlobalOptions {
     stallTimeoutSeconds?: number;
     /** Legacy per-invocation no-op retained for API compatibility. */
     neverCancelRuns?: string[];
+    /**
+     * Internal. `false` skips seen-marker writes (poll's discarded debounce ticks). Set
+     * only by `runPollCore`; excluded from the public `IterateInput` in api.mts.
+     */
     persistSeen?: boolean;
     /** Shepherd through readiness and emit the exact merge/queue command when ready. */
     merge?: boolean;
+    /**
+     * Internal. Defers attaching a quota warning until an until-terminal poll actually
+     * breaks. Set only by `runPollCore`; excluded from the public `IterateInput` in
+     * api.mts.
+     */
     deferQuotaWarning?: boolean;
 }
 export {};