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

package/README.md

@@ -20,12 +20,12 @@ 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 unified recheck instructions. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, `yarn`, or `bun`.
+The CLI emits unified recheck instructions. Generated commands call `pr-shepherd` directly.
 
-At a high level, the skill invokes `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
+At a high level, the skill invokes `pr-shepherd poll <PR>`, which provides actionable feedback directly to the agent:
 
-```
-> npx pr-shepherd 123
+```text
+> pr-shepherd poll 123
 
 # PR #123 [FIX_CODE]
 
@@ -44,12 +44,12 @@ At a high level, the skill invokes `pr-shepherd <PR>` through the selected packa
 ## Failing checks
 
 - `24697658766` — `CI › lint / typecheck / test (22.x)`
-  > npx oxfmt
+  > oxfmt
 
 ## Post-fix push
 
 - base: `main`
-- resolve: `npx pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
+- resolve: `pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
 
 ## Instructions
 
@@ -61,13 +61,13 @@ _(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. Schedule one session-only follow-up task to run `npx pr-shepherd 123` to recheck once after a fresh delay between 30 seconds and 4 minutes, then end this turn. Do not sleep or rerun inline.
+7. CI needs time to run on the new push. Run `pr-shepherd poll 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:
 
-```
-npx pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"
+```text
+pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"
 ```
 
 ## Workflow
@@ -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).
+- 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).
 - 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
 
-One-tick 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 telling the agent how to run the next tick; the loop continues 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 poll` again until `[CANCEL]` or `[ESCALATE]`.
 
 Claude Code (via `pr-shepherd` skill):
 
@@ -127,9 +127,10 @@ Claude Code (via `pr-shepherd` skill):
 Codex or direct CLI:
 
 ```sh
-npx pr-shepherd 42
-npx pr-shepherd 42 --ready-delay 15m
-npx pr-shepherd iterate 42               # legacy-compatible spelling
+pr-shepherd 42
+pr-shepherd 42 --ready-delay 15m
+pr-shepherd poll 42
+pr-shepherd iterate 42               # legacy-compatible spelling
 ```
 
 ## Iterate decision loop
@@ -141,25 +142,16 @@ On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and
 `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
+pr-shepherd clean current    # remove state for the current branch's PR
+pr-shepherd clean repo       # remove all state for this repo
+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
 
-> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `pr-shepherd` through the repo package runner, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so the selected runner resolves it without prompting:
->
-> ```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
-> ```
->
-> A plain `npm install pr-shepherd` adds it to regular dependencies instead; use that only if you specifically want it under `dependencies`. Or install globally: `npm install -g pr-shepherd`.
+> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. Ensure `pr-shepherd` is available on `PATH` wherever the skill runs.
 
 ### Claude Code
 
@@ -170,15 +162,7 @@ claude /plugin marketplace add jonathanong/pr-shepherd
 claude /plugin install pr-shepherd
 ```
 
-This repo ships two `marketplace.json` files that serve different Claude install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
-
-Alternatively, install the Claude skills individually via `npx skills`:
-
-```bash
-npx skills add jonathanong/pr-shepherd
-```
-
-Installs the `pr-shepherd` skill into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
+This repo ships two `marketplace.json` files that serve different Claude install flows: the root `marketplace.json` resolves the published plugin (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
 
 ### Codex
 
@@ -205,33 +189,16 @@ codex plugin marketplace add ~/.codex/plugin-sources/pr-shepherd
 
 After adding the marketplace, open the Codex plugin directory, choose the `jonathanong` marketplace, and install/enable `pr-shepherd`. The marketplace root must contain `.agents/plugins/marketplace.json` and `plugins/pr-shepherd/`.
 
-Install the CLI where Codex will run it:
+Install the CLI where Codex will run it so `pr-shepherd` is available on `PATH`. The plugin only installs the skill; it does not install the CLI into target repositories.
 
-```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`.
-
-Iterate a PR from Codex with the target repository's package runner:
+Iterate a PR from Codex:
 
 ```bash
-<runner> pr-shepherd iterate 42
+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`. 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
-
-```bash
-npm install -g pr-shepherd
-```
-
 ## Configuration
 
 Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to override defaults. The loader walks up from `cwd` to `$HOME` (if `$HOME` is on that path) or the filesystem root; the first match wins.

package/bin/cli/fix-formatter.mjs

@@ -5,7 +5,6 @@ import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag
 import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instructions.mjs";
 export function formatFixCodeResult(header, result, opts) {
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const runner = opts?.runner;
     const sections = [header];
     if (result.fix.threads.length > 0) {
         sections.push("## Review threads");
@@ -31,7 +30,8 @@ export function formatFixCodeResult(header, result, opts) {
         sections.push("## Actionable comments");
         for (const c of result.fix.actionableComments) {
             const heading = c.url ? `[commentId=${c.id}](${c.url})` : `\`commentId=${c.id}\``;
-            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType)})`);
+            const editedMarker = c.edited ? " [edited since first look]" : "";
+            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType)})${editedMarker}`);
             sections.push(blockquote(c.body));
         }
     }
