pr-shepherd 0.17.0 → 0.18.0

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

package/README.md

@@ -20,7 +20,7 @@ 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 emits runtime-specific retry instructions. Claude-compatible output schedules exactly one next session-only iteration after a fresh delay between 30 seconds and 4 minutes, then ends the turn. Codex-compatible output sleeps inline for that delay, then reruns the configured pr-shepherd command. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, `yarn`, or `bun`.
+The CLI emits unified recheck instructions. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, `yarn`, or `bun`.
 
 At a high level, the skill invokes `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
 
@@ -97,7 +97,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. Keep an active goal cycling the reusable command until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). Claude schedules one next session-only iteration per tick; Codex sleeps inline and reruns.
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling the reusable command 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.
@@ -134,7 +134,7 @@ npx pr-shepherd iterate 42               # legacy-compatible spelling
 
 ## Iterate decision loop
 
-On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, or `wait`). Claude schedules one next session-only iteration after a fresh 30s-4m delay; Codex sleeps inline for that delay and reruns. See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
+On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, or `wait`). See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
 
 ## Cleaning state
 
@@ -216,13 +216,7 @@ npm install --save-dev pr-shepherd
 
 The plugin only installs the skill; it does not install the CLI into target repositories. To install the CLI globally instead, use `npm install -g 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 iterate a PR from Codex with the target repository's package runner:
+Iterate a PR from Codex with the target repository's package runner:
 
 ```bash
 <runner> pr-shepherd iterate 42
@@ -230,7 +224,7 @@ Then iterate a PR from Codex with the target repository's package runner:
 
 For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd iterate 42`. For Bun repos (with `bun.lock` or `bun.lockb`), use `bunx pr-shepherd iterate 42`. For npm repos, use `npx pr-shepherd iterate 42`.
 
-Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. The skill runs one tick and Codex-compatible instructions tell you to pick a fresh sleep/timeout between 30 seconds and 4 minutes before the next rerun. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows.
+Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows.
 
 ### As a global CLI
 
