pr-shepherd 0.16.4 → 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.16.4",
+  "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`, or `yarn`.
+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,19 @@ 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
+
+`pr-shepherd` accumulates state under `$PR_SHEPHERD_STATE_DIR` (seen markers, fix-attempt counters, stall fingerprints, etc.). To reset it:
+
+```sh
+npx pr-shepherd clean current    # remove state for the current branch's PR
+npx pr-shepherd clean repo       # remove all state for this repo
+npx pr-shepherd clean all        # remove all pr-shepherd state
+```
+
+Add `--dry-run` to preview what would be removed. See [docs/cli-usage.md](docs/cli-usage.md) for the full `clean` reference.
 
 ## Install
 
@@ -143,6 +155,7 @@ On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and
 > ```bash
 > pnpm add -D pr-shepherd      # pnpm repos
 > yarn add -D pr-shepherd      # yarn repos
+> bun add -d pr-shepherd       # bun repos
 > npm install --save-dev pr-shepherd
 > ```
 >
@@ -197,26 +210,21 @@ Install the CLI where Codex will run it:
 ```bash
 pnpm add -D pr-shepherd      # pnpm repos
 yarn add -D pr-shepherd      # yarn repos
+bun add -d pr-shepherd       # bun repos
 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
 ```
 
-For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd iterate 42`. For npm repos, use `npx pr-shepherd iterate 42`.
+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
 
@@ -241,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/clean-formatter.mjs

@@ -0,0 +1,20 @@
+import { joinSections } from "../util/markdown.mjs";
+export function formatCleanResult(result) {
+    if (!result.ok) {
+        return `Error: ${result.error ?? "unknown error"}`;
+    }
+    const heading = result.dryRun ? "## Would clean" : "## Cleaned";
+    const paths = result.deleted;
+    if (result.skipped.length > 0) {
+        const label = result.dryRun ? "Nothing to clean (dry-run)" : "Nothing to clean";
+        return `${label} — ${result.target} does not exist.`;
+    }
+    const sections = [
+        heading,
+        paths.map((p) => `- ${p}`).join("\n"),
+        result.dryRun
+            ? `Would remove ${paths.length} item(s) under ${result.target}`
+            : `Removed ${paths.length} item(s) under ${result.target}`,
+    ];
+    return joinSections(sections);
+}

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

@@ -1,10 +1,9 @@
 import { renderResolveCommand } from "../commands/iterate/render.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, renderAuthor, } from "./list-formatters.mjs";
+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];
@@ -92,15 +91,8 @@ export function formatFixCodeResult(header, result, opts) {
     const firstLookTotal = result.fix.firstLookThreads.length + result.fix.firstLookComments.length;
     if (firstLookTotal > 0) {
         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) }));
-        }
-        for (const c of result.fix.firstLookComments) {
-            const editedSuffix = c.edited ? ", edited" : "";
-            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
-        }
-        sections.push(bullets.join("\n"));
+        const resolutionOnlyIds = new Set(result.fix.resolutionOnlyThreads.map((t) => t.id));
+        sections.push(buildFirstLookBullets(result.fix.firstLookThreads, resolutionOnlyIds, result.fix.firstLookComments).join("\n"));
     }
     if (result.fix.inProgressRunIds.length > 0) {
         sections.push("## In-progress runs");
@@ -117,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/formatters.mjs

@@ -1,7 +1,8 @@
 export { formatIterateResult } from "./iterate-formatter.mjs";
 export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
+export { formatCleanResult } from "./clean-formatter.mjs";
 import { safeFence } from "./fence.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, } from "./list-formatters.mjs";
 import { joinSections } from "../util/markdown.mjs";
 export function formatFetchResult(result) {
     const activeTotal = result.actionableThreads.length +
@@ -46,15 +47,8 @@ export function formatFetchResult(result) {
     }
     if (firstLookTotal > 0) {
         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) }));
-        }
-        for (const c of result.firstLookComments) {
-            const editedSuffix = c.edited ? ", edited" : "";
-            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
-        }
-        sections.push(bullets.join("\n"));
+        const resolutionOnlyIds = new Set(result.resolutionOnlyThreads.map((t) => t.id));
+        sections.push(buildFirstLookBullets(result.firstLookThreads, resolutionOnlyIds, result.firstLookComments).join("\n"));
     }
     sections.push("## Summary");
     sections.push(total === 0
@@ -108,6 +102,8 @@ export function formatMutateResult(result) {
         lines.push(`Minimized comments (${result.minimizedComments.length}): ${result.minimizedComments.join(", ")}`);
     if (result.dismissedReviews.length)
         lines.push(`Dismissed reviews (${result.dismissedReviews.length}): ${result.dismissedReviews.join(", ")}`);
+    if (result.skippedDismissals?.length)
+        lines.push(`Skipped dismissals (${result.skippedDismissals.length}): ${result.skippedDismissals.join(", ")}`);
     if (result.rateLimit) {
         const details = [
             result.rateLimit.retryAfterSeconds !== undefined

package/bin/cli/handlers.mjs

@@ -1,11 +1,66 @@
 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, 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];
+    if (!variant || !CLEAN_VARIANTS.has(variant)) {
+        process.stderr.write("Usage: pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]\n");
+        process.exitCode = 1;
+        return;
+    }
+    const rest = args.slice(1);
+    for (const a of rest) {
+        if (!a.startsWith("--"))
+            continue;
+        if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
+            continue;
+        process.stderr.write(`pr-shepherd: clean: unknown flag: "${a}"\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const fmtIdx = rest.indexOf("--format");
+    const fmtEqEntry = rest.find((a) => a.startsWith("--format="));
+    let formatValue;
+    if (fmtEqEntry !== undefined) {
+        formatValue = fmtEqEntry.slice("--format=".length);
+    }
+    else if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
+        formatValue = rest[fmtIdx + 1];
+    }
+    if (formatValue !== undefined && formatValue !== "text" && formatValue !== "json") {
+        process.stderr.write(`pr-shepherd: clean: invalid --format value: "${formatValue}". Expected "text" or "json".\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const jsonOut = formatValue === "json";
+    const dryRun = rest.includes("--dry-run");
+    // Skip the value consumed by --format <value> so it isn't mistaken for the positional.
+    const flagConsumedIndices = new Set();
+    if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
+        flagConsumedIndices.add(fmtIdx);
+        flagConsumedIndices.add(fmtIdx + 1);
+    }
+    const positionals = rest.filter((a, i) => !flagConsumedIndices.has(i) && !a.startsWith("--"));
+    if (positionals.length > 1) {
+        process.stderr.write(`pr-shepherd: clean: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const value = positionals[0];
+    const result = await runClean({ variant: variant, value, dryRun });
+    if (!result.ok) {
+        process.stderr.write(`pr-shepherd: clean: ${result.error}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${formatCleanResult(result)}\n`);
+}
 export async function handleCommitSuggestion(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
@@ -34,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,39 +1,35 @@
-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 `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."];
         case "escalate":
-            return ["Stop — the PR needs human direction before iterating can resume."];
+            return [
+                "Stop — the PR needs human direction before iterating can resume. This is a manual handoff; do not continue automated fix attempts.",
+            ];
     }
 }
-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) {