pr-shepherd 0.20.0 → 0.21.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.20.0",
+  "version": "0.21.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -22,10 +22,10 @@ Example Workflow:
 
 The CLI emits unified recheck instructions. Generated commands call `pr-shepherd` directly.
 
-At a high level, the skill invokes `pr-shepherd poll <PR>`, which provides actionable feedback directly to the agent:
+At a high level, the skill invokes `pr-shepherd <PR>` (which polls by default), providing actionable feedback directly to the agent:
 
 ```text
-> pr-shepherd poll 123
+> pr-shepherd 123
 
 # PR #123 [FIX_CODE]
 
@@ -61,7 +61,7 @@ _(schematic — actual steps depend on PR state)_
 4. Rebase and push: `git fetch origin && git rebase origin/main && git push --force-with-lease` — capture `HEAD_SHA=$(git rev-parse HEAD)`.
 5. Run the `resolve:` command above, substituting `"$HEAD_SHA"`.
 6. Add or update a `## Shepherd Journal` section in the PR description for any large decisions made, appending under the existing heading if it already exists.
-7. CI needs time to run on the new push. Run `pr-shepherd poll 123` again to continue until Shepherd returns `[CANCEL]` or `[ESCALATE]`.
+7. CI needs time to run on the new push. Run `pr-shepherd 123` again to continue until Shepherd returns `[CANCEL]` or `[ESCALATE]`.
 ```
 
 On every iteration, a command is returned to instruct the agent exactly what to do. No guessing, no thinking, as few agentic turns as possible:
@@ -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 `pr-shepherd poll` until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling `pr-shepherd <PR>` 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.
@@ -114,7 +114,7 @@ Recommendations:
 
 ### Iterate a PR to completion
 
-Poll dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section; the skill follows it, then invokes `pr-shepherd poll` again until `[CANCEL]` or `[ESCALATE]`.
+Poll dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section; the skill follows it, then invokes `pr-shepherd <PR>` again until `[CANCEL]` or `[ESCALATE]`.
 
 Claude Code (via `pr-shepherd` skill):
 
@@ -128,9 +128,9 @@ Codex or direct CLI:
 
 ```sh
 pr-shepherd 42
+pr-shepherd 42 --interval 45s --timeout 4m
 pr-shepherd 42 --ready-delay 15m
