pr-shepherd 0.15.2 → 0.16.0

package/bin/cli/list-formatters.mjs

@@ -1,5 +1,8 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
 const BODY_PREVIEW_MAX = 100;
+export function renderAuthor(author, authorType) {
+    return authorType ? `@${author} · ${authorType}` : `@${author}`;
+}
 export function renderBodyPreview(body) {
     const normalizedBody = body.replace(/\r\n?/g, "\n");
     const firstLine = normalizedBody.split("\n")[0]?.trim() ?? "";
@@ -24,7 +27,7 @@ export function renderThreadBullet(t, opts = {}) {
         : "`(no location)`";
     const suggestionMarker = t.suggestion ? " [suggestion]" : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (@${t.author})${suggestionMarker}${statusSuffix}: ${renderBodyPreview(t.body)}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${statusSuffix}: ${renderBodyPreview(t.body)}`;
     if (t.suggestion && opts.renderSuggestion) {
         return `${bulletLine}\n${renderSuggestionBlock(t.suggestion)}`;
     }
@@ -33,11 +36,11 @@ export function renderThreadBullet(t, opts = {}) {
 export function renderCommentBullet(c, opts = {}) {
     const link = c.url ? ` [↗](${c.url})` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    return `- \`commentId=${c.id}\`${link} (@${c.author})${statusSuffix}: ${renderBodyPreview(c.body)}`;
+    return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
 }
 export function renderReviewBullet(r, opts = {}) {
     const bodySuffix = opts.includeBody && r.body != null && r.body !== "" ? `: ${renderBodyPreview(r.body)}` : "";
-    return `- \`reviewId=${r.id}\` (@${r.author})${bodySuffix}`;
+    return `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})${bodySuffix}`;
 }
 export function renderReviewListSection(heading, items) {
     if (items.length === 0)

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

@@ -7,7 +7,7 @@ export function makeIterateResult(action = "wait") {
         mergeStateStatus: "BLOCKED",
         mergeStatus: "BLOCKED",
         reviewDecision: null,
-        copilotReviewInProgress: false,
+        blockingBotReviewInProgress: false,
         isDraft: false,
         shouldCancel: false,
         remainingSeconds: 60,
@@ -15,8 +15,6 @@ export function makeIterateResult(action = "wait") {
         baseBranch: "main",
         checks: [],
     };
-    if (action === "cooldown")
-        return { ...base, action: "cooldown", log: "SKIP: CI still starting" };
     if (action === "wait")
         return { ...base, action: "wait", log: "WAIT: 0 passing, 1 in-progress" };
     if (action === "mark_ready")
@@ -26,7 +24,6 @@ export function makeIterateResult(action = "wait") {
             ...base,
             action: "fix_code",
             fix: {
-                mode: "rebase-and-push",
                 threads: [],
                 resolutionOnlyThreads: [],
                 actionableComments: [],
@@ -42,7 +39,7 @@ export function makeIterateResult(action = "wait") {
                     requiresDismissMessage: false,
                     hasMutations: false,
                 },
-                instructions: ["End this iteration."],
+                instructions: ["Stop this iteration before the next tick."],
                 firstLookThreads: [],
                 firstLookComments: [],
                 inProgressRunIds: [],
@@ -55,7 +52,7 @@ export function makeIterateResult(action = "wait") {
             ...base,
             action: "cancel",
             reason: "ready-delay-elapsed",
-            log: "CANCEL: PR #42 — stopping monitor",
+            log: "CANCEL: PR #42 — stopping",
         };
     if (action === "escalate") {
         return {
@@ -67,7 +64,7 @@ export function makeIterateResult(action = "wait") {
                 ambiguousComments: [],
                 changesRequestedReviews: [],
                 suggestion: "check manually",
-                humanMessage: "⚠️ /pr-shepherd:monitor paused — needs human direction",
+                humanMessage: "⚠️ /pr-shepherd:pr-shepherd paused — needs human direction",
             },
         };
     }

package/bin/cli-parser.mjs

@@ -3,35 +3,26 @@
  *
  * Usage:
  *   pr-shepherd --version
- *   pr-shepherd [PR] [--format text|json] [--cooldown-seconds N] [--ready-delay Nm]
+ *   pr-shepherd [PR] [--format text|json] [--ready-delay Nm]
  *                  [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                  [--no-auto-cancel-actionable]
- *   pr-shepherd check [PR] [--format text|json]
  *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
  *                            [--dismiss-review-ids Q] [--message MSG] [--require-sha SHA]
  *   pr-shepherd commit-suggestion [PR] --thread-id ID [--message MSG] [--description DESC]
  *                                      [--dry-run] [--format text|json]
  *   (--message is required unless --dry-run is set)
- *   pr-shepherd iterate [PR] [--format text|json] [--cooldown-seconds N] [--ready-delay Nm]
+ *   pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]
  *                              [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                              [--no-auto-cancel-actionable]
- *   pr-shepherd monitor [PR] [--format text|json]
- *   pr-shepherd status PR1 [PR2 …]
  */
 import { readFileSync } from "node:fs";
-import { runCheck } from "./commands/check.mjs";
 import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
-import { formatJson } from "./reporters/json.mjs";
-import { formatText } from "./reporters/text.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultIterateInvocation, validateDefaultIterateArgs } from "./cli/default-iterate.mjs";
-import { statusToExitCode } from "./cli/exit-codes.mjs";
 import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
-import { handleCommitSuggestion, handleIterate, handleMonitor, handleStatus, } from "./cli/handlers.mjs";
+import { handleCommitSuggestion, handleIterate } from "./cli/handlers.mjs";
 import { setupLog } from "./log/setup.mjs";
-import { detectAgentRuntime } from "./agent-runtime.mjs";
-import { loadConfig } from "./config/load.mjs";
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
@@ -56,9 +47,6 @@ export async function main(argv) {
         return;
     }
     switch (subcommand) {
-        case "check":
-            await handleCheck(args.slice(1));
-            break;
         case "resolve":
             await handleResolve(args.slice(1));
             break;
@@ -68,15 +56,9 @@ export async function main(argv) {
         case "iterate":
             await handleIterate(args.slice(1));
             break;
-        case "monitor":
-            await handleMonitor(args.slice(1));
-            break;
-        case "status":
-            await handleStatus(args.slice(1));
-            break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
-            process.stderr.write("Usage: pr-shepherd <check|resolve|commit-suggestion|iterate|monitor|status|log-file> [options]\n" +
+            process.stderr.write("Usage: pr-shepherd <resolve|commit-suggestion|iterate|log-file> [options]\n" +
                 "       pr-shepherd --version | -v\n");
             process.exitCode = 1;
             return;
@@ -90,17 +72,6 @@ function readVersion() {
 // ---------------------------------------------------------------------------
 // Subcommand handlers
 // ---------------------------------------------------------------------------
-async function handleCheck(args) {
-    const { prNumber, global: globalOpts } = parseCommonArgs(args);
-    const runtime = detectAgentRuntime();
-    const cfg = loadConfig();
-    const report = await runCheck({ ...globalOpts, prNumber, autoResolve: false });
-    const output = globalOpts.format === "json"
-        ? formatJson(report, { runtime, runner: cfg.cli?.runner })
-        : formatText(report, { runtime, runner: cfg.cli?.runner });
-    process.stdout.write(`${output}\n`);
-    process.exitCode = statusToExitCode(report.status);
-}
 async function handleLogFile(args) {
     const jsonOut = args.some((a) => a === "--format=json") ||
         (() => {

package/bin/commands/check-status.mjs

@@ -13,14 +13,14 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
     // is BLOCKED (review pending, insufficient approvals, branch-protection rule, etc.).
     // Requires hasChecks so that a PR with zero relevant checks (CI never started, or all
     // filtered/skipped) doesn't prematurely trigger READY before any check has reported.
-    // copilotReviewInProgress is still excluded — a bot review is shepherd's problem, not a hand-off.
+    // blockingBotReviewInProgress is still excluded — a bot review is shepherd's problem, not a hand-off.
     if (verdict.allPassed &&
         verdict.hasChecks &&
         unresolvedThreads === 0 &&
         unresolvedComments === 0 &&
         changesRequestedReviews === 0 &&
         mergeStatus.status === "BLOCKED" &&
-        !mergeStatus.copilotReviewInProgress) {
+        !mergeStatus.blockingBotReviewInProgress) {
         return "READY";
     }
     if (mergeStatus.status === "BLOCKED" ||

package/bin/commands/check.mjs

@@ -7,6 +7,7 @@ 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";
 import { computeStatus } from "./check-status.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
 export async function runCheck(opts) {
@@ -41,7 +42,6 @@ export async function runCheck(opts) {
     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);
-    const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
     const outdated = getOutdatedThreads(unresolvedThreads);
     let autoResolved = [];
     let autoResolveErrors = [];
@@ -56,6 +56,7 @@ export async function runCheck(opts) {
     const minimizedThreadCandidates = batchData.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized);
     const seenMap = await loadSeenMap(stateKey);
+    const visibleCommentClassification = classifyVisibleComments(batchData.comments, seenMap, config.iterate.minimizeComments);
     const autoResolvedIds = new Set(autoResolved.map((t) => t.id));
     const firstLookThreads = [
         ...outdatedCandidates.flatMap((t) => {
@@ -106,17 +107,16 @@ export async function runCheck(opts) {
     await Promise.allSettled([
         ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
         ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+        ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
         ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
-    const actionableThreads = activeThreads;
     const resolutionOnlyThreads = unresolvedThreads.filter((t) => !autoResolvedIds.has(t.id) && (t.isOutdated || t.isMinimized));
-    const actionableComments = visibleComments;
     const mergeStatus = deriveMergeStatus(batchData);
     const blockedByFilteredCheck = mergeStatus.status === "BLOCKED" &&
         !verdict.anyFailing &&
         !verdict.anyInProgress &&
         verdict.filteredNames.length > 0;
-    const status = computeStatus(verdict, actionableThreads.length + resolutionOnlyThreads.length, actionableComments.length, mergeStatus, batchData.changesRequestedReviews.length);
+    const status = computeStatus(verdict, activeThreads.length + resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, batchData.changesRequestedReviews.length);
     return {
         pr: prNumber,
         nodeId: batchData.nodeId,
@@ -134,14 +134,15 @@ export async function runCheck(opts) {
             blockedByFilteredCheck,
         },
         threads: {
-            actionable: actionableThreads,
+            actionable: activeThreads,
             resolutionOnly: resolutionOnlyThreads,
             autoResolved,
             autoResolveErrors,
             firstLook: firstLookThreads,
         },
         comments: {
-            actionable: actionableComments,
+            actionable: visibleCommentClassification.actionable,
+            minimizeIds: visibleCommentClassification.minimizeIds,
             firstLook: firstLookComments,
         },
         changesRequestedReviews: batchData.changesRequestedReviews,

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

@@ -0,0 +1,23 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
+/**
+ * Build the `commit-suggestion` instruction step for agent consumers.
+ * Shared between `fix_code` (iterate) and `resolve --fetch` paths.
+ * @param sectionName - The markdown section heading where suggestion threads appear
+ *   (e.g. `"## Review threads"` for iterate, `"## Actionable Review Threads"` for resolve).
+ * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
+ */
+export function buildCommitSuggestionInstruction(prNumber, sectionName, includeDriftHint, runner) {
+    const command = buildPrShepherdCommand([
+        "commit-suggestion",
+        String(prNumber),
+        "--thread-id",
+        "<id>",
+        "--message",
+        "<one-sentence headline>",
+        "--format=json",
+    ], { runner }).text;
+    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.`;
+}

package/bin/commands/iterate/check-instructions.mjs

@@ -6,7 +6,7 @@ export function buildFailingCheckInstructions(checks) {
     const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
     const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
     if (failedRunIdChecks.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` or \`[conclusion: STARTUP_FAILURE]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`, `If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`, `If the log shows a real test/build failure: apply a code fix.`);
+        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` or \`[conclusion: STARTUP_FAILURE]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log. If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\`. 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.`);

package/bin/commands/iterate/classify.mjs

@@ -1,12 +1,17 @@
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
-export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
+import { shouldMinimizeAuthor } from "../../comments/minimize-policy.mjs";
+export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all") {
     // 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);
+    const minimizeIds = [...summaries.firstLook, ...summaries.seen]
+        .filter((r) => shouldMinimizeAuthor(r.authorType, minimizeComments))
+        .map((r) => r.id);
     if (minimizeApprovals) {
-        for (const r of approvals)
-            minimizeIds.push(r.id);
+        for (const r of approvals) {
+            if (shouldMinimizeAuthor(r.authorType, minimizeComments))
+                minimizeIds.push(r.id);
+        }
         return {
             minimizeIds,
             firstLookSummaries: summaries.firstLook,

package/bin/commands/iterate/escalate.mjs

@@ -55,7 +55,7 @@ export function validateBaseBranch(raw) {
 }
 export function buildEscalateHumanMessage(escalate, pr) {
     const lines = [];
-    lines.push("⚠️ /pr-shepherd:monitor paused — needs human direction");
+    lines.push("⚠️ /pr-shepherd:pr-shepherd paused — needs human direction");
     lines.push("");
     lines.push(`**Triggers:** ${escalate.triggers.map((t) => `\`${t}\``).join(", ")}`);
     lines.push("");
@@ -80,18 +80,17 @@ export function buildEscalateHumanMessage(escalate, pr) {
             lines.push(`- comment \`${c.id}\` (@${c.author}): ${firstLine}`);
         }
     }
-    if (escalate.attemptHistory && escalate.attemptHistory.length > 0) {
+    if (escalate.thrashHistory && escalate.thrashHistory.length > 0) {
         lines.push("");
         lines.push("## Fix attempts");
-        for (const a of escalate.attemptHistory) {
+        for (const a of escalate.thrashHistory) {
             lines.push(`- thread \`${a.threadId}\` attempted ${a.attempts} times`);
         }
     }
     lines.push("");
     lines.push("---");
     lines.push("");
-    lines.push(`Run \`/pr-shepherd:check ${pr}\` to see current state.`);
-    lines.push(`After fixing manually, rerun \`/pr-shepherd:monitor ${pr}\` to resume.`);
+    lines.push(`After fixing manually, rerun \`/pr-shepherd:pr-shepherd ${pr}\` to resume.`);
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
@@ -104,7 +103,7 @@ export function buildEscalateSuggestion(triggers, detail) {
         return `Could not determine the PR's base branch${reason} — refusing to emit a rebase that could force-push onto the wrong base. Run the rebase manually against the PR's real target branch.`;
     }
     if (triggers.includes("fix-thrash")) {
-        return "Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:monitor";
+        return "Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:pr-shepherd";
     }
     if (triggers.includes("pr-level-changes-requested")) {
         return "Reviewer requested changes but left no inline comments — read the review and act manually";

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

@@ -23,7 +23,7 @@ export async function handleFixCode(ctx) {
             unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
             ambiguousComments: report.comments.actionable.map(toAgentComment),
             changesRequestedReviews: report.changesRequestedReviews,
-            attemptHistory: escalateTriggers.thrashHistory,
+            thrashHistory: escalateTriggers.thrashHistory,
             suggestion: buildEscalateSuggestion(escalateTriggers.triggers),
         };
         return {
@@ -56,7 +56,8 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = hasGuaranteedSupersedingPush
         ? buildInProgressRunIds(report, cancelledSet)
         : [];
-    const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
+    const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
+    const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
     const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, cliRunner);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
         const fallbackEscalateBase = {
@@ -83,7 +84,6 @@ export async function handleFixCode(ctx) {
         baseBranch: baseLookup.branch,
         action: "fix_code",
         fix: {
-            mode: "rebase-and-push",
             threads,
             resolutionOnlyThreads,
             actionableComments,

package/bin/commands/iterate/helpers.mjs

@@ -58,15 +58,6 @@ export function buildRelevantChecks(report) {
     });
     return [...passing, ...failing];
 }
-export async function getLastCommitTime() {
-    try {
-        const { stdout } = await execFile("git", ["log", "-1", "--format=%ct", "HEAD"]);
-        return parseInt(stdout.trim(), 10);
-    }
-    catch {
-        return null;
-    }
-}
 // Best-effort: cancelling a completed run is a no-op, not an error.
 export async function tryCancelRun(runId, owner, repo) {
     try {
@@ -118,23 +109,3 @@ export function buildWaitLog(base) {
     }
     return parts.join(" — ");
 }
-export function buildCooldownResult(prNumber, readyDelaySeconds) {
-    return {
-        action: "cooldown",
-        pr: prNumber,
-        repo: "",
-        status: "UNKNOWN",
-        state: "UNKNOWN",
-        mergeStateStatus: "UNKNOWN",
-        mergeStatus: "UNKNOWN",
-        reviewDecision: null,
-        copilotReviewInProgress: false,
-        isDraft: false,
-        shouldCancel: false,
-        remainingSeconds: readyDelaySeconds,
-        summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 0 },
-        baseBranch: "",
-        checks: [],
-        log: "SKIP: CI still starting — waiting for first check to appear",
-    };
-}

package/bin/commands/iterate/index.mjs

@@ -4,13 +4,13 @@ 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, buildWaitLog, } from "./helpers.mjs";
+import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildWaitLog } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
+import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
-    const cooldownSeconds = opts.cooldownSeconds ?? config.iterate.cooldownSeconds;
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
     const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -18,17 +18,18 @@ export async function runIterate(opts) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
     const optsWithPr = { ...opts, prNumber };
-    const lastCommitTime = await getLastCommitTime();
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    if (lastCommitTime !== null && nowSeconds - lastCommitTime < cooldownSeconds) {
-        return buildCooldownResult(prNumber, readyDelaySeconds);
-    }
     const report = await runCheck({
         ...optsWithPr,
         autoResolve: config.actions.autoResolveOutdated,
     });
+    const [repoOwner, repoName] = report.repo.split("/");
+    if (!repoOwner || !repoName) {
+        throw new Error(`Unexpected repo format: "${report.repo}" (expected "owner/name")`);
+    }
+    const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
     if (report.mergeStatus.state !== "OPEN") {
         const state = report.mergeStatus.state.toLowerCase();
+        await clearStallState(stallKey);
         return {
             pr: report.pr,
             repo: report.repo,
@@ -36,7 +37,7 @@ export async function runIterate(opts) {
             mergeStateStatus: report.mergeStatus.mergeStateStatus,
             mergeStatus: report.mergeStatus.status,
             reviewDecision: report.mergeStatus.reviewDecision,
-            copilotReviewInProgress: report.mergeStatus.copilotReviewInProgress,
+            blockingBotReviewInProgress: report.mergeStatus.blockingBotReviewInProgress,
             isDraft: report.mergeStatus.isDraft,
             shouldCancel: true,
             remainingSeconds: 0,
@@ -46,13 +47,9 @@ export async function runIterate(opts) {
             checks: buildRelevantChecks(report),
             action: "cancel",
             reason: report.mergeStatus.state === "MERGED" ? "merged" : "closed",
-            log: `CANCEL: PR #${report.pr} is ${state} — stopping monitor`,
+            log: `CANCEL: PR #${report.pr} is ${state} — stopping`,
         };
     }
-    const [repoOwner, repoName] = report.repo.split("/");
-    if (!repoOwner || !repoName) {
-        throw new Error(`Unexpected repo format: "${report.repo}" (expected "owner/name")`);
-    }
     const isReady = report.status === "READY";
     const readyState = await updateReadyDelay(report.pr, isReady, readyDelaySeconds, repoOwner, repoName);
     const base = {
@@ -63,7 +60,7 @@ export async function runIterate(opts) {
         mergeStateStatus: report.mergeStatus.mergeStateStatus,
         mergeStatus: report.mergeStatus.status,
         reviewDecision: report.mergeStatus.reviewDecision,
-        copilotReviewInProgress: report.mergeStatus.copilotReviewInProgress,
+        blockingBotReviewInProgress: report.mergeStatus.blockingBotReviewInProgress,
         isDraft: report.mergeStatus.isDraft,
         shouldCancel: readyState.shouldCancel,
         remainingSeconds: readyState.remainingSeconds,
@@ -72,6 +69,7 @@ export async function runIterate(opts) {
         checks: buildRelevantChecks(report),
     };
     if (readyState.shouldCancel) {
+        await clearStallState(stallKey);
         let cancelNote;
         if (base.mergeStatus !== "BLOCKED")
             cancelNote = "has been ready for review";
@@ -85,23 +83,24 @@ export async function runIterate(opts) {
             ...base,
             action: "cancel",
             reason: "ready-delay-elapsed",
-            log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping monitor`,
+            log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
         };
     }
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
-    const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
     const { minimizeIds: reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = classifyReviewSummaries({
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
-    }, report.approvedReviews, config.iterate.minimizeApprovals);
+    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.threads.resolutionOnly.length > 0 ||
         report.comments.actionable.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
         report.checks.failing.length > 0 ||
         report.mergeStatus.status === "CONFLICTS" ||
-        reviewSummaryIds.length > 0;
+        reviewSummaryIds.length > 0 ||
+        firstLookSummaries.length > 0 ||
+        editedSummaries.length > 0;
     if (hasActionableWork) {
         return handleFixCode({
             base,
@@ -122,7 +121,7 @@ export async function runIterate(opts) {
     }
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
-        !report.mergeStatus.copilotReviewInProgress &&
+        !report.mergeStatus.blockingBotReviewInProgress &&
         !readyState.shouldCancel;
     if (canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady) {
         await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });

package/bin/commands/iterate/render.mjs

@@ -1,9 +1,9 @@
-import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
+import { renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
+import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 export const FIX_INSTRUCTION_STOP_AFTER_PUSH = "Stop this iteration — CI needs time to run on the new push before the next tick.";
 export const FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK = "Stop this iteration before the next tick.";
-export const FIX_INSTRUCTION_END_ITERATION = "End this iteration.";
 /**
  * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE`, `$HEAD_SHA`, and
  * whitespace-bearing argv entries for placeholder substitution. `$HEAD_SHA` is appended separately
@@ -19,20 +19,11 @@ export function renderResolveCommand(rc) {
 export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
     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.`);
+        instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\` before applying code fixes. 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) {
-        const commitSuggestionCommand = buildPrShepherdCommand([
-            "commit-suggestion",
-            String(prNumber),
-            "--thread-id",
-            "<id>",
-            "--message",
-            "<one-sentence headline>",
-            "--format=json",
-        ], { runner }).text;
-        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`${commitSuggestionCommand}\` 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.`);
+        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads", false, runner));
     }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions
@@ -97,11 +88,8 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (needsPush) {
         instructions.push(FIX_INSTRUCTION_STOP_AFTER_PUSH);
     }
-    else if (resolveCommand.hasMutations) {
-        instructions.push(FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK);
-    }
     else {
-        instructions.push(FIX_INSTRUCTION_END_ITERATION);
+        instructions.push(FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK);
     }
     return instructions;
 }

package/bin/commands/resolve-instructions.mjs

@@ -1,5 +1,6 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 import { SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS, buildShepherdJournalInstruction, } from "./shepherd-journal.mjs";
+import { buildCommitSuggestionInstruction } from "./commit-suggestion-instruction.mjs";
 /**
  * Build the numbered triage/fix/resolve instruction steps for the agent to follow.
  * Steps are conditionally emitted based on what the fetch returned (mirrors
@@ -32,16 +33,7 @@ export function buildFetchInstructions(prNumber, result, runner) {
         instructions.push(`First-look bullets 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 (hasSuggestions) {
-        const commitSuggestionCommand = buildPrShepherdCommand([
-            "commit-suggestion",
-            String(prNumber),
-            "--thread-id",
-            "<id>",
-            "--message",
-            "<one-sentence headline>",
-            "--format=json",
-        ], { runner }).text;
-        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`${commitSuggestionCommand}\` 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.`);
+        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Actionable Review Threads", true, runner));
     }
     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-mutate.mjs

@@ -0,0 +1,16 @@
+import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
+import { applyResolveOptions } from "../comments/resolve.mjs";
+export async function runResolveMutate(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.");
+    }
+    return applyResolveOptions(prNumber, repo, {
+        resolveThreadIds: opts.resolveThreadIds,
+        minimizeCommentIds: opts.minimizeCommentIds,
+        dismissReviewIds: opts.dismissReviewIds,
+        dismissMessage: opts.dismissMessage,
+        requireSha: opts.requireSha,
+    });
+}