pr-shepherd 0.59.2 → 0.60.0

package/bin/commands/rule-auto-resolve-format.d.mts

@@ -1,17 +1,5 @@
 import type { AutoMinimizedItem, AutoResolvedThread, RuleAutoResolveReport, ShepherdReport } from "../types.mts";
 export declare function uniqueReasons(reasons: readonly string[]): string[];
-export declare function reasonClause(reasons: readonly string[]): string | undefined;
-export declare function ruleAutoResolveBody(counts: {
-    threads: number;
-    comments: number;
-    reviewSummaries: number;
-}): string | undefined;
-export declare function formatRuleAutoResolveJournalItem(input: {
-    body: string;
-    reasons: readonly string[];
-    viewerLogin?: string;
-    urls: readonly string[];
-}): string;
 export declare function decorateAutoResolveError(error: string, reasons: readonly string[]): string;
 export declare function reasonsForError(error: string, ids: readonly string[], ruleReasons: ReadonlyMap<string, readonly string[]>): string[];
 export declare function ruleAutoResolveFromReport(report: ShepherdReport): RuleAutoResolveReport | undefined;

package/bin/commands/rule-auto-resolve-format.mjs

@@ -7,7 +7,7 @@ export function uniqueReasons(reasons) {
     }
     return unique;
 }
