pr-shepherd 0.22.0 → 0.24.0

package/bin/cli/mark-files-as-viewed-formatter.mjs

@@ -0,0 +1,52 @@
+export function formatMarkFilesAsViewedResult(result) {
+    const lines = [];
+    lines.push(`# PR #${result.prNumber} — Mark files as viewed (${result.markedPaths.length} marked)`);
+    lines.push("");
+    lines.push(`repo: ${result.repo}`);
+    appendPathSection(lines, "Matched files", result.matchedPaths);
+    appendPathSection(lines, "Marked viewed", result.markedPaths);
+    appendPathSection(lines, "Already viewed", result.alreadyViewedPaths);
+    appendPathSection(lines, "Missing from PR diff", result.missingPaths);
+    appendTextSection(lines, "Unmatched selectors", result.unmatchedSelectors);
+    if (result.rateLimit) {
+        const details = [
+            result.rateLimit.retryAfterSeconds !== undefined
+                ? `retry after ${result.rateLimit.retryAfterSeconds}s`
+                : null,
+            result.rateLimit.remaining !== undefined && result.rateLimit.limit !== undefined
+                ? `remaining ${result.rateLimit.remaining}/${result.rateLimit.limit}`
+                : null,
+            result.rateLimit.resetAt !== undefined
+                ? `reset at ${new Date(result.rateLimit.resetAt * 1000).toISOString()}`
+                : null,
+        ]
+            .filter(Boolean)
+            .join(", ");
+        lines.push("");
+        lines.push(`Stopped: GitHub rate limit hit — ${result.rateLimit.message}${details ? ` (${details})` : ""}`);
+    }
+    appendPathSection(lines, "Not marked due to rate limit", result.unmarkedPaths ?? []);
+    const errors = result.rateLimit
+        ? result.errors.filter((e) => !e.startsWith("rate limit:"))
+        : result.errors;
+    appendTextSection(lines, "Errors", errors);
+    if (result.matchedPaths.length === 0) {
+        lines.push("");
+        lines.push("No files matched.");
+    }
+    return lines.join("\n");
+}
+function appendPathSection(lines, label, paths) {
+    if (paths.length === 0)
+        return;
+    lines.push("");
+    lines.push(`## ${label} (${paths.length})`);
+    lines.push(paths.map((path) => `- \`${path}\``).join("\n"));
+}
+function appendTextSection(lines, label, values) {
+    if (values.length === 0)
+        return;
+    lines.push("");
+    lines.push(`## ${label} (${values.length})`);
+    lines.push(values.map((value) => `- ${value}`).join("\n"));
+}

package/bin/cli/mutate-formatter.mjs

@@ -0,0 +1,50 @@
+function pushIds(lines, label, ids) {
+    if (ids?.length)
+        lines.push(`${label} (${ids.length}): ${ids.join(", ")}`);
+}
+function formatRateLimit(result) {
+    const rateLimit = result.rateLimit;
+    if (rateLimit) {
+        const details = [
+            typeof rateLimit.retryAfterSeconds === "number"
+                ? `retry after ${rateLimit.retryAfterSeconds}s`
+                : null,
+            typeof rateLimit.remaining === "number" && typeof rateLimit.limit === "number"
+                ? `remaining ${rateLimit.remaining}/${rateLimit.limit}`
+                : null,
+            typeof rateLimit.resetAt === "number"
+                ? `reset at ${new Date(rateLimit.resetAt * 1000).toISOString()}`
+                : null,
+        ]
+            .filter(Boolean)
+            .join(", ");
+        const detailSuffix = details ? ` (${details})` : "";
+        return `Stopped: GitHub rate limit hit — ${rateLimit.message}${detailSuffix}`;
+    }
+    return null;
+}
+export function formatMutateResult(result) {
+    const lines = [];
+    pushIds(lines, "Replied to threads", result.repliedThreads);
+    pushIds(lines, "Resolved threads", result.resolvedThreads);
+    pushIds(lines, "Minimized comments", result.minimizedComments);
+    pushIds(lines, "Dismissed reviews", result.dismissedReviews);
+    pushIds(lines, "Skipped dismissals", result.skippedDismissals);
+    pushIds(lines, "Skipped human thread resolves", result.skippedHumanResolves);
+    pushIds(lines, "Skipped human minimizes", result.skippedHumanMinimizes);
+    pushIds(lines, "Skipped human review dismissals", result.skippedHumanDismissals);
+    pushIds(lines, "Skipped non-human/unknown thread replies", result.skippedNonHumanReplies);
+    const rateLimit = formatRateLimit(result);
+    if (rateLimit)
+        lines.push(rateLimit);
+    pushIds(lines, "Not replied due to rate limit", result.unrepliedThreads);
+    pushIds(lines, "Not resolved due to rate limit", result.unresolvedThreads);
+    pushIds(lines, "Not minimized due to rate limit", result.unminimizedComments);
+    pushIds(lines, "Not dismissed due to rate limit", result.undismissedReviews);
+    const errors = result.rateLimit
+        ? result.errors.filter((e) => !e.startsWith("rate limit:"))
+        : result.errors;
+    if (errors.length)
+        lines.push(`Errors:\n  ${errors.join("\n  ")}`);
+    return lines.join("\n");
+}

