pr-shepherd 0.10.3 → 0.12.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
-  "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.10.3",
+  "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
+  "version": "0.12.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -1,6 +1,6 @@
 # pr-shepherd
 
-Autonomous PR CI monitor and review-comment resolver for Claude Code.
+Autonomous PR CI monitor and review-comment resolver for agentic coding tools, including Claude Code and Codex.
 The goal is to have an agent take a plan to a human-reviewable PR autonomously.
 
 Example Workflow:
@@ -20,6 +20,8 @@ Example Workflow:
 
 `pr-shepherd` optimizes token management, rate limits, and agentic orchestration by moving **ALL** deterministic logic and prompts to code via a CLI tool, enshrining what would be a large skill or command prompt (of which the agent would inevitably make mistakes) into the code and returning a clear, actionable prompt.
 
+The CLI adapts monitor instructions to the calling agent. Claude Code gets `/loop` bootstrap instructions. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`; it gets a reusable `npx pr-shepherd <PR>` command and explicit goal-friendly iterate instructions because Codex does not provide `/loop` scheduling in this workflow.
+
 At a high level, to start the monitor, the skill/command invokes a CLI that returns a prompt to be ingested by the agent _(schematic — paraphrased for brevity; actual output is more detailed)_:
 
 ```
@@ -40,7 +42,7 @@ Loop args: `4m`
 after completing the actions below. The cron job handles the next fire.
 
 Run in a single Bash call:
-  npx pr-shepherd iterate 123
+  npx pr-shepherd 123
 
 …(self-dedup guidance, error-handling instructions)…
 
@@ -50,10 +52,10 @@ Run in a single Bash call:
 2. Otherwise, invoke the /loop skill with Loop args and the full ## Loop prompt body.
 ```
 
-Each iteration calls `npx pr-shepherd iterate <PR>`, which provides actionable feedback directly to the agent:
+Each iteration calls `npx pr-shepherd <PR>`, which provides actionable feedback directly to the agent:
 
 ```
-> npx pr-shepherd iterate 123
+> npx pr-shepherd 123
 
 # PR #123 [FIX_CODE]
 
@@ -125,7 +127,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. As it uses `/loop`, it will continue working when your rate limit window is reset. The loop cancels automatically when the PR is merged, closed, or after the ready-delay elapses.
+- 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 `npx pr-shepherd <PR>` 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).
 - 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.
@@ -142,9 +144,11 @@ Recommendations:
 
 ### Monitor a PR
 
-Creates a cron loop that fires every 4 minutes, checks CI and review
-comments, fixes issues, and marks the PR ready for review when clean. The
-loop cancels automatically when the PR is merged or closed.
+In Claude Code, creates a cron loop that fires every 4 minutes, checks CI and review comments, fixes issues, and marks the PR ready for review when clean. The loop cancels automatically when the PR is merged or closed.
+
+In Codex, run `npx pr-shepherd monitor <PR>` once to emit the goal-friendly recurrence prompt, then follow that prompt. Its reusable follow-up command is `npx pr-shepherd <PR>`.
+
+Claude Code:
 
 ```
 /pr-shepherd:monitor                     # infer PR from current branch
@@ -153,6 +157,16 @@ loop cancels automatically when the PR is merged or closed.
 /pr-shepherd:monitor 42 --ready-delay 15m
 ```
 
+Codex:
+
+```sh
+npx pr-shepherd monitor                  # bootstrap from current branch, then follow its instructions
+npx pr-shepherd monitor 42               # bootstrap PR #42, then follow its instructions
+npx pr-shepherd 42                       # subsequent explicit check/action tick
+npx pr-shepherd 42 --ready-delay 15m
+npx pr-shepherd iterate 42               # legacy-compatible spelling
+```
+
 ### Check a PR
 
 One-shot status snapshot — merge state, CI results, and unresolved comments.
@@ -208,6 +222,34 @@ claude /plugin install pr-shepherd
 
 This repo ships two `marketplace.json` files that serve different install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
 