@@ -109,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, readyDelaySuffix, runner)));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/formatters.mjs

@@ -2,7 +2,7 @@ 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, renderThreadResolutionStatusTag, buildFirstLookBullets, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, renderEditedCommentTag, } from "./list-formatters.mjs";
 import { joinSections } from "../util/markdown.mjs";
 export function formatFetchResult(result) {
     const activeTotal = result.actionableThreads.length +
@@ -18,8 +18,7 @@ export function formatFetchResult(result) {
     if (firstLookTotal > 0)
         headingParts.push(`${firstLookTotal} first-look`);
     const headingSuffix = headingParts.length > 0 ? headingParts.join(", ") : "0 actionable";
-    const sections = [];
-    sections.push(`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`);
+    const sections = [`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`];
     if (result.actionableThreads.length > 0) {
         sections.push(`## Actionable Review Threads (${result.actionableThreads.length})` +
             (result.commitSuggestionsEnabled ? " [commit-suggestions: enabled]" : ""));
@@ -35,7 +34,9 @@ export function formatFetchResult(result) {
     }
     if (result.actionableComments.length > 0) {
         sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
-        sections.push(result.actionableComments.map((c) => renderCommentBullet(c)).join("\n"));
+        sections.push(result.actionableComments
+            .map((c) => renderCommentBullet(c, { statusTag: renderEditedCommentTag(c) }))
+            .join("\n"));
     }
     if (result.changesRequestedReviews.length > 0) {
         sections.push(`## Pending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length})`);

package/bin/cli/handlers.mjs

@@ -106,6 +106,5 @@ export async function handleIterate(args) {
         format: globalOpts.format,
         verbose: globalOpts.verbose ?? false,
         readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
-        runner: cfg.cli?.runner,
     });
 }

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

@@ -0,0 +1,154 @@
+export const COMMAND_USAGE = {
+    resolve: `pr-shepherd resolve
+
+Fetch actionable review items or apply GitHub review-state mutations after fixes.
+
+Usage:
+  pr-shepherd resolve [PR] [--fetch] [--format text|json]
+  pr-shepherd resolve [PR] --resolve-thread-ids A,B [--minimize-comment-ids X,Y]
+                            [--dismiss-review-ids Q] [--message MSG]
+                            [--require-sha SHA] [--format text|json]
+
+Modes:
+  fetch                Default when no mutation IDs are provided. Fetches review threads,
+                       comments, first-look items, and instructions.
+  mutate               Runs when any mutation ID flag is present. Resolves threads,
+                       minimizes comments/review summaries, and dismisses reviews.
+
+Flags:
+  --fetch                         Force fetch mode.
+  --resolve-thread-ids <ids>      Comma-separated review thread IDs to resolve.
+  --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
+  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --message <text>                Dismiss message. Required with --dismiss-review-ids.
+  --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.
+  --format text|json              Output format. Default: text.
+  --help, -h                      Print this help and exit before GitHub I/O.
+
+PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
+Exit code: 0 on success; 1 on validation, lookup, or mutation failure.`,
+    "commit-suggestion": `pr-shepherd commit-suggestion
+
+Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
+The command does not edit files or mutate git history.
+
+Usage:
+  pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG
+                                      [--description DESC] [--format text|json]
+
+Flags:
+  --thread-id <id>       Review thread ID containing exactly one suggestion to apply. Required.
+  --message <text>       Suggested commit subject. Required and must be non-empty.
+  --description <text>   Optional longer commit body.
+  --format text|json     Output format. Default: text.
+  --help, -h             Print this help and exit before GitHub, git, config, or log I/O.
+
+Preconditions:
+  The current branch must match the PR head ref, and local HEAD must match the PR head SHA.
+
+Exit codes:
+  0  suggestion patch and instructions produced
+  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]'.
+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:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --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.
+  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
+
+Actions:
+  WAIT        No immediate code action; recheck later or use pr-shepherd poll.
+  MARK_READY  Draft PR was marked ready for review.
+  FIX_CODE    Apply fixes, commit, push, and run the printed resolve command.
+  CANCEL      Terminal state: merged/closed or ready-delay elapsed.
+  ESCALATE    Terminal state requiring human direction.
+
+Exit codes:
+  0  WAIT or MARK_READY
+  1  FIX_CODE, or a command/validation error
+  2  CANCEL
+  3  ESCALATE`,
+    poll: `pr-shepherd poll
+
+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.
+
+Usage:
+  pr-shepherd poll [PR] [poll-flags] [iterate-flags]
+
+Poll flags:
+  --interval <duration>          Sleep between WAIT ticks. Default: 30s.
+  --timeout <duration>           Maximum wall-clock wait. Default: 5m.
+
+Forwarded iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --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.
+  --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.
+
+Exit codes:
+  0  WAIT timeout or MARK_READY
+  1  FIX_CODE, or a command/validation error
+  2  CANCEL
+  3  ESCALATE`,
+    clean: `pr-shepherd clean
+
+Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
+
+Usage:
+  pr-shepherd clean pr [number] [--dry-run] [--format text|json]
+  pr-shepherd clean branch [name] [--dry-run] [--format text|json]
+  pr-shepherd clean current [--dry-run] [--format text|json]
+  pr-shepherd clean repo [--dry-run] [--format text|json]
+  pr-shepherd clean all [--dry-run] [--format text|json]
+
+Variants:
+  pr [number]          Remove state for one PR. Defaults to current branch PR.
+  branch [name]        Resolve a branch to its open PR, then remove that PR's state.
+                       Defaults to current branch.
+  current              Alias for branch against the current branch.
+  repo                 Remove all state for the current repository, including worktree logs.
+  all                  Remove all pr-shepherd state.
+
+Flags:
+  --dry-run            Preview paths without removing them.
+  --format text|json   Output format. Default: text.
+  --help, -h           Print this help and exit before any cleanup.
+
+Exit code: 0 on success; 1 on validation or cleanup 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.`,
+};

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

@@ -0,0 +1,59 @@
+export const TOP_USAGE = `pr-shepherd
+
+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 poll [PR] [poll-flags] [iterate-flags]
+  pr-shepherd resolve [PR] [resolve-flags]
+  pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [flags]
+  pr-shepherd clean <pr|branch|current|repo|all> [value] [flags]
+  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.
+  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.
+  clean                Remove pr-shepherd state files.
+  log-file             Print the per-worktree debug log path.
+
+PR argument:
+  PR may be a number such as 42 or a GitHub pull request URL.
+  When omitted, pr-shepherd infers the current branch's pull request.
+
+Common flags:
+  --format text|json   Output Markdown text or JSON. Default: text.
+  --verbose            Include verbose iterate fields and poll progress.
+  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
+
+Iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --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.
+
+Poll flags:
+  --interval <duration>          Sleep between WAIT ticks. Default: 30s.
+  --timeout <duration>           Maximum poll wall-clock wait. Default: 5m.
+
+Clean variants:
+  pr [number]          Remove state for one PR. Defaults to current branch PR.
+  branch [name]        Remove state for a branch's PR. Defaults to current branch.
+  current              Alias for branch against the current branch.
+  repo                 Remove all state for the current repository.
+  all                  Remove all pr-shepherd state.
+
+Exit codes for iterate and poll:
+  0  WAIT or MARK_READY
+  1  FIX_CODE, or a command/validation error
+  2  CANCEL
+  3  ESCALATE
+
+Durations accept seconds, minutes, or hours: 30s, 2m, 1h, or bare seconds.
+
+Run 'pr-shepherd <command> --help' for command-specific details.`;

package/bin/cli/help.mjs

@@ -1,35 +1,9 @@
 import { hasFlag } from "./args.mjs";
+import { COMMAND_USAGE } from "./help-command-pages.mjs";
+import { TOP_USAGE } from "./help-top-page.mjs";
 export const USAGE = {
-    top: "Usage:\n" +
-        "  pr-shepherd --version | -v\n" +
-        "  pr-shepherd [PR] [--format text|json] [--ready-delay Nm]\n" +
-        "                 [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                 [--no-auto-cancel-actionable]\n" +
-        "  pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]\n" +
-        "                           [--dismiss-review-ids Q] [--message MSG] [--require-sha SHA]\n" +
-        "  pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]\n" +
-        "                                     [--format text|json]\n" +
-        "  pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]\n" +
-        "                             [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                             [--no-auto-cancel-actionable]\n" +
-        "  pr-shepherd poll [PR] [--interval 30s] [--timeout 5m] [--format text|json] [--ready-delay Nm]\n" +
-        "                        [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                        [--no-auto-cancel-actionable]\n" +
-        "  pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]\n" +
-        "  pr-shepherd log-file [--format text|json]",
-    resolve: "Usage: pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B]\n" +
-        "                               [--minimize-comment-ids X,Y] [--dismiss-review-ids Q]\n" +
-        "                               [--message MSG] [--require-sha SHA]",
-    "commit-suggestion": "Usage: pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG\n" +
-        "                                          [--description DESC] [--format text|json]",
-    iterate: "Usage: pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]\n" +
-        "                                [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                                [--no-auto-cancel-actionable]",
-    poll: "Usage: pr-shepherd poll [PR] [--interval 30s] [--timeout 5m] [--format text|json]\n" +
-        "                             [--ready-delay Nm] [--stall-timeout <duration>]\n" +
-        "                             [--no-auto-mark-ready] [--no-auto-cancel-actionable]",
-    clean: "Usage: pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]",
-    "log-file": "Usage: pr-shepherd log-file [--format text|json]",
+    top: TOP_USAGE,
+    ...COMMAND_USAGE,
 };
 /** Prints usage for `key` to stdout and returns true if `--help` or `-h` is in args. */
 export function maybePrintHelp(args, key) {

package/bin/cli/iterate-emitter.mjs

@@ -3,7 +3,6 @@ import { formatIterateResult, projectIterateLean, projectIterateVerbose } from "
 export function emitIterateResult(result, opts) {
     const projectionOpts = {
         readyDelaySuffix: opts.readyDelaySuffix,
-        runner: opts.runner,
     };
     if (opts.format === "json") {
         const output = opts.verbose

package/bin/cli/iterate-formatter.mjs

@@ -18,7 +18,6 @@ import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, }
 export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const runner = opts?.runner;
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
@@ -87,13 +86,13 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 header,
                 adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
                 adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         case "cancel": {
             const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
@@ -102,19 +101,18 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 cancelHeaderLines.join("\n"),
                 adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         }
         case "escalate":
             return joinSections([
                 header,
                 result.escalate.humanMessage,
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         case "fix_code":
             return formatFixCodeResult(header, result, {
                 readyDelaySuffix,
-                runner,
             });
     }
 }

package/bin/cli/iterate-instructions.mjs

@@ -3,8 +3,8 @@ import { buildPrShepherdCommand } from "./runner.mjs";
 function buildRecheckInstruction(rerunCommand, purpose) {
     return `Recheck: rerun \`${rerunCommand}\` to ${purpose} once after a fresh 30s–4m delay.`;
 }
-export function buildSimpleIterateInstructions(result, readyDelaySuffix, runner) {
-    const rerunCommand = buildIterateCommand(result.pr, readyDelaySuffix, runner);
+export function buildSimpleIterateInstructions(result, readyDelaySuffix) {
+    const rerunCommand = buildIterateCommand(result.pr, readyDelaySuffix);
     switch (result.action) {
         case "wait":
             return [buildRecheckInstruction(rerunCommand, "continue the active goal")];
@@ -20,8 +20,8 @@ export function buildSimpleIterateInstructions(result, readyDelaySuffix, runner)
             ];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix, runner) {
-    const rerunCommand = buildIterateCommand(pr, readyDelaySuffix, runner);
+export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix) {
+    const rerunCommand = buildIterateCommand(pr, readyDelaySuffix);
     return instructions.map((instruction) => {
         if (instruction === FIX_INSTRUCTION_STOP) {
             return `${instruction} ${buildRecheckInstruction(rerunCommand, "recheck")}`;
@@ -32,11 +32,9 @@ export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix, run
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
-export function buildIterateCommand(pr, readyDelaySuffix, runner) {
+export function buildIterateCommand(pr, readyDelaySuffix) {
     const suffix = readyDelaySuffix?.trim();
-    return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])], {
-        runner,
-    }).text;
+    return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])]).text;
 }
 export function numberInstructions(instructions) {
     return instructions.map((instruction, i) => `${i + 1}. ${instruction}`).join("\n");

package/bin/cli/iterate-lean.mjs

@@ -6,8 +6,7 @@ import { adaptIterateLog, adaptFixCodeInstructions, buildSimpleIterateInstructio
  */
 export function projectIterateLean(result, opts) {
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const runner = opts?.runner;
-    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, readyDelaySuffix, runner);
+    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, readyDelaySuffix);
     const base = {
         action: result.action,
         pr: result.pr,
@@ -94,7 +93,7 @@ export function projectIterateLean(result, opts) {
                     }),
                     resolveCommand: result.fix.resolveCommand,
                     ...(result.fix.instructions.length > 0 && {
-                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner),
+                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix),
                     }),
                 },
             };
