pr-shepherd 0.26.3 → 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.3",
+  "version": "0.27.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

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/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/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.${(resolveCommand.dismissReviewIds?.length ?? 0) > 0 ? " Bot/non-human CR reviews listed in `--dismiss-review-ids` will be dismissed by the `resolve:` command after your push." : ""}`);
+        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/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.3",
+  "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.3",
+  "version": "0.27.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",