@@ -255,7 +249,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`, then `GITHUB_PERSONAL_ACCESS_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).
+Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`, then `GITHUB_PERSONAL_ACCESS_TOKEN`), `PR_SHEPHERD_STATE_DIR` (override loop-state and log base dir), `PR_SHEPHERD_LOG_DISABLED=1` (disable the per-worktree debug log).
 
 See [docs/configuration.md](docs/configuration.md) for full semantics and deprecated-key migration.
 

package/bin/cli/args.mjs

@@ -15,6 +15,8 @@ const FLAGS_WITH_VALUES = new Set([
     "--resolve-thread-ids",
     "--minimize-comment-ids",
     "--dismiss-review-ids",
+    "--interval",
+    "--timeout",
 ]);
 // Boolean flags that do NOT consume the next argument. Any --flag not in this
 // set and not in FLAGS_WITH_VALUES is treated conservatively as value-taking

package/bin/cli/default-iterate.mjs

@@ -43,7 +43,7 @@ function isDefaultIterateFlag(arg) {
 function writeDefaultUsageError(arg) {
     process.stderr.write(`Unknown subcommand: ${arg}\n`);
     process.stderr.write("Usage: pr-shepherd [PR] [options]\n" +
-        "       pr-shepherd <resolve|commit-suggestion|iterate|log-file> [options]\n" +
+        "       pr-shepherd <resolve|commit-suggestion|iterate|poll|log-file|clean> [options]\n" +
         "       pr-shepherd --version | -v\n");
     process.exitCode = 1;
 }

package/bin/cli/duration-flag.mjs

@@ -1,3 +1,25 @@
+export function validateSecondsDurationFlag(command, flag, value, presentAsSeparateArg) {
+    if (value === null) {
+        if (presentAsSeparateArg) {
+            process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 30s)\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} 30s)\n`);
+        process.exitCode = 1;
+        return null;
+    }
+    if (!/^[1-9]\d*(?:s|sec|seconds?|m|min|minutes?|h|hours?)?$/.test(trimmed)) {
+        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 30s, 5m, 1h, or bare seconds (e.g. 30).\n`);
+        process.exitCode = 1;
+        return null;
+    }
+    return trimmed;
+}
 export function validateDurationFlag(command, flag, value, presentAsSeparateArg) {
     if (value === null) {
         if (presentAsSeparateArg) {

package/bin/cli/exit-codes.mjs

@@ -9,6 +9,20 @@ export function parseDurationToMinutes(s, defaultMinutes) {
         return n * 60;
     return n;
 }
+export function parseDurationToSeconds(s, defaultSeconds) {
+    const m = /^(\d+)(s|sec|seconds?|m|min|minutes?|h|hours?)?$/.exec(s.trim());
+    if (!m)
+        return defaultSeconds;
+    const n = parseInt(m[1], 10);
+    if (!Number.isFinite(n))
+        return defaultSeconds;
+    const unit = m[2] ?? "s";
+    if (unit.startsWith("h"))
+        return n * 3600;
+    if (unit.startsWith("m"))
+        return n * 60;
+    return n;
+}
 export function statusToExitCode(status) {
     switch (status) {
         case "MERGED":

package/bin/cli/fix-formatter.mjs

@@ -4,7 +4,6 @@ import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mj
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, } 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 runner = opts?.runner;
     const sections = [header];
@@ -110,7 +109,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, runner)));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/handlers.mjs

@@ -2,11 +2,10 @@ import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
 import { runIterate } from "../commands/iterate/index.mjs";
 import { runClean } from "../commands/clean.mjs";
 import { loadConfig } from "../config/load.mjs";
-import { detectAgentRuntime } from "../agent-runtime.mjs";
-import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
-import { parseDurationToMinutes, iterateActionToExitCode } from "./exit-codes.mjs";
-import { formatCommitSuggestionResult, formatCleanResult, formatIterateResult, projectIterateLean, projectIterateVerbose, } from "./formatters.mjs";
-import { validateDurationFlag } from "./duration-flag.mjs";
+import { parseCommonArgs, getFlag } from "./args.mjs";
+import { formatCommitSuggestionResult, formatCleanResult } from "./formatters.mjs";
+import { parseIterateFlags } from "./iterate-flags.mjs";
+import { emitIterateResult } from "./iterate-emitter.mjs";
 const CLEAN_VARIANTS = new Set(["pr", "branch", "current", "repo", "all"]);
 export async function handleClean(args) {
     const variant = args[0];
@@ -90,41 +89,22 @@ export async function handleCommitSuggestion(args) {
 }
 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(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes) * 60;
-    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 flags = parseIterateFlags(extra, cfg);
+    if (flags.readyDelaySuffix === null)
+        return;
     const result = await runIterate({
         ...globalOpts,
         prNumber,
-        readyDelaySeconds,
-        stallTimeoutSeconds,
-        noAutoMarkReady,
-        noAutoCancelActionable,
+        readyDelaySeconds: flags.readyDelaySeconds,
+        stallTimeoutSeconds: flags.stallTimeoutSeconds,
+        noAutoMarkReady: flags.noAutoMarkReady,
+        noAutoCancelActionable: flags.noAutoCancelActionable,
     });
-    const projectionOpts = {
-        runtime,
-        readyDelaySuffix,
+    emitIterateResult(result, {
+        format: globalOpts.format,
+        verbose: globalOpts.verbose ?? false,
+        readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
         runner: cfg.cli?.runner,
-    };
-    if (globalOpts.format === "json") {
-        const output = globalOpts.verbose
-            ? projectIterateVerbose(result, projectionOpts)
-            : projectIterateLean(result, projectionOpts);
-        process.stdout.write(`${JSON.stringify(output)}\n`);
-    }
-    else {
-        const text = formatIterateResult(result, { verbose: globalOpts.verbose, ...projectionOpts });
-        process.stdout.write(`${text}\n`);
-    }
-    process.exitCode = iterateActionToExitCode(result.action);
+    });
 }

package/bin/cli/iterate-emitter.mjs

@@ -0,0 +1,19 @@
+import { iterateActionToExitCode } from "./exit-codes.mjs";
+import { formatIterateResult, projectIterateLean, projectIterateVerbose } from "./formatters.mjs";
+export function emitIterateResult(result, opts) {
+    const projectionOpts = {
+        readyDelaySuffix: opts.readyDelaySuffix,
+        runner: opts.runner,
+    };
+    if (opts.format === "json") {
+        const output = opts.verbose
+            ? projectIterateVerbose(result, projectionOpts)
+            : projectIterateLean(result, projectionOpts);
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+    }
+    else {
+        const text = formatIterateResult(result, { verbose: opts.verbose, ...projectionOpts });
+        process.stdout.write(`${text}\n`);
+    }
+    process.exitCode = iterateActionToExitCode(result.action);
+}

package/bin/cli/iterate-flags.mjs

@@ -0,0 +1,21 @@
+import { getFlag, hasFlag } from "./args.mjs";
+import { parseDurationToMinutes } from "./exit-codes.mjs";
+import { validateDurationFlag } from "./duration-flag.mjs";
+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 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;
+    return {
+        readyDelaySuffix,
+        readyDelaySeconds,
+        stallTimeoutSeconds,
+        noAutoMarkReady,
+        noAutoCancelActionable,
+    };
+}

package/bin/cli/iterate-formatter.mjs

@@ -17,7 +17,6 @@ import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, }
  */
 export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
-    const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const runner = opts?.runner;
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
@@ -27,7 +26,14 @@ export function formatIterateResult(result, opts) {
     const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\``;
     let summaryLine;
     if (verbose) {
-        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}`;
+        let verboseBranch = "";
+        if (result.mergeStatus === "BEHIND" && result.baseBranch) {
+            verboseBranch = ` · **branch** behind \`origin/${result.baseBranch}\``;
+        }
+        else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
+            verboseBranch = ` · **branch** conflicts with \`origin/${result.baseBranch}\``;
+        }
+        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}`;
     }
     else {
         const counts = [`${result.summary.passing} passing`];
@@ -45,37 +51,68 @@ export function formatIterateResult(result, opts) {
             segs.push(`**blockingBotReviewInProgress**`);
         if (result.isDraft)
             segs.push(`**isDraft**`);
+        if (result.mergeStatus === "BEHIND" && result.baseBranch) {
+            segs.push(`**branch** behind \`origin/${result.baseBranch}\``);
+        }
+        else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
+            segs.push(`**branch** conflicts with \`origin/${result.baseBranch}\``);
+        }
         summaryLine = segs.join(" · ");
     }
