pr-shepherd 0.31.0 → 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.0",
+  "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/bin/suggestions/patch.mjs

@@ -4,6 +4,49 @@
  * The diff uses `--- a/<path>` / `+++ b/<path>` headers so `git apply` and
  * `git apply --check` accept it without a `diff --git` preamble.
  */
+/**
+ * Strip leading/trailing replacement lines that are identical to the adjacent
+ * file lines just outside the removed range.
+ *
+ * GitHub stores a suggestion as a verbatim replacement for the *highlighted*
+ * line range, but reviewers often paste surrounding context into the box. Those
+ * context-duplicating lines must not appear as additions in the diff — they
+ * belong to the surrounding unchanged file content. Stripping them here produces
+ * a minimal diff that applies cleanly without duplicating lines.
+ *
+ * Comparison normalises trailing `\r` from file lines so CRLF files (which
+ * carry `\r` on each entry after `split("\n")`) still match suggestion lines
+ * delivered as LF-only by the GitHub API.
+ */
+function trimReplacementToContext(fileLines, startLine, endLine, replacementLines) {
+    const norm = (s) => (s.endsWith("\r") ? s.slice(0, -1) : s);
+    // Leading trim: largest L where replacement[0..L) == fileLines[startLine-1-L..startLine-1)
+    const maxL = Math.min(startLine - 1, replacementLines.length);
+    let L = 0;
+    leading: for (let l = maxL; l >= 1; l--) {
+        for (let i = 0; i < l; i++) {
+            if (norm(replacementLines[i]) !== norm(fileLines[startLine - 1 - l + i]))
+                continue leading;
+        }
+        L = l;
+        break;
+    }
+    const remainder = replacementLines.slice(L);
+    // Trailing trim: largest T where remainder[len-T..len) == fileLines[endLine..endLine+T)
+    const maxT = Math.min(fileLines.length - endLine, remainder.length);
+    let T = 0;
+    trailing: for (let t = maxT; t >= 1; t--) {
+        for (let j = 0; j < t; j++) {
+            if (norm(remainder[remainder.length - t + j]) !== norm(fileLines[endLine + j]))
+                continue trailing;
+        }
+        T = t;
+        break;
+    }
+    if (L === 0 && T === 0)
+        return replacementLines;
+    return T === 0 ? remainder : remainder.slice(0, remainder.length - T);
+}
 export function buildUnifiedDiff({ path, originalContent, startLine, endLine, replacementLines, context = 3, }) {
     const endsWithNewline = originalContent.endsWith("\n");
     const body = endsWithNewline ? originalContent.slice(0, -1) : originalContent;
@@ -13,9 +56,12 @@ export function buildUnifiedDiff({ path, originalContent, startLine, endLine, re
     const beforeLines = fileLines.slice(beforeStart, startLine - 1);
     const afterEnd = Math.min(fileLines.length, endLine + context);
     const afterLines = fileLines.slice(endLine, afterEnd);
+    // Trim replacement lines that duplicate adjacent file context so the diff is
+    // minimal and `git apply`-clean (issue #294).
+    const replacement = trimReplacementToContext(fileLines, startLine, endLine, replacementLines);
     const hunkOrigStart = beforeStart + 1;
     const hunkOrigCount = beforeLines.length + removedLines.length + afterLines.length;
-    const hunkNewCount = beforeLines.length + replacementLines.length + afterLines.length;
+    const hunkNewCount = beforeLines.length + replacement.length + afterLines.length;
     const noNewline = "\\n";
     const isLastOrigLine = (lineIdx) => !endsWithNewline && lineIdx === fileLines.length - 1;
     const out = [
@@ -37,10 +83,10 @@ export function buildUnifiedDiff({ path, originalContent, startLine, endLine, re
     // not just because context is 0 (there may still be unshown lines beyond the hunk).
     const addedEndsFile = !endsWithNewline && endLine >= fileLines.length;
     const hasCr = originalContent.includes("\r\n");
-    for (let i = 0; i < replacementLines.length; i++) {
-        const line = hasCr ? replacementLines[i] + "\r" : replacementLines[i];
+    for (let i = 0; i < replacement.length; i++) {
+        const line = hasCr ? replacement[i] + "\r" : replacement[i];
         out.push(`+${line}\n`);
-        if (addedEndsFile && i === replacementLines.length - 1)
+        if (addedEndsFile && i === replacement.length - 1)
             out.push(noNewline);
     }
     for (let i = 0; i < afterLines.length; i++) {

package/package.json

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