pr-shepherd 0.46.5 → 0.46.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.46.5",
+  "version": "0.46.6",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -2,6 +2,8 @@
 
 Autonomous PR CI monitor and review-comment resolver for agentic coding tools, including Claude Code and Codex.
 
+**[jongleberry.com/pr-shepherd](https://jongleberry.com/pr-shepherd/)** — the why and the principles behind the design, for humans and agents.
+
 ## Why
 
 An agent finishing a PR should think about code, not reconstruct GitHub state or invent a next-step policy each tick. Without Shepherd it fans out across GitHub MCP, `gh`, and GraphQL, then guesses what to do with the result.
@@ -88,6 +90,7 @@ This system is opinionated and works best with PRs that use required status chec
 - Shepherd identifies its own latest reply only when that comment begins `<!-- pr-shepherd -->`, not from author equality. A marked viewer-authored thread can be resolved without another reply as a retry.
 - Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
+- With `--merge`, actionable review threads/comments/reviews/summaries are held back (`WAIT`, with raw deferred-work counts) while a PR sits in the merge queue, since a Shepherd-initiated push would eject it; set `actions.workWhileQueued: true` to act on them immediately instead. Failing checks and merge conflicts are never deferred.
 - The CLI never performs git mutations itself — it only emits commit/push instructions for the agent to run. Push access to the PR head is a usage precondition; GitHub viewer fields do not create a separate push-authorization handoff.
 - Generated iterate mutations and automatic actions are capability-aware and omit unauthorized commands. Explicit `apply` operations honor the caller's intent and surface GitHub's result; semantic human-content protections still apply.
 - `build_suggestion_patches` turns one or more ordered GitHub suggestion threads into checked patches and commit metadata, but never edits the working tree or git history. Local HEAD may be ahead when the live PR head is its ancestor.

package/bin/api.d.mts

@@ -8,7 +8,7 @@ export interface CreatePrShepherdOptions {
 }
 /** A positive PR number, GitHub pull-request URL, or owner/repo#number reference. */
 export type PrReference = number | string;
-export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository"> & {
+export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "deferQuotaWarning"> & {
     pr?: PrReference;
 };
 export interface ReviewMutationsOperation {

package/bin/checks/triage.mjs

@@ -1,6 +1,7 @@
 /* eslint-disable max-lines */
 import { restWithRateLimit, restText } from "../github/http.mjs";
 import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
+import { loadConfig } from "../config/load.mjs";
 const STARTUP_FAILURE_STATUS = "startup_failure";
 const LOG_EXCERPT_CONTEXT_LINES = 16;
 const LOG_EXCERPT_TAIL_LINES = 28;
@@ -181,10 +182,11 @@ async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false) {
     }
 }
 function buildLogExcerpt(raw) {
+    const ignorePatterns = compileIgnoreLogLinePatterns();
     const lines = raw
         .split(/\r?\n/)
         .map(cleanLogLine)
-        .filter((line) => line.trim() !== "");
+        .filter((line) => line.trim() !== "" && !isNoiseLine(line, ignorePatterns));
     if (lines.length === 0)
         return undefined;
     const aggregateExcerpt = buildAggregateJobResultsExcerpt(lines);
@@ -276,6 +278,15 @@ function truncateAnchoredExcerpt(lines, anchorIndex) {
         return text;
     return truncateLogExcerpt(`${TRUNCATED_SUFFIX.trim()}\n${lines.slice(anchorIndex).join("\n")}`);
 }
+// User-configured via `checks.ignoreLogLines` (regex source strings) — empty by
+// default. What counts as noise varies by CI toolchain, so Shepherd ships no
+// built-in patterns; a project opts in via `.pr-shepherdrc.yml`.
+function compileIgnoreLogLinePatterns() {
+    return loadConfig().checks.ignoreLogLines.map((pattern) => new RegExp(pattern));
+}
+function isNoiseLine(line, patterns) {
+    return patterns.some((re) => re.test(line));
+}
 function cleanLogLine(line) {
     return line
         .replace(/^\uFEFF/, "")

package/bin/cli/body-truncate.d.mts

@@ -0,0 +1,12 @@
+export declare const BODY_TRUNCATE_MAX_CHARS = 1200;
+export declare const NESTED_BODY_TRUNCATE_MAX_CHARS = 600;
+/**
+ * Truncates `body` to roughly `maxChars`, keeping a head and tail portion so an
+ * opening question and a trailing summary both survive. Never cuts inside a
+ * ``` or ~~~ fence: the cut points snap outward to the nearest fence-safe line
+ * boundary — an unbalanced fence here would swallow every section rendered
+ * after it in the same tick. A single line too long to fit a budget on its own
+ * (headEnd stays -1, or no line fits from the tail) falls back to a
+ * character-level slice of that line rather than dropping it entirely.
+ */
+export declare function truncateBody(body: string, maxChars: number, url?: string): string;

package/bin/cli/body-truncate.mjs

@@ -0,0 +1,123 @@
+const HEAD_FRACTION = 0.7;
+export const BODY_TRUNCATE_MAX_CHARS = 1200;
+export const NESTED_BODY_TRUNCATE_MAX_CHARS = 600;
+function fenceOpener(trimmed) {
+    const char = trimmed[0];
+    if (char !== "`" && char !== "~")
+        return null;
+    let len = 0;
+    while (trimmed[len] === char)
+        len++;
+    return len >= 3 ? { char, len } : null;
+}
+function isFenceCloser(trimmed, fence) {
+    return trimmed.length >= fence.len && [...trimmed].every((c) => c === fence.char);
+}
+// Backtick and tilde fences close only against their own kind — a run of one
+// character never closes a fence opened with the other (CommonMark semantics).
+function fenceStatesAfterEachLine(lines) {
+    const states = [];
+    let fence = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (fence) {
+            if (isFenceCloser(trimmed, fence))
+                fence = null;
+        }
+        else {
+            fence = fenceOpener(trimmed);
+        }
+        states.push(fence !== null);
+    }
+    return states;
+}
+function cumulativeLengths(lines) {
+    const out = [];
+    let total = 0;
+    for (const line of lines) {
+        total += line.length + 1;
+        out.push(total);
+    }
+    return out;
+}
+/** Last line index keepable within `budget`, extended forward past any fence still open at that point. */
+function findHeadEnd(states, cumLens, budget) {
+    let end = -1;
+    for (let i = 0; i < cumLens.length; i++) {
+        if (cumLens[i] > budget)
+            break;
+        end = i;
+    }
+    while (end >= 0 && end < states.length - 1 && states[end])
+        end++;
+    return end;
+}
+/** First line index keepable within `budget` counted from the end, extended backward past any fence open entering it. */
+function findTailStart(states, cumLens, budget) {
+    const n = cumLens.length;
+    const total = cumLens[n - 1] ?? 0;
+    let start = n;
+    for (let j = n - 1; j >= 0; j--) {
+        const suffixLen = total - (j > 0 ? cumLens[j - 1] : 0);
+        if (suffixLen > budget)
+            break;
+        start = j;
+    }
+    while (start > 0 && states[start - 1])
+        start--;
+    return start;
+}
+const REVIEW_COMMENT_URL_RE = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/\d+#discussion_r(\d+)$/;
+const ISSUE_COMMENT_URL_RE = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/(?:pull|issues)\/\d+#issuecomment-(\d+)$/;
+// An agent can run this directly — no browser round-trip — to read the full body.
+function commentViewCommand(url) {
+    const review = REVIEW_COMMENT_URL_RE.exec(url);
+    if (review) {
+        const [, owner, repo, id] = review;
+        return `gh api repos/${owner}/${repo}/pulls/comments/${id}`;
+    }
+    const issue = ISSUE_COMMENT_URL_RE.exec(url);
+    if (issue) {
+        const [, owner, repo, id] = issue;
+        return `gh api repos/${owner}/${repo}/issues/comments/${id}`;
+    }
+    return undefined;
+}
+function elisionMarker(charCount, url) {
+    const pointer = url ? (commentViewCommand(url) ?? url) : undefined;
+    return pointer
+        ? `[…${charCount} chars elided — full text: ${pointer}]`
+        : `[…${charCount} chars elided]`;
+}
+/**
+ * Truncates `body` to roughly `maxChars`, keeping a head and tail portion so an
+ * opening question and a trailing summary both survive. Never cuts inside a
+ * ``` or ~~~ fence: the cut points snap outward to the nearest fence-safe line
+ * boundary — an unbalanced fence here would swallow every section rendered
+ * after it in the same tick. A single line too long to fit a budget on its own
+ * (headEnd stays -1, or no line fits from the tail) falls back to a
+ * character-level slice of that line rather than dropping it entirely.
+ */
+export function truncateBody(body, maxChars, url) {
+    if (body.length <= maxChars)
+        return body;
+    const lines = body.split("\n");
+    const states = fenceStatesAfterEachLine(lines);
+    const cumLens = cumulativeLengths(lines);
+    const headBudget = Math.ceil(maxChars * HEAD_FRACTION);
+    const tailBudget = maxChars - headBudget;
+    const headEnd = findHeadEnd(states, cumLens, headBudget);
+    const tailStart = findTailStart(states, cumLens, tailBudget);
+    if (tailStart <= headEnd + 1)
+        return body;
+    const head = headEnd >= 0 ? lines.slice(0, headEnd + 1).join("\n") : lines[0].slice(0, headBudget);
+    const tail = tailStart < lines.length
+        ? lines.slice(tailStart).join("\n")
+        : tailBudget > 0
+            ? lines[lines.length - 1].slice(-tailBudget)
+            : "";
+    const elidedChars = body.length - head.length - tail.length;
+    if (elidedChars <= 0)
+        return body;
+    return [head, elisionMarker(elidedChars, url), tail].join("\n\n");
+}

package/bin/cli/fix-formatter-extra.d.mts

@@ -1,3 +1,4 @@
 import type { CheckAnnotation, IterateResultFixCode } from "../types.mts";
-export declare function renderCheckAnnotation(a: CheckAnnotation): string;
+/** Returns null when the annotation adds nothing beyond the check's own conclusion tag. */
+export declare function renderCheckAnnotation(a: CheckAnnotation, logExcerpt?: string): string | null;
 export declare function renderProtectedRun(run: IterateResultFixCode["fix"]["protectedRuns"][number]): string;

package/bin/cli/fix-formatter-extra.mjs

@@ -1,15 +1,30 @@
 import { blockquote } from "./list-formatters.mjs";
-export function renderCheckAnnotation(a) {
+// A bare "Process completed with exit code N." on its own carries nothing beyond
+// the check's own [conclusion: FAILURE] tag, so the whole annotation is dropped.
+const TRIVIAL_EXIT_CODE_RE = /^Process completed with exit code \d+\.?$/;
+/** Returns null when the annotation adds nothing beyond the check's own conclusion tag. */
+export function renderCheckAnnotation(a, logExcerpt) {
+    const hasRawDetails = a.rawDetails !== undefined && a.rawDetails.trim() !== "";
+    const hasTitle = a.title !== undefined && a.title.trim() !== "";
+    if (TRIVIAL_EXIT_CODE_RE.test(a.message.trim()) && !hasRawDetails && !hasTitle)
+        return null;
     const loc = `${a.path}:${renderAnnotationRange(a)}`;
     const link = a.blobUrl ? ` [↗](${a.blobUrl})` : "";
     const title = a.title ? ` — ${a.title}` : "";
     const lines = [`- \`${a.id}\`${link} \`${loc}\` [${a.level}]${title}`];
-    if (a.message.trim() !== "")
+    if (a.message.trim() !== "" && !duplicatesLog(a.message, logExcerpt)) {
         lines.push(blockquote(a.message));
-    if (a.rawDetails !== undefined && a.rawDetails.trim() !== "")
+    }
+    if (hasRawDetails && !duplicatesLog(a.rawDetails, logExcerpt)) {
         lines.push(blockquote(a.rawDetails));
+    }
     return lines.join("\n");
 }
+// The bullet's path:line + blob link already anchors this text; if the identical
+// text is also in the check's log excerpt, only the blockquote body is redundant.
+function duplicatesLog(text, logExcerpt) {
+    return logExcerpt !== undefined && logExcerpt.includes(text.trim());
+}
 export function renderProtectedRun(run) {
     const label = run.workflowName
         ? `${run.workflowName} (${run.checkNames.join(", ")})`

package/bin/cli/fix-formatter.d.mts

@@ -1,2 +1,4 @@
 import type { IterateResultFixCode } from "../types.mts";
-export declare function formatFixCodeResult(header: string, result: IterateResultFixCode): string;
+export declare function formatFixCodeResult(header: string, result: IterateResultFixCode, opts?: {
+    verbose?: boolean;
+}): string;

package/bin/cli/fix-formatter.mjs

@@ -3,11 +3,14 @@ import { renderResolveCommand } from "../commands/iterate/render.mjs";
 import { inlineCode, joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
+import { BODY_TRUNCATE_MAX_CHARS } from "./body-truncate.mjs";
 import { numberInstructions } from "./iterate-instructions.mjs";
 import { renderCheckAnnotation, renderProtectedRun } from "./fix-formatter-extra.mjs";
 import { isFailingAgentCheck } from "../checks/conclusions.mjs";
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
-export function formatFixCodeResult(header, result) {
+export function formatFixCodeResult(header, result, opts = {}) {
+    const verbose = opts.verbose ?? false;
+    const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
     const sections = [header];
     const renderThreads = (heading, threads) => {
         if (threads.length === 0)
@@ -21,7 +24,7 @@ export function formatFixCodeResult(header, result) {
             const suggestionMarker = t.suggestion ? " [suggestion]" : "";
             const editedMarker = t.edited ? " [edited since first look]" : "";
             sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType, t.authorAssociation, t.viewerDidAuthor)})${reviewMarker}${suggestionMarker}${editedMarker}`);
-            sections.push(renderThreadConversation(t));
+            sections.push(renderThreadConversation(t, verbose));
             if (t.suggestion) {
                 sections.push(renderSuggestionBlock(t.suggestion, ""));
             }
@@ -34,7 +37,7 @@ export function formatFixCodeResult(header, result) {
     if (result.fix.resolutionOnlyThreads.length > 0) {
         sections.push("## Review threads to resolve");
         sections.push(result.fix.resolutionOnlyThreads
-            .map((t) => renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t) }))
+            .map((t) => renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t), verbose }))
             .join("\n"));
     }
     if (result.fix.actionableComments.length > 0) {
@@ -44,7 +47,7 @@ export function formatFixCodeResult(header, result) {
             const editedMarker = c.edited ? " [edited since first look]" : "";
             const authorizationMarker = c.viewerCanMinimize === false ? " [viewer cannot minimize]" : "";
             sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${authorizationMarker}${editedMarker}`);
-            sections.push(blockquote(c.body));
+            sections.push(blockquote(c.body, topCap, c.url));
         }
     }
     const failingChecks = result.fix.checks.filter((ch) => isFailingAgentCheck(ch));
@@ -87,10 +90,17 @@ export function formatFixCodeResult(header, result) {
         });
         sections.push(bullets.join("\n\n"));
     }
