pr-shepherd 0.10.2 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -128,6 +128,7 @@ Recommendations:
 - Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. As it uses `/loop`, it will continue working when your rate limit window is reset. The loop cancels automatically when the PR is merged, closed, or after the ready-delay elapses.
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
+- Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
 
 ## Design Principles
 

package/bin/checks/triage.mjs

@@ -1,23 +1,19 @@
-import { rest, restText } from "../github/http.mjs";
-export function triageFailingChecks(failingChecks, repo, logTailLines, logTailChars = 200) {
+import { rest } from "../github/http.mjs";
+export function triageFailingChecks(failingChecks, repo) {
     const jobsCache = new Map();
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, logTailLines, logTailChars)));
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
 }
-async function triageCheck(check, repo, jobsCache, logTailLines, logTailChars) {
-    if (check.runId === null) {
+async function triageCheck(check, repo, jobsCache) {
+    if (check.runId === null || check.conclusion === "CANCELLED") {
         return { ...check };
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache);
     const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
-    const logTail = jobInfo?.jobId !== undefined && logTailLines > 0
-        ? await fetchLogTail(jobInfo.jobId, repo, logTailLines, logTailChars, jobInfo.failedStep)
-        : undefined;
     return {
         ...check,
         ...(jobInfo?.workflowName !== undefined && { workflowName: jobInfo.workflowName }),
         ...(jobInfo?.jobName !== undefined && { jobName: jobInfo.jobName }),
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
-        ...(logTail !== undefined && { logTail }),
     };
 }
 function fetchJobs(runId, repo, cache) {
@@ -67,42 +63,5 @@ function pickJobInfo(jobs, checkName) {
         workflowName: job.workflow_name,
         jobName: job.name,
         failedStep,
-        jobId: job.id,
     };
 }
-async function fetchLogTail(jobId, repo, logTailLines, logTailChars, failedStepName) {
-    const { owner, name } = repo;
-    try {
-        const text = await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`);
-        const allLines = text.split("\n");
-        const stepLines = failedStepName ? extractStepLines(allLines, failedStepName) : null;
-        const lines = stepLines ?? allLines;
-        const tail = lines.length <= logTailLines ? lines.join("\n") : lines.slice(-logTailLines).join("\n");
-        return tail.length <= logTailChars ? tail : tail.slice(-logTailChars);
-    }
-    catch {
-        return undefined;
-    }
-}
-// Extract the lines inside the ##[group]..##[endgroup] section for the named step.
-// Returns null when no matching group is found so the caller falls back to the full log.
-function extractStepLines(lines, stepName) {
-    const lowerStep = stepName.toLowerCase();
-    let inStep = false;
-    const result = [];
-    for (const line of lines) {
-        const content = line.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z\s+/, "");
-        if (!inStep) {
-            if (content.startsWith("##[group]") && content.slice(9).toLowerCase().includes(lowerStep)) {
-                inStep = true;
-            }
-        }
-        else if (content.startsWith("##[endgroup]")) {
-            inStep = false;
-        }
-        else {
-            result.push(line);
-        }
-    }
-    return result.length > 0 ? result : null;
-}

package/bin/cli/fix-formatter.mjs

@@ -1,5 +1,4 @@
 import { renderResolveCommand } from "../commands/iterate.mjs";
-import { safeFence } from "./fence.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
 import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "./list-formatters.mjs";
@@ -37,16 +36,13 @@ export function formatFixCodeResult(header, result) {
                 : ch.detailsUrl
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
-            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\``];
-            if (ch.failedStep)
-                lines.push(`  > ${ch.failedStep}`);
-            if (ch.summary)
-                lines.push(`  > ${ch.summary}`);
-            if (ch.logTail) {
-                const fence = safeFence(ch.logTail);
-                lines.push(`  ${fence}`);
-                lines.push(ch.logTail.replace(/^/gm, "  ").trimEnd());
-                lines.push(`  ${fence}`);
+            const conclusionTag = ch.conclusion !== null ? ` [conclusion: ${ch.conclusion}]` : "";
+            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}`];
+            if (ch.conclusion !== "CANCELLED") {
+                if (ch.failedStep)
+                    lines.push(`  > ${ch.failedStep}`);
+                if (ch.summary)
+                    lines.push(`  > ${ch.summary}`);
             }
             return lines.join("\n");
         });
@@ -63,6 +59,13 @@ export function formatFixCodeResult(header, result) {
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }
+    if (result.fix.editedSummaries.length > 0) {
+        sections.push("## Review summaries (edited since first look — already minimized; do not re-minimize)");
+        for (const r of result.fix.editedSummaries) {
+            sections.push(`### \`reviewId=${r.id}\` (@${r.author})`);
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
+        }
+    }
     const firstLookSummaryIds = new Set(result.fix.firstLookSummaries.map((r) => r.id));
     const seenSummaryIds = result.fix.reviewSummaryIds.filter((id) => !firstLookSummaryIds.has(id));
     if (seenSummaryIds.length > 0) {
@@ -84,10 +87,15 @@ export function formatFixCodeResult(header, result) {
             bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of result.fix.firstLookComments) {
-            bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
+            const editedSuffix = c.edited ? ", edited" : "";
+            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
         }
         sections.push(bullets.join("\n"));
     }
+    if (result.fix.inProgressRunIds.length > 0) {
+        sections.push("## In-progress runs");
+        sections.push(result.fix.inProgressRunIds.map((id) => `- \`${id}\``).join("\n"));
+    }
     if (result.cancelled.length > 0) {
         sections.push("## Cancelled runs");
         sections.push(result.cancelled.map((id) => `- \`${id}\``).join("\n"));

package/bin/cli/formatters.mjs

@@ -44,7 +44,8 @@ export function formatFetchResult(result) {
             bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of result.firstLookComments) {
-            bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
+            const editedSuffix = c.edited ? ", edited" : "";
+            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
         }
         sections.push(bullets.join("\n"));
     }
@@ -66,48 +67,29 @@ export function formatCommitSuggestionResult(result) {
     const range = result.startLine === result.endLine
         ? `line ${result.startLine}`
         : `lines ${result.startLine}–${result.endLine}`;
-    function pushPatch(patch) {
-        const fence = safeFence(patch);
+    lines.push(`Suggestion from @${result.author} for PR #${result.pr} — thread ${result.threadId}:`);
+    lines.push(`  repo: ${result.repo}`);
+    lines.push(`  ${result.path} (${range})`);
+    if (result.patch) {
+        const fence = safeFence(result.patch);
         lines.push("");
         lines.push(`${fence}diff`);
-        lines.push(patch.trimEnd());
+        lines.push(result.patch.trimEnd());
         lines.push(fence);
     }
-    if (result.dryRun) {
-        if (result.valid) {
-            lines.push(`Dry-run: would apply suggestion from @${result.author}:`);
-            lines.push(`  ${result.path} (${range})`);
-        }
-        else {
-            lines.push(`Dry-run: suggestion cannot apply cleanly:`);
-            lines.push(`- path: ${result.path} (${range})`);
-            lines.push(`- author: @${result.author}`);
-            lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        }
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    else if (result.applied) {
-        lines.push(`Applied suggestion from @${result.author}:`);
-        lines.push(`  ${result.path} (${range})`);
-        if (result.commitSha)
-            lines.push(`Commit: ${result.commitSha}`);
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    else {
-        lines.push(`Failed to apply suggestion ${result.threadId}:`);
-        lines.push(`- path: ${result.path} (${range})`);
-        lines.push(`- author: @${result.author}`);
-        lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    if (result.postActionInstruction) {
+    lines.push("");
+    lines.push("## Suggested commit message");
+    lines.push("");
+    lines.push(result.commitMessage);
+    lines.push("");
+    lines.push(result.commitBody);
+    if (result.postActionInstructions.length > 0) {
         lines.push("");
         lines.push("## Instructions");
         lines.push("");
-        lines.push(`1. ${result.postActionInstruction}`);
+        result.postActionInstructions.forEach((inst, i) => {
+            lines.push(`${i + 1}. ${inst}`);
+        });
     }
     return lines.join("\n");
 }

package/bin/cli/handlers.mjs

@@ -11,14 +11,12 @@ export async function handleCommitSuggestion(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
     if (!threadId) {
-        process.stderr.write("Usage: pr-shepherd commit-suggestion [PR] --thread-id ID [--message MSG] [--description DESC] [--dry-run]\n" +
-            "       (--message is required unless --dry-run is set)\n");
+        process.stderr.write("Usage: pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]\n");
         process.exitCode = 1;
         return;
     }
-    const dryRun = hasFlag(extra, "--dry-run");
     const message = getFlag(extra, "--message") ?? undefined;
-    if (!dryRun && (!message || message.trim() === "")) {
+    if (!message || message.trim() === "") {
         process.stderr.write("--message is required and must be non-empty\n");
         process.exitCode = 1;
         return;
@@ -30,17 +28,10 @@ export async function handleCommitSuggestion(args) {
         threadId,
         message,
         description,
-        dryRun,
     });
     process.stdout.write(globalOpts.format === "json"
         ? `${JSON.stringify(result, null, 2)}\n`
         : `${formatCommitSuggestionResult(result)}\n`);
-    if (result.dryRun) {
-        process.exitCode = result.valid ? 0 : 1;
-    }
-    else {
-        process.exitCode = result.applied ? 0 : 1;
-    }
 }
 export async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);

package/bin/cli/iterate-lean.mjs

@@ -55,6 +55,9 @@ export function projectIterateLean(result) {
                     ...(result.fix.firstLookSummaries.length > 0 && {
                         firstLookSummaries: result.fix.firstLookSummaries,
                     }),
+                    ...(result.fix.editedSummaries.length > 0 && {
+                        editedSummaries: result.fix.editedSummaries,
+                    }),
                     ...(result.fix.surfacedApprovals.length > 0 && {
                         surfacedApprovals: result.fix.surfacedApprovals,
                     }),
@@ -64,6 +67,9 @@ export function projectIterateLean(result) {
                     ...(result.fix.firstLookComments.length > 0 && {
                         firstLookComments: result.fix.firstLookComments,
                     }),
+                    ...(result.fix.inProgressRunIds.length > 0 && {
+                        inProgressRunIds: result.fix.inProgressRunIds,
+                    }),
                     ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
                     ...(result.fix.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.fix.changesRequestedReviews,

package/bin/cli/list-formatters.mjs

@@ -6,7 +6,10 @@ export function renderBodyPreview(body) {
     return firstLine.slice(0, BODY_PREVIEW_MAX);
 }
 export function renderFirstLookStatusTag(t) {
-    return t.autoResolved ? "[status: outdated, auto-resolved]" : `[status: ${t.firstLookStatus}]`;
+    const editedSuffix = t.edited ? ", edited" : "";
+    return t.autoResolved
+        ? `[status: outdated, auto-resolved${editedSuffix}]`
+        : `[status: ${t.firstLookStatus}${editedSuffix}]`;
 }
 export function renderThreadBullet(t, opts = {}) {
     const link = t.url ? ` [↗](${t.url})` : "";

package/bin/cli-parser.iterate-fixtures.mjs

@@ -31,6 +31,7 @@ export function makeIterateResult(action = "wait") {
                 actionableComments: [],
                 reviewSummaryIds: [],
                 firstLookSummaries: [],
+                editedSummaries: [],
                 surfacedApprovals: [],
                 checks: [],
                 changesRequestedReviews: [],
@@ -43,6 +44,7 @@ export function makeIterateResult(action = "wait") {
                 instructions: ["End this iteration."],
                 firstLookThreads: [],
                 firstLookComments: [],
+                inProgressRunIds: [],
             },
             cancelled: [],
         };

package/bin/commands/check.mjs

@@ -1,17 +1,3 @@
-/**
- * `shepherd check [PR]`
- *
- * Read-only snapshot of PR status. Fetches CI + comments + merge status in
- * one GraphQL request, applies all classifiers, and returns a ShepherdReport.
- *
- * Exit codes:
- *   0  READY — all checks passed, no unresolved threads, CLEAN merge status.
- *   1  FAILING — CI has red checks, or merge has conflicts.
- *   1  PENDING — CI passing but merge blocked (BLOCKED, UNSTABLE, or BEHIND).
- *   1  UNKNOWN — merge state unresolvable.
- *   2  IN_PROGRESS — CI checks still running.
- *   3  UNRESOLVED_COMMENTS — CI ok but actionable threads remain.
- */
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getRepoInfo, getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
@@ -21,7 +7,7 @@ import { autoResolveOutdated } from "../comments/resolve.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { loadSeenSet, markSeen } from "../state/seen-comments.mjs";
+import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -29,14 +15,10 @@ export async function runCheck(opts) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
     const config = loadConfig();
-    // Only paginate APPROVED reviews when the caller will actually minimize them.
-    // Otherwise the first-page cap of 50 (already in the batch) is plenty — no extra round-trip.
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
     let batchData = result.data;
-    // GraphQL sometimes returns UNKNOWN for mergeable/mergeStateStatus while the
-    // REST API already has the correct value. Fall back to REST in that case.
-    // Skip for non-OPEN PRs — REST also returns UNKNOWN for merged/closed PRs.
+    // Fall back to REST when GraphQL returns UNKNOWN — skip for non-OPEN PRs.
     if ((batchData.state ?? "OPEN") === "OPEN" &&
         (batchData.mergeable === "UNKNOWN" || batchData.mergeStateStatus === "UNKNOWN")) {
         const restState = await getMergeableState(prNumber, repo.owner, repo.name);
@@ -53,13 +35,10 @@ export async function runCheck(opts) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
-    const triaged = failing.length > 0 && !opts.skipTriage
-        ? await triageFailingChecks(failing, repo, config.checks.logTailLines, config.checks.logTailChars)
-        : failing;
+    const triaged = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
-    // Auto-resolve outdated threads.
     const outdated = getOutdatedThreads(unresolvedThreads);
     let autoResolved = [];
     let autoResolveErrors = [];
@@ -69,51 +48,70 @@ export async function runCheck(opts) {
         autoResolveErrors = errors;
     }
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
-    // First-look: collect previously-hidden items not yet seen by the agent.
     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 seenSet = await loadSeenSet(stateKey);
+    const seenMap = await loadSeenMap(stateKey);
     const autoResolvedIds = new Set(autoResolved.map((t) => t.id));
     const firstLookThreads = [
-        ...outdatedCandidates
-            .filter((t) => !seenSet.has(t.id))
-            .map((t) => ({
-            ...t,
-            firstLookStatus: "outdated",
-            autoResolved: autoResolvedIds.has(t.id),
-        })),
-        ...resolvedCandidates
-            .filter((t) => !seenSet.has(t.id))
-            .map((t) => ({ ...t, firstLookStatus: "resolved" })),
-        ...minimizedThreadCandidates
-            .filter((t) => !seenSet.has(t.id))
-            .map((t) => ({ ...t, firstLookStatus: "minimized" })),
+        ...outdatedCandidates.flatMap((t) => {
+            const cls = classifyItem(t.id, t.body, 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, t.body, 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, t.body, seenMap);
+            if (cls === "unchanged")
+                return [];
+            const base = { ...t, firstLookStatus: "minimized" };
+            return cls === "edited" ? [{ ...base, edited: true }] : [base];
+        }),
     ];
-    const firstLookComments = minimizedCommentCandidates
-        .filter((c) => !seenSet.has(c.id))
-        .map((c) => ({ ...c, firstLookStatus: "minimized" }));
-    // Split review summaries into first-look (unseen — surface body) vs seen (minimize silently).
-    const firstLookSummaries = batchData.reviewSummaries.filter((r) => !seenSet.has(r.id));
-    const seenSummaries = batchData.reviewSummaries.filter((r) => seenSet.has(r.id));
-    // Mark first-look items as seen (best-effort — markSeen never throws).
+    const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
+        const cls = classifyItem(c.id, c.body, seenMap);
+        if (cls === "unchanged")
+            return [];
+        const base = { ...c, firstLookStatus: "minimized" };
+        return cls === "edited" ? [{ ...base, edited: true }] : [base];
+    });
+    const firstLookSummaries = [];
+    const editedSummaries = [];
+    const seenSummaries = [];
+    for (const r of batchData.reviewSummaries) {
+        const cls = classifyItem(r.id, r.body, seenMap);
+        if (cls === "new")
+            firstLookSummaries.push(r);
+        else if (cls === "edited")
+            editedSummaries.push(r);
+        else
+            seenSummaries.push(r);
+    }
     await Promise.allSettled([
-        ...firstLookThreads.map((t) => markSeen(stateKey, t.id)),
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id)),
-        ...firstLookSummaries.map((r) => markSeen(stateKey, r.id)),
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
+        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+        ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
-    // Actionable: all active threads and all visible comments (no classification — LLM handles triage).
     const actionableThreads = activeThreads;
     const actionableComments = visibleComments;
-    // Derive merge status.
     const mergeStatus = deriveMergeStatus(batchData);
-    // Derive blockedByFilteredCheck ghost state.
     const blockedByFilteredCheck = mergeStatus.status === "BLOCKED" &&
         !verdict.anyFailing &&
         !verdict.anyInProgress &&
         verdict.filteredNames.length > 0;
-    // Compute overall status.
     const status = computeStatus(verdict, actionableThreads.length, actionableComments.length, mergeStatus, batchData.changesRequestedReviews.length);
     return {
         pr: prNumber,
@@ -144,6 +142,7 @@ export async function runCheck(opts) {
         changesRequestedReviews: batchData.changesRequestedReviews,
         reviewSummaries: seenSummaries,
         firstLookSummaries,
+        editedSummaries,
         approvedReviews: batchData.approvedReviews,
     };
 }

package/bin/commands/commit-suggestion.mjs

@@ -1,11 +1,8 @@
 import { execFile as execFileCb } from "node:child_process";
-import { readFile, writeFile, unlink } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
-import { applyResolveOptions } from "../comments/resolve.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
 const execFile = promisify(execFileCb);
@@ -13,13 +10,9 @@ export async function runCommitSuggestion(opts) {
     if (!opts.threadId) {
         throw new Error("--thread-id is required");
     }
-    if (!opts.dryRun && (!opts.message || opts.message.trim() === "")) {
+    if (!opts.message || opts.message.trim() === "") {
         throw new Error("--message is required and must be non-empty");
     }
-    const { stdout: statusOut } = await execFile("git", ["status", "--porcelain"]);
-    if (statusOut.trim() !== "") {
-        throw new Error("Working tree has uncommitted changes. Commit or stash them before running commit-suggestion.");
-    }
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
@@ -56,6 +49,17 @@ export async function runCommitSuggestion(opts) {
     if (!thread.path || thread.line === null) {
         throw new Error(`Thread ${opts.threadId} has no file/line anchor.`);
     }
+    // Validate the target file is clean before generating the patch, so the emitted
+    // `git add -- <file>` instruction cannot accidentally stage unrelated local edits.
+    const { stdout: fileStatus } = await execFile("git", [
+        "status",
+        "--porcelain",
+        "--",
+        thread.path,
+    ]);
+    if (fileStatus.trim() !== "") {
+        throw new Error(`${thread.path} has uncommitted changes. Commit or stash them before running commit-suggestion.`);
+    }
     const parsed = parseSuggestion(thread.body);
     if (!parsed) {
         throw new Error(`Thread ${opts.threadId} has no suggestion block in the comment body.`);
@@ -75,74 +79,25 @@ export async function runCommitSuggestion(opts) {
         endLine,
         replacementLines: parsed.lines,
     });
-    const patchFile = join(tmpdir(), `pr-shepherd-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`);
-    let patchError = null;
-    try {
-        await writeFile(patchFile, patch, { mode: 0o600 });
-        try {
-            await execFile("git", ["apply", "--check", patchFile]);
-        }
-        catch (err) {
-            patchError = (err.stderr?.trim() || String(err)).trim();
-        }
-        if (opts.dryRun) {
-            return {
-                pr: prNumber,
-                repo: `${repo.owner}/${repo.name}`,
-                threadId: opts.threadId,
-                path: filePath,
-                startLine,
-                endLine,
-                author: thread.author,
-                applied: false,
-                dryRun: true,
-                valid: patchError === null,
-                reason: patchError !== null ? `git apply rejected the patch: ${patchError}` : null,
-                patch,
-                postActionInstruction: patchError === null ? "Re-run without --dry-run to apply and commit." : "",
-            };
-        }
-        if (patchError !== null) {
-            return {
-                pr: prNumber,
-                repo: `${repo.owner}/${repo.name}`,
-                threadId: opts.threadId,
-                path: filePath,
-                startLine,
-                endLine,
-                author: thread.author,
-                applied: false,
-                reason: `git apply rejected the patch: ${patchError}`,
-                patch,
-                postActionInstruction: "",
-            };
-        }
-        try {
-            await execFile("git", ["apply", patchFile]);
-        }
-        catch (applyErr) {
-            try {
-                await execFile("git", ["checkout", "--", filePath]);
-            }
-            catch {
-                // best-effort rollback
-            }
-            throw applyErr;
-        }
-    }
-    finally {
-        await unlink(patchFile).catch(() => undefined);
-    }
-    await execFile("git", ["add", "--", filePath]);
     const coAuthor = `Co-authored-by: ${thread.author} <${thread.author}@users.noreply.github.com>`;
     const commitBody = opts.description ? `${opts.description}\n\n${coAuthor}` : coAuthor;
-    await execFile("git", ["commit", "-m", opts.message, "-m", commitBody]);
-    const { stdout: shaOut } = await execFile("git", ["rev-parse", "HEAD"]);
-    const commitSha = shaOut.trim();
-    const resolveResult = await applyResolveOptions(prNumber, repo, {
-        resolveThreadIds: [opts.threadId],
-    });
-    const resolveErrors = resolveResult.errors;
+    const commitMessageArg = opts.message;
+    const commitBodyArg = commitBody;
+    const quotedPath = `'${filePath.replace(/'/g, "'\\''")}'`;
+    const range = startLine === endLine ? `line ${startLine}` : `lines ${startLine}–${endLine}`;
+    const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+    const commitCmd = [
+        "git commit",
+        `-m ${sq(commitMessageArg)}`,
+        ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
+    ].join(" ");
+    const postActionInstructions = [
+        `Apply the patch to \`${filePath}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
+        `Stage the file: \`git add -- ${quotedPath}\``,
+        `Commit: \`${commitCmd}\``,
+        `Resolve the thread on GitHub: \`npx pr-shepherd resolve ${prNumber} --resolve-thread-ids ${opts.threadId}\``,
+        `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
+    ];
     return {
         pr: prNumber,
         repo: `${repo.owner}/${repo.name}`,
@@ -151,11 +106,10 @@ export async function runCommitSuggestion(opts) {
         startLine,
         endLine,
         author: thread.author,
-        applied: true,
-        commitSha,
         patch,
-        postActionInstruction: resolveErrors.length > 0
-            ? `Commit created (${commitSha}), but failed to resolve thread ${opts.threadId}: ${resolveErrors.join("; ")}. Run \`git push\` then resolve manually.`
-            : "Run `git push` (or `git push --force-with-lease` after rebasing) to publish the commit.",
+        commitMessage: commitMessageArg,
+        commitBody: commitBodyArg,
+        filesToStage: [filePath],
+        postActionInstructions,
     };
 }

package/bin/commands/iterate/classify.mjs

@@ -1,13 +1,24 @@
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
-    // Both first-look and seen summaries go into the minimize mutation; first-look bodies are
-    // rendered in the output so the agent sees them before the minimize happens.
+    // 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].map((r) => r.id);
     if (minimizeApprovals) {
         for (const r of approvals)
             minimizeIds.push(r.id);
-        return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: [] };
+        return {
+            minimizeIds,
+            firstLookSummaries: summaries.firstLook,
+            editedSummaries: summaries.edited,
+            surfacedApprovals: [],
+        };
     }
-    return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: approvals };
+    return {
+        minimizeIds,
+        firstLookSummaries: summaries.firstLook,
+        editedSummaries: summaries.edited,
+        surfacedApprovals: approvals,
+    };
 }
 export function buildResolveCommand(threads, allCommentIds, reviews, checks, prNumber) {
     const argv = ["npx", "pr-shepherd", "resolve", String(prNumber)];

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

@@ -4,9 +4,9 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { tryCancelRun } from "./helpers.mjs";
+import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
@@ -46,12 +46,19 @@ export async function handleFixCode(ctx) {
         const results = await Promise.all(uniqueRunIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
         cancelled = results.filter((id) => id !== null);
     }
+    const cancelledSet = new Set(cancelled);
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
     const actionableComments = report.comments.actionable.map(toAgentComment);
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
+    const needsPush = threads.length > 0 ||
+        actionableComments.length > 0 ||
+        checks.length > 0 ||
+        changesRequestedReviews.length > 0 ||
+        hasConflicts;
+    const inProgressRunIds = needsPush ? buildInProgressRunIds(report, cancelledSet) : [];
     const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
     const resolveCommand = buildResolveCommand(threads, allCommentIds, changesRequestedReviews, checks, prNumber);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
@@ -73,7 +80,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,
@@ -84,6 +91,7 @@ export async function handleFixCode(ctx) {
             actionableComments,
             reviewSummaryIds,
             firstLookSummaries,
+            editedSummaries,
             surfacedApprovals,
             checks,
             changesRequestedReviews,
@@ -91,6 +99,7 @@ export async function handleFixCode(ctx) {
             instructions,
             firstLookThreads,
             firstLookComments,
+            inProgressRunIds,
         },
         cancelled,
     }, report, reviewSummaryIds);

package/bin/commands/iterate/helpers.mjs

@@ -2,6 +2,13 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { rest } from "../../github/http.mjs";
 const execFile = promisify(execFileCb);
+export function buildInProgressRunIds(report, cancelledSet) {
+    return [
+        ...new Set(report.checks.inProgress
+            .map((c) => c.runId)
+            .filter((id) => id !== null && !cancelledSet.has(id))),
+    ];
+}
 export function buildSummary(report) {
     return {
         passing: report.checks.passing.length,
@@ -84,6 +91,33 @@ export async function getCurrentHeadSha() {
         return null;
     }
 }
+export function buildWaitLog(base) {
+    const { summary, remainingSeconds } = base;
+    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
+    switch (base.mergeStatus) {
+        case "BLOCKED":
+            if (base.reviewDecision === "REVIEW_REQUIRED")
+                parts.push("awaiting human review");
+            else if (base.reviewDecision === "APPROVED")
+                parts.push("awaiting additional approvals");
+            else
+                parts.push("awaiting human review or branch protection");
+            break;
+        case "BEHIND":
+            parts.push("branch is behind base");
+            break;
+        case "DRAFT":
+            parts.push("PR is a draft");
+            break;
+        case "UNSTABLE":
+            parts.push("some checks are unstable");
+            break;
+    }
+    if (remainingSeconds > 0) {
+        parts.push(`${remainingSeconds}s until auto-cancel`);
+    }
+    return parts.join(" — ");
+}
 export function buildCooldownResult(prNumber, readyDelaySeconds) {
     return {
         action: "cooldown",

package/bin/commands/iterate/index.mjs

@@ -4,10 +4,9 @@ import { getCurrentPrNumber } from "../../github/client.mjs";
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { getLastCommitTime, getCurrentHeadSha, buildSummary, buildRelevantChecks, buildCooldownResult, } from "./helpers.mjs";
+import { getLastCommitTime, getCurrentHeadSha, buildSummary, buildRelevantChecks, buildCooldownResult, buildWaitLog, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { buildWaitLog } from "./render.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
@@ -91,7 +90,11 @@ export async function runIterate(opts) {
     }
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const { minimizeIds: reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = classifyReviewSummaries({ firstLook: report.firstLookSummaries, seen: report.reviewSummaries }, report.approvedReviews, config.iterate.minimizeApprovals);
+    const { minimizeIds: reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = classifyReviewSummaries({
+        firstLook: report.firstLookSummaries,
+        seen: report.reviewSummaries,
+        edited: report.editedSummaries,
+    }, report.approvedReviews, config.iterate.minimizeApprovals);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.comments.actionable.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
@@ -111,6 +114,7 @@ export async function runIterate(opts) {
             repoName,
             reviewSummaryIds,
             firstLookSummaries,
+            editedSummaries,
             surfacedApprovals,
         });
     }

package/bin/commands/iterate/render.mjs

@@ -1,18 +1,7 @@
 /**
- * Render a resolve command as a shell snippet for the narrow placeholder-based
- * invocation used by iterate.
- *
- * This is not a general-purpose shell escaper. It only wraps
- * `$DISMISS_MESSAGE` and whitespace-bearing `rc.argv` entries in double quotes
- * so the surrounding command template can later substitute placeholder values.
- *
- * Callers must preserve that contract:
- * - placeholder substitution must replace the entire quoted token (for example,
- *   replace `"$DISMISS_MESSAGE"` as a whole, not text inside the quotes);
- * - `rc.argv` must not contain `"`, `$`, `` ` ``, or `\`, because this helper
- *   does not escape them and will throw if they are present;
- * - `$HEAD_SHA` must not appear in `rc.argv`; when `requiresHeadSha` is set it
- *   is appended separately below as the already-quoted token `"$HEAD_SHA"`.
+ * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE` and whitespace-bearing
+ * argv entries in double quotes for placeholder substitution. Throws if argv contains `"`, `$`,
+ * `` ` ``, or `\`. `$HEAD_SHA` is appended separately when `requiresHeadSha` is set.
  */
 export function renderResolveCommand(rc) {
     const needsQuoting = (arg) => {
@@ -29,11 +18,14 @@ export function renderResolveCommand(rc) {
     }
     return parts.join(" ");
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = []) {
     const instructions = [];
+    if (inProgressRunIds.length > 0) {
+        instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\`. Do this before applying any code fixes — the push at the end of this iteration will supersede those runs anyway, so letting them continue burns CI minutes for results no one will read. If \`gh\` reports a run is already completed, ignore it and continue with the next ID.`);
+    }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
-        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` the CLI already resolved the thread — remove its ID from \`--resolve-thread-ids\` in the \`resolve:\` command below. On \`applied: false\` read \`reason\` and \`patch\`, fall through to the manual-edit step, and do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) to preview the patch without mutating the working tree.`);
+        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` 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). If the patch fails to apply, fall through to the manual-edit step. Do not retry the same command.`);
     }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions
@@ -41,11 +33,17 @@ export function buildFixInstructions(threads, actionableComments, checks, review
             : "";
         instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.${suggestionFallback}`);
     }
-    const checksWithRunId = checks.filter((c) => c.runId);
+    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
+    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED");
     const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
     const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
-    if (checksWithRunId.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID, examine the log tail in the fenced block to decide what to do:\n   - If the log tail shows a transient runner or infrastructure failure (network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\` and stop this iteration — CI will re-run automatically.\n   - If the log tail shows a real test or build failure, apply a code fix.\n   - If the fenced log block is absent, run \`gh run view <runId> --log-failed\` first to fetch it, then choose between rerun and fix above.`);
+    if (failedRunIdChecks.length > 0) {
+        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`);
+        instructions.push(`If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`);
+        instructions.push(`If the log shows a real test/build failure: apply a code fix.`);
+    }
+    if (cancelledRunIdChecks.length > 0) {
+        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
     }
     if (externalChecks.length > 0) {
         instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
@@ -80,6 +78,12 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (firstLookSummaries.length > 0) {
         instructions.push(`Review the bodies shown under \`## Review summaries (first look — to be minimized)\` — you are seeing these for the first time. Their IDs are already included in the \`resolve:\` command's \`--minimize-comment-ids\`; if any warrants a \`## Shepherd Journal\` entry, record it before running resolve.`);
     }
+    const editedTotal = editedSummaries.length +
+        firstLookThreads.filter((t) => t.edited).length +
+        firstLookComments.filter((c) => c.edited).length;
+    if (editedTotal > 0) {
+        instructions.push(`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. Do **not** include their IDs in \`--minimize-comment-ids\`, \`--resolve-thread-ids\`, or \`--dismiss-review-ids\` — they are already closed or minimized on GitHub.`);
+    }
     if (resolveCommand.hasMutations) {
         const substituteParts = [];
         if (resolveCommand.requiresHeadSha) {
@@ -108,30 +112,3 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     }
     return instructions;
 }
-export function buildWaitLog(base) {
-    const { summary, remainingSeconds } = base;
-    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
-    switch (base.mergeStatus) {
-        case "BLOCKED":
-            if (base.reviewDecision === "REVIEW_REQUIRED")
-                parts.push("awaiting human review");
-            else if (base.reviewDecision === "APPROVED")
-                parts.push("awaiting additional approvals");
-            else
-                parts.push("awaiting human review or branch protection");
-            break;
-        case "BEHIND":
-            parts.push("branch is behind base");
-            break;
-        case "DRAFT":
-            parts.push("PR is a draft");
-            break;
-        case "UNSTABLE":
-            parts.push("some checks are unstable");
-            break;
-    }
-    if (remainingSeconds > 0) {
-        parts.push(`${remainingSeconds}s until auto-cancel`);
-    }
-    return parts.join(" — ");
-}

package/bin/commands/resolve-instructions.mjs

@@ -23,8 +23,13 @@ export function buildFetchInstructions(prNumber, result) {
     if (firstLookTotal > 0) {
         instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
     }
+    const editedTotal = firstLookThreads.filter((t) => t.edited).length +
+        firstLookComments.filter((c) => c.edited).length;
+    if (editedTotal > 0) {
+        instructions.push(`First-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body. Do **not** include their IDs in \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\` — they are already closed or minimized on GitHub.`);
+    }
     if (hasSuggestions) {
-        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` mark it Fixed — the CLI already resolved the thread, so exclude the ID from \`--resolve-thread-ids\`. On \`applied: false\` read \`reason\` and \`patch\`, then fall through to the manual fix step — do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) if you want to inspect the unified diff before it mutates the working tree — the CLI validates with \`git apply --check\`, returns the patch and \`valid: true/false\`, and exits \`1\` on drift without committing or resolving the thread.`);
+        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` 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). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
     }
     if (hasCodeItems) {
         instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);

package/bin/commands/resolve.mjs

@@ -5,32 +5,59 @@ import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mj
 import { loadConfig } from "../config/load.mjs";
 import { extractSuggestion } from "../suggestions/extract.mjs";
 import { buildFetchInstructions } from "./resolve-instructions.mjs";
-import { loadSeenSet, markSeen } from "../state/seen-comments.mjs";
-/**
- * Fetch mode: auto-resolve outdated threads and return all active items for LLM triage.
- */
+import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
+/** Fetch mode: auto-resolve outdated threads and return all active items for LLM triage. */
 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.");
     }
-    // Always bypass cache for resolve — we need fresh data before mutating.
     const { data } = await fetchPrBatch(prNumber, repo);
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = data.comments.filter((c) => !c.isMinimized);
-    // First-look: collect items that would normally be hidden and check seen markers.
     const outdatedCandidates = data.reviewThreads.filter((t) => t.isOutdated);
     const resolvedCandidates = data.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
     const minimizedThreadCandidates = data.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
     const minimizedCommentCandidates = data.comments.filter((c) => c.isMinimized);
-    const seenSet = await loadSeenSet(stateKey);
-    const unseenOutdated = outdatedCandidates.filter((t) => !seenSet.has(t.id));
-    const unseenResolved = resolvedCandidates.filter((t) => !seenSet.has(t.id));
-    const unseenMinimizedThreads = minimizedThreadCandidates.filter((t) => !seenSet.has(t.id));
-    const unseenMinimizedComments = minimizedCommentCandidates.filter((c) => !seenSet.has(c.id));
-    // Auto-resolve outdated (same as before — fires regardless of first-look status).
+    const seenMap = await loadSeenMap(stateKey);
+    const unseenOutdated = [];
+    const editedOutdated = [];
+    for (const t of outdatedCandidates) {
+        const cls = classifyItem(t.id, t.body, seenMap);
+        if (cls === "new")
+            unseenOutdated.push(t);
+        else if (cls === "edited")
+            editedOutdated.push(t);
+    }
+    const unseenResolved = [];
+    const editedResolved = [];
+    for (const t of resolvedCandidates) {
+        const cls = classifyItem(t.id, t.body, seenMap);
+        if (cls === "new")
+            unseenResolved.push(t);
+        else if (cls === "edited")
+            editedResolved.push(t);
+    }
+    const unseenMinimizedThreads = [];
+    const editedMinimizedThreads = [];
+    for (const t of minimizedThreadCandidates) {
+        const cls = classifyItem(t.id, t.body, seenMap);
+        if (cls === "new")
+            unseenMinimizedThreads.push(t);
+        else if (cls === "edited")
+            editedMinimizedThreads.push(t);
+    }
+    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 outdated = getOutdatedThreads(unresolvedThreads);
     const autoResolvedIds = new Set();
     if (outdated.length > 0) {
@@ -56,17 +83,37 @@ export async function runResolveFetch(opts) {
             firstLookStatus: "outdated",
             autoResolved: autoResolvedIds.has(t.id),
         })),
+        ...editedOutdated.map((t) => ({
+            ...t,
+            firstLookStatus: "outdated",
+            autoResolved: autoResolvedIds.has(t.id),
+            edited: true,
+        })),
         ...unseenResolved.map((t) => ({ ...t, firstLookStatus: "resolved" })),
+        ...editedResolved.map((t) => ({
+            ...t,
+            firstLookStatus: "resolved",
+            edited: true,
+        })),
         ...unseenMinimizedThreads.map((t) => ({ ...t, firstLookStatus: "minimized" })),
+        ...editedMinimizedThreads.map((t) => ({
+            ...t,
+            firstLookStatus: "minimized",
+            edited: true,
+        })),
+    ];
+    const firstLookComments = [
+        ...unseenMinimizedComments.map((c) => ({ ...c, firstLookStatus: "minimized" })),
+        ...editedMinimizedComments.map((c) => ({
+            ...c,
+            firstLookStatus: "minimized",
+            edited: true,
+        })),
     ];
-    const firstLookComments = unseenMinimizedComments.map((c) => ({
-        ...c,
-        firstLookStatus: "minimized",
-    }));
-    // Mark first-look items as seen (best-effort — markSeen never throws).
+    // Mark new and edited items as seen (best-effort — markSeen never throws).
     await Promise.allSettled([
-        ...firstLookThreads.map((t) => markSeen(stateKey, t.id)),
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id)),
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
+        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
     ]);
     const result = {
         prNumber,
@@ -80,9 +127,7 @@ export async function runResolveFetch(opts) {
     };
     return { ...result, instructions: buildFetchInstructions(prNumber, result) };
 }
-/**
- * Mutation mode: resolve/minimize/dismiss by ID.
- */
+/** Mutation mode: resolve/minimize/dismiss by ID. */
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());

package/bin/config.json

@@ -17,9 +17,7 @@
     "fetchReviewSummaries": true
   },
   "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"],
-    "logTailLines": 5,
-    "logTailChars": 200
+    "ciTriggerEvents": ["pull_request", "pull_request_target"]
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]

package/bin/reporters/agent.mjs

@@ -3,7 +3,8 @@
  *
  * These strip fields that are always-false by the time items reach iterate
  * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
- * monitor prompt never reads (event, status, conclusion, category).
+ * monitor prompt never reads (event, status, category).
+ * conclusion is preserved on AgentCheck so the formatter can branch on CANCELLED.
  * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
  * The original domain types are preserved for check command output.
  */
@@ -27,15 +28,18 @@ export function toAgentComment(c) {
     return { id: c.id, author: c.author, body: c.body, url: c.url };
 }
 export function toAgentCheck(c) {
+    if (c.conclusion === "SKIPPED" || c.conclusion === "NEUTRAL") {
+        throw new Error(`Unexpected conclusion ${c.conclusion} in toAgentCheck`);
+    }
     return {
         name: c.name,
         runId: c.runId,
         detailsUrl: c.detailsUrl,
+        conclusion: c.conclusion,
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.jobName !== undefined && { jobName: c.jobName }),
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
-        ...(c.logTail !== undefined && { logTail: c.logTail }),
     };
 }
 /**

package/bin/reporters/check-instructions.mjs

@@ -28,8 +28,8 @@ export function buildCheckInstructions(report) {
     for (const c of checks.failing) {
         const stepHint = c.failedStep ? ` (failed step: \`${c.failedStep}\`)` : "";
         const diagnosisHint = c.runId
-            ? c.logTail !== undefined
-                ? `examine the log tail${stepHint} — if transient, run \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
+            ? c.conclusion === "CANCELLED"
+                ? `cancelled — if unintended, rerun with \`gh run rerun ${c.runId}\``
                 : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
             : c.detailsUrl
                 ? `open the check details (${c.detailsUrl}) to diagnose the failure`

package/bin/reporters/text.mjs

@@ -112,7 +112,8 @@ export function formatText(report) {
             lines.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of firstLookComments) {
-            lines.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
+            const editedSuffix = c.edited ? ", edited" : "";
+            lines.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
         }
         firstLookSection = lines.join("\n");
     }

package/bin/state/seen-comments.mjs

@@ -1,10 +1,32 @@
-import { readFile, writeFile, mkdir, access, readdir } from "node:fs/promises";
+import { readFile, writeFile, rename, unlink, mkdir, access, readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
 import { resolveStateBase } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/** Compute a 16-hex-char SHA-256 prefix of a comment body. */
+export function hashBody(body) {
+    return createHash("sha256").update(body, "utf8").digest("hex").slice(0, 16);
+}
+/**
+ * Classify a candidate item against the seen map.
+ *
+ * - "new"       — no marker exists; surface the body and write the marker.
+ * - "edited"    — marker exists but stored hash differs from the current body;
+ *                 surface the updated body and update the marker hash.
+ * - "unchanged" — marker exists and hash matches (or marker has no hash, which
+ *                 is treated conservatively as unchanged).
+ */
+export function classifyItem(id, body, map) {
+    const m = map.get(id);
+    if (!m)
+        return "new";
+    if (typeof m.bodyHash === "string" && m.bodyHash !== hashBody(body))
+        return "edited";
+    return "unchanged";
+}
 /**
  * Read the seen/ directory once and return a Set of already-seen IDs.
  * Prefer this over repeated hasSeen() calls to avoid EMFILE on large PRs.
@@ -20,6 +42,32 @@ export async function loadSeenSet(key) {
         return new Set();
     }
 }
+/**
+ * Read the seen/ directory and return a Map from ID to SeenMarker.
+ * Used when the caller needs the stored bodyHash to detect in-place edits.
+ * Returns an empty Map if the directory does not yet exist.
+ */
+export async function loadSeenMap(key) {
+    const map = new Map();
+    try {
+        const dir = resolveDir(key);
+        const entries = await readdir(dir);
+        const ids = entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5));
+        for (const id of ids) {
+            try {
+                const raw = await readFile(join(dir, `${id}.json`), "utf8");
+                map.set(id, JSON.parse(raw));
+            }
+            catch {
+                // unreadable or malformed — skip
+            }
+        }
+    }
+    catch {
+        // directory doesn't exist or unreadable — return empty map
+    }
+    return map;
+}
 /** Return true if a "seen" marker exists for this id. */
 export async function hasSeen(key, id) {
     try {
@@ -30,17 +78,50 @@ export async function hasSeen(key, id) {
         return false;
     }
 }
-/** Write a "seen" marker for this id. Idempotent — preserves original seenAt on double-write. */
-export async function markSeen(key, id) {
+/**
+ * Write (or update) a "seen" marker for this id, storing the body hash so
+ * in-place edits can be detected on future fetches.
+ *
+ * - First call (no existing marker): creates `{ seenAt: now, bodyHash }`.
+ * - Subsequent call, hash unchanged: no-op (skips the write).
+ * - Subsequent call, hash changed: updates `bodyHash`, preserves original `seenAt`.
+ *
+ * All errors are silently swallowed — the marker is best-effort.
+ */
+export async function markSeen(key, id, body) {
+    let tmp;
     try {
         const path = resolvePath(key, id);
         await mkdir(dirname(path), { recursive: true });
-        // O_EXCL: create-only — EEXIST means already marked, which is the idempotent success case.
-        // seenAt is unix milliseconds (Date.now()), matching JS convention for this module.
-        await writeFile(path, JSON.stringify({ seenAt: Date.now() }), { flag: "wx", encoding: "utf8" });
+        const newHash = hashBody(body);
+        let existing = null;
+        try {
+            const raw = await readFile(path, "utf8");
+            existing = JSON.parse(raw);
+        }
+        catch {
+            // no existing marker — will create below
+        }
+        if (existing !== null && existing.bodyHash === newHash)
+            return;
+        const seenAt = existing?.seenAt ?? Date.now();
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await writeFile(tmp, JSON.stringify({ seenAt, bodyHash: newHash }), "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
     }
     catch {
-        // EEXIST = already seen. All other errors are best-effort.
+        // best-effort
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
     }
 }
 /** Read the full marker for inspection (returns null on miss or error). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",