@@ -125,13 +124,12 @@ export function projectIterateLean(result, opts) {
 }
 export function projectIterateVerbose(result, opts) {
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const runner = opts?.runner;
     if (result.action === "fix_code") {
         return {
             ...result,
             fix: {
                 ...result.fix,
-                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner),
+                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix),
             },
         };
     }
@@ -139,6 +137,6 @@ export function projectIterateVerbose(result, opts) {
     return {
         ...result,
         ...log,
-        instructions: buildSimpleIterateInstructions(result, readyDelaySuffix, runner),
+        instructions: buildSimpleIterateInstructions(result, readyDelaySuffix),
     };
 }

package/bin/cli/list-formatters.mjs

@@ -39,6 +39,9 @@ export function renderCommentBullet(c, opts = {}) {
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
     return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
 }
+export function renderEditedCommentTag(c) {
+    return c.edited ? "[edited since first look]" : undefined;
+}
 export function renderReviewBullet(r, opts = {}) {
     const bodySuffix = opts.includeBody && r.body != null && r.body !== "" ? `: ${renderBodyPreview(r.body)}` : "";
     return `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})${bodySuffix}`;

package/bin/cli/poll-handler.mjs

@@ -37,6 +37,5 @@ export async function handlePoll(args) {
         format: globalOpts.format,
         verbose: globalOpts.verbose ?? false,
         readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
-        runner: cfg.cli?.runner,
     });
 }

