pr-shepherd 0.23.0 → 0.25.0

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.23.0",
+  "version": "0.25.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -59,7 +59,8 @@ See [docs/actions.md](docs/actions.md) for the complete output contract.
 This system is opinionated and works best with PRs that use required status checks and conversation resolution.
 
 - Human-authored threads are replied to, not resolved or minimized by Shepherd.
-- Bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible.
+- Detected bots and configured `botUsernames` review threads are returned until resolved; bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
+- Agents must not reply to their own latest thread reply; generated instructions call this out before `--reply-thread-ids` mutations.
 - 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`.
 - The CLI never performs git mutations. It emits instructions; the caller commits, rebases, pushes, and handles repository hooks.
@@ -96,10 +97,11 @@ pr-shepherd poll 42                    # explicit poll command
 ### Resolve Review Items
 
 ```sh
-pr-shepherd resolve 42 --fetch
 pr-shepherd resolve 42 --reply-thread-ids PRRT_abc --message "Renamed the variable for clarity." --require-sha "$(git rev-parse HEAD)"
 ```
 
+Use `pr-shepherd iterate 42` or `pr-shepherd 42` to fetch the next PR action. `resolve` requires at least one action flag and only applies explicit review-state mutations.
+
 ### Apply One Suggestion Thread
 
 ```sh

package/bin/cli/args.mjs

