pr-shepherd 0.26.2 → 0.27.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.26.2",
+  "version": "0.27.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -88,7 +88,7 @@ Direct CLI:
 
 ```sh
 pr-shepherd 42                         # poll until non-WAIT or timeout
-pr-shepherd 42 --interval 45s --timeout 4m
+pr-shepherd 42 --interval 60s --timeout 270s
 pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshots
 pr-shepherd 42 --ready-delay 15m
 pr-shepherd iterate 42                 # single tick

package/bin/cli/duration-flag.mjs

@@ -1,3 +1,4 @@
+import { parseSecondsDurationParts } from "./exit-codes.mjs";
 export function validateSecondsDurationFlag(command, flag, value, presentAsSeparateArg) {
     if (value === null) {
         if (presentAsSeparateArg) {
@@ -13,8 +14,8 @@ export function validateSecondsDurationFlag(command, flag, value, presentAsSepar
         process.exitCode = 1;
         return null;
     }
-    if (!/^[1-9]\d*(?:s|sec|seconds?|m|min|minutes?|h|hours?)?$/.test(trimmed)) {
-        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 30s, 5m, 1h, or bare seconds (e.g. 30).\n`);
+    if (!parseSecondsDurationParts(trimmed)) {
+        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 30s, 4.5m, 1h, or bare seconds (e.g. 30).\n`);
         process.exitCode = 1;
         return null;
     }

package/bin/cli/exit-codes.mjs

@@ -1,4 +1,17 @@
 import { loadConfig } from "../config/load.mjs";
+const SECOND_DURATION_UNITS = new Set([
+    "s",
+    "sec",
+    "second",
+    "seconds",
+    "m",
+    "min",
+    "minute",
+    "minutes",
+    "h",
+    "hour",
+    "hours",
+]);
 export function parseDurationToMinutes(s, defaultMinutes) {
     const m = /^(\d+)(m|min|minutes?|h|hours?)?$/.exec(s.trim());
     if (!m)
@@ -9,19 +22,32 @@ export function parseDurationToMinutes(s, defaultMinutes) {
         return n * 60;
     return n;
 }
+export function parseSecondsDurationParts(s) {
+    const trimmed = s.trim();
+    const match = /^(\d+(?:\.\d+)?)([a-z]+)?$/.exec(trimmed);
+    if (!match)
+        return null;
+    const amount = match[1];
+    const explicitUnit = match[2];
+    if (!amount || (amount.includes(".") && !explicitUnit))
+        return null;
+    const unit = explicitUnit ?? "s";
+    if (!SECOND_DURATION_UNITS.has(unit))
+        return null;
+    const value = Number(amount);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    return { value, unit };
+}
 export function parseDurationToSeconds(s, defaultSeconds) {
-    const m = /^(\d+)(s|sec|seconds?|m|min|minutes?|h|hours?)?$/.exec(s.trim());
-    if (!m)
-        return defaultSeconds;
-    const n = parseInt(m[1], 10);
-    if (!Number.isFinite(n))
+    const parsed = parseSecondsDurationParts(s);
+    if (!parsed)
         return defaultSeconds;
-    const unit = m[2] ?? "s";
-    if (unit.startsWith("h"))
-        return n * 3600;
-    if (unit.startsWith("m"))
-        return n * 60;
-    return n;
+    if (parsed.unit.startsWith("h"))
+        return parsed.value * 3600;
+    if (parsed.unit.startsWith("m"))
+        return parsed.value * 60;
+    return parsed.value;
 }
 export function statusToExitCode(status) {
     switch (status) {

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

@@ -109,8 +109,8 @@ Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
 
 Poll flags:
-  --interval <duration>          Sleep between WAIT ticks. Default: 30s.
-  --timeout <duration>           Maximum wall-clock wait. Default: 5m.
+  --interval <duration>          Sleep between WAIT ticks. Default: 60s.
+  --timeout <duration>           Maximum wall-clock wait. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
 
 Forwarded iterate flags:
@@ -122,7 +122,7 @@ Forwarded iterate flags:
   --verbose                      Include verbose iterate fields and detailed per-tick lines.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
 
-Durations accept seconds, minutes, or hours: 30s, 2m, 1h, or bare seconds.
+Durations accept seconds, minutes, or hours: 30s, 4.5m, 1h, or bare seconds.
 Each WAIT tick writes a single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
 
 Exit codes:

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

@@ -42,8 +42,8 @@ Iterate flags:
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
 
 Poll flags:
-  --interval <duration>          Sleep between WAIT ticks. Default: 30s.
-  --timeout <duration>           Maximum poll wall-clock wait. Default: 5m.
+  --interval <duration>          Delay between WAIT ticks. Default: 60s.
+  --timeout <duration>           Poll wall-clock cap. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
 
 Clean variants:
@@ -59,6 +59,6 @@ Exit codes for iterate and poll:
   2  CANCEL
   3  ESCALATE
 
-Durations accept seconds, minutes, or hours: 30s, 2m, 1h, or bare seconds.
+Duration examples: 30s, 4.5m, 1h, or bare seconds.
 
 Run 'pr-shepherd <command> --help' for command-specific details.`;

package/bin/cli/list-formatters.mjs

@@ -94,6 +94,9 @@ export function renderEditedCommentTag(c) {
     return c.edited ? "[edited since first look]" : undefined;
 }
 export function renderReviewBullet(r, opts = {}) {
+    if (r.staleBotCr) {
+        return `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)}) [pending dismissal — already surfaced; include in \`--dismiss-review-ids\`]`;
+    }
     const bodySuffix = opts.includeBody && r.body != null && r.body !== "" ? `: ${renderBodyPreview(r.body)}` : "";
     return `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})${bodySuffix}`;
 }

package/bin/cli/poll-handler.mjs

@@ -5,8 +5,8 @@ import { parseDurationToSeconds } from "./exit-codes.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
-const DEFAULT_POLL_INTERVAL_SECONDS = 30;
-const DEFAULT_POLL_TIMEOUT_SECONDS = 300;
+const DEFAULT_POLL_INTERVAL_SECONDS = 60;
+const DEFAULT_POLL_TIMEOUT_SECONDS = 270;
 export async function handlePoll(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();

package/bin/commands/check.mjs

@@ -13,7 +13,7 @@ import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMerge
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
-import { classifyReviewsForDisplay } from "../comments/review-visibility.mjs";
+import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { normalizeBotUsernames } from "../comments/authors.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
@@ -75,7 +75,7 @@ export async function runCheck(opts) {
         else
             seenSummaries.push(r);
     }
-    const changesRequestedReviewVisibility = classifyReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap);
+    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     await Promise.allSettled([
         ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),

package/bin/commands/iterate/classify.mjs

@@ -48,7 +48,7 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, _reviews, checks, prNumber, botUsernames = new Set(), ruleAutoResolveThreadIds = []) {
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber, botUsernames = new Set(), ruleAutoResolveThreadIds = []) {
     const allThreads = [...threads, ...resolutionOnlyThreads];
     const replyThreadIds = dedupeIds(allThreads
         .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
@@ -60,21 +60,36 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
             .map((t) => t.id),
         ...ruleAutoResolveThreadIds,
     ]);
+    // Bot/non-human CHANGES_REQUESTED reviews are auto-dismissed after the agent pushes a fix.
+    // Human reviews are left for the reviewer to re-review or dismiss themselves.
+    const dismissReviewIds = dedupeIds(reviews
+        .filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames))
+        .map((r) => r.id));
     const hasReply = replyThreadIds.length > 0;
