pr-shepherd 0.23.0 → 0.24.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.24.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.

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/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/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/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-instructions.mjs

@@ -51,8 +51,11 @@ export function buildFetchInstructions(prNumber, result) {
         : reviewSummaries.length > 0
             ? ` Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`.`
             : "";
-    const resolveCommand = `${buildPrShepherdCommand(["resolve", String(prNumber)]).text} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]`;
-    instructions.push(`Run \`${resolveCommand}\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
+    const resolveCommand = `${buildPrShepherdCommand(["resolve", String(prNumber)]).text} [--reply-thread-ids <ids>] [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids>] [--message "<reason>"]`;
+    if (actionableThreads.length > 0 || resolutionOnlyThreads.length > 0) {
+        instructions.push(`Do not reply to your own thread comments. If the latest visible comment in a thread is your own prior Shepherd reply, leave that thread out of \`--reply-thread-ids\`.`);
+    }
+    instructions.push(`Run \`${resolveCommand}\` with only the non-empty flag subsets. Skip the command entirely if all ID lists are empty.${requireShaHint}${dismissNote}`);
     instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS));
     instructions.push(`Report: echo the CLI's mutation output, then one line per Acknowledged item: \`Acknowledged <id> (@<author>): <reason>\`. If any fetched item was neither resolved nor acknowledged, stop and escalate: "<N> item(s) fetched but not acted on or acknowledged — need human direction before closing".`);
     return instructions;

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

@@ -8,6 +8,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 { runResolveMutate } from "./resolve-mutate.mjs";
 export async function runResolveFetch(opts) {
     const repo = await getRepoInfo();
@@ -19,7 +21,9 @@ export async function runResolveFetch(opts) {
     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 cfg = loadConfig();
+    const botUsernames = normalizeBotUsernames(cfg.botUsernames);
+    const threadVisibility = classifyThreadVisibility(data.reviewThreads, seenMap, botUsernames);
     const unseenMinimizedComments = [];
     const editedMinimizedComments = [];
     for (const c of minimizedCommentCandidates) {
@@ -29,8 +33,7 @@ export async function runResolveFetch(opts) {
         else if (cls === "edited")
             editedMinimizedComments.push(c);
     }
-    const cfg = loadConfig();
-    const visibleCommentClassification = classifyVisibleComments(data.comments, seenMap, cfg.iterate?.minimizeComments);
+    const visibleCommentClassification = classifyVisibleComments(data.comments, seenMap, cfg.iterate?.minimizeComments, botUsernames);
     const changesRequestedReviewVisibility = classifyReviewsForDisplay(data.changesRequestedReviews, seenMap);
     const reviewSummaryVisibility = cfg.resolve.fetchReviewSummaries
         ? classifyReviewsForDisplay(data.reviewSummaries, seenMap)
@@ -58,6 +61,7 @@ export async function runResolveFetch(opts) {
         ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
         ...reviewSummaryVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
+    await markReviewInlineThreadMarkers(stateKey, data.reviewThreads);
     const result = {
         prNumber,
         actionableThreads,

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)));
+}

package/bin/comments/thread-visibility.mjs

@@ -1,5 +1,6 @@
 import { classifyItem } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
+import { isConfiguredBotAuthor } from "./authors.mjs";
 function withEdited(thread, edited) {
     return edited ? { ...thread, edited: true } : thread;
 }
@@ -15,20 +16,19 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
         return null;
     return { ...visible, firstLookStatus };
 }
