pr-shepherd 0.32.2 → 0.32.4

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.32.2",
+  "version": "0.32.4",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/cli/duration-flag.mjs

@@ -1,8 +1,10 @@
 import { parseSecondsDurationParts } from "./exit-codes.mjs";
-export function validateSecondsDurationFlag(command, flag, value, presentAsSeparateArg) {
+export function validateSecondsDurationFlag(command, flag, value, presentAsSeparateArg, opts = {}) {
+    const bareUnit = opts.defaultUnit === "m" ? "minutes" : "seconds";
+    const example = opts.defaultUnit === "m" ? "15m" : "30s";
     if (value === null) {
         if (presentAsSeparateArg) {
-            process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 30s)\n`);
+            process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} ${example})\n`);
             process.exitCode = 1;
             return null;
         }
@@ -10,34 +12,12 @@ export function validateSecondsDurationFlag(command, flag, value, presentAsSepar
     }
     const trimmed = value.trim();
     if (trimmed.startsWith("--")) {
-        process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 30s)\n`);
+        process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} ${example})\n`);
         process.exitCode = 1;
         return null;
     }
-    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;
-    }
-    return trimmed;
-}
-export function validateDurationFlag(command, flag, value, presentAsSeparateArg) {
-    if (value === null) {
-        if (presentAsSeparateArg) {
-            process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 15m)\n`);
-            process.exitCode = 1;
-            return null;
-        }
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (trimmed.startsWith("--")) {
-        process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 15m)\n`);
-        process.exitCode = 1;
-        return null;
-    }
-    if (!/^\d+(?:m|min|minutes?|h|hours?)?$/.test(trimmed)) {
-        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 5m, 2h, 10m, or 1h.\n`);
+    if (!parseSecondsDurationParts(trimmed, opts)) {
+        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 30s, 4.5m, 1h, or a bare number (${bareUnit}).\n`);
         process.exitCode = 1;
         return null;
     }

package/bin/cli/exit-codes.mjs