+    const hasDismiss = dismissReviewIds.length > 0;
+    // Mutations that require --message: replies (to human threads) and dismissals (of bot CR reviews).
+    const hasMessageMutations = hasReply || hasDismiss;
     const hasResolveOrMinimize = resolveThreadIds.length > 0 || allCommentIds.length > 0;
-    if (hasReply && hasResolveOrMinimize) {
-        // Split: reply command needs SHA; resolve/minimize command does not.
+    if (hasMessageMutations && hasResolveOrMinimize) {
+        // Split: message-bearing mutations (replies + dismissals) ride in resolveArgv;
+        // resolve/minimize mutations go in resolveOnlyArgv so they can run without SHA or message.
         const resolveArgv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
-        resolveArgv.push("--reply-thread-ids", replyThreadIds.join(","));
+        if (replyThreadIds.length > 0) {
+            resolveArgv.push("--reply-thread-ids", replyThreadIds.join(","));
+        }
         resolveArgv.push("--message", "$DISMISS_MESSAGE");
-        // `requiresHeadSha` is only true when actionable thread fixes or failing
-        // checks are being addressed — mutations that can race with a moving HEAD.
-        const requiresHeadSha = threads.length > 0 || checks.length > 0;
+        if (hasDismiss) {
+            resolveArgv.push("--dismiss-review-ids", dismissReviewIds.join(","));
+        }
+        // SHA is required when actionable thread fixes or failing checks are being addressed,
+        // or when bot CR reviews are being dismissed (post-push SHA gate).
+        const requiresHeadSha = threads.length > 0 || checks.length > 0 || hasDismiss;
         const resolveCommand = {
             argv: resolveArgv,
             requiresHeadSha,
             requiresDismissMessage: true,
-            replyThreadIds,
+            ...(replyThreadIds.length > 0 ? { replyThreadIds } : undefined),
+            ...(hasDismiss ? { dismissReviewIds } : undefined),
             hasMutations: true,
         };
         const resolveOnlyArgv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
@@ -93,7 +108,7 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
         };
         return { resolveCommand, resolveOnlyCommand };
     }