@@ -25,7 +25,6 @@ const FLAGS_WITH_VALUES = new Set([
 // for PR-number detection — so removed flags don't silently cause their
 // numeric value to be misidentified as the PR number.
 const BOOLEAN_FLAGS = new Set([
-    "--fetch",
     "--no-auto-mark-ready",
     "--no-auto-cancel-actionable",
     "--dry-run",

package/bin/cli/fix-formatter.mjs

@@ -12,9 +12,10 @@ export function formatFixCodeResult(header, result, opts) {
             const lineLabel = renderLineRange(t.startLine, t.line);
             const loc = t.path ? `\`${t.path}:${lineLabel}\`` : "(no location)";
             const heading = t.url ? `[threadId=${t.id}](${t.url})` : `\`threadId=${t.id}\``;
+            const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
             const suggestionMarker = t.suggestion ? " [suggestion]" : "";
             const editedMarker = t.edited ? " [edited since first look]" : "";
-            sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${editedMarker}`);
+            sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType)})${reviewMarker}${suggestionMarker}${editedMarker}`);
             sections.push(renderThreadConversation(t));
             if (t.suggestion) {
                 sections.push(renderSuggestionBlock(t.suggestion, ""));

package/bin/cli/formatters.mjs

@@ -4,68 +4,6 @@ export { formatCleanResult } from "./clean-formatter.mjs";
 export { formatMarkFilesAsViewedResult } from "./mark-files-as-viewed-formatter.mjs";
 export { formatMutateResult } from "./mutate-formatter.mjs";
 import { safeFence } from "./fence.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, renderEditedCommentTag, } from "./list-formatters.mjs";
-import { joinSections } from "../util/markdown.mjs";
-export function formatFetchResult(result) {
-    const activeTotal = result.actionableThreads.length +
-        result.resolutionOnlyThreads.length +
-        result.actionableComments.length +
-        result.changesRequestedReviews.length +
-        result.reviewSummaries.length;
-    const firstLookTotal = result.firstLookThreads.length + result.firstLookComments.length;
-    const total = activeTotal + firstLookTotal;
-    const headingParts = [];
-    if (activeTotal > 0)
-        headingParts.push(`${activeTotal} actionable`);
-    if (firstLookTotal > 0)
-        headingParts.push(`${firstLookTotal} first-look`);
-    const headingSuffix = headingParts.length > 0 ? headingParts.join(", ") : "0 actionable";
-    const sections = [`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`];
-    if (result.actionableThreads.length > 0) {
-        sections.push(`## Actionable Review Threads (${result.actionableThreads.length})` +
-            (result.commitSuggestionsEnabled ? " [commit-suggestions: enabled]" : ""));
-        sections.push(result.actionableThreads
-            .map((t) => renderThreadBullet(t, { renderSuggestion: true }))
-            .join("\n\n"));
-    }
-    if (result.resolutionOnlyThreads.length > 0) {
-        sections.push(`## Review threads to resolve (${result.resolutionOnlyThreads.length})`);
-        sections.push(result.resolutionOnlyThreads
-            .map((t) => renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t) }))
-            .join("\n"));
-    }
-    if (result.actionableComments.length > 0) {
-        sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
-        sections.push(result.actionableComments
-            .map((c) => renderCommentBullet(c, { statusTag: renderEditedCommentTag(c) }))
-            .join("\n"));
-    }
-    if (result.changesRequestedReviews.length > 0) {
-        sections.push(`## Pending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length})`);
-        sections.push(result.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
-    }
-    if (result.reviewSummaries.length > 0) {
-        sections.push(`## Review summaries (${result.reviewSummaries.length})`);
-        sections.push(result.reviewSummaries.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n"));
-    }
-    if (firstLookTotal > 0) {
-        sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
-        const resolutionOnlyIds = new Set(result.resolutionOnlyThreads.map((t) => t.id));
-        sections.push(buildFirstLookBullets(result.firstLookThreads, resolutionOnlyIds, result.firstLookComments).join("\n"));
-    }
-    sections.push("## Summary");
-    sections.push(total === 0
-        ? "0 actionable, 0 first-look — all items seen"
-        : [
-            activeTotal > 0 ? `${activeTotal} actionable` : null,
-            firstLookTotal > 0 ? `${firstLookTotal} first-look` : null,
-        ]
-            .filter(Boolean)
-            .join(", "));
-    sections.push("## Instructions");
-    sections.push(result.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
-    return joinSections(sections);
-}
 export function formatCommitSuggestionResult(result) {
     const lines = [];
     const range = result.startLine === result.endLine

package/bin/cli/help-command-pages.mjs

@@ -1,24 +1,15 @@
 export const COMMAND_USAGE = {
     resolve: `pr-shepherd resolve
 
-Fetch actionable review items or apply GitHub review-state mutations after fixes.
+Apply GitHub review-state mutations after fixes.
 
 Usage:
-  pr-shepherd resolve [PR] [--fetch] [--format text|json]
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
   pr-shepherd resolve [PR] --resolve-thread-ids A,B [--minimize-comment-ids X,Y]
                             [--dismiss-review-ids Q] [--message MSG]
                             [--require-sha SHA] [--format text|json]
 
-Modes:
-  fetch                Default when no mutation IDs are provided. Fetches review threads,
-                       comments, first-look items, and instructions.
-  mutate               Runs when any mutation ID flag is present. Resolves threads,
-                       replies to human threads, resolves non-human/manual thread IDs,
-                       minimizes non-human comments/review summaries, and dismisses non-human reviews.
-
 Flags:
-  --fetch                         Force fetch mode.
   --resolve-thread-ids <ids>      Comma-separated review thread IDs to resolve.
                                   Human-authored thread IDs are skipped; use --reply-thread-ids.
   --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
@@ -30,6 +21,9 @@ Flags:
   --format text|json              Output format. Default: text.
   --help, -h                      Print this help and exit before GitHub I/O.
 
+At least one non-empty action flag is required:
+  --reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids.
+
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; 1 on validation, lookup, or mutation failure.`,
     "commit-suggestion": `pr-shepherd commit-suggestion

package/bin/cli/help-top-page.mjs

@@ -18,7 +18,7 @@ Commands:
   [PR]                 Poll until non-WAIT or timeout. This is the default command.
   iterate              Run one iterate tick (single-tick alias).
   poll                 Re-run iterate while the action is WAIT, then print the final tick.
-  resolve              Fetch actionable review items, or resolve/minimize/dismiss IDs.
+  resolve              Apply review-state mutations (requires at least one action flag).
   commit-suggestion    Convert one GitHub suggestion thread into a patch and commit instructions.
   mark-files-as-viewed Mark PR changed files as viewed in GitHub.
   clean                Remove pr-shepherd state files.

package/bin/cli/iterate-instructions.mjs

@@ -32,7 +32,7 @@ export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix) {
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
-export function buildIterateCommand(pr, readyDelaySuffix) {
+function buildIterateCommand(pr, readyDelaySuffix) {
     const suffix = readyDelaySuffix?.trim();
     return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])]).text;
 }

package/bin/cli/list-formatters.mjs

@@ -9,7 +9,7 @@ export function renderBodyPreview(body) {
     const firstLine = normalizedBody.split("\n")[0]?.trim() ?? "";
     return firstLine.slice(0, BODY_PREVIEW_MAX);
 }
-export function renderFirstLookStatusTag(t) {
+function renderFirstLookStatusTag(t) {
     const editedSuffix = t.edited ? ", edited" : "";
     return t.autoResolved
         ? `[status: outdated, auto-resolved${editedSuffix}]`
@@ -28,8 +28,9 @@ export function renderThreadBullet(t, opts = {}) {
         : "`(no location)`";
     const suggestionMarker = t.suggestion ? " [suggestion]" : "";
     const editedMarker = t.edited && !opts.suppressEditedMarker ? " [edited since first look]" : "";
+    const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${editedMarker}${statusSuffix}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
     if (!opts.noBody && (!t.comments || t.comments.length === 0)) {
         const legacyLine = `${bulletLine}: ${renderBodyPreview(t.body)}`;
         return t.suggestion && opts.renderSuggestion

package/bin/cli-parser.mjs

@@ -6,7 +6,7 @@
  *   pr-shepherd [PR] [--interval 45s] [--timeout 4m] [--format text|json] [--ready-delay Nm]
  *                  [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                  [--no-auto-cancel-actionable]
- *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
+ *   pr-shepherd resolve [PR] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
  *                            [--reply-thread-ids A,B] [--dismiss-review-ids Q]
  *                            [--message MSG] [--require-sha SHA]
  *   pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]
@@ -22,12 +22,12 @@
  *   pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]
  */
 import { readFileSync } from "node:fs";
-import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
+import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, maybePrintHelp } from "./cli/help.mjs";
-import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
+import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
@@ -130,30 +130,31 @@ async function handleResolve(args) {
     const dismissReviewIds = parseList(getFlag(extra, "--dismiss-review-ids"));
     const dismissMessage = getFlag(extra, "--message") ?? undefined;
     const requireSha = getFlag(extra, "--require-sha") ?? undefined;
-    const fetchMode = hasFlag(extra, "--fetch") ||
-        (resolveThreadIds.length === 0 &&
-            replyThreadIds.length === 0 &&
-            minimizeCommentIds.length === 0 &&
-            dismissReviewIds.length === 0);
-    if (fetchMode) {
-        const result = await runResolveFetch({ ...globalOpts, prNumber });
-        process.stdout.write(globalOpts.format === "json"
-            ? `${JSON.stringify(result, null, 2)}\n`
-            : `${formatFetchResult(result)}\n`);
+    if (hasFlag(extra, "--fetch")) {
+        process.stderr.write("pr-shepherd: resolve: --fetch has been removed; run pr-shepherd iterate or poll to fetch the next action.\n");
+        process.exitCode = 1;
+        return;
     }
-    else {
-        const result = await runResolveMutate({
-            ...globalOpts,
-            prNumber,
-            resolveThreadIds,
-            replyThreadIds,
-            minimizeCommentIds,
-            dismissReviewIds,
-            dismissMessage,
-            requireSha,
-        });
-        process.stdout.write(globalOpts.format === "json"
-            ? `${JSON.stringify(result, null, 2)}\n`
-            : `${formatMutateResult(result)}\n`);
+    const hasAction = resolveThreadIds.length > 0 ||
+        replyThreadIds.length > 0 ||
+        minimizeCommentIds.length > 0 ||
+        dismissReviewIds.length > 0;
+    if (!hasAction) {
+        process.stderr.write("pr-shepherd: resolve: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n");
+        process.exitCode = 1;
+        return;
     }
+    const result = await runResolveMutate({
+        ...globalOpts,
+        prNumber,
+        resolveThreadIds,
+        replyThreadIds,
+        minimizeCommentIds,
+        dismissReviewIds,
+        dismissMessage,
+        requireSha,
+    });
+    process.stdout.write(globalOpts.format === "json"
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `${formatMutateResult(result)}\n`);
 }

package/bin/commands/check.mjs

@@ -14,6 +14,8 @@ import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs"
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay } from "../comments/review-visibility.mjs";
+import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
+import { normalizeBotUsernames } from "../comments/authors.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -43,10 +45,11 @@ export async function runCheck(opts) {
     const triagedBase = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const seenMap = await loadSeenMap(stateKey);
+    const botUsernames = normalizeBotUsernames(config.botUsernames);
     const triaged = await attachUnseenCheckAnnotations(triagedBase, seenMap, prNumber);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized);
-    const visibleCommentClassification = classifyVisibleComments(batchData.comments, seenMap, config.iterate.minimizeComments);
-    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads, seenMap);
+    const visibleCommentClassification = classifyVisibleComments(batchData.comments, seenMap, config.iterate.minimizeComments, botUsernames);
+    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads, seenMap, botUsernames);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -76,6 +79,7 @@ export async function runCheck(opts) {
         ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
         ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
+    await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
     const changesRequestedReviewCount = batchData.changesRequestedReviews.length;
     const approvedReviews = approvedReviewVisibility.visible;

package/bin/commands/commit-suggestion-instruction.mjs

@@ -1,9 +1,9 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
  * Build the `commit-suggestion` instruction step for agent consumers.
- * Shared between `fix_code` (iterate) and `resolve --fetch` paths.
- * @param sectionName - The markdown section heading where suggestion threads appear
- *   (e.g. `"## Review threads"` for iterate, `"## Actionable Review Threads"` for resolve).
+ * Currently emitted by iterate `fix_code` for suggestion review threads.
+ * @param sectionName - The markdown section heading where suggestion threads appear,
+ *   e.g. `"## Review threads"`.
  * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
  */
 export function buildCommitSuggestionInstruction(prNumber, sectionName, includeDriftHint) {

package/bin/commands/iterate/classify.mjs

@@ -1,6 +1,6 @@
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { shouldMinimizeAuthor } from "../../comments/minimize-policy.mjs";
-import { isHumanAuthor } from "../../comments/authors.mjs";
+import { isConfiguredBotAuthor, isHumanAuthor, } from "../../comments/authors.mjs";
 function dedupeIds(ids) {
     const seen = new Set();
     const out = [];
@@ -12,17 +12,19 @@ function dedupeIds(ids) {
     }
     return out;
 }
-export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all") {
+export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all", botUsernames = new Set(), unresolvedThreads = []) {
+    const blockedReviewIds = new Set(unresolvedThreads.flatMap((t) => (t.reviewId !== undefined ? [t.reviewId] : [])));
     // First-look and seen summaries go into the minimize mutation; edited summaries do NOT —
     // they are already minimized server-side (body changed after minimize was applied).
     // First-look bodies are rendered so the agent sees them before the minimize happens.
     const minimizeIds = [...summaries.firstLook, ...summaries.seen]
-        .filter((r) => shouldMinimizeAuthor(r.authorType, minimizeComments, r.author))
+        .filter((r) => shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
+        .filter((r) => !blockedReviewIds.has(r.id))
         .map((r) => r.id);
     if (minimizeApprovals) {
         const surfacedApprovals = [];
         for (const r of approvals) {
-            if (shouldMinimizeAuthor(r.authorType, minimizeComments, r.author))
+            if (shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
                 minimizeIds.push(r.id);
             else
                 surfacedApprovals.push(r);
@@ -41,11 +43,15 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, _reviews, checks, prNumber) {
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, _reviews, checks, prNumber, botUsernames = new Set()) {
     const argv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
     const allThreads = [...threads, ...resolutionOnlyThreads];
-    const replyThreadIds = dedupeIds(allThreads.filter(isHumanAuthor).map((t) => t.id));
-    const resolveThreadIds = dedupeIds(allThreads.filter((t) => !isHumanAuthor(t)).map((t) => t.id));
+    const replyThreadIds = dedupeIds(allThreads
+        .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
+        .map((t) => t.id));
+    const resolveThreadIds = dedupeIds(allThreads
+        .filter((t) => !isHumanAuthor(t) || isConfiguredBotAuthor(t, botUsernames))
+        .map((t) => t.id));
     if (replyThreadIds.length > 0) {
         argv.push("--reply-thread-ids", replyThreadIds.join(","));
         argv.push("--message", "$DISMISS_MESSAGE");

package/bin/commands/iterate/fix-code.mjs

@@ -25,7 +25,7 @@ function nextFixAttempts(stored, headSha, threads) {
     return { threadAttempts, threadBodyHashes };
 }
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
@@ -76,7 +76,7 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = pushLikely ? buildInProgressRunIds(report, cancelledSet) : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber);
+    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
     // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:

package/bin/commands/iterate/index.mjs

@@ -9,8 +9,10 @@ import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
+import { normalizeBotUsernames } from "../../comments/authors.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
+    const botUsernames = normalizeBotUsernames(config.botUsernames);
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
     const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -56,7 +58,7 @@ export async function runIterate(opts) {
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
-    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments);
+    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [...report.threads.actionable, ...report.threads.resolutionOnly]);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.threads.resolutionOnly.length > 0 ||
         report.threads.firstLook.length > 0 ||
@@ -122,6 +124,7 @@ export async function runIterate(opts) {
             firstLookSummaries,
             editedSummaries,
             surfacedApprovals,
+            botUsernames,
         });
     }
     const canMarkReady = report.status === "READY" &&

package/bin/commands/iterate/render.mjs

@@ -78,6 +78,9 @@ export function buildFixInstructions(threads, actionableComments, checks, change
         instructions.push(`If you applied code edits: commit them with a descriptive message, then rebase onto \`origin/${baseBranch}\` per your repository's conventions before pushing.`);
     }
     if (resolveCommand.hasMutations) {
+        if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
+            instructions.push(`Before running the \`resolve:\` command, remove any thread from \`--reply-thread-ids\` if the latest visible comment in that thread is your own prior Shepherd reply. Do not reply to your own comments.`);
+        }
         const substituteParts = [];
         if (resolveCommand.requiresHeadSha) {
             substituteParts.push(`\`$HEAD_SHA\` with the pushed commit SHA (or \`$(git rev-parse HEAD)\` if you did not push)`);

package/bin/commands/iterate/stall.mjs

@@ -1,7 +1,7 @@
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage } from "./escalate.mjs";
-export function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
+function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
         ...report.checks.inProgress.map((p) => `inProgress:${p.name}`),

package/bin/commands/resolve-mutate.mjs

@@ -1,8 +1,9 @@
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { applyResolveOptions } from "../comments/resolve.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
-import { isHumanAuthor } from "../comments/authors.mjs";
-import { markSeen } from "../state/seen-comments.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
+import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();
@@ -11,11 +12,17 @@ export async function runResolveMutate(opts) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
     const { data } = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true });
+    const config = loadConfig();
+    const botUsernames = normalizeBotUsernames(config.botUsernames);
     const threadById = new Map(data.reviewThreads.map((t) => [t.id, t]));
-    const humanThreadIds = new Set(data.reviewThreads.filter(isHumanAuthor).map((t) => t.id));
-    const humanCommentIds = new Set(data.comments.filter(isHumanAuthor).map((c) => c.id));
+    const humanThreadIds = new Set(data.reviewThreads
+        .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
+        .map((t) => t.id));
+    const humanCommentIds = new Set(data.comments
+        .filter((c) => isHumanAuthor(c) && !isConfiguredBotAuthor(c, botUsernames))
+        .map((c) => c.id));
     const humanReviewIds = new Set([...data.reviewSummaries, ...data.approvedReviews, ...data.changesRequestedReviews]
-        .filter(isHumanAuthor)
+        .filter((r) => isHumanAuthor(r) && !isConfiguredBotAuthor(r, botUsernames))
         .map((r) => r.id));
     const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id));
     const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id));