-pr-shepherd poll 42
-pr-shepherd iterate 42               # legacy-compatible spelling
+pr-shepherd iterate 42               # single tick
 ```
 
 ## Iterate decision loop

package/bin/checks/triage.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 // ---------------------------------------------------------------------------
 // Stub fetch globally so http.mts uses our mock.
 // ---------------------------------------------------------------------------

package/bin/cli/default-poll.mjs

@@ -0,0 +1,32 @@
+import { parsePrNumber } from "./args.mjs";
+import { validateDefaultArgs } from "./validate-default-args.mjs";
+import { USAGE } from "./help.mjs";
+const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
+    "--format",
+    "--ready-delay",
+    "--stall-timeout",
+    "--interval",
+    "--timeout",
+]);
+const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
+    "--verbose",
+    "--no-auto-mark-ready",
+    "--no-auto-cancel-actionable",
+]);
+export function isDefaultPollInvocation(subcommand) {
+    if (subcommand === "--help" || subcommand === "-h")
+        return false;
+    return (subcommand === undefined || parsePrNumber(subcommand) !== null || isDefaultPollFlag(subcommand));
+}
+export function validateDefaultPollArgs(args) {
+    return validateDefaultArgs(args, DEFAULT_POLL_FLAGS_WITH_VALUES, DEFAULT_POLL_BOOLEAN_FLAGS, writeDefaultUsageError);
+}
+function isDefaultPollFlag(arg) {
+    const name = arg.split("=", 1)[0];
+    return DEFAULT_POLL_FLAGS_WITH_VALUES.has(name) || DEFAULT_POLL_BOOLEAN_FLAGS.has(arg);
+}
+function writeDefaultUsageError(arg) {
+    process.stderr.write(`Unknown subcommand: ${arg}\n`);
+    process.stderr.write(`${USAGE.top}\n`);
+    process.exitCode = 1;
+}

package/bin/cli/help-command-pages.mjs

@@ -51,11 +51,10 @@ Exit codes:
   1  validation, lookup, precondition, or suggestion parsing failure`,
     iterate: `pr-shepherd iterate
 
-Run one iterate tick for a pull request. This is an alias for 'pr-shepherd [PR]'.
+Run one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.
 The output contains one action and an action-specific ## Instructions section.
 
 Usage:
-  pr-shepherd [PR] [iterate-flags]
   pr-shepherd iterate [PR] [iterate-flags]
 
 Iterate flags:
@@ -98,11 +97,11 @@ Forwarded iterate flags:
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
   --format text|json             Output Markdown text or JSON. Default: text.
-  --verbose                      Include verbose iterate fields and always print poll progress.
+  --verbose                      Include verbose iterate fields and detailed per-tick lines.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
 
 Durations accept seconds, minutes, or hours: 30s, 2m, 1h, or bare seconds.
-WAIT progress is written to stderr when stderr is a TTY or --verbose is set.
+Each WAIT tick writes a single dot to stderr; --verbose emits the detailed per-tick line.
 
 Exit codes:
   0  WAIT timeout or MARK_READY

package/bin/cli/help-top-page.mjs

@@ -5,8 +5,8 @@ Autonomous PR CI monitor and review-comment resolver for agentic coding tools.
 Usage:
   pr-shepherd --version | -v
   pr-shepherd --help | -h
-  pr-shepherd [PR] [flags]
-  pr-shepherd iterate [PR] [flags]
+  pr-shepherd [PR] [poll-flags] [iterate-flags]
+  pr-shepherd iterate [PR] [iterate-flags]
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
   pr-shepherd resolve [PR] [resolve-flags]
   pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [flags]
@@ -14,8 +14,8 @@ Usage:
   pr-shepherd log-file [--format text|json]
 
 Commands:
-  [PR]                 Run one iterate tick. This is the default command.
-  iterate              Alias for the default one-tick iterate command.
+  [PR]                 Poll until non-WAIT or timeout. This is the default command.
+  iterate              Run one iterate tick (single-tick alias).
   poll                 Re-run iterate while the action is WAIT, then print the final tick.
   resolve              Fetch actionable review items, or resolve/minimize/dismiss IDs.
   commit-suggestion    Convert one GitHub suggestion thread into a patch and commit instructions.
@@ -28,7 +28,7 @@ PR argument:
 
 Common flags:
   --format text|json   Output Markdown text or JSON. Default: text.
-  --verbose            Include verbose iterate fields and poll progress.
+  --verbose            Include verbose iterate fields and detailed poll-tick lines.
   --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
 
 Iterate flags:

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

@@ -1,5 +1,3 @@
-// @ts-nocheck
-import { describe, it, expect } from "vitest";
 import { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
 import { makeIterateResult } from "../cli-parser.iterate-fixtures.mjs";
 export { makeIterateResult, projectIterateLean, projectIterateVerbose };

package/bin/cli/validate-default-args.mjs

@@ -0,0 +1,32 @@
+import { parsePrNumber } from "./args.mjs";
+/**
+ * Validate args for default-dispatch paths (e.g. `pr-shepherd [PR] [flags]`).
+ * Returns false when an unexpected token is found; calls onError with the
+ * offending arg so callers can print their own usage message.
+ */
+export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError) {
+    let sawPr = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (flagsWithValues.has(arg)) {
+            if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
+                onError(arg);
+                return false;
+            }
+            i += 1;
+            continue;
+        }
+        const inlineFlag = arg.split("=", 1)[0];
+        if (flagsWithValues.has(inlineFlag))
+            continue;
+        if (booleanFlags.has(arg))
+            continue;
+        if (parsePrNumber(arg) !== null && !sawPr) {
+            sawPr = true;
+            continue;
+        }
+        onError(arg);
+        return false;
+    }
+    return true;
+}

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

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/clean.mts", () => ({
     runClean: vi.fn(),

package/bin/cli-parser.commit-suggestion.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),

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

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),

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

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),

package/bin/cli-parser.mjs

@@ -3,7 +3,7 @@
  *
  * Usage:
  *   pr-shepherd --version
- *   pr-shepherd [PR] [--format text|json] [--ready-delay Nm]
+ *   pr-shepherd [PR] [--interval 45s] [--timeout 4m] [--format text|json] [--ready-delay Nm]
  *                  [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                  [--no-auto-cancel-actionable]
  *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
@@ -22,7 +22,7 @@ import { readFileSync } from "node:fs";
 import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
-import { isDefaultIterateInvocation, validateDefaultIterateArgs } from "./cli/default-iterate.mjs";
+import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, maybePrintHelp } from "./cli/help.mjs";
 import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate } from "./cli/handlers.mjs";
@@ -49,8 +49,8 @@ export async function main(argv) {
     }
     // Short-circuit all --help/-h before any I/O or logging.
     if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
-        if (isDefaultIterateInvocation(subcommand)) {
-            process.stdout.write(`${USAGE.iterate}\n`);
+        if (isDefaultPollInvocation(subcommand)) {
+            process.stdout.write(`${USAGE.poll}\n`);
         }
         else {
             const key = subcommand != null && subcommand in USAGE
@@ -62,10 +62,10 @@ export async function main(argv) {
     }
     // Initialize the per-worktree log and install a stdout tee.
     await setupLog(argv);
-    if (isDefaultIterateInvocation(subcommand)) {
-        if (!validateDefaultIterateArgs(args))
+    if (isDefaultPollInvocation(subcommand)) {
+        if (!validateDefaultPollArgs(args))
             return;
-        await handleIterate(args);
+        await handlePoll(args);
         return;
     }
     switch (subcommand) {

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

@@ -1,6 +1,5 @@
-// @ts-nocheck
 import { readFileSync } from "node:fs";
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),
     runResolveMutate: vi.fn(),

package/bin/commands/check.mjs

@@ -46,7 +46,8 @@ export async function runCheck(opts) {
     let autoResolveErrors = [];
     if (opts.autoResolve && outdated.length > 0) {
         const { resolved: resolvedIds, errors } = await autoResolveOutdated(outdated.map((t) => t.id));
-        autoResolved = outdated.filter((t) => resolvedIds.includes(t.id));
+        const resolvedIdsSet = new Set(resolvedIds); // ⚡ Bolt optimization: O(1) lookup
+        autoResolved = outdated.filter((t) => resolvedIdsSet.has(t.id));
         autoResolveErrors = errors;
     }
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated && !t.isMinimized);

package/bin/commands/check.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 vi.mock("../github/batch.mts", () => ({ fetchPrBatch: vi.fn() }));
 vi.mock("../github/client.mts", () => ({
     getRepoInfo: vi.fn().mockResolvedValue({ owner: "owner", name: "repo" }),

package/bin/commands/clean.test-support.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import { vi, beforeEach, afterEach } from "vitest";
 import { join } from "node:path";
 import { mkdtemp, realpath, rm, mkdir, writeFile, stat } from "node:fs/promises";

package/bin/commands/commit-suggestion.apply.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi } from "vitest";
 // ---------------------------------------------------------------------------
 // Hoisted mocks
 // ---------------------------------------------------------------------------

package/bin/commands/commit-suggestion.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 // ---------------------------------------------------------------------------
 // Hoisted mocks
 // ---------------------------------------------------------------------------

package/bin/commands/iterate-stall.test-support.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import { vi } from "vitest";
 import { NOW, makeOpts } from "./iterate-test-support.mjs";
 import { readStallState, writeStallState } from "../state/iterate-stall.mjs";

package/bin/commands/iterate.fix-code-in-progress.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 const mockFetch = vi.fn();
 vi.stubGlobal("fetch", mockFetch);
 const { mockExecFile } = vi.hoisted(() => ({ mockExecFile: vi.fn() }));
@@ -44,6 +43,7 @@ function makeReport(overrides = {}) {
         repo: "owner/repo",
         status: "READY",
         baseBranch: "main",
+        branchProtection: null,
         mergeStatus: {
             status: "CLEAN",
             state: "OPEN",

package/bin/commands/poll.mjs

@@ -3,9 +3,12 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
-    if (process.stderr.isTTY || verbose) {
+    if (verbose) {
         process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
     }
+    else {
+        process.stderr.write(".");
+    }
 }
 const MAX_TIMER_MS = 2 ** 31 - 1;
 export async function runPoll(opts) {
@@ -16,17 +19,23 @@ export async function runPoll(opts) {
     let tick = 0;
     let lastResult;
     const verbose = opts.verbose === true;
+    let dotsPrinted = false;
     while (true) {
         tick += 1;
         lastResult = await runIterate(iterateOpts);
         if (lastResult.action !== "wait")
-            return lastResult;
+            break;
         const elapsedMs = Date.now() - start;
         const remainingMs = timeoutMs - elapsedMs;
         if (remainingMs <= 0)
-            return lastResult;
+            break;
         const nextSleepMs = Math.min(intervalMs, remainingMs);
         writeTickProgress(tick, Math.round(elapsedMs / 1000), Math.round(nextSleepMs / 1000), verbose);
+        if (!verbose)
+            dotsPrinted = true;
         await sleep(nextSleepMs);
     }
+    if (dotsPrinted)
+        process.stderr.write("\n");
+    return lastResult;
 }

package/bin/commands/resolve.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 vi.mock("../github/client.mts", () => ({
     getRepoInfo: vi.fn().mockResolvedValue({ owner: "owner", name: "repo" }),
     getCurrentPrNumber: vi.fn().mockResolvedValue(42),
@@ -67,6 +66,7 @@ function makeBatchData(overrides = {}) {
         reviewSummaries: [],
         approvedReviews: [],
         checks: [],
+        branchProtection: null,
         ...overrides,
     };
 }

package/bin/commands/shepherd-journal.test-support.mjs

@@ -1,5 +1,3 @@
-// @ts-nocheck
-import { describe, expect, it } from "vitest";
 import { buildShepherdJournalInstruction, SHEPHERD_JOURNAL_APPEND_HINT, SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS, SHEPHERD_JOURNAL_SECTION, SHEPHERD_JOURNAL_SECTION_PATTERN, } from "./shepherd-journal.mjs";
 import { buildFixInstructions } from "./iterate/render.mjs";
 import { buildFetchInstructions } from "./resolve-instructions.mjs";

package/bin/comments/resolve.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 // ---------------------------------------------------------------------------
 // Mock github/client.mts before any imports.
 // ---------------------------------------------------------------------------

package/bin/github/batch-parsers.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 vi.mock("./client.mts", () => ({
     graphql: vi.fn(),
     graphqlWithRateLimit: vi.fn(),

package/bin/github/batch.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 vi.mock("./client.mts", () => ({
     graphql: vi.fn(),
     graphqlWithRateLimit: vi.fn(),

package/bin/github/http.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 // ---------------------------------------------------------------------------
 // Stub fetch and child_process globally before any imports.
 // ---------------------------------------------------------------------------

package/bin/suggestions/patch.test-support.mjs

@@ -1,4 +1,2 @@
-// @ts-nocheck
-import { describe, it, expect } from "vitest";
 import { buildUnifiedDiff } from "./patch.mjs";
 export { buildUnifiedDiff };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -20,20 +20,20 @@ Poll dispatcher for iterating a PR to completion.
    - Otherwise, infer: `gh pr view --json number --jq .number`
    - If no PR found, report an error and stop.
 
-2. **Run `pr-shepherd poll`:**
+2. **Run `pr-shepherd`:**
 
    ```bash
