pr-shepherd 0.15.0 → 0.15.1

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

package/README.md

@@ -126,7 +126,7 @@ Some other workflow improvements:
 
 Recommendations:
 
-- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable command with a fresh 1-4 minute sleep before each rerun until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
 - Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
@@ -279,7 +279,7 @@ Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until
 <runner> pr-shepherd 42
 ```
 
-For an active Codex goal, rerun that command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
+For an active Codex goal, rerun that command after picking a fresh 1-4 minute sleep until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
 
 ### Without the plugin
 

package/bin/cli/fix-formatter.mjs

@@ -6,7 +6,6 @@ import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instruct
 export function formatFixCodeResult(header, result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
     const sections = [header];
     if (result.fix.threads.length > 0) {
@@ -118,7 +117,7 @@ export function formatFixCodeResult(header, result, opts) {
     }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
-    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner)));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/handlers.mjs

@@ -66,7 +66,6 @@ export async function handleIterate(args) {
     const projectionOpts = {
         runtime,
         readyDelaySuffix,
-        retryInterval: cfg.watch.interval,
         runner: cfg.cli?.runner,
     };
     if (globalOpts.format === "json") {

package/bin/cli/iterate-formatter.mjs

@@ -20,7 +20,6 @@ export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
@@ -57,37 +56,36 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 verbose ? header : heading,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "wait":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "cancel":
             return joinSections([
                 [`${heading} — ${result.reason}`, "", baseLine, summaryLine].join("\n"),
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "escalate":
             return joinSections([
                 header,
                 result.escalate.humanMessage,
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "fix_code":
             return formatFixCodeResult(header, result, {
                 runtime,
                 readyDelaySuffix,
-                retryInterval,
                 runner,
             });
     }

package/bin/cli/iterate-instructions.mjs

@@ -1,28 +1,30 @@
 import { FIX_INSTRUCTION_END_ITERATION, FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
 import { buildPrShepherdCommand } from "./runner.mjs";
-const DEFAULT_CODEX_RETRY_INTERVAL = "4m";
-const VALID_RETRY_INTERVAL = /^\d+[smhd]$/;
 const CLAUDE_DYNAMIC_WAKEUP = "Schedule the next dynamic wakeup with `ScheduleWakeup` using `delaySeconds` between 60 and 240 and the same loop prompt (skip if running under a fixed-interval cron loop — the next scheduled fire handles it), then end this iteration.";
-export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner) {
+const CODEX_DYNAMIC_WAIT = "pick a fresh sleep/timeout between 1 and 4 minutes, wait that long";
+function capitalizeFirst(value) {
+    return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}
+export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner) {
     const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix, runner);
-    const retryDelay = buildCodexRetryDelay(retryInterval);
+    const retryDelay = buildCodexRetryDelay();
     switch (result.action) {
         case "cooldown":
             return [
                 runtime === "codex"
-                    ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` after CI starts reporting.`
+                    ? `Continue the active Codex goal — ${retryDelay}, then rerun \`${rerunCommand}\` after CI starts reporting.`
                     : `CI still needs time to start reporting. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "wait":
             return [
                 runtime === "codex"
-                    ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
+                    ? `Continue the active Codex goal — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
                     : CLAUDE_DYNAMIC_WAKEUP,
             ];
         case "mark_ready":
             return [
                 runtime === "codex"
-                    ? `The CLI already marked the PR ready for review. Continue the active Codex goal until the ready-delay completes — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
+                    ? `The CLI already marked the PR ready for review. Continue the active Codex goal until the ready-delay completes — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
                     : `The CLI already marked the PR ready for review. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "cancel":
@@ -41,18 +43,18 @@ export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix
             ];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, retryInterval, runner) {
+export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, runner) {
     if (runtime !== "codex")
         return instructions;
     const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix, runner);
-    const retryDelay = buildCodexRetryDelay(retryInterval);
+    const retryDelay = buildCodexRetryDelay();
     return instructions.map((instruction) => {
         if (instruction === FIX_INSTRUCTION_STOP_AFTER_PUSH) {
-            return `Continue the active Codex goal — CI needs time to run on the new push. Wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`;
+            return `Continue the active Codex goal — CI needs time to run on the new push. ${capitalizeFirst(retryDelay)}, then rerun \`${rerunCommand}\` to recheck.`;
         }
         if (instruction === FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK ||
             instruction === FIX_INSTRUCTION_END_ITERATION) {
-            return `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`;
+            return `Continue the active Codex goal — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`;
         }
         return instruction;
     });
@@ -68,11 +70,8 @@ export function buildCodexIterateCommand(pr, readyDelaySuffix, runner) {
         runner,
     }).text;
 }