-    const header = [heading, "", baseLine, summaryLine].join("\n");
+    const bp = result.branchProtection;
+    const requiredParts = [];
+    if (bp) {
+        if (bp.requiresApprovingReviews && bp.requiredApprovingReviewCount > 0) {
+            requiredParts.push(`approvals \`${bp.requiredApprovingReviewCount}\``);
+        }
+        if (bp.requiresConversationResolution) {
+            requiredParts.push("conversation-resolution required");
+        }
+        if (bp.requiresStatusChecks) {
+            if (bp.requiredStatusCheckContexts.length > 0) {
+                requiredParts.push(`checks: ${bp.requiredStatusCheckContexts.map((c) => `\`${c}\``).join(", ")}`);
+            }
+            else {
+                requiredParts.push("status checks required");
+            }
+        }
+    }
+    const requiredLine = requiredParts.length > 0 ? `**required** ${requiredParts.join(", ")}` : null;
+    const headerLines = [heading, "", baseLine, summaryLine];
+    if (requiredLine)
+        headerLines.push(requiredLine);
+    const header = headerLines.join("\n");
     switch (result.action) {
         case "wait":
             return joinSections([
                 header,
-                adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
+                adaptIterateLog(result.log),
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
-                adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
+                adaptIterateLog(result.log),
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
             ]);
-        case "cancel":
+        case "cancel": {
+            const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
+            if (requiredLine)
+                cancelHeaderLines.push(requiredLine);
             return joinSections([
-                [`${heading} — ${result.reason}`, "", baseLine, summaryLine].join("\n"),
-                adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
+                cancelHeaderLines.join("\n"),
+                adaptIterateLog(result.log),
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
             ]);
+        }
         case "escalate":
             return joinSections([
                 header,
                 result.escalate.humanMessage,
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
             ]);
         case "fix_code":
             return formatFixCodeResult(header, result, {
-                runtime,
                 readyDelaySuffix,
                 runner,
             });

package/bin/cli/iterate-instructions.mjs

@@ -1,19 +1,16 @@
-import { FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
+import { FIX_INSTRUCTION_STOP } from "../commands/iterate/render.mjs";
 import { buildPrShepherdCommand } from "./runner.mjs";
-function buildRecheckInstruction(runtime, rerunCommand, purpose) {
-    if (runtime === "codex") {
-        return `Pick a fresh sleep/timeout between 30 seconds and 4 minutes, wait that long, then rerun \`${rerunCommand}\` to ${purpose}.`;
-    }
-    return `Single-shot continuation: schedule one session-only follow-up task to run \`${rerunCommand}\` to ${purpose} once after a fresh delay between 30 seconds and 4 minutes, then end this turn. Do not sleep or rerun inline.`;
+function buildRecheckInstruction(rerunCommand, purpose) {
+    return `Recheck: rerun \`${rerunCommand}\` to ${purpose} once after a fresh 30s–4m delay.`;
 }
-export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner) {
+export function buildSimpleIterateInstructions(result, readyDelaySuffix, runner) {
     const rerunCommand = buildIterateCommand(result.pr, readyDelaySuffix, runner);
     switch (result.action) {
         case "wait":
-            return [buildRecheckInstruction(runtime, rerunCommand, "continue the active goal")];
+            return [buildRecheckInstruction(rerunCommand, "continue the active goal")];
         case "mark_ready":
             return [
-                `The CLI already marked the PR ready for review. ${buildRecheckInstruction(runtime, rerunCommand, "recheck")}`,
+                `The CLI already marked the PR ready for review. ${buildRecheckInstruction(rerunCommand, "recheck")}`,
             ];
         case "cancel":
             return ["Stop — the active goal is complete."];
@@ -23,19 +20,16 @@ export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix
             ];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, runner) {
+export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix, runner) {
     const rerunCommand = buildIterateCommand(pr, readyDelaySuffix, runner);
     return instructions.map((instruction) => {
-        if (instruction === FIX_INSTRUCTION_STOP_AFTER_PUSH) {
-            return `CI needs time to run on the new push. ${buildRecheckInstruction(runtime, rerunCommand, "recheck")}`;
-        }
-        if (instruction === FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK) {
-            return buildRecheckInstruction(runtime, rerunCommand, "recheck");
+        if (instruction === FIX_INSTRUCTION_STOP) {
+            return `${instruction} ${buildRecheckInstruction(rerunCommand, "recheck")}`;
         }
         return instruction;
     });
 }
-export function adaptIterateLog(log, _runtime) {
+export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
 export function buildIterateCommand(pr, readyDelaySuffix, runner) {

package/bin/cli/iterate-lean.mjs

@@ -5,10 +5,9 @@ import { adaptIterateLog, adaptFixCodeInstructions, buildSimpleIterateInstructio
  * outside the state where they are meaningful.
  */
 export function projectIterateLean(result, opts) {
-    const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const runner = opts?.runner;
-    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, runner);
+    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, readyDelaySuffix, runner);
     const base = {
         action: result.action,
         pr: result.pr,
@@ -32,26 +31,27 @@ export function projectIterateLean(result, opts) {
             remainingSeconds: result.remainingSeconds,
         }),
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
+        ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
     };
     switch (result.action) {
         case "wait":
             return {
                 ...base,
-                log: adaptIterateLog(result.log, runtime),
+                log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
         case "cancel":
             return {
                 ...base,
                 reason: result.reason,
-                log: adaptIterateLog(result.log, runtime),
+                log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
         case "mark_ready":
             // drop markedReady — always true, redundant with action discriminator
             return {
                 ...base,
-                log: adaptIterateLog(result.log, runtime),
+                log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
         case "fix_code":
@@ -94,7 +94,7 @@ export function projectIterateLean(result, opts) {
                     }),
                     resolveCommand: result.fix.resolveCommand,
                     ...(result.fix.instructions.length > 0 && {
-                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
+                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner),
                     }),
                 },
             };
@@ -124,7 +124,6 @@ export function projectIterateLean(result, opts) {
     }
 }
 export function projectIterateVerbose(result, opts) {
-    const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const runner = opts?.runner;
     if (result.action === "fix_code") {
@@ -132,16 +131,14 @@ export function projectIterateVerbose(result, opts) {
             ...result,
             fix: {
                 ...result.fix,
-                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
+                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner),
             },
         };
     }
-    const log = "log" in result && typeof result.log === "string"
-        ? { log: adaptIterateLog(result.log, runtime) }
-        : {};
+    const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
     return {
         ...result,
         ...log,
-        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner),
+        instructions: buildSimpleIterateInstructions(result, readyDelaySuffix, runner),
     };
 }