-export function reasonClause(reasons) {
+function reasonClause(reasons) {
     const unique = uniqueReasons(reasons);
     if (unique.length === 0)
         return undefined;
@@ -21,7 +21,7 @@ function joinedReason(reasons) {
 function plural(count, singular, pluralForm = `${singular}s`) {
     return `${count} ${count === 1 ? singular : pluralForm}`;
 }
-export function ruleAutoResolveBody(counts) {
+function ruleAutoResolveBody(counts) {
     const parts = [];
     if (counts.threads > 0)
         parts.push(`auto-resolved ${plural(counts.threads, "thread")}`);
@@ -39,15 +39,6 @@ function withReasonClause(body, reasons) {
     const clause = reasonClause(reasons);
     return clause ? `${body} ${clause}` : body;
 }
-export function formatRuleAutoResolveJournalItem(input) {
-    const login = input.viewerLogin?.trim();
-    const actor = login ? `as @${login}` : "(token login unavailable)";
-    const clause = reasonClause(input.reasons);
-    const links = input.urls.map((url) => url.trim()).filter(Boolean);
-    const reasonSuffix = clause ? ` ${clause}` : "";
-    const linkSuffix = links.length > 0 ? `: ${links.join(", ")}` : "";
-    return `- ${input.body} ${actor}${reasonSuffix}${linkSuffix}`;
-}
 export function decorateAutoResolveError(error, reasons) {
     const clause = reasonClause(reasons);
     return clause ? `${error} ${clause}` : error;

package/bin/commands/rule-auto-resolve.d.mts

@@ -13,9 +13,4 @@ export declare function applySuppressedRuleAutoResolve(input: {
     enabled: boolean;
     partition: BatchPartition;
     batch: BatchPrData;
-    prNumber: number;
-    repo: {
-        owner: string;
-        name: string;
-    };
 }): Promise<RuleAutoResolveApplied>;

package/bin/commands/rule-auto-resolve.mjs

@@ -1,7 +1,6 @@
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
-import { runJournal } from "./journal/index.mjs";
 import { canGenerateGithubMutation } from "../github/mutation-policy.mjs";
-import { decorateAutoResolveError, formatRuleAutoResolveJournalItem, minimizedItem, reasonClause, reasonsForError, resolvedThread, ruleAutoResolveBody, uniqueReasons, } from "./rule-auto-resolve-format.mjs";
+import { decorateAutoResolveError, minimizedItem, reasonsForError, resolvedThread, uniqueReasons, } from "./rule-auto-resolve-format.mjs";
 const EMPTY = {
     threadIds: [],
     commentIds: [],
@@ -17,9 +16,6 @@ function idsIn(ids, confirmed) {
 function decorateErrors(errors, ids, ruleReasons) {
     return errors.map((error) => decorateAutoResolveError(error, reasonsForError(error, ids, ruleReasons)));
 }
-function successReasons(ids, ruleReasons) {
-    return uniqueReasons(ids.flatMap((id) => [...(ruleReasons.get(id) ?? [])]));
-}
 export async function applySuppressedRuleAutoResolve(input) {
     if (!input.enabled) {
         return {
@@ -70,9 +66,6 @@ export async function applySuppressedRuleAutoResolve(input) {
         ...minimized.errors.flatMap((error) => reasonsForError(error, minimizeIds, input.partition.ruleReasons)),
         ...resolved.errors.flatMap((error) => reasonsForError(error, threadIds, input.partition.ruleReasons)),
     ]);
-    const journalError = await journalSuccesses(input, autoResolved, autoMinimized);
-    if (journalError)
-        autoResolveErrors.push(journalError);
     return {
         threadIds: input.partition.ruleAutoResolveThreadIds.filter((id) => !resolvedSet.has(id)),
         commentIds: input.partition.ruleAutoResolveCommentIds.filter((id) => !minimizedSet.has(id)),
@@ -83,37 +76,3 @@ export async function applySuppressedRuleAutoResolve(input) {
         errorReasons,
     };
 }
-async function journalSuccesses(input, autoResolved, autoMinimized) {
-    const body = ruleAutoResolveBody({
-        threads: autoResolved.length,
-        comments: autoMinimized.filter((item) => item.kind === "pr-comment").length,
-        reviewSummaries: autoMinimized.filter((item) => item.kind === "review-summary").length,
-    });
-    if (!body)
-        return undefined;
-    const ids = [...autoResolved.map((thread) => thread.id), ...autoMinimized.map((item) => item.id)];
-    const reasons = successReasons(ids, input.partition.ruleReasons);
-    const item = formatRuleAutoResolveJournalItem({
-        body,
-        reasons,
-        ...(input.batch.viewerLogin ? { viewerLogin: input.batch.viewerLogin } : {}),
-        urls: [
-            ...autoResolved.map((thread) => thread.url),
-            ...autoMinimized.map((item) => item.url ?? ""),
-        ],
-    });
-    try {
-        await runJournal({
-            prNumber: input.prNumber,
-            targetRepository: { owner: input.repo.owner, name: input.repo.name },
-            rawItem: item,
-            dryRun: false,
-        });
-        return undefined;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        const clause = reasonClause(reasons);
-        return clause ? `journal: ${message} ${clause}` : `journal: ${message}`;
-    }
-}

package/bin/commands/shepherd-journal.d.mts

@@ -4,12 +4,3 @@ export declare const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Read each body under `## Review summaries (first look)` and journal any warranted note before review mutations.";
-/** The concrete `apply journal` command. The placeholder is single-quoted so a substituted decision stays literal in the shell. */
-export declare function buildShepherdJournalCommand(prReference: string | number): string;
-/**
- * Build the Shepherd Journal instruction step. The reference-citation convention (link
- * threads/comments by heading URL, cite reviews by ID) is a short clause, so it stays inline:
- * a separate playbook would cost the agent an extra read turn that outweighs the clause.
- */
-export declare function buildShepherdJournalInstruction(prReference: string | number): string;

package/bin/commands/shepherd-journal.mjs

@@ -1,21 +1,6 @@
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
 export const SHEPHERD_JOURNAL_SECTION = "Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = `Read each body under \`## Review summaries (first look)\` and journal any warranted note before review mutations.`;
-/** The concrete `apply journal` command. The placeholder is single-quoted so a substituted decision stays literal in the shell. */
-export function buildShepherdJournalCommand(prReference) {
-    return `${buildPrShepherdCommand(["apply", "journal", String(prReference)]).text} '- <decision>'`;
-}
-/**
- * Build the Shepherd Journal instruction step. The reference-citation convention (link
- * threads/comments by heading URL, cite reviews by ID) is a short clause, so it stays inline:
- * a separate playbook would cost the agent an extra read turn that outweighs the clause.
- */
-export function buildShepherdJournalInstruction(prReference) {
-    const command = buildShepherdJournalCommand(prReference);
-    return `Journal key decisions or rejections with URLs or IDs: \`${command}\``;
-}

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`
@@ -81,8 +87,8 @@ export interface PrShepherdConfig {
          */
         resolveOtherHumanThreads: ResolveOtherHumanThreads;
         /**
-         * `inline` (default) prints the commit/push and journal steps of `fix_code` instructions
-         * every tick; `playbook` folds them into one `Playbook: "Fix-code loop"` pointer. The
+         * `inline` (default) prints the commit/push step of `fix_code` instructions
+         * every tick; `playbook` folds it into one `Playbook: "Fix-code loop"` pointer. The
          * default is inline because the token bench measured playbook as a net cost: it adds a read. The `--instructions` flag and MCP `instructions` input override per call.
          */
         instructions: InstructionStyle;

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/mcp/server.mjs

@@ -33,7 +33,7 @@ const iterateInputSchema = z
     instructions: z
         .enum(["playbook", "inline"])
         .optional()
-        .describe("fix_code instruction style. inline (default) prints every step each tick; playbook folds commit, push and journal into the Fix-code loop playbook."),
+        .describe("fix_code instruction style. inline (default) prints every step each tick; playbook folds commit and push into the Fix-code loop playbook."),
     pollMode: z
         .enum(["auto", "poll", "event"])
         .optional()

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.2",
+  "version": "0.60.0",
   "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.2",
+  "version": "0.60.0",
   "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.2",
+  "version": "0.60.0",
   "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.59.2", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.60.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/references/fix-code-loop.md

@@ -1,10 +1,9 @@
 # Fix-code loop
 
-Apply when a step says `Playbook: "Fix-code loop"`. It replaces the commit, push, and journal procedure that `--instructions=inline` prints on every `[FIX_CODE]` tick. Run the numbered steps in `## Instructions` in order; this is the one that names it.
+Apply when a step says `Playbook: "Fix-code loop"`. It replaces the commit and push procedure that `--instructions=inline` prints on every `[FIX_CODE]` tick. Run the numbered steps in `## Instructions` in order; this is the one that names it.
 
 - Review and fix first. Decide per item whether it needs a code change; the reply and resolve mutations are generated either way.
 - Commit and push. If you changed any files (code, docs, or config), commit them and push to the PR head branch. If you did not, do not commit. The repository's pre-push hooks and `AGENTS.md` own lint, typecheck, and format, and its conventions own rebase style and push flags.
-- Journal. Only when the step that names this playbook prints an `apply journal` command: for any substantial decision or rejection, run that command with a `- <decision>` item. Link threads and comments by heading URL and cite reviews by ID. Journal before the review mutations. When no `apply journal` command is printed, journaling is unavailable on this tick; do not build or run one.
 - The `apply review` step stays inline because it needs `$DISMISS_MESSAGE` substitution. Push first: its `--require-sha HEAD` must read the pushed SHA.
 - `[FIX_CODE]` is non-terminal. After the last step, iterate again immediately with the same options. Only `[ESCALATE]` hands work to a human, and `[CANCEL]` ends polling.
 - Playbooks named by other steps (`Playbook: "<name>"`) ship with the package. Without the skill, print one with `pr-shepherd playbook "<name>"`, or the MCP `playbook` tool.