-   pr-shepherd poll <N>
+   pr-shepherd <N> --interval 45s --timeout 4m
    ```
 
-   Do not pass `$ARGUMENTS` through as extra flags. If you need to inspect supported options, run `pr-shepherd poll --help`.
+   Do not pass `$ARGUMENTS` through as extra flags. If you need to inspect supported options, run `pr-shepherd --help`.
 
-   Print the full output. Follow the `## Instructions` section exactly for the current action. When those instructions tell you to stop and recheck with `pr-shepherd <N>` after a delay, use `pr-shepherd poll <N>` as the next invocation instead; do not also run the one-shot command.
+   Print the full output. Follow the `## Instructions` section exactly for the current action.
 
-3. **Persistence:** Continuously call `pr-shepherd poll <N>` until the CLI returns `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action is non-terminal:
-   - `[WAIT]`: call `pr-shepherd poll <N>` again.
-   - `[MARK_READY]`: call `pr-shepherd poll <N>` again.
-   - `[FIX_CODE]`: follow the output's `## Instructions`, then call `pr-shepherd poll <N>` again.
+3. **Persistence:** Continuously call `pr-shepherd <N> --interval 45s --timeout 4m` until the CLI returns `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action is non-terminal:
+   - `[WAIT]`: call `pr-shepherd <N> --interval 45s --timeout 4m` again.
+   - `[MARK_READY]`: call `pr-shepherd <N> --interval 45s --timeout 4m` again.
+   - `[FIX_CODE]`: follow the output's `## Instructions`, then call `pr-shepherd <N> --interval 45s --timeout 4m` again.
 
    Treat a nonzero poll exit code as PR state only when the output contains a matching `# PR #N [ACTION]` heading. Exit code `1` can also mean a command or validation failure; if there is no `[FIX_CODE]` heading, surface the error and stop instead of looping.
 

package/bin/cli/default-iterate.mjs

@@ -1,50 +0,0 @@
-import { parsePrNumber } from "./args.mjs";
-import { USAGE } from "./help.mjs";
-const DEFAULT_ITERATE_FLAGS_WITH_VALUES = new Set(["--format", "--ready-delay", "--stall-timeout"]);
-const DEFAULT_ITERATE_BOOLEAN_FLAGS = new Set([
-    "--verbose",
-    "--no-auto-mark-ready",
-    "--no-auto-cancel-actionable",
-]);
-export function isDefaultIterateInvocation(subcommand) {
-    if (subcommand === "--help" || subcommand === "-h")
-        return false;
-    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.top}\n`);
-    process.exitCode = 1;
-}