@@ -46,7 +53,8 @@ export async function runResolveMutate(opts) {
             const thread = threadById.get(id);
             if (!thread)
                 return Promise.resolve();
-            return markSeen({ owner: repo.owner, repo: repo.name, pr: prNumber }, id, threadTranscriptBody(thread, [opts.dismissMessage]));
+            const previousBody = threadTranscriptBody(thread);
+            return markReplySeen({ owner: repo.owner, repo: repo.name, pr: prNumber }, id, previousBody, threadTranscriptBody(thread, [opts.dismissMessage]), opts.dismissMessage);
         }));
     }
     return result;

package/bin/commands/resolve.mjs

@@ -1,73 +1 @@
-import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
-import { fetchPrBatch } from "../github/batch.mjs";
-import { loadConfig } from "../config/load.mjs";
-import { classifyVisibleComments } from "../comments/visible-comments.mjs";
-import { extractSuggestion } from "../suggestions/extract.mjs";
-import { buildFetchInstructions } from "./resolve-instructions.mjs";
-import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
-import { threadTranscriptBody } from "../threads/transcript.mjs";
-import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
-import { classifyReviewsForDisplay } from "../comments/review-visibility.mjs";
 export { runResolveMutate } from "./resolve-mutate.mjs";
-export async function runResolveFetch(opts) {
-    const repo = await getRepoInfo();
-    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (prNumber === null) {
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
-    }
-    const { data } = await fetchPrBatch(prNumber, repo);
-    const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
-    const minimizedCommentCandidates = data.comments.filter((c) => c.isMinimized);
-    const seenMap = await loadSeenMap(stateKey);
-    const threadVisibility = classifyThreadVisibility(data.reviewThreads, seenMap);
-    const unseenMinimizedComments = [];
-    const editedMinimizedComments = [];
-    for (const c of minimizedCommentCandidates) {
-        const cls = classifyItem(c.id, c.body, seenMap);
-        if (cls === "new")
-            unseenMinimizedComments.push(c);
-        else if (cls === "edited")
-            editedMinimizedComments.push(c);
-    }
-    const cfg = loadConfig();
-    const visibleCommentClassification = classifyVisibleComments(data.comments, seenMap, cfg.iterate?.minimizeComments);
-    const changesRequestedReviewVisibility = classifyReviewsForDisplay(data.changesRequestedReviews, seenMap);
-    const reviewSummaryVisibility = cfg.resolve.fetchReviewSummaries
-        ? classifyReviewsForDisplay(data.reviewSummaries, seenMap)
-        : { visible: [], toMarkSeen: [] };
-    const actionableThreads = threadVisibility.activeThreads.map(({ isResolved: _r, isOutdated: _o, ...rest }) => {
-        const thread = rest;
-        const suggestion = extractSuggestion(rest);
-        if (suggestion)
-            thread.suggestion = suggestion;
-        return thread;
-    });
-    const firstLookComments = [
-        ...unseenMinimizedComments.map((c) => ({ ...c, firstLookStatus: "minimized" })),
-        ...editedMinimizedComments.map((c) => ({
-            ...c,
-            firstLookStatus: "minimized",
-            edited: true,
-        })),
-    ];
-    // Mark new and edited items as seen (best-effort — markSeen never throws).
-    await Promise.allSettled([
-        ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-        ...reviewSummaryVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-    ]);
-    const result = {
-        prNumber,
-        actionableThreads,
-        resolutionOnlyThreads: threadVisibility.resolutionOnlyThreads,
-        firstLookThreads: threadVisibility.firstLookThreads,
-        actionableComments: visibleCommentClassification.actionable,
-        firstLookComments,
-        changesRequestedReviews: changesRequestedReviewVisibility.visible,
-        reviewSummaries: reviewSummaryVisibility.visible,
-        commitSuggestionsEnabled: cfg.actions.commitSuggestions,
-    };
-    return { ...result, instructions: buildFetchInstructions(prNumber, result) };
-}