package/bin/cli-parser.mjs

@@ -7,9 +7,12 @@
  *                  [--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]
- *                            [--dismiss-review-ids Q] [--message MSG] [--require-sha SHA]
+ *                            [--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]
  *                                      [--format text|json]
+ *   pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]
+ *                                           [--format text|json]
  *   pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]
  *                              [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                              [--no-auto-cancel-actionable]
@@ -25,7 +28,7 @@ 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 { handleClean, handleCommitSuggestion, handleIterate } from "./cli/handlers.mjs";
+import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
@@ -75,6 +78,9 @@ export async function main(argv) {
         case "commit-suggestion":
             await handleCommitSuggestion(args.slice(1));
             break;
+        case "mark-files-as-viewed":
+            await handleMarkFilesAsViewed(args.slice(1));
+            break;
         case "iterate":
             await handleIterate(args.slice(1));
             break;
@@ -119,12 +125,14 @@ async function handleLogFile(args) {
 async function handleResolve(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
+    const replyThreadIds = parseList(getFlag(extra, "--reply-thread-ids"));
     const minimizeCommentIds = parseList(getFlag(extra, "--minimize-comment-ids"));
     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) {
@@ -138,6 +146,7 @@ async function handleResolve(args) {
             ...globalOpts,
             prNumber,
             resolveThreadIds,
+            replyThreadIds,
             minimizeCommentIds,
             dismissReviewIds,
             dismissMessage,

package/bin/commands/check.mjs

@@ -3,8 +3,6 @@ import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { fetchStartupFailureChecks, triageFailingChecks } from "../checks/triage.mjs";
-import { getOutdatedThreads } from "../comments/outdated.mjs";
-import { autoResolveOutdated } from "../comments/resolve.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
@@ -14,6 +12,10 @@ import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.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";
+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,51 +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 unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved);
-    const outdated = getOutdatedThreads(unresolvedThreads);
-    let autoResolved = [];
-    let autoResolveErrors = [];
-    if (opts.autoResolve && outdated.length > 0) {
-        const { resolved: resolvedIds, errors } = await autoResolveOutdated(outdated.map((t) => t.id));
-        const resolvedIdsSet = new Set(resolvedIds); // ⚡ Bolt optimization: O(1) lookup
-        autoResolved = outdated.filter((t) => resolvedIdsSet.has(t.id));
-        autoResolveErrors = errors;
-    }
-    const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated && !t.isMinimized);
-    const outdatedCandidates = batchData.reviewThreads.filter((t) => t.isOutdated);
-    const resolvedCandidates = batchData.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
-    const minimizedThreadCandidates = batchData.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized);
-    const visibleCommentClassification = classifyVisibleComments(batchData.comments, seenMap, config.iterate.minimizeComments);
-    const autoResolvedIds = new Set(autoResolved.map((t) => t.id));
-    const firstLookThreads = [
-        ...outdatedCandidates.flatMap((t) => {
-            const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
-            if (cls === "unchanged")
-                return [];
-            const base = {
-                ...t,
-                firstLookStatus: "outdated",
-                autoResolved: autoResolvedIds.has(t.id),
-            };
-            return cls === "edited" ? [{ ...base, edited: true }] : [base];
-        }),
-        ...resolvedCandidates.flatMap((t) => {
-            const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
-            if (cls === "unchanged")
-                return [];
-            const base = { ...t, firstLookStatus: "resolved" };
-            return cls === "edited" ? [{ ...base, edited: true }] : [base];
-        }),
-        ...minimizedThreadCandidates.flatMap((t) => {
-            const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
-            if (cls === "unchanged")
-                return [];
-            const base = { ...t, firstLookStatus: "minimized" };
-            return cls === "edited" ? [{ ...base, edited: true }] : [base];
-        }),
-    ];
+    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")
@@ -107,16 +69,23 @@ export async function runCheck(opts) {
         else
             seenSummaries.push(r);
     }
+    const changesRequestedReviewVisibility = classifyReviewsForDisplay(batchData.changesRequestedReviews, seenMap);
+    const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     await Promise.allSettled([
-        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
         ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+        ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
         ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
         ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
+        ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+        ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
-    const resolutionOnlyThreads = unresolvedThreads.filter((t) => !autoResolvedIds.has(t.id) && (t.isOutdated || t.isMinimized));
-    let status = computeStatus(verdict, activeThreads.length + resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, batchData.changesRequestedReviews.length);
+    await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
+    const changesRequestedReviews = changesRequestedReviewVisibility.visible;
+    const changesRequestedReviewCount = batchData.changesRequestedReviews.length;
+    const approvedReviews = approvedReviewVisibility.visible;
+    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
     if (status === "READY" && !didRefreshMergeability) {
-        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, activeThreads.length + resolutionOnlyThreads.length, visibleCommentClassification.actionable.length);
+        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length);
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
@@ -139,22 +108,22 @@ export async function runCheck(opts) {
             blockedByFilteredCheck,
         },
         threads: {
-            actionable: activeThreads,
-            resolutionOnly: resolutionOnlyThreads,
-            autoResolved,
-            autoResolveErrors,
-            firstLook: firstLookThreads,
+            actionable: threadVisibility.activeThreads,
+            resolutionOnly: threadVisibility.resolutionOnlyThreads,
+            autoResolved: [],
+            autoResolveErrors: [],
+            firstLook: threadVisibility.firstLookThreads,
         },
         comments: {
             actionable: visibleCommentClassification.actionable,
             minimizeIds: visibleCommentClassification.minimizeIds,
             firstLook: firstLookComments,
         },
-        changesRequestedReviews: batchData.changesRequestedReviews,
+        changesRequestedReviews,
         reviewSummaries: seenSummaries,
         firstLookSummaries,
         editedSummaries,
-        approvedReviews: batchData.approvedReviews,
+        approvedReviews,
         branchProtection: batchData.branchProtection,
     };
 }

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

@@ -19,5 +19,5 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName, includeD
     const driftHint = includeDriftHint
         ? " If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step."
         : " If the patch fails to apply, fall through to the manual-edit step.";
-    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`: run \`${command}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved).${driftHint} Do not retry the same command.`;
+    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`: run \`${command}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Human-authored thread IDs are replied to by the resolve command below; Shepherd does not auto-resolve them.${driftHint} Do not retry the same command.`;
 }