@@ -1,4 +1,3 @@
-import { loadConfig } from "../config/load.mjs";
 const SECOND_DURATION_UNITS = new Set([
     "s",
     "sec",
@@ -12,17 +11,7 @@ const SECOND_DURATION_UNITS = new Set([
     "hour",
     "hours",
 ]);
-export function parseDurationToMinutes(s, defaultMinutes) {
-    const m = /^(\d+)(m|min|minutes?|h|hours?)?$/.exec(s.trim());
-    if (!m)
-        return defaultMinutes ?? loadConfig().watch.readyDelayMinutes;
-    const n = parseInt(m[1], 10);
-    const unit = m[2] ?? "m";
-    if (unit.startsWith("h"))
-        return n * 60;
-    return n;
-}
-export function parseSecondsDurationParts(s) {
+export function parseSecondsDurationParts(s, opts = {}) {
     const trimmed = s.trim();
     const match = /^(\d+(?:\.\d+)?)([a-z]+)?$/.exec(trimmed);
     if (!match)
@@ -31,16 +20,18 @@ export function parseSecondsDurationParts(s) {
     const explicitUnit = match[2];
     if (!amount || (amount.includes(".") && !explicitUnit))
         return null;
-    const unit = explicitUnit ?? "s";
+    const unit = explicitUnit ?? opts.defaultUnit ?? "s";
     if (!SECOND_DURATION_UNITS.has(unit))
         return null;
     const value = Number(amount);
-    if (!Number.isFinite(value) || value <= 0)
+    if (!Number.isFinite(value))
+        return null;
+    if (opts.allowZero ? value < 0 : value <= 0)
         return null;
     return { value, unit };
 }
-export function parseDurationToSeconds(s, defaultSeconds) {
-    const parsed = parseSecondsDurationParts(s);
+export function parseDurationToSeconds(s, defaultSeconds, opts = {}) {
+    const parsed = parseSecondsDurationParts(s, opts);
     if (!parsed)
         return defaultSeconds;
     if (parsed.unit.startsWith("h"))

package/bin/cli/handlers.mjs

@@ -94,7 +94,7 @@ export async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();
     const flags = parseIterateFlags(extra, cfg);
-    if (flags.readyDelaySuffix === null)
+    if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
         return;
     const result = await runIterate({
         ...globalOpts,

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

@@ -80,14 +80,16 @@ Usage:
   pr-shepherd iterate [PR] [iterate-flags]
 
 Iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
 
+Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).
+
 Actions:
   WAIT        No immediate code action; recheck later or use pr-shepherd poll.
   MARK_READY  Draft PR was marked ready for review.
@@ -110,21 +112,23 @@ Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
 
 Poll flags:
-  --interval <duration>          Sleep between WAIT ticks. Default: 60s.
-  --timeout <duration>           Maximum wall-clock wait. Default: 4.5m.
+  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.
+  --timeout <duration>           Maximum wall-clock wait. Bare number = seconds. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
   --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
 
 Forwarded iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
   --format text|json             Output Markdown text or JSON. Default: text.
   --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, 4.5m, 1h, or bare seconds.
+Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
+for --interval/--timeout, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
+an explicit unit (4.5m).
 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.
 With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
 

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

@@ -36,14 +36,14 @@ Common flags:
   --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
 
 Iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
 
 Poll flags:
-  --interval <duration>          Delay between WAIT ticks. Default: 60s.
-  --timeout <duration>           Poll wall-clock cap. Default: 4.5m.
+  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.
+  --timeout <duration>           Poll wall-clock cap. Bare number = seconds. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
   --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
 
@@ -60,6 +60,6 @@ Exit codes for iterate and poll:
   2  CANCEL
   3  ESCALATE
 
-Duration examples: 30s, 4.5m, 1h, or bare seconds.
+Duration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).
 
 Run 'pr-shepherd <command> --help' for command-specific details.`;

package/bin/cli/iterate-flags.mjs

@@ -1,19 +1,22 @@
 import { getFlag, hasFlag } from "./args.mjs";
-import { parseDurationToMinutes } from "./exit-codes.mjs";
-import { validateDurationFlag } from "./duration-flag.mjs";
+import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { validateSecondsDurationFlag } from "./duration-flag.mjs";
+// --ready-delay and --stall-timeout are minute-family flags: a bare number means minutes, and 0 is a
+// valid value (it disables the ready-delay settle window / stall-timeout escalation, respectively).
+const MINUTE_FLAG_OPTS = { defaultUnit: "m", allowZero: true };
 export function parseIterateFlags(extra, cfg) {
     const readyDelayStr = getFlag(extra, "--ready-delay");
-    const readyDelaySuffix = validateDurationFlag("pr-shepherd", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"));
-    const readyDelaySeconds = parseDurationToMinutes(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes) * 60;
+    const readyDelaySuffix = validateSecondsDurationFlag("pr-shepherd", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"), MINUTE_FLAG_OPTS);
+    const readyDelaySeconds = parseDurationToSeconds(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes * 60, MINUTE_FLAG_OPTS);
     const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
     const noAutoCancelActionable = hasFlag(extra, "--no-auto-cancel-actionable");
     const stallTimeoutStr = getFlag(extra, "--stall-timeout");
-    const stallTimeoutSeconds = stallTimeoutStr
-        ? parseDurationToMinutes(stallTimeoutStr, cfg.iterate.stallTimeoutMinutes) * 60
-        : cfg.iterate.stallTimeoutMinutes * 60;
+    const stallTimeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--stall-timeout", stallTimeoutStr, hasFlag(extra, "--stall-timeout"), MINUTE_FLAG_OPTS);
+    const stallTimeoutSeconds = parseDurationToSeconds(stallTimeoutSuffix ?? "", cfg.iterate.stallTimeoutMinutes * 60, MINUTE_FLAG_OPTS);
     return {
         readyDelaySuffix,
         readyDelaySeconds,
+        stallTimeoutSuffix,
         stallTimeoutSeconds,
         noAutoMarkReady,
         noAutoCancelActionable,

package/bin/cli/poll-handler.mjs

@@ -11,7 +11,7 @@ export async function handlePoll(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();
     const flags = parseIterateFlags(extra, cfg);
-    if (flags.readyDelaySuffix === null)
+    if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
         return;
     const intervalStr = getFlag(extra, "--interval");
     const intervalSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--interval", intervalStr, hasFlag(extra, "--interval"));

package/bin/commands/iterate/escalate.mjs

@@ -25,6 +25,19 @@ export function checkEscalateTriggers(actionableThreads, threadAttempts) {
  * shell commands by `buildFixInstructions`, so we reject anything outside
  * `[A-Za-z0-9._/-]` to prevent shell injection.
  */
+/**
+ * Render a seconds count as an approximate human duration: "8 seconds" below one minute,
+ * otherwise whole minutes ("166 minutes", "60 minutes") — matching the precision the
+ * generic stall timer has always reported, just adding a seconds tier for sub-minute ages
+ * instead of always flooring to "0 minutes".
+ */
+export function formatDurationApprox(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    if (s < 60)
+        return `${s} second${s === 1 ? "" : "s"}`;
+    const mins = Math.floor(s / 60);
+    return `${mins} minute${mins === 1 ? "" : "s"}`;
+}
 export function validateBaseBranch(raw) {
     const trimmed = raw.trim();
     if (trimmed === "") {
@@ -64,8 +77,7 @@ export function buildEscalateHumanMessage(escalate, pr) {
                 : c.detailsUrl
                     ? `external \`${c.detailsUrl}\``
                     : "no run ID";
-            const ageMinutes = Math.floor(c.ageSeconds / 60);
-            lines.push(`- check \`${c.name}\` — ${c.status} ${c.source}, ${target}, waiting ${ageMinutes} minute${ageMinutes === 1 ? "" : "s"}`);
+            lines.push(`- check \`${c.name}\` — ${c.status} ${c.source}, ${target}, waiting ${formatDurationApprox(c.ageSeconds)}`);
             if (c.summary)
                 lines.push(`  > ${c.summary}`);
         }
@@ -110,8 +122,8 @@ export function buildEscalateHumanMessage(escalate, pr) {
 }
 export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("stall-timeout")) {
-        const mins = detail ?? "60";
-        return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
+        const duration = detail ?? "60 minutes";
+        return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
     if (triggers.includes("base-branch-unknown")) {
         const reason = detail ? ` (${detail})` : "";

package/bin/commands/iterate/stall.mjs

@@ -1,6 +1,6 @@
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
-import { buildEscalateSuggestion, buildEscalateHumanMessage } from "./escalate.mjs";
+import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
@@ -37,14 +37,14 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         action: prospectiveResult.action,
     });
     if (stalledChecks.length > 0) {
-        const stalledMinutes = Math.floor(Math.max(...stalledChecks.map((c) => c.ageSeconds)) / 60);
+        const stalledDuration = formatDurationApprox(Math.max(...stalledChecks.map((c) => c.ageSeconds)));
         const escalateBase = {
             triggers: ["stall-timeout"],
             unresolvedThreads: [],
             ambiguousComments: [],
             changesRequestedReviews: [],
             stalledChecks,
-            suggestion: buildEscalateSuggestion(["stall-timeout"], String(stalledMinutes)),
+            suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
         };
         return {
             ...base,
@@ -68,13 +68,13 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
             await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
         }
         else if (ageSeconds >= stallTimeoutSeconds) {
-            const stalledMinutes = Math.floor(ageSeconds / 60);
+            const stalledDuration = formatDurationApprox(ageSeconds);
             const escalateBase = {
                 triggers: ["stall-timeout"],
                 unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
                 ambiguousComments: report.comments.actionable.map(toAgentComment),
                 changesRequestedReviews: report.changesRequestedReviews,
-                suggestion: buildEscalateSuggestion(["stall-timeout"], String(stalledMinutes)),
+                suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
             };
             return {
                 ...base,

package/bin/commands/poll.mjs

@@ -66,9 +66,16 @@ export async function runPoll(opts) {
     const untilTerminal = untilTerminalOpt === true;
     let dotsPrinted = false;
     let lastWaitSignature = null;
+    // When prNumber is omitted, iterateOpts.prNumber starts undefined and each tick would otherwise
+    // re-infer the PR from the current branch. That inference query only matches OPEN PRs, so once
+    // the monitored PR merges it returns nothing and runIterate throws instead of reporting the
+    // terminal CANCEL/merged result. Pin the PR resolved by the first tick so later ticks target it
+    // directly and never re-run branch discovery.
+    let prNumber = opts.prNumber;
     while (true) {
         tick += 1;
-        lastResult = await runIterate(iterateOpts);
+        lastResult = await runIterate({ ...iterateOpts, prNumber });
+        prNumber ??= lastResult.pr;
         if (lastResult.action !== "wait" && !(untilTerminal && lastResult.action === "mark_ready")) {
             break;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.32.2",
+  "version": "0.32.4",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -38,7 +38,7 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.56.0",
+    "oxfmt": "^0.57.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.32.2",
+  "version": "0.32.4",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",