pr-shepherd 0.59.3 → 0.60.1

package/bin/commands/iterate/index.mjs

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

package/bin/commands/iterate/render.mjs

@@ -49,10 +49,7 @@ instructionStyle = "inline") {
         instructions.push("Review every item under `## First-look items` before acting.");
     if (firstLookSummaries.length > 0)
         instructions.push("Read each body under `## Review summaries (first look)` before acting.");
-    const editedTotal = editedSummaries.length +
-        actionableComments.filter((c) => c.edited).length +
-        firstLookThreads.filter((t) => t.edited).length +
-        firstLookComments.filter((c) => c.edited).length;
+    const editedTotal = editedSummaries.length + firstLookThreads.filter((t) => t.edited).length;
     if (editedTotal > 0)
         instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
     if (unlocatedThreads.length > 0)

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

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

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

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

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

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

package/bin/commands/poll.mjs

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

package/bin/comments/review-output-budget.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Per-tick output budget for review items (see `iterate.reviewOutputMaxChars`).
+ *
+ * Fetching is complete; only the rendered volume is capped. When the bodies of every surfaced
+ * review item fit the budget, nothing changes. Otherwise items are taken in a fixed priority
+ * order — group by group, oldest first within a group — until the next item would exceed the
+ * budget (at least one item is always shown). Every other budgeted item is held: the caller
+ * omits it from the report, from generated mutation IDs, and from seen-marker writes, so a
+ * later tick shows it.
+ */
+/** One review item's identity, age, and rendered-body cost in characters. */
+export interface BudgetItem {
+    id: string;
+    createdAtUnix?: number;
+    cost: number;
+}
+/** Raw rollup emitted only when items were held: `shown` of `total` review items this tick. */
+export interface ReviewItemRollup {
+    shown: number;
+    total: number;
+}
+export interface ReviewOutputSelection {
+    /** False only for a budgeted item held back this tick. Unbudgeted IDs are always kept. */
+    keep: (id: string) => boolean;
+    rollup?: ReviewItemRollup;
+}
+/**
+ * Select which review items to show. `groups` is in priority order; an ID that appears in more
+ * than one group (e.g. a thread that is both resolution-only and first-look) is counted and
+ * charged once, in its first group. `maxChars <= 0` disables the cap.
+ */
+export declare function selectReviewOutput(groups: ReadonlyArray<ReadonlyArray<BudgetItem>>, maxChars: number): ReviewOutputSelection;

package/bin/comments/review-output-budget.mjs

@@ -0,0 +1,55 @@
+/**
+ * Per-tick output budget for review items (see `iterate.reviewOutputMaxChars`).
+ *
+ * Fetching is complete; only the rendered volume is capped. When the bodies of every surfaced
+ * review item fit the budget, nothing changes. Otherwise items are taken in a fixed priority
+ * order — group by group, oldest first within a group — until the next item would exceed the
+ * budget (at least one item is always shown). Every other budgeted item is held: the caller
+ * omits it from the report, from generated mutation IDs, and from seen-marker writes, so a
+ * later tick shows it.
+ */
+const KEEP_ALL = { keep: () => true };
+function oldestFirst(items) {
+    // Unknown ages sort last; Array.prototype.sort is stable, so fetch order breaks ties.
+    const age = (item) => item.createdAtUnix ?? Number.MAX_SAFE_INTEGER;
+    return [...items].sort((a, b) => age(a) - age(b));
+}
+/**
+ * Select which review items to show. `groups` is in priority order; an ID that appears in more
+ * than one group (e.g. a thread that is both resolution-only and first-look) is counted and
+ * charged once, in its first group. `maxChars <= 0` disables the cap.
+ */
+export function selectReviewOutput(groups, maxChars) {
+    if (maxChars <= 0)
+        return KEEP_ALL;
+    const seen = new Set();
+    const ordered = [];
+    for (const group of groups) {
+        const unique = group.filter((item) => {
+            if (seen.has(item.id))
+                return false;
+            seen.add(item.id);
+            return true;
+        });
+        ordered.push(...oldestFirst(unique));
+    }
+    const totalCost = ordered.reduce((sum, item) => sum + item.cost, 0);
+    if (totalCost <= maxChars)
+        return KEEP_ALL;
+    const shown = new Set();
+    let used = 0;
+    for (const item of ordered) {
+        if (shown.size > 0 && used + item.cost > maxChars)
+            break;
+        shown.add(item.id);
+        used += item.cost;
+    }
+    const held = new Set(ordered.filter((item) => !shown.has(item.id)).map((item) => item.id));
+    // The at-least-one rule can show every item despite the budget: nothing is held, no rollup.
+    if (held.size === 0)
+        return KEEP_ALL;
+    return {
+        keep: (id) => !held.has(id),
+        rollup: { shown: shown.size, total: ordered.length },
+    };
+}

package/bin/comments/visible-comments.d.mts

@@ -1,11 +1,13 @@
 import { type SeenMarker } from "../state/seen-comments.mts";
 import type { MinimizeCommentsPolicy } from "../config/load.mts";
-import type { ActionableComment, PrComment } from "../types.mts";
+import type { ActionableComment, EditedComment, PrComment } from "../types.mts";
 import type { NormalizedBotUsernames } from "./authors.mts";
 interface VisibleCommentClassification {
     actionable: ActionableComment[];
     minimizeIds: string[];
     toMarkSeen: ActionableComment[];
+    /** Seen comments whose body changed. Not readiness work; iterate surfaces and marks them. */
+    edited: EditedComment[];
 }
 export declare function classifyVisibleComments(comments: PrComment[], seenMap: Map<string, SeenMarker>, minimizeComments: MinimizeCommentsPolicy | undefined, botUsernames?: NormalizedBotUsernames, deniedMinimizeIds?: ReadonlySet<string>): VisibleCommentClassification;
 export {};

package/bin/comments/visible-comments.mjs

@@ -5,7 +5,14 @@ export function classifyVisibleComments(comments, seenMap, minimizeComments, bot
     const actionable = [];
     const minimizeIds = [];
     const toMarkSeen = [];
+    const edited = [];
     for (const c of comments.filter((comment) => !comment.isMinimized)) {
+        const cls = classifyItem(c.id, c.body, seenMap);
+        // An edit is never readiness work, even when the comment is eligible for minimization.
+        if (cls === "edited") {
+            edited.push({ ...c, edited: true });
+            continue;
+        }
         if (!deniedMinimizeIds.has(c.id) &&
             canGenerateGithubMutation(c.viewerCanMinimize, "minimize") &&
             shouldMinimizeAuthor(c.authorType, minimizeComments, c.author, botUsernames)) {
@@ -14,12 +21,10 @@ export function classifyVisibleComments(comments, seenMap, minimizeComments, bot
             toMarkSeen.push(c); // prevents re-surfacing as first-look after GitHub marks it minimized
             continue;
         }
-        const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
             continue;
-        const comment = cls === "edited" ? { ...c, edited: true } : c;
-        actionable.push(comment);
-        toMarkSeen.push(comment);
+        actionable.push(c);
+        toMarkSeen.push(c);
     }
-    return { actionable, minimizeIds, toMarkSeen };
+    return { actionable, minimizeIds, toMarkSeen, edited };
 }

package/bin/config/load.d.mts

@@ -74,6 +74,12 @@ export interface PrShepherdConfig {
          * (default) omits the hint entirely; the CLI never prescribes rebase/merge mechanics itself.
          */
         behindBaseHint: string;
+        /**
+         * Per-tick budget for review-item bodies in `fix_code` output, in characters. Over budget,
+         * iterate shows a priority-ordered subset and holds the rest (unmarked) for later ticks.
+         * `0` disables the cap.
+         */
+        reviewOutputMaxChars: number;
         /**
          * When to resolve other-human inline threads after Shepherd replies. Own and bot threads
          * always reply-and-resolve. `none` (default) keeps other humans reply-only; `outdated`

package/bin/config/load.mjs

@@ -92,6 +92,11 @@ function parseInstructionStyle(value) {
         return value;
     throw new Error(`Invalid config: iterate.instructions must be "playbook" or "inline", got ${JSON.stringify(value)}`);
 }
+function parseReviewOutputMaxChars(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0)
+        return value;
+    throw new Error(`Invalid config: iterate.reviewOutputMaxChars must be a non-negative integer, got ${JSON.stringify(value)}`);
+}
 function parseCliCommand(value) {
     if (!Array.isArray(value) ||
         value.length === 0 ||
@@ -299,6 +304,7 @@ const KNOWN_NESTED_KEYS = {
         "behindBaseHint",
         "resolveOtherHumanThreads",
         "instructions",
+        "reviewOutputMaxChars",
     ]),
     poll: new Set([
         "intervalSeconds",
@@ -404,6 +410,7 @@ function parseConfig(value, normalizeMergeArgs = true) {
     config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
     config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
     config.iterate.instructions = parseInstructionStyle(config.iterate.instructions);
+    config.iterate.reviewOutputMaxChars = parseReviewOutputMaxChars(config.iterate.reviewOutputMaxChars);
     config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
     config.standardRules = parseStandardRules(config.classify);
     return config;

package/bin/config.json

@@ -23,7 +23,8 @@
     "minimizeComments": "all",
     "behindBaseHint": "",
     "resolveOtherHumanThreads": "none",
-    "instructions": "inline"
+    "instructions": "inline",
+    "reviewOutputMaxChars": 50000
   },
   "poll": {
     "intervalSeconds": 60,

package/bin/github/poll-summary-fingerprint.mjs

@@ -29,7 +29,11 @@ export function fingerprintRawSummaryPr(summary) {
         // Omitted bodies cannot participate in the hash. Bind truncated evidence
         // to the PR revision instead, so updates require a fresh full review poll.
         ...(reviewTruncated && { reviewUpdatedAt: raw.updatedAt }),
-        comments: hideBodies(raw.comments),
+        // A PR comment edit is not readiness evidence; its ID still binds new comments.
+        comments: {
+            ...raw.comments,
+            nodes: raw.comments.nodes.map(({ body: _body, ...node }) => node),
+        },
         reviews: hideBodies(raw.reviews),
         reviewThreads: {
             ...raw.reviewThreads,

package/bin/github/poll-summary-review.mjs

@@ -19,7 +19,8 @@ export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister)
         raw.reviewThreads.pageInfo.hasPreviousPage;
     for (const comment of raw.comments.nodes) {
         if (!isSuppressed(rules, "pr-comment", comment, comment.id, undefined, comment.body, comment.isMinimized) &&
-            classifyItem(comment.id, comment.body, seen) !== "unchanged")
+            // An edited PR comment is shown once by iterate but never blocks readiness.
+            classifyItem(comment.id, comment.body, seen) === "new")
             actionable += 1;
     }
     const latestStateByAuthor = new Map((raw.latestReviews?.nodes ?? []).flatMap((review) => review.author ? [[review.author.login.toLowerCase(), review.state]] : []));

package/bin/reporters/agent.d.mts

@@ -10,9 +10,7 @@
  */
 import type { ReviewThread, PrComment, TriagedCheck, ClassifiedCheck, AgentThread, AgentComment, AgentCheck, AgentStalledCheck } from "../types.mts";
 export declare function toAgentThread(t: ReviewThread): AgentThread;
-export declare function toAgentComment(c: PrComment & {
-    edited?: boolean;
-}): AgentComment;
+export declare function toAgentComment(c: PrComment): AgentComment;
 export declare function toAgentCheck(c: TriagedCheck): AgentCheck;
 export declare function toAgentStalledCheck(c: ClassifiedCheck, nowSeconds: number): AgentStalledCheck;
 /**

package/bin/reporters/agent.mjs

@@ -51,7 +51,6 @@ export function toAgentComment(c) {
         ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
         body: c.body,
         url: c.url,
-        ...(c.edited === true && { edited: true }),
     };
 }
 export function toAgentCheck(c) {

package/bin/types/escalate.d.mts

@@ -31,6 +31,15 @@ export interface EscalateDetails {
         threadId: string;
         attempts: number;
     }>;
+    /**
+     * Set only when `iterate.reviewOutputMaxChars` held review items back on the tick that
+     * escalated: `shown` of `total` review items appear here. The held items stay unmarked, so the
+     * next run shows them.
+     */
+    reviewItems?: {
+        shown: number;
+        total: number;
+    };
     /** Review mutations generated for this tick, retained so an escalation cannot strand them. */
     pendingReviewCommands?: {
         resolveOnlyCommand?: ResolveCommand;

package/bin/types/iterate.d.mts

@@ -1,4 +1,4 @@
-import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment, RuleAutoResolveReport } from "./report.mts";
+import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment, EditedComment, RuleAutoResolveReport } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
 import type { BranchProtection, MergeStateStatus, MergedBasePullRequest, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
 import type { MergeRequirements } from "./merge-requirements.mts";
@@ -12,7 +12,10 @@ export interface IterateResultSummary {
     passing: number;
     skipped: number;
     filtered: number;
+    /** Non-completed checks GitHub reports as `IN_PROGRESS`. */
     inProgress: number;
+    /** Non-completed checks GitHub reports as `QUEUED`, `WAITING`, `PENDING`, or `REQUESTED`. */
+    queued: number;
     superseded: number;
 }
 export interface IterateResultBase {
@@ -70,6 +73,11 @@ export interface IterateResultBase {
     nextCheck?: NextCheck;
     /** Classification-rule resolve/minimize applied during this fetch. Omitted when nothing happened. */
     ruleAutoResolve?: RuleAutoResolveReport;
+    /**
+     * PR comments edited since Shepherd last showed them. Edits never block readiness, so they are
+     * held during `wait`/`ready` and shown once on the next other action. Omitted when empty.
+     */
+    editedComments?: EditedComment[];
 }
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
@@ -143,6 +151,11 @@ interface FixRebaseAndPush {
     firstLookThreads: FirstLookThread[];
     /** First-look comments — previously hidden, surfaced for acknowledgment only. */
     firstLookComments: FirstLookComment[];
+    /** Set only when `iterate.reviewOutputMaxChars` held review items back: `shown` of `total`. */
+    reviewItems?: {
+        shown: number;
+        total: number;
+    };
 }
 export interface IterateResultFixCode extends IterateResultBase {
     action: "fix_code";
@@ -176,6 +189,11 @@ export interface IterateCommandOptions extends GlobalOptions {
      * only by `runPollCore`; excluded from the public `IterateInput` in api.mts.
      */
     persistSeen?: boolean;
+    /**
+     * Internal. `true` attaches edited comments without writing their markers; the poll loop
+     * writes them for the one result it returns. Set only by `runPollCore`.
+     */
+    deferEditedCommentMarkers?: boolean;
     /**
      * Internal. `true` allows fingerprint reuse of a previous WAIT-shaped report.
      * Poll sets this only for internal WAIT/MARK_READY continuation ticks — never the

package/bin/types/report.d.mts

@@ -26,10 +26,14 @@ export interface FirstLookThread extends ReviewThread {
 }
 export interface FirstLookComment extends PrComment {
     firstLookStatus: "minimized";
-    edited?: boolean;
 }
-export type ActionableComment = PrComment & {
-    edited?: boolean;
+export type ActionableComment = PrComment;
+/**
+ * A seen PR comment whose body changed since Shepherd last showed it. An edit is not readiness
+ * work: iterate shows it once on the next action that is not `wait` or `ready`.
+ */
+export type EditedComment = PrComment & {
+    edited: true;
 };
 export type ShepherdStatus = "MERGED" | "CLOSED" | "READY" | "FAILING" | "PENDING" | "IN_PROGRESS" | "UNRESOLVED_COMMENTS" | "UNKNOWN";
 export interface ShepherdReport {
@@ -91,6 +95,8 @@ export interface ShepherdReport {
         minimizeIds?: string[];
         /** First-look items — minimized comments not yet seen by the agent. */
         firstLook: FirstLookComment[];
+        /** Seen PR comments (minimized or not) whose body changed. Not marked seen by check. Omitted when empty. */
+        edited?: EditedComment[];
         /** PR comments and review summaries minimized by a suppress+autoResolve rule this fetch. */
         autoMinimized?: AutoMinimizedItem[];
     };
@@ -103,6 +109,20 @@ export interface ShepherdReport {
     editedSummaries: Review[];
     /** APPROVED reviews not yet minimized — opt-in minimize target. */
     approvedReviews: Review[];
+    /**
+     * Set only when `iterate.reviewOutputMaxChars` held review items back this tick: `shown` of
+     * `total` review items appear in this report. Held items are absent from every review list,
+     * from the generated mutation IDs, and from the seen markers written this tick.
+     */
+    reviewItems?: {
+        shown: number;
+        total: number;
+    };
+    /**
+     * Internal, iterate-only: parent review IDs of unresolved threads held by the budget. Their
+     * summaries are not minimized this tick. Not rendered.
+     */
+    heldThreadReviewIds?: string[];
     /** COMMENTED review summary IDs matched by user rules with autoResolve:true — minimized without surfacing to agent. */
     ruleAutoResolveReviewSummaryIds?: string[];
     /** Branch protection rule for the PR's base branch. Null when no rule exists or the base ref is unavailable. */
@@ -167,7 +187,6 @@ export interface AgentComment {
     authorAssociation?: import("./github.mts").CommentAuthorAssociation;
     body: string;
     url: string;
-    edited?: boolean;
 }
 /** Check shape emitted to the iterate agent under `fix_code` or check escalation. */
 export interface AgentCheck {

package/bin/util/cap-list.d.mts

@@ -0,0 +1,7 @@
+/** First `LEAN_LIST_CAP` items plus the count of items left out. */
+export declare function capList<T>(items: readonly T[]): {
+    shown: T[];
+    hidden: number;
+};
+/** `", +N more"` suffix for a capped inline list; empty when nothing was left out. */
+export declare function moreSuffix(hidden: number): string;

package/bin/util/cap-list.mjs

@@ -0,0 +1,13 @@
+/** Lean list cap shared by Markdown lines, lean JSON, and wait logs. */
+const LEAN_LIST_CAP = 5;
+/** First `LEAN_LIST_CAP` items plus the count of items left out. */
+export function capList(items) {
+    return {
+        shown: items.slice(0, LEAN_LIST_CAP),
+        hidden: Math.max(0, items.length - LEAN_LIST_CAP),
+    };
+}
+/** `", +N more"` suffix for a capped inline list; empty when nothing was left out. */
+export function moreSuffix(hidden) {
+    return hidden > 0 ? `, +${hidden} more` : "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.59.3",
+  "version": "0.60.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -90,7 +90,7 @@
     "husky": "^9.1.7",
     "knip": "^6.14.1",
     "marked": "^18.0.11",
-    "oxfmt": "^0.71.0",
+    "oxfmt": "^0.72.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"

package/plugins/pr-shepherd/.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.59.3",
+  "version": "0.60.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

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

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