package/bin/cli/poll-handler.mjs

@@ -0,0 +1,42 @@
+import { runPoll } from "../commands/poll.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
+import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { validateSecondsDurationFlag } from "./duration-flag.mjs";
+import { parseIterateFlags } from "./iterate-flags.mjs";
+import { emitIterateResult } from "./iterate-emitter.mjs";
+const DEFAULT_POLL_INTERVAL_SECONDS = 30;
+const DEFAULT_POLL_TIMEOUT_SECONDS = 300;
+export async function handlePoll(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const cfg = loadConfig();
+    const flags = parseIterateFlags(extra, cfg);
+    if (flags.readyDelaySuffix === null)
+        return;
+    const intervalStr = getFlag(extra, "--interval");
+    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--interval", intervalStr, hasFlag(extra, "--interval"));
+    if (intervalSuffix === null)
+        return;
+    const intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", DEFAULT_POLL_INTERVAL_SECONDS);
+    const timeoutStr = getFlag(extra, "--timeout");
+    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
+    if (timeoutSuffix === null)
+        return;
+    const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", DEFAULT_POLL_TIMEOUT_SECONDS);
+    const result = await runPoll({
+        ...globalOpts,
+        prNumber,
+        readyDelaySeconds: flags.readyDelaySeconds,
+        stallTimeoutSeconds: flags.stallTimeoutSeconds,
+        noAutoMarkReady: flags.noAutoMarkReady,
+        noAutoCancelActionable: flags.noAutoCancelActionable,
+        intervalSeconds,
+        timeoutSeconds,
+    });
+    emitIterateResult(result, {
+        format: globalOpts.format,
+        verbose: globalOpts.verbose ?? false,
+        readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
+        runner: cfg.cli?.runner,
+    });
+}