-export function classifyThreadVisibility(threads, seenMap) {
+export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set()) {
     const unresolvedThreads = threads.filter((t) => !t.isResolved);
     const activeThreads = unresolvedThreads
         .filter((t) => !t.isOutdated && !t.isMinimized)
         .flatMap((t) => {
+        if (isConfiguredBotAuthor(t, botUsernames))
+            return [t];
         const visible = classifyVisibleThread(t, seenMap);
         return visible ? [visible] : [];
     });
     const resolutionOnlyThreads = unresolvedThreads
         .filter((t) => t.isOutdated || t.isMinimized)
-        .flatMap((t) => {
-        const visible = classifyVisibleThread(t, seenMap);
-        return visible ? [visible] : [];
-    });
+        .map((t) => classifyVisibleThread(t, seenMap) ?? t);
     const firstLookThreads = [
         ...threads.flatMap((t) => {
             if (!t.isOutdated)

package/bin/comments/visible-comments.mjs

@@ -1,11 +1,11 @@
 import { shouldMinimizeAuthor } from "./minimize-policy.mjs";
 import { classifyItem } from "../state/seen-comments.mjs";
-export function classifyVisibleComments(comments, seenMap, minimizeComments) {
+export function classifyVisibleComments(comments, seenMap, minimizeComments, botUsernames = new Set()) {
     const actionable = [];
     const minimizeIds = [];
     const toMarkSeen = [];
     for (const c of comments.filter((comment) => !comment.isMinimized)) {
-        if (shouldMinimizeAuthor(c.authorType, minimizeComments, c.author)) {
+        if (shouldMinimizeAuthor(c.authorType, minimizeComments, c.author, botUsernames)) {
             actionable.push(c);
             minimizeIds.push(c.id);
             continue;

package/bin/config/load.mjs

@@ -45,6 +45,12 @@ function parseMinimizeCommentsPolicy(value) {
         return value;
     throw new Error(`Invalid config: iterate.minimizeComments must be one of "all", "bots", "users", or "none", got ${JSON.stringify(value)}`);
 }
+function parseBotUsernames(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid config: botUsernames must be an array of strings`);
+    }
+    return value;
+}
 const defaults = builtins;
 const configCache = new Map();
 export function loadConfig() {
@@ -60,6 +66,7 @@ export function loadConfig() {
         const raw = readFileSync(rcPath, "utf8");
         const parsed = (parse(raw) ?? {});
         const config = deepMerge(defaults, parsed);
+        config.botUsernames = parseBotUsernames(config.botUsernames);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;

package/bin/config.json

@@ -1,4 +1,18 @@
 {
+  "botUsernames": [
+    "chatgpt-connector",
+    "openai-codex",
+    "codex",
+    "claude",
+    "copilot-pull-request-reviewer",
+    "gemini-code-assist",
+    "coderabbitai",
+    "greptile-apps",
+    "qodo-merge-pro",
+    "deepsource-io",
+    "sonarqubecloud",
+    "what-the-diff"
+  ],
   "iterate": {
     "fixAttemptsPerThread": 3,
     "stallTimeoutMinutes": 60,

package/bin/github/batch-parsers.mjs

@@ -13,6 +13,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         const comments = t.comments.nodes.map((c) => ({
             id: c.id,
             isMinimized: c.isMinimized,
+            ...(c.pullRequestReview?.id ? { reviewId: c.pullRequestReview.id } : undefined),
             author: c.author?.login ?? "unknown",
             authorType: mapAuthorType(c.author?.__typename, c.author?.login),
             body: c.body,
@@ -27,6 +28,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             path: t.path ?? comment?.path ?? null,
             line: t.line ?? comment?.line ?? null,
             startLine: t.startLine ?? comment?.startLine ?? null,
+            ...(comment?.pullRequestReview?.id ? { reviewId: comment.pullRequestReview.id } : undefined),
             author: comment?.author?.login ?? "unknown",
             authorType: mapAuthorType(comment?.author?.__typename, comment?.author?.login),
             body: comment?.body ?? "",

package/bin/github/client.mjs

@@ -7,9 +7,8 @@
  */
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
-import { graphql as httpGraphql, rest, GitHubRequestError, } from "./http.mjs";
+import { graphql as httpGraphql, rest } from "./http.mjs";
 import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY } from "./queries.mjs";
-export { GitHubRequestError };
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
 // GraphQL — thin re-exports so callers don't need to import http.mts directly

package/bin/github/gql/batch-pr.gql

@@ -83,6 +83,9 @@ query BatchPr(
                 __typename
                 login
               }
+              pullRequestReview {
+                id
+              }
               body
               path
               line

package/bin/reporters/agent.mjs

@@ -13,6 +13,7 @@ export function toAgentThread(t) {
     const suggestion = extractSuggestion(t) ?? undefined;
     return {
         id: t.id,
+        ...(t.reviewId !== undefined && { reviewId: t.reviewId }),
         path: t.path,
         line: t.line,
         ...(t.line !== null &&

package/bin/state/seen-comments.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { readFile, writeFile, rename, unlink, mkdir, access, readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -23,8 +24,14 @@ export function classifyItem(id, body, map) {
     const m = map.get(id);
     if (!m)
         return "new";
-    if (typeof m.bodyHash === "string" && m.bodyHash !== hashBody(body))
+    const currentHash = hashBody(body);
+    if (typeof m.previousBodyHash === "string" && m.previousBodyHash === currentHash) {
+        return "unchanged";
+    }
+    if (typeof m.bodyHash === "string" && m.bodyHash !== currentHash)
         return "edited";
+    if (m.bodyHash === undefined && Array.isArray(m.inlineThreadIds))
+        return "new";
     return "unchanged";
 }
 /**
@@ -94,11 +101,31 @@ export async function hasSeen(key, id) {
  * All errors are silently swallowed — the marker is best-effort.
  */
 export async function markSeen(key, id, body) {
+    await writeSeenMarker(key, id, { bodyHash: hashBody(body) });
+}
+export async function markReviewInlineThreads(key, reviewId, inlineThreadIds) {
+    await writeSeenMarker(key, reviewId, {
+        inlineThreadIds: [...new Set(inlineThreadIds)].sort((a, b) => a.localeCompare(b)),
+    });
+}
+/**
+ * Write a marker after Shepherd successfully replies to a review thread.
+ *
+ * `previousBody` suppresses stale GitHub fetches that have not yet included the new reply.
+ * `body` suppresses the expected final transcript once GitHub includes Shepherd's reply.
+ */
+export async function markReplySeen(key, id, previousBody, body, replyBody) {
+    await writeSeenMarker(key, id, {
+        bodyHash: hashBody(body),
+        previousBodyHash: hashBody(previousBody),
+        replyBodyHash: hashBody(replyBody),
+    });
+}
+async function writeSeenMarker(key, id, markerFields) {
     let tmp;
     try {
         const path = resolvePath(key, id);
         await mkdir(dirname(path), { recursive: true });
-        const newHash = hashBody(body);
         let existing = null;
         try {
             const raw = await readFile(path, "utf8");
@@ -107,14 +134,15 @@ export async function markSeen(key, id, body) {
         catch {
             // no existing marker — will create below
         }
-        if (existing !== null && existing.bodyHash === newHash)
+        const unchanged = Object.entries(markerFields).every(([field, value]) => markerFieldEqual(existing?.[field], value));
+        if (existing !== null && unchanged)
             return;
         const seenAt = existing?.seenAt ?? Date.now();
         tmp = `${path}.${randomUUID()}.tmp`;
         // Store `id` in the payload so loadSeenMap can key by the original ID
         // rather than the filename, guarding against case-insensitive filesystems
         // (e.g. macOS APFS) where IDs differing only in case would collide.
-        await writeFile(tmp, JSON.stringify({ seenAt, bodyHash: newHash, id }), "utf8");
+        await writeFile(tmp, JSON.stringify({ ...existing, seenAt, ...markerFields, id }), "utf8");
         await rename(tmp, path);
         tmp = undefined;
     }
@@ -132,6 +160,14 @@ export async function markSeen(key, id, body) {
         }
     }
 }
+function markerFieldEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (Array.isArray(left) && Array.isArray(right)) {
+        return left.length === right.length && left.every((value, index) => value === right[index]);
+    }
+    return false;
+}
 /** Read the full marker for inspection (returns null on miss or error). */
 export async function readSeenMarker(key, id) {
     try {