package/bin/cli/runner.mjs

@@ -1,111 +1,10 @@
-import { readFileSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-export function buildPrShepherdCommand(args, opts) {
-    const runner = resolveCliRunner(opts.runner, opts.cwd);
-    const argv = baseArgvForRunner(runner).concat(args);
+export function buildPrShepherdCommand(args) {
+    const argv = ["pr-shepherd", ...args];
     return { argv, text: renderShellCommand(argv) };
 }
-export function resolveCliRunner(runner, cwd = process.cwd()) {
-    const configured = parseCliRunner(runner);
-    return configured === "auto" ? detectPackageRunner(cwd) : configured;
-}
-const VALID_RUNNERS = ["auto", "npx", "pnpm", "yarn", "bun"];
-const VALID_RUNNERS_LIST = VALID_RUNNERS.map((v) => `"${v}"`).join(", ");
-export function parseCliRunner(runner) {
-    if (runner === undefined)
-        return "auto";
-    if (typeof runner !== "string") {
-        throw new Error(`Invalid config: cli.runner must be one of ${VALID_RUNNERS_LIST}, got ${JSON.stringify(runner)}`);
-    }
-    const value = runner.trim();
-    if (VALID_RUNNERS.includes(value))
-        return value;
-    throw new Error(`Invalid config: cli.runner must be one of ${VALID_RUNNERS_LIST}, got ${JSON.stringify(runner)}`);
-}
 export function renderShellCommand(argv) {
     return argv.map(renderShellArg).join(" ");
 }
-function baseArgvForRunner(runner) {
-    switch (runner) {
-        case "npx":
-            return ["npx", "pr-shepherd"];
-        case "pnpm":
-            return ["pnpm", "exec", "pr-shepherd"];
-        case "yarn":
-            return ["yarn", "run", "pr-shepherd"];
-        case "bun":
-            return ["bunx", "pr-shepherd"];
-    }
-}
-const runnerCache = new Map();
-export function __resetRunnerCache() {
-    runnerCache.clear();
-}
-function detectPackageRunner(startDir) {
-    const cached = runnerCache.get(startDir);
-    if (cached)
-        return cached;
-    const home = homedir();
-    const repoRoot = findRepoRoot(startDir);
-    let current = startDir;
-    while (true) {
-        const atBoundary = current === repoRoot || current === home || current === dirname(current);
-        // Read signals for this directory unless it is home without being the repo root.
-        // This lets dotfiles repos (repoRoot === home) detect their own package manager
-        // while still preventing home's lockfiles from influencing unrelated projects.
-        if (!atBoundary || current === repoRoot) {
-            const packageManager = readPackageManager(current);
-            if (packageManager?.startsWith("pnpm@"))
-                return cacheRunner(startDir, "pnpm");
-            if (packageManager?.startsWith("yarn@"))
-                return cacheRunner(startDir, "yarn");
-            if (packageManager?.startsWith("npm@"))
-                return cacheRunner(startDir, "npx");
-            if (packageManager?.startsWith("bun@"))
-                return cacheRunner(startDir, "bun");
-            if (isFile(join(current, "pnpm-lock.yaml")))
-                return cacheRunner(startDir, "pnpm");
-            if (isFile(join(current, "yarn.lock")))
-                return cacheRunner(startDir, "yarn");
-            if (isFile(join(current, "bun.lock")))
-                return cacheRunner(startDir, "bun");
-            if (isFile(join(current, "bun.lockb")))
-                return cacheRunner(startDir, "bun");
-            if (isFile(join(current, "package-lock.json")))
-                return cacheRunner(startDir, "npx");
-        }
-        if (atBoundary)
-            return cacheRunner(startDir, "npx");
-        current = dirname(current);
-    }
-}
-function cacheRunner(startDir, runner) {
-    runnerCache.set(startDir, runner);
-    return runner;
-}
-function readPackageManager(packageDir) {
-    try {
-        const parsed = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
-        return typeof parsed.packageManager === "string" ? parsed.packageManager.trim() : null;
-    }
-    catch {
-        return null;
-    }
-}
-function findRepoRoot(startDir) {
-    let current = startDir;
-    while (true) {
-        if (statSync(join(current, ".git"), { throwIfNoEntry: false }))
-            return current;
-        if (current === dirname(current))
-            return null;
-        current = dirname(current);
-    }
-}
-function isFile(path) {
-    return statSync(path, { throwIfNoEntry: false })?.isFile() === true;
-}
 function renderShellArg(arg) {
     if (/^\$[A-Z_][A-Z0-9_]*$/.test(arg))
         return `"${arg}"`;

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

@@ -43,7 +43,7 @@ const SUGGESTION_RESULT = {
         "Apply the patch to `a.ts`: run `git apply` with the diff shown above.",
         "Stage the file: `git add -- a.ts`",
         'Commit: `git commit -m "apply fix" -m "Co-authored-by: alice <alice@users.noreply.github.com>"`',
-        "Resolve the thread on GitHub: `npx pr-shepherd resolve 42 --resolve-thread-ids t1`",
+        "Resolve the thread on GitHub: `pr-shepherd resolve 42 --resolve-thread-ids t1`",
         "Push when ready: `git push` (or `git push --force-with-lease` after rebasing).",
     ],
 };

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

@@ -35,7 +35,7 @@ export function makeIterateResult(action = "wait") {
                 checks: [],
                 changesRequestedReviews: [],
                 resolveCommand: {
-                    argv: ["npx", "pr-shepherd", "resolve", "42"],
+                    argv: ["pr-shepherd", "resolve", "42"],
                     requiresHeadSha: true,
                     requiresDismissMessage: false,
                     hasMutations: false,

package/bin/commands/commit-suggestion-instruction.mjs

@@ -6,7 +6,7 @@ import { buildPrShepherdCommand } from "../cli/runner.mjs";
  *   (e.g. `"## Review threads"` for iterate, `"## Actionable Review Threads"` for resolve).
  * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
  */
-export function buildCommitSuggestionInstruction(prNumber, sectionName, includeDriftHint, runner) {
+export function buildCommitSuggestionInstruction(prNumber, sectionName, includeDriftHint) {
     const command = buildPrShepherdCommand([
         "commit-suggestion",
         String(prNumber),
@@ -15,7 +15,7 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName, includeD
         "--message",
         "<one-sentence headline>",
         "--format=json",
-    ], { runner }).text;
+    ]).text;
     const driftHint = includeDriftHint
         ? " If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step."
         : " If the patch fails to apply, fall through to the manual-edit step.";

package/bin/commands/commit-suggestion.mjs

@@ -5,7 +5,6 @@ import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/cli
 import { fetchPrBatch } from "../github/batch.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
-import { loadConfig } from "../config/load.mjs";
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 const execFile = promisify(execFileCb);
 export async function runCommitSuggestion(opts) {
@@ -93,7 +92,12 @@ export async function runCommitSuggestion(opts) {
         `-m ${sq(commitMessageArg)}`,
         ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
     ].join(" ");
-    const resolveCommand = buildPrShepherdCommand(["resolve", String(prNumber), "--resolve-thread-ids", opts.threadId], { runner: loadConfig().cli?.runner }).text;
+    const resolveCommand = buildPrShepherdCommand([
+        "resolve",
+        String(prNumber),
+        "--resolve-thread-ids",
+        opts.threadId,
+    ]).text;
     const postActionInstructions = [
         `Apply the patch to \`${filePath}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
         `Stage the file: \`git add -- ${quotedPath}\``,

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

@@ -107,7 +107,7 @@ function setupHappyPath() {
 // ---------------------------------------------------------------------------
 export function registerHooks() {
     beforeEach(() => {
-        mockLoadConfig.mockReturnValue({ cli: { runner: "auto" } });
+        mockLoadConfig.mockReturnValue({});
     });
 }
 export { FILE_CONTENT, GLOBAL_OPTS, fetchPrBatch, getCurrentBranch, getCurrentPrNumber, makeBatch, makeGitSuccess, makeThread, mockExecFile, mockFetchBatch, mockGetCurrentBranch, mockGetCurrentPrNumber, mockLoadConfig, mockReadFile, readFile, runCommitSuggestion, setupHappyPath, };

package/bin/commands/iterate/classify.mjs

@@ -37,8 +37,8 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber, runner) {
-    const argv = buildPrShepherdCommand(["resolve", String(prNumber)], { runner }).argv;
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber) {
+    const argv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
     const resolveThreadIds = dedupeIds(threads.map((t) => t.id));
     const threadIds = dedupeIds([...resolveThreadIds, ...resolutionOnlyThreads.map((t) => t.id)]);
     if (threadIds.length > 0) {

package/bin/commands/iterate/fix-code.mjs

@@ -7,7 +7,7 @@ import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, cliRunner, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
@@ -64,7 +64,7 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = pushLikely ? buildInProgressRunIds(report, cancelledSet) : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, cliRunner);
+    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber);
     const overlappingReviewIds = resolveCommand.droppedDismissReviewIds ?? [];
     if (overlappingReviewIds.length > 0) {
         process.stderr.write(`pr-shepherd: resolve command overlap: ${overlappingReviewIds.length} ` +
@@ -100,7 +100,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, cliRunner);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/index.mjs

@@ -122,7 +122,6 @@ export async function runIterate(opts) {
             firstLookSummaries,
             editedSummaries,
             surfacedApprovals,
-            cliRunner: config.cli?.runner,
         });
     }
     const canMarkReady = report.status === "READY" &&

package/bin/commands/iterate/render.mjs

@@ -15,7 +15,7 @@ export function renderResolveCommand(rc) {
     }
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = []) {
     const instructions = [];
     const hasNonConflictHints = threads.length > 0 ||
         checks.length > 0 ||
@@ -53,7 +53,7 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
-        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads", false, runner));
+        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads", false));
     }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions
@@ -93,10 +93,11 @@ export function buildFixInstructions(threads, actionableComments, checks, change
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
     }
     const editedTotal = editedSummaries.length +
+        actionableComments.filter((c) => c.edited).length +
         firstLookThreads.filter((t) => t.edited).length +
         firstLookComments.filter((c) => c.edited).length;
     if (editedTotal > 0) {
-        instructions.push(`Items under \`## Review summaries (edited since first look)\` and any first-look bullet tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
+        instructions.push(`Items marked \`[edited since first look]\`, items under \`## Review summaries (edited since first look)\`, and any first-look bullet tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
     }
     if (resolveCommand.hasMutations) {
         instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));

package/bin/commands/resolve-instructions.mjs

@@ -6,7 +6,7 @@ import { buildCommitSuggestionInstruction } from "./commit-suggestion-instructio
  * Steps are conditionally emitted based on what the fetch returned (mirrors
  * `buildFixInstructions` in `commands/iterate/render.mts`).
  */
-export function buildFetchInstructions(prNumber, result, runner) {
+export function buildFetchInstructions(prNumber, result) {
     const { actionableThreads, resolutionOnlyThreads, firstLookThreads, actionableComments, firstLookComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     const total = actionableThreads.length +
@@ -27,13 +27,14 @@ export function buildFetchInstructions(prNumber, result, runner) {
     if (firstLookTotal > 0) {
         instructions.push(`Items in \`## First-look items\` are shown so you can acknowledge their current status before acting. If a first-look thread also appears under \`## Review threads to resolve\`, include its ID in \`--resolve-thread-ids\`; otherwise do not pass first-look-only IDs to mutation flags.`);
     }
-    const editedTotal = firstLookThreads.filter((t) => t.edited).length +
+    const editedTotal = actionableComments.filter((c) => c.edited).length +
+        firstLookThreads.filter((t) => t.edited).length +
         firstLookComments.filter((c) => c.edited).length;
     if (editedTotal > 0) {
-        instructions.push(`First-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
+        instructions.push(`Actionable comments marked \`[edited since first look]\` and first-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
     }
     if (hasSuggestions) {
-        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Actionable Review Threads", true, runner));
+        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Actionable Review Threads", true));
     }
     if (hasCodeItems) {
         instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);
@@ -50,9 +51,7 @@ export function buildFetchInstructions(prNumber, result, runner) {
         : reviewSummaries.length > 0
             ? ` Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`.`
             : "";
-    const resolveCommand = `${buildPrShepherdCommand(["resolve", String(prNumber)], {
-        runner,
-    }).text} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]`;
+    const resolveCommand = `${buildPrShepherdCommand(["resolve", String(prNumber)]).text} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]`;
     instructions.push(`Run \`${resolveCommand}\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
     instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS));
     instructions.push(`Report: echo the CLI's mutation output, then one line per Acknowledged item: \`Acknowledged <id> (@<author>): <reason>\`. If any fetched item was neither resolved nor acknowledged, stop and escalate: "<N> item(s) fetched but not acted on or acknowledged — need human direction before closing".`);

package/bin/commands/resolve.mjs

@@ -129,5 +129,5 @@ export async function runResolveFetch(opts) {
         reviewSummaries: cfg.resolve.fetchReviewSummaries ? data.reviewSummaries : [],
         commitSuggestionsEnabled: cfg.actions.commitSuggestions,
     };
-    return { ...result, instructions: buildFetchInstructions(prNumber, result, cfg.cli?.runner) };
+    return { ...result, instructions: buildFetchInstructions(prNumber, result) };
 }

package/bin/comments/visible-comments.mjs

@@ -13,8 +13,9 @@ export function classifyVisibleComments(comments, seenMap, minimizeComments) {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
             continue;
-        actionable.push(c);
-        toMarkSeen.push(c);
+        const comment = cls === "edited" ? { ...c, edited: true } : c;
+        actionable.push(comment);
+        toMarkSeen.push(comment);
     }
     return { actionable, minimizeIds, toMarkSeen };
 }

package/bin/config/load.mjs

@@ -3,7 +3,6 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
-import { parseCliRunner } from "../cli/runner.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
 function findRcFile(startDir) {
@@ -61,12 +60,6 @@ export function loadConfig() {
         const raw = readFileSync(rcPath, "utf8");
         const parsed = (parse(raw) ?? {});
         const config = deepMerge(defaults, parsed);
-        // Validate cli and watch at load time so misconfigurations are caught once
-        // with the rc file path in context, rather than during instruction rendering.
-        if (config.cli === null || Array.isArray(config.cli) || typeof config.cli !== "object") {
-            throw new Error(`Invalid config: cli must be a plain object, got ${JSON.stringify(config.cli)}`);
-        }
-        config.cli.runner = parseCliRunner(config.cli.runner);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;

package/bin/config.json

@@ -1,7 +1,4 @@
 {
-  "cli": {
-    "runner": "auto"
-  },
   "iterate": {
     "fixAttemptsPerThread": 3,
     "stallTimeoutMinutes": 30,

package/bin/reporters/agent.mjs

@@ -32,6 +32,7 @@ export function toAgentComment(c) {
         ...(c.authorType !== undefined && { authorType: c.authorType }),
         body: c.body,
         url: c.url,
+        ...(c.edited === true && { edited: true }),
     };
 }
 export function toAgentCheck(c) {

package/package.json

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

@@ -8,7 +8,7 @@ allowed-tools: ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill"]
 
 # pr-shepherd
 
-One-tick dispatcher for iterating a PR to completion.
+Poll dispatcher for iterating a PR to completion.
 
 ## Arguments: $ARGUMENTS
 
@@ -20,40 +20,24 @@ One-tick 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. **Short-circuit if merged or closed:**
+2. **Run `pr-shepherd poll`:**
 
    ```bash
-   gh pr view <N> --json state --jq '.state'
+   pr-shepherd poll <N>
    ```
 
-   If `MERGED` or `CLOSED`, output: `PR #N is already merged/closed. Nothing to do.` and stop.
+   Do not pass `$ARGUMENTS` through as extra flags. If you need to inspect supported options, run `pr-shepherd poll --help`.
 
-3. **Select the package runner** from the target repository root:
-   - Prefer `package.json` `packageManager`: `pnpm@...` → `pnpm exec`, `yarn@...` → `yarn run`, `bun@...` → `bunx`, `npm@...` → `npx`.
-   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` → `pnpm exec`, `yarn.lock` → `yarn run`, `bun.lock` / `bun.lockb` → `bunx`, `package-lock.json` or no signal → `npx`.
+   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.
 
-4. **Run one iterate tick:**
+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.
 
-   If the package is missing in the target repository, tell the user to install pr-shepherd with the matching dev-dependency command: `pnpm add -D pr-shepherd`, `yarn add -D pr-shepherd`, `bun add -d pr-shepherd`, or `npm install --save-dev pr-shepherd`.
+   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.
 
-   ```bash
-   <runner> pr-shepherd <N>
-   ```
-
-   Print the full output. Follow the `## Instructions` section exactly.
-
-5. **Persistence:** Do not stop polling/iterating unless directed by the human or until the CLI returns a terminal state (`[CANCEL]` or `[ESCALATE]`). Every other action — `[WAIT]`, `[MARK_READY]`, `[FIX_CODE]` — is non-terminal and must be followed by another tick via one of the strategies below.
-
-6. **Stop conditions (terminal states):**
+4. **Stop conditions (terminal states):**
    - Stop when the CLI emits `[CANCEL]` (ready-delay completed, or PR merged/closed).
    - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures.
    - **Do NOT merge the pull request** unless the human has explicitly requested or allowed it.
-
-7. **Non-terminal actions** (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) — follow the `## Instructions` in the output. Pick one iteration strategy:
-   - **Blocking poll** — rerun as `<runner> pr-shepherd poll <N> [--interval <duration>] [--timeout <duration>]` (defaults: interval 30s, timeout 5m). Holds the agent turn until the action is non-WAIT or the timeout fires. Simplest when the agent cannot reliably schedule its own follow-up.
-   - **Scheduled wakeup + one tick** — schedule a single session-only follow-up task to rerun `<runner> pr-shepherd <N>` after a fresh 30s–4m delay, then end the turn.
-   - **Inline sleep + rerun** — sleep inline for a fresh 30s–4m delay, then rerun.
-
-   **Never write a custom polling loop** (shell `while`/`until` loops, script files that loop over pr-shepherd output, etc.). Custom loops poll only for terminal states and silently skip `[FIX_CODE]` handling — actionable review threads, failing checks, and resolve commands get missed. Use `pr-shepherd poll` for WAIT-state waiting; it exits on any non-WAIT action so the caller handles `[FIX_CODE]` and other actionable outputs normally.
-
-   Do not combine strategies (e.g., poll AND schedule a wakeup). Remember step 5 — every non-terminal output requires a follow-up tick.