pr-shepherd 0.31.1 → 0.32.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.31.1",
+  "version": "0.32.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -90,6 +90,7 @@ Direct CLI:
 pr-shepherd 42                         # poll until non-WAIT or timeout
 pr-shepherd 42 --interval 60s --timeout 270s
 pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshots
+pr-shepherd 42 --until-terminal        # continue through WAIT/MARK_READY until work or terminal state
 pr-shepherd 42 --ready-delay 15m
 pr-shepherd iterate 42                 # single tick
 pr-shepherd poll 42                    # explicit poll command

package/bin/cli/args.mjs

@@ -28,6 +28,7 @@ const BOOLEAN_FLAGS = new Set([
     "--no-auto-mark-ready",
     "--no-auto-cancel-actionable",
     "--quiet-status",
+    "--until-terminal",
     "--dry-run",
     "--verbose",
 ]);

package/bin/cli/default-poll.mjs

@@ -13,6 +13,7 @@ const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--no-auto-mark-ready",
     "--no-auto-cancel-actionable",
     "--quiet-status",
+    "--until-terminal",
 ]);
 export function isDefaultPollInvocation(subcommand) {
     if (subcommand === "--help" || subcommand === "-h")

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

@@ -1,3 +1,4 @@
+import { LOG_FILE_USAGE } from "./help-log-file-page.mjs";
 export const COMMAND_USAGE = {
     resolve: `pr-shepherd resolve
 
@@ -103,7 +104,7 @@ Exit codes:
 
 Run iterate repeatedly while the action is WAIT. Print only the final tick to stdout.
 Poll exits as soon as iterate returns MARK_READY, FIX_CODE, CANCEL, or ESCALATE, or when timeout
-returns the last WAIT result.
+returns the last WAIT result. With --until-terminal, poll also continues through MARK_READY.
 
 Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
@@ -112,6 +113,7 @@ Poll flags:
   --interval <duration>          Sleep between WAIT ticks. Default: 60s.
   --timeout <duration>           Maximum wall-clock wait. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
+  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
 
 Forwarded iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
@@ -124,6 +126,7 @@ Forwarded iterate flags:
 
 Durations accept seconds, minutes, or hours: 30s, 4.5m, 1h, or bare seconds.
 Each WAIT tick writes a single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
+With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
 
 Exit codes:
   0  WAIT timeout or MARK_READY
@@ -173,21 +176,5 @@ Flags:
   --help, -h           Print this help and exit before any GitHub I/O.
 
 Exit code: 0 on success (including no-change no-op); 1 on validation, lookup, or mutation failure.`,
-    "log-file": `pr-shepherd log-file
-
-Print the per-worktree append-only debug log path for the current repository.
-The log is created by the first non-help pr-shepherd command that initializes logging.
-
-Usage:
-  pr-shepherd log-file [--format text|json]
-
-Flags:
-  --format text|json   Print a raw path or {"path": "..."} JSON. Default: text.
-  --help, -h           Print this help and exit before logging setup.
-
-Environment:
-  PR_SHEPHERD_LOG_DISABLED=1 disables logging.
-  PR_SHEPHERD_STATE_DIR overrides the base state directory.
-
-Exit code: 0 on success; 1 if repository identity cannot be resolved.`,
+    "log-file": LOG_FILE_USAGE,
 };

package/bin/cli/help-log-file-page.mjs

@@ -0,0 +1,17 @@
+export const LOG_FILE_USAGE = `pr-shepherd log-file
+
+Print the per-worktree append-only debug log path for the current repository.
+The log is created by the first non-help pr-shepherd command that initializes logging.
+
+Usage:
+  pr-shepherd log-file [--format text|json]
+
+Flags:
+  --format text|json   Print a raw path or {"path": "..."} JSON. Default: text.
+  --help, -h           Print this help and exit before logging setup.
+
+Environment:
+  PR_SHEPHERD_LOG_DISABLED=1 disables logging.
+  PR_SHEPHERD_STATE_DIR overrides the base state directory.
+
+Exit code: 0 on success; 1 if repository identity cannot be resolved.`;

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

@@ -45,6 +45,7 @@ Poll flags:
   --interval <duration>          Delay between WAIT ticks. Default: 60s.
   --timeout <duration>           Poll wall-clock cap. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
+  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
 
 Clean variants:
   pr [number]          Remove state for one PR. Defaults to current branch PR.

package/bin/cli/poll-handler.mjs

@@ -33,6 +33,7 @@ export async function handlePoll(args) {
         intervalSeconds,
         timeoutSeconds,
         quietStatus: hasFlag(extra, "--quiet-status"),
+        untilTerminal: hasFlag(extra, "--until-terminal"),
     });
     emitIterateResult(result, {
         format: globalOpts.format,

package/bin/commands/poll.mjs

@@ -55,39 +55,45 @@ function writeWaitProgress(opts) {
     return signature;
 }
 export async function runPoll(opts) {
-    const { intervalSeconds, timeoutSeconds, ...iterateOpts } = opts;
+    const { intervalSeconds, timeoutSeconds, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
     const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
     const start = Date.now();
     let tick = 0;
     let lastResult;
     const verbose = opts.verbose === true;
-    const quietStatus = opts.quietStatus === true;
+    const quietStatus = quietStatusOpt === true;
+    const untilTerminal = untilTerminalOpt === true;
     let dotsPrinted = false;
     let lastWaitSignature = null;
     while (true) {
         tick += 1;
         lastResult = await runIterate(iterateOpts);
-        if (lastResult.action !== "wait")
+        if (lastResult.action !== "wait" && !(untilTerminal && lastResult.action === "mark_ready")) {
             break;
+        }
         const elapsedMs = Date.now() - start;
-        const remainingMs = timeoutMs - elapsedMs;
-        if (remainingMs <= 0)
-            break;
-        if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
-            break;
+        if (!untilTerminal) {
+            const remainingMs = timeoutMs - elapsedMs;
+            if (remainingMs <= 0)
+                break;
+            if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
+                break;
+        }
         const nextSleepMs = intervalMs;
-        lastWaitSignature = writeWaitProgress({
-            tick,
-            elapsedMs,
-            sleepMs: nextSleepMs,
-            result: lastResult,
-            quietStatus,
-            verbose,
-            lastWaitSignature,
-        });
-        if (!quietStatus && !verbose)
-            dotsPrinted = true;
+        if (lastResult.action === "wait") {
+            lastWaitSignature = writeWaitProgress({
+                tick,
+                elapsedMs,
+                sleepMs: nextSleepMs,
+                result: lastResult,
+                quietStatus,
+                verbose,
+                lastWaitSignature,
+            });
+            if (!quietStatus && !verbose)
+                dotsPrinted = true;
+        }
         await sleep(nextSleepMs);
     }
     if (dotsPrinted)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -38,7 +38,7 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.53.0",
+    "oxfmt": "^0.54.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4"

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.31.1",
+  "version": "0.32.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

@@ -16,9 +16,9 @@ Poll dispatcher for iterating a PR to completion.
 
 1. **Resolve the PR number** (`$N`): use the number or URL in `$ARGUMENTS`; otherwise infer it with `gh pr view --json number --jq .number`. If none is found, report an error and stop.
 
-2. **Define the poll command once:** `pr-shepherd $N --interval 60s --timeout 4.5m --quiet-status`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
+2. **Define the poll command once:** `pr-shepherd $N --interval 60s --until-terminal --quiet-status`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
 
-3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) is non-terminal: do its instructions, then poll again. The poll already bounds each wait via `--interval`/`--timeout`; do not add manual `sleep`s between ticks.
+3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. `[FIX_CODE]` is non-terminal: do its instructions, then poll again. The poll already waits between ticks via `--interval`; do not add manual `sleep`s between ticks.
 
 4. **Nonzero exit codes:** Treat a nonzero poll exit as PR state only when the output contains a matching `# PR #$N [ACTION]` heading. Exit `1` can also mean a command or validation failure; if there is no `[ACTION]` heading, surface the error and stop instead of looping.