+### For Codex
+
+Codex does not use the Claude plugin or `/pr-shepherd:*` slash commands. Install the CLI where Codex will run it, then call `npx pr-shepherd` directly:
+
+```bash
+npm install --save-dev pr-shepherd
+```
+
+If your Codex environment does not already set `CODEX_CI=1`, set `AGENT=codex` so `pr-shepherd` emits Codex-compatible instructions instead of Claude `/loop` instructions:
+
+```bash
+export AGENT=codex
+```
+
+Then start a PR monitor from Codex:
+
+```bash
+npx pr-shepherd monitor 42
+```
+
+Follow the output's `## Instructions`. The monitor bootstrap runs one tick and prints the reusable follow-up command, usually:
+
+```bash
+npx 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). `npx pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
+
 ### Without the plugin
 
 See [docs/custom-commands.md](docs/custom-commands.md) for a project-local slash command that wraps the CLI without the plugin.
@@ -234,7 +276,7 @@ actions:
   autoMarkReady: false # disable to stay draft until you manually promote
 ```
 
-Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_STATE_DIR` (override loop-state and log base dir), `PR_SHEPHERD_LOG_DISABLED=1` (disable the per-worktree debug log).
+Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_STATE_DIR` (override loop-state and log base dir), `PR_SHEPHERD_LOG_DISABLED=1` (disable the per-worktree debug log), `AGENT=codex` or `CODEX_CI=1` (emit Codex-compatible monitor instructions).
 
 See [docs/configuration.md](docs/configuration.md) for full semantics and deprecated-key migration.
 

package/bin/agent-runtime.mjs

@@ -0,0 +1,7 @@
+export function detectAgentRuntime(env = process.env) {
+    if (env.AGENT?.trim().toLowerCase() === "codex")
+        return "codex";
+    if (env.CODEX_CI === "1")
+        return "codex";
+    return "claude";
+}

package/bin/checks/triage.mjs

@@ -1,23 +1,19 @@
-import { rest, restText } from "../github/http.mjs";
-export function triageFailingChecks(failingChecks, repo, logTailLines, logTailChars = 200) {
+import { rest } from "../github/http.mjs";
+export function triageFailingChecks(failingChecks, repo) {
     const jobsCache = new Map();
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, logTailLines, logTailChars)));
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
 }
-async function triageCheck(check, repo, jobsCache, logTailLines, logTailChars) {
-    if (check.runId === null) {
+async function triageCheck(check, repo, jobsCache) {
+    if (check.runId === null || check.conclusion === "CANCELLED") {
         return { ...check };
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache);
     const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
-    const logTail = jobInfo?.jobId !== undefined && logTailLines > 0
-        ? await fetchLogTail(jobInfo.jobId, repo, logTailLines, logTailChars, jobInfo.failedStep)
-        : undefined;
     return {
         ...check,
         ...(jobInfo?.workflowName !== undefined && { workflowName: jobInfo.workflowName }),
         ...(jobInfo?.jobName !== undefined && { jobName: jobInfo.jobName }),
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
-        ...(logTail !== undefined && { logTail }),
     };
 }
 function fetchJobs(runId, repo, cache) {
@@ -67,42 +63,5 @@ function pickJobInfo(jobs, checkName) {
         workflowName: job.workflow_name,
         jobName: job.name,
         failedStep,
-        jobId: job.id,
     };
 }
-async function fetchLogTail(jobId, repo, logTailLines, logTailChars, failedStepName) {
-    const { owner, name } = repo;
-    try {
-        const text = await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`);
-        const allLines = text.split("\n");
-        const stepLines = failedStepName ? extractStepLines(allLines, failedStepName) : null;
-        const lines = stepLines ?? allLines;
-        const tail = lines.length <= logTailLines ? lines.join("\n") : lines.slice(-logTailLines).join("\n");
-        return tail.length <= logTailChars ? tail : tail.slice(-logTailChars);
-    }
-    catch {
-        return undefined;
-    }
-}
-// Extract the lines inside the ##[group]..##[endgroup] section for the named step.
-// Returns null when no matching group is found so the caller falls back to the full log.
-function extractStepLines(lines, stepName) {
-    const lowerStep = stepName.toLowerCase();
-    let inStep = false;
-    const result = [];
-    for (const line of lines) {
-        const content = line.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z\s+/, "");
-        if (!inStep) {
-            if (content.startsWith("##[group]") && content.slice(9).toLowerCase().includes(lowerStep)) {
-                inStep = true;
-            }
-        }
-        else if (content.startsWith("##[endgroup]")) {
-            inStep = false;
-        }
-        else {
-            result.push(line);
-        }
-    }
-    return result.length > 0 ? result : null;
-}