package/bin/comments/authors.mjs

@@ -1,6 +1,15 @@
-export function isBotLogin(login) {
+function isBotLogin(login) {
     return (login ?? "").toLowerCase().includes("[bot]");
 }
+function normalizeBotUsername(login) {
+    return (login ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/\[bot\]$/i, "");
+}
+export function normalizeBotUsernames(botUsernames = []) {
+    return new Set((botUsernames ?? []).map((name) => normalizeBotUsername(name)));
+}
 export function normalizeAuthorType(typeName, login) {
     if (isBotLogin(login))
         return "Bot";
@@ -12,3 +21,12 @@ export function isHumanAuthor(author) {
     const login = author.author ?? author.login ?? "";
     return author.authorType === "User" && !isBotLogin(login);
 }
+export function isConfiguredBotAuthor(author, botUsernames = new Set()) {
+    const login = author.author ?? author.login ?? "";
+    if (author.authorType === "Bot" || isBotLogin(login))
+        return true;
+    const normalized = normalizeBotUsername(login);
+    if (normalized === "")
+        return false;
+    return botUsernames.has(normalized);
+}

package/bin/comments/minimize-policy.mjs

@@ -1,13 +1,14 @@
-import { isHumanAuthor } from "./authors.mjs";
-export function shouldMinimizeAuthor(authorType, policy, author) {
-    if (isHumanAuthor({ author, authorType }))
+import { isConfiguredBotAuthor, isHumanAuthor } from "./authors.mjs";
+export function shouldMinimizeAuthor(authorType, policy, author, botUsernames = new Set()) {
+    const isConfiguredBot = isConfiguredBotAuthor({ author, authorType }, botUsernames);
+    if (isHumanAuthor({ author, authorType }) && !isConfiguredBot)
         return false;
     switch (policy) {
         case undefined:
         case "all":
-            return authorType !== "User";
+            return authorType !== "User" || isConfiguredBot;
         case "bots":
-            return authorType === "Bot";
+            return isConfiguredBot;
         case "users":
             return false;
         case "none":

package/bin/comments/review-thread-markers.mjs

@@ -0,0 +1,18 @@
+import { markReviewInlineThreads } from "../state/seen-comments.mjs";
+function groupInlineThreadIdsByReview(threads) {
+    const byReview = new Map();
+    for (const thread of threads) {
+        if (thread.reviewId === undefined)
+            continue;
+        const ids = byReview.get(thread.reviewId) ?? new Set();
+        ids.add(thread.id);
+        byReview.set(thread.reviewId, ids);
+    }
+    return new Map([...byReview.entries()].map(([reviewId, ids]) => [
+        reviewId,
+        [...ids].sort((a, b) => a.localeCompare(b)),
+    ]));
+}
+export async function markReviewInlineThreadMarkers(key, threads) {
+    await Promise.allSettled([...groupInlineThreadIdsByReview(threads)].map(([reviewId, inlineThreadIds]) => markReviewInlineThreads(key, reviewId, inlineThreadIds)));
+}