pr-shepherd 0.26.1 → 0.26.3

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.1",
+  "version": "0.26.3",
   "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/checks/classify.mjs

@@ -20,7 +20,7 @@ export function classifyChecks(checks) {
     const config = loadConfig();
     const relevantEvents = new Set(config.checks.ciTriggerEvents);
     const isIgnored = buildIgnoreMatcher(config.ignoreChecks ?? []);
-    return checks.filter((c) => !isIgnored(c.name)).map((c) => classify(c, relevantEvents));
+    return checks.map((c) => isIgnored(c.name) ? { ...c, category: "ignored" } : classify(c, relevantEvents));
 }
 function buildIgnoreMatcher(patterns) {
     if (patterns.length === 0)
@@ -51,7 +51,7 @@ function classify(check, relevantEvents) {
 }
 /** Compute a high-level CI verdict from a list of classified checks. */
 export function getCiVerdict(classified) {
-    const relevant = classified.filter((c) => c.category !== "filtered" && c.category !== "skipped");
+    const relevant = classified.filter((c) => c.category !== "filtered" && c.category !== "skipped" && c.category !== "ignored");
     const anyInProgress = relevant.some((c) => c.category === "in_progress");
     const anyFailing = relevant.some((c) => c.category === "failing");
     // When there are no relevant checks (e.g. docs-only PR where all checks are filtered/skipped),
@@ -59,5 +59,6 @@ export function getCiVerdict(classified) {
     const allPassed = !anyInProgress && !anyFailing;
     const hasChecks = relevant.length > 0;
     const filteredNames = classified.filter((c) => c.category === "filtered").map((c) => c.name);
-    return { allPassed, hasChecks, anyInProgress, anyFailing, filteredNames };
+    const ignoredNames = Array.from(new Set(classified.filter((c) => c.category === "ignored").map((c) => c.name)));
+    return { allPassed, hasChecks, anyInProgress, anyFailing, filteredNames, ignoredNames };
 }

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/iterate-formatter.mjs

@@ -112,6 +112,10 @@ export function formatIterateResult(result, opts) {
     const headerLines = [heading, "", baseLine, summaryLine];
     if (requiredLine)
         headerLines.push(requiredLine);
+    if (result.ignoredNames && result.ignoredNames.length > 0) {
+        const names = result.ignoredNames.map((n) => "`" + n + "`").join(", ");
+        headerLines.push(`**ignored** ${names}`);
+    }
     const activityLine = formatActivityLine(result);
     if (activityLine)
         headerLines.push(activityLine);
@@ -133,6 +137,10 @@ export function formatIterateResult(result, opts) {
             const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
             if (requiredLine)
                 cancelHeaderLines.push(requiredLine);
+            if (result.ignoredNames && result.ignoredNames.length > 0) {
+                const ignoredStr = result.ignoredNames.map((n) => "`" + n + "`").join(", ");
+                cancelHeaderLines.push(`**ignored** ${ignoredStr}`);
+            }
             if (activityLine)
                 cancelHeaderLines.push(activityLine);
             return joinSections([

package/bin/cli/iterate-lean.mjs

@@ -55,6 +55,9 @@ export function projectIterateLean(result, opts) {
         ...((result.inProgressChecks?.length ?? 0) > 0 && {
             inProgressChecks: result.inProgressChecks,
         }),
+        ...((result.ignoredNames?.length ?? 0) > 0 && {
+            ignoredNames: result.ignoredNames,
+        }),
     };
     switch (result.action) {
         case "wait":

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-status.mjs

@@ -13,13 +13,18 @@ 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.
+    // Exception: UNSTABLE with ignored checks — UNSTABLE means only non-required checks are
+    // pending/failing, and if those are all ignored the handoff is safe even with no other checks.
+    // BLOCKED is excluded from the ignoredNames extension: BLOCKED can mean required checks haven't
+    // started, and handing off prematurely there risks a broken merge attempt.
     // blockingBotReviewInProgress is still excluded — a bot review is shepherd's problem, not a hand-off.
+    const hasRelevantPassingChecks = verdict.hasChecks || (mergeStatus.status === "UNSTABLE" && verdict.ignoredNames.length > 0);
     if (verdict.allPassed &&
-        verdict.hasChecks &&
+        hasRelevantPassingChecks &&
         unresolvedThreads === 0 &&
         unresolvedComments === 0 &&
         changesRequestedReviews === 0 &&
-        mergeStatus.status === "BLOCKED" &&
+        (mergeStatus.status === "BLOCKED" || mergeStatus.status === "UNSTABLE") &&
         !mergeStatus.blockingBotReviewInProgress) {
         return "READY";
     }

package/bin/commands/check.mjs

@@ -124,6 +124,7 @@ export async function runCheck(opts) {
             filtered,
             filteredNames: verdict.filteredNames,
             blockedByFilteredCheck,
+            ...(verdict.ignoredNames.length > 0 && { ignoredNames: verdict.ignoredNames }),
         },
         threads: {
             actionable: threadVisibility.activeThreads,

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/index.mjs

@@ -50,6 +50,7 @@ export async function runIterate(opts) {
             branchProtection: report.branchProtection,
             checks: buildRelevantChecks(report),
             inProgressChecks: buildActiveChecks(report),
+            ...(report.checks.ignoredNames?.length ? { ignoredNames: report.checks.ignoredNames } : {}),
             activity: report.activity,
             action: "cancel",
             reason: report.mergeStatus.state === "MERGED" ? "merged" : "closed",
@@ -93,6 +94,7 @@ export async function runIterate(opts) {
         branchProtection: report.branchProtection,
         checks: buildRelevantChecks(report),
         inProgressChecks: buildActiveChecks(report),
+        ...(report.checks.ignoredNames?.length ? { ignoredNames: report.checks.ignoredNames } : {}),
         activity: report.activity,
     };
     if (readyState.shouldCancel) {

package/bin/commands/iterate/render.mjs

@@ -79,7 +79,7 @@ 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.`);
+        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." : ""}`);
     }
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "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.