-    // Single command: either reply-only or resolve/minimize-only (no split needed).
+    // Single command: all mutations combined (or only one category present).
     const argv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
     if (replyThreadIds.length > 0) {
         argv.push("--reply-thread-ids", replyThreadIds.join(","));
@@ -105,16 +120,23 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     if (allCommentIds.length > 0) {
         argv.push("--minimize-comment-ids", allCommentIds.join(","));
     }
-    const hasMutations = hasReply || hasResolveOrMinimize;
-    // SHA is only required when replying after actionable fixes or failing checks.
-    // Resolve/minimize-only mutations never need SHA.
-    const requiresHeadSha = hasReply && (threads.length > 0 || checks.length > 0);
+    if (hasDismiss) {
+        // Add --message when dismissing without a reply (replies already added it above).
+        if (!hasReply)
+            argv.push("--message", "$DISMISS_MESSAGE");
+        argv.push("--dismiss-review-ids", dismissReviewIds.join(","));
+    }
+    const hasMutations = hasMessageMutations || hasResolveOrMinimize;
+    // SHA is required when replying after actionable fixes/checks, or whenever dismissing
+    // (dismissal is a post-push operation that must race-check against a moving HEAD).
+    const requiresHeadSha = hasDismiss || (hasReply && (threads.length > 0 || checks.length > 0));
     const resolveCommand = {
         argv,
         requiresHeadSha,
-        requiresDismissMessage: replyThreadIds.length > 0,
+        requiresDismissMessage: hasMessageMutations,
         ...(replyThreadIds.length > 0 ? { replyThreadIds } : undefined),
         ...(resolveThreadIds.length > 0 ? { resolveThreadIds } : undefined),
+        ...(hasDismiss ? { dismissReviewIds } : undefined),
         hasMutations,
     };
     return { resolveCommand };

package/bin/commands/iterate/escalate.mjs

@@ -123,5 +123,9 @@ export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("thread-missing-location")) {
         return "Review thread has no file/line reference — automated location routing failed and manual handling is required.";
     }
+    if (triggers.includes("bot-cr-not-dismissed")) {
+        const ids = detail ? ` (review IDs: ${detail})` : "";
+        return `Bot CHANGES_REQUESTED review(s) remained undismissed past the stall window${ids}. The agent likely dropped \`--dismiss-review-ids\` from a prior resolve command. Dismiss the review(s) manually (or re-run resolve with the IDs) to unblock the PR.`;
+    }
     return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }

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

@@ -1,5 +1,6 @@
 /* eslint-disable max-lines */
 import { readFixAttempts, writeFixAttempts, } from "../../state/fix-attempts.mjs";
+import { readBotCrSeenState, writeBotCrSeenState, updateBotCrSeenState, } from "../../state/bot-cr-seen.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
 import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
@@ -9,6 +10,7 @@ import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
 import { annotationMarkerBody } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