-    const checksWithAnnotations = result.fix.checks.filter((ch) => (ch.annotations?.length ?? 0) > 0);
-    if (checksWithAnnotations.length > 0) {
+    const annotatedChecks = result.fix.checks
+        .map((ch) => ({
+        ch,
+        rendered: (ch.annotations ?? [])
+            .map((a) => renderCheckAnnotation(a, ch.logExcerpt))
+            .filter((s) => s !== null),
+    }))
+        .filter(({ rendered }) => rendered.length > 0);
+    if (annotatedChecks.length > 0) {
         sections.push("## Check annotations");
-        for (const ch of checksWithAnnotations) {
+        for (const { ch, rendered } of annotatedChecks) {
             const workflowPrefix = ch.workflowName ? `${ch.workflowName} › ` : "";
             const jobLabel = ch.jobName ? ch.jobName : ch.name;
             const locator = ch.runId
@@ -99,25 +109,41 @@ export function formatFixCodeResult(header, result) {
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
             sections.push(`### ${locator} — \`${workflowPrefix}${jobLabel}\``);
-            sections.push(ch.annotations.map(renderCheckAnnotation).join("\n\n"));
+            sections.push(rendered.join("\n\n"));
         }
     }
     if (result.fix.changesRequestedReviews.length > 0) {
         sections.push("## Changes-requested reviews");
-        sections.push(result.fix.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
+        for (const r of result.fix.changesRequestedReviews) {
+            // A stale bot CR that already had its full body surfaced on a prior tick stays a terse
+            // one-line reminder (renderReviewBullet's staleBotCr branch) — repeating the full body
+            // every tick would be noise, not new content. Every other review (a bot CR's first
+            // emission, or any human CR) gets the same H3 + blockquote shape as the sibling
+            // review-summary/approval sections below, so the agent actually has a body to read —
+            // the bare bullet this replaced only ever rendered the reviewId, never the body.
+            if (r.staleBotCr) {
+                sections.push(renderReviewBullet(r));
+                continue;
+            }
+            const staleTag = r.staleReview
+                ? " [stale — review is on an old commit, all threads resolved; ask reviewer to re-review or dismiss]"
+                : "";
+            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})${staleTag}`);
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
+        }
     }
     if (result.fix.firstLookSummaries.length > 0) {
         sections.push("## Review summaries (first look)");
         for (const r of result.fix.firstLookSummaries) {
             sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})${r.viewerCanMinimize === false ? " [viewer cannot minimize]" : ""}`);
-            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
         }
     }
     if (result.fix.editedSummaries.length > 0) {
         sections.push("## Review summaries (edited since first look — already minimized; do not re-minimize)");
         for (const r of result.fix.editedSummaries) {
             sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})${r.viewerCanMinimize === false ? " [viewer cannot minimize]" : ""}`);
-            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
         }
     }
     const firstLookSummaryIds = new Set(result.fix.firstLookSummaries.map((r) => r.id));
@@ -130,14 +156,14 @@ export function formatFixCodeResult(header, result) {
         sections.push("## Approvals (surfaced — not minimized)");
         for (const r of result.fix.surfacedApprovals) {
             sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})${r.viewerCanMinimize === false ? " [viewer cannot minimize]" : ""}`);