package/bin/cli-parser.iterate-fix.test-support.mjs

@@ -32,15 +32,11 @@ export function registerHooks() {
     beforeEach(() => {
         vi.clearAllMocks();
         process.exitCode = undefined;
-        delete process.env.AGENT;
-        delete process.env.CODEX_CI;
         stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
         stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
     });
     afterEach(() => {
         process.exitCode = undefined;
-        delete process.env.AGENT;
-        delete process.env.CODEX_CI;
         stdoutSpy.mockRestore();
         stderrSpy.mockRestore();
     });

package/bin/cli-parser.iterate-fixtures.mjs

@@ -13,6 +13,7 @@ export function makeIterateResult(action = "wait") {
         remainingSeconds: 60,
         summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 1 },
         baseBranch: "main",
+        branchProtection: null,
         checks: [],
     };
     if (action === "wait")
@@ -39,7 +40,9 @@ export function makeIterateResult(action = "wait") {
                     requiresDismissMessage: false,
                     hasMutations: false,
                 },
-                instructions: ["Stop this iteration before the next tick."],
+                instructions: [
+                    "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.",
+                ],
                 firstLookThreads: [],
                 firstLookComments: [],
                 inProgressRunIds: [],

package/bin/cli-parser.iterate.test-support.mjs

@@ -33,15 +33,11 @@ export function registerHooks() {
     beforeEach(() => {
         vi.clearAllMocks();
         process.exitCode = undefined;
-        delete process.env.AGENT;
-        delete process.env.CODEX_CI;
         stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
         stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
     });
     afterEach(() => {
         process.exitCode = undefined;
-        delete process.env.AGENT;
-        delete process.env.CODEX_CI;
         stdoutSpy.mockRestore();
         stderrSpy.mockRestore();
     });

package/bin/cli-parser.mjs

@@ -14,6 +14,9 @@
  *   pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]
  *                              [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                              [--no-auto-cancel-actionable]
+ *   pr-shepherd poll [PR] [--interval 30s] [--timeout 5m] [--format text|json] [--ready-delay Nm]
+ *                         [--stall-timeout <duration>] [--no-auto-mark-ready]
+ *                         [--no-auto-cancel-actionable]
  *   pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]
  */
 import { readFileSync } from "node:fs";
@@ -23,6 +26,7 @@ import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultIterateInvocation, validateDefaultIterateArgs } from "./cli/default-iterate.mjs";
 import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate } from "./cli/handlers.mjs";
+import { handlePoll } from "./cli/poll-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
 // Entry
@@ -57,12 +61,15 @@ export async function main(argv) {
         case "iterate":
             await handleIterate(args.slice(1));
             break;
+        case "poll":
+            await handlePoll(args.slice(1));
+            break;
         case "clean":
             await handleClean(args.slice(1));
             break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
-            process.stderr.write("Usage: pr-shepherd <resolve|commit-suggestion|iterate|log-file|clean> [options]\n" +
+            process.stderr.write("Usage: pr-shepherd <resolve|commit-suggestion|iterate|poll|log-file|clean> [options]\n" +
                 "       pr-shepherd --version | -v\n");
             process.exitCode = 1;
             return;

package/bin/commands/check-terminal-report.mjs

@@ -31,5 +31,6 @@ export function buildTerminalReport(prNumber, repo, batchData, mergeStatus, stat
         firstLookSummaries: [],
         editedSummaries: [],
         approvedReviews: [],
+        branchProtection: batchData.branchProtection,
     };
 }