package/bin/commands/iterate/classify.mjs

@@ -1,5 +1,6 @@
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { shouldMinimizeAuthor } from "../../comments/minimize-policy.mjs";
+import { isConfiguredBotAuthor, isHumanAuthor, } from "../../comments/authors.mjs";
 function dedupeIds(ids) {
     const seen = new Set();
     const out = [];
@@ -11,23 +12,28 @@ 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))
+        .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))
+            if (shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
                 minimizeIds.push(r.id);
+            else
+                surfacedApprovals.push(r);
         }
         return {
             minimizeIds,
             firstLookSummaries: summaries.firstLook,
             editedSummaries: summaries.edited,
-            surfacedApprovals: [],
+            surfacedApprovals,
         };
     }
     return {
@@ -37,45 +43,40 @@ 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 resolveThreadIds = dedupeIds(threads.map((t) => t.id));
-    const threadIds = dedupeIds([...resolveThreadIds, ...resolutionOnlyThreads.map((t) => t.id)]);
-    if (threadIds.length > 0) {
-        argv.push("--resolve-thread-ids", threadIds.join(","));
+    const allThreads = [...threads, ...resolutionOnlyThreads];
+    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");
+    }
+    if (resolveThreadIds.length > 0) {
+        argv.push("--resolve-thread-ids", resolveThreadIds.join(","));
     }
     if (allCommentIds.length > 0) {
         argv.push("--minimize-comment-ids", allCommentIds.join(","));
     }
-    const commentIdSet = new Set(allCommentIds);
-    const filteredReviewIds = [];
-    const droppedDismissReviewIds = [];
-    for (const review of reviews) {
-        if (commentIdSet.has(review.id))
-            droppedDismissReviewIds.push(review.id);
-        else
-            filteredReviewIds.push(review.id);
-    }
-    const hasDismiss = filteredReviewIds.length > 0;
-    if (hasDismiss) {
-        argv.push("--dismiss-review-ids", filteredReviewIds.join(","));
-        argv.push("--message", "$DISMISS_MESSAGE");
-    }
-    // hasMutations = we appended at least one of --resolve-thread-ids,
-    // --minimize-comment-ids, or --dismiss-review-ids. Returned explicitly
+    // hasMutations = we appended at least one reply, resolve, or minimize mutation. Returned explicitly
     // (rather than derived from argv.length) so callers don't couple to the
     // base-argv shape.
-    const hasMutations = threadIds.length > 0 || allCommentIds.length > 0 || filteredReviewIds.length > 0;
+    const hasMutations = replyThreadIds.length > 0 || resolveThreadIds.length > 0 || allCommentIds.length > 0;
     // `requiresHeadSha` is only added when this resolve command includes a
-    // mutation that can race with a moving HEAD: resolving actionable threads,
-    // dismissing CHANGES_REQUESTED reviews, or addressing failing checks.
-    const hasCodeMutations = hasMutations && (threads.length > 0 || checks.length > 0 || filteredReviewIds.length > 0);
+    // mutation that can race with a moving HEAD: replying after actionable
+    // thread fixes or addressing failing checks.
+    const hasCodeMutations = hasMutations && (threads.length > 0 || checks.length > 0);
     const requiresHeadSha = hasCodeMutations;
     return {
         argv,
         requiresHeadSha,
-        requiresDismissMessage: hasDismiss,
-        ...(droppedDismissReviewIds.length > 0 ? { droppedDismissReviewIds } : undefined),
+        requiresDismissMessage: replyThreadIds.length > 0,
+        ...(replyThreadIds.length > 0 ? { replyThreadIds } : undefined),
+        ...(resolveThreadIds.length > 0 ? { resolveThreadIds } : undefined),
         hasMutations,
     };
 }

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