-            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
         }
     }
     const firstLookTotal = result.fix.firstLookThreads.length + result.fix.firstLookComments.length;
     if (firstLookTotal > 0) {
         sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
         const resolutionOnlyIds = new Set(result.fix.resolutionOnlyThreads.map((t) => t.id));
-        sections.push(buildFirstLookBullets(result.fix.firstLookThreads, resolutionOnlyIds, result.fix.firstLookComments).join("\n"));
+        sections.push(buildFirstLookBullets(result.fix.firstLookThreads, resolutionOnlyIds, result.fix.firstLookComments, verbose).join("\n"));
     }
     if (result.fix.inProgressRunIds.length > 0) {
         sections.push("## In-progress runs");

package/bin/cli/iterate-checks-formatter.mjs

@@ -14,7 +14,7 @@ function formatRelevantCheck(check) {
     const lines = [`- \`${workflow}${job}\` [conclusion: ${check.conclusion}]`];
     appendCheckFields(lines, check);
     appendLogExcerpt(lines, check.logExcerpt);
-    appendAnnotations(lines, check.annotations);
+    appendAnnotations(lines, check.annotations, check.logExcerpt);
     return lines;
 }
 function appendCheckFields(lines, check) {
@@ -43,13 +43,15 @@ function appendLogExcerpt(lines, logExcerpt) {
     for (const line of logExcerpt.split("\n"))
         lines.push(`  > ${line}`);
 }
-function appendAnnotations(lines, annotations) {
-    if (!annotations || annotations.length === 0)
+function appendAnnotations(lines, annotations, logExcerpt) {
+    const rendered = (annotations ?? [])
+        .map((a) => renderCheckAnnotation(a, logExcerpt))
+        .filter((s) => s !== null);
+    if (rendered.length === 0)
         return;
     lines.push("  - annotations:");
-    for (const annotation of annotations) {
-        for (const line of renderCheckAnnotation(annotation).split("\n")) {
+    for (const text of rendered) {
+        for (const line of text.split("\n"))
             lines.push(`    ${line}`);
-        }
     }
 }

package/bin/cli/iterate-formatter.mjs

@@ -3,7 +3,7 @@ import { formatRelevantChecks } from "./iterate-checks-formatter.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, } from "./iterate-instructions.mjs";
 import { formatMergeRequirementLines } from "../merge-status/requirements-format.mjs";
-import { appendMergeQueueHeader, formatMergeAction } from "./iterate-merge-formatter.mjs";
+import { appendMergeQueueHeader, formatDeferredWorkLine, formatMergeAction, } from "./iterate-merge-formatter.mjs";
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { formatActivityLine } from "./iterate-activity-formatter.mjs";
 /**
@@ -115,13 +115,13 @@ export function formatIterateResult(result, opts) {
     const verboseChecks = verbose ? formatRelevantChecks(result.checks) : null;
     const telemetrySections = [quotaWarning, apiUsage, verboseChecks];
     switch (result.action) {
-        case "wait":
-            return joinSections([
-                header,
-                ...telemetrySections,
-                adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
-            ]);
+        case "wait": {
+            const waitLines = [header, ...telemetrySections, adaptIterateLog(result.log)];
+            if (result.deferredWork)
+                waitLines.push(formatDeferredWorkLine(result.deferredWork));
+            waitLines.push(`## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`);
+            return joinSections(waitLines);
+        }
         case "mark_ready":
             return joinSections([
                 header,
@@ -147,6 +147,7 @@ export function formatIterateResult(result, opts) {
                 const supersededStr = result.supersededNames.map((n) => "`" + n + "`").join(", ");
                 cancelHeaderLines.push(`**superseded** ${supersededStr}`);
             }
+            appendMergeQueueHeader(cancelHeaderLines, result);
             if (activityLine)
                 cancelHeaderLines.push(activityLine);
             return joinSections([
@@ -166,6 +167,6 @@ export function formatIterateResult(result, opts) {
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
         case "fix_code":
-            return formatFixCodeResult(joinSections([header, ...telemetrySections]), result);
+            return formatFixCodeResult(joinSections([header, ...telemetrySections]), result, { verbose });
     }
 }

package/bin/cli/iterate-lean.mjs

@@ -23,6 +23,7 @@ export function projectIterateLean(result, opts) {
         status: result.status,
         state: result.state,
         mergeStateStatus: result.mergeStateStatus,
+        ...(result.mergeStatus !== "CLEAN" && { mergeStatus: result.mergeStatus }), // mergeStateStatus alone can't always reconstruct this
         ...(readyDelaySuffix && { readyDelayOverride: readyDelaySuffix }),
         ...(result.mergeStatus === "BLOCKED" &&
             result.reviewDecision !== null && { reviewDecision: result.reviewDecision }),
@@ -70,6 +71,7 @@ export function projectIterateLean(result, opts) {
         case "wait":
             return {
                 ...base,
+                ...(result.deferredWork && { deferredWork: result.deferredWork }),
                 log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };

package/bin/cli/iterate-merge-formatter.d.mts

@@ -1,3 +1,5 @@
-import type { IterateResult, IterateResultMerge } from "../types.mts";
+import type { IterateDeferredWork, IterateResult, IterateResultMerge } from "../types.mts";
+/** One inline rollup line of the non-CI work held back while the PR sits in the merge queue. */
+export declare function formatDeferredWorkLine(dw: IterateDeferredWork): string;
 export declare function appendMergeQueueHeader(lines: string[], result: IterateResult): void;
 export declare function formatMergeAction(header: string, result: IterateResultMerge): string;

package/bin/cli/iterate-merge-formatter.mjs

@@ -1,6 +1,21 @@
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 import { inlineCode, joinSections } from "../util/markdown.mjs";
 import { buildSimpleIterateInstructions, numberInstructions } from "./iterate-instructions.mjs";
+/** One inline rollup line of the non-CI work held back while the PR sits in the merge queue. */
+export function formatDeferredWorkLine(dw) {
+    const parts = [];
+    if (dw.threads > 0)
+        parts.push(`${dw.threads} thread${dw.threads === 1 ? "" : "s"}`);
+    if (dw.comments > 0)
+        parts.push(`${dw.comments} comment${dw.comments === 1 ? "" : "s"}`);
+    if (dw.changesRequestedReviews > 0) {
+        parts.push(`${dw.changesRequestedReviews} changes-requested review${dw.changesRequestedReviews === 1 ? "" : "s"}`);
+    }
+    if (dw.reviewSummaries > 0) {
+        parts.push(`${dw.reviewSummaries} review summar${dw.reviewSummaries === 1 ? "y" : "ies"}`);
+    }
+    return `**deferred (in merge queue)** ${parts.join(", ")}`;
+}
 export function appendMergeQueueHeader(lines, result) {
     const queue = result.mergeQueue;
     if (!queue)

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

@@ -35,9 +35,10 @@ export declare function renderThreadBullet(t: ThreadBulletInput, opts?: {
     renderSuggestion?: boolean;
     noBody?: boolean;
     suppressEditedMarker?: boolean;
+    verbose?: boolean;
 }): string;
-export declare function renderThreadConversation(t: ThreadBulletInput): string;
-export declare function blockquote(body: string): string;
+export declare function renderThreadConversation(t: ThreadBulletInput, verbose?: boolean): string;
+export declare function blockquote(body: string, maxChars?: number, url?: string): string;
 export declare function renderCommentBullet(c: {
     id: string;
     url?: string;
@@ -74,5 +75,5 @@ export declare function renderReviewListSection(heading: string, items: {
  * Threads that also appear in resolutionOnlyIds have their body suppressed
  * (already shown in `## Review threads to resolve`).
  */
-export declare function buildFirstLookBullets(firstLookThreads: FirstLookThread[], resolutionOnlyIds: Set<string>, firstLookComments: FirstLookComment[]): string[];
+export declare function buildFirstLookBullets(firstLookThreads: FirstLookThread[], resolutionOnlyIds: Set<string>, firstLookComments: FirstLookComment[], verbose?: boolean): string[];
 export {};

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/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/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/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 {};

package/bin/types/merge-queue.d.mts

@@ -11,3 +11,19 @@ export interface MergeQueueReport {
     /** The current PR head is not a parent of the removed synthetic queue commit. */
     headUpdatedAfterRemoval?: true;
 }
+/**
+ * Raw counts of actionable work held back while the PR sits in the merge queue
+ * (`actions.workWhileQueued` is `false`, the default) — a Shepherd-initiated push
+ * or mutation right now would eject the PR. Omitted entirely once every count is
+ * zero. Not emitted for checks/annotations/conflicts: those always surface via
+ * `fix_code` immediately regardless of queue membership.
+ */
+export interface IterateDeferredWork {
+    /** Unique review threads across actionable, resolution-only, first-look, and rule-auto-resolve. */
+    threads: number;
+    /** Unique PR comments across actionable, minimize-queued, and first-look. */
+    comments: number;
+    changesRequestedReviews: number;
+    /** Unique review summaries across the minimize queue, first-look, edited, and (if opted in) surfaced approvals. */
+    reviewSummaries: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.46.5",
+  "version": "0.46.6",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -12,7 +12,7 @@
     "github",
     "pull-request"
   ],
-  "homepage": "https://github.com/jonathanong/pr-shepherd",
+  "homepage": "https://jongleberry.com/pr-shepherd/",
   "bugs": {
     "url": "https://github.com/jonathanong/pr-shepherd/issues"
   },
@@ -67,12 +67,14 @@
     "knip": "knip",
     "knip:production": "knip --production",
     "lint:dead-code": "npm run --silent knip && npm run --silent knip:production",
-    "lint": "oxlint src/ test-helpers/ fixtures/*.mts test-cases/ plugins/ .agents/plugins/ && npm run --silent lint:dead-code",
-    "format": "oxfmt src/ test-helpers/ fixtures/*.mts test-cases/*.mts plugins/ .agents/plugins/ docs/ README.md",
-    "format:check": "oxfmt --check src/ test-helpers/ fixtures/*.mts test-cases/*.mts plugins/ .agents/plugins/ docs/ README.md",
+    "lint": "oxlint src/ test-helpers/ fixtures/*.mts test-cases/ plugins/ .agents/plugins/ site/build.mjs site/serve.mjs site/lib/ && npm run --silent lint:dead-code",
+    "format": "oxfmt src/ test-helpers/ fixtures/*.mts test-cases/*.mts plugins/ .agents/plugins/ docs/ README.md site/build.mjs site/serve.mjs site/lib/",
+    "format:check": "oxfmt --check src/ test-helpers/ fixtures/*.mts test-cases/*.mts plugins/ .agents/plugins/ docs/ README.md site/build.mjs site/serve.mjs site/lib/",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage && node scripts/strip-lcov-branches.mjs",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "site:build": "node site/build.mjs",
+    "site:serve": "node site/serve.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
@@ -86,6 +88,7 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
+    "marked": "^18.0.11",
     "oxfmt": "^0.64.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.46.5",
+  "version": "0.46.6",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.46.5", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.46.6", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.46.5", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.46.6", "pr-shepherd-mcp"]
   }
 }