+import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 function nextFixAttempts(stored, headSha, threads) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
@@ -29,6 +31,31 @@ export async function handleFixCode(ctx) {
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
+    const botCrReviews = report.changesRequestedReviews.filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames));
+    const botCrStateKey = { owner: repoOwner, repo: repoName, pr: prNumber };
+    const previousBotCrState = await readBotCrSeenState(botCrStateKey);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const { next: nextBotCrState, staleIds: staleBotCrIds } = updateBotCrSeenState(previousBotCrState, botCrReviews, nowSeconds, stallTimeoutSeconds);
+    await writeBotCrSeenState(botCrStateKey, nextBotCrState);
+    if (staleBotCrIds.length > 0) {
+        const staleSet = new Set(staleBotCrIds);
+        const staleReviews = botCrReviews.filter((r) => staleSet.has(r.id));
+        const escalateBase = {
+            triggers: ["bot-cr-not-dismissed"],
+            unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
+            ambiguousComments: report.comments.actionable.map(toAgentComment),
+            changesRequestedReviews: staleReviews,
+            suggestion: buildEscalateSuggestion(["bot-cr-not-dismissed"], staleBotCrIds.join(", ")),
+        };
+        return {
+            ...base,
+            action: "escalate",
+            escalate: {
+                ...escalateBase,
+                humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+            },
+        };
+    }
     const escalateTriggers = checkEscalateTriggers(report.threads.actionable, threadAttempts);
     if (escalateTriggers.triggers.length > 0) {
         const escalateBase = {

package/bin/commands/iterate/render.mjs

@@ -2,19 +2,12 @@ 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";
-// Module-private: the final "stop" step appended to every fix_code instruction list. No longer
-// re-exported now that the recheck/delay suffix that consumed it (in iterate-instructions) is gone.
 const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
-/**
- * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE`, `$HEAD_SHA`, and
- * whitespace-bearing argv entries for placeholder substitution. `$HEAD_SHA` is never in `argv` —
- * `renderResolveCommand` appends `--require-sha "$HEAD_SHA"` when `requiresHeadSha` is set.
- */
+/** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export function renderResolveCommand(rc) {
     const parts = [...rc.argv];
-    if (rc.requiresHeadSha) {
+    if (rc.requiresHeadSha)
         parts.push("--require-sha", "$HEAD_SHA");
-    }
     return renderShellCommand(parts);
 }
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, _baseBranch, // retained for call-site stability; rebase mechanics now defer to the caller
@@ -79,7 +72,12 @@ resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], f
         instructions.push(`For each item under \`## Check annotations\`: inspect the referenced file range and decide whether the annotation requires a code change. These annotations are surfaced once per PR and do not need any resolve/minimize mutation.`);
     }
     if (changesRequestedReviews.length > 0) {
-        instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
+        const staleClause = changesRequestedReviews.some((r) => r.staleBotCr)
+            ? " Bullets tagged `[pending dismissal — already surfaced]` are bot CR reviews you saw on a previous tick; the CLI hides re-surfaced bodies to keep output lean — re-read the prior tick if you need the body."
+            : "";
+        instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.${staleClause}`);
+        if ((resolveCommand.dismissReviewIds?.length ?? 0) > 0)
+            instructions.push(`Pass every ID listed in \`--dismiss-review-ids\` to the \`resolve:\` command verbatim — these are bot/non-human CR reviews that the agent (not the author) must dismiss. Dropping an ID leaves the PR in \`CHANGES_REQUESTED\` state; the next tick re-surfaces it as \`[pending dismissal]\` and an unattended bot CR escalates after \`iterate.stallTimeoutMinutes\`.`);
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push(`Run the \`resolve-only:\` command shown above — no substitutions needed.`);

package/bin/commands/poll.mjs

@@ -42,6 +42,20 @@ function writeQuietStatus(tick, elapsedSeconds, sleepSeconds, result) {
     process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT ${result.status}/${result.mergeStateStatus}/${result.reviewDecision ?? "NO_REVIEW_DECISION"}${active}${commitSeg}${reviewRoundSeg}${reviewSeg} — sleeping ${sleepSeconds}s\n`);
 }
 const MAX_TIMER_MS = 2 ** 31 - 1;
+const TIMER_DRIFT_TOLERANCE_MS = 500;
+function writeWaitProgress(opts) {
+    const elapsedSeconds = Math.round(opts.elapsedMs / 1000);
+    const sleepSeconds = Math.round(opts.sleepMs / 1000);
+    if (!opts.quietStatus) {
+        writeTickProgress(opts.tick, elapsedSeconds, sleepSeconds, opts.verbose);
+        return opts.lastWaitSignature;
+    }
+    const signature = waitSignature(opts.result);
+    if (signature !== opts.lastWaitSignature) {
+        writeQuietStatus(opts.tick, elapsedSeconds, sleepSeconds, opts.result);
+    }
+    return signature;
+}
 export async function runPoll(opts) {
     const { intervalSeconds, timeoutSeconds, ...iterateOpts } = opts;
     const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);
@@ -62,19 +76,20 @@ export async function runPoll(opts) {
         const remainingMs = timeoutMs - elapsedMs;
         if (remainingMs <= 0)
             break;
-        const nextSleepMs = Math.min(intervalMs, remainingMs);
-        if (quietStatus) {
-            const signature = waitSignature(lastResult);
-            if (signature !== lastWaitSignature) {
-                writeQuietStatus(tick, Math.round(elapsedMs / 1000), Math.round(nextSleepMs / 1000), lastResult);
-            }
-            lastWaitSignature = signature;
-        }
-        else {
-            writeTickProgress(tick, Math.round(elapsedMs / 1000), Math.round(nextSleepMs / 1000), verbose);
-            if (!verbose)
-                dotsPrinted = true;
-        }
+        if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
+            break;
+        const nextSleepMs = intervalMs;
+        lastWaitSignature = writeWaitProgress({
+            tick,
+            elapsedMs,
+            sleepMs: nextSleepMs,
+            result: lastResult,
+            quietStatus,
+            verbose,
+            lastWaitSignature,
+        });
+        if (!quietStatus && !verbose)
+            dotsPrinted = true;
         await sleep(nextSleepMs);
     }
     if (dotsPrinted)

package/bin/comments/review-visibility.mjs

@@ -1,4 +1,5 @@
 import { classifyItem } from "../state/seen-comments.mjs";
+import { isHumanAuthor, isConfiguredBotAuthor } from "./authors.mjs";
 export function classifyReviewsForDisplay(reviews, seenMap) {
     const visible = [];
     const toMarkSeen = [];
@@ -12,3 +13,49 @@ export function classifyReviewsForDisplay(reviews, seenMap) {
     }
     return { visible, toMarkSeen };
 }
+/**
+ * Bot CHANGES_REQUESTED reviews are different from every other surfaceable
+ * item: the agent — not the author — is responsible for dismissing them via
+ * `--dismiss-review-ids` after a fix push. If the agent forgets, the review
+ * stays in `CHANGES_REQUESTED` state and silently blocks the PR.
+ *
+ * The standard seen-gate (`classifyReviewsForDisplay`) suppresses items with
+ * unchanged bodies, which would also drop the bot CR ID from the
+ * `--dismiss-review-ids` flag — making the bug irrecoverable. This function
+ * keeps every bot CR in the visible set on every tick, using the seen-map
+ * only to pick the render form:
+ *
+ * - `new` / `edited` → full bullet (caller renders body normally).
+ * - `unchanged` → flagged `staleBotCr: true` so the formatter emits a terse
+ *   one-line reminder.
+ *
+ * Human-authored CR reviews continue to flow through the standard seen-gate.
+ */
+export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames) {
+    const visible = [];
+    const toMarkSeen = [];
+    for (const review of reviews) {
+        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
+        const cls = classifyItem(review.id, review.body, seenMap);
+        if (isBot) {
+            if (cls === "unchanged") {
+                visible.push({ ...review, staleBotCr: true });
+            }
+            else if (cls === "edited") {
+                visible.push({ ...review, edited: true });
+                toMarkSeen.push(review);
+            }
+            else {
+                visible.push(review);
+                toMarkSeen.push(review);
+            }
+            continue;
+        }
+        if (cls === "unchanged")
+            continue;
+        const rendered = cls === "edited" ? { ...review, edited: true } : review;
+        visible.push(rendered);
+        toMarkSeen.push(review);
+    }
+    return { visible, toMarkSeen };
+}

package/bin/state/bot-cr-seen.mjs

@@ -0,0 +1,110 @@
+/**
+ * Persistent first-seen state for bot CHANGES_REQUESTED reviews.
+ *
+ * Bot CRs are auto-dismissed via `--dismiss-review-ids` in the post-push
+ * `resolve:` command. If the agent drops that flag, the bot CR keeps the PR in
+ * `CHANGES_REQUESTED` state. This file tracks when each bot CR was first
+ * observed so the iterate loop can escalate after `iterate.stallTimeoutMinutes`
+ * — independent of the broader fingerprint-based `stall-timeout` mechanism in
+ * `iterate-stall.mts` (which only fires when no field of the iterate result
+ * changed).
+ *
+ * State lives in
+ * `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/bot-cr-seen.json`.
+ *
+ * `bodyHash` lets us reset `firstSeenAt` when the bot re-issues the review
+ * with a different body, so a fresh review gets the full timeout window.
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveStateBase } from "./base.mjs";
+import { hashBody } from "./seen-comments.mjs";
+export async function readBotCrSeenState(key) {
+    try {
+        const raw = await readFile(resolvePath(key), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object")
+            return null;
+        const reviews = parsed["reviews"];
+        if (reviews === null || typeof reviews !== "object" || Array.isArray(reviews))
+            return null;
+        const validated = {};
+        for (const [id, entry] of Object.entries(reviews)) {
+            if (entry === null || typeof entry !== "object")
+                continue;
+            const e = entry;
+            if (typeof e["firstSeenAt"] !== "number" || !Number.isFinite(e["firstSeenAt"]))
+                continue;
+            if (typeof e["bodyHash"] !== "string")
+                continue;
+            validated[id] = { firstSeenAt: e["firstSeenAt"], bodyHash: e["bodyHash"] };
+        }
+        return { reviews: validated };
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeBotCrSeenState(key, state) {
+    let tmp;
+    try {
+        const path = resolvePath(key);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, JSON.stringify(state), "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+    }
+    catch {
+        // best-effort
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+/**
+ * Update tracked entries against the current set of bot CR reviews:
+ * - Insert any new IDs with `firstSeenAt = now` and the current body hash.
+ * - Reset `firstSeenAt` for entries whose body hash changed (review re-issued).
+ * - Drop entries whose IDs are no longer in the input (review was dismissed
+ *   or superseded by an approval).
+ *
+ * Pure function: returns the next state and the IDs whose age has reached the
+ * `stallTimeoutSeconds` threshold (escalate candidates).
+ */
+export function updateBotCrSeenState(previous, currentBotCrReviews, nowSeconds, stallTimeoutSeconds) {
+    const previousReviews = previous?.reviews ?? {};
+    const next = {};
+    const staleIds = [];
+    for (const r of currentBotCrReviews) {
+        const bodyHash = hashBody(r.body);
+        const prior = previousReviews[r.id];
+        const entry = prior && prior.bodyHash === bodyHash ? prior : { firstSeenAt: nowSeconds, bodyHash };
+        next[r.id] = entry;
+        if (stallTimeoutSeconds > 0 && nowSeconds - entry.firstSeenAt >= stallTimeoutSeconds) {
+            staleIds.push(r.id);
+        }
+    }
+    return { next: { reviews: next }, staleIds };
+}
+function resolvePath(key) {
+    for (const [field, value] of [
+        ["owner", key.owner],
+        ["repo", key.repo],
+    ]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`Invalid state key segment "${field}": ${value}`);
+        }
+    }
+    const base = resolveStateBase();
+    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "bot-cr-seen.json");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.26.2",
+  "version": "0.27.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -39,7 +39,7 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.51.0",
+    "oxfmt": "^0.52.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4"

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.26.2",
+  "version": "0.27.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -16,7 +16,7 @@ Poll dispatcher for iterating a PR to completion.
 
 1. **Resolve the PR number** (`$N`): use the number or URL in `$ARGUMENTS`; otherwise infer it with `gh pr view --json number --jq .number`. If none is found, report an error and stop.
 
-2. **Define the poll command once:** `pr-shepherd $N --interval 45s --timeout 4m`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
+2. **Define the poll command once:** `pr-shepherd $N --interval 60s --timeout 4.5m`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
 
 3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) is non-terminal: do its instructions, then poll again. The poll already bounds each wait via `--interval`/`--timeout`; do not add manual `sleep`s between ticks.