@@ -1,25 +1,35 @@
 /* eslint-disable max-lines */
-import { readFixAttempts, writeFixAttempts } from "../../state/fix-attempts.mjs";
+import { readFixAttempts, writeFixAttempts, } from "../../state/fix-attempts.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
-import { markSeen } from "../../state/seen-comments.mjs";
+import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
 import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
 import { annotationMarkerBody } from "../check-annotations.mjs";
+import { threadTranscriptBody } from "../../threads/transcript.mjs";
+function nextFixAttempts(stored, headSha, threads) {
+    const threadAttempts = stored ? { ...stored.threadAttempts } : {};
+    const threadBodyHashes = stored?.threadBodyHashes
+        ? { ...stored.threadBodyHashes }
+        : {};
+    for (const t of threads) {
+        const bodyHash = hashBody(threadTranscriptBody(t));
+        const previousHash = threadBodyHashes[t.id];
+        if (stored?.headSha === headSha && (previousHash === undefined || previousHash === bodyHash))
+            continue;
+        threadAttempts[t.id] = previousHash === bodyHash ? (threadAttempts[t.id] ?? 0) + 1 : 1;
+        threadBodyHashes[t.id] = bodyHash;
+    }
+    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 isNewSha = stored?.headSha !== headSha;
-    const currentAttempts = stored ? { ...stored.threadAttempts } : {};
-    if (isNewSha) {
-        for (const t of report.threads.actionable) {
-            currentAttempts[t.id] = (currentAttempts[t.id] ?? 0) + 1;
-        }
-    }
-    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, currentAttempts);
+    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
+    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, threadAttempts);
     if (escalateTriggers.triggers.length > 0) {
         const escalateBase = {
             triggers: escalateTriggers.triggers,
@@ -38,7 +48,7 @@ export async function handleFixCode(ctx) {
             },
         };
     }
-    await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts: currentAttempts });
+    await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
     let cancelled = [];
     if (!opts.noAutoCancelActionable) {
         const uniqueRunIds = [
@@ -66,13 +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 overlappingReviewIds = resolveCommand.droppedDismissReviewIds ?? [];
-    if (overlappingReviewIds.length > 0) {
-        process.stderr.write(`pr-shepherd: resolve command overlap: ${overlappingReviewIds.length} ` +
-            `review IDs were also in minimize/comment IDs and were dropped from --dismiss-review-ids: ` +
-            `${overlappingReviewIds.join(", ")}\n`);
-    }
+    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

@@ -65,7 +65,7 @@ export function buildFixInstructions(threads, actionableComments, checks, change
         instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.${suggestionFallback}`);
     }
     if (resolutionOnlyThreads.length > 0) {
-        instructions.push(`Resolve the threads under \`## Review threads to resolve\` with the \`resolve:\` command shown below. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
+        instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`resolve:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
     }
     instructions.push(...buildFailingCheckInstructions(checks));
     if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
@@ -78,12 +78,15 @@ 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)`);
         }
         if (resolveCommand.requiresDismissMessage) {
-            substituteParts.push(`\`$DISMISS_MESSAGE\` with a one-sentence description of what you changed`);
+            substituteParts.push(`\`$DISMISS_MESSAGE\` with a one-sentence reply/description of what you changed`);
         }
         const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
         instructions.push(`Run the \`resolve:\` command shown above${substituteHint}.`);
@@ -105,7 +108,7 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     if (editedTotal > 0) {
         instructions.push(`Items marked \`[edited since first look]\`, items under \`## Review summaries (edited since first look)\`, and any first-look bullet tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
     }
-    if (resolveCommand.hasMutations) {
+    if (resolveCommand.hasMutations || hasNonConflictHints || firstLookTotal > 0) {
         instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));
     }
     instructions.push(FIX_INSTRUCTION_STOP);

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}`),