package/bin/cli/args.mjs

@@ -94,8 +94,8 @@ export function parseCommonArgs(args) {
             }
         }
     }
-    const prIndex = args.findIndex((a, index) => !skipForPrDetect.has(index) && !a.startsWith("--") && /^\d+$/.test(a));
-    const prNumber = prIndex !== -1 ? parseInt(args[prIndex], 10) : undefined;
+    const prIndex = args.findIndex((a, index) => !skipForPrDetect.has(index) && !a.startsWith("--") && parsePrNumber(a) !== null);
+    const prNumber = prIndex !== -1 ? parsePrNumber(args[prIndex]) : undefined;
     // Remove consumed global-flag indices (and the PR number itself) from extra.
     if (prIndex !== -1) {
         consumedIndices.add(prIndex);
@@ -107,6 +107,14 @@ export function parseCommonArgs(args) {
         extra,
     };
 }
+export function parsePrNumber(value) {
+    if (/^\d+$/.test(value))
+        return parseInt(value, 10);
+    const match = value.match(/^https?:\/\/github\.com\/[^/]+\/[^/]+\/pull\/(\d+)(?:[/?#].*)?$/);
+    if (match)
+        return parseInt(match[1], 10);
+    return null;
+}
 /** Get the value of a flag like `--flag value` or `--flag=value`. */
 export function getFlag(args, name) {
     for (let i = 0; i < args.length; i++) {

package/bin/cli/default-iterate.mjs

@@ -0,0 +1,54 @@
+import { parsePrNumber } from "./args.mjs";
+const DEFAULT_ITERATE_FLAGS_WITH_VALUES = new Set([
+    "--format",
+    "--ready-delay",
+    "--cooldown-seconds",
+    "--stall-timeout",
+]);
+const DEFAULT_ITERATE_BOOLEAN_FLAGS = new Set([
+    "--verbose",
+    "--no-auto-mark-ready",
+    "--no-auto-cancel-actionable",
+]);
+export function isDefaultIterateInvocation(subcommand) {
+    return (subcommand === undefined ||
+        parsePrNumber(subcommand) !== null ||
+        isDefaultIterateFlag(subcommand));
+}
+export function validateDefaultIterateArgs(args) {
+    let sawPr = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (DEFAULT_ITERATE_FLAGS_WITH_VALUES.has(arg)) {
+            if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
+                writeDefaultUsageError(arg);
+                return false;
+            }
+            i += 1;
+            continue;
+        }
+        const inlineFlag = arg.split("=", 1)[0];
+        if (DEFAULT_ITERATE_FLAGS_WITH_VALUES.has(inlineFlag))
+            continue;
+        if (DEFAULT_ITERATE_BOOLEAN_FLAGS.has(arg))
+            continue;
+        if (parsePrNumber(arg) !== null && !sawPr) {
+            sawPr = true;
+            continue;
+        }
+        writeDefaultUsageError(arg);
+        return false;
+    }
+    return true;
+}
+function isDefaultIterateFlag(arg) {
+    const name = arg.split("=", 1)[0];
+    return DEFAULT_ITERATE_FLAGS_WITH_VALUES.has(name) || DEFAULT_ITERATE_BOOLEAN_FLAGS.has(arg);
+}
+function writeDefaultUsageError(arg) {
+    process.stderr.write(`Unknown subcommand: ${arg}\n`);
+    process.stderr.write("Usage: pr-shepherd [PR] [options]\n" +
+        "       pr-shepherd <check|resolve|commit-suggestion|iterate|monitor|status|log-file> [options]\n" +
+        "       pr-shepherd --version | -v\n");
+    process.exitCode = 1;
+}

package/bin/cli/duration-flag.mjs

@@ -0,0 +1,22 @@
+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`);
+        process.exitCode = 1;
+        return null;
+    }
+    return trimmed;
+}

package/bin/cli/fix-formatter.mjs

@@ -1,9 +1,12 @@
 import { renderResolveCommand } from "../commands/iterate.mjs";
-import { safeFence } from "./fence.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "./list-formatters.mjs";
-export function formatFixCodeResult(header, result) {
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, } from "./list-formatters.mjs";
+import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instructions.mjs";
+export function formatFixCodeResult(header, result, opts) {
+    const runtime = opts?.runtime ?? "claude";
+    const readyDelaySuffix = opts?.readyDelaySuffix;
+    const retryInterval = opts?.retryInterval;
     const sections = [header];
     if (result.fix.threads.length > 0) {
         sections.push("## Review threads");
@@ -19,6 +22,12 @@ export function formatFixCodeResult(header, result) {
             }
         }
     }
+    if (result.fix.resolutionOnlyThreads.length > 0) {
+        sections.push("## Review threads to resolve");
+        sections.push(result.fix.resolutionOnlyThreads
+            .map((t) => renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t) }))
+            .join("\n"));
+    }
     if (result.fix.actionableComments.length > 0) {
         sections.push("## Actionable comments");
         for (const c of result.fix.actionableComments) {
@@ -37,16 +46,13 @@ export function formatFixCodeResult(header, result) {
                 : ch.detailsUrl
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
-            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\``];
-            if (ch.failedStep)
-                lines.push(`  > ${ch.failedStep}`);
-            if (ch.summary)
-                lines.push(`  > ${ch.summary}`);
-            if (ch.logTail) {
-                const fence = safeFence(ch.logTail);
-                lines.push(`  ${fence}`);
-                lines.push(ch.logTail.replace(/^/gm, "  ").trimEnd());
-                lines.push(`  ${fence}`);
+            const conclusionTag = ch.conclusion !== null ? ` [conclusion: ${ch.conclusion}]` : "";
+            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}`];
+            if (ch.conclusion !== "CANCELLED") {
+                if (ch.failedStep)
+                    lines.push(`  > ${ch.failedStep}`);
+                if (ch.summary)
+                    lines.push(`  > ${ch.summary}`);
             }
             return lines.join("\n");
         });
@@ -85,7 +91,7 @@ export function formatFixCodeResult(header, result) {
     }
     const firstLookTotal = result.fix.firstLookThreads.length + result.fix.firstLookComments.length;
     if (firstLookTotal > 0) {
-        sections.push(`## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`);
+        sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
         const bullets = [];
         for (const t of result.fix.firstLookThreads) {
             bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
@@ -96,6 +102,10 @@ export function formatFixCodeResult(header, result) {
         }
         sections.push(bullets.join("\n"));
     }
+    if (result.fix.inProgressRunIds.length > 0) {
+        sections.push("## In-progress runs");
+        sections.push(result.fix.inProgressRunIds.map((id) => `- \`${id}\``).join("\n"));
+    }
     if (result.cancelled.length > 0) {
         sections.push("## Cancelled runs");
         sections.push(result.cancelled.map((id) => `- \`${id}\``).join("\n"));
@@ -107,7 +117,7 @@ export function formatFixCodeResult(header, result) {
     }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
-    sections.push(result.fix.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/formatters.mjs

@@ -1,10 +1,11 @@
 export { formatIterateResult } from "./iterate-formatter.mjs";
-export { projectIterateLean } from "./iterate-lean.mjs";
+export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
 import { safeFence } from "./fence.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, } from "./list-formatters.mjs";
 import { joinSections } from "../util/markdown.mjs";
 export function formatFetchResult(result) {
     const activeTotal = result.actionableThreads.length +
+        result.resolutionOnlyThreads.length +
         result.actionableComments.length +
         result.changesRequestedReviews.length +
         result.reviewSummaries.length;
@@ -25,6 +26,12 @@ export function formatFetchResult(result) {
             .map((t) => renderThreadBullet(t, { renderSuggestion: true }))
             .join("\n\n"));
     }
+    if (result.resolutionOnlyThreads.length > 0) {
+        sections.push(`## Review threads to resolve (${result.resolutionOnlyThreads.length})`);
+        sections.push(result.resolutionOnlyThreads
+            .map((t) => renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t) }))
+            .join("\n"));
+    }
     if (result.actionableComments.length > 0) {
         sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
         sections.push(result.actionableComments.map((c) => renderCommentBullet(c)).join("\n"));
@@ -38,7 +45,7 @@ export function formatFetchResult(result) {
         sections.push(result.reviewSummaries.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n"));
     }
     if (firstLookTotal > 0) {
-        sections.push(`## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`);
+        sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
         const bullets = [];
         for (const t of result.firstLookThreads) {
             bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
@@ -67,48 +74,29 @@ export function formatCommitSuggestionResult(result) {
     const range = result.startLine === result.endLine
         ? `line ${result.startLine}`
         : `lines ${result.startLine}–${result.endLine}`;
-    function pushPatch(patch) {
-        const fence = safeFence(patch);
+    lines.push(`Suggestion from @${result.author} for PR #${result.pr} — thread ${result.threadId}:`);
+    lines.push(`  repo: ${result.repo}`);
+    lines.push(`  ${result.path} (${range})`);
+    if (result.patch) {
+        const fence = safeFence(result.patch);
         lines.push("");
         lines.push(`${fence}diff`);
-        lines.push(patch.trimEnd());
+        lines.push(result.patch.trimEnd());
         lines.push(fence);
     }
-    if (result.dryRun) {
-        if (result.valid) {
-            lines.push(`Dry-run: would apply suggestion from @${result.author}:`);
-            lines.push(`  ${result.path} (${range})`);
-        }
-        else {
-            lines.push(`Dry-run: suggestion cannot apply cleanly:`);
-            lines.push(`- path: ${result.path} (${range})`);
-            lines.push(`- author: @${result.author}`);
-            lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        }
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    else if (result.applied) {
-        lines.push(`Applied suggestion from @${result.author}:`);
-        lines.push(`  ${result.path} (${range})`);
-        if (result.commitSha)
-            lines.push(`Commit: ${result.commitSha}`);
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    else {
-        lines.push(`Failed to apply suggestion ${result.threadId}:`);
-        lines.push(`- path: ${result.path} (${range})`);
-        lines.push(`- author: @${result.author}`);
-        lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    if (result.postActionInstruction) {
+    lines.push("");
+    lines.push("## Suggested commit message");
+    lines.push("");
+    lines.push(result.commitMessage);
+    lines.push("");
+    lines.push(result.commitBody);
+    if (result.postActionInstructions.length > 0) {
         lines.push("");
         lines.push("## Instructions");
         lines.push("");
-        lines.push(`1. ${result.postActionInstruction}`);
+        result.postActionInstructions.forEach((inst, i) => {
+            lines.push(`${i + 1}. ${inst}`);
+        });
     }
     return lines.join("\n");
 }

package/bin/cli/handlers.mjs

@@ -1,24 +1,24 @@
 import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
 import { runIterate } from "../commands/iterate.mjs";
-import { runMonitor, formatMonitorResult } from "../commands/monitor.mjs";
+import { runMonitor, formatMonitorResult, formatMonitorJson } from "../commands/monitor.mjs";
 import { runStatus, formatStatusTable } from "../commands/status.mjs";
 import { getRepoInfo } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
+import { detectAgentRuntime } from "../agent-runtime.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseStatusPrNumbers, parseIntStrict, } from "./args.mjs";
 import { parseDurationToMinutes, iterateActionToExitCode, deriveSimpleReady, } from "./exit-codes.mjs";
-import { formatCommitSuggestionResult, formatIterateResult, projectIterateLean, } from "./formatters.mjs";
+import { formatCommitSuggestionResult, formatIterateResult, projectIterateLean, projectIterateVerbose, } from "./formatters.mjs";
+import { validateDurationFlag } from "./duration-flag.mjs";
 export async function handleCommitSuggestion(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
     if (!threadId) {
-        process.stderr.write("Usage: pr-shepherd commit-suggestion [PR] --thread-id ID [--message MSG] [--description DESC] [--dry-run]\n" +
-            "       (--message is required unless --dry-run is set)\n");
+        process.stderr.write("Usage: pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]\n");
         process.exitCode = 1;
         return;
     }
-    const dryRun = hasFlag(extra, "--dry-run");
     const message = getFlag(extra, "--message") ?? undefined;
-    if (!dryRun && (!message || message.trim() === "")) {
+    if (!message || message.trim() === "") {
         process.stderr.write("--message is required and must be non-empty\n");
         process.exitCode = 1;
         return;
@@ -30,23 +30,20 @@ export async function handleCommitSuggestion(args) {
         threadId,
         message,
         description,
-        dryRun,
     });
     process.stdout.write(globalOpts.format === "json"
         ? `${JSON.stringify(result, null, 2)}\n`
         : `${formatCommitSuggestionResult(result)}\n`);
-    if (result.dryRun) {
-        process.exitCode = result.valid ? 0 : 1;
-    }
-    else {
-        process.exitCode = result.applied ? 0 : 1;
-    }
 }
 export async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const runtime = detectAgentRuntime();
     const readyDelayStr = getFlag(extra, "--ready-delay");
+    const readyDelaySuffix = validateDurationFlag("pr-shepherd", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"));
+    if (readyDelaySuffix === null)
+        return;
     const cfg = loadConfig();
-    const readyDelaySeconds = parseDurationToMinutes(readyDelayStr ?? "", cfg.watch.readyDelayMinutes) * 60;
+    const readyDelaySeconds = parseDurationToMinutes(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes) * 60;
     const cooldownSecondsStr = getFlag(extra, "--cooldown-seconds");
     const cooldownSeconds = cooldownSecondsStr
         ? parseIntStrict(cooldownSecondsStr, "--cooldown-seconds")
@@ -66,24 +63,28 @@ export async function handleIterate(args) {
         noAutoMarkReady,
         noAutoCancelActionable,
     });
+    const projectionOpts = { runtime, readyDelaySuffix, retryInterval: cfg.watch.interval };
     if (globalOpts.format === "json") {
-        const output = globalOpts.verbose ? result : projectIterateLean(result);
+        const output = globalOpts.verbose
+            ? projectIterateVerbose(result, projectionOpts)
+            : projectIterateLean(result, projectionOpts);
         process.stdout.write(`${JSON.stringify(output)}\n`);
     }
     else {
-        process.stdout.write(`${formatIterateResult(result, { verbose: globalOpts.verbose })}\n`);
+        process.stdout.write(`${formatIterateResult(result, {
+            verbose: globalOpts.verbose,
+            ...projectionOpts,
+        })}\n`);
     }
     process.exitCode = iterateActionToExitCode(result.action);
 }
 export async function handleMonitor(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const runtime = detectAgentRuntime();
     const readyDelayStr = getFlag(extra, "--ready-delay");
-    if (hasFlag(extra, "--ready-delay") &&
-        (readyDelayStr === null || readyDelayStr.startsWith("--"))) {
-        process.stderr.write("pr-shepherd monitor: --ready-delay requires a value (e.g. --ready-delay 15m)\n");
-        process.exitCode = 1;
+    const readyDelaySuffix = validateDurationFlag("pr-shepherd monitor", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"));
+    if (readyDelaySuffix === null)
         return;
-    }
     const remaining = [];
     for (let i = 0; i < extra.length; i++) {
         const a = extra[i];
@@ -108,7 +109,8 @@ export async function handleMonitor(args) {
         result = await runMonitor({
             ...globalOpts,
             prNumber,
-            readyDelaySuffix: readyDelayStr ?? undefined,
+            readyDelaySuffix: readyDelaySuffix ?? undefined,
+            runtime,
         });
     }
     catch (err) {
@@ -117,8 +119,8 @@ export async function handleMonitor(args) {
         return;
     }
     process.stdout.write(globalOpts.format === "json"
-        ? `${JSON.stringify(result, null, 2)}\n`
-        : `${formatMonitorResult(result)}\n`);
+        ? `${JSON.stringify(formatMonitorJson(result, { runtime }), null, 2)}\n`
+        : `${formatMonitorResult(result, { runtime })}\n`);
 }
 export async function handleStatus(args) {
     const { global: globalOpts } = parseCommonArgs(args);