pr-shepherd 0.14.1 → 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.14.1",
+  "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/checks/startup-failures.mjs

@@ -0,0 +1,22 @@
+export function mergeStartupFailureChecks(checks, startupFailureChecks) {
+    const byRunId = new Map();
+    checks.forEach((check, index) => {
+        if (check.runId === null)
+            return;
+        const indices = byRunId.get(check.runId) ?? [];
+        indices.push(index);
+        byRunId.set(check.runId, indices);
+    });
+    const merged = [...checks];
+    const removed = new Set();
+    for (const startupFailure of startupFailureChecks) {
+        const indices = startupFailure.runId === null ? undefined : byRunId.get(startupFailure.runId);
+        if (indices === undefined) {
+            merged.push(startupFailure);
+            continue;
+        }
+        merged[indices[0]] = startupFailure;
+        indices.slice(1).forEach((index) => removed.add(index));
+    }
+    return merged.filter((_, index) => !removed.has(index));
+}

package/bin/checks/triage.mjs

@@ -1,10 +1,13 @@
 import { rest } from "../github/http.mjs";
+const STARTUP_FAILURE_STATUS = "startup_failure";
 export function triageFailingChecks(failingChecks, repo) {
     const jobsCache = new Map();
     return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
 }
 async function triageCheck(check, repo, jobsCache) {
-    if (check.runId === null || check.conclusion === "CANCELLED") {
+    if (check.runId === null ||
+        check.conclusion === "CANCELLED" ||
+        check.conclusion === "STARTUP_FAILURE") {
         return { ...check };
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache);
@@ -16,6 +19,49 @@ async function triageCheck(check, repo, jobsCache) {
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
     };
 }
+export async function fetchStartupFailureChecks(repo, headSha, prNumber) {
+    try {
+        return await fetchStartupFailureChecksUncached(repo, headSha, prNumber);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`pr-shepherd: startup-failure run fetch failed for PR #${prNumber} at ${headSha} (ignored): ${msg}\n`);
+        return [];
+    }
+}
+async function fetchStartupFailureChecksUncached(repo, headSha, prNumber) {
+    const { owner, name } = repo;
+    const perPage = 100;
+    const MAX_RUN_PAGES = 10;
+    const checks = [];
+    for (let page = 1; page <= MAX_RUN_PAGES; page++) {
+        const data = await rest("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`);
+        checks.push(...data.workflow_runs
+            .filter((run) => runBelongsToPr(run, prNumber, headSha))
+            .map(workflowRunToCheckRun));
+        if (data.workflow_runs.length < perPage)
+            break;
+        if (page === MAX_RUN_PAGES) {
+            process.stderr.write(`pr-shepherd: startup-failure run pagination cap (${MAX_RUN_PAGES * perPage} runs) reached for ${headSha} — startup-failure detection may be incomplete\n`);
+        }
+    }
+    return checks;
+}
+function workflowRunToCheckRun(run) {
+    const summary = run.display_title?.trim() || undefined;
+    return {
+        name: run.name?.trim() || `workflow run ${run.id}`,
+        status: "COMPLETED",
+        conclusion: "STARTUP_FAILURE",
+        detailsUrl: run.html_url,
+        event: run.event,
+        runId: String(run.id),
+        ...(summary !== undefined && { summary }),
+    };
+}
+function runBelongsToPr(run, prNumber, headSha) {
+    return (run.pull_requests ?? []).some((pr) => pr.number === prNumber && (pr.head?.sha ?? headSha) === headSha);
+}
 function fetchJobs(runId, repo, cache) {
     const cached = cache.get(runId);
     if (cached)

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

@@ -1,7 +1,8 @@
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getRepoInfo, getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
-import { triageFailingChecks } from "../checks/triage.mjs";
+import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
+import { fetchStartupFailureChecks, triageFailingChecks } from "../checks/triage.mjs";
 import { getOutdatedThreads } from "../comments/outdated.mjs";
 import { autoResolveOutdated } from "../comments/resolve.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
@@ -28,7 +29,9 @@ export async function runCheck(opts) {
             mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
         };
     }
-    const classifiedChecks = classifyChecks(batchData.checks);
+    const startupFailureChecks = await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
+    const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
+    const classifiedChecks = classifyChecks(allChecks);
     const verdict = getCiVerdict(classifiedChecks);
     const passing = classifiedChecks.filter((c) => c.category === "passed");
     const failing = classifiedChecks.filter((c) => c.category === "failing");

package/bin/commands/iterate/check-instructions.mjs

@@ -0,0 +1,24 @@
+export function buildFailingCheckInstructions(checks) {
+    const instructions = [];
+    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED" && c.conclusion !== "STARTUP_FAILURE");
+    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
+    const startupFailureRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "STARTUP_FAILURE");
+    const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
+    const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
+    if (failedRunIdChecks.length > 0) {
+        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` or \`[conclusion: STARTUP_FAILURE]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`, `If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`, `If the log shows a real test/build failure: apply a code fix.`);
+    }
+    if (cancelledRunIdChecks.length > 0) {
+        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
+    }
+    if (startupFailureRunIdChecks.length > 0) {
+        instructions.push(`For each \`[conclusion: STARTUP_FAILURE]\` bullet under \`## Failing checks\`: the workflow failed before jobs/logs were created. Run \`gh run view <runId>\` to inspect the run metadata, then run \`gh run rerun <runId>\` if the workflow should be attempted again.`);
+    }
+    if (externalChecks.length > 0) {
+        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
+    }
+    if (bareChecks.length > 0) {
+        instructions.push(`For each bullet in \`## Failing checks\` starting with \`(no runId)\`: there is no run or details URL to inspect. Escalate these to a human — they require manual investigation outside the pr-shepherd flow.`);
+    }
+    return instructions;
+}