-export function buildCodexRetryDelay(retryInterval) {
-    const interval = typeof retryInterval === "string" ? retryInterval.trim() : "";
-    return VALID_RETRY_INTERVAL.test(interval)
-        ? `the configured interval (${interval})`
-        : `the configured interval (default ${DEFAULT_CODEX_RETRY_INTERVAL})`;
+export function buildCodexRetryDelay() {
+    return CODEX_DYNAMIC_WAIT;
 }
 export function numberInstructions(instructions) {
     return instructions.map((instruction, i) => `${i + 1}. ${instruction}`).join("\n");

package/bin/cli/iterate-lean.mjs

@@ -7,9 +7,8 @@ import { adaptIterateLog, adaptFixCodeInstructions, buildSimpleIterateInstructio
 export function projectIterateLean(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
-    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, retryInterval, runner);
+    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, runner);
     const base = {
         action: result.action,
         pr: result.pr,
@@ -102,7 +101,7 @@ export function projectIterateLean(result, opts) {
                     }),
                     resolveCommand: result.fix.resolveCommand,
                     ...(result.fix.instructions.length > 0 && {
-                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
+                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
                     }),
                 },
             };
@@ -134,14 +133,13 @@ export function projectIterateLean(result, opts) {
 export function projectIterateVerbose(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
     if (result.action === "fix_code") {
         return {
             ...result,
             fix: {
                 ...result.fix,
-                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
+                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
             },
         };
     }
@@ -151,6 +149,6 @@ export function projectIterateVerbose(result, opts) {
     return {
         ...result,
         ...log,
-        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner),
+        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner),
     };
 }

package/bin/commands/monitor.mjs

@@ -20,7 +20,7 @@ export async function runMonitor(opts) {
     const loopTag = `#pr-shepherd-loop:pr=${prNumber}:`;
     const loopArgs = interval;
     const reusableCommand = buildIterateCommand(prNumber, opts.readyDelaySuffix, config.cli?.runner);
-    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, loopArgs, opts.runtime ?? "claude", config.cli?.runner);
+    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, opts.runtime ?? "claude", config.cli?.runner);
     return {
         prNumber,
         loopTag,
@@ -40,8 +40,10 @@ export function formatMonitorResult(result, opts) {
             `# PR #${prNumber} [MONITOR]`,
             "",
             `Loop tag: \`${loopTag}\``,
-            `Loop args: \`${loopArgs}\``,
-        ].join("\n"),
+            runtime === "codex" ? null : `Loop args: \`${loopArgs}\``,
+        ]
+            .filter((line) => line !== null)
+            .join("\n"),
         runtime === "codex" ? `Reusable command: \`${result.reusableCommand}\`` : null,
         "## Loop prompt",
         loopPrompt,
@@ -54,10 +56,20 @@ export function formatMonitorResult(result, opts) {
 }
 export function formatMonitorJson(result, opts) {
     const runtime = opts?.runtime ?? "claude";
-    const { reusableCommand, ...base } = result;
+    if (runtime === "codex") {
+        return {
+            prNumber: result.prNumber,
+            loopTag: result.loopTag,
+            loopPrompt: result.loopPrompt,
+            reusableCommand: result.reusableCommand,
+            instructions: buildMonitorInstructions(result, runtime),
+        };
+    }
     return {
-        ...base,
-        ...(runtime === "codex" && { reusableCommand }),
+        prNumber: result.prNumber,
+        loopTag: result.loopTag,
+        loopArgs: result.loopArgs,
+        loopPrompt: result.loopPrompt,
         instructions: buildMonitorInstructions(result, runtime),
     };
 }
@@ -77,14 +89,14 @@ function buildIterateCommand(prNumber, readyDelaySuffix, runner) {
     const validatedDelay = validateReadyDelaySuffix(readyDelaySuffix);
     return buildPrShepherdCommand([String(prNumber), ...(validatedDelay ? ["--ready-delay", validatedDelay] : [])], { runner }).text;
 }
-function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "claude", runner) {
+function buildLoopPrompt(prNumber, loopTag, iterateCmd, runtime = "claude", runner) {
     if (runtime === "codex") {
         return [
             loopTag,
             "",
             "**IMPORTANT — Codex recurrence rules:**",
             "- Run the command below once and follow its `## Instructions` exactly.",
-            `- If the output tells you to continue the active Codex goal, wait about the configured interval (${loopArgs}) and rerun the reusable command from the monitor output.`,
+            "- If the output tells you to continue the active Codex goal, pick a fresh sleep/timeout between 1 and 4 minutes, wait that long, and rerun the reusable command from the monitor output.",
             "- Stop only when Shepherd emits `[CANCEL]` because the ready-delay completed or the PR was merged/closed, or when Shepherd emits `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).",
             `- Do not call \`/loop\`, \`ScheduleWakeup\`, \`CronCreate\`, or \`${buildPrShepherdCommand(["monitor", String(prNumber)], { runner }).text}\`; Codex recurrence is explicit \`iterate\` command cycles.`,
             "",
@@ -117,7 +129,7 @@ function buildMonitorInstructions(result, runtime) {
     if (runtime === "codex") {
         return [
             "Run the `## Loop prompt` body once inline now.",
-            `For an active Codex goal, keep cycling with \`${result.reusableCommand}\` about every configured interval (${result.loopArgs}) until a terminal condition is reached. Codex does not create a \`/loop\` monitor.`,
+            `For an active Codex goal, keep cycling with \`${result.reusableCommand}\` by picking a fresh sleep/timeout between 1 and 4 minutes before each rerun until a terminal condition is reached. Codex does not create a \`/loop\` monitor.`,
         ];
     }
     return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "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.15.0",
+  "version": "0.15.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",