package/bin/commands/iterate/render.mjs

@@ -1,4 +1,5 @@
 import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
+import { buildFailingCheckInstructions } from "./check-instructions.mjs";
 export const FIX_INSTRUCTION_STOP_AFTER_PUSH = "Stop this iteration — CI needs time to run on the new push before the next tick.";
 export const FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK = "Stop this iteration before the next tick.";
 export const FIX_INSTRUCTION_END_ITERATION = "End this iteration.";
@@ -41,24 +42,7 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (resolutionOnlyThreads.length > 0) {
         instructions.push(`Resolve the threads under \`## Review threads to resolve\` with the \`resolve:\` command shown below. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
     }
-    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
-    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED");
-    const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
-    const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
-    if (failedRunIdChecks.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`);
-        instructions.push(`If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`);
-        instructions.push(`If the log shows a real test/build failure: apply a code fix.`);
-    }
-    if (cancelledRunIdChecks.length > 0) {
-        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
-    }
-    if (externalChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
-    }
-    if (bareChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`(no runId)\`: there is no run or details URL to inspect. Escalate these to a human — they require manual investigation outside the pr-shepherd flow.`);
-    }
+    instructions.push(...buildFailingCheckInstructions(checks));
     if (reviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }

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/bin/reporters/agent.mjs

@@ -4,7 +4,7 @@
  * These strip fields that are always-false by the time items reach iterate
  * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
  * monitor prompt never reads (event, status, category).
- * conclusion is preserved on AgentCheck so the formatter can branch on CANCELLED.
+ * conclusion is preserved on AgentCheck so the formatter can branch on run-level conclusions.
  * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
  * The original domain types are preserved for check command output.
  */

package/bin/reporters/check-instructions.mjs

@@ -35,7 +35,9 @@ export function buildCheckInstructions(report, opts) {
         const diagnosisHint = c.runId
             ? c.conclusion === "CANCELLED"
                 ? `cancelled — if unintended, rerun with \`gh run rerun ${c.runId}\``
-                : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
+                : c.conclusion === "STARTUP_FAILURE"
+                    ? `startup failure — run \`gh run view ${c.runId}\` to inspect the workflow run; rerun with \`gh run rerun ${c.runId}\` if appropriate`
+                    : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
             : c.detailsUrl
                 ? `open the check details (${c.detailsUrl}) to diagnose the failure`
                 : `no run or details URL available — escalate